LHCb Web>LHCbComputing>CVSUsageGuidelines (revision 31)~~EditAttachPDF~~

The CVS service at CERN is being gradually dismissed and all the projects are being migrated to Subversion.

The migration of the LHCb repository will happen in steps (by group of pacakges). This page is still valid during the migration process, but it is integrated by SVNUsageGuidelines for what concern the Subversion support.

Using CVS in LHCb

The LHCb code is kept in a CVS (Concurrent Versioning System) repository (currently being migrated to Subversion). This page is intended for LHCb CVS users. Instructions for LHCb CVS librarians are available here.

For instructions about the usage of the Subversion repository, look at SVNUsageGuidelines.

Accessing CVS

Web access

The LHCb repository is world readable via the web, at http://isscvs.cern.ch/cgi-bin/cvsweb.cgi/?cvsroot=lhcb
Gaudi has migrated to SVN. World read web access to the Gaudi repository is at https://svnweb.cern.ch/world/wsvn/gaudi

Installing the CVS client

The cvs client is pre-installed on most Linux systems. The distribution for Linux can be obtained from ximbiot.com. If you prefer a GUI lincvs (or crossvc as it is called on newer systems, such as SLC5) is good and available on most systems.
On Windows we recommend the WinCVS client

Setting up read access

The LHCb CVS repository resides on the CERN/IT CVS server. Access is world read if you are already authenticated, typically Kerberos (AFS) authentication on Linux, ssh authentication (how?

) on Windows. To access the repository, set up the following environment variables:

Linux:

`CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb`

CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb

Windows:

`CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb CVS_RSH = C:\Program Files\PuTTY\plink`

CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb
CVS_RSH = C:\Program Files\PuTTY\plink

Setting up write access

To get write access to LHCb CVS repository:

Ask the LHCb CVS librarian: Hubert Degaudenzi, or one of his deputies: Marco Cattaneo, Loic Brarda, Joel Closier
Note that write access is normally granted for a subset of packages only, usually a "Hat" in the directory structure. Please specify the package group for which you require access

Accessing CVS without Kerberos IV (from January 30th 2009 and on)

From the beginning of 2009, the CERN IT is removing the support for the Kerberos IV authentication method. This has some side effects on way to connect to the CVS servers and the "kserver" (Kerberos IV) method cannot be used anymore on Linux. The CVS client has still to be installed as described here. It has been decided to move globally to the "ext" (ssh) method instead of the "gserver" (Kerberos V) method. It has the advantage to be the same on Linux, Windows and MacOS and it doesn't require to have a special patched version of the CVS client. For details on how to setup SSH access on UNIX systems, see here

It is important to note that for the users working on the lxplus cluster the change is almost transparent. The ssh client/server on these machine are using the Kerberos V tokens for the ssh authentication. The only part which is mandatory for them is the conversion of the already checked out sources.

The following instructions are detailing the various settings for CVS on standalone or external boxes. Please read them carefully.

Setting up read access

To access the repository, set up the following environment variables in order to use ssh:

Linux and MacOS:

`CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb CVS_RSH = ssh`

CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb
CVS_RSH = ssh

Windows:

`CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb CVS_RSH = C:\Program Files\PuTTY\plink`

CVSROOT = :ext:isscvs.cern.ch:/local/reps/lhcb
CVS_RSH = C:\Program Files\PuTTY\plink

and follow the instructions for Linux/MacOS and Windows to create your private/public key pair. For windows, there is however a little change to be done when creating the isscvs.cern.ch session in Putty. When you create your session call it "isscvs.cern.ch" and the host name is the same "isscvs.cern.ch" (in the Session section) and in the Connection->Data section put your autologin name as the user name you want to use. Putty will then forward automatically your user to the isscvs.cern.ch session and then you can simply do a :

`"C:\Program Files\PuTTY\putty" isscvs.cern.ch`

"C:\Program Files\PuTTY\putty" isscvs.cern.ch

Connecting with a different user name

For windows, it is quite simple. You just have to change the autologin name in the "isscvs.cern.ch" session. You can do it by loading the session in putty and change the username in the Connection->Data section as above.

