CVS Code Management

Code Management

This is a quick-reference guide for GEANT4 developers who need to access to the GEANT4 CVS repository and perform operations by using the CVS version control system.

Please also look at the Tag & Release Policy document for GEANT4.
For a more exhaustive tutorial on CVS, see documentation you find from the original CVS Home Page.

The GEANT4 CVS repository is located on the cvs server geant4.cvs.cern.ch in the directory /cvs/Geant4. It is accessible only through cvs using either the kserver or ssh protocol. The repository is only accessible to users listed in an access file. Therefore, whoever wants to have access rights to the repository should ask to one of the ZB group Administrators to be added to the users lists.

The GEANT4 CVS repository structure
How to setup and access the repository
Checkout and update the code
Viewing changes and resolving conflicts
Committing changes to the repository
Tagging and versioning
Useful CVS commands
How to compile and run a GEANT4 application
Where to find released source code

1. The GEANT4 CVS repository structure

The code is actually stored within the geant4 tree, while all documentation and diagrams are stored in the documents tree. The source is distributed according to each sub-domain.
The sub-domain global is a place holder for all the development done which affects all the sub-domains.
include directories contain header files (.hh) and inline functions definition files (.icc); src directories contain the related implementation files (.cc); test directories contain test applications specific to the related sub-domain, to test the code under distinct conditions.

2. How to setup and access the repository.

Some environment variables must be set before accessing the repository. The best solution is to set them once at login, putting the related commands inside the login shell script (.cshrc, .tcshrc, ...):

Access to the repository is given either using the shh protocol, or using the gserver protocol. ssh will be the simplest method from outside CERN, and whenever a CERN afs token is not normally present. The cvs service documentation shows how to avoid being prompted for the password for access via ssh.
- Access via ssh: two variables need to be set:
```
      setenv CVS_RSH ssh
      setenv CVSROOT :ext:USERNAME@Geant4.cvs.cern.ch:/cvs/Geant4
```
  where USERNAME is your lxplus.cern.ch login name.
- Access via kersever: Support for access to cvs at CERN via kserver will stop end of January 2009. Please use gserver instead.
- Access via gserver:you need to set the repository path CVSROOT:
```
      setenv CVSROOT :gserver:USERNAME@Geant4.cvs.cern.ch:/cvs/Geant4
```
  where USERNAME is your lxplus.cern.ch login name.
Specify the system architecture G4SYSTEM (Linux-g++ for Linux systems, Darwin-g++ for MacOSX systems, SUN-CC for SunOS systems, ... NOTE: all architecture-specific setups are placed in geant4/config/sys).
```
      G4SYSTEM = Linux-g++                <-- e.g. for LXPLUS
      
```
Specify (optional) the default editor CVSEDITOR to be called by CVS when committing:
```
      CVSEDITOR = vi                      <-- e.g. select vi
      
```

3. Checkout and update the code

Once all the needed environment variables are set, the developer must go in his local file system to the directory where the software should be downloaded; let's suppose in $HOME/ ...

If you are going to build the CVS tree in the local working-space for the first time, use this command (referred to the CVS geant4 module), which will check out the current HEAD of the repository:
```
  cd $HOME
  cvs checkout geant4
```
To update the local geant4/ tree and checkout from the repository all last modifications and new files:
```
  cd $HOME/geant4
  cvs update -d -P
```
To see what is changed from the current HEAD version in the repository and the local tree geant4/:
```
  cd $HOME/geant4
  cvs -n update -A
  
```
This command just prints to the standard output.
To update the local geant4/ tree pruning empty directories:
```
  cvs update -P
```
To update just a category in the local geant4/ tree, to a specified tag for it (example, tag "run-V09-01-00" for the run category):
```
  cd $HOME/geant4/source/run
  cvs update -r run-V09-01-00
```
or
```
  cd $HOME/geant4/source
  cvs update -r run-V09-01-00 run
```
To update a category to HEAD (therefore removing sticky tags for that category), checking-out possible new files (-d option) and pruning (-P option) empty directories (example for run category):
```
  cd $HOME/geant4/source/run
  cvs update -A -d -P
```
To checkout a released tree (e.g. tag "geant4-09-01"):
```
  cvs checkout -r geant4-09-01 -d geant4
```
To update to a specific reference tag (e.g. tag "geant4-09-01-ref-02"):
```
  cd $HOME/geant4
  cvs update -r geant4-09-01-ref-02 -d -P
```

