CMT: Advanced

The Configuration Management Tool (CMT) 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.

Using CMT's requirements file, CMT supports the same build environment in both Linux and Windows and is capable of generating:

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

GLAST offline software also uses CMT's definition of:

  • Packages
  • Package directory structure
  • requirements file
  • Tagging Conventions

Packages

CMT packages represent a set of software components (e.g., applications, libraries, tools, etc.). These package components are either independent, or they are related to each other. Conventions for naming as well as for addressing packages, files, and directories are provided by the CMT environment. The MRvcmt and glastpack tools are also provided for automating the implementation of these conventions.

Configuration requirements are described in the requirements file, enabling CMT to determine the effective set of configuration parameters needed to build or use the packages (e.g., source files on which a library depends, kind of library to be built, etc.).

Tagging Conventions

The CMT tag format allows for three numbers (major release number, minor release number, and patch number), and for some string to indicate the scope of the tag. These tag names follow the format where the three numbers are prefaced by v, r, and p (for version, revision and patch), e.g. v1r5p1. The initial version of a package is vXrY. For example: v1r0, or v0r0.

Note: Do not use a patch number of 0 (p0); patch numbers must be 1 or higher to avoid a possible problem with how CMT handles such numbers.

Also see:

Package Directory Structure

CMT is designed to work with packages organized in a tree structure. Each package tree contains one required subdirectory (named cmt), and other directories containing code, header files, parameter files, scripts, data, etc.

The tree for each package is organized as follows:

  • Package Directory. At the top of the tree is the package directory, named after the package itself (e.g., TkrRecon).
  • Package Subdirectory. The package directory contains a single subdirectory which does not exist in the CVS repository. It is created "on the fly" and named after the package tag when code is checked out from CVS using CMT. This package subdirectory is then referred to as the package root directory (e.g., v10r10p2).

All code and administrative files, as well as the target directories for the built components, fall into directories sitting underneath the package root directory.

Thus, if you are checking out TkrRecon/v10r10p2 using MRvcmt, you would: enter the package name (TkrRecon); select the package tag (v10r10p2); and set up a path to the CMT executable for the release version (BeamtestRelease, GlastRelease, EngineeringModel, or ScienceTools).

In your work area, a TkrRecon directory and a v10r10p2 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.

Standard Root Sub-directories (as defined by Glast Offline Software)

To aid automated procedures accessing the package (as well as end-users), several standard directories are defined as existing underneath the package root, including:

Directory
Contents
  • cmt (required)

The only directory required to exist in this scheme is the cmt directory which contains all of the administrative files used to configure and define the package in the scope of the configuration management system.

requirements -- The most important of these files is requirements; this file provides the configuration specification to CMT for the package. (Also see Recursive Checkouts.)

.cvssignore -- For most packages, the only other file in the cmt directory is a file whose name must be .cvsignore which contains a list of files (whose names may include * used as a wildcard). CVS will ignore these files during commands such as cvs import and cvs update.

  • src

Contains all of the source, or implementation, files for the package.

For example, C++ files are those ending with the ‘.cxx’ or ‘.cpp’ extension.

src -- The src directory also contains a file called mainpage.h describing the purpose and use of the package (used in Doxygen documentation generation).

This directory may also contain private declarations (i.e., C++ header files) which are not intended to be exported to other packages; src 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.

Note: This arrangement may affect the way the requirements file expresses build information.
  • <package name>

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 (in the context of C++) to access that header file code in package 'B' 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

Contains documentation associated with the package, and is where Doxygen generated documentation will be stored.

release.notes -- The doc folder should contain a file called release.notes and, each time the package is tagged, a line should be added to this file, as in this example.

Note: If MRvcmt is used for tagging, it will present the release.notes file for editing.

Tip: If, as in the example, you include a line with "EOH" at the bottom of all header lines, MRvcmt will fill in the first three fields (version, date, user) for you.

Other subdirectories sometimes found in the package root directory include:

  • xml
  • pfiles
  • python
  • macro
  • rootMacros
  • jobOptions
    • 06/29/2007>

