summaryrefslogtreecommitdiff
path: root/dmake/man/dmake.nc
diff options
context:
space:
mode:
Diffstat (limited to 'dmake/man/dmake.nc')
-rw-r--r--dmake/man/dmake.nc3644
1 files changed, 0 insertions, 3644 deletions
diff --git a/dmake/man/dmake.nc b/dmake/man/dmake.nc
deleted file mode 100644
index 8b308f75ff26..000000000000
--- a/dmake/man/dmake.nc
+++ /dev/null
@@ -1,3644 +0,0 @@
-
-
-
-DMAKE(1) DMAKE(1)
-
-
-NAME
- dmake - maintain program groups, or interdependent files
-
-SYNOPSIS
- dmake [-P#] [-{f|C|K} file] [-{w|W} target ...]
- [macro[[!][*][+][:]]=value ...] [-ABcdeEghiknpqrsStTuVxX]
- [-v[cdfimrtw]] [-m[trae]] [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 prerequisite targets. If any of the target's prerequi-
- sites 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 spe-
- cial 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 definitions found inside the makefile to redefine a
- macro defined on the command line, see the MACROS section for excep-
- tions.
-
- 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 tar-
- get. 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 COMPATIBILITY
- 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" and "AUGMAKE META RULES" sections), 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 special macro and is
- further described below.
-
- -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 stan-
- dard error from any child processes and from the dmake process
-
-
-
-Dmake Version 4.12 2008-02-26 1
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 versions of dmake.
-
- -d Disable the use of the directory cache. Normally dmake caches
- directories as it checks file timestamps. Giving 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 defi-
- nitions in the makefile to override definitions in the environ-
- ment.
-
- -e Same as -E, except that the environment is processed after the
- user specified makefile has been processed (thus definitions in
- the environment override definitions in the makefile). The -e
- and -E options are mutually exclusive. If both are given the
- latter takes effect.
-
- -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.
-
- -k Causes dmake to ignore errors caused by command execution 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 con-
- tinue to make as much as possible.
-
- -m[trae]
- Measure timing information. Print the time when targets and/or
- recipes are started and finished to stdout. The following format
- is used:
-
- {s|e} {target|recipe} time maketarget
-
- s or e stands for started or ended, target or recipe denotes if
- this line refers to the whole target or a recipe. time is
-
-
-
-Dmake Version 4.12 2008-02-26 2
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- displayed in Unix time format, i.e. the number of seconds since
- an epoch. (Since 1970-01-01T00:00:00Z). maketarget obviously
- represents the target the timing information is given for. The
- optional flags [trae] can be used to change the information that
- is displayed. If no optional flags are given only the t flag is
- assumed to be selected, ie. -mt. The optional flags stand for:
-
- t Display the start and end time of each target.
-
- r Display the start and end time of each recipe.
-
- a Display the target as an absolute path, i.e. prepend the
- current working directory.
-
- e Also display the start and end time of the $(shell com-
- mand) function (aka. shell escape) macros.
-
- -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 it is found, the
- line is expanded and invoked, thereby enabling recursive makes
- to give a full description of all that they will do. This check
- 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 PRO-
- CESSING" 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 com-
- mands it is executing to stdout (also suppresses warnings).
- This is equivalent to the .SILENT attribute or macro.
-
- -S Force sequential execution of recipes on architectures which
- support concurrent makes. For backward compatibility with old
- makefiles that have nasty side-effect prerequisite dependencies.
- (Implies -P1)
-
- -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)
-
-
-
-Dmake Version 4.12 2008-02-26 3
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- -v[cdfimrtw]
- Verbose flag, when making targets print to stdout what we are
- going to make and what we think its time stamp is. The optional
- flags [cdfimrtw] 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 -vcdfimrtw). The meanings
- of the optional flags are:
-
- c Notify of directory cache operations only.
-
- 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.
-
- r Force output of recipe lines, warnings and executed com-
- mands. This switch is useful when debugging makefiles
- that disable the output using the @ or @@ property for
- recipe lines or the .SILENT target/attribute. It also
- overrides the -s flag.
-
- t Keep any temporary files created; normally they are auto-
- matically deleted.
-
- w Notify of non-essential warnings (these are historical).
-
- -V Print the version of dmake, and values of builtin macros.
-
- -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 func-
- tion as expected.
-
- -X Inhibit the execution of #! lines found at the beginning 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 expressions.
-
-
-
-
-Dmake Version 4.12 2008-02-26 4
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- ATTRIBUTES Describes the notion of attributes and how they are
- used when making targets.
-
- MACROS Defining and expanding macros.
-
- RULES AND TARGETS How to define targets and their prerequisites.
-
- RECIPES How to tell dmake how to make a target.
-
- BUILTIN COMMANDS Internal dmake commands.
-
- TEXT DIVERSIONS How to use text diversions in recipes and macro
- expansions.
-
- VIRTUAL TARGETS Targets that only enforce dependencies, but which
- can not create a target file.
-
- SPECIAL TARGETS Some targets are special.
-
- SPECIAL MACROS Macros used by dmake to alter the processing of the
- makefile, and those defined by dmake for the user.
-
- CONTROL MACROS Itemized list of special control macros.
-
- RUNTIME MACROS Discussion of special run-time macros such as $@ and
- $<.
-
- FUNCTION MACROS Description of functional macros.
-
- 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 target to an
- existing file in the file system.
-
- 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 explicit recipe. This and the
- previous section are really a single section in the
- text.
-
- AUGMAKE META RULES A subclass of the PERCENT(%) RULES.
-
- 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.
-
-
-
-Dmake Version 4.12 2008-02-26 5
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 supplied makefile. The startup
- file defines the default values of all required control macros and the
- set of default rules for making targets and inferences. When searching
- for the startup makefile, 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 MAKESTARTUP
- defined on the command line.
-
- 2. The location given as the value of the environment vari-
- able MAKESTARTUP defined in the current environment.
-
- 3. The location given as the value of the macro MAKESTARTUP
- defined internally within dmake. In this version, the
- internal definition of MAKESTARTUP is "$(DMAKE-
- ROOT)/startup.mk", so you can set the environment vari-
- able DMAKEROOT to the location of your startup directory.
-
- If DMAKEROOT is not changed, for native Windows dmake
- versions its value defaults to "$(ABSMAKECMD:d)startup"
- (see definition of ABSMAKECMD for details). For unix
- like versions build with the autotools build system it
- defaults to the value of "${prefix}/share/startup" at
- build time. The actual value, usually something like
- /usr/local/share/startup can be checked with the -V com-
- mand line switch.
-
- The above search is disabled by specifying the -r option on the command
- line. An error is issued if a startup makefile cannot be found and the
- -r option was not specified. A user may substitute a custom startup
- file by defining the MAKESTARTUP environment variable or by redefining
- the MAKESTARTUP macro on the command line. To determine where dmake
- looks for the default startup file, check your environment or issue the
-
-
-
-Dmake Version 4.12 2008-02-26 6
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 .MAKEFILES specifies the names of possible make-
- files 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 pre-
- requisite 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 addi-
- tional 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 speci-
- fied makefile. The graph is rooted at the special target .ROOT. .ROOT
- is the top level target that dmake builds when it starts to build tar-
- gets. 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 .PHONY:;
-
- which nicely emulates the behaviour of Sun's make extensions. The
- building of .ROOT's prerequisites is always forced to be sequential.
- However, this definition is trivially changed by supplying the defini-
- tion:
-
- .ROOT : .TARGETS
-
- which skips the preamble and postamble phases of building .TARGETS.
-
- Please note that even though .INIT and .DONE are special exceptions,
- see section SPECIAL TARGETS, the use of self defined targets starting
- with `.' should be avoided as they would be handled as .<suffix> meta
- targets. The target names _INIT and _DONE for example would work
- equally well without the .<suffix> drawback.
-
-
-
-Dmake Version 4.12 2008-02-26 7
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
-SYNTAX
- This section is a summary of the syntax of makefile statements. The
- description is given in a style similar to BNF, where { } enclose items
- that may appear zero or more times, and [ ] enclose items that are
- optional. Alternative productions for a left hand side are indicated
- by '->', and newlines are significant. All symbols in 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
- -> expression == expression
- -> expression != expression
- -> expression <= expression
- -> expression >= expression
- -> ( expression )
- -> expression || expression
- -> expression && expression
-
-
- Rule-Definition -> target-definition
- [ recipe ]
-
- target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line]
-
-
-
-Dmake Version 4.12 2008-02-26 8
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- targets -> target { targets }
- -> "target" { targets }
-
-
- target -> special-target
- -> TARGET
-
-
- attrs -> attribute { attrs }
- -> "attribute" { attrs }
-
-
- op -> : { modifier }
-
-
- modifier -> :
- -> ^
- -> !
- -> -
- -> |
-
-
- recipe -> { TAB rcp-line }
- -> [@[@]][%][-] [
- { LINE }
- ]
-
-
- rcp-line -> [@[@]][%][-][+] LINE
-
-
- Attribute-Definition -> attrs : targets
-
-
- attribute -> .EPILOG
- -> .ERRREMOVE
- -> .EXECUTE
- -> .GROUP
- -> .IGNORE
- -> .IGNOREGROUP
- -> .LIBRARY
- -> .MKSARGS
- -> .NOINFER
- -> .NOSTATE
- -> .PHONY
- -> .PRECIOUS
- -> .PROLOG
- -> .SETDIR=path
- -> .SILENT
- -> .SEQUENTIAL
- -> .SWAP
- -> .USESHELL
- -> .SYMBOL
- -> .UPDATEALL
- -> .WINPATH
-
-
-
-
-Dmake Version 4.12 2008-02-26 9
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- special-target -> .ERROR
- -> .EXIT
- -> .EXPORT
- -> .GROUPEPILOG
- -> .GROUPPROLOG
- -> .IMPORT
- -> .INCLUDE
- -> .INCLUDEDIRS
- -> .MAKEFILES
- -> .REMOVE
- -> .ROOT
- -> .SOURCE
- -> .SOURCE.suffix
- -> .SUFFIXES (deprecated)
- -> .TARGETS
- -> .INIT
- -> .DONE
- -> .suffix
- -> .suffix1.suffix2
-
-
- 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 expression. A LINE can be contin-
- ued over several physical lines by terminating it with a single back-
- slash character. Comments 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. \# trans-
- lates 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 terminate a LINE. Note the special
- treatment of \<nl> in macro definion and recipe lines below. When pro-
- cessing 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. A \<nl> sequence in a macro
- definition is deleted from the macro value before assigning this value.
- During recipe expansion the sequence \<nl> is treated as white space
- but 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 or macro def-
- inition line.
-
- 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
-
-
-
-Dmake Version 4.12 2008-02-26 10
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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, :, 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 prerequisite spec-
- ifications 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 attributes are:
-
-
- .EPILOG Insert shell epilog code when executing a group recipe
- associated with any target having this attribute set.
-
- .ERRREMOVE Always remove any target having this attribute if an error
- is encountered while making them. Setting this attribute
- overrides the .PRECIOUS attribute.
-
- .EXECUTE If the -n flag was given then execute the recipe associated
- with any target having this attribute set.
-
- .FIRST Used in conjunction with .INCLUDE. Terminates the inclu-
- sion 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
-
-
-
-Dmake Version 4.12 2008-02-26 11
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- target whose recipe and prerequisites are being inferred.
- (i.e. the inference algorithm will not use any prerequisite
- with this attribute set, as a target) If specified as
- '.NOINFER:' (ie. with no prerequisites or targets) then the
- effect is equivalent to specifying -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 match-
- ing the target name can be located. Any targets that have
- a .PHONY attributed target as a prerequisite will be made
- each time the .PHONY attributed prerequisite is made.
-
- .PRECIOUS Do not remove associated target under any circumstances.
- Set by default for any targets whose corresponding files
- exist in the file system prior to the execution of 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 prereq-
- uisites. If set as a global attribute this implies setting
- MAXPROCESS=1.
-
- .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 direc-
- tory 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 `:' charac-
- ters 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 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 executed using a
- shell. Specifying this attribute is equivalent to
-
-
-
-Dmake Version 4.12 2008-02-26 12
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 accompanying recipe. A
- common example is the production 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.
-
- .WINPATH Switch between default (POSIX) and Windows style path rep-
- resentation. (This attribute is specific for cygwin dmake
- executables and non-cygwin environments ignore this
- attribute.)
-
- Under Cygwin it can be useful to generate Windows style
- paths (with regular slashes) instead of the default cygwin
- style (POSIX) paths for dmake's dynamic macros. The
- affected macros are $@, $*, $>, $?, $<, $&, $^ and
- $(MAKEDIR), $(PWD), $(TMD), $(TMPFILE) and the $(mktmp ...)
- function macro. This feature can be used to create DOS
- style path parameters for native W32 programs from dynamic
- macros.
-
- Note that the Windows style paths use regular slashes ('/')
- instead of the usual Windows backslash ('\') as directory
- separator to avoid quoting problems (after all it is still
- a cygwin dmake!) and cygwin, as well as native Windows,
- programs should have no problems using this (c:/foo/bar)
- path representation.
-
- Example: Assuming the current target to be /tmp/mytarget
- the $@ macro without .WINPATH active expands to:
-
- /tmp/mytarget
-
- With .WINPATH set it expands to:
-
- C:/cygwin/tmp/mytarget
-
- All attributes are user setable and except for .UPDATEALL and .MKSARGS
- may be used in one of two forms. The .MKSARGS attribute is restricted
- to use as a global attribute, and the use of the .UPDATEALL attribute
- 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 : ...
-
-
-
-
-Dmake Version 4.12 2008-02-26 13
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 common 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 particular,
- .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and .UPDATEALL have no
- assigned global meaning.
-
- Any attribute may be used with any target, even with the special tar-
- gets. 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 recursively
- 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 modified.
-
- 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, specifying ! has the effect of silently forc-
- ing the specified macro assignment.
-
-
-
-Dmake Version 4.12 2008-02-26 14
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- When dmake defines a non-environment macro it strips leading and trail-
- ing white space from the macro value. Macros imported from the envi-
- ronment 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 specifica-
- tion 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 expres-
- sion representing a macro expansion, the expansion is performed. Cir-
- cular 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 macros. For example, suppose CWD
- is defined as
-
- CWD = $(PWD:b)
-
- then the value of $(CWD) is the name of the current directory. This
- can be used to define macros specific to this directory, for example:
-
- _$(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 hier-
- archy of directories using .SETDIR attributed targets and a collection
- of small distributed makefile stubs.
-
- 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 may be a combination of:
-
- b or B - file (not including suffix) portion of path names
- d or D - directory portion of all path names
- e or E - suffix portion of path names
- f or F - file (including suffix) portion of path names
- i or I - inferred names of targets
- n or N - normalized path names
- l or L - macro value in lower case
- u or U - macro value in upper case
- 1 - return the first white space separated token from value
-
-
-
-
-Dmake Version 4.12 2008-02-26 15
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- or a single one of:
-
- m or M - map escape codes found in macro to their ASCII value
- s or S - simple pattern substitution
- t or T - tokenization.
- ^ - 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
- $(test:1) -> d1/d2/d3/a.out
-
- For this macro
- test = d1/d2/../a.out "d1/file name.ext"
- the following results are returned:
-
- $(test:n) -> d1/a.out "d1/file name.ext"
-
- 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 directory separator string. Thus successive pairs
- of :d modifiers each remove a level of directory in the token string.
-
- The infered names of targets :i modifier returnes the actual filename
- associated to the target, see BINDING TARGETS. If the value is not a
- target or prerequisite the value is returned unchanged. For the follow-
- ing example:
- test = aprog bprog
- If aprog and bprog are targets or prerequisits and they are bound to
- /tmp/aprog and bprog (see .SOURCE special target) the macro expansion
- has the following effect:
-
- $(test:i) -> /tmp/aprog bprog
-
- The normalized path names :n modifier honors the setting of .WINPATH to
- determine the output format of the result.
-
- The map escape codes modifier changes the following escape codes \a =>
- <bel>, \b => <backspace>, \f => <formfeed>, \n => <nl>, \r => <cr>, \t
- => <tab>, \v => <vertical tab>, \" => ", and \xxx => <xxx> where xxx is
- the octal representation of a character into the corresponding ASCII
- value.
-
- The tokenization, prepend and append modifier may use the same escape
- codes that are supported by the map escape codes modifier in the string
- that is inserted, prepended or added by the respective macro modifier.
-
-
-
-Dmake Version 4.12 2008-02-26 16
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- These modifiers may quote this string to include otherwise problematic
- characters. E.g. spaces, colons and parentheses.
-
- The tokenization modifier takes all white space separated tokens from
- the macro value and separates them by the separator string. 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 environ-
- ment in which the make is being invoked.
-
- The final non-standard macro expansion is of the form:
-
- string1{token_list}string2
-
- where string1, string2 and token_list are expanded. After expansion,
- string1 is prepended to each token found in token_list and string2 is
- appended to each resulting token from the previous prepend. string1
- and string2 are not delimited by white space whereas the tokens in
-
-
-
-Dmake Version 4.12 2008-02-26 17
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 characters of
- token_list appear immediately after the opening '{' with no intervening
- white space. The reason for this restriction is the following incom-
- patibility 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 expansion while
- the former causes it to be suppressed. See the SPECIAL MACROS section
- for a description of the special macros that dmake defines and under-
- stands.
-
-RULES AND TARGETS
- A makefile contains a series of entries that specify dependencies.
- Such entries are called target/prerequisite or rule definitions. Each
- rule definition is optionally followed by a set of lines that provide a
- recipe for updating any targets defined by the rule. Whenever dmake
- attempts to bring a target up to date and an explicit recipe is pro-
- vided 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:
-
- .IMPORT .ERROR : ...
-
- is not allowed since both .IMPORT and .ERROR are special targets. Spe-
- cial 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
-
-
-
-Dmake Version 4.12 2008-02-26 18
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 sep-
- arated 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. (The meaning of the runtime macro $?
- is changed, see below in the RUNTIME MACROS section.) Ordinarily
- the recipe is executed once for all out of date prerequisites at
- the same time.
-
- ^ says to insert the specified prerequisites, if any, before any
- other prerequisites already associated with the specified tar-
- gets. 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,
-
- foo :
- foo : bar baz
-
- can be replaced by
-
- foo :- bar baz
-
- however the old form still works as expected.
-
- : When the rule operator is not modified by a second ':' only one
- set of rules may be specified for making a target. Multiple
- definitions may be used to add to the list of prerequisites that
- a target depends on. However, if a target is multiply defined
- only one definition may specify a recipe for making the target.
-
- 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 def-
- inition lines that specify a different set of prerequisites with
- a different recipe for updating the target. Any such target is
- made if any of the definitions find it to be out of date with
- respect to the related prerequisites and the corresponding
- recipe is used to update the target. 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
-
-
-
-Dmake Version 4.12 2008-02-26 19
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 make-
- file.
-
- | Is defined only for PERCENT rule target definitions. When spec-
- ified it indicates that the following construct should be parsed
- using the old semantinc meaning:
-
- %.o :| %.c %.r %.f ; some rule
-
- is equivalent to:
-
- %.o : %.c ; some rule
- %.o : %.r ; some rule
- %.o : %.f ; some rule
-
- Targets defined using a single `:' operator with a recipe may be rede-
- fined again with a new recipe by using a `:' operator with a `:' modi-
- fier. This is equivalent to a target having been initially defined
- with a rule using a `:' modifier. Once a target is defined using a `:'
- modifier it may not be defined again with a recipe using only the `:'
- operator with no `:' modifier. In both cases the use of a `:' modifier
- creates a new list of prerequisites and makes it the current prerequi-
- site list for the target. The `:' operator with no recipe always modi-
- fies the current list of prerequisites. Thus assuming each of the fol-
- lowing definitions 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 existing 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 defi-
- nitions on a single line. It is taken to be the first recipe line in a
-
-
-
-Dmake Version 4.12 2008-02-26 20
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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
- target to be treated as a virtual target, see VIRTUAL TARGETS below.
-
-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 termi-
- nated by a new target definition, a macro definition, or end-of-file.
- Each recipe line MUST begin with a <TAB> character (or spaces, see
- .NOTABS) which may optionally be followed with one or all the following
- recipe property characters '@%+-' which affect the recipe execution:
-
- '-' indicates that non-zero exit values (ie. errors) are to be
- ignored when this recipe line is executed.
-
- '+' indicates that the current recipe line is to be executed using
- the shell. Group recipes implicitely ignore this property.
-
- '%' indicates that dmake should swap itself out to secondary storage
- (MSDOS only) before running the recipe.
-
- '@' indicates that the recipe line should NOT be echoed to the ter-
- minal prior to being executed.
-
- '@@' is a stronger version of the previous property. The recipe line
- and the output (stdout and stderr) of the executed recipe are
- NOT shown on the terminal.
-
- Each property is off by default (ie. by default, errors are signifi-
- cant, 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 independent of 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 the recipe properties (-, %, @ and @@) 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
-
-
-
-Dmake Version 4.12 2008-02-26 21
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- group recipe:
-
- target :
- [
- first recipe line
- second recipe line
- tall of these recipe lines are fed to a
- single copy of a shell for execution.
- ]
-
-
-BUILTIN COMMANDS
- dmake supports some builtin commands. An optional leading '+' describes
- that the builtin can be used also when being executed in a shell other-
- wise it is only implemented when used directly. Remember that if a
- character of the recipe is found in the SHELLMETAS macro the execution
- of the recipe in a shell is forced.
-
- [+]noop [something]
- The noop internal command always returns success if used but it
- is not executed even though the rest of the commandline is eval-
- uated. This command can be used to evaluate macro expansions at
- the runtime of the recipe without starting a real commmand.
-
- [+]<empty recipe>
- If an empty recipe line is encountered it is not executed. This
- sounds more trivial than it really is because the recipe could
- consist of macros that evaluated to empty or whitespace only
- strings.
-
- echo [-n] data
- This internal command prints data (with all leading whitespace
- removed, but otherwise literally) to stdout. If the '-n' switch
- is given no trailing newline is printed. Note that no quoting is
- removed nor that escape sequences are handled.
-
- No special treatment of buildin commands for group recipes is imple-
- mented even though the <empty recipe> will most propably also not be
- evaluated by most shells that can be used to handle the recipe groups.
-
-TEXT DIVERSIONS
- dmake supports the notion of text diversions. If a recipe line con-
- tains the macro expression
-
- $(mktmp[,[file][,text]] data)
-
- then all text contained in the data expression is expanded and is writ-
- ten to a temporary file. The data in the file will always be termi-
- nated from a new line character. The file parameter can be used to
- override the name of the temporary file. If its expanded value is not
- empty it will be used instead of the unique and thread safe file name
- that otherwise would be generated internally. The return value of the
- macro is the name of the temporary file unless the text parameter is
- defined. In this case the return value is the expanded value of text.
-
- data can be any text and must be separated from the 'mktmp' portion of
- the macro name by white-space. The only restriction on the data text
- is that it must contain a balanced number of parentheses of the same
- kind as are used to initiate the $(mktmp ...) expression. For example:
-
-
-
-Dmake Version 4.12 2008-02-26 22
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- $(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. If the data text is to contain new
- lines the map escape codes macro expasion can be used. For example the
- expression:
-
- mytext:=this is a\ntest of the text diversion
- all:
- cat $(mktmp $(mytext:m))
-
- is replaced by:
-
- cat /tmp/mk12294AA
-
- where the temporary file contains two lines both of which are termi-
- nated by a new-line. A second more illustrative example generates a
- response file to an MSDOS link command:
-
- OBJ = fred.obj mary.obj joe.obj
- all : $(OBJ)
- link @$(mktmp $(^:t"+\n"))
-
- The result of making `all' in the second example is the command:
-
- 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 always
- inserted at the end of the data string.
-
- If the optional file specifier is present it can be used to specify the
- name of the temporary file to create. An 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
-
-
-
-Dmake Version 4.12 2008-02-26 23
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- delimit the directories. Some users however wish to use the '/' to
- delimit pathnames and use environments that allow them to do so. The
- macro USESHELL is set to "yes" if the current recipe is forced to use a
- shell via the .USESHELL or '+' directives, otherwise its value is "no".
- The dmake startup files define the macro DIVFILE whose value is either
- the value of TMPFILE or the value of TMPFILE edited to replace any '/'
- characters to the appropriate value based on the current shell and
- whether it will be used to execute the recipe.
-
- Previous versions of dmake defined text diversions using <+, +>
- strings, where <+ started a text diversion and +> terminated one.
- dmake is backward compatible with this construct 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 temporary file
- is placed into the directory specified by that variable. A makefile
- can modify the location of temporary files by defining a macro named
- TMPDIR and exporting it using the .EXPORT special target.
-
-VIRTUAL TARGETS
- Dmake allows to define targets with the sole purpose to enforce a
- dependency chain that are unable to create the target, hence virtual
- targets. When dmake tries to make a target, but only finds a target
- definition without recipe lines, it would normally issues a "Don't know
- how to make ..." error message, but if a target rule is terminated by a
- semicolon and has no following recipe lines, or if it has no recipe
- lines, but defines prerequisites, or if the AUGMAKE mode is enabled
- (see the COMPATIBILITY section for details), the target is treated as a
- virtual target and the error is suppressed. In addition to this, if the
- default target does not have recipe lines it is also treated as a vir-
- tual target.
-
- Virtual targets should not have a corresponding file therefore they
- inherit the time of their newest prerequisite if they have prerequi-
- sites, otherwise they get the current time assigned when being made.
- If the virtual target has a corresponding file a warning is issued, but
- the time stamp of that file is taken into account. The virtual target
- uses the time stamp of the corresponding file if it is newer than the
- one determined by the previous rule.
-
-SPECIAL TARGETS
- This section describes the special targets that are recognized 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 condition is detected by
- dmake. All attributes that can be used with any other
- target may be used with this target. Any prerequisites
-
-
-
-Dmake Version 4.12 2008-02-26 24
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- of this target will be brought up to date during its pro-
- cessing. 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 termi-
- nated 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 appears.
- Any attributes specified with this target are ignored.
- Only macros which have been assigned a value in the make-
- file prior to the export directive are exported, macros
- as yet undefined or macros whose value contains any of
- the characters "+=:*" are not exported.
-
- Note that macros that are not expanded during the macro
- assignment and contain other macros will be written into
- the environment containing these other macros in the form
- of $(macroname).
-
- .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
- .EVERYTHING is used as a prerequisite name then all envi-
- ronment variables defined in the environment 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 MACROS section for a
- description of the processing 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 trying to locate the file. If
- the filename is surrounded by " or just by itself then it
- is searched for in the current directory. If it is not
- found it is then searched for in each of the directories
- specified 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
- starting at the root of the file system then it is only
- searched for once, and the .INCLUDEDIRS list is ignored.
- If .INCLUDE fails to find the file it invokes the infer-
- ence engine to try to infer and hence make the file to be
- included. In this way the file can be checked out of an
- RCS repository for example. .INCLUDE accepts the
- .IGNORE, .SETDIR, and .NOINFER attributes. If the
-
-
-
-Dmake Version 4.12 2008-02-26 25
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- .IGNORE attribute is given and the file cannot be found
- then dmake continues processing, otherwise an error mes-
- sage is generated. If the .NOINFER attribute is given
- and the file cannot be found then dmake will not attempt
- to infer and make the file. The .SETDIR attribute 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 mak-
- ing 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 prerequisite that
- results in a successful inclusion.
-
- .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
-
-
- .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
- application of transitive closure on the dependency
- graph.
-
- .ROOT The internal root of the dependency graph, see section
- STARTUP for details.
-
- .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 trying to locate a file matching the
- a target whose name ends in the suffix .suff.
-
- .SUFFIXES This deprecated special target has no special meaning.
- Avoid its use.
-
- .TARGETS The internal targets that all user defined targets are
- prerequisites of, see section STARTUP for details.
-
- There are a few targets that are "slightly" special:
-
-
-
-
-Dmake Version 4.12 2008-02-26 26
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- .INIT
- .DONE
-
- These targets exist because of historical reasons, see the usage of
- .INIT and .DONE in section "STARTUP", they can be used and defined as
- ordinary targets but are special in the sense that even though they
- start with a `.' they are not treated as a .<suffix> meta target (See
- the AUGMAKE META RULES section for details).
-
- Please note that self defined targets shouldn't use the prefix `.' as
- they would be handled as .<suffix> meta targets and dmake most propably
- would complain about this.
-
- In addition to the special targets above, several other forms of tar-
- gets are recognized and are considered special, 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.
-
- ABSMAKECMD Warning! This macro's value is differently defined for
- a native Windows dmake executable (compiled with MS
- Visual C++ or MinGW) and dmake for other operating sys-
- tems or build with other compilers.
-
- In the first case its value is the absolute filename of
- the executable of the current dmake process, otherwise
- it is defined as the NULL string.
-
- 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.
-
-
-
-Dmake Version 4.12 2008-02-26 27
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- 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 expressions that
- were specified on the command line.
-
- MAKETARGETS Contains the name(s) of the target(s), if any, that
- were specified on the command line.
-
- MAKEVERSION Contains a string indicating the current dmake version
- number.
-
- MAXPROCESSLIMIT Is a numeric string representing the maximum number of
- processes that dmake can use when making targets using
- parallel mode.
-
- NULL Is permanently defined to be the NULL string. This is
- useful when comparing a conditional expression to an
- NULL value.
-
- PWD Is the full path to the current directory in which make
- is executing.
-
- SPACECHAR Is permanently defined to contain one space character.
- This is useful when using space characters in function
- macros, e.g. subst, that otherwise would get deleted
- (leading/trailing spaces) or for using spaces in func-
- tion macro parameters.
-
- TMPFILE Is set to the name of the most recent temporary file
- opened by dmake. Temporary files are used for text
- diversions and for group recipe processing.
-
- TMD Stands for "To Make Dir", and is the path from the
- present directory (value of $(PWD)) to the directory
- that dmake was started up in (value of $(MAKEDIR)). If
- the present directory is the directory that dmake was
- started up in TMD will be set to the relative path ".".
- This allows to create valid paths by prepending
- $(TMD)$(DIRSEPSTR) to a relative path. This macro is
- modified when .SETDIR attributes are processed. TMD
- will usually be a relative path with the following two
- exceptions. If the relative path would go up until the
- root directory or if different drive letters (DOS file
- system) make a relative path impossible the absolute
- path from MAKEDIR is used.
-
- USESHELL The value of this macro is set to "yes" if the current
- recipe is forced to use a shell for its execution via
- the .USESHELL or '+' directives, its value is "no" oth-
- erwise.
-
-
- The second group of string valued macros control dmake behavior and may
- be set by the user.
-
-
-
-
-Dmake Version 4.12 2008-02-26 28
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- .DIRCACHE If set to "yes" enables the directory cache (this is
- the default). If set to "no" disables the directory
- cache (equivalent to -d command-line flag).
-
- .DIRCACHERESPCASE
- If set to "yes" causes the directory cache, if enabled,
- to respect file case, if set to "no" files are cached
- case insensitive. By default it is set to "no" on Win-
- dows as the filesystems on this operating system are
- case insensitive and set to "yes" for all other operat-
- ing systems. The default can be overriden, if desired.
-
- Note: Using case insensitive directory caching on case
- sensitive file systems is a BAD idea. If in doubt use
- case sensitive directory caching even on case insensi-
- tive file systems as the worst case in this scenario is
- that /foo/bar/ and /foo/BAR/ are cached separately
- (with the same content) even though they are the same
- directory. This would only happen if different targets
- use different upper/lower case spellings for the same
- directory and that is never a good idea.
-
- NAMEMAX Defines the maximum length of a filename component.
- The value of the variable is initialized at startup to
- the value of the compiled macro NAME_MAX. On some sys-
- tems the value of NAME_MAX is too short by default.
- Setting a new value for NAMEMAX will override the com-
- piled value.
-
- .NOTABS When set to "yes" enables the use of spaces as well as
- <tabs> to begin recipe lines. By default a non-group
- recipe is terminated by a line without any leading
- white-space or by a line not beggining with a <tab>
- character. Enabling this mode modifies the first con-
- dition of the above termination rule to terminate a
- non-group recipe with a line that contains only
- white-space. This mode does not effect the parsing of
- group recipes bracketed by [].
-
- AUGMAKE If set to "yes" value will enable the transformation of
- special meta targets to support special AUGMAKE infer-
- ences (See the "AUGMAKE META RULES" and "COMPATIBILITY"
- sections).
-
- DIRBRKSTR Contains the string of chars used to terminate the name
- of a directory in a pathname. Under UNIX its value is
- "/", under MSDOS its value is "/\:".
-
- DIRSEPSTR Contains the string that is used to separate directory
- components when path names are constructed. It is
- defined with a default value at startup.
-
- DIVFILE Is defined in the startup file and gives the name that
- should be returned for the diversion file name when
- used in $(mktmp ...) expansions, see the TEXT DIVERSION
- section for details.
-
- .KEEP_STATE Assigning this macro a value tells dmake the name of
- the state file to use and turns on the keeping of state
-
-
-
-Dmake Version 4.12 2008-02-26 29
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- information for any targets that are brought up to date
- by the make.
-
- GROUPFLAGS This macro gives the set of flags to pass to the shell
- when invoking it to execute a group recipe. The value
- of the macro is the list of flags with a leading switch
- indicator. (ie. `-' under UNIX)
-
- GROUPSHELL This macro defines the full path to the executable
- image to be used as the shell when processing group
- recipes. This macro must be defined if group recipes
- are used. It is assigned a default value in the
- startup makefile. Under UNIX this value is /bin/sh.
-
- GROUPSUFFIX If defined, this macro gives the string to use as a
- suffix when creating group recipe files to be handed to
- the command interpreter. For example, if it is defined
- as .sh, then all temporary files created by dmake will
- end in the suffix .sh. Under MSDOS if you are using
- command.com as your GROUPSHELL, then this suffix must
- be set to .bat in order for group recipes to function
- correctly. The setting of GROUPSUFFIX and GROUPSHELL
- is done automatically for command.com in the startup.mk
- files.
-
- MAKE Is defined in the startup file by default. Initially
- this macro is defined to have the value "$(MAKECMD)
- $(MFLAGS)". The string $(MAKE) is recognized when
- using the -n switch.
-
- MAKESTARTUP This macro defines the full path to the initial startup
- makefile. Use the -V command line option to discover
- its initial value.
-
- MAXLINELENGTH This macro defines the maximum size of a single line of
- makefile input text. The size is specified as a num-
- ber, the default value is defined internally and is
- shown via the -V option. A buffer of this size plus 2
- is allocated for reading makefile text. The buffer is
- freed before any targets are made, thereby allowing
- files containing long input lines to be processed with-
- out consuming memory during the actual make. This
- macro can only be used to extend the line length beyond
- it's default minimum value.
-
- MAXPROCESS Specify the maximum number of child processes to use
- when making targets. The default value of this macro
- is "1" and its value cannot exceed the value of the
- macro MAXPROCESSLIMIT. Setting the value of MAXPROCESS
- on the command line or in the makefile is equivalent to
- supplying a corresponding value to the -P flag on the
- command line. If the global .SEQUENTIAL attribute is
- set (or the -S command line switch is used) the value
- of MAXPROCESS is fixed to "1" and cannot be changed.
-
- OOODMAKEMODE This macro enables a special compatibility mode needed
- by the OpenOffice.org build system. If set, the switch
- disables the removal of leading './' path elements dur-
- ing target filename normalization (See BINDING
-
-
-
-Dmake Version 4.12 2008-02-26 30
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- TARGETS). If './' appear in the pathname, but not at
- the beginning of it, they are still removed by the nor-
- malization. Please note that targets that are given on
- the command line are going to be registered as default
- targets after the startup file is read.
-
- PREP This macro defines the number of iterations to be
- expanded automatically when processing % rule defini-
- tions of the form:
-
- % : %.suff
-
- See the sections on PERCENT(%) RULES for details on how
- PREP is used.
-
- SHELL This macro defines the full path to the executable
- image to be used as the shell when processing single
- line recipes. This macro must be defined if recipes
- requiring the shell for execution are to be used. It
- is assigned a default value in the startup makefile.
- Under UNIX this value is /bin/sh.
-
- SHELLCMDQUOTE This macro can be used to add additional characters
- before and after the command string that is passed to
- the shell defined by the SHELL macro. If needed, like
- for cmd.exe and command.com, it is assigned a value in
- the startup file.
-
- SHELLFLAGS This macro gives the set of flags to pass to the shell
- when invoking it to execute a single line recipe. The
- value of the macro is the list of flags with a leading
- switch indicator. (ie. `-' under UNIX)
-
- SHELLMETAS Each time dmake executes a single recipe line (not a
- group recipe) the line is searched for any occurrence
- of a character defined in the value of SHELLMETAS. If
- such a character is found the recipe line is defined to
- require a shell to ensure its correct execution. In
- such instances a shell is used to invoke the recipe
- line. If no match is found the recipe line is executed
- without the use of a shell.
-
-
- There is only one character valued macro defined by dmake: SWITCHAR
- contains the switch character used to introduce options on command
- lines. For UNIX its value is `-', and for MSDOS its value may be `/'
- or `-'. The macro is internally defined and is not user setable. The
- MSDOS version of dmake attempts to first extract SWITCHAR from an envi-
- ronment variable of the same name. If that fails it then attempts to
- use the undocumented getswitchar system call, and returns the result of
- that. Under MSDOS version 4.0 you must set the value of the environ-
- ment macro SWITCHAR to '/' to obtain predictable behavior.
-
- All boolean macros currently understood by dmake correspond directly to
- the previously defined attributes. These macros provide a second way
- to apply global attributes, and represent the preferred method of doing
- so. They are used by assigning them a value. If the value is not a
- NULL string then the boolean condition is set to on. If the value is a
- NULL string then the condition is set to off. There are five
-
-
-
-Dmake Version 4.12 2008-02-26 31
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- conditions defined and they correspond directly to the attributes of
- the same name. Their meanings are defined in the ATTRIBUTES section
- above. The macros are: .EPILOG, .IGNORE, .MKSARGS, .NOINFER, .PRE-
- CIOUS, .PROLOG, .SEQUENTIAL, .SILENT, .SWAP, and .USESHELL. Assigning
- any of these a non NULL value will globally set the corresponding
- attribute to on.
-
-RUNTIME MACROS
- These macros are defined when dmake is making targets, and may take on
- different values for each target. $@ is defined to be the full target
- name, $? is the list of all out of date prerequisites, except for the !
- ruleop, in which case it is set to the current build prerequisite
- instead. $& is the list of all prerequisites, $> is the name of the
- library if the current target is a library member, and $< is the list
- of prerequisites specified in the current rule. If the current target
- had a recipe inferred then $< is the name of the inferred prerequisite
- even if the target had a list of prerequisites supplied using an
- explicit rule that did not provide a recipe. In such situations $&
- gives the full list of prerequisites.
-
- $* is defined as $(@:db) when making targets with explicit recipes and
- is defined as the value of % when making targets whose recipe is the
- result of an inference. In the first case $* is the target name with
- no suffix, and in the second case, is the value of the matched % pat-
- tern from the associated %-rule. $^ expands to the set of out of date
- prerequisites taken from the current value of $<. In addition to
- these, $$ expands to $, {{ expands to {, }} expands to }, and the
- strings <+ and +> are recognized as respectively starting and terminat-
- ing a text diversion when they appear literally together in the same
- input line.
-
- The difference between $? and $^ can best be illustrated by an example,
- consider:
-
- fred.out : joe amy hello
- rules for making fred
-
- fred.out : my.c your.h his.h her.h # more prerequisites
-
- Assume joe, amy, and my.c are newer then fred.out. When dmake executes
- the recipe for making fred.out the values of the following macros will
- be:
-
- $@ --> fred.out
- $* --> fred
- $? --> joe amy my.c # note output of $? vs $^
- $^ --> joe amy
- $< --> joe amy hello
- $& --> joe amy hello my.c your.h his.h her.h
-
-
-FUNCTION MACROS
- dmake supports a full set of functional macros. One of these, the
- $(mktmp ...) macro, is discussed in detail in the TEXT DIVERSION sec-
- tion and is not covered here. The names of function macros must appear
- literally after the opening $( or ${. They are not recognized if they
- are the result of a recursive expansion.
-
- Note that some of these macros take comma separated parameters but that
-
-
-
-Dmake Version 4.12 2008-02-26 32
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- these parameters must not contain literal whitespaces. Whitespaces in
- macros used in these parameters are allowed.
-
-
- $(and macroterm ...)
- expands each macroterm in turn until there are no more or
- one of them returns an empty string. If all expand to
- non-empty strings the macro returs the string "t" other-
- wise it returns an empty string.
-
-
- $(assign expression)
- Causes expression to be parsed as a macro assignment
- expression and results in the specified assignment being
- made. An error is issued if the assignment is not
- syntatically correct. expression may contain white
- space. This is in effect a dynamic macro assignment
- facility and may appear anywhere any other macro may
- appear. The result of the expanding a dynamic macro
- assignment expression is the name of the macro that was
- assigned and $(NULL) if the expression is not a valid
- macro assignment expression. Some examples are:
-
- $(assign foo := fred)
- $(assign $(ind_macro_name) +:= $(morejunk))
-
- $(echo list)
- Echo's the value of list. list is not expanded.
-
- $(eq,text_a,text_b true false)
- expands text_a and text_b and compares their results. If
- equal it returns the result of the expansion of the true
- term, otherwise it returns the expansion of the false
- term.
-
- $(!eq,text_a,text_b true false)
- Behaves identically to the previous macro except that the
- true string is chosen if the expansions of the two
- strings are not equal
-
- $(foreach,var,list data)
- Implements iterative macro expansion over data using var
- as the iterator taking on values from list. var and list
- are expanded and the result is the concatenation of
- expanding data with var being set to each whitespace sep-
- arated token from list. For example:
-
- list = a b c
- all :; echo [$(foreach,i,$(list) [$i])]
-
- will output
-
- [[a] [b] [c]]
-
- The iterator variable is defined as a local variable to
- this foreach instance. The following expression illus-
- trates this:
-
- $(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h])
-
-
-
-Dmake Version 4.12 2008-02-26 33
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- when evaluated the result is:
-
- [root/a/f.h] [root/b/f.h] [root/c/f.h]
-
- The specification of list must be a valid macro expres-
- sion, such as:
-
- $($(assign list=a b c))
- $(sort d a b c)
- $(echo a b c)
-
- and cannot just be the list itself. That is, the follow-
- ing foreach expression:
-
- $(foreach,i,a b c [$i])
-
- yields:
-
- "b c [a]"
-
- when evaluated.
-
- $(nil expression)
- Always returns the value of $(NULL) regardless of what
- expression is. This function macro can be used to dis-
- card results of expanding macro expressions.
-
- $(normpath list)
- Will return the normalized path names of all white-space
- separated tokens in list. Quotes can be used to normalize
- path names that contain white-space characters. On cygwin
- the result honors the setting of .WINPATH to determine
- the output format of the returned path names.
-
- $(normpath,para list)
- Same as above except that the expanded value of para is
- used to override the .WINPATH setting.
-
- $(not macroterm)
- expands macroterm and returs the string "t" if the result
- of the expansion is the empty string; otherwise, it
- returns the empty string.
-
- $(null,text true false)
- expands the value of text. If it is NULL then the macro
- returns the value of the expansion of true and the expan-
- sion of false otherwise. The terms true, and false must
- be strings containing no white-space.
-
- $(!null,text true false)
- Behaves identically to the previous macro except that the
- true string is chosen if the expansion of text is not
- NULL.
-
- $(or macroterm ...)
- expands each macroterm in turn and returs the empty
- string if each term expands to the empty string; other-
- wise, it returs the string "t".
-
-
-
-
-Dmake Version 4.12 2008-02-26 34
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- $(shell command)
- is a shell escape macro. It runs command as if it were
- part of a recipe and returns, separated by a single
- space, all the non-white space terms written to stdout by
- the command. For example:
-
- $(shell ls *.c)
-
- will return "a.c b.c c.c d.c" if the files exist in the
- current directory. The recipe modification flags [+@%-]
- are honored if they appear as the first characters in the
- command. For example:
-
- $(shell +ls *.c)
-
- will run the command using the current shell.
-
- Note that if the macro is part of a recipe it will be
- evaluated after all previous recipe lines have been exe-
- cuted. For obvious reasons it will be evaluated before
- the current recipe line or group recipe is executed.
-
- $(shell,expand command)
- Is an extension to the $(shell command) function macro
- that expands the result of running command.
-
- $(sort list)
- Will take all white-space separated tokens in list and
- will return their sorted equivalent list.
-
- $(strip data)
- Will replace all strings of white-space in data by a sin-
- gle space.
-
- $(subst,pat,replacement data)
- Will search for pat in data and will replace any occur-
- rence of pat with the replacement string. The expansion
-
- $(subst,.o,.c $(OBJECTS))
-
- is equivalent to:
-
- $(OBJECTS:s/.o/.c/)
-
-
- $(uniq list)
- Will take all white-space separated tokens in list and
- will return their sorted equivalent list containing no
- duplicates.
-
- For historic reasons dmake treats the following case slightly special:
-
- $(name something)
-
- If it encounters a macro with a whitespace after name and name is not
- literally one of the above mentioned function macro identifiers then
- dmake will return the recursively expanded value of $(name). The
- remaining something part will be expanded but the result will be dis-
- carded. The use of this special feature is deprecated and should not be
-
-
-
-Dmake Version 4.12 2008-02-26 35
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- used.
-
-
-CONDITIONAL MACROS
- dmake supports conditional macros. These allow the definition of tar-
- get specific macro values. You can now say the following:
-
- target ?= MacroName MacroOp Value
-
- This creates a definition for MacroName whose value is Value only when
- target is being made. You may use a conditional macro assignment any-
- where that a regular macro assignment may appear, including as the
- value of a $(assign ...) macro.
-
- The new definition is associated with the most recent cell definition
- for target. If no prior definition exists then one is created. The
- implications of this are immediately evident in the following example:
-
- foo := hello
-
- all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]"
-
- cond ?= bar := global decl
-
- cond .SETDIR=unix::;@echo $(foo) $(bar)
- cond ?= foo := hi
-
- cond .SETDIR=msdos::;@echo $(foo) $(bar)
- cond ?= foo := hihi
-
- The first conditional assignment creates a binding for 'bar' that is
- activated when 'cond' is made. The bindings following the :: defini-
- tions are activated when their respective recipe rules are used. Thus
- the first binding serves to provide a global value for 'bar' while any
- of the cond :: rules are processed, and the local bindings for 'foo'
- come into effect when their associated :: rule is processed.
-
- Conditionals for targets of .UPDATEALL are all activated before the
- target group is made. Assignments are processed in order. Note that
- the value of a conditional macro assignment is NOT AVAILABLE until the
- associated target is made, thus the construct
-
- mytarget ?= bar := hello
- mytarget ?= foo := $(bar)
-
- results in $(foo) expanding to "", if you want the result to be "hello"
- you must use:
-
- mytarget ?= bar := hello
- mytarget ?= foo = $(bar)
-
- Once a target is made any associated conditional macros are deactivated
- and their values are no longer available. Activation occurrs after all
- inference, and .SETDIR directives have been processed and after $@ is
- assigned, but before prerequisites are processed; thereby making the
- values of conditional macro definitions available during construction
- of prerequisites.
-
- If a %-meta rule target has associated conditional macro assignments,
-
-
-
-Dmake Version 4.12 2008-02-26 36
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- and the rule is chosen by the inference algorithm then the conditional
- macro assignments are inferred together with the associated recipe.
-
-DYNAMIC PREREQUISITES
- dmake looks for prerequisites whose names contain macro expansions dur-
- ing target processing. Any such prerequisites are expanded and the
- result of the expansion is used as the prerequisite name. As an exam-
- ple the line:
-
- fred : $$@.c
-
- causes the $$@ to be expanded when dmake is making fred, and it
- resolves to the target fred. This enables dynamic prerequisites to be
- generated. The value of @ may be modified by any of the valid macro
- modifiers. So you can say for example:
-
- fred.out : $$(@:b).c
-
- where the $$(@:b) expands to fred. Note the use of $$ instead of $ to
- indicate the dynamic expansion, this is due to the fact that the rule
- line is expanded when it is initially parsed, and $$ then returns $
- which later triggers the dynamic prerequisite expansion. Dynamic macro
- expansion is performed in all user defined rules, and the special tar-
- gets .SOURCE*, and .INCLUDEDIRS.
-
- NOTE: The use of a $ as part of a prerequisite or target name is
- strongly discouraged as the runtime macros (like $@) are expanded when
- used in a recipe line so that the $ is interpreted as a macro identi-
- fier and not as a character of the filename leading to invalid runtime
- macros. In addition to this no filename normalization is done for pre-
- requisites and targets that contain $ characters. Nevertheless it is
- possible to use $ in prerequisites by using $$$$ but this is not recom-
- mended and can lead to surprising results.
-
- If dynamic macro expansion results in multiple white space separated
- tokens then these are inserted into the prerequisite list inplace of
- the dynamic prerequisite. Due to the recursive nature of macro expan-
- sion the prerequisite list is fully expanded even if the dynamic pre-
- requisite contained other runtime macros.
-
-BINDING TARGETS
- This operation takes a target name and binds it to an existing file, if
- possible. dmake makes a distinction between the internal target name
- of a target and its associated external file name. Thus it is possible
- for a target's internal name and its external file name to differ. To
- perform the binding, the following set of rules is used. Assume that
- we are trying to bind a target whose name is of the form X.suff, where
- .suff is the suffix and X is the stem portion (ie. that part which con-
- tains the directory and the basename). dmake takes this target name
- and performs a series of search operations that try to find a suitably
- named file in the external file system. The search operation is user
- controlled via the settings of the various .SOURCE targets.
-
- 1. If target has the .SYMBOL attribute set then look for it
- in the library. If found, replace the target name with
- the library member name and continue with step 2. If the
- name is not found then return.
-
- 2. Extract the suffix portion (that following the `.') of
- the target name. If the suffix is not null, look up the
-
-
-
-Dmake Version 4.12 2008-02-26 37
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- special target .SOURCE.<suff> (<suff> is the suffix). If
- the special target exists then search each directory
- given in the .SOURCE.<suff> prerequisite list for the
- target. If the target's suffix was null (ie. .suff was
- empty) then perform the above search but use the special
- target .SOURCE.NULL instead. If at any point a match is
- found then terminate the search. If a directory in the
- prerequisite list is the special name `.NULL ' perform a
- search for the full target name without prepending any
- directory portion (ie. prepend the NULL directory).
-
- 3. The search in step 2. failed. Repeat the same search but
- this time use the special target .SOURCE. (a default
- target of '.SOURCE : .NULL' is defined by dmake at
- startup, and is user redefinable)
-
- 4. The search in step 3. failed. If the target has the
- library member attribute (.LIBMEMBER) set then try to
- find the target in the library which was passed along
- with the .LIBMEMBER attribute (see the MAKING LIBRARIES
- section). The bound file name assigned to a target which
- is successfully located in a library is the same name
- that would be assigned had the search failed (see 5.).
-
- 5. The search failed. Either the target was not found in
- any of the search directories or no applicable .SOURCE
- special targets exist. If applicable .SOURCE special
- targets exist, but the target was not found, then dmake
- assigns the first name searched as the bound file name.
- If no applicable .SOURCE special targets exist, then the
- full original target name becomes the bound file name.
-
- There is potential here for a lot of search operations. The trick is
- to define .SOURCE.x special targets with short search lists and leave
- .SOURCE as short as possible. The search algorithm has the following
- useful side effect. When a target having the .LIBMEMBER (library mem-
- ber) attribute is searched for, it is first searched for as an ordinary
- file. When a number of library members require updating it is desir-
- able to compile all of them first and to update the library at the end
- in a single operation. If one of the members does not compile and
- dmake stops, then the user may fix the error and make again. dmake
- will not remake any of the targets whose object files have already been
- generated as long as none of their prerequisite files have been modi-
- fied as a result of the fix.
-
- When dmake constructs target (and prerequisite) pathnames they are nor-
- malized to the shortest (or most natural, see below for the cygwin
- case) representation. Substrings like './' or of the form 'baz/..' are
- removed and multiple slashes are collapsed to one unless they are at
- the beginning of the pathname. Leading slashes are normalized according
- to POSIX rules, i.e. more than two leading slashes are reduced to one
- slash and a leading '//' is kept as it might have a special meaning.
- For example "./foo", "bar/../foo" and foo are recognized as the same
- file. This may result in somewhat unexpected values of the macro
- expansion of runtime macros like $@, but is infact the corect result.
-
- NOTE: A cygwin dmake executable will accept DOS like pathnames with
- drive letters and cygwin POSIX pathnames and normalize them into its
- natural POSIX representation. This might result in even more surpris-
- ing values of runtime macros.
-
-
-
-Dmake Version 4.12 2008-02-26 38
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- When defining .SOURCE and .SOURCE.x targets the construct
-
- .SOURCE :
- .SOURCE : fred gery
-
- is equivalent to
-
- .SOURCE :- fred gery
-
- dmake correctly handles the UNIX Make variable VPATH. By definition
- VPATH contains a list of ':' separated directories to search when look-
- ing for a target. dmake maps VPATH to the following special rule:
-
- .SOURCE :^ $(VPATH:s/:/ /)
-
- Which takes the value of VPATH and sets .SOURCE to the same set of
- directories as specified in VPATH.
-
-PERCENT(%) RULES AND MAKING INFERENCES
- When dmake makes a target, the target's set of prerequisites (if any)
- must exist and the target must have a recipe which dmake can use to
- make it. If the makefile does not specify an explicit recipe for the
- target then dmake uses special rules to try to infer a recipe which it
- can use to make the target. Previous versions of Make perform this
- task by using rules that are defined by targets of the form .<suf-
- fix>.<suffix> (this is still supported, see "AUGMAKE META RULES") or by
- using the not supported by dmake .SUFFIXES list of suffixes (see "SPE-
- CIAL TARGETS" for more details about .SUFFIXES). The exact workings of
- this mechanism were sometimes difficult to understand and often limit-
- ing in their usefulness. Instead, dmake supports the concept of %-meta
- rules. The syntax and semantics of these rules differ from standard
- rule lines as follows:
-
- <%-targets> [<attributes>] <ruleop> [<%-prereqs>] [;<recipe>]
-
- where %-targets are one or more targets containing exactly a single `%'
- sign, attributes is a list (possibly empty) of attributes, ruleop is
- the standard set of rule operators, %-prereqs , if present, is a list
- of prerequisites containing zero or more `%' signs, and recipe, if
- present, is the first line of the recipe.
-
- If more than one %-target is present this line is equivalent to a repe-
- tition of the whole [<attributes>] <ruleop> [<%-prereqs>] [;<recipe>]
- sequence for each %-target, i.e. it is possible to specify the same
- rule for multiple %-targets. Because of this following only speaks
- about <%-target> as %-targets are divided into multiple definitions
- with a single %-target.
-
- NOTE: As multiple %-targets didn't work reliably with dmake versions
- prior to 4.5 unless the rule operator `|:' was used we currently issue
- a warning stating that it now works.
-
- The %-target defines a pattern against which a target whose recipe is
- being inferred gets matched. The pattern match goes as follows: all
- chars are matched exactly from left to right up to but not including
- the % sign in the pattern, % then matches the longest string from the
- actual target name not ending in the suffix given after the % sign in
- the pattern. Consider the following examples:
-
- %.c matches fred.c but not joe.c.Z
- dir/%.c matches dir/fred.c but not dd/fred.c
- fred/% matches fred/joe.c but not f/joe.c
- % matches anything
-
-
-
-
-Dmake Version 4.12 2008-02-26 39
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- In each case the part of the target name that matched the % sign is
- retained and is substituted for any % signs in the prerequisite list of
- the %-meta rule when the rule is selected during inference and dmake
- constructs the new dependency.
-
- Please note, that only the first, non-indirect, prerequisite of the
- list is used for the inference mechanism. If more than one non-indirect
- prerequisite is given a warning is issued and all but the first non-
- indirect prerequisites are ignored. See below for a description of
- indirect prerequisites.
-
- As an example the following %-meta rules describe the following:
-
- %.c : %.y ; recipe...
-
- describes how to make any file ending in .c if a corresponding file
- ending in .y can be found.
-
- foo%.o : fee%.k ; recipe...
-
- is used to describe how to make fooxxxx.o from feexxxx.k.
-
- %.a :; recipe...
-
- describes how to make a file whose suffix is .a without inferring any
- prerequisites.
-
- %.c : %.y 'yaccsrc/%.y' ; recipe...
-
- matches the corresponding .y file as prerequisite and additionally
- another .y file in the yaccsrc subdirectory as indirect prerequisite.
- Another interesting example is:
-
- % : RCS/%,v ; co $<
-
- which describes how to take any target and check it out of the RCS
- directory if the corresponding file exists in the RCS directory. The
- equivalent SCCS rule would be:
-
- % : s.% ; get $<
-
-
- The previous RCS example defines an infinite rule, because it says how
- to make anything from RCS/%,v, and anything also includes RCS/fred.c,v.
- To limit the size of the graph that results from such rules dmake uses
- the macro variable PREP (stands for % repetition). By default the
- value of this variable is 0, which says that no repetitions of a %-rule
- are to be generated. If it is set to something greater than 0, then
- that many repetitions of any infinite %-rule are allowed. If in the
- above example PREP was set to 1, then dmake would generate the depen-
- dency graph:
-
- % --> RCS/%,v --> RCS/RCS/%,v,v
-
- Where each link is assigned the same recipe as the first link. PREP
- should be used only in special cases, since it may result in a large
- increase in the number of possible prerequisites tested. dmake further
- assumes that any target that has no suffix can be made from a prerequi-
- site that has at least one suffix.
-
- dmake supports dynamic prerequisite generation for prerequisites of
- %-meta rules. This is best illustrated by an example. The RCS rule
- shown above can infer how to check out a file from a corresponding RCS
- file only if the target is a simple file name with no directory
-
-
-
-Dmake Version 4.12 2008-02-26 40
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- information. That is, the above rule can infer how to find
- RCS/fred.c,v from the target fred.c, but cannot infer how to find
- srcdir/RCS/fred.c,v from srcdir/fred.c because the above rule will
- cause dmake to look for RCS/srcdir/fred.c,v; which does not exist
- (assume that srcdir has its own RCS directory as is the common case).
-
- A more versatile formulation of the above RCS check out rule is the
- following:
-
- % : $$(@:d)RCS/$$(@:f),v : co $@
-
- This rule uses the dynamic macro $@ to specify the prerequisite to try
- to infer. During inference of this rule the macro $@ is set to the
- value of the target of the %-meta rule and the appropriate prerequisite
- is generated by extracting the directory portion of the target name (if
- any), appending the string RCS/ to it, and appending the target file
- name with a trailing ,v attached to the previous result.
-
- dmake can also infer indirect prerequisites. An inferred target can
- have a list of prerequisites added that will not show up in the value
- of $< but will show up in the value of $? and $&. Indirect prerequi-
- sites are specified in an inference rule by quoting the prerequisite
- with single quotes. For example, if you had the explicit dependency:
-
- fred.o : fred.c ; rule to make fred.o
- fred.o : local.h
-
- then this can be inferred for fred.o from the following inference rule:
-
- %.o : %.c 'local.h' ; makes a .o from a .c
-
- You may infer indirect prerequisites that are a function of the value
- of '%' in the current rule. The meta-rule:
-
- %.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
-
- infers an indirect prerequisite found in the INC directory whose name
- is the same as the expansion of $(INC), and the prerequisite name
- depends on the base name of the current target. The set of indirect
- prerequisites is attached to the meta rule in which they are specified
- and are inferred only if the rule is used to infer a recipe for a tar-
- get. They do not play an active role in driving the inference algo-
- rithm. The construct:
-
- %.o :| %.c %.f 'local.h'; recipe
-
- is equivalent to:
-
- %.o : %.c 'local.h' ; recipe
- %.o : %.f 'local.h' ; recipe
-
-
- If any of the attributes .EPILOG, .IGNORE, .LIBRARY, .NOSTATE, .PHONY,
- .PRECIOUS, .PROLOG, .SETDIR, .SILENT, .SWAP, .USESHELL and .WINPATH are
- given for a %-rule then when that rule is bound to a target as the
- result of an inference, the target's set of attributes is augmented by
- the attributes from the above set that are specified in the bound
- %-rule. Other attributes specified for %-meta rules are not inherited
- by the target. The .SETDIR attribute is treated in a special way. If
- the target already had a .SETDIR attribute set then dmake changes to
- that directory prior to performing the inference. During inference any
- .SETDIR attributes for the inferred prerequisite are honored. The
- directories must exist for a %-meta rule to be selected as a possible
- inference path. If the directories do not exist no error message is
-
-
-
-Dmake Version 4.12 2008-02-26 41
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- issued, instead the corresponding path in the inference graph is
- rejected.
-
- dmake bases all of its inferences on the inference graph constructed
- from the %-rules defined in the makefile. It knows exactly which tar-
- gets can be made from which prerequisites by making queries on the
- inference graph.
-
- For a %-meta rule to be inferred as the rule whose recipe will be used
- to make a target, the target's name must match the %-target pattern,
- and any inferred %-prerequisite must already exist or have an explicit
- recipe so that the prerequisite can be made. Without transitive clo-
- sure on the inference graph the above rule describes precisely when an
- inference match terminates the search. If transitive closure is
- enabled (the usual case), and a prerequisite does not exist or cannot
- be made, then dmake invokes the inference algorithm recursively on the
- prerequisite to see if there is some way the prerequisite can be manu-
- factured. For, if the prerequisite can be made then the current target
- can also be made using the current %-meta rule. This means that there
- is no longer a need to give a rule for making a .o from a .y if you
- have already given a rule for making a .o from a .c and a .c from a .y.
- In such cases dmake can infer how to make the .o from the .y via the
- intermediary .c and will remove the .c when the .o is made. Transitive
- closure can be disabled by giving the -T switch on the command line.
-
- A word of caution. dmake bases its transitive closure on the %-meta
- rule targets. When it performs transitive closure it infers how to
- make a target from a prerequisite by performing a pattern match as if
- the potential prerequisite were a new target. The set of rules:
-
- %.o : %.c ; rule for making .o from .c
- %.c : %.y ; rule for making .c from .y
- % : RCS/%,v ; check out of RCS file
-
- will, by performing transitive closure, allow dmake to infer how to
- make a .o from a .y using a .c as an intermediate temporary file.
- Additionally it will be able to infer how to make a .y from an RCS
- file, as long as that RCS file is in the RCS directory and has a name
- which ends in .y,v. The transitivity computation is performed dynami-
- cally for each target that does not have a recipe. This has potential
- to be costly if the %-meta rules are not carefully specified. The
- .NOINFER attribute is used to mark a %-meta node as being a final tar-
- get during inference. Any node with this attribute set will not be
- used for subsequent inferences. As an example the node RCS/%,v is
- marked as a final node since we know that if the RCS file does not
- exist there likely is no other way to make it. Thus the standard
- startup makefile contains an entry similar to:
- .NOINFER : RCS/%,v
- Thereby indicating that the RCS file is the end of the inference chain.
- Whenever the inference algorithm determines that a target can be made
- from more than one prerequisite and the inference chains for the two
- methods are the same length the algorithm reports an ambiguity and
- prints the ambiguous inference chains.
-
- dmake tries to remove intermediate files resulting from transitive clo-
- sure if the file is not marked as being PRECIOUS, or the -u flag was
- not given on the command line, and if the inferred intermediate did not
- previously exist. Intermediate targets that existed prior to being
- made are never removed. This is in keeping with the philosophy that
- dmake should never remove things from the file system that it did not
- add. If the special target .REMOVE is defined and has a recipe then
- dmake constructs a list of the intermediate files to be removed and
- makes them prerequisites of .REMOVE. It then makes .REMOVE thereby
- removing the prerequisites if the recipe of .REMOVE says to. Typically
-
-
-
-Dmake Version 4.12 2008-02-26 42
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- .REMOVE is defined in the startup file as:
-
- .REMOVE :; $(RM) $<
-
-AUGMAKE META RULES
- As a subclass of the meta targets that is actually mapped to %-meta
- rules dmake understands several SYSV AUGMAKE targets transformations.
- This .<suffix> special target construct transforms into the following
- %-meta rules:
-
- .suff :; recipe
-
- gets mapped into:
-
- % : %.suff; recipe
-
-
- dmake also supports the old format special target .<suffix>.<suffix> by
- identifying any rules of this form and mapping them to the appropriate
- %-rule. So for example if an old makefile contains the construct:
-
- .c.o :; cc -c $< -o $@
-
- dmake maps this into the following %-rule:
-
- %.o : %.c; cc -c $< -o $@
-
- The following SYSV AUGMAKE special targets transformation must be
- enabled by providing the -A flag on the command line or by setting the
- value of AUGMAKE to non-NULL. The construct
-
- .c~.o :; recipe
-
- gets mapped into:
-
- %.o : s.%.c ; recipe
-
- In general, a special target of the form .<str>~ is replaced by the
- %-rule construct s.%.<str>, thereby providing support for the syntax
- used by SYSV AUGMAKE for providing SCCS support. When enabled, these
- mappings allow processing of existing SYSV makefiles without modifica-
- tions.
-
-MAKING TARGETS
- In order to update a target dmake must execute a recipe. When a recipe
- needs to be executed it is first expanded so that any macros in the
- recipe text are expanded, and it is then either executed directly or
- passed to a shell. dmake supports two types of recipes. The regular
- recipes and group recipes.
-
- When a regular recipe is invoked dmake executes each line of the recipe
- separately using a new copy of a shell if a shell is required. Thus
- effects of commands do not generally persist across recipe lines (e.g.
- cd requests in a recipe line do not carry over to the next recipe
- line). This is true even in environments such as MSDOS, where dmake
- internally sets the current working director to match the directory it
- was in before the command was executed.
-
- The decision on whether a shell is required to execute a command is
- based on the value of the macro SHELLMETAS or on the specification of
- '+' or .USESHELL for the current recipe or target respectively. If any
- character in the value of SHELLMETAS is found in the expanded recipe
- text-line or the use of a shell is requested explicitly via '+' or
- .USESHELL then the command is executed using a shell, otherwise the
-
-
-
-Dmake Version 4.12 2008-02-26 43
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- command is executed directly. The shell that is used for execution is
- given by the value of the macro SHELL. The flags that are passed to
- the shell are given by the value of SHELLFLAGS. Thus dmake constructs
- the command line:
-
- $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
-
- If the $(SHELLCMDQUOTE) macro is set its value is inserted before and
- after the $(expanded_recipe_command) string.
-
- Normally dmake writes the command line that it is about to invoke to
- standard output. If the .SILENT attribute is set for the target or for
- the recipe line (via @), then the recipe line is not echoed.
-
- Group recipe processing is similar to that of regular recipes, except
- that a shell is always invoked. The shell that is invoked is given by
- the value of the macro GROUPSHELL, and its flags are taken from the
- value of the macro GROUPFLAGS. If a target has the .PROLOG attribute
- set then dmake prepends to the shell script the recipe associated with
- the special target .GROUPPROLOG, and if the attribute .EPILOG is set as
- well, then the recipe associated with the special target .GROUPEPILOG
- is appended to the script file. This facility can be used to always
- prepend a common header and common trailer to group recipes. Group
- recipes are echoed to standard output just like standard recipes, but
- are enclosed by lines beginning with [ and ].
-
- The recipe flags [+,-,%,@] are recognized at the start of a recipe line
- even if they appear in a macro. For example:
-
- SH = +
- all:
- $(SH)echo hi
-
- is completely equivalent to writing
-
- SH = +
- all:
- +echo hi
-
-
- The last step performed by dmake prior to running a recipe is to set
- the macro CMNDNAME to the name of the command to execute (determined by
- finding the first white-space ending token in the command line). It
- then sets the macro CMNDARGS to be the remainder of the line. dmake
- then expands the macro COMMAND which by default is set to
-
- COMMAND = $(CMNDNAME) $(CMNDARGS)
-
- The result of this final expansion is the command that will be exe-
- cuted. The reason for this expansion is to allow for a different
- interface to the argument passing facilities (esp. under DOS) than that
- provided by dmake. You can for example define COMMAND to be
-
- COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
-
- which dumps the arguments into a temporary file and runs the command
-
- $(CMNDNAME) @/tmp/ASAD23043
-
- which has a much shorter argument list. It is now up to the command to
- use the supplied argument as the source for all other arguments. As an
- optimization, if COMMAND is not defined dmake does not perform the
- above expansion. On systems, such as UNIX, that handle long command
- lines this provides a slight saving in processing the makefiles.
-
-
-
-Dmake Version 4.12 2008-02-26 44
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
-MAKING LIBRARIES
- Libraries are easy to maintain using dmake. A library is a file con-
- taining a collection of object files. Thus to make a library you sim-
- ply specify it as a target with the .LIBRARY attribute set and specify
- its list of prerequisites. The prerequisites should be the object mem-
- bers that are to go into the library. When dmake makes the library
- target it uses the .LIBRARY attribute to pass to the prerequisites the
- .LIBMEMBER attribute and the name of the library. This enables the
- file binding mechanism to look for the member in the library if an
- appropriate object file cannot be found. dmake now supports Elf
- libraries on systems that support Elf and hence supports, on those sys-
- tems, long member file names. A small example best illustrates this.
-
- mylib.a .LIBRARY : mem1.o mem2.o mem3.o
- rules for making library...
- # remember to remove .o's when lib is made
-
- # equivalent to: '%.o : %.c ; ...'
- .c.o :; rules for making .o from .c say
-
- dmake will use the .c.o rule for making the library members if appro-
- priate .c files can be found using the search rules. NOTE: this is
- not specific in any way to C programs, they are simply used as an exam-
- ple.
-
- dmake tries to handle the old library construct format in a sensible
- way. The construct lib(member.o) is separated and the lib portion is
- declared as a library target. The new target is defined with the
- .LIBRARY attribute set and the member.o portion of the construct is
- declared as a prerequisite of the lib target. If the construct
- lib(member.o) appears as a prerequisite of a target in the makefile,
- that target has the new name of the lib assigned as its prerequisite.
- Thus the following example:
-
- a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@ $<
-
- .c.o :; $(CC) -c $(CFLAGS) -o $@ $<
- %.a:
- ar rv $@ $?
- ranlib $@
- rm -rf $?
-
- constructs the following dependency graph.
-
- a.out : ml.a; $(CC) -o $@ $<
- ml.a .LIBRARY : a.o b.o
-
- %.o : %.c ; $(CC) -c $(CFLAGS) -o $@ $<
- %.a :
- ar rv $@ $?
- ranlib $@
- rm -rf $?
-
- and making a.out then works as expected.
-
- The same thing happens for any target of the form lib((entry)). These
- targets have an additional feature in that the entry target has the
- .SYMBOL attribute set automatically.
-
- NOTE: If the notion of entry points is supported by the archive and by
- dmake (currently not the case) then dmake will search the archive for
- the entry point and return not only the modification time of the member
- which defines the entry but also the name of the member file. This
- name will then replace entry and will be used for making the member
-
-
-
-Dmake Version 4.12 2008-02-26 45
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- file. Once bound to an archive member the .SYMBOL attribute is removed
- from the target. This feature is presently disabled as there is little
- standardization among archive formats, and we have yet to find a make-
- file utilizing this feature (possibly due to the fact that it is unim-
- plemented in most versions of UNIX Make).
-
- Finally, when dmake looks for a library member it must first locate the
- library file. It does so by first looking for the library relative to
- the current directory and if it is not found it then looks relative to
- the current value of $(TMD). This allows commonly used libraries to be
- kept near the root of a source tree and to be easily found by dmake.
-
-KEEP STATE
- dmake supports the keeping of state information for targets that it
- makes whenever the macro .KEEP_STATE is assigned a value. The value of
- the macro should be the name of a state file that will contain the
- state information. If state keeping is enabled then each target that
- does not poses the .NOSTATE attribute will have a record written into
- the state file indicating the target's name, the current directory, the
- command used to update the target, and which, if any, :: rule is being
- used. When you make this target again if any of this information does
- not match the previous settings and the target is not out dated it will
- still be re-made. The assumption is that one of the conditions above
- has changed and that we wish to remake the target. For example, state
- keeping is used in the maintenance of dmake to test compile different
- versions of the source using different compilers. Changing the com-
- piler causes the compilation flags to be modified and hence all sources
- to be recompiled.
-
- The state file is an ascii file and is portable, however it is not in
- human readable form as the entries represent hash keys of the above
- information.
-
- The Sun Microsystem's Make construct
-
- .KEEP_STATE :
-
- is recognized and is mapped to .KEEP_STATE:=_state.mk. The dmake ver-
- sion of state keeping does not include scanning C source files for
- dependencies like Sun Make. This is specific to C programs and it was
- felt that it does not belong in make. dmake instead provides the tool,
- cdepend, to scan C source files and to produce depedency information.
- Users are free to modify cdepend to produce other dependency files.
- (NOTE: cdepend does not come with the distribution at this time, but
- will be available in a patch in the near future)
-
-MULTI PROCESSING
- If the architecture supports it then dmake is capable of making a tar-
- get's prerequisites in parallel. dmake will make as much in parallel
- as it can and use a number of child processes up to the maximum speci-
- fied by MAXPROCESS or by the value supplied to the -P command line
- flag. A parallel make is enabled by setting the value of MAXPROCESS
- (either directly or via -P option) to a value which is > 1. dmake
- guarantees that all dependencies as specified in the makefile are hon-
- ored. A target will not be made until all of its prerequisites have
- been made. Note that when you specify -P 4 then four child processes
- are run concurrently but dmake actually displays the fifth command it
- will run immediately upon a child process becomming free. This is an
- artifact of the method used to traverse the dependency graph and cannot
- be removed. If a parallel make is being performed then the following
- restrictions on parallelism are enforced.
-
- 1. Individual recipe lines in a non-group recipe are per-
- formed sequentially in the order in which they are
-
-
-
-Dmake Version 4.12 2008-02-26 46
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- specified within the makefile and in parallel with the
- recipes of other targets.
-
- 2. If a target contains multiple recipe definitions (cf. ::
- rules) then these are performed sequentially in the order
- in which the :: rules are specified within the makefile
- and in parallel with the recipes of other targets.
-
- 3. If a target rule contains the `!' modifier, then the
- recipe is performed sequentially for the list of outdated
- prerequisites and in parallel with the recipes of other
- targets.
-
- 4. If a target has the .SEQUENTIAL attribute set then all of
- its prerequisites are made sequentially relative to one
- another (as if MAXPROCESS=1), but in parallel with other
- targets in the makefile.
-
- Note: If you specify a parallel make then the order of target update
- and the order in which the associated recipes are invoked will not cor-
- respond to that displayed by the -n flag.
-
-CONDITIONALS
- dmake supports a makefile construct called a conditional. It allows
- the user to conditionally select portions of makefile text for input
- processing and to discard other portions. This becomes useful for
- writing makefiles that are intended to function for more than one tar-
- get host and environment. The conditional expression is specified as
- follows:
-
- .IF expression
- ... if text ...
- .ELIF expression
- ... if text ...
- .ELSE
- ... else text ...
- .END
-
- The .ELSE and .ELIF portions are optional, and the conditionals may be
- nested (ie. the text may contain another conditional). .IF, .ELSE,
- and .END may appear anywhere in the makefile, but a single conditional
- expression may not span multiple makefiles.
-
- expression can be one of the following forms:
-
- String evaluation
- <text> | <text> == <text> | <text> != <text>
-
- Numeric evaluation
- <text> <= <text> | <text> >= <text>
-
- Boolean evaluation
- ( <text> ) | <text> || <text> | <text> && <text>
-
- where text is either text or a macro expression. In any case, before
- the comparison is made, the expression is expanded. The text portions
- are then selected and compared. In the case of the numeric comparisons
- enclosing quotes are removed after expanding the expressions and the
- leading numerical parts are converted to an integer number. If no
- numerical part is found this results to 0 (zero). The string "12ab" for
- example evaluates to the number 12. Expressions can be nested with ()
- and the use of || or &&. White space at the start and end of the text
- portion is discarded before the comparison. This means that a macro
- that evaluates to nothing but white space is considered a NULL value
-
-
-
-Dmake Version 4.12 2008-02-26 47
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- for the purpose of the comparison. In the first case the expression
- evaluates TRUE if the text is not NULL otherwise it evaluates FALSE.
- The remaining two cases both evaluate the expression on the basis of a
- string comparison. If a macro expression needs to be equated to a NULL
- string then compare it to the value of the macro $(NULL). You can use
- the $(shell ...) macro to construct more complex test expressions.
-
-EXAMPLES
- # A simple example showing how to use make
- #
- prgm : a.o b.o
- cc a.o b.o -o prgm
- a.o : a.c g.h
- cc a.c -o $@
- b.o : b.c g.h
- cc b.c -o $@
-
- In the previous example prgm is remade only if a.o and/or b.o is out of
- date with respect to prgm. These dependencies can be stated more con-
- cisely by using the inference rules defined in the standard startup
- file. The default rule for making .o's from .c's looks something like
- this:
-
- %.o : %.c; cc -c $(CFLAGS) -o $@ $<
-
- Since there exists a rule (defined in the startup file) for making .o's
- from .c's dmake will use that rule for manufacturing a .o from a .c and
- we can specify our dependencies more concisely.
-
- prgm : a.o b.o
- cc -o prgm $<
- a.o b.o : g.h
-
- A more general way to say the above using the new macro expansions
- would be:
-
- SRC = a b
- OBJ = {$(SRC)}.o
-
- prgm : $(OBJ)
- cc -o $@ $<
-
- $(OBJ) : g.h
-
- If we want to keep the objects in a separate directory, called objdir,
- then we would write something like this.
-
- SRC = a b
- OBJ = {$(SRC)}.o
-
- prgm : $(OBJ)
- cc $< -o $@
-
- $(OBJ) : g.h
- %.o : %.c
- $(CC) -c $(CFLAGS) -o $(@:f) $<
- mv $(@:f) objdir
-
- .SOURCE.o : objdir # tell dmake to look here for .o's
-
- An example of building library members would go something like this:
- (NOTE: The same rules as above will be used to produce .o's from .c's)
-
- SRC= a b
-
-
-
-Dmake Version 4.12 2008-02-26 48
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- LIB= lib
- LIBm= { $(SRC) }.o
-
- prgm: $(LIB)
- cc -o $@ $(LIB)
-
- $(LIB) .LIBRARY : $(LIBm)
- ar rv $@ $<
- rm $<
-
- Finally, suppose that each of the source files in the previous example
- had the `:' character in their target name. Then we would write the
- above example as:
-
- SRC= f:a f:b
- LIB= lib
- LIBm= "{ $(SRC) }.o" # put quotes around each token
-
- prgm: $(LIB)
- cc -o $@ $(LIB)
-
- $(LIB) .LIBRARY : $(LIBm)
- ar rv $@ $<
- rm $<
-
-COMPATIBILITY
- There are two notable differences between dmake and the standard ver-
- sion of BSD UNIX 4.2/4.3 Make.
-
- 1. BSD UNIX 4.2/4.3 Make supports wild card filename expansion
- for prerequisite names. Thus if a directory contains a.h,
- b.h and c.h, then a line like
-
- target: *.h
-
- will cause UNIX make to expand the *.h into "a.h b.h c.h".
- dmake does not support this type of filename expansion.
-
- 2. Unlike UNIX make, touching a library member causes dmake to
- search the library for the member name and to update the
- library time stamp. This is only implemented in the UNIX
- version. MSDOS and other versions may not have librarians
- that keep file time stamps, as a result dmake touches the
- library file itself, and prints a warning.
-
- dmake is not compatible with GNU Make. In particular it does not
- understand GNU Make's macro expansions that query the file system.
-
- dmake is fully compatible with SYSV AUGMAKE, and supports the following
- AUGMAKE features:
-
- 1. GNU Make style include, and if/else/endif directives are
- allowed in non-group recipes. Thus, the word include appear-
- ing at the start of a line that is not part of a gruop recipe
- will be mapped to the ".INCLUDE" directive that damke uses.
- Similarly, the words ifeq,ifneq,elif,else, and endif are
- mapped to their corresponding dmake equivalents.
-
- 2. The macro modifier expression $(macro:str=sub) is understood
- and is equivalent to the expression $(macro:s/str/sub), with
- the restriction that str must match the following regular
- expression:
-
- str[ |\t][ |\t]*
-
-
-
-Dmake Version 4.12 2008-02-26 49
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- (ie. str only matches at the end of a token where str is a
- suffix and is terminated by a space, a tab, or end of line)
- Normally sub is expanded before the substitution is made, if
- you specify -A on the command line then sub is not expanded.
-
- 3. The macro % is defined to be $@ (ie. $% expands to the same
- value as $@).
-
- 4. The AUGMAKE notion of libraries is handled correctly.
-
- 5. Directories are always made if you specify -A. This is con-
- sistent with other UNIX versions of Make.
-
- 6. Makefiles that utilize virtual targets to force making of
- other targets work as expected if AUGMAKE special target han-
- dling is enabled. For example:
-
- FRC:
- myprog.o : myprog.c $(FRC) ; ...
-
- Works as expected if you issue the command
-
- 'dmake -A FRC=FRC'
-
- but fails with a 'don't know how to make FRC' error message
- if you do not specify AUGMAKE special target handling via the
- -A flag (or by setting AUGMAKE:=yes internally).
-
-LIMITS
- In some environments the length of an argument string is restricted.
- (e.g. MSDOS command line arguments cannot be longer than 128 bytes if
- you are using the standard command.com command interpreter as your
- shell, dmake text diversions may help in these situations.)
-
-PORTABILITY
- To write makefiles that can be moved from one environment to another
- requires some forethought. In particular you must define as macros all
- those things that may be different in the new environment. dmake has
- two facilities that help to support writing portable makefiles, recur-
- sive macros and conditional expressions. The recursive macros, allow
- one to define environment configurations that allow different environ-
- ments for similar types of operating systems. For example the same
- make script can be used for SYSV and BSD but with different macro defi-
- nitions.
-
- To write a makefile that is portable between UNIX and MSDOS requires
- both features since in almost all cases you will need to define new
- recipes for making targets. The recipes will probably be quite differ-
- ent since the capabilities of the tools on each machine are different.
- Different macros will be needed to help handle the smaller differences
- in the two environments.
-
-FILES
- Makefile, makefile, startup.mk (use dmake -V to tell you where the
- startup file is)
-
-SEE ALSO
- sh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
- S.I. Feldman Make - A Program for Maintaining Computer Programs
-
-AUTHOR
- Dennis Vadura, dvadura@wticorp.com
- Many thanks to Carl Seger for his helpful suggestions, and to Trevor
- John Thompson for his many excellent ideas and informative bug reports.
-
-
-
-Dmake Version 4.12 2008-02-26 50
-
-
-
-
-
-DMAKE(1) DMAKE(1)
-
-
- Many thanks also go to those on the NET that have helped in making
- dmake one of the best Make tools available.
-
-BUGS
- Some system commands return non-zero status inappropriately. Use -i
- (`-' within the makefile) to overcome the difficulty.
-
- Some systems do not have easily accessible time stamps for library mem-
- bers (MSDOS, AMIGA, etc) for these dmake uses the time stamp of the
- library instead and prints a warning the first time it does so. This
- is almost always ok, except when multiple makefiles update a single
- library file. In these instances it is possible to miss an update if
- one is not careful.
-
- This man page is way too long.
-
-WARNINGS
- Rules supported by make(1) may not work if transitive closure is turned
- off (-T, .NOINFER).
-
- PWD from csh/ksh will cause problems if a cd operation is performed and
- -e or -E option is used.
-
- Using internal macros such as COMMAND, may wreak havoc if you don't
- understand their functionality.
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-Dmake Version 4.12 2008-02-26 51
-
-