4. Viewing changes and resolving conflicts

From whatever sub-tree of $HOME/geant4/, by typing ...

  cvs -n update -A

the system will print out to the standard output which files have been changed in the repository or modified in the local sub-tree. It will not display the contents of new directories which may have been introduced in the repository !

For each file changed or modified, the system will display a checkmark before its name:

U .../file
there exists a newer revision of this file in the repository.
P .../file
there exists a newer revision of this file in the repository. The file is patched (to be transferred) and updated.
A .../file
this file has been added in the local sub-tree but it has not yet been committed to the repository.
R .../file
this file has been removed from the local sub-tree (with cvs remove file), but the change has not yet been committed to the repository.
M .../file
this file has been modified in the local sub-tree, but not yet in the repository.
C .../file
this file has been modified in the local sub-tree, but in the meantime, in the repository, there has been an update of that file. In this case the file cannot be committed to the repository until the clash is resolved. First update from the HEAD of the repository (cvs update -A file). CVS will then attempt to merge the changes. Mostly, this works fine, but check what it has done. Occasionally, when a unique merge is logically not possible, it says Conflicts during merge; watch especially carefully for this. It marks the alternative possibilities with lines beginning <<<<<<, ======, or >>>>>>. Edit the file and resolve the conflicts, then commit the file (cvs commit file). (CVS puts a copy of your original file in .#filename.v.1.2 or some such).
? .../file
this file is in the local sub-tree, but it doesn't correspond to anything in the repository. It doesn't appear in the repository file list.

5. Committing changes to the repository

Once sure of all modifications made, having checked that there are not clashes with files currently in the repository and locally tested that everything works fine, changes and new files can be committed to the repository.

First update to the HEAD revision of the repository (unless you need to work on a branch...):
```
    cvs update -A
    
```
If there are new files which must be committed, CVS has to be instructed first to add them to the repository. So first, locate to the right sub-tree where the new files are placed and do:
```
    cvs add new_file
    
```
for each new file (where new_file is the name of the file), or
```
    cvs add *
    
```
to add at the next committal all new files placed in that sub-tree (be careful not to add "rubbish" files...).
If there's a new directory to be added, then on doing:
```
    cvs add new_directory
    
```
CVS will be instructed to add the new directory and every file inside it at the next committal.
If there are files to be deleted from the repository, CVS has to be instructed as well. So first, locate to the right sub-tree where the affected files are placed and do:
```
    rm old_file             <-- remove it from the local tree
    cvs remove old_file     <-- instruct CVS to remove it at the next committal
    
```
To commit to the repository, locate to the right sub-tree and do:
```
    cvs commit -m "description"
    
```
where description is a reasonable message specifying what the committal is meant to update. This command will commit all modified files in the current sub-tree. If the -m option is not specified, CVS will open an editor (CVSEDITOR) forcing the user to write the description of the committal for each sub-directory which has files for committing.
With:
```
    cvs commit -m "description" file_name
    
```
only the file file_name will be committed in the repository.

NOTE 1 - Pay attention - the cvs commit command is going to modify the files in the repository!
NOTE 2 - If NOT working on a branch, always update on the HEAD before committing. CVS allows the addition and removal of files from sticking tags, a feature which might generate some confusion and alter already established and consistently tagged code.

6. Tagging and versioning

Symbolic tags are meant to permanently record which revisions of which files were used in creating a software distribution. The checkout and update commands then allow one to extract an exact copy of a tagged release at any time in the future, regardless of whether files have been changed, added, or removed since the release was tagged.

To fix a symbolic tag, locate first in the sub-directory corresponding to the sub-tree to be tagged, be sure that the tag is not already existing and then do:
```
  cvs tag tag_ID
  
```
where tag_ID is the label-name of the symbolic tag (e.g. run-V03-00-00). This command will tag all files contained in that sub-directory recursively and the sub-directory itself.
To update to the tag just done:
```
  cvs update -r tag_ID
  
```
This will set your local tree to the sticky tag.
To tag a specified file file_name:
```
  cvs tag tag_ID file_name
  
```
To remove a tag from a file:
```
  cvs tag -d tag_ID file_name
  
```

Pay attention, the cvs tag command writes directly to the repository!

7. Useful CVS commands

To have a complete view of the available commands on CVS, see the documentation from the original CVS Home Page.

To display a brief report on the current status of files with respect to the source repository:
```
  cvs status -v file_name
  
```
To display log information for a given file/directory about related revisions:
```
  cvs log file_name
  
```
It is also possible to specify a date to select the single latest revision or earlier:
```
  cvs log -ddates file_name
  
```
where dates is a specific date (e.g. -d2007/01/14 specifies to look at revisions till 14^th January 2007).
To compare different revisions of files:
```
  cvs diff -r tag_ID1 -r tag_ID2 file_name
  
```
where tag_ID1 and tag_ID2 are the label-names of different symbolic tags or revisions (e.g. geant4-02-00 and geant4-03-00, or 1.3 and 1.4).

It is also possible to specify a date:
```
  cvs diff -D date1 -D date2 file_name
  
```
(e.g. -D 2006/01/01 -D 2007/02/05, from 1^st January 2006 to 5^th February 2007).

8. How to compile and run a GEANT4 application

The GEANT4 package needs to run with the STL (Standard Template Library) C++ library available in the system, and the CLHEP software installed. This is currently sufficient to link libraries and build executables, excluding visualization.

To build GEANT4 executables including the visualization part, one also needs specific graphics libraries, depending upon the graphics system chosen.

For local systems, one has to check the availability and location of the graphics libraries (see also the User Documentation for clues to what is required).

The code is compiled in optimised mode by default (NOTE: this saves a lot of disk space !!). To compile in debug mode, the user should define first the G4DEBUG environment variable:

  G4DEBUG = 1

To compile the code overriding environment variables predefined inside architecture.gmk one should add a -e option to the gmake command which causes shell environment variables to take precedence. Watch in this case for inadvertant overrides !

8.1. How to build libraries and tests excluding visualization

Once set the needed environment variables and built the geant4/ tree on the local file system, do:

  cd $HOME/geant4/source
  gmake

This will create all necessary libraries for each sub-domain.

Typing:

  cd $HOME/geant4/source
  gmake clean

all libraries (.a), object-files (.o) and compilation dependencies (.d) (the current system installation) will be cleaned-up.

The command:

  gmake clean_lib

deletes the libraries only (they are quickly re-made at the next gmake) for the current installation.

The command:

  gmake clean_all

removes ALL Geant4 installations.

Once all kernel libraries are installed, it is suggested to the developer to define his working area (possibly detached from the Geant4 installation area G4INSTALL), through the environment variable G4WORKDIR.

To build a test executable, G4TARGET is the environment variable which identifies the executable to be built. It is not necessary to specify it for the standard examples provided with the toolkit.
e.g. exampleN01 (tcsh):

  cd $HOME/geant4/examples/novice/N01        <-- locate directory
  gmake                                      <-- compile and link

The binary will be placed in $G4WORKDIR/bin/$G4SYSTEM.

8.2. How to build libraries including visualization

For all detailed information about installation, please refer to our User Documentation. Here you can find the minimum set of instructions.

Once the needed environment variables are set and the geant4/ tree built on the local file system:

Depending on the graphics system chosen define one of the following environment variables to the path where software is located.
If OpenGL:
e.g. (for the MesaGL installation in the Geant4 development area)...
```
 G4VIS_BUILD_OPENGLX_DRIVER = 1
 G4VIS_USE_OPENGLX = 1
 OGLHOME = /afs/cern.ch/sw/geant4/dev/Mesa/$G4SYSTEM
 
```
G4VIS_BUILD_XXXXX flags allow to build the needed drivers inside G4 kernel libraries.
G4VIS_USE_XXXXX flags allow the usage of the graphics system at run-time.
(On some systems, you might find libGLX.a is missing.
Ask your system administrator to make a link:
ln -s libGL.a libGLX.a.
Also, if you are using Mesa, you might need:
ln -s libMesaGL.a libGL.a and ln -s libMesaGLU.a libGLU.a)
If one wants to run DAWN, the renderer developed at Fukui (Japan), one must install it first locally, or use the pre-compiled package installed in /afs/cern.ch/sw/geant4/dev/DAWN/$G4SYSTEM and set the corresponding DAWN_HOME environment variable to point to the path where the package is installed.
Build libraries and executables and run them.

9. Where to find released source code

The last publicly available code of geant4 is accessible from the Web.