clearmake

clearmake is the ClearCase variant of the UNIX and Linux 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.

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

Uses 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) Rebuilds 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

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

–i

Ignores error codes returned by commands.

Caution: If scripts called by clearmake fail, using this option will let clearmake continue and potentially create bad DOs and CRs due to the script failures. These DOs and CRs can be winked in to other views and create problems in a network environment. Use this option thoughtfully to avoid creating bad DOs and CRs in your build environment. In many cases, it is better to use the –k option.

–n

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

Exception: A command that contains the string $(MAKE) is always executed.

–s

(Silent) Does 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) Does not use the built-in rules in the file ccase-home-dir/etc/builtin.mk (UNIX and Linux) or ccase-home-dir\etc\builtin.mk (Windows). When used with the Gnu compatibility mode (–C gnu), this option also disables reading platform-specific startup files. For more information, see the –C option.

–b

(Both no rules and no predefined variables) Does not use the built-in rules and built-in variables in the file ccase-home-dir/etc/gnubuiltin.mk (UNIX and Linux) or ccase-home-dir\etc\nt_gnubuiltin.mk (Windows). This flag is only valid in the Gnu compatibility mode (–C gnu). For more information, see the –C option.

The –b option is the same as the –R option of GNU make.

–v

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

• Messages that indicate why clearmake does not reuse a DO that 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)
• List of the names of DOs being created
• Listing of any .bldhost file read during the build.

–w

(Working directory) Prints a message that contains 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; returns 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 do not 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 the DevOps Code ClearCase Guide to 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 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.)

Alternatively, you can specify num as the value of environment variable CCASE_CONC.

Note: clearmake -J warns you when a multi-target rule is found in a parallel build on UNIX and Linux.

clearmake -J -v (or -d) issues a warning when there is a target rule with multiple targets, but which is not a target group, is seen.

For example:

clearmake: Warning: File "Makefile", line 8
foo.h foo.c:

Rules with multiple targets might not build correctly in parallel, unless they are declared as a target group, such as:

a + b:

or as patterns in GNU compatibility, such as:

%.a %.b

Note that in a non-parallel build configuration, this warning is mostly informational and can be ignored.

–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 DevOps Code ClearCase Guide to 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 and Linux systems only, compat-mode can also have one of the values listed below. The –C option is UNIX and Linux platform independent. However, some modes try to read system-specific files; if those files do not exist, the command fails. For more information about the platform-specific methods for dealing with this failure, see the DevOps Code ClearCase and ClearCase MultiSite Release Notes.

sun	Emulates the standard make(1) native to Solaris 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.
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 those dependencies declared explicitly in the makefile or inferred from a suffix rule. All detected dependencies are ignored. For safety, this option disables winkin.

For example, a derived object in your view might 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 to set or cancel 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 path name).

–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 path names (UNIX and Linux) or a semicolon-separated list such path names 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 and Linux) or ClearCase DLLs (Windows) that clearmake uses.

• On a UNIX or Linux system, unconditionally build the default target in a particular makefile, along with all of its dependent targets.

  % clearmake -u -f project.mk

• On a Windows system, build the 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

• On a Windows system, 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

• On a UNIX or Linux system, perform a parallel build of target bgrs, using up to five of the hosts listed in file .bldhost.linux_x86_64 in your home directory.

  % setenv CCASE_HOST_TYPE linux_x86_64

  % clearmake -J 5 bgrs

• On a Windows system, 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

• On a UNIX or Linux system, build the default target in Sun compatibility mode.

  % clearmake -C sun

ccase-home-dir/etc/builtin.mk

ccase-home-dir\etc\builtin.mk

ant_ccase, clearaudit, clearmake.options, env_ccase, make(1), makefile_aix, makefile_ccase, makefile_gnu, makefile_sun, omake, promote_server, scrubber, umask(1), DevOps Code ClearCase Guide to Building Software