makefile_ccase

makefiles processed by clearmake

Applicability

Product

Command type

VersionVault

general information

Platform

UNIX

Linux

Windows

Description

(Defined only when explicit rules from the makefile are evaluated) The list of dependencies that are out of date with respect to the target. When configuration lookup is enabled (default), it expands to the list of all dependencies, unless that behavior is modified with the .INCREMENTAL_TARGET special target. In that case, $? expands to the list of all dependencies different from the previously recorded versions.

Note: The distinctive features of clearmake, such as build auditing, derived object sharing, and build avoidance, are supported in dynamic views only.

A makefile contains a sequence of entries, each of which specifies a build target, some dependencies, and the build scripts of commands to be executed. A makefile can also contain make macro definitions, target-dependent macro definitions, and build directives (special targets.)

  • Target/dependencies line. The first line of an entry is a white-space-separated, non-null list of targets, followed by a colon (:) or a double colon (::), and a (possibly empty) list of dependencies. Both targets and dependencies may contain VersionVault path name patterns. (See the wildcards_ccase reference page.)

    The list of dependencies may not need to include source objects, such as header files, because clearmake detects these dependencies. However, the list must include build-order dependencies, for example, object modules and libraries that must be built before executables.

  • Build script. Text following a semicolon (;) on the same line, and all subsequent lines that begin with a <TAB> character, constitute a build script: a set of commands to be executed in a shell (UNIX and Linux) or command interpreter (Windows). A command can be continued onto the next text line with a \<NL> sequence. Any line beginning with a number sign (#) is a comment.

    A build script ends at the first nonempty line that does not begin with a <TAB> or number sign (#); this begins a new target/dependencies line or a make macro definition.

    Build scripts must use standard path names only. Do not include view-extended or version-extended path names in a build script.

    Executing a build script updates the target and is called a target rebuild. The commands in a build script are executed one at a time, each in its own instances of the subshell or command interpreter.

    clearmake always completely eliminates a \<NL> sequence, even in its compatibility modes. Some other make programs sometimes preserve such a sequence—for example, in a UNIX and Linux sed(1) insert command:

    target: depdcy
    sed -e '/xxx=0/i\
    yyy=xxx;' depdcy > target

  • Make macro. A make macro is an assignment of a character-string value to a simple name. By convention, all letters in the name are uppercase (for example, CFLAGS).
  • Target-dependent macro definitions. A target-dependent macro definition takes the form target-list := macro_name = string

    You can use macros in makefiles or in BOS files. For more information, see BOS file entries.

  • Special targets. A line that begins with a dot (.) is a special target, which acts as a directive to clearmake.

Build options specification files

A build options specification (BOS) file is a text file that contains macro definitions and/or VersionVault special targets. You can place temporary macros (such as CFLAGS=–g (UNIX and Linux) and CFLAGS=/Zi (Windows) ) into a BOS file rather than specifying them on the clearmake command line.

By default, clearmake reads BOS files in this order:

  1. The default BOS files
    1. The file .clearmake.options in your home directory as indicated in the password database (UNIX and Linux) or by the HOME environment variable or in the user profile (Windows). This is the place for macros to be used every time you execute clearmake.
    2. One or more local BOS files, each of which corresponds to one of the makefiles specified with a –f option or read by clearmake. Each BOS file has a name in the form makefile-name.options. For example:
      • makefile.options
      • Makefile.options
      • project.mk.options
  2. BOS files specified in the CCASE_OPTS_SPECS environment variable.
  3. BOS files specified on the command line with –A.

If you specify –N, clearmake does not read default BOS files.

clearmake displays the names of the BOS files it reads if you specify the –v or –d option, or if CCASE_VERBOSITY is set to 1.

For information about the contents of BOS files, see BOS file entries.

Format of makefiles

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

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 and Linux), 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.

  • For example, on UNIX or Linux:

    lib.a : lib.a(mod1.o) lib.a(mod2.o)

    Thus, lib.a(mod1.o) refers to an archive that contains object module mod1.o. The expression lib.a(mod1.o mod2.o) is not valid.

  • Similarly, on Windows:

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

    hello.lib(mod1.obj) refers to an archive that contains mod1.obj. The expression hello.lib(mod1.obj mod2.obj) is not valid.

Inference rules for archive libraries have the form

  • UNIX and Linux: .sfx.a
  • Windows: .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.

Note: On UNIX and Linux, the u key for ar is not reliable within a VersionVault 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:

Causes clearmake to ignore any errors during execution of the command. By default, an error causes clearmake to terminate.

The command-line option –i suppresses termination-on-error for all command lines.

@

Suppresses display of the command line. By default, clearmake displays each command line just before executing it.

The command-line option –s suppresses display of all command lines. The –n option displays commands, but does not execute them.

–@    @–

These two prefixes combine the effect of    and @.

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:

  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.

For a list of build-related environment variables, see the VersionVault Guide to Building Software.

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, on UNIX or Linux:

cat Makefile
C_SOURCES = one.c two.c three.c four.c
test:
     echo "OBJECT FILES are: $(C_SOURCES:.c=.o)"
     echo "EXECUTABLES are: $(C_SOURCES:.c=)"

clearmake test
OBJECT FILES are: one.o two.o three.o four.o
EXECUTABLES are: one two three four

And on Windows:

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

Note: Files have different file extension naming conventions in Windows, Linux, and UNIX: .obj for Windows and .o for UNIX and Linux. 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.

$*

(Defined only for inference rules) The file name part of the inferred dependency, with the file name extension deleted.

$@

The full target name of the current target.

$<

(Defined only for inference rules) The file name of the implicit dependency.

$?

(Defined only when explicit rules from the makefile are evaluated) The list of dependencies that are out of date with respect to the target. When configuration lookup is enabled (default), it expands to the list of all dependencies, unless that behavior is modified with the .INCREMENTAL_TARGET special target. In that case, $? expands to the list of all dependencies different from the previously recorded versions.

When a dependency is an archive library member of the form lib(file.o), the name of the member, file.o, appears in the list.

$%

(Defined only when the target is an archive library member) For a target of the form lib(file.o), $@ evaluates to lib and $% evaluates to the library member, file.o.

MAKE

The name of the make processor (that is, clearmake). This macro is useful for recursive invocation of clearmake.

MAKEFILE

During makefile parsing, this macro expands to the path name of the current makefile. After makefile parsing is complete, it expands to the path name of the last makefile that was parsed. This holds only for top-level makefiles, not for included makefiles or for built-in rules; in these cases, it echoes the name of the including makefile.

Use this macro as an explicit dependency to include the version of the makefile in the CR produced by a target rebuild.

On UNIX or Linux:

supersort: main.o sort.o cmd.o $(MAKEFILE)
  cc -o supersort ...

On Windows:

supersort: main.obj sort.obj cmd.obj $(MAKEFILE))
  link /out:$@ $?

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 path name or a list of directory path names separated by colons (UNIX and Linux) 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 path name 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:

