config_record

Bill of materials for clearmake or omake build or clearaudit shell

APPLICABILITY

ClearCase (data structure)

DESCRIPTION

A configuration record (CR) is a metadata item that contains information gathered in a ClearCase build audit. Build audits are performed by clearmake or omake in conjunction with the MVFS during execution of a target rebuild, which typically involves execution of a single build script. For a double-colon target, the rebuild may involve execution of multiple build scripts.

clearaudit enables build auditing during execution of an arbitrary program (typically a shell).

One CR is written each time a target rebuild creates one or more derived objects. A configuration record is logically associated with, and can be accessed through, all the derived objects created during the build audit. The CR is the bill of materials for the derived object.

A CR is created only when you invoke clearmake or omake from a dynamic view.

MVFS OBJECTS AND NON-MVFS OBJECTS

In a configuration record, two kinds of file-system objects are distinguished.

• An MVFS object is a file or directory in a VOB.
• A non-MVFS object is an object not accessed through a VOB (compiler, system-supplied header file, temporary file, and so on).

CONTENTS OF A CONFIGURATION RECORD

A configuration record provides a build's bill of materials and documents its assembly procedure. A CR can include several sections. If the CR is created by clearaudit, it does not include sections related to build scripts.

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

The MVFS Objects section of a CR includes this information:

• Each MVFS file or directory read during the build. This includes versions of elements and view-private files used as build input, and checked-out versions of file elements.
• Each derived object produced by the target rebuild.

Non-MVFS Objects Section

The Non-MVFS Objects section of a CR includes each non-MVFS file that appears as an explicit dependency in the makefile.

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.

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, a single invocation of clearmake or omake to build a high-level target can cause multiple build scripts to be executed and, accordingly, multiple CRs to be created. Such a set of CRs can form a configuration record hierarchy, which reflects the structure of the makefile.

For example, consider this hierarchical makefile:

hello.exe: hello.obj msg.obj libhello.lib (top-level target)
link /out:hello.exe hello.obj msg.obj libhello.lib
date > $(TEMP)\flag.hello

hello.obj: (second-level target)
cl /c hello.c

msg.obj: (second-level target)
cl /c msg.c

libhello.lib: user.obj env.obj (second-level target)
lib /out:libhello.lib user.obj env.obj

user.obj: (third-level target)
cl /c user.c

env.obj: (third-level target)
cl /c env.c

A complete build of target hello.exe produces the CR hierarchy shown in Figure 9.

Figure 9 CR Hierarchy Created by Complete Build: 'clearmake hello.exe'

An individual parent-child link in a hierarchy is established in either of these 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. It is the second line of the build script that 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.

PHYSICAL STORAGE OF CONFIGURATION RECORDS

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 the DO is winked in to another view (or the VOB, for a nonshareable DO), or is checked in as a DO version:

• promote_server copies the data container to a VOB storage pool.
• The CR moves from the view's private storage area to the VOB database.

The process of winking in an entire set of sibling DOs may involve making copies of the CR in multiple VOB databases.

SEE ALSO

catcr, clearaudit, clearmake, diffcr, lsdo, view_scrubber

Building Software with ClearCase