Tip: Look at well-maintained packages in ViewCVS to determine current practice.

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 a 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 CalRecon package:

package AcdRecon
version v3r1p3

author Heather Kelly <heather@milkyway.gsfc.nasa.gov>

branches src doc

use GlastPolicy v*
use GlastSvc v9r*
use TkrUtil v*
use Event v*
use GuiSvc v3*
use AcdUtil v*

# no use of default_include_path (no public headers)

apply_pattern package_headers

library AcdRecon *.cxx -s=Dll *.cxx ${AcdRecon_headers}

apply_pattern component_library library=AcdRecon

#=============================================================
private
use RootIo v*

public
apply_pattern declare_joboptions files="-s=../src/test *.txt"
apply_pattern package_test

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

Naming Packages

Package Names:

  • Non-Gaudi. Names should start with a lower-case letter.
  • Gaudi. If the package will be using Gaudi, it should start with a capital letter.
  • GlastRelease packages. GlastRelease packages generally use camel case naming, as in camelCase.
  • ScienceTools packages. ScienceTools package names separate words with underscores, as in not_camel_case.
  • Interface packages. Interface packages for external libraries don't necessarily follow these conventions; many have names which are all caps.

Configuring Your CMTPATH

A CMTPATH file is a text file that contains a list of directories where packages are -- or will -- be stored.

Tip: Setting up the CMTPATH to point first to your work directory, and then to the parent release directory in the build area will enable you to make efficient use of your local work space and the shared release directories.

Typically, end-users and developers working on SLAC Public set up a work environment so that only the packages to be modified and/or tested locally are checked out to their local directories. All other release packages that may need to be accessed during testing (such as those defined in the requirements file) are located in the build area (currently on glast u09) where the Release Manager has checked out the code from CVS and built it; these packages are accessed as needed by proper setup of the CMTPATH.

For example, a typical work environment for an end-user or developer working on GlastRelease and using SLAC Public is shown below:

  • Gleam is checked out and placed in WorkArea-1.
  • Checkout packages to be modified and/or tested are placed in WorkArea-2.

Notes:

  • Inside your work directory you will find a file named CMTPATH which has the syntax of the CMT .cmtrc file, and is managed via "add" and "remove" commands.
  • This file contains a list of directories where packages are -- or will -- be stored, and is used to:
    • Resolve dependencies during a build.
    • Resolve references during execution.

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

  • If you have checked out a copy of a package which is used by another package; the latter package must also be rebuilt. This situation often occurs, particularly when working with lower level packages such as Event.

For example, if modifying any of the RootData packages (e.g., digiRootData), RootIo must also be checked out and rebuilt since RootIo uses digiRootData. Simply having -- and building -- digiRootData in your local area, then running Gleam, would not pick up the changes in digiRootData.

  • As shown below, the CMTPATH is set to point first to the directories and subdirectories in WorkArea-2, then to the parent GlastRelease directories in the build area:

    CMTPATH ${LOCAL_WORK_AREA} : ${GR_RELEASE}

  where LOCAL_WORK_AREA is equal to:
    /nfs/farm/g/glast/u33/yourWorkDirectory/Releases/GR-v9r3
  and GR_RELEASE is equal to:
    /nfs/farm/g/glast/u30/builds/rh9_gcc32opt/GlastRelease/GlastRelease-v9r3
  • Paths do not inherit:

    If area A needs area B in its CMTPATH, and B requires C,
    A must explicitly add B and C.

Recursive Checkouts

A recursive checkout cycles through all dependent packages as specified by the cmt requirements file.

Note: Recursive can also be used to mean cycling through all dependent packages as implied by #include directives or other, external means.

Tip: MRvcmt is a frontend GUI designed to facilitate such checkouts. Though MRvcmt is the recommended method for both developers and end-users, developers using a Linux machine may also use glastpack to do recursive checkouts.

Related Topics

Other Useful Links:

 

Last updated by: Chuck Patterson 06/29/2007

 

 

06/29/2007