CMT: An Introduction

Tip: In conjunction with the Concurrent Versioning System (CVS), the Configuration Management Tool (CMT) is used to manage the build of a software release. It is CMT that knows how to do a recursive checkout.

Note: MRvcmt is a frontend GUI designed to facilitate such checkouts. Though MRvcmt is the recommended method, developers using a Linux machine may also use glastpack to do recursive checkouts.

Configuration Management Tool (CMT)

The Configuration Management Tool consists of a number of package-oriented management conventions and several shell-based utilities for configuration management that can be used in conjuction with CVS. In addition, CMT supports the same build environment in both Linux and Windows. GLAST offline software uses CMT's definition of packages, package directory structure, requirements file, and CVS Tagging Conventions.

Using the requirements file, CMT is capable of generating:

gmake-style makefiles (Linux)
Microsoft Developer Studio project and workspace files (Windows)

Package Directory Structure

CMT is designed to work with packages organized in a particular structure.

Package Directory. Each package is contained in a directory named after the package itself.

Package Subdirectory. The package directory contains a single subdirectory which is created "on the fly" and named after the tag of the package being checked out; this subdirectory is then referred to as the package root directory. Thus, if you are checking out TkrRecon/v4r3 on SLAC Public using MRvcmt, you would enter the package name (TkrRecon), select the package tag (v4r3), and set up a path to the CMT executable for the release version (BeamtestRelease, GlastRelease, EngineeringModel, or ScienceTools). In your user work area, a TkrRecon directory and a v4r3 subdirectory (i.e., the root directory) would be created on the fly; the package would be configured and built, and all code and administrative files, as well as the target directories for the built components, placed into directories sitting underneath this package root directory.

GLAST Offline defines several standard directories which exist underneath the package root. This consistency aids both automated procedures accessing the package and the end-users. The only directory required to exist in this scheme is the cmt directory. The following is a list of the directories in this convention.

cmt

The cmt directory contains all of the administrative files used to configure and define the package in the scope of the configuration management system. The most important file is the requirements file, which provides the configuration specification to CMT for the package. For most packages, the only other file in this directory is a file whose name must be .cvsignore; this file is also stored in CVS.

The src directory contains all of the source, or implementation, files for the package. For example, C++ files are those ending with the ‘.cxx’ or ‘.cpp’ extension. The src directory should also contain a file called mainpage.h describing the purpose and use of the package. This file is used in Doxygen documentation generation.

In addition, the src directory may also contain private declarations (i.e., C++ header files) which are not intended to be exported to other packages. This directory is generally private to the package, in that dependent packages are not expected to ‘see’ the content of the src directory. Files may be arranged in any manner; for example, underneath subdirectories. However, this may affect the way the requirements file expresses build information.

<package name>

This directory contains exported declarations for the package, primarily header files in the context of C/C++. Putting the publicly available declarations underneath a directory with the package name makes for a consistent pattern of includes declarations in the dependent packages.

For example, if package A has a header file called A.h and package B depends on A, then to access that header file code in package B (in the context of C++) would use: #include “A/A.h”. This works regardless of where the package root directories for A and B reside in the overall file system.

doc

The doc directory contains documentation associated with the package, and is where Doxygen generated documentation will be stored. This directory also has a file called release.notes. Each time you tag a package, you should add a line to this file describing the changes in the new code. If you use the MRvcmt tag function to do your tagging, you will be presented with the release.notes file in an edit window in which to make your addition.

CMT Requirements File

Each package has a CMT requirements file containing the information required to build its components (typically libraries and applications) and to use them at run time (e.g., where its shared library is located).

Dependencies. Other packages on which a package depends are specified by use statements. Each package's requirements file has access to public information in the requirements files of the other packages, enabling it to know which compiler options to use and which libraries to link against.

Parameters. Parameters of build and test tools as well as deployment tools are also located in the requirements file.

Example: Requirements File for a Gleam Package

package Gleam

version  v5r13p1

# $Id: cmtIntroduction.htm,v 1.1.1.1 2007/06/29 15:03:47 chuckp Exp $

use GuiSvc      v*

use Event       v*
use GlastSvc    v*

# simulation

use FluxSvc     v*
use CRflux      v*

use G4Generator v*
use G4Propagator v*

#digitization
use CalDigi     v*
use TkrDigi     v*
use AcdDigi     v*


#reconstruction
use Trigger     v*
use DetDisplay  v*
use TkrRecon    v*
use CalRecon    v* 

use AcdRecon    v*       

#level 1 filter
use EbfWriter   v*
use OnboardFilter v*

#ROOT persistence: RootIo specifies the data packages
use RootIo      v*
use RootDisplay v*

#diagnostic and summary of bottom line
use merit       v*
use AnalysisNtuple v*

# Allow FRED option -- see fredOptions.txt
use  Fred * IExternal
use  HepRepSvc *
use  HepRepXml *
use  HepRepCorba *

### define a simple executable wth GUI

set JOBOPTIONS "${GLEAMROOT}/src/jobOptions.txt"

macro jobOpts "" WIN32 "*.txt *.h"  
application Gleam $(GlastMain) $(Win32Resource) $(jobOpts) 

macro Gleamlinkopts  "  $(GuiSvc_lib) $(guiapp_linkopts) $(gui_linkopts) -u GuiSvc_loadRef  -ldl "\
      WIN32 " ${guiapp_linkopts} $(GuiSvc_lib)  /include:_GuiSvc_loadRef "


# define a standard test executable, if desired
apply_pattern package_test

Configuring Your CMTPATH

A CMTPATH file is a text file that contains a list of directories where packages are/will be stored. As shown in the following examples, directories are separated by a single colon:

Example #1: Linux. CMTPATH=/nfs/farm/g/glast/u06/mydirectory:/nfs/farm/g/glast/u06/someotherdirectory

Example #2: Windows. CMTPATH=C:\glast\packages:C:\glast\otherdirectory

Caution! By convention, when CMT searches for a package, it uses the first occurrence in its CMTPATH; take care to assign the order properly.

Note: Inside your working directory you will find a file named "CMTPATH". This file has the syntax of the CMT .cmtrc file, and is managed via "add" and "remove" commands. Paths do NOT inherit; for example, if area A needs area B in its CMTPATH, and B requires C, A must explicitly add B and C.