Code Management
This is a quick-reference guide for Geant4 developers who need
to access to the Geant4 SVN repository and perform operations by using
the subversion version control system.
Please also look at the
Tag & Release
Policy document for Geant4.
For a more exhaustive tutorial on SVN, see documentation you find from
the original SVN
Home Page.
The Geant4 SVN repositories are located on the svn
server svn.cern.ch.
There are repositories for source code (in geant4),
documentation and
papers (in g4documents), validation and testing (in g4tests),
and Geant4-related tools (in g4tools).
The repository is accessible only through svn/g4svn commands
using
either the https or svn+ssh protocol. The
repository is
only accessible to collaborators after signing-in once a year to
confirm their
Collaboration
membership and acceptance of the Geant4 regulations.
Access to the web form is only available to collaborators; if you
cannot access the form, contact your working group coordinator to get
you onto the list of collaborators.
- The GEANT4 SVN repository structure
- Browsing the Geant4 svn repository
- How to setup and access the repository
- Checkout and update the code
- Checkout of User Documentation
- Viewing changes and resolving conflicts
- Committing changes to the repository
- Tagging and versioning
- Useful SVN commands
- Information on svn
- Where to find released source code
The Geant4 source is actually structured in the source
directory
under geant4 in a tree of directories following the category
and
subcategory structure. Other directories under geant4 include
examples, tests, etc.
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 unit test
applications specific to the related sub-domain, to test the code under
distinct conditions.
The Geant4 code repository has three top level
directories,
trunk, tags, and branches.
- trunk
- Current development under the directory geant4
(corresponding to the HEAD in CVS);
- tags
- Contains tagged versions of geant4 and of all
(sub)categories in a directory tree. The code therein cannot be
modified;
- branches
- Contains branches of geant4 and for (sub)categories in a
directory tree.
The svn repository can be browsed using the svnweb
interface, to login use your CERN account.
The svn servers allow to browse the
Geant4 repository using the svnweb
interface.
To use svn, your need to check and install or set up the
following:
- svn must be installed on your machine and must be in
your PATH
- You need to get access to g4svn, a script to help
with complicate svn commands.
- python is needed by g4svn, and version 2.4, or
higher, is required. On slc4, python is version 2.3, and this will
fail. On slc4 machines at CERN, use g4svn.sh from the geant4 dev area /afs/cern.ch/sw/geant4/dev/scripts
to use g4svn with a recent version of python.
- access via ssh. If you are prompted for a password
by svn, g4svn will prompt you many times for a single command. Please
follow instructions below to set up "trusted" access for ssh.
Install svn
You need to have svn installed on your machine. This
is normally either installed or can be installed using system tools.
Access the tool g4svn
To work with Geant4, you also need a Phyton script g4svn
to simplify the svn operations with most complicated syntax.
Please note that in most cases below the plain svn command is
used directly, while in a few cases you need to use g4svn.
This g4svn script is available either using directly
svn, or at CERN its available from the Geant4 dev area,
see blow. If you want to install svn into $HOME/bin, do:
cd $HOME/bin
svn co svn+ssh://_Your_CERN_login_@svn.cern.ch/reps/g4tools/trunk/svntools/g4svn .
- or -
cd $HOME/bin
svn co https://svn.cern.ch/reps/g4tools/trunk/svntools/g4svn .
using either the svn+ssh protocol (preferred, see
below) or the https
protocol.
The "." at the end of the command can be replace by a directory "xyz",
then checkout will then be placed into this directory, i.e. into
$HOME/bin/xyz in the example above. In case of problems with the svn,
you can can also download the g4svn tool as a zip file.
At CERN you can also use g4svn from the Geant4 AFS
dev area /afs/cern.ch/sw/geant4/dev/scripts.
g4svn should be in your PATH, so you either copy g4svn into a
directory in your PATH or you add its directory to your PATH; on Unix
~/bin very often is in the PATH.
For Windows follow the instructions in the
g4svn documentation.
Set up trusted ssh access
If you are asked for a password by svn, you shoukd
set up "trusted" access where you
deposit the public part of an ssh key generated on you machine on teh
webserver. Detailed instruction for to set this up are available in the
intructions from the CERN SVN service team.
Choice of protocol to access the svn server
Access to the repository is given either using the svn+ssh
protocol, or using the https protocol. Using svn+ssh
will in general be the simpler and safer method from all locations,
if ssh is available. The use of the https protocol caches
information locally, including the password in an encrypted form.
Using the svn+ssh protocol nothing is cached.
Once the environment for the above is set, you are ready to
checkout
the software. In the following examples we use the svn+ssh
protocol, if you prefer using https, replace svn+ssh
with https in the examples below (let's suppose to use
$HOME/ as checkout directory).
- If you are going to build the SVN tree in the local
working-space for the first time, the command (for the SVN geant4
module) to check out the current trunk of the repository (what
referred to be the HEAD in CVS), is:
cd $HOME
g4svn co trunk
NOTE that the trunk in general will fail to compile. You should
check out a reference tag, or release instead (i.e. using the
reference tag geant4-09-04-ref-00):
cd $HOME
g4svn co geant4-09-04-ref-00
will checkout the reference tag into the directory geant4. If
your local account differs from the login at CERN, you will need to
provide the login using the option --login:
cd $HOME
g4svn co --login="your_CERN_login" geant4-09-04-ref-00
Alternatively you directly may use svn to do the checkout:
cd $HOME
svn co svn+ssh://"your_CERN_login"@svn.cern.ch/reps/geant4/tags/geant4/_symbols/geant4-09-04-ref-00 geant4
Next you will need to update, or switch, the subcategory/ies you are
working with to the trunk using g4svn. As example, if you
want to change files in the run category, you need to switch run
to the trunk:
cd geant4/run
g4svn switch trunk
- To update the local geant4/ tree and checkout from
the repository all last modifications and new files:
svn update
Note that this will only update those parts of the
(sub)directory tree which had been switched to the trunk.
- To see what has changed since the last checkout, update, or
commit in the local tree geant4/:
svn status
This command just prints to the standard output.
- To see differences of the repository and the local tree geant4/:
svn status -u
This command just prints to the standard output.
- To update just a category in the local geant4/
tree, to a specified tag for it (example, tag "run-V09-03-00" for the run
category):
cd $HOME/geant4/source/run
g4svn switch run-V09-03-00
- To update to a specific reference tag (e.g. tag
"geant4-09-04-ref-00"):
cd $HOME/geant4
g4svn switch geant4-09-04-ref-00
4.1 Checkout of User Documentation
The User Documentation is a seperate repository, g4documents, which
also has trunk/, tags/ and branches/ subdirectory.
- To check out the trunk of user documentation,
use teh following svn command:
svn co svn+ssh://"your_CERN_login"@svn.cern.ch/reps/g4documents/trunk/documents/UserDoc
This repository also has lots of documentation and papers, use svn ls
to browse, e.g.
svn ls svn+ssh://"your_CERN_login"@svn.cern.ch/reps/g4documents/trunk/
svn ls svn+ssh://"your_CERN_login"@svn.cern.ch/reps/g4documents/trunk/documents
...
From whatever sub-tree of $HOME/geant4/, by typing
...
svn status -u
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
also
display the contents of new directories which may have been
introduced
in the repository !
Use
svn status -h
to get a full explanation of the output produced by svn status.
Once sure of all modifications made, having checked that there
are no clashes
with files, and locally tested that everything works fine, changes and
new
files can be committed to the repository.
- First update to the trunk revision of the
repository (unless you need to work on a branch...):
g4svn switch trunk
- If there are new files which must be committed, SVN 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 then do:
svn add new_file
for each new file (where new_file is the name of the file), or
else
svn 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:
svn add new_directory
SVN 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, SVN
has to be instructed as well. So first, locate to the right sub-tree
where the affected files are placed and do:
svn remove old_file <-- instruct SVN to remove the local file, and
to "delete" the repository version at the next commit
- To commit to the repository, locate to the right sub-tree
and do:
svn 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, SVN will open an editor forcing the user to write the
description of the committal for each sub-directory which has files for
committing.
With:
svn commit -m "description" file_name(s)
only the file file_name(s) will be committed in the repository.
NOTE 1 - Pay attention - the svn commit command
is going to modify the files in the repository!
NOTE 2 - If you are NOT working on a branch, you must
always update on the trunk before committing. Our SVN repository
will not allow commiting, adding or removing files to/from a tagged
version!
Symbolic tags are meant to permanently record which revisions
of which files
were used in creating a software distribution. The checkout and
switch 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 create a tag version of a directory tree, locate first
in the sub-directory corresponding to the sub-tree to be tagged and
then do:
g4svn tag tag_ID
where tag_ID is the label-name of the symbolic tag (e.g. run-V09-03-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:
g4svn switch tag_ID
This will switch your local tree to the tagged tree.
- Tagging individual files is not supported in general, as
our svn setup always operates on directories. An exception to
this rule currently is that tags for Makefiles and/or geant4/Configure
are supported, following a specific tags naming scheme any-gmk-Vxx-xx-xx
or Configure-Vxx-xx-xx.
Pay attention, the g4svn tag command writes directly
to the repository!
- To see the history and log messages for a specific file
xyz.cc:
svn log xyz.cc
This will give change history for the given file showing your the svn
revisions numbers the file was changed and the log message given at the
commit.
- To compare a checked out file to specific previous revision
svn revision number rev1
svn diff -r rev1 xzy.cc
or
tkdiff -r rev1 xyz.cc
show changes made in xyz.cc since revision rev1. Ommitting the optional
revision number
svn diff xzy.cc
or
tkdiff xyz.cc
wil show changes made to the local file.
- To compare two revisions identified by their svn
revision numbers rev1 and
rev2 of a file,
see svn log command to
get the revision numbers,
svn diff -r rev1:rev2 xyz.cc
or
tkdiff -r rev1 -r rev2 xyz.cc
Will show changes made in xyz.cc between revision rev1 and rev2. Note
the slightly different syntax using svn and tkdiff. One can also
compare the trunk against a revision in a branch or tag using full
repository URLs:
svn diff svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/g3tog4 \
svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/geant4-09-04-patches_branch/source/g3tog4
This will show all differences for all files under these two paths. A
more useful output is given by the --summarize option, showing which
files were modified:
svn diff --summarize svn+ssh://svn.cern.ch/reps/geant4/trunk/geant4/source/g3tog4 \
svn+ssh://svn.cern.ch/reps/geant4/branches/geant4/_symbols/geant4-09-04-patches_branch/source/g3tog4
- To browse the repository
svn ls
will show the files in teh repository of the current directory, useful
option are -R to
recurse subdirectories and -v
for verbose output showing the date, revision, and author of last
modification. With a repository URL specified, this path is used
instead of teh working directory.
- To see the repository URL, the revision, and other info
svn info
To have a complete view of the available commands on SVN, see
the documentation
from the originalSVN
Home
Page.
To have a detailed description of both g4svn, and more detail
on
svn commands, please see the
g4svn
documentation.
Also the documentation of the CERN SVN service will be
helpful.
To help the transition from CVS to SVN, here is a list of
svn commands equivalent to cvs commands.
The last
publicly
available code of geant4 is accessible from the Web.
|
