CMT developers' guide

This document was rewrote by Ma Qiumei based on Li Weidong's guide.

This page explains how to work on the boss with CMT, cvs tools. Please follow this so we get uniformity in our software repository.

Note on shells: all instructions here assume you are using the bash shell. If you use tcsh, there will be some small  changes.

If some problems, Please let me know.

mail:maqm@ihep.ac.cn

tel:88233733

Contents

Access control

For write access, i.e. to import new packages or to commit and tag changes, you have to ask for permission to be set up. Please contact the maqm@mail.ihep.ac.cn about this. 

How to get started with boss

CMT environment setup on lxplus farm.

How to create a new package

This section describes how to create a new package to work with, which is private to you. Firstly , choosing a location and a name , the name must be a unique package name in boss (should not either just differentiate by case of letters).You'd better decide on a good name and location now. 

First change to the directory in which the package should be created. Normally this will be in your development area. Then use the cmt create command: 

  cd <dev area>
  cmt create <packagename> <version>
This creates a package with the name <packagename> and first version <packagename>-00-00-01, following the boss convention on version names.

Go into the cmt directory created for you and edit requirements. See the CMT manual for details of what goes in this file. 

Package layout -
the following files and directories will be created automatically: 

src/               directory for source files and private include files
cmt                directory for CMT files
cmt/requirements   the one CMT file you have to create for each package
You'd better also create the following youself: 
<packagename>/    directory for include files needed by client packages
test/              directory for files needed for private tests??
doc/               directory for documentation files??
share/             directory for platform-independent config files, scripts, etc.
README             text file, briefly describing purpose and context of package
ChangeLog          record of changes
When you create source files, please use these very basic templates as a starting point, or just cut and paste the few lines into your file: 

Header files

// $Id: devguide.html,v 1.1 2005/08/25 09:34:35 wensp Exp $ // -*-c++-*-
// a template header file for a class called "Template"
#ifndef BES_TEMPLATE_H
#define BES_TEMPLATE_H
// class definition goes here
#endif // BES_TEMPLATE_H

Source files:

// $Id: devguide.html,v 1.1 2005/08/25 09:34:35 wensp Exp $ // -*-c++-*- // a template source file for a class called "Template"

 #include "Template.h" // class implementation goes here

The name for the inclusion protection macro should be changed to include the name of your class. The file name and #include in the source file should of course be changed to your class name.

Building cycle

>cd cmt

>vi requirements

>cmt config

>source setup.sh

>gmake

Testting (if available)

for example:

./test.exe

How to import a new package into CVS firstly

 You should also get specific permission from the maqm@ihep.ac.cn to import a new package. It's necessary to avoid any chance of two packages having the same name which is not allowed by CMT.

Before you committing a new package, you must make sure that it works. It should compile and link without errors and with as few warnings as possible. 

First, cleanning up files produced by building, e.g. 

   cmt broadcast gmake clean
Remove all files you don't want to import, e.g. spurious config files.

Check you have correctly specified the author in your cmt/requirements file.

Then set CVSIGNORE to avoid importing files created by cmt config 

   export CVSIGNORE='setup.* cleanup.* *.make Makefile Linux-* SunOS-* Visual'

Then to import the package to cvs, you must issue the commit command from within the top dir you want to import, e.g. 

   cd <package-name>/<version>
   cvs import -m 'First import of <package-name>' BossCvs/<package-name> \
      Bes <version>
Try the global -n option with cvs to see what a command would do but not actually do it, e.g. 
   cvs -n import .....

Note: set CVSROOT right

export CVSROOT=¡°:pserver:username@koala.ihep.ac.cn:/bes/bes¡±

cvs login

How to check out a package from CVS

 Doing this when you want to modify a package: this could be for your own private use or because you are the developer of that package. Unless you are the developer of a package, it is recommended that you check out a tagged version of the package. A tag is a mark the developer gives to a coherent set of revisions of all the files in the package, for the convenience of people who want to use it. The command cmt cvstags shows the tags available for a package. You can also find them by broswing the cvs repository or by asking the author of the package. For example: 
  cmt cvstags BesRelease