Name

Matches

Does not match

(UNIX and Linux)

/dir/subdir/x.o

%.o

x.o

subdir/%.o

subdir/x.o

/dir/subdir/otherdir/x.o

(Windows)

\dir\subdir\x.obj

%.obj

x.obj

subdir\%.obj

subdir\x.obj

\dir\subdir\otherdir\x.obj

The following targets accept lists of patterns:

  • .DEPENDENCY_IGNORED_FOR_REUSE
  • .DIRECTORY_AFFECTS_REUSE
  • .DIRECTORY_IGNORED_FOR_REUSE
  • .INCREMENTAL_REPOSITORY_SIBLING
  • .INCREMENTAL_TARGET
  • .JAVA_TGTS
  • .MAKEFILES_IN_CONFIG_REC
  • .NO_CMP_NON_MF_DEPS
  • .NO_CMP_SCRIPT
  • .NO_CONFIG_MATCH_SLINKS
  • .NO_CONFIG_REC
  • .NO_DO_FOR_SIBLING
  • .NO_WINK_IN
  • .SIBLING_IGNORED_FOR_REUSE
  • .ONESHELL

Special targets for use in makefiles

You can use the following special targets in the makefile.

.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 (also on UNIX and Linux, a quit character, which is typically Ctrl+\).
.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, Templates.DB/%.module (UNIX and Linux) or %.module (Windows).

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.

.DIRECTORY_AFFECTS_REUSE: tgt ...
This special target can be used to specify a declared directory dependency for reuse. It overrides both the .DIRECTORY_IGNORED_FOR_REUSE special target and the CCASE_DIR_IGNORED_REUSE environment variable.

This target takes one or more (white-space-separated) directory path names. You can specify the path names with a %tail-matching pattern.

.DIRECTORY_IGNORED_FOR_REUSE: tgt ...
clearmake notes directories for reuse that are recorded in a config record as dependencies. This target can be used to selectively override a declared directory dependency.

This target takes one or more (white-space-separated) directory path names. You can specify the path names with a %tail-matching pattern.

