3.5 Macros

A macro definition associates a name and a value. The macro expansion of a macro name returns the value. Macros are used at read time to organize names of files, compiler options, and so on. At run time, macros provide information about the current target being built.

Macro Modifiers

When a macro is referenced, the expanded value can be modified through the use of macro modifiers. To modify a macro, expand it with:

$(name,modifier[,modifier ...])

Everything between $( and ) is expanded, the value of name is expanded, and then each modifier is applied in succession to the expanded value. The separator between name and modifier can be a comma or colon, but subsequent modifiers must follow a comma. A literal comma is available by using \,. Some modifiers use regular expressions. The treatment of the backslash, can make it awkward to use a modifier when a backslash also terminates its argument. You can work around this by using two backslashes before a comma separator(\\,) or
if possible, move the awkward modifier to the end. If this not possible, use two modifications. For example,

OBJS = $(SRCS,<obj\,R,>.obj)

does not work, but this pair of macro definitions does:

OBJS = $(SRCS,<obj\)
OBJS := $(OBJS,R,>.obj)

Considering the macro value as a list of macro elements separated by white space, the first modifier is applied to all elements, then the next modifier is applied, and the next, and so on. The following list of modifiers is organized into functional groups. Examples of each modifier use the following macro definition:

SRCS = \src\main.c \sys\sub.cpp io.cpp

Filename Components

Absolute Pathname

Append and Prepend Strings

Change Case

Expand Pathnames

Include File

Include File with Regular Expression Matching

Member and Nonmember

Select a Particular Element

String Substitution

Sd regex d subst d

The substitution modifier. The d is a single-character delimiter that is neither in regular expression regex nor in substitution string subst and isn't a comma. If regex matches some part of a macro element, the matched part of the element is replaced with subst. The element is not changed if regex does not match it.

If regex is omitted, the last regular expression is reused. This is useful in combination with the member modifier, M. For example, given that CFLAGS has the value -AX -Ifoo -Ibar -DX=-IT:

$(CFLAGS,M^-I,S'^-I'') is foo bar
$(CFLAGS,M^-I,S''') is foo bar

The M modifier selects elements that start with -I, and the S operator substitutes the -I with nothing. This is quite different from

$(CFLAGS,S'^-I'') is -AX foo bar -DX=-IT

Notice how the elements unmatched by regex ^-I are not changed.

from=to

This modifier replaces occurrences of from string with to string. If from does not appear in a macro element, the element is not changed.

from and to can be simple strings or can use the percent sign (%) as a wildcard. If % is used, the search for from is anchored to the end of the element.

$(SRCS,%.c=%.obj) is \src\main.obj \sys\sub.cpp io.cpp
$(SRCS,.c=.obj) is \src\main.\sys\obj sub.cpp io.cpp

The use of % anchors the search for %.c so it matches main.c but not sub.cpp. The simple string substitution .c=.obj replaces any occurrence of .c with .obj so matches and changes sub.cpp to sub.objpp.

The delimiter between strings is the equal sign, but it is treated literally when prefixed with a backslash (\=). If fromString ends with a backslash, you must use two (\\=) to mean literal backslash followed by a delimiter. (Under PM/CB or NMAKE emulation, the delimiter is not quotable. This means that \= is taken literally, and there is no need to double the backslash).

For historical reasons, when fromString and toString are simple strings, this modifier operates on the entire macro value rather than on its elements, and can be used to replace the white space between elements. However, the W modifier is better suited for this task.

Tokenize

Wildcard Expand File and Directory Names

Regular Expressions

The M, N, and S modifiers use pattern-matching strings known as regular expressions. The regular expression (or regex) matches characters in strings, both literally and with wildcards, and the match is case-sensitive.

Configuring Regular Expressions

Two directives control the special characters that appear in regular expressions:

• .REGEX_CHAR sets the character used to indicate special character sequences. The default character is a backslash (\).

• .REGEX_WILD sets the wildcard character that matches any single character. The default character is a period ( . ).

The backslash and period are standard characters in UNIX-styled regular expressions, but are awkward to use in Windows NT because the backslash is the directory separator and the period is the file extension separator. The .REGEX_CHAR and .REGEX_WILD directives can be used to change these characters to some other characters.

The default characters are most problematic for the M and N modifiers when you are trying to match a file name. For this case, use the M"spec" and N"spec" modifiers because the spec is a file specification rather than a regular expression.

Regular Expressions for the M Modifier

Assume the following macro definitions:

SRCS = main.c sub.cpp io.cpp
CFLAGS = -AX -Ifoo -Ibar /Ibaz -DX=-IT xI.c yi.c

To select files whose names include .c:

$(SRCS,M\.c) is main.c sub.cpp

To select files that end in .c, the search can be anchored to the end with the regex character $. To get $ to the regular expression, you need to use $$ in the makefile:

$(SRCS,M\.c$$) is main.c

You can also select .c files with the M"spec" modifier:

$(SRCS,M"*.c") is main.c

Analogous to the $ anchor, the ^ regex character anchors the search to the front of the macro element:

$(CFLAGS,M-I) is -Ifoo -Ibar -DX=-IT
$(CFLAGS,M^-I) is -Ifoo -Ibar

The [set] regex characters indicate a set of characters, where the set can be single characters ([aA@] matches a, A or @), a range of characters ([a-z] matches a through z), or a mixture. For example:

$(CFLAGS,M^[-/]I) is -Ifoo -Ibar /Ibaz

Regular Expressions for the S Modifier

One powerful feature of regular expressions is that when used in substitutions, they can access the matched parts of the string. The down side of the more powerful regular expressions is that the expressions can be hard to read. For example, when DIR = NT_L, the expression $(DIR,S/\(.*\)_.*/\1/) is NT.

The \(, \) pair surround a part of the regular expression that is referenced later. Inside the pair is .*, which matches any character (.) repeated zero or more times (*). Taken together they instruct omake to match any character, zero or more times, and attach a tag to it. The rest of the regular expression is _ , which matches _, and .*, which matches any character repeated zero or more times.

The expression \1 is the stuff matched in the first pair of \( \), so the substitution evaluates to NT. Simple regular expressions are easy to read, but if you write more complicated expressions, be sure to provide thorough comments.

With Configuring .REGEX_CHAR and .REGEX_WILD

If omake is configured for alternative regular expression characters, the following directives appear in your make.ini:

.REGEX_CHAR : ~
.REGEX_WILD : ?

These examples are then easier to read:

$(SRCS,M.c) is main.c sub.cpp
$(SRCS,M.c$$) is main.c
$(CFLAGS,M-I) is -Ifoo -Ibar -DX=-IT
$(CFLAGS,M^-I) is -Ifoo -Ibar
$(CFLAGS,M^[-/]I) is -Ifoo -Ibar /Ibaz
$(DIR,S/~(?*~)_?*/~1/) is NT

Predefined and Built-In Macros

omake defines several macros before it reads the initialization file and makefiles. These macros come in two general types:

• Predefined macros cannot be changed or undefined. Important subsets of the predefined macros are run-time macros, which change with the target being built, and state macros, which hold the state of the command-line options and read-time directives.

• Built-in macros have the same precedence as normal makefile macros, and so can be redefined in your makefiles or on the command line.

Predefined Macros: Run-Time Macros

The run-time macros are changed dynamically by omake according to the current target being built. A key feature of the run-time macros is that their values are pathnames. A target's pathname is the location the target was found on disk. The run-time macros evaluate to pathnames, which is important for use on build scripts where the executed command needs the location of the targets.

All run-time macros have names of the form .name, and several have one- or two-letter aliases that you are likely to see in makefiles of other make utilities.

Run-Time Macros

.NEWSOURCES (alias is ?)

This run-time macro evaluates to the pathnames of all dependencies newer than the current target. When configuration lookup is enabled, it evaluates to the pathnames of all dependencies for the current target, unless that behavior is modified with the .INCREMENTAL_TARGET directive (see the description in the section Dot Directives), in which case it evaluates to the pathnames of all dependencies different from the previously recorded versions.

.SOURCE (alias is <)

This run-time macro evaluates to the pathname of the inferred dependency that satisfied the inference rule, or the pathname of the first explicit dependency if no inferred dependency was found. Here is a sample inference rule for updating an object file with the Borland C compiler:

%.obj : %.c
cl -c $(.SOURCE)

Using an alias, the second line becomes

cl -c $<

.SOURCES (aliases are ^ or **)

This run-time macro evaluates to the pathnames of all dependencies of the current target. Here is an example that updates an executable with all object files that are its dependencies:

project.exe : main.obj io.obj
link /out :$(.TARGET), $(.SOURCES);

Using an alias, the second line becomes

link /out : $@, $**;

NOTE: The ** macro is the exception to the rule that multicharacter macros need parentheses or braces around them. The expression $** is the same as $(**).

.TARGET (alias is @)

This run-time macro evaluates to the pathname of the target currently being made. For example:

%.obj : %.c
cl -o$(.TARGET) -c $(.SOURCE)

Using an alias, the second line becomes

cl -o$@ -c $<

This macro can also be used at read time on a dependency line and its value is the name of the target currently getting dependencies. For example:

main.obj io.obj : $(.TARGET,R).c io.h

Using an alias, the line becomes

main.obj io.obj : $(@,R).c io.h

The .TARGET macro value is set to the name of each target, in turn. The dependencies are then macro-expanded and added to the target's list of dependencies. The R macro modifier selects the root of the target name. The above dependency line is equivalent to the two lines:

main.obj : main.c io.h
io.obj : io.c io.h

For compatibility with other Make utilities. omake treats $$@ on the dependency side of a dependency line just like $(.TARGET).

.TARGETROOT (alias is *)

This run-time macro evaluates to the pathname of the target currently being made, minus its extension. This macro can also be used at read time on the dependency side of a dependency line. Here is the read-time example from the .TARGET macro rewritten using this macro:

main.obj io.obj : $(.TARGETROOT).c io.h

Using an alias, the line becomes

main.obj io.obj : $*.c io.h

Predefined Macros: General Macros

The predefined macros in Table 3 give you information about the current make process. One of the most important predefined macros is the status macro at the bottom of the table.

Predefined Macros: State Macros

The state macros provide information about the state of command-line options and read-time directives. Most command-line options have an equivalent directive, and the value of the state macro is the same regardless of whether the option or directive was used.

In the list of macros in Table 4, the macro values that are the state of a directive or command-line option mean the value is 1 if the directive or command-line option was used; otherwise the value is 0.

NOTE: In terms of implementation, .ALWAYS, .IGNORE, and .SILENT are not directives; they are target attributes. They look like directives when they appear in a makefile on the target side of a dependency line when there are no dependencies. For example,

.IGNORE :

sets the .IGNORE attribute for every target created after the appearance of this line. The .ALWAYS, .IGNORE, and .SILENT macros have the correct value, as if these attributes were directives.

NOTE: Exactly one of $(.MS_NMAKE), $(.omake) or $(.POLY_MAKE) is 1.

An Example Use of the State Macros

Here is an example of how these macros can be used. Suppose you want to debug the contents of your makefile with the -#1 command-line option. However, this also produces output that comes from your make.ini file, which probably doesn't need debugging. Modify your make.ini file with the following:

Built-in Macros

omake defines the built-in macros with a default value, but they have the same precedence as normal makefile macros, so you can be redefine them.

Compatibility with Other Make Utilities

Through emulation, omake supports all PM/CB and NMAKE macros.