scm271 Ecc s10

► ► ► Module 10
Managing Builds in ClearCase
IBM Software Group
Essentials of Rational ClearCase

Module 10: Managing Builds in ClearCase
Topics
Objectives.......................................................................................................... 10-2
ClearCase Build Utilities: clearmake and omake ................................................ 10-6
Derived Objects ............................................................................................... 10-10
Build Auditing .................................................................................................. 10-13
Build Avoidance............................................................................................... 10-15
Build Avoidance Among Views: Wink In........................................................... 10-17
Express Builds .................................................................................................. 10-23
Versioning DOs and Configuration Records ...................................................... 10-25
© Copyright IBM Corp. 2003 10 - 1

Course materials may not be reproduced in whole or in part without the prior written permission of IBM.
Objectives
Objectives
Upon completing this module, you should be able to:
Describe the advantages of building software with
clearmake and omake (on Windows)
Explain build auditing
Explain build avoidance
Execute builds using clearmake and omake (on
Windows)
View and compare configuration records
Add derived objects to source control
2
10 - 2 © Copyright IBM Corp. 2003

Module 10 - Managing Builds in ClearCase
Building Software
Building Software
A build is the process that passes human-readable program code through a software
processor to create computer-executable program modules.
An organization’s configuration management policies determine who performs builds
and when in the development process builds are performed. In many cases, a project’s
build manager or integrator performs builds on work delivered to shared work areas.
Often, developers perform builds on their source files before merging them to the
integration area.
Usually, building software is a multi-step process that involves large numbers of files and
complex dependencies. Build management utilities help manage and increase the
efficiency of the build process.
Rational Resources
Building Software with ClearCase
Rational ClearCase OMAKE Guide
ClearCase Reference Manual
Other Resources
Andrew Oram and Steve Talbott, Managing Projects with make, 2nd edition, (O’Reilly &
Associates, 1991)
GNU make documentation

What Is make?
What Is make?
An industry-standard, non-proprietary tool that
controls the generation of executables and other
non-source files from the program's source files
It prevents unnecessary re-building among
interdependent source files
Guarantees consistency of build process
Requires a makefile to specify build instructions and
dependencies via rules in the following format:
<target>: <dependency, …>
<command, …>
UNIX created the original make utility. It was designed to improve the efficiency of
compiling C program files by preventing unnecessary recompilation. The make utility
codifies the relationships between files and specifies which commands need to be
generated to bring files up to date when they are changed.
The make utility gets information on how to build from a makefile. A makefile consists
of rules that specify target, dependencies, and commands. Targets are the written
output of a command. Dependencies are the known input files, passed to the
command and from which the command creates the target. If one or more of these
dependencies changes, the target must be re-built.
make is typically used with programming languages such as C++, Java, or Basic.
However, make can be used to drive any build that creates output file(s) by
transforming input file(s) based on command(s).

A makefile Example
A makefile Example
Dependencies
Target
Command
In this example, hello.o and util.o are the dependency files that are passed to the cc
command. Hello is the target output of the command.

ClearCase Build Utilities: clearmake and omake
ClearCase Build Utilities: clearmake and omake

Both are stand-alone executables, not cleartool
subcommands
Compatible with makefiles constructed for use with

other make variants
The clearmake utility is available on both Windows and UNIX. The omake utility is
only available on Windows.
Both utilities feature compatibility modes that allow you to use makefiles built to use
with other make variants.
Clearaudit provides exactly the same auditing facility as clearmake, but does not have
any of the make functionality. Clearaudit is used to run any command in an audited
shell. It produces an audit trail of all file versions used by the user-defined command
during its execution and associates that audit with all files created by the command.
Clearaudit can only be used with dynamic views.
You can use clearaudit to produce derived objects and configuration records for
software builds performed with another make program, such as UNIX make(1) or
Windows nmake.

clearmake and omake Advantages
clearmake and omake Advantages