For Linux/MacOSX, this is a little bit different because on these platform the username is always forwarded to the ssh connection. In order to change the username that ssh is using, you have to modify or create the ssh configuration file ~/.ssh/config. In that file, the entry for isscvs.cern.ch should look like:

Host isscvs.cern.ch    
   User myusername    
   Protocol 2
   ForwardX11 no
   IdentityFile ~/.ssh/id_rsa
Host svn.cern.ch
   User myusername
   Protocol 2
   ForwardX11 no
   IdentityFile ~/.ssh/id_rsa

where "myusername" is the name you want to use for the ssh authentication. Note that the entry for svn.cern.ch is needed since the latest getpack also queries this server.

To be noted that this procedure for the setting of the user name reproduces exactly the same behavior as the one with the former kserver method. It prevents the explicit embedding of the user name in the CVSROOT variable. This variable is reproduced in each and every CVS checked out directory (CVS/Root). There is a problem in the release areas and distribution kits if a given user name is hardcoded there. There should be no explicit user name.

Kerberos again

Moving from the kerberos method for ssh doesn't mean that it cannot be used at all. on Linux/MacOSX The Kerberos V token can still be used for the ssh authentication. It is forwarded to ssh which then creates the "ext" connection to the CVS server and this is the default at CERN on the lxplus cluster. On other machine or cluster (or external to CERN), you have to obtain your token from the CERN Kerberos domain and setup your ssh entry like:

`Host isscvs.cern.ch GSSAPIAuthentication yes Protocol 2 ForwardX11 no`

Host isscvs.cern.ch
     GSSAPIAuthentication yes
     Protocol  2
     ForwardX11 no

Modifications in getpack

After these settings, you are able to do a plain CVS source code extraction

`cvs co MyPackage`

cvs co MyPackage

on Linux, MacOSX or Windows. This is not however the usual checkout tool used in LHCb. The getpack utility is used for a plain checkout but it is also able to do a recursive checkout according to the CMT dependency.

The former behavior of the getpack script with the "ext" (ssh) connection method was to embed the user name in the connection string (":ext:myusername@isscvs.cern.ch:/local/reps/lhcb"). As we have seen above this not a good idea and now getpack doesn't include by default the username in the connection string (":ext:isscvs.cern.ch:/local/reps/lhcb"). The user name has to be tuned in the ssh configuration (~/.ssh/config or Putty) as described above if needed.

For backward compatibility, getpack will add anyway the user name in the "ext" connection string in one case: if the GETPACK_USER variable is defined. This is not recommended and this variable should be unset.

Converting the already checked out software sources

For the source code packages which have been checkout with the old "kserver" method (you can check in the CVS/Root file), they have to be converted to use the new method. The CERN IT is providing a migration tool for this:

`/afs/cern.ch/project/cvs/dist/bin/move2ssh`

/afs/cern.ch/project/cvs/dist/bin/move2ssh

This script has been run on the AFS LHCb release areas and it is recommended that you run it on your own checkout software sources (most of the time in the ~/cmtuser directory). This script has also been added for convenience in the $LHCBSCRIPTS directory.

If you don't convert your source directories, you wont be able to do a "cvs diff" or "cvs update" from January 31st 2009 and on.

Guidelines for CVS actions in LHCb

Creating a new package

If you wish to create a new package and add it to CVS, follow the guidelines given here

Guidelines for CVS commit

Commit often, but commit only code that compiles and runs (i.e. that does not prevent the configuration of the application).
- Before changing any released package, you should discuss the changes with the package owner (whose name usually appears in the cmt/requirements and doc/release.notes files). It is usually a good idea to inform the appropriate mailing list of the planned changes.
If this is the first modification to be committed after a release:
- Increment the version number in the cmt/requirements file
  - Increment the major version ( v) if the change is backward incompatible (change in interfaces, major change in behaviour)
  - Increment the minor version ( r) for a new feature or a bug fix
