2.2 Configuration Records

A configuration record (CR) is the bill of materials for a derived object or set of DOs. The CR documents aspects of the build environment, the assembly procedure for a DO, and all the files involved in the creation of the DO.

Configuration Record Example

The catcr command displays the configuration record of a specified DO. Figure 3 shows a CR, with annotations to indicate the various kinds of information in the listing.

Figure 3 Kinds of Information in a Configuration Record

Some notes on Figure 3:

• Directory versions. By default, catcr does not list versions of the VOB directories involved in a build. To list this information, use the -long option:

cleartool catcr -long util.obj
directory version \vob_hw\.@@\main\1 <25-Feb-99.16:59:31>
directory version \vob_hw\src@@\main\3 <26-Feb-99.20:53:07>
...

• Declared dependencies. One principal feature of ClearCase is the automatic detection of source dependencies on MVFS files: versions of elements and objects in view-private storage.

• Listing of checked-out versions. Checked-out versions of file elements are highlighted. Checked-out versions of directory elements are listed like this:

directory version \vob_hw\src@@\main\CHECKEDOUT <26-Feb-96.17:05:23>

When the elements are subsequently checked in, a listing of the same configuration record shows the updated information. For example,

\vob_hw\src\util.c <25-Feb-99.17:02:27>

becomes

\vob_hw\src\util.c@@\main\4 <25-Feb-99.17:02:27>

The actual configuration record contains a ClearCase internal identifier for each MVFS object. After the version is checked in, catcr lists that object differently.

NOTE: The time stamps in the configuration record are for informational purposes and are not used by ClearCase during rebuild or winkin decisions. ClearCase uses OIDs to track versions used in builds.

Contents of a Configuration Record

The following sections describe the contents of configuration records.

Header Section

As displayed by catcr, the header section of a CR includes the following lines:

• Makefile target associated with the build script and the user who started the build:

Target util.obj built by akp.dvt

For a CR produced by clearaudit, the target is ClearAudit_Shell.

• Host on which the build script was executed:

Host 'mars' running Windows NT 4.0

• Reference time of the build (the time clearmake, omake, or clearaudit began execution), and the time when the build script for this particular CR began execution:

Reference Time 15-Sep-99.08:18:56, this audit started 15-Sep-99.08:19:00

In a hierarchical build, involving execution of multiple build scripts, all the resulting CRs share the same reference time. (For more on reference time, see the clearmake reference page.)

• View storage directory of the view in which the build took place:

View was \\mars\views\930825.vws

• Working directory at the time build script execution or clearaudit execution began:

Initial working directory was s:\proj\hw\src

MVFS Objects Section

An MVFS object is a file or directory in a VOB. The MVFS Objects section of a CR includes this information:

• Each MVFS file or directory read during the build. These include versions of elements and view-private files used as build input, checked-out versions of file elements, DOs read, and any tools or scripts used during the build that are under version control.

• Each derived object produced by the target rebuild.

Non-MVFS Objects Section

A non-MVFS object is an object not accessed through a VOB (compiler, system-supplied header file, temporary file, and so on). The Non-MVFS Objects section of a CR includes each non-MVFS file that appears as an explicit dependency in the makefile or is a dependency inferred from a suffix rule. See Declaring Source Dependencies in Makefiles.

This section is omitted if there are no such files or if the CR was produced by clearaudit.

Variables and Options Section

The Variables and Options section of a CR lists the values of make macros referenced by the build script and command-line options.

This section is omitted from a CR produced by clearaudit.

Build Script Section

The Build Script section of a CR lists the script that was read from a makefile and executed by clearmake or omake.

This section is omitted from a CR produced by clearaudit.

Configuration Record Hierarchies

A typical makefile has a hierarchical structure. Thus, running clearmake or omake once to build a high-level target can cause multiple build scripts to be executed and multiple CRs to be created. Such a set of CRs can form a configuration record hierarchy, which reflects the structure of the makefile (Figure 4).

Figure 4 Configuration Record Hierarchy

An individual parent/child link in a CR hierarchy is established in one of two ways:

• In a target/dependencies line

For example, the following target/dependencies line declares derived objects hello.obj, msg.obj, and libhello.lib to be build dependencies of derived object hello.exe:

hello.exe: hello.obj msg.obj libhello.lib
...

Accordingly, the CR for hello.exe is the parent of the CRs for the .obj files and the .lib file.

• In a build script

For example, in the following build script, derived object libhello.lib in another directory is referenced in the build script for derived object hello.exe:

hello.exe: $(OBJS)
cd ..\lib & $(MAKE) libhello.lib
link /out: hello.exe $(OBJS) ..\lib\libhello.lib

Accordingly, the CR for hello.exe is the parent of the CR for libhello.lib.

NOTE: The recursive invocation of clearmake in the first line of this build script produces a separate CR hierarchy, which is not necessarily linked to the CR for hello.exe. The second line of the build script links the CR for ..\lib\libhello.lib with that of hello.exe by causing link to read ..\lib\libhello.lib and making it a detected dependency.

The catcr and diffcr commands have options for handling CR hierarchies:

• By default, they process individual CRs.

• With the -recurse option, they process the entire CR hierarchy of each derived object specified, keeping the individual CRs separate.

• With the -flat option, they combine (or flatten) the CR hierarchy of each specified derived object.

Some ClearCase features process entire CR hierarchies automatically. For example, when the mklabel command attaches version labels to all versions used to build a particular derived object (mklabel -config), it uses the entire CR hierarchy of the specified DO. Similarly, ClearCase maintenance procedures do not scrub the CR associated with a deleted DO if it is a member of the CR hierarchy of a higher-level DO.

Configuration Record Cache

When a derived object is created in a view, both its data container and its associated configuration record are stored in the view's private storage area. The CR is stored in the view database, in compressed format. To speed configuration lookup during subsequent builds in this view, a compressed copy of the CR is also cached in a view-private file, .cmake.state, located in the directory that was current when the build started.

When a DO is winked in for the first time, the associated CR moves from the view's private storage area to the VOB database, as shown in Figure 5.