clearmake

ClearCase build utility

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

NOTE: The distinctive features of clearmake, such as build auditing, derived object sharing, and build avoidance, are supported in dynamic views only. In addition, while parallel building is supported in ClearCase snapshot views, it is not supported in ClearCase LT.

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.

RESTRICTIONS

Identities: No special identity required.

Locks: If it encounters a VOB lock while trying to write data, clearmake pauses and retries the operation every 60 seconds until it succeeds.

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.

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 and includes a list of the environment variables that clearmake reads during the build. Use this option only when 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.

-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.

-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 Building Software.

-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.) 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 gnubuiltin.mk instead of builtin.mk. See the makefile_gnu reference page.
std	Invokes clearmake with no compatibility mode enabled. Use this option to nullify a setting of the environment variable CCASE_MAKE_COMPAT.

On UNIX systems only, compat-mode can also have one of the values listed below. 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 Release Notes.

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. See the makefile_smake reference page.
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. See the makefile_pmake reference page.
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). See the makefile_sun reference page.
aix	Emulates the standard make(1) native to IBM AIX systems. See the makefile_aix reference page.

-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.

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

UNIX FILES

ccase-home-dir/etc/builtin.mk

WINDOWS FILES

ccase-home-dir\etc\builtin.mk

SEE ALSO

clearaudit, clearmake.options, env_ccase, make(1), makefile_aix, makefile_ccase, makefile_gnu, makefile_pmake, makefile_smake, makefile_sun, omake, promote_server, scrubber, umask(1), Building Software