DMAKE(p) Unsupported Free Software DMAKE(p)NAMEdmake - maintain program groups, or interdependent files
SYNOPSISdmake [-P#] [-{f|C|K} file] [-{w|W} target ...]
[macro[[!][*][+][:]]=value ...] [-v{cdfimtw}]
[-ABcdeEghiknpqrsStTuVxX] [target ...]
DESCRIPTIONdmake is a re-implementation of the UNIX Make utility with
significant enhancements. dmake executes commands found
in an external file called a makefile to update one or
more target names. Each target may depend on zero or more
prerequisite targets. If any of the target's prerequi-
sites is newer than the target or if the target itself
does not exist, then dmake will attempt to make the tar-
get.
If no -f command line option is present then dmake
searches for an existing makefile from the list of prereq-
uisites specified for the special target .MAKEFILES (see
the STARTUP section for more details). If "-" is the name
of the file specified to the -f flag then dmake uses stan-
dard input as the source of the makefile text.
Any macro definitions (arguments with embedded "=" signs)
that appear on the command line are processed first and
supercede definitions for macros of the same name found
within the makefile. In general it is impossible for def-
initions found inside the makefile to redefine a macro
defined on the command line, see the MACROS section for
exceptions.
If no target names are specified on the command line, then
dmake uses the first non-special target found in the make-
file as the default target. See the SPECIAL TARGETS sec-
tion for the list of special targets and their function.
Makefiles written for most previous versions of Make will
be handled correctly by dmake. Known differences between
dmake and other versions of make are discussed in the COM-
PATIBILITY section found at the end of this document.
dmake returns 0 if no errors were detected and a non-zero
result if an error occurred.
OPTIONS-A Enable AUGMAKE special inference rule transforma-
tions (see the "PERCENT(%) RULES" section), these
are set to off by default.
-B Enable the use of spaces instead of <tabs> to begin
recipe lines. This flag equivalent to the .NOTABS
special macro and is further described below.
-c Use non-standard comment stripping. If you specify
Version 4.01 PL0 UW 1
DMAKE(p) Unsupported Free Software DMAKE(p)-c then dmake will treat any # character as a start
of comment character wherever it may appear unless
it is escaped by a \.
-C [+]file
This option writes to file a copy of standard out-
put and standard error from any child processes and
from the dmake process itself. If you specify a +
prior to the file name then the text is appended to
the previous contents of file. This option is
active in the MSDOS implementation only and is
ignored by non-MSDOS versions of dmake.
-d Disable the use of the directory cache. Normally
dmake caches directories as it checks file times-
tamps. Giving this flag is equivalent to the
.DIRCACHE attribute or macro being set to no.
-E Read the environment and define all strings of the
form 'ENV-VAR=evalue' defined within as macros
whose name is ENV-VAR, and whose value is 'evalue'.
The environment is processed prior to processing
the user specified makefile thereby allowing defi-
nitions in the makefile to override definitions in
the environment.
-e Same as -E, except that the environment is pro-
cessed after the user specified makefile has been
processed (thus definitions in the environment
override definitions in the makefile). The -e and
-E options are mutually exclusive. If both are
given the latter takes effect.
-f file
Use file as the source for the makefile text. Only
one -f option is allowed.
-g Globally disable group recipe parsing, equivalent
to the .IGNOREGROUP attribute or macro being set to
yes at the start of the makefile.
-h Print the command summary for dmake.
-i Tells dmake to ignore errors, and continue making
other targets. This is equivalent to the .IGNORE
attribute or macro.
-K file
Turns on .KEEP_STATE state tracking and tells dmake
to use file as the state file.
-k Causes dmake to ignore errors caused by command
execution and to make all targets not depending on
targets that could not be made. Ordinarily dmakeVersion 4.01 PL0 UW 2
DMAKE(p) Unsupported Free Software DMAKE(p)
stops after a command returns a non-zero status,
specifying -k causes dmake to ignore the error and
continue to make as much as possible.
-n Causes dmake to print out what it would have exe-
cuted, but does not actually execute the commands.
A special check is made for the string "$(MAKE)"
inside a recipe line, if it is found, the line is
expanded and invoked, thereby enabling recursive
makes to give a full description of all that they
will do. This check is disabled inside group
recipes.
-p Print out a version of the digested makefile in
human readable form. (useful for debugging, but
cannot be re-read by dmake)
-P# On systems that support multi-processing cause
dmake to use # concurrent child processes to make
targets. See the "MULTI PROCESSING" section for
more information.
-q Check and see if the target is up to date. Exits
with code 0 if up to date, 1 otherwise.
-r Tells dmake not to read the initial startup make-
file, see STARTUP section for more details.
-s Tells dmake to do all its work silently and not
echo the commands it is executing to stdout (also
suppresses warnings). This is equivalent to the
.SILENT attribute or macro.
-S Force sequential execution of recipes on architec-
tures which support concurrent makes. For backward
compatibility with old makefiles that have nasty
side-effect prerequisite dependencies.
-t Causes dmake to touch the targets and bring them up
to date without executing any commands. Note that
targets will not be created if they do not already
exist.
-T Tells dmake to not perform transitive closure on
the inference graph.
-u Force an unconditional update. (ie. do everything
that would be done if everything that a target
depended on was out of date)
-v[dfimtw]
Verbose flag, when making targets print to stdout
what we are going to make and what we think its
time stamp is. The optional flags [dfimt] can be
Version 4.01 PL0 UW 3
DMAKE(p) Unsupported Free Software DMAKE(p)
used to restrict the information that is displayed.
In the absence of any optional flags all are
assumed to be given (ie. -v is equivalent to
-vdfimt). The meanings of the optional flags are:
c Notify of directory cache operations only.
d Notify of change directory operations only.
f Notify of file I/O operations only.
i Notify of inference algorithm operation
only.
m Notify of target update operations only.
t Keep any temporary files created; normally
they are automatically deleted.
w Notify of non-essential warnings (these are
historical).
-V Print the version of dmake, and values of builtin
macros.
-W target
Run dmake pretending that target is out of date.
-w target
What if? Show what would be made if target were out
of date.
-x Upon processing the user makefile export all non-
internally defined macros to the user's environ-
ment. This option together with the -e option
allows SYSV AUGMAKE recursive makes to function as
expected.
-X Inhibit the execution of #! lines found at the
beginning of a makefile. The use of this flag pre-
vents non-termination of recursive make invoca-
tions.
INDEX
Here is a list of the sections that follow and a short
description of each. Perhaps you won't have to read the
entire man page to find what you need.
STARTUP Describes dmake initialization.
SYNTAX Describes the syntax of makefile
expressions.
ATTRIBUTES Describes the notion of attributes and
Version 4.01 PL0 UW 4
DMAKE(p) Unsupported Free Software DMAKE(p)
how they are used when making targets.
MACROS Defining and expanding macros.
RULES AND TARGETS How to define targets and their prereq-
uisites.
RECIPES How to tell dmake how to make a target.
TEXT DIVERSIONS How to use text diversions in recipes
and macro expansions.
SPECIAL TARGETS Some targets are special.
SPECIAL MACROS Macros used by dmake to alter the pro-
cessing of the makefile, and those
defined by dmake for the user.
CONTROL MACROS Itemized list of special control
macros.
RUNTIME MACROS Discussion of special run-time macros
such as $@ and $<.
FUNCTION MACROS GNU style function macros, only $(mktmp
...) for now.
CONDITIONAL MACROS Target specific conditional macros.
DYNAMIC PREREQUISITES
Processing of prerequisites which con-
tain macro expansions in their name.
BINDING TARGETS The rules that dmake uses to bind a
target to an existing file in the file
system.
PERCENT(%) RULES Specification of recipes to be used by
the inference algorithm.
MAKING INFERENCES The rules that dmake uses when infer-
ring how to make a target which has no
explicit recipe. This and the previous
section are really a single section in
the text.
MAKING TARGETS How dmake makes targets other than
libraries.
MAKING LIBRARIES How dmake makes libraries.
KEEP STATE A discussion of how .KEEP_STATE works.
MULTI PROCESSING Discussion of dmake's parallel make
Version 4.01 PL0 UW 5
DMAKE(p) Unsupported Free Software DMAKE(p)
facilities for architectures that sup-
port them.
CONDITIONALS Conditional expressions which control
the processing of the makefile.
EXAMPLES Some hopefully useful examples.
COMPATIBILITY How dmake compares with previous ver-
sions of make.
LIMITS Limitations of dmake.
PORTABILITY Comments on writing portable makefiles.
FILES Files used by dmake.
SEE ALSO Other related programs, and man pages.
AUTHOR The guy responsible for this thing.
BUGS Hope not.
STARTUP
When dmake begins execution it first processes the command
line and then processes an initial startup-makefile. This
is followed by an attempt to locate and process a user
supplied makefile. The startup file defines the default
values of all required control macros and the set of
default rules for making targets and inferences. When
searching for the startup makefile, dmake searches the
following locations, in the order specified, until a
startup file is located:
1. The location given as the value of the macro
MAKESTARTUP defined on the command line.
2. The location given as the value of the envi-
ronment variable MAKESTARTUP defined in the
current environment.
3. The location given as the value of the macro
MAKESTARTUP defined internally within dmake.
The above search is disabled by specifying the -r option
on the command line. An error is issued if a startup
makefile cannot be found and the -r option was not speci-
fied. A user may substitute a custom startup file by
defining the MAKESTARTUP environment variable or by
redefining the MAKESTARTUP macro on the command line. To
determine where dmake looks for the default startup file,
check your environment or issue the command "dmake -V".
Version 4.01 PL0 UW 6
DMAKE(p) Unsupported Free Software DMAKE(p)
A similar search is performed to locate a default user
makefile when no -f command line option is specified. By
default, the prerequisite list of the special target
.MAKEFILES specifies the names of possible makefiles and
the search order that dmake should use to determine if one
exists. A typical definition for this target is:
.MAKEFILES : makefile.mk Makefile makefile
dmake will first look for makefile.mk and then the others.
If a prerequisite cannot be found dmake will try to make
it before going on to the next prerequisite. For example,
makefile.mk can be checked out of an RCS file if the
proper rules for doing so are defined in the startup file.
If the first line of the user makefile is of the form:
then dmake will expand and run the command prior to read-
ing any additional input. If the return code of the com-
mand is zero then dmake will continue on to process the
remainder of the user makefile, if the return code is non-
zero then dmake will exit.
dmake builds the internal dependency graph as it parses a
user specified makefile. The graph is rooted at the spe-
cial target .ROOT. .ROOT is the top level target that
dmake builds when it starts to build targets. All user
specified targets (those from the command line or taken as
defaults from the makefile) are made prerequisites of the
special target .TARGETS. dmake by default creates the
relationship that .ROOT depends on .TARGETS and as a
result everything is made. This approach allows the user
to customize, within their makefile, the order and which,
target, is built first. For example the default makefiles
come with settings for .ROOT that specify:
.ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS
.DONE
with .INIT and .DONE defined as:
.INIT .DONE .PHONY:;
which nicely emulates the behaviour of Sun's make exten-
sions. The building of .ROOT's prerequisites is always
forced to be sequential. However, this definition is
trivially chaned by supplying the definition:
.ROOT : .TARGETS
which skips the preamble and postamble phases of building
.TARGETS.
Version 4.01 PL0 UW 7
DMAKE(p) Unsupported Free Software DMAKE(p)SYNTAX
This section is a summary of the syntax of makefile state-
ments. The description is given in a style similar to
BNF, where { } enclose items that may appear zero or more
times, and [ ] enclose items that are optional. Alterna-
tive productions for a left hand side are indicated by
'->', and newlines are significant. All symbols in bold
type are text or names representing text supplied by the
user.
Makefile -> { Statement }
Statement -> Macro-Definition
-> Conditional-Macro-Definition
-> Conditional
-> Rule-Definition
-> Attribute-Definition
Macro-Definition -> MACRO = LINE
-> MACRO [!]*= LINE
-> MACRO [!]:= LINE
-> MACRO [!]*:= LINE
-> MACRO [!]+= LINE
-> MACRO [!]+:= LINE
Conditional-Macro-Definition -> TARGET ?= Macro-Definition
Conditional -> .IF expression
Makefile
[ .ELIF expression
Makefile ]
[ .ELSE
Makefile ]
.END
expression -> LINE
-> STRING == LINE
-> STRING != LINE
Rule-Definition -> target-definition
[ recipe ]
target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line]
targets -> target { targets }
-> "target" { targets }
target -> special-target
-> TARGET
attrs -> attribute { attrs }
-> "attribute" { attrs }
Version 4.01 PL0 UW 8
DMAKE(p) Unsupported Free Software DMAKE(p)
op -> : { modifier }
modifier -> :
-> ^
-> !
-> -
-> |
recipe -> { TAB rcp-line }
-> [@][%][-] [
{ LINE }
]
rcp-line -> [@][%][-][+] LINE
Attribute-Definition -> attrs : targets
attribute -> .EPILOG
-> .ERRREMOVE
-> .EXECUTE
-> .GROUP
-> .IGNORE
-> .IGNOREGROUP
-> .LIBRARY
-> .MKSARGS
-> .NOINFER
-> .NOSTATE
-> .PHONY
-> .PRECIOUS
-> .PROLOG
-> .SETDIR=path
-> .SILENT
-> .SEQUENTIAL
-> .SWAP
-> .USESHELL
-> .SYMBOL
-> .UPDATEALL
special-target -> .ERROR
-> .EXIT
-> .EXPORT
-> .GROUPEPILOG
-> .GROUPPROLOG
-> .IMPORT
-> .INCLUDE
-> .INCLUDEDIRS
-> .MAKEFILES
-> .REMOVE
-> .SOURCE
-> .SOURCE.suffix
-> .suffix1.suffix2
Where, TAB represents a <tab> character, STRING represents
Version 4.01 PL0 UW 9
DMAKE(p) Unsupported Free Software DMAKE(p)
an arbitrary sequence of characters, and LINE represents a
possibly empty sequence of characters terminated by a non-
escaped (not immediately preceded by a backslash '\') new-
line character. MACRO, PREREQUISITE, and TARGET each rep-
resent a string of characters not including space or tab
which respectively form the name of a macro, prerequisite
or target. The name may itself be a macro expansion
expression. A LINE can be continued over several physical
lines by terminating it with a single backslash character.
Comments are initiated by the pound # character and extend
to the end of line. All comment text is discarded, a '#'
may be placed into the makefile text by escaping it with
'\' (ie. \# translates to # when it is parsed). An excep-
tion to this occurs when a # is seen inside a recipe line
that begins with a <tab> or is inside a group recipe. If
you specify the -c command line switch then this behavior
is disabled and dmake will treat all # characters as start
of comment indicators unless they are escaped by \. A set
of continued lines may be commented out by placing a sin-
gle # at the start of the first line. A continued line
cannot span more than one makefile.
white space is defined to be any combination of <space>,
<tab>, and the sequence \<nl> when \<nl> is used to termi-
nate a LINE. When processing macro definition lines, any
amount of white space is allowed on either side of the
macro operator and white space is stripped from both
before and after the macro value string. The sequence
\<nl> is treated as white space during recipe expansion
and is deleted from the final recipe string. You must
escape the \<nl> with another \ in order to get a \ at the
end of a recipe line. The \<nl> sequence is deleted from
macro values when they are expanded.
When processing target definition lines, the recipe for a
target must, in general, follow the first definition of
the target (See the RULES AND TARGETS section for an
exception), and the recipe may not span across multiple
makefiles. Any targets and prerequisites found on a tar-
get definition line are taken to be white space separated
tokens. The rule operator (op in SYNTAX section) is also
considered to be a token but does not require white space
to precede or follow it. Since the rule operator begins
with a `:', traditional versions of make do not allow the
`:' character to form a valid target name. dmake allows
`:' to be present in target/prerequisite names as long as
the entire target/prerequisite name is quoted. For exam-
ple:
a:fred : test
would be parsed as TARGET = a, PREREQUISITES={fred, :,
test}, which is not what was intended. To fix this you
must write:
Version 4.01 PL0 UW 10
DMAKE(p) Unsupported Free Software DMAKE(p)
"a:fred" : test
Which will be parsed as expected. Quoted target and pre-
requisite specifications may also contain white space
thereby allowing the use of complex function macro expres-
sions.. See the EXAMPLES section for how to apply " quot-
ing to a list of targets.
ATTRIBUTESdmake defines several target attributes. Attributes may
be assigned to a single target, a group of targets, or to
all targets in the makefile. Attributes are used to mod-
ify dmake actions during target update. The recognized
attributes are:
.EPILOG Insert shell epilog code when executing a
group recipe associated with any target having
this attribute set.
.ERRREMOVE Always remove any target having this attribute
if an error is encountered while making them.
Setting this attribute overrides the .PRECIOUS
attribute.
.EXECUTE If the -n flag was given then execute the
recipe associated with any target having this
attribute set.
.FIRST Used in conjunction with .INCLUDE. Terminates
the inclusion with the first successfully
included prerequisite.
.GROUP Force execution of a target's recipe as a
group recipe.
.IGNORE Ignore an error when trying to make any target
with this attribute set.
.IGNOREGROUP
Disable the special meaning of '[' to initiate
a group recipe.
.LIBRARY Target is a library.
.MKSARGS If running in an MSDOS environment then use
MKS extended argument passing conventions to
pass arguments to commands. Non-MSDOS envi-
ronments ignore this attribute.
.NOINFER Any target with this attribute set will not be
subjected to transitive closure if it is
inferred as a prerequisite of a target whose
recipe and prerequisites are being inferred.
Version 4.01 PL0 UW 11
DMAKE(p) Unsupported Free Software DMAKE(p)
(i.e. the inference algorithm will not use any
prerequisite with this attribute set, as a
target) If specified as '.NOINFER:' (ie. with
no prerequisites or targets) then the effect
is equivalent to specifying -T on the command
line.
.NOSTATE Any target with this attribute set will not
have command line flag information stored in
the state file if .KEEP_STATE has been
enabled.
.PHONY Any target with this attribute set will have
its recipe executed each time the target is
made even if a file matching the target name
can be located. Any targets that have a
.PHONY attributed target as a prerequisite
will be made each time the .PHONY attributed
prerequisite is made.
.PRECIOUS Do not remove associated target under any cir-
cumstances. Set by default for any targets
whose corresponding files exist in the file
system prior to the execution of dmake.
.PROLOG Insert shell prolog code when executing a
group recipe associated with any target having
this attribute set.
.SEQUENTIAL Force a sequential make of the associated tar-
get's prerequisites.
.SETDIR Change current working directory to specified
directory when making the associated target.
You must specify the directory at the time the
attribute is specified. To do this simply
give .SETDIR=path as the attribute. path is
expanded and the result is used as the value
of the directory to change to. If path con-
tains $$@ then the name of the target to be
built is used in computing the path to change
directory to. If path is surrounded by single
quotes then path is not expanded, and is used
literally as the directory name. If the path
contains any `:' characters then the entire
attribute string must be quoted using ". If a
target having this attribute set also has the
.IGNORE attribute set then if the change to
the specified directory fails it will be
ignored, and no error message will be issued.
.SILENT Do not echo the recipe lines when making any
target with this attribute set, and do not
issue any warnings.
Version 4.01 PL0 UW 12
DMAKE(p) Unsupported Free Software DMAKE(p)
.SWAP Under MSDOS when making a target with this
attribute set swap the dmake executable to
disk prior to executing the recipe line. Also
see the '%' recipe line flag defined in the
RECIPES section.
.SYMBOL Target is a library member and is an entry
point into a module in the library. This
attribute is used only when searching a
library for a target. Targets of the form
lib((entry)) have this attribute set automati-
cally.
.USESHELL Force each recipe line of a target to be exe-
cuted using a shell. Specifying this
attribute is equivalent to specifying the '+'
character at the start of each line of a non-
group recipe.
.UPDATEALL Indicates that all the targets listed in this
rule are updated by the execution of the
accompanying recipe. A common example is the
production of the y.tab.c and y.tab.h files by
yacc when it is run on a grammar. Specifying
.UPDATEALL in such a rule prevents the running
of yacc twice, once for the y.tab.c file and
once for the y.tab.h file. .UPDATEALL targets
that are specified in a single rule are
treated as a single target and all timestamps
are updated whenever any target in the set is
made. As a side-effect, dmake internally
sorts such targets in ascending alphabetical
order and the value of $@ is always the first
target in the sorted set.
All attributes are user setable and except for .UPDATEALL,
.SETDIR and .MKSARGS may be used in one of two forms. The
.MKSARGS attribute is restricted to use as a global
attribute, and the use of the .UPDATEALL and .SETDIR
attributes is restricted to rules of the second form only.
ATTRIBUTE_LIST : targets
assigns the attributes specified by ATTRIBUTE_LIST to each
target in targets or
targets ATTRIBUTE_LIST : ...
assigns the attributes specified by ATTRIBUTE_LIST to each
target in targets. In the first form if targets is empty
(ie. a NULL list), then the list of attributes will apply
to all targets in the makefile (this is equivalent to the
common Make construct of ".IGNORE :" but has been modified
to the notion of an attribute instead of a special
Version 4.01 PL0 UW 13
DMAKE(p) Unsupported Free Software DMAKE(p)
target). Not all of the attributes have global meaning.
In particular, .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYM-
BOL and .UPDATEALL have no assigned global meaning.
Any attribute may be used with any target, even with the
special targets. Some combinations are useless (e.g.
.INCLUDE .PRECIOUS: ... ), while others are useful (e.g.
.INCLUDE .IGNORE : "file.mk" will not complain if file.mk
cannot be found using the include file search rules, see
the section on SPECIAL TARGETS for a description of
.INCLUDE). If a specified attribute will not be used with
the special target a warning is issued and the attribute
is ignored.
MACROSdmake supports six forms of macro assignment.
MACRO = LINE This is the most common and familiar form
of macro assignment. It assigns LINE lit-
erally as the value of MACRO. Future
expansions of MACRO recursively expand its
value.
MACRO *= LINE This form behaves exactly as the simple
'=' form with the exception that if MACRO
already has a value then the assignment is
not performed.
MACRO := LINE This form differs from the simple '=' form
in that it expands LINE prior to assigning
it as the value of MACRO. Future expan-
sions of MACRO do not recursively expand
its value.
MACRO *:= LINE This form behaves exactly as the ':=' form
with the exception that if MACRO already
has a value then the assignment and expan-
sion are not performed.
MACRO += LINE This form of macro assignment allows macro
values to grow. It takes the literal
value of LINE and appends it to the previ-
ous value of MACRO separating the two by a
single space. Future expansions of MACRO
recursively expand its value.
MACRO +:= LINE This form is similar to the '+=' form
except that the value of LINE is expanded
prior to being added to the value of
MACRO.
Macro expressions specified on the command line allow the
macro value to be redefined within the makefile only if
Version 4.01 PL0 UW 14
DMAKE(p) Unsupported Free Software DMAKE(p)
the macro is defined using the '+=' and '+:=' operators.
Other operators will define a macro that cannot be further
modified.
Each of the preceeding macro assignment operators may be
prefixed by ! to indicate that the assignment should be
forced and that no warnings should be issued. Thus, spec-
ifying ! has the effect of silently forcing the specified
macro assignment.
When dmake defines a non-environment macro it strips lead-
ing and trailing white space from the macro value. Macros
imported from the environment via either the .IMPORT spe-
cial target (see the SPECIAL TARGETS section), or the -e,
or -E flags are an exception to this rule. Their values
are always taken literally and white space is never
stripped. In addition, named macros defined using the
.IMPORT special target do not have their values expanded
when they are used within a makefile. In contrast, envi-
ronment macros that are imported due to the specification
of the -e or -E flags are subject to expansion when used.
To specify a macro expansion enclose the name in () or {}
and precede it with a dollar sign $. Thus $(TEST) repre-
sents an expansion of the macro variable named TEST. If
TEST is defined then $(TEST) is replaced by its expanded
value. If TEST is not defined then $(TEST) expands to the
NULL string (this is equivalent to defining a macro as
'TEST=' ). A short form may be used for single character
named macros. In this case the parentheses are optional,
and $(I) is equivalent to $I. Macro expansion is recur-
sive, hence, if the value string contains an expression
representing a macro expansion, the expansion is per-
formed. Circular macro expansions are detected and cause
an error to be issued.
When defining a macro the given macro name is first
expanded before being used to define the macro. Thus it
is possible to define macros whose names depend on values
of other macros. For example, suppose CWD is defined as
CWD = $(PWD:b)
then the value of $(CWD) is the name of the current direc-
tory. This can be used to define macros specific to this
directory, for example:
_$(CWD).prt = list of files to print...
The actual name of the defined macro is a function of the
current directory. A construct such as this is useful
when processing a hierarchy of directories using .SETDIR
attributed targets and a collection of small distributed
makefile stubs.
Version 4.01 PL0 UW 15
DMAKE(p) Unsupported Free Software DMAKE(p)
Macro variables may be defined within the makefile, on the
command line, or imported from the environment.
dmake supports several non-standard macro expansions: The
first is of the form:
$(macro_name:modifier_list:modifier_list:...)
where modifier_list is chosen from the set { B or b, D or
d, E or e, F or f, I or i, L or l, S or s, T or t, U or u,
^, +, 1 } and
b - file (not including suffix) portion of path names
d - directory portion of all path names
e - suffix portion of path names
f - file (including suffix) portion of path names
i - inferred names of targets
l - macro value in lower case
s - simple pattern substitution
t - tokenization.
u - macro value in upper case
^ - prepend a prefix to each token
+ - append a suffix to each token
1 - return the first white space separated token from value
Thus if we have the example:
test = d1/d2/d3/a.out f.out d1/k.out
The following macro expansions produce the values on the
right of '->' after expansion.
$(test:d) -> d1/d2/d3/ d1/
$(test:b) -> a f k
$(test:f) -> a.out f.out k.out
${test:db} -> d1/d2/d3/a f d1/k
${test:s/out/in/:f} -> a.in f.in k.in
$(test:f:t"+") -> a.out+f.out+k.out
$(test:e) -> .out .out .out
$(test:u) -> D1/D2/D3/A.OUT F.OUT D1/K.OUT
$(test:1) -> d1/d2/d3/a.out
If a token ends in a string composed from the value of the
macro DIRBRKSTR (ie. ends in a directory separator string,
e.g. '/' in UNIX) and you use the :d modifier then the
expansion returns the directory name less the final direc-
tory separator string. Thus successive pairs of :d modi-
fiers each remove a level of directory in the token
string.
The tokenization modifier takes all white space separated
tokens from the macro value and separates them by the
quoted separator string. The separator string may contain
the following escape codes \a => <bel>, \b => <backspace>,
\f => <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v
=> <vertical tab>, \" => ", and \xxx => <xxx> where xxx is
Version 4.01 PL0 UW 16
DMAKE(p) Unsupported Free Software DMAKE(p)
the octal representation of a character. Thus the expan-
sion:
$(test:f:t"+\n")
produces:
a.out+
f.out+
k.out
The prefix operator ^ takes all white space separated
tokens from the macro value and prepends string to each.
$(test:f:^mydir/)
produces:
mydir/a.out mydir/f.out mydir/k.out
The suffix operator + takes all white space separated
tokens from the macro value and appends string to each.
$(test:b:+.c)
produces:
a.c f.c k.c
The next non-standard form of macro expansion allows for
recursive macros. It is possible to specify a
$(macro_name) or ${macro_name} expansion where macro_name
contains more $( ... ) or ${ ... } macro expansions
itself.
For example $(CC$(_HOST)$(_COMPILER)) will first expand
CC$(_HOST)$(_COMPILER) to get a result and use that result
as the name of the macro to expand. This is useful for
writing a makefile for more than one target environment.
As an example consider the following hypothetical case.
Suppose that _HOST and _COMPILER are imported from the
environment and are set to represent the host machine type
and the host compiler respectively.
CFLAGS_VAX_CC = -c -O # _HOST == "_VAX", _COMPILER == "_CC"
CFLAGS_PC_MSC = -c -ML # _HOST == "_PC", _COMPILER == "_MSC"
# redefine CFLAGS macro as:
CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
This causes CFLAGS to take on a value that corresponds to
the environment in which the make is being invoked.
The final non-standard macro expansion is of the form:
string1{token_list}string2
where string1, string2 and token_list are expanded. After
expansion, string1 is prepended to each token found in
Version 4.01 PL0 UW 17
DMAKE(p) Unsupported Free Software DMAKE(p)
token_list and string2 is appended to each resulting token
from the previous prepend. string1 and string2 are not
delimited by white space whereas the tokens in token_list
are. A null token in the token list is specified using
"". Thus using another example we have:
test/{f1 f2}.o --> test/f1.o test/f2.o
test/ {f1 f2}.o --> test/ f1.o f2.o
test/{f1 f2} .o --> test/f1 test/f2 .o
test/{"f1" ""}.o --> test/f1.o test/.o
and
test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
test/d2/f1.o test/d2/f2.o
This last expansion is activated only when the first char-
acters of token_list appear immediately after the opening
'{' with no intervening white space. The reason for this
restriction is the following incompatibility with Bourne
Shell recipes. The line
{ echo hello;}
is valid /bin/sh syntax; while
{echo hello;}
is not. Hence the latter triggers the enhanced macro
expansion while the former causes it to be suppressed.
See the SPECIAL MACROS section for a description of the
special macros that dmake defines and understands.
RULES AND TARGETS
A makefile contains a series of entries that specify
dependencies. Such entries are called target/prerequisite
or rule definitions. Each rule definition is optionally
followed by a set of lines that provide a recipe for
updating any targets defined by the rule. Whenever dmake
attempts to bring a target up to date and an explicit
recipe is provided with a rule defining the target, that
recipe is used to update the target. A rule definition
begins with a line having the following syntax:
<targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>]
targets is a non-empty list of targets. If the target is
a special target (see SPECIAL TARGETS section below) then
it must appear alone on the rule line. For example:
.IMPORT .ERROR : ...
is not allowed since both .IMPORT and .ERROR are special
targets. Special targets are not used in the construction
Version 4.01 PL0 UW 18
DMAKE(p) Unsupported Free Software DMAKE(p)
of the dependency graph and will not be made.
attributes is a possibly empty list of attributes. Any
attribute defined in the ATTRIBUTES section above may be
specified. All attributes will be applied to the list of
named targets in the rule definition. No other targets
will be affected.
NOTE: As stated earlier, if both the target list and
prerequisite list are empty but the attributes
list is not, then the specified attributes affect
all targets in the makefile.
ruleop is a separator which is used to identify the tar-
gets from the prerequisites. Optionally it also provides
a facility for modifying the way in which dmake handles
the making of the associated targets. In its simplest
form the operator is a single ':', and need not be sepa-
rated by white space from its neighboring tokens. It may
additionally be followed by any of the modifiers { !, ^,
-, :, | }, where:
! says execute the recipe for the associated targets
once for each out of date prerequisite. Ordinarily
the recipe is executed once for all out of date
prerequisites at the same time.
^ says to insert the specified prerequisites, if any,
before any other prerequisites already associated
with the specified targets. In general, it is not
useful to specify ^ with an empty list of prerequi-
sites.
- says to clear the previous list of prerequisites
before adding the new prerequisites. Thus,
.SUFFIXES :
.SUFFIXES : .a .b
can be replaced by
.SUFFIXES :- .a .b
however the old form still works as expected.
NOTE: .SUFFIXES is ignored by dmake it is used
here simply as an example.
: When the rule operator is not modified by a second
':' only one set of rules may be specified for mak-
ing a target. Multiple definitions may be used to
add to the list of prerequisites that a target
Version 4.01 PL0 UW 19
DMAKE(p) Unsupported Free Software DMAKE(p)
depends on. However, if a target is multiply
defined only one definition may specify a recipe
for making the target.
When a target's rule operator is modified by a sec-
ond ':' (:: for example) then this definition may
not be the only definition with a recipe for the
target. There may be other :: target definition
lines that specify a different set of prerequisites
with a different recipe for updating the target.
Any such target is made if any of the definitions
find it to be out of date with respect to the
related prerequisites and the corresponding recipe
is used to update the target. By definition all
'::' recipes that are found to be out of date for
are executed.
In the following simple example, each rule has a
`::' ruleop. In such an operator we call the first
`:' the operator, and the second `:' the modifier.
a.o :: a.c b.h
first recipe for making a.o
a.o :: a.y b.h
second recipe for making a.o
If a.o is found to be out of date with respect to
a.c then the first recipe is used to make a.o. If
it is found out of date with respect to a.y then
the second recipe is used. If a.o is out of date
with respect to b.h then both recipes are invoked
to make a.o. In the last case the order of invoca-
tion corresponds to the order in which the rule
definitions appear in the makefile.
| Is defined only for PERCENT rule target defini-
tions. When specified it indicates that the fol-
lowing construct should be parsed using the old
semantinc meaning:
%.o :| %.c %.r %.f ; some rule
is equivalent to:
%.o : %.c ; some rule
%.o : %.r ; some rule
%.o : %.f ; some rule
Targets defined using a single `:' operator with a recipe
may be redefined again with a new recipe by using a `:'
operator with a `:' modifier. This is equivalent to a
target having been initially defined with a rule using a
`:' modifier. Once a target is defined using a `:'
Version 4.01 PL0 UW 20
DMAKE(p) Unsupported Free Software DMAKE(p)
modifier it may not be defined again with a recipe using
only the `:' operator with no `:' modifier. In both cases
the use of a `:' modifier creates a new list of prerequi-
sites and makes it the current prerequisite list for the
target. The `:' operator with no recipe always modifies
the current list of prerequisites. Thus assuming each of
the following definitions has a recipe attached, then:
joe : fred ... (1)
joe :: more ... (2)
and
joe :: fred ... (3)
joe :: more ... (4)
are legal and mean: add the recipe associated with (2),
or (4) to the set of recipes for joe, placing them after
existing recipes for making joe. The constructs:
joe :: fred ... (5)
joe : more ... (6)
and
joe : fred ... (7)
joe : more ... (8)
are errors since we have two sets of perfectly good
recipes for making the target.
prerequisites is a possibly empty list of targets that
must be brought up to date before making the current tar-
get.
recipe is a short form and allows the user to specify
short rule definitions on a single line. It is taken to
be the first recipe line in a larger recipe if additional
lines follow the rule definition. If the semi-colon is
present but the recipe line is empty (ie. null string)
then it is taken to be an empty rule. Any target so
defined causes the Don't know how to make ... error mes-
sage to be suppressed when dmake tries to make the target
and fails. This silence is maintained for rules that are
terminated by a semicolon and have no following recipe
lines, for targets listed on the command line, for the
first target found in the makefile, and for any target
having no recipe but containing a list of prerequisites
(see the COMPATIBILITY section for an exception to this
rule if the AUGMAKE (-A) flag was specified.
RECIPES
The traditional format used by most versions of Make
defines the recipe lines as arbitrary strings that may
Version 4.01 PL0 UW 21
DMAKE(p) Unsupported Free Software DMAKE(p)
contain macro expansions. They follow a rule definition
line and may be spaced apart by comment or blank lines.
The list of recipe lines defining the recipe is terminated
by a new target definition, a macro definition, or end-of-
file. Each recipe line MUST begin with a <TAB> character
which may optionally be followed with one or all of the
characters '@%+-'. The '-' indicates that non-zero exit
values (ie. errors) are to be ignored when this recipe
line is executed, the '+' indicates that the current
recipe line is to be executed using the shell, the '%'
indicates that dmake should swap itself out to secondary
storage (MSDOS only) before running the recipe and the '@'
indicates that the recipe line should NOT be echoed to the
terminal prior to being executed. Each switch is off by
default (ie. by default, errors are significant, commands
are echoed, no swapping is done and a shell is used only
if the recipe line contains a character found in the value
of the SHELLMETAS macro). Global settings activated via
command line options or special attribute or target names
may also affect these settings. An example recipe:
target :
first recipe line
second recipe line, executed independent of first.
@a recipe line that is not echoed
-and one that has errors ignored
%and one that causes dmake to swap out
+and one that is executed using a shell.
The second and new format of the recipe block begins the
block with the character '[' (the open group character) in
the last non-white space position of a line, and termi-
nates the block with the character ']' (the close group
character) in the first non-white space position of a
line. In this form each recipe line need not have a lead-
ing TAB. This is called a recipe group. Groups so
defined are fed intact as a single unit to a shell for
execution whenever the corresponding target needs to be
updated. If the open group character '[' is preceded by
one or all of -, @ or % then they apply to the entire
group in the same way that they apply to single recipe
lines. You may also specify '+' but it is redundant as a
shell is already being used to run the recipe. See the
MAKING TARGETS section for a description of how dmake
invokes recipes. Here is an example of a group recipe:
target :
[
first recipe line
second recipe line
tall of these recipe lines are fed to a
single copy of a shell for execution.
]
Version 4.01 PL0 UW 22
DMAKE(p) Unsupported Free Software DMAKE(p)TEXT DIVERSIONSdmake supports the notion of text diversions. If a recipe
line contains the macro expression
$(mktmp[,[file][,text]] data)
then all text contained in the data expression is expanded
and is written to a temporary file. The return value of
the macro is the name of the temporary file.
data can be any text and must be separated from the
'mktmp' portion of the macro name by white-space. The
only restriction on the data text is that it must contain
a balanced number of parentheses of the same kind as are
used to initiate the $(mktmp ...) expression. For exam-
ple:
$(mktmp $(XXX))
is legal and works as expected, but:
$(mktmp text (to dump to file)
is not legal. You can achieve what you wish by either
defining a macro that expands to '(' or by using {} in the
macro expression; like this:
${mktmp text (to dump to file}
Since the temporary file is opened when the macro contain-
ing the text diversion expression is expanded, diversions
may be nested and any diversions that are created as part
of ':=' macro expansions persist for the duration of the
dmake run. The diversion text may contain the same escape
codes as those described in the MACROS section. Thus if
the data text is to contain new lines they must be
inserted using the \n escape sequence. For example the
expression:
all:
cat $(mktmp this is a\n\
test of the text diversion\n)
is replaced by:
cat /tmp/mk12294AA
where the temporary file contains two lines both of which
are terminated by a new-line. If the data text spans mul-
tiple lines in the makefile then each line must be contin-
ued via the use of a \. A second more illustrative exam-
ple generates a response file to an MSDOS link command:
OBJ = fred.obj mary.obj joe.obj
Version 4.01 PL0 UW 23
DMAKE(p) Unsupported Free Software DMAKE(p)
all : $(OBJ)
link @$(mktmp $(^:t"+\n")\n)
The result of making `all' in the second example is the
command:
link @/tmp/mk02394AA
where the temporary file contains:
fred.obj+
mary.obj+
joe.obj
The last line of the file is terminated by a new-line
which is inserted due to the \n found at the end of the
data string.
If the optional file specifier is present then its
expanded value is the name of the temporary file to cre-
ate. Whenever a $(mktmp ...) macro is expanded the macro
$(TMPFILE) is set to a new temporary file name. Thus the
construct:
$(mktmp,$(TMPFILE) data)
is completely equivalent to not specifying the $(TMPFILE)
optional argument. Another example that would be useful
for MSDOS users with a Turbo-C compiler
$(mktmp,turboc.cfg $(CFLAGS))
will place the contents of CFLAGS into a local turboc.cfg
file. The second optional argument, text, if present
alters the name of the value returned by the $(mktmp ...)
macro.
Under MS-DOS text diversions may be a problem. Many DOS
tools require that path names which contain directories
use the \ character to delimit the directories. Some
users however wish to use the '/' to delimit pathnames and
use environments that allow them to do so. The macro USE-
SHELL is set to "yes" if the current recipe is forced to
use a shell via the .USESHELL or '+' directives, otherwise
its value is "no". The dmake startup files define the
macro DIVFILE whose value is either the value of TMPFILE
or the value of TMPFILE edited to replace any '/' charac-
ters to the appropriate value based on the current shell
and whether it will be used to execute the recipe.
Previous versions of dmake defined text diversions using
<+, +> strings, where <+ started a text diversion and +>
terminated one. dmake is backward compatible with this
construct only if the <+ and +> appear literally on the
Version 4.01 PL0 UW 24
DMAKE(p) Unsupported Free Software DMAKE(p)
same recipe line or in the same macro value string. In
such instances the expression:
<+data+>
is mapped to:
$(mktmp data)
which is fully output compatible with the earlier con-
struct. <+, +> constructs whose text spans multiple lines
must be converted by hand to use $(mktmp ...).
If the environment variable TMPDIR is defined then the
temporary file is placed into the directory specified by
that variable. A makefile can modify the location of tem-
porary files by defining a macro named TMPDIR and export-
ing it using the .EXPORT special target.
SPECIAL TARGETS
This section describes the special targets that are recog-
nized by dmake. Some are affected by attributes and oth-
ers are not.
.ERROR If defined then the recipe associated with
this target is executed whenever an error
condition is detected by dmake. All
attributes that can be used with any other
target may be used with this target. Any
prerequisites of this target will be brought
up to date during its processing. NOTE:
errors will be ignored while making this
target, in extreme cases this may cause some
problems.
.EXIT If this target is encountered while parsing
a makefile then the parsing of the makefile
is immediately terminated at that point.
.EXPORT All prerequisites associated with this tar-
get are assumed to correspond to macro names
and they and their values are exported to
the environment as environment strings at
the point in the makefile at which this tar-
get appears. Any attributes specified with
this target are ignored. Only macros which
have been assigned a value in the makefile
prior to the export directive are exported,
macros as yet undefined or macros whose
value contains any of the characters "+=:*"
are not exported. is suppre
.IMPORT Prerequisite names specified for this target
are searched for in the environment and
Version 4.01 PL0 UW 25
DMAKE(p) Unsupported Free Software DMAKE(p)
defined as macros with their value taken
from the environment. If the special name
.EVERYTHING is used as a prerequisite name
then all environment variables defined in
the environment are imported. The function-
ality of the -E flag can be forced by plac-
ing the construct .IMPORT : .EVERYTHING at
the start of a makefile. Similarly, by
placing the construct at the end, one can
emulate the effect of the -e command line
flag. If a prerequisite name cannot be
found in the environment an error message is
issued. .IMPORT accepts the .IGNORE
attribute. When given, it causes dmake to
ignore the above error. See the MACROS sec-
tion for a description of the processing of
imported macro values.
.INCLUDE Parse another makefile just as if it had
been located at the point of the .INCLUDE in
the current makefile. The list of prerequi-
sites gives the list of makefiles to try to
read. If the list contains multiple make-
files then they are read in order from left
to right. The following search rules are
used when trying to locate the file. If the
filename is surrounded by " or just by
itself then it is searched for in the cur-
rent directory. If it is not found it is
then searched for in each of the directories
specified as prerequisites of the
.INCLUDEDIRS special target. If the file
name is surrounded by < and >, (ie.
<my_spiffy_new_makefile>) then it is
searched for only in the directories given
by the .INCLUDEDIRS special target. In both
cases if the file name is a fully qualified
name starting at the root of the file system
then it is only searched for once, and the
.INCLUDEDIRS list is ignored. If .INCLUDE
fails to find the file it invokes the infer-
ence engine to try to infer and hence make
the file to be included. In this way the
file can be checked out of an RCS repository
for example. .INCLUDE accepts the .IGNORE,
.SETDIR, and .NOINFER attributes. If the
.IGNORE attribute is given and the file can-
not be found then dmake continues process-
ing, otherwise an error message is gener-
ated. If the .NOINFER attribute is given
and the file cannot be found then dmake will
not attempt to infer and make the file. The
.SETDIR attribute causes dmake to change
directories to the specified directory prior
Version 4.01 PL0 UW 26
DMAKE(p) Unsupported Free Software DMAKE(p)
to attempting the include operation. If all
fails dmake attempts to make the file to be
included. If making the file fails then
dmake terminates unless the .INCLUDE direc-
tive also specified the .IGNORE attribute.
If .FIRST is specified along with .INCLUDE
then dmake attempts to include each named
prerequisite and will terminate the inclu-
sion with the first prerequisite that
results in a successful inclusion.
.INCLUDEDIRS The list of prerequisites specified for this
target defines the set of directories to
search when trying to include a makefile.
.KEEP_STATE This special target is a synonym for the
macro definition
.KEEP_STATE := _state.mk
It's effect is to turn on STATE keeping and
to define _state.mk as the state file.
.MAKEFILES The list of prerequisites is the set of
files to try to read as the default make-
file. By default this target is defined as:
.MAKEFILES : makefile.mk Makefile makefile
.SOURCE The prerequisite list of this target defines
a set of directories to check when trying to
locate a target file name. See the section
on BINDING of targets for more information.
.SOURCE.suff The same as .SOURCE, except that the
.SOURCE.suff list is searched first when
trying to locate a file matching the a tar-
get whose name ends in the suffix .suff.
.REMOVE The recipe of this target is used whenever
dmake needs to remove intermediate targets
that were made but do not need to be kept
around. Such targets result from the appli-
cation of transitive closure on the depen-
dency graph.
In addition to the special targets above, several other
forms of targets are recognized and are considered spe-
cial, their exact form and use is defined in the sections
that follow.
SPECIAL MACROSdmake defines a number of special macros. They are
Version 4.01 PL0 UW 27
DMAKE(p) Unsupported Free Software DMAKE(p)
divided into three classes: control macros, run-time
macros, and function macros. The control macros are used
by dmake to configure its actions, and are the preferred
method of doing so. In the case when a control macro has
the same function as a special target or attribute they
share the same name as the special target or attribute.
The run-time macros are defined when dmake makes targets
and may be used by the user inside recipes. The function
macros provide higher level functions dealing with macro
expansion and diversion file processing.
CONTROL MACROS
To use the control macros simply assign them a value just
like any other macro. The control macros are divided into
three groups: string valued macros, character valued
macros, and boolean valued macros.
The following are all of the string valued macros. This
list is divided into two groups. The first group gives
the string valued macros that are defined internally and
cannot be directly set by the user.
INCDEPTH This macro's value is a string of digits
representing the current depth of makefile
inclusion. In the first makefile level
this value is zero.
MFLAGS Is the list of flags that were given on
the command line including a leading
switch character. The -f flag is not
included in this list.
MAKECMD Is the name with which dmake was invoked.
MAKEDIR Is the full path to the initial directory
in which dmake was invoked.
MAKEFILE Contains the string "-f makefile" where,
makefile is the name of initial user make-
file that was first read.
MAKEFLAGS Is the same as $(MFLAGS) but has no lead-
ing switch character. (ie. MFLAGS =
-$(MAKEFLAGS))
MAKEMACROS Contains the complete list of macro
expressions that were specified on the
command line.
MAKETARGETS Contains the name(s) of the target(s), if
any, that were specified on the command
line.
MAKEVERSION Contains a string indicating the current
Version 4.01 PL0 UW 28
DMAKE(p) Unsupported Free Software DMAKE(p)dmake version number.
MAXPROCESSLIMIT Is a numeric string representing the maxi-
mum number of processes that dmake can use
when making targets using parallel mode.
NULL Is permanently defined to be the NULL
string. This is useful when comparing a
conditional expression to an NULL value.
PWD Is the full path to the current directory
in which make is executing.
TMPFILE Is set to the name of the most recent tem-
porary file opened by dmake. Temporary
files are used for text diversions and for
group recipe processing.
TMD Stands for "To Make Dir", and is the path
from the present directory (value of
$(PWD)) to the directory that dmake was
started up in (value of $(MAKEDIR)). This
macro is modified when .SETDIR attributes
are processed.
USESHELL The value of this macro is set to "yes" if
the current recipe is forced to use a
shell for its execution via the .USESHELL
or '+' directives, its value is "no" oth-
erwise.
The second group of string valued macros control dmake
behavior and may be set by the user.
.DIRCACHE If set to "yes" enables the directory
cache (this is the default). If set to
"no" disables the directory cache (equiva-
lent to -d command-line flag).
.DIRCACHERESPCASE
If set to "yes" causes the directory
cache, if enabled, to respect file case,
if set to "no" facilities of the native OS
are used to match file case.
.NAMEMAX Defines the maximum length of a filename
component. The value of the variable is
initialized at startup to the value of the
compiled macro NAME_MAX. On some systems
the value of NAME_MAX is too short by
default. Setting a new value for .NAMEMAX
will override the compiled value.
Version 4.01 PL0 UW 29
DMAKE(p) Unsupported Free Software DMAKE(p)
.NOTABS When set to "yes" enables the use of
spaces as well as <tabs> to begin recipe
lines. By default a non-group recipe is
terminated by a line without any leading
white-space or by a line not beggining
with a <tab> character. Enabling this
mode modifies the first condition of the
above termination rule to terminate a
non-group recipe with a line that contains
only white-space. This mode does not
effect the parsing of group recipes brack-
eted by [].
AUGMAKE If set to "yes" value will enable the
transformation of special meta targets to
support special AUGMAKE inferences (See
the COMPATIBILITY section).
DIRBRKSTR Contains the string of chars used to ter-
minate the name of a directory in a path-
name. Under UNIX its value is "/", under
MSDOS its value is "/\:".
DIRSEPSTR Contains the string that is used to sepa-
rate directory components when path names
are constructed. It is defined with a
default value at startup.
DIVFILE Is defined in the startup file and gives
the name that should be returned for the
diversion file name when used in $(mktmp
...) expansions, see the TEXT DIVERSION
section for details.
DYNAMICNESTINGLEVEL
Specifies the maximum number of recursive
dynamic macro expansions. Its initial
value is 100.
.KEEP_STATE Assigning this macro a value tells dmake
the name of the state file to use and
turns on the keeping of state information
for any targets that are brought up to
date by the make.
GROUPFLAGS This macro gives the set of flags to pass
to the shell when invoking it to execute a
group recipe. The value of the macro is
the list of flags with a leading switch
indicator. (ie. `-' under UNIX)
GROUPSHELL This macro defines the full path to the
executable image to be used as the shell
when processing group recipes. This macro
Version 4.01 PL0 UW 30
DMAKE(p) Unsupported Free Software DMAKE(p)
must be defined if group recipes are used.
It is assigned a default value in the
startup makefile. Under UNIX this value
is /bin/sh.
GROUPSUFFIX If defined, this macro gives the string to
use as a suffix when creating group recipe
files to be handed to the command inter-
preter. For example, if it is defined as
.sh, then all temporary files created by
dmake will end in the suffix .sh. Under
MSDOS if you are using command.com as your
GROUPSHELL, then this suffix must be set
to .bat in order for group recipes to
function correctly. The setting of GROUP-
SUFFIX and GROUPSHELL is done automati-
cally for command.com in the startup.mk
files.
MAKE Is defined in the startup file by default.
Initially this macro is defined to have
the value "$(MAKECMD) $(MFLAGS)". The
string $(MAKE) is recognized when using
the -n switch.
MAKESTARTUP This macro defines the full path to the
initial startup makefile. Use the -V com-
mand line option to discover its initial
value.
MAXLINELENGTH This macro defines the maximum size of a
single line of makefile input text. The
size is specified as a number, the default
value is defined internally and is shown
via the -V option. A buffer of this size
plus 2 is allocated for reading makefile
text. The buffer is freed before any tar-
gets are made, thereby allowing files con-
taining long input lines to be processed
without consuming memory during the actual
make. This macro can only be used to
extend the line length beyond it's default
minimum value.
MAXPROCESS Specify the maximum number of child pro-
cesses to use when making targets. The
default value of this macro is "1" and its
value cannot exceed the value of the macro
MAXPROCESSLIMIT. Setting the value of
MAXPROCESS on the command line or in the
makefile is equivalent to supplying a cor-
responding value to the -P flag on the
command line.
Version 4.01 PL0 UW 31
DMAKE(p) Unsupported Free Software DMAKE(p)
PREP This macro defines the number of itera-
tions to be expanded automatically when
processing % rule definitions of the form:
% : %.suff
See the sections on PERCENT(%) RULES for
details on how PREP is used.
SHELL This macro defines the full path to the
executable image to be used as the shell
when processing single line recipes. This
macro must be defined if recipes requiring
the shell for execution are to be used.
It is assigned a default value in the
startup makefile. Under UNIX this value
is /bin/sh.
SHELLFLAGS This macro gives the set of flags to pass
to the shell when invoking it to execute a
single line recipe. The value of the
macro is the list of flags with a leading
switch indicator. (ie. `-' under UNIX)
SHELLMETAS Each time dmake executes a single recipe
line (not a group recipe) the line is
searched for any occurrence of a character
defined in the value of SHELLMETAS. If
such a character is found the recipe line
is defined to require a shell to ensure
its correct execution. In such instances
a shell is used to invoke the recipe line.
If no match is found the recipe line is
executed without the use of a shell.
There is only one character valued macro defined by dmake:
SWITCHAR contains the switch character used to introduce
options on command lines. For UNIX its value is `-', and
for MSDOS its value may be `/' or `-'. The macro is
internally defined and is not user setable. The MSDOS
version of dmake attempts to first extract SWITCHAR from
an environment variable of the same name. If that fails
it then attempts to use the undocumented getswitchar sys-
tem call, and returns the result of that. Under MSDOS
version 4.0 you must set the value of the environment
macro SWITCHAR to '/' to obtain predictable behavior.
All boolean macros currently understood by dmake corre-
spond directly to the previously defined attributes.
These macros provide a second way to apply global
attributes, and represent the preferred method of doing
so. They are used by assigning them a value. If the
value is not a NULL string then the boolean condition is
Version 4.01 PL0 UW 32
DMAKE(p) Unsupported Free Software DMAKE(p)
set to on. If the value is a NULL string then the condi-
tion is set to off. There are five conditions defined and
they correspond directly to the attributes of the same
name. Their meanings are defined in the ATTRIBUTES sec-
tion above. The macros are: .EPILOG, .IGNORE, .MKSARGS,
.NOINFER, .PRECIOUS, .PROLOG, .SEQUENTIAL, .SILENT, .SWAP,
and .USESHELL. Assigning any of these a non NULL value
will globally set the corresponding attribute to on.
RUNTIME MACROS
These macros are defined when dmake is making targets, and
may take on different values for each target. $@ is
defined to be the full target name, $? is the list of all
out of date prerequisites, $& is the list of all prerequi-
sites, $> is the name of the library if the current target
is a library member, and $< is the list of prerequisites
specified in the current rule. If the current target had
a recipe inferred then $< is the name of the inferred pre-
requisite even if the target had a list of prerequisites
supplied using an explicit rule that did not provide a
recipe. In such situations $& gives the full list of pre-
requisites.
$* is defined as $(@:db) when making targets with explicit
recipes and is defined as the value of % when making tar-
gets whose recipe is the result of an inference. In the
first case $* is the target name with no suffix, and in
the second case, is the value of the matched % pattern
from the associated %-rule. $^ expands to the set of out
of date prerequisites taken from the current value of $<.
In addition to these, $$ expands to $, {{ expands to {, }}
expands to }, and the strings <+ and +> are recognized as
respectively starting and terminating a text diversion
when they appear literally together in the same input
line.
The difference between $? and $^ can best be illustrated
by an example, consider:
fred.out : joe amy hello
rules for making fred
fred.out : my.c your.h his.h her.h # more prerequisites
Assume joe, amy, and my.c are newer then fred.out. When
dmake executes the recipe for making fred.out the values
of the following macros will be:
$@ --> fred.out
$* --> fred
$? --> joe amy my.c # note output of $? vs $^
$^ --> joe amy
$< --> joe amy hello
$& --> joe amy hello my.c your.h his.h her.h
Version 4.01 PL0 UW 33
DMAKE(p) Unsupported Free Software DMAKE(p)FUNCTION MACROSdmake supports a full set of functional macros. One of
these, the $(mktmp ...) macro, is discussed in detail in
the TEXT DIVERSION section and is not covered here.
$(and macroterm ...)
expands each macroterm in turn until there
are no more or one of them returns an empty
string. If all expand to non-empty strings
the macro returs the string "t" otherwise it
returns an empty string.
$(assign expression)
Causes expression to be parsed as a macro
assignment expression and results in the
specified assignment being made. An error
is issued if the assignment is not syntati-
cally correct. expression may contain white
space. This is in effect a dynamic macro
assignment facility and may appear anywhere
any other macro may appear. The result of
the expanding a dynamic macro assignment
expression is the name of the macro that was
assigned and $(NULL) if the expression is
not a valid macro assignment expression.
Some examples are:
$(assign foo := fred)
$(assign $(ind_macro_name) +:= $(morejunk))
$(echo list)
Echo's the value of list. list is not
expanded.
$(eq,text_a,text_b true false)
expands text_a and text_b and compares their
results. If equal it returns the result of
the expansion of the true term, otherwise it
returns the expansion of the false term.
$(!eq,text_a,text_b true false)
Behaves identically to the previous macro
except that the true string is chosen if the
expansions of the two strings are not equal
$(foreach,var,list data)
Implements iterative macro expansion over
data using var as the iterator taking on
values from list. var and list are expanded
and the result is the concatenation of
expanding data with var being set to each
whitespace separated token from list. For
Version 4.01 PL0 UW 34
DMAKE(p) Unsupported Free Software DMAKE(p)
example:
list = a b c
all :; echo [$(foreach,i,$(list) [$i])]
will output
[[a] [b] [c]]
The iterator variable is defined as a local
variable to this foreach instance. The fol-
lowing expression illustrates this:
$(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h])
when evaluated the result is:
[root/a/f.h] [root/b/f.h] [root/c/f.h]
The specification of list must be a valid
macro expression, such as:
$($(assign list=a b c))
$(sort d a b c)
$(echo a b c)
and cannot just be the list itself. That
is, the following foreach expression:
$(foreach,i,a b c [$i])
yields:
"b c [a]"
when evaluated.
$(nil expression)
Always returns the value of $(NULL) regard-
less of what expression is. This function
macro can be used to discard results of
expanding macro expressions.
$(not macroterm)
expands macroterm and returs the string "t"
if the result of the expansion is the empty
string; otherwise, it returns the empty
string.
$(null,text true false)
expands the value of text. If it is NULL
then the macro returns the value of the
expansion of true and the expansion of false
otherwise. The terms true, and false must
Version 4.01 PL0 UW 35
DMAKE(p) Unsupported Free Software DMAKE(p)
be strings containing no white-space.
$(!null,text true false)
Behaves identically to the previous macro
except that the true string is chosen if the
expansion of text is not NULL.
$(or macroterm ...)
expands each macroterm in turn and returs
the empty string if each term expands to the
empty string; otherwise, it returs the
string "t".
$(shell command)
Runs command as if it were part of a recipe
and returns, separated by a single space,
all the non-white space terms written to
stdout by the command. For example:
$(shell ls *.c)
will return "a.c b.c c.c d.c" if the files
exist in the current directory. The recipe
modification flags [+@%-] are honored if
they appear as the first characters in the
command. For example:
$(shell +ls *.c)
will run the command using the current
shell.
$(shell,expand command)
Is an extension to the $(shell... function
macro that expands the result of running
command.
$(sort list)
Will take all white-space separated tokens
in list and will return their sorted equiva-
lent list.
$(strip data)
Will replace all strings of white-space in
data by a single space.
$(subst,pat,replacement data)
Will search for pat in data and will replace
any occurrence of pat with the replacement
string. The expansion
$(subst,.o,.c $(OBJECTS))
is equivalent to:
Version 4.01 PL0 UW 36
DMAKE(p) Unsupported Free Software DMAKE(p)
$(OBJECTS:s/.o/.c/)
$(uniq list)
Will take all white-space separated tokens
in list and will return their sorted equiva-
lent list containing no duplicates.
CONDITIONAL MACROSdmake supports conditional macros. These allow the defi-
nition of target specific macro values. You can now say
the following:
target ?= MacroName MacroOp Value
This creates a definition for MacroName whose value is
Value only when target is being made. You may use a con-
ditional macro assignment anywhere that a regular macro
assignment may appear, including as the value of a
$(assign ...) macro.
The new definition is associated with the most recent cell
definition for target. If no prior definition exists then
one is created. The implications of this are immediately
evident in the following example:
foo := hello
all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]"
cond ?= bar := global decl
cond .SETDIR=unix::;@echo $(foo) $(bar)
cond ?= foo := hi
cond .SETDIR=msdos::;@echo $(foo) $(bar)
cond ?= foo := hihi
The first conditional assignment creates a binding for
'bar' that is activated when 'cond' is made. The bindings
following the :: definitions are activated when their
respective recipe rules are used. Thus the first binding
serves to provide a global value for 'bar' while any of
the cond :: rules are processed, and the local bindings
for 'foo' come into effect when their associated :: rule
is processed.
Conditionals for targets of .UPDATEALL are all activated
before the target group is made. Assignments are pro-
cessed in order. Note that the value of a conditional
macro assignment is NOT AVAILABLE until the associated
target is made, thus the construct
mytarget ?= bar := hello
Version 4.01 PL0 UW 37
DMAKE(p) Unsupported Free Software DMAKE(p)
mytarget ?= foo := $(bar)
results in $(foo) expanding to "", if you want the result
to be "hello" you must use:
mytarget ?= bar := hello
mytarget ?= foo = $(bar)
Once a target is made any associated conditional macros
are deactivated and their values are no longer available.
Activation occurrs after all inference, and .SETDIR direc-
tives have been processed and after $@ is assigned, but
before prerequisites are processed; thereby making the
values of conditional macro definitions available during
construction of prerequisites.
If a %-meta rule target has associated conditional macro
assignments, and the rule is chosen by the inference algo-
rithm then the conditional macro assignments are inferred
together with the associated recipe.
DYNAMIC PREREQUISITESdmake looks for prerequisites whose names contain macro
expansions during target processing. Any such prerequi-
sites are expanded and the result of the expansion is used
as the prerequisite name. As an example the line:
fred : $$@.c
causes the $$@ to be expanded when dmake is making fred,
and it resolves to the target fred. This enables dynamic
prerequisites to be generated. The value of @ may be mod-
ified by any of the valid macro modifiers. So you can say
for example:
fred.out : $$(@:b).c
where the $$(@:b) expands to fred. Note the use of $$
instead of $ to indicate the dynamic expansion, this is
due to the fact that the rule line is expanded when it is
initially parsed, and $$ then returns $ which later trig-
gers the dynamic prerequisite expansion. If you really
want a $ to be part of a prerequisite name you must use
$$$$. Dynamic macro expansion is performed in all user
defined rules, and the special targets .SOURCE*, and
.INCLUDEDIRS.
If dynamic macro expansion results in multiple white space
separated tokens then these are inserted into the prereq-
uisite list inplace of the dynamic prerequisite. If the
new list contains additional dynamic prerequisites they
will be expanded when they are processed. The level of
recursion in this expansion is controlled by the value of
the variable DYNAMICNESTINGLEVEL and is set to 100 by
Version 4.01 PL0 UW 38
DMAKE(p) Unsupported Free Software DMAKE(p)
default.
BINDING TARGETS
This operation takes a target name and binds it to an
existing file, if possible. dmake makes a distinction
between the internal target name of a target and its asso-
ciated external file name. Thus it is possible for a tar-
get's internal name and its external file name to differ.
To perform the binding, the following set of rules is
used. Assume that we are trying to bind a target whose
name is of the form X.suff, where .suff is the suffix and
X is the stem portion (ie. that part which contains the
directory and the basename). dmake takes this target name
and performs a series of search operations that try to
find a suitably named file in the external file system.
The search operation is user controlled via the settings
of the various .SOURCE targets.
1. If target has the .SYMBOL attribute set then
look for it in the library. If found,
replace the target name with the library
member name and continue with step 2. If
the name is not found then return.
2. Extract the suffix portion (that following
the `.') of the target name. If the suffix
is not null, look up the special target
.SOURCE.<suff> (<suff> is the suffix). If
the special target exists then search each
directory given in the .SOURCE.<suff> pre-
requisite list for the target. If the tar-
get's suffix was null (ie. .suff was empty)
then perform the above search but use the
special target .SOURCE.NULL instead. If at
any point a match is found then terminate
the search. If a directory in the prerequi-
site list is the special name `.NULL ' per-
form a search for the full target name with-
out prepending any directory portion (ie.
prepend the NULL directory).
3. The search in step 2. failed. Repeat the
same search but this time use the special
target .SOURCE. (a default target of
'.SOURCE : .NULL' is defined by dmake at
startup, and is user redefinable)
4. The search in step 3. failed. If the target
has the library member attribute (.LIBMEM-
BER) set then try to find the target in the
library which was passed along with the
.LIBMEMBER attribute (see the MAKING
LIBRARIES section). The bound file name
assigned to a target which is successfully
Version 4.01 PL0 UW 39
DMAKE(p) Unsupported Free Software DMAKE(p)
located in a library is the same name that
would be assigned had the search failed (see
5.).
5. The search failed. Either the target was
not found in any of the search directories
or no applicable .SOURCE special targets
exist. If applicable .SOURCE special tar-
gets exist, but the target was not found,
then dmake assigns the first name searched
as the bound file name. If no applicable
.SOURCE special targets exist, then the full
original target name becomes the bound file
name.
There is potential here for a lot of search operations.
The trick is to define .SOURCE.x special targets with
short search lists and leave .SOURCE as short as possible.
The search algorithm has the following useful side effect.
When a target having the .LIBMEMBER (library member)
attribute is searched for, it is first searched for as an
ordinary file. When a number of library members require
updating it is desirable to compile all of them first and
to update the library at the end in a single operation.
If one of the members does not compile and dmake stops,
then the user may fix the error and make again. dmake
will not remake any of the targets whose object files have
already been generated as long as none of their prerequi-
site files have been modified as a result of the fix.
When dmake constructs target pathnames './' substrings are
removed and substrings of the form 'foo/..' are elimi-
nated. This may result in somewhat unexpected values of
the macro expansion $@, but is infact the corect result.
When defining .SOURCE and .SOURCE.x targets the construct
is equivalent to
dmake correctly handles the UNIX Make variable VPATH. By
definition VPATH contains a list of ':' separated directo-
ries to search when looking for a target. dmake maps
VPATH to the following special rule:
Which takes the value of VPATH and sets .SOURCE to the
same set of directories as specified in VPATH.
PERCENT(%) RULES AND MAKING INFERENCES
When dmake makes a target, the target's set of prerequi-
sites (if any) must exist and the target must have a
recipe which dmake can use to make it. If the makefile
Version 4.01 PL0 UW 40
DMAKE(p) Unsupported Free Software DMAKE(p)
does not specify an explicit recipe for the target then
dmake uses special rules to try to infer a recipe which it
can use to make the target. Previous versions of Make
perform this task by using rules that are defined by tar-
gets of the form .<suffix>.<suffix> and by using the .SUF-
FIXES list of suffixes. The exact workings of this mecha-
nism were sometimes difficult to understand and often lim-
iting in their usefulness. Instead, dmake supports the
concept of %-meta rules. The syntax and semantics of
these rules differ from standard rule lines as follows:
<%-target> [<attributes>] <ruleop> [<%-prerequisites>] [;<recipe>]
where %-target is a target containing exactly a single `%'
sign, attributes is a list (possibly empty) of attributes,
ruleop is the standard set of rule operators, %-prerequi-
sites , if present, is a list of prerequisites containing
zero or more `%' signs, and recipe, if present, is the
first line of the recipe.
The %-target defines a pattern against which a target
whose recipe is being inferred gets matched. The pattern
match goes as follows: all chars are matched exactly from
left to right up to but not including the % sign in the
pattern, % then matches the longest string from the actual
target name not ending in the suffix given after the %
sign in the pattern. Consider the following examples:
%.c matches fred.c but not joe.c.Z
dir/%.c matches dir/fred.c but not dd/fred.c
fred/% matches fred/joe.c but not f/joe.c
% matches anything
In each case the part of the target name that matched the
% sign is retained and is substituted for any % signs in
the prerequisite list of the %-meta rule when the rule is
selected during inference and dmake constructs the new
dependency. As an example the following %-meta rules
describe the following:
%.c : %.y ; recipe...
describes how to make any file ending in .c if a corre-
sponding file ending in .y can be found.
foo%.o : fee%.k ; recipe...
is used to describe how to make fooxxxx.o from feexxxx.k.
%.a :; recipe...
describes how to make a file whose suffix is .a without
inferring any prerequisites.
Version 4.01 PL0 UW 41
DMAKE(p) Unsupported Free Software DMAKE(p)
%.c : %.y yaccsrc/%.y ; recipe...
is a short form for the construct:
%.c : %.y ; recipe...
%.c : yaccsrc/%.y ; recipe...
ie. It is possible to specify the same recipe for two
%-rules by giving more than one prerequisite in the pre-
requisite list. A more interesting example is:
% : RCS/%,v ; co $<
which describes how to take any target and check it out of
the RCS directory if the corresponding file exists in the
RCS directory. The equivalent SCCS rule would be:
% : s.% ; get $<
The previous RCS example defines an infinite rule, because
it says how to make anything from RCS/%,v, and anything
also includes RCS/fred.c,v. To limit the size of the
graph that results from such rules dmake uses the macro
variable PREP (stands for % repetition). By default the
value of this variable is 0, which says that no repeti-
tions of a %-rule are to be generated. If it is set to
something greater than 0, then that many repetitions of
any infinite %-rule are allowed. If in the above example
PREP was set to 1, then dmake would generate the depen-
dency graph:
% --> RCS/%,v --> RCS/RCS/%,v,v
Where each link is assigned the same recipe as the first
link. PREP should be used only in special cases, since it
may result in a large increase in the number of possible
prerequisites tested. dmake further assumes that any tar-
get that has no suffix can be made from a prerequisite
that has at least one suffix.
dmake supports dynamic prerequisite generation for prereq-
uisites of %-meta rules. This is best illustrated by an
example. The RCS rule shown above can infer how to check
out a file from a corresponding RCS file only if the tar-
get is a simple file name with no directory information.
That is, the above rule can infer how to find RCS/fred.c,v
from the target fred.c, but cannot infer how to find
srcdir/RCS/fred.c,v from srcdir/fred.c because the above
rule will cause dmake to look for RCS/srcdir/fred.c,v;
which does not exist (assume that srcdir has its own RCS
directory as is the common case).
A more versatile formulation of the above RCS check out
Version 4.01 PL0 UW 42
DMAKE(p) Unsupported Free Software DMAKE(p)
rule is the following:
% : $$(@:d)RCS/$$(@:f),v : co $@
This rule uses the dynamic macro $@ to specify the prereq-
uisite to try to infer. During inference of this rule the
macro $@ is set to the value of the target of the %-meta
rule and the appropriate prerequisite is generated by
extracting the directory portion of the target name (if
any), appending the string RCS/ to it, and appending the
target file name with a trailing ,v attached to the previ-
ous result.
dmake can also infer indirect prerequisites. An inferred
target can have a list of prerequisites added that will
not show up in the value of $< but will show up in the
value of $? and $&. Indirect prerequisites are specified
in an inference rule by quoting the prerequisite with sin-
gle quotes. For example, if you had the explicit depen-
dency:
fred.o : fred.c ; rule to make fred.o
fred.o : local.h
then this can be inferred for fred.o from the following
inference rule:
%.o : %.c 'local.h' ; makes a .o from a .c
You may infer indirect prerequisites that are a function
of the value of '%' in the current rule. The meta-rule:
%.o : %.c '$(INC)/%.h' ; rule to make a .o from a
.c
infers an indirect prerequisite found in the INC directory
whose name is the same as the expansion of $(INC), and the
prerequisite name depends on the base name of the current
target. The set of indirect prerequisites is attached to
the meta rule in which they are specified and are inferred
only if the rule is used to infer a recipe for a target.
They do not play an active role in driving the inference
algorithm. The construct:
%.o : %.c %.f 'local.h'; recipe
is equivalent to:
%.o : %.c 'local.h' : recipe
while:
%.o :| %.c %.f 'local.h'; recipe
Version 4.01 PL0 UW 43
DMAKE(p) Unsupported Free Software DMAKE(p)
is equivalent to:
%.o : %.c 'local.h' : recipe
%.o : %.f 'local.h' : recipe
If any of the attributes .SETDIR, .EPILOG, .PROLOG,
.SILENT, .USESHELL, .SWAP, .PRECIOUS, .LIBRARY, .NOSTATE
and .IGNORE are given for a %-rule then when that rule is
bound to a target as the result of an inference, the tar-
get's set of attributes is augmented by the attributes
from the above set that are specified in the bound %-rule.
Other attributes specified for %-meta rules are not inher-
ited by the target. The .SETDIR attribute is treated in a
special way. If the target already had a .SETDIR
attribute set then dmake changes to that directory prior
to performing the inference. During inference any .SETDIR
attributes for the inferred prerequisite are honored. The
directories must exist for a %-meta rule to be selected as
a possible inference path. If the directories do not
exist no error message is issued, instead the correspond-
ing path in the inference graph is rejected.
dmake also supports the old format special target .<suf-
fix>.<suffix> by identifying any rules of this form and
mapping them to the appropriate %-rule. So for example if
an old makefile contains the construct:
.c.o :; cc -c $< -o $@
dmake maps this into the following %-rule:
%.o : %.c; cc -c $< -o $@
Furthermore, dmake understands several SYSV AUGMAKE spe-
cial targets and maps them into corresponding %-meta
rules. These transformation must be enabled by providing
the -A flag on the command line or by setting the value of
AUGMAKE to non-NULL. The construct
.suff :; recipe
gets mapped into:
% : %.suff; recipe
and the construct
.c~.o :; recipe
gets mapped into:
%.o : s.%.c ; recipe
Version 4.01 PL0 UW 44
DMAKE(p) Unsupported Free Software DMAKE(p)
In general, a special target of the form .<str>~ is
replaced by the %-rule construct s.%.<str>, thereby pro-
viding support for the syntax used by SYSV AUGMAKE for
providing SCCS support. When enabled, these mappings
allow processing of existing SYSV makefiles without modi-
fications.
dmake bases all of its inferences on the inference graph
constructed from the %-rules defined in the makefile. It
knows exactly which targets can be made from which prereq-
uisites by making queries on the inference graph. For
this reason .SUFFIXES is not needed and is completely
ignored.
For a %-meta rule to be inferred as the rule whose recipe
will be used to make a target, the target's name must
match the %-target pattern, and any inferred %-prerequi-
site must already exist or have an explicit recipe so that
the prerequisite can be made. Without transitive closure
on the inference graph the above rule describes precisely
when an inference match terminates the search. If transi-
tive closure is enabled (the usual case), and a prerequi-
site does not exist or cannot be made, then dmake invokes
the inference algorithm recursively on the prerequisite to
see if there is some way the prerequisite can be manufac-
tured. For, if the prerequisite can be made then the cur-
rent target can also be made using the current %-meta
rule. This means that there is no longer a need to give a
rule for making a .o from a .y if you have already given a
rule for making a .o from a .c and a .c from a .y. In
such cases dmake can infer how to make the .o from the .y
via the intermediary .c and will remove the .c when the .o
is made. Transitive closure can be disabled by giving the
-T switch on the command line.
A word of caution. dmake bases its transitive closure on
the %-meta rule targets. When it performs transitive clo-
sure it infers how to make a target from a prerequisite by
performing a pattern match as if the potential prerequi-
site were a new target. The set of rules:
%.o : %.c :; rule for making .o from .c
%.c : %.y :; rule for making .c from .y
% : RCS/%,v :; check out of RCS file
will, by performing transitive closure, allow dmake to
infer how to make a .o from a .y using a .c as an interme-
diate temporary file. Additionally it will be able to
infer how to make a .y from an RCS file, as long as that
RCS file is in the RCS directory and has a name which ends
in .y,v. The transitivity computation is performed dynam-
ically for each target that does not have a recipe. This
has potential to be costly if the %-meta rules are not
carefully specified. The .NOINFER attribute is used to
Version 4.01 PL0 UW 45
DMAKE(p) Unsupported Free Software DMAKE(p)
mark a %-meta node as being a final target during infer-
ence. Any node with this attribute set will not be used
for subsequent inferences. As an example the node RCS/%,v
is marked as a final node since we know that if the RCS
file does not exist there likely is no other way to make
it. Thus the standard startup makefile contains an entry
similar to:
.NOINFER : RCS/%,v
Thereby indicating that the RCS file is the end of the
inference chain. Whenever the inference algorithm deter-
mines that a target can be made from more than one prereq-
uisite and the inference chains for the two methods are
the same length the algorithm reports an ambiguity and
prints the ambiguous inference chains.
dmake tries to remove intermediate files resulting from
transitive closure if the file is not marked as being PRE-
CIOUS, or the -u flag was not given on the command line,
and if the inferred intermediate did not previously exist.
Intermediate targets that existed prior to being made are
never removed. This is in keeping with the philosophy
that dmake should never remove things from the file system
that it did not add. If the special target .REMOVE is
defined and has a recipe then dmake constructs a list of
the intermediate files to be removed and makes them pre-
requisites of .REMOVE. It then makes .REMOVE thereby
removing the prerequisites if the recipe of .REMOVE says
to. Typically .REMOVE is defined in the startup file as:
.REMOVE :; $(RM) $<
MAKING TARGETS
In order to update a target dmake must execute a recipe.
When a recipe needs to be executed it is first expanded so
that any macros in the recipe text are expanded, and it is
then either executed directly or passed to a shell. dmake
supports two types of recipes. The regular recipes and
group recipes.
When a regular recipe is invoked dmake executes each line
of the recipe separately using a new copy of a shell if a
shell is required. Thus effects of commands do not gener-
ally persist across recipe lines (e.g. cd requests in a
recipe line do not carry over to the next recipe line).
This is true even in environments such as MSDOS, where
dmake internally sets the current working director to
match the directory it was in before the command was exe-
cuted.
The decision on whether a shell is required to execute a
command is based on the value of the macro SHELLMETAS or
on the specification of '+' or .USESHELL for the current
recipe or target respectively. If any character in the
value of SHELLMETAS is found in the expanded recipe text-
Version 4.01 PL0 UW 46
DMAKE(p) Unsupported Free Software DMAKE(p)
line or the use of a shell is requested explicitly via '+'
or .USESHELL then the command is executed using a shell,
otherwise the command is executed directly. The shell
that is used for execution is given by the value of the
macro SHELL. The flags that are passed to the shell are
given by the value of SHELLFLAGS. Thus dmake constructs
the command line:
$(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
Normally dmake writes the command line that it is about to
invoke to standard output. If the .SILENT attribute is
set for the target or for the recipe line (via @), then
the recipe line is not echoed.
Group recipe processing is similar to that of regular
recipes, except that a shell is always invoked. The shell
that is invoked is given by the value of the macro GROUP-
SHELL, and its flags are taken from the value of the macro
GROUPFLAGS. If a target has the .PROLOG attribute set
then dmake prepends to the shell script the recipe associ-
ated with the special target .GROUPPROLOG, and if the
attribute .EPILOG is set as well, then the recipe associ-
ated with the special target .GROUPEPILOG is appended to
the script file. This facility can be used to always
prepend a common header and common trailer to group
recipes. Group recipes are echoed to standard output just
like standard recipes, but are enclosed by lines beginning
with [ and ].
The recipe flags [+,-,%,@] are recognized at the start of
a recipe line even if they appear in a macro. For exam-
ple:
SH = +
all:
$(SH)echo hi
is completely equivalent to writing
SH = +
all:
+echo hi
The last step performed by dmake prior to running a recipe
is to set the macro CMNDNAME to the name of the command to
execute (determined by finding the first white-space end-
ing token in the command line). It then sets the macro
CMNDARGS to be the remainder of the line. dmake then
expands the macro COMMAND which by default is set to
COMMAND = $(CMNDNAME) $(CMNDARGS)
Version 4.01 PL0 UW 47
DMAKE(p) Unsupported Free Software DMAKE(p)
The result of this final expansion is the command that
will be executed. The reason for this expansion is to
allow for a different interface to the argument passing
facilities (esp. under DOS) than that provided by dmake.
You can for example define COMMAND to be
COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
which dumps the arguments into a temporary file and runs
the command
$(CMNDNAME) @/tmp/ASAD23043
which has a much shorter argument list. It is now up to
the command to use the supplied argument as the source for
all other arguments. As an optimization, if COMMAND is
not defined dmake does not perform the above expansion.
On systems, such as UNIX, that handle long command lines
this provides a slight saving in processing the makefiles.
MAKING LIBRARIES
Libraries are easy to maintain using dmake. A library is
a file containing a collection of object files. Thus to
make a library you simply specify it as a target with the
.LIBRARY attribute set and specify its list of prerequi-
sites. The prerequisites should be the object members
that are to go into the library. When dmake makes the
library target it uses the .LIBRARY attribute to pass to
the prerequisites the .LIBMEMBER attribute and the name of
the library. This enables the file binding mechanism to
look for the member in the library if an appropriate
object file cannot be found. dmake now supports Elf
libraries on systems that support Elf and hence supports,
on those systems, long member file names. A small example
best illustrates this.
mylib.a .LIBRARY : mem1.o mem2.o mem3.o
rules for making library...
# remember to remove .o's when lib is made
# equivalent to: '%.o : %.c ; ...'
.c.o :; rules for making .o from .c say
dmake will use the .c.o rule for making the library mem-
bers if appropriate .c files can be found using the search
rules. NOTE: this is not specific in any way to C pro-
grams, they are simply used as an example.
dmake tries to handle the old library construct format in
a sensible way. The construct lib(member.o) is separated
and the lib portion is declared as a library target. The
new target is defined with the .LIBRARY attribute set and
the member.o portion of the construct is declared as a
prerequisite of the lib target. If the construct
Version 4.01 PL0 UW 48
DMAKE(p) Unsupported Free Software DMAKE(p)
lib(member.o) appears as a prerequisite of a target in the
makefile, that target has the new name of the lib assigned
as its prerequisite. Thus the following example:
a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@ $<
.c.o :; $(CC) -c $(CFLAGS) -o $@ $<
%.a:
ar rv $@ $?
ranlib $@
rm -rf $?
constructs the following dependency graph.
a.out : ml.a; $(CC) -o $@ $<
ml.a .LIBRARY : a.o b.o
%.o : %.c ; $(CC) -c $(CFLAGS) -o $@ $<
%.a :
ar rv $@ $?
ranlib $@
rm -rf $?
and making a.out then works as expected.
The same thing happens for any target of the form
lib((entry)). These targets have an additional feature in
that the entry target has the .SYMBOL attribute set auto-
matically.
NOTE: If the notion of entry points is supported by the
archive and by dmake (currently not the case) then dmake
will search the archive for the entry point and return not
only the modification time of the member which defines the
entry but also the name of the member file. This name
will then replace entry and will be used for making the
member file. Once bound to an archive member the .SYMBOL
attribute is removed from the target. This feature is
presently disabled as there is little standardization
among archive formats, and we have yet to find a makefile
utilizing this feature (possibly due to the fact that it
is unimplemented in most versions of UNIX Make).
Finally, when dmake looks for a library member it must
first locate the library file. It does so by first look-
ing for the library relative to the current directory and
if it is not found it then looks relative to the current
value of $(TMD). This allows commonly used libraries to
be kept near the root of a source tree and to be easily
found by dmake.
KEEP STATEdmake supports the keeping of state information for tar-
gets that it makes whenever the macro .KEEP_STATE is
Version 4.01 PL0 UW 49
DMAKE(p) Unsupported Free Software DMAKE(p)
assigned a value. The value of the macro should be the
name of a state file that will contain the state informa-
tion. If state keeping is enabled then each target that
does not poses the .NOSTATE attribute will have a record
written into the state file indicating the target's name,
the current directory, the command used to update the tar-
get, and which, if any, :: rule is being used. When you
make this target again if any of this information does not
match the previous settings and the target is not out
dated it will still be re-made. The assumption is that
one of the conditions above has changed and that we wish
to remake the target. For example, state keeping is used
in the maintenance of dmake to test compile different ver-
sions of the source using different compilers. Changing
the compiler causes the compilation flags to be modified
and hence all sources to be recompiled.
The state file is an ascii file and is portable, however
it is not in human readable form as the entries represent
hash keys of the above information.
The Sun Microsystem's Make construct
.KEEP_STATE :
is recognized and is mapped to .KEEP_STATE:=_state.mk.
The dmake version of state keeping does not include scan-
ning C source files for dependencies like Sun Make. This
is specific to C programs and it was felt that it does not
belong in make. dmake instead provides the tool, cdepend,
to scan C source files and to produce depedency informa-
tion. Users are free to modify cdepend to produce other
dependency files. (NOTE: cdepend does not come with the
distribution at this time, but will be available in a
patch in the near future)
MULTI PROCESSING
If the architecture supports it then dmake is capable of
making a target's prerequisites in parallel. dmake will
make as much in parallel as it can and use a number of
child processes up to the maximum specified by MAXPROCESS
or by the value supplied to the -P command line flag. A
parallel make is enabled by setting the value of MAXPRO-
CESS (either directly or via -P option) to a value which
is > 1. dmake guarantees that all dependencies as speci-
fied in the makefile are honored. A target will not be
made until all of its prerequisites have been made. Note
that when you specify -P 4 then four child processes are
run concurrently but dmake actually displays the fifth
command it will run immediately upon a child process
becomming free. This is an artifact of the method used to
traverse the dependency graph and cannot be removed. If a
parallel make is being performed then the following
restrictions on parallelism are enforced.
Version 4.01 PL0 UW 50
DMAKE(p) Unsupported Free Software DMAKE(p)
1. Individual recipe lines in a non-group
recipe are performed sequentially in the
order in which they are specified within the
makefile and in parallel with the recipes of
other targets.
2. If a target contains multiple recipe defini-
tions (cf. :: rules) then these are per-
formed sequentially in the order in which
the :: rules are specified within the make-
file and in parallel with the recipes of
other targets.
3. If a target rule contains the `!' modifier,
then the recipe is performed sequentially
for the list of outdated prerequisites and
in parallel with the recipes of other tar-
gets.
4. If a target has the .SEQUENTIAL attribute
set then all of its prerequisites are made
sequentially relative to one another (as if
MAXPROCESS=1), but in parallel with other
targets in the makefile.
Note: If you specify a parallel make then the order of
target update and the order in which the associated
recipes are invoked will not correspond to that displayed
by the -n flag.
CONDITIONALSdmake supports a makefile construct called a conditional.
It allows the user to conditionally select portions of
makefile text for input processing and to discard other
portions. This becomes useful for writing makefiles that
are intended to function for more than one target host and
environment. The conditional expression is specified as
follows:
.IF expression
... if text ...
.ELIF expression
... if text ...
.ELSE
... else text ...
.END
The .ELSE and .ELIF portions are optional, and the condi-
tionals may be nested (ie. the text may contain another
conditional). .IF, .ELSE, and .END may appear anywhere in
the makefile, but a single conditional expression may not
span multiple makefiles.
expression can be one of the following three forms:
Version 4.01 PL0 UW 51
DMAKE(p) Unsupported Free Software DMAKE(p)
<text> | <text> == <text> | <text> != <text>
where text is either text or a macro expression. In any
case, before the comparison is made, the expression is
expanded. The text portions are then selected and com-
pared. White space at the start and end of the text por-
tion is discarded before the comparison. This means that
a macro that evaluates to nothing but white space is con-
sidered a NULL value for the purpose of the comparison.
In the first case the expression evaluates TRUE if the
text is not NULL otherwise it evaluates FALSE. The
remaining two cases both evaluate the expression on the
basis of a string comparison. If a macro expression needs
to be equated to a NULL string then compare it to the
value of the macro $(NULL). You can use the $(shell ...)
macro to construct more complex test expressions.
EXAMPLES
# A simple example showing how to use make
#
prgm : a.o b.o
cc a.o b.o -o prgm
a.o : a.c g.h
cc a.c -o $@
b.o : b.c g.h
cc b.c -o $@
In the previous example prgm is remade only if a.o and/or
b.o is out of date with respect to prgm. These dependen-
cies can be stated more concisely by using the inference
rules defined in the standard startup file. The default
rule for making .o's from .c's looks something like this:
%.o : %.c; cc -c $(CFLAGS) -o $@ $<
Since there exists a rule (defined in the startup file)
for making .o's from .c's dmake will use that rule for
manufacturing a .o from a .c and we can specify our depen-
dencies more concisely.
prgm : a.o b.o
cc -o prgm $<
a.o b.o : g.h
A more general way to say the above using the new macro
expansions would be:
SRC = a b
OBJ = {$(SRC)}.o
prgm : $(OBJ)
cc -o $@ $<
$(OBJ) : g.h
Version 4.01 PL0 UW 52
DMAKE(p) Unsupported Free Software DMAKE(p)
If we want to keep the objects in a separate directory,
called objdir, then we would write something like this.
SRC = a b
OBJ = {$(SRC)}.o
prgm : $(OBJ)
cc $< -o $@
$(OBJ) : g.h
%.o : %.c
$(CC) -c $(CFLAGS) -o $(@:f) $<
mv $(@:f) objdir
.SOURCE.o : objdir # tell dmake to look here for .o's
An example of building library members would go something
like this: (NOTE: The same rules as above will be used to
produce .o's from .c's)
SRC= a b
LIB= lib
LIBm= { $(SRC) }.o
prgm: $(LIB)
cc -o $@ $(LIB)
$(LIB) .LIBRARY : $(LIBm)
ar rv $@ $<
rm $<
Finally, suppose that each of the source files in the pre-
vious example had the `:' character in their target name.
Then we would write the above example as:
SRC= f:a f:b
LIB= lib
LIBm= "{ $(SRC) }.o" # put quotes around each token
prgm: $(LIB)
cc -o $@ $(LIB)
$(LIB) .LIBRARY : $(LIBm)
ar rv $@ $<
rm $<
COMPATIBILITY
There are two notable differences between dmake and the
standard version of BSD UNIX 4.2/4.3 Make.
1. BSD UNIX 4.2/4.3 Make supports wild card file-
name expansion for prerequisite names. Thus if
a directory contains a.h, b.h and c.h, then a
line like
Version 4.01 PL0 UW 53
DMAKE(p) Unsupported Free Software DMAKE(p)
target: *.h
will cause UNIX make to expand the *.h into "a.h
b.h c.h". dmake does not support this type of
filename expansion.
2. Unlike UNIX make, touching a library member
causes dmake to search the library for the mem-
ber name and to update the library time stamp.
This is only implemented in the UNIX version.
MSDOS and other versions may not have librarians
that keep file time stamps, as a result dmake
touches the library file itself, and prints a
warning.
dmake is not compatible with GNU Make. In particular it
does not understand GNU Make's macro expansions that query
the file system.
dmake is fully compatible with SYSV AUGMAKE, and supports
the following AUGMAKE features:
1. GNU Make style include, and if/else/endif direc-
tives are allowed in non-group recipes. Thus,
the word include appearing at the start of a
line that is not part of a gruop recipe will be
mapped to the ".INCLUDE" directive that damke
uses. Similarly, the words
ifeq,ifneq,elif,else, and endif are mapped to
their corresponding dmake equivalents.
2. The macro modifier expression $(macro:str=sub)
is understood and is equivalent to the expres-
sion $(macro:s/str/sub), with the restriction
that str must match the following regular
expression:
str[ |\t][ |\t]*
(ie. str only matches at the end of a token
where str is a suffix and is terminated by a
space, a tab, or end of line) Normally sub is
expanded before the substitution is made, if you
specify -A on the command line then sub is not
expanded.
3. The macro % is defined to be $@ (ie. $% expands
to the same value as $@).
4. The AUGMAKE notion of libraries is handled cor-
rectly.
5. When defining special targets for the inference
rules and the AUGMAKE special target handling is
Version 4.01 PL0 UW 54
DMAKE(p) Unsupported Free Software DMAKE(p)
enabled then the special target .X is equivalent
to the %-rule "% : %.X".
6. Directories are always made if you specify -A.
This is consistent with other UNIX versions of
Make.
7. Makefiles that utilize virtual targets to force
making of other targets work as expected if AUG-
MAKE special target handling is enabled. For
example:
FRC:
myprog.o : myprog.c $(FRC) ; ...
Works as expected if you issue the command
'dmake -A FRC=FRC'
but fails with a 'don't know how to make FRC'
error message if you do not specify AUGMAKE spe-
cial target handling via the -A flag (or by set-
ting AUGMAKE:=yes internally).
8. The MSDOS version of dmake now supports a single
buitin runtime command noop, which returns suc-
cess if requested and does nothing.
LIMITS
In some environments the length of an argument string is
restricted. (e.g. MSDOS command line arguments cannot be
longer than 128 bytes if you are using the standard com-
mand.com command interpreter as your shell, dmake text
diversions may help in these situations.)
PORTABILITY
To write makefiles that can be moved from one environment
to another requires some forethought. In particular you
must define as macros all those things that may be differ-
ent in the new environment. dmake has two facilities that
help to support writing portable makefiles, recursive
macros and conditional expressions. The recursive macros,
allow one to define environment configurations that allow
different environments for similar types of operating sys-
tems. For example the same make script can be used for
SYSV and BSD but with different macro definitions.
To write a makefile that is portable between UNIX and
MSDOS requires both features since in almost all cases you
will need to define new recipes for making targets. The
recipes will probably be quite different since the capa-
bilities of the tools on each machine are different. Dif-
ferent macros will be needed to help handle the smaller
differences in the two environments.
Version 4.01 PL0 UW 55
DMAKE(p) Unsupported Free Software DMAKE(p)FILES
Makefile, makefile, startup.mk (use dmake-V to tell you
where the startup file is)
SEE ALSOsh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
S.I. Feldman Make - A Program for Maintaining Computer
Programs
AUTHOR
Dennis Vadura, dvadura@wticorp.com
Many thanks to Carl Seger for his helpful suggestions, and
to Trevor John Thompson for his many excellent ideas and
informative bug reports. Many thanks also go to those on
the NET that have helped in making dmake one of the best
Make tools available.
BUGS
Some system commands return non-zero status inappropri-
ately. Use -i (`-' within the makefile) to overcome the
difficulty.
Some systems do not have easily accessible time stamps for
library members (MSDOS, AMIGA, etc) for these dmake uses
the time stamp of the library instead and prints a warning
the first time it does so. This is almost always ok,
except when multiple makefiles update a single library
file. In these instances it is possible to miss an update
if one is not careful.
This man page is way too long.
WARNINGS
Rules supported by make(1) may not work if transitive clo-
sure is turned off (-T, .NOINFER).
PWD from csh/ksh will cause problems if a cd operation is
performed and -e or -E option is used.
Using internal macros such as COMMAND, may wreak havoc if
you don't understand their functionality.
Version 4.01 PL0 UW 56
