dvadura@watdragon.waterloo.edu (Dennis Vadura) (06/30/91)
Submitted-by: Dennis Vadura <dvadura@watdragon.waterloo.edu> Posting-number: Volume 20, Issue 81 Archive-name: dmake/patch02f Patch-To: dmake: Volume 19, Issue 22-58 #!/bin/sh # this is dp2.05 (part 5 of a multipart archive) # do not concatenate these parts, unpack them in order with /bin/sh # file dm37p2 continued # if test ! -r _shar_seq_.tmp; then echo 'Please unpack part 1 first!' exit 1 fi (read Scheck if test "$Scheck" != 5; 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 echo 'x - still skipping dm37p2' else echo 'x - continuing file dm37p2' sed 's/^X//' << 'SHAR_EOF' >> 'dm37p2' && XProcessing of prerequisites which contain macro expansions in their name. X.IP "\fBBINDING TARGETS\fP" 1.9i XThe rules that \fBdmake\fP uses to bind Xa target to an existing file in the file system. X.IP "\fBPERCENT(%) RULES\fP" 1.9i XSpecification of recipes to be used by the inference algorithm. X.IP "\fBMAKING INFERENCES\fP" 1.9i XThe rules that \fBdmake\fP uses when inferring how to make a target which Xhas no explicit recipe. This and the previous section are really a single Xsection in the text. X.IP "\fBMAKING TARGETS\fP" 1.9i XHow \fBdmake\fP makes targets other than libraries. X.IP "\fBMAKING LIBRARIES\fP" 1.9i XHow \fBdmake\fP makes libraries. X.IP "\fBKEEP STATE\fP" 1.9i XA discussion of how .KEEP_STATE works. X.IP "\fBMULTI PROCESSING\fP" 1.9i XDiscussion of \fBdmake's\fP parallel make facilities for architectures that Xsupport them. X.IP "\fBCONDITIONALS\fP" 1.9i XConditional expressions which control the processing of the makefile. X.IP "\fBEXAMPLES\fP" 1.9i XSome hopefully useful examples. X.IP "\fBCOMPATIBILITY\fP" 1.9i XHow \fBdmake\fP compares with previous versions of make. X.IP "\fBLIMITS\fP" 1.9i XLimitations of \fBdmake\fP. X.IP \fBPORTABILITY\fP 1.9i XComments on writing portable makefiles. X.IP \fBFILES\fP 1.9i XFiles used by \fBdmake\fP. X.IP "\fBSEE ALSO\fP" 1.9i XOther related programs, and man pages. X.IP "\fBAUTHOR\fP" 1.9i XThe guy responsible for this thing. X.IP \fBBUGS\fP 1.9i XHope not. X.SH STARTUP XWhen X.B dmake Xbegins execution it first processes the command line and then processes Xan initial startup-makefile. XThis is followed by an attempt to locate and process a user supplied makefile. XThe startup file defines the default values of all required control macros Xand the set of default rules for making targets and inferences. XWhen searching for the startup makefile, X.B dmake Xsearches the following locations, in the order specified, Xuntil a startup file is located: X.LP X.RS X.IP 1. XThe location given as the value of the macro XMAKESTARTUP defined on the command line. X.IP 2. XThe location given as the value of the environment variable MAKESTARTUP Xdefined in the current environment. X.IP 3. XThe location given as the value of the macro XMAKESTARTUP defined internally within \fBdmake\fP. X.RE X.LP XThe above search is disabled by specifying the \-r option on the command line. XAn error is issued if a startup makefile cannot be found and the \-r Xoption was not specified. XA user may substitute a custom startup file by defining Xthe MAKESTARTUP environment variable or by redefining the XMAKESTARTUP macro on the command line. XTo determine where X.B dmake Xlooks for the default startup file, check your environment or issue the command X\fI"dmake \-V"\fP. X.PP XA similar search is performed to locate a default user makefile when no X\fB\-f\fP command line option is specified. XBy default, the prerequisite list of the special target .MAKEFILES Xspecifies the names of possible makefiles and the search order that X\fBdmake\fP should use to determine if one exists. XA typical definition for this target is: X.RS X.sp X\&.MAKEFILES : makefile.mk Makefile makefile X.sp X.RE X\fBdmake\fP will first look for makefile.mk and then the others. XIf a prerequisite Xcannot be found \fBdmake\fP will try to make it before going on to the next Xprerequisite. For example, makefile.mk can be checked out of an RCS file Xif the proper rules for doing so are defined in the startup file. X.SH SYNTAX XThis section is a summary of the syntax of makefile statements. XThe description is given in a style similar to BNF, where { } enclose Xitems that may appear zero or more times, and [ ] enclose items that Xare optional. Alternative productions for a left hand side are indicated Xby '\(->', and newlines are significant. All symbols in \fBbold\fP type Xare text or names representing text supplied by the user. X.sp 2 X.RS X.Ip "Makefile" "\(-> { Statement }" X.Ip "Statement" "\(-> Macro-Definition" X\(-> Conditional X\(-> Rule-Definition X\(-> Attribute-Definition X.Ip "Macro-Definition" "\(-> \fBMACRO = LINE\fP" X\(-> \fBMACRO *= LINE\fP X\(-> \fBMACRO := LINE\fP X\(-> \fBMACRO *:= LINE\fP X\(-> \fBMACRO += LINE\fP X\(-> \fBMACRO +:= LINE\fP X.Ip "Conditional \(-> " "\fB\&.IF\fR expression" XX Makefile X[ \fB.ELIF\fR expression XX Makefile ] X[ \fB.ELSE\fR XX Makefile ] X\fB\&.END\fR X.Ip expression "\(-> \fBLINE\fR" X\(-> \fBSTRING == LINE\fR X\(-> \fBSTRING != LINE\fR X.sp X.Ip "Rule-Definition \(-> " "target-definition" XX [ recipe ] X.PP Xtarget-definition \(-> targets [attrs] op { \fBPREREQUISITE\fP } [\fB;\fR rcp-line] X.Ip "targets" "\(-> target { targets }" X\(-> \fB"\fRtarget\fB"\fR { targets } X.Ip "target" "\(-> special-target" X\(-> \fBTARGET\fR X.Ip "attrs" "\(-> attribute { attrs }" X\(-> \fB"\fRattribute\fB"\fR { attrs } X.Ip "op" "\(-> \fB:\fR { modifier }" X.Ip "modifier" "\(-> \fB:\fR" X\(-> \fB^\fR X\(-> \fB!\fR X\(-> \fB\-\fR X.Ip "recipe" "\(-> { \fBTAB\fR rcp-line }" X\(-> [\fB@\fR][\fB%\fR][\fB\-\fR] \fB[ X.Is "recipe \(-> " X.Ii " " XX \fR{ \fBLINE\fR } X.Ii " " X\fB]\fR X.Ip "rcp-line" "\(-> [\fB@\fR][\fB%\fR][\fB\-\fR][\fB+\fR] \fBLINE\fR" X.sp X.Ip Attribute-Definition "\(-> attrs \fB:\fR targets" X.sp X.Ip "attribute" "\(-> \fB.EPILOG\fR" X\(-> \fB.IGNORE\fR X\(-> \fB.LIBRARY\fR X\(-> \fB.MKSARGS\fR X\(-> \fB.NOINFER\fR X\(-> \fB.NOSTATE\fR X\(-> \fB.PHONY\fR X\(-> \fB.PRECIOUS\fR X\(-> \fB.PROLOG\fR X\(-> \fB.SETDIR=\fIpath\fP\fR X\(-> \fB.SILENT\fR X\(-> \fB.SEQUENTIAL\fR X\(-> \fB.SWAP\fR X\(-> \fB.USESHELL\fR X\(-> \fB.SYMBOL\fR X\(-> \fB.UPDATEALL\fR X.Ip "special-target" "\(-> \fB.ERROR\fR" X\(-> \fB.EXPORT\fR X\(-> \fB.GROUPEPILOG\fR X\(-> \fB.GROUPPROLOG\fR X\(-> \fB.IMPORT\fR X\(-> \fB.INCLUDE\fR X\(-> \fB.INCLUDEDIRS\fR X\(-> \fB.MAKEFILES\fR X\(-> \fB.REMOVE\fR X\(-> \fB.SOURCE\fR X\(-> \fB.SOURCE.\fIsuffix\fR X\(-> .\fIsuffix1\fR.\fIsuffix2\fR X.fi X.RE X.sp 1 X.PP XWhere, \fBTAB\fP represents a <tab> character, \fBSTRING\fP represents an Xarbitrary sequence of characters, and X\fBLINE\fP represents a Xpossibly empty sequence of characters terminated by a non-escaped X(not immediately preceded by a backslash '\e') new-line character. X\fBMACRO\fP, \fBPREREQUISITE\fP, Xand \fBTARGET\fP each represent a string of characters not Xincluding space or tab which respectively form the name of a macro, Xprerequisite or target. XThe name may itself be a macro expansion expression. XA \fBLINE\fP can be continued over several physical lines by terminating it with Xa single backslash character. Comments are initiated by the Xpound \fB#\fR character and extend to the end of line. XAll comment text is discarded, a '#' may be placed into the makefile text Xby escaping it with '\e' (ie. \e# translates to # when it is parsed). XAn exception to this occurs when a # is seen inside Xa recipe line that begins with a <tab> or is inside a group recipe. XIf you specify the \fB\-c\fP command line switch then this behavior is Xdisabled and X.B dmake Xwill treat all # characters as start of comment indicators unless they Xare escaped by \e. XA set of continued lines may be commented out by placing a single # at the Xstart of the first line. XA continued line cannot span more than one makefile. X.PP X\fBwhite space\fP is defined to be any combination of X<space>, <tab>, and the sequence \e<nl> Xwhen \e<nl> is used to terminate a LINE. XWhen processing \fBmacro\fP definition lines, Xany amount of white space is allowed on either side of the macro operator X(=, *=, :=, *:=, += or +:=), and Xwhite space is stripped from both before and after the macro Xvalue string. XThe sequence \e<nl> is treated as Xwhite space during recipe expansion Xand is deleted from the final recipe string. XYou must escape the \e<nl> with another \e in order to get a \e at the end Xof a recipe line. XThe \e<nl> sequence is deleted from macro values when they are expanded. X.PP XWhen processing \fBtarget\fP definition lines, Xthe recipe for a target must, in general, follow the first definition Xof the target (See the RULES AND TARGETS section for an exception), and Xthe recipe may not span across multiple makefiles. XAny targets and prerequisites found on a target definition line are taken Xto be white space separated tokens. XThe rule operator (\fIop\fP in SYNTAX section) is also considered Xto be a token but does not require Xwhite space to precede or follow it. Since the rule operator begins with a `:', Xtraditional versions of make do not allow the `:' character to Xform a valid target name. \fBdmake\fP allows `:' to be present in Xtarget/prerequisite names as long as the entire target/prerequisite name is Xquoted. For example: X.sp X\ta:fred : test X.sp Xwould be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which Xis not what was intended. To fix this you must write: X.sp X\t"a:fred" : test X.sp XWhich will be parsed as expected. XSee the EXAMPLES section for how to apply \fB"\fP quoting Xto a list of targets. X.SH ATTRIBUTES X.B dmake Xdefines several target attributes. Attributes may be Xassigned to a single target, a group of targets, or to all targets in the Xmakefile. Attributes are used to modify X\fBdmake\fP actions during target update. XThe recognized attributes are: X.sp X.IP \fB.EPILOG\fP 1.2i XInsert shell epilog code when executing a group recipe associated with Xany target having this attribute set. X.IP \fB.IGNORE\fP 1.2i XIgnore an error when trying to make any target with this attribute set. X.IP \fB.LIBRARY\fP 1.2i XTarget is a library. X.IP \fB.MKSARGS\fP 1.2i XIf running in an MSDOS environment then use MKS extended argument passing Xconventions to pass arguments to commands. Non-MSDOS Xenvironments ignore this attribute. X.IP \fB.NOINFER\fP 1.2i XAny target with this attribute set will not be subjected Xto transitive closure if it is inferred as a prerequisite Xof a target whose recipe and prerequisites are being inferred. X(i.e. the inference algorithm will not use any prerequisite with this attribute Xset, as a target) XIf specified as '.NOINFER:' (ie. with no prerequisites or targets) then the Xeffect is equivalent to specifying \fB\-T\fP on the command line. X.IP \fB.NOSTATE\fP 1.2i XAny target with this attribute set will not have command line flag Xinformation stored in the state file if .KEEP_STATE has been enabled. X.IP \fB.PHONY\fP 1.2i XAny target with this attribute set will have its recipe executed Xeach time the target is made even if a file matching the target name can Xbe located. Any targets that have a .PHONY attributed target as a Xprerequisite will be made each time the .PHONY attributed prerequisite is Xmade. X.IP \fB.PRECIOUS\fP 1.2i XDo not remove associated target under any circumstances. XSet by default for any targets whose corresponding files exist in the file Xsystem prior to the execution of \fBdmake\fP. X.IP \fB.PROLOG\fP 1.2i XInsert shell prolog code when executing a group recipe associated with Xany target having this attribute set. X.IP \fB.SEQUENTIAL\fP 1.2i XForce a sequential make of the associated target's prerequisites. X.IP \fB.SETDIR\fP 1.2i XChange current working directory to specified directory when making the Xassociated target. You must Xspecify the directory at the time the attribute is specified. To do this Xsimply give \fI.SETDIR=path\fP as the attribute. \fIpath\fP is expanded and Xthe result is used as the value of the directory to change to. XIf path is surrounded by single quotes then path is not expanded, and is used Xliterally as the directory name. XIf the \fIpath\fP contains any `:' characters then the entire attribute string Xmust be quoted using ". XIf a target having this attribute set also has the .IGNORE Xattribute set then if the change to the specified directory fails it will be Xignored, and no error message will be issued. X.IP \fB.SILENT\fP 1.2i XDo not echo the recipe lines when making any target with this attribute set, Xand do not issue any warnings. X.IP \fB.SWAP\fP 1.2i XUnder MSDOS Xwhen making a target with this attribute set swap the \fBdmake\fP executable Xto disk prior to executing the recipe line. Also see the '%' recipe line Xflag defined in the RECIPES section. X.IP \fB.SYMBOL\fP 1.2i XTarget is a library member and is an entry point into a module in the Xlibrary. This attribute is used only when searching a library for a target. XTargets of the form lib((entry)) have this attribute set automatically. X.IP \fB.USESHELL\fP 1.2i XForce each recipe line of a target to be executed using a shell. XSpecifying this attribute is equivalent to specifying the '+' character at the Xstart of each line of a non-group recipe. X.IP \fB.UPDATEALL\fP 1.2i XIndicates that all the targets listed in this rule are updated by the Xexecution of the accompanying recipe. XA common example is the production of the X.I y.tab.c Xand X.I y.tab.h Xfiles by X.B yacc Xwhen it is run on a grammar. Specifying .UPDATEALL in such a rule Xprevents the running of yacc twice, once for the y.tab.c file and once Xfor the y.tab.h file. X.sp X.PP XAll attributes are user setable and except for .UPDATEALL, .SETDIR and .MKSARGS Xmay be used in one of two forms. XThe .MKSARGS attribute is restricted to use as a global attribute, and Xthe use of the .UPDATEALL and .SETDIR attributes is restricted to rules Xof the second form only. X.sp X\tATTRIBUTE_LIST : \fItargets\fP X.sp Xassigns the attributes specified by ATTRIBUTE_LIST to each target in X.I targets Xor X.sp X\t\fItargets\fP ATTRIBUTE_LIST : ... X.sp Xassigns the attributes specified by ATTRIBUTE_LIST to each target in X.I targets. XIn the first form if X.I targets Xis empty (ie. a NULL list), then the Xlist of attributes will apply to all targets in the makefile X(this is equivalent to the common Make construct of \fI".IGNORE :"\fP Xbut has been modified to the notion of an attribute instead of Xa special target). XNot all of the attributes have global meaning. XIn particular, .LIBRARY, .SYMBOL, and .UPDATEALL Xhave no assigned global meaning. X.PP XAny attribute may be used with any target, even with the special targets. XSome combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ), Xwhile others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain Xif file.mk cannot be found using the include file search rules, Xsee the section on SPECIAL TARGETS for a description of .INCLUDE). XIf a specified attribute will not be used with the special target a warning Xis issued and the attribute is ignored. X.SH MACROS X.B dmake Xsupports six types of macro assignment. X.sp X.IP "\fBMACRO = LINE\fP" 1.55i XThis is the most common and familiar form of macro assignment. It assigns XLINE literally as the value of MACRO. XFuture expansions of MACRO recursively expand its value. X.IP "\fBMACRO *= LINE\fP" 1.55i XThis form behaves exactly as the simple '=' form with the exception that if XMACRO already has a value then the assignment is not performed. X.IP "\fBMACRO := LINE\fP" 1.55i XThis form differs from the simple '=' form in that it expands LINE Xprior to assigning it as the value of MACRO. XFuture expansions of MACRO do not recursively expand its value. X.IP "\fBMACRO *:= LINE\fP" 1.55i XThis form behaves exactly as the ':=' form with the exception that if XMACRO already has a value then the assignment and expansion are not performed. X.IP "\fBMACRO += LINE\fP" 1.55i XThis form of macro assignment allows macro values to grow. It takes the Xliteral value of LINE and appends it to the previous value of MACRO separating Xthe two by a single space. XFuture expansions of MACRO recursively expand its value. X.IP "\fBMACRO +:= LINE\fP" 1.55i XThis form is similar to the '+=' form except that the value of LINE is expanded Xprior to being added to the value of MACRO. X.PP XMacro expressions specified on the command line allow the macro value Xto be redefined within the makefile only if the macro is defined using Xthe '+=' and '+:=' operators. Other operators will define a macro that cannot Xbe further modified. X.PP XWhen \fBdmake\fP defines a non-environment macro it strips leading and Xtrailing white space from the macro value. XMacros imported from the environment via either the .IMPORT special Xtarget (see the SPECIAL TARGETS section), or the \fB\-e\fP, or \fB\-E\fP flags Xare an exception to this rule. Their values are Xalways taken literally and white space is never stripped. XIn addition, named macros defined using the .IMPORT special target do Xnot have their values expanded when they are used within a makefile. XIn contrast, environment macros that are imported Xdue to the specification of the \fB\-e\fP or \fB\-E\fP flags Xare subject to expansion when used. X.PP XTo specify a macro expansion Xenclose the name in () or {} and precede it with a dollar sign $. XThus $(TEST) represents an expansion of the macro variable named TEST. XIf TEST is Xdefined then $(TEST) is replaced by its expanded value. If TEST is not Xdefined then $(TEST) expands to the NULL string (this is equivalent to Xdefining a macro as 'TEST=' ). A short form may be used for single character Xnamed macros. In this case the parentheses are optional, and $(I) is Xequivalent to $I. XMacro expansion is recursive, hence, if the value string contains an expression Xrepresenting a macro expansion, the expansion is performed. Circular macro Xexpansions are detected and cause an error to be issued. X.PP XWhen defining a macro the given macro name is first expanded before being used Xto define the macro. Thus it is possible to define macros whose names Xdepend on values of other macros. For example, suppose CWD is defined as X.sp X\tCWD = $(PWD:b) X.sp Xthen the value of $(CWD) is the name of the current directory. XThis can be used to define macros specific to this directory, for Xexample: X.sp X\t_$(CWD).prt = list of files to print... X.sp XThe actual name of the defined macro is a function of the current directory. XA construct such as this is useful when processing a hierarchy of directories Xusing .SETDIR attributed targets and a collection of small distributed Xmakefile stubs. X.PP XMacro variables may be defined within the makefile, on the command Xline, or imported from the environment. X.PP X.B \fBdmake\fR Xsupports several non-standard macro expansions: XThe first is of the form: X.RS X.IP \fI$(macro_name:modifier_list:modifier_list:...)\fR X.RE X.LP Xwhere X.I modifier_list Xis chosen from the set { D or d, F or f, B or b, S or s, T or t } and X.RS X.sp X.Is "d " X.Ii "d " X\- directory portion of all path names X.Ii "f" X\- file (including suffix) portion of path names X.Ii "b" X\- file (not including suffix) portion of path names X.Ii "s" X\- simple pattern substitution X.Ii "t" X\- tokenization. X.sp X.RE XThus if we have the example: X.LP X\ttest = d1/d2/d3/a.out f.out d1/k.out X.LP XThe following macro expansions produce the values on the right of '\(->' after Xexpansion. X.RS X.sp X.Is "$(test:s/out/in/:f) " X.Ii "$(test:d)" X\(-> d1/d2/d3/ d1/ X.Ii "$(test:b)" X\(-> a f k X.Ii "$(test:f)" X\(-> a.out f.out k.out X.Ii "${test:db}" X\(-> d1/d2/d3/a f d1/k X.Ii "${test:s/out/in/:f}" X\(-> a.in f.in k.in X.Ii $(test:f:t"+") X\(-> a.out+f.out+k.out X.RE X.PP XIf a token ends in a string composed from the value of the macro DIRBRKSTR X(ie. ends in a directory separator string, e.g. '/' in UNIX) and you use the X\fB:d\fP modifier then the expansion returns the directory name less the Xfinal directory separator string. Thus successive pairs of :d modifiers Xeach remove a level of directory in the token string. X.PP XThe tokenization modifier takes all white space separated tokens from the Xmacro value and separates them by the quoted separator string. The separator Xstring may contain the following escape codes \ea => <bel>, X\&\eb => <backspace>, \ef => <formfeed>, \en => <nl>, \er => <cr>, X\&\et => <tab>, \ev => <vertical tab>, \e" => ", and \exxx => <xxx> where Xxxx is the octal representation of a character. Thus the Xexpansion: X.LP X.RS X.nf X$(test:f:t"+\en") X.RE Xproduces: X.RS Xa.out+ Xf.out+ Xk.out X.fi X.RE X.PP XThe second non-standard form of macro expansion allows for recursive macros. XIt is possible to specify a $(\fImacro_name\fR) or ${\fImacro_name\fR} expansion Xwhere \fImacro_name\fR contains more $( ... ) or ${ ... } macro expansions Xitself. X.PP XFor example $(CC$(_HOST)$(_COMPILER)) will first expand CC$(_HOST)$(_COMPILER) Xto get a result and use that result as the name of the macro to expand. XThis is useful for writing a makefile for more than one target Xenvironment. As an example consider the following hypothetical case. XSuppose that _HOST and _COMPILER are imported from the environment Xand are set to represent the host machine type and the host compiler Xrespectively. X.RS X.sp X.nf XCFLAGS_VAX_CC = \-c \-O # _HOST == "_VAX", _COMPILER == "_CC" XCFLAGS_PC_MSC = \-c \-ML # _HOST == "_PC", _COMPILER == "_MSC" X.sp X# redefine CFLAGS macro as: X.sp XCFLAGS := $(CFLAGS$(_HOST)$(_COMPILER)) X.fi X.sp X.RE XThis causes CFLAGS to take on a value that corresponds to the Xenvironment in which the make is being invoked. X.PP XThe final non-standard macro expansion is of the form: X.RS X.sp Xstring1{token_list}string2 X.RE X.LP Xwhere string1, string2 and token_list are expanded. After expansion, Xstring1 is prepended to each token found in token_list and Xstring2 is appended to each resulting token from the previous prepend. Xstring1 and string2 are not delimited by white space Xwhereas the tokens in token_list are. XA null token in the token list Xis specified using "". XThus using another example we have: X.RS X.sp X.Is "test/{f1 f2}.o " X.Ii "test/{f1 f2}.o" X--> test/f1.o test/f2.o X.Ii "test/ {f1 f2}.o" X--> test/ f1.o f2.o X.Ii "test/{f1 f2} .o" X--> test/f1 test/f2 .o X.Ii "test/{""f1"" """"}.o" X--> test/f1.o test/.o X.sp X.Ii and X.sp X.Is "test/{d1 d2}/{f1 f2}.o --> " X.Ii "test/{d1 d2}/{f1 f2}.o --> " Xtest/d1/f1.o test/d1/f2.o Xtest/d2/f1.o test/d2/f2.o X.sp X.RE XThis last expansion is activated only when the first characters of X.I token_list Xappear immediately after the opening '{' with no intervening white space. XThe reason for this restriction is the following incompatibility with XBourne Shell recipes. The line X.RS X.sp X{ echo hello;} X.sp X.RE Xis valid /bin/sh syntax; while X.RS X.sp X{echo hello;} X.sp X.RE Xis not. XHence the latter triggers the enhanced macro expansion while the former Xcauses it to be suppressed. XSee the SPECIAL MACROS section for a description of the special macros that X\fBdmake\fP defines and understands. X.SH "RULES AND TARGETS" XA makefile contains a series of entries that specify dependencies. XSuch entries are called \fItarget/prerequisite\fP or \fIrule\fP definitions. XEach rule definition Xis optionally followed by a set of lines that provide a recipe for updating Xany targets defined by the rule. XWhenever X.B dmake Xattempts to bring a target up to date and an explicit recipe is provided with Xa rule defining the target, that recipe is used to update the Xtarget. A rule definition begins with a line having the following syntax: X.sp X.RS X.nf X\fI<targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<prerequisites>\fP] [;\fI<recipe>\fP] X.fi X.RE X.sp X.I targets Xis a non-empty list of targets. If the target is a Xspecial target (see SPECIAL TARGETS section below) then it must appear alone Xon the rule line. For example: X.sp X.RS X\&.IMPORT .ERROR : ... X.RE X.sp Xis not allowed since both .IMPORT and .ERROR are special targets. XSpecial targets are not used in the construction of the dependency graph and Xwill not be made. X.PP X.I attributes Xis a possibly empty list of attributes. Any attribute defined in the XATTRIBUTES section above may be specified. All attributes will be applied to Xthe list of named targets in the rule definition. No other targets will Xbe affected. X.sp X.IP NOTE: 0.75i XAs stated earlier, Xif both the target list and prerequisite list are empty but the attributes Xlist is not, then the specified attributes affect all targets in the makefile. X.sp X.PP X.I ruleop Xis a separator which is used to identify the targets from the prerequisites. XOptionally it also provides a facility for modifying the way in which X.B dmake Xhandles the making of the associated targets. XIn its simplest form the operator is a single ':', and need not be separated Xby white space from its neighboring tokens. It may additionally be followed Xby any of the modifiers { !, ^, \-, : }, where: X.sp X.IP \fB!\fP Xsays execute the recipe for the associated targets once for each out of date Xprerequisite. Ordinarily the recipe is executed Xonce for all out of date prerequisites at the same time. X.IP \fB^\fP Xsays to insert the specified prerequisites, if any, before any Xother prerequisites already associated with the specified targets. XIn general, it is not useful to specify ^ with an empty Xlist of prerequisites. X.IP \fB\-\fP Xsays to clear the previous list of prerequisites before adding Xthe new prerequisites. Thus, X.sp X\t.SUFFIXES : X.br X\t.SUFFIXES : .a .b X.sp Xcan be replaced by X.sp X\t.SUFFIXES :\- .a .b X.sp Xhowever the old form still works as expected. NOTE: .SUFFIXES is ignored by X.B dmake Xit is used here simply as an example. X.IP \fB:\fP XWhen the rule operator is not modified by a second ':' Xonly one set of rules may be specified for making a target. XMultiple definitions may be used to add to the Xlist of prerequisites that a target depends on. XHowever, if a target is multiply defined Xonly one definition may specify a recipe Xfor making the target. X.sp XWhen a target's rule operator is modified by a second ':' X(:: for example) then this definition may not be the only Xdefinition with a recipe for the target. There may be other :: target Xdefinition lines that specify a different set of prerequisites with a Xdifferent recipe for updating the target. XAny such target is made if any of the definitions Xfind it to be out of date Xwith respect to the related prerequisites Xand the corresponding recipe is used to update the Xtarget. X.sp XIn the following simple example, each rule has a `::' \fIruleop\fP. In such an Xoperator we call the first `:' the operator, and the second `:' the modifier. X.sp X.nf Xa.o :: a.c b.h XX first recipe for making a.o XX Xa.o :: a.y b.h XX second recipe for making a.o X.fi X.sp XIf a.o is found to be out of date with respect to a.c then the first recipe Xis used to make a.o. If it is found out of date with respect to a.y then Xthe second recipe is used. If a.o is out of date with respect to Xb.h then both recipes are invoked to make a.o. XIn the last case the order of invocation corresponds to the order in which the Xrule definitions appear in the makefile. X.PP XTargets defined using a single `:' operator Xwith a recipe may be redefined again with a new recipe by using a X`:' operator with a `:' modifier. XThis is equivalent to a target having been Xinitially defined with a rule using a `:' modifier. XOnce a target is defined using a `:' Xmodifier it may not be defined again with a recipe using only the `:' operator Xwith no `:' modifier. In both cases the use of a `:' modifier creates a new Xlist of prerequisites and makes it the current prerequisite list for the target. XThe `:' operator with no recipe always modifies the current list Xof prerequisites. XThus assuming each of the following definitions has a recipe attached, then: X.RS X.sp X.nf Xjoe : fred ... (1) Xjoe :: more ... (2) X.sp Xand X.sp Xjoe :: fred ... (3) Xjoe :: more ... (4) X.sp X.fi X.RE Xare legal and mean: add the recipe associated with (2), or (4) to the set Xof recipes for joe, placing them after existing recipes for Xmaking joe. XThe constructs: X.RS X.sp X.nf Xjoe :: fred ... (5) Xjoe : more ... (6) X.sp Xand X.sp Xjoe : fred ... (7) Xjoe : more ... (8) X.sp X.fi X.RE Xare errors since we have two sets of perfectly good recipes for Xmaking the target. X.PP X.I prerequisites Xis a possibly empty list of targets that must be brought up to date before Xmaking the current target. X.PP X.I recipe Xis a short form and allows the user to specify short rule definitions Xon a single line. XIt is taken to be the first recipe line in a larger recipe Xif additional lines follow the rule definition. XIf the semi-colon is present but the recipe line is empty (ie. null string) Xthen it is taken Xto be an empty rule. Any target so defined causes the X.I "Don't know how to make ..." Xerror message to be suppressed when X.B dmake Xtries to make the target and fails. XThis silence is maintained for rules that are terminated Xby a semicolon and have no following recipe lines, for targets listed on the Xcommand line, for the first target found in the makefile, and for any target Xhaving no recipe but containing a list of prerequisites (see the COMPATIBILITY Xsection for an exception to this rule if the AUGMAKE (\fB\-A\fP) flag Xwas specified. X.SH "RECIPES" XThe traditional format used by most versions of Make defines the recipe Xlines as arbitrary strings that may contain macro expansions. They Xfollow a rule definition line and may be spaced Xapart by comment or blank lines. XThe list of recipe lines defining the recipe is terminated by a new target Xdefinition, a macro definition, or end-of-file. XEach recipe line X.B MUST Xbegin with a \fB<TAB>\fP character which Xmay optionally be followed with one or all Xof the characters X.IR "'@%+\-'" "." XThe X.I "'\-'" Xindicates that non-zero exit values (ie. errors) Xare to be ignored when this recipe line is executed, the X.I "'\+'" Xindicates that the current recipe line is to be executed using the shell, the X.I "'%'" Xindicates that X.B dmake Xshould swap itself out to secondary storage (MSDOS only) before running the Xrecipe and the X.I "'@'" Xindicates that the recipe line should NOT be echoed to the terminal prior to Xbeing executed. Each switch is off by default X(ie. by default, errors are significant, commands are echoed, no swapping is Xdone and a shell is Xused only if the recipe line contains a character found in the value of the XSHELLMETAS macro). XGlobal settings activated via command line options or special attribute or Xtarget names may also affect these settings. XAn example recipe: X.sp X.RS X.nf Xtarget : X\tfirst recipe line X\tsecond recipe line, executed independently of the first. X\t@a recipe line that is not echoed X\t\-and one that has errors ignored X\t%and one that causes dmake to swap out X\t\+and one that is executed using a shell. X.fi X.RE X.PP XThe second and new format of the recipe block begins the block with the Xcharacter '[' (the open group character) in the last non-white space Xposition of a line, and terminates the Xblock with the character ']' (the close group character) Xin the first non-white space position of a line. XIn this form each recipe line need not have a leading TAB. This is Xcalled a recipe group. Groups so defined are fed intact as a single Xunit to a shell for execution whenever the corresponding target needs to Xbe updated. If the open group character '[' is preceded Xby one or all of \-, @ or % Xthen they apply to the entire group in the same way that they Xapply to single recipe lines. You may also specify '+' but it is Xredundant as a shell is already being used to run the recipe. XSee the MAKING TARGETS section for a description of how X.B dmake Xinvokes recipes. XHere is an example of a group recipe: X.sp X.RS X.nf Xtarget : X[ X\tfirst recipe line X\tsecond recipe line X\tall of these recipe lines are fed to a X\tsingle copy of a shell for execution. X] X.fi X.RE X.sp X.SH "TEXT DIVERSIONS" X.B dmake Xsupports the notion of text diversions. XIf a recipe line contains the macro expression X.RS X.sp X$(mktmp[,[\fIfile\fP][,\fItext\fP]] \fIdata\fP) X.sp X.RE Xthen all text contained in the \fIdata\fP expression is expanded and Xis written to a temporary file. The return Xvalue of the macro is the name of the temporary file. X.PP X.I data Xcan be any text and must be separated from the 'mktmp' portion of the Xmacro name by white-space. The only restriction on the data text is that Xit must contain a balanced number of parentheses of the same kind as are Xused to initiate the $(mktmp ...) expression. For example: X.sp X\t$(mktmp $(XXX)) X.sp Xis legal and works as expected, but: X.sp X\t$(mktmp text (to dump to file) X.sp Xis not legal. You can achieve what you wish by either defining a macro that Xexpands to '(' or by using {} in the macro expression; like this: X.sp X\t${mktmp text (to dump to file} X.sp XSince the temporary file is opened when the Xmacro containing the text diversion expression is expanded, diversions may Xnow be nested and any diversions that are created as part of ':=' macro Xexpansions persist for the duration of the X.B dmake Xrun. XThe diversion text may contain Xthe same escape codes as those described in the MACROS section. XThus if the \fIdata\fP text is to contain new lines they must be inserted Xusing the \en escape sequence. For example the expression: X.RS X.sp X.nf Xall: XX cat $(mktmp this is a\en\e XX test of the text diversion\en) X.fi X.sp X.RE Xis replaced by: X.RS X.sp Xcat /tmp/mk12294AA X.sp X.RE Xwhere the temporary file contains two lines both of which are terminated Xby a new-line. If the \fIdata\fP text spans multiple lines in the makefile Xthen each line must be continued via the use of a \e. XA second more illustrative example generates a response file to an MSDOS Xlink command: X.RS X.sp X.nf XOBJ = fred.obj mary.obj joe.obj Xall : $(OBJ) XX link @$(mktmp $(^:t"+\en")\en) 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 \en found at the end of the \fIdata\fP string. X.PP XIf the optional \fIfile\fP specifier is present then its expanded value Xis the name of the temporary file to create. Whenever a $(mktmp ...) macro Xis expanded the macro $(TMPFILE) is set to a new temporary file name. Thus Xthe construct: X.RS X.sp X$(mktmp,$(TMPFILE) data) X.sp X.RE Xis completely equivalent to not specifying the $(TMPFILE) optional argument. XAnother example that would be useful for MSDOS users with a Turbo-C compiler X.RS X.sp X$(mktmp,turboc.cfg $(CFLAGS)) X.sp X.RE Xwill place the contents of CFLAGS into a local \fIturboc.cfg\fP file. XThe second optional argument, \fItext\fP, if present alters the name Xof the value returned by the $(mktmp ...) macro. X.PP XUnder MS-DOS text diversions may be a problem. Many DOS tools require Xthat path names which contain directories use the \e character to delimit Xthe directories. Some users however wish to use the '/' to delimit pathnames Xand use environments that allow them to do so. XThe macro USESHELL is set to "yes" if the Xcurrent recipe is forced to use a shell via the .USESHELL or '+' directives, Xotherwise its value is "no". XThe X.B dmake Xstartup files define the macro DIVFILE whose value is either the Xvalue of TMPFILE or the value of TMPFILE edited to replace any '/' characters Xto the appropriate value based on the current shell and whether it will be Xused to execute the recipe. X.PP XPrevious versions of X.B dmake Xdefined text diversions using <+, +> strings, Xwhere <+ started a text diversion and +> terminated one. X.B dmake Xis backward compatible with this construct if the <+ and +> appear literally Xon the same recipe line or in the same macro value string. In such instances Xthe expression: X.sp X\t<+data+> X.sp Xis mapped to: X.sp X\t$(mktmp data) X.sp Xwhich is fully output compatible with the earlier construct. <+, +> Xconstructs whose text spans multiple lines must be converted by hand to use X$(mktmp ...). X.PP XIf the environment variable TMPDIR is defined then the Xtemporary file is placed into the directory specified by that variable. XA makefile can modify the location of temporary files by Xdefining a macro named TMPDIR and exporting it using the .EXPORT special Xtarget. X.SH "SPECIAL TARGETS" XThis section describes the special targets that are recognized by \fBdmake\fP. XSome are affected by attributes and others are not. X.IP \fB.ERROR\fP 1.4i XIf defined then the recipe associated with this target is executed Xwhenever an error condition is detected by \fBdmake\fP. All attributes that Xcan be used with any other target may be used with this target. Any Xprerequisites of this target will be brought up to date during its 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 special name \fB.EVERYTHING\fP is used as a prerequisite name then Xall environment variables defined in the environment are imported. XThe functionality of the \fB\-e\fP flag can be forced by placing the construct X\&\fI.IMPORT : .EVERYTHING\fP at the start of a makefile. Similarly, by Xplacing the construct at the end, one can emulate the effect of the \fB\-E\fP SHAR_EOF true || echo 'restore of dm37p2 failed' fi echo 'End of part 5' echo 'File dm37p2 is continued in part 6' echo 6 > _shar_seq_.tmp exit 0 exit 0 # Just in case... -- Kent Landfield INTERNET: kent@sparky.IMD.Sterling.COM Sterling Software, IMD UUCP: uunet!sparky!kent Phone: (402) 291-8300 FAX: (402) 291-4362 Please send comp.sources.misc-related mail to kent@uunet.uu.net.