OS/2 Shareware BBS: 10 Tools

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 10 Tools / 10-Tools.zip / dmake40.zip / man / dmake.nc.A next >

Wrap

Text File | 1994-10-23 | 69KB | 1,801 lines

DMAKE(p) Unsupported Free Software DMAKE(p) NAME dmake - maintain program groups, or interdependent files SYNOPSIS dmake [-P#] [-{f|C|K} file] [-{w|W} target ...] [macro[[!][*][+][:]]=value ...] [-v{cdfimt}] [-ABcdeEghiknpqrsStTuVxX] [target ...] DESCRIPTION dmake is a re-implementation of the UNIX Make utility with significant enhancements. dmake executes commands found in an external file called a makefile to update one or more target names. Each target may depend on zero or more prere- quisite targets. If any of the target's prerequisites is newer than the target or if the target itself does not exist, then dmake will attempt to make the target. If no -f command line option is present then dmake searches for an existing makefile from the list of prerequisites specified for the special target .MAKEFILES (see the STARTUP section for more details). If "-" is the name of the file specified to the -f flag then dmake uses standard input as the source of the makefile text. Any macro definitions (arguments with embedded "=" signs) that appear on the command line are processed first and supercede definitions for macros of the same name found within the makefile. In general it is impossible for defin- itions found inside the makefile to redefine a macro defined on the command line, see the MACROS section for exceptions. If no target names are specified on the command line, then dmake uses the first non-special target found in the makefile as the default target. See the SPECIAL TARGETS section for the list of special targets and their function. Makefiles written for most previous versions of Make will be handled correctly by dmake. Known differences between dmake and other versions of make are discussed in the COMPATIBIL- ITY section found at the end of this document. dmake returns 0 if no errors were detected and a non-zero result if an error occurred. OPTIONS -A Enable AUGMAKE special inference rule transformations (see the "PERCENT(%) RULES" section), these are set to off by default. -B Enable the use of spaces instead of <tabs> to begin recipe lines. This flag equivalent to the .NOTABS spe- cial macro and is further described below. Version 3.9 PL0 UW 1 DMAKE(p) Unsupported Free Software DMAKE(p) -c Use non-standard comment stripping. If you specify -c then dmake will treat any # character as a start of comment character wherever it may appear unless it is escaped by a \. -C [+]file This option writes to file a copy of standard output and standard error from any child processes and from the dmake process itself. If you specify a + prior to the file name then the text is appended to the previous contents of file. This option is active in the MSDOS implementation only and is ignored by non-MSDOS ver- sions of dmake. -d Disable the use of the directory cache. Normally dmake caches directories as it checks file timestamps. Giv- ing this flag is equivalent to the .DIRCACHE attribute or macro being set to no. -E Read the environment and define all strings of the form 'ENV-VAR=evalue' defined within as macros whose name is ENV-VAR, and whose value is 'evalue'. The environment is processed prior to processing the user specified makefile thereby allowing definitions in the makefile to override definitions in the environment. -e Same as -E, except that the environment is processed after the user specified makefile has been processed (thus definitions in the environment override defini- tions in the makefile). The -e and -E options are mutually exclusive. If both are given the latter takes effect. -f file Use file as the source for the makefile text. Only one -f option is allowed. -g Globally disable group recipe parsing, equivalent to the .IGNOREGROUP attribute or macro being set to yes at the start of the makefile. -h Print the command summary for dmake. -i Tells dmake to ignore errors, and continue making other targets. This is equivalent to the .IGNORE attribute or macro. -K file Turns on .KEEP_STATE state tracking and tells dmake to use file as the state file. Version 3.9 PL0 UW 2 DMAKE(p) Unsupported Free Software DMAKE(p) -k Causes dmake to ignore errors caused by command execu- tion and to make all targets not depending on targets that could not be made. Ordinarily dmake stops after a command returns a non-zero status, specifying -k causes dmake to ignore the error and continue to make as much as possible. -n Causes dmake to print out what it would have executed, but does not actually execute the commands. A special check is made for the string "$(MAKE)" inside a recipe line, if found, the line is expanded and invoked, thereby enabling recursive makes to give a full description of all that they will do. The check for "$(MAKE)" is disabled inside group recipes. -p Print out a version of the digested makefile in human readable form. (useful for debugging, but cannot be re-read by dmake) -P# On systems that support multi-processing cause dmake to use # concurrent child processes to make targets. See the "MULTI PROCESSING" section for more information. -q Check and see if the target is up to date. Exits with code 0 if up to date, 1 otherwise. -r Tells dmake not to read the initial startup makefile, see STARTUP section for more details. -s Tells dmake to do all its work silently and not echo the commands it is executing to stdout (also suppresses warnings). This is equivalent to the .SILENT attri- bute or macro. -S Force sequential execution of recipes on architectures which support concurrent makes. For backward compati- bility with old makefiles that have nasty side-effect prerequisite dependencies. -t Causes dmake to touch the targets and bring them up to date without executing any commands. Note that targets will not be created if they do not already exist. -T Tells dmake to not perform transitive closure on the inference graph. -u Force an unconditional update. (ie. do everything that would be done if everything that a target depended on was out of date) -v[dfimt] Verbose flag, when making targets print to stdout what Version 3.9 PL0 UW 3 DMAKE(p) Unsupported Free Software DMAKE(p) we are going to make and what we think its time stamp is. The optional flags [dfimt] can be used to restrict the information that is displayed. In the absence of any optional flags all are assumed to be given (ie. -v is equivalent to -vdfimt). The meanings of the optional flags are: d Notify of change directory operations only. f Notify of file I/O operations only. i Notify of inference algorithm operation only. m Notify of target update operations only. t Keep any temporary files created; normally they are automatically deleted. -V Print the version of dmake, and values of builtin mac- ros. -W target Run dmake pretending that target is out of date. -w target What if? Show what would be made if target were out of date. -x Upon processing the user makefile export all non- internally defined macros to the user's environment. This option together with the -e option allows SYSV AUGMAKE recursive makes to function as expected. -X Inhibit the execution of #! lines found at the begin- ning of a makefile. The use of this flag prevents non-termination of recursive make invocations. INDEX Here is a list of the sections that follow and a short description of each. Perhaps you won't have to read the entire man page to find what you need. STARTUP Describes dmake initialization. SYNTAX Describes the syntax of makefile expres- sions. ATTRIBUTES Describes the notion of attributes and how they are used when making targets. MACROS Defining and expanding macros. Version 3.9 PL0 UW 4 DMAKE(p) Unsupported Free Software DMAKE(p) RULES AND TARGETS How to define targets and their prere- quisites. RECIPES How to tell dmake how to make a target. TEXT DIVERSIONS How to use text diversions in recipes and macro expansions. SPECIAL TARGETS Some targets are special. SPECIAL MACROS Macros used by dmake to alter the pro- cessing of the makefile, and those defined by dmake for the user. CONTROL MACROS Itemized list of special control macros. RUN-TIME MACROS Discussion of special run-time macros such as $@ and $<. FUNCTION MACROS GNU style function macros, only $(mktmp ...) for now. CONDITIONAL MACROS Target specific conditional macros. DYNAMIC PREREQUISITES Processing of prerequisites which contain macro expansions in their name. BINDING TARGETS The rules that dmake uses to bind a tar- get to an existing file in the file sys- tem. PERCENT(%) RULES Specification of recipes to be used by the inference algorithm. MAKING INFERENCES The rules that dmake uses when inferring how to make a target which has no expli- cit recipe. This and the previous sec- tion are really a single section in the text. MAKING TARGETS How dmake makes targets other than libraries. MAKING LIBRARIES How dmake makes libraries. KEEP STATE A discussion of how .KEEP_STATE works. MULTI PROCESSING Discussion of dmake's parallel make facilities for architectures that support them. Version 3.9 PL0 UW 5 DMAKE(p) Unsupported Free Software DMAKE(p) CONDITIONALS Conditional expressions which control the processing of the makefile. EXAMPLES Some hopefully useful examples. COMPATIBILITY How dmake compares with previous versions of make. LIMITS Limitations of dmake. PORTABILITY Comments on writing portable makefiles. FILES Files used by dmake. SEE ALSO Other related programs, and man pages. AUTHOR The guy responsible for this thing. BUGS Hope not. STARTUP When dmake begins execution it first processes the command line and then processes an initial startup-makefile. This is followed by an attempt to locate and process a user sup- plied makefile. The startup file defines the default values of all required control macros and the set of default rules for making targets and inferences. When searching for the startup makefile, dmake searches the following locations, in the order specified, until a startup file is located: 1. The location given as the value of the macro MAK- ESTARTUP defined on the command line. 2. The location given as the value of the environment variable MAKESTARTUP defined in the current environment. 3. The location given as the value of the macro MAK- ESTARTUP defined internally within dmake. The above search is disabled by specifying the -r option on the command line. An error is issued if a startup makefile cannot be found and the -r option was not specified. A user may substitute a custom startup file by defining the MAKES- TARTUP environment variable or by redefining the MAKESTARTUP macro on the command line. To determine where dmake looks for the default startup file, check your environment or issue the command "dmake -V". A similar search is performed to locate a default user makefile when no -f command line option is specified. By default, the prerequisite list of the special target Version 3.9 PL0 UW 6 DMAKE(p) Unsupported Free Software DMAKE(p) .MAKEFILES specifies the names of possible makefiles and the search order that dmake should use to determine if one exists. A typical definition for this target is: .MAKEFILES : makefile.mk Makefile makefile dmake will first look for makefile.mk and then the others. If a prerequisite cannot be found dmake will try to make it before going on to the next prerequisite. For example, makefile.mk can be checked out of an RCS file if the proper rules for doing so are defined in the startup file. If the first line of the user makefile is of the form: #! command command_args then dmake will expand and run the command prior to reading any additional input. If the return code of the command is zero then dmake will continue on to process the remainder of the user makefile, if the return code is non-zero then dmake will exit. dmake builds the internal dependency graph as it parses a user specified makefile. The graph is rooted at the special target .ROOT. .ROOT is the top level target that dmake builds when it starts to build targets. All user specified targets (those from the command line or taken as defaults from the makefile) are made prerequisites of the special target .TARGETS. dmake by default creates the relationship that .ROOT depends on .TARGETS and as a result everything is made. This approach allows the user to customize, within their makefile, the order and which, target, is built first. For example the default makefiles come with settings for .ROOT that specify: .ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS .DONE with .INIT and .DONE defined as: .INIT .DONE :; which nicely emulates the behaviour of Sun's make exten- sions. The building of .ROOT's prerequisites is always forced to be sequential. SYNTAX This section is a summary of the syntax of makefile state- ments. The description is given in a style similar to BNF, where { } enclose items that may appear zero or more times, and [ ] enclose items that are optional. Alternative pro- ductions for a left hand side are indicated by '->', and Version 3.9 PL0 UW 7 DMAKE(p) Unsupported Free Software DMAKE(p) newlines are significant. All symbols in bold type are text or names representing text supplied by the user. Makefile -> { Statement } Statement -> Macro-Definition -> Conditional-Macro-Definition -> Conditional -> Rule-Definition -> Attribute-Definition Macro-Definition -> MACRO = LINE -> MACRO [!]*= LINE -> MACRO [!]:= LINE -> MACRO [!]*:= LINE -> MACRO [!]+= LINE -> MACRO [!]+:= LINE Conditional-Macro-Definition -> TARGET ?= Macro- Definition Conditional -> .IF expression Makefile [ .ELIF expression Makefile ] [ .ELSE Makefile ] .END expression -> LINE -> STRING == LINE -> STRING != LINE Rule-Definition -> target-definition [ recipe ] target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line] targets -> target { targets } -> "target" { targets } target -> special-target -> TARGET attrs -> attribute { attrs } -> "attribute" { attrs } op -> : { modifier } Version 3.9 PL0 UW 8 DMAKE(p) Unsupported Free Software DMAKE(p) modifier -> : -> ^ -> ! -> - -> | recipe -> { TAB rcp-line } -> [@][%][-] [ { LINE } ] rcp-line -> [@][%][-][+] LINE Attribute-Definition -> attrs : targets attribute -> .EPILOG -> .GROUP -> .IGNORE -> .IGNOREGROUP -> .LIBRARY -> .MKSARGS -> .NOINFER -> .NOSTATE -> .PHONY -> .PRECIOUS -> .PROLOG -> .SETDIR=path -> .SILENT -> .SEQUENTIAL -> .SWAP -> .USESHELL -> .SYMBOL -> .UPDATEALL special-target -> .ERROR -> .EXIT -> .EXPORT -> .GROUPEPILOG -> .GROUPPROLOG -> .IMPORT -> .INCLUDE -> .INCLUDEDIRS -> .MAKEFILES -> .REMOVE -> .SOURCE -> .SOURCE.suffix -> .suffix1.suffix2 Version 3.9 PL0 UW 9 DMAKE(p) Unsupported Free Software DMAKE(p) Where, TAB represents a <tab> character, STRING represents an arbitrary sequence of characters, and LINE represents a possibly empty sequence of characters terminated by a non- escaped (not immediately preceded by a backslash '\') new- line character. MACRO, PREREQUISITE, and TARGET each represent a string of characters not including space or tab which respectively form the name of a macro, prerequisite or target. The name may itself be a macro expansion expres- sion. A LINE can be continued over several physical lines by terminating it with a single backslash character. Com- ments are initiated by the pound # character and extend to the end of line. All comment text is discarded, a '#' may be placed into the makefile text by escaping it with '\' (ie. \# translates to # when it is parsed). An exception to this occurs when a # is seen inside a recipe line that begins with a <tab> or is inside a group recipe. If you specify the -c command line switch then this behavior is disabled and dmake will treat all # characters as start of comment indicators unless they are escaped by \. A set of continued lines may be commented out by placing a single # at the start of the first line. A continued line cannot span more than one makefile. white space is defined to be any combination of <space>, <tab>, and the sequence \<nl> when \<nl> is used to ter- minate a LINE. When processing macro definition lines, any amount of white space is allowed on either side of the macro operator and white space is stripped from both before and after the macro value string. The sequence \<nl> is treated as white space during recipe expansion and is deleted from the final recipe string. You must escape the \<nl> with another \ in order to get a \ at the end of a recipe line. The \<nl> sequence is deleted from macro values when they are expanded. When processing target definition lines, the recipe for a target must, in general, follow the first definition of the target (See the RULES AND TARGETS section for an exception), and the recipe may not span across multiple makefiles. Any targets and prerequisites found on a target definition line are taken to be white space separated tokens. The rule operator (op in SYNTAX section) is also considered to be a token but does not require white space to precede or follow it. Since the rule operator begins with a `:', traditional versions of make do not allow the `:' character to form a valid target name. dmake allows `:' to be present in target/prerequisite names as long as the entire target/prerequisite name is quoted. For example: a:fred : test would be parsed as TARGET = a, PREREQUISITES={fred, :, Version 3.9 PL0 UW 10 DMAKE(p) Unsupported Free Software DMAKE(p) test}, which is not what was intended. To fix this you must write: "a:fred" : test Which will be parsed as expected. Quoted target and prere- quisite specifications may also contain white space thereby allowing the use of complex function macro expressions.. See the EXAMPLES section for how to apply " quoting to a list of targets. ATTRIBUTES dmake defines several target attributes. Attributes may be assigned to a single target, a group of targets, or to all targets in the makefile. Attributes are used to modify dmake actions during target update. The recognized attri- butes are: .EPILOG Insert shell epilog code when executing a group recipe associated with any target having this attribute set. .FIRST Used in conjunction with .INCLUDE. Terminates the inclusion with the first successfully included prerequisite. .GROUP Force execution of a target's recipe as a group recipe. .IGNORE Ignore an error when trying to make any target with this attribute set. .IGNOREGROUP Disable the special meaning of '[' to initiate a group recipe. .LIBRARY Target is a library. .MKSARGS If running in an MSDOS environment then use MKS extended argument passing conventions to pass arguments to commands. Non-MSDOS environments ignore this attribute. .NOINFER Any target with this attribute set will not be subjected to transitive closure if it is inferred as a prerequisite of a target whose recipe and prerequisites are being inferred. (i.e. the inference algorithm will not use any prerequisite with this attribute set, as a tar- get) If specified as '.NOINFER:' (ie. with no prerequisites or targets) then the effect is Version 3.9 PL0 UW 11 DMAKE(p) Unsupported Free Software DMAKE(p) equivalent to specifying -T on the command line. .NOSTATE Any target with this attribute set will not have command line flag information stored in the state file if .KEEP_STATE has been enabled. .PHONY Any target with this attribute set will have its recipe executed each time the target is made even if a file matching the target name can be located. Any targets that have a .PHONY attri- buted target as a prerequisite will be made each time the .PHONY attributed prerequisite is made. .PRECIOUS Do not remove associated target under any cir- cumstances. Set by default for any targets whose corresponding files exist in the file sys- tem prior to the execution of dmake. .PROLOG Insert shell prolog code when executing a group recipe associated with any target having this attribute set. .SEQUENTIAL Force a sequential make of the associated target's prerequisites. .SETDIR Change current working directory to specified directory when making the associated target. You must specify the directory at the time the attribute is specified. To do this simply give .SETDIR=path as the attribute. path is expanded and the result is used as the value of the directory to change to. If path contains $$@ then the name of the target to be built is used in computing the path to change directory to. If path is surrounded by single quotes then path is not expanded, and is used literally as the directory name. If the path contains any `:' characters then the entire attribute string must be quoted using ". If a target having this attribute set also has the .IGNORE attribute set then if the change to the specified directory fails it will be ignored, and no error message will be issued. .SILENT Do not echo the recipe lines when making any target with this attribute set, and do not issue any warnings. .SWAP Under MSDOS when making a target with this attribute set swap the dmake executable to disk prior to executing the recipe line. Also see the '%' recipe line flag defined in the RECIPES Version 3.9 PL0 UW 12 DMAKE(p) Unsupported Free Software DMAKE(p) section. .SYMBOL Target is a library member and is an entry point into a module in the library. This attribute is used only when searching a library for a target. Targets of the form lib((entry)) have this attribute set automatically. .USESHELL Force each recipe line of a target to be exe- cuted using a shell. Specifying this attribute is equivalent to specifying the '+' character at the start of each line of a non-group recipe. .UPDATEALL Indicates that all the targets listed in this rule are updated by the execution of the accom- panying recipe. A common example is the produc- tion of the y.tab.c and y.tab.h files by yacc when it is run on a grammar. Specifying .UPDATEALL in such a rule prevents the running of yacc twice, once for the y.tab.c file and once for the y.tab.h file. .UPDATEALL targets that are specified in a single rule are treated as a single target and all timestamps are updated whenever any target in the set is made. As a side-effect, dmake internally sorts such targets in ascending alphabetical order and the value of $@ is always the first target in the sorted set. All attributes are user setable and except for .UPDATEALL, .SETDIR and .MKSARGS may be used in one of two forms. The .MKSARGS attribute is restricted to use as a global attri- bute, and the use of the .UPDATEALL and .SETDIR attributes is restricted to rules of the second form only. ATTRIBUTE_LIST : targets assigns the attributes specified by ATTRIBUTE_LIST to each target in targets or targets ATTRIBUTE_LIST : ... assigns the attributes specified by ATTRIBUTE_LIST to each target in targets. In the first form if targets is empty (ie. a NULL list), then the list of attributes will apply to all targets in the makefile (this is equivalent to the com- mon Make construct of ".IGNORE :" but has been modified to the notion of an attribute instead of a special target). Not all of the attributes have global meaning. In particu- lar, .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and .UPDATEALL have no assigned global meaning. Version 3.9 PL0 UW 13 DMAKE(p) Unsupported Free Software DMAKE(p) Any attribute may be used with any target, even with the special targets. Some combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ), while others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain if file.mk cannot be found using the include file search rules, see the section on SPECIAL TARGETS for a description of .INCLUDE). If a specified attribute will not be used with the special target a warning is issued and the attribute is ignored. MACROS dmake supports six forms of macro assignment. MACRO = LINE This is the most common and familiar form of macro assignment. It assigns LINE literally as the value of MACRO. Future expansions of MACRO recursively expand its value. MACRO *= LINE This form behaves exactly as the simple '=' form with the exception that if MACRO already has a value then the assignment is not performed. MACRO := LINE This form differs from the simple '=' form in that it expands LINE prior to assigning it as the value of MACRO. Future expansions of MACRO do not recursively expand its value. MACRO *:= LINE This form behaves exactly as the ':=' form with the exception that if MACRO already has a value then the assignment and expansion are not performed. MACRO += LINE This form of macro assignment allows macro values to grow. It takes the literal value of LINE and appends it to the previous value of MACRO separating the two by a single space. Future expansions of MACRO recur- sively expand its value. MACRO +:= LINE This form is similar to the '+=' form except that the value of LINE is expanded prior to being added to the value of MACRO. Macro expressions specified on the command line allow the macro value to be redefined within the makefile only if the macro is defined using the '+=' and '+:=' operators. Other operators will define a macro that cannot be further modi- fied. Version 3.9 PL0 UW 14 DMAKE(p) Unsupported Free Software DMAKE(p) Each of the preceeding macro assignment operators may be prefixed by ! to indicate that the assignment should be forced and that no warnings should be issued. Thus, speci- fying ! has the effect of silently forcing the specified macro assignment. When dmake defines a non-environment macro it strips leading and trailing white space from the macro value. Macros imported from the environment via either the .IMPORT special target (see the SPECIAL TARGETS section), or the -e, or -E flags are an exception to this rule. Their values are always taken literally and white space is never stripped. In addition, named macros defined using the .IMPORT special target do not have their values expanded when they are used within a makefile. In contrast, environment macros that are imported due to the specification of the -e or -E flags are subject to expansion when used. To specify a macro expansion enclose the name in () or {} and precede it with a dollar sign $. Thus $(TEST) represents an expansion of the macro variable named TEST. If TEST is defined then $(TEST) is replaced by its expanded value. If TEST is not defined then $(TEST) expands to the NULL string (this is equivalent to defining a macro as 'TEST=' ). A short form may be used for single character named macros. In this case the parentheses are optional, and $(I) is equivalent to $I. Macro expansion is recursive, hence, if the value string contains an expression represent- ing a macro expansion, the expansion is performed. Circular macro expansions are detected and cause an error to be issued. When defining a macro the given macro name is first expanded before being used to define the macro. Thus it is possible to define macros whose names depend on values of other mac- ros. For example, suppose CWD is defined as CWD = $(PWD:b) then the value of $(CWD) is the name of the current direc- tory. This can be used to define macros specific to this directory, for example: _$(CWD).prt = list of files to print... The actual name of the defined macro is a function of the current directory. A construct such as this is useful when processing a hierarchy of directories using .SETDIR attri- buted targets and a collection of small distributed makefile stubs. Version 3.9 PL0 UW 15 DMAKE(p) Unsupported Free Software DMAKE(p) Macro variables may be defined within the makefile, on the command line, or imported from the environment. dmake supports several non-standard macro expansions: The first is of the form: $(macro_name:modifier_list:modifier_list:...) where modifier_list is chosen from the set { B or b, D or d, E or e, F or f, I or i, L or l, S or s, T or t, U or u, ^, + } and b - file (not including suffix) portion of path names d - directory portion of all path names e - suffix portion of path names f - file (including suffix) portion of path names i - inferred names of targets l - macro value in lower case s - simple pattern substitution t - tokenization. u - macro value in upper case ^ - prepend a prefix to each token + - append a suffix to each token Thus if we have the example: test = d1/d2/d3/a.out f.out d1/k.out The following macro expansions produce the values on the right of '->' after expansion. $(test:d) -> d1/d2/d3/ d1/ $(test:b) -> a f k $(test:f) -> a.out f.out k.out ${test:db} -> d1/d2/d3/a f d1/k ${test:s/out/in/:f} -> a.in f.in k.in $(test:f:t"+") -> a.out+f.out+k.out $(test:e) -> .out .out .out $(test:u) -> D1/D2/D3/A.OUT F.OUT D1/K.OUT If a token ends in a string composed from the value of the macro DIRBRKSTR (ie. ends in a directory separator string, e.g. '/' in UNIX) and you use the :d modifier then the expansion returns the directory name less the final direc- tory separator string. Thus successive pairs of :d modif- iers each remove a level of directory in the token string. The tokenization modifier takes all white space separated tokens from the macro value and separates them by the quoted separator string. The separator string may contain the fol- lowing escape codes \a => <bel>, \b => <backspace>, \f => <formfeed>, \n => <nl>, \r => <cr>, \t => <tab>, \v => Version 3.9 PL0 UW 16 DMAKE(p) Unsupported Free Software DMAKE(p) <vertical tab>, \" => ", and \xxx => <xxx> where xxx is the octal representation of a character. Thus the expansion: $(test:f:t"+\n") produces: a.out+ f.out+ k.out The prefix operator ^ takes all white space separated tokens from the macro value and prepends string to each. $(test:f:^mydir/) produces: mydir/a.out mydir/f.out mydir/k.out The suffix operator + takes all white space separated tokens from the macro value and appends string to each. $(test:b:+.c) produces: a.c f.c k.c The next non-standard form of macro expansion allows for recursive macros. It is possible to specify a $(macro_name) or ${macro_name} expansion where macro_name contains more $( ... ) or ${ ... } macro expansions itself. For example $(CC$(_HOST)$(_COMPILER)) will first expand CC$(_HOST)$(_COMPILER) to get a result and use that result as the name of the macro to expand. This is useful for writing a makefile for more than one target environment. As an example consider the following hypothetical case. Suppose that _HOST and _COMPILER are imported from the environment and are set to represent the host machine type and the host compiler respectively. CFLAGS_VAX_CC = -c -O # _HOST == "_VAX", _COMPILER == "_CC" CFLAGS_PC_MSC = -c -ML # _HOST == "_PC", _COMPILER == "_MSC" # redefine CFLAGS macro as: CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER)) This causes CFLAGS to take on a value that corresponds to the environment in which the make is being invoked. The final non-standard macro expansion is of the form: string1{token_list}string2 Version 3.9 PL0 UW 17 DMAKE(p) Unsupported Free Software DMAKE(p) where string1, string2 and token_list are expanded. After expansion, string1 is prepended to each token found in token_list and string2 is appended to each resulting token from the previous prepend. string1 and string2 are not del- imited by white space whereas the tokens in token_list are. A null token in the token list is specified using "". Thus using another example we have: test/{f1 f2}.o --> test/f1.o test/f2.o test/ {f1 f2}.o --> test/ f1.o f2.o test/{f1 f2} .o --> test/f1 test/f2 .o test/{"f1" ""}.o --> test/f1.o test/.o and test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o test/d2/f1.o test/d2/f2.o This last expansion is activated only when the first charac- ters of token_list appear immediately after the opening '{' with no intervening white space. The reason for this res- triction is the following incompatibility with Bourne Shell recipes. The line { echo hello;} is valid /bin/sh syntax; while {echo hello;} is not. Hence the latter triggers the enhanced macro expan- sion while the former causes it to be suppressed. See the SPECIAL MACROS section for a description of the special mac- ros that dmake defines and understands. RULES AND TARGETS A makefile contains a series of entries that specify depen- dencies. Such entries are called target/prerequisite or rule definitions. Each rule definition is optionally fol- lowed by a set of lines that provide a recipe for updating any targets defined by the rule. Whenever dmake attempts to bring a target up to date and an explicit recipe is provided with a rule defining the target, that recipe is used to update the target. A rule definition begins with a line having the following syntax: <targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>] targets is a non-empty list of targets. If the target is a special target (see SPECIAL TARGETS section below) then it must appear alone on the rule line. For example: Version 3.9 PL0 UW 18 DMAKE(p) Unsupported Free Software DMAKE(p) .IMPORT .ERROR : ... is not allowed since both .IMPORT and .ERROR are special targets. Special targets are not used in the construction of the dependency graph and will not be made. attributes is a possibly empty list of attributes. Any attribute defined in the ATTRIBUTES section above may be specified. All attributes will be applied to the list of named targets in the rule definition. No other targets will be affected. NOTE: As stated earlier, if both the target list and prerequisite list are empty but the attributes list is not, then the specified attributes affect all targets in the makefile. ruleop is a separator which is used to identify the targets from the prerequisites. Optionally it also provides a facility for modifying the way in which dmake handles the making of the associated targets. In its simplest form the operator is a single ':', and need not be separated by white space from its neighboring tokens. It may additionally be followed by any of the modifiers { !, ^, -, :, | }, where: ! says execute the recipe for the associated targets once for each out of date prerequisite. Ordinarily the recipe is executed once for all out of date prere- quisites at the same time. ^ says to insert the specified prerequisites, if any, before any other prerequisites already associated with the specified targets. In general, it is not useful to specify ^ with an empty list of prerequisites. - says to clear the previous list of prerequisites before adding the new prerequisites. Thus, .SUFFIXES : .SUFFIXES : .a .b can be replaced by .SUFFIXES :- .a .b however the old form still works as expected. NOTE: .SUFFIXES is ignored by dmake it is used here simply as an example. Version 3.9 PL0 UW 19 DMAKE(p) Unsupported Free Software DMAKE(p) : When the rule operator is not modified by a second ':' only one set of rules may be specified for making a target. Multiple definitions may be used to add to the list of prerequisites that a target depends on. How- ever, if a target is multiply defined only one defini- tion may specify a recipe for making the target. When a target's rule operator is modified by a second ':' (:: for example) then this definition may not be the only definition with a recipe for the target. There may be other :: target definition lines that specify a different set of prerequisites with a dif- ferent recipe for updating the target. Any such target is made if any of the definitions find it to be out of date with respect to the related prerequisites and the corresponding recipe is used to update the target. By definition all '::' recipes that are found to be out of date for are executed. In the following simple example, each rule has a `::' ruleop. In such an operator we call the first `:' the operator, and the second `:' the modifier. a.o :: a.c b.h first recipe for making a.o a.o :: a.y b.h second recipe for making a.o If a.o is found to be out of date with respect to a.c then the first recipe is used to make a.o. If it is found out of date with respect to a.y then the second recipe is used. If a.o is out of date with respect to b.h then both recipes are invoked to make a.o. In the last case the order of invocation corresponds to the order in which the rule definitions appear in the makefile. | Is defined only for PERCENT rule target definitions. When specified it indicates that the following con- struct should be parsed using the old semantinc mean- ing: %.o :| %.c %.r %.f ; some rule is equivalent to: %.o : %.c ; some rule %.o : %.r ; some rule %.o : %.f ; some rule Version 3.9 PL0 UW 20 DMAKE(p) Unsupported Free Software DMAKE(p) Targets defined using a single `:' operator with a recipe may be redefined again with a new recipe by using a `:' operator with a `:' modifier. This is equivalent to a tar- get having been initially defined with a rule using a `:' modifier. Once a target is defined using a `:' modifier it may not be defined again with a recipe using only the `:' operator with no `:' modifier. In both cases the use of a `:' modifier creates a new list of prerequisites and makes it the current prerequisite list for the target. The `:' operator with no recipe always modifies the current list of prerequisites. Thus assuming each of the following defini- tions has a recipe attached, then: joe : fred ... (1) joe :: more ... (2) and joe :: fred ... (3) joe :: more ... (4) are legal and mean: add the recipe associated with (2), or (4) to the set of recipes for joe, placing them after exist- ing recipes for making joe. The constructs: joe :: fred ... (5) joe : more ... (6) and joe : fred ... (7) joe : more ... (8) are errors since we have two sets of perfectly good recipes for making the target. prerequisites is a possibly empty list of targets that must be brought up to date before making the current target. recipe is a short form and allows the user to specify short rule definitions on a single line. It is taken to be the first recipe line in a larger recipe if additional lines follow the rule definition. If the semi-colon is present but the recipe line is empty (ie. null string) then it is taken to be an empty rule. Any target so defined causes the Don't know how to make ... error message to be suppressed when dmake tries to make the target and fails. This silence is maintained for rules that are terminated by a semicolon and have no following recipe lines, for targets listed on the command line, for the first target found in the makefile, and for any target having no recipe but containing a list of prerequisites (see the COMPATIBILITY section for Version 3.9 PL0 UW 21 DMAKE(p) Unsupported Free Software DMAKE(p) an exception to this rule if the AUGMAKE (-A) flag was specified. RECIPES The traditional format used by most versions of Make defines the recipe lines as arbitrary strings that may contain macro expansions. They follow a rule definition line and may be spaced apart by comment or blank lines. The list of recipe lines defining the recipe is terminated by a new target definition, a macro definition, or end-of-file. Each recipe line MUST begin with a <TAB> character which may optionally be followed with one or all of the characters '@%+-'. The '-' indicates that non-zero exit values (ie. errors) are to be ignored when this recipe line is executed, the '+' indi- cates that the current recipe line is to be executed using the shell, the '%' indicates that dmake should swap itself out to secondary storage (MSDOS only) before running the recipe and the '@' indicates that the recipe line should NOT be echoed to the terminal prior to being executed. Each switch is off by default (ie. by default, errors are signi- ficant, commands are echoed, no swapping is done and a shell is used only if the recipe line contains a character found in the value of the SHELLMETAS macro). Global settings activated via command line options or special attribute or target names may also affect these settings. An example recipe: target : first recipe line second recipe line, executed independently of the first. @a recipe line that is not echoed -and one that has errors ignored %and one that causes dmake to swap out +and one that is executed using a shell. The second and new format of the recipe block begins the block with the character '[' (the open group character) in the last non-white space position of a line, and terminates the block with the character ']' (the close group character) in the first non-white space position of a line. In this form each recipe line need not have a leading TAB. This is called a recipe group. Groups so defined are fed intact as a single unit to a shell for execution whenever the corresponding target needs to be updated. If the open group character '[' is preceded by one or all of -, @ or % then they apply to the entire group in the same way that they apply to single recipe lines. You may also specify '+' but it is redundant as a shell is already being used to run the recipe. See the MAKING TARGETS section for a description of how dmake invokes recipes. Here is an example of a group recipe: Version 3.9 PL0 UW 22 DMAKE(p) Unsupported Free Software DMAKE(p) target : [ first recipe line second recipe line all of these recipe lines are fed to a single copy of a shell for execution. ] TEXT DIVERSIONS dmake supports the notion of text diversions. If a recipe line contains the macro expression $(mktmp[,[file][,text]] data) then all text contained in the data expression is expanded and is written to a temporary file. The return value of the macro is the name of the temporary file. data can be any text and must be separated from the 'mktmp' portion of the macro name by white-space. The only restric- tion on the data text is that it must contain a balanced number of parentheses of the same kind as are used to ini- tiate the $(mktmp ...) expression. For example: $(mktmp $(XXX)) is legal and works as expected, but: $(mktmp text (to dump to file) is not legal. You can achieve what you wish by either defining a macro that expands to '(' or by using {} in the macro expression; like this: ${mktmp text (to dump to file} Since the temporary file is opened when the macro containing the text diversion expression is expanded, diversions may be nested and any diversions that are created as part of ':=' macro expansions persist for the duration of the dmake run. The diversion text may contain the same escape codes as those described in the MACROS section. Thus if the data text is to contain new lines they must be inserted using the \n escape sequence. For example the expression: all: cat $(mktmp this is a\n\ test of the text diversion\n) is replaced by: Version 3.9 PL0 UW 23 DMAKE(p) Unsupported Free Software DMAKE(p) cat /tmp/mk12294AA where the temporary file contains two lines both of which are terminated by a new-line. If the data text spans multi- ple lines in the makefile then each line must be continued via the use of a \. A second more illustrative example gen- erates a response file to an MSDOS link command: OBJ = fred.obj mary.obj joe.obj all : $(OBJ) link @$(mktmp $(^:t"+\n")\n) The result of making `all' in the second example is the com- mand: link @/tmp/mk02394AA where the temporary file contains: fred.obj+ mary.obj+ joe.obj The last line of the file is terminated by a new-line which is inserted due to the \n found at the end of the data string. If the optional file 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: $(mktmp,$(TMPFILE) data) is completely equivalent to not specifying the $(TMPFILE) optional argument. Another example that would be useful for MSDOS users with a Turbo-C compiler $(mktmp,turboc.cfg $(CFLAGS)) will place the contents of CFLAGS into a local turboc.cfg file. The second optional argument, text, if present alters the name of the value returned by the $(mktmp ...) macro. Under MS-DOS text diversions may be a problem. Many DOS tools require that path names which contain directories use the \ character to delimit the directories. Some users how- ever 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 dmake startup files define the macro Version 3.9 PL0 UW 24 DMAKE(p) Unsupported Free Software DMAKE(p) 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. Previous versions of dmake defined text diversions using <+, +> strings, where <+ started a text diversion and +> ter- minated one. dmake is backward compatible with this con- struct only if the <+ and +> appear literally on the same recipe line or in the same macro value string. In such instances the expression: <+data+> is mapped to: $(mktmp data) which is fully output compatible with the earlier construct. <+, +> constructs whose text spans multiple lines must be converted by hand to use $(mktmp ...). If the environment variable TMPDIR is defined then the tem- porary 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. SPECIAL TARGETS This section describes the special targets that are recog- nized by dmake. Some are affected by attributes and others are not. .ERROR If defined then the recipe associated with this target is executed whenever an error con- dition is detected by dmake. 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. .EXIT If this target is encountered while parsing a makefile then the parsing of the makefile is immediately terminated at that point. .EXPORT 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 Version 3.9 PL0 UW 25 DMAKE(p) Unsupported Free Software DMAKE(p) 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 .IMPORT 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 .EVERY- THING is used as a prerequisite name then all environment variables defined in the environ- ment are imported. The functionality of the -E flag can be forced by placing the construct .IMPORT : .EVERYTHING at the start of a makefile. Similarly, by placing the construct at the end, one can emulate the effect of the -e 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 dmake to ignore the above error. See the MAC- ROS section for a description of the process- ing of imported macro values. .INCLUDE 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 try- ing 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 as prerequisites of 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 start- ing 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 dmake continues processing, otherwise an error message is generated. The .SETDIR attribute Version 3.9 PL0 UW 26 DMAKE(p) Unsupported Free Software DMAKE(p) causes dmake to change directories to the specified directory prior to attempting the include operation. If all fails dmake attempts to make the file to be included. If making the file fails then dmake terminates unless the .INCLUDE directive also specified the .IGNORE attribute. If .FIRST is specified along with .INCLUDE then dmake attempts to include each named prerequisite and will ter- minate the inclusion with the first prere- quisite that results in a successful inclu- sion. .INCLUDEDIRS The list of prerequisites specified for this target defines the set of directories to search when trying to include a makefile. .KEEP_STATE This special target is a synonym for the macro definition .KEEP_STATE := _state.mk It's effect is to turn on STATE keeping and to define _state.mk as the state file. .MAKEFILES The list of prerequisites is the set of files to try to read as the default makefile. By default this target is defined as: .MAKEFILES : makefile.mk Makefile makefile .SOURCE 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. .SOURCE.suff The same as .SOURCE, except that the .SOURCE.suff list is searched first when try- ing to locate a file matching the a target whose name ends in the suffix .suff. .REMOVE The recipe of this target is used whenever dmake needs to remove intermediate targets that were made but do not need to be kept around. Such targets result from the applica- tion of transitive closure on the dependency graph. In addition to the special targets above, several other forms of targets are recognized and are considered special, Version 3.9 PL0 UW 27 DMAKE(p) Unsupported Free Software DMAKE(p) their exact form and use is defined in the sections that follow. SPECIAL MACROS 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 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 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. 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. 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. INCDEPTH 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. MFLAGS 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. MAKECMD Is the name with which dmake was invoked. MAKEDIR Is the full path to the initial directory in which dmake was invoked. MAKEFILE Contains the string "-f makefile" where, makefile is the name of initial user makefile that was first read. MAKEFLAGS Is the same as $(MFLAGS) but has no leading switch character. (ie. MFLAGS = -$(MAKEFLAGS)) MAKEMACROS Contains the complete list of macro expres- sions that were specified on the command Version 3.9 PL0 UW 28 DMAKE(p) Unsupported Free Software DMAKE(p)