clearmake

ClearCase build utility; maintains, updates, and regenerates groups of programs

APPLICABILITY

SYNOPSIS

• UNIX only-Build a target:

clearmake [ -f makefile ] ... [ -cukinservwdpqUNR ]

[ -J num ] [ -B bldhost-file ] [ -C compat-mode ] [ -V | -M ] [ -O | -T | -F ]
[ -A BOS-file ] ... [ macro=value ... ] [ target-name ... ]

• Windows only-Build a target:

clearmake [ -f makefile ] ... [ -cukinservwdpqUNR ]

[ -C compat-mode ] [ -V | -M ] [ -O | -T | -F ]
[ -A BOS-file ] ... [ macro=value ... ] [ target-name ... ]

• Display version information for clearmake:

clearmake { -ver·sion | -VerAll }

DESCRIPTION

clearmake is ClearCase's variant of the UNIX make(1) utility. It includes most of the features of UNIX System V make(1). It also features compatibility modes, which enable you to use clearmake with makefiles that were constructed for use with other popular make variants, including Gnu make.

clearmake features a number of ClearCase extensions:

• Configuration Lookup-A build-avoidance scheme that is more sophisticated than the standard scheme, which uses time stamps of built objects. Configuration lookup also includes automatic dependency detection. For example, this guarantees correct build behavior as C-language header files change, even if the header files are not listed as dependencies in the makefile.

• Derived Object Sharing-Developers working in different views can share the files created by clearmake builds.

• Creation of Configuration Records-Software bill-of-materials records that fully document a build and support the ability to rebuild.

NOTE: clearmake is intended for use in dynamic views. You can use clearmake in a snapshot view, but most of the features that distinguish it from ordinary make programs-build avoidance, build auditing, derived object sharing, and so on-are not enabled in snapshot views. (Parallel builds are enabled.) The rest of the information in this reference page assumes you are using clearmake in a dynamic view.

Related Reference Pages

The following reference pages include information related to clearmake operations and results:

See also Building Software with ClearCase.

View Context Required

For a build that uses the data in one or more VOBs, the shell or command interpreter from which you invoke clearmake must have a view context:

• On UNIX systems, the view context must be either a set view or a working directory view. If you have a working directory view, but it differs from the set view, clearmake changes its set view to the working directory view.

• On Windows systems, you must be on the dynamic-views drive (default: M:\) or a drive assigned to a view. If you want derived objects to be shared among views, you must be on a drive assigned to a view.

You can build objects in a standard directory, without a view context, but this disables many of clearmake's special features.

clearmake AND MAKEFILES

clearmake is designed to read makefiles in a way that is compatible with other make variants. For details, including discussions of areas in which the compatibility is not absolute, see Using clearmake Compatibility Modes in Building Software with ClearCase.

For more information about makefiles and clearmake, see Building Software with ClearCase.

HOW BUILDS WORK

In many ways, ClearCase builds adhere closely to the standard make paradigm:

1. You invoke clearmake, optionally specifying the names of one or more targets. (Such explicitly specified targets are called "goal targets.")

2. clearmake reads zero or more makefiles, each of which contains targets and their associated build scripts. It also reads zero or more build options specification (BOS) files, which supplement the information in the makefiles.

3. clearmake supplements the makefile-based software build instructions with its own built-in rules, or, when it runs in a compatibility mode, with built-in rules specific to that mode.

4. For each target, clearmake performs build avoidance, determining whether it actually needs to execute the associated build script (target rebuild). It takes into account both source dependencies (Have any changes occurred in source files used in building the target?) and build dependencies (Must other targets be updated before this one?).

5. If it decides to rebuild the target, clearmake executes its build script.

The following sections describe special clearmake build features in more detail. Figure 7 illustrates the associated data flow.

Figure 7 Data Flow in a clearmake Build

CONFIGURATION RECORDS AND DERIVED OBJECTS

In conjunction with the MVFS file system, clearmake audits the execution of all build scripts, keeping track of file use at the system-call level. For each execution of a build script, it creates a configuration record (CR), which includes the versions of files and directories used in the build, the build script, build options, (for example, macro assignments) and other related information. A copy of the CR is stored in the VOB database of each VOB in which the build script has built new objects.

A file created within a VOB by a build script is called a derived object (DO), and it can be shareable or nonshareable. When a shareable derived object is built in a view, a corresponding VOB database object is also created. This enables any view to access and possibly share (subject to access permissions) any derived object, no matter what view it was originally created in.

When a build tool creates a nonshareable derived object, the tool does not write any information about the DO to the VOB. Therefore, the DO is invisible to other views and cannot be winked in by them. Builds that create nonshareable DOs are called express builds. For more information about using express builds, see Preventing Winkin to Other Views.

NOTE: Symbolic links created by a build script and files created in non-VOB directories are not DOs. See MVFS FILES AND NON-MVFS OBJECTS.

For each build script execution, ClearCase logically associates each DO created with the build script's CR.

