Usenet 1994 January/usenetsourcesnewsgroupsinfomagicjanuary1994.iso/sources/misc/volume27/dmake/part17

Text File | 1992-01-29 | 40.2 KB | 1,123 lines

Newsgroups: comp.sources.misc
From: [e-mail] (Dennis Vadura)
Subject:  v27i118:  dmake - dmake Version 3.8, Part17/41
Message-ID: <[e-mail]>
X-Md4-Signature: 5dab39e4279c3944c41d4946f3ca28ca
Date: Tue, 28 Jan 1992 21:41:01 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Dennis Vadura)
Posting-number: Volume 27, Issue 118
Archive-name: dmake/part17
Environment: Atari-ST, Coherent, Mac, MSDOS, OS/2, UNIX
Supersedes: dmake: Volume 19, Issue 22-58

---- Cut Here and feed the following to sh ----
# this is dmake.shar.17 (part 17 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" != 17; 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' &&
.B dmake
will attempt to make the target.
.PP
If no
.B \-f
command line option is present then
.B dmake
searches for an existing
.I makefile
from the list of prerequisites specified for the special target \fI.MAKEFILES\fR
(see the STARTUP section for more details).
If "\-" is the name of the file specified to the
.B \-f
flag then \fBdmake\fR uses standard input as the source of the makefile text.
.PP
Any macro definitions (arguments with embedded "="
signs) that appear on the command line are processed first
and supersede definitions for macros of the same name found
within the makefile.  In general it is impossible for definitions found
inside the makefile to redefine a macro defined on the command line, see the
MACROS section for an exception.
.PP
If no
.I target
names are specified on the command line, then \fBdmake\fR uses the first
non-special target found in the makefile as the default target.
See the
.B "SPECIAL TARGETS"
section for the list of special targets and their function.
\fBdmake\fR is a re-implementation of the UNIX Make utility with
significant enhancements.  Makefiles written for most previous
versions of
.I Make
will be handled correctly by
.B dmake.
Known differences between \fBdmake\fR and other versions of make
are discussed in the
.B COMPATIBILITY
section found at the end of this document.
.SH OPTIONS
.IP "\fB\-A\fR"
Enable AUGMAKE special inference rule transformations
(see the "PERCENT(%) RULES" section), these are set to off by default.
.IP "\fB\-B\fR"
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.
.IP "\fB\-c\fR"
Use non-standard comment stripping.  If you specify \fB\-c\fP then
.B dmake
will treat any \fB#\fP character as a start of comment character wherever it
may appear unless it is escaped by a \e.
.IP "\fB\-C [+]file\fR"
This option writes to \fIfile\fP a copy of standard output and
standard error from any child processes and from the
.B dmake
process itself.  If you specify a \fB+\fP prior to the file name then
the text is appended to the previous contents of \fIfile\fP.
This option is active in the MSDOS implementation only and is ignored
by non-MSDOS versions of
.B dmake.
.IP "\fB\-E\fR"
Read the environment and define all strings of the
form '\fBENV\-VAR\fP=\fIevalue\fP'
defined within as macros whose name is \fBENV\-VAR\fP,
and whose value is '\fIevalue\fP'.
The environment is processed prior to processing the user
specified makefile thereby allowing definitions in the makefile to override
definitions in the environment.
.IP "\fB\-e\fR"
Same as \-E, except that the environment is processed 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.
.IP "\fB\-f file\fR"
Use \fBfile\fR as the source for the makefile text.
Only one \fB\-f\fR option is allowed.
.IP "\fB\-h\fR"
Print the command summary for \fBdmake\fR.
.IP "\fB\-i\fR"
Tells \fBdmake\fR to ignore errors, and continue making other targets.
This is equivalent to the .IGNORE attribute or macro.
.IP "\fB\-K file\fR"
Turns on \fB.KEEP_STATE\fP state tracking and tells \fBdmake\fP to use
\fIfile\fP as the state file.
.IP "\fB\-k\fR"
Causes \fBdmake\fR to ignore errors caused by command execution and to make
all targets not depending on targets that could not be made.
Ordinarily \fBdmake\fR stops after a command returns a non-zero status,
specifying \fB\-k\fR causes \fBdmake\fR to ignore the error
and continue to make as much as possible.
.IP "\fB\-n\fR"
Causes \fBdmake\fR to print out what it would have executed,
but does not actually execute the commands.  A special check is made for
the string "$(MAKE)" inside a recipe line, if found, the line is expanded
and invoked, thereby enabling recursive makes to give a full
description of all that they will do.
The check for "$(MAKE)" is disabled inside group recipes.
.IP "\fB\-p\fR"
Print out a version of the digested makefile in human readable form.
(useful for debugging, but cannot be re-read by \fBdmake\fP)
.IP "\fB\-P#\fR"
On systems that support multi-processing cause \fBdmake\fP to use \fI#\fP
concurrent child processes to make targets.
See the "MULTI PROCESSING" section for more information.
.IP "\fB\-q\fR"
Check and see if the target is up to date.  Exits with code 0 if up to date,
1 otherwise.
.IP "\fB\-r\fR"
Tells \fBdmake\fR not to read the initial startup makefile, see STARTUP
section for more details.
.IP "\fB\-s\fR"
Tells \fBdmake\fR 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.
.IP "\fB\-S\fR"
Force sequential execution of recipes on architectures which support
concurrent makes.  For backward compatibility with old makefiles that have
nasty side-effect prerequisite dependencies.
.IP "\fB\-t\fR"
Causes \fBdmake\fR 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.
.IP "\fB\-T\fR"
Tells \fBdmake\fP to not perform transitive closure on the inference graph.
.IP "\fB\-u\fR"
Force an unconditional update.  (ie. do everything that would
be done if everything that a target depended on was out of date)
.IP "\fB\-v[dfimt]\fR"
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 \fB[dfimt]\fP can be
used to restrict the information that is displayed.  In the absence of any
optional flags all are assumed to be given (ie. \fB\-v\fP is equivalent to
\fB\-vdfimt\fP).  The meanings of the optional flags are:
.RS
.IP "\fBd\fP"
Notify of change directory operations only.
.IP "\fBf\fP"
Notify of file I/O operations only.
.IP "\fBi\fP"
Notify of inference algorithm operation only.
.IP "\fBm\fP"
Notify of target update operations only.
.IP "\fBt\fP"
Keep any temporary files created; normally they are automatically deleted.
.RE
.IP "\fB\-V\fR"
Print the version of \fBdmake\fR, and values of builtin macros.
.IP "\fB\-x\fR"
Upon processing the user makefile export all non-internally defined macros
to the user's environment.  This option together with the \-e option
allows SYSV AUGMAKE recursive makes to function as expected.
.SH INDEX
Here is a list of the sections that follow and a short description of each.
Perhaps you won't have to read the whole man page to find
what you need.
.IP \fBSTARTUP\fP 1.9i
Describes \fBdmake\fP initialization.
.IP \fBSYNTAX\fP 1.9i
Describes the syntax of makefile expressions.
.IP \fBATTRIBUTES\fP 1.9i
Describes the notion of attributes and how they are used when
making targets.
.IP \fBMACROS\fP 1.9i
Defining and expanding macros.
.IP "\fBRULES AND TARGETS" 1.9i
How to define targets and their prerequisites.
.IP \fBRECIPES\fP 1.9i
How to tell \fBdmake\fP how to make a target.
.IP "\fBTEXT DIVERSIONS\fP" 1.9i
How to use text diversions in recipes and macro expansions.
.IP "\fBSPECIAL TARGETS\fP" 1.9i
Some targets are special.
.IP "\fBSPECIAL MACROS\fP" 1.9i
Macros used by \fBdmake\fP to alter the processing of the makefile,
and those defined by \fBdmake\fP for the user.
.IP "\fBCONTROL MACROS\fP" 1.9i
Itemized list of special control macros.
.IP "\fBRUN-TIME MACROS\fP" 1.9i
Discussion of special run-time macros such as $@ and $<.
.IP "\fBFUNCTION MACROS\fP" 1.9i
GNU style function macros, only $(mktmp ...) for now.
.IP "\fBDYNAMIC PREREQUISITES\fP" 1.9i
Processing of prerequisites which contain macro expansions in their name.
.IP "\fBBINDING TARGETS\fP" 1.9i
The rules that \fBdmake\fP uses to bind
a target to an existing file in the file system.
.IP "\fBPERCENT(%) RULES\fP" 1.9i
Specification of recipes to be used by the inference algorithm.
.IP "\fBMAKING INFERENCES\fP" 1.9i
The rules that \fBdmake\fP uses when inferring how to make a target which
has no explicit recipe.  This and the previous section are really a single
section in the text.
.IP "\fBMAKING TARGETS\fP" 1.9i
How \fBdmake\fP makes targets other than libraries.
.IP "\fBMAKING LIBRARIES\fP" 1.9i
How \fBdmake\fP makes libraries.
.IP "\fBKEEP STATE\fP" 1.9i
A discussion of how .KEEP_STATE works.
.IP "\fBMULTI PROCESSING\fP" 1.9i
Discussion of \fBdmake's\fP parallel make facilities for architectures that
support them.
.IP "\fBCONDITIONALS\fP" 1.9i
Conditional expressions which control the processing of the makefile.
.IP "\fBEXAMPLES\fP" 1.9i
Some hopefully useful examples.
.IP "\fBCOMPATIBILITY\fP" 1.9i
How \fBdmake\fP compares with previous versions of make.
.IP "\fBLIMITS\fP" 1.9i
Limitations of \fBdmake\fP.
.IP \fBPORTABILITY\fP 1.9i
Comments on writing portable makefiles.
.IP \fBFILES\fP 1.9i
Files used by \fBdmake\fP.
.IP "\fBSEE ALSO\fP" 1.9i
Other related programs, and man pages.
.IP "\fBAUTHOR\fP" 1.9i
The guy responsible for this thing.
.IP \fBBUGS\fP 1.9i
Hope not.
.SH STARTUP
When
.B 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,
.B dmake
searches the following locations, in the order specified,
until a startup file is located:
.LP
.RS
.IP 1.
The location given as the value of the macro
MAKESTARTUP defined on the command line.
.IP 2.
The location given as the value of the environment variable MAKESTARTUP
defined in the current environment.
.IP 3.
The location given as the value of the macro
MAKESTARTUP defined internally within \fBdmake\fP.
.RE
.LP
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 specified.
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
.B dmake
looks for the default startup file, check your environment or issue the command
\fI"dmake \-V"\fP.
.PP
A similar search is performed to locate a default user makefile when no
\fB\-f\fP 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
\fBdmake\fP should use to determine if one exists.
A typical definition for this target is:
.RS
.sp
\&.MAKEFILES : makefile.mk Makefile makefile
.sp
.RE
\fBdmake\fP will first look for makefile.mk and then the others.
If a prerequisite
cannot be found \fBdmake\fP 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.
.PP
If the first line of the user makefile is of the form:
.RS
.sp
\#! command command_args
.sp
.RE
then \fBdmake\fP will expand and run the command prior to reading any
addtional input.  If the return code of the command is zero then \fBdmake\fP
will continue on to process the remainder of the user makefile, if the return
code is non-zero then dmake will exit.
.SH SYNTAX
This section is a summary of the syntax of makefile statements.
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.  Alternative productions for a left hand side are indicated
by '\(->', and newlines are significant.  All symbols in \fBbold\fP type
are text or names representing text supplied by the user.
.sp 2
.RS
.Ip "Makefile" "\(-> { Statement }"
.Ip "Statement" "\(-> Macro-Definition"
\(-> Conditional
\(-> Rule-Definition
\(-> Attribute-Definition
.Ip "Macro-Definition" "\(-> \fBMACRO = LINE\fP"
\(-> \fBMACRO *= LINE\fP
\(-> \fBMACRO := LINE\fP
\(-> \fBMACRO *:= LINE\fP
\(-> \fBMACRO += LINE\fP
\(-> \fBMACRO +:= LINE\fP
.Ip "Conditional \(-> " "\fB\&.IF\fR expression"
X   Makefile
[ \fB.ELIF\fR expression
X   Makefile ]
[ \fB.ELSE\fR
X   Makefile ]
\fB\&.END\fR
.Ip expression    "\(-> \fBLINE\fR"
\(-> \fBSTRING == LINE\fR
\(-> \fBSTRING != LINE\fR
.sp
.Ip "Rule-Definition \(-> " "target-definition"
X   [ recipe ]
.PP
target-definition \(-> targets [attrs] op { \fBPREREQUISITE\fP } [\fB;\fR rcp-line]
.Ip "targets" "\(-> target { targets }"
\(-> \fB"\fRtarget\fB"\fR { targets }
.Ip "target" "\(-> special-target"
\(-> \fBTARGET\fR
.Ip "attrs" "\(-> attribute { attrs }"
\(-> \fB"\fRattribute\fB"\fR { attrs }
.Ip "op" "\(-> \fB:\fR { modifier }"
.Ip "modifier" "\(-> \fB:\fR"
\(-> \fB^\fR
\(-> \fB!\fR
\(-> \fB\-\fR
.Ip "recipe" "\(-> { \fBTAB\fR rcp-line }"
\(-> [\fB@\fR][\fB%\fR][\fB\-\fR] \fB[
.Is "recipe \(-> "
.Ii " "
X   \fR{ \fBLINE\fR }
.Ii " "
\fB]\fR
.Ip "rcp-line" "\(-> [\fB@\fR][\fB%\fR][\fB\-\fR][\fB+\fR] \fBLINE\fR"
.sp
.Ip Attribute-Definition "\(-> attrs \fB:\fR targets"
.sp
.Ip "attribute"     "\(-> \fB.EPILOG\fR"
\(-> \fB.IGNORE\fR
\(-> \fB.LIBRARY\fR
\(-> \fB.MKSARGS\fR
\(-> \fB.NOINFER\fR
\(-> \fB.NOSTATE\fR
\(-> \fB.PHONY\fR
\(-> \fB.PRECIOUS\fR
\(-> \fB.PROLOG\fR
\(-> \fB.SETDIR=\fIpath\fP\fR
\(-> \fB.SILENT\fR
\(-> \fB.SEQUENTIAL\fR
\(-> \fB.SWAP\fR
\(-> \fB.USESHELL\fR
\(-> \fB.SYMBOL\fR
\(-> \fB.UPDATEALL\fR
.Ip "special-target" "\(-> \fB.ERROR\fR"
\(-> \fB.EXPORT\fR
\(-> \fB.GROUPEPILOG\fR
\(-> \fB.GROUPPROLOG\fR
\(-> \fB.IMPORT\fR
\(-> \fB.INCLUDE\fR
\(-> \fB.INCLUDEDIRS\fR
\(-> \fB.MAKEFILES\fR
\(-> \fB.REMOVE\fR
\(-> \fB.SOURCE\fR
\(-> \fB.SOURCE.\fIsuffix\fR
\(-> .\fIsuffix1\fR.\fIsuffix2\fR
.fi
.RE
.sp 1
.PP
Where, \fBTAB\fP represents a <tab> character, \fBSTRING\fP represents an
arbitrary sequence of characters, and
\fBLINE\fP represents a
possibly empty sequence of characters terminated by a non-escaped
(not immediately preceded by a backslash '\e') new-line character.
\fBMACRO\fP, \fBPREREQUISITE\fP,
and \fBTARGET\fP each represent 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 \fBLINE\fP can be continued over several physical lines by terminating it with
a single backslash character.  Comments are initiated by the
pound \fB#\fR 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 '\e' (ie. \e# translates to # when it is parsed).
An exception 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 \fB\-c\fP command line switch then this behavior is
disabled and
.B dmake
will treat all # characters as start of comment indicators unless they
are escaped by \e.
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 \e<nl>
when \e<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 \e<nl> is treated as
white space during recipe expansion
and is deleted from the final recipe string.
You must escape the \e<nl> with another \e in order to get a \e at the end
of a recipe line.
The \e<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.  Quoted target and prerequisite
specifications may also contain white space thereby allowing the use of
complex function macro expressions..
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, .NOSTATE, .PHONY, .SETDIR, .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 \ea => <bel>,
\&\eb => <backspace>, \ef => <formfeed>, \en => <nl>, \er => <cr>,
\&\et => <tab>, \ev => <vertical tab>, \e" => ", and \exxx => <xxx> where
xxx is the octal representation of a character.  Thus the
expansion:
.LP
.RS
.nf
$(test:f:t"+\en")
.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@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}
SHAR_EOF
true || echo 'restore of dmake/man/dmake.tf failed'
fi
echo 'End of part 17, continue with part 18'
echo 18 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...