5.3 Format of Makefiles

The following sections describe the special considerations for using makefiles with clearmake.

NOTE: For information about environment variables that affect clearmake, see the env_ccase reference page. You can also use the -d or -v option to the clearmake command to view a list of environment variables that clearmake reads during the build.

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 lib, or some other librarian. For example:

hello.lib : hello.lib(mod1.obj) hello.lib(mod2.obj)

The string within parentheses refers to a member (object module) within the library. Use of function names within parentheses is not supported. Thus, hello.lib(mod1.obj) refers to an archive that contains object module mod1.obj. The expression hello.lib(mod1.obj mod2.obj) is not valid.

Inference rules for archive libraries have this form:

.sfx.lib

where sfx is the file-name extension (suffix) from which the archive member is to be made.

The way in which clearmake handles incremental archive construction differs from other make variants. For more on this topic, see Working with Incremental Update Tools.

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 any command with one or two characters, 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 ccase-home-dir\etc\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.

Macros

The following sections describe the order of precedence of macros in a clearmake build, and the different types of macros.

Order of Precedence of Make Macros and Environment Variables

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

1. Target-dependent macro definitions

2. Macros specified on the clearmake command line

3. Make macros set in a BOS file

4. Make macro definitions in a makefile

5. Environment variables

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:

• The higher-level BOS file setting (now transformed into an EV) is overridden by a make macro set in the lower-level makefile. However, if the recursive invocation uses clearmake's -e option, the BOS file setting prevails.

• If another BOS file (associated with another makefile) is read at the lower level, its make macros override those from the higher-level BOS file.

See the env_ccase reference page for a list of all environment variables.

Make Macros

A macro definition takes this form:

macro_name = string

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:

$(macro_name)
$(macro_name:subst1=subst2)

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:

z:\myvob> type Makefile
C_SOURCES = one.c two.c three.c four.c
test:
echo OBJECT FILES are: $(C_SOURCES:.c=.obj)
echo EXECUTABLES are: $(C_SOURCES:.c=.exe)

