| <HTML><head><TITLE>Manpage of DMAKE 4.3</TITLE> |
| </head><body> |
| <H1>DMAKE - Version 4.3</H1> |
| <A HREF="#index">Index</A> |
| <HR> |
| |
| <A NAME="lbAB"> </A> |
| <H2>NAME</H2> |
| |
| <B>dmake</B> - maintain program groups, or interdependent files |
| <A NAME="lbAC"> </A> |
| <H2>SYNOPSIS</H2> |
| |
| <B>dmake</B> |
| |
| [-P#] [-{f|C|K} file] [-{w|W} target ...] |
| [macro[[!][*][+][:]]=<I>value</I> ...] |
| [-v{cdfimrtw}] [-ABcdeEghiknpqrsStTuVxX] [target ...] |
| <A NAME="lbAD"> </A> |
| <H2>DESCRIPTION</H2> |
| |
| <P> |
| |
| <B>dmake</B> |
| |
| is a re-implementation of the UNIX Make utility with significant enhancements. |
| <B>dmake</B> |
| |
| executes commands found in an external file called a |
| <I>makefile</I> |
| |
| 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</B> |
| |
| will attempt to make the target. |
| <P> |
| |
| If no |
| <B>-f</B> |
| |
| command line option is present then |
| <B>dmake</B> |
| |
| searches for an existing |
| <I>makefile</I> |
| |
| from the list of prerequisites specified for the special target <I>.MAKEFILES</I> |
| (see the STARTUP section for more details). |
| If "-" is the name of the file specified to the |
| <B>-f</B> |
| |
| flag then <B>dmake</B> uses standard input as the source of the makefile text. |
| <P> |
| |
| 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. |
| <P> |
| |
| If no |
| <I>target</I> |
| |
| names are specified on the command line, then <B>dmake</B> uses the first |
| non-special target found in the makefile as the default target. |
| See the |
| <B>SPECIAL TARGETS</B> |
| |
| section for the list of special targets and their function. |
| Makefiles written for most previous |
| versions of |
| <I>Make</I> |
| |
| will be handled correctly by |
| <B>dmake.</B> |
| |
| Known differences between <B>dmake</B> and other versions of make |
| are discussed in the |
| <B>COMPATIBILITY</B> |
| |
| section found at the end of this document. |
| <B>dmake</B> |
| |
| returns 0 if no errors were detected and a non-zero result if an error |
| occurred. |
| <A NAME="lbAE"> </A> |
| <H2>OPTIONS</H2> |
| |
| <DL COMPACT> |
| <DT><B>-A</B><DD> |
| Enable AUGMAKE special inference rule transformations |
| (see the "PERCENT(%) RULES" section), these are set to off by default. |
| <DT><B>-B</B><DD> |
| 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. |
| <DT><B>-c</B><DD> |
| Use non-standard comment stripping. If you specify <B>-c</B> then |
| <B>dmake</B> |
| |
| will treat any <B>#</B> character as a start of comment character wherever it |
| may appear unless it is escaped by a \. |
| <DT><B>-C [+]file</B><DD> |
| This option writes to <I>file</I> a copy of standard output and |
| standard error from any child processes and from the |
| <B>dmake</B> |
| |
| process itself. If you specify a <B>+</B> prior to the file name then |
| the text is appended to the previous contents of <I>file</I>. |
| This option is active in the MSDOS implementation only and is ignored |
| by non-MSDOS versions of |
| <B>dmake.</B> |
| |
| <DT><B>-d</B><DD> |
| Disable the use of the directory cache. Normally <B>dmake</B> caches directories |
| as it checks file timestamps. Giving this flag is equivalent to the |
| .DIRCACHE attribute or macro being set to <I>no</I>. |
| <DT><B>-E</B><DD> |
| Read the environment and define all strings of the |
| form '<B>ENV-VAR</B>=<I>evalue</I>' |
| defined within as macros whose name is <B>ENV-VAR</B>, |
| and whose value is '<I>evalue</I>'. |
| The environment is processed prior to processing the user |
| specified makefile thereby allowing definitions in the makefile to override |
| definitions in the environment. |
| <DT><B>-e</B><DD> |
| 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. |
| <DT><B>-f file</B><DD> |
| Use <B>file</B> as the source for the makefile text. |
| Only one <B>-f</B> option is allowed. |
| <DT><B>-g</B><DD> |
| Globally disable group recipe parsing, equivalent to the .IGNOREGROUP |
| attribute or macro being set to <I>yes</I> at the start of the makefile. |
| <DT><B>-h</B><DD> |
| Print the command summary for <B>dmake</B>. |
| <DT><B>-i</B><DD> |
| Tells <B>dmake</B> to ignore errors, and continue making other targets. |
| This is equivalent to the .IGNORE attribute or macro. |
| <DT><B>-K file</B><DD> |
| Turns on <B>.KEEP_STATE</B> state tracking and tells <B>dmake</B> to use |
| <I>file</I> as the state file. |
| <DT><B>-k</B><DD> |
| Causes <B>dmake</B> to ignore errors caused by command execution and to make |
| all targets not depending on targets that could not be made. |
| Ordinarily <B>dmake</B> stops after a command returns a non-zero status, |
| specifying <B>-k</B> causes <B>dmake</B> to ignore the error |
| and continue to make as much as possible. |
| <DT><B>-n</B><DD> |
| Causes <B>dmake</B> 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. |
| <DT><B>-p</B><DD> |
| Print out a version of the digested makefile in human readable form. |
| (useful for debugging, but cannot be re-read by <B>dmake</B>) |
| <DT><B>-P#</B><DD> |
| On systems that support multi-processing cause <B>dmake</B> to use <I>#</I> |
| concurrent child processes to make targets. |
| See the "MULTI PROCESSING" section for more information. |
| <DT><B>-q</B><DD> |
| Check and see if the target is up to date. Exits with code 0 if up to date, |
| 1 otherwise. |
| <DT><B>-r</B><DD> |
| Tells <B>dmake</B> not to read the initial startup makefile, see STARTUP |
| section for more details. |
| <DT><B>-s</B><DD> |
| Tells <B>dmake</B> 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. |
| <DT><B>-S</B><DD> |
| Force sequential execution of recipes on architectures which support |
| concurrent makes. For backward compatibility with old makefiles that have |
| nasty side-effect prerequisite dependencies. |
| <DT><B>-t</B><DD> |
| Causes <B>dmake</B> 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. |
| <DT><B>-T</B><DD> |
| Tells <B>dmake</B> to not perform transitive closure on the inference graph. |
| <DT><B>-u</B><DD> |
| Force an unconditional update. (ie. do everything that would |
| be done if everything that a target depended on was out of date) |
| <DT><B>-v[cdfimrtw]</B><DD> |
| 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 <B>[cdfimrtw]</B> can be |
| used to restrict the information that is displayed. In the absence of any |
| optional flags all are assumed to be given (ie. <B>-v</B> is equivalent to |
| <B>-vdfimt</B>). The meanings of the optional flags are: |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT><B>c</B><DD> |
| Notify of directory cache operations only. |
| <DT><B>d</B><DD> |
| Notify of change directory operations only. |
| <DT><B>f</B><DD> |
| Notify of file I/O operations only. |
| <DT><B>i</B><DD> |
| Notify of inference algorithm operation only. |
| <DT><B>m</B><DD> |
| Notify of target update operations only. |
| <DT><B>r</B><DD> |
| Force output of recipe lines and warnings. This switch is usefull when |
| debugging makefiles that disable the output using the @ sign for recipe |
| lines or the .SILENT target/attribute. It also overrides the -s flag. |
| <DT><B>t</B><DD> |
| Keep any temporary files created; normally they are automatically deleted. |
| <DT><B>w</B><DD> |
| Notify of non-essential warnings (these are historical). |
| </DL> |
| </DL> |
| |
| <DT><B>-V</B><DD> |
| Print the version of <B>dmake</B>, and values of builtin macros. |
| <DT><B>-W target</B><DD> |
| Run <B>dmake</B> pretending that <I>target</I> is out of date. |
| <DT><B>-w target</B><DD> |
| <I>What if?</I> Show what would be made if <I>target</I> were out of date. |
| <DT><B>-x</B><DD> |
| 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. |
| <DT><B>-X</B><DD> |
| Inhibit the execution of <B>#!</B> lines found at the beginning of a makefile. |
| The use of this flag prevents non-termination of recursive make invocations. |
| </DL> |
| <A NAME="lbAF"> </A> |
| <H2>INDEX</H2> |
| |
| 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. |
| <DL COMPACT> |
| <DT><B>STARTUP</B><DD> |
| Describes <B>dmake</B> initialization. |
| <DT><B>SYNTAX</B><DD> |
| Describes the syntax of makefile expressions. |
| <DT><B>ATTRIBUTES</B><DD> |
| Describes the notion of attributes and how they are used when |
| making targets. |
| <DT><B>MACROS</B><DD> |
| Defining and expanding macros. |
| <DT><B>RULES AND TARGETS<DD> |
| How to define targets and their prerequisites. |
| <DT>RECIPES</B><DD> |
| How to tell <B>dmake</B> how to make a target. |
| <DT><B>TEXT DIVERSIONS</B><DD> |
| How to use text diversions in recipes and macro expansions. |
| <DT><B>SPECIAL TARGETS</B><DD> |
| Some targets are special. |
| <DT><B>SPECIAL MACROS</B><DD> |
| Macros used by <B>dmake</B> to alter the processing of the makefile, |
| and those defined by <B>dmake</B> for the user. |
| <DT><B>CONTROL MACROS</B><DD> |
| Itemized list of special control macros. |
| <DT><B>RUNTIME MACROS</B><DD> |
| Discussion of special run-time macros such as $@ and $<. |
| <DT><B>FUNCTION MACROS</B><DD> |
| GNU style function macros, only $(mktmp ...) for now. |
| <DT><B>CONDITIONAL MACROS</B><DD> |
| Target specific conditional macros. |
| <DT><B>DYNAMIC PREREQUISITES</B><DD> |
| Processing of prerequisites which contain macro expansions in their name. |
| <DT><B>BINDING TARGETS</B><DD> |
| The rules that <B>dmake</B> uses to bind |
| a target to an existing file in the file system. |
| <DT><B>PERCENT(%) RULES</B><DD> |
| Specification of recipes to be used by the inference algorithm. |
| <DT><B>MAKING INFERENCES</B><DD> |
| The rules that <B>dmake</B> 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. |
| <DT><B>MAKING TARGETS</B><DD> |
| How <B>dmake</B> makes targets other than libraries. |
| <DT><B>MAKING LIBRARIES</B><DD> |
| How <B>dmake</B> makes libraries. |
| <DT><B>KEEP STATE</B><DD> |
| A discussion of how .KEEP_STATE works. |
| <DT><B>MULTI PROCESSING</B><DD> |
| Discussion of <B>dmake's</B> parallel make facilities for architectures that |
| support them. |
| <DT><B>CONDITIONALS</B><DD> |
| Conditional expressions which control the processing of the makefile. |
| <DT><B>EXAMPLES</B><DD> |
| Some hopefully useful examples. |
| <DT><B>COMPATIBILITY</B><DD> |
| How <B>dmake</B> compares with previous versions of make. |
| <DT><B>LIMITS</B><DD> |
| Limitations of <B>dmake</B>. |
| <DT><B>PORTABILITY</B><DD> |
| Comments on writing portable makefiles. |
| <DT><B>FILES</B><DD> |
| Files used by <B>dmake</B>. |
| <DT><B>SEE ALSO</B><DD> |
| Other related programs, and man pages. |
| <DT><B>AUTHOR</B><DD> |
| The guy responsible for this thing. |
| <DT><B>BUGS</B><DD> |
| Hope not. |
| </DL> |
| <A NAME="lbAG"> </A> |
| <H2>STARTUP</H2> |
| |
| When |
| <B>dmake</B> |
| |
| 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</B> |
| |
| searches the following locations, in the order specified, |
| until a startup file is located: |
| <P> |
| |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT>1.<DD> |
| The location given as the value of the macro |
| MAKESTARTUP defined on the command line. |
| <DT>2.<DD> |
| The location given as the value of the environment variable MAKESTARTUP |
| defined in the current environment. |
| <DT>3.<DD> |
| The location given as the value of the macro |
| MAKESTARTUP defined internally within <B>dmake</B>. 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. |
| </DL> |
| </DL> |
| |
| <P> |
| |
| 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</B> |
| |
| looks for the default startup file, check your environment or issue the command |
| <I>"dmake -V"</I>. |
| <P> |
| |
| A similar search is performed to locate a default user makefile when no |
| <B>-f</B> 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 |
| <B>dmake</B> should use to determine if one exists. |
| A typical definition for this target is: |
| <DL COMPACT><DT><DD> |
| <P> |
| .MAKEFILES : makefile.mk Makefile makefile |
| <P> |
| </DL> |
| |
| <B>dmake</B> will first look for makefile.mk and then the others. |
| If a prerequisite |
| cannot be found <B>dmake</B> 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. |
| <P> |
| |
| If the first line of the user makefile is of the form: |
| <DL COMPACT><DT><DD> |
| <P> |
| #! command command_args |
| <P> |
| </DL> |
| |
| then <B>dmake</B> will expand and run the command prior to reading any |
| additional input. If the return code of the command is zero then <B>dmake</B> |
| will continue on to process the remainder of the user makefile, if the return |
| code is non-zero then dmake will exit. |
| <P> |
| |
| <B>dmake</B> builds the internal dependency graph as it parses a user specified |
| makefile. The graph is rooted at the special target <B>.ROOT</B>. .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 <B>.TARGETS</B>. |
| <B>dmake</B> 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| .ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS .DONE |
| </DL> |
| |
| <P> |
| with .INIT and .DONE defined as: |
| <P> |
| <DL COMPACT><DT><DD> |
| .INIT .DONE .PHONY:; |
| </DL> |
| |
| <P> |
| 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 chaned by supplying the definition: |
| <P> |
| <DL COMPACT><DT><DD> |
| .ROOT : .TARGETS |
| </DL> |
| |
| <P> |
| which skips the preamble and postamble phases of building .TARGETS. |
| <A NAME="lbAH"> </A> |
| <H2>SYNTAX</H2> |
| |
| 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 <B>bold</B> type |
| are text or names representing text supplied by the user. |
| <P> |
| <DL COMPACT><DT><DD> |
| |
| <P> |
| <PRE> |
| <DL COMPACT> |
| <DT>Makefile<DD>-> { Statement } |
| |
| |
| <DT>Statement<DD>-> Macro-Definition |
| -> Conditional-Macro-Definition |
| -> Conditional |
| -> Rule-Definition |
| -> Attribute-Definition |
| |
| |
| <DT>Macro-Definition<DD>-> <B>MACRO = LINE</B> |
| -> <B>MACRO [!</B>]*= LINE |
| -> <B>MACRO [!</B>]:= LINE |
| -> <B>MACRO [!</B>]*:= LINE |
| -> <B>MACRO [!</B>]+= LINE |
| -> <B>MACRO [!</B>]+:= LINE |
| |
| |
| <DT>Conditional-Macro-Definition -> <DD><B>TARGET</B> ?= Macro-Definition |
| |
| |
| <DT>Conditional -> <DD><B>.IF</B> expression |
| Makefile |
| [ <B>.ELIF</B> expression |
| Makefile ] |
| [ <B>.ELSE</B> |
| Makefile ] |
| <B>.END</B> |
| |
| |
| <DT>expression<DD>-> <B>LINE</B> |
| -> <B>STRING == LINE</B> |
| -> <B>STRING != LINE</B> |
| -> <B>STRING <= LINE</B> |
| -> <B>STRING >= LINE</B> |
| -> <B>(</B> expression <B>)</B> |
| -> expression <B>||</B> expression |
| -> expression <B>&&</B> expression |
| |
| |
| <DT>Rule-Definition -> <DD>target-definition |
| [ recipe ] |
| </DL> |
| |
| target-definition -> targets [attrs] op { <B>PREREQUISITE</B> } [<B>;</B> rcp-line] |
| |
| |
| <DL COMPACT> |
| <DT>targets<DD>-> target { targets } |
| -> <B>"</B>target<B>"</B> { targets } |
| |
| |
| <DT>target<DD>-> special-target |
| -> <B>TARGET</B> |
| |
| |
| <DT>attrs<DD>-> attribute { attrs } |
| -> <B>"</B>attribute<B>"</B> { attrs } |
| |
| |
| <DT>op<DD>-> <B>:</B> { modifier } |
| |
| |
| <DT>modifier<DD>-> <B>:</B> |
| -> <B>^</B> |
| -> <B>!</B> |
| -> <B>-</B> |
| -> <B>|</B> |
| |
| |
| <DT>recipe<DD>-> { <B>TAB</B> rcp-line } |
| -> [<B>@</B>][<B>%</B>][<B>-</B>] <B>[ |
| |
| |
| <DT> <DD> </B>{ <B>LINE</B> } |
| |
| <DT> <DD><B>]</B> |
| |
| |
| <DT>rcp-line<DD>-> [<B>@</B>][<B>%</B>][<B>-</B>][<B>+</B>] <B>LINE</B> |
| |
| |
| <DT>Attribute-Definition<DD>-> attrs <B>:</B> targets |
| |
| |
| <DT>attribute<DD>-> <B>.EPILOG</B> |
| -> <B>.ERRREMOVE</B> |
| -> <B>.EXECUTE</B> |
| -> <B>.GROUP</B> |
| -> <B>.IGNORE</B> |
| -> <B>.IGNOREGROUP</B> |
| -> <B>.LIBRARY</B> |
| -> <B>.MKSARGS</B> |
| -> <B>.NOINFER</B> |
| -> <B>.NOSTATE</B> |
| -> <B>.PHONY</B> |
| -> <B>.PRECIOUS</B> |
| -> <B>.PROLOG</B> |
| -> <B>.SETDIR=</B><I>path</I> |
| -> <B>.SILENT</B> |
| -> <B>.SEQUENTIAL</B> |
| -> <B>.SWAP</B> |
| -> <B>.USESHELL</B> |
| -> <B>.SYMBOL</B> |
| -> <B>.UPDATEALL</B> |
| |
| |
| <DT>special-target<DD>-> <B>.ERROR</B> |
| -> <B>.EXIT</B> |
| -> <B>.EXPORT</B> |
| -> <B>.GROUPEPILOG</B> |
| -> <B>.GROUPPROLOG</B> |
| -> <B>.IMPORT</B> |
| -> <B>.INCLUDE</B> |
| -> <B>.INCLUDEDIRS</B> |
| -> <B>.MAKEFILES</B> |
| -> <B>.REMOVE</B> |
| -> <B>.SOURCE</B> |
| -> <B>.SOURCE.</B><I>suffix</I> |
| -> .<I>suffix1</I>.<I>suffix2</I> |
| </PRE> |
| |
| </DL> |
| </DL> |
| |
| <P> |
| <P> |
| |
| Where, <B>TAB</B> represents a <tab> character, <B>STRING</B> represents an |
| arbitrary sequence of characters, and |
| <B>LINE</B> represents a |
| possibly empty sequence of characters terminated by a non-escaped |
| (not immediately preceded by a backslash '\') new-line character. |
| <B>MACRO</B>, <B>PREREQUISITE</B>, |
| and <B>TARGET</B> 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 <B>LINE</B> can be continued over several physical lines by terminating it with |
| a single backslash character. Comments are initiated by the |
| pound <B>#</B> character and extend to the end of line. |
| All comment text is discarded, a '#' may be placed into the makefile text |
| by escaping it with '\' (ie. \# translates to # when it is parsed). |
| An exception to this occurs when a # is seen inside |
| a recipe line that begins with a <tab> or is inside a group recipe. |
| If you specify the <B>-c</B> command line switch then this behavior is |
| disabled and |
| <B>dmake</B> |
| |
| will treat all # characters as start of comment indicators unless they |
| are escaped by \. |
| A set of continued lines may be commented out by placing a single # at the |
| start of the first line. |
| A continued line cannot span more than one makefile. |
| <P> |
| |
| <B>white space</B> is defined to be any combination of |
| <space>, <tab>, and the sequence \<nl> |
| when \<nl> is used to terminate a LINE. |
| When processing <B>macro</B> definition lines, |
| any amount of white space is allowed on either side of the macro operator |
| and white space is stripped from both before and after the macro |
| value string. |
| The sequence \<nl> is treated as white space during recipe expansion |
| and is deleted from the final recipe string. |
| You must escape the \<nl> with another \ in order to get a \ at the end |
| of a recipe line. |
| The \<nl> sequence is deleted from macro values when they are expanded. |
| <P> |
| |
| When processing <B>target</B> 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 (<I>op</I> 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. <B>dmake</B> allows `:' to be present in |
| target/prerequisite names as long as the entire target/prerequisite name is |
| quoted. For example: |
| <P> |
| a:fred : test |
| <P> |
| would be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which |
| is not what was intended. To fix this you must write: |
| <P> |
| "a:fred" : test |
| <P> |
| 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 <B>"</B> quoting |
| to a list of targets. |
| <A NAME="lbAI"> </A> |
| <H2>ATTRIBUTES</H2> |
| |
| <B>dmake</B> |
| |
| 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 |
| <B>dmake</B> actions during target update. |
| The recognized attributes are: |
| <P> |
| <DL COMPACT> |
| <DT><B>.EPILOG</B><DD> |
| Insert shell epilog code when executing a group recipe associated with |
| any target having this attribute set. |
| <DT><B>.ERRREMOVE</B><DD> |
| Always remove any target having this attribute if an error is encountered |
| while making them. Setting this attribute overrides the .PRECIOUS attribute. |
| <DT><B>.EXECUTE</B><DD> |
| If the -n flag was given then execute the recipe associated with any |
| target having this attribute set. |
| <DT><B>.FIRST</B><DD> |
| Used in conjunction with .INCLUDE. Terminates the inclusion with the first |
| successfully included prerequisite. |
| <DT><B>.GROUP</B><DD> |
| Force execution of a target's recipe as a group recipe. |
| <DT><B>.IGNORE</B><DD> |
| Ignore an error when trying to make any target with this attribute set. |
| <DT><B>.IGNOREGROUP</B><DD> |
| Disable the special meaning of '[' to initiate a group recipe. |
| <DT><B>.LIBRARY</B><DD> |
| Target is a library. |
| <DT><B>.MKSARGS</B><DD> |
| If running in an MSDOS environment then use MKS extended argument passing |
| conventions to pass arguments to commands. Non-MSDOS |
| environments ignore this attribute. |
| <DT><B>.NOINFER</B><DD> |
| 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 <B>-T</B> on the command line. |
| <DT><B>.NOSTATE</B><DD> |
| Any target with this attribute set will not have command line flag |
| information stored in the state file if .KEEP_STATE has been enabled. |
| <DT><B>.PHONY</B><DD> |
| 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. |
| <DT><B>.PRECIOUS</B><DD> |
| 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 <B>dmake</B>. |
| <DT><B>.PROLOG</B><DD> |
| Insert shell prolog code when executing a group recipe associated with |
| any target having this attribute set. |
| <DT><B>.SEQUENTIAL</B><DD> |
| Force a sequential make of the associated target's prerequisites. |
| <DT><B>.SETDIR</B><DD> |
| 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 <I>.SETDIR=path</I> as the attribute. <I>path</I> is expanded and |
| the result is used as the value of the directory to change to. |
| If <I>path</I> contains <B>$$@</B> 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 <I>path</I> 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. |
| <DT><B>.SILENT</B><DD> |
| Do not echo the recipe lines when making any target with this attribute set, |
| and do not issue any warnings. |
| <DT><B>.SWAP</B><DD> |
| Under MSDOS |
| when making a target with this attribute set swap the <B>dmake</B> executable |
| to disk prior to executing the recipe line. Also see the '%' recipe line |
| flag defined in the RECIPES section. |
| <DT><B>.SYMBOL</B><DD> |
| 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. |
| <DT><B>.USESHELL</B><DD> |
| 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. |
| <DT><B>.UPDATEALL</B><DD> |
| 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</I> |
| |
| and |
| <I>y.tab.h</I> |
| |
| files by |
| <B>yacc</B> |
| |
| 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, <B>dmake</B> internally sorts |
| such targets in ascending alphabetical order and the value of $@ is always |
| the first target in the sorted set. |
| </DL> |
| <P> |
| |
| All attributes are user setable and except for .UPDATEALL, .SETDIR and .MKSARGS |
| may be used in one of two forms. |
| The .MKSARGS attribute is restricted to use as a global attribute, and |
| the use of the .UPDATEALL and .SETDIR attributes is restricted to rules |
| of the second form only. |
| <P> |
| ATTRIBUTE_LIST : <I>targets</I> |
| <P> |
| assigns the attributes specified by ATTRIBUTE_LIST to each target in |
| <I>targets</I> |
| |
| or |
| <P> |
| <I>targets</I> ATTRIBUTE_LIST : ... |
| <P> |
| assigns the attributes specified by ATTRIBUTE_LIST to each target in |
| <I>targets.</I> |
| |
| In the first form if |
| <I>targets</I> |
| |
| 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 <I>".IGNORE :"</I> |
| 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. |
| <P> |
| |
| Any attribute may be used with any target, even with the special targets. |
| Some combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ), |
| while others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not complain |
| if file.mk cannot be found using the include file search rules, |
| see the section on SPECIAL TARGETS for a description of .INCLUDE). |
| If a specified attribute will not be used with the special target a warning |
| is issued and the attribute is ignored. |
| <A NAME="lbAJ"> </A> |
| <H2>MACROS</H2> |
| |
| <B>dmake</B> |
| |
| supports six forms of macro assignment. |
| <P> |
| <DL COMPACT> |
| <DT><B>MACRO = LINE</B><DD> |
| 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. |
| <DT><B>MACRO *= LINE</B><DD> |
| This form behaves exactly as the simple '=' form with the exception that if |
| MACRO already has a value then the assignment is not performed. |
| <DT><B>MACRO := LINE</B><DD> |
| 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. |
| <DT><B>MACRO *:= LINE</B><DD> |
| 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. |
| <DT><B>MACRO += LINE</B><DD> |
| 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. |
| <DT><B>MACRO +:= LINE</B><DD> |
| This form is similar to the '+=' form except that the value of LINE is expanded |
| prior to being added to the value of MACRO. |
| </DL> |
| <P> |
| |
| 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. |
| <P> |
| |
| Each of the preceeding macro assignment operators may be prefixed by <B>!</B> |
| to indicate that the assignment should be forced and that no warnings should |
| be issued. Thus, specifying <B>!</B> has the effect of silently forcing the |
| specified macro assignment. |
| <P> |
| |
| When <B>dmake</B> 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 <B>-e</B>, or <B>-E</B> 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 <B>-e</B> or <B>-E</B> flags |
| are subject to expansion when used. |
| <P> |
| |
| 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. |
| <P> |
| |
| 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 |
| <P> |
| CWD = $(PWD:b) |
| <P> |
| 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: |
| <P> |
| _$(CWD).prt = list of files to print... |
| <P> |
| 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. |
| <P> |
| |
| Macro variables may be defined within the makefile, on the command |
| line, or imported from the environment. |
| <P> |
| |
| <B>dmake</B> |
| |
| supports several non-standard macro expansions: |
| The first is of the form: |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT><I>$(macro_name:modifier_list:modifier_list:...)</I><DD> |
| </DL> |
| </DL> |
| |
| <P> |
| |
| where |
| <I>modifier_list</I> |
| |
| is chosen from the set { B or b, D or d, E or e, F or f, I or i, L or l, S or |
| s, T or t, U or u, ^, +, 1 } and |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| |
| <PRE> |
| |
| <DL COMPACT> |
| <DT>b <DD>- file (not including suffix) portion of path names |
| |
| <DT>d<DD>- directory portion of all path names |
| |
| <DT>e<DD>- suffix portion of path names |
| |
| <DT>f<DD>- file (including suffix) portion of path names |
| |
| <DT>i<DD>- inferred names of targets |
| |
| <DT>l<DD>- macro value in lower case |
| |
| <DT>s<DD>- simple pattern substitution |
| |
| <DT>t<DD>- tokenization. |
| |
| <DT>u<DD>- macro value in upper case |
| |
| <DT>^<DD>- prepend a prefix to each token |
| |
| <DT>+<DD>- append a suffix to each token |
| |
| <DT>1<DD>- return the first white space separated token from value |
| |
| </DL> |
| </DL> |
| </PRE> |
| |
| Thus if we have the example: |
| <DL COMPACT><DT><DD> |
| test = d1/d2/d3/a.out f.out d1/k.out |
| </DL> |
| |
| The following macro expansions produce the values on the right of '->' after |
| expansion. |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| |
| <PRE> |
| |
| <DL COMPACT> |
| <DT>$(test:d)<DD>-> d1/d2/d3/ d1/ |
| |
| <DT>$(test:b)<DD>-> a f k |
| |
| <DT>$(test:f)<DD>-> a.out f.out k.out |
| |
| <DT>${test:db}<DD>-> d1/d2/d3/a f d1/k |
| |
| <DT>${test:s/out/in/:f}<DD>-> a.in f.in k.in |
| |
| <DT>$(test:f:t+)<DD>-> a.out+f.out+k.out |
| |
| <DT>$(test:e)<DD>-> .out .out .out |
| |
| <DT>$(test:u)<DD>-> D1/D2/D3/A.OUT F.OUT D1/K.OUT |
| |
| <DT>$(test:1)<DD>-> d1/d2/d3/a.out |
| </DL> |
| </DL> |
| </PRE> |
| |
| <P> |
| |
| 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 |
| <B>:d</B> 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. |
| <P> |
| |
| The tokenization modifier takes all white space separated tokens from the |
| macro value and separates them by the quoted separator string. The separator |
| string may contain the following escape codes \a => <bel>, |
| \b => <backspace>, \f => <formfeed>, \n => <nl>, \r => <cr>, |
| \t => <tab>, \v => <vertical tab>, \" => ", and \xxx => <xxx> where |
| xxx is the octal representation of a character. Thus the |
| expansion: |
| <P> |
| |
| <DL COMPACT><DT><DD> |
| <PRE> |
| $(test:f:t"+\n") |
| </DL> |
| produces: |
| <DL COMPACT><DT><DD>a.out+ |
| f.out+ |
| k.out |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| |
| The prefix operator <B>^</B> takes all white space separated tokens from the |
| macro value and prepends <I>string</I> to each. |
| <P> |
| |
| <DL COMPACT><DT><DD> |
| <PRE> |
| $(test:f:^mydir/) |
| </DL> |
| produces: |
| <DL COMPACT><DT><DD>mydir/a.out mydir/f.out mydir/k.out |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| |
| The suffix operator <B>+</B> takes all white space separated tokens from the |
| macro value and appends <I>string</I> to each. |
| <P> |
| |
| <DL COMPACT><DT><DD> |
| <PRE> |
| $(test:b:+.c) |
| </DL> |
| produces: |
| <DL COMPACT><DT><DD>a.c f.c k.c |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| |
| The next non-standard form of macro expansion allows for recursive macros. |
| It is possible to specify a $(<I>macro_name</I>) or ${<I>macro_name</I>} expansion |
| where <I>macro_name</I> contains more $( ... ) or ${ ... } macro expansions |
| itself. |
| <P> |
| |
| 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. |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| CFLAGS_VAX_CC = -c -O # _HOST == "_VAX", _COMPILER == "_CC" |
| CFLAGS_PC_MSC = -c -ML # _HOST == "_PC", _COMPILER == "_MSC" |
| |
| # redefine CFLAGS macro as: |
| |
| CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER)) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| This causes CFLAGS to take on a value that corresponds to the |
| environment in which the make is being invoked. |
| <P> |
| |
| The final non-standard macro expansion is of the form: |
| <DL COMPACT><DT><DD> |
| <P> |
| string1{token_list}string2 |
| </DL> |
| |
| <P> |
| |
| where string1, string2 and token_list are expanded. After expansion, |
| string1 is prepended to each token found in token_list and |
| string2 is appended to each resulting token from the previous prepend. |
| string1 and string2 are not 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| |
| <PRE> |
| |
| <DL COMPACT> |
| <DT>test/{f1 f2}.o<DD>--> test/f1.o test/f2.o |
| |
| <DT>test/ {f1 f2}.o<DD>--> test/ f1.o f2.o |
| |
| <DT>test/{f1 f2} .o<DD>--> test/f1 test/f2 .o |
| |
| <DT>test/{f1 }.o<DD>--> test/f1.o test/.o |
| |
| |
| <DT>and<DD> |
| |
| |
| <DT>test/{d1 d2}/{f1 f2}.o --> <DD>test/d1/f1.o test/d1/f2.o |
| test/d2/f1.o test/d2/f2.o |
| |
| </DL> |
| </DL> |
| </PRE> |
| |
| This last expansion is activated only when the first characters of |
| <I>token_list</I> |
| 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 |
| <DL COMPACT><DT><DD> |
| <P> |
| { echo hello;} |
| <P> |
| </DL> |
| |
| is valid /bin/sh syntax; while |
| <DL COMPACT><DT><DD> |
| <P> |
| {echo hello;} |
| <P> |
| </DL> |
| |
| |
| 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 |
| <B>dmake</B> defines and understands. |
| <A NAME="lbAK"> </A> |
| <H2>RULES AND TARGETS</H2> |
| |
| A makefile contains a series of entries that specify dependencies. |
| Such entries are called <I>target/prerequisite</I> or <I>rule</I> 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</B> |
| |
| 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| <I><targets></I> [<I><attributes></I>] <I><ruleop></I> [<I><prerequisites></I>] [;<I><recipe></I>] |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| <I>targets</I> |
| |
| 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| .IMPORT .ERROR : ... |
| </DL> |
| |
| <P> |
| 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. |
| <P> |
| |
| <I>attributes</I> |
| |
| 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. |
| <P> |
| <DL COMPACT> |
| <DT>NOTE:<DD> |
| 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. |
| <P> |
| </DL> |
| <P> |
| |
| <I>ruleop</I> |
| |
| 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</B> |
| |
| 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: |
| <P> |
| <DL COMPACT> |
| <DT><B>!</B><DD> |
| says execute the recipe for the associated targets once for each out of date |
| prerequisite. Ordinarily the recipe is executed |
| once for all out of date prerequisites at the same time. |
| <DT><B>^</B><DD> |
| 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. |
| <DT><B>-</B><DD> |
| says to clear the previous list of prerequisites before adding |
| the new prerequisites. Thus, |
| <P> |
| .SUFFIXES : |
| <BR> |
| |
| .SUFFIXES : .a .b |
| <P> |
| can be replaced by |
| <P> |
| .SUFFIXES :- .a .b |
| <P> |
| however the old form still works as expected. NOTE: .SUFFIXES is ignored by |
| <B>dmake</B> |
| |
| it is used here simply as an example. |
| <DT><B>:</B><DD> |
| 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. |
| <P> |
| 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. |
| <P> |
| In the following simple example, each rule has a `::' <I>ruleop</I>. In such an |
| operator we call the first `:' the operator, and the second `:' the modifier. |
| <P> |
| <PRE> |
| a.o :: a.c b.h |
| first recipe for making a.o |
| |
| a.o :: a.y b.h |
| second recipe for making a.o |
| </PRE> |
| |
| <P> |
| 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. |
| <DT><B>|</B><DD> |
| Is defined only for PERCENT rule target definitions. When specified it |
| indicates that the following construct should be parsed using the old |
| semantinc meaning: |
| <P> |
| <PRE> |
| %.o :| %.c %.r %.f ; some rule |
| |
| is equivalent to: |
| |
| %.o : %.c ; some rule |
| %.o : %.r ; some rule |
| %.o : %.f ; some rule |
| </PRE> |
| |
| </DL> |
| <P> |
| |
| Targets defined using a single `:' operator |
| with a recipe may be redefined again with a new recipe by using a |
| `:' operator with a `:' modifier. |
| This is equivalent to a 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| joe : fred ... (1) |
| joe :: more ... (2) |
| |
| and |
| |
| joe :: fred ... (3) |
| joe :: more ... (4) |
| |
| </PRE> |
| |
| </DL> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| joe :: fred ... (5) |
| joe : more ... (6) |
| |
| and |
| |
| joe : fred ... (7) |
| joe : more ... (8) |
| |
| </PRE> |
| |
| </DL> |
| |
| are errors since we have two sets of perfectly good recipes for |
| making the target. |
| <P> |
| |
| <I>prerequisites</I> |
| |
| is a possibly empty list of targets that must be brought up to date before |
| making the current target. |
| <P> |
| |
| <I>recipe</I> |
| |
| is a short form and allows the user to specify short rule definitions |
| on a single line. |
| It is taken to be the first recipe line in a larger recipe |
| if additional lines follow the rule definition. |
| If the semi-colon is present but the recipe line is empty (ie. null string) |
| then it is taken |
| to be an empty rule. Any target so defined causes the |
| <I>Don't know how to make ...</I> |
| |
| error message to be suppressed when |
| <B>dmake</B> |
| |
| tries to make the target and fails. |
| This silence is maintained for rules that are terminated |
| by a semicolon and have no following recipe lines, for targets listed on the |
| command line, for the first target found in the makefile, and for any target |
| having no recipe but containing a list of prerequisites (see the COMPATIBILITY |
| section for an exception to this rule if the AUGMAKE (<B>-A</B>) flag |
| was specified. |
| <A NAME="lbAL"> </A> |
| <H2>RECIPES</H2> |
| |
| 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</B> |
| |
| begin with a <B><TAB></B> character which |
| may optionally be followed with one or all |
| of the characters |
| <I>'@%+-'</I>. |
| |
| The |
| <I>'-'</I> |
| |
| indicates that non-zero exit values (ie. errors) |
| are to be ignored when this recipe line is executed, the |
| <I>'+'</I> |
| |
| indicates that the current recipe line is to be executed using the shell, the |
| <I>'%'</I> |
| |
| indicates that |
| <B>dmake</B> |
| |
| should swap itself out to secondary storage (MSDOS only) before running the |
| recipe and the |
| <I>'@'</I> |
| |
| indicates that the recipe line should NOT be echoed to the terminal prior to |
| being executed. Each switch is off by default |
| (ie. by default, errors are 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| target : |
| first recipe line |
| second recipe line, executed independent of first. |
| @a recipe line that is not echoed |
| -and one that has errors ignored |
| %and one that causes dmake to swap out |
| +and one that is executed using a shell. |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| |
| The second and new format of the recipe block begins the block with the |
| character '[' (the open group character) in the last non-white space |
| position of a line, and terminates the |
| block with the character ']' (the close group character) |
| in the first non-white space position of a line. |
| In this form each recipe line need not have a leading TAB. This is |
| called a recipe group. Groups so defined are fed intact as a single |
| unit to a shell for execution whenever the corresponding target needs to |
| be updated. If the open group character '[' is preceded |
| by one or all of -, @ or % |
| then they apply to the entire group in the same way that they |
| apply to single recipe lines. You may also specify '+' but it is |
| redundant as a shell is already being used to run the recipe. |
| See the MAKING TARGETS section for a description of how |
| <B>dmake</B> |
| |
| invokes recipes. |
| Here is an example of a group recipe: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| target : |
| [ |
| first recipe line |
| second recipe line |
| tall of these recipe lines are fed to a |
| single copy of a shell for execution. |
| ] |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| <A NAME="lbAM"> </A> |
| <H2>TEXT DIVERSIONS</H2> |
| |
| <B>dmake</B> |
| |
| supports the notion of text diversions. |
| If a recipe line contains the macro expression |
| <DL COMPACT><DT><DD> |
| <P> |
| $(mktmp[,[<I>file</I>][,<I>text</I>]] <I>data</I>) |
| <P> |
| </DL> |
| |
| then all text contained in the <I>data</I> expression is expanded and |
| is written to a temporary file. The return |
| value of the macro is the name of the temporary file. |
| <P> |
| |
| <I>data</I> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| $(mktmp $(XXX)) |
| <P> |
| </DL> |
| |
| is legal and works as expected, but: |
| <DL COMPACT><DT><DD> |
| <P> |
| $(mktmp text (to dump to file) |
| <P> |
| </DL> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| ${mktmp text (to dump to file} |
| <P> |
| </DL> |
| |
| 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</B> |
| |
| run. |
| The diversion text may contain |
| the same escape codes as those described in the MACROS section. |
| Thus if the <I>data</I> text is to contain new lines they must be inserted |
| using the \n escape sequence. For example the expression: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| all: |
| cat $(mktmp this is a\n\ |
| test of the text diversion\n) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| is replaced by: |
| <DL COMPACT><DT><DD> |
| <P> |
| cat /tmp/mk12294AA |
| <P> |
| </DL> |
| |
| where the temporary file contains two lines both of which are terminated |
| by a new-line. If the <I>data</I> text spans multiple lines in the makefile |
| then each line must be continued via the use of a \. |
| A second more illustrative example generates a response file to an MSDOS |
| link command: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| OBJ = fred.obj mary.obj joe.obj |
| all : $(OBJ) |
| link @$(mktmp $(^:t"+\n")\n) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| The result of making `all' in the second example is the command: |
| <DL COMPACT><DT><DD> |
| <P> |
| link @/tmp/mk02394AA |
| <P> |
| </DL> |
| |
| where the temporary file contains: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| fred.obj+ |
| mary.obj+ |
| joe.obj |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| The last line of the file is terminated by a new-line which is inserted |
| due to the \n found at the end of the <I>data</I> string. |
| <P> |
| |
| If the optional <I>file</I> specifier is present then its expanded value |
| is the name of the temporary file to create. An example that would be useful |
| for MSDOS users with a Turbo-C compiler |
| <DL COMPACT><DT><DD> |
| <P> |
| $(mktmp,turboc.cfg $(CFLAGS)) |
| <P> |
| </DL> |
| |
| will place the contents of CFLAGS into a local <I>turboc.cfg</I> file. |
| The second optional argument, <I>text</I>, if present alters the name |
| of the value returned by the $(mktmp ...) macro. |
| <P> |
| |
| Under MS-DOS text diversions may be a problem. Many DOS tools require |
| that path names which contain directories use the \ character to delimit |
| the directories. Some users 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</B> |
| |
| 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. |
| <P> |
| |
| Previous versions of |
| <B>dmake</B> |
| |
| defined text diversions using <+, +> strings, |
| where <+ started a text diversion and +> terminated one. |
| <B>dmake</B> |
| |
| 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: |
| <P> |
| <+data+> |
| <P> |
| is mapped to: |
| <P> |
| $(mktmp data) |
| <P> |
| which is fully output compatible with the earlier construct. <+, +> |
| constructs whose text spans multiple lines must be converted by hand to use |
| $(mktmp ...). |
| <P> |
| |
| 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. |
| <A NAME="lbAN"> </A> |
| <H2>SPECIAL TARGETS</H2> |
| |
| This section describes the special targets that are recognized by <B>dmake</B>. |
| Some are affected by attributes and others are not. |
| <DL COMPACT> |
| <DT><B>.ERROR</B><DD> |
| If defined then the recipe associated with this target is executed |
| whenever an error condition is detected by <B>dmake</B>. 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. |
| <DT><B>.EXIT</B><DD> |
| If this target is encountered while parsing a makefile then the parsing of the |
| makefile is immediately terminated at that point. |
| <DT><B>.EXPORT</B><DD> |
| 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. |
| is suppre |
| <DT><B>.IMPORT</B><DD> |
| 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 <B>.EVERYTHING</B> is used as a prerequisite name then |
| all environment variables defined in the environment are imported. |
| The functionality of the <B>-E</B> flag can be forced by placing the construct |
| <I>.IMPORT : .EVERYTHING</I> at the start of a makefile. Similarly, by |
| placing the construct at the end, one can emulate the effect of the <B>-e</B> |
| 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 <B>dmake</B> |
| to ignore the above error. |
| See the MACROS section for a description of the processing of imported macro |
| values. |
| <DT><B>.INCLUDE</B><DD> |
| 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 <B>dmake</B> continues processing, |
| otherwise an error message is generated. |
| If the .NOINFER attribute is given and the file |
| cannot be found then <B>dmake</B> will not attempt to |
| <I>infer and make</I> the file. |
| The .SETDIR attribute causes |
| <B>dmake</B> |
| |
| to change directories to the specified directory prior to attempting the |
| include operation. If all fails <B>dmake</B> attempts to <I>make</I> the file |
| to be included. If making the file fails then <B>dmake</B> terminates unless |
| the .INCLUDE directive also specified the .IGNORE attribute. |
| If .FIRST is specified along with .INCLUDE then <B>dmake</B> attempts to |
| include each named prerequisite and will terminate the inclusion with the |
| first prerequisite that results in a successful inclusion. |
| <DT><B>.INCLUDEDIRS</B><DD> |
| The list of prerequisites specified for this target defines the set of |
| directories to search when trying to include a makefile. |
| <DT><B>.KEEP_STATE</B><DD> |
| This special target is a synonym for the macro definition |
| <P> |
| .KEEP_STATE := _state.mk |
| <P> |
| It's effect is to turn on STATE keeping and to define <I>_state.mk</I> |
| as the state file. |
| <DT><B>.MAKEFILES</B><DD> |
| The list of prerequisites is the set of files to try to read as the default |
| makefile. By default this target is defined as: |
| <P> |
| .MAKEFILES : makefile.mk Makefile makefile |
| <P> |
| <DT><B>.SOURCE</B><DD> |
| 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. |
| <DT><B>.SOURCE.suff</B><DD> |
| 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. |
| <DT><B>.REMOVE</B><DD> |
| The recipe of this target is used whenever <B>dmake</B> 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. |
| </DL> |
| <P> |
| |
| 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. |
| <A NAME="lbAO"> </A> |
| <H2>SPECIAL MACROS</H2> |
| |
| <B>dmake</B> |
| |
| 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</B> |
| |
| 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</B> |
| |
| 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. |
| <A NAME="lbAP"> </A> |
| <H2>CONTROL MACROS</H2> |
| |
| 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. |
| <P> |
| |
| 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. |
| <DL COMPACT> |
| <DT><B>INCDEPTH</B><DD> |
| 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. |
| <DT><B>MFLAGS</B><DD> |
| 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. |
| <DT><B>MAKECMD</B><DD> |
| Is the name with which <B>dmake</B> was invoked. |
| <DT><B>MAKEDIR</B><DD> |
| Is the full path to the initial directory in which |
| <B>dmake</B> |
| |
| was invoked. |
| <DT><B>MAKEFILE</B><DD> |
| Contains the string "-f <I>makefile</I>" where, <I>makefile</I> is the name |
| of initial user makefile that was first read. |
| <DT><B>MAKEFLAGS</B><DD> |
| Is the same as $(MFLAGS) but has no leading switch |
| character. (ie. MFLAGS = -$(MAKEFLAGS)) |
| <DT><B>MAKEMACROS</B><DD> |
| Contains the complete list of macro expressions that were specified on the |
| command line. |
| <DT><B>MAKETARGETS</B><DD> |
| Contains the name(s) of the target(s), if any, that were |
| specified on the command line. |
| <DT><B>MAKEVERSION</B><DD> |
| Contains a string indicating the current <B>dmake</B> version number. |
| <DT><B>MAXPROCESSLIMIT</B><DD> |
| Is a numeric string representing the maximum number of processes that |
| <B>dmake</B> can use when making targets using parallel mode. |
| <DT><B>NULL</B><DD> |
| Is permanently defined to be the NULL string. |
| This is useful when comparing a conditional expression to an NULL value. |
| <DT><B>PWD</B><DD> |
| Is the full path to the |
| current directory in which make is executing. |
| <DT><B>TMPFILE</B><DD> |
| Is set to the name of the most recent temporary file opened by <B>dmake</B>. |
| Temporary files are used for text diversions and for group recipe processing. |
| <DT><B>TMD</B><DD> |
| Stands for "To Make Dir", and |
| is the path from the present directory (value of $(PWD)) to the directory |
| that <B>dmake</B> was started up in (value of $(MAKEDIR)). |
| This macro is modified when .SETDIR attributes are processed. |
| <DT><B>USESHELL</B><DD> |
| 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. |
| <P> |
| </DL> |
| <P> |
| |
| The second group of string valued macros control |
| <B>dmake</B> |
| |
| behavior and may be set by the user. |
| <DL COMPACT> |
| <DT><B>.DIRCACHE</B><DD> |
| 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). |
| <DT><B>.DIRCACHERESPCASE</B><DD> |
| If set to "yes" causes the directory cache, if enabled, to respect |
| file case, if set to "no" facilities of the native OS are used to |
| match file case. |
| <DT><B>.NAMEMAX</B><DD> |
| 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. |
| <DT><B>.NOTABS</B><DD> |
| 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 []. |
| <DT><B>AUGMAKE</B><DD> |
| If set to "yes" value will enable the transformation of special |
| meta targets to support special AUGMAKE inferences (See the COMPATIBILITY |
| section). |
| <DT><B>DIRBRKSTR</B><DD> |
| 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 "/\:". |
| <DT><B>DIRSEPSTR</B><DD> |
| Contains the string that is used to separate directory components when |
| path names are constructed. It is defined with a default value at startup. |
| <DT><B>DIVFILE</B><DD> |
| 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. |
| <DT><B>DYNAMICNESTINGLEVEL</B><DD> |
| Specifies the maximum number of recursive dynamic macro expansions. Its |
| initial value is 100. |
| <DT><B>.KEEP_STATE</B><DD> |
| Assigning this macro a value tells |
| <B>dmake</B> |
| |
| 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. |
| <DT><B>GROUPFLAGS</B><DD> |
| 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) |
| <DT><B>GROUPSHELL</B><DD> |
| 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. |
| <DT><B>GROUPSUFFIX</B><DD> |
| 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 <B>dmake</B> 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. |
| <DT><B>MAKE</B><DD> |
| 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. |
| <DT><B>MAKESTARTUP</B><DD> |
| This macro defines the full path to the initial startup |
| makefile. Use the <B>-V</B> command line option to discover its initial |
| value. |
| <DT><B>MAXLINELENGTH</B><DD> |
| 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 <B>-V</B> 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. |
| <DT><B>MAXPROCESS</B><DD> |
| 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. |
| <DT><B>PREP</B><DD> |
| This macro defines the number of iterations to be expanded |
| automatically when processing % rule definitions of the form: |
| <P> |
| % : %.suff |
| <P> |
| See the sections on PERCENT(%) RULES for details on how PREP is used. |
| <DT><B>SHELL</B><DD> |
| 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. |
| <DT><B>SHELLFLAGS</B><DD> |
| 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) |
| <DT><B>SHELLMETAS</B><DD> |
| Each time |
| <B>dmake</B> |
| |
| 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. |
| <P> |
| </DL> |
| <P> |
| |
| There is only one character valued macro defined by <B>dmake</B>: |
| <B>SWITCHAR</B> 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 <B>dmake</B> 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. |
| <P> |
| |
| All boolean macros currently understood by |
| <B>dmake</B> |
| |
| 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: |
| <B>.EPILOG</B>, |
| <B>.IGNORE</B>, |
| <B>.MKSARGS</B>, |
| <B>.NOINFER</B>, |
| <B>.PRECIOUS</B>, |
| <B>.PROLOG</B>, |
| <B>.SEQUENTIAL</B>, |
| <B>.SILENT</B>, |
| <B>.SWAP</B>, and |
| <B>.USESHELL</B>. |
| Assigning any of these a non NULL value will globally set |
| the corresponding attribute to on. |
| <A NAME="lbAQ"> </A> |
| <H2>RUNTIME MACROS</H2> |
| |
| These macros are defined |
| when <B>dmake</B> is making targets, and may take on different values for each |
| target. <B>$@</B> is defined to be the full target name, <B>$?</B> is the |
| list of all out of date prerequisites, <B>$&</B> is the list of all |
| prerequisites, <B>$></B> is the name of the library if the current target is a |
| library member, and |
| <B>$<</B> is the list of prerequisites specified in the current rule. |
| If the current target had a recipe inferred then <B>$<</B> 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 |
| <B>$&</B> gives the full list of prerequisites. |
| <P> |
| |
| <B>$*</B> is defined as |
| <B>$(@:db)</B> 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 <B>$*</B> is the target name with no suffix, |
| and in the second case, is the value of the matched % pattern from |
| the associated %-rule. |
| <B>$^</B> expands to the set of out of date prerequisites taken from the |
| current value of <B>$<</B>. |
| In addition to these, |
| <B>$$</B> expands to $, <B>{{</B> expands to {, <B>}}</B> expands to }, and the |
| strings <B><+</B> and <B>+></B> are recognized |
| as respectively starting and terminating a text diversion when they appear |
| literally together in the same input line. |
| <P> |
| |
| The difference between $? and $^ can best be illustrated by an example, |
| consider: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| fred.out : joe amy hello |
| rules for making fred |
| |
| fred.out : my.c your.h his.h her.h # more prerequisites |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| Assume joe, amy, and my.c are newer then fred.out. When |
| <B>dmake</B> |
| |
| executes the recipe for making fred.out the values of the following macros |
| will be: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| |
| |
| <DL COMPACT> |
| <DT>$@<DD>--> fred.out |
| |
| <DT>$*<DD>--> fred |
| |
| <DT>$?<DD>--> joe amy my.c # note output of $? vs $^ |
| |
| <DT>$^<DD>--> joe amy |
| |
| <DT>$<<DD>--> joe amy hello |
| |
| <DT>$&<DD>--> joe amy hello my.c your.h his.h her.h |
| </PRE> |
| |
| <P> |
| </DL> |
| </DL> |
| |
| <A NAME="lbAR"> </A> |
| <H2>FUNCTION MACROS</H2> |
| |
| <B>dmake</B> |
| |
| 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. |
| <DL COMPACT><DT><DD> |
| <P> |
| <DL COMPACT> |
| <DT>$(<B>and</B> <B>macroterm ...</B>)<DD> |
| expands each <B>macroterm</B> 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. |
| <P> |
| <DT>$(<B>assign</B> <B>expression</B>)<DD> |
| Causes <I>expression</I> 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. <I>expression</I> 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 <I>expression</I> is not a valid macro assignment expression. |
| Some examples are: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| $(assign foo := fred) |
| $(assign $(ind_macro_name) +:= $(morejunk)) |
| </PRE> |
| |
| </DL> |
| |
| <DT>$(<B>echo</B> <B>list</B>)<DD> |
| Echo's the value of <I>list</I>. <I>list</I> is not expanded. |
| <DT>$(<B>eq</B>,<I>text_a</I>,<I>text_b</I> <B>true</B> <B>false</B>)<DD> |
| expands |
| <I>text_a</I> |
| |
| and |
| <I>text_b</I> |
| |
| and compares their results. If equal it returns the result of the expansion |
| of the |
| <B>true</B> |
| |
| term, otherwise it returns the expansion of the |
| <B>false</B> |
| |
| term. |
| <DT>$(<B>!eq</B>,<I>text_a</I>,<I>text_b</I> <B>true</B> <B>false</B>)<DD> |
| Behaves identically to the previous macro except that the |
| <B>true</B> |
| |
| string is chosen if the expansions of the two strings are not equal |
| <DT>$(<B>foreach</B>,<I>var</I>,<I>list</I> <B>data</B>)<DD> |
| Implements iterative macro expansion over <I>data</I> using <B>var</B> as the |
| iterator taking on values from <I>list</I>. <I>var</I> and <I>list</I> are |
| expanded and the result is the concatenation of expanding <I>data</I> with |
| <I>var</I> being set to each whitespace separated token from <I>list</I>. |
| For example: |
| <DL COMPACT><DT><DD> |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| list = a b c |
| all :; echo [$(foreach,i,$(list) [$i])] |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| will output |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| [[a] [b] [c]] |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| The iterator variable is defined as a local variable to this foreach |
| instance. The following expression illustrates this: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| $(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h]) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| when evaluated the result is: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| [root/a/f.h] [root/b/f.h] [root/c/f.h] |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| The specification of list must be a valid macro expression, such as: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| $($(assign list=a b c)) |
| $(sort d a b c) |
| $(echo a b c) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| and cannot just be the list itself. That is, the following foreach |
| expression: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| $(foreach,i,a b c [$i]) |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| yields: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| "b c [a]" |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| when evaluated. |
| </DL> |
| |
| <DT>$(<B>nil</B> <B>expression</B>)<DD> |
| Always returns the value of $(NULL) regardless of what <I>expression</I> is. |
| This function macro can be used to discard results of expanding |
| macro expressions. |
| <DT>$(<B>not</B> <B>macroterm</B>)<DD> |
| expands <B>macroterm</B> and returs the string "t" if the result of the |
| expansion is the empty string; otherwise, it returns the empty string. |
| <DT>$(<B>null</B>,<I>text</I> <B>true</B> <B>false</B>)<DD> |
| expands the value of |
| <I>text.</I> |
| |
| If it is NULL then the macro returns the value of the expansion of <B>true</B> |
| and the expansion of <B>false</B> otherwise. The terms <B>true</B>, and |
| <B>false</B> must be strings containing no white-space. |
| <DT>$(<B>!null</B>,<I>text</I> <B>true</B> <B>false</B>)<DD> |
| Behaves identically to the previous macro except that the |
| <B>true</B> |
| |
| string is chosen if the expansion of |
| <I>text</I> |
| |
| is not NULL. |
| <DT>$(<B>or</B> <B>macroterm ...</B>)<DD> |
| expands each <B>macroterm</B> in turn and returs the empty string if |
| each term expands to the empty string; otherwise, it returs the string |
| "t". |
| <DT>$(<B>shell</B> <B>command</B>)<DD> |
| Runs <I>command</I> 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: |
| <DL COMPACT><DT><DD> |
| <DL COMPACT><DT><DD> |
| <P> |
| $(shell ls *.c) |
| <P> |
| </DL> |
| |
| will return <I>"a.c b.c c.c d.c"</I> if the files exist in the current |
| directory. The recipe modification flags <B>[+@%-]</B> are honored if they |
| appear as the first characters in the command. For example: |
| <DL COMPACT><DT><DD> |
| <P> |
| $(shell +ls *.c) |
| <P> |
| </DL> |
| |
| will run the command using the current shell. |
| </DL> |
| |
| <DT>$(<B>shell,expand</B> <B>command</B>)<DD> |
| Is an extension to the <B>$(shell...</B> function macro that expands the result |
| of running <B>command</B>. |
| <DT>$(<B>sort</B> <B>list</B>)<DD> |
| Will take all white-space separated tokens in <I>list</I> and will |
| return their sorted equivalent list. |
| <DT>$(<B>strip</B> <B>data</B>)<DD> |
| Will replace all strings of white-space in data by a single space. |
| <DT>$(<B>subst</B>,<I>pat</I>,<I>replacement</I> <B>data</B>)<DD> |
| Will search for <I>pat</I> in |
| <B>data</B> |
| |
| and will replace any occurrence of |
| <I>pat</I> |
| |
| with the |
| <I>replacement</I> |
| |
| string. The expansion |
| <DL COMPACT><DT><DD> |
| <P> |
| $(subst,.o,.c $(OBJECTS)) |
| <P> |
| </DL> |
| |
| is equivalent to: |
| <DL COMPACT><DT><DD> |
| <P> |
| $(OBJECTS:s/.o/.c/) |
| <P> |
| </DL> |
| |
| <DT>$(<B>uniq</B> <B>list</B>)<DD> |
| Will take all white-space separated tokens in <I>list</I> and will |
| return their sorted equivalent list containing no duplicates. |
| </DL> |
| </DL> |
| |
| <A NAME="lbAS"> </A> |
| <H2>CONDITIONAL MACROS</H2> |
| |
| <B>dmake</B> |
| |
| supports conditional macros. These allow the definition of target specific |
| macro values. You can now say the following: |
| <DL COMPACT><DT><DD> |
| <P> |
| <B>target</B> ?= <I>MacroName MacroOp Value</I> |
| <P> |
| </DL> |
| |
| This creates a definition for <I>MacroName</I> whose value is <I>Value</I> |
| only when <B>target</B> 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. |
| <P> |
| |
| The new definition is associated with the most recent cell definition |
| for <B>target</B>. If no prior definition exists then one is created. The |
| implications of this are immediately evident in the following example: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| foo := hello |
| |
| all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]" |
| |
| cond ?= bar := global decl |
| |
| cond .SETDIR=unix::;@echo $(foo) $(bar) |
| cond ?= foo := hi |
| |
| cond .SETDIR=msdos::;@echo $(foo) $(bar) |
| cond ?= foo := hihi |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| 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. |
| <P> |
| |
| 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 |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| mytarget ?= bar := hello |
| mytarget ?= foo := $(bar) |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| results in $(foo) expanding to "", if you want the result to be "hello" |
| you must use: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| mytarget ?= bar := hello |
| mytarget ?= foo = $(bar) |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| 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. |
| <P> |
| |
| 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. |
| <A NAME="lbAT"> </A> |
| <H2>DYNAMIC PREREQUISITES</H2> |
| |
| <B>dmake</B> |
| |
| 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: |
| <P> |
| fred : $$@.c |
| <P> |
| causes the $$@ to be expanded when <B>dmake</B> is making fred, and it resolves |
| to the target <I>fred</I>. |
| 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: |
| <P> |
| fred.out : $$(@:b).c |
| <P> |
| where the $$(@:b) expands to <I>fred</I>. |
| 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. |
| If you really want a $ to be part of a prerequisite name you must use $$$$. |
| Dynamic macro expansion is performed in all user defined rules, |
| and the special targets .SOURCE*, and .INCLUDEDIRS. |
| <P> |
| |
| If dynamic macro expansion results in multiple white space separated tokens |
| then these are inserted into the prerequisite list inplace of the dynamic |
| prerequisite. If the new list contains additional dynamic prerequisites they |
| will be expanded when they are processed. The level of recursion in this |
| expansion is controlled by the value of the variable <B>DYNAMICNESTINGLEVEL</B> |
| and is set to 100 by default. |
| <A NAME="lbAU"> </A> |
| <H2>BINDING TARGETS</H2> |
| |
| This operation takes a target name and binds it to an existing file, if |
| possible. |
| <B>dmake</B> |
| |
| 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 <I>X.suff</I>, |
| where <I>.suff</I> is the suffix and <I>X</I> is the stem portion |
| (ie. that part which contains the directory and the basename). |
| <B>dmake</B> |
| |
| 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. |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT>1.<DD> |
| 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. |
| <DT>2.<DD> |
| 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. <I>.suff</I> 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). |
| <DT>3.<DD> |
| 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 <B>dmake</B> at startup, |
| and is user redefinable) |
| <DT>4.<DD> |
| 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.). |
| <DT>5.<DD> |
| 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 <B>dmake</B> 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. |
| </DL> |
| </DL> |
| |
| <P> |
| |
| 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 <B>dmake</B> stops, then |
| the user may fix the error and make again. <B>dmake</B> 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. |
| <P> |
| |
| When <B>dmake</B> constructs target pathnames './' substrings are removed and |
| substrings of the form 'foo/..' are eliminated. This may result in somewhat |
| unexpected values of the macro expansion <B>$@</B>, but is infact the corect |
| result. |
| <P> |
| |
| When defining .SOURCE and .SOURCE.x targets the construct |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| <BR> |
| |
| |
| <P> |
| </DL> |
| |
| is equivalent to |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| </DL> |
| |
| <P> |
| |
| <B>dmake</B> correctly handles the UNIX Make variable VPATH. By definition VPATH |
| contains a list of ':' separated directories to search when looking for a |
| target. <B>dmake</B> maps VPATH to the following special rule: |
| <DL COMPACT><DT><DD> |
| <P> |
| |
| <P> |
| </DL> |
| |
| Which takes the value of VPATH and sets .SOURCE to the same set of directories |
| as specified in VPATH. |
| <A NAME="lbAV"> </A> |
| <H2>PERCENT(%) RULES AND MAKING INFERENCES</H2> |
| |
| When <B>dmake</B> makes a target, the target's set of prerequisites (if any) |
| must exist and the target must have a recipe which <B>dmake</B> |
| can use to make it. |
| If the makefile does not specify an explicit recipe for the target then |
| <B>dmake</B> |
| |
| 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> and by |
| using the .SUFFIXES list of suffixes. The exact workings of this mechanism |
| were sometimes difficult to understand and often limiting in their usefulness. |
| Instead, <B>dmake</B> supports the concept of <I>%-meta</I> rules. |
| The syntax and semantics of these rules differ from standard rule lines as |
| follows: |
| <P> |
| <PRE> |
| <DL COMPACT><DT><DD><I><%-target></I> [<I><attributes></I>] <I><ruleop></I> [<I><%-prerequisites></I>] [;<I><recipe></I>] |
| </DL> |
| </PRE> |
| |
| <P> |
| where <I>%-target</I> is a target containing exactly a single `%' sign, |
| <I>attributes</I> |
| |
| is a list (possibly empty) of attributes, |
| <I>ruleop</I> |
| |
| is the standard set of rule operators, |
| <I>%-prerequisites</I> |
| |
| , if present, is a list of prerequisites containing zero or more `%' signs, |
| and |
| <I>recipe,</I> |
| |
| if present, is the first line of the recipe. |
| <P> |
| |
| The |
| <I>%-target</I> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| |
| |
| <DL COMPACT> |
| <DT>%.c<DD>matches fred.c but not joe.c.Z |
| |
| <DT>dir/%.c<DD>matches dir/fred.c but not dd/fred.c |
| |
| <DT>fred/%<DD>matches fred/joe.c but not f/joe.c |
| |
| <DT>%<DD>matches anything |
| </PRE> |
| |
| <P> |
| </DL> |
| </DL> |
| |
| 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</B> |
| |
| constructs the new dependency. |
| As an example the following %-meta rules describe the following: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.c : %.y ; recipe... |
| <P> |
| </DL> |
| |
| describes how to make any file ending in .c if a corresponding file ending |
| in .y can be found. |
| <DL COMPACT><DT><DD> |
| <P> |
| foo%.o : fee%.k ; recipe... |
| <P> |
| </DL> |
| |
| is used to describe how to make fooxxxx.o from feexxxx.k. |
| <DL COMPACT><DT><DD> |
| <P> |
| %.a :; recipe... |
| <P> |
| </DL> |
| |
| describes how to make a file whose suffix is .a without inferring any |
| prerequisites. |
| <DL COMPACT><DT><DD> |
| <P> |
| %.c : %.y yaccsrc/%.y ; recipe... |
| <P> |
| </DL> |
| |
| is a short form for the construct: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.c : %.y ; recipe... |
| <BR> |
| |
| %.c : yaccsrc/%.y ; recipe... |
| <P> |
| </DL> |
| |
| ie. It is possible to specify the same recipe for two %-rules by giving |
| more than one prerequisite in the prerequisite list. |
| A more interesting example is: |
| <DL COMPACT><DT><DD> |
| <P> |
| % : RCS/%,v ; co $< |
| <P> |
| </DL> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| % : s.% ; get $< |
| <P> |
| </DL> |
| |
| <P> |
| |
| The previous RCS example defines an infinite rule, because it says how to make |
| <I>anything</I> |
| |
| from RCS/%,v, and |
| <I>anything</I> |
| |
| also includes RCS/fred.c,v. |
| To limit the size of the graph that results from such rules |
| <B>dmake</B> |
| |
| 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 <B>dmake</B> would generate the dependency |
| graph: |
| <DL COMPACT><DT><DD> |
| <P> |
| % --> RCS/%,v --> RCS/RCS/%,v,v |
| <P> |
| </DL> |
| |
| 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</B> |
| |
| further assumes that any target that has no suffix can be made from |
| a prerequisite that has at least one suffix. |
| <P> |
| |
| <B>dmake</B> |
| |
| 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 <I>RCS/fred.c,v</I> from the target <I>fred.c</I>, |
| but cannot infer how to find <I>srcdir/RCS/fred.c,v</I> from <I>srcdir/fred.c</I> |
| because the above rule will cause <B>dmake</B> 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). |
| <P> |
| |
| A more versatile formulation of the above RCS check out rule is the following: |
| <DL COMPACT><DT><DD> |
| <P> |
| % : $$(@:d)RCS/$$(@:f),v : co $@ |
| <P> |
| </DL> |
| |
| 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 <I>RCS/</I> to it, and appending the target file name with a trailing |
| <I>,v</I> attached to the previous result. |
| <P> |
| |
| <B>dmake</B> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| fred.o : fred.c ; rule to make fred.o |
| fred.o : local.h |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| then this can be inferred for fred.o from the following inference rule: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o : %.c 'local.h' ; makes a .o from a .c |
| <P> |
| </DL> |
| |
| You may infer indirect prerequisites that are a function of the value of '%' |
| in the current rule. The meta-rule: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c |
| <P> |
| </DL> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o : %.c %.f 'local.h'; recipe |
| <P> |
| </DL> |
| |
| is equivalent to: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| %.o : %.c 'local.h' : recipe |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| while: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o :| %.c %.f 'local.h'; recipe |
| <P> |
| </DL> |
| |
| is equivalent to: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| %.o : %.c 'local.h' : recipe |
| %.o : %.f 'local.h' : recipe |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| <P> |
| |
| If any of the attributes .SETDIR, .EPILOG, .PROLOG, .SILENT, |
| .USESHELL, .SWAP, .PRECIOUS, .LIBRARY, .NOSTATE and .IGNORE |
| 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</B> |
| |
| 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. |
| <P> |
| |
| <B>dmake</B> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| .c.o :; cc -c $< -o $@ |
| <P> |
| </DL> |
| |
| <B>dmake</B> |
| |
| maps this into the following %-rule: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o : %.c; cc -c $< -o $@ |
| <P> |
| </DL> |
| |
| Furthermore, |
| <B>dmake</B> |
| |
| understands several SYSV AUGMAKE special targets and maps them into |
| corresponding %-meta rules. These 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 |
| <DL COMPACT><DT><DD> |
| <P> |
| .suff :; recipe |
| <P> |
| </DL> |
| |
| gets mapped into: |
| <DL COMPACT><DT><DD> |
| <P> |
| % : %.suff; recipe |
| <P> |
| </DL> |
| |
| and the construct |
| <DL COMPACT><DT><DD> |
| <P> |
| .c~.o :; recipe |
| <P> |
| </DL> |
| |
| gets mapped into: |
| <DL COMPACT><DT><DD> |
| <P> |
| %.o : s.%.c ; recipe |
| <P> |
| </DL> |
| |
| 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. |
| <P> |
| |
| <B>dmake</B> |
| |
| 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. For this reason .SUFFIXES is not |
| needed and is completely ignored. |
| <P> |
| |
| 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 <I>transitive closure</I> 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</B> |
| |
| 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</B> |
| |
| 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. |
| <P> |
| |
| A word of caution. |
| <B>dmake</B> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <PRE> |
| |
| %.o : %.c :; rule for making .o from .c |
| %.c : %.y :; rule for making .c from .y |
| % : RCS/%,v :; check out of RCS file |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| will, by performing transitive closure, allow <B>dmake</B> 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: |
| <DL COMPACT><DT><DD> |
| <PRE> |
| .NOINFER : RCS/%,v |
| </PRE> |
| |
| </DL> |
| |
| 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. |
| <P> |
| |
| <B>dmake</B> |
| |
| tries to |
| remove intermediate files resulting from transitive closure if the file |
| is not marked as being PRECIOUS, or the <B>-u</B> 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</B> |
| |
| 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</B> |
| |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| .REMOVE :; $(RM) $< |
| </DL> |
| |
| <A NAME="lbAW"> </A> |
| <H2>MAKING TARGETS</H2> |
| |
| In order to update a target <B>dmake</B> 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</B> |
| |
| supports two types of recipes. The regular recipes and group recipes. |
| <P> |
| |
| When a regular recipe is invoked <B>dmake</B> 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 <B>MSDOS</B>, where dmake internally |
| sets the current working director to match the directory it was in before |
| the command was executed. |
| <P> |
| |
| 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 <B>dmake</B> constructs the command line: |
| <P> |
| $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command) |
| <P> |
| Normally |
| <B>dmake</B> |
| |
| 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. |
| <P> |
| |
| 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</B> |
| |
| 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 ]. |
| <P> |
| |
| The recipe flags [+,-,%,@] are recognized at the start of a recipe line |
| even if they appear in a macro. For example: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| SH = + |
| all: |
| $(SH)echo hi |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| is completely equivalent to writing |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| SH = + |
| all: |
| +echo hi |
| </PRE> |
| |
| <P> |
| </DL> |
| |
| <P> |
| |
| The last step performed by |
| <B>dmake</B> |
| |
| 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</B> |
| |
| then expands the macro COMMAND which by default is set to |
| <DL COMPACT><DT><DD> |
| <P> |
| COMMAND = $(CMNDNAME) $(CMNDARGS) |
| <P> |
| </DL> |
| |
| 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</B>. |
| |
| You can for example define COMMAND to be |
| <DL COMPACT><DT><DD> |
| <P> |
| COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS)) |
| <P> |
| </DL> |
| |
| which dumps the arguments into a temporary file and runs the command |
| <DL COMPACT><DT><DD> |
| <P> |
| $(CMNDNAME) @/tmp/ASAD23043 |
| <P> |
| </DL> |
| |
| 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</B> |
| |
| 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. |
| <A NAME="lbAX"> </A> |
| <H2>MAKING LIBRARIES</H2> |
| |
| Libraries are easy to maintain using <B>dmake</B>. 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</B> |
| |
| 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</B> |
| |
| now supports <B>Elf</B> libraries on systems that support <B>Elf</B> and |
| hence supports, on those systems, long member file names. |
| A small example best illustrates this. |
| <DL COMPACT><DT><DD> |
| <PRE> |
| |
| mylib.a .LIBRARY : mem1.o mem2.o mem3.o |
| rules for making library... |
| # remember to remove .o's when lib is made |
| |
| # equivalent to: '%.o : %.c ; ...' |
| .c.o :; rules for making .o from .c say |
| |
| </PRE> |
| |
| </DL> |
| |
| <B>dmake</B> |
| |
| 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. |
| <P> |
| |
| <B>dmake</B> |
| |
| tries to handle the old library construct format in a sensible way. |
| The construct |
| <I>lib(member.o)</I> |
| |
| is separated and the <I>lib</I> portion is declared |
| as a library target. |
| The new target is defined |
| with the .LIBRARY attribute set and the <I>member.o</I> portion of the |
| construct is |
| declared as a prerequisite of the lib target. |
| If the construct <I>lib(member.o)</I> |
| 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: |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@ $< |
| |
| .c.o :; $(CC) -c $(CFLAGS) -o $@ $< |
| %.a: |
| <DL COMPACT><DT><DD>ar rv $@ $? |
| ranlib $@ |
| rm -rf $? |
| </DL> |
| |
| </PRE> |
| |
| </DL> |
| |
| constructs the following dependency |
| graph. |
| <DL COMPACT><DT><DD> |
| <P> |
| <PRE> |
| a.out : ml.a; $(CC) -o $@ $< |
| ml.a .LIBRARY : a.o b.o |
| |
| %.o : %.c ; $(CC) -c $(CFLAGS) -o $@ $< |
| %.a : |
| <DL COMPACT><DT><DD>ar rv $@ $? |
| ranlib $@ |
| rm -rf $? |
| </DL> |
| |
| </PRE> |
| |
| </DL> |
| |
| and making a.out then works as expected. |
| <P> |
| |
| The same thing happens for any target of the form <I>lib((entry))</I>. |
| These targets have an |
| additional feature in that the <I>entry</I> target has the .SYMBOL attribute |
| set automatically. |
| <P> |
| |
| NOTE: If the notion of entry points is supported by the archive and by |
| <B>dmake</B> (currently not the case) then |
| <B>dmake</B> |
| |
| 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 <I>entry</I> 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). |
| <P> |
| |
| Finally, when |
| <B>dmake</B> |
| |
| 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</B>. |
| |
| <A NAME="lbAY"> </A> |
| <H2>KEEP STATE</H2> |
| |
| <B>dmake</B> |
| |
| 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</B> |
| |
| 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. |
| <P> |
| |
| 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. |
| <P> |
| |
| The Sun Microsystem's Make construct |
| <DL COMPACT><DT><DD> |
| <P> |
| .KEEP_STATE : |
| <P> |
| </DL> |
| |
| is recognized and is mapped to <B>.KEEP_STATE:=_state.mk</B>. |
| The |
| <B>dmake</B> |
| |
| 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</B> |
| |
| instead provides the tool, <B>cdepend</B>, to scan C source files and to produce |
| depedency information. Users are free to modify cdepend to produce other |
| dependency files. (NOTE: |
| <B>cdepend</B> |
| |
| does not come with the distribution at this time, but will be available in |
| a patch in the near future) |
| <A NAME="lbAZ"> </A> |
| <H2>MULTI PROCESSING</H2> |
| |
| If the architecture supports it then <B>dmake</B> is capable of making a target's |
| prerequisites in parallel. <B>dmake</B> 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. |
| <B>dmake</B> 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 <B>-P 4</B> then four child processes are |
| run concurrently but <B>dmake</B> 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. |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT>1.<DD> |
| 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. |
| <DT>2.<DD> |
| 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. |
| <DT>3.<DD> |
| 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. |
| <DT>4.<DD> |
| 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. |
| </DL> |
| </DL> |
| |
| <P> |
| |
| 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. |
| <A NAME="lbBA"> </A> |
| <H2>CONDITIONALS</H2> |
| |
| <B>dmake</B> |
| |
| supports a makefile construct called a <I>conditional</I>. 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| .IF <I>expression</I> |
| ... if text ... |
| .ELIF <I>expression</I> |
| ... if text ... |
| .ELSE |
| ... else text ... |
| .END |
| </DL> |
| </PRE> |
| |
| <P> |
| 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. |
| <P> |
| |
| <I>expression</I> can be one of the following forms: |
| <P> |
| String evaluation |
| <BR> |
| |
| <text> | <text> == <text> | <text> != <text> |
| <P> |
| Numeric evaluation |
| <BR> |
| |
| <text> <= <text> | <text> >= <text> |
| <P> |
| Boolean evaluation |
| <BR> |
| |
| ( <text> ) | <text> || <text> | <text> && <text> |
| <P> |
| where <I>text</I> 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 the expanded expressions are converted to an integer number. |
| 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. |
| <A NAME="lbBB"> </A> |
| <H2>EXAMPLES</H2> |
| |
| <DL COMPACT><DT><DD> |
| <PRE> |
| |
| # 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 $@ |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| 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: |
| <P> |
| %.o : %.c; cc -c $(CFLAGS) -o $@ $< |
| <P> |
| Since there exists a rule (defined in the startup file) |
| for making .o's from .c's |
| <B>dmake</B> will use that rule |
| for manufacturing a .o from a .c and we can specify our dependencies |
| more concisely. |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| prgm : a.o b.o |
| cc -o prgm $< |
| a.o b.o : g.h |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| A more general way to say the above using the new macro expansions |
| would be: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| SRC = a b |
| OBJ = {$(SRC)}.o |
| |
| prgm : $(OBJ) |
| cc -o $@ $< |
| |
| $(OBJ) : g.h |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| If we want to keep the objects in a separate directory, called |
| objdir, then we would write |
| something like this. |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| SRC = a b |
| OBJ = {$(SRC)}.o |
| |
| prgm : $(OBJ) |
| cc $< -o $@ |
| |
| $(OBJ) : g.h |
| %.o : %.c |
| $(CC) -c $(CFLAGS) -o $(@:f) $< |
| mv $(@:f) objdir |
| |
| .SOURCE.o : objdir # tell dmake to look here for .o's |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| 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) |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| SRC = a b |
| LIB = lib |
| LIBm = { $(SRC) }.o |
| |
| prgm: $(LIB) |
| cc -o $@ $(LIB) |
| |
| $(LIB) .LIBRARY : $(LIBm) |
| ar rv $@ $< |
| rm $< |
| </PRE> |
| |
| </DL> |
| |
| <P> |
| 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: |
| <P> |
| <DL COMPACT><DT><DD> |
| <PRE> |
| SRC = f:a f:b |
| LIB = lib |
| LIBm = "{ $(SRC) }.o" # put quotes around each token |
| |
| prgm: $(LIB) |
| cc -o $@ $(LIB) |
| |
| $(LIB) .LIBRARY : $(LIBm) |
| ar rv $@ $< |
| rm $< |
| </PRE> |
| |
| </DL> |
| |
| <A NAME="lbBC"> </A> |
| <H2>COMPATIBILITY</H2> |
| |
| There are two notable differences between |
| <B>dmake</B> |
| |
| and the standard version of BSD UNIX 4.2/4.3 Make. |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT>1.<DD> |
| 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 |
| <P> |
| target: *.h |
| <P> |
| will cause UNIX make to expand the *.h into "a.h b.h c.h". <B>dmake</B> |
| does not support this type of filename expansion. |
| <DT>2.<DD> |
| Unlike UNIX make, touching a library member causes <B>dmake</B> |
| 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 <B>dmake</B> touches the library file itself, and prints a warning. |
| </DL> |
| </DL> |
| |
| <P> |
| |
| <B>dmake</B> is not compatible with GNU Make. In particular it does not |
| understand GNU Make's macro expansions that query the file system. |
| <P> |
| |
| <B>dmake</B> |
| |
| is fully compatible with SYSV AUGMAKE, and supports the following AUGMAKE |
| features: |
| <DL COMPACT><DT><DD> |
| <DL COMPACT> |
| <DT>1.<DD> |
| GNU Make style <B>include</B>, and <B>if/else/endif</B> directives are allowed |
| in non-group recipes. |
| Thus, the word <B>include</B> appearing at |
| the start of a line that is not part of a gruop recipe will be mapped |
| to the ".INCLUDE" directive that <B>damke</B> uses. |
| Similarly, the words <B>ifeq</B>,<B>ifneq</B>,<B>elif</B>,<B>else</B>, |
| and <B>endif</B> are mapped to their corresponding <B>dmake</B> equivalents. |
| <DT>2.<DD> |
| 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: |
| <P> |
| str[ |\t][ |\t]* |
| <P> |
| (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 <I>sub</I> is expanded before the substitution is made, if you specify |
| -A on the command line then sub is not expanded. |
| <DT>3.<DD> |
| The macro % is defined to be $@ (ie. $% expands to the same value as $@). |
| <DT>4.<DD> |
| The AUGMAKE notion of libraries is handled correctly. |
| <DT>5.<DD> |
| When defining special targets for the inference rules and the AUGMAKE special |
| target handling is enabled then the special target |
| .X is equivalent to the %-rule "% : %.X". |
| <DT>6.<DD> |
| Directories are always made if you specify <B>-A</B>. This is consistent |
| with other UNIX versions of Make. |
| <DT>7.<DD> |
| Makefiles that utilize virtual targets to force making of other targets work |
| as expected if AUGMAKE special target handling is enabled. For example: |
| <P> |
| <PRE> |
| FRC: |
| myprog.o : myprog.c $(FRC) ; ... |
| </PRE> |
| |
| <P> |
| Works as expected if you issue the command |
| <P> |
| '<B>dmake</B> -A FRC=FRC' |
| <P> |
| 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). |
| <DT>8.<DD> |
| The <B>MSDOS</B> version of <B>dmake</B> now supports a single buitin runtime |
| command <B>noop</B>, which returns success if requested and does nothing. |
| </DL> |
| </DL> |
| |
| <A NAME="lbBD"> </A> |
| <H2>LIMITS</H2> |
| |
| 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</B> |
| |
| text diversions may help in these situations.) |
| <A NAME="lbBE"> </A> |
| <H2>PORTABILITY</H2> |
| |
| 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</B> |
| |
| 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. |
| <P> |
| |
| 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. |
| <A NAME="lbBF"> </A> |
| <H2>FILES</H2> |
| |
| Makefile, makefile, startup.mk (use dmake -V to tell you where the startup |
| file is) |
| <A NAME="lbBG"> </A> |
| <H2>SEE ALSO</H2> |
| |
| <A HREF="http://localhost/cgi-bin/man/man2html?1+sh">sh</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+csh">csh</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+touch">touch</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+f77">f77</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+pc">pc</A>(1), <A HREF="http://localhost/cgi-bin/man/man2html?1+cc">cc</A>(1) |
| <BR> |
| |
| S.I. Feldman <I>Make - A Program for Maintaining Computer Programs</I> |
| <A NAME="lbBH"> </A> |
| <H2>AUTHOR</H2> |
| |
| Dennis Vadura, <A HREF="mailto:dvadura@wticorp.com">dvadura@wticorp.com</A> |
| <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 <B>dmake</B> one of the best Make tools |
| available. |
| <A NAME="lbBI"> </A> |
| <H2>BUGS</H2> |
| |
| Some system commands return non-zero status inappropriately. |
| Use |
| <B>-i</B> |
| |
| (`-' within the makefile) to overcome the difficulty. |
| <P> |
| |
| Some systems do not have easily accessible |
| time stamps for library members (MSDOS, AMIGA, etc) |
| for these <B>dmake</B> 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. |
| <P> |
| |
| This man page is way too long. |
| <A NAME="lbBJ"> </A> |
| <H2>WARNINGS</H2> |
| |
| Rules supported by <A HREF="http://localhost/cgi-bin/man/man2html?1+make">make</A>(1) may not work if transitive closure is turned off |
| (-T, .NOINFER). |
| <P> |
| |
| PWD from csh/ksh will cause problems if a cd operation is performed and |
| -e or -E option is used. |
| <P> |
| |
| Using internal macros such as COMMAND, may wreak havoc if you don't understand |
| their functionality. |
| <P> |
| |
| <HR> |
| <A NAME="index"> </A><H2>Index</H2> |
| <DL> |
| <DT><A HREF="#lbAB">NAME</A><DD> |
| <DT><A HREF="#lbAC">SYNOPSIS</A><DD> |
| <DT><A HREF="#lbAD">DESCRIPTION</A><DD> |
| <DT><A HREF="#lbAE">OPTIONS</A><DD> |
| <DT><A HREF="#lbAF">INDEX</A><DD> |
| <DT><A HREF="#lbAG">STARTUP</A><DD> |
| <DT><A HREF="#lbAH">SYNTAX</A><DD> |
| <DT><A HREF="#lbAI">ATTRIBUTES</A><DD> |
| <DT><A HREF="#lbAJ">MACROS</A><DD> |
| <DT><A HREF="#lbAK">RULES AND TARGETS</A><DD> |
| <DT><A HREF="#lbAL">RECIPES</A><DD> |
| <DT><A HREF="#lbAM">TEXT DIVERSIONS</A><DD> |
| <DT><A HREF="#lbAN">SPECIAL TARGETS</A><DD> |
| <DT><A HREF="#lbAO">SPECIAL MACROS</A><DD> |
| <DT><A HREF="#lbAP">CONTROL MACROS</A><DD> |
| <DT><A HREF="#lbAQ">RUNTIME MACROS</A><DD> |
| <DT><A HREF="#lbAR">FUNCTION MACROS</A><DD> |
| <DT><A HREF="#lbAS">CONDITIONAL MACROS</A><DD> |
| <DT><A HREF="#lbAT">DYNAMIC PREREQUISITES</A><DD> |
| <DT><A HREF="#lbAU">BINDING TARGETS</A><DD> |
| <DT><A HREF="#lbAV">PERCENT() RULES AND MAKING INFERENCES</A><DD> |
| <DT><A HREF="#lbAW">MAKING TARGETS</A><DD> |
| <DT><A HREF="#lbAX">MAKING LIBRARIES</A><DD> |
| <DT><A HREF="#lbAY">KEEP STATE</A><DD> |
| <DT><A HREF="#lbAZ">MULTI PROCESSING</A><DD> |
| <DT><A HREF="#lbBA">CONDITIONALS</A><DD> |
| <DT><A HREF="#lbBB">EXAMPLES</A><DD> |
| <DT><A HREF="#lbBC">COMPATIBILITY</A><DD> |
| <DT><A HREF="#lbBD">LIMITS</A><DD> |
| <DT><A HREF="#lbBE">PORTABILITY</A><DD> |
| <DT><A HREF="#lbBF">FILES</A><DD> |
| <DT><A HREF="#lbBG">SEE ALSO</A><DD> |
| <DT><A HREF="#lbBH">AUTHOR</A><DD> |
| <DT><A HREF="#lbBI">BUGS</A><DD> |
| <DT><A HREF="#lbBJ">WARNINGS</A><DD> |
| </DL> |
| <HR> |
| This document was created by man2html from the dmake manual page. |
| </body> |
| </HTML> |