You can suppress the creation of CRs and derived objects with the -F option. For details on CRs, derived objects, see Derived Objects and Configuration Records in Building Software with ClearCase. For information on ClearCase-specific special targets, see Building Software with ClearCase.

Configuration Record Hierarchies

A typical makefile has a hierarchical structure. Thus, a single invocation of clearmake to build a high-level target can cause multiple build scripts to be executed and, accordingly, multiple CRs to be created.

CONFIGURATION LOOKUP AND WINKIN

For directory targets, clearmake uses standard make logic.

When a target names a nondirectory file in a VOB, clearmake (by default) uses configuration lookup to determine whether a build is required. This involves comparing the CRs of existing DOs with the current build configuration:

• The versions of elements selected by the view's config spec.

• The build options to be applied, as specified on the clearmake command line, in the environment, in makefile(s), or in build options specification file. See BUILD OPTIONS SPECIFICATION FILE.

• The build script to be executed.

In performing configuration lookup, clearmake considers a DO version (a derived object that has been checked in as a version of an element) only if the version's element has the same pathname as the original derived object. That is, if you copy a DO to a different location from where it was created and check it in there, clearmake does not consider the DO version.

clearmake first tries to avoid rebuilding by reusing a DO in the current view; this succeeds only if the CR of the candidate DO matches the current build configuration. For the purpose of rebuilding, a branch/0 version of a file selected by a view is considered to match its non-zero predecessor version in a CR.

clearmake can also avoid rebuilding by finding a shareable DO, built in another view, whose CR matches the current build configuration. In this case, it winks in (winkin) that derived object, causing it to be shared among views. Other derived objects created by the same build script (siblings) are winked in at the same time. clearmake rebuilds a target only if it cannot locate any existing derived object that matches the current build configuration.

DO versions must be checked out before they can be re-used or winked in. The -c option to clearmake provides support for automatically checking out these DOs before they are used. The CCASE_AUTO_DO_CI environment variable provides a means to automatically check in DOs checked out by clearmake -c. Checkouts executed by this feature behave like any cleartool checkout does with respect to reservation. Methods that can be used to change cleartool checkout's default reservation policy apply here as well. The checkouts are not audited. Checkins preserve the timestamp of the DO as though cleartool checkin -ptime were used. This feature is fully compatible with checkout or checkin triggers, which fire normally when the event occurs.

The .cmake.state File

The .cmake.state file is a view-private cache of config records for derived objects built in the view. clearmake creates this file in the directory that was current when the build started. During subsequent builds in that directory in the view, clearmake references the file instead of communicating with the VOB. This makes configuration lookup faster, improving clearmake performance.

You can delete .cmake.state files if they get too large. When clearmake looks for a .cmake.state file and it doesn't exist, no errors occur and clearmake creates a new file.

Suppressing Configuration Lookup

You can override the default configuration lookup behavior with command options and ClearCase special targets. (For information on ClearCase special targets, see Building Software with ClearCase). For example, -T turns off configuration lookup, basing rebuild decisions on time stamps, and -V disables winkin of DOs from other views.

Preventing Winkin to Other Views

You can prevent derived objects that you create from being winked in to other views by using express builds. During an express build, clearmake creates nonshareable DOs. These DOs have config records, but clearmake does not write information about the DOs into the VOB. DOs created during an express build are invisible to other views. To use express builds, invoke clearmake in a view configured with the nonshareable DOs property:

• To configure an existing view for express builds, use chview -nshareable_dos view-tag. See the chview reference page for more information.

• To create a new view and configure it with the nonshareable DOs property, use the mkview command and specify the -nshareable_dos option. See the mkview reference page for more information.

• Use the -T or -F options to create view-private files only.

• Use special targets that prevent winkin; for example, .NO_WINK_IN. For more information, see Building Software with ClearCase.

• Set an environment variable that no other users set identically. This environment variable will be recorded in the config records clearmake creates.

MVFS FILES AND NON-MVFS OBJECTS

All files with pathnames below a VOB-tag (VOB mount point) are termed MVFS files:

• Checked-in versions of file elements (data stored in VOB)

• Checked-out versions of file elements (data stored in view)

• Other view-private files

• Derived objects

Conversely, a non-MVFS object is any file, directory, or UNIX link whose pathname is not under a VOB-tag; such objects are not version controlled. By default, non-MVFS objects are not audited during clearmake builds. Non-MVFS files that are read during a build are not included in the detected dependency list of the CR, and non-MVFS files that are created are not ClearCase derived objects. A CR includes information on a non-MVFS object used by a build script only if either of these conditions are true:

• The object appears as an explicit dependency in the makefile.

• The object can be inferred to be a dependency through clearmake's file-name extension rules.

The explicit dependency is referred to as a makefile dependency. For example:

src.o : /usr/include/stdio.h

UNIX Systems Only-Non-MVFS Files in Configuration Lookup and Remote Building

During configuration lookup, clearmake examines each non-MVFS file that is listed in the CR of a candidate DO. The CR entry includes: the non-MVFS file's size, its time stamp, and its checksum. The current version of the non-MVFS file must match the CR entry in one of these ways:

