ESAF User Guide
ESAF User Guide source (LaTeX) is downloadable via CVS.
The latest version in PDF in available here.
In the following sections we present some basical notes about the installation of ESAF on your PC.
Requirements
- gcc 3.2 or higher
- last version of ROOT
- g77 Fortran compiler
- zlib library
- CVS
- ssh agent (default for Linux/UNIX)
Download from web
You can download the sources archive here. Then you must uncompress the file using
tar xfvz filename.tar.gz
Download via CVS
ESAF is stored at Lyon Computer Center under the CVS control . The code is available in read-only mode for normal users and in read-write mode for the developers.
In order to download the code via CVS you must
- create a file config in your directory .ssh with the following lines:
Host cvs.in2p3.fr
Port 2222
User euso
PasswordAuthentication yes
RSAAuthentication no
PunkeyAuthentication no
ForwardX11 no
ForwardAgent no - set the following UNIX environment variables:
export CVSROOT=euso@cvs.in2p3.fr:/cvs/euso/
export CVS_RSH=ssh - get the code with the standard CVS command cvs co esaf
- get the ESAF documentation with the command cvs co esafdoc
We recommend to dowmload via CVS to have always up to date the sources. You can be aware the ESAF developing getting regularly e-mails (for that you should contact Alessandro Thea) and/or you can consult ESAF repository at Lyon Computer Center .
Compiling and linking
Just enter into the esaf directory that CVS has created and then type make.
The compilation and linking may take several minutes, depending on the machine you are using. If everything went fine, at the end you should have 2 executable files in the bin/i686 directory, named Simu and Reco.
Compilation and or Linking may fail for several reasons; if so, and you didn't modified the code, make sure that all requirements are satisfied.
Running
Before running, check that the environment variable LD_LIBRARY_PATH includes the esaf/lib/i686 directory. If this is not the case, type the command:
export ESAFDIR = /home/myuser/esaf;
export LD_LIBRARY_PATH=\$(LD_LIBRARY_PATH):$ESAFDIR/lib/i686
This variable tells the operating system where the dynamic shared libraries are located. You can change the variable ESAFDIR correspondly to the directory in which you have installed ESAF. Depending of your system setup, you might have to add the \$ROOTSYS/lib directory to the same path. You can check whether it is already defined or not by typing echo \$ROOTSYS.
The first binary is called Simu. It is the simulation program with the graphical user interface (GUI).
The simplest way to run Simu is the following:
bin/i686/Simu -b --events=nev
The -b option means that you are running in batch mode, without interactive
windows. If you remove this option, a GUI starts.
This GUI is right now a very incomplete demo and should not be used at this stage of development.
The --events option specifies how many events simulate. Default is 1.
All other parameters (a very large number!) are hidden in
the configuration files in the directory esaf/config.
To change the behaviour of the program right now the only way is to edit these
files. The meaning of each variable is described into the files themselves.
In the next section we give just the list of these files with their general
meaning. Please refer to the code and to the complete user guide to have more infos.
Updating
ESAF is continuously updating (developing and debugging); often the changes in the
program are very significant and affect the output files so that they are not compatible
between different versions of the program. Therefore we advise you to constantly keep
up-to-date the code.
To do this you have simply to go on ESAF installation directory and type to the system prompt
cvs up -d
This updates files that are changed, deleted or created; the option -d (optional) updates the
directory structure (it is modified sporadically, so you can simply type cvs up).
It is also possible to make an update of a specific part of the code running cvs up from the
directory of interest (as long as in that directory there is a subdirectory CVS).
There is an ESAF CVS mailing list that informs the users whenever a developer puts on the repository
a new or modified part of code, with the indication of the files changed. If you are interested to receive
these mails, you are invited to contact Alessandro Thea.
Building Options
In the ESAF main directory there is the file Rules that contains compilations options.
The most important option for the user is ESAFTMP; this variable points to a temporary
directory where are saved files for creation of libraries and executables. By default this variable is
set as follows:
ESAFTMP = /tmp
You are advised to change the default directory (editing the file Rules)
because the directory /tmp, present in all systems, is generally emptied when you reboot the machine.
The ESAFTMP directory contains the directory ESAFTMP.username/architeture/ in which are
other subdirectories, one for each library of ESAF.
The other option in the file Rules are DEBUG, for compiling with (DEBUG = 1) or without (DEBUG = 0) debugging option.
Cleaning and rebuilding
Sometimes, after major changes or when a file obsolete is removed, make can fail to rebuild ESAF. This is due to old temporary files in conflict with the new code.
In this case you can compiling typing make clean; make instead of make. If also this fails you must delete by hand the directory ESAFTMP.
As last chance, if you still have problems, you can delete the entire ESAF main directory and the
ESAFTMP directory and reinstall ESAF.