summaryrefslogtreecommitdiff
path: root/dmake/man/dmake.tf
diff options
context:
space:
mode:
authorBjoern Michaelsen <bjoern.michaelsen@canonical.com>2013-02-25 11:56:21 +0100
committerNorbert Thiebaud <nthiebaud@gmail.com>2013-02-28 02:37:34 +0000
commit2b791f1cc51eaad25bd3464f94231fe4b236fae6 (patch)
tree64dd6453b3ce0487cb0aa7676545859388508edc /dmake/man/dmake.tf
parent9133cc452c9e473164755a2177b7a2285c09cb22 (diff)
remove dmake, build.pl, deliver.pl and zipdep.pl
This is writing history: LibreOffice builds in ONE non-recursive make process with full dependencies. We will now be able to really move forward without the old build system. A big 'Thank you!' goes out to everyone contributing to solenv/gbuild, especially: - David Tardon - Norbert Thiebaud - Tor Lillqvist - Michael Stahl - Matúš Kukan - Stephan Bergmann - Luboš Luňák - Caolán McNamara - Mathias Bauer - Jan Holesovsky - Peter Foley - Andras Timar - Hans-Joachim Lankenau and all the heroes migrating all the modules of LibreOffice to gbuild. By explicit request this commit has to be completed with this quote: I say we take off and nuke the entire site from orbit. It's the only way to be sure. Hold on a second. This installation has a substantial dollar value attached to it. They can bill me. Change-Id: I72fa17cfb24fae00ca78cfe0eb5782c1788d2dcc Reviewed-on: https://gerrit.libreoffice.org/2445 Tested-by: LibreOffice gerrit bot <gerrit@libreoffice.org> Reviewed-by: Niko Rönkkö <ronkko@iki.fi> Reviewed-by: Norbert Thiebaud <nthiebaud@gmail.com>
Diffstat (limited to 'dmake/man/dmake.tf')
-rw-r--r--dmake/man/dmake.tf3480
1 files changed, 0 insertions, 3480 deletions
diff --git a/dmake/man/dmake.tf b/dmake/man/dmake.tf
deleted file mode 100644
index 562e872120ae..000000000000
--- a/dmake/man/dmake.tf
+++ /dev/null
@@ -1,3480 +0,0 @@
-.\" Copyright (c) 1990,...,1995 Dennis Vadura, All rights reserved.
-.\"
-.\" You must use groff to format this man page!!!
-.\"
-.ds TB "0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.2i +0.5i +0.5i +2.0i
-.de Ip
-.sp \\n[PD]u
-.nf
-.nr dmake-indent \w@\\$1 @u
-.IP "\\$1" \\n[dmake-indent]u
-\\$2
-..
-.de Is
-.nr dmake-indent \w@\\$1@u
-.nf
-..
-.de Ii
-.PD 0
-.IP "\\$1" \\n[dmake-indent]u
-.it 1 PD
-..
-.TH DMAKE 1 "2008-02-26" "Dmake Version 4.12"
-.SH NAME
-\fBdmake\fR \- maintain program groups, or interdependent files
-.SH SYNOPSIS
-.nh
-.B dmake
-[\-P#] [\-{f|C|K} file] [\-{w|W} target ...]
-[macro[[!][*][+][:]]=\fIvalue\fP ...]
-[\-ABcdeEghiknpqrsStTuVxX] [\-v[cdfimrtw]] [\-m[trae]] [target ...]
-.hy 14
-.SH DESCRIPTION
-.PP
-.B dmake
-is a re-implementation of the UNIX Make utility with significant enhancements.
-.B dmake
-executes commands found in an external file called a
-.I makefile
-to update one or more target names.
-Each target may depend on zero or more prerequisite targets.
-If any of the target's prerequisites is newer than the target or if the target
-itself does not exist, then
-.B dmake
-will attempt to make the target.
-.PP
-If no
-.B \-f
-command line option is present then
-.B dmake
-searches for an existing
-.I makefile
-from the list of prerequisites specified for the special target \fI.MAKEFILES\fR
-(see the STARTUP section for more details).
-If "\-" is the name of the file specified to the
-.B \-f
-flag then \fBdmake\fR uses standard input as the source of the makefile text.
-.PP
-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 exceptions.
-.PP
-If no
-.I target
-names are specified on the command line, then \fBdmake\fR uses the first
-non-special target found in the makefile as the default target.
-See the
-.B "SPECIAL TARGETS"
-section for the list of special targets and their function.
-Makefiles written for most previous
-versions of
-.I Make
-will be handled correctly by
-.B dmake.
-Known differences between \fBdmake\fR and other versions of make
-are discussed in the
-.B COMPATIBILITY
-section found at the end of this document.
-.B dmake
-returns 0 if no errors were detected and a non-zero result if an error
-occurred.
-.SH OPTIONS
-.IP "\fB\-A\fR"
-Enable AUGMAKE special inference rule transformations
-(see the "PERCENT(%) RULES" and "AUGMAKE META RULES" sections), these are
-set to off by default.
-.IP "\fB\-B\fR"
-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.
-.IP "\fB\-c\fR"
-Use non-standard comment stripping. If you specify \fB\-c\fP then
-.B dmake
-will treat any \fB#\fP character as a start of comment character wherever it
-may appear unless it is escaped by a \e.
-.IP "\fB\-C [+]file\fR"
-This option writes to \fIfile\fP a copy of standard output and
-standard error from any child processes and from the
-.B dmake
-process itself. If you specify a \fB+\fP prior to the file name then
-the text is appended to the previous contents of \fIfile\fP.
-This option is active in the MSDOS implementation only and is ignored
-by non-MSDOS versions of
-.B dmake.
-.IP "\fB\-d\fR"
-Disable the use of the directory cache. Normally \fBdmake\fP caches directories
-as it checks file timestamps. Giving this flag is equivalent to the
-\&.DIRCACHE attribute or macro being set to \fIno\fP.
-.IP "\fB\-E\fR"
-Read the environment and define all strings of the
-form '\fBENV\-VAR\fP=\fIevalue\fP'
-defined within as macros whose name is \fBENV\-VAR\fP,
-and whose value is '\fIevalue\fP'.
-The environment is processed prior to processing the user
-specified makefile thereby allowing definitions in the makefile to override
-definitions in the environment.
-.IP "\fB\-e\fR"
-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.
-.IP "\fB\-f file\fR"
-Use \fBfile\fR as the source for the makefile text.
-Only one \fB\-f\fR option is allowed.
-.IP "\fB\-g\fR"
-Globally disable group recipe parsing, equivalent to the .IGNOREGROUP
-attribute or macro being set to \fIyes\fP at the start of the makefile.
-.IP "\fB\-h\fR"
-Print the command summary for \fBdmake\fR.
-.IP "\fB\-i\fR"
-Tells \fBdmake\fR to ignore errors, and continue making other targets.
-This is equivalent to the .IGNORE attribute or macro.
-.IP "\fB\-K file\fR"
-Turns on \fB.KEEP_STATE\fP state tracking and tells \fBdmake\fP to use
-\fIfile\fP as the state file.
-.IP "\fB\-k\fR"
-Causes \fBdmake\fR to ignore errors caused by command execution and to make
-all targets not depending on targets that could not be made.
-Ordinarily \fBdmake\fR stops after a command returns a non-zero status,
-specifying \fB\-k\fR causes \fBdmake\fR to ignore the error
-and continue to make as much as possible.
-.IP "\fB\-m[trae]\fR"
-Measure timing information. Print the time when targets and/or recipes
-are started and finished to stdout. The following format is used:
-.IP ""
-\fB{s|e} {target|recipe} time maketarget\fP
-.IP ""
-\fBs\fP or \fBe\fP stands for started or ended, \fBtarget\fP or
-\fBrecipe\fP denotes if this line refers to the whole target or a
-recipe. \fBtime\fP is displayed in Unix time format, i.e. the number
-of seconds since an epoch. (Since 1970-01-01T00:00:00Z). \fBmaketarget\fP
-obviously represents the target the timing information is given for.
-The optional flags \fB[trae]\fP can be used to change the information that
-is displayed. If no optional flags are given only the \fBt\fP flag
-is assumed to be selected, ie. \fB\-mt\fP. The optional flags stand for:
-.RS
-.IP "\fBt\fP"
-Display the start and end time of each target.
-.IP "\fBr\fP"
-Display the start and end time of each recipe.
-.IP "\fBa\fP"
-Display the target as an absolute path, i.e. prepend the current working
-directory.
-.IP "\fBe\fP"
-Also display the start and end time of the \fB$(shell command)\fP function
-(aka. shell escape) macros.
-.RE
-.IP "\fB\-n\fR"
-Causes \fBdmake\fR 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.
-.IP "\fB\-p\fR"
-Print out a version of the digested makefile in human readable form.
-(useful for debugging, but cannot be re-read by \fBdmake\fP)
-.IP "\fB\-P#\fR"
-On systems that support multi-processing cause \fBdmake\fP to use \fI#\fP
-concurrent child processes to make targets.
-See the "MULTI PROCESSING" section for more information.
-.IP "\fB\-q\fR"
-Check and see if the target is up to date. Exits with code 0 if up to date,
-1 otherwise.
-.IP "\fB\-r\fR"
-Tells \fBdmake\fR not to read the initial startup makefile, see STARTUP
-section for more details.
-.IP "\fB\-s\fR"
-Tells \fBdmake\fR to do all its work silently and not echo the commands it is
-executing to stdout (also suppresses warnings).
-This is equivalent to the .SILENT attribute or macro.
-.IP "\fB\-S\fR"
-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)
-.IP "\fB\-t\fR"
-Causes \fBdmake\fR 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.
-.IP "\fB\-T\fR"
-Tells \fBdmake\fP to not perform transitive closure on the inference graph.
-.IP "\fB\-u\fR"
-Force an unconditional update. (ie. do everything that would
-be done if everything that a target depended on was out of date)
-.IP "\fB\-v[cdfimrtw]\fR"
-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 \fB[cdfimrtw]\fP can be
-used to restrict the information that is displayed. In the absence of any
-optional flags all are assumed to be given (ie. \fB\-v\fP is equivalent to
-\fB\-vcdfimrtw\fP). The meanings of the optional flags are:
-.RS
-.IP "\fBc\fP"
-Notify of directory cache operations only.
-.IP "\fBd\fP"
-Notify of change directory operations only.
-.IP "\fBf\fP"
-Notify of file I/O operations only.
-.IP "\fBi\fP"
-Notify of inference algorithm operation only.
-.IP "\fBm\fP"
-Notify of target update operations only.
-.IP "\fBr\fP"
-Force output of recipe lines, warnings and executed commands. 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.
-.IP "\fBt\fP"
-Keep any temporary files created; normally they are automatically deleted.
-.IP "\fBw\fP"
-Notify of non-essential warnings (these are historical).
-.RE
-.IP "\fB\-V\fR"
-Print the version of \fBdmake\fR, and values of builtin macros.
-.IP "\fB\-W target\fR"
-Run \fBdmake\fP pretending that \fItarget\fP is out of date.
-.IP "\fB\-w target\fR"
-\fIWhat if?\fP Show what would be made if \fItarget\fP were out of date.
-.IP "\fB\-x\fR"
-Upon processing the user makefile export all non-internally defined macros
-to the user's environment. This option together with the \-e option
-allows SYSV AUGMAKE recursive makes to function as expected.
-.IP "\fB\-X\fR"
-Inhibit the execution of \fB#!\fP lines found at the beginning of a makefile.
-The use of this flag prevents non-termination of recursive make invocations.
-.SH 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.
-.IP \fBSTARTUP\fP 1.9i
-Describes \fBdmake\fP initialization.
-.IP \fBSYNTAX\fP 1.9i
-Describes the syntax of makefile expressions.
-.IP \fBATTRIBUTES\fP 1.9i
-Describes the notion of attributes and how they are used when
-making targets.
-.IP \fBMACROS\fP 1.9i
-Defining and expanding macros.
-.IP "\fBRULES AND TARGETS" 1.9i
-How to define targets and their prerequisites.
-.IP \fBRECIPES\fP 1.9i
-How to tell \fBdmake\fP how to make a target.
-.IP "\fBBUILTIN COMMANDS\fP" 1.9i
-Internal dmake commands.
-.IP "\fBTEXT DIVERSIONS\fP" 1.9i
-How to use text diversions in recipes and macro expansions.
-.IP "\fBVIRTUAL TARGETS\fP" 1.9i
-Targets that only enforce dependencies, but which can not create a target file.
-.IP "\fBSPECIAL TARGETS\fP" 1.9i
-Some targets are special.
-.IP "\fBSPECIAL MACROS\fP" 1.9i
-Macros used by \fBdmake\fP to alter the processing of the makefile,
-and those defined by \fBdmake\fP for the user.
-.IP "\fBCONTROL MACROS\fP" 1.9i
-Itemized list of special control macros.
-.IP "\fBRUNTIME MACROS\fP" 1.9i
-Discussion of special run-time macros such as $@ and $<.
-.IP "\fBFUNCTION MACROS\fP" 1.9i
-Description of functional macros.
-.IP "\fBCONDITIONAL MACROS\fP" 1.9i
-Target specific conditional macros.
-.IP "\fBDYNAMIC PREREQUISITES\fP" 1.9i
-Processing of prerequisites which contain macro expansions in their name.
-.IP "\fBBINDING TARGETS\fP" 1.9i
-The rules that \fBdmake\fP uses to bind
-a target to an existing file in the file system.
-.IP "\fBPERCENT(%) RULES\fP" 1.9i
-Specification of recipes to be used by the inference algorithm.
-.IP "\fBMAKING INFERENCES\fP" 1.9i
-The rules that \fBdmake\fP 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.
-.IP "\fBAUGMAKE META RULES\fP" 1.9i
-A subclass of the \fBPERCENT(%) RULES\fP.
-.IP "\fBMAKING TARGETS\fP" 1.9i
-How \fBdmake\fP makes targets other than libraries.
-.IP "\fBMAKING LIBRARIES\fP" 1.9i
-How \fBdmake\fP makes libraries.
-.IP "\fBKEEP STATE\fP" 1.9i
-A discussion of how .KEEP_STATE works.
-.IP "\fBMULTI PROCESSING\fP" 1.9i
-Discussion of \fBdmake's\fP parallel make facilities for architectures that
-support them.
-.IP "\fBCONDITIONALS\fP" 1.9i
-Conditional expressions which control the processing of the makefile.
-.IP "\fBEXAMPLES\fP" 1.9i
-Some hopefully useful examples.
-.IP "\fBCOMPATIBILITY\fP" 1.9i
-How \fBdmake\fP compares with previous versions of make.
-.IP "\fBLIMITS\fP" 1.9i
-Limitations of \fBdmake\fP.
-.IP \fBPORTABILITY\fP 1.9i
-Comments on writing portable makefiles.
-.IP \fBFILES\fP 1.9i
-Files used by \fBdmake\fP.
-.IP "\fBSEE ALSO\fP" 1.9i
-Other related programs, and man pages.
-.IP "\fBAUTHOR\fP" 1.9i
-The guy responsible for this thing.
-.IP \fBBUGS\fP 1.9i
-Hope not.
-.SH STARTUP
-When
-.B 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,
-.B dmake
-searches the following locations, in the order specified,
-until a startup file is located:
-.LP
-.RS
-.IP 1.
-The location given as the value of the macro
-MAKESTARTUP defined on the command line.
-.IP 2.
-The location given as the value of the environment variable MAKESTARTUP
-defined in the current environment.
-.IP 3.
-The location given as the value of the macro
-MAKESTARTUP defined internally within \fBdmake\fP. In this version, the
-internal definition of MAKESTARTUP is "$(DMAKEROOT)/startup.mk", so you
-can set the environment variable DMAKEROOT to the location of your startup
-directory.
-.sp
-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
-command line switch.
-.RE
-.LP
-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
-.B dmake
-looks for the default startup file, check your environment or issue the command
-\fI"dmake \-V"\fP.
-.PP
-A similar search is performed to locate a default user makefile when no
-\fB\-f\fP command line option is specified.
-By default, the prerequisite list of the special target .MAKEFILES
-specifies the names of possible makefiles and the search order that
-\fBdmake\fP should use to determine if one exists.
-A typical definition for this target is:
-.RS
-.sp
-\&.MAKEFILES : makefile.mk Makefile makefile
-.sp
-.RE
-\fBdmake\fP will first look for makefile.mk and then the others.
-If a prerequisite
-cannot be found \fBdmake\fP 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.
-.PP
-If the first line of the user makefile is of the form:
-.RS
-.sp
-#!command command_args
-.sp
-.RE
-then \fBdmake\fP will expand and run the command prior to reading any
-additional input. If the return code of the command is zero then \fBdmake\fP
-will continue on to process the remainder of the user makefile, if the return
-code is non-zero then dmake will exit.
-.PP
-\fBdmake\fP builds the internal dependency graph as it parses a user specified
-makefile. The graph is rooted at the special target \fB.ROOT\fP. .ROOT is the
-top level target that dmake builds when it starts to build targets. All user
-specified targets (those from the command line or taken as defaults from
-the makefile) are made prerequisites of the special target \fB.TARGETS\fP.
-\fBdmake\fP 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:
-.sp
-.RS
-\&.ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS .DONE
-.RE
-.sp
-with .INIT and .DONE defined as:
-.sp
-.RS
-\&.INIT .DONE .PHONY:;
-.RE
-.sp
-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 definition:
-.sp
-.RS
-\&.ROOT : .TARGETS
-.RE
-.sp
-which skips the preamble and postamble phases of building .TARGETS.
-.PP
-.B 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.
-.SH 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 \fBbold\fP type
-are text or names representing text supplied by the user.
-.sp 2
-.RS
-.Ip "Makefile" "\(-> { Statement }"
-.Ip "Statement" "\(-> Macro-Definition"
-\(-> Conditional-Macro-Definition
-\(-> Conditional
-\(-> Rule-Definition
-\(-> Attribute-Definition
-.Ip "Macro-Definition" "\(-> \fBMACRO = LINE\fP"
-\(-> \fBMACRO [\fB!\fR]*= LINE\fP
-\(-> \fBMACRO [\fB!\fR]:= LINE\fP
-\(-> \fBMACRO [\fB!\fR]*:= LINE\fP
-\(-> \fBMACRO [\fB!\fR]+= LINE\fP
-\(-> \fBMACRO [\fB!\fR]+:= LINE\fP
-.Ip "Conditional-Macro-Definition \(-> " "\fBTARGET\fP ?= Macro-Definition"
-.Ip "Conditional \(-> " "\fB\&.IF\fR expression"
- Makefile
-[ \fB.ELIF\fR expression
- Makefile ]
-[ \fB.ELSE\fR
- Makefile ]
-\fB\&.END\fR
-.Ip "expression" "\(-> \fBLINE\fR"
-\(-> \fBSTRING\fR
-\(-> expression \fB==\fR expression
-\(-> expression \fB!=\fR expression
-\(-> expression \fB<=\fR expression
-\(-> expression \fB>=\fR expression
-\(-> \fB(\fR expression \fB)\fR
-\(-> expression \fB||\fR expression
-\(-> expression \fB&&\fR expression
-.Ip "Rule-Definition \(-> " "target-definition"
- [ recipe ]
-.PP
-target-definition \(-> targets [attrs] op { \fBPREREQUISITE\fP } [\fB;\fR rcp-line]
-.Ip "targets" "\(-> target { targets }"
-\(-> \fB"\fRtarget\fB"\fR { targets }
-.Ip "target" "\(-> special-target"
-\(-> \fBTARGET\fR
-.Ip "attrs" "\(-> attribute { attrs }"
-\(-> \fB"\fRattribute\fB"\fR { attrs }
-.Ip "op" "\(-> \fB:\fR { modifier }"
-.Ip "modifier" "\(-> \fB:\fR"
-\(-> \fB^\fR
-\(-> \fB!\fR
-\(-> \fB\-\fR
-\(-> \fB|\fR
-.Ip "recipe" "\(-> { \fBTAB\fR rcp-line }"
-\(-> [\fB@\fR[\fB@\fR]][\fB%\fR][\fB\-\fR] \fB[
-.Is "recipe \(-> "
-.Ii " "
- \fR{ \fBLINE\fR }
-.Ii " "
-\fB]\fR
-.Ip "rcp-line" "\(-> [\fB@\fR[\fB@\fR]][\fB%\fR][\fB\-\fR][\fB+\fR] \fBLINE\fR"
-.Ip Attribute-Definition "\(-> attrs \fB:\fR targets"
-.Ip attribute "\(-> \fB.EPILOG\fR"
-\(-> \fB.ERRREMOVE\fR
-\(-> \fB.EXECUTE\fR
-\(-> \fB.GROUP\fR
-\(-> \fB.IGNORE\fR
-\(-> \fB.IGNOREGROUP\fR
-\(-> \fB.LIBRARY\fR
-\(-> \fB.MKSARGS\fR
-\(-> \fB.NOINFER\fR
-\(-> \fB.NOSTATE\fR
-\(-> \fB.PHONY\fR
-\(-> \fB.PRECIOUS\fR
-\(-> \fB.PROLOG\fR
-\(-> \fB.SETDIR=\fIpath\fP\fR
-\(-> \fB.SILENT\fR
-\(-> \fB.SEQUENTIAL\fR
-\(-> \fB.SWAP\fR
-\(-> \fB.USESHELL\fR
-\(-> \fB.SYMBOL\fR
-\(-> \fB.UPDATEALL\fR
-\(-> \fB.WINPATH\fR
-.Ip "special-target" "\(-> \fB.ERROR\fR"
-\(-> \fB.EXIT\fR
-\(-> \fB.EXPORT\fR
-\(-> \fB.GROUPEPILOG\fR
-\(-> \fB.GROUPPROLOG\fR
-\(-> \fB.IMPORT\fR
-\(-> \fB.INCLUDE\fR
-\(-> \fB.INCLUDEDIRS\fR
-\(-> \fB.MAKEFILES\fR
-\(-> \fB.REMOVE\fR
-\(-> \fB.ROOT\fR
-\(-> \fB.SOURCE\fR
-\(-> \fB.SOURCE.\fIsuffix\fR
-\(-> \fB.SUFFIXES (deprecated)\fR
-\(-> \fB.TARGETS\fR
-\(-> \fB.INIT\fR
-\(-> \fB.DONE\fR
-\(-> .\fIsuffix\fR
-\(-> .\fIsuffix1\fR.\fIsuffix2\fR
-.fi
-.RE
-.sp 1
-.PP
-Where, \fBTAB\fP represents a <tab> character, \fBSTRING\fP represents an
-arbitrary sequence of characters, and
-\fBLINE\fP represents a
-possibly empty sequence of characters terminated by a non-escaped
-(not immediately preceded by a backslash '\e') new-line character.
-\fBMACRO\fP, \fBPREREQUISITE\fP,
-and \fBTARGET\fP 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 \fBLINE\fP can be continued over several physical lines by terminating it with
-a single backslash character. Comments are initiated by the
-pound \fB#\fR 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 '\e' (ie. \e# translates to # when it is parsed).
-An exception to this occurs when a # is seen inside
-a recipe line that begins with a <tab> or is inside a group recipe.
-If you specify the \fB\-c\fP command line switch then this behavior is
-disabled and
-.B dmake
-will treat all # characters as start of comment indicators unless they
-are escaped by \e.
-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.
-.PP
-\fBwhite space\fP is defined to be any combination of
-<space>, <tab>, and the sequence \e<nl> when \e<nl> is used to terminate a
-LINE. \fBNote\fP the special treatment of \e<nl> in macro definion and recipe
-lines below.
-When processing \fBmacro definition\fP 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 \e<nl> sequence in a macro definition is deleted from the
-macro value before assigning this value.
-During \fBrecipe expansion\fP the sequence \e<nl> is treated as white space
-but is deleted from the final recipe string.
-You must escape the \e<nl> with another \e in order to get a \e at the end
-of a recipe or macro definition line.
-.PP
-When processing \fBtarget\fP definition lines,
-the recipe for a target must, in general, follow the first definition
-of the target (See the RULES AND TARGETS section for an exception), and
-the recipe may not span across multiple makefiles.
-Any targets and prerequisites found on a target definition line are taken
-to be white space separated tokens.
-The rule operator (\fIop\fP 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. \fBdmake\fP allows `:' to be present in
-target/prerequisite names as long as the entire target/prerequisite name is
-quoted. For example:
-.sp
-\ta:fred : test
-.sp
-would be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which
-is not what was intended. To fix this you must write:
-.sp
-\t"a:fred" : test
-.sp
-Which will be parsed as expected. Quoted target and prerequisite
-specifications may also contain white space thereby allowing the use of
-complex function macro expressions..
-See the EXAMPLES section for how to apply \fB"\fP quoting
-to a list of targets.
-.SH ATTRIBUTES
-.B 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
-\fBdmake\fP actions during target update.
-The recognized attributes are:
-.sp
-.IP \fB.EPILOG\fP 1.2i
-Insert shell epilog code when executing a group recipe associated with
-any target having this attribute set.
-.IP \fB.ERRREMOVE\fP 1.2i
-Always remove any target having this attribute if an error is encountered
-while making them. Setting this attribute overrides the .PRECIOUS attribute.
-.IP \fB.EXECUTE\fP 1.2i
-If the \-n flag was given then execute the recipe associated with any
-target having this attribute set.
-.IP \fB.FIRST\fP 1.2i
-Used in conjunction with .INCLUDE. Terminates the inclusion with the first
-successfully included prerequisite.
-.IP \fB.GROUP\fP 1.2i
-Force execution of a target's recipe as a group recipe.
-.IP \fB.IGNORE\fP 1.2i
-Ignore an error when trying to make any target with this attribute set.
-.IP \fB.IGNOREGROUP\fP 1.2i
-Disable the special meaning of '[' to initiate a group recipe.
-.IP \fB.LIBRARY\fP 1.2i
-Target is a library.
-.IP \fB.MKSARGS\fP 1.2i
-If running in an MSDOS environment then use MKS extended argument passing
-conventions to pass arguments to commands. Non-MSDOS
-environments ignore this attribute.
-.IP \fB.NOINFER\fP 1.2i
-Any target with this attribute set will not be subjected
-to transitive closure if it is inferred as a prerequisite
-of a target whose recipe and prerequisites are being inferred.
-(i.e. the inference algorithm will not use any prerequisite with this attribute
-set, as a target)
-If specified as '.NOINFER:' (ie. with no prerequisites or targets) then the
-effect is equivalent to specifying \fB\-T\fP on the command line.
-.IP \fB.NOSTATE\fP 1.2i
-Any target with this attribute set will not have command line flag
-information stored in the state file if .KEEP_STATE has been enabled.
-.IP \fB.PHONY\fP 1.2i
-Any target with this attribute set will have its recipe executed
-each time the target is made even if a file matching the target name can
-be located. Any targets that have a .PHONY attributed target as a
-prerequisite will be made each time the .PHONY attributed prerequisite is
-made.
-.IP \fB.PRECIOUS\fP 1.2i
-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 \fBdmake\fP.
-.IP \fB.PROLOG\fP 1.2i
-Insert shell prolog code when executing a group recipe associated with
-any target having this attribute set.
-.IP \fB.SEQUENTIAL\fP 1.2i
-Force a sequential make of the associated target's prerequisites. If set
-as a global attribute this implies setting MAXPROCESS=1.
-.IP \fB.SETDIR\fP 1.2i
-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 \fI.SETDIR=path\fP as the attribute. \fIpath\fP is expanded and
-the result is used as the value of the directory to change to.
-If \fIpath\fP contains \fB$$@\fP 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 \fIpath\fP contains any `:' characters then the entire attribute string
-must be quoted using ".
-If a target having this attribute set also has the .IGNORE
-attribute set then if the change to the specified directory fails it will be
-ignored, and no error message will be issued.
-.IP \fB.SILENT\fP 1.2i
-Do not echo the recipe lines when making any target with this attribute set,
-and do not issue any warnings.
-.IP \fB.SWAP\fP 1.2i
-Under MSDOS
-when making a target with this attribute set swap the \fBdmake\fP executable
-to disk prior to executing the recipe line. Also see the '%' recipe line
-flag defined in the RECIPES section.
-.IP \fB.SYMBOL\fP 1.2i
-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.
-.IP \fB.USESHELL\fP 1.2i
-Force each recipe line of a target to be executed using a shell.
-Specifying this attribute is equivalent to specifying the '+' character at the
-start of each line of a non-group recipe.
-.IP \fB.UPDATEALL\fP 1.2i
-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
-.I y.tab.c
-and
-.I y.tab.h
-files by
-.B 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, \fBdmake\fP internally sorts
-such targets in ascending alphabetical order and the value of $@ is always
-the first target in the sorted set.
-.IP \fB.WINPATH\fP 1.2i
-Switch between default (POSIX) and Windows style path representation.
-(This attribute is specific for cygwin dmake executables and non-cygwin
-environments ignore this attribute.)
-.sp
-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.
-.sp
-\fBNote\fP 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 \fBdmake\fP!) and cygwin, as well
-as native Windows, programs should have no problems using this (c:/foo/bar)
-path representation.
-.sp
-Example: Assuming the current target to be /tmp/mytarget the $@ macro
-without .WINPATH active expands to:
-.RS
-.sp
-.RS
-/tmp/mytarget
-.sp
-.RE
-With .WINPATH set it expands to:
-.sp
-.RS
-C:/cygwin/tmp/mytarget
-.RE
-.RE
-.LP
-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.
-.sp
-\tATTRIBUTE_LIST : \fItargets\fP
-.sp
-assigns the attributes specified by ATTRIBUTE_LIST to each target in
-.I targets
-or
-.sp
-\t\fItargets\fP ATTRIBUTE_LIST : ...
-.sp
-assigns the attributes specified by ATTRIBUTE_LIST to each target in
-.I targets.
-In the first form if
-.I 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 \fI".IGNORE :"\fP
-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.
-.PP
-Any attribute may be used with any target, even with the special targets.
-Some combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ),
-while others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain
-if file.mk cannot be found using the include file search rules,
-see the section on SPECIAL TARGETS for a description of .INCLUDE).
-If a specified attribute will not be used with the special target a warning
-is issued and the attribute is ignored.
-.SH MACROS
-.B dmake
-supports six forms of macro assignment.
-.sp
-.IP "\fBMACRO = LINE\fP" 1.55i
-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.
-.IP "\fBMACRO *= LINE\fP" 1.55i
-This form behaves exactly as the simple '=' form with the exception that if
-MACRO already has a value then the assignment is not performed.
-.IP "\fBMACRO := LINE\fP" 1.55i
-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.
-.IP "\fBMACRO *:= LINE\fP" 1.55i
-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.
-.IP "\fBMACRO += LINE\fP" 1.55i
-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.
-.IP "\fBMACRO +:= LINE\fP" 1.55i
-This form is similar to the '+=' form except that the value of LINE is expanded
-prior to being added to the value of MACRO.
-.PP
-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.
-.PP
-Each of the preceeding macro assignment operators may be prefixed by \fB!\fP
-to indicate that the assignment should be forced and that no warnings should
-be issued. Thus, specifying \fB!\fP has the effect of silently forcing the
-specified macro assignment.
-.PP
-When \fBdmake\fP defines a non-environment macro it strips leading and
-trailing white space from the macro value.
-Macros imported from the environment via either the .IMPORT special
-target (see the SPECIAL TARGETS section), or the \fB\-e\fP, or \fB\-E\fP flags
-are an exception to this rule. Their values are
-always taken literally and white space is never stripped.
-In addition, named macros defined using the .IMPORT special target do
-not have their values expanded when they are used within a makefile.
-In contrast, environment macros that are imported
-due to the specification of the \fB\-e\fP or \fB\-E\fP flags
-are subject to expansion when used.
-.PP
-To specify a macro expansion
-enclose the name in () or {} and precede it with a dollar sign $.
-Thus $(TEST) represents an expansion of the macro variable named TEST.
-If TEST is
-defined then $(TEST) is replaced by its expanded value. If TEST is not
-defined then $(TEST) expands to the NULL string (this is equivalent to
-defining a macro as 'TEST=' ). A short form may be used for single character
-named macros. In this case the parentheses are optional, and $(I) is
-equivalent to $I.
-Macro expansion is recursive, hence, if the value string contains an expression
-representing a macro expansion, the expansion is performed. Circular macro
-expansions are detected and cause an error to be issued.
-.PP
-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
-.sp
-\tCWD = $(PWD:b)
-.sp
-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:
-.sp
-\t_$(CWD).prt = list of files to print...
-.sp
-The actual name of the defined macro is a function of the current directory.
-A construct such as this is useful when processing a hierarchy of directories
-using .SETDIR attributed targets and a collection of small distributed
-makefile stubs.
-.PP
-Macro variables may be defined within the makefile, on the command
-line, or imported from the environment.
-.PP
-.B \fBdmake\fR
-supports several non-standard macro expansions:
-The first is of the form:
-.RS
-.IP \fI$(macro_name:modifier_list:modifier_list:...)\fR
-.RE
-.LP
-where
-.I modifier_list
-may be a combination of:
-.RS
-.sp
-.Is "b or B "
-.Ii "b or B"
-\- file (not including suffix) portion of path names
-.Ii "d or D"
-\- directory portion of all path names
-.Ii "e or E"
-\- suffix portion of path names
-.Ii "f or F"
-\- file (including suffix) portion of path names
-.Ii "i or I"
-\- inferred names of targets
-.Ii "n or N"
-\- normalized path names
-.Ii "l or L"
-\- macro value in lower case
-.Ii "u or U"
-\- macro value in upper case
-.Ii "1"
-\- return the first white space separated token from value
-.RE
-.sp
-or a single one of:
-.RS
-.sp
-.Ii "m or M"
-\- map escape codes found in macro to their ASCII value
-.Ii "s or S"
-\- simple pattern substitution
-.Ii "t or T"
-\- tokenization.
-.Ii "^"
-\- prepend a prefix to each token
-.Ii "+"
-\- append a suffix to each token
-.sp
-.RE
-.fi
-Thus if we have the example:
-.RS
-test = d1/d2/d3/a.out f.out d1/k.out
-.RE
-The following macro expansions produce the values on the right of '\(->' after
-expansion.
-.RS
-.sp
-.Is "$(test:s/out/in/:f) "
-.Ii "$(test:d)"
-\(-> d1/d2/d3/ d1/
-.Ii "$(test:b)"
-\(-> a f k
-.Ii "$(test:f)"
-\(-> a.out f.out k.out
-.Ii "${test:db}"
-\(-> d1/d2/d3/a f d1/k
-.Ii "${test:s/out/in/:f}"
-\(-> a.in f.in k.in
-.Ii $(test:f:t"+")
-\(-> a.out+f.out+k.out
-.Ii $(test:e)
-\(-> .out .out .out
-.Ii $(test:u)
-\(-> D1/D2/D3/A.OUT F.OUT D1/K.OUT
-.Ii $(test:1)
-\(-> d1/d2/d3/a.out
-.RE
-.fi
-.PP
-For this macro
-.RS
-test = d1/d2/../a.out "d1/file name.ext"
-.RE
-the following results are returned:
-.RS
-.sp
-.Is "$(test:s/out/in/:f) "
-.Ii "$(test:n)"
-\(-> d1/a.out "d1/file name.ext"
-.RE
-.fi
-.PP
-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
-\fB:d\fP 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.
-.PP
-The infered names of targets \fB:i\fP 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 following example:
-.RS
-test = aprog bprog
-.RE
-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:
-.RS
-.sp
-.Is "$(test:s/out/in/:f) "
-.Ii "$(test:i)"
-\(-> /tmp/aprog bprog
-.RE
-.fi
-.PP
-The normalized path names \fB:n\fP modifier honors the setting of .WINPATH to
-determine the output format of the result.
-.PP
-The map escape codes modifier changes the following escape codes \ea => <bel>,
-\&\eb => <backspace>, \ef => <formfeed>, \en => <nl>, \er => <cr>,
-\&\et => <tab>, \ev => <vertical tab>, \e" => ", and \exxx => <xxx> where
-xxx is the octal representation of a character into the corresponding ASCII
-value.
-.PP
-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.
-These modifiers may quote this string to include otherwise problematic
-characters. E.g. spaces, colons and parentheses.
-.PP
-The tokenization modifier takes all white space separated tokens from the
-macro value and separates them by the separator string. Thus the
-expansion:
-.LP
-.RS
-.nf
-$(test:f:t"+\en")
-.RE
-produces:
-.RS
-a.out+
-f.out+
-k.out
-.fi
-.RE
-.PP
-The prefix operator \fB^\fP takes all white space separated tokens from the
-macro value and prepends \fIstring\fP to each.
-.LP
-.RS
-.nf
-$(test:f:^mydir/)
-.RE
-produces:
-.RS
-mydir/a.out mydir/f.out mydir/k.out
-.fi
-.RE
-.PP
-The suffix operator \fB+\fP takes all white space separated tokens from the
-macro value and appends \fIstring\fP to each.
-.LP
-.RS
-.nf
-$(test:b:+.c)
-.RE
-produces:
-.RS
-a.c f.c k.c
-.fi
-.RE
-.PP
-The next non-standard form of macro expansion allows for recursive macros.
-It is possible to specify a $(\fImacro_name\fR) or ${\fImacro_name\fR} expansion
-where \fImacro_name\fR contains more $( ... ) or ${ ... } macro expansions
-itself.
-.PP
-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.
-.RS
-.sp
-.nf
-CFLAGS_VAX_CC = \-c \-O # _HOST == "_VAX", _COMPILER == "_CC"
-CFLAGS_PC_MSC = \-c \-ML # _HOST == "_PC", _COMPILER == "_MSC"
-.sp
-# redefine CFLAGS macro as:
-.sp
-CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
-.fi
-.sp
-.RE
-This causes CFLAGS to take on a value that corresponds to the
-environment in which the make is being invoked.
-.PP
-The final non-standard macro expansion is of the form:
-.RS
-.sp
-string1{token_list}string2
-.RE
-.LP
-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 token_list are.
-A null token in the token list
-is specified using "".
-Thus using another example we have:
-.RS
-.sp
-.Is "test/{f1 f2}.o "
-.Ii "test/{f1 f2}.o"
---> test/f1.o test/f2.o
-.Ii "test/ {f1 f2}.o"
---> test/ f1.o f2.o
-.Ii "test/{f1 f2} .o"
---> test/f1 test/f2 .o
-.Ii "test/{""f1"" """"}.o"
---> test/f1.o test/.o
-.sp
-.Ii and
-.sp
-.Is "test/{d1 d2}/{f1 f2}.o --> "
-.Ii "test/{d1 d2}/{f1 f2}.o --> "
-test/d1/f1.o test/d1/f2.o
-test/d2/f1.o test/d2/f2.o
-.sp
-.RE
-.fi
-This last expansion is activated only when the first characters of
-\fItoken_list\fP
-appear immediately after the opening '{' with no intervening white space.
-The reason for this restriction is the following incompatibility with
-Bourne Shell recipes. The line
-.RS
-.sp
-{ echo hello;}
-.sp
-.RE
-is valid /bin/sh syntax; while
-.RS
-.sp
-{echo hello;}
-.sp
-.RE
-.fi
-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
-\fBdmake\fP defines and understands.
-.SH "RULES AND TARGETS"
-A makefile contains a series of entries that specify dependencies.
-Such entries are called \fItarget/prerequisite\fP or \fIrule\fP 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
-.B dmake
-attempts to bring a target up to date and an explicit recipe is provided with
-a rule defining the target, that recipe is used to update the
-target. A rule definition begins with a line having the following syntax:
-.sp
-.RS
-.nf
-\fI<targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<prerequisites>\fP] [;\fI<recipe>\fP]
-.fi
-.RE
-.sp
-.I 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:
-.sp
-.RS
-\&.IMPORT .ERROR : ...
-.RE
-.sp
-is not allowed since both .IMPORT and .ERROR are special targets.
-Special targets are not used in the construction of the dependency graph and
-will not be made.
-.PP
-.I 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.
-.sp
-.IP NOTE: 0.75i
-As stated earlier,
-if both the target list and prerequisite list are empty but the attributes
-list is not, then the specified attributes affect all targets in the makefile.
-.sp
-.PP
-.I 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
-.B dmake
-handles the making of the associated targets.
-In its simplest form the operator is a single ':', and need not be separated
-by white space from its neighboring tokens. It may additionally be followed
-by any of the modifiers { !, ^, \-, :, | }, where:
-.sp
-.IP \fB!\fP
-says execute the recipe for the associated targets once for each out of date
-prerequisite. (The meaning of the runtime macro \fB$?\fP is changed, see
-below in the
-.B "RUNTIME MACROS"
-section.) Ordinarily the recipe is executed
-once for all out of date prerequisites at the same time.
-.IP \fB^\fP
-says to insert the specified prerequisites, if any, before any
-other prerequisites already associated with the specified targets.
-In general, it is not useful to specify ^ with an empty
-list of prerequisites.
-.IP \fB\-\fP
-says to clear the previous list of prerequisites before adding
-the new prerequisites. Thus,
-.sp
-\tfoo :
-.br
-\tfoo : bar baz
-.sp
-can be replaced by
-.sp
-\tfoo :\- bar baz
-.sp
-however the old form still works as expected.
-.IP \fB:\fP
-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.
-.sp
-When a target's rule operator is modified by a second ':'
-(:: for example) then this definition may not be the only
-definition with a recipe for the target. There may be other :: target
-definition lines that specify a different set of prerequisites with a
-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.
-.sp
-In the following simple example, each rule has a `::' \fIruleop\fP. In such an
-operator we call the first `:' the operator, and the second `:' the modifier.
-.sp
-.nf
-a.o :: a.c b.h
- first recipe for making a.o
-
-a.o :: a.y b.h
- second recipe for making a.o
-.fi
-.sp
-If a.o is found to be out of date with respect to a.c then the first recipe
-is used to make a.o. If it is found out of date with respect to a.y then
-the second recipe is used. If a.o is out of date with respect to
-b.h then both recipes are invoked to make a.o.
-In the last case the order of invocation corresponds to the order in which the
-rule definitions appear in the makefile.
-.IP \fB|\fP
-Is defined only for PERCENT rule target definitions. When specified it
-indicates that the following construct should be parsed using the old
-semantinc meaning:
-.sp
-.nf
-%.o :| %.c %.r %.f ; some rule
-.sp
-is equivalent to:
-.sp
-%.o : %.c ; some rule
-%.o : %.r ; some rule
-%.o : %.f ; some rule
-.fi
-.PP
-Targets defined using a single `:' operator
-with a recipe may be redefined again with a new recipe by using a
-`:' operator with a `:' modifier.
-This is equivalent to a 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 prerequisite list for the target.
-The `:' operator with no recipe always modifies the current list
-of prerequisites.
-Thus assuming each of the following definitions has a recipe attached, then:
-.RS
-.sp
-.nf
-joe : fred ... (1)
-joe :: more ... (2)
-.sp
-and
-.sp
-joe :: fred ... (3)
-joe :: more ... (4)
-.sp
-.fi
-.RE
-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:
-.RS
-.sp
-.nf
-joe :: fred ... (5)
-joe : more ... (6)
-.sp
-and
-.sp
-joe : fred ... (7)
-joe : more ... (8)
-.sp
-.fi
-.RE
-are errors since we have two sets of perfectly good recipes for
-making the target.
-.PP
-.I prerequisites
-is a possibly empty list of targets that must be brought up to date before
-making the current target.
-.PP
-.I recipe
-is a short form and allows the user to specify short rule definitions
-on a single line.
-It is taken to be the first recipe line in a larger recipe
-if additional lines follow the rule definition.
-If the semi-colon is present but the recipe line is empty (ie. null string)
-then it is taken
-to be an empty rule. Any target so defined causes target to be treated
-as a virtual target, see VIRTUAL TARGETS below.
-.SH "RECIPES"
-The traditional format used by most versions of Make defines the recipe
-lines as arbitrary strings that may contain macro expansions. They
-follow a rule definition line and may be spaced
-apart by comment or blank lines.
-The list of recipe lines defining the recipe is terminated by a new target
-definition, a macro definition, or end-of-file.
-Each recipe line
-.B MUST
-begin with a \fB<TAB>\fP character (or \fBspaces\fP, see \fB.NOTABS\fP)
-which may optionally be followed with one or all the following
-.I recipe property
-characters
-.IR "'@%+\-'"
-which affect the recipe execution:
-.IP "'\-'"
-indicates that non-zero exit values (ie. errors)
-are to be ignored when this recipe line is executed.
-.IP "'\+'"
-indicates that the current recipe line is to be executed using the shell. Group recipes implicitely ignore this property.
-.IP "'%'"
-indicates that
-.B dmake
-should swap itself out to secondary storage (MSDOS only) before running the
-recipe.
-.IP "'@'"
-indicates that the recipe line should NOT be echoed to the terminal prior to
-being executed.
-.IP "'@@'"
-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.
-.LP
-Each property is off by default
-(ie. by default, errors are significant, 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:
-.sp
-.RS
-.nf
-target :
-.RS
-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.
-.RE
-.fi
-.RE
-.PP
-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
-.I 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
-.B dmake
-invokes recipes.
-Here is an example of a group recipe:
-.sp
-.RS
-.nf
-target :
-[
- first recipe line
- second recipe line
- tall of these recipe lines are fed to a
- single copy of a shell for execution.
-]
-.fi
-.RE
-.sp
-.SH "BUILTIN COMMANDS"
-.B dmake
-supports some builtin commands. An optional leading '+' describes that
-the builtin can be used also when being executed in a shell otherwise 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.
-.IP "[\fB+\fP]\fBnoop\fP [\fBsomething\fP]"
-The \fBnoop\fP internal command always returns success if used but it is
-not executed even though the rest of the commandline is evaluated.
-This command can be used to evaluate macro expansions at the runtime of the
-recipe without starting a real commmand.
-.IP "[\fB+\fP]<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.
-.IP "\fBecho\fP [\fB-n\fP] \fBdata\fP"
-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.
-.PP
-No special treatment of buildin commands for group recipes is implemented
-even though the <empty recipe> will most propably also not be evaluated by
-most shells that can be used to handle the recipe groups.
-.SH "TEXT DIVERSIONS"
-.B dmake
-supports the notion of text diversions.
-If a recipe line contains the macro expression
-.RS
-.sp
-$(mktmp[,[\fIfile\fP][,\fItext\fP]] \fIdata\fP)
-.sp
-.RE
-then all text contained in the \fIdata\fP expression is expanded and
-is written to a temporary file. The \fIdata\fP in the file will always
-be terminated from a new line character. The \fIfile\fP 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 \fItext\fP
-parameter is defined. In this case the return value is the expanded value
-of \fItext\fP.
-.PP
-.I 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:
-.RS
-.sp
-$(mktmp $(XXX))
-.sp
-.RE
-is legal and works as expected, but:
-.RS
-.sp
-$(mktmp text (to dump to file)
-.sp
-.RE
-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:
-.RS
-.sp
-${mktmp text (to dump to file}
-.sp
-.RE
-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
-.B dmake
-run.
-If the \fIdata\fP text is to contain new lines the map escape codes macro
-expasion can be used. For example the expression:
-.RS
-.sp
-.nf
-mytext:=this is a\entest of the text diversion
-all:
- cat $(mktmp $(mytext:m))
-.fi
-.sp
-.RE
-is replaced by:
-.RS
-.sp
-cat /tmp/mk12294AA
-.sp
-.RE
-where the temporary file contains two lines both of which are terminated
-by a new-line.
-A second more illustrative example generates a response file to an MSDOS
-link command:
-.RS
-.sp
-.nf
-OBJ = fred.obj mary.obj joe.obj
-all : $(OBJ)
- link @$(mktmp $(^:t"+\en"))
-.fi
-.sp
-.RE
-The result of making `all' in the second example is the command:
-.RS
-.sp
-link @/tmp/mk02394AA
-.sp
-.RE
-where the temporary file contains:
-.RS
-.sp
-.nf
-fred.obj+
-mary.obj+
-joe.obj
-.fi
-.sp
-.RE
-The last line of the file is terminated by a new-line which is always
-inserted at the end of the \fIdata\fP string.
-.PP
-If the optional \fIfile\fP 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
-.RS
-.sp
-$(mktmp,turboc.cfg $(CFLAGS))
-.sp
-.RE
-will place the contents of CFLAGS into a local \fIturboc.cfg\fP file.
-The second optional argument, \fItext\fP, if present alters the name
-of the value returned by the $(mktmp ...) macro.
-.PP
-Under MS-DOS text diversions may be a problem. Many DOS tools require
-that path names which contain directories use the \e character to delimit
-the directories. Some users however wish to use the '/' to delimit pathnames
-and use environments that allow them to do so.
-The macro USESHELL is set to "yes" if the
-current recipe is forced to use a shell via the .USESHELL or '+' directives,
-otherwise its value is "no".
-The
-.B dmake
-startup files define the macro DIVFILE whose value is either the
-value of TMPFILE or the value of TMPFILE edited to replace any '/' characters
-to the appropriate value based on the current shell and whether it will be
-used to execute the recipe.
-.PP
-Previous versions of
-.B dmake
-defined text diversions using <+, +> strings,
-where <+ started a text diversion and +> terminated one.
-.B dmake
-is backward compatible with this construct only
-if the <+ and +> appear literally
-on the same recipe line or in the same macro value string. In such instances
-the expression:
-.sp
-\t<+data+>
-.sp
-is mapped to:
-.sp
-\t$(mktmp data)
-.sp
-which is fully output compatible with the earlier construct. <+, +>
-constructs whose text spans multiple lines must be converted by hand to use
-$(mktmp ...).
-.PP
-If the environment variable TMPDIR is defined then the
-temporary file is placed into the directory specified by that variable.
-A makefile can modify the location of temporary files by
-defining a macro named TMPDIR and exporting it using the .EXPORT special
-target.
-.SH "VIRTUAL TARGETS"
-.B 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 \fBdmake\fP tries to make a target, but only finds a target definition
-without recipe lines, it would normally issues
-a \fB"Don't know how to make ..."\fP 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 virtual target.
-.PP
-Virtual targets should not have a corresponding file therefore
-they inherit the time of their newest prerequisite if they have prerequisites,
-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.
-.SH "SPECIAL TARGETS"
-This section describes the special targets that are recognized by \fBdmake\fP.
-Some are affected by attributes and others are not.
-.IP \fB.ERROR\fP 1.4i
-If defined then the recipe associated with this target is executed
-whenever an error condition is detected by \fBdmake\fP. All attributes that
-can be used with any other target may be used with this target. Any
-prerequisites of this target will be brought up to date during its processing.
-NOTE: errors will be ignored while making this target, in extreme cases this
-may cause some problems.
-.IP \fB.EXIT\fP 1.4i
-If this target is encountered while parsing a makefile then the parsing of the
-makefile is immediately terminated at that point.
-.IP \fB.EXPORT\fP 1.4i
-All prerequisites associated with this target are assumed to
-correspond to macro names and they and their values
-are exported to the environment as environment strings at the point in
-the makefile at which this target appears.
-Any attributes specified with this target are ignored.
-Only macros which have been assigned a value in the makefile prior to the
-export directive are exported, macros as yet undefined
-or macros whose value contains any of the characters "+=:*"
-are not exported.
-.sp
-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).
-.IP \fB.IMPORT\fP 1.4i
-Prerequisite names specified for this target are searched for in the
-environment and defined as macros with their value taken from the environment.
-If the special name \fB.EVERYTHING\fP is used as a prerequisite name then
-all environment variables defined in the environment are imported.
-The functionality of the \fB\-E\fP flag can be forced by placing the construct
-\&\fI.IMPORT : .EVERYTHING\fP at the start of a makefile. Similarly, by
-placing the construct at the end, one can emulate the effect of the \fB\-e\fP
-command line flag.
-If a prerequisite name cannot be found in the environment
-an error message is issued.
-\&.IMPORT accepts the .IGNORE attribute. When given, it causes \fBdmake\fP
-to ignore the above error.
-See the MACROS section for a description of the processing of imported macro
-values.
-.IP \fB.INCLUDE\fP 1.4i
-Parse another makefile just as if it had been located at the point of the
-\&.INCLUDE in the current makefile.
-The list of prerequisites gives the list of
-makefiles to try to read. If the list contains multiple makefiles then they
-are read in order from left to right. The following search rules are used
-when trying to locate the file. If the filename is surrounded by " or just
-by itself then it is searched for in the current directory. If it is not
-found it is then searched for in each of the directories specified
-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 inference 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 .IGNORE attribute is given and the file
-cannot be found then \fBdmake\fP continues processing,
-otherwise an error message is generated.
-If the .NOINFER attribute is given and the file
-cannot be found then \fBdmake\fP will not attempt to
-\fIinfer and make\fP the file.
-The .SETDIR attribute causes
-.B dmake
-to change directories to the specified directory prior to attempting the
-include operation. If all fails \fBdmake\fP attempts to \fImake\fP the file
-to be included. If making the file fails then \fBdmake\fP terminates unless
-the .INCLUDE directive also specified the .IGNORE attribute.
-If .FIRST is specified along with .INCLUDE then \fBdmake\fP attempts to
-include each named prerequisite and will terminate the inclusion with the
-first prerequisite that results in a successful inclusion.
-.IP \fB.INCLUDEDIRS\fP 1.4i
-The list of prerequisites specified for this target defines the set of
-directories to search when trying to include a makefile.
-.IP \fB.KEEP_STATE\fP 1.4i
-This special target is a synonym for the macro definition
-.sp
-\&\t.KEEP_STATE := _state.mk
-.sp
-It's effect is to turn on STATE keeping and to define \fI_state.mk\fP
-as the state file.
-.IP \fB.MAKEFILES\fP 1.4i
-The list of prerequisites is the set of files to try to read as the default
-makefile. By default this target is defined as:
-.sp
-\t\&.MAKEFILES : makefile.mk Makefile makefile
-.sp
-.IP \fB.REMOVE\fP 1.4i
-The recipe of this target is used whenever \fBdmake\fP needs to remove
-intermediate targets that were made but do not need to be kept around.
-Such targets result from the application of transitive closure on the
-dependency graph.
-.IP \fB.ROOT\fP 1.4i
-The internal root of the dependency graph, see section STARTUP for details.
-.IP \fB.SOURCE\fP 1.4i
-The prerequisite list of this target defines a set of directories to check
-when trying to locate a target file name. See the section on BINDING of
-targets for more information.
-.IP \fB.SOURCE.suff\fP 1.4i
-The same as .SOURCE, except that the .SOURCE.suff list is searched first when
-trying to locate a file matching the a target whose name ends in the suffix
-\&.suff.
-.IP \fB.SUFFIXES\fP 1.4i
-This deprecated special target has no special meaning. Avoid its use.
-.IP \fB.TARGETS\fP 1.4i
-The internal targets that all user defined targets are prerequisites of,
-see section STARTUP for details.
-.PP
-There are a few targets that are "slightly" special:
-.RS
-.nf
-
-\&\fB.INIT\fP
-\&\fB.DONE\fP
-
-.fi
-.RE
-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).
-.PP
-.B 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.
-.PP
-In addition to the special targets above,
-several other forms of targets are recognized and are considered special,
-their exact form and use is defined in the sections that follow.
-.SH "SPECIAL MACROS"
-.B dmake
-defines a number of special macros. They are divided into three classes:
-control macros, run-time macros, and function macros.
-The control macros are used by
-.B dmake
-to configure its actions, and are the preferred method of doing so.
-In the case when a control macro has the same function as a special
-target or attribute they share the same name as the special target or
-attribute.
-The run-time macros are defined when
-.B dmake
-makes targets and may be used by the user inside recipes.
-The function macros provide higher level functions dealing with macro
-expansion and diversion file processing.
-.SH "CONTROL MACROS"
-To use the control macros simply assign them a value just like any other
-macro. The control macros are divided into three groups:
-string valued macros, character valued macros, and boolean valued macros.
-.PP
-The following are all of the string valued macros.
-This list is divided into two groups. The first group gives the string
-valued macros that are defined internally and cannot be directly set by the
-user.
-.IP \fBABSMAKECMD\fP 1.6i
-\fBWarning!\fP 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 systems or build with other compilers.
-.sp
-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.
-.IP \fBINCDEPTH\fP 1.6i
-This macro's value is a string of digits representing
-the current depth of makefile inclusion.
-In the first makefile level this value is zero.
-.IP \fBMFLAGS\fP 1.6i
-Is the list of flags
-that were given on the command line including a leading switch character.
-The \-f flag is not included in this list.
-.IP \fBMAKECMD\fP 1.6i
-Is the name with which \fBdmake\fP was invoked.
-.IP \fBMAKEDIR\fP 1.6i
-Is the full path to the initial directory in which
-.B dmake
-was invoked.
-.IP \fBMAKEFILE\fP 1.6i
-Contains the string "\-f \fImakefile\fP" where, \fImakefile\fP is the name
-of initial user makefile that was first read.
-.IP \fBMAKEFLAGS\fP 1.6i
-Is the same as $(MFLAGS) but has no leading switch
-character. (ie. MFLAGS = \-$(MAKEFLAGS))
-.IP \fBMAKEMACROS\fP 1.6i
-Contains the complete list of macro expressions that were specified on the
-command line.
-.IP \fBMAKETARGETS\fP 1.6i
-Contains the name(s) of the target(s), if any, that were
-specified on the command line.
-.IP \fBMAKEVERSION\fP 1.6i
-Contains a string indicating the current \fBdmake\fP version number.
-.IP \fBMAXPROCESSLIMIT\fP 1.6i
-Is a numeric string representing the maximum number of processes that
-\fBdmake\fP can use when making targets using parallel mode.
-.IP \fBNULL\fP 1.6i
-Is permanently defined to be the NULL string.
-This is useful when comparing a conditional expression to an NULL value.
-.IP \fBPWD\fP 1.6i
-Is the full path to the
-current directory in which make is executing.
-.IP \fBSPACECHAR\fP 1.6i
-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 function macro parameters.
-.IP \fBTMPFILE\fP 1.6i
-Is set to the name of the most recent temporary file opened by \fBdmake\fP.
-Temporary files are used for text diversions and for group recipe processing.
-.IP \fBTMD\fP 1.6i
-Stands for "To Make Dir", and
-is the path from the present directory (value of $(PWD)) to the directory
-that \fBdmake\fP was started up in (value of $(MAKEDIR)). If the present
-directory is the directory that \fBdmake\fP 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.
-.IP \fBUSESHELL\fP 1.6i
-The value of this macro is set to "yes" if the current recipe is forced to
-use a shell for its execution via the .USESHELL or '+' directives, its value
-is "no" otherwise.
-.sp
-.PP
-The second group of string valued macros control
-.B dmake
-behavior and may be set by the user.
-.IP \fB.DIRCACHE\fP 1.6i
-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).
-.IP \fB.DIRCACHERESPCASE\fP 1.6i
-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 Windows as the filesystems on
-this operating system are case insensitive and set to "yes" for all
-other operating systems. The default can be overriden, if desired.
-.sp
-\fBNote:\fP Using case insensitive directory caching on case sensitive
-file systems is a \fBBAD\fP idea. If in doubt use case sensitive
-directory caching even on case insensitive 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 \fBnever\fP a good idea.
-.IP \fBNAMEMAX\fP 1.6i
-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 systems the value of NAME_MAX is too short by default. Setting a new
-value for NAMEMAX will override the compiled value.
-.IP \fB.NOTABS\fP 1.6i
-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 condition of
-the above termination rule to terminate a
-non\-group recipe with a line that contains only white\-space.
-This mode does not effect the parsing of group recipes bracketed by [].
-.IP \fBAUGMAKE\fP 1.6i
-If set to "yes" value will enable the transformation of special
-meta targets to support special AUGMAKE inferences (See the "AUGMAKE
-META RULES" and "COMPATIBILITY" sections).
-.IP \fBDIRBRKSTR\fP 1.6i
-Contains the string of chars used to terminate
-the name of a directory in a pathname.
-Under UNIX its value is "/", under MSDOS its value is "/\e:".
-.IP \fBDIRSEPSTR\fP 1.6i
-Contains the string that is used to separate directory components when
-path names are constructed. It is defined with a default value at startup.
-.IP \fBDIVFILE\fP 1.6i
-Is defined in the startup file and gives the name that should be returned for
-the diversion file name when used in
-$(mktmp ...) expansions, see the TEXT DIVERSION section for details.
-.IP \fB.KEEP_STATE\fP 1.6i
-Assigning this macro a value tells
-.B dmake
-the name of the state file to use and turns on the keeping of state
-information for any targets that are brought up to date by the make.
-.IP \fBGROUPFLAGS\fP 1.6i
-This macro gives the set of flags to pass to the shell when
-invoking it to execute a group recipe. The value of the macro is the
-list of flags with a leading switch indicator. (ie. `\-' under UNIX)
-.IP \fBGROUPSHELL\fP 1.6i
-This macro defines the full
-path to the executable image to be used as the shell when
-processing group recipes. This macro must be defined if group recipes are
-used. It is assigned a default value in the startup makefile. Under UNIX
-this value is /bin/sh.
-.IP \fBGROUPSUFFIX\fP 1.6i
-If defined, this macro gives the string to use as a suffix
-when creating group recipe files to be handed to the command interpreter.
-For example, if it is defined as .sh, then all
-temporary files created by \fBdmake\fP will end in the suffix .sh.
-Under MSDOS if you are using command.com as your GROUPSHELL, then this suffix
-must be set to .bat in order for group recipes to function correctly.
-The setting of GROUPSUFFIX and GROUPSHELL is done automatically for
-command.com in the startup.mk files.
-.IP \fBMAKE\fP 1.6i
-Is defined in the startup file by default.
-Initially this macro is defined to have the value "$(MAKECMD) $(MFLAGS)".
-The string $(MAKE) is recognized when using the \-n switch.
-.IP \fBMAKESTARTUP\fP 1.6i
-This macro defines the full path to the initial startup
-makefile. Use the \fB\-V\fP command line option to discover its initial
-value.
-.IP \fBMAXLINELENGTH\fP 1.6i
-This macro defines the maximum size of a single line of
-makefile input text. The size is specified as a number, the default value
-is defined internally and is shown via the \fB\-V\fP option.
-A buffer of this size plus 2 is allocated for reading makefile text. The
-buffer is freed before any targets are made, thereby allowing files containing
-long input lines to be processed without consuming memory during the actual
-make.
-This macro can only be used to extend the line length beyond it's default
-minimum value.
-.IP \fBMAXPROCESS\fP 1.6i
-Specify the maximum number of child processes to use when making targets.
-The default value of this macro is "1" and its value cannot exceed the value
-of the macro MAXPROCESSLIMIT. Setting the value of MAXPROCESS on the command
-line or in the makefile is equivalent to supplying a corresponding value to
-the -P flag on the command line. 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.
-.IP \fBOOODMAKEMODE\fP 1.6i
-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 during target filename normalization (See BINDING TARGETS). If './'
-appear in the pathname, but not at the beginning of it, they are still
-removed by the normalization. Please note that targets that are given on the
-command line are going to be registered as default targets \fBafter\fP the
-startup file is read.
-.IP \fBPREP\fP 1.6i
-This macro defines the number of iterations to be expanded
-automatically when processing % rule definitions of the form:
-.sp
-% : %.suff
-.sp
-See the sections on PERCENT(%) RULES for details on how PREP is used.
-.IP \fBSHELL\fP 1.6i
-This macro defines the full path to the executable
-image to be used as the shell when
-processing single line recipes. This macro must be defined if recipes
-requiring the shell for execution are to be used.
-It is assigned a default value in the startup makefile.
-Under UNIX this value is /bin/sh.
-.IP \fBSHELLCMDQUOTE\fP 1.6i
-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 \fIcmd.exe\fP and \fIcommand.com\fP, it is assigned
-a value in the startup file.
-.IP \fBSHELLFLAGS\fP 1.6i
-This macro gives the set of flags to pass to the shell when
-invoking it to execute a single line recipe. The value of the macro is the
-list of flags with a leading switch indicator. (ie. `\-' under UNIX)
-.IP \fBSHELLMETAS\fP 1.6i
-Each time
-.B dmake
-executes a single recipe line (not a group recipe) the line is
-searched for any occurrence of a character defined in the value of SHELLMETAS.
-If such a character is found the recipe line is defined to require a shell
-to ensure its correct execution. In such instances
-a shell is used to invoke the recipe line.
-If no match is found the recipe line is executed without the use of a shell.
-.sp
-.PP
-There is only one character valued macro defined by \fBdmake\fP:
-\fBSWITCHAR\fP contains the switch character used
-to introduce options on command lines. For UNIX its value is `\-', and for
-MSDOS its value may be `/' or `\-'.
-The macro is internally defined and is not user setable.
-The MSDOS version of \fBdmake\fP attempts to first extract SWITCHAR from an
-environment variable of the same name. If that fails it then attempts to
-use the undocumented getswitchar system call, and returns the result of
-that. Under MSDOS version 4.0 you must set the value of the environment
-macro SWITCHAR to '/' to obtain predictable behavior.
-.PP
-All boolean macros currently understood by
-.B dmake
-correspond directly to the previously defined attributes.
-These macros provide
-a second way to apply global attributes, and represent the
-preferred method of doing so. They are used by assigning them a
-value. If the value is not a NULL string then the boolean condition
-is set to on.
-If the value is a NULL string then the condition is set to off.
-There are five conditions defined and they correspond directly to the
-attributes of the same name. Their meanings are defined in the ATTRIBUTES
-section above.
-The macros are:
-\&\fB.EPILOG\fP,
-\&\fB.IGNORE\fP,
-\&\fB.MKSARGS\fP,
-\&\fB.NOINFER\fP,
-\&\fB.PRECIOUS\fP,
-\&\fB.PROLOG\fP,
-\&\fB.SEQUENTIAL\fP,
-\&\fB.SILENT\fP,
-\&\fB.SWAP\fP, and
-\&\fB.USESHELL\fP.
-Assigning any of these a non NULL value will globally set
-the corresponding attribute to on.
-.SH "RUNTIME MACROS"
-These macros are defined
-when \fBdmake\fP is making targets, and may take on different values for each
-target. \fB$@\fP is defined to be the full target name, \fB$?\fP is the
-list of all out of date prerequisites, except for the \fB!\fP ruleop, in
-which case it is set to the current build
-prerequisite instead. \fB$&\fP is the list of all
-prerequisites, \fB$>\fP is the name of the library if the current target is a
-library member, and
-\fB$<\fP is the list of prerequisites specified in the current rule.
-If the current target had a recipe inferred then \fB$<\fP is the name of the
-inferred prerequisite even if the target had a list of prerequisites supplied
-using an explicit rule that did not provide a recipe. In such situations
-\fB$&\fP gives the full list of prerequisites.
-.PP
-\fB$*\fP is defined as
-\fB$(@:db)\fP when making targets with explicit recipes and is defined as the
-value of % when making targets whose recipe is the result of an inference.
-In the first case \fB$*\fP is the target name with no suffix,
-and in the second case, is the value of the matched % pattern from
-the associated %-rule.
-\fB$^\fP expands to the set of out of date prerequisites taken from the
-current value of \fB$<\fP.
-In addition to these,
-\fB$$\fP expands to $, \fB{{\fP expands to {, \fB}}\fP expands to }, and the
-strings \fB<+\fP and \fB+>\fP are recognized
-as respectively starting and terminating a text diversion when they appear
-literally together in the same input line.
-.PP
-The difference between $? and $^ can best be illustrated by an example,
-consider:
-.RS
-.sp
-.nf
-fred.out : joe amy hello
-\trules for making fred
-
-fred.out : my.c your.h his.h her.h # more prerequisites
-.fi
-.sp
-.RE
-Assume joe, amy, and my.c are newer then fred.out. When
-.B dmake
-executes the recipe for making fred.out the values of the following macros
-will be:
-.RS
-.sp
-.nf
-.Is "$@ "
-.Ii "$@"
---> fred.out
-.Ii "$*"
---> fred
-.Ii "$?"
---> joe amy my.c # note output of $? vs $^
-.Ii "$^"
---> joe amy
-.Ii "$<"
---> joe amy hello
-.Ii "$&"
---> joe amy hello my.c your.h his.h her.h
-.fi
-.sp
-.RE
-.SH "FUNCTION MACROS"
-.B dmake
-supports a full set of functional macros. One of these, the $(mktmp ...)
-macro, is discussed in detail in the TEXT DIVERSION section and is not
-covered here.
-The names of function macros must appear literally after the opening $(
-or ${. They are \fBnot\fP recognized if they are the result of a recursive
-expansion.
-.PP
-Note that some of these macros take comma separated parameters
-but that these parameters must not contain literal whitespaces. Whitespaces
-in macros used in these parameters are allowed.
-.RS
-.sp
-.IP "$(\fBand\fP \fBmacroterm ...\fP)"
-expands each \fBmacroterm\fP 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" otherwise it returns an empty string.
-.sp
-.IP "$(\fBassign\fP \fBexpression\fP)"
-Causes \fIexpression\fP 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. \fIexpression\fP 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 \fIexpression\fP is not a valid macro assignment expression.
-Some examples are:
-.RS
-.sp
-.nf
-$(assign foo := fred)
-$(assign $(ind_macro_name) +:= $(morejunk))
-.fi
-.RE
-.IP "$(\fBecho\fP \fBlist\fP)"
-Echo's the value of \fIlist\fP. \fIlist\fP is not expanded.
-.IP "$(\fBeq\fP,\fItext_a\fP,\fItext_b\fP \fBtrue\fP \fBfalse\fP)"
-expands
-.I text_a
-and
-.I text_b
-and compares their results. If equal it returns the result of the expansion
-of the
-.B true
-term, otherwise it returns the expansion of the
-.B false
-term.
-.IP "$(\fB!eq\fP,\fItext_a\fP,\fItext_b\fP \fBtrue\fP \fBfalse\fP)"
-Behaves identically to the previous macro except that the
-.B true
-string is chosen if the expansions of the two strings are not equal
-.IP "$(\fBforeach\fP,\fIvar\fP,\fIlist\fP \fBdata\fP)"
-Implements iterative macro expansion over \fIdata\fP using \fBvar\fP as the
-iterator taking on values from \fIlist\fP. \fIvar\fP and \fIlist\fP are
-expanded and the result is the concatenation of expanding \fIdata\fP with
-\fIvar\fP being set to each whitespace separated token from \fIlist\fP.
-For example:
-.RS
-.RS
-.sp
-.nf
-list = a b c
-all :; echo [$(foreach,i,$(list) [$i])]
-.fi
-.sp
-.RE
-will output
-.RS
-.sp
-.nf
-[[a] [b] [c]]
-.fi
-.sp
-.RE
-The iterator variable is defined as a local variable to this foreach
-instance. The following expression illustrates this:
-.RS
-.sp
-.nf
-$(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h])
-.fi
-.sp
-.RE
-when evaluated the result is:
-.RS
-.sp
-.nf
-[root/a/f.h] [root/b/f.h] [root/c/f.h]
-.fi
-.sp
-.RE
-The specification of list must be a valid macro expression, such as:
-.RS
-.sp
-.nf
-$($(assign list=a b c))
-$(sort d a b c)
-$(echo a b c)
-.fi
-.sp
-.RE
-and cannot just be the list itself. That is, the following foreach
-expression:
-.RS
-.sp
-.nf
-$(foreach,i,a b c [$i])
-.fi
-.sp
-.RE
-yields:
-.RS
-.sp
-.nf
-"b c [a]"
-.fi
-.sp
-.RE
-when evaluated.
-.RE
-.IP "$(\fBnil\fP \fBexpression\fP)"
-Always returns the value of $(NULL) regardless of what \fIexpression\fP is.
-This function macro can be used to discard results of expanding
-macro expressions.
-.IP "$(\fBnormpath\fP \fBlist\fP)"
-Will return the normalized path names of all white-space separated tokens
-in \fBlist\fP. 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.
-.IP "$(\fBnormpath,para\fP \fBlist\fP)"
-Same as above except that the expanded value of \fBpara\fP is used to
-override the .WINPATH setting.
-.IP "$(\fBnot\fP \fBmacroterm\fP)"
-expands \fBmacroterm\fP and returs the string "t" if the result of the
-expansion is the empty string; otherwise, it returns the empty string.
-.IP "$(\fBnull\fP,\fItext\fP \fBtrue\fP \fBfalse\fP)"
-expands the value of
-.I text.
-If it is NULL then the macro returns the value of the expansion of \fBtrue\fP
-and the expansion of \fBfalse\fP otherwise. The terms \fBtrue\fP, and
-\fBfalse\fP must be strings containing no white\-space.
-.IP "$(\fB!null\fP,\fItext\fP \fBtrue\fP \fBfalse\fP)"
-Behaves identically to the previous macro except that the
-.B true
-string is chosen if the expansion of
-.I text
-is not NULL.
-.IP "$(\fBor\fP \fBmacroterm ...\fP)"
-expands each \fBmacroterm\fP in turn and returs the empty string if
-each term expands to the empty string; otherwise, it returs the string
-"t".
-.IP "$(\fBshell\fP \fBcommand\fP)"
-is a shell escape macro. It runs \fIcommand\fP as if it were part of a
-recipe and returns, separated by a single space, all the non-white
-space terms written to stdout by the command.
-For example:
-.RS
-.RS
-.sp
-$(shell ls *.c)
-.sp
-.RE
-will return \fI"a.c b.c c.c d.c"\fP if the files exist in the current
-directory. The recipe modification flags \fB[+@%\-]\fP are honored if they
-appear as the first characters in the command. For example:
-.RS
-.sp
-$(shell +ls *.c)
-.sp
-.RE
-will run the command using the current shell.
-.LP
-\fBNote\fP that if the macro is part of a recipe it will be evaluated after
-all previous recipe lines have been executed. For obvious reasons it will be
-evaluated before the current recipe line or group recipe is executed.
-.RE
-.IP "$(\fBshell,expand\fP \fBcommand\fP)"
-Is an extension to the \fB$(shell command)\fP function macro that expands the
-result of running \fBcommand\fP.
-.IP "$(\fBsort\fP \fBlist\fP)"
-Will take all white\-space separated tokens in \fIlist\fP and will
-return their sorted equivalent list.
-.IP "$(\fBstrip\fP \fBdata\fP)"
-Will replace all strings of white\-space in data by a single space.
-.IP "$(\fBsubst\fP,\fIpat\fP,\fIreplacement\fP \fBdata\fP)"
-Will search for \fIpat\fP in
-.B data
-and will replace any occurrence of
-.I pat
-with the
-.I replacement
-string. The expansion
-.RS
-.sp
-$(subst,.o,.c $(OBJECTS))
-.sp
-.RE
-is equivalent to:
-.RS
-.sp
-$(OBJECTS:s/.o/.c/)
-.sp
-.RE
-.IP "$(\fBuniq\fP \fBlist\fP)"
-Will take all white\-space separated tokens in \fIlist\fP and will
-return their sorted equivalent list containing no duplicates.
-.sp
-.RE
-For historic reasons \fBdmake\fP treats the following case slightly special:
-.RS
-.sp
-$(\fBname\fP \fBsomething\fP)
-.sp
-.RE
-If it encounters a macro with a whitespace after \fBname\fP and \fBname\fP
-is not literally one of the above mentioned function macro identifiers then
-\fBdmake\fP will return the recursively expanded value of \fB$(name)\fP.
-The remaining \fBsomething\fP part will be expanded but the result will be
-discarded. The use of this special feature is deprecated and should not be
-used.
-.sp
-.SH "CONDITIONAL MACROS"
-.B dmake
-supports conditional macros. These allow the definition of target specific
-macro values. You can now say the following:
-.RS
-.sp
-\fBtarget\fP ?= \fIMacroName MacroOp Value\fP
-.sp
-.RE
-This creates a definition for \fIMacroName\fP whose value is \fIValue\fP
-only when \fBtarget\fP is being made. You may use a conditional macro
-assignment anywhere that a regular macro assignment may appear, including
-as the value of a $(assign ...) macro.
-.LP
-The new definition is associated with the most recent cell definition
-for \fBtarget\fP. If no prior definition exists then one is created. The
-implications of this are immediately evident in the following example:
-.sp
-.RS
-.nf
-foo := hello
-.sp
-all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]"
-.sp
-cond ?= bar := global decl
-.sp
-cond .SETDIR=unix::;@echo $(foo) $(bar)
-cond ?= foo := hi
-.sp
-cond .SETDIR=msdos::;@echo $(foo) $(bar)
- cond ?= foo := hihi
-.fi
-.RE
-.sp
-The first conditional assignment creates a binding for 'bar' that is
-activated when 'cond' is made. The bindings following the :: definitions 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.
-.LP
-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
-.sp
-.RS
-.nf
-mytarget ?= bar := hello
-mytarget ?= foo := $(bar)
-.fi
-.RE
-.sp
-results in $(foo) expanding to "", if you want the result to be "hello"
-you must use:
-.sp
-.RS
-.nf
-mytarget ?= bar := hello
-mytarget ?= foo = $(bar)
-.fi
-.RE
-.sp
-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.
-.LP
-If a %-meta rule target has associated conditional macro assignments,
-and the rule is chosen by the inference algorithm then the conditional
-macro assignments are inferred together with the associated recipe.
-.SH "DYNAMIC PREREQUISITES"
-.B dmake
-looks for prerequisites whose names contain macro expansions during target
-processing. Any such prerequisites are expanded and the result of the
-expansion is used as the prerequisite name. As an example the line:
-.sp
-\tfred : $$@.c
-.sp
-causes the $$@ to be expanded when \fBdmake\fP is making fred, and it resolves
-to the target \fIfred\fP.
-This enables dynamic prerequisites to be generated. The value
-of @ may be modified by any of the valid macro modifiers. So you can say for
-example:
-.sp
-\tfred.out : $$(@:b).c
-.sp
-where the $$(@:b) expands to \fIfred\fP.
-Note the use of $$ instead of $ to indicate the dynamic expansion, this
-is due to the fact that the rule line is expanded when it is initially parsed,
-and $$ then returns $ which later triggers the dynamic prerequisite expansion.
-Dynamic macro expansion is performed in all user defined rules, and the special
-targets .SOURCE*, and .INCLUDEDIRS.
-.PP
-\fBNOTE:\fP The use of a \fB$\fP as part of a prerequisite or target name is
-\fBstrongly discouraged\fP as the runtime macros (like $@) are expanded when
-used in a recipe line so that the $ is interpreted as a macro identifier and
-not as a character of the filename leading to invalid runtime macros.
-In addition to this no filename normalization is done for prerequisites and
-targets that contain $ characters.
-Nevertheless it is possible to use $ in prerequisites by using $$$$ but this
-is \fBnot recommended\fP and can lead to surprising results.
-.PP
-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 expansion the prerequisite
-list is fully expanded even if the dynamic prerequisite contained other
-runtime macros.
-.SH "BINDING TARGETS"
-This operation takes a target name and binds it to an existing file, if
-possible.
-.B dmake
-makes a distinction between the internal target name of a target and its
-associated external file name.
-Thus it is possible for a target's internal name and its external
-file name to differ.
-To perform the binding, the following set of rules is used.
-Assume that we are
-trying to bind a target whose name is of the form \fIX.suff\fP,
-where \fI.suff\fP is the suffix and \fIX\fP is the stem portion
-(ie. that part which contains the directory and the basename).
-.B dmake
-takes this target name and performs a series of search operations that try to
-find a suitably named file in the external file system.
-The search operation is user controlled
-via the settings of the various .SOURCE targets.
-.RS
-.IP 1.
-If target has the .SYMBOL attribute set then look for it in the library.
-If found, replace the target name with the library member name and continue
-with step 2. If the name is not found then return.
-.IP 2.
-Extract the suffix portion (that following the `.') of the target name.
-If the suffix is not null, look up the special target .SOURCE.<suff>
-(<suff> is the suffix).
-If the special target exists then search each directory given in
-the .SOURCE.<suff> prerequisite list for the target.
-If the target's suffix was null (ie. \fI.suff\fP was empty) then
-perform the above search but use the special target .SOURCE.NULL instead.
-If at any point a match is found then terminate the search.
-If a directory in the prerequisite list is the special name `.NULL ' perform
-a search for the full target name without prepending any directory portion
-(ie. prepend the NULL directory).
-.IP 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 \fBdmake\fP at startup,
-and is user redefinable)
-.IP 4.
-The search in step 3. failed.
-If the target has the library member attribute (.LIBMEMBER)
-set then try to find the target in the library which was passed along
-with the .LIBMEMBER attribute (see the MAKING LIBRARIES section).
-The bound file name assigned to a target which is successfully
-located in a library is the same name that would be assigned had the search
-failed (see 5.).
-.IP 5.
-The search failed. Either the target was not found in any of the search
-directories or no applicable .SOURCE special targets exist.
-If applicable .SOURCE special targets exist, but the target was not found,
-then \fBdmake\fP assigns the first name searched as the bound file name.
-If no applicable .SOURCE special targets exist,
-then the full original target name becomes the bound file name.
-.RE
-.PP
-There is potential here for a lot of search operations. The trick is to
-define .SOURCE.x special targets with short search lists and leave .SOURCE
-as short as possible.
-The search algorithm has the following useful side effect.
-When a target having the .LIBMEMBER (library member) attribute is searched for,
-it is first searched for as an ordinary file.
-When a number of library members require updating it is desirable to compile
-all of them first and to update the library at the end in a single operation.
-If one of the members does not compile and \fBdmake\fP stops, then
-the user may fix the error and make again. \fBdmake\fP will not remake any
-of the targets whose object files have already been generated as long as
-none of their prerequisite files have been modified as a result of the fix.
-.PP
-When \fBdmake\fP constructs target (and prerequisite) pathnames they are
-normalized 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 \fB$@\fP, but is infact the corect result.
-.PP
-\fBNOTE:\fP A cygwin \fBdmake\fP 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 surprising
-values of runtime macros.
-.PP
-When defining .SOURCE and .SOURCE.x targets the construct
-.RS
-.sp
-\&.SOURCE :
-.br
-\&.SOURCE : fred gery
-.sp
-.RE
-is equivalent to
-.RS
-.sp
-\&.SOURCE :\- fred gery
-.RE
-.PP
-\fBdmake\fP correctly handles the UNIX Make variable VPATH. By definition VPATH
-contains a list of ':' separated directories to search when looking for a
-target. \fBdmake\fP maps VPATH to the following special rule:
-.RS
-.sp
-\&.SOURCE :^ $(VPATH:s/:/ /)
-.sp
-.RE
-Which takes the value of VPATH and sets .SOURCE to the same set of directories
-as specified in VPATH.
-.SH "PERCENT(%) RULES AND MAKING INFERENCES"
-When \fBdmake\fP makes a target, the target's set of prerequisites (if any)
-must exist and the target must have a recipe which \fBdmake\fP
-can use to make it.
-If the makefile does not specify an explicit recipe for the target then
-.B dmake
-uses special rules to try to infer a recipe which it can use
-to make the target. Previous versions of Make perform this task by using
-rules that are defined by targets of the form .<suffix>.<suffix> (this is still
-supported, see "AUGMAKE META RULES") or by using the \fBnot supported\fP by
-dmake .SUFFIXES list of suffixes (see "SPECIAL TARGETS" for more details
-about .SUFFIXES). The exact workings of this mechanism
-were sometimes difficult to understand and often limiting in their usefulness.
-Instead, \fBdmake\fP supports the concept of \fI%-meta\fP rules.
-The syntax and semantics of these rules differ from standard rule lines as
-follows:
-.sp
-.nf
-.RS
-\fI<%-targets>\fP [\fI<attributes>\fP] \fI<ruleop>\fP [\fI<%-prereqs>\fP] [;\fI<recipe>\fP]
-.RE
-.fi
-.sp
-where \fI%-targets\fP are one or more targets containing exactly a single `%'
-sign,
-.I attributes
-is a list (possibly empty) of attributes,
-.I ruleop
-is the standard set of rule operators,
-.I "%-prereqs"
-\&, if present, is a list of prerequisites containing zero or more `%' signs,
-and
-.I recipe,
-if present, is the first line of the recipe.
-.PP
-If more than one %-target is present this line is equivalent to a repetition
-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 \fI<%-target>\fP as
-\fI%-targets\fP are divided into multiple definitions with a single %-target.
-.PP
-\fBNOTE:\fP 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 \fBnow\fP works.
-.PP
-The
-.I %-target
-defines a pattern against which a target whose recipe is
-being inferred gets matched. The pattern match goes as follows: all chars are
-matched exactly from left to right up to but not including the % sign in the
-pattern, % then matches the longest string from the actual target name
-not ending in
-the suffix given after the % sign in the pattern.
-Consider the following examples:
-.RS
-.sp
-.nf
-.Is "dir/%.c "
-.Ii "%.c"
-matches fred.c but not joe.c.Z
-.Ii "dir/%.c"
-matches dir/fred.c but not dd/fred.c
-.Ii "fred/%"
-matches fred/joe.c but not f/joe.c
-.Ii "%"
-matches anything
-.fi
-.sp
-.RE
-In each case the part of the target name that matched the % sign is retained
-and is substituted for any % signs in the prerequisite list of the %-meta rule
-when the rule is selected during inference and
-.B dmake
-constructs the new dependency.
-.PP
-.B 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.
-.PP
-As an example the following %-meta rules describe the following:
-.RS
-.sp
-%.c : %.y ; recipe...
-.sp
-.RE
-describes how to make any file ending in .c if a corresponding file ending
-in .y can be found.
-.RS
-.sp
-foo%.o : fee%.k ; recipe...
-.sp
-.RE
-is used to describe how to make fooxxxx.o from feexxxx.k.
-.RS
-.sp
-%.a :; recipe...
-.sp
-.RE
-describes how to make a file whose suffix is .a without inferring any
-prerequisites.
-.RS
-.sp
-%.c : %.y 'yaccsrc/%.y' ; recipe...
-.sp
-.RE
-matches the corresponding .y file as prerequisite and additionally another .y
-file in the yaccsrc subdirectory as indirect prerequisite.
-Another interesting example is:
-.RS
-.sp
-% : RCS/%,v ; co $<
-.sp
-.RE
-which describes how to take any target and check it out of
-the RCS directory if the corresponding file exists in the RCS directory.
-The equivalent SCCS rule would be:
-.RS
-.sp
-% : s.% ; get $<
-.sp
-.RE
-.PP
-The previous RCS example defines an infinite rule, because it says how to make
-.I anything
-from RCS/%,v, and
-.I anything
-also includes RCS/fred.c,v.
-To limit the size of the graph that results from such rules
-.B dmake
-uses the macro variable PREP (stands for % repetition). By default the value
-of this variable is 0, which says that no repetitions of a %-rule are to be
-generated. If it is set to something greater than 0, then that many
-repetitions of any infinite %-rule are allowed. If in the above
-example PREP was set to 1, then \fBdmake\fP would generate the dependency
-graph:
-.RS
-.sp
-% --> RCS/%,v --> RCS/RCS/%,v,v
-.sp
-.RE
-Where each link is assigned the same recipe as the first link.
-PREP should be used only in special cases, since it may result in
-a large increase in the number of possible prerequisites tested.
-.B dmake
-further assumes that any target that has no suffix can be made from
-a prerequisite that has at least one suffix.
-.PP
-.B dmake
-supports dynamic prerequisite generation for prerequisites of %-meta rules.
-This is best illustrated by an example. The RCS rule shown above can infer
-how to check out a file from a corresponding RCS file only if the target
-is a simple file name with no directory information. That is, the above rule
-can infer how to find \fIRCS/fred.c,v\fP from the target \fIfred.c\fP,
-but cannot infer how to find \fIsrcdir/RCS/fred.c,v\fP from \fIsrcdir/fred.c\fP
-because the above rule will cause \fBdmake\fP to look for RCS/srcdir/fred.c,v;
-which does not exist (assume that srcdir has its own RCS directory as is the
-common case).
-.PP
-A more versatile formulation of the above RCS check out rule is the following:
-.RS
-.sp
-% : $$(@:d)RCS/$$(@:f),v : co $@
-.sp
-.RE
-This rule uses the dynamic macro $@ to specify the prerequisite to try to
-infer. During inference of this rule the macro $@ is set to the value of
-the target of the %-meta rule and the appropriate prerequisite is generated by
-extracting the directory portion of the target name (if any), appending the
-string \fIRCS/\fP to it, and appending the target file name with a trailing
-\fI,v\fP attached to the previous result.
-.PP
-.B dmake
-can also infer indirect prerequisites.
-An inferred target can have a list of prerequisites added that will not
-show up in the value of $< but will show up in the value of $? and $&.
-Indirect prerequisites are specified in an inference rule by quoting the
-prerequisite with single quotes. For example, if you had the explicit
-dependency:
-.RS
-.sp
-.nf
-fred.o : fred.c ; rule to make fred.o
-fred.o : local.h
-.fi
-.sp
-.RE
-then this can be inferred for fred.o from the following inference rule:
-.RS
-.sp
-%.o : %.c 'local.h' ; makes a .o from a .c
-.sp
-.RE
-You may infer indirect prerequisites that are a function of the value of '%'
-in the current rule. The meta-rule:
-.RS
-.sp
-%.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
-.sp
-.RE
-infers an indirect prerequisite found in the INC directory whose name is the
-same as the expansion of $(INC), and the prerequisite name depends on the
-base name of the current target.
-The set of indirect prerequisites is attached to the meta rule in which they
-are specified and are inferred only if the rule is used to infer a recipe
-for a target. They do not play an active role in driving the inference
-algorithm.
-The construct:
-.RS
-.sp
-%.o :| %.c %.f 'local.h'; recipe
-.sp
-.RE
-is equivalent to:
-.RS
-.sp
-.nf
-%.o : %.c 'local.h' ; recipe
-%.o : %.f 'local.h' ; recipe
-.fi
-.sp
-.RE
-.PP
-If any of the attributes .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
-.B dmake
-changes to that directory prior to performing the inference.
-During inference any .SETDIR attributes for the inferred prerequisite
-are honored.
-The directories must exist for a %-meta rule to be selected as a possible
-inference path. If the directories do not exist no error message is issued,
-instead the corresponding path in the inference graph is rejected.
-.PP
-.B dmake
-bases all of its inferences on the inference graph constructed from the
-%-rules defined in the makefile.
-It knows exactly which targets can be made from which prerequisites by
-making queries on the inference graph.
-.PP
-For a %-meta rule to be inferred as the
-rule whose recipe will be used to make a target, the target's name must match
-the %-target pattern, and any inferred %-prerequisite must already exist or
-have an explicit recipe so that the prerequisite can be made.
-Without \fItransitive closure\fP on the inference graph the above rule
-describes precisely when an inference match terminates the search.
-If transitive closure is enabled (the usual case), and a prerequisite does
-not exist or cannot be made, then
-.B dmake
-invokes the inference algorithm recursively on the prerequisite to see if
-there is some way the prerequisite can be manufactured. For, if the
-prerequisite can be made then the current target can also be made using the
-current %-meta rule.
-This means that there is no longer a need to give a rule
-for making a .o from a .y if you have already given a rule for making a .o
-from a .c and a .c from a .y. In such cases
-.B dmake
-can infer how to make the
-\&.o from the .y via the intermediary .c and will remove the .c when the .o is
-made. Transitive closure can be disabled by giving the \-T switch on the
-command line.
-.PP
-A word of caution.
-.B dmake
-bases its transitive closure on the %-meta rule targets.
-When it performs transitive closure it infers how to make a target from a
-prerequisite by performing a pattern match as if the potential prerequisite
-were a new target.
-The set of rules:
-.RS
-.nf
-.sp
-%.o : %.c ; rule for making .o from .c
-%.c : %.y ; rule for making .c from .y
-% : RCS/%,v ; check out of RCS file
-.fi
-.sp
-.RE
-will, by performing transitive closure, allow \fBdmake\fP to infer how to make
-a .o from a .y using a .c as an intermediate temporary file. Additionally
-it will be able to infer how to make a .y from an RCS file, as long as that
-RCS file is in the RCS directory and has a name which ends in .y,v.
-The transitivity computation is performed dynamically for each target that
-does not have a recipe. This has potential to be costly if the %-meta
-rules are not carefully specified. The .NOINFER attribute is used to mark
-a %-meta node as being a final target during inference. Any node with this
-attribute set will not be used for subsequent inferences. As an example
-the node RCS/%,v is marked as a final node since we know that if the RCS file
-does not exist there likely is no other way to make it. Thus the standard
-startup makefile contains an entry similar to:
-.RS
-.nf
-\&.NOINFER : RCS/%,v
-.fi
-.RE
-Thereby indicating that the RCS file is the end of the inference chain.
-Whenever the inference algorithm determines that a target can be made from
-more than one prerequisite and the inference chains for the two methods
-are the same length the algorithm reports an ambiguity and prints the
-ambiguous inference chains.
-.PP
-.B dmake
-tries to
-remove intermediate files resulting from transitive closure if the file
-is not marked as being PRECIOUS, or the \fB\-u\fP flag was not given on the
-command line, and if the inferred intermediate did not previously exist.
-Intermediate targets that existed prior to being made are never removed.
-This is in keeping with the philosophy that
-.B dmake
-should never remove things from the file system that it did not add.
-If the special target .REMOVE is defined and has a recipe then
-.B dmake
-constructs a list of the intermediate files to be removed and makes them
-prerequisites of .REMOVE. It then makes .REMOVE thereby removing the
-prerequisites if the recipe of .REMOVE says to. Typically .REMOVE is defined
-in the startup file as:
-.RS
-.sp
-\&.REMOVE :; $(RM) $<
-.RE
-.SH "AUGMAKE META RULES"
-As a subclass of the meta targets that is actually mapped to %-meta rules
-.B dmake
-understands several SYSV AUGMAKE targets transformations. This .<suffix>
-special target construct transforms into the following %-meta rules:
-.RS
-.sp
-\&.suff :; recipe
-.sp
-.RE
-gets mapped into:
-.RS
-.sp
-% : %.suff; recipe
-.sp
-.RE
-.PP
-.B dmake
-also supports the old format special target .<suffix>.<suffix>
-by identifying any rules
-of this form and mapping them to the appropriate %-rule. So for example if
-an old makefile contains the construct:
-.RS
-.sp
-\&.c.o :; cc \-c $< \-o $@
-.sp
-.RE
-.B dmake
-maps this into the following %-rule:
-.RS
-.sp
-%.o : %.c; cc \-c $< \-o $@
-.sp
-.RE
-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
-.RS
-.sp
-\&.c~.o :; recipe
-.sp
-.RE
-gets mapped into:
-.RS
-.sp
-%.o : s.%.c ; recipe
-.sp
-.RE
-In general, a special target of the form .<str>~ is replaced by the %-rule
-construct s.%.<str>, thereby providing support for the syntax used by SYSV
-AUGMAKE for providing SCCS support.
-When enabled, these mappings allow processing of existing SYSV
-makefiles without modifications.
-.RE
-.SH "MAKING TARGETS"
-In order to update a target \fBdmake\fP must execute a recipe.
-When a recipe needs to be executed it is first expanded so that any macros
-in the recipe text are expanded, and it is then either executed directly or
-passed to a shell.
-.B dmake
-supports two types of recipes. The regular recipes and group recipes.
-.PP
-When a regular recipe is invoked \fBdmake\fP executes each line of the recipe
-separately using a new copy of a shell if a shell is required.
-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 \fBMSDOS\fP, where dmake internally
-sets the current working director to match the directory it was in before
-the command was executed.
-.PP
-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 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 \fBdmake\fP constructs the command line:
-.sp
-\t$(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
-.sp
-If the $(SHELLCMDQUOTE) macro is set its value is inserted before and after
-the $(expanded_recipe_command) string.
-.sp
-Normally
-.B 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.
-.PP
-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
-.B 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 ].
-.PP
-The recipe flags [+,\-,%,@] are recognized at the start of a recipe line
-even if they appear in a macro. For example:
-.RS
-.sp
-.nf
-SH = +
-all:
-\t$(SH)echo hi
-.fi
-.sp
-.RE
-is completely equivalent to writing
-.RS
-.sp
-.nf
-SH = +
-all:
-\t+echo hi
-.fi
-.sp
-.RE
-.PP
-The last step performed by
-.B 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.
-.B dmake
-then expands the macro COMMAND which by default is set to
-.RS
-.sp
-COMMAND = $(CMNDNAME) $(CMNDARGS)
-.sp
-.RE
-The result of this final expansion is the command that will be executed.
-The reason for this expansion is to allow for a different interface to
-the argument passing facilities (esp. under DOS) than that provided by
-.B dmake\fR.\fP
-You can for example define COMMAND to be
-.RS
-.sp
-COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
-.sp
-.RE
-which dumps the arguments into a temporary file and runs the command
-.RS
-.sp
-$(CMNDNAME) @/tmp/ASAD23043
-.sp
-.RE
-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
-.B 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.
-.SH "MAKING LIBRARIES"
-Libraries are easy to maintain using \fBdmake\fP. A library is a file
-containing a collection of object files.
-Thus to make a library you simply specify it as a target with the .LIBRARY
-attribute set and specify its list of prerequisites. The prerequisites should
-be the object members that are to go into the library. When
-.B 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.
-.B dmake
-now supports \fBElf\fP libraries on systems that support \fBElf\fP and
-hence supports, on those systems, long member file names.
-A small example best illustrates this.
-.RS
-.nf
-.sp
-mylib.a .LIBRARY : mem1.o mem2.o mem3.o
-\trules for making library...
-\t# remember to remove .o's when lib is made
-.sp
-# equivalent to: '%.o : %.c ; ...'
-\&.c.o :; rules for making .o from .c say
-.sp
-.fi
-.RE
-.B dmake
-will use the .c.o rule for making the library members if appropriate .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 example.
-.PP
-.B dmake
-tries to handle the old library construct format in a sensible way.
-The construct
-.I lib(member.o)
-is separated and the \fIlib\fP portion is declared
-as a library target.
-The new target is defined
-with the .LIBRARY attribute set and the \fImember.o\fP portion of the
-construct is
-declared as a prerequisite of the lib target.
-If the construct \fIlib(member.o)\fP
-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:
-.RS
-.sp
-.nf
-a.out : ml.a(a.o) ml.a(b.o); $(CC) \-o $@ $<
-
-\&.c.o :; $(CC) \-c $(CFLAGS) \-o $@ $<
-%.a:
-.RS
-ar rv $@ $?
-ranlib $@
-rm \-rf $?
-.RE
-.sp
-.fi
-.RE
-constructs the following dependency
-graph.
-.RS
-.sp
-.nf
-a.out : ml.a; $(CC) \-o $@ $<
-ml.a .LIBRARY : a.o b.o
-
-%.o : %.c ; $(CC) -c $(CFLAGS) \-o $@ $<
-%.a :
-.RS
-ar rv $@ $?
-ranlib $@
-rm -rf $?
-.RE
-.sp
-.fi
-.RE
-and making a.out then works as expected.
-.PP
-The same thing happens for any target of the form \fIlib((entry))\fP.
-These targets have an
-additional feature in that the \fIentry\fP target has the .SYMBOL attribute
-set automatically.
-.PP
-NOTE: If the notion of entry points is supported by the archive and by
-\fBdmake\fP (currently not the case) then
-.B 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 \fIentry\fP and will be used for
-making the member 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 makefile utilizing this
-feature (possibly due to the fact that it is unimplemented in most versions
-of UNIX Make).
-.PP
-Finally, when
-.B 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
-.B dmake\fR.\fP
-.SH "KEEP STATE"
-.B 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
-.B dmake
-to test compile different versions of the source using different compilers.
-Changing the compiler causes the compilation flags to be modified and hence
-all sources to be recompiled.
-.PP
-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.
-.PP
-The Sun Microsystem's Make construct
-.RS
-.sp
-\&.KEEP_STATE :
-.sp
-.RE
-is recognized and is mapped to \fB.KEEP_STATE:=_state.mk\fP.
-The
-.B dmake
-version 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.
-.B dmake
-instead provides the tool, \fBcdepend\fP, to scan C source files and to produce
-depedency information. Users are free to modify cdepend to produce other
-dependency files. (NOTE:
-.B cdepend
-does not come with the distribution at this time, but will be available in
-a patch in the near future)
-.SH "MULTI PROCESSING"
-If the architecture supports it then \fBdmake\fP is capable of making a target's
-prerequisites in parallel. \fBdmake\fP will make as much in parallel as it
-can and use a number of child processes up to the maximum specified 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.
-\fBdmake\fP guarantees that all dependencies as specified in the makefile are
-honored. A target will not be made until all of its prerequisites have been
-made. Note that when you specify \fB-P 4\fP then four child processes are
-run concurrently but \fBdmake\fP 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.
-.RS
-.IP 1.
-Individual recipe lines in a non-group recipe are performed sequentially in
-the order in which they are specified within the makefile and in parallel with
-the recipes of other targets.
-.IP 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.
-.IP 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.
-.IP 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.
-.RE
-.PP
-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 correspond to that displayed by the \-n flag.
-.SH "CONDITIONALS"
-.B dmake
-supports a makefile construct called a \fIconditional\fR. 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 target
-host and environment. The conditional expression is specified as follows:
-.sp
-.RS
-.nf
-\&.IF \fIexpression\fR
- ... if text ...
-\&.ELIF \fIexpression\fR
- ... if text ...
-\&.ELSE
- ... else text ...
-\&.END
-.RE
-.fi
-.sp
-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.
-.PP
-\fIexpression\fR can be one of the following forms:
-.sp
-String evaluation
-.br
-\t<text> | <text> == <text> | <text> != <text>
-.sp
-Numeric evaluation
-.br
-\t<text> <= <text> | <text> >= <text>
-.sp
-Boolean evaluation
-.br
-\t( <text> ) | <text> || <text> | <text> && <text>
-.sp
-where \fItext\fR 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 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.
-.SH "EXAMPLES"
-.RS
-.nf
-.sp
-# 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 $@
-.fi
-.RE
-.sp
-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 concisely
-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:
-.sp
-\&\t%.o : %.c; cc \-c $(CFLAGS) \-o $@ $<
-.sp
-Since there exists a rule (defined in the startup file)
-for making .o's from .c's
-\fBdmake\fR will use that rule
-for manufacturing a .o from a .c and we can specify our dependencies
-more concisely.
-.sp
-.RS
-.nf
-prgm : a.o b.o
- cc \-o prgm $<
-a.o b.o : g.h
-.fi
-.RE
-.sp
-A more general way to say the above using the new macro expansions
-would be:
-.sp
-.RS
-.nf
-SRC = a b
-OBJ = {$(SRC)}.o
-.sp
-prgm : $(OBJ)
- cc \-o $@ $<
-.sp
-$(OBJ) : g.h
-.fi
-.RE
-.sp
-If we want to keep the objects in a separate directory, called
-objdir, then we would write
-something like this.
-.sp
-.RS
-.nf
-SRC = a b
-OBJ = {$(SRC)}.o
-.sp
-prgm : $(OBJ)
- cc $< \-o $@
-.sp
-$(OBJ) : g.h
-\&%.o : %.c
- $(CC) \-c $(CFLAGS) \-o $(@:f) $<
- mv $(@:f) objdir
-
-\&.SOURCE.o : objdir # tell dmake to look here for .o's
-.fi
-.RE
-.sp
-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)
-.sp
-.RS
-.nf
-SRC\t= a b
-LIB\t= lib
-LIBm\t= { $(SRC) }.o
-.sp
-prgm: $(LIB)
- cc \-o $@ $(LIB)
-.sp
-$(LIB) .LIBRARY : $(LIBm)
- ar rv $@ $<
- rm $<
-.fi
-.RE
-.sp
-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:
-.sp
-.RS
-.nf
-SRC\t= f:a f:b
-LIB\t= lib
-LIBm\t= "{ $(SRC) }.o" # put quotes around each token
-.sp
-prgm: $(LIB)
- cc \-o $@ $(LIB)
-.sp
-$(LIB) .LIBRARY : $(LIBm)
- ar rv $@ $<
- rm $<
-.fi
-.RE
-.SH "COMPATIBILITY"
-There are two notable differences between
-.B \fBdmake\fR
-and the standard version of BSD UNIX 4.2/4.3 Make.
-.RS
-.IP 1. .3i
-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
-.sp
-\ttarget: *.h
-.sp
-will cause UNIX make to expand the *.h into "a.h b.h c.h". \fBdmake\fR
-does not support this type of filename expansion.
-.IP 2. .3i
-Unlike UNIX make, touching a library member causes \fBdmake\fR
-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 \fBdmake\fR touches the library file itself, and prints a warning.
-.RE
-.PP
-\fBdmake\fP is not compatible with GNU Make. In particular it does not
-understand GNU Make's macro expansions that query the file system.
-.PP
-.B dmake
-is fully compatible with SYSV AUGMAKE, and supports the following AUGMAKE
-features:
-.RS
-.IP 1. .3i
-GNU Make style \fBinclude\fP, and \fBif/else/endif\fP directives are allowed
-in non-group recipes.
-Thus, the word \fBinclude\fP appearing at
-the start of a line that is not part of a gruop recipe will be mapped
-to the ".INCLUDE" directive that \fBdamke\fP uses.
-Similarly, the words \fBifeq\fP,\fBifneq\fP,\fBelif\fP,\fBelse\fP,
-and \fBendif\fP are mapped to their corresponding \fBdmake\fP equivalents.
-.IP 2. .3i
-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:
-.sp
-\tstr[ |\et][ |\et]*
-.sp
-(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 \fIsub\fP is expanded before the substitution is made, if you specify
-\-A on the command line then sub is not expanded.
-.IP 3.
-The macro % is defined to be $@ (ie. $% expands to the same value as $@).
-.IP 4.
-The AUGMAKE notion of libraries is handled correctly.
-.IP 5.
-Directories are always made if you specify \fB\-A\fP. This is consistent
-with other UNIX versions of Make.
-.IP 6.
-Makefiles that utilize virtual targets to force making of other targets work
-as expected if AUGMAKE special target handling is enabled. For example:
-.sp
-.nf
-\tFRC:
-\tmyprog.o : myprog.c $(FRC) ; ...
-.fi
-.sp
-Works as expected if you issue the command
-.sp
-\t'\fBdmake\fP \-A FRC=FRC'
-.sp
-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).
-.RE
-.SH "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,
-.B dmake
-text diversions may help in these situations.)
-.SH "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.
-.B dmake
-has two facilities that help to support writing portable makefiles, recursive
-macros and conditional expressions. The recursive macros, allow one to define
-environment configurations that allow different environments for similar types
-of operating systems. For example the same make script can be used for SYSV and
-BSD but with different macro definitions.
-.PP
-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 different 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.
-.SH FILES
-Makefile, makefile, startup.mk (use dmake \-V to tell you where the startup
-file is)
-.SH "SEE ALSO"
-sh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
-.br
-S.I. Feldman \fIMake - A Program for Maintaining Computer Programs\fP
-.SH "AUTHOR"
-Dennis Vadura, dvadura@wticorp.com
-.br
-Many thanks to Carl Seger for his helpful suggestions,
-and to Trevor John Thompson for his many excellent ideas and
-informative bug reports. Many thanks also go to those on the
-NET that have helped in making \fBdmake\fP one of the best Make tools
-available.
-.SH BUGS
-Some system commands return non-zero status inappropriately.
-Use
-.B \-i
-(`\-' within the makefile) to overcome the difficulty.
-.PP
-Some systems do not have easily accessible
-time stamps for library members (MSDOS, AMIGA, etc)
-for these \fBdmake\fR 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.
-.PP
-This man page is way too long.
-.SH WARNINGS
-Rules supported by make(1) may not work if transitive closure is turned off
-(-T, .NOINFER).
-.PP
-PWD from csh/ksh will cause problems if a cd operation is performed and
--e or -E option is used.
-.PP
-Using internal macros such as COMMAND, may wreak havoc if you don't understand
-their functionality.