Build auditing
Creating a complete configuration record that
documents the build process, its inputs, and its
results
Build-avoidance algorithms
Sharing of binaries (derived objects) among views
Distributing a build across concurrent parallel
processes, on a single host or on multiple hosts
Standard make utilities only check modification times of stated dependencies, and do
not include dependencies not explicitly declared. ClearCase build utilities enhance the
build process by:
• Auditing the build, with automatic detection of source dependencies, including
header file dependencies.
• Creating a complete configuration record that documents the build process and its
results.
• Employing sophisticated build-avoidance algorithms to guarantee correct results
when building in a parallel development environment.
• Sharing of binaries among views, thus saving time and disk storage.
• Executing multiple build scripts concurrently.
You learn more about these features and how they work later in this module.

Building within Views
Building within Views

Builds are executed within the context of a view
View configuration selects versions for the build
Advantages of ClearCase build utilities are only
available if you build in dynamic views
clearmake and omake are intended to be used in dynamic views. You can build in
snapshot views, but the features that distinguish ClearCase build utilities do not work in
snapshot views.

Invoking Build Utilities from the Command Line
Invoking Build Utilities from the Command Line
clearmake [ -f makefile ] ... [ -ukinservwdpqUNR ]

[ -C compat-mode ] [ -V | -M ] [ -O | -T | -F ]
[ -A BOS-file ] ... [ macro=value ... ] [ target-name ... ]
Lowercase options are “standard” make options

Uppercase options are clearmake- and omake-
specific options
Options that do not take arguments can be grouped
(for example, -VOi)
Versions used in the build are selected by the
config spec of the view where the build is performed
Designating no target on the command line (such as clearmake as opposed to

clearmake hello.o) builds the default target designated by the makefile.
For detailed information, see Online Help topic makefile_ccase or Building Software
with ClearCase.

Derived Objects
Derived Objects
The build process creates derived objects (DO)
Derived objects can be reused
During the build with

clearmake, this
makefile produces the
derived objects:
hello
hello.o
util.o
10
The build process creates derived objects, which are objects created during the build,
either as a direct target or as a side-effect.
Derived objects can be reused by the same view or shared with other views.

Derived Objects (cont.)

The ClearCase File Browser displays information
about derived objects.
Derived objects
11
The ClearCase File Browser lists derived objects in the current view. In the example,
you can see derived objects hello, hello.o, and util.o.
CLI Procedure
The cleartool lsdo command displays the fully qualified names of all derived objects
created in the current VOB directory regardless of the view in which the DO was built.
/vobs/Hardware/src% cleartool lsdo -long
12-Dec-02.14:03:33 Pat User (pat.user@butanone)
create derived object "hello@@12-Dec.14:03.105"
size of derived object is: 7376
last access: 12-Dec-02.14:03:33
references: 1 => butanone:/tmp/default.vws
create derived object "hello.o@@12-Dec.13:54.103"
create derived object "util.o@@12-Dec.13:54.104"


Each DO has a unique identifier (DO-ID)
Example: hello@@14-Jan.09:54.617
By default, DOs are shareable; they can be reused by other

views
Shareable DOs are held in the view storage area, and a DO
catalog entry is stored in the VOB
12
Each DO has a unique identifier, which is the target name followed by a date and time
stamp and a unique decimal number.
Each DO also has a data container, a file that is the output of a make operation.
When a DO is created, its data container is stored in local view storage.
By default, DOs are shareable, which means that they can be reused in future builds in
other views. During a build, the build tool writes information about a newly built
shareable derived object to the VOB database. This VOB database catalog entry
identifies where a DO resides, and is used to determine whether the DO can be reused
in future builds.

Build Auditing
Build Auditing
During a build, MVFS monitors system calls
Stores data in a configuration record, the bill of
materials for a DO or set of DOs
Configuration records are associated with DOs
13
During a build, the MVFS (multiversioned file system) monitors system calls and records
data. ClearCase audits calls involving:
• Versioned objects used as build input
• View-private files used as build input
• Files created within VOB directories during the build
• Explicitly declared dependencies outside the VOB
ClearCase stores the audited information in a configuration record. A configuration
record is the bill of materials that fully documents the build. Configuration records are
associated with derived objects.
The configuration record has a variety of uses:
• Reproducing builds
• Binary sharing and avoidance of duplicate object files
• Detecting source dependencies if they are not explicitly listed in the makefile (for
version controlled objects)