• First check: file size and time stamp

• Second check: file size and checksum

clearmake also performs these checks during a parallel build. If the characteristics of a file are different on the local machine and the remote build host, clearmake does not attempt the rebuild; instead, it prints the following message:

abe: Error: Inconsistent version for dependency "dependency"

This ensures the consistency of a build across multiple hosts.

BUILD OPTIONS SPECIFICATION FILE

A build options specification (BOS) file is a text file containing macro definitions and/or ClearCase special targets. We recommend that you place nonpermanent option specifications (for example, a macro that specifies "compile for debugging") in a BOS file, instead of on the clearmake command line. This minimizes the likelihood of having clearmake perform a rebuild unexpectedly (for example, because you specified -g (UNIX) or /Zi (Windows) on a compiler command line last time, but forgot to specify it this time).

See Building Software with ClearCase for details.

clearmake SLEEP

clearmake can monitor the current VOB's lock status during a build, so that if an administrator locks the VOB while clearmake is running, the build does not terminate abnormally. Before executing the build script and before creating a derived object and configuration record, clearmake checks the lock status of the current VOB. If the VOB is locked, clearmake starts a sleep-check cycle. When it finds the VOB unlocked, the build proceeds.

NOTE: clearmake starts the sleep-check cycle even if the user who invokes the build is on the exception list for the lock.

When a sleep-check cycle begins, clearmake prints a message announcing the sleep, its duration, and the reason for it. Initially, clearmake checks the lock status 10 times, waiting 60 seconds between attempts. clearmake then increments the sleep time by 5 seconds and again tries 10 times, and so on. clearmake prints a sleep message at the start of each group of 10 retries.

This implementation does not guarantee that the build will not terminate abnormally. There are still a few "windows of failure." The build script will fail and terminate abnormally, and the build will terminate if any of these conditions is true:

• The build script modifies the VOB, either by running a cleartool command that modifies the VOB, or simply removing the derived object which is the target of the build.

• The build script writes to another VOB other than the current VOB, and the other VOB is locked.

• The VOB becomes locked in the short time between the check and the build script execution, and the build script has an action that modifies the VOB.

By default, clearmake checks the VOB containing the working directory that was current at the start of the build. To check a set of VOBs, set the environment variable CCASE_BLD_VOBS to the list of VOB-tags to check. Separate the VOB-tags in the list with a space, tab, colon (UNIX), semicolon (Windows), or comma.

To disable the checks, set the environment variable CCASE_BLD_NOWAIT. When this environment variable is set, clearmake does not check for a VOB-lock (or wait for the VOB to be unlocked).

CACHING UNAVAILABLE VIEWS

When clearmake shops for a derived object to wink in to a build, it may find DOs from a view that is unavailable (because the view server host is down, the albd_server is not running on the server host, and so on). Attempting to fetch the DO's configuration record from an unavailable view causes a long time-out, and the build may reference multiple DOs from the same view.

clearmake and other cleartool commands that access configuration records and DOs (lsdo, describe, catcr, diffcr) maintain a cache of tags of inaccessible views. For each view-tag, the command records the time of the first unsuccessful contact. Before trying to access a view, the command checks the cache. If the view's tag is not listed in the cache, the command tries to contact the view. If the view's tag is listed in the cache, the command compares the time elapsed since the last attempt with the time-out period specified by the CCASE_DNVW_RETRY environment variable. If the elapsed time is greater than the time-out period, the command removes the view-tag from the cache and tries to contact the view again.

NOTE: The cache is not persistent across clearmake sessions. Each recursive or individual invocation of clearmake attempts to contact a view whose tag may have been cached in a previous invocation.

The default time-out period is 60 minutes. To specify a different time-out period, set CCASE_DNVW_RETRY to another integer value (representing minutes). To disable the cache, set CCASE_DNVW_RETRY to 0.

UNIX ONLY-PARALLEL BUILDING

clearmake supports parallel building (execution of several build scripts concurrently on one or more hosts). Parallel building is enabled by the -J option, which specifies the parallelism (concurrency) level, and the build hosts file, which lists hosts where build scripts can be dispatched.

Before starting a parallel build, clearmake determines what work needs to be done, organizing the work as a sequence of target rebuilds. clearmake then dispatches build scripts to hosts, using a load balancing scheme. By default, a host is used only if it is at least 50% idle. You can adjust this idleness threshold with a -idle specification in your build hosts file. See the bldhost and bldserver.control reference pages for details.

To suppress parallel building for some or all of a makefile's targets, use the special .NOTPARALLEL target. See Building Software with ClearCase for details.

For information on setting up a parallel build, see Setting Up a Parallel Build in Building Software with ClearCase.

UNIX Only-Remote Build Environment

clearmake dispatches a build script to a remote host by invoking a remote shell there. This shell, in turn, runs an audited build executor (abe) process which executes the build script. If the abe process cannot be started, clearmake will not use the host.

