dvadura@watdragon.waterloo.edu (Dennis Vadura) (07/27/90)
Posting-number: Volume 14, Issue 18
Submitted-by: dvadura@watdragon.waterloo.edu (Dennis Vadura)
Archive-name: dmake/part08
#!/bin/sh
# this is part 8 of a multipart archive
# do not concatenate these parts, unpack them in order with /bin/sh
# file man/dmake.tf continued
#
CurArch=8
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
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 both
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, and the
X.I "'@'"
Xindicates that the recipe line should NOT be echoed to the terminal prior to
Xbeing executed. Both switches are off by default
X(ie. by default, errors are significant and commands are echoed).
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@a recipe line that is not echoed
X\t\-and one that has errors ignored.
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 both
Xof \- or @ then they apply to the entire group in the same way that the \-
Xand @ apply to single recipe lines.
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 in recipes. If a recipe line contains
Xthe character sequence \fB<+\fP it is recognized and a text diversion is
Xstarted. This causes
X.B dmake
Xto open a temporary file and to copy into that file all text that is found
Xup to but not including the text diversion termination sequence \fB+>\fP.
XAny diversions started with a \fB<+\fP must be terminated with a
Xcorresponding \fB+>\fP; the terminating \fB+>\fP may appear on the same
Xor on a subsequent recipe line. Nesting of diversions is not
Xsupported. New\-lines provided in the recipe that forms the text of a
Xdiversion are inserted into the resulting temporary file at the
Xappropriate locations. The diversion text may contain
Xthe same escape codes as those described in the MACROS section.
X.PP
XThe primary use of diversions is on systems (like MSDOS) that do not
Xsupport long command lines. The diversion makes it possible to produce
Xa temporary file containing the arguments which can then be supplied to
Xa utility via the temporary file.
X.PP
XHere are some examples:
X.RS
X.sp
X.nf
Xall:
X cat <+this is a
X test of the text diversion+>
X.fi
X.sp
X.RE
XThe above will cause
X.B dmake
Xto execute the command:
X.RS
X.sp
Xcat /tmp/mk12294AA
X.sp
X.RE
Xand the contents of the temporary file will be the text found between the
X.B <+
Xand
X.B +>
Xstrings of the above recipe.
X.RS
X.sp
X.nf
XOBJ = fred.obj mary.obj joe.obj
Xall : $(OBJ)
X link @<+$(^: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 placed immediately before the \fB+>\fP text diversion
Xterminator.
X.PP
XIf the environment variable TMPDIR is defined then the
Xtemporary file is created in the directory specified by that variable.
XA makefile can change where temporary files are created 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 two classes:
Xcontrol macros and run-time macros. The 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.
XWe first give the control macros and their meanings.
X.PP
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 also divided into three 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 \fBMAXPROCESSLIMIT\fP 1.4i
XIs a numeric string representing the maximum number of processes that
X\fBdmake\fP can use when making targets in the 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 \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.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 \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 work correctly.
X.IP \fBMAKE\fP 1.6i
XIt is 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
Xto introduce options on command lines. On UNIX it's value is '-', on
XMSDOS it's value may be '/' or '-'.
XThe macro is internally defined and is not user setable.
X.PP
XAll boolean macros currently understood by
X.B dmake
Xcorrespond directly to the previously defined attributes.
XThese macros provide
Xa second way to apply global attributes, and represent the
Xpreferred method of doing so. They are used by assigning them a
Xvalue. If the value is not a NULL string then the boolean condition
Xis set to on.
XIf the value is a NULL string then the condition is set to off.
XThere are five conditions defined and they correspond directly to the
Xattributes of the same name. Their meanings are defined in the ATTRIBUTES
Xsection above.
XThe macros are:
X\&\fB.EPILOG\fP,
X\&\fB.IGNORE\fP,
X\&\fB.PRECIOUS\fP,
X\&\fB.PROLOG\fP, and
X\&\fB.SILENT\fP.
XAssigning any of these a non NULL value will turn on the corresponding
Xattribute on a global scale.
X.PP
XThe second class of macros is the run-time macros. These macros are defined
Xwhen \fBdmake\fP is making targets, and may take on different values for each
Xtarget. \fB$@\fP is defined to be the full target name, \fB$?\fP is the
Xlist of all out of date prerequisites, \fB$&\fP is the list of all
Xprerequisites, \fB$>\fP is the name of the library if the current target is a
Xlibrary member,
X\fB$<\fP is the list of prerequisites specified in the current rule (this
Xincludes any inferred prerequisites),
X\fB$*\fP is defined as
X\fB$(@:db)\fP when making targets with explicit recipes and is defined as the
Xvalue of % when making targets whose recipe is the result of an inference.
XIn the first case \fB$*\fP is the target name with no suffix,
Xand in the latter is the value of the matched % pattern from
Xthe associated %-rule.
X\fB$^\fP expands to the set of out of date prerequisites taken from the
Xcurrent value of \fB$<\fP.
XIn addition to these,
X\fB$$\fP expands to $, \fB{{\fP expands to {, \fB}}\fP expands to }, and the
Xstrings \fB<+\fP and \fB+>\fP are reserved for use in recipe scripts
Xfor starting and terminating a text diversion respectively.
X.PP
XThe difference between $? and $^ can best be illustrated by an example,
Xconsider:
X.RS
X.sp
X.nf
Xfred.out : joe amy hello
X\trules for making fred
X
Xfred.out : my.c your.h his.h her.h # more prerequisites
X.fi
X.sp
X.RE
XAssume joe, amy, and my.c are newer then fred.out. When
X.B dmake
Xexecutes the recipe for making fred.out the values of the following macros
Xwill be:
X.RS
X.sp
X.nf
X.Is "$@ "
X.Ii "$@"
X--> fred.out
X.Ii "$*"
X--> fred
X.Ii "$?"
X--> joe amy my.c # note the difference between $? and $^
X.Ii "$^"
X--> joe amy
X.Ii "$<"
X--> joe amy hello
X.Ii "$&"
X--> joe amy hello my.c your.h his.h her.h
X.fi
X.sp
X.RE
X.SH "DYNAMIC PREREQUISITES"
X.B dmake
Xlooks for prerequisites whose names contain macro expansions during target
Xprocessing. Any such prerequisites are expanded and the result of the
Xexpansion is used as the prerequisite name. As an example the line:
X.sp
X\tfred : $$@.c
X.sp
Xcauses the $$@ to be expanded when \fBdmake\fP is making fred, and it resolves
Xto the target \fIfred\fP.
XThis enables dynamic prerequisites to be generated. The value
Xof @ may be modified by any of the valid macro modifiers. So you can say for
Xexample:
X.sp
X\tfred.out : $$(@:b).c
X.sp
Xwhere the $$(@:b) expands to \fIfred\fP.
XNote the use of $$ instead of $ to indicate the dynamic expansion, this
Xis due to the fact that the rule line is expanded when it is initially parsed,
Xand $$ then returns $ which later triggers the dynamic prerequisite expansion.
XIf you really want a $ to be part of a prerequisite name you must use $$$$.
XDynamic macro expansion is performed in all user defined rules,
Xand the special targets .SOURCE*, and .INCLUDEDIRS.
X.SH "BINDING TARGETS"
XThis operation takes a target name and binds it to an existing file, if
Xpossible.
X.B dmake
Xmakes a distinction between the internal target name of a target and it's
Xassociated external file name.
XThus it is possible for a target's internal name and its external
Xfile name to differ.
XTo perform the binding, the following set of rules is used.
XAssume that we are
Xtrying to bind a target whose name is of the form \fIX.suff\fP,
Xwhere \fI.suff\fP is the suffix and \fIX\fP is the stem portion
X(ie. that part which contains the directory and the basename).
X.B dmake
Xtakes this target name and performs a series of search operations that try to
Xfind a suitably named file in the external file system.
XThe search operation is user controlled
Xvia the settings of the various .SOURCE targets.
X.RS
X.IP 1.
XIf target has the .SYMBOL attribute set then look for it in the library.
XIf found, replace the target name with the library member name and continue
Xwith step 2. If the name is not found then return.
X.IP 2.
XExtract the suffix portion (that following the `.') of the target name.
XIf the suffix is not null, look up the special target .SOURCE.<suff>
X(<suff> is the suffix).
XIf the special target exists then search each directory given in
Xthe .SOURCE.<suff> prerequisite list for the target.
XIf the target's suffix was null (ie. \fI.suff\fP was empty) then
Xperform the above search but use the special target .SOURCE.NULL instead.
XIf at any point a match is found then terminate the search.
XIf a directory in the prerequisite list is the special name `.NULL ' perform
Xa stat for the full target name without prepending any directory portion
X(ie. prepend the NULL directory).
X(a default target of '.SOURCE : .NULL' is defined by \fBdmake\fP at startup,
Xand is user redefinable)
X.IP 3.
XThe search in step 2. failed. Repeat the same search but this time
Xuse the special target .SOURCE.
X.IP 4.
XThe search in step 3. failed.
XIf the target has the library member attribute (.LIBMEMBER)
Xset then try to find the target in the library which was passed along
Xwith the .LIBMEMBER attribute (see the MAKING LIBRARIES section).
XThe bound file name assigned to a target which is successfully
Xlocated in a library is the same name that would be assigned had the search
Xfailed (see 5.).
X.IP 5.
XThe search failed. Either the target was not found in any of the search
Xdirectories or no applicable .SOURCE special targets exist.
XIf applicable .SOURCE special targets exist, but the target was not found,
Xthen \fBdmake\fP assigns the first name searched as the bound file name.
XIf no applicable .SOURCE special targets exist,
Xthen the full original target name becomes the bound file name.
X.RE
X.PP
XThere is potential here for a lot of search operations. The trick is to
Xdefine .SOURCE.x special targets with short search lists and leave .SOURCE
Xas short as possible.
XThe search algorithm has the following useful side effect.
XWhen a target having the .LIBMEMBER (library member) attribute is searched for,
Xit is first searched for as an ordinary file.
XWhen a number of library members require updating it is desirable to compile
Xall of them first and to update the library at the end in a single operation.
XIf one of the members does not compile and \fBdmake\fP stops, then
Xthe user may fix the error and make again. \fBdmake\fP will not remake any
Xof the targets whose object files have already been generated as long as
Xnone of their prerequisite files have been modified as a result of the fix.
X.PP
XWhen defining .SOURCE and .SOURCE.x targets the construct
X.sp
X\t.SOURCE :
X.br
X\t.SOURCE : fred gery
X.sp
Xis equivalent to
X.sp
X\t.SOURCE :- fred gery
X.PP
X\fBdmake\fP correctly handles the UNIX Make variable VPATH. By definition VPATH
Xcontains a list of ':' separated directories to search when looking for a
Xtarget. \fBdmake\fP maps VPATH to the following special rule:
X.sp
X\t.SOURCE :^ $(VPATH:s/:/ /)
X.sp
XWhich takes the value of VPATH and sets .SOURCE to the same set of directories
Xas specified in VPATH.
X.SH "PERCENT(%) RULES AND MAKING INFERENCES"
XWhen \fBdmake\fP makes a target it's set of prerequisites (if any)
Xmust exist and the target must have a recipe which \fBdmake\fP
Xcan use to make it.
XIf the makefile does not specify an explicit recipe for the target then
X.B dmake
Xuses special rules to try to infer a recipe which it can use
Xto make the target. Previous versions of Make perform this task by using
Xrules that are defined by targets of the form .<suffix>.<suffix> and by
Xusing the .SUFFIXES list of suffixes. The exact workings of this mechanism
Xwere sometimes difficult to understand and often limiting in their usefulness.
XInstead, \fBdmake\fP supports the concept of \fI%-meta\fP rules.
XThe syntax and semantics of these rules differ from standard rule lines as
Xfollows:
X.sp
X.nf
X.RS
X\fI<%-target>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<%-prerequisites>\fP] [;\fI<recipe>\fP]
X.RE
X.fi
X.sp
Xwhere \fI%-target\fP is a target containing exactly a single `%' sign,
X.I attributes
Xis a list (possibly empty) of attributes,
X.I ruleop
Xis the standard set of rule operators,
X.I "%-prerequisites"
X\&, if present, is a list of prerequisites containing zero or more `%' signs,
Xand
X.I recipe,
Xif present, is the first line of the recipe.
X.PP
XThe
X.I %-target
Xdefines a pattern against which a target whose recipe is
Xbeing inferred gets matched. The pattern match goes as follows: all chars are
Xmatched exactly from left to right up to but not including the % sign in the
Xpattern, % then matches the longest string from the actual target name
Xnot ending in
Xthe suffix given after the % sign in the pattern.
XConsider the following examples:
X.RS
X.sp
X.nf
X.Is "dir/%.c "
X.Ii "%.c"
Xmatches fred.c but not joe.c.Z
X.Ii "dir/%.c"
Xmatches dir/fred.c but not dd/fred.c
X.Ii "fred/%"
Xmatches fred/joe.c but not f/joe.c
X.Ii "%"
Xmatches anything
X.fi
X.sp
X.RE
XIn each case the part of the target name that matched the % sign is retained
Xand is substituted for any % signs in the prerequisite list of the %-meta rule
Xwhen the rule is selected during inference and
X.B dmake
Xconstructs the dependency specified by the %-meta rule for the actual target.
XAs an example the following %-meta rules describe the following:
X.RS
X.sp
X%.c : %.y ; recipe...
X.sp
X.RE
Xdescribes how to make any file ending in .c if a corresponding file ending
Xin .y can be found.
X.RS
X.sp
Xfoo%.o : fee%.k ; recipe...
X.sp
X.RE
Xis used to describe how to make fooxxxx.o from feexxxx.k.
X.RS
X.sp
X%.a :; recipe...
X.sp
X.RE
Xdescribes how to make a file whose suffix is .a without inferring any
Xprerequisites.
X.RS
X.sp
X%.c : %.y yaccsrc/%.y ; recipe...
X.sp
X.RE
Xis a short form for the construct:
X.RS
X.sp
X%.c : %.y ; recipe...
X.br
X%.c : yaccsrc/%.y ; recipe...
X.sp
X.RE
Xie. It is possible to specify the same recipe for two %-rules by giving
Xmore than one prerequisite in the prerequisite list.
XA more interesting example is:
X.RS
X.sp
X% : RCS/%,v ; co $@
X.sp
X.RE
Xwhich describes how to take any target and check it out of
Xthe RCS directory if the corresponding file exists in the RCS directory.
XThe equivalent SCCS rule would be:
X.RS
X.sp
X% : s.% ; get $@
X.sp
X.RE
X.PP
XThe previous RCS example defines an infinite rule, because it says how to make
X.I anything
Xfrom RCS/%,v, and
X.I anything
Xalso includes RCS/fred.c,v.
XTo limit the size of the graph that results from such rules
X.B dmake
Xuses the macro variable PREP (stands for % repetition). By default the value
Xof this variable is 0, which says that no repetitions of a %-rule are to be
Xgenerated. If it is set to something greater than 0, then that many
Xrepetitions of any infinite %-rule are allowed. If in the above
Xexample PREP was set to 1, then \fBdmake\fP would generate the dependency
Xgraph:
X.RS
X.sp
X% --> RCS/%,v --> RCS/RCS/%,v,v
X.sp
X.RE
XWhere each link is assigned the same recipe as the first link.
XPREP should be used only in special cases, since it may result in
Xa large increase in the number of possible prerequisites tested.
X.PP
X.B dmake
Xsupports dynamic prerequisite generation for prerequisites of %-meta rules.
XThis is best illustrated by an example. The RCS rule shown above can infer
Xhow to check out a file from a corresponding RCS file only if the target
Xis a simple file name with no directory information. That is, the above rule
Xcan infer how to find \fIRCS/fred.c,v\fP from the target \fIfred.c\fP,
Xbut cannot infer how to find \fIsrcdir/RCS/fred.c,v\fP from \fIsrcdir/fred.c\fP
Xbecause the above rule will cause \fBdmake\fP to look for RCS/srcdir/fred.c,v;
Xwhich does not exist (assume that srcdir has it's own RCS directory as is the
Xcommon case).
X.PP
XA more versatile formulation of the above RCS check out rule is the following:
X.RS
X.sp
X% : $$(@:d)RCS/$$(@:f),v : co $@
X.sp
X.RE
XThis rule uses the dynamic macro $@ to specify the prerequisite to try to
Xinfer. During inference of this rule the macro $@ is set to the value of
Xthe target of the %-meta rule and the appropriate prerequisite is generated by
Xextracting the directory portion of the target name (if any), appending the
Xstring \fIRCS/\fP to it, and appending the target file name with a trailing
X\fI,v\fP attached to the previous result.
X.PP
X.B dmake
Xcan also infer indirect prerequisites.
XAn inferred target can have a list of prerequisites added that will not
Xshow up in the value of $< but will show up in the value of $? and $&.
XIndirect prerequisites are specified in an inference rule by quoting the
Xprerequisite with single quotes. For example, if you had the explicit
Xdependency:
X.RS
X.sp
X.nf
Xfred.o : fred.c ; rule to make fred.o
Xfred.o : local.h
X.fi
X.sp
X.RE
Xthen this can be infered for fred.o from the following inference rule:
X.RS
X.sp
X%.o : %.c 'local.h' ; rule to make a .o from a .c
X.sp
X.RE
XYou may infer indirect prerequisites that are a function of the value of '%'
Xin the current rule. The meta-rule:
X.RS
X.sp
X%.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
X.sp
X.RE
Xinfers an indirect prerequisite found in the INC directory whose name is the
Xsame as the expansion of $(INC), and the prerequisite name depends on the
Xbase name of the current target.
XThe set of indirect prerequisites is attached to the meta rule in which they
Xare specified and are inferred only if the rule is used to infer a recipe
Xfor a target. They do not play an active role in driving the inference
Xalgorithm.
XThe construct:
X.RS
X.sp
X%.o : %.c %.f 'local.h'; recipe
X.sp
X.RE
Xis equivalent to:
X.RS
X.sp
X.nf
X%.o : %.c 'local.h' : recipe
X%.o : %.f 'local.h' : recipe
X.fi
X.sp
X.RE
X.PP
XIf any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT, .PRECIOUS,
X\&.LIBRARY, and .IGNORE
Xare given for a %-rule then when that rule is bound to a target
Xas the result of an inference, the target's set of attributes is augmented by
Xthe attributes from the above set that are specified in the bound %-rule.
XOther attributes specified for %-meta rules are not inherited by the target.
XThe .SETDIR attribute is treated in a special way.
XIf the target already had a .SETDIR attribute set and the bound %-rule also
Xspecified a .SETDIR attribute then the one
Xoriginally specified with the target prevails.
XDuring inference any .SETDIR attributes for the inferred prerequisite
Xare honored.
XThe directories must exist for a %-meta rule to be selected as a possible
Xinference path. If the directories do not exist no error message is issued,
Xinstead the corresponding path in the inference graph is simply rejected.
X.PP
X.B dmake
Xalso supports the old format special target .<suffix>.<suffix>
Xby identifying any rules
Xof this form and mapping them to the appropriate %-rule. So for example if
Xan old makefile contains the construct:
X.RS
X.sp
X\&.c.o :; cc -c $< -o $@
X.sp
X.RE
X.B dmake
Xmaps this into the following %-rule:
X.RS
X.sp
X%.o : %.c; cc -c $< -o $@
X.sp
X.RE
XFurthermore,
X.B dmake
Xunderstands several SYSV AUGMAKE special targets and maps them into
Xcorresponding %-meta rules. These transformation must be enabled by providing
Xthe -A flag on the command line or by setting the value of AUGMAKE to non
XNULL.
XThe construct
X.RS
X.sp
X\&.suff :; recipe
X.sp
X.RE
Xgets mapped into:
X.RS
X.sp
X% : %.suff; recipe
X.sp
X.RE
Xand the construct
X.RS
X.sp
X\&.c~.o :; recipe
X.sp
X.RE
Xgets mapped into:
X.RS
X.sp
X%.o : s.%.c ; recipe
X.sp
X.RE
XIn general, a special target of the form .<str>~ is replaced by the %-rule
Xconstruct s.%.<str>, thereby providing support for the syntax used by SYSV
XAUGMAKE for providing SCCS support.
XWhen enabled, these mappings allow to processing of existing SYSV
Xmakefiles without modifications.
X.PP
X.B dmake
Xbases all of it's inferences on the inference graph constructed from the
X%-rules defined in the makefile.
XIt knows exactly which targets can be made from which prerequisites by
Xmaking queries on the inference graph. For this reason .SUFFIXES is not
Xneeded and is completely ignored.
X.PP
XFor a %-meta rule to be inferred as the
Xrule whose recipe will be used to make a target, the target's name must match
Xthe %-target pattern, and any inferred %-prerequisite must already exist or
Xhave an explicit recipe so that the prerequisite can be made.
XWithout \fItransitive closure\fP on the inference graph the above rule
Xdescribes precisely when an inference match terminates the search.
XIf transitive closure is enabled (the usual case), and a prerequisite does
Xnot exist or cannot be made, then
X.B dmake
Xinvokes the inference algorithm recursively on the prerequisite to see if
Xthere is some way the prerequisite can be manufactured. For if the
Xprerequisite can be made then the current target can also be made using the
Xcurrent %-meta rule.
XThis means that there is no longer a need to give a rule
Xfor making a .o from a .y if you have already given a rule for making a .o
Xfrom a .c and a .c from a .y. In such cases
X.B dmake
Xcan infer how to make the
X\&.o from the .y via the intermediary .c and will remove the .c when the .o is
Xmade. Transitive closure can be disabled by giving the -T switch on the
Xcommand line.
X.PP
XA word of caution.
X.B dmake
Xbases its transitive closure on the %-meta rule targets.
XWhen it performs transitive closure it infers how to make a target from a
Xprerequisite by performing a pattern match as if the potential prerequisite
Xwere a new target.
XThe set of rules:
X.RS
X.nf
X.sp
X%.o : %.c :; rule for making .o from .c
X%.c : %.y :; rule for making .c from .y
X% : RCS/%,v :; check out of RCS file
X.fi
X.sp
X.RE
Xwill, by performing transitive closure, allow \fBdmake\fP to infer how to make
Xa .o from a .y using a .c as an intermediate temporary file. Additionally
Xit will be able to infer how to make a .y from an RCS file, as long as that
XRCS file is in the RCS directory and has a name which ends in .y,v.
XThe transitivity computation is performed dynamically for each target that
Xdoes not have a recipe. This has potential to be very slow if the %-meta
Xrules are not carefully specified. The .NOINFER attribute is used to mark
Xa %-meta node as being a final target during inference. Any node with this
Xattribute set will not be used for subsequent inferences. As an example
Xthe node RCS/%,v is marked as a final node since we know that if the RCS file
Xdoes not exist there likely is no other way to make it. Thus the standard
Xstartup makefile contains the entry:
X.RS
X.nf
X\&.NOINFER : RCS/%,v
X.fi
X.RE
XThereby indicating that the RCS file is the end of the inference chain.
X.PP
X.B dmake
Xtries to
Xremove intermediate files resulting from transitive closure if the file
Xis not marked as being PRECIOUS, or the \fB-u\fP flag was not given on the
Xcommand line, and if the inferred intermediate did not previously exist.
XIntermediate targets that existed prior to being made are never removed.
XThis is in keeping with the philosophy that
X.B dmake
Xshould never remove things from the file system that it did not add.
XIf the special target .REMOVE is defined and has a recipe then
X.B dmake
Xconstructs a list of the intermediate files to be removed and makes them
Xprerequisites of .REMOVE. It then makes .REMOVE thereby removing the
Xprerequisites if the recipe of .REMOVE says to. Typically .REMOVE is defined
Xin the startup file as:
X.sp
X\t".REMOVE :; $(RM) $<".
X.SH "MAKING TARGETS"
XIn order to update a target \fBdmake\fP must execute a recipe.
XWhen a recipe needs to be executed it is first expanded so that any macros
Xin the recipe text are expanded, and it is then either executed directly or
Xpassed to a shell.
X.B dmake
Xsupports two types of recipes. The regular recipes and group recipes.
X.PP
XWhen a regular recipe is invoked \fBdmake\fP executes each line of the recipe
Xseparately using a new copy of a shell if a shell is required.
XThus effects of commands do not generally persist across recipe lines.
X(e.g. cd requests in a recipe line do not carry over to the next recipe line)
XThe decision on whether a shell is required to execute a command is based on
Xthe value of the macro SHELLMETAS. If any character in the value of
X\&SHELLMETAS is found in the expanded recipe text-line then the command is
Xexecuted using a shell, otherwise the command is executed directly.
XThe shell that is used for execution is given by the value of the macro SHELL.
XThe flags that are passed to the shell are given by the value of SHELLFLAGS.
XThus \fBdmake\fP constructs the command line:
X.sp
X\t$(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
X.sp
XNormally
X.B dmake
Xwrites the command line that it is about to invoke to standard output.
XIf the .SILENT attribute is set for the target or for
Xthe recipe line (via @), then the recipe line is not echoed.
X.PP
XGroup recipe processing is similar to that of regular recipes, except that
Xa shell is always invoked. The shell that is invoked is given by the value of
Xthe macro GROUPSHELL, and its flags are taken from the value of the macro
XGROUPFLAGS. If a target has the .PROLOG attribute set then
X.B dmake
Xprepends to the shell script the recipe associated with the special target
X\&.GROUPPROLOG, and if the attribute .EPILOG is set as well, then the recipe
Xassociated with the special target .GROUPEPILOG is appended to the script
Xfile.
XThis facility can be used to always prepend a common header and common trailer
Xto group recipes.
XGroup recipes are echoed to standard output just like standard recipes, but
Xare enclosed by lines beginning with [ and ].
X.SH "MAKING LIBRARIES"
XLibraries are easy to maintain using \fBdmake\fP. A library is a file
SHAR_EOF
echo "End of part 8"
echo "File man/dmake.tf is continued in part 9"
echo "9" > s2_seq_.tmp
exit 0