How to choose a tag? You could check the package's ChangeLog with cvsweb. If in doubt, you can also ask the author, who is identified in the cmt/requirements file of each package, which is again browsable with cvsweb. Often the latest tag is the best one to take.

Once you have decided which tag to use, checkout is straightforward. Go to your working area and do this: 

   cmt co  -r <tag> <package>
e.g. 
   cmt co -r BesRelease-00-00-05 BesRelease
Note the use of cmt, not cvs!

If you are the developer of a package, you will need to check out the HEAD version rather than an old tagged version. If you do cmt co without using the `-r' option to specify tag, you will get the HEAD revisions, which cmt places in a directory named after the latest tag, e.g. 

cmt co BesRelease
This will check out the code into BesRelease/BesRelease-00-00-05, if BesRelease-00-00-05 is the most recent tag.

If you are a developer, you will most likely want to commit your changes (check them back in) - see the next section. Please do commit and tag your changes when you want anyone else to use them.

How to check out several packages

For example:

Checking out a complete container

cmt co Database

cmt co ¨Crequirements Database/*/cmt/requirements

Checking out all packages in boss

cmt co BesRelease

cmt co ¨Crequirements BesRelease/*/cmt/requirements

How to commit changes to a package

 Decide whether you are making changes to fix bugs or improve functionality. Try not to mix these two roles in a single version increment. Make sure you have the agreement of the coordinator for the changes you plan to make. First, make sure your changes compile. Go to the package's cmt directory: 
   cd <package-name>/<version>/cmt
Check for conflicting updates and repeat above if necessary. 
   cvs -n update
This shows files which are not known to CVS (?), files which you have modified (M) files which have been modified in the repository which you should therefore update (U) and files for which there is a possible conflict since you have modified them and they are also changed in the repository. Check this is as you expect and deal with any conflicts and updates. Then rpeat the steps above to test your code if necessary.

Before commiting, Update the ChangeLog file: write a short summary of the changes you made which files you made them too, and why. Look at other entries to get an idea of what is expected. NB ChangeLogs will be concatenated to make release notes.

To commit your changes, go to the package directory and type 

   cvs commit -m 'message'
Where 'message' should summarise the changes you made in a few words.

How to tag a package

If you feel that your changes are complete and you want other people to be able to use them, you need to tag the package.

The commond to tag a package

cvs tag <new-version>

Work out the new package version number. The format of the version number is <package>-xx-xx-xx e.g. BesRelease-00-00-01. 

¡¡

Then move the package version in the directory name: 
   cd ..
   mv <old-version> <new-version>
After this you will have to do cmt config in this package (or broadcast from your BesRelease) 
so other packages will know it has moved.

How to build a release

you can see <How to get started with boss>

Some useful variables and commands

1.The CVSROOT environment variable

   Now CVSROOT's value is ":pserver:username@koala.ihep.ac.cn:/bes/bes"

2.The CMTCONFIG environment variable

3.The CMTPATH environment variable

   CMTPATH is locations that CMT looks in to locate packages.

4.The CMT command itself

   cmt [arguments]

5.Main commands

    cmt config

    cmt create ¡­

   cmt show ¡­

   cmt broadcast ¡­

   cmt co ¡­

   cmt help

    source cleanup.sh

    source setup.sh

Some useful standard patterns
A simple installed library

   apply_pattern installed_library library=

A component library

   apply_pattern component_library library=

A dual_use library

   apply_pattern    dual_use_library files=<list of files>

How to use the three patterns

    1.Packages that create utility classes that are designed to be used directly or as base classes should use the installed_library pattern.

    2.Packages that create a Service should use the component_library pattern. 
       In general a single package should not create multiple services.

    3.Packages that create Algorithms or AlgTools should use the dual_use_library pattern.

Declare run-time files

   apply_pattern declare_runtime extras=*.data

       Note:Declares *.txt *.py and *.data files in share directory

Install run-time files

   apply_pattern install_runtime

Useful documents and links