z:\myvob> clearmake test
OBJECT FILES are: one.obj two.obj three.obj four.obj
EXECUTABLES are: one.exe two.exe three.exe four.exe

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 semicolon-separated list of directory pathnames. (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

Like other build tools, clearmake interprets certain target names as declarations. Some of these special targets accept lists of patterns as their dependents, as noted in the description of the target. Pattern lists may contain the pattern character, %. When evaluating whether a name matches a pattern, the tail of the prefix of the name (subtracting directory names as appropriate) must match the part of the pattern before the %; the file-name extension of the name must match the part of the pattern after the %. For example:

The following targets accept lists of patterns:

• .DEPENDENCY_IGNORED_FOR_REUSE

• .INCREMENTAL_REPOSITORY_SIBLING

• .INCREMENTAL_TARGET

• .NO_CMP_NON_MF_DEPS

• .NO_CMP_SCRIPT

• .NO_CONFIG_REC

• .NO_DO_FOR_SIBLING

• .NO_WINK_IN

• .SIBLING_IGNORED_FOR_REUSE

Special Targets for Use in Makefiles

.DEFAULT :

If a file must be built, but there are no explicit commands or relevant built-in rules to build it, the commands associated with this target are used (if it exists).

.IGNORE :

Same effect as the -i option.

.PRECIOUS : tgt ...

The specified targets are not removed when an interrupt character (typically, <CTRL-C>) is typed.

.SILENT :

Same effect as the -s option.

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.

.DEPENDENCY_IGNORED_FOR_REUSE: file ...

The dependencies you specify are ignored when clearmake determines whether a target object in a VOB is up to date and can be reused. By default, clearmake considers that a target cannot be reused if its dependencies have been modified or deleted since it was built. This target applies only to reuse, not to winkin. Also, this target applies only to detected dependencies, which are not declared explicitly in the makefile.

You can specify the list of files with a tail-matching pattern; for example, %.module.

Unlike the files listed in most special targets, the files on this list refer to the names of dependencies and not the names of targets. As such, the special target may apply to the dependencies of many targets at once. This special target is most useful when identifying a class of dependencies found in a particular toolset for which common behavior is desired across all targets that have that dependency.

.INCREMENTAL_REPOSITORY_SIBLING: file ...

The sibling files listed are incremental repository files created as siblings of a primary target, may contain incomplete configuration information, and prevent clearmake from winking in the primary target. This special target is useful for situations where a toolset creates an incremental sibling object, and you want more control over how that object is used.

You can specify the list of files with a tail-matching pattern; for example, %.pdb.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target may apply to the siblings of many targets at once. This special target is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.INCREMENTAL_TARGET: tgt ...

Performs incremental configuration record merging for the listed targets; in other words, combines dependency information from instances of this target generated previously with the current build of this target. This special target is most useful when building libraries, because typically only some of the objects going into a library are read each time the library is updated.

You can specify the list of files with a tail-matching pattern; for example, %.lib.

For information on restructuring a makefile to build incremental archive files, see Working with Incremental Update Tools.

NOTE: .INCREMENTAL_TARGET applies only to makefile targets built incrementally using a single make rule. Do not use it for the following kinds of files:

Files built incrementally that are not makefile targets. For example, sibling objects like log files or template repositories.

Files built incrementally from several different build scripts.

The general guideline is that if you're not building a library in a single makefile rule, and you're not building an executable using an incremental linker, you should not use .INCREMENTAL_TARGET.

.JAVA_TGTS: file ...

This special target is used to handle sub-classes generated by Java compilers.

In the makefile, any file name that matches the pattern will allow a $ to be escaped by a another $. For example, to specify a $foo.class:

You can specify the list of files with a tail-matching pattern; for example, %.class

.java.class:
javac $<
a$$foo.class: a.class

Note that $$ mapping to a single $ is default behavior in Gnu make compatibility mode. For more information, see the makefile_gnu reference page.

.MAKEFILES_IN_CONFIG_REC: file ...

Use this special target to record the versions of makefiles in the configuration records of derived objects.

This target takes an optional dependency list which may be a pattern. When used without a dependency list, this target causes all makefiles read by a build session to be recorded in the configuration record of all derived objects built during that build session.

To conserve disk space, you may want to supply a dependency list to this target so that, for example, only DOs built for top-level targets have the makefiles recorded in their configuration records.

.MAKEFILES_AFFECT_REUSE:

By default, makefiles recorded by using the .MAKEFILES_IN_CONFIG_REC special target do not affect DO reuse. You can use this target to enable recorded makefiles to affect DO reusability. (If you want to have some recorded makefiles affect reusability, but not all, you can also use the .DEPENDENCY_IGNORED_FOR_REUSE special target in conjunction with this target.)

NOTE: If a makefile is declared an explicit dependency of a target, then it always affects DO reuse for that target, whether .MAKEFILES_AFFECT_REUSE was used or not.

Makefiles recorded in a configuration record are labeled by mklabel -config. Makefiles that were recorded in a configuration record but that were not recorded by using .MAKEFILES_AFFECT_REUSE are ignored by catcr -critical_only and diffcr -critical_only.

.NO_CMP_NON_MF_DEPS: tgt ...

The specified targets are built as if the -M option were specified; if a dependency is not declared in the makefile, it is not used in configuration lookup.

You can specify the list of files with a tail-matching pattern; for example, %.obj.

.NO_CMP_SCRIPT : tgt ...

The specified targets are built as if the -O option were specified; build scripts are not compared during configuration lookup. This is useful when different makefiles (and, hence, different build scripts) are regularly used to build the same target.

You can specify the list of files with a tail-matching pattern; for example, %.obj.

.NO_CONFIG_REC : tgt ...

The specified targets are built as if the -F option were specified; modification time is used for build avoidance, and no CRs or derived objects are created.

You can specify the list of files with a tail-matching pattern; for example, %.obj.

.NO_DO_FOR_SIBLING : file ...

Disables the creation of a derived object for any file listed if that file is created as a sibling derived object (an object created by the same build rule that created the target). These sibling derived objects are left as view-private files.

You can specify the list of files with a tail-matching pattern; for example, %.tmp.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target may apply to the siblings of many targets at once. This special target is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.NO_WINK_IN : tgt ...

The specified targets are built as if the -V option were specified; configuration lookup is restricted to the current view.

You can specify the list of files with a tail-matching pattern; for example, %.obj.

.NOTPARALLEL : tgt ...

Without any tgt arguments, disables parallel building for the current makefile. clearmake builds the entire makefile serially, one target at a time. With a set of tgt arguments, prevents clearmake from building any of the targets in the set in parallel with each other. However, targets in a set can be built in parallel with targets in a different set or with any other targets. For example:

.NOTPARALLEL:%.a
.NOTPARALLEL:acc1 acc2

clearmake does not build any .a file in parallel with any other .a file, and acc1 is not built in parallel with acc2. However, clearmake may build .a files in parallel with acc1 or acc2.

.NOTPARALLEL does not affect lower-level builds in a recursive make, unless you specify it in the makefiles for those builds or include it in a BOS file.

You can specify the list of files with a tail-matching pattern; for example, %.a.

See also Chapter 9, Setting Up a Parallel Build.

.SIBLING_IGNORED_FOR_REUSE: file ...

The files are ignored when clearmake determines whether a target object in a VOB is up to date and can be reused. This is the default behavior, but this special target can be useful in conjunction with the .SIBLINGS_AFFECT_REUSE special target or -R command-line option. This target applies only to reuse, not to winkin.

You can specify the list of files with a tail-matching pattern; for example, %.sbr.

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not the names of targets. As such, the special target may apply to the siblings of many targets at once. This directive is most useful when identifying a class of siblings found in a particular toolset for which common behavior is desired across all targets that have that sibling.

.SIBLINGS_AFFECT_REUSE:

Build as if the -R command line option were specified; examine sibling derived objects when determining whether a target object in a VOB can be reused (is up to date). By default, when determining whether a target is up to date, clearmake ignores modifications to objects created by the same build rule that created the target (sibling derived objects). This directive tells clearmake to consider a target out of date if its siblings have been modified or deleted.