Rational ClearCase Commands Reference

Restrictions

clearmake does not support the use of standard input as a makefile.

Libraries

If a target or dependency name contains parentheses, it is assumed to be an archive (library) created by ar(1) (UNIX), lib (Windows), or some other librarian. The string within parentheses refers to a member (object module) within the library. Use of function names within parentheses is not supported.

Inference rules for archive libraries have the form

The way in which clearmake handles incremental archive construction differs from other make variants.

Note: On UNIX, the u key for ar is not reliable within a ClearCase environment. Do not use it.

Command Echoing and Error Handling

You can control the echoing of commands and the handling of errors that occur during command execution on a line-by-line basis, or on a global basis.

You can prefix one or two characters to any command, as follows:

The –k option provides for partial recovery from errors. If an error occurs, execution of the current target (that is, the set of commands for the current target) stops, but execution continues on other targets that do not depend on that target.

Built-In Rules

—File name extensions (suffixes) and their associated rules in the makefile override any identical file name extensions in the built-in rules. clearmake reads built-in rules from the file builtin.mk when you run in standard compatibility mode. In other compatibility modes, other files are read.

Include Files

—If a line in a makefile starts with the string include or sinclude followed by white space (at least one <SPACE> or <TAB> character), the rest of the line is assumed to be a file name. (This name can contain macros.) The contents of the file are placed at the current location in the makefile.

For include, a fatal error occurs if the file is not readable. For sinclude, a nonreadable file is silently ignored.

Order of Precedence of Make Macros and Environment Variables

By default, the order of precedence of macros and environment variables is as follows:

For example, target-dependent macro definitions override all other macro definitions, and macros specified on the clearmake command line override those set in a BOS file.

If you use the –e option to clearmake, environment variables override macro definitions in the makefile.

All BOS file macros (except those overridden on the command line) are placed in the build script's environment. If a build script recursively invokes clearmake:

For a list of build-related environment variables, see Building Software.

Make Macros

A macro definition takes this form:

Macros can appear in the makefile, on the command line, or in a build options specification file. (See “Build Options Specification Files”.)

Macro definitions require no quotes or delimiters, except for the equal sign (=), which separates the macro name from the value. Leading and trailing white space characters are stripped. Lines can be continued using a \<NL> sequence; this sequence and all surrounding white space is effectively converted to a single <SPACE> character. macro_name cannot include white space, but string can; it includes all characters up to an unescaped <NL> character.

clearmake performs macro substitution whenever it encounters either of the following in the makefile:

It substitutes string for the macro invocation. In the latter form, clearmake performs an additional substitution within string: all occurrences of subst1 at the end of a word within string are replaced by subst2. If subst1 is empty, subst2 is appended to each word in the value of macro_name. If subst2 is empty, subst1 is removed from each word in the value of macro_name.

For example, on UNIX:

And on Windows:

Note: UNIX and Windows object files have different file extension naming conventions: .o for UNIX and .obj for Windows. Where this distinction is not important for the purposes of these discussions, .o is sometimes used to designate any object file in this reference page.

Internal Macros

clearmake maintains these macros internally. They are useful in rules for building targets.

VPATH Macro

The VPATH macro specifies a search path for targets and dependencies. clearmake searches directories in VPATH when it fails to find a target or dependency in the current working directory. clearmake searches only in the current view. The value of VPATH can be one directory pathname or a list of directory pathnames separated by colons (UNIX) or semicolons (Windows). (In Gnu compatibility mode, you can also use spaces as separators.)

Configuration lookup is VPATH-sensitive when qualifying makefile dependencies (explicit dependencies in the makefile). Thus, if a newer version of a dependent file appears in a directory on the search path before the pathname in the CR (the version used in the previous build), clearmake rejects the previous build and rebuilds the target with the new file.

The VPATH setting may affect the expansion of internal macros, such as $<.

Special Targets for Use in Makefiles

You can use the following special targets in the makefile.

Special Targets for Use in Makefiles or BOS Files

You can use the following special targets either in the makefile itself or in a build options specification file. See “Build Options Specification Files”.

Target for UNIX Only

You can use the following target only in UNIX makefiles or BOS files.

Build Macros and Case-Sensitivity

clearmake is case-sensitive with respect to makefile macros. Consider a makefile macro reference, $(CPU). There are numerous input sources from which to satisfy this macro:

For any macro to be expanded correctly from any of these sources, the macro definition and macro reference must be in the same case. For example, $(CPU) is not replaced by the value of an EV named CPU.

Makefile Target/Dependency Pathnames

When you write makefiles, you must be aware of the MVFS setting on your computer and specify targets and dependencies accordingly. If the MVFS is case-preserving, you must use case-correct pathnames in makefiles to guarantee the consistency of the resulting config records. Even if your MVFS is not case-preserving, we recommend that you use case-correct pathnames so that users on case-preserving computers can share the makefile.

Note: The –d option to clearmake warns you when case is the only difference in pathnames in the makefile and on the file system.

Table 7 describes makefile requirements for the different MVFS settings.

Supporting Both omake and clearmake

It is possible, but not trivial, to prepare makefiles that can be used with either omake or clearmake. The general approach is to supply omake-specific macro definitions in the makefile, and to supply clearmake-specific macro overrides in a build options specification (BOS) file; clearmake reads the BOS file, but omake does not. When clearmake executes, it looks for macro definitions in two locations:

BOS files at other locations can be passed to clearmake with the –A option.

Using UNIX-Style Command Shells in Makefiles

On Windows, clearmake accepts either slashes ( / ) or backslashes ( \ ) in pathnames. However, clearmake uses a backslash as the separator in any pathnames that it constructs in build scripts (for example, as a result of VPATH directory searching). This can cause problems with command shells that require slashes in any pathnames supplied to them in command lines.

If you are using such a shell (for example, by setting the SHELL makefile variable accordingly), you can force clearmake to use slashes when constructing pathnames. To do this, set the CMAKE_PNAME_SEP variable:

You can set CMAKE_PNAME_SEP in the makefile, in the BOS file, on the command line, or as an environment variable.

Standard Macro Definitions

A standard macro definition has the same form as a make macro defined in a makefile:

For example, on UNIX:

and on Windows:

Target-Dependent Macro Definitions

A target-dependent macro definition takes this form:

Any standard macro definition can follow the := operator; the definition takes effect only when targets matching patterns in target-pattern-list and their dependencies are processed. Patterns in the target-pattern-list must be separated by white space. For example on UNIX:

On Windows:

Two or more higher-level targets can have a common dependency. If the targets have different target-dependent macro definitions, the dependency is built using the macros for the first higher-level target clearmake considered building (whether or not clearmake actually built it).

Shell Command Macro Definitions

A shell command macro definition replaces a macro name with the output of a shell command:

This defines the value of macro_name to be the output of string, any shell command. In command output, <NL> characters are replaced by <SPACE> characters. For example, on UNIX:

On Windows:

Special Targets

You can use some ClearCase special targets in a build options spec. See “Special Targets”.

Include Directives

To include one BOS file in another, use the include or sinclude (silent include) directive. For example, on UNIX:

On Windows:

Comments

A BOS file can contain comment lines, which begin with a number sign (#).