UCM Introduction

Author: Peter Kasper

Contents:
Concepts: The basic components of code management.
Documentation Conventions: Conventions and definitions.
See the Table of Contents for more information.

As the HEP community moves rapidly away from VAX's in favor of various UNIX platforms, it has become desirable to find a UNIX based code management system to replace existing systems which depend on CMS. This document describes a set of tools from which replacement systems can be built.

The package is available from the Fermilab Computing Division through their product distribution system, UPD. The product name is ucm. It assumes the following RCS commands are available on the system :- co, ci, rlog, and rcs. It is currently installed on fnalu and can be accessed by typing "setup ucm".

UCM version v5_1

Concepts

A simple code management system can be loosely divided into the following components:-

Source Management (UVM)

The source consists of any files from which the program executables, parameter files, and documentation files will be built. The source files will change as the software package is developed. Source management involves the creation of a source repository and an access interface which tracks changes to the source and provides information about those changes. On VAX/VMS systems this task was performed by CMS. The component of UCM which replaces CMS is called UVM which is a layer over RCS.

UVM organizes source files into "elements" within UVM "libraries". Each element contains one or more "revisions" representing the changes made to the element. Each revision is assigned a revision number which can be "tagged" with a symbolic revision name. A single revision can contain several tags but a single tag can only be applied to one revision per element. Revision tags are equivalent to "classes" in CMS and are generally used to identify different release versions of the software package. The elements within a library can be organized into UVM "groups". This is like placing files into subdirectories but is more flexible in that a single element can be placed in more than one group.

Dependency and Flavor Management (KPP)

Problems can occur if, for instance, the same code is intended to run on different machine platforms or operating systems. This will often require slightly different versions of the code. Rather than maintaining two separate versions of the source it is more convenient to able to flag the platform dependent parts of the code and run it through a precompiler which will use the flags to produce a compiler-ready output appropriate to a specified platform. The C PreProcessor is designed to do this for C source code, however, not all compilers have preprocessors and one can also imagine situations where the same sort of functionality may be useful in other source types (e.g. documentation or parameter files).

The KPP part of UCM is a generic text preprocessor which provides the more basic functions of CPP (such as conditional text and file inclusion) but because it is language insensitive, it can be safely used in a much broader context.

Update Management (UVMBLD)

Update management in UNIX is elegantly solved using one the various "make" utilities. However, maintaining the "Makefiles" used to drive the updates can be a problem for large software projects. UVMBLD is a component of UCM designed to simplify this process. It has a built-in knowledge of UVM and KPP protocols which enable it create Makefiles containing all the appropriate include-file dependencies and revision specifications.

Distribution Systems (UVMHTML)

Software distribution is not addressed by UCM as there are a number of appropriate systems available in the UNIX world. However, the UVMHTML component of UCM can be loosely categorized under this heading. In that it provides a way of monitoring the contents of UVM libraries with a WWW browser. The web-pages created by UVMHTML enable a web user to not only view the contents of a UVM library but also to access much the library developement information provided by UVM.

UCM version v5_1

Documentation Conventions

The following conventions and definitions will be assumed in the command specifications throughout this document:-

bold text: User supplied variables (case sensitive).
[ ... ]: Optional parameters
Va*lue: Case insensitive argument which can be abbreviated to the set of values to the left of the asterisk.
UVM library: A UVM library is a UNIX directory which contains a sub-directory /UVM. The UVM sub-directory contains, at minimum, a transaction log for the library called UVM/HISTORY.
UVM element: A UVM element is an RCS version file located in the UVM library's top level directory. A UVM element is specified by a library name and a file name. For example, the element library/file would consist of a file library/file,v. Note that the characters ",v" are appended to the RCS file names but not to the working versions extracted from the library.
UVM group: A group of UVM elements which can be referenced by the group name. The list of elements comprising a group is maintained in the file UVM/group.GRP.
Revision number: Element revisions are numbered according to the RCS conventions.