Document each commit in the file doc/release.notes
- Give a brief but meaningful description of the changes ("minor fixes" is not good enough)
  - But no need to document the fix to the fix that you committed a few hours ago
  - Please keep the lines short, max 80 characters per line, carriage return to a new line if necessary.
- Add your comment above the release separation line (done for you by the <insert> key in the LHCb emacs customisation)

! 2008-06-18 - Marco Cattaneo - This is the comment for the latest commit, do not touch anything below this line. !================== GaudiConf v10r9 2008-06-04 ========================

! 2008-06-18 - Marco Cattaneo
 - This is the comment for the latest commit, do not touch anything below this line.
 
!================== GaudiConf v10r9 2008-06-04 ========================

Check what you are about to commit against the repository:

`cvs -n update -A`

cvs -n update -A

This will list the actions that CVS will perform without actually applying any change (-n), identifying your modifications with M, any new files with ?, any files changed on the CVS repository since your last checkout with U, any files changed on the CVS repository and also modified by you with C, and any files removed by you but existing in CVS as lost. Once you're sure of your changes, you can call the same command again without the (-n) option.

- Remove any C in front of a file: C in front of a file means that several people are working on the same package so be careful: CVS has tried to merge your modifications with the changes already done and it has NOT succeeded. Check the merged files carefully: CVS marks with >>>>>> and <<<<<< the regions that have incompatible modifications. You must fix these (and remove the <<<<<< and >>>>>> before committing). Merged files only appear when you do not use the option (-n), but you then need to be more careful of what you do.
- Remove any ? in source directories: These are files that you added and that are not in the repository. If you wish to save them in CVS, you have to

`cvs add TheFiletoAdd`

cvs add TheFiletoAdd

do not add any file in the cmt/ directory, or any copy of a file that should not be kept (e.g. files whose name ends with "~")

- Tell CVS to remove from the repository the files you have deleted if any: files that were marked as lost are files that you removed. If you wish to remove them from CVS, issue the comand

`cvs rm TheFileToRemove`

cvs rm TheFileToRemove

- Check again the package:

`cvs update`

cvs update

- - Any C should have been replaced by M
  - Any ? should have been replaced by A
  - Any lost should have been replaced by R
- Finally, commit the package

`cvs commit -m "some brief and meaningful one line comment"`

cvs commit -m "some brief and meaningful one line comment"

Always tag a package after a CVS commit. See the Guidelines for CVS tags
The next day, check that your commit has not broken other packages
- Check the nightly builds the day after your commit
- Fix any packages that were broken by your commit (or ask the package owner to do it)

Guidelines for CVS tag

These guidelines were presented

on 18th June 2008 (33rd LHCb software week)

It is recommended to use a tag of the form <username>_<yyyymmdd> where <yyyymmdd> is the date of the commit. To tag the repository as of a certain date (e.g. now) do

`cvs rtag cattanem_20080620 Rec/Brunel`

cvs rtag cattanem_20080620 Rec/Brunel

or to tag according to what's presently in your directory, do in your directory (e.g. Rec/Brunel):

`cvs tag pkoppenb_20080620`

cvs tag pkoppenb_20080620

See section 4.6 of the cvs user guide

for details.

Do not use an official tag of the form vxry
Add the new tag to the tag collector (how?) to inform the release manager of the new tag if you would like it include in the next official release.

How to alter a tag

It is likely at some point you will tag a package, only to discover you have forgotten to commit a change to CVS beforehand. In this case the best thing to do is to remove the tag, make the missing changes and then retag. E.g. remove the tag theTag

`cvs rtag -d theTag Det/RichDet`

cvs rtag -d theTag Det/RichDet

make your changes, and then tag again

`cvs rtag theTag Det/RichDet`

cvs rtag theTag Det/RichDet

This also works with cvs tag. You can also do it in one step by Forcing the tag,

`cvs rtag -F theTag Det/RichDet`

cvs rtag -F theTag Det/RichDet

but this is only safe if you have not removed any files. If you have removed files, the -F does not remove the tag from the files that have been moved to the CVS archive, so if you later checkout theTag you will get back the removed files. It is recommended to use the first method in this case.