Configuration Record: Example
Configuration Record: Example

/vobs/Hardware/src% cleartool catcr -l "hello@@12-Dec.14:03.105"
Target hello built by pat.ccuser
Information Host “butanone" running SunOS 5.6 (sun4u)
about the build Reference Time 12-Dec-02.14:03:32, this audit started …
itself View was butanone:/ccdata/views/pat_r2int.vws [uuid 56:80:88:fb:31]

Initial working directory was /vobs/Hardware/src
----------------------------
MVFS objects:
----------------------------
ClearCase directory version /vobs/Hardware/src@@/main/2 <12-Dec-13:58:41>
objects included derived object /vobs/Hardware/src/hello@@12-Dec.14:03.105 [new
derived object]
in the build
derived object /vobs/Hardware/src/util.o@@12-Dec.13:54.104
[referenced derived object, in makefile]
----------------------------
Macros and Variables and Options:
variables set by ----------------------------
makefile MKTUT_CC=cc
----------------------------
Build Script:
Build script
----------------------------
executed
cc -o hello hello.o util.o
14
The configuration record is a compiled object; you cannot view it using standard OS
utilities. To view a derived object (DO) configuration record, you must use the
cleartool catcr command.
Usage:
cleartool catcr <DO-ID>
Sections of a configuration record:
• Header Section displays information about the build.
• MVFS Section displays information about:
– All MVFS files and directories read during the build: versioned objects and view-
private files including checked-out versions
– All derived objects produced by the target rebuild
• Non-MVFS Section (not in this example) displays declared dependencies outside a
VOB, identified by a date/time modified (DTM) stamp.
• Variables and Options Sections lists the values of make macros referenced by the
build script and command-line options.
• Build Script Section identifies the build script used for this instance of the build.
Note
The version of the makefile is not included in the configuration record. To include
makefile versions, they must be explicitly declared as a target dependency.

Build Avoidance
Build Avoidance
Build avoidance is the ability to build using existing
DOs instead of creating new DOs
Configuration lookup compares the configuration
record of DO candidates with the build configuration
of the current view to determine whether to:
Reuse a DO that already exists in the current view
Use an existing DO from another view
Rebuild a DO by executing the build script
15
Build configuration refers to the set of source versions, the current build script that
would be executed, and the current build options of the view.
Configuration lookup is a process that compares the configuration record of a
previously built derived object with the build configuration of the view initiating a build.
If clearmake can find a like object, based on the configuration record, it attempts to
reuse the object rather than rebuild it. This process of reusing build objects is known as
build avoidance.

Build Avoidance Within a View: Reuse
Build Avoidance Within a View: Reuse

When you rebuild, clearmake reuses any matching
DOs stored in the view.
16
When you rebuild in a view, the configuration lookup process searches for DOs within
the view that it can reuse. The build tool attempts to avoid rebuilding derived objects. If
an appropriate DO exists in the view, clearmake reuses that DO.
After a build, the view process also creates a .cmake.state file, which is a compressed
copy of the configuration record cached in a view-private file. It is located in the
directory that was current when the view started. The .cmake.state file helps speed up
subsequent builds in this view.

Build Avoidance Among Views: Wink In
Build Avoidance Among Views: Wink In

If no DO match in the view, configuration lookup
checks the VOB DO catalog for DO matches
Wink in is the process of reusing a DO that was
created by another view
Wink in process:
Matching DOs are promoted, or migrated from view
storage to VOB storage
DO configuration records are moved to VOB database
A pointer is created from the second view to the data
container in VOB storage
17
If the configuration lookup does not find matching DOs in the view, it searches the
VOB DO catalog looking for matches to use.
If an unshared object exists in another view, clearmake compares the currently selected
versions with the .cmake.state file found in the unshared DO’s resident view.
To use the object, clearmake first promotes it to the VOB. It copies the DO data
container to VOB storage and moves the configuration record to the VOB database.
If the object has already been reused or manually promoted to the VOB, clearmake
supplies a pointer to the view that initiated the second build.

Wink In Process
Wink In Process
18
Unshared derived objects are promoted to shared status during the wink in process:
• Data container is copied to the DO cache in the VOB.
• Configuration record is moved to the VOB database.
• DO is winked in to View 2.
• Reference count in the VOB database catalog entry for hello.obj is incremented.
The cleartool lsdo -l command output indicates whether a DO is shared. The following
example is truncated to show only a shared DO:
cleartool lsdo -l
20-Jan-01.14:00:58 Pat User (pat.ccuers@butanone)
create derived object "hello.o@@20-Jan.14:00.76"
last access: 20-Jan-01.14:00:58
references: 3 (shared)
=> JAMES-PORT:E:\User\ccasetut\james\james_view.vws
=> JAMES-PORT:E:\User\ccasetut\james\james_view2.vws
=> JAMES-PORT:E:\User\ccasetut\james\rel1_vws

Build Avoidance Flow Chart
Build Avoidance Flow Chart
19
The flow chart on the slides illustrates the process by which ClearCase attempts to reuse
and wink in derived objects.

Build Reproducibility
Build Reproducibility
Configuration lookup ensures consistent rebuilds by
enabling clearmake to detect source dependencies
not declared in the makefile
Makefile:
hello: hello.o util.o
$(MKTUT_CC) -o hello hello.o util.o
hello.o:
$(MKTUT_CC) -c hello.c
util.o:
$(MKTUT_CC) -c util.c
hello.c: If hello.h changes, clearmake recognizes
the dependency, even if it is not declared
#include “hello.h” in the makefile.
int main() { ...
20
Configuration lookup also ensures that you can reproduce builds. Unlike standard make
utilities that rely on modification times of declared dependencies, configuration lookup
includes automatic dependency detection that detects dependencies not explicitly
stated in the makefile.
In the example, the Makefile does not explicitly list hello.h as a build dependency of
hello.c.
However, the hello.c file has an include rule referencing the need for hello.h.
Since hello.h is a versioned file, any previous builds would reference its version
extended name in the configuration record for the build.
make would miss any changes to hello.h (new versions, checkouts, etc.) because it is
not explicitly declared in the makefile.
Because of the configuration lookup feature of clearmake, a rebuild is detected when
hello.h is changed, as the version of hello.h used for the build is different than any other
version used for any other build.
To guarantee reproducibility, the build environment — including compilers and tools
— must be tightly controlled. Ideally, the build tools should be versioned.

Comparing Configuration Records
Comparing Configuration Records

Use cleartool diffcr to compare configuration records
of two derived objects.
diffcr [-recurse | -flat] [-select do-leaf-pattern] [-ci] [-type {f|d|l}...]

[-element_only] [-view_only] [-wd] [-name tail-pattern] [-nxname]
[-long | -short] do-pname do-pname2
21
You can use the cleartool diffcr command to compare the configuration records of two
derived objects. Developers might want to compare DO configuration records of two
builds, one that works and one that does not. The comparison could help them figure
out where the defect was introduced. A tester might want to compare two builds to
learn what areas of the application have changed so that they know where to focus
testing of new functionality.
The following build differences are detected:
• Versions of MVFS objects used as sources
• Objects produced during the build
• Versions of non-MVFS objects that appeared as makefile dependencies during the
build (for builds performed with omake)
• Total number of times an object was referenced during a build, and the first target
in which that object was referenced
• Build options
• Build script executed
You will need to know the fully-qualified DO-ID for the object you want to compare
with an object in the local view. An example appears on the next page.

Comparing Configuration Records: Example
Comparing Configuration Records: Example

/usr/Hardware/src% cleartool diffcr hello hello@@31-
Dec.07:25.304
< Target hello built by pat.users
> Target hello built by pat.users
< Reference Time 31-May-02.07:21:10, this audit started 31-
May-02.07:21:15
> Reference Time 31-Dec-02.07:25:39, this audit started 31-
May-02.07:25:45
< View was saturn:/home/joe/joe.vws [uuid
2be87837.138511cf.a4f0.00:01:80:a3:04:83]
> View was butanone:/ccdata/views/patr2_int.vws [uuid
6ea879f4.138511cf.a522.00:01:80:a3:04:83]
----------------------------
MVFS objects:
----------------------------
Different versions of
< /vobs/project/src/util.c@@/main/1 hello.c were used
> /vobs/project/src/util.c@@/main/3
----------------------------
< /vobs/project/src/hello@@31-Oct.07:21.297
> /vobs/project/src/hello@@31-Oct.07:25.304
22
This example shows a diffcr between two derived objects created in two different
views.
Some lines in the example above are truncated.

Express Builds
Express Builds
Express builds create DOs, but do not write
information to the VOB
Create nonshareable DOs — may be reused by
view in which they are created, but are not
shareable
Advantages:
Scalability: write access to the VOB is not blocked by DO
write operations, so more users can build
Performance: faster because they do not write DO
information to the VOB
Isolation: sharing is disabled until build quality is evaluated
23
There is a performance tradeoff when you create a derived object. While the build is
writing the DO information to the VOB database, you cannot write to the VOB. This
performance loss is offset when the DO is used by subsequent builds, which can make
those builds go faster. The performance loss is not offset if the DO is never used by
another build.
A ClearCase express build creates derived objects, but does not write information to the
VOB. These derived objects are nonshareable and cannot be used by other views. They
can be reused by the view in which they were built. Performance is significantly better
using express builds.
Commonly, projects will perform nightly non-express builds for the sole purpose of
populating the DO pool with wink-in candidates. The next day, developers will perform
express builds and realize the greater performance, but also get the advantage of being
able to wink-in DOs from the previous night’s build.
To do express builds, you must use a dynamic view whose DO property is set to create
nonshareable DOs.
You can change a nonshareable DO to shareable by promoting it to the VOB. There are
two ways to do this:
• Use cleartool winkin
• Use view scrubber -p
For more details on how to convert nonshareable DOs to shareable, see Building
Software with ClearCase.

Express Builds (cont.)
Express Builds (cont.)
To run express builds,

clear the Create
shareable derived
objects check box in
View Advanced
Options.
24
The view DO property is shown in the Properties of the View dialog box.
• Views with a shareable DO property create shareable derived objects.
• Views with a nonshareable DO property perform express builds and create
nonshareable DOs.

Versioning DOs and Configuration Records
Versioning DOs and Configuration Records

You can add derived objects and configuration
records to source control
Can still access the configuration record of DO
versions
Use the -from option of the cleartool checkin
command
25
You might want to versions DOs and configuration records when you have stable builds
that you want to preserve.
You can add derived objects and configuration records to source control using the –
from option of the cleartool checkin command.
The –from argument allows you to copy data from another location into an element
version tree. It is important to use this argument if you want to preserve the
configuration record along with the DO — specifically, do not copy the build target to
the checked-out file version.
Checking in a non-shareable DO with cleartool ci -from causes it and all of its sub-
targets to be converted to shareable.

Checking in a DO: Example
Checking in a DO: Example
/vobs/Hardware/bin% cleartool checkout -nc

hello
Checked out “hello” from version “/main/2”
/vobs/Hardware/bin% cleartool checkin –c
“Release 3” -from ../src/hello hello
Save private copy of "hello"? [yes] no
Checked in "hello" version “/main/3".
26
When checking in DOs from another location, do not copy, move or rename the build
target to the checked-out file version. Copying, moving, or renaming the build target
breaks the association between the DO and its configuration record.

Checking in Configuration Records
Checking in Configuration Records

To check in only the configuration record of a DO, use
the -cr option to cleartool checkin
/vobs/Hardware/bin% cleartool checkin -c "CR only"
-cr -from ../src/hello hello
Save private copy of "hello"? [yes] no
cleartool: Warning: Version checked in is not
selected by view.
Checked in "hello" version “/main/pat_r2_int/4".
To check in DOs with this method, you cannot access

the data of the DOs; however, they can be displayed
with ls and cleartool ls
/vobs/Hardware/bin% ls hello
hello
/vobs/Hardware/bin% hello
hello: No such device or address
27
If the configuration record is checked in, you can set a view configuration specification
to select the versions in the configuration record and reproduce the build.

Module Review
Module Review
List the distinguishing features of clearmake (and
omake on Windows).
What is a build audit?
What is build avoidance?
What does it mean to promote a derived object?
What does it mean to wink in a derived object?
What is an express build and why might you want to
perform one?
How do you version a derived object?
28

Module Lab
Module Lab
In this lab, you will:
View a makefile
Execute clearmake in view1
List derived objects
View a configuration record
Rebuild in view2
Compare configuration records
Add DO to source control
29



scm271 Ecc s10

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

scm271 Ecc s10

Diunggah oleh

Hak Cipta:

Format Tersedia

► ► ► Module 10

Managing Builds in ClearCase

IBM Software Group

Essentials of Rational ClearCase

© Copyright IBM Corp. 2003 10 - 1

10 - 2 © Copyright IBM Corp. 2003

© Copyright IBM Corp. 2003 10 - 3

10 - 4 © Copyright IBM Corp. 2003

© Copyright IBM Corp. 2003 10 - 5

ClearCase Build Utilities: clearmake and omake

ClearCase Build Utilities: clearmake and omake

 Compatible with makefiles constructed for use with

10 - 6 © Copyright IBM Corp. 2003

clearmake and omake Advantages

clearmake and omake Advantages

© Copyright IBM Corp. 2003 10 - 7

Building within Views

Building within Views

10 - 8 © Copyright IBM Corp. 2003

Invoking Build Utilities from the Command Line

Invoking Build Utilities from the Command Line

clearmake [ -f makefile ] ... [ -ukinservwdpqUNR ]

 Lowercase options are “standard” make options

Designating no target on the command line (such as clearmake as opposed to

© Copyright IBM Corp. 2003 10 - 9

During the build with

10 - 10 © Copyright IBM Corp. 2003

Derived Objects (cont.)

Derived Objects (cont.)

© Copyright IBM Corp. 2003 10 - 11

Derived Objects (cont.)

Derived Objects (cont.)

 By default, DOs are shareable; they can be reused by other

10 - 12 © Copyright IBM Corp. 2003

© Copyright IBM Corp. 2003 10 - 13

Configuration Record: Example

Configuration Record: Example

itself View was butanone:/ccdata/views/pat_r2int.vws [uuid 56:80:88:fb:31]

10 - 14 © Copyright IBM Corp. 2003

© Copyright IBM Corp. 2003 10 - 15

Build Avoidance Within a View: Reuse

Build Avoidance Within a View: Reuse

10 - 16 © Copyright IBM Corp. 2003

Build Avoidance Among Views: Wink In

Build Avoidance Among Views: Wink In

© Copyright IBM Corp. 2003 10 - 17

10 - 18 © Copyright IBM Corp. 2003

Build Avoidance Flow Chart

Build Avoidance Flow Chart

© Copyright IBM Corp. 2003 10 - 19

10 - 20 © Copyright IBM Corp. 2003

Comparing Configuration Records

Comparing Configuration Records

diffcr [-recurse | -flat] [-select do-leaf-pattern] [-ci] [-type {f|d|l}...]

© Copyright IBM Corp. 2003 10 - 21

Comparing Configuration Records: Example

Comparing Configuration Records: Example

10 - 22 © Copyright IBM Corp. 2003

© Copyright IBM Corp. 2003 10 - 23

Express Builds (cont.)

Express Builds (cont.)

To run express builds,

Compatible with makefiles constructed for use with

Lowercase options are “standard” make options

By default, DOs are shareable; they can be reused by other

To check in DOs with this method, you cannot access