This special target has an equivalent environment variable called CCASE_DIR_IGNORED_REUSE, which takes no arguments, but is either on or off. If on, this environment variable overrides the build avoidance treatment of all declared directory dependencies.

.INCREMENTAL_REPOSITORY_SIBLING: file ...
The specified files are incremental repository files created as siblings of a primary target and may contain incomplete configuration information. This special target is useful in situations where a toolset creates an incremental sibling object and you want to prevent clearmake from winking in a primary target that has this sibling. If you have an incremental sibling and do not use .INCREMENTAL_REPOSITORY_SIBLING, you could inadvertantly wink it in; this could be a serious problem if the sibling overwrites your view's version of that sibling.

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 library archives, 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, %.a or %.lib.

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, then you should not use .INCREMENTAL_TARGET.

.JAVA_TGTS: file ...
This special target is used to handle subclasses generated by Java compilers.

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

.JAVA_TGTS: %.class
.java.class:
javac $<
a$$x.class: a.class

Note that $$ mapping to a single $ is default behavior in Gnu make compatibility mode.

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

.JAVAC:

Use this special target to enable clearmake to use heuristics on audits of Java builds to accurately evaluate .class dependencies. These dependencies are then stored in .class.dep files for future clearmake runs, and they enable those runs to build .class targets in the same order that the Java compiler does.

This special target must be used with no dependencies and no build script:

JAVAC:

Other than that, makefiles must use implicit suffix or pattern rules. For example:

.SUFFIXES: .java .class .java.class:        

rm -f $@        

$(JAVAC) $(JFLAGS) $<

For compatibility modes that support them, use implicit pattern rules. For example:

%.class: %.java         

rm -f $@         

$(JAVAC) $(JFLAGS) $?  

The makefiles must also use absolute paths for .class targets. Clearmake contains a built-in macro function you can use to specify absolute paths:

$(javaclasses)

.MAKEFILES_AFFECT_REUSE:

