v15i063: dmake version 3.6 (part 11/25)

[Dennis Vadura]

Posting-number: Volume 15, Issue 63
Submitted-by: Dennis Vadura <dvadura at watdragon.waterloo.edu>
Archive-name: dmake-3.6/part11

#!/bin/sh
# this is part 11 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file man/dmake.tf continued
#
CurArch=11
if test ! -r s2_seq_.tmp
then echo "Please unpack part 1 first!"
     exit 1; fi
( read Scheck
  if test "$Scheck" != $CurArch
  then echo "Please unpack part $Scheck next!"
       exit 1;
  else exit 0; fi
) < s2_seq_.tmp || exit 1
echo "x - Continuing file man/dmake.tf"
sed 's/^X//' << 'SHAR_EOF' >> man/dmake.tf
Xthe recipe may not span across multiple makefiles.
XAny targets and prerequisites found on a target definition line are taken
Xto be white space separated tokens.
XThe rule operator (\fIop\fP in SYNTAX section) is also considered
Xto be a token but does not require
Xwhite space to precede or follow it.  Since the rule operator begins with a `:',
Xtraditional versions of make do not allow the `:' character to
Xform a valid target name.  \fBdmake\fP allows `:' to be present in
Xtarget/prerequisite names as long as the entire target/prerequisite name is
Xquoted.  For example:
X.sp
X\ta:fred : test
X.sp
Xwould be parsed as TARGET = a, PREREQUISITES are fred, :, and test, which
Xis not what was intended.  To fix this you must write:
X.sp
X\t"a:fred" : test
X.sp
XWhich will be parsed as expected.
XSee the EXAMPLES section for how to apply this to a list of targets.
X.SH ATTRIBUTES
X.B dmake
Xdefines several target attributes.  Attributes may be
Xassigned to a single target, a group of targets, or to all targets in the
Xmakefile.  Attributes are used to modify
X\fBdmake\fP actions during target update.
XThe recognized attributes are:
X.sp
X.IP \fB.EPILOG\fP 1.2i
XInsert shell epilog code when executing a group recipe associated with
Xany target having this attribute set.
X.IP \fB.IGNORE\fP 1.2i
XIgnore an error when trying to make any target with this attribute set.
X.IP \fB.LIBRARY\fP 1.2i
XTarget is a library.
X.IP \fB.MKSARGS\fP 1.2i
XIf in an MSDOS environment then use MKS extended argument passing
Xconventions to pass arguments to commands.  Non-MSDOS
Xenvironments ignore this attribute.
X.IP \fB.NOINFER\fP 1.2i
XAny target with this attribute set will not be subjected
Xto transitive closure if it is inferred as a prerequisite 
Xof a target whose recipe and prerequisites are being inferred.
X(i.e. the inference algorithm will not use any prerequisite with this attribute 
Xset, as a target)
X.IP \fB.PRECIOUS\fP 1.2i
XDo not remove this target under any circumstances.
XSet by default for any targets whose corresponding files exist in the file
Xsystem prior to the execution of \fBdmake\fP.
X.IP \fB.PROLOG\fP 1.2i
XInsert shell prolog code when executing a group recipe associated with
Xany target having this attribute set.
X.IP \fB.SEQUENTIAL\fP 1.2i
XForce a sequential make of the associated target's prerequisites.
X.IP \fB.SETDIR\fP 1.2i
XChange current working directory to specified directory when making the
Xassociated target.  You must
Xspecify the directory at the time the attribute is specified.  To do this
Xsimply give \fI.SETDIR=path\fP as the attribute.  \fIpath\fP is expanded and
Xthe result is used as the value of the directory to change to.
XIf path is surrounded by single quotes then path is not expanded, and is used
Xliterally as the directory name.
XIf the \fIpath\fP contains any `:' characters then the entire attribute string
Xmust be quoted using ".
XIf a target having this attribute set also has the .IGNORE
Xattribute set then if the change to the specified directory fails it will be
Xignored, and no error message will be issued.
X.IP \fB.SILENT\fP 1.2i
XDo not echo the recipe lines when making any target with this attribute set,
Xand do not issue any warnings.
X.IP \fB.SWAP\fP 1.2i
XUnder MSDOS
Xwhen making a target with this attribute set swap the \fBdmake\fP executable
Xto disk prior to executing the recipe line.
X.IP \fB.SYMBOL\fP 1.2i
XTarget is a library member and is an entry point into a module in the
Xlibrary.  This attribute is used only when searching a library for a target.
XTargets of the form lib((entry)) have this attribute set automatically.
X.IP \fB.USESHELL\fP 1.2i
XForce each recipe line of a target to be executed using a shell.
XSpecifying this attribute is equivalent to specifying the '+' character at the
Xstart of each line of a non-group recipe.
X.IP \fB.UPDATEALL\fP 1.2i
XIndicates that all the targets listed in this rule are updated by the
Xexecution of the accompanying recipe.
XA common example is the production of the
X.I y.tab.c
Xand
X.I y.tab.h
Xfiles by
X.B yacc
Xwhen it is run on a grammar.  Specifying .UPDATEALL in such a rule
Xprevents the running of yacc twice, once for the y.tab.c file and once
Xfor the y.tab.h file.
X.sp
X.PP
XAll attributes are user setable and except for .UPDATEALL and .MKSARGS
Xmay be used in one of two forms.
XThe .MKSARGS attribute is restricted to use as a global attribute, and
Xthe use of the .UPDATEALL attribute is restricted to rules of the second
Xform only.
X.sp
X\tATTRIBUTE_LIST : \fItargets\fP
X.sp
Xassigns the attributes specified by ATTRIBUTE_LIST to each target in
X.I targets
Xor
X.sp
X\t\fItargets\fP ATTRIBUTE_LIST : ...
X.sp
Xassigns the attributes specified by ATTRIBUTE_LIST to each target in
X.I targets.
XIn the first form if
X.I targets
Xis empty (ie. a NULL list), then the
Xlist of attributes will apply to all targets in the makefile
X(this is equivalent to the common Make construct of \fI".IGNORE :"\fP
Xbut has been modified to the notion of an attribute instead of
Xa special target).
XNot all of the attributes have global meaning.
XIn particular, .LIBRARY, .SYMBOL, and .UPDATEALL
Xhave no assigned global meaning.
X.PP
XAny attribute may be used with any target, even with the special targets.
XSome combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ),
Xwhile others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain
Xif file.mk cannot be found using the include file search rules,
Xsee the section on SPECIAL TARGETS for a description of .INCLUDE).
XIf a specified attribute will not be used with the special target a warning
Xis issued and the attribute is ignored.
X.SH MACROS
X.B dmake
Xsupports six types of macro assignment.
X.sp
X.IP "\fBMACRO = LINE\fP" 1.55i
XThis is the most common and familiar form of macro assignment.  It assigns
XLINE literally as the value of MACRO.
XFuture expansions of MACRO recursively expand it's value.
X.IP "\fBMACRO *= LINE\fP" 1.55i
XThis form behaves exactly as the simple '=' form with the exception that if
XMACRO already has a value then the assignment is not performed.
X.IP "\fBMACRO := LINE\fP" 1.55i
XThis form differs from the simple '=' form in that it expands LINE
Xprior to assigning it as the value of MACRO.
XFuture expansions of MACRO do not recursively expand it's value.
X.IP "\fBMACRO *:= LINE\fP" 1.55i
XThis form behaves exactly as the ':=' form with the exception that if
XMACRO already has a value then the assignment and expansion are not performed.
X.IP "\fBMACRO += LINE\fP" 1.55i
XThis form of macro assignment allows macro values to grow.  It takes the
Xliteral value of LINE and appends it to the previous value of MACRO separating
Xthe two by a single space.
XFuture expansions of MACRO recursively expand it's value.
X.IP "\fBMACRO +:= LINE\fP" 1.55i
XThis form is similar to the '+=' form except that the value of LINE is expanded
Xprior to being added to the value of MACRO.
X.PP
XMacro expressions specified on the command line allow the macro value
Xto be redefined within the makefile only if the macro is defined using
Xthe '+=' and '+:=' operators.  Other operators will define a macro that cannot
Xbe further modified.
X.PP
XWhen \fBdmake\fP defines a non-environment macro it strips leading and
Xtrailing white space from the macro value.
XMacros imported from the environment via either the .IMPORT special
Xtarget (see the SPECIAL TARGETS section), or the \fB-e\fP, or \fB-E\fP flags
Xare an exception to this rule.  Their values are
Xalways taken literally and white space is never stripped.
XIn addition, macros defined using the .IMPORT special target do
Xnot have their values expanded when they are used within a makefile.
XIn contrast, environment macros that are imported
Xdue to the specification of the \fB-e\fP or \fB-E\fP flags
Xare subject to expansion when used.
X.PP
XTo specify a macro expansion
Xenclose the name in () or {} and precede it with a dollar sign $.
XThus $(TEST) represents an expansion of the macro variable named TEST.
XIf TEST is
Xdefined then $(TEST) is replaced by its expanded value.  If TEST is not
Xdefined then $(TEST) expands to the NULL string (this is equivalent to
Xdefining a macro as 'TEST=' ).  A short form may be used for single character
Xnamed macros.  In this case the parentheses are optional, and $(I) is
Xequivalent to $I.
XMacro expansion is recursive, hence, if the value string contains an expression
Xrepresenting a macro expansion, the expansion is performed.  Circular macro
Xexpansions are detected and cause an error to be issued.
X.PP
XWhen defining a macro the given macro name is first expanded before being used
Xto define the macro.  Thus it is possible to define macros whose names
Xdepend on values of other macros.  For example, suppose
X.sp
X\tCWD = $(PWD:b)
X.sp
Xis defined, then the value of $(CWD) is the name of the current directory.
XThis can be used to define macros specific to this directory, for
Xexample:
X.sp
X\t_$(CWD).prt = list of files to print...
X.sp
XThe actual name of the defined macro is a function of the current directory.
XA construct such as this is useful when processing a hierarchy of directories
Xusing .SETDIR attributed targets and a collection of small distributed
Xmakefile stubs.
X.PP
XMacro variables may be defined within the makefile, on the command
Xline, or imported from the environment.
X.PP
X.B \fBdmake\fR
Xsupports several non-standard macro expansions:
XThe first is of the form:
X.RS
X.IP \fI$(macro_name:modifier_list:modifier_list:...)\fR
X.RE
X.LP
Xwhere
X.I modifier_list
Xis chosen from the set { D or d, F or f, B or b, S or s, T or t } and
X.RS
X.sp
X.Is "d "
X.Ii "d "
X\- directory portion of all path names
X.Ii "f"
X\- file (including suffix) portion of path names
X.Ii "b"
X\- file (not including suffix) portion of path names
X.Ii "s"
X\- simple pattern substitution
X.Ii "t"
X\- tokenization.
X.sp
X.RE
XThus if we have the example:
X.LP
X\ttest = d1/d2/d3/a.out f.out d1/k.out
X.LP
XThe following macro expansions produce the values on the right of '-->' after
Xexpansion.
X.RS
X.sp
X.Is "$(test:s/out/in/:f)  "
X.Ii "$(test:d)"
X--> d1/d2/d3/ d1/
X.Ii "$(test:b)"
X--> a f k
X.Ii "$(test:f)"
X--> a.out f.out k.out
X.Ii "${test:db}"
X--> d1/d2/d3/a f d1/k
X.Ii "${test:s/out/in/:f}"
X--> a.in f.in k.in
X.Ii $(test:f:t"+")
X--> a.out+f.out+k.out
X.RE
X.PP
XIf a token ends in a string composed from the value of the macro DIRBRKSTR
X(ie. ends in a directory separator string, e.g. '/' in UNIX) and you use the
X\fB:d\fP modifier then the expansion returns the directory name less the
Xfinal directory separator string.  Thus successive pairs of :d modifiers
Xeach remove a level of directory in the token string.
X.PP
XThe tokenization modifier takes all white space separated tokens from the
Xmacro value and separates them by the quoted separator string.  The separator
Xstring may contain the following escape codes \\a => <bel>,
X\&\\b => <backspace>, \\f => <formfeed>, \\n => <nl>, \\r => <cr>,
X\&\\t => <tab>, \\v => <vertical tab>, \\" => ", and \\xxx => <xxx> where
Xxxx is the octal representation of a character.  Thus the
Xexpansion:
X.LP
X.RS
X.nf
X$(test:f:t"+\\n")
X.RE
Xproduces:
X.RS
Xa.out+
Xf.out+
Xk.out
X.fi
X.RE
X.PP
XThe second non-standard form of macro expansion allows for recursive macros.
XIt is possible to specify a $(\fImacro_name\fR) or ${\fImacro_name\fR} expansion
Xwhere \fImacro_name\fR contains more $( ... ) or ${ ... } macro expansions
Xitself.
X.PP
XFor example $(CC$(_HOST)$(_COMPILER)) will first expand CC$(_HOST)$(_COMPILER)
Xto get a result and use that result as the name of the macro to expand.
XThis is useful for writing a makefile for more than one target
Xenvironment.  As an example consider the following hypothetical case. 
XSuppose that _HOST and _COMPILER are imported from the environment
Xand are set to represent the host machine type and the host compiler
Xrespectively.
X.RS
X.sp
X.nf
XCFLAGS_VAX_CC = -c -O	# _HOST == "_VAX", _COMPILER == "_CC"
XCFLAGS_PC_MSC = -c -ML	# _HOST == "_PC",  _COMPILER == "_MSC"
X.sp
X# redefine CFLAGS macro as:
X.sp
XCFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
X.fi
X.sp
X.RE
XThis causes CFLAGS to take on a value that corresponds to the
Xenvironment in which the make is being invoked.
X.PP
XThe final non-standard macro expansion is of the form:
X.RS
X.sp
Xstring1{token_list}string2
X.RE
X.LP
Xwhere string1, string2 and token_list are expanded.  After expansion,
Xstring1 is prepended to each token found in token_list and
Xstring2 is appended to each resulting token from the previous prepend.
Xstring1 and string2 are not delimited by white space
Xwhereas the tokens in token_list are.  A null token in the token list 
Xis specified using "".
XThus using another example we have:
X.RS
X.sp
X.Is "test/{ f1  ""f2"" """" }.o    "
X.Ii "test/{f1 f2}.o"
X--> test/f1.o test/f2.o
X.Ii "test/ {f1 f2}.o"
X--> test/ f1.o f2.o
X.Ii "test/{f1 f2} .o"
X--> test/f1 test/f2 .o
X.Ii "test/{ f1  ""f2"" """" }.o"
X--> test/f1.o test/f2.o test/.o
X.sp
X.Ii and
X.sp
X.Is "test/{ d1 d2 }/{ f1 f2 }.o --> "
X.Ii "test/{ d1 d2 }/{ f1 f2 }.o --> "
Xtest/d1/f1.o test/d1/f2.o
Xtest/d2/f1.o test/d2/f2.o
X.sp
X.RE
XSee the SPECIAL MACROS section for a description of the special macros that
X\fBdmake\fP defines and understands.
X.SH "RULES AND TARGETS"
XA makefile contains a series of entries that specify dependencies.
XSuch entries are called \fItarget/prerequisite\fP or \fIrule\fP definitions.
XEach rule definition
Xis optionally followed by a set of lines that provide a recipe for updating
Xany targets defined by the rule.
XWhenever
X.B dmake
Xattempts to bring a target up to date and an explicit recipe is provided with
Xa rule defining the target, that recipe is used to update the
Xtarget.  A rule definition begins with a line having the following syntax:
X.sp
X.RS
X.nf
X\fI<targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<prerequisites>\fP] [;\fI<recipe>\fP]
X.fi
X.RE
X.sp
X.I targets
Xis a non-empty list of targets.  If the target is a
Xspecial target (see SPECIAL TARGETS section below) then it must appear alone
Xon the rule line.  For example:
X.sp
X.RS
X\&.IMPORT .ERROR : ...
X.RE
X.sp
Xis not allowed since both .IMPORT and .ERROR are special targets.
XSpecial targets are not used in the construction of the dependency graph and
Xwill not be made.
X.PP
X.I attributes
Xis a possibly empty list of attributes.  Any attribute defined in the
XATTRIBUTES section above may be specified.  All attributes will be applied to
Xthe list of named targets in the rule definition.  No other targets will
Xbe affected.
X.sp
X.IP NOTE: 0.75i
XAs stated earlier,
Xif both the target list and prerequisite list are empty but the attributes
Xlist is not, then the specified attributes affect all targets in the makefile.
X.sp
X.PP
X.I ruleop
Xis a separator which is used to identify the targets from the prerequisites.
XOptionally it also provides a facility for modifying the way in which
X.B dmake
Xhandles the making of the associated targets.
XIn its simplest form the operator is a single ':', and need not be separated
Xby white space from its neighbouring tokens.  It may additionally be followed
Xby any of the modifiers { !, ^, -, : }, where:
X.sp
X.IP \fB!\fP
Xsays execute the recipe for the associated targets once for each out of date
Xprerequisite.  Ordinarily the recipe is executed
Xonce for all out of date prerequisites at the same time.
X.IP \fB^\fP
Xsays to insert the specified prerequisites, if any, before any
Xother prerequisites already associated with the specified targets.
XIn general, it is not useful to specify ^ with an empty
Xlist of prerequisites.
X.IP \fB-\fP
Xsays to clear the previous list of prerequisites before adding
Xthe new prerequisites.  Thus,
X.sp
X\t.SUFFIXES :
X.br
X\t.SUFFIXES : .a .b
X.sp
Xcan be replaced by
X.sp
X\t.SUFFIXES :- .a .b
X.sp
Xhowever the old form still works as expected.  NOTE:  .SUFFIXES is ignored by
X.B dmake
Xit is used here simply as an example.
X.IP \fB:\fP
XWhen the rule operator is not modified by a second ':'
Xonly one set of rules may be specified for making a target.
XMultiple definitions may be used to add to the
Xlist of prerequisites that a target depends on.
XHowever, if a target is multiply defined
Xonly one definition may specify a recipe
Xfor making the target.
X.sp
XWhen a target's rule operator is modified by a second ':'
X(:: for example) then this definition may not be the only
Xdefinition with a recipe for the target.  There may be other :: target
Xdefinition lines that specify a different set of prerequisites with a
Xdifferent recipe for updating the target.  
XAny such target is made if any of the definitions
Xfind it to be out of date
Xwith respect to the related prerequisites
Xand the corresponding recipe is used to update the
Xtarget.
X.sp 
XIn the following simple example, each rule has a `::' \fIruleop\fP.  In such an
Xoperator we call the first `:' the operator, and the second `:' the modifier.
X.sp
X.nf
Xa.o :: a.c b.h
X   first recipe for making a.o
X
Xa.o :: a.y b.h
X   second recipe for making a.o
X.fi
X.sp
XIf a.o is found to be out of date with respect to a.c then the first recipe
Xis used to make a.o.  If it is found out of date with respect to a.y then
Xthe second recipe is used.  If a.o is out of date with respect to
Xb.h then both recipes are invoked to make a.o.
XIn the last case the order of invocation corresponds to the order in which the
Xrule definitions appear in the makefile.
X.PP
XTargets defined using a single `:' operator
Xwith a recipe may be redefined again with a new recipe by using a
X`:' operator with a `:' modifier.
XThis is equivalent to a target having been
Xinitially defined with a rule using a `:' modifier.
XOnce a target is defined using a `:'
Xmodifier it may not be defined again with a recipe using only the `:' operator
Xwith no `:' modifier.  In both cases the use of a `:' modifier creates a new
Xlist of prerequisites and makes it the current prerequisite list for the target.
XThe `:' operator with no recipe always modifies the current list
Xof prerequisites.
XThus assuming each of the following definitions has a recipe attached, then:
X.RS
X.sp
X.nf
Xjoe :  fred ...	(1)
Xjoe :: more ...	(2)
X.sp
Xand
X.sp
Xjoe :: fred ...	(3)
Xjoe :: more ...	(4)
X.sp
X.fi
X.RE
Xare legal and mean:  add the recipe associated with (2), or (4) to the set
Xof recipes for joe, placing them after existing recipes for
Xmaking joe.
XThe constructs:
X.RS
X.sp
X.nf
Xjoe :: fred ...	(5)
Xjoe : more ...	(6)
X.sp
Xand
X.sp
Xjoe : fred ...	(7)
Xjoe : more ...	(8)
X.sp
X.fi
X.RE
Xare errors since we have two sets of perfectly good recipes for
Xmaking the target.
X.PP
X.I prerequisites
Xis a possibly empty list of targets that must be brought up to date before
Xmaking the current target.
X.PP
X.I recipe
Xis a short form and allows the user to specify short rule definitions
Xon a single line.
XIt is taken to be the first recipe line in a larger recipe
Xif additional lines follow the rule definition.
XIf the semi-colon is present but the recipe line is empty (ie. null string)
Xthen it is taken
Xto be an empty rule.  Any target so defined causes the
X.I "Don't know how to make ..."
Xerror message to be suppressed when
X.B dmake
Xtries to make the target and fails.
XThis silence is maintained for rules that are terminated
Xby a semicolon and have no following recipe lines, for targets listed on the
Xcommand line, and for the first target found in the makefile.
X.SH "RECIPES"
XThe traditional format used by most versions of Make defines the recipe
Xlines as arbitrary strings that may contain macro expansions.  They
Xfollow a rule definition line and may be spaced
Xapart by comment or blank lines.
XThe list of recipe lines defining the recipe is terminated by a new target
Xdefinition, a macro definition, or end-of-file.
XEach recipe line
X.B MUST
Xbegin with a \fB<TAB>\fP character which
Xmay optionally be followed with one or all
Xof the characters
X.IR "'@%+\-'" "."
XThe
X.I "'\-'"
Xindicates that non-zero exit values (ie. errors)
Xare to be ignored when this recipe line is executed, the
X.I "'\+'"
Xindicates that the current recipe line is to be executed using the shell, the
X.I "'%'"
Xindicates that
X.B dmake
Xshould swap itself out to secondary storage (MSDOS only) before running the
Xrecipe and the
X.I "'@'"
Xindicates that the recipe line should NOT be echoed to the terminal prior to
Xbeing executed.  Each switch is off by default
X(ie. by default, errors are significant, commands are echoed, no swapping is
Xdone and a shell is
Xused only if the recipe line contains a character found in the value of the
XSHELLMETAS macro).
XGlobal settings activated via command line options or special attribute or
Xtarget names may also affect these settings.
XAn example recipe:
X.sp
X.RS
X.nf
Xtarget :
X\tfirst recipe line
X\tsecond recipe line, executed independently of the first.
X\t at a recipe line that is not echoed
X\t\-and one that has errors ignored
X\t%and one that causes dmake to swap out
X\t\+and one that is executed using a shell.
X.fi
X.RE
X.PP
XThe second and new format of the recipe block begins the block with the
Xcharacter '[' (the open group character) in the last non-white space
Xposition of a line, and terminates the
Xblock with the character ']' (the close group character)
Xin the first non-white space position of a line.
XIn this form each recipe line need not have a leading TAB.  This is
Xcalled a recipe group.  Groups so defined are fed intact as a single
Xunit to a shell for execution whenever the corresponding target needs to
Xbe updated.  If the open group character '[' is preceded
Xby one or all of \-, @ or %
Xthen they apply to the entire group in the same way that they
Xapply to single recipe lines.  You may also specify '+' but it is
Xredundant as a shell is already being used to run the recipe.
XSee the MAKING TARGETS section for a description of how
X.B dmake
Xinvokes recipes.
XHere is an example of a group recipe:
X.sp
X.RS
X.nf
Xtarget :
X[
X\tfirst recipe line
X\tsecond recipe line
X\tall of these recipe lines are fed to a
X\tsingle copy of a shell for execution.
X]
X.fi
X.RE
X.sp
X.SH "TEXT DIVERSIONS"
X.B dmake
Xsupports the notion of text diversions.
XIf a recipe line contains the macro expression
X.RS
X.sp
X$(mktmp[,\fIname_modifier\fP] \fIdata\fP)
X.sp
X.RE
Xthen all text contained in the \fIdata\fP expression is expanded and
Xis written to a new temporary file.  The name of that file is then returned
Xas the value of the macro expansion and is substituted for the text of the
Xmacro expression if no \fIname_modifier\fP is present.
X.PP
X.I data
Xcan be any text and must be separated from the 'mktmp' portion of the
Xmacro name by white-space.  The only restriction on the data text is that
Xit must contain an balanced number of parentheses of the same kind as are
Xused to initiate the $(mktmp ...) expression.  For example:
X.sp
X\t$(mktmp $(XXX))
X.sp
Xis legal and works as expected, but:
X.sp
X\t$(mktmp text (to dump to file)
X.sp
Xis not legal.  You can achieve what you wish by either defining a macro that
Xexpands to '(' or by using {} in the macro expression; like this:
X.sp
X\t${mktmp text (to dump to file}
X.sp
Xwhich works as expected.  Since the temporary file is opened when the
Xmacro containg the text diversion expression is expanded, diversions may
Xnow be nested and any diversions that are created as part of ':=' macro
Xexpansions persist for the duration of the
X.B dmake
Xrun.
XThe diversion text may contain
Xthe same escape codes as those described in the MACROS section.
XThus if the \fIdata\fP text is to contain new lines they must be inserted
Xusing the \\n escape sequence.  For example the expression:
X.RS
X.sp
X.nf
Xall:
X	cat $(mktmp this is a\\n\\
X	test of the text diversion\\n)
X.fi
X.sp
X.RE
Xis replaced by:
X.RS
X.sp
Xcat /tmp/mk12294AA
X.sp
X.RE
Xwhere the temporary file contains two lines both of which are terminated
Xby a new-line.  If the \fIdata\fP text spans multiple lines in the makefile
Xthen each line must be continued via the use of a \\.
XA second more illustrative example generates a response file to an MSDOS
Xlink command:
X.RS
X.sp
X.nf
XOBJ = fred.obj mary.obj joe.obj
Xall : $(OBJ)
X	link @$(mktmp $(^:t"+\\n")\\n)
X.fi
X.sp
X.RE
XThe result of making `all' in the second example is the command:
X.RS
X.sp
Xlink @/tmp/mk02394AA
X.sp
X.RE
Xwhere the temporary file contains:
X.RS
X.sp
X.nf
Xfred.obj+
Xmary.obj+
Xjoe.obj
X.fi
X.sp
X.RE
XThe last line of the file is terminated by a new-line which is inserted
Xdue to the \\n found at the end of the \fIdata\fP string.
X.PP
XIf the optional 
X.I name_modifier
Xis supplied in the diversion expression then the returned value of the 
Xexpression is the expanded value of \fIname_modifier\fP.  Together with
Xthe special macros TMPFILE and USESHELL this can be
Xused to alter the name of the temporary file returned as the result of the
X$(mktmp ...) expansion.
X.PP
XUnder MS-DOS text diversions may be a problem.  Many DOS tools require
Xthat path names which contain directories use the \\ character to delimit
Xthe directories.  Some users however wish to use the '/' to delimit pathnames
Xon their system and use environments that allow them to do so.  These
Xenvironments usually accept the \\ delimited path names as well.
XIn order to allow the user the most flexibility
X.B dmake
Xdefines three macros that can be used when text diversion file names are being
Xplaced into the recipe text to be executed.  The macro TMPFILE contains
Xthe name of the most recently opened temporary file, and
Xthe macro, USESHELL, is set to "yes" if the
Xcurrent recipe is forced to use a shell via the .USESHELL or '+' directives,
Xotherwise its value is "no".
XIn the absence of a \fIname_modifier\fP in the diversion expression the result
Xof expanding the diversion expression is the value of TMPFILE.
XThe
X.B dmake
Xstartup files define the macro DIVFILE whose value is either the
Xvalue of TMPFILE or the value of TMPFILE editted to replace any '/' characters
Xto the appropriate value based on the current shell and whether it will be
Xused to execute the recipe.
X.PP
XPrevious versions of
X.B dmake
Xdefined text diversions using <+, +> strings,
Xwhere <+ started a text diversion and +> terminated one.
X.B dmake
Xis backward compatible with this construct if the <+ and +> appear literally
Xon the same recipe line or in the same macro value string.  In such instances
Xthe expression:
X.sp
X\t<+data text+>
X.sp
Xis mapped to:
X.sp
X\t$(mktmp data text)
X.sp
Xwhich is fully output compatible with the earlier construct.  <+, +>
Xconstructs whose text spans multiple lines must be converted by hand to use
X$(mktmp ...).
X.PP
XIf the environment variable TMPDIR is defined then the
Xtemporary file is placed into the directory specified by that variable.
XA makefile can modify the location of temporary files by
Xdefining a macro named TMPDIR and exporting it using the .EXPORT special
Xtarget.
X.SH "SPECIAL TARGETS"
XThis section describes the special targets that are recognized by \fBdmake\fP.
XSome are affected by attributes and others are not.
X.IP \fB.ERROR\fP 1.4i
XIf defined then the recipe associated with this target is executed
Xwhenever an error condition is detected by \fBdmake\fP.  All attributes that
Xcan be used with any other target may be used with this target.  Any
Xprerequisites of this target will be brought up to date during it's processing.
XNOTE:  errors will be ignored while making this target, in extreme cases this
Xmay cause some problems.
X.IP \fB.EXPORT\fP 1.4i
XAll prerequisites associated with this target are assumed to
Xcorrespond to macro names and they and their values
Xare exported to the environment as environment strings at the point in
Xthe makefile at which this target appears.
XAny attributes specified with this target are ignored.
XOnly macros which have been assigned a value in the makefile prior to the
Xexport directive are exported, macros as yet undefined are not exported.
X.IP \fB.IMPORT\fP 1.4i
XPrerequisite names specified for this target are searched for in the
Xenvironment and defined as macros with their value taken from the environment.
XIf the name cannot be found in the environment an error message is issued.
X\&.IMPORT accepts the .IGNORE attribute.  When given, it causes \fBdmake\fP
Xto ignore the above error.
XSee the MACROS section for a description of the processing of imported macro
Xvalues.
X.IP \fB.INCLUDE\fP 1.4i
XParse another makefile just as if it had been located at the point of the
X\&.INCLUDE in the current makefile.  The list of prerequisites gives the list of
Xmakefiles to try to read.  If the list contains multiple makefiles then they
Xare read in order from left to right.  The following search rules are used
Xwhen trying to locate the file.  If the filename is surrounded by " or just
Xby itself then it is searched for in the current directory.  If it is not
Xfound it is then searched for in each of the directories specified for the
X\&.INCLUDEDIRS special target.  If the file name is surrounded by < and >, (ie.
X<my_spiffy_new_makefile>) then it is searched for only in the directories
Xgiven by the .INCLUDEDIRS special target.  In both cases if the file name is a
Xfully qualified name starting at the root of the file system then it is only
Xsearched for once, and the .INCLUDEDIRS list is ignored.  .INCLUDE accepts
Xthe .IGNORE and .SETDIR attributes.  If .IGNORE attribute is given and the file
Xcannot be found then \fBdmake\fP continues processing,
Xotherwise an error message is generated.
XThe .SETDIR attribute causes
X.B dmake
Xto change directories to the specified directory prior to attempting the
Xinclude operation.
X.IP \fB.INCLUDEDIRS\fP 1.4i
XThe list of prerequisites specified for this target defines the set of
Xdirectories to search when trying to include a makefile.
X.IP \fB.MAKEFILES\fP 1.4i
XThe list of prerequisites is the set of files to try to read as the default
Xmakefile.  By default this target is defined as: 
X.sp
X\t\&.MAKEFILES : makefile.mk Makefile makefile
X.sp
X.IP \fB.SOURCE\fP 1.4i
XThe prerequisite list of this target defines a set of directories to check
Xwhen trying to locate a target file name.  See the section on BINDING of
Xtargets for more information.
X.IP \fB.SOURCE.suff\fP 1.4i
XThe same as .SOURCE, except that the .SOURCE.suff list is searched first when
Xtrying to locate a file matching the a target whose name ends in the suffix
X\&.suff.
X.IP \fB.REMOVE\fP 1.4i
XThe recipe of this target is used whenever \fBdmake\fP needs to remove
Xintermediate targets that were made but do not need to be kept around.
XSuch targets result from the application of transitive closure on the
Xdependency graph.
X.PP
XIn addition to the special targets above,
Xseveral other forms of targets are recognized and are considered special,
Xtheir exact form and use is defined in the sections that follow.
X.SH "SPECIAL MACROS"
X.B dmake
Xdefines a number of special macros.  They are divided into three classes:
Xcontrol macros, run-time macros, and function macros.
XThe control macros are used by
X.B dmake
Xto configure it's actions, and are the preferred method of doing so.
XIn the case when a control macro has the same function as a special 
Xtarget or attribute they share the same name as the special target or
Xattribute.
XThe run-time macros are defined when
X.B dmake
Xmakes targets and may be used by the user inside recipes.
XThe function macros provide higher level functions dealing with macro
Xexpansion and diversion file processing.
X.SH "CONTROL MACROS"
XTo use the control macros simply assign them a value just like any other
Xmacro.  The control macros are divided into three groups:
Xstring valued macros, character valued macros, and boolean valued macros.
X.PP
XThe following are all of the string valued macros.
XThis list is divided into two groups.  The first group gives the string
Xvalued macros that are defined internally and cannot be directly set by the
Xuser.
X.IP \fBDIRBRKSTR\fP 1.4i
XContains the string of chars used to terminate
Xthe name of a directory in a pathname.
XUnder UNIX it's value is "/", under MSDOS it's value is "/\\:".
X.IP \fBINCDEPTH\fP 1.4i
XThis macro's value is a string of digits representing
Xthe current depth of makefile inclusion.
XIn the first makefile level this value is zero.
X.IP \fBMFLAGS\fP 1.4i
XIs the list of flags
Xthat were given on the command line including a leading switch character.
XThe -f flag is not included in this list.
X.IP \fBMAKECMD\fP 1.4i
XIs the name with which \fBdmake\fP was invoked.
X.IP \fBMAKEDIR\fP 1.4i
XIs the full path to the initial directory in which
X.B dmake
Xwas invoked.
X.IP \fBMAKEFILE\fP 1.4i
XContains the string "-f \fImakefile\fP" where, \fImakefile\fP is the name
Xof initial user makefile that was first read.
X.IP \fBMAKEFLAGS\fP 1.4i
XIs the same as $(MFLAGS) but has no leading switch
Xcharacter. (ie. MFLAGS = -$(MAKEFLAGS))
X.IP \fBMAKEMACROS\fP 1.4i
XContains the complete list of macro expressions that were specified on the
Xcommand line.
X.IP \fBMAKETARGETS\fP 1.4i
XContains the name(s) of the target(s), if any, that were
Xspecified on the command line.
X.IP \fBMAXPROCESSLIMIT\fP 1.4i
XIs a numeric string representing the maximum number of processes that 
X\fBdmake\fP can use when making targets using parallel mode.
X.IP \fBNULL\fP 1.4i
XIs permanently defined to be the NULL string.
XThis is useful when comparing a conditional expression to an NULL value.
X.IP \fBPWD\fP 1.4i
XIs the full path to the
Xcurrent directory in which make is executing.
X.IP \fBTMPFILE\fP 1.4i
XIs set to the name of the most recent temporary file opened by \fBdmake\fP.
XTemporary files are used for text diversions and for group recipe processing.
X.IP \fBTMD\fP 1.4i
XStands for "To Make Dir", and
Xis the path from the present directory (value of $(PWD)) to the directory
Xthat \fBdmake\fP was started up in (value of $(MAKEDIR)).
XThis macro is modified when .SETDIR attributes are processed.
X.IP \fBUSESHELL\fP 1.4i
XThe value of this macro is set to "yes" if the current recipe is forced to
Xuse a shell for its execution via the .USESHELL or '+' directives, its value
Xis "no" otherwise.
X.sp
X.PP
XThe second group of string valued macros control
X.B dmake
Xbehavior and may be set by the user.
X.IP \fB.SETDIR\fP 1.6i
XIf this macro is assigned a value then \fBdmake\fP will
Xchange to the directory given by that value before making any targets.  This
Xmacro is equivalent to the .SETDIR attribute.  Thus the two lines:
X.sp
X\&.SETDIR=fred/hello :
X.sp
X\&.SETDIR := fred/hello
X.sp
Xare completely equivalent.  The difference being that the first is processed
Xas a rule definition and the other as a macro.
X.IP \fBAUGMAKE\fP 1.6i
XIf set to a non NULL value will enable the transformation of special
Xmeta targets to support special AUGMAKE inferences.
X.IP \fBDIRSEPSTR\fP 1.6i
XContains the string that is used to separate directory components when
Xpath names are constructed.  It is defined with a default value at startup.
X.IP \fBDIVFILE\fP 1.6i
XIs defined in the startup file and gives the name that should be used for
Xthe diversion file name when specified as the name modifier in
X$(mktmp ...) expansions, see the TEXT DIVERSION section for details.
X.IP \fBGROUPFLAGS\fP 1.6i
XThis macro gives the set of flags to pass to the shell when
Xinvoking it to execute a group recipe.  The value of the macro is the
Xlist of flags with a leading switch indicator.  (ie. `-' under UNIX)
X.IP \fBGROUPSHELL\fP 1.6i
XThis macro defines the full
Xpath to the executable image to be used as the shell when
Xprocessing group recipes.  This macro must be defined if group recipes are
Xused.  It is assigned a default value in the startup makefile.  Under UNIX
Xthis value is /bin/sh.
X.IP \fBGROUPSUFFIX\fP 1.6i
XIf defined, this macro gives the string to use as a suffix
Xwhen creating group recipe files to be handed to the command interpreter.
XFor example, if it is defined as .sh, then all
Xtemporary files created by \fBdmake\fP will end in the suffix .sh.
XUnder MSDOS if you are using command.com as your GROUPSHELL, then this suffix
Xmust be set to .bat in order for group recipes to function correctly.
X.IP \fBMAKE\fP 1.6i
XIs defined in the startup file by default.
XThe string $(MAKE) is recognized when
Xusing the -n option for single line recipes.  Initially this macro is defined
Xto have the value "$(MAKECMD) $(MFLAGS)".
X.IP \fBMAKESTARTUP\fP 1.6i
XThis macro defines the full path to the initial startup
Xmakefile.  Use the \fB-V\fP command line option to discover it's initial
Xvalue.
X.IP \fBMAXLINELENGTH\fP 1.6i
XThis macro defines the maximum size of a single line of
Xmakefile input text.  The size is specified as a number, the default value
Xis defined internally and is shown via the \fB-V\fP option.
XA buffer of this size plus 2 is allocated for reading makefile text.  The
Xbuffer is freed before any targets are made, thereby allowing files containing
Xlong input lines to be processed without consuming memory during the actual
Xmake.
X.IP \fBMAXPROCESS\fP 1.6i
XSpecify the maximum number of child processes to use when making targets.
XThe default value of this macro is "1" and it's value cannot exceed the value
Xof the macro MAXPROCESSLIMIT.  Setting the value of MAXPROCESS on the command
Xline or in the makefile is equivalent to supplying a corresponding value to
Xthe -P flag on the command line.
X.IP \fBPREP\fP 1.6i
XThis macro defines the number of iterations to be expanded
Xautomatically when processing % rule definitions of the form:
X.sp
X% : %.suff
X.sp
XSee the sections on PERCENT(%) RULES for details on how PREP is used.
X.IP \fBSHELL\fP 1.6i
XThis macro defines the full path to the executable
Ximage to be used as the shell when
Xprocessing single line recipes.  This macro must be defined if recipes
Xrequiring the shell for execution are to be used.
XIt is assigned a default value in the startup makefile.
XUnder UNIX this value is /bin/sh.
X.IP \fBSHELLFLAGS\fP 1.6i
XThis macro gives the set of flags to pass to the shell when
Xinvoking it to execute a single line recipe.  The value of the macro is the
Xlist of flags with a leading switch indicator.  (ie. `-' under UNIX)
X.IP \fBSHELLMETAS\fP 1.6i
XEach time
X.B dmake
Xexecutes a single recipe line (not a group recipe) the line is
Xsearched for any occurrence of a character defined in the value of SHELLMETAS.
XIf such a character is found the recipe line is defined to require a shell
Xto ensure it's correct execution.  In such instances
Xa shell is used to invoke the recipe line.
XIf no match is found the recipe line is executed without the use of a shell.
X.sp
X.PP
XThere is only one character valued macro defined by \fBdmake\fP:
X\fBSWITCHAR\fP contains the switch character used
SHAR_EOF
echo "End of part 11"
echo "File man/dmake.tf is continued in part 12"
echo "12" > s2_seq_.tmp
exit 0