In this lesson, you'll take a closer look at an important ClearCase feature: sharing of the derived objects produced in builds.
At the end of the preceding lesson, you were in the src directory, in a shell set to view USER_HOST_tut. Verify that you are still in the same situation.
% cleartool pwv -short USER_HOST_tut % pwd VOBTAG/src |
If you've gotten lost, you may need to use a full pathname to find the source directory.
cd VOBTAG/src |
If this command fails, it is probably because you exited the shell that was set to your view. Enter the following commands to reestablish your view context and your working directory within the VOB.
cleartool setview USER_HOST_tut cd VOBTAG/src |
A file produced by a build script under control of the clearmake build utility is called a derived object (or DO). The target hello you specified in Step 23 is a derived object; so are its sub-targets, hello.o and util.o. (And so are compiler listing files and other such files that are not even specified anywhere in the makefile.)
The cleartool ls command provides a simple derived object listing:
% cleartool ls -l hello hello.o util.o derived object hello@@DATESTRING.nnn (derive object ID) derived object hello.o@@DATESTRING.nnn (derive object ID) derived object util.o@@DATESTRING.nnn (derive object ID) |
The -l (“long”) option expands the listing to include the words derived object, but the distinctive DO name format makes derived objects easily recognizable without this annotation. Each DO is assigned a unique derived object ID, which incorporates its file name and a date-time stamp. These IDs enable users, and ClearCase, to distinguish the instances of the same files built in different views.
The three DOs look (and behave) the same, but as you will see shortly, hello.o is actually shared by multiple views. When first created in some ClearCase view, a DO is unshared, and it is stored “locally” in the view. Subsequent executions of clearmake in other views can cause the derived object to become shared among views. Here is what happened to hello.o to make it a “shared derived object”:
The REL1REL2 script used clearmake to build hello.o in view USER_HOST_old.
In Step 23, you performed a build in view USER_HOST_tut. During this build, clearmake determined that rebuilding hello.o in this view would produce an exact copy of an existing instance in another view. Accordingly, it saved time and storage space by performing a wink-in of the existing file. That is, it made the same derived object, hello.o, appear in both views, USER_HOST_old and USER_HOST_tut.
clearmake used “circumstantial evidence” to decide that rebuilding hello.o was unnecessary:
All the source versions that were used to build hello.o in the USER_HOST_old view are the same as the source versions selected by the USER_HOST_tut view.
The build script that was used to build hello.o in the USER_HOST_old view matches the script that would be used now in the USER_HOST_tut view.
This evidence is provided by ClearCase's build auditing capability. During execution of a build script, ClearCase virtual file system code in the UNIX kernel monitors every open(2) and read(2) system call. This file-system-level audit guarantees an accurate accounting of which files—and which versions of those files—are used as build input. clearmake summarizes the audit as a configuration record (config rec), and stores it in the VOB.
The catcr (“display config rec”) command lists the contents of a config rec. Note that this command accepts the name of any DO produced during the build. (The config rec shared by a build's DOs does not, itself, have a user-visible name.)
% cleartool catcr -flat hello ---------------------------- MVFS objects: ---------------------------- 1 VOBTAG/src/hello@@DATESTRING.nnn 1 VOBTAG/src/hello.c@@/main/3 <DATESTRING> 2 VOBTAG/src/hello.h@@/main/1 <DATESTRING> 2 VOBTAG/src/hello.o@@DATESTRING.nnn 1 VOBTAG/src/util.c@@/main/2 <DATESTRING> 2 VOBTAG/src/util.o@@DATESTRING.nnn |
The config rec includes the following:
pertinent build environment data: hardware architecture, hostname, username, working directory timestamp, view
the name and version number of each source file used in the build
the name and unique identifier of each derived object incorporated from a build of a sub-target
a copy of the build script
Notice that only the second and third items in this list appeared in the output above; use catcr -long to see the remaining information.
Why the –flat option? The build of hello is typical in that one or more levels of sub-targets must be constructed before the actual target named in the clearmake command is built. Config recs reflect this hierarchical nature of makefile-based software builds: a separate config rec is produced for each build script.
By default, the command catcr hello lists the config rec for the top-level build only. Using the –flat option causes clearmake to combine three config recs into a single report:
the config rec for the top-level build
(build script: cc -o hello hello.o util.o)
the config rec for the build of sub-target hello.o
(build script cc -c hello.c)
the config rec for the build of sub-target util.o
(build script cc -c util.c)
Since this is the first time you've examined a config rec, you may be just a little skeptical of the claim that ClearCase build auditing is guaranteed to produce a correct listing. So verify that the source file versions reported in the config rec for hello are, indeed, the versions currently in your view.
% cleartool ls -short *.c |
hello.c@@/main/3 util.c@@/main/2 |
When clearmake built target hello in Step 23, it announced that it was performing a wink-in of an existing hello.o instead of building a new hello.o. The lsdo (“list derived objects”) command verifies that your view is now sharing this file with another view. Displaying the config rec for this file verifies that it was, indeed, built in another view.
% cleartool lsdo -l hello.o DATESTRING (USER.GROUP) create derived object "hello.o@@DATESTRING.nnn" Getreferences: 2 (shared) => HOST:HOME/tut/old.vws (two views now share) => HOST:HOME/tut/tut.vws (this derived object) % cleartool catcr hello.o Target hello.o built on host "HOST" by USER.GROUP Reference Time DATESTRING, this audit started DATESTRING View was HOST:HOME/tut/old.vws Initial working directory was HOST:VOBTAG/src ---------------------------- MVFS objects: ---------------------------- VOBTAG/src/hello.c@@/main/3 <DATESTRING> VOBTAG/src/hello.h@@/main/1 <DATESTRING> VOBTAG/src/hello.o@@DATESTRING ---------------------------- Variables and Options: ---------------------------- MKTUT_CC=cc ---------------------------- Build Script: ---------------------------- cc -c hello.c ---------------------------- |
An element cannot be modified unless you enter a checkout command. (And it cannot be deleted except with the rmelem (“remove element”) command, which is beyond the scope of this tutorial.) Such restrictions would be cumbersome for derived objects—developers like to build, rebuild, clean up, and rebuild again at will. So ClearCase allows derived objects to be deleted or overwritten with standard UNIX commands.
Deleting a shared derived object from your view does not simultaneously remove it from the other views that share it. Rather, deleting the DO merely reduces its reference count. The other views continue to see the DO—your view sees no file with that name. And since the DO still exists, it remains a candidate for wink-in during subsequent rebuilds.
Let's play with the shared derived object hello.o, verifying that it can be deleted from your view and then winked-in again.
% rm hello.o (deleted in your view) |
% ls hello.o
ls: hello: No such file or directory
% cleartool lsdo -l hello.o
DATESTRING (USER.GROUP@HOST)
create derived object "hello.o@@DATESTRING.nnn"
references: 1 (shared) => HOST:HOME/tut/old.vws
(survives in other view)
% clearmake -v hello.o
No candidate in current view for "hello.o"
Wink in derived object "VOBTAG/src/hello" (shared again!)
|
The references: 1 (shared) annotation indicates that the derived object was at one time shared by two or more views, but currently is referenced by only one view.
This concludes our short exploration of derived objects. To prepare for fixing the bug in the second release (the extra <NL> character in the time string), the next lesson conducts another exploration. You'll investigate how to change the way a view selects versions of elements. This capability will allow you to “turn back the clock” to a previous release, then fix the bug in that release.