For information on how the environment is set, see the abe reference page.

UNIX Only-Terminal Output

In a serial build (-J not specified), a target's build script is connected to stdout directly. Output appears as soon as it is produced by the script's commands. In a parallel build (-J specified with an argument >=1), the standard output of each build script is accumulated in a temporary file by clearmake. As each build script finishes, clearmake sends it to stdout all at once.

UNIX Only-Enabling Parallel Building on the Local Host

To perform a parallel build on the local host, make sure that both of the following conditions are true:

• CCASE_HOST_TYPE is unset when you invoke clearmake.

• You specify -J num on the clearmake command line, where num is greater than 0.

clearmake uses the idle specification in your host's bldserver.control file to determine whether it can perform the build on your host. If your host does not have a bldserver.control file, clearmake assumes an idle threshold of 0 and performs the build regardless of the load on your host.

NOTE: clearmake prints a message that it is performing a parallel build on the local host.

UNIX Only-Parallel Build Scheduler

clearmake schedules and manages target rebuilds as follows:

• It executes the build script for an out-of-date target as soon after detection as system build resources will allow.

• It does not assume that executing a build script for a specific target implies that the target was updated.

clearmake evaluates the dependency graph, beginning with the command-line supplied targets. Before evaluating a specific target, clearmake ensures that all dependents of that target have been evaluated and brought up to date. As soon as a target is deemed to be out of date, it is made available for rebuilding. A rebuild is initiated as soon as system resources allow. Depending on the availability of build hosts and load-balancing settings, this may happen immediately or be delayed.

When DO shopping/winkin occurs, clearmake postpones DO lookup for any target that has scheduled dependents until the target is encountered in the rebuild logic. When a target with previously scheduled dependents is encountered in the rebuild logic, clearmake then performs the DO shopping/winkin attempt only when the target's dependencies have completed. This eliminates unnecessary rebuilds in serial mode and allows a parallel clearmake to initiate rebuilds sooner.

UNIX Only-Building Targets on Specified Hosts

When you perform a parallel build with clearmake, you can specify that clearmake must build a target on a certain host. The environment variable CCASE_BLD_HOSTS specifies one or more build hosts.

NOTE: These hosts do not have to appear in your build hosts file. If a specified host appears in your build hosts file, clearmake ignores any -idle specifications for the host in the build hosts file and uses -idle 0.

We recommend that you set this variable conditionally in your makefile, using target-dependent variable bindings. If you set the variable on the clearmake command line, in your process environment, or unconditionally in your makefile, it applies to all targets.

NOTE: clearmake supports target-dependent variable bindings in standard mode and in Sun compatibility mode. You can also use target-dependent variable bindings in your BOS file for any compatibility mode.

For example, to ensure that the target foo is built on host neon or saturn:

foo := CCASE_BLD_HOSTS = neon saturn

You can also use patterns in target names. For example, to build all .o files on host pluto:

%.o := CCASE_BLD_HOSTS = pluto

clearmake applies CCASE_BLD_HOSTS bindings to dependencies of the specified targets. To apply CCASE_BLD_HOSTS to the specified targets but not their dependencies, add the line shown below to the builtins file for your compatibility mode:

BUILD REFERENCE TIME AND BUILD SESSIONS

clearmake takes into account the fact that as your build progresses, other developers can continue to work on their files, and may check in new versions of elements that your build uses. If your build takes an hour to complete, you do not want build scripts executed early in the build to use version 6 of a header file, and scripts executed later to use version 7 or 8. To prevent such inconsistencies, clearmake locks out any version that meets both of these conditions:

• The version is selected by a config spec rule that includes the LATEST version label.

• The version was checked in after the time the build began (the build reference time).

This reference-time facility applies to checked-in versions of elements only; it does not lock out changes to checked-out versions, other view-private files, and non-MVFS objects. clearmake adjusts for the fact that the system clocks on different hosts in a network may be somewhat out of sync (clock skew).

For more information, see Pointers on Using ClearCase Build Tools in Building Software with ClearCase.

EXIT STATUS

clearmake returns a zero exit status if all goal targets are successfully processed. It returns a nonzero exit status in two cases:

• clearmake itself detects an error, such as a syntax error in the makefile. In this case, the error message includes the string "clearmake".

• A makefile build script terminates with a nonzero exit status (for example, a compiler error).

See also the description of the -q option.

OPTIONS AND ARGUMENTS

clearmake supports the options below. In general, standard make options are lowercase characters and clearmake extensions are uppercase. Options that do not take arguments can be combined on the command line (for example, -rOi).

-f makefile

Use makefile as the input file. If you omit this option, clearmake looks for input files named makefile and Makefile (in that order) in the current working directory. You can use more than one -f makefile argument pair. Multiple input files are effectively concatenated.

-u

(Unconditional) Rebuild all goal targets specified on the command line, along with the recursive closure of their dependencies, regardless of whether they need to be rebuilt. (See also -U.)

-k

Abandon work on the current entry if it fails, but continue on other targets that do not depend on that entry.

