This notes are intended to be a short introduction to the TOSCA software environment. We are trying to answer the most common questions and describe the milestones of the environment. The note describes the concrete commands which allow you to build and run simulation and analysis programs, to develop the code and join your efforts with other people. The basis of the environment consist of CVS, GNU make and a set of scripts. The occasional user and developer needs to know just basic things about make and its GNU version. We provide here all the CVS (Concurent Version System) commands that developer needs, but the responsible for the package needs to know more things. We assume that the reader knows how to work in UNIX environment.
For the moment the TOSCA software is installed in the CERN afs three, all the nessesary libraries have been made for AIX and OSF1 environments, the software should work in HP-UX, SunOS, Solaris and Linux environments but haven't checked yet.
All the nessesary variables are defined in the tosca_environment.csh
file. You need to read it into your shell (csh or tcsh only for the time being)
with the command:
source /afs/cern.ch/nomad/user2/tosca/scripts/tosca_environment.csh
The underlined part of path is temporary solution until the TOSCA group account will
be set up. When one will need to replace the command with:
source /afs/cern.ch/tosca/scripts/tosca_environment.csh
Note that on different clusters the position of the TOSCA code three could
be different as well as different parts of it could be placed on different disks.
The user needs only to care about the position of the tosca_environment.csh file.
Everything else can be coded in a position independent way using only the variables provided
by that file:
For the moment there are 3 programs intended to do the simulation and analysis of TOSCA events:
In order to share the responsibilities, organise code and development process a program can be subdivided on packages, each of them represents a separate library and has separate versioning of production quality code. Programs have tagged versions that go to the production and those versions essentially consists of list of the versions of packages that are used to build the executable.
Getos is subdivided on the following packages:
It is not expected that camel will be split into the packages as it should stay by intention a small utility program.
There are packages that are so general that can be used by several programs. Such packages are independent of any program environment and have separate place for source code and separate libraries. For the moment there is only one such package:
mkdir getoswork
cd getoswork
$TOSCA/scripts/getosinstall
Now you could edit the getos.datacard file if you need that, assign to the
unit 11 (default input unit) the events generated by neglib:
ln -sf your_events.negfz fort.11
and run the default getos version:
$TOSCA_BIN/getos
The output will go to the unit 13 by default. A small hint: if the
output is huge and doesn't fit the directory quota you can redirect it
by saying before getos run:
ln -sf your/scratch/disk/events.fz fort.13
If you need to change some code or to add a new routine you copy or create and edit the Fortran file with .F(note capital F) extension and it will be compiled and the new executable will be made by typing:
gmake
The new executable will be named getos.OSF1 or getos.AIX depending on your computer
architecture.
You can copy all or several routines from framework of user described detector in $TOSCASRC/getos/usr/v0r1/*.F files. Or you can extract the getos/usr from CVS repository (see Software development section).
If you need to build a particular production version of getos you should type:
gmake GETOSVERSION=v0r1
where v0r1 is taken as an example.
If you want to build the getos with particular version of some package you could specify that on command line:
gmake ETVERSION=v0r1
where ET and v0r1 were taken as an example. ET is one of the packages
of getos (see Programs and packages section).
Please note that packages do depend each other and the reference libraries were compiled with a specific version of another package. Although during the development the care is taken to be backward compatible it is possible that you will need to checkout the needed versions of packages from CVS repository and to recompile them. Thus it is not recommended to specify the version of one package unless you have some specific needs and enough experience to trace the dependencies.
To work with camel you need to do almost the same thing:
mkdir camelwork
cd camelwork
$TOSCA/scripts/caminstall
Next you need to fill the provided dummy files with analysis code:
gmake
You could edit the camel.data file to select the run and event range.
You need to assign the file to the default input unit 11:
ln -sf your/scratch/disk/events.fz fort.11
Please note that camel could not read neglib events for the moment.
If you have enabled the event output they will be written by default to the unit 13.
You can get more information about camel from NOMAD documentation repository http://nomadinfo.cern.ch/pub/doc/ps/camel.ps. Note that it is quite outdated but still usefull. You can get the genom512 documentation from the same place http://nomadinfo.cern.ch/pub/doc/ps/genom512.ps. Genom is the origin of getos and they have a lot of things in common.
The following is intended for the software developer and not to the causal user. Most probably you don't need to read that if you have no intention to develop a detector simulation code or TOSCA software.
All the code of the TOSCA software should be placed in the CVS repository. For the time being there is only one TOSCA CVS repository defined by TOSCA_CVSROOT environment variable. It is highly recommended to keep only one repository. The development could be done on any computer as far as it has either AFS client software or the CVS software with remote repository capabilities (the latest versions from GNU for example).
The first step in the development is to set the TOSCA repository as a default
one:
setenv CVSROOT $TOSCA_CVSROOT
You need to create your development directory as well as directories
for binaries and libraries:
mkdir your_development_dir
cd your_development_dir
mkdir bin
mkdir lib
You need to set environment variables to describe your configuration:
setenv USERSRCDIR /path.../your_development_dir
setenv USERLIBDIR $USERSRCDIR/lib
setenv USERBINDIR $USERSRCDIR/bin
Next you want to get your private copy of the latest development code of getos
as example:
cvs checkout getos
The subdirectory getos will be created with all the tree of packages and code.
Most probably you don't need the code for the whole program but only for one package (ET for example). Instead of the previous line you can type:
cvs checkout getos/et
The subdirectory getos/et will contain all the code of the package.
If you need to get from CVS repository given version of a package you can checkout it providing the version number:
cvs checkout -r v0r1 getos/et
Now you change your current directory to getos/et and edit all the files you want to change or you create new ones. Note that there are two kind of packages: the simple package has only root directory with the source files, include files and documentation. The getos/usr package could be an example. Another kind of packages could contain several subdirectories (usually doc, include and src but there can be a lot of source subdirectories).The getos/nom package is a good example of such kind.
Having changed the code you need to compile and debug it. To compile the private
version of library you need to call:
gmake
To build the executable with your version(s) of packages you should follow the step described in Programs and packages section. As far as your environment variables USERSRCDIR and USERLIBDIR are defined the right versions of libraries will be used. If your variable USERBINDIR is defined the executable will be placed in that directory instead of current one.
If you want to see the changes you have made to the code you can type
cvs diff -c
You could give to the command the list of files for which you want to see the changes.
To see the log records of changes made to file you can type:
cvs log src/crazy.F
As development goes people are adding the different pieces of code to the repository. If you want to use that code you need to update your copy of source:
cvs update
You will get all the changes made by other people inserted into your copy and
new files will be created if somebody else has added the file to repository.
If you want to see the difference between your code and the lastest version in the repository you can type:
cvs diff -D now -c
It is possible that you and another person have changed the same piece of code in a different way. Such situation is called conflict because although CVS is quite smart in patching and merging different versions in the case of conflict there is two alternatives and it is the developer who needs to decide which one should be used. CVS informs you during update about such situation and puts both variants into the file separating them like what:
<<<<<<<<<<< crazy.F Here goes your version of code =========== Here is the latest version from repository >>>>>>>>>>> version 1.3
The Fortran complier will signal error to you as such piece of code don't follow Fortran standards. You need to resolve the conflict by choosing one version over the other one or merging them if possible. Next you need to commit the resolved code into repository. How to do that is described in the next section.
If somebody other has added new subdirectory to the package the update command will not create it in your copy of code. You need to go up to the directory where you have checked out the package and checkout the source again:
cd ../..
cvs checkout getos/et
All the changes you have made will be kept.
The CVS is only the code keeper. It doesn't provide the environment for building the libraries and executables with right versions of libraries. That work is done by a set of Makefiles and GNU make. In the directory $TOSCASRC/Rules where are templates of Makefiles:
If you are going to create a new package you need to copy them and modify typing in the name of the program and the package and setting the variables DEFINES and INCLUDES to the list of the compile-time options and the list of the directories that contains the include files you code need for compilation.
During the development of package you could add more compile-time options and/or references to include files in other directories. In such cases you will need to modify the variables DEFINES and INCLUDES in the top Makefile of your package.
As far as you have added and debugged a new feature of code you could add that to the CVS repository and in such way to share the results of your work with other people. All the operations mentioned below will change the CVS repository. Although the commit could be played back it is better to avoid such situations. That's why only limited number of people could do the following operations. If you think that you should be among them ask the CVS master to add you to the list of developers of given package. Or you can ask a person who is in the developer list to do it for you. Your development directory files should be readable by him or her.
If you have created the new file(s) or directory you should inform cvs about that:
cd src
cvs add crazy.F crazy.doc
cd ..
If some files are not needed anymore you can remove them:
cd include
rm oldies.inc goldies.inc
cvs remove oldies.inc goldies.inc
cd ..
Note that the files will not be removed from repository but will be kept
in the Attic subdirectory.
Now you can commit the code:
cvs -e pico commit
The cvs will call the text editor pico to allow you to type the descriptions of changes made. Try to avoid very short messages, rather describe what you've implement and in which way it was done.
If you don't want to commit all the files you can commit only selected ones
cvs -e pico commit src/crazy.F src/crazy.doc
If commit was not done most probably it is due to the conflict. You need to update your code, resolve it and try to commit again.
If you are going to change include files which are used by other packages you need to be very careful. Each library is compiled with include files of particular version of your package. Changing the files in a non-backward compatible way will lead to hard-to-find problems in program. Thus you should have really good reason to do that and you should inform all the people concerned about the incompatibility. Most probably you will increase the version number of your package instead of increasing the release number. A few usefull hints: If you want to add variable to the COMMON block add it at the end of common. If you are using vector of different values in common it is better to provide a few spare words (the same applies to the ZEBRA banks). Keep at some place the version number of you package so others could check it in program and make workaround. Try to make ZEBRA banks self-descriptive as it is done in the NOMAD raw hits for example. Store somewhere in run header or in bank the version number of package that has produced the banks.
You can find more information about CVS by typing:
man cvs
at any computer where cvs is installed (cernsp,dxplus or csf as an example).
Or you can get the introduction, full documentation or source from the Web
http://asdwww.cern.ch/pl/cvs/index.html.
The GNU make manual can be found under two names:man make
man gmakeYou can get the full documentation from the Web http://www.cygnus.com/pubs/gnupro/5_GNUPro_Utilities/e_GNU_Make/make.html
The following is intended for the software librarian and not to the developer. Most probably you don't need to read that if you have no intention to be responsible for a detector simulation code or another piece of TOSCA software.
To be written soon
To be written soon