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

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

Newsgroups: comp.sources.misc
From: [e-mail] (Dennis Vadura)
Subject:  v27i119:  dmake - dmake Version 3.8, Part18/41
Message-ID: <[e-mail]>
X-Md4-Signature: 7fdf4a53c7fbf586bb2803b75065e813
Date: Tue, 28 Jan 1992 21:41:38 GMT
Approved: [e-mail]

Submitted-by: [e-mail] (Dennis Vadura)
Posting-number: Volume 27, Issue 119
Archive-name: dmake/part18
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.18 (part 18 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" != 18; 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' &&
.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 \en escape sequence.  For example the expression:
.RS
.sp
.nf
all:
X    cat $(mktmp this is a\en\e
X    test of the text diversion\en)
.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 \e.
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"+\en")\en)
.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 \en 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 \e 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
or macros whose value contains any of the characters "+=:*"
are not exported.
is suppre
.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 "/\e:".
.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.NOTABS\fP 1.6i
When set to non-NULL enables the use of spaces as well as <tabs> to begin
recipe lines.
By default a non\-group recipe is terminated by a line without any leading
white\-space or by a line not beggining with a <tab> character.
Enabling this mode modifies the first condition of
the above termination rule to terminate a
non\-group recipe with a line that contains only white\-space.
This mode does not effect the parsing of group recipes bracketed by [].
.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.
This macro can only be used to extend the line length beyond it's default
minimum value.
.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
This macro gives the set of flags to pass to the shell when
invoking it to execute a single line recipe.  The value of the macro is the
list of flags with a leading switch indicator.  (ie. `\-' under UNIX)
.IP \fBSHELLMETAS\fP 1.6i
Each time
.B dmake
executes a single recipe line (not a group recipe) the line is
searched for any occurrence of a character defined in the value of SHELLMETAS.
If such a character is found the recipe line is defined to require a shell
to ensure its correct execution.  In such instances
a shell is used to invoke the recipe line.
If no match is found the recipe line is executed without the use of a shell.
.sp
.PP
There is only one character valued macro defined by \fBdmake\fP:
\fBSWITCHAR\fP contains the switch character used
to introduce options on command lines.  For UNIX its value is `\-', and for
MSDOS its value may be `/' or `\-'.
The macro is internally defined and is not user setable.
The MSDOS version of \fBdmake\fP attempts to first extract SWITCHAR from an
environment variable of the same name.  If that fails it then attempts to
use the undocumented getswitchar system call, and returns the result of
that.  Under MSDOS version 4.0 you must set the value of the environment
macro SWITCHAR to '/' to obtain predictable behavior.
.PP
All boolean macros currently understood by
.B dmake
correspond directly to the previously defined attributes.
These macros provide
a second way to apply global attributes, and represent the
preferred method of doing so.  They are used by assigning them a
value.  If the value is not a NULL string then the boolean condition
is set to on.
If the value is a NULL string then the condition is set to off.
There are five conditions defined and they correspond directly to the
attributes of the same name.  Their meanings are defined in the ATTRIBUTES
section above.
The macros are:
\&\fB.EPILOG\fP,
\&\fB.IGNORE\fP,
\&\fB.MKSARGS\fP,
\&\fB.NOINFER\fP,
\&\fB.PRECIOUS\fP,
\&\fB.PROLOG\fP,
\&\fB.SEQUENTIAL\fP,
\&\fB.SILENT\fP,
\&\fB.SWAP\fP, and
\&\fB.USESHELL\fP.
Assigning any of these a non NULL value will globally set
the corresponding attribute to on.
.SH "RUN_TIME MACROS"
These macros are defined
when \fBdmake\fP is making targets, and may take on different values for each
target.  \fB$@\fP is defined to be the full target name, \fB$?\fP is the
list of all out of date prerequisites, \fB$&\fP is the list of all
prerequisites, \fB$>\fP is the name of the library if the current target is a
library member, and
\fB$<\fP is the list of prerequisites specified in the current rule.
If the current target had a recipe inferred then \fB$<\fP is the name of the
inferred prerequisite even if the target had a list of prerequisites supplied
using an explicit rule that did not provide a recipe.  In such situations
\fB$&\fP gives the full list of prerequisites.
.PP
\fB$*\fP is defined as
\fB$(@:db)\fP when making targets with explicit recipes and is defined as the
value of % when making targets whose recipe is the result of an inference.
In the first case \fB$*\fP is the target name with no suffix,
and in the second case, is the value of the matched % pattern from
the associated %-rule.
\fB$^\fP expands to the set of out of date prerequisites taken from the
current value of \fB$<\fP.
In addition to these,
\fB$$\fP expands to $, \fB{{\fP expands to {, \fB}}\fP expands to }, and the
strings \fB<+\fP and \fB+>\fP are recognized
as respectively starting and terminating a text diversion when they appear
literally together in the same input line.
.PP
The difference between $? and $^ can best be illustrated by an example,
consider:
.RS
.sp
.nf
fred.out : joe amy hello
\trules for making fred
X
fred.out : my.c your.h his.h her.h      # more prerequisites
.fi
.sp
.RE
Assume joe, amy, and my.c are newer then fred.out.  When
.B dmake
executes the recipe for making fred.out the values of the following macros
will be:
.RS
.sp
.nf
.Is "$@ "
.Ii "$@"
--> fred.out
.Ii "$*"
--> fred
.Ii "$?"
--> joe amy my.c  # note the difference between $? and $^
.Ii "$^"
--> joe amy
.Ii "$<"
--> joe amy hello
.Ii "$&"
--> joe amy hello my.c your.h his.h her.h
.fi
.sp
.RE
.SH "FUNCTION MACROS"
.B dmake
supports a full set of functional macros.  One of these, the $(mktmp ...)
macro, is discussed in detail in the TEXT DIVERSION section and is not
covered here.
.RS
.sp
.IP "$(\fBnull\fP,\fItext\fP \fBtrue\fP \fBfalse\fP)"
expands the value of
.I text.
If it is NULL then the macro returns the value of the expansion of \fBtrue\fP
and the expansion of \fBfalse\fP otherwise.  The terms \fBtrue\fP, and
\fBfalse\fP must be strings containing no white\-space.
.IP "$(\fB!null\fP,\fItext\fP \fBtrue\fP \fBfalse\fP)"
Behaves identically to the previous macro except that the
.B true
string is chosen if the expansion of
.I text
is not NULL.
.IP "$(\fBeq\fP,\fItext_a\fP,\fItext_b\fP \fBtrue\fP \fBfalse\fP)"
expands
.I text_a
and
.I text_b
and compares their results.  If equal it returns the result of the expansion
of the
.B true
term, otherwise it returns the expansion of the
.B false
term.
.IP "$(\fB!eq\fP,\fItext_a\fP,\fItext_b\fP \fBtrue\fP \fBfalse\fP)"
Behaves identically to the previous macro except that the
.B true
string is chosen if the expansions of the two strings are not equal
.IP "$(\fBshell\fP \fBcommand\fP)"
Runs \fIcommand\fP as if it were part of a recipe and returns,
separated by a single space, all the non-white
space terms written to stdout by the command.
For example:
.RS
.RS
.sp
$(shell ls *.c)
.sp
.RE
will return \fI"a.c b.c c.c d.c"\fP if the files exist in the current
directory.  The recipe modification flags \fB[+@%\-]\fP are honored if they
appear as the first characters in the command.  For example:
.RS
.sp
$(shell +ls *.c)
.sp
.RE
will run the command using the current shell.
.RE
.IP "$(\fBsort\fP \fBlist\fP)"
Will take all white\-space separated tokens in \fIlist\fP and will
return their sorted equivalent list.
.IP "$(\fBstrip\fP \fBdata\fP)"
Will replace all strings of white\-space in data by a single space.
.IP "$(\fBsubst\fP,\fIpat\fP,\fIreplacement\fP \fBdata\fP)"
Will search for \fIpat\fP in
.B data
and will replace any occurrence of
.I pat
with the
.I replacement
string.
.RS
The expansion
.RS
.sp
$(subst,.o,.c $(OBJECTS))
.sp
.RE
is equivalent to:
.RS
.sp
$(OBJECTS:s/.o/.c/)
.sp
.RE
.RE
.SH "DYNAMIC PREREQUISITES"
.B dmake
looks for prerequisites whose names contain macro expansions during target
processing.  Any such prerequisites are expanded and the result of the
expansion is used as the prerequisite name.  As an example the line:
.sp
\tfred : $$@.c
.sp
causes the $$@ to be expanded when \fBdmake\fP is making fred, and it resolves
to the target \fIfred\fP.
This enables dynamic prerequisites to be generated.  The value
of @ may be modified by any of the valid macro modifiers.  So you can say for
example:
.sp
\tfred.out : $$(@:b).c
.sp
where the $$(@:b) expands to \fIfred\fP.
Note the use of $$ instead of $ to indicate the dynamic expansion, this
is due to the fact that the rule line is expanded when it is initially parsed,
and $$ then returns $ which later triggers the dynamic prerequisite expansion.
If you really want a $ to be part of a prerequisite name you must use $$$$.
Dynamic macro expansion is performed in all user defined rules,
and the special targets .SOURCE*, and .INCLUDEDIRS.
.SH "BINDING TARGETS"
This operation takes a target name and binds it to an existing file, if
possible.
.B dmake
makes a distinction between the internal target name of a target and its
associated external file name.
Thus it is possible for a target's internal name and its external
file name to differ.
To perform the binding, the following set of rules is used.
Assume that we are
trying to bind a target whose name is of the form \fIX.suff\fP,
where \fI.suff\fP is the suffix and \fIX\fP is the stem portion
(ie. that part which contains the directory and the basename).
.B dmake
takes this target name and performs a series of search operations that try to
find a suitably named file in the external file system.
The search operation is user controlled
via the settings of the various .SOURCE targets.
.RS
.IP 1.
If target has the .SYMBOL attribute set then look for it in the library.
If found, replace the target name with the library member name and continue
with step 2.  If the name is not found then return.
.IP 2.
Extract the suffix portion (that following the `.') of the target name.
If the suffix is not null, look up the special target .SOURCE.<suff>
(<suff> is the suffix).
If the special target exists then search each directory given in
the .SOURCE.<suff> prerequisite list for the target.
If the target's suffix was null (ie. \fI.suff\fP was empty) then
perform the above search but use the special target .SOURCE.NULL instead.
If at any point a match is found then terminate the search.
If a directory in the prerequisite list is the special name `.NULL ' perform
a search for the full target name without prepending any directory portion
(ie. prepend the NULL directory).
(a default target of '.SOURCE : .NULL' is defined by \fBdmake\fP at startup,
and is user redefinable)
.IP 3.
The search in step 2. failed.  Repeat the same search but this time
use the special target .SOURCE.
.IP 4.
The search in step 3. failed.
If the target has the library member attribute (.LIBMEMBER)
set then try to find the target in the library which was passed along
with the .LIBMEMBER attribute (see the MAKING LIBRARIES section).
The bound file name assigned to a target which is successfully
located in a library is the same name that would be assigned had the search
failed (see 5.).
.IP 5.
The search failed.  Either the target was not found in any of the search
directories or no applicable .SOURCE special targets exist.
If applicable .SOURCE special targets exist, but the target was not found,
then \fBdmake\fP assigns the first name searched as the bound file name.
If no applicable .SOURCE special targets exist,
then the full original target name becomes the bound file name.
.RE
.PP
There is potential here for a lot of search operations.  The trick is to
define .SOURCE.x special targets with short search lists and leave .SOURCE
as short as possible.
The search algorithm has the following useful side effect.
When a target having the .LIBMEMBER (library member) attribute is searched for,
it is first searched for as an ordinary file.
When a number of library members require updating it is desirable to compile
all of them first and to update the library at the end in a single operation.
If one of the members does not compile and \fBdmake\fP stops, then
the user may fix the error and make again.  \fBdmake\fP will not remake any
of the targets whose object files have already been generated as long as
none of their prerequisite files have been modified as a result of the fix.
.PP
When defining .SOURCE and .SOURCE.x targets the construct
.sp
\t.SOURCE :
.br
\t.SOURCE : fred gery
.sp
is equivalent to
.sp
\t.SOURCE :\- fred gery
.PP
\fBdmake\fP correctly handles the UNIX Make variable VPATH.  By definition VPATH
contains a list of ':' separated directories to search when looking for a
target.  \fBdmake\fP maps VPATH to the following special rule:
.sp
\t.SOURCE :^ $(VPATH:s/:/ /)
.sp
Which takes the value of VPATH and sets .SOURCE to the same set of directories
as specified in VPATH.
.SH "PERCENT(%) RULES AND MAKING INFERENCES"
When \fBdmake\fP makes a target, the target's set of prerequisites (if any)
must exist and the target must have a recipe which \fBdmake\fP
can use to make it.
If the makefile does not specify an explicit recipe for the target then
.B dmake
uses special rules to try to infer a recipe which it can use
to make the target.  Previous versions of Make perform this task by using
rules that are defined by targets of the form .<suffix>.<suffix> and by
using the .SUFFIXES list of suffixes.  The exact workings of this mechanism
were sometimes difficult to understand and often limiting in their usefulness.
Instead, \fBdmake\fP supports the concept of \fI%-meta\fP rules.
The syntax and semantics of these rules differ from standard rule lines as
follows:
.sp
.nf
.RS
\fI<%-target>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<%-prerequisites>\fP] [;\fI<recipe>\fP]
.RE
.fi
.sp
where \fI%-target\fP is a target containing exactly a single `%' sign,
.I attributes
is a list (possibly empty) of attributes,
.I ruleop
is the standard set of rule operators,
.I "%-prerequisites"
\&, if present, is a list of prerequisites containing zero or more `%' signs,
and
.I recipe,
if present, is the first line of the recipe.
.PP
The
.I %-target
defines a pattern against which a target whose recipe is
being inferred gets matched.  The pattern match goes as follows:  all chars are
matched exactly from left to right up to but not including the % sign in the
pattern, % then matches the longest string from the actual target name
not ending in
the suffix given after the % sign in the pattern.
Consider the following examples:
.RS
.sp
.nf
.Is "dir/%.c   "
.Ii "%.c"
matches fred.c but not joe.c.Z
.Ii "dir/%.c"
matches dir/fred.c but not dd/fred.c
.Ii "fred/%"
matches fred/joe.c but not f/joe.c
.Ii "%"
matches anything
.fi
.sp
.RE
In each case the part of the target name that matched the % sign is retained
and is substituted for any % signs in the prerequisite list of the %-meta rule
when the rule is selected during inference and
.B dmake
constructs the new dependency.
As an example the following %-meta rules describe the following:
.RS
.sp
%.c : %.y ; recipe...
.sp
.RE
describes how to make any file ending in .c if a corresponding file ending
in .y can be found.
.RS
.sp
foo%.o : fee%.k ; recipe...
.sp
.RE
is used to describe how to make fooxxxx.o from feexxxx.k.
.RS
.sp
%.a :; recipe...
.sp
.RE
describes how to make a file whose suffix is .a without inferring any
prerequisites.
.RS
.sp
%.c : %.y yaccsrc/%.y ; recipe...
.sp
.RE
is a short form for the construct:
.RS
.sp
%.c : %.y ; recipe...
.br
%.c : yaccsrc/%.y ; recipe...
.sp
.RE
ie. It is possible to specify the same recipe for two %-rules by giving
more than one prerequisite in the prerequisite list.
A more interesting example is:
.RS
.sp
% : RCS/%,v ; co $<
.sp
.RE
which describes how to take any target and check it out of
the RCS directory if the corresponding file exists in the RCS directory.
The equivalent SCCS rule would be:
.RS
.sp
% : s.% ; get $<
.sp
.RE
.PP
The previous RCS example defines an infinite rule, because it says how to make
.I anything
from RCS/%,v, and
.I anything
also includes RCS/fred.c,v.
To limit the size of the graph that results from such rules
.B dmake
uses the macro variable PREP (stands for % repetition).  By default the value
of this variable is 0, which says that no repetitions of a %-rule are to be
generated.  If it is set to something greater than 0, then that many
repetitions of any infinite %-rule are allowed.  If in the above
example PREP was set to 1, then \fBdmake\fP would generate the dependency
graph:
.RS
.sp
% --> RCS/%,v --> RCS/RCS/%,v,v
.sp
.RE
Where each link is assigned the same recipe as the first link.
PREP should be used only in special cases, since it may result in
a large increase in the number of possible prerequisites tested.
.B dmake
further assumes that any target that has no suffix can be made from
a prerequisite that has at least one suffix.
.PP
.B dmake
supports dynamic prerequisite generation for prerequisites of %-meta rules.
This is best illustrated by an example.  The RCS rule shown above can infer
how to check out a file from a corresponding RCS file only if the target
is a simple file name with no directory information.  That is, the above rule
can infer how to find \fIRCS/fred.c,v\fP from the target \fIfred.c\fP,
but cannot infer how to find \fIsrcdir/RCS/fred.c,v\fP from \fIsrcdir/fred.c\fP
because the above rule will cause \fBdmake\fP to look for RCS/srcdir/fred.c,v;
which does not exist (assume that srcdir has its own RCS directory as is the
common case).
.PP
A more versatile formulation of the above RCS check out rule is the following:
.RS
.sp
% :  $$(@:d)RCS/$$(@:f),v : co $@
.sp
.RE
This rule uses the dynamic macro $@ to specify the prerequisite to try to
infer.  During inference of this rule the macro $@ is set to the value of
the target of the %-meta rule and the appropriate prerequisite is generated by
extracting the directory portion of the target name (if any), appending the
string \fIRCS/\fP to it, and appending the target file name with a trailing
\fI,v\fP attached to the previous result.
.PP
.B dmake
can also infer indirect prerequisites.
An inferred target can have a list of prerequisites added that will not
show up in the value of $< but will show up in the value of $? and $&.
Indirect prerequisites are specified in an inference rule by quoting the
prerequisite with single quotes.  For example, if you had the explicit
dependency:
.RS
.sp
.nf
fred.o : fred.c ; rule to make fred.o
fred.o : local.h
.fi
.sp
.RE
then this can be inferred for fred.o from the following inference rule:
.RS
.sp
%.o : %.c 'local.h' ; rule to make a .o from a .c
.sp
.RE
You may infer indirect prerequisites that are a function of the value of '%'
in the current rule.  The meta-rule:
.RS
.sp
%.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
.sp
.RE
infers an indirect prerequisite found in the INC directory whose name is the
same as the expansion of $(INC), and the prerequisite name depends on the
base name of the current target.
The set of indirect prerequisites is attached to the meta rule in which they
are specified and are inferred only if the rule is used to infer a recipe
for a target.  They do not play an active role in driving the inference
algorithm.
The construct:
.RS
.sp
%.o : %.c %.f 'local.h'; recipe
.sp
.RE
is equivalent to:
.RS
.sp
.nf
%.o : %.c 'local.h' : recipe
%.o : %.f 'local.h' : recipe
.fi
.sp
.RE
.PP
If any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT,
\&.USESHELL, .SWAP, .PRECIOUS, .LIBRARY, .NOSTATE and .IGNORE
are given for a %-rule then when that rule is bound to a target
as the result of an inference, the target's set of attributes is augmented by
the attributes from the above set that are specified in the bound %-rule.
Other attributes specified for %-meta rules are not inherited by the target.
The .SETDIR attribute is treated in a special way.
If the target already had a .SETDIR attribute set then
.B dmake
changes to that directory prior to performing the inference.
During inference any .SETDIR attributes for the inferred prerequisite
are honored.
The directories must exist for a %-meta rule to be selected as a possible
inference path.  If the directories do not exist no error message is issued,
instead the corresponding path in the inference graph is rejected.
.PP
.B dmake
also supports the old format special target .<suffix>.<suffix>
by identifying any rules
of this form and mapping them to the appropriate %-rule.  So for example if
an old makefile contains the construct:
.RS
.sp
\&.c.o :; cc \-c $< \-o $@
.sp
.RE
.B dmake
maps this into the following %-rule:
.RS
.sp
%.o : %.c; cc \-c $< \-o $@
.sp
.RE
Furthermore,
.B dmake
understands several SYSV AUGMAKE special targets and maps them into
corresponding %-meta rules.  These transformation must be enabled by providing
the \-A flag on the command line or by setting the value of AUGMAKE to
non\-NULL.
The construct
.RS
.sp
\&.suff :; recipe
.sp
.RE
gets mapped into:
.RS
.sp
% : %.suff; recipe
.sp
.RE
and the construct
.RS
.sp
\&.c~.o :; recipe
.sp
.RE
gets mapped into:
.RS
.sp
%.o : s.%.c ; recipe
.sp
.RE
In general, a special target of the form .<str>~ is replaced by the %-rule
construct s.%.<str>, thereby providing support for the syntax used by SYSV
AUGMAKE for providing SCCS support.
When enabled, these mappings allow processing of existing SYSV
makefiles without modifications.
.PP
.B dmake
bases all of its inferences on the inference graph constructed from the
%-rules defined in the makefile.
It knows exactly which targets can be made from which prerequisites by
making queries on the inference graph.  For this reason .SUFFIXES is not
needed and is completely ignored.
.PP
For a %-meta rule to be inferred as the
rule whose recipe will be used to make a target, the target's name must match
the %-target pattern, and any inferred %-prerequisite must already exist or
have an explicit recipe so that the prerequisite can be made.
Without \fItransitive closure\fP on the inference graph the above rule
describes precisely when an inference match terminates the search.
If transitive closure is enabled (the usual case), and a prerequisite does
not exist or cannot be made, then
.B dmake
invokes the inference algorithm recursively on the prerequisite to see if
there is some way the prerequisite can be manufactured.  For, if the
prerequisite can be made then the current target can also be made using the
current %-meta rule.
This means that there is no longer a need to give a rule
for making a .o from a .y if you have already given a rule for making a .o
from a .c and a .c from a .y.  In such cases
.B dmake
can infer how to make the
\&.o from the .y via the intermediary .c and will remove the .c when the .o is
made.  Transitive closure can be disabled by giving the \-T switch on the
command line.
.PP
A word of caution.
.B dmake
bases its transitive closure on the %-meta rule targets.
When it performs transitive closure it infers how to make a target from a
prerequisite by performing a pattern match as if the potential prerequisite
were a new target.
The set of rules:
.RS
.nf
.sp
%.o : %.c :; rule for making .o from .c
%.c : %.y :; rule for making .c from .y
% : RCS/%,v :; check out of RCS file
.fi
.sp
.RE
will, by performing transitive closure, allow \fBdmake\fP to infer how to make
a .o from a .y using a .c as an intermediate temporary file.  Additionally
it will be able to infer how to make a .y from an RCS file, as long as that
RCS file is in the RCS directory and has a name which ends in .y,v.
The transitivity computation is performed dynamically for each target that
does not have a recipe.  This has potential to be costly if the %-meta
rules are not carefully specified.  The .NOINFER attribute is used to mark
a %-meta node as being a final target during inference.  Any node with this
attribute set will not be used for subsequent inferences.  As an example
the node RCS/%,v is marked as a final node since we know that if the RCS file
does not exist there likely is no other way to make it.  Thus the standard
startup makefile contains an entry similar to:
.RS
.nf
\&.NOINFER : RCS/%,v
.fi
.RE
Thereby indicating that the RCS file is the end of the inference chain.
X
Whenever the inference algorithm determines that a target can be made from
more than one prerequisite and the inference chains for the two methods
are the same length the algorithm reports an ambiguity and prints the
ambiguous inference chains.
.PP
.B dmake
tries to
remove intermediate files resulting from transitive closure if the file
is not marked as being PRECIOUS, or the \fB\-u\fP flag was not given on the
command line, and if the inferred intermediate did not previously exist.
Intermediate targets that existed prior to being made are never removed.
This is in keeping with the philosophy that
.B dmake
should never remove things from the file system that it did not add.
If the special target .REMOVE is defined and has a recipe then
.B dmake
constructs a list of the intermediate files to be removed and makes them
prerequisites of .REMOVE.  It then makes .REMOVE thereby removing the
prerequisites if the recipe of .REMOVE says to.  Typically .REMOVE is defined
in the startup file as:
.sp
\t.REMOVE :; $(RM) $<
.SH "MAKING TARGETS"
In order to update a target \fBdmake\fP must execute a recipe.
When a recipe needs to be executed it is first expanded so that any macros
in the recipe text are expanded, and it is then either executed directly or
passed to a shell.
.B dmake
supports two types of recipes.  The regular recipes and group recipes.
.PP
When a regular recipe is invoked \fBdmake\fP executes each line of the recipe
separately using a new copy of a shell if a shell is required.
SHAR_EOF
true || echo 'restore of dmake/man/dmake.tf failed'
fi
echo 'End of part 18, continue with part 19'
echo 19 > _shar_seq_.tmp
exit 0
exit 0 # Just in case...