-i

Ignore error codes returned by commands.

-n

(No-execute) List command lines from the makefile for targets which need to be rebuilt, but do not execute them. Even lines beginning with an at-sign (@) are listed. See Building Software with ClearCase.

Exception: A command containing the string $(MAKE) is always executed on Windows systems. On UNIX systems, it is executed unless you are using sgismake or sgipmake compatibility mode. These modes do not necessarily execute $(MAKE).).

-s

(Silent) Do not list command lines before executing them.

-e

Environment variables override macro assignments within the makefile. (But macro=value assignments on the command line or in a build options spec override environment variables.)

-r

(No-rules) Do not use the built-in rules in file ccase-home-dir/etc/builtin.mk (UNIX) or ccase-home-dir\etc\builtin.mk (Windows). When used with -C, this option also disables reading platform-specific startup files. See the -C option for more information.

-v

(Verbose) Slightly more verbose than the default output mode. These features are particularly useful:

Listing of why clearmake does not reuse a DO that already appears in your view (for example, because its CR does not match your build configuration, or because your view does not have a DO at that pathname)

Listing of the names of DOs being created

-w

(Working directory) Prints a message containing the working directory both before and after executing the makefile.

-d

(Debug) Quite verbose; appropriate only for debugging makefiles.

-p

(Print) Lists all target descriptions and all macro definitions, including target-specific macro definitions and implicit rules, and stops before executing anything.

-q

(Query) Evaluates makefile targets, but does not run the build scripts. clearmake returns 0 if the targets are up to date, and 1 if any targets need to be rebuilt. Note that clearmake treats a winkin of a derived object as a rebuild, so clearmake -q returns 1 if a DO can be winked in for a target.

-c

(Check out DOs) Before building or winking in a target, clearmake determines whether the target is a checked-in DO visible in the view at the path named in the makefile. If such a DO is found, clearmake -c checks it out before rebuilding it or winking it in. If a target creates sibling DOs, target group syntax must be used in the makefile or siblings will not be subject to this behavior.

-U

Unconditionally builds goal targets only. Subtargets undergo build avoidance. If you don't specify any target on the command line, the default target is the goal. (The -u option unconditionally builds both goal targets and build dependencies.)

-N

Disables the default procedure for reading one or more BOS files. For a description of the default procedure, see Building Software with ClearCase.

-R

(Reuse) Examines sibling derived objects (objects created by the same build rule that created the target) when determining whether a target object in a VOB can be reused (is up to date). By default, when determining whether a target can be reused, clearmake ignores modifications to sibling derived objects. -R directs clearmake to consider a target out of date if its siblings have been modified or deleted.

-J num

Enables clearmake's parallel building capability. The maximum number of concurrent target rebuilds is set to the integer num. If num=0, parallel building is disabled. (This is equivalent to not specifying a -J option at all.)

Alternatively, you can specify num as the value of environment variable CCASE_CONC, described in Special Environment Variables.

For more information, see UNIX ONLY-PARALLEL BUILDING.)

-B bldhost-file

Uses bldhost-file as the build hosts file for a parallel build. If you do not specify -B, clearmake uses the file .bldhost.$CCASE_HOST_TYPE in your home directory. When you use -B, you must also use -J or have the CCASE_CONC environment variable set. For more information, see the bldhost reference page.

-C compat-mode

(Compatibility) Invokes one of clearmake's compatibility modes. (Alternatively, you can use environment variable CCASE_MAKE_COMPAT in a BOS file or in the environment to specify a compatibility mode.)

On UNIX systems, compat-mode can be one of the following:

sgismake	Emulates the smake(1) native to IRIX systems. To define built-in make rules, clearmake reads file /usr/include/make/system.mk instead of ccase-home-dir/etc/builtin.mk.
sgipmake	Emulates the pmake(1) native to IRIX systems. To define built-in make rules, clearmake reads file /usr/include/make/system.mk instead of ccase-home-dir/etc/builtin.mk.
sun	Emulates the standard make(1) native to SunOS systems. clearmake defines built-in make rules in the following ways: If you specify -r, clearmake reads ccase-home-dir/etc/sunvars.mk. If you do not specify -r, clearmake reads ccase-home-dir/etc/sunvars.mk and ccase-home-dir/etc/sunbuiltin.mk. If the current directory contains a default.mk file, clearmake reads it; otherwise, clearmake reads /usr/share/lib/make/make.rules (Solaris) or /usr/include/make/default.mk (SunOS).
aix	Emulates the standard make(1) native to IBM AIX systems.
gnu	Emulates the Free Software Foundation's Gnu make program. To define built-in make rules, clearmake reads file ccase-home-dir/etc/gnubuiltin.mk instead of ccase-home-dir/etc/builtin.mk.
std	Invokes the standard clearmake with no compatibility mode enabled. Use this option to nullify a setting of the environment variable CCASE_MAKE_COMPAT.

The -C option is UNIX-platform independent. However, some modes try to read system-specific files, and if the files do not exist, the command fails. For more information on the platform-specific methods for dealing with this failure, see ClearCase and MultiSite Release Notes.

