ClearCase's automatic build auditing facility tracks only the MVFS objects actually used in the building of a target. Sometimes, however, you may wish to track other objects:

You can force such objects to be recorded in a build's CR as shown in Figure 12-1 by declaring them as dependencies of the makefile target:

Figure 12-1. Explicitly-Declared Source Dependencies

We suggest that you use view-private files as flag files, rather than using non-MVFS files (such as /tmp/flag). In a distributed build, a view-private flag file is guaranteed to be the same object on all hosts; there is no such guarantee for a non-MVFS file.

As an alternative to declaring your C compiler as a build dependency, you might place it (and other tools) in a “tools VOB”. The versions of such tools will automatically be recorded, eliminating the need for explicit dependency declarations. Additional issues in the auditing of build tools are discussed in the next section.

There are situations in which clearmake's configuration lookup algorithm qualifies a derived object, even though an actual target rebuild would produce a different result. Configuration lookup requires that for each object listed in an existing CR, the current view must select the same version of that object. It does not take into account the possibility that a target rebuild might use a different object altogether.

For files that are accessed by explicit pathnames, this situation cannot occur. But it can occur if a file is accessed at build time by a search through multiple directories. For example, the following build script uses a search to locate a library file, libprojutil.a:

hello:
      cc -o hello -L /usr/project/lib -L /usr/local/lib \
            main.o util.o -lprojutil

The command clearmake hello might qualify an existing derived object built with /usr/local/lib/libprojutil.a, even though performing a target rebuild would now use /usr/project/lib/libprojutil.a instead.

clearmake addresses this problem in the same way as some standard make implementations:

You must use the VPATH macro to specify the set of directories to be searched:

VPATH = /usr/project/lib:/usr/local/lib

Given this makefile, clearmake will use the VPATH (if any) when it performs configuration lookup on libprojutil.a. If a candidate derived object was built with /usr/local/lib/projutil.a, but would be built with /usr/project/lib/projutil.a in the current view, the candidate is rejected.

---

Note: The VPATH macro is not used for all source dependencies listed in the config rec. It is used only for explicitly-declared dependencies of the target.

---

Build Tool Dependencies. You can use this mechanism to implement dependencies on build tools. For example, you might track the version of the C compiler used in a build as follows:

msg.o: msg.c $(CC)
       $(CC) -c msg.c

With this makefile, either your VPATH must include the directories on your search path (if the $(CC) value is simply “cc”), or you must use a full pathname as the $(CC) value.

A build session can have any number of subsessions, all of which inherit the reference time of the build session. A subsession corresponds to a “nested build” or “recursive make”, started when a clearmake process is invoked in the process family of a higher-level clearmake. Examples of clearmake invocations that start subsessions include:

A subsession begins while a higher-level session is still conducting build audits. The subsession conducts its own build audit(s), independent of the audits of the higher-level session — that is, the audits are not nested or related in any way, other than that they share the same build reference time.

Any version created during a build session and selected by a LATEST config spec rule will not be visible in that build session. For example, a build might checkin a derived object it has created; subsequent commands in the same build session will not “see” the checked-in version, unless it is selected by a config spec rule that does not involve the version label LATEST.

Different build sessions have different reference times. The “best” way to have a series of builds share the same reference time is to structure them as a single, hierarchical build.

An alternative approach is to run all the builds within the same clearaudit session. For example, you might write a shell script, multi_make, that includes several invocations of clearmake (along with other commands). Running the script as follows ensures that all the clearmake builds will be subsessions that share the same reference time:

% clearaudit -c multi_make

Undesirable results occur when the same file is written at two or more session levels (for example, a top-level build session and a subsession): the build audit for the higher-level session does not contain complete information about the file system operations that affected the file. For example:

% clearaudit -c "clearmake shuffle > logfile"

The file logfile may be written both:

In this case, clearaudit issues this error message:

Unable to create derived object "logfile"

To work around this limitation, “postprocess” the derived object at the higher level with a copy command:

% clearaudit -c "clearmake shuffle > log.tmp"
% cp log.tmp logfile
% rm log.tmp

CRs created during a build session and its subsessions are not automatically linked into a single configuration record hierarchy. For more information, see “CR Hierarchies”.

A common incremental-update scenario in “traditional” UNIX environments is the building of an archive (programming library) by ar(1).

A traditional make program treats an archive as a compound object; it can examine the time-modified stamps of the individual components (object modules) in the archive; and it can update the archive by replacing one or more individual object modules. Here is a simple makefile in which a special syntax enables multiple targets to incrementally update a single archive, libvg.a:

libvg.a:: libvg.a(base.o)
libvg.a:: libvg.a(in.o)
libvg.a:: libvg.a(out.o)

If you edit one of the library's sources (for example, out.c); a “traditional” make program uses the special syntax and a .c.a built-in rule to update the library as follows:

clearmake does not implement this algorithm, and includes no support for treating an archive as a compound object. ClearCase build-avoidance is based solely on meta-data (CRs), not on any analysis at the file-system-data level. clearmake interprets the above makefile as follows

Thus, clearmake accepts the standard incremental-update syntax, but interprets it in a way that produces a non-incremental build procedure.

Some makefile restructuring can ameliorate the situation described above. Often, a restructured build procedure can take advantage of wink-in to compensate for the loss of incremental updating. For example, you might revise the procedure for building the archive libvg.a (discussed in the preceding section) to dispense with the special ar-informed syntax:

libvega.a: base.o in.o out.o
       ar rv libvega.a base.o in.o out.o
base.o:
       cc -c base.c
in.o:
       cc -c in.c
out.o:
       cc -c out.c

Object modules built by this makefile are standard, sharable derived objects; typically, as they libraries sources stabilize over time, most builds of target libvega.a will reuse or wink-in most of the object modules.

Avoid the following restructuring; it will cause a complete rebuild of the archive each time any object module is updated:

base.o: base.c 
       cc -c base.c
       ar rv libvg.a base.o
  .
  . and so on

You may encounter incremental updating in other situations, as well. For example, C++ compilers that support parameterized types (templates) often update type map files incrementally as different targets are built. ClearCase includes special makefile rules that store per-target type map files.

Ada compilers often update certain common files in Ada libraries incrementally, as different compilation units are built. There are no current clearmake workarounds to implement per-target CRs for Ada libraries. To produce a CR for an Ada library, you can perform a complete rebuild of the library from its sources in a single clearaudit session.