By default, makefiles recorded by using the .MAKEFILES_IN_CONFIG_REC special target do not affect DO reuse. You can use the .MAKEFILES_AFFECT_REUSE target to enable recorded makefiles to affect DO reuse. (If you want to have some recorded makefiles affect reuse, 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, it always affects DO reuse for that target, whether or not .MAKEFILES_AFFECT_REUSE was used.

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

.MAKEFILES_IN_CONFIG_REC: file ...

You can 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 might 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.

.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, %.o.

.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, %.o.

.NO_CONFIG_MATCH_SLINKS: tgt ...
When used, this target specifies that clearmake does not attempt to apply CR-based build-avoidance to a target file when it is a symbolic link, but uses time stamps, if applicable.

This special target takes one or more (white-space-separated) target path names. You can specify the path names with a %tail-matching pattern.

.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, %.o.

.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, ptrepository/_% (UNIX and Linux) or %.tmp (Windows).

Unlike the files listed in most special targets, the files on this list refer to the names of sibling objects and not to 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_SIBLING_DO_CONTAINED_IN : dir ...

This special target suppresses the creation of derived object for any file that lives in or beneath a specified directory. For example, if the makefile has the following targets:

.NO_SIBLING_DO_CONTAINED_IN: sun5/%  
objs/sun5/a.o: src/a.c    
cc -o $@ -c $<  

objs/sun5/subdir/a2.o: src/a2.c    
cc -o $@ -c $<  

objs/b.o: src/b.c    
cc  -o $@ -c $<  

then the written files named a.o and a2.o do not become DOs, but the file b.o does.

If a makefile contains the following:

.NO_SIBLING_DO_CONTAINED_IN: subdir%    

all: subdir1/T1 subdir2/T2  

subdir1/T1:          
touch $@          
touch $@.sibling  

subdir2/T2:        
touch $@        
touch $@.sibling

then subdir1/T1 and subdir2/T2 become derived objects, but subdir1/T1.sibling and subdir2/T2.sibling do not.

This target takes one or more (white space-separated) directory path names. You can specify the path names with a %tail-matching pattern.

.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, %.o.

.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, Templates.DB/%.module (UNIX and Linux) or %.sbr (Windows).

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.
.ONESHELL
The .ONESHELL special target is available only in the GNU compatibility mode, which tries to emulate the .ONESHELL special target available in GNU make 4.2 and later.

When .ONESHELL is available anywhere in the makefile, all lines of the build script are executed in a single invocation of the shell, whereas in the traditional make paradigm, each line of the build script is executed under a separate shell process. Only the leading special character (@, -, +) in the first line of the build script is considered. If the shell is identified as a POSIX shell, leading special characters in subsequent lines (lines other than the first line) are removed from the build script before processing. For more information, see Using One Shell.

Target for UNIX and Linux only

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

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

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

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

Using makefiles in snapshot views on UNIX or Linux

Because snapshot views do not make use of the MVFS, absolute VOB path names (for example, /vobs/tools/foo.h) are not supported in snapshot views on UNIX or Linux. For that reason, your makefiles must not include absolute VOB path names.

To eliminate absolute VOB path names from makefiles, use the pwv –root command to get the value of the current view-root directory. Use that value in one of the following methods:

  • Pass the context-dependent view root to the makefile from an external definition (for example, with Imake).
  • Define the context-dependent view root in the makefile. For example:

    VWROOT=‘cleartool pwv -root‘
    TOOLS=$(VWROOT)/vobs/tools

    The method shown in this example works for any clearmake compatibility mode. There are also methods specific to each compatibility mode. See your make documentation for more information.

Sharing makefiles between Windows and UNIX or Linux

clearmake is available on both Windows and UNIX or Linux. In principle, you can write portable makefiles, but in practice, the obstacles are substantial. The variations in tool and argument names between systems makes writing portable build scripts particularly challenging. If you choose to pursue portable makefiles, use the following general procedures to produce usable results:

  • Start on UNIX or Linux; avoid most compatibility modes. Windows clearmake supports Gnu compatibility mode but does not support others (for example, Sun compatibility mode). Instead, it supports basic make syntax. To write or tailor transportable makefiles, begin makefile development on UNIX or Linux, without compatibility modes other than Gnu in effect. Gnu generates errors and warnings for problematic syntax. When things work cleanly on UNIX or Linux, move your makefiles to Windows for testing.
  • Use a makefile-generating utility, such as imake, to generate makefiles. Use imake or some other utility to generate the makefiles you will need, including clearmake makefiles for Windows.

Using makefiles on Windows

There are several rules to follow when constructing, or converting, makefiles for use by clearmake on a Windows host. Note that, as a general rule, your makefiles must match the syntax required by clearmake on UNIX or Linux.

The following sections describe how you must specify build macros, targets, and dependencies in makefiles to avoid case problems.

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:

  • From the makefile itself
  • From the current table of environment variables
  • From the command line
  • From a build option specification (BOS) file

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 path names

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 path names in makefiles to guarantee the consistency of the resulting config records. Even if your MVFS is not case-preserving, use case-correct path names 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 path names in the makefile and on the file system.

The following table describes makefile requirements for the different MVFS settings.

Table 1. MVFS settings and case requirements for makefiles

MVFS setting

Build tool and MVFS behavior

Makefile requirements

Case-insensitive and case preserving

The MVFS preserves the case of created files. The build tool looks for the file as it is specified in the makefile.

The case of the target must match the case of the file produced by the MVFS.

Case-insensitive and non-case-preserving

The MVFS converts the names of all files created to lowercase. The build tool looks for a lowercase file name.

The case of the target does not matter.

Case-sensitive and case-preserving

The MVFS preserves the case of created files. The build tool looks for the file as it is specified in the makefile.

The case of the target must match the case of the file produced by the MVFS.

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:

  • %HOME%\.clearmake.options
  • makefile.options, in the same directory as makefile (substitute the actual name of your makefile, if it is not makefile)

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

Using Linux and UNIX system command shells in makefiles

On Windows, clearmake accepts either slashes ( / ) or backslashes ( \) in path names. However, clearmake uses a backslash as the separator in any path names 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 path names 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 path names. To do this, set the CMAKE_PNAME_SEP variable:

CMAKE_PNAME_SEP = /

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

BOS file entries

The following sections describe the entries you can put in BOS files.

Standard macro definitions

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

macro_name = string

For example, on UNIX or Linux:

CDEBUGFLAGS = -g

and on Windows:

CDEBUGFLAGS = /Zi

Target-dependent macro definitions

A target-dependent macro definition takes this form:

target-pattern-list := macro_name = string

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 or Linux:

foo.o bar.o := CDEBUGFLAGS=-g

On Windows:

foo.o bar.o := CDEBUGFLAGS=/Zi

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:

macro_name :sh = string

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 or Linux:

BUILD_DATE :sh = date

On Windows:

NT_VER :sh = VER

Special targets

You can use some VersionVault 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 or Linux:

include /usr/local/lib/ux.optionss
include $(OPTS_DIR)/pm_build.options

On Windows:

include \lib\aux.options
sinclude $(OPTS_DIR)\pm_build.options

Comments

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