On Windows systems, compat-mode can be one of the following:

gnu	Emulates the Free Software Foundation's Gnu make program. To define built-in make rules, clearmake reads file ccase-home-dir\etc\gnubuiltin.mk instead of ccase-home-dir\etc\builtin.mk.
std	Invokes the standard clearmake with no compatibility mode enabled. Use this option to nullify a setting of the environment variable CCASE_MAKE_COMPAT.

For details on compatibility mode features, see Using clearmake Compatibility Modes in Building Software with ClearCase.

-V

(View) Restricts configuration lookup to the current view only. Winkin is disabled. This option is mutually exclusive with -M.

-M

(Makefile) Restricts dependency checking to makefile dependencies only-those dependencies declared explicitly in the makefile or inferred from a suffix rule. All detected dependencies are ignored. For safety, this disables winkin.

For example, a derived object in your view may be reused even if it was built with a different version of a header file than is currently selected by your view. This option is mutually exclusive with -V.

-O (Objects)

-T (Time stamps)

-F (Files)

(-O, -T, and -F are mutually exclusive.)

-O compares only the names and versions of objects listed in the targets' CRs; it does not compare build scripts or build options. This is useful when this extra level of checking would force a rebuild that you do not want. Examples:

The only change from the previous build is the setting or canceling of a "compile-for-debugging" option.

A target was built using a makefile in the current working directory. Now, you want to reuse it in a build to be performed in the parent directory, where a different makefile builds the target (with a different script, which typically references the target using a different pathname).

-T makes rebuild decisions using the standard algorithm, based on time stamps; configuration lookup is disabled. (A CR is still created for each build script execution.)

NOTE: This option causes both view-private files and derived objects to be used for build avoidance. Because the view-private file does not have a CR to be included in the CR hierarchy, the hierarchy created for a hierarchical build has a gap wherever clearmake reuses a view-private file for a subtarget.

-F works like -T, but also suppresses creation of configuration records. All MVFS files created during the build are view-private files, not derived objects.

-A BOS-file ...

You can use this option one or more times to specify BOS files to be read instead of, or immediately after, the ones that are read by default. Using -N along with this option specifies "instead of"; omitting -N causes clearmake to read the -A file after reading the standard BOS files.

Alternatively, you can specify a colon-separated list of BOS file pathnames (UNIX) or a semicolon-separated list such pathnames as the value of environment variable CCASE_OPTS_SPECS.

-ver·sion

Prints version information about the clearmake executable.

-VerAll

Prints version information about the clearmake executable and the libraries (UNIX) or ClearCase DLLs (Windows) that clearmake uses.

MAKE MACROS AND ENVIRONMENT VARIABLES

String-valued variables called make macros can be used anywhere in a makefile: in target lists, in dependency lists, and/or in build scripts. For example, the value of make macro CFLAGS can be incorporated into a build script as follows:

• UNIX:

cc -c $(CFLAGS) msg.c

• Windows:

cl $(CFLAGS) msg.c

Environment variables (EVs) can also be used in a makefile, but only in a build script. For example:

print:
print_report -style $$PRT_STYLE -dest $${PRT_DEST}.rpt

clearmake converts the double-dollar-sign ($$) to a single dollar sign:

• On UNIX systems, the EV is expanded in the shell in which the build script executes. (Programs invoked by the build script can also read their environment, using getenv(2).)

• On Windows systems, the EV is expanded in the shell in which the build script executes only if the shell recognizes the dollar sign ($) (cmd.exe does not).

Conflict Resolution

Conflicts can occur in specifications of make macros and environment variables. For example, the same make macro might be specified both in a makefile and on the command line; or the same name may be specified both as a make macro and as an environment variable.

clearmake resolves such conflicts similarly to other make variants; it uses the following priority order, from highest to lowest:

1. Target-specific macros specified in a BOS file

2. Target-specific macros specified in a makefile

3. Make macros specified on the command line

4. Make macros specified in a BOS file

5. Make macros specified in a makefile

6. Environment variables

7. Built-in macros

Using the -e option gives environment variables higher priority than make macros specified in a makefile.

Conflict Resolution Details. The following discussion treats this topic more precisely but less concisely.

clearmake starts by converting all EVs in its environment to make macros. (SHELL is an exception-see SHELL Environment Variable.) These EVs are also placed in the environment of the shell process in which a build script executes. Then, it adds in the make macros declared in the makefile. If this produces name conflicts, they are resolved as follows:

• If clearmake was not invoked with the -e option, the macro value overwrites the EV value in the environment.

• If clearmake was invoked with the -e option, the EV value becomes the value of the make macro.

Finally, clearmake adds make macros specified on the command line or in a BOS file; these settings are also added to the environment. These assignments always override any others that conflict. (A command-line assignment overrides a BOS setting of the same macro.)

SHELL Environment Variable

