v19i040: dmake - dmake version 3.7, Part19/37

[Dennis Vadura]

Submitted-by: Dennis Vadura <dvadura at watdragon.waterloo.edu>
Posting-number: Volume 19, Issue 40
Archive-name: dmake/part19
Supersedes: dmake-3.6: Volume 15, Issue 52-77

---- Cut Here and feed the following to sh ----
#!/bin/sh
# this is dmake.shar.19 (part 19 of a multipart archive)
# do not concatenate these parts, unpack them in order with /bin/sh
# file dmake/man/dmake.tf continued
#
if test ! -r _shar_seq_.tmp; then
	echo 'Please unpack part 1 first!'
	exit 1
fi
(read Scheck
 if test "$Scheck" != 19; then
	echo Please unpack part "$Scheck" next!
	exit 1
 else
	exit 0
 fi
) < _shar_seq_.tmp || exit 1
if test -f _shar_wnt_.tmp; then
sed 's/^X//' << 'SHAR_EOF' >> 'dmake/man/dmake.tf' &&
are escaped by \\.
A set of continued lines may be commented out by placing a single # at the
start of the first line.
A continued line cannot span more than one makefile.
.PP
\fBwhite space\fP is defined to be any combination of
<space>, <tab>, and the sequence \\<nl>
when \\<nl> is used to terminate a LINE.
When processing \fBmacro\fP definition lines,
any amount of white space is allowed on either side of the macro operator
(=, *=, :=, *:=, += or +:=), 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.
.PP
When processing \fBtarget\fP 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 target definition line are taken
to be white space separated tokens.
The rule operator (\fIop\fP 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.  \fBdmake\fP allows `:' to be present in
target/prerequisite names as long as the entire target/prerequisite name is
quoted.  For example:
.sp
\ta:fred : test
.sp
would be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which
is not what was intended.  To fix this you must write:
.sp
\t"a:fred" : test
.sp
Which will be parsed as expected.
See the EXAMPLES section for how to apply \fB"\fP quoting
to a list of targets.
.SH ATTRIBUTES
.B dmake
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 modify
\fBdmake\fP actions during target update.
The recognized attributes are:
.sp
.IP \fB.EPILOG\fP 1.2i
Insert shell epilog code when executing a group recipe associated with
any target having this attribute set.
.IP \fB.IGNORE\fP 1.2i
Ignore an error when trying to make any target with this attribute set.
.IP \fB.LIBRARY\fP 1.2i
Target is a library.
.IP \fB.MKSARGS\fP 1.2i
If running in an MSDOS environment then use MKS extended argument passing
conventions to pass arguments to commands.  Non-MSDOS
environments ignore this attribute.
.IP \fB.NOINFER\fP 1.2i
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.
(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 \fB-T\fP on the command line.
.IP \fB.NOSTATE\fP 1.2i
Any target with this attribute set will not have command line flag
information stored in the state file if .KEEP_STATE has been enabled.
.IP \fB.PHONY\fP 1.2i
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.
.IP \fB.PRECIOUS\fP 1.2i
Do not remove associated target under any circumstances.
Set by default for any targets whose corresponding files exist in the file
system prior to the execution of \fBdmake\fP.
.IP \fB.PROLOG\fP 1.2i
Insert shell prolog code when executing a group recipe associated with
any target having this attribute set.
.IP \fB.SEQUENTIAL\fP 1.2i
Force a sequential make of the associated target's prerequisites.
.IP \fB.SETDIR\fP 1.2i
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 \fI.SETDIR=path\fP as the attribute.  \fIpath\fP is expanded and
the result is used as the value of the directory to change to.
If path is surrounded by single quotes then path is not expanded, and is used
literally as the directory name.
If the \fIpath\fP 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.
.IP \fB.SILENT\fP 1.2i
Do not echo the recipe lines when making any target with this attribute set,
and do not issue any warnings.
.IP \fB.SWAP\fP 1.2i
Under MSDOS
when making a target with this attribute set swap the \fBdmake\fP executable
to disk prior to executing the recipe line.  Also see the '%' recipe line
flag defined in the RECIPES section.
.IP \fB.SYMBOL\fP 1.2i
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 automatically.
.IP \fB.USESHELL\fP 1.2i
Force each recipe line of a target to be executed using a shell.
Specifying this attribute is equivalent to specifying the '+' character at the
start of each line of a non-group recipe.
.IP \fB.UPDATEALL\fP 1.2i
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
.I y.tab.c
and
.I y.tab.h
files by
.B 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.
.sp
.PP
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.
.sp
\tATTRIBUTE_LIST : \fItargets\fP
.sp
assigns the attributes specified by ATTRIBUTE_LIST to each target in
.I targets
or
.sp
\t\fItargets\fP ATTRIBUTE_LIST : ...
.sp
assigns the attributes specified by ATTRIBUTE_LIST to each target in
.I targets.
In the first form if
.I 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 \fI".IGNORE :"\fP
but has been modified to the notion of an attribute instead of
a special target).
Not all of the attributes have global meaning.
In particular, .LIBRARY, .SYMBOL, and .UPDATEALL
have no assigned global meaning.
.PP
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.
.SH MACROS
.B dmake
supports six types of macro assignment.
.sp
.IP "\fBMACRO = LINE\fP" 1.55i
This is the most common and familiar form of macro assignment.  It assigns
LINE literally as the value of MACRO.
Future expansions of MACRO recursively expand its value.
.IP "\fBMACRO *= LINE\fP" 1.55i
This form behaves exactly as the simple '=' form with the exception that if
MACRO already has a value then the assignment is not performed.
.IP "\fBMACRO := LINE\fP" 1.55i
This form differs from the simple '=' form in that it expands LINE
prior to assigning it as the value of MACRO.
Future expansions of MACRO do not recursively expand its value.
.IP "\fBMACRO *:= LINE\fP" 1.55i
This form behaves exactly as the ':=' form with the exception that if
MACRO already has a value then the assignment and expansion are not performed.
.IP "\fBMACRO += LINE\fP" 1.55i
This form of macro assignment allows macro values to grow.  It takes the
literal value of LINE and appends it to the previous value of MACRO separating
the two by a single space.
Future expansions of MACRO recursively expand its value.
.IP "\fBMACRO +:= LINE\fP" 1.55i
This form is similar to the '+=' form except that the value of LINE is expanded
prior to being added to the value of MACRO.
.PP
Macro expressions specified on the command line allow the macro value
to be redefined within the makefile only if the macro is defined using
the '+=' and '+:=' operators.  Other operators will define a macro that cannot
be further modified.
.PP
When \fBdmake\fP defines a non-environment macro it strips leading and
trailing white space from the macro value.
Macros imported from the environment via either the .IMPORT special
target (see the SPECIAL TARGETS section), or the \fB-e\fP, or \fB-E\fP 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, environment macros that are imported
due to the specification of the \fB-e\fP or \fB-E\fP flags
are subject to expansion when used.
.PP
To specify a macro expansion
enclose the name in () or {} and precede it with a dollar sign $.
Thus $(TEST) represents 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 recursive, hence, if the value string contains an expression
representing a macro expansion, the expansion is performed.  Circular macro
expansions are detected and cause an error to be issued.
.PP
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
.sp
\tCWD = $(PWD:b)
.sp
then the value of $(CWD) is the name of the current directory.
This can be used to define macros specific to this directory, for
example:
.sp
\t_$(CWD).prt = list of files to print...
.sp
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.
.PP
Macro variables may be defined within the makefile, on the command
line, or imported from the environment.
.PP
.B \fBdmake\fR
supports several non-standard macro expansions:
The first is of the form:
.RS
.IP \fI$(macro_name:modifier_list:modifier_list:...)\fR
.RE
.LP
where
.I modifier_list
is chosen from the set { D or d, F or f, B or b, S or s, T or t } and
.RS
.sp
.Is "d "
.Ii "d "
\- directory portion of all path names
.Ii "f"
\- file (including suffix) portion of path names
.Ii "b"
\- file (not including suffix) portion of path names
.Ii "s"
\- simple pattern substitution
.Ii "t"
\- tokenization.
.sp
.RE
Thus if we have the example:
.LP
\ttest = d1/d2/d3/a.out f.out d1/k.out
.LP
The following macro expansions produce the values on the right of '-->' after
expansion.
.RS
.sp
.Is "$(test:s/out/in/:f)  "
.Ii "$(test:d)"
--> d1/d2/d3/ d1/
.Ii "$(test:b)"
--> a f k
.Ii "$(test:f)"
--> a.out f.out k.out
.Ii "${test:db}"
--> d1/d2/d3/a f d1/k
.Ii "${test:s/out/in/:f}"
--> a.in f.in k.in
.Ii $(test:f:t"+")
--> a.out+f.out+k.out
.RE
.PP
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
\fB:d\fP modifier then the expansion returns the directory name less the
final directory separator string.  Thus successive pairs of :d modifiers
each remove a level of directory in the token string.
.PP
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 the octal representation of a character.  Thus the
expansion:
.LP
.RS
.nf
$(test:f:t"+\\n")
.RE
produces:
.RS
a.out+
f.out+
k.out
.fi
.RE
.PP
The second non-standard form of macro expansion allows for recursive macros.
It is possible to specify a $(\fImacro_name\fR) or ${\fImacro_name\fR} expansion
where \fImacro_name\fR contains more $( ... ) or ${ ... } macro expansions
itself.
.PP
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.
.RS
.sp
.nf
CFLAGS_VAX_CC = -c -O	# _HOST == "_VAX", _COMPILER == "_CC"
CFLAGS_PC_MSC = -c -ML	# _HOST == "_PC",  _COMPILER == "_MSC"
.sp
# redefine CFLAGS macro as:
.sp
CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
.fi
.sp
.RE
This causes CFLAGS to take on a value that corresponds to the
environment in which the make is being invoked.
.PP
The final non-standard macro expansion is of the form:
.RS
.sp
string1{token_list}string2
.RE
.LP
where string1, string2 and token_list are expanded.  After expansion,
string1 is prepended to each token found in 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:
.RS
.sp
.Is "test/{f1  f2}.o    "
.Ii "test/{f1 f2}.o"
--> test/f1.o test/f2.o
.Ii "test/ {f1 f2}.o"
--> test/ f1.o f2.o
.Ii "test/{f1 f2} .o"
--> test/f1 test/f2 .o
.Ii "test/{""f1""  """"}.o"
--> test/f1.o test/.o
.sp
.Ii and
.sp
.Is "test/{d1 d2}/{f1 f2}.o --> "
.Ii "test/{d1 d2}/{f1 f2}.o --> "
test/d1/f1.o test/d1/f2.o
test/d2/f1.o test/d2/f2.o
.sp
.RE
This last expansion is activated only when the first characters of
.I 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
.RS
.sp
{ echo hello;}
.sp
.RE
is valid /bin/sh syntax; while
.RS
.sp
{echo hello;}
.sp
.RE
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
\fBdmake\fP defines and understands.
.SH "RULES AND TARGETS"
A makefile contains a series of entries that specify dependencies.
Such entries are called \fItarget/prerequisite\fP or \fIrule\fP 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
.B 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:
.sp
.RS
.nf
\fI<targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<prerequisites>\fP] [;\fI<recipe>\fP]
.fi
.RE
.sp
.I 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:
.sp
.RS
\&.IMPORT .ERROR : ...
.RE
.sp
is not allowed since both .IMPORT and .ERROR are special targets.
Special targets are not used in the construction of the dependency graph and
will not be made.
.PP
.I 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.
.sp
.IP NOTE: 0.75i
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.
.sp
.PP
.I ruleop
is a separator which is used to identify the targets from the prerequisites.
Optionally it also provides a facility for modifying the way in which
.B dmake
handles the making of the associated targets.
In its simplest form the operator is a single ':', and need not be separated
by white space from its neighboring tokens.  It may additionally be followed
by any of the modifiers { !, ^, -, : }, where:
.sp
.IP \fB!\fP
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.
.IP \fB^\fP
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 prerequisites.
.IP \fB-\fP
says to clear the previous list of prerequisites before adding
the new prerequisites.  Thus,
.sp
\t.SUFFIXES :
.br
\t.SUFFIXES : .a .b
.sp
can be replaced by
.sp
\t.SUFFIXES :- .a .b
.sp
however the old form still works as expected.  NOTE:  .SUFFIXES is ignored by
.B dmake
it is used here simply as an example.
.IP \fB:\fP
When the rule operator is not modified by a second ':'
only one set of rules may be specified for making a target.
Multiple definitions may be used to add to the
list of prerequisites that a target depends on.
However, if a target is multiply defined
only one definition may specify a recipe
for making the target.
.sp
When a target's rule operator is modified by a second ':'
(:: 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.
.sp 
In the following simple example, each rule has a `::' \fIruleop\fP.  In such an
operator we call the first `:' the operator, and the second `:' the modifier.
.sp
.nf
a.o :: a.c b.h
X   first recipe for making a.o
X
a.o :: a.y b.h
X   second recipe for making a.o
.fi
.sp
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 invocation corresponds to the order in which the
rule definitions appear in the makefile.
.PP
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 `:'
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 prerequisites 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:
.RS
.sp
.nf
joe :  fred ...	(1)
joe :: more ...	(2)
.sp
and
.sp
joe :: fred ...	(3)
joe :: more ...	(4)
.sp
.fi
.RE
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:
.RS
.sp
.nf
joe :: fred ...	(5)
joe : more ...	(6)
.sp
and
.sp
joe : fred ...	(7)
joe : more ...	(8)
.sp
.fi
.RE
are errors since we have two sets of perfectly good recipes for
making the target.
.PP
.I prerequisites
is a possibly empty list of targets that must be brought up to date before
making the current target.
.PP
.I 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
.I "Don't know how to make ..."
error message to be suppressed when
.B 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 (\fB-A\fP) flag
was specified.
.SH "RECIPES"
The traditional format used by most versions of Make defines the recipe
lines as arbitrary strings that may 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
.B MUST
begin with a \fB<TAB>\fP character which
may optionally be followed with one or all
of the characters
.IR "'@%+\-'" "."
The
.I "'\-'"
indicates that non-zero exit values (ie. errors)
are to be ignored when this recipe line is executed, the
.I "'\+'"
indicates that the current recipe line is to be executed using the shell, the
.I "'%'"
indicates that
.B dmake
should swap itself out to secondary storage (MSDOS only) before running the
recipe and the
.I "'@'"
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:
.sp
.RS
.nf
target :
\tfirst recipe line
\tsecond recipe line, executed independently of the first.
\t at a recipe line that is not echoed
\t\-and one that has errors ignored
\t%and one that causes dmake to swap out
\t\+and one that is executed using a shell.
.fi
.RE
.PP
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 terminates 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 leading 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
.B dmake
invokes recipes.
Here is an example of a group recipe:
.sp
.RS
.nf
target :
[
\tfirst recipe line
\tsecond recipe line
\tall of these recipe lines are fed to a
\tsingle copy of a shell for execution.
]
.fi
.RE
.sp
.SH "TEXT DIVERSIONS"
.B dmake
supports the notion of text diversions.
If a recipe line contains the macro expression
.RS
.sp
$(mktmp[,[\fIfile\fP][,\fItext\fP]] \fIdata\fP)
.sp
.RE
then all text contained in the \fIdata\fP expression is expanded and
is written to a temporary file.  The return
value of the macro is the name of the temporary file.
.PP
.I 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 example:
.sp
\t$(mktmp $(XXX))
.sp
is legal and works as expected, but:
.sp
\t$(mktmp text (to dump to file)
.sp
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:
.sp
\t${mktmp text (to dump to file}
.sp
Since the temporary file is opened when the
macro containing the text diversion expression is expanded, diversions may
now be nested and any diversions that are created as part of ':=' macro
expansions persist for the duration of the
.B dmake
run.
The diversion text may contain
the same escape codes as those described in the MACROS section.
Thus if the \fIdata\fP text is to contain new lines they must be inserted
using the \\n escape sequence.  For example the expression:
.RS
.sp
.nf
all:
X	cat $(mktmp this is a\\n\\
X	test of the text diversion\\n)
.fi
.sp
.RE
is replaced by:
.RS
.sp
cat /tmp/mk12294AA
.sp
.RE
where the temporary file contains two lines both of which are terminated
by a new-line.  If the \fIdata\fP text spans multiple lines in the makefile
then each line must be continued via the use of a \\.
A second more illustrative example generates a response file to an MSDOS
link command:
.RS
.sp
.nf
OBJ = fred.obj mary.obj joe.obj
all : $(OBJ)
X	link @$(mktmp $(^:t"+\\n")\\n)
.fi
.sp
.RE
The result of making `all' in the second example is the command:
.RS
.sp
link @/tmp/mk02394AA
.sp
.RE
where the temporary file contains:
.RS
.sp
.nf
fred.obj+
mary.obj+
joe.obj
.fi
.sp
.RE
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 \fIdata\fP string.
.PP
If the optional \fIfile\fP specifier is present then its expanded value
is the name of the temporary file to create.  Whenever a $(mktmp ...) macro
is expanded the macro $(TMPFILE) is set to a new temporary file name.  Thus
the construct:
.RS
.sp
$(mktmp,$(TMPFILE) data)
.sp
.RE
is completely equivalent to not specifying the $(TMPFILE) optional argument.
Another example that would be useful for MSDOS users with a Turbo-C compiler
.RS
.sp
$(mktmp,turboc.cfg $(CFLAGS))
.sp
.RE
will place the contents of CFLAGS into a local \fIturboc.cfg\fP file.
The second optional argument, \fItext\fP, if present alters the name
of the value returned by the $(mktmp ...) macro.
.PP
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 USESHELL 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
.B dmake
startup files define the macro DIVFILE whose value is either the
value of TMPFILE or the value of TMPFILE edited to replace any '/' characters
to the appropriate value based on the current shell and whether it will be
used to execute the recipe.
.PP
Previous versions of
.B dmake
defined text diversions using <+, +> strings,
where <+ started a text diversion and +> terminated one.
.B dmake
is backward compatible with this construct if the <+ and +> appear literally
on the same recipe line or in the same macro value string.  In such instances
the expression:
.sp
\t<+data+>
.sp
is mapped to:
.sp
\t$(mktmp data)
.sp
which is fully output compatible with the earlier construct.  <+, +>
constructs whose text spans multiple lines must be converted by hand to use
$(mktmp ...).
.PP
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 temporary files by
defining a macro named TMPDIR and exporting it using the .EXPORT special
target.
.SH "SPECIAL TARGETS"
This section describes the special targets that are recognized by \fBdmake\fP.
Some are affected by attributes and others are not.
.IP \fB.ERROR\fP 1.4i
If defined then the recipe associated with this target is executed
whenever an error condition is detected by \fBdmake\fP.  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.
.IP \fB.EXPORT\fP 1.4i
All prerequisites associated with this target 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 target 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 are not exported.
.IP \fB.IMPORT\fP 1.4i
Prerequisite names specified for this target are searched for in the
environment and defined as macros with their value taken from the environment.
If the special name \fB.EVERYTHING\fP is used as a prerequisite name then
all environment variables defined in the environment are imported.
The functionality of the \fB-e\fP flag can be forced by placing the construct
\&\fI.IMPORT : .EVERYTHING\fP at the start of a makefile.  Similarly, by
placing the construct at the end, one can emulate the effect of the \fB-E\fP
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 \fBdmake\fP
to ignore the above error.
See the MACROS section for a description of the processing of imported macro
values.
.IP \fB.INCLUDE\fP 1.4i
Parse another makefile just as if it had been located at the point of the
\&.INCLUDE in the current makefile.  The list of prerequisites gives the list of
makefiles to try to read.  If the list contains multiple makefiles 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 current directory.  If it is not
found it is then searched for in each of the directories specified for 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.  .INCLUDE accepts
the .IGNORE and .SETDIR attributes.  If .IGNORE attribute is given and the file
cannot be found then \fBdmake\fP continues processing,
otherwise an error message is generated.
The .SETDIR attribute causes
.B dmake
to change directories to the specified directory prior to attempting the
include operation.
.IP \fB.INCLUDEDIRS\fP 1.4i
The list of prerequisites specified for this target defines the set of
directories to search when trying to include a makefile.
.IP \fB.KEEP_STATE\fP 1.4i
This special target is a synonym for the macro definition
.sp
\&\t.KEEP_STATE := _state.mk
.sp
It's effect is to turn on STATE keeping and to define \fI_state.mk\fP
as the state file.
.IP \fB.MAKEFILES\fP 1.4i
The list of prerequisites is the set of files to try to read as the default
makefile.  By default this target is defined as: 
.sp
\t\&.MAKEFILES : makefile.mk Makefile makefile
.sp
.IP \fB.SOURCE\fP 1.4i
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.
.IP \fB.SOURCE.suff\fP 1.4i
The same as .SOURCE, except that the .SOURCE.suff list is searched first when
trying to locate a file matching the a target whose name ends in the suffix
\&.suff.
.IP \fB.REMOVE\fP 1.4i
The recipe of this target is used whenever \fBdmake\fP needs to remove
intermediate targets that were made but do not need to be kept around.
Such targets result from the application of transitive closure on the
dependency graph.
.PP
In addition to the special targets above,
several other forms of targets are recognized and are considered special,
their exact form and use is defined in the sections that follow.
.SH "SPECIAL MACROS"
.B dmake
defines a number of special macros.  They are divided into three classes:
control macros, run-time macros, and function macros.
The control macros are used by
.B 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
.B 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.
.SH "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.
.PP
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.
.IP \fBDIRBRKSTR\fP 1.4i
Contains the string of chars used to terminate
the name of a directory in a pathname.
Under UNIX its value is "/", under MSDOS its value is "/\\:".
.IP \fBINCDEPTH\fP 1.4i
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.
.IP \fBMFLAGS\fP 1.4i
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.
.IP \fBMAKECMD\fP 1.4i
Is the name with which \fBdmake\fP was invoked.
.IP \fBMAKEDIR\fP 1.4i
Is the full path to the initial directory in which
.B dmake
was invoked.
.IP \fBMAKEFILE\fP 1.4i
Contains the string "-f \fImakefile\fP" where, \fImakefile\fP is the name
of initial user makefile that was first read.
.IP \fBMAKEFLAGS\fP 1.4i
Is the same as $(MFLAGS) but has no leading switch
character. (ie. MFLAGS = -$(MAKEFLAGS))
.IP \fBMAKEMACROS\fP 1.4i
Contains the complete list of macro expressions that were specified on the
command line.
.IP \fBMAKETARGETS\fP 1.4i
Contains the name(s) of the target(s), if any, that were
specified on the command line.
.IP \fBMAXPROCESSLIMIT\fP 1.4i
Is a numeric string representing the maximum number of processes that 
\fBdmake\fP can use when making targets using parallel mode.
.IP \fBNULL\fP 1.4i
Is permanently defined to be the NULL string.
This is useful when comparing a conditional expression to an NULL value.
.IP \fBPWD\fP 1.4i
Is the full path to the
current directory in which make is executing.
.IP \fBTMPFILE\fP 1.4i
Is set to the name of the most recent temporary file opened by \fBdmake\fP.
Temporary files are used for text diversions and for group recipe processing.
.IP \fBTMD\fP 1.4i
Stands for "To Make Dir", and
is the path from the present directory (value of $(PWD)) to the directory
that \fBdmake\fP was started up in (value of $(MAKEDIR)).
This macro is modified when .SETDIR attributes are processed.
.IP \fBUSESHELL\fP 1.4i
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" otherwise.
.sp
.PP
The second group of string valued macros control
.B dmake
behavior and may be set by the user.
.IP \fB.SETDIR\fP 1.6i
If this macro is assigned a value then \fBdmake\fP will
change to the directory given by that value before making any targets.
.IP \fBAUGMAKE\fP 1.6i
If set to a non NULL value will enable the transformation of special
meta targets to support special AUGMAKE inferences (See the COMPATIBILITY
section).
.IP \fBDIRSEPSTR\fP 1.6i
Contains the string that is used to separate directory components when
path names are constructed.  It is defined with a default value at startup.
.IP \fBDIVFILE\fP 1.6i
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.
.IP \fB.KEEP_STATE\fP 1.6i
Assigning this macro a value tells
.B 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.
.IP \fBGROUPFLAGS\fP 1.6i
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)
.IP \fBGROUPSHELL\fP 1.6i
This macro defines the full
path to the executable image to be used as the shell when
processing group recipes.  This macro 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.
.IP \fBGROUPSUFFIX\fP 1.6i
If defined, this macro gives the string to use as a suffix
when creating group recipe files to be handed to the command interpreter.
For example, if it is defined as .sh, then all
temporary files created by \fBdmake\fP 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 GROUPSUFFIX and GROUPSHELL is done automatically for
command.com in the startup.mk files.
.IP \fBMAKE\fP 1.6i
Is defined in the startup file by default.
The string $(MAKE) is recognized when
using the -n option for single line recipes.  Initially this macro is defined
to have the value "$(MAKECMD) $(MFLAGS)".
.IP \fBMAKESTARTUP\fP 1.6i
This macro defines the full path to the initial startup
makefile.  Use the \fB-V\fP command line option to discover its initial
value.
.IP \fBMAXLINELENGTH\fP 1.6i
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 \fB-V\fP option.
A buffer of this size plus 2 is allocated for reading makefile text.  The
buffer is freed before any targets are made, thereby allowing files containing
long input lines to be processed without consuming memory during the actual
make.
.IP \fBMAXPROCESS\fP 1.6i
Specify the maximum number of child processes 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 corresponding value to
the -P flag on the command line.
.IP \fBPREP\fP 1.6i
This macro defines the number of iterations to be expanded
automatically when processing % rule definitions of the form:
.sp
% : %.suff
.sp
See the sections on PERCENT(%) RULES for details on how PREP is used.
.IP \fBSHELL\fP 1.6i
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.
.IP \fBSHELLFLAGS\fP 1.6i
SHAR_EOF
true || echo 'restore of dmake/man/dmake.tf failed'
fi
echo 'End of part 19, continue with part 20'
echo 20 > _shar_seq_.tmp
exit 0

exit 0 # Just in case...
-- 
Kent Landfield                   INTERNET: kent at sparky.IMD.Sterling.COM
Sterling Software, IMD           UUCP:     uunet!sparky!kent
Phone:    (402) 291-8300         FAX:      (402) 291-4362
Please send comp.sources.misc-related mail to kent at uunet.uu.net.