Roadmap for Physicist Programmers

Contents

Introduction

This document outlines the steps necessary to install, run and eventually contribute to the off-line software. When reading this document, please note

Using a Supported Platform

There is no guarantee that the off-line code will work on any arbitrary platform; before doing anything else you need to ensure that yours is a supported platform.

Electing a Site Librarian

Every site that is actively using the off-line software needs a Site Librarian whose job it is to manage local resources, install the code and build executables. If you are the only one at your site doing this, or if you run on a laptop, then congratulations, you just got the job of Site Librarian!

Finding a Mentor

We all need mentors, someone of whom we can freely ask questions, particularly questions that might just be dumb! Mentors don't have to be experts; if there are several people working on software at your site you can be another's mentor. A site librarian is a natural choice as a mentor for others at their site. In the first instance, accessibility is more important than expertise. When a mentor cannot answer a question then either of you should ask someone else, particularly a core group member, or the OO discussion list:-
  minos_software_discussion@egnext1.slac.stanford.edu
ask George Irwin (gmieg@slac.stanford.edu) to add you to the list if not already on it. Hopefully the reply will enrich you both. Never feel inhibited about asking questions, but local mentoring should help to speed things up.

Installing the Code

[The plan is that this section will eventually be the cookbook that Doug Michael asked for in the review.]

This involves several steps, some of which need only be done by the Site Librarian.

Installing ROOT

Our code is based on the Root framework and so ROOT must be installed before you can start work with our software. Possibly your system manager has already installed ROOT. Try typing
  root
to see if ROOT has been installed and if so what version it is. You need to keep up to date with ROOT. See the supported versions for the required version.

If you need to install ROOT, it is strongly recommended that you get the source and recompile it as many spurious problems can be traced to version skew between the pre-built binaries, supplied by the ROOT team, and the local environment, even if the platform and compiler versions appear to match. Full instructions can be found in the Downloading ROOT page of the ROOT web but the following instructions should work for a typical UNIX installation using a csh family shell. Substitute the required version for 3.00-06 in these notes.

  1. Decide where to install ROOT, for example:-
      ~/root_3.00-06/root
    
  2. Create the directory and define the environmental variable ROOTSYS:-
      mkdir -p ~/root_3.00-06/root
      setenv ROOTSYS ~/root_3.00-06/root
    
  3. Move to the directory above ROOTSYS:-
      cd $ROOTSYS/../
    
    From the download page click on the version you require and then click on the "ROOT 2.25/03 complete source tree" and place it into this directory.
  4. Unpack it:-
      gunzip -c root_v2.25.03.source.tar.gz | tar xvf -
    
  5. Step down to ROOTSYS and configure for the required platform:-
      cd $ROOTSYS
      ./configure linuxegcs
    
    this assumes LINUX with EGCS compiler. For a full range of platforms type:-
      ./configure --help
    
  6. Now clean and rebuild the code:-
      gmake distclean
      gmake  
    
    don't worry about the many
    No such file or directory
    
    warnings.
  7. Define the environmental variable LD_LIBRARY_PATH, used by the loader when looking for directories holding libraries used to build an executable. If LD_LIBRARY_PATH is not defined then you need to define it:-
    setenv LD_LIBRARY_PATH ${ROOTSYS}/lib
    
    or, if already defined, then you need to append to it:-
    setenv LD_LIBRARY_PATH ${ROOTSYS}/lib:${LD_LIBRARY_PATH}
    
  8. Add the ROOT binary directory to your PATH:-
      setenv PATH ${PATH}:$ROOTSYS/bin
    
  9. Check that root runs:-
        root
    
  10. Add the definitions of PATH, ROOTSYS and LD_LIBRARY_PATH to your .chsrc.

Learning about CVS

The Minos software is held in a CVS repository. Try:-
  cvs -v
to confirm that it is installed and to check the version number. If CVS is not installed, consult you system manager. You need to know some basic CVS commands if you are going to get code from the repository or place updates into it. See:-

Accessing the Repository

Before you can access the CVS repository you have to authenticate yourself using SSH. See:-
  
Instructions for using the OO MINOS cvs repository
which tells you how to set up and register your personal SSH keys and then how to get all the code from the repository.

Compiling and Linking

This section will change shortly, once we put our code under srt control.

You need to define the environmental variable MINFPATH to point to the Minfast directory of your copy of the code. Assuming that you have loaded the code into:-

  ~/minosroot
then the command is:-
  setenv MINFPATH ~minosroot/Minfast/
Once this is done installing the code should only require the commands:-
  cd $MINFPATH 
  gmake all

Running the Code

To run the minfast job:-
  cd $MINFPATH 
  ./minfastjob
although you will need an input data file from someone before you can get very far. Take a look at:-
  /afs/fnal.gov/files/data/minos/d12/root_files/AAA_README.TXT
which contains details of standard input files.

The MINOS Companion has the following introductions to help you get started with ROOT and Minfast.

Code Development

If you want to develop code as a new package that will be part of the off-line code base then you need to carry out the following steps.

Get Training

Unless you are familiar with C++ and OO programming it is strongly recommended that you take a course in both. A list of books and courses we know about can be found on the Education page. You should also look at The MINOS Off-line Software User Manual

Discuss Your Analysis and Design

Don't rush into coding except to write throw away prototype code to help clarify design alternatives. Instead discuss with the core group or on the OO discussion email list what you are planning, to find out who else is working in the area you have chosen. The biweekly phone conferences are an excellent place for such discusions. There is also an OO Software discussion forum.

Having established that your package might be useful (we don't demand that all packages end up in the code base, only that they might be of general interest) start to write a PACKRAT (Package Rationale) for you package and publicise it for other to comment on. For example PACKRATs see MINOS Computing and Software Review

Initially concentrate on:-

Study the Coding Standard

Look at both the hot list and the full Coding Convention for does and don'ts about layout, C++ and OO design.

Commit Code to the Repository

Once you have a little code that compiles, start to commit it to the repository so that others can start to see what you are doing. Don't wait until you think the package is finished before committing code for otherwise you may fail to benefit from the suggestions of others.

Expect to have the code informally reviewed. This may sound intimidating but it isn't meant to be! Regard it as a code nurturing exercise. The aim is always to be warn against bad design, explaining why it is bad, to help speed up the learning process. Reviewers understand that good OO design properly implemented in C++ is hard and that none of us knows it all!

You can expect people to pay close attention to:-


Go Back to the The OO Companion Top Page


If you have any comments about this page please send them to Nick West