makefile_gnu

clearmake compatibility with GNU make

Applicability

Product

Command type

VersionVault

data structure

Platform

UNIX

Linux

Windows

Synopsis

clearmake –C gnu

Description

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

The clearmake program has been designed for compatibility with existing make programs, minimizing the work necessary to switch to clearmake. There are many independently evolving variants of make, which provide different sets of extended features. clearmake does not support all features of all variants, and absolute compatibility is not guaranteed. If your makefiles use only the common extensions, they will probably work with clearmake.

Note: When building with configuration records, clearmake handles double-colon rules differently from other make programs. For details, see the VersionVault Guide to Building Software.

VPATH separator character

As separators in the VPATH macro you can use spaces, colons (UNIX and Linux), or semicolons (Windows). For more information, see the makefile_ccase reference page.

Windows: Using Linux and UNIX system command shells in your makefile

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

Windows: Overriding the escape character

To override the escape character (\), set CCASE_NO_ESC_PATT_CHARS. When this environment variable is set, the character that follows \ is not treated literally (see env_ccase).

Compatibility

clearmake provides partial compatibility with GNU make. This section provides the details.

Supported GNU make command options

clearmake –C gnu supports most of the single-character and long-form spellings of GNU make command options, as follows:

–b
Considers siblings when determining whether to rebuild or reuse.
– –directory=dir
Change to the specified directory before reading the makefiles.
–d – –debug
Prints debugging information in addition to normal processing messages.
–e – –environment-override
Gives variables taken from the environment precedence over variables from makefiles.
–f file – –file=file – –makefile=file
Reads file as a makefile.
–I dir
Specifies a directory dir to search for included makefiles (this is equivalent to –include-dir.
–i – –ignore-errors
Ignores all errors in commands executed to remake files.
– –include-dir=dir
Specifies a directory in which to search for included makefiles (this is equivalent to –I
–k – –keep-going
Continues as much as possible after an error.
– –no-builtin-variables
Eliminate use of built-in, rule-specific variables.
– –-no-print-directory
Disables printing of the working directory under –w.
–n – –just-print – –dry-run – –-recon
Prints the commands that would be executed, but does not execute them.
–p – –print-data-base
Prints the database (rules and variable values) that results from reading the makefiles, then executes as usual or as otherwise specified.
–q – –question
Question mode. Does not run any commands or print anything. Returns an exit status of 0 if the specified targets are already up to date, or 1 if any remaking is required.
–r – –no-builtin-rules
Eliminates use of the built-in implicit rules.
–s – –silent – –quiet
Silent operation. Does not print the commands as they are executed.
– –warn-undefined-variables
Issues a warning whenever a reference to an undefined variable is found. Null warnings for VPATH and SHELL are suppressed by default; null warnings for these can be displayed using the clearmake options –v or –d.
–w – –print-directory
Prints a message containing the working directory both before and after executing the makefile.

Unsupported GNU make command-line options

The following options are not supported:

  • -m
  • -C dir
  • -h --help
  • -j [jobs] --jobs[=jobs]
  • -l [load] --load-average[=load] --max-load[=load]
  • -o file --old-file=file --assume-old=file
  • -R (this is supported as –b)
  • -S --no-keep-going --stop
  • -t --touch
  • -v --version
  • -W file --what-if=file --new-file=file --assume-new=file

Supported GNU make features

The following features are enabled with –C gnu (see the GNU make documentation):

  • Conditional makefile interpretation; for example,

    ifeq ($(CC),gcc)
            $(CC) -o foo $(objects) $(libs_for_gcc)
    else
            $(CC) -o foo $(objects) $(normal_libs)
    endif

  • Conditional expansion:

    $(if condition, then-part [,else-part])
    $(or condition1[,condition2[,condition3...]])
    $(and condition1[,condition2[,condition3...]])

  • Order-only prerequisites:

    targets : normal-prerequisites | order-only-prerequisites

    Note: clearmake does not recognize the distinction between normal and order-only prerequisites when they are specified as two different paths that have the same leaf name; for example,
     target1 : dir1/prereq1 | dir2/prereq1
  • Creating parameterized functions:

    $(call variable,parameter,parameter,...)

    Note: With clearmake, $(call) does not support the recursive definition of a macro, as in this example, where Macro2 is using itself for its definition:

    Var1 = Val1
    Macro1 = $(1) $(2)
    Macro2= $(call  macro1, $(Var1),$(Macro2))  macro "Macro2"

  • Simply expanded variables in which the RHS is expanded once when the assignment is first scanned. For example:

    y := $(x) bar

  • The += syntax to append to the value of a variable.
  • The ?= macro operator.
  • The use of $$ in target names as an equivalent to a literal $.
  • Special characters ()<>;!=&|$#:"{}\ (UNIX and Linux) or ()<>;!=&|$#:" (Windows) within macro names
  • Escaping special characters in target names by preceding them with a \. Note that the escaping must be consistent within the makefile. For example,

    test: test#footest\#foo:
    echo $@test: test#footest\#foo:
    echo $@

    generates a Don't know how to make error.

  • Stripping leading sequences of ./ (UNIX and Linux) or .\ (Windows) from file names, so that (for example) .\file and file are considered the same target
  • Variable references using pattern substitution:

    ${VAR:PATTERN_1=PATTERN_2}

  • Text-manipulation functions:

    $(subst FROM,TO,TEXT)
    $(patsubst PATTERN,REPLACEMENT,TEXT)
    $(strip STRING)
    $(findstring FIND,IN)
    $(filter PATTERN...,TEXT)
    $(filter-out PATTERN...,TEXT)
    $(sort LIST)
    $(dir NAMES...)
    $(notdir NAMES...)
    $(suffix NAMES...)
    $(basename NAMES...)
    $(addsuffix SUFFIX,NAMES...)
    $(addprefix PREFIX,NAMES...)
    $(join LIST1,LIST2)
    $(word N,TEXT)
    $(words TEXT)
    $(wordlist START, END, TEXT)
    $(firstword NAMES...)
    $(wildcard PATTERN)
    $(foreach VAR,LIST,TEXT)
    $(origin VARIABLE)
    $(shell COMMAND)
    $(value variable)
    $(warning text)
    $(error text)
    $(eval argument)
    $(file op filename[,text])

    Notes:
    • If $(eval argument) appears on the right-hand side of a macro that is evaluated at run-time, the results are not guaranteed. This is due to the fact that clearmake distinguishes between the parsing phase and the run-time phase. Consequently, the argument cannot be reliably parsed at run-time.
    • The $(file op filename[,text]) file function allows a build script to overwrite, append, or read a file without using shell redirection.
  • The VPATH variable for specifying a search path for every dependency.
    Note: clearmake searches only in the current view. For more information, see the makefile_ccase reference page.
  • The MAKECMDGOALS variable for specifying the targets given on the command line.
  • The vpath statement for specifying a search path for a specified class of names.
  • The export statement.
  • The unexport directive.
  • The .PHONY target declaration.
  • All of GNU make's built-in implicit rules.
  • Pattern rules. For example:

    %.o : %.c
        COMMANDS
        ...

  • Static pattern rules:

    TARGETS ...: TARGET-PATTERN: DEP-PATTERNS ...
        COMMANDS
        ...

  • The automatic variables:

    $@  $*  $<  $%  $?  $^  $+ 

    Also, their file name and directory-name variants. For example:

    $(@F)  $(@D)  ...

  • Multiline variable definition:

    define VAR
        TEXT
        ...
    endef

  • Target-specific variable values:

    target ... : variable-assignment

    or

    target ... : override variable-assignment

  • .VARIABLES

    Expands to a list of the names of all global variables defined so far. This includes variables which have empty values, as well as built-in variables, but does not include any variables which are only defined in a target-specific context. Note that any value you assign to this variable will be ignored; it will always return its special value.

  • .LIBPATTERNS

    Defines the naming of the libraries that to be searched for, and their order.

  • MAKEOVERRIDES

    Refer to GNU make documentation for information about MAKEOVERRIDES.

Unsupported GNU make features

The following features are not supported:

  • Wildcards in a dependency specification when any of the dependency names include embedded space characters.
  • Automatic remaking of any makefiles that are declared as targets (you must explicitly rebuild them).
  • The declarations .DELETE_ON_ERROR, .INTERMEDIATE, .SECONDARY.
  • Automatic makefile regeneration and restart if the makefile and included makefile fragments are targets in the makefile itself.
  • Automatic deletion of intermediate results of a chain of implicit-rules.
  • Special search method for library dependencies written in the form -lNAME. For each directory on the VPATH/vpath list, GNU make searches in DIR/lib .
  • When MAKEFILES is defined, GNU make considers its value as a list of names of additional makefiles to be read before the others, as though they were implicitly included.