clearmake does not use the SHELL environment variable to select the shell program in which to execute build scripts. It uses a UNIX Bourne shell (/bin/sh) or Windows cmd.exe, unless you specify another program with a SHELL macro. You can specify SHELL on the command line, in the makefile, or in a build options spec; the value of SHELL must be a full pathname, and on Windows, it must include the file extension.

NOTE: If clearmake determines that it can execute the build script directly, it does not use the shell program even if you specify one explicitly. If you use Windows .bat files in build scripts, you must make them executable (use the cleartool protect command). To force clearmake to always use the shell program, set the environment variable CCASE_SHELL_REQUIRED.

Specifying Command Options in an Environment Variable

The CCASE_MAKEFLAGS and MAKEFLAGS environment variables provide an alternative (or supplementary) mechanism for specifying clearmake command options. These environment variables can contain a string of keyletters, the same letters used for clearmake command-line options. (However, clearmake does not allow options that take arguments in a CCASE_MAKEFLAGS or MAKEFLAGS string. See Special Environment Variables for information about specifying options that are not supported through CCASE_MAKEFLAGS or MAKEFLAGS.)

For example, the commands

are equivalent to this one:

clearmake combines the value of CCASE_MAKEFLAGS or MAKEFLAGS with the options specified on the command line (if any). The combined string of keyletters becomes the value of the macro MAKEFLAGS, available to build scripts.

This is very useful for build scripts that involve recursive invocations of clearmake. When clearmake -n is applied to such a build script, all the nested invocations of clearmake pick up the "no-execute" option from the value of CCASE_MAKEFLAGS or MAKEFLAGS. Thus, no targets are actually rebuilt, even though many levels of clearmake command may be executed. This is one way to debug all of the makefiles for a software project without building anything.

clearmake uses one of CCASE_MAKEFLAGS or MAKEFLAGS, but not both. If CCASE_MAKEFLAGS is set, clearmake uses it. If CCASE_MAKEFLAGS is not set, clearmake looks for MAKEFLAGS.

If you use other make programs in addition to clearmake, putting clearmake-specific options in the MAKEFLAGS environment variable may cause the make programs to generate errors. Therefore, we suggest you use the CCASE_MAKEFLAGS and MAKEFLAGS environment variables in the following ways:

Special Environment Variables

The environment variables described below are also read by clearmake at startup. In some cases, as noted, you can also specify the information as a make macro on the command line, in a makefile, or in a BOS file.

CCASE_ABE_PN (or CLEARCASE_ABE_PN)

The full pathname with which clearmake invokes the audited build executor (abe) on a local or remote host during a parallel build.

Default: /bin/abe

CCASE_AUDIT_TMPDIR (or CLEARCASE_BLD_AUDIT_TMPDIR)

Sets the directory where clearmake and clearaudit create temporary build audit files. If this variable is not set or is set to an empty value, clearmake creates these files in the directory specified by the TMPDIR (UNIX) or TMP (Windows) environment variable.

On UNIX systems, if neither CCASE_AUDIT_TMPDIR nor CLEARCASE_BLD_AUDIT_TMPDIR is set, clearmake creates these files in the /tmp directory.

All temporary files are deleted when clearmake exits. If the value of CCASE_AUDIT_TMPDIR is a directory under a VOB-tag, clearmake prints an error message and exits.

NOTE: Multiple build clients can use a common directory for audit files. Names of audit files are unique because clearmake names them using both the PID of the clearmake process and the hostname of the machine on which the process is running.

Default on UNIX: /tmp

Default on Windows: None

CCASE_AUTO_DO_CI

Checks in DOs checked out by clearmake -c unless the build of the corresponding target fails or the automatic checkout of the DO or a sibling DO fails. Checkout comments are preserved. The checkin is invoked with the -ptime option to preserve the DO's modification time. This environment variable has no effect unless you specify -c.

Default: Undefined

CCASE_BLD_HOSTS

Specifies one or more build hosts on which clearmake must build targets. For more information, see UNIX Only-Building Targets on Specified Hosts.

Default: Undefined.

CCASE_BLD_NOWAIT

Turns off clearmake's sleep-check cycle during a build. When this environment variable is set, clearmake does not check for a VOB-lock (or wait for the VOB to be unlocked). See clearmake SLEEP for more information.

CCASE_BLD_UMASK (or CLEARCASE_BLD_UMASK)

Sets the umask(1) value to be used for files created from a clearmake build script. It may be advisable to have this EV be more permissive than your standard umask-for example, CCASE_BLD_UMASK = 2 where umask = 2. The reason to create DOs that are more accessible than other files is winkin: a winked-in file retains its original ownership and permissions. For example, when another user winks in a file that you originally built, the file is still owned by you, is still a member of your principal group, and still has the permissions with which you created it. You can use the standard chmod command to change the permissions of a DO after you create it, and these permissions remain in effect while the DO is unshared. However, for a shared DO, you may need to use the standard chmod and protect -chmod to set appropriate permissions.

If you are using a tool that ignores umask (and hence CCASE_BLD_UMASK) settings and you want winkins to work correctly, you have to use chmod on the file in your build script to give it write permissions if the tool creates the file without these permissions.

CCASE_BLD_UMASK can also be coded as a make macro.

NOTE: If you want to use CCASE_BLD_UMASK, do not set your umask value in your shell startup file. If you set the umask value in your startup file, the umask value will be reset to its original value when clearmake starts a shell to run the build script. Setting CCASE_BLD_UMASK in your startup file has no effect.

Default: Same as current umask.

CCASE_BLD_VOBS

A list of VOB-tags (separated with a space, tab, comma, colon (UNIX), or semicolon (Windows) to be checked for lock status during a build. If a VOB on this list is locked, clearmake goes into a sleep-check cycle. See clearmake SLEEP for more information.

CCASE_CONC (or CLEARCASE_BLD_CONC)

Sets the concurrency level. This EV takes the same values as the -J option. Specifying a -J option on the command line overrides the setting of this EV.

Default: None.

CCASE_DNVW_RETRY

Specifies time-out period, in minutes, for clearmake to wait before trying to contact an inaccessible view listed in its cache. To disable the cache, set CCASE_DNVW_RETRY to 0.

Default: 60 minutes.

CCASE_HOST_TYPE (or CLEARCASE_BLD_HOST_TYPE)

Determines the name of the build hosts file to be used during a parallel build (-J option): file .bldhost.$CCASE_HOST_TYPE in your home directory. (Your home directory is determined by examining the password database.)

Specifying a -B option on the command line overrides the setting of this EV.

C Shell Users: Set this EV in your .cshrc file, not in your .login file. The parallel build facility invokes a remote shell, which does not read the .login file.

CCASE_HOST_TYPE can also be coded as a make macro.

Default: none.

CCASE_MAKE_CFG_DIR (or CLEARCASE_MAKE_CONFIG_DIR)

Expands to the full pathname of the clearmake configuration directory in the ClearCase installation area-typically /usr/atria/config/clearmake (UNIX) or ccase-home-dir\config\clearmake (Windows).

CCASE_MAKE_COMPAT (or CLEARCASE_MAKE_COMPAT)

Specifies one of clearmake's compatibility modes. This EV takes the same values as the -C option. Specifying a -C option on the command line overrides the setting of this EV. This EV may also be coded as a make macro, but only in a BOS file (not in a makefile).

Default: None.

CCASE_OPTS_SPECS (or CLEARCASE_BLD_OPTIONS_SPECS)

A list of pathnames separated by colons (UNIX) or semicolons (Windows), each of which specifies a BOS file to be read. You can use this EV instead of specifying BOS files on the command line with one or more -A options.

Default: None.

CCASE_SHELL_FLAGS (or CLEARCASE_BLD_SHELL_FLAGS)

Specifies command options to be passed to the subshell program that executes a build script command.

Default for UNIX: -e

Default for Windows: None

CCASE_SHELL_REQUIRED

Forces clearmake to execute build scripts in the shell program you specify with the SHELL macro. To make clearmake execute builds scripts in the shell program, set this EV to TRUE. To allow clearmake to execute build scripts directly, unset the EV.

Default: clearmake executes build scripts directly.

CCASE_VERBOSITY (or CLEARCASE_BLD_VERBOSITY)

Sets the clearmake message logging level, as follows:

1	Equivalent to -v on the command line
2	Equivalent to -d on the command line
0 or undefined	Equivalent to standard message logging level

If you also specify -v or -d on the command line, the higher value prevails.

Default: 0

CMAKE_PNAME_SEP

Sets the pathname separator for pathnames constructed by clearmake. This variable can also be coded as a make macro in the makefile or in a BOS file.

Default: If this variable is not set or is set to any other value than / or \ (the slashes), clearmake uses \ (a backslash) as the pathname separator.

EXAMPLES

• Unconditionally build the default target in a particular makefile, along with all its dependent targets.

% clearmake -u -f project.mk

• Build target hello without checking build scripts or build options during configuration lookup. Be moderately verbose in generating status messages.

z:\src> clearmake -v -O hello

• Build the default target in the default makefile, with a particular value of make macro INCL_DIR. Base rebuild decisions on time-stamped comparisons instead of performing configuration lookup, but still produce CRs.

y:\> clearmake -T INCL_DIR=\src\include_test

• Perform a parallel build of target bgrs, using up to five of the hosts listed in file .bldhost.solaris in your home directory.

% setenv CCASE_HOST_TYPE solaris

% clearmake -J 5 bgrs

• Build target bgrs.exe, restricting configuration lookup to the current view only. Have environment variables override makefile macro assignments.

z:\src> clearmake -e -V bgrs.exe

• Build the default target in Sun compatibility mode.

% clearmake -C sun

FILES

ccase-home-dir/etc/builtin.mk (UNIX) or ccase-home-dir\etc\builtin.mk (Windows)

SEE ALSO

abe, bldhost, bldserver.control, clearaudit, omake, promote_server, scrubber, umask(1)

Building Software with ClearCase