AliRoot Code Development
- Software Development Environment
- Coding Conventions
- Code Management
- Global Development Schema
- Module Development Schema
IMPORTANT! Recently the AliRoot code was transfered to CERN Central SVN Service.
HowTO for Subversion repository
Software Development Environment
At the moment the ALICE Off-line Project has adopted no official code development environment. ALICE has participated to a project with the IT/IPT group aimed at providing a common Software Development Environment for the LHC experiments, but this has now been frozen.
It has been decided by the ALICE Off-line Project to adopt UML as a standard for exchanging information on class design. No Software Development Tool has been selected at the moment, and hand-drawn schemas are perfectly acceptable for public discussions. A list of what is available can be found in the SDT page of the IPT/IT group. A mini-tutorial on UML has been prepared for ALICE users.
Dynamic class diagrams can be obtained directly by ROOT from the Classes->Class Tree menu of each canvas.
The Alice Off-line project has defined a set of coding conventions. Their purpose is to make the code easier to understand and maintain thanks to the adoption of a good programming style. The collaboration between CERN-Alice and ITC-Irst resulted in the delivery of RuleChecker, a tool for the automatic verification of the code compliance with Alice coding conventions. It is the responsibility of the authors and Package Coordinators to make sure that the code delivered follows the coding conventions.
The AliRoot project source code is maintained using a version system called Subversion (svn) . svn is used for versioning and for concurrent development by different authors. A HOWTO for SVN in aliroot is available. Please also read the instructions provided by CERN Central SVN Service about how to access and manage the repository
CERN Central SVN Service allows annonymus/guest access. This implies only read access, users being able to download and compile AliRoot
Read Only Access
An anonymous/guest read-only access is provided using http protocol. Example:
svn ls http://svn.cern.ch/guest/AliRoot/branches
svn co http://svn.cern.ch/guest/AliRoot/branches/v4-09-Release AliRootHow to get an administrative login ?
To get a login, a developer should have the permission of the module administrators for each module with write access. Then he/she has to send an e-mail to the AliRoot Program Librarian with the following information
- your CERN computing account. AliRoot repository is hosted on CERN Central SVN Service which requires a valid computing account. Note that you can have a computing account without a full registration at CERN.
- the list of modules where write access is requested;
- the list of modules for e-mail notification.
We wish to stress out that a module developer has full read write access to its module which implies some care while checking in the repository.
To access the svn repository the developer has to use https or svn+ssh protocol for the first checkout:
svn co https://svn.cern.ch/reps/AliRoot/trunk AliRoot (or)
svn co svn+ssh://svn.cern.ch/reps/AliRoot/trunk AliRoot
The first attempt to commit will require username and password that will be stored in encrypted form in $HOME/.subversion/ The next commits will require no password.
For more information on how to use the svn repository to install ALICE's software, please see installation.
All registered users of a module are authorized to commit modifications in this module. This means that they have full write access on the module and, therefore, should be careful of their actions. The SVN permissions protect modules from modifications from users of other modules. When committing a file "svn commit AliTPC.h" an editor is started which prompt for a comment. An empty comment results in a failure of the commit. A mail is issued to all users from the module so as to warn them of the modifications.
Only the AliRoot Program Librarian is authorized to create tags and branches in the repository and to modify them.
How to update the last modifications ?
It is possible for all users (read-only operation). You just have to run "svn update" in the working directory. This command may try to merge personal modifications with other developers modifications. In this, the developer has to check that these merge operations are correct before committing the new files.
The development of the code and the release procedure is explained by this schema:
In the following we will explain the procedure using the svn notation. In svn all the files have a version number, that reflects the number of times each file has been modified. A tag is a snapshot of the files, at a given moment, each with its own version number. This allows to retrieve, refer to and identify a given status of the whole repository, without having to know each individual version number of each file. The snapshot is copied in the AliRoot/tags directory on the server. No changes are allowed in a tagged version.
svn has the possibility to maintain parallel lines of development. These are called branches. Modifications of the files of a given branch can be made without affecting the other branch. In analogy with this tree-like naming schema, the first line of development is called main branch or trunk. A branch is a copy of the trunk to the AliRoot/branches directory on the server. Bug fixes and minor modifications are allowed in the branch.
When the release code is ready, a branch is created (vX-Release-YY). Patches introduced to the released code are tagged starting from this branch. The development of the next release continues on the main branch (trunk). From time to time this code is tagged to mark important steps in the development of the next release, and these tags are based on the main branch.
On the afs directories at CERN, the previous release code and libraries are moved in the old directory tree, while the new release is moved onto the pro directory tree and the cycle begins again.
The CVS repository is divided into modules. Several of these modules correspond to subdetectors of ALICE. As it is explained above for each of these modules few people in each project will have the write to commit changes. It is very important that some discipline is used in this process, because a large number of people will have write access to the master repository of the ALICE Off-line software. For the moment the following rules have been decided and will have to be respected:
- No modification has to be made on the release branches. The pro branch can be modified in case of bugs, but only by the ALICE librarian. Requests for modifications have to be sent to him/her.
- The trunk can be modified by the librarian and by the members of the projects with write access. This branch is the current new version, and it is expected to be reasonably stable, i.e. it should compile and run. It is not required to be bug free, even if this should be the final goal. Management of the code is in the hands of the projects, but the librarian can intervene to fix minor details or make global changes in agreement with the projects. One week before the release projects should not make any modifications to the trunk to allow the librarian to prepare a coherent and stable release.
- Always put a meaningful comment when checking in files. Comments should not be too long, but should indicate clearly the modifications made.
- Always try to make atomic commits. It means to commit the logically related modifications together with the same comment.
- No test operations should be made on the repository. Mistakes can always be undone in svn, but their trace stays there and cannot be removed. Too many undo's will make the repository messy and difficult to manage.
- Always add the following copyright notice at the beginning of each new .cxx file:
/*************************************************************************
* Copyright(c) 1998-2008, ALICE Experiment at CERN, All rights reserved. *
* *
* Author: The ALICE Off-line Project. *
* Contributors are mentioned in the code where appropriate. *
* *
* Permission to use, copy, modify and distribute this software and its *
* documentation strictly for non-commercial purposes is hereby granted *
* without fee, provided that the above copyright notice appears in all *
* copies and that both the copyright notice and this permission notice *
* appear in the supporting documentation. The authors make no claims *
* about the suitability of this software for any purpose. It is *
* provided "as is" without express or implied warranty. * **************************************************************************/ - Always add the following copyright notice at the beginning of each new .h file:
#ifndef classname_H
#define classname_H
/* Copyright(c) 1998-1999, ALICE Experiment at CERN, All rights reserved. *
* See cxx source for full Copyright notice */
/* $Id$ */
The above rules are not, and probably cannot, be enforced by the server. It is therefore of the highest importance that they are understood and applied by those who have write access to the repository.
The following is a sample session on how to create a development branch then merge it back with the head. We suppose to be working with the ITS code.
$ cd $ALICE_ROOT |
Set working directory |
$ svn status -u |
Check the status of the directory. |
$ svn update |
Make sure that the directory is up-to-date. |
| Here starts the development work. | |
$ emacs ... |
Develop and test the code. |
$ svn commit -m "Meaningful message" |
Check in the code into the trunk. |
| Repeat the above till you have all the features needed for the next release. | |
