| blob | 9961119ddf6b36f6f38fbd26f53977d1d8647d3f |
4 DMAKE(1) DMAKE(1)
7 NAME
8 dmake - maintain program groups, or interdependent files
10 SYNOPSIS
11 dmake [-P#] [-{f|C|K} file] [-{w|W} target ...]
12 [macro[[!][*][+][:]]=value ...] [-ABcdeEghiknpqrsStTuVxX]
13 [-v[cdfimrtw]] [-m[trae]] [target ...]
15 DESCRIPTION
16 dmake is a re-implementation of the UNIX Make utility with significant
17 enhancements. dmake executes commands found in an external file called
18 a makefile to update one or more target names. Each target may depend
19 on zero or more prerequisite targets. If any of the target's prerequi-
20 sites is newer than the target or if the target itself does not exist,
21 then dmake will attempt to make the target.
23 If no -f command line option is present then dmake searches for an
24 existing makefile from the list of prerequisites specified for the spe-
25 cial target .MAKEFILES (see the STARTUP section for more details). If
26 "-" is the name of the file specified to the -f flag then dmake uses
27 standard input as the source of the makefile text.
29 Any macro definitions (arguments with embedded "=" signs) that appear
30 on the command line are processed first and supercede definitions for
31 macros of the same name found within the makefile. In general it is
32 impossible for definitions found inside the makefile to redefine a
33 macro defined on the command line, see the MACROS section for excep-
34 tions.
36 If no target names are specified on the command line, then dmake uses
37 the first non-special target found in the makefile as the default tar-
38 get. See the SPECIAL TARGETS section for the list of special targets
39 and their function. Makefiles written for most previous versions of
40 Make will be handled correctly by dmake. Known differences between
41 dmake and other versions of make are discussed in the COMPATIBILITY
42 section found at the end of this document. dmake returns 0 if no
43 errors were detected and a non-zero result if an error occurred.
45 OPTIONS
46 -A Enable AUGMAKE special inference rule transformations (see the
47 "PERCENT(%) RULES" and "AUGMAKE META RULES" sections), these are
48 set to off by default.
50 -B Enable the use of spaces instead of <tabs> to begin recipe
51 lines. This flag equivalent to the .NOTABS special macro and is
52 further described below.
54 -c Use non-standard comment stripping. If you specify -c then
55 dmake will treat any # character as a start of comment character
56 wherever it may appear unless it is escaped by a \.
58 -C [+]file
59 This option writes to file a copy of standard output and stan-
60 dard error from any child processes and from the dmake process
64 Dmake Version 4.12 2008-02-26 1
70 DMAKE(1) DMAKE(1)
73 itself. If you specify a + prior to the file name then the text
74 is appended to the previous contents of file. This option is
75 active in the MSDOS implementation only and is ignored by non-
76 MSDOS versions of dmake.
78 -d Disable the use of the directory cache. Normally dmake caches
79 directories as it checks file timestamps. Giving this flag is
80 equivalent to the .DIRCACHE attribute or macro being set to no.
82 -E Read the environment and define all strings of the form
83 'ENV-VAR=evalue' defined within as macros whose name is ENV-VAR,
84 and whose value is 'evalue'. The environment is processed prior
85 to processing the user specified makefile thereby allowing defi-
86 nitions in the makefile to override definitions in the environ-
87 ment.
89 -e Same as -E, except that the environment is processed after the
90 user specified makefile has been processed (thus definitions in
91 the environment override definitions in the makefile). The -e
92 and -E options are mutually exclusive. If both are given the
93 latter takes effect.
95 -f file
96 Use file as the source for the makefile text. Only one -f
97 option is allowed.
99 -g Globally disable group recipe parsing, equivalent to the
100 .IGNOREGROUP attribute or macro being set to yes at the start of
101 the makefile.
103 -h Print the command summary for dmake.
105 -i Tells dmake to ignore errors, and continue making other targets.
106 This is equivalent to the .IGNORE attribute or macro.
108 -K file
109 Turns on .KEEP_STATE state tracking and tells dmake to use file
110 as the state file.
112 -k Causes dmake to ignore errors caused by command execution and to
113 make all targets not depending on targets that could not be
114 made. Ordinarily dmake stops after a command returns a non-zero
115 status, specifying -k causes dmake to ignore the error and con-
116 tinue to make as much as possible.
118 -m[trae]
119 Measure timing information. Print the time when targets and/or
120 recipes are started and finished to stdout. The following format
121 is used:
123 {s|e} {target|recipe} time maketarget
125 s or e stands for started or ended, target or recipe denotes if
126 this line refers to the whole target or a recipe. time is
130 Dmake Version 4.12 2008-02-26 2
136 DMAKE(1) DMAKE(1)
139 displayed in Unix time format, i.e. the number of seconds since
140 an epoch. (Since 1970-01-01T00:00:00Z). maketarget obviously
141 represents the target the timing information is given for. The
142 optional flags [trae] can be used to change the information that
143 is displayed. If no optional flags are given only the t flag is
144 assumed to be selected, ie. -mt. The optional flags stand for:
146 t Display the start and end time of each target.
148 r Display the start and end time of each recipe.
150 a Display the target as an absolute path, i.e. prepend the
151 current working directory.
153 e Also display the start and end time of the $(shell com-
154 mand) function (aka. shell escape) macros.
156 -n Causes dmake to print out what it would have executed, but does
157 not actually execute the commands. A special check is made for
158 the string "$(MAKE)" inside a recipe line, if it is found, the
159 line is expanded and invoked, thereby enabling recursive makes
160 to give a full description of all that they will do. This check
161 is disabled inside group recipes.
163 -p Print out a version of the digested makefile in human readable
164 form. (useful for debugging, but cannot be re-read by dmake)
166 -P# On systems that support multi-processing cause dmake to use #
167 concurrent child processes to make targets. See the "MULTI PRO-
168 CESSING" section for more information.
170 -q Check and see if the target is up to date. Exits with code 0 if
171 up to date, 1 otherwise.
173 -r Tells dmake not to read the initial startup makefile, see
174 STARTUP section for more details.
176 -s Tells dmake to do all its work silently and not echo the com-
177 mands it is executing to stdout (also suppresses warnings).
178 This is equivalent to the .SILENT attribute or macro.
180 -S Force sequential execution of recipes on architectures which
181 support concurrent makes. For backward compatibility with old
182 makefiles that have nasty side-effect prerequisite dependencies.
183 (Implies -P1)
185 -t Causes dmake to touch the targets and bring them up to date
186 without executing any commands. Note that targets will not be
187 created if they do not already exist.
189 -T Tells dmake to not perform transitive closure on the inference
190 graph.
192 -u Force an unconditional update. (ie. do everything that would be
193 done if everything that a target depended on was out of date)
197 Dmake Version 4.12 2008-02-26 3
203 DMAKE(1) DMAKE(1)
206 -v[cdfimrtw]
207 Verbose flag, when making targets print to stdout what we are
208 going to make and what we think its time stamp is. The optional
209 flags [cdfimrtw] can be used to restrict the information that is
210 displayed. In the absence of any optional flags all are assumed
211 to be given (ie. -v is equivalent to -vcdfimrtw). The meanings
212 of the optional flags are:
214 c Notify of directory cache operations only.
216 d Notify of change directory operations only.
218 f Notify of file I/O operations only.
220 i Notify of inference algorithm operation only.
222 m Notify of target update operations only.
224 r Force output of recipe lines, warnings and executed com-
225 mands. This switch is usefull when debugging makefiles
226 that disable the output using the @ or @@ property for
227 recipe lines or the .SILENT target/attribute. It also
228 overrides the -s flag.
230 t Keep any temporary files created; normally they are auto-
231 matically deleted.
233 w Notify of non-essential warnings (these are historical).
235 -V Print the version of dmake, and values of builtin macros.
237 -W target
238 Run dmake pretending that target is out of date.
240 -w target
241 What if? Show what would be made if target were out of date.
243 -x Upon processing the user makefile export all non-internally
244 defined macros to the user's environment. This option together
245 with the -e option allows SYSV AUGMAKE recursive makes to func-
246 tion as expected.
248 -X Inhibit the execution of #! lines found at the beginning of a
249 makefile. The use of this flag prevents non-termination of
250 recursive make invocations.
252 INDEX
253 Here is a list of the sections that follow and a short description of
254 each. Perhaps you won't have to read the entire man page to find what
255 you need.
257 STARTUP Describes dmake initialization.
259 SYNTAX Describes the syntax of makefile expressions.
264 Dmake Version 4.12 2008-02-26 4
270 DMAKE(1) DMAKE(1)
273 ATTRIBUTES Describes the notion of attributes and how they are
274 used when making targets.
276 MACROS Defining and expanding macros.
278 RULES AND TARGETS How to define targets and their prerequisites.
280 RECIPES How to tell dmake how to make a target.
282 BUILTIN COMMANDS Internal dmake commands.
284 TEXT DIVERSIONS How to use text diversions in recipes and macro
285 expansions.
287 VIRTUAL TARGETS Targets that only enforce dependencies, but which
288 can not create a target file.
290 SPECIAL TARGETS Some targets are special.
292 SPECIAL MACROS Macros used by dmake to alter the processing of the
293 makefile, and those defined by dmake for the user.
295 CONTROL MACROS Itemized list of special control macros.
297 RUNTIME MACROS Discussion of special run-time macros such as $@ and
298 $<.
300 FUNCTION MACROS Description of functional macros.
302 CONDITIONAL MACROS Target specific conditional macros.
304 DYNAMIC PREREQUISITES
305 Processing of prerequisites which contain macro
306 expansions in their name.
308 BINDING TARGETS The rules that dmake uses to bind a target to an
309 existing file in the file system.
311 PERCENT(%) RULES Specification of recipes to be used by the inference
312 algorithm.
314 MAKING INFERENCES The rules that dmake uses when inferring how to make
315 a target which has no explicit recipe. This and the
316 previous section are really a single section in the
317 text.
319 AUGMAKE META RULES A subclass of the PERCENT(%) RULES.
321 MAKING TARGETS How dmake makes targets other than libraries.
323 MAKING LIBRARIES How dmake makes libraries.
325 KEEP STATE A discussion of how .KEEP_STATE works.
327 MULTI PROCESSING Discussion of dmake's parallel make facilities for
328 architectures that support them.
332 Dmake Version 4.12 2008-02-26 5
338 DMAKE(1) DMAKE(1)
341 CONDITIONALS Conditional expressions which control the processing
342 of the makefile.
344 EXAMPLES Some hopefully useful examples.
346 COMPATIBILITY How dmake compares with previous versions of make.
348 LIMITS Limitations of dmake.
350 PORTABILITY Comments on writing portable makefiles.
352 FILES Files used by dmake.
354 SEE ALSO Other related programs, and man pages.
356 AUTHOR The guy responsible for this thing.
358 BUGS Hope not.
360 STARTUP
361 When dmake begins execution it first processes the command line and
362 then processes an initial startup-makefile. This is followed by an
363 attempt to locate and process a user supplied makefile. The startup
364 file defines the default values of all required control macros and the
365 set of default rules for making targets and inferences. When searching
366 for the startup makefile, dmake searches the following locations, in
367 the order specified, until a startup file is located:
370 1. The location given as the value of the macro MAKESTARTUP
371 defined on the command line.
373 2. The location given as the value of the environment vari-
374 able MAKESTARTUP defined in the current environment.
376 3. The location given as the value of the macro MAKESTARTUP
377 defined internally within dmake. In this version, the
378 internal definition of MAKESTARTUP is "$(DMAKE-
379 ROOT)/startup.mk", so you can set the environment vari-
380 able DMAKEROOT to the location of your startup directory.
382 If DMAKEROOT is not changed, for native Windows dmake
383 versions its value defaults to "$(ABSMAKECMD:d)startup"
384 (see definition of ABSMAKECMD for details). For unix
385 like versions build with the autotools build system it
386 defaults to the value of "${prefix}/share/startup" at
387 build time. The actual value, usually something like
388 /usr/local/share/startup can be checked with the -V com-
389 mand line switch.
391 The above search is disabled by specifying the -r option on the command
392 line. An error is issued if a startup makefile cannot be found and the
393 -r option was not specified. A user may substitute a custom startup
394 file by defining the MAKESTARTUP environment variable or by redefining
395 the MAKESTARTUP macro on the command line. To determine where dmake
396 looks for the default startup file, check your environment or issue the
400 Dmake Version 4.12 2008-02-26 6
406 DMAKE(1) DMAKE(1)
409 command "dmake -V".
411 A similar search is performed to locate a default user makefile when no
412 -f command line option is specified. By default, the prerequisite list
413 of the special target .MAKEFILES specifies the names of possible make-
414 files and the search order that dmake should use to determine if one
415 exists. A typical definition for this target is:
417 .MAKEFILES : makefile.mk Makefile makefile
419 dmake will first look for makefile.mk and then the others. If a pre-
420 requisite cannot be found dmake will try to make it before going on to
421 the next prerequisite. For example, makefile.mk can be checked out of
422 an RCS file if the proper rules for doing so are defined in the startup
423 file.
425 If the first line of the user makefile is of the form:
427 #!command command_args
429 then dmake will expand and run the command prior to reading any addi-
430 tional input. If the return code of the command is zero then dmake
431 will continue on to process the remainder of the user makefile, if the
432 return code is non-zero then dmake will exit.
434 dmake builds the internal dependency graph as it parses a user speci-
435 fied makefile. The graph is rooted at the special target .ROOT. .ROOT
436 is the top level target that dmake builds when it starts to build tar-
437 gets. All user specified targets (those from the command line or taken
438 as defaults from the makefile) are made prerequisites of the special
439 target .TARGETS. dmake by default creates the relationship that .ROOT
440 depends on .TARGETS and as a result everything is made. This approach
441 allows the user to customize, within their makefile, the order and
442 which, target, is built first. For example the default makefiles come
443 with settings for .ROOT that specify:
445 .ROOT .PHONY .NOSTATE .SEQUENTIAL : .INIT .TARGETS .DONE
447 with .INIT and .DONE defined as:
449 .INIT .DONE .PHONY:;
451 which nicely emulates the behaviour of Sun's make extensions. The
452 building of .ROOT's prerequisites is always forced to be sequential.
453 However, this definition is trivially changed by supplying the defini-
454 tion:
456 .ROOT : .TARGETS
458 which skips the preamble and postamble phases of building .TARGETS.
460 Please note that even though .INIT and .DONE are special exceptions,
461 see section SPECIAL TARGETS, the use of self defined targets starting
462 with `.' should be avoided as they would be handled as .<suffix> meta
463 targets. The target names _INIT and _DONE for example would work
464 equally well without the .<suffix> drawback.
468 Dmake Version 4.12 2008-02-26 7
474 DMAKE(1) DMAKE(1)
477 SYNTAX
478 This section is a summary of the syntax of makefile statements. The
479 description is given in a style similar to BNF, where { } enclose items
480 that may appear zero or more times, and [ ] enclose items that are
481 optional. Alternative productions for a left hand side are indicated
482 by '->', and newlines are significant. All symbols in bold type are
483 text or names representing text supplied by the user.
488 Makefile -> { Statement }
491 Statement -> Macro-Definition
492 -> Conditional-Macro-Definition
493 -> Conditional
494 -> Rule-Definition
495 -> Attribute-Definition
498 Macro-Definition -> MACRO = LINE
499 -> MACRO [!]*= LINE
500 -> MACRO [!]:= LINE
501 -> MACRO [!]*:= LINE
502 -> MACRO [!]+= LINE
503 -> MACRO [!]+:= LINE
506 Conditional-Macro-Definition -> TARGET ?= Macro-Definition
509 Conditional -> .IF expression
510 Makefile
511 [ .ELIF expression
512 Makefile ]
513 [ .ELSE
514 Makefile ]
515 .END
518 expression -> LINE
519 -> STRING
520 -> expression == expression
521 -> expression != expression
522 -> expression <= expression
523 -> expression >= expression
524 -> ( expression )
525 -> expression || expression
526 -> expression && expression
529 Rule-Definition -> target-definition
530 [ recipe ]
532 target-definition -> targets [attrs] op { PREREQUISITE } [; rcp-line]
536 Dmake Version 4.12 2008-02-26 8
542 DMAKE(1) DMAKE(1)
545 targets -> target { targets }
546 -> "target" { targets }
549 target -> special-target
550 -> TARGET
553 attrs -> attribute { attrs }
554 -> "attribute" { attrs }
557 op -> : { modifier }
560 modifier -> :
561 -> ^
562 -> !
563 -> -
564 -> |
567 recipe -> { TAB rcp-line }
568 -> [@[@]][%][-] [
569 { LINE }
570 ]
573 rcp-line -> [@[@]][%][-][+] LINE
576 Attribute-Definition -> attrs : targets
579 attribute -> .EPILOG
580 -> .ERRREMOVE
581 -> .EXECUTE
582 -> .GROUP
583 -> .IGNORE
584 -> .IGNOREGROUP
585 -> .LIBRARY
586 -> .MKSARGS
587 -> .NOINFER
588 -> .NOSTATE
589 -> .PHONY
590 -> .PRECIOUS
591 -> .PROLOG
592 -> .SETDIR=path
593 -> .SILENT
594 -> .SEQUENTIAL
595 -> .SWAP
596 -> .USESHELL
597 -> .SYMBOL
598 -> .UPDATEALL
599 -> .WINPATH
604 Dmake Version 4.12 2008-02-26 9
610 DMAKE(1) DMAKE(1)
613 special-target -> .ERROR
614 -> .EXIT
615 -> .EXPORT
616 -> .GROUPEPILOG
617 -> .GROUPPROLOG
618 -> .IMPORT
619 -> .INCLUDE
620 -> .INCLUDEDIRS
621 -> .MAKEFILES
622 -> .REMOVE
623 -> .ROOT
624 -> .SOURCE
625 -> .SOURCE.suffix
626 -> .SUFFIXES (deprecated)
627 -> .TARGETS
628 -> .INIT
629 -> .DONE
630 -> .suffix
631 -> .suffix1.suffix2
634 Where, TAB represents a <tab> character, STRING represents an arbitrary
635 sequence of characters, and LINE represents a possibly empty sequence
636 of characters terminated by a non-escaped (not immediately preceded by
637 a backslash '\') new-line character. MACRO, PREREQUISITE, and TARGET
638 each represent a string of characters not including space or tab which
639 respectively form the name of a macro, prerequisite or target. The
640 name may itself be a macro expansion expression. A LINE can be contin-
641 ued over several physical lines by terminating it with a single back-
642 slash character. Comments are initiated by the pound # character and
643 extend to the end of line. All comment text is discarded, a '#' may be
644 placed into the makefile text by escaping it with '\' (ie. \# trans-
645 lates to # when it is parsed). An exception to this occurs when a # is
646 seen inside a recipe line that begins with a <tab> or is inside a group
647 recipe. If you specify the -c command line switch then this behavior
648 is disabled and dmake will treat all # characters as start of comment
649 indicators unless they are escaped by \. A set of continued lines may
650 be commented out by placing a single # at the start of the first line.
651 A continued line cannot span more than one makefile.
653 white space is defined to be any combination of <space>, <tab>, and the
654 sequence \<nl> when \<nl> is used to terminate a LINE. Note the special
655 treatment of \<nl> in macro definion and recipe lines below. When pro-
656 cessing macro definition lines, any amount of white space is allowed on
657 either side of the macro operator and white space is stripped from both
658 before and after the macro value string. A \<nl> sequence in a macro
659 definition is deleted from the macro value before assigning this value.
660 During recipe expansion the sequence \<nl> is treated as white space
661 but is deleted from the final recipe string. You must escape the \<nl>
662 with another \ in order to get a \ at the end of a recipe or macro def-
663 inition line.
665 When processing target definition lines, the recipe for a target must,
666 in general, follow the first definition of the target (See the RULES
667 AND TARGETS section for an exception), and the recipe may not span
668 across multiple makefiles. Any targets and prerequisites found on a
672 Dmake Version 4.12 2008-02-26 10
678 DMAKE(1) DMAKE(1)
681 target definition line are taken to be white space separated tokens.
682 The rule operator (op in SYNTAX section) is also considered to be a
683 token but does not require white space to precede or follow it. Since
684 the rule operator begins with a `:', traditional versions of make do
685 not allow the `:' character to form a valid target name. dmake allows
686 `:' to be present in target/prerequisite names as long as the entire
687 target/prerequisite name is quoted. For example:
689 a:fred : test
691 would be parsed as TARGET = a, PREREQUISITES={fred, :, test}, which is
692 not what was intended. To fix this you must write:
694 "a:fred" : test
696 Which will be parsed as expected. Quoted target and prerequisite spec-
697 ifications may also contain white space thereby allowing the use of
698 complex function macro expressions.. See the EXAMPLES section for how
699 to apply " quoting to a list of targets.
701 ATTRIBUTES
702 dmake defines several target attributes. Attributes may be assigned to
703 a single target, a group of targets, or to all targets in the makefile.
704 Attributes are used to modify dmake actions during target update. The
705 recognized attributes are:
708 .EPILOG Insert shell epilog code when executing a group recipe
709 associated with any target having this attribute set.
711 .ERRREMOVE Always remove any target having this attribute if an error
712 is encountered while making them. Setting this attribute
713 overrides the .PRECIOUS attribute.
715 .EXECUTE If the -n flag was given then execute the recipe associated
716 with any target having this attribute set.
718 .FIRST Used in conjunction with .INCLUDE. Terminates the inclu-
719 sion with the first successfully included prerequisite.
721 .GROUP Force execution of a target's recipe as a group recipe.
723 .IGNORE Ignore an error when trying to make any target with this
724 attribute set.
726 .IGNOREGROUP
727 Disable the special meaning of '[' to initiate a group
728 recipe.
730 .LIBRARY Target is a library.
732 .MKSARGS If running in an MSDOS environment then use MKS extended
733 argument passing conventions to pass arguments to commands.
734 Non-MSDOS environments ignore this attribute.
736 .NOINFER Any target with this attribute set will not be subjected to
737 transitive closure if it is inferred as a prerequisite of a
741 Dmake Version 4.12 2008-02-26 11
747 DMAKE(1) DMAKE(1)
750 target whose recipe and prerequisites are being inferred.
751 (i.e. the inference algorithm will not use any prerequisite
752 with this attribute set, as a target) If specified as
753 '.NOINFER:' (ie. with no prerequisites or targets) then the
754 effect is equivalent to specifying -T on the command line.
756 .NOSTATE Any target with this attribute set will not have command
757 line flag information stored in the state file if
758 .KEEP_STATE has been enabled.
760 .PHONY Any target with this attribute set will have its recipe
761 executed each time the target is made even if a file match-
762 ing the target name can be located. Any targets that have
763 a .PHONY attributed target as a prerequisite will be made
764 each time the .PHONY attributed prerequisite is made.
766 .PRECIOUS Do not remove associated target under any circumstances.
767 Set by default for any targets whose corresponding files
768 exist in the file system prior to the execution of dmake.
770 .PROLOG Insert shell prolog code when executing a group recipe
771 associated with any target having this attribute set.
773 .SEQUENTIAL Force a sequential make of the associated target's prereq-
774 uisites. If set as a global attribute this implies setting
775 MAXPROCESS=1.
777 .SETDIR Change current working directory to specified directory
778 when making the associated target. You must specify the
779 directory at the time the attribute is specified. To do
780 this simply give .SETDIR=path as the attribute. path is
781 expanded and the result is used as the value of the direc-
782 tory to change to. If path contains $$@ then the name of
783 the target to be built is used in computing the path to
784 change directory to. If path is surrounded by single
785 quotes then path is not expanded, and is used literally as
786 the directory name. If the path contains any `:' charac-
787 ters then the entire attribute string must be quoted using
788 ". If a target having this attribute set also has the
789 .IGNORE attribute set then if the change to the specified
790 directory fails it will be ignored, and no error message
791 will be issued.
793 .SILENT Do not echo the recipe lines when making any target with
794 this attribute set, and do not issue any warnings.
796 .SWAP Under MSDOS when making a target with this attribute set
797 swap the dmake executable to disk prior to executing the
798 recipe line. Also see the '%' recipe line flag defined in
799 the RECIPES section.
801 .SYMBOL Target is a library member and is an entry point into a
802 module in the library. This attribute is used only when
803 searching a library for a target. Targets of the form
804 lib((entry)) have this attribute set automatically.
806 .USESHELL Force each recipe line of a target to be executed using a
807 shell. Specifying this attribute is equivalent to
811 Dmake Version 4.12 2008-02-26 12
817 DMAKE(1) DMAKE(1)
820 specifying the '+' character at the start of each line of a
821 non-group recipe.
823 .UPDATEALL Indicates that all the targets listed in this rule are
824 updated by the execution of the accompanying recipe. A
825 common example is the production of the y.tab.c and y.tab.h
826 files by yacc when it is run on a grammar. Specifying
827 .UPDATEALL in such a rule prevents the running of yacc
828 twice, once for the y.tab.c file and once for the y.tab.h
829 file. .UPDATEALL targets that are specified in a single
830 rule are treated as a single target and all timestamps are
831 updated whenever any target in the set is made. As a side-
832 effect, dmake internally sorts such targets in ascending
833 alphabetical order and the value of $@ is always the first
834 target in the sorted set.
836 .WINPATH Switch between default (POSIX) and Windows style path rep-
837 resentation. (This attribute is specific for cygwin dmake
838 executables and non-cygwin environments ignore this
839 attribute.)
841 Under Cygwin it can be useful to generate Windows style
842 paths (with regular slashes) instead of the default cygwin
843 style (POSIX) paths for dmake's dynamic macros. The
844 affected macros are $@, $*, $>, $?, $<, $&, $^ and
845 $(MAKEDIR), $(PWD), $(TMD), $(TMPFILE) and the $(mktmp ...)
846 function macro. This feature can be used to create DOS
847 style path parameters for native W32 programs from dynamic
848 macros.
850 Note that the Windows style paths use regular slashes ('/')
851 instead of the usual Windows backslash ('\') as directory
852 separator to avoid quoting problems (after all it is still
853 a cygwin dmake!) and cygwin, as well as native Windows,
854 programs should have no problems using this (c:/foo/bar)
855 path representation.
857 Example: Assuming the current target to be /tmp/mytarget
858 the $@ macro without .WINPATH active expands to:
860 /tmp/mytarget
862 With .WINPATH set it expands to:
864 C:/cygwin/tmp/mytarget
866 All attributes are user setable and except for .UPDATEALL and .MKSARGS
867 may be used in one of two forms. The .MKSARGS attribute is restricted
868 to use as a global attribute, and the use of the .UPDATEALL attribute
869 is restricted to rules of the second form only.
871 ATTRIBUTE_LIST : targets
873 assigns the attributes specified by ATTRIBUTE_LIST to each target in
874 targets or
876 targets ATTRIBUTE_LIST : ...
881 Dmake Version 4.12 2008-02-26 13
887 DMAKE(1) DMAKE(1)
890 assigns the attributes specified by ATTRIBUTE_LIST to each target in
891 targets. In the first form if targets is empty (ie. a NULL list), then
892 the list of attributes will apply to all targets in the makefile (this
893 is equivalent to the common Make construct of ".IGNORE :" but has been
894 modified to the notion of an attribute instead of a special target).
895 Not all of the attributes have global meaning. In particular,
896 .LIBRARY, .NOSTATE, .PHONY, .SETDIR, .SYMBOL and .UPDATEALL have no
897 assigned global meaning.
899 Any attribute may be used with any target, even with the special tar-
900 gets. Some combinations are useless (e.g. .INCLUDE .PRECIOUS: ... ),
901 while others are useful (e.g. .INCLUDE .IGNORE : "file.mk" will not
902 complain if file.mk cannot be found using the include file search
903 rules, see the section on SPECIAL TARGETS for a description of
904 .INCLUDE). If a specified attribute will not be used with the special
905 target a warning is issued and the attribute is ignored.
907 MACROS
908 dmake supports six forms of macro assignment.
911 MACRO = LINE This is the most common and familiar form of macro
912 assignment. It assigns LINE literally as the value of
913 MACRO. Future expansions of MACRO recursively expand
914 its value.
916 MACRO *= LINE This form behaves exactly as the simple '=' form with
917 the exception that if MACRO already has a value then
918 the assignment is not performed.
920 MACRO := LINE This form differs from the simple '=' form in that it
921 expands LINE prior to assigning it as the value of
922 MACRO. Future expansions of MACRO do not recursively
923 expand its value.
925 MACRO *:= LINE This form behaves exactly as the ':=' form with the
926 exception that if MACRO already has a value then the
927 assignment and expansion are not performed.
929 MACRO += LINE This form of macro assignment allows macro values to
930 grow. It takes the literal value of LINE and appends
931 it to the previous value of MACRO separating the two by
932 a single space. Future expansions of MACRO recursively
933 expand its value.
935 MACRO +:= LINE This form is similar to the '+=' form except that the
936 value of LINE is expanded prior to being added to the
937 value of MACRO.
939 Macro expressions specified on the command line allow the macro value
940 to be redefined within the makefile only if the macro is defined using
941 the '+=' and '+:=' operators. Other operators will define a macro that
942 cannot be further modified.
944 Each of the preceeding macro assignment operators may be prefixed by !
945 to indicate that the assignment should be forced and that no warnings
946 should be issued. Thus, specifying ! has the effect of silently forc-
947 ing the specified macro assignment.
951 Dmake Version 4.12 2008-02-26 14
957 DMAKE(1) DMAKE(1)
960 When dmake defines a non-environment macro it strips leading and trail-
961 ing white space from the macro value. Macros imported from the envi-
962 ronment via either the .IMPORT special target (see the SPECIAL TARGETS
963 section), or the -e, or -E flags are an exception to this rule. Their
964 values are always taken literally and white space is never stripped.
965 In addition, named macros defined using the .IMPORT special target do
966 not have their values expanded when they are used within a makefile.
967 In contrast, environment macros that are imported due to the specifica-
968 tion of the -e or -E flags are subject to expansion when used.
970 To specify a macro expansion enclose the name in () or {} and precede
971 it with a dollar sign $. Thus $(TEST) represents an expansion of the
972 macro variable named TEST. If TEST is defined then $(TEST) is replaced
973 by its expanded value. If TEST is not defined then $(TEST) expands to
974 the NULL string (this is equivalent to defining a macro as 'TEST=' ).
975 A short form may be used for single character named macros. In this
976 case the parentheses are optional, and $(I) is equivalent to $I. Macro
977 expansion is recursive, hence, if the value string contains an expres-
978 sion representing a macro expansion, the expansion is performed. Cir-
979 cular macro expansions are detected and cause an error to be issued.
981 When defining a macro the given macro name is first expanded before
982 being used to define the macro. Thus it is possible to define macros
983 whose names depend on values of other macros. For example, suppose CWD
984 is defined as
986 CWD = $(PWD:b)
988 then the value of $(CWD) is the name of the current directory. This
989 can be used to define macros specific to this directory, for example:
991 _$(CWD).prt = list of files to print...
993 The actual name of the defined macro is a function of the current
994 directory. A construct such as this is useful when processing a hier-
995 archy of directories using .SETDIR attributed targets and a collection
996 of small distributed makefile stubs.
998 Macro variables may be defined within the makefile, on the command
999 line, or imported from the environment.
1001 dmake supports several non-standard macro expansions: The first is of
1002 the form:
1004 $(macro_name:modifier_list:modifier_list:...)
1006 where modifier_list may be a combination of:
1008 b or B - file (not including suffix) portion of path names
1009 d or D - directory portion of all path names
1010 e or E - suffix portion of path names
1011 f or F - file (including suffix) portion of path names
1012 i or I - inferred names of targets
1013 n or N - normalized path names
1014 l or L - macro value in lower case
1015 u or U - macro value in upper case
1016 1 - return the first white space separated token from value
1021 Dmake Version 4.12 2008-02-26 15
1027 DMAKE(1) DMAKE(1)
1030 or a single one of:
1032 m or M - map escape codes found in macro to their ASCII value
1033 s or S - simple pattern substitution
1034 t or T - tokenization.
1035 ^ - prepend a prefix to each token
1036 + - append a suffix to each token
1038 Thus if we have the example:
1039 test = d1/d2/d3/a.out f.out d1/k.out
1040 The following macro expansions produce the values on the right of '->'
1041 after expansion.
1043 $(test:d) -> d1/d2/d3/ d1/
1044 $(test:b) -> a f k
1045 $(test:f) -> a.out f.out k.out
1046 ${test:db} -> d1/d2/d3/a f d1/k
1047 ${test:s/out/in/:f} -> a.in f.in k.in
1048 $(test:f:t"+") -> a.out+f.out+k.out
1049 $(test:e) -> .out .out .out
1050 $(test:u) -> D1/D2/D3/A.OUT F.OUT D1/K.OUT
1051 $(test:1) -> d1/d2/d3/a.out
1053 For this macro
1054 test = d1/d2/../a.out "d1/file name.ext"
1055 the following results are returned:
1057 $(test:n) -> d1/a.out "d1/file name.ext"
1059 If a token ends in a string composed from the value of the macro
1060 DIRBRKSTR (ie. ends in a directory separator string, e.g. '/' in UNIX)
1061 and you use the :d modifier then the expansion returns the directory
1062 name less the final directory separator string. Thus successive pairs
1063 of :d modifiers each remove a level of directory in the token string.
1065 The infered names of targets :i modifier returnes the actual filename
1066 associated to the target, see BINDING TARGETS. If the value is not a
1067 target or prerequisite the value is returned unchanged. For the follow-
1068 ing example:
1069 test = aprog bprog
1070 If aprog and bprog are targets or prerequisits and they are bound to
1071 /tmp/aprog and bprog (see .SOURCE special target) the macro expansion
1072 has the following effect:
1074 $(test:i) -> /tmp/aprog bprog
1076 The normalized path names :n modifier honors the setting of .WINPATH to
1077 determine the output format of the result.
1079 The map escape codes modifier changes the following escape codes \a =>
1080 <bel>, \b => <backspace>, \f => <formfeed>, \n => <nl>, \r => <cr>, \t
1081 => <tab>, \v => <vertical tab>, \" => ", and \xxx => <xxx> where xxx is
1082 the octal representation of a character into the corresponding ASCII
1083 value.
1085 The tokenization, prepend and append modifier may use the same escape
1086 codes that are supported by the map escape codes modifier in the string
1087 that is inserted, prepended or added by the respective macro modifier.
1091 Dmake Version 4.12 2008-02-26 16
1097 DMAKE(1) DMAKE(1)
1100 These modifiers may quote this string to include otherwise problematic
1101 characters. E.g. spaces, colons and parentheses.
1103 The tokenization modifier takes all white space separated tokens from
1104 the macro value and separates them by the separator string. Thus the
1105 expansion:
1107 $(test:f:t"+\n")
1108 produces:
1109 a.out+
1110 f.out+
1111 k.out
1113 The prefix operator ^ takes all white space separated tokens from the
1114 macro value and prepends string to each.
1116 $(test:f:^mydir/)
1117 produces:
1118 mydir/a.out mydir/f.out mydir/k.out
1120 The suffix operator + takes all white space separated tokens from the
1121 macro value and appends string to each.
1123 $(test:b:+.c)
1124 produces:
1125 a.c f.c k.c
1127 The next non-standard form of macro expansion allows for recursive
1128 macros. It is possible to specify a $(macro_name) or ${macro_name}
1129 expansion where macro_name contains more $( ... ) or ${ ... } macro
1130 expansions itself.
1132 For example $(CC$(_HOST)$(_COMPILER)) will first expand
1133 CC$(_HOST)$(_COMPILER) to get a result and use that result as the name
1134 of the macro to expand. This is useful for writing a makefile for more
1135 than one target environment. As an example consider the following
1136 hypothetical case. Suppose that _HOST and _COMPILER are imported from
1137 the environment and are set to represent the host machine type and the
1138 host compiler respectively.
1140 CFLAGS_VAX_CC = -c -O # _HOST == "_VAX", _COMPILER == "_CC"
1141 CFLAGS_PC_MSC = -c -ML # _HOST == "_PC", _COMPILER == "_MSC"
1143 # redefine CFLAGS macro as:
1145 CFLAGS := $(CFLAGS$(_HOST)$(_COMPILER))
1147 This causes CFLAGS to take on a value that corresponds to the environ-
1148 ment in which the make is being invoked.
1150 The final non-standard macro expansion is of the form:
1152 string1{token_list}string2
1154 where string1, string2 and token_list are expanded. After expansion,
1155 string1 is prepended to each token found in token_list and string2 is
1156 appended to each resulting token from the previous prepend. string1
1157 and string2 are not delimited by white space whereas the tokens in
1161 Dmake Version 4.12 2008-02-26 17
1167 DMAKE(1) DMAKE(1)
1170 token_list are. A null token in the token list is specified using "".
1171 Thus using another example we have:
1173 test/{f1 f2}.o --> test/f1.o test/f2.o
1174 test/ {f1 f2}.o --> test/ f1.o f2.o
1175 test/{f1 f2} .o --> test/f1 test/f2 .o
1176 test/{"f1" ""}.o --> test/f1.o test/.o
1178 and
1180 test/{d1 d2}/{f1 f2}.o --> test/d1/f1.o test/d1/f2.o
1181 test/d2/f1.o test/d2/f2.o
1183 This last expansion is activated only when the first characters of
1184 token_list appear immediately after the opening '{' with no intervening
1185 white space. The reason for this restriction is the following incom-
1186 patibility with Bourne Shell recipes. The line
1188 { echo hello;}
1190 is valid /bin/sh syntax; while
1192 {echo hello;}
1194 is not. Hence the latter triggers the enhanced macro expansion while
1195 the former causes it to be suppressed. See the SPECIAL MACROS section
1196 for a description of the special macros that dmake defines and under-
1197 stands.
1199 RULES AND TARGETS
1200 A makefile contains a series of entries that specify dependencies.
1201 Such entries are called target/prerequisite or rule definitions. Each
1202 rule definition is optionally followed by a set of lines that provide a
1203 recipe for updating any targets defined by the rule. Whenever dmake
1204 attempts to bring a target up to date and an explicit recipe is pro-
1205 vided with a rule defining the target, that recipe is used to update
1206 the target. A rule definition begins with a line having the following
1207 syntax:
1209 <targets> [<attributes>] <ruleop> [<prerequisites>] [;<recipe>]
1211 targets is a non-empty list of targets. If the target is a special
1212 target (see SPECIAL TARGETS section below) then it must appear alone on
1213 the rule line. For example:
1215 .IMPORT .ERROR : ...
1217 is not allowed since both .IMPORT and .ERROR are special targets. Spe-
1218 cial targets are not used in the construction of the dependency graph
1219 and will not be made.
1221 attributes is a possibly empty list of attributes. Any attribute
1222 defined in the ATTRIBUTES section above may be specified. All
1223 attributes will be applied to the list of named targets in the rule
1224 definition. No other targets will be affected.
1227 NOTE: As stated earlier, if both the target list and prerequisite
1228 list are empty but the attributes list is not, then the
1232 Dmake Version 4.12 2008-02-26 18
1238 DMAKE(1) DMAKE(1)
1241 specified attributes affect all targets in the makefile.
1244 ruleop is a separator which is used to identify the targets from the
1245 prerequisites. Optionally it also provides a facility for modifying
1246 the way in which dmake handles the making of the associated targets.
1247 In its simplest form the operator is a single ':', and need not be sep-
1248 arated by white space from its neighboring tokens. It may additionally
1249 be followed by any of the modifiers { !, ^, -, :, | }, where:
1252 ! says execute the recipe for the associated targets once for each
1253 out of date prerequisite. (The meaning of the runtime macro $?
1254 is changed, see below in the RUNTIME MACROS section.) Ordinarily
1255 the recipe is executed once for all out of date prerequisites at
1256 the same time.
1258 ^ says to insert the specified prerequisites, if any, before any
1259 other prerequisites already associated with the specified tar-
1260 gets. In general, it is not useful to specify ^ with an empty
1261 list of prerequisites.
1263 - says to clear the previous list of prerequisites before adding
1264 the new prerequisites. Thus,
1266 foo :
1267 foo : bar baz
1269 can be replaced by
1271 foo :- bar baz
1273 however the old form still works as expected.
1275 : When the rule operator is not modified by a second ':' only one
1276 set of rules may be specified for making a target. Multiple
1277 definitions may be used to add to the list of prerequisites that
1278 a target depends on. However, if a target is multiply defined
1279 only one definition may specify a recipe for making the target.
1281 When a target's rule operator is modified by a second ':' (::
1282 for example) then this definition may not be the only definition
1283 with a recipe for the target. There may be other :: target def-
1284 inition lines that specify a different set of prerequisites with
1285 a different recipe for updating the target. Any such target is
1286 made if any of the definitions find it to be out of date with
1287 respect to the related prerequisites and the corresponding
1288 recipe is used to update the target. By definition all '::'
1289 recipes that are found to be out of date for are executed.
1291 In the following simple example, each rule has a `::' ruleop.
1292 In such an operator we call the first `:' the operator, and the
1293 second `:' the modifier.
1295 a.o :: a.c b.h
1296 first recipe for making a.o
1298 a.o :: a.y b.h
1299 second recipe for making a.o
1303 Dmake Version 4.12 2008-02-26 19
1309 DMAKE(1) DMAKE(1)
1312 If a.o is found to be out of date with respect to a.c then the
1313 first recipe is used to make a.o. If it is found out of date
1314 with respect to a.y then the second recipe is used. If a.o is
1315 out of date with respect to b.h then both recipes are invoked to
1316 make a.o. In the last case the order of invocation corresponds
1317 to the order in which the rule definitions appear in the make-
1318 file.
1320 | Is defined only for PERCENT rule target definitions. When spec-
1321 ified it indicates that the following construct should be parsed
1322 using the old semantinc meaning:
1324 %.o :| %.c %.r %.f ; some rule
1326 is equivalent to:
1328 %.o : %.c ; some rule
1329 %.o : %.r ; some rule
1330 %.o : %.f ; some rule
1332 Targets defined using a single `:' operator with a recipe may be rede-
1333 fined again with a new recipe by using a `:' operator with a `:' modi-
1334 fier. This is equivalent to a target having been initially defined
1335 with a rule using a `:' modifier. Once a target is defined using a `:'
1336 modifier it may not be defined again with a recipe using only the `:'
1337 operator with no `:' modifier. In both cases the use of a `:' modifier
1338 creates a new list of prerequisites and makes it the current prerequi-
1339 site list for the target. The `:' operator with no recipe always modi-
1340 fies the current list of prerequisites. Thus assuming each of the fol-
1341 lowing definitions has a recipe attached, then:
1343 joe : fred ... (1)
1344 joe :: more ... (2)
1346 and
1348 joe :: fred ... (3)
1349 joe :: more ... (4)
1351 are legal and mean: add the recipe associated with (2), or (4) to the
1352 set of recipes for joe, placing them after existing recipes for making
1353 joe. The constructs:
1355 joe :: fred ... (5)
1356 joe : more ... (6)
1358 and
1360 joe : fred ... (7)
1361 joe : more ... (8)
1363 are errors since we have two sets of perfectly good recipes for making
1364 the target.
1366 prerequisites is a possibly empty list of targets that must be brought
1367 up to date before making the current target.
1369 recipe is a short form and allows the user to specify short rule defi-
1370 nitions on a single line. It is taken to be the first recipe line in a
1374 Dmake Version 4.12 2008-02-26 20
1380 DMAKE(1) DMAKE(1)
1383 larger recipe if additional lines follow the rule definition. If the
1384 semi-colon is present but the recipe line is empty (ie. null string)
1385 then it is taken to be an empty rule. Any target so defined causes
1386 target to be treated as a virtual target, see VIRTUAL TARGETS below.
1388 RECIPES
1389 The traditional format used by most versions of Make defines the recipe
1390 lines as arbitrary strings that may contain macro expansions. They
1391 follow a rule definition line and may be spaced apart by comment or
1392 blank lines. The list of recipe lines defining the recipe is termi-
1393 nated by a new target definition, a macro definition, or end-of-file.
1394 Each recipe line MUST begin with a <TAB> character (or spaces, see
1395 .NOTABS) which may optionally be followed with one or all the following
1396 recipe property characters '@%+-' which affect the recipe execution:
1398 '-' indicates that non-zero exit values (ie. errors) are to be
1399 ignored when this recipe line is executed.
1401 '+' indicates that the current recipe line is to be executed using
1402 the shell. Group recipes implicitely ignore this property.
1404 '%' indicates that dmake should swap itself out to secondary storage
1405 (MSDOS only) before running the recipe.
1407 '@' indicates that the recipe line should NOT be echoed to the ter-
1408 minal prior to being executed.
1410 '@@' is a stronger version of the previous property. The recipe line
1411 and the output (stdout and stderr) of the executed recipe are
1412 NOT shown on the terminal.
1414 Each property is off by default (ie. by default, errors are signifi-
1415 cant, commands are echoed, no swapping is done and a shell is used only
1416 if the recipe line contains a character found in the value of the
1417 SHELLMETAS macro). Global settings activated via command line options
1418 or special attribute or target names may also affect these settings.
1419 An example recipe:
1421 target :
1422 first recipe line
1423 second recipe line, executed independent of first.
1424 @a recipe line that is not echoed
1425 -and one that has errors ignored
1426 %and one that causes dmake to swap out
1427 +and one that is executed using a shell.
1429 The second and new format of the recipe block begins the block with the
1430 character '[' (the open group character) in the last non-white space
1431 position of a line, and terminates the block with the character ']'
1432 (the close group character) in the first non-white space position of a
1433 line. In this form each recipe line need not have a leading TAB. This
1434 is called a recipe group. Groups so defined are fed intact as a single
1435 unit to a shell for execution whenever the corresponding target needs
1436 to be updated. If the open group character '[' is preceded by one or
1437 all of the recipe properties (-, %, @ and @@) then they apply to the
1438 entire group in the same way that they apply to single recipe lines.
1439 You may also specify '+' but it is redundant as a shell is already
1440 being used to run the recipe. See the MAKING TARGETS section for a
1441 description of how dmake invokes recipes. Here is an example of a
1445 Dmake Version 4.12 2008-02-26 21
1451 DMAKE(1) DMAKE(1)
1454 group recipe:
1456 target :
1457 [
1458 first recipe line
1459 second recipe line
1460 tall of these recipe lines are fed to a
1461 single copy of a shell for execution.
1462 ]
1465 BUILTIN COMMANDS
1466 dmake supports some builtin commands. An optional leading '+' describes
1467 that the builtin can be used also when being executed in a shell other-
1468 wise it is only implemented when used directly. Remember that if a
1469 character of the recipe is found in the SHELLMETAS macro the execution
1470 of the recipe in a shell is forced.
1472 [+]noop [something]
1473 The noop internal command always returns success if used but it
1474 is not executed even though the rest of the commandline is eval-
1475 uated. This command can be used to evaluate macro expansions at
1476 the runtime of the recipe without starting a real commmand.
1478 [+]<empty recipe>
1479 If an empty recipe line is encountered it is not executed. This
1480 sounds more trivial than it really is because the recipe could
1481 consist of macros that evaluated to empty or whitespace only
1482 strings.
1484 echo [-n] data
1485 This internal command prints data (with all leading whitespace
1486 removed, but otherwise literally) to stdout. If the '-n' switch
1487 is given no trailing newline is printed. Note that no quoting is
1488 removed nor that escape sequences are handled.
1490 No special treatment of buildin commands for group recipes is imple-
1491 mented even though the <empty recipe> will most propably also not be
1492 evaluated by most shells that can be used to handle the recipe groups.
1494 TEXT DIVERSIONS
1495 dmake supports the notion of text diversions. If a recipe line con-
1496 tains the macro expression
1498 $(mktmp[,[file][,text]] data)
1500 then all text contained in the data expression is expanded and is writ-
1501 ten to a temporary file. The data in the file will always be termi-
1502 nated from a new line character. The file parameter can be used to
1503 override the name of the temporary file. If its expanded value is not
1504 empty it will be used instead of the unique and thread safe file name
1505 that otherwise would be generated internally. The return value of the
1506 macro is the name of the temporary file unless the text parameter is
1507 defined. In this case the return value is the expanded value of text.
1509 data can be any text and must be separated from the 'mktmp' portion of
1510 the macro name by white-space. The only restriction on the data text
1511 is that it must contain a balanced number of parentheses of the same
1512 kind as are used to initiate the $(mktmp ...) expression. For example:
1516 Dmake Version 4.12 2008-02-26 22
1522 DMAKE(1) DMAKE(1)
1525 $(mktmp $(XXX))
1527 is legal and works as expected, but:
1529 $(mktmp text (to dump to file)
1531 is not legal. You can achieve what you wish by either defining a macro
1532 that expands to '(' or by using {} in the macro expression; like this:
1534 ${mktmp text (to dump to file}
1536 Since the temporary file is opened when the macro containing the text
1537 diversion expression is expanded, diversions may be nested and any
1538 diversions that are created as part of ':=' macro expansions persist
1539 for the duration of the dmake run. If the data text is to contain new
1540 lines the map escape codes macro expasion can be used. For example the
1541 expression:
1543 mytext:=this is a\ntest of the text diversion
1544 all:
1545 cat $(mktmp $(mytext:m))
1547 is replaced by:
1549 cat /tmp/mk12294AA
1551 where the temporary file contains two lines both of which are termi-
1552 nated by a new-line. A second more illustrative example generates a
1553 response file to an MSDOS link command:
1555 OBJ = fred.obj mary.obj joe.obj
1556 all : $(OBJ)
1557 link @$(mktmp $(^:t"+\n"))
1559 The result of making `all' in the second example is the command:
1561 link @/tmp/mk02394AA
1563 where the temporary file contains:
1565 fred.obj+
1566 mary.obj+
1567 joe.obj
1569 The last line of the file is terminated by a new-line which is always
1570 inserted at the end of the data string.
1572 If the optional file specifier is present it can be used to specify the
1573 name of the temporary file to create. An example that would be useful
1574 for MSDOS users with a Turbo-C compiler
1576 $(mktmp,turboc.cfg $(CFLAGS))
1578 will place the contents of CFLAGS into a local turboc.cfg file. The
1579 second optional argument, text, if present alters the name of the value
1580 returned by the $(mktmp ...) macro.
1582 Under MS-DOS text diversions may be a problem. Many DOS tools require
1583 that path names which contain directories use the \ character to
1587 Dmake Version 4.12 2008-02-26 23
1593 DMAKE(1) DMAKE(1)
1596 delimit the directories. Some users however wish to use the '/' to
1597 delimit pathnames and use environments that allow them to do so. The
1598 macro USESHELL is set to "yes" if the current recipe is forced to use a
1599 shell via the .USESHELL or '+' directives, otherwise its value is "no".
1600 The dmake startup files define the macro DIVFILE whose value is either
1601 the value of TMPFILE or the value of TMPFILE edited to replace any '/'
1602 characters to the appropriate value based on the current shell and
1603 whether it will be used to execute the recipe.
1605 Previous versions of dmake defined text diversions using <+, +>
1606 strings, where <+ started a text diversion and +> terminated one.
1607 dmake is backward compatible with this construct only if the <+ and +>
1608 appear literally on the same recipe line or in the same macro value
1609 string. In such instances the expression:
1611 <+data+>
1613 is mapped to:
1615 $(mktmp data)
1617 which is fully output compatible with the earlier construct. <+, +>
1618 constructs whose text spans multiple lines must be converted by hand to
1619 use $(mktmp ...).
1621 If the environment variable TMPDIR is defined then the temporary file
1622 is placed into the directory specified by that variable. A makefile
1623 can modify the location of temporary files by defining a macro named
1624 TMPDIR and exporting it using the .EXPORT special target.
1626 VIRTUAL TARGETS
1627 Dmake allows to define targets with the sole purpose to enforce a
1628 dependency chain that are unable to create the target, hence virtual
1629 targets. When dmake tries to make a target, but only finds a target
1630 definition without recipe lines, it would normally issues a "Don't know
1631 how to make ..." error message, but if a target rule is terminated by a
1632 semicolon and has no following recipe lines, or if it has no recipe
1633 lines, but defines prerequisites, or if the AUGMAKE mode is enabled
1634 (see the COMPATIBILITY section for details), the target is treated as a
1635 virtual target and the error is suppressed. In addition to this, if the
1636 default target does not have recipe lines it is also treated as a vir-
1637 tual target.
1639 Virtual targets should not have a corresponding file therefore they
1640 inherit the time of their newest prerequisite if they have prerequi-
1641 sites, otherwise they get the current time assigned when being made.
1642 If the virtual target has a corresponding file a warning is issued, but
1643 the time stamp of that file is taken into account. The virtual target
1644 uses the time stamp of the corresponding file if it is newer than the
1645 one determined by the previous rule.
1647 SPECIAL TARGETS
1648 This section describes the special targets that are recognized by
1649 dmake. Some are affected by attributes and others are not.
1651 .ERROR If defined then the recipe associated with this target is
1652 executed whenever an error condition is detected by
1653 dmake. All attributes that can be used with any other
1654 target may be used with this target. Any prerequisites
1658 Dmake Version 4.12 2008-02-26 24
1664 DMAKE(1) DMAKE(1)
1667 of this target will be brought up to date during its pro-
1668 cessing. NOTE: errors will be ignored while making this
1669 target, in extreme cases this may cause some problems.
1671 .EXIT If this target is encountered while parsing a makefile
1672 then the parsing of the makefile is immediately termi-
1673 nated at that point.
1675 .EXPORT All prerequisites associated with this target are assumed
1676 to correspond to macro names and they and their values
1677 are exported to the environment as environment strings at
1678 the point in the makefile at which this target appears.
1679 Any attributes specified with this target are ignored.
1680 Only macros which have been assigned a value in the make-
1681 file prior to the export directive are exported, macros
1682 as yet undefined or macros whose value contains any of
1683 the characters "+=:*" are not exported.
1685 Note that macros that are not expanded during the macro
1686 assignment and contain other macros will be written into
1687 the environment containing these other macros in the form
1688 of $(macroname).
1690 .IMPORT Prerequisite names specified for this target are searched
1691 for in the environment and defined as macros with their
1692 value taken from the environment. If the special name
1693 .EVERYTHING is used as a prerequisite name then all envi-
1694 ronment variables defined in the environment are
1695 imported. The functionality of the -E flag can be forced
1696 by placing the construct .IMPORT : .EVERYTHING at the
1697 start of a makefile. Similarly, by placing the construct
1698 at the end, one can emulate the effect of the -e command
1699 line flag. If a prerequisite name cannot be found in the
1700 environment an error message is issued. .IMPORT accepts
1701 the .IGNORE attribute. When given, it causes dmake to
1702 ignore the above error. See the MACROS section for a
1703 description of the processing of imported macro values.
1705 .INCLUDE Parse another makefile just as if it had been located at
1706 the point of the .INCLUDE in the current makefile. The
1707 list of prerequisites gives the list of makefiles to try
1708 to read. If the list contains multiple makefiles then
1709 they are read in order from left to right. The following
1710 search rules are used when trying to locate the file. If
1711 the filename is surrounded by " or just by itself then it
1712 is searched for in the current directory. If it is not
1713 found it is then searched for in each of the directories
1714 specified as prerequisites of the .INCLUDEDIRS special
1715 target. If the file name is surrounded by < and >, (ie.
1716 <my_spiffy_new_makefile>) then it is searched for only in
1717 the directories given by the .INCLUDEDIRS special target.
1718 In both cases if the file name is a fully qualified name
1719 starting at the root of the file system then it is only
1720 searched for once, and the .INCLUDEDIRS list is ignored.
1721 If .INCLUDE fails to find the file it invokes the infer-
1722 ence engine to try to infer and hence make the file to be
1723 included. In this way the file can be checked out of an
1724 RCS repository for example. .INCLUDE accepts the
1725 .IGNORE, .SETDIR, and .NOINFER attributes. If the
1729 Dmake Version 4.12 2008-02-26 25
1735 DMAKE(1) DMAKE(1)
1738 .IGNORE attribute is given and the file cannot be found
1739 then dmake continues processing, otherwise an error mes-
1740 sage is generated. If the .NOINFER attribute is given
1741 and the file cannot be found then dmake will not attempt
1742 to infer and make the file. The .SETDIR attribute causes
1743 dmake to change directories to the specified directory
1744 prior to attempting the include operation. If all fails
1745 dmake attempts to make the file to be included. If mak-
1746 ing the file fails then dmake terminates unless the
1747 .INCLUDE directive also specified the .IGNORE attribute.
1748 If .FIRST is specified along with .INCLUDE then dmake
1749 attempts to include each named prerequisite and will ter-
1750 minate the inclusion with the first prerequisite that
1751 results in a successful inclusion.
1753 .INCLUDEDIRS The list of prerequisites specified for this target
1754 defines the set of directories to search when trying to
1755 include a makefile.
1757 .KEEP_STATE This special target is a synonym for the macro definition
1759 .KEEP_STATE := _state.mk
1761 It's effect is to turn on STATE keeping and to define
1762 _state.mk as the state file.
1764 .MAKEFILES The list of prerequisites is the set of files to try to
1765 read as the default makefile. By default this target is
1766 defined as:
1768 .MAKEFILES : makefile.mk Makefile makefile
1771 .REMOVE The recipe of this target is used whenever dmake needs to
1772 remove intermediate targets that were made but do not
1773 need to be kept around. Such targets result from the
1774 application of transitive closure on the dependency
1775 graph.
1777 .ROOT The internal root of the dependency graph, see section
1778 STARTUP for details.
1780 .SOURCE The prerequisite list of this target defines a set of
1781 directories to check when trying to locate a target file
1782 name. See the section on BINDING of targets for more
1783 information.
1785 .SOURCE.suff The same as .SOURCE, except that the .SOURCE.suff list is
1786 searched first when trying to locate a file matching the
1787 a target whose name ends in the suffix .suff.
1789 .SUFFIXES This deprecated special target has no special meaning.
1790 Avoid its use.
1792 .TARGETS The internal targets that all user defined targets are
1793 prerequisites of, see section STARTUP for details.
1795 There are a few targets that are "slightly" special:
1800 Dmake Version 4.12 2008-02-26 26
1806 DMAKE(1) DMAKE(1)
1809 .INIT
1810 .DONE
1812 These targets exist because of historical reasons, see the usage of
1813 .INIT and .DONE in section "STARTUP", they can be used and defined as
1814 ordinary targets but are special in the sense that even though they
1815 start with a `.' they are not treated as a .<suffix> meta target (See
1816 the AUGMAKE META RULES section for details).
1818 Please note that self defined targets shouldn't use the prefix `.' as
1819 they would be handled as .<suffix> meta targets and dmake most propably
1820 would complain about this.
1822 In addition to the special targets above, several other forms of tar-
1823 gets are recognized and are considered special, their exact form and
1824 use is defined in the sections that follow.
1826 SPECIAL MACROS
1827 dmake defines a number of special macros. They are divided into three
1828 classes: control macros, run-time macros, and function macros. The
1829 control macros are used by dmake to configure its actions, and are the
1830 preferred method of doing so. In the case when a control macro has the
1831 same function as a special target or attribute they share the same name
1832 as the special target or attribute. The run-time macros are defined
1833 when dmake makes targets and may be used by the user inside recipes.
1834 The function macros provide higher level functions dealing with macro
1835 expansion and diversion file processing.
1837 CONTROL MACROS
1838 To use the control macros simply assign them a value just like any
1839 other macro. The control macros are divided into three groups: string
1840 valued macros, character valued macros, and boolean valued macros.
1842 The following are all of the string valued macros. This list is
1843 divided into two groups. The first group gives the string valued
1844 macros that are defined internally and cannot be directly set by the
1845 user.
1847 ABSMAKECMD Warning! This macro's value is differently defined for
1848 a native Windows dmake executable (compiled with MS
1849 Visual C++ or MinGW) and dmake for other operating sys-
1850 tems or build with other compilers.
1852 In the first case its value is the absolute filename of
1853 the executable of the current dmake process, otherwise
1854 it is defined as the NULL string.
1856 INCDEPTH This macro's value is a string of digits representing
1857 the current depth of makefile inclusion. In the first
1858 makefile level this value is zero.
1860 MFLAGS Is the list of flags that were given on the command
1861 line including a leading switch character. The -f flag
1862 is not included in this list.
1864 MAKECMD Is the name with which dmake was invoked.
1866 MAKEDIR Is the full path to the initial directory in which
1867 dmake was invoked.
1871 Dmake Version 4.12 2008-02-26 27
1877 DMAKE(1) DMAKE(1)
1880 MAKEFILE Contains the string "-f makefile" where, makefile is
1881 the name of initial user makefile that was first read.
1883 MAKEFLAGS Is the same as $(MFLAGS) but has no leading switch
1884 character. (ie. MFLAGS = -$(MAKEFLAGS))
1886 MAKEMACROS Contains the complete list of macro expressions that
1887 were specified on the command line.
1889 MAKETARGETS Contains the name(s) of the target(s), if any, that
1890 were specified on the command line.
1892 MAKEVERSION Contains a string indicating the current dmake version
1893 number.
1895 MAXPROCESSLIMIT Is a numeric string representing the maximum number of
1896 processes that dmake can use when making targets using
1897 parallel mode.
1899 NULL Is permanently defined to be the NULL string. This is
1900 useful when comparing a conditional expression to an
1901 NULL value.
1903 PWD Is the full path to the current directory in which make
1904 is executing.
1906 SPACECHAR Is permanently defined to contain one space character.
1907 This is useful when using space characters in function
1908 macros, e.g. subst, that otherwise would get deleted
1909 (leading/trailing spaces) or for using spaces in func-
1910 tion macro parameters.
1912 TMPFILE Is set to the name of the most recent temporary file
1913 opened by dmake. Temporary files are used for text
1914 diversions and for group recipe processing.
1916 TMD Stands for "To Make Dir", and is the path from the
1917 present directory (value of $(PWD)) to the directory
1918 that dmake was started up in (value of $(MAKEDIR)). If
1919 the present directory is the directory that dmake was
1920 started up in TMD will be set to the relative path ".".
1921 This allows to create valid paths by prepending
1922 $(TMD)$(DIRSEPSTR) to a relative path. This macro is
1923 modified when .SETDIR attributes are processed. TMD
1924 will usually be a relative path with the following two
1925 exceptions. If the relative path would go up until the
1926 root directory or if different drive letters (DOS file
1927 system) make a relative path impossible the absolute
1928 path from MAKEDIR is used.
1930 USESHELL The value of this macro is set to "yes" if the current
1931 recipe is forced to use a shell for its execution via
1932 the .USESHELL or '+' directives, its value is "no" oth-
1933 erwise.
1936 The second group of string valued macros control dmake behavior and may
1937 be set by the user.
1942 Dmake Version 4.12 2008-02-26 28
1948 DMAKE(1) DMAKE(1)
1951 .DIRCACHE If set to "yes" enables the directory cache (this is
1952 the default). If set to "no" disables the directory
1953 cache (equivalent to -d command-line flag).
1955 .DIRCACHERESPCASE
1956 If set to "yes" causes the directory cache, if enabled,
1957 to respect file case, if set to "no" files are cached
1958 case insensitive. By default it is set to "no" on Win-
1959 dows as the filesystems on this operating system are
1960 case insensitive and set to "yes" for all other operat-
1961 ing systems. The default can be overriden, if desired.
1963 Note: Using case insensitive directory caching on case
1964 sensitive file systems is a BAD idea. If in doubt use
1965 case sensitive directory caching even on case insensi-
1966 tive file systems as the worst case in this scenario is
1967 that /foo/bar/ and /foo/BAR/ are cached separately
1968 (with the same content) even though they are the same
1969 directory. This would only happen if different targets
1970 use different upper/lower case spellings for the same
1971 directory and that is never a good idea.
1973 NAMEMAX Defines the maximum length of a filename component.
1974 The value of the variable is initialized at startup to
1975 the value of the compiled macro NAME_MAX. On some sys-
1976 tems the value of NAME_MAX is too short by default.
1977 Setting a new value for NAMEMAX will override the com-
1978 piled value.
1980 .NOTABS When set to "yes" enables the use of spaces as well as
1981 <tabs> to begin recipe lines. By default a non-group
1982 recipe is terminated by a line without any leading
1983 white-space or by a line not beggining with a <tab>
1984 character. Enabling this mode modifies the first con-
1985 dition of the above termination rule to terminate a
1986 non-group recipe with a line that contains only
1987 white-space. This mode does not effect the parsing of
1988 group recipes bracketed by [].
1990 AUGMAKE If set to "yes" value will enable the transformation of
1991 special meta targets to support special AUGMAKE infer-
1992 ences (See the "AUGMAKE META RULES" and "COMPATIBILITY"
1993 sections).
1995 DIRBRKSTR Contains the string of chars used to terminate the name
1996 of a directory in a pathname. Under UNIX its value is
1997 "/", under MSDOS its value is "/\:".
1999 DIRSEPSTR Contains the string that is used to separate directory
2000 components when path names are constructed. It is
2001 defined with a default value at startup.
2003 DIVFILE Is defined in the startup file and gives the name that
2004 should be returned for the diversion file name when
2005 used in $(mktmp ...) expansions, see the TEXT DIVERSION
2006 section for details.
2008 .KEEP_STATE Assigning this macro a value tells dmake the name of
2009 the state file to use and turns on the keeping of state
2013 Dmake Version 4.12 2008-02-26 29
2019 DMAKE(1) DMAKE(1)
2022 information for any targets that are brought up to date
2023 by the make.
2025 GROUPFLAGS This macro gives the set of flags to pass to the shell
2026 when invoking it to execute a group recipe. The value
2027 of the macro is the list of flags with a leading switch
2028 indicator. (ie. `-' under UNIX)
2030 GROUPSHELL This macro defines the full path to the executable
2031 image to be used as the shell when processing group
2032 recipes. This macro must be defined if group recipes
2033 are used. It is assigned a default value in the
2034 startup makefile. Under UNIX this value is /bin/sh.
2036 GROUPSUFFIX If defined, this macro gives the string to use as a
2037 suffix when creating group recipe files to be handed to
2038 the command interpreter. For example, if it is defined
2039 as .sh, then all temporary files created by dmake will
2040 end in the suffix .sh. Under MSDOS if you are using
2041 command.com as your GROUPSHELL, then this suffix must
2042 be set to .bat in order for group recipes to function
2043 correctly. The setting of GROUPSUFFIX and GROUPSHELL
2044 is done automatically for command.com in the startup.mk
2045 files.
2047 MAKE Is defined in the startup file by default. Initially
2048 this macro is defined to have the value "$(MAKECMD)
2049 $(MFLAGS)". The string $(MAKE) is recognized when
2050 using the -n switch.
2052 MAKESTARTUP This macro defines the full path to the initial startup
2053 makefile. Use the -V command line option to discover
2054 its initial value.
2056 MAXLINELENGTH This macro defines the maximum size of a single line of
2057 makefile input text. The size is specified as a num-
2058 ber, the default value is defined internally and is
2059 shown via the -V option. A buffer of this size plus 2
2060 is allocated for reading makefile text. The buffer is
2061 freed before any targets are made, thereby allowing
2062 files containing long input lines to be processed with-
2063 out consuming memory during the actual make. This
2064 macro can only be used to extend the line length beyond
2065 it's default minimum value.
2067 MAXPROCESS Specify the maximum number of child processes to use
2068 when making targets. The default value of this macro
2069 is "1" and its value cannot exceed the value of the
2070 macro MAXPROCESSLIMIT. Setting the value of MAXPROCESS
2071 on the command line or in the makefile is equivalent to
2072 supplying a corresponding value to the -P flag on the
2073 command line. If the global .SEQUENTIAL attribute is
2074 set (or the -S command line switch is used) the value
2075 of MAXPROCESS is fixed to "1" and cannot be changed.
2077 OOODMAKEMODE This macro enables a special compatibility mode needed
2078 by the OpenOffice.org build system. If set, the switch
2079 disables the removal of leading './' path elements dur-
2080 ing target filename normalization (See BINDING
2084 Dmake Version 4.12 2008-02-26 30
2090 DMAKE(1) DMAKE(1)
2093 TARGETS). If './' appear in the pathname, but not at
2094 the beginning of it, they are still removed by the nor-
2095 malization. Please note that targets that are given on
2096 the command line are going to be registered as default
2097 targets after the startup file is read.
2099 PREP This macro defines the number of iterations to be
2100 expanded automatically when processing % rule defini-
2101 tions of the form:
2103 % : %.suff
2105 See the sections on PERCENT(%) RULES for details on how
2106 PREP is used.
2108 SHELL This macro defines the full path to the executable
2109 image to be used as the shell when processing single
2110 line recipes. This macro must be defined if recipes
2111 requiring the shell for execution are to be used. It
2112 is assigned a default value in the startup makefile.
2113 Under UNIX this value is /bin/sh.
2115 SHELLCMDQUOTE This macro can be used to add additional characters
2116 before and after the command string that is passed to
2117 the shell defined by the SHELL macro. If needed, like
2118 for cmd.exe and command.com, it is assigned a value in
2119 the startup file.
2121 SHELLFLAGS This macro gives the set of flags to pass to the shell
2122 when invoking it to execute a single line recipe. The
2123 value of the macro is the list of flags with a leading
2124 switch indicator. (ie. `-' under UNIX)
2126 SHELLMETAS Each time dmake executes a single recipe line (not a
2127 group recipe) the line is searched for any occurrence
2128 of a character defined in the value of SHELLMETAS. If
2129 such a character is found the recipe line is defined to
2130 require a shell to ensure its correct execution. In
2131 such instances a shell is used to invoke the recipe
2132 line. If no match is found the recipe line is executed
2133 without the use of a shell.
2136 There is only one character valued macro defined by dmake: SWITCHAR
2137 contains the switch character used to introduce options on command
2138 lines. For UNIX its value is `-', and for MSDOS its value may be `/'
2139 or `-'. The macro is internally defined and is not user setable. The
2140 MSDOS version of dmake attempts to first extract SWITCHAR from an envi-
2141 ronment variable of the same name. If that fails it then attempts to
2142 use the undocumented getswitchar system call, and returns the result of
2143 that. Under MSDOS version 4.0 you must set the value of the environ-
2144 ment macro SWITCHAR to '/' to obtain predictable behavior.
2146 All boolean macros currently understood by dmake correspond directly to
2147 the previously defined attributes. These macros provide a second way
2148 to apply global attributes, and represent the preferred method of doing
2149 so. They are used by assigning them a value. If the value is not a
2150 NULL string then the boolean condition is set to on. If the value is a
2151 NULL string then the condition is set to off. There are five
2155 Dmake Version 4.12 2008-02-26 31
2161 DMAKE(1) DMAKE(1)
2164 conditions defined and they correspond directly to the attributes of
2165 the same name. Their meanings are defined in the ATTRIBUTES section
2166 above. The macros are: .EPILOG, .IGNORE, .MKSARGS, .NOINFER, .PRE-
2167 CIOUS, .PROLOG, .SEQUENTIAL, .SILENT, .SWAP, and .USESHELL. Assigning
2168 any of these a non NULL value will globally set the corresponding
2169 attribute to on.
2171 RUNTIME MACROS
2172 These macros are defined when dmake is making targets, and may take on
2173 different values for each target. $@ is defined to be the full target
2174 name, $? is the list of all out of date prerequisites, except for the !
2175 ruleop, in which case it is set to the current build prerequisite
2176 instead. $& is the list of all prerequisites, $> is the name of the
2177 library if the current target is a library member, and $< is the list
2178 of prerequisites specified in the current rule. If the current target
2179 had a recipe inferred then $< is the name of the inferred prerequisite
2180 even if the target had a list of prerequisites supplied using an
2181 explicit rule that did not provide a recipe. In such situations $&
2182 gives the full list of prerequisites.
2184 $* is defined as $(@:db) when making targets with explicit recipes and
2185 is defined as the value of % when making targets whose recipe is the
2186 result of an inference. In the first case $* is the target name with
2187 no suffix, and in the second case, is the value of the matched % pat-
2188 tern from the associated %-rule. $^ expands to the set of out of date
2189 prerequisites taken from the current value of $<. In addition to
2190 these, $$ expands to $, {{ expands to {, }} expands to }, and the
2191 strings <+ and +> are recognized as respectively starting and terminat-
2192 ing a text diversion when they appear literally together in the same
2193 input line.
2195 The difference between $? and $^ can best be illustrated by an example,
2196 consider:
2198 fred.out : joe amy hello
2199 rules for making fred
2201 fred.out : my.c your.h his.h her.h # more prerequisites
2203 Assume joe, amy, and my.c are newer then fred.out. When dmake executes
2204 the recipe for making fred.out the values of the following macros will
2205 be:
2207 $@ --> fred.out
2208 $* --> fred
2209 $? --> joe amy my.c # note output of $? vs $^
2210 $^ --> joe amy
2211 $< --> joe amy hello
2212 $& --> joe amy hello my.c your.h his.h her.h
2215 FUNCTION MACROS
2216 dmake supports a full set of functional macros. One of these, the
2217 $(mktmp ...) macro, is discussed in detail in the TEXT DIVERSION sec-
2218 tion and is not covered here. The names of function macros must appear
2219 literally after the opening $( or ${. They are not recognized if they
2220 are the result of a recursive expansion.
2222 Note that some of these macros take comma separated parameters but that
2226 Dmake Version 4.12 2008-02-26 32
2232 DMAKE(1) DMAKE(1)
2235 these parameters must not contain literal whitespaces. Whitespaces in
2236 macros used in these parameters are allowed.
2239 $(and macroterm ...)
2240 expands each macroterm in turn until there are no more or
2241 one of them returns an empty string. If all expand to
2242 non-empty strings the macro returs the string "t" other-
2243 wise it returns an empty string.
2246 $(assign expression)
2247 Causes expression to be parsed as a macro assignment
2248 expression and results in the specified assignment being
2249 made. An error is issued if the assignment is not
2250 syntatically correct. expression may contain white
2251 space. This is in effect a dynamic macro assignment
2252 facility and may appear anywhere any other macro may
2253 appear. The result of the expanding a dynamic macro
2254 assignment expression is the name of the macro that was
2255 assigned and $(NULL) if the expression is not a valid
2256 macro assignment expression. Some examples are:
2258 $(assign foo := fred)
2259 $(assign $(ind_macro_name) +:= $(morejunk))
2261 $(echo list)
2262 Echo's the value of list. list is not expanded.
2264 $(eq,text_a,text_b true false)
2265 expands text_a and text_b and compares their results. If
2266 equal it returns the result of the expansion of the true
2267 term, otherwise it returns the expansion of the false
2268 term.
2270 $(!eq,text_a,text_b true false)
2271 Behaves identically to the previous macro except that the
2272 true string is chosen if the expansions of the two
2273 strings are not equal
2275 $(foreach,var,list data)
2276 Implements iterative macro expansion over data using var
2277 as the iterator taking on values from list. var and list
2278 are expanded and the result is the concatenation of
2279 expanding data with var being set to each whitespace sep-
2280 arated token from list. For example:
2282 list = a b c
2283 all :; echo [$(foreach,i,$(list) [$i])]
2285 will output
2287 [[a] [b] [c]]
2289 The iterator variable is defined as a local variable to
2290 this foreach instance. The following expression illus-
2291 trates this:
2293 $(foreach,i,$(foreach,i,$(sort c a b) root/$i) [$i/f.h])
2297 Dmake Version 4.12 2008-02-26 33
2303 DMAKE(1) DMAKE(1)
2306 when evaluated the result is:
2308 [root/a/f.h] [root/b/f.h] [root/c/f.h]
2310 The specification of list must be a valid macro expres-
2311 sion, such as:
2313 $($(assign list=a b c))
2314 $(sort d a b c)
2315 $(echo a b c)
2317 and cannot just be the list itself. That is, the follow-
2318 ing foreach expression:
2320 $(foreach,i,a b c [$i])
2322 yields:
2324 "b c [a]"
2326 when evaluated.
2328 $(nil expression)
2329 Always returns the value of $(NULL) regardless of what
2330 expression is. This function macro can be used to dis-
2331 card results of expanding macro expressions.
2333 $(normpath list)
2334 Will return the normalized path names of all white-space
2335 separated tokens in list. Quotes can be used to normalize
2336 path names that contain white-space characters. On cygwin
2337 the result honors the setting of .WINPATH to determine
2338 the output format of the returned path names.
2340 $(normpath,para list)
2341 Same as above except that the expanded value of para is
2342 used to override the .WINPATH setting.
2344 $(not macroterm)
2345 expands macroterm and returs the string "t" if the result
2346 of the expansion is the empty string; otherwise, it
2347 returns the empty string.
2349 $(null,text true false)
2350 expands the value of text. If it is NULL then the macro
2351 returns the value of the expansion of true and the expan-
2352 sion of false otherwise. The terms true, and false must
2353 be strings containing no white-space.
2355 $(!null,text true false)
2356 Behaves identically to the previous macro except that the
2357 true string is chosen if the expansion of text is not
2358 NULL.
2360 $(or macroterm ...)
2361 expands each macroterm in turn and returs the empty
2362 string if each term expands to the empty string; other-
2363 wise, it returs the string "t".
2368 Dmake Version 4.12 2008-02-26 34
2374 DMAKE(1) DMAKE(1)
2377 $(shell command)
2378 is a shell escape macro. It runs command as if it were
2379 part of a recipe and returns, separated by a single
2380 space, all the non-white space terms written to stdout by
2381 the command. For example:
2383 $(shell ls *.c)
2385 will return "a.c b.c c.c d.c" if the files exist in the
2386 current directory. The recipe modification flags [+@%-]
2387 are honored if they appear as the first characters in the
2388 command. For example:
2390 $(shell +ls *.c)
2392 will run the command using the current shell.
2394 Note that if the macro is part of a recipe it will be
2395 evaluated after all previous recipe lines have been exe-
2396 cuted. For obvious reasons it will be evaluated before
2397 the current recipe line or group recipe is executed.
2399 $(shell,expand command)
2400 Is an extension to the $(shell command) function macro
2401 that expands the result of running command.
2403 $(sort list)
2404 Will take all white-space separated tokens in list and
2405 will return their sorted equivalent list.
2407 $(strip data)
2408 Will replace all strings of white-space in data by a sin-
2409 gle space.
2411 $(subst,pat,replacement data)
2412 Will search for pat in data and will replace any occur-
2413 rence of pat with the replacement string. The expansion
2415 $(subst,.o,.c $(OBJECTS))
2417 is equivalent to:
2419 $(OBJECTS:s/.o/.c/)
2422 $(uniq list)
2423 Will take all white-space separated tokens in list and
2424 will return their sorted equivalent list containing no
2425 duplicates.
2427 For historic reasons dmake treats the following case slightly special:
2429 $(name something)
2431 If it encounters a macro with a whitespace after name and name is not
2432 literally one of the above mentioned function macro identifiers then
2433 dmake will return the recursively expanded value of $(name). The
2434 remaining something part will be expanded but the result will be dis-
2435 carded. The use of this special feature is deprecated and should not be
2439 Dmake Version 4.12 2008-02-26 35
2445 DMAKE(1) DMAKE(1)
2448 used.
2451 CONDITIONAL MACROS
2452 dmake supports conditional macros. These allow the definition of tar-
2453 get specific macro values. You can now say the following:
2455 target ?= MacroName MacroOp Value
2457 This creates a definition for MacroName whose value is Value only when
2458 target is being made. You may use a conditional macro assignment any-
2459 where that a regular macro assignment may appear, including as the
2460 value of a $(assign ...) macro.
2462 The new definition is associated with the most recent cell definition
2463 for target. If no prior definition exists then one is created. The
2464 implications of this are immediately evident in the following example:
2466 foo := hello
2468 all : cond;@echo "all done, foo=[$(foo)] bar=[$(bar)]"
2470 cond ?= bar := global decl
2472 cond .SETDIR=unix::;@echo $(foo) $(bar)
2473 cond ?= foo := hi
2475 cond .SETDIR=msdos::;@echo $(foo) $(bar)
2476 cond ?= foo := hihi
2478 The first conditional assignment creates a binding for 'bar' that is
2479 activated when 'cond' is made. The bindings following the :: defini-
2480 tions are activated when their respective recipe rules are used. Thus
2481 the first binding serves to provide a global value for 'bar' while any
2482 of the cond :: rules are processed, and the local bindings for 'foo'
2483 come into effect when their associated :: rule is processed.
2485 Conditionals for targets of .UPDATEALL are all activated before the
2486 target group is made. Assignments are processed in order. Note that
2487 the value of a conditional macro assignment is NOT AVAILABLE until the
2488 associated target is made, thus the construct
2490 mytarget ?= bar := hello
2491 mytarget ?= foo := $(bar)
2493 results in $(foo) expanding to "", if you want the result to be "hello"
2494 you must use:
2496 mytarget ?= bar := hello
2497 mytarget ?= foo = $(bar)
2499 Once a target is made any associated conditional macros are deactivated
2500 and their values are no longer available. Activation occurrs after all
2501 inference, and .SETDIR directives have been processed and after $@ is
2502 assigned, but before prerequisites are processed; thereby making the
2503 values of conditional macro definitions available during construction
2504 of prerequisites.
2506 If a %-meta rule target has associated conditional macro assignments,
2510 Dmake Version 4.12 2008-02-26 36
2516 DMAKE(1) DMAKE(1)
2519 and the rule is chosen by the inference algorithm then the conditional
2520 macro assignments are inferred together with the associated recipe.
2522 DYNAMIC PREREQUISITES
2523 dmake looks for prerequisites whose names contain macro expansions dur-
2524 ing target processing. Any such prerequisites are expanded and the
2525 result of the expansion is used as the prerequisite name. As an exam-
2526 ple the line:
2528 fred : $$@.c
2530 causes the $$@ to be expanded when dmake is making fred, and it
2531 resolves to the target fred. This enables dynamic prerequisites to be
2532 generated. The value of @ may be modified by any of the valid macro
2533 modifiers. So you can say for example:
2535 fred.out : $$(@:b).c
2537 where the $$(@:b) expands to fred. Note the use of $$ instead of $ to
2538 indicate the dynamic expansion, this is due to the fact that the rule
2539 line is expanded when it is initially parsed, and $$ then returns $
2540 which later triggers the dynamic prerequisite expansion. Dynamic macro
2541 expansion is performed in all user defined rules, and the special tar-
2542 gets .SOURCE*, and .INCLUDEDIRS.
2544 NOTE: The use of a $ as part of a prerequisite or target name is
2545 strongly discouraged as the runtime macros (like $@) are expanded when
2546 used in a recipe line so that the $ is interpreted as a macro identi-
2547 fier and not as a character of the filename leading to invalid runtime
2548 macros. In addition to this no filename normalization is done for pre-
2549 requisites and targets that contain $ characters. Nevertheless it is
2550 possible to use $ in prerequisites by using $$$$ but this is not recom-
2551 mended and can lead to surprising results.
2553 If dynamic macro expansion results in multiple white space separated
2554 tokens then these are inserted into the prerequisite list inplace of
2555 the dynamic prerequisite. Due to the recursive nature of macro expan-
2556 sion the prerequisite list is fully expanded even if the dynamic pre-
2557 requisite contained other runtime macros.
2559 BINDING TARGETS
2560 This operation takes a target name and binds it to an existing file, if
2561 possible. dmake makes a distinction between the internal target name
2562 of a target and its associated external file name. Thus it is possible
2563 for a target's internal name and its external file name to differ. To
2564 perform the binding, the following set of rules is used. Assume that
2565 we are trying to bind a target whose name is of the form X.suff, where
2566 .suff is the suffix and X is the stem portion (ie. that part which con-
2567 tains the directory and the basename). dmake takes this target name
2568 and performs a series of search operations that try to find a suitably
2569 named file in the external file system. The search operation is user
2570 controlled via the settings of the various .SOURCE targets.
2572 1. If target has the .SYMBOL attribute set then look for it
2573 in the library. If found, replace the target name with
2574 the library member name and continue with step 2. If the
2575 name is not found then return.
2577 2. Extract the suffix portion (that following the `.') of
2578 the target name. If the suffix is not null, look up the
2582 Dmake Version 4.12 2008-02-26 37
2588 DMAKE(1) DMAKE(1)
2591 special target .SOURCE.<suff> (<suff> is the suffix). If
2592 the special target exists then search each directory
2593 given in the .SOURCE.<suff> prerequisite list for the
2594 target. If the target's suffix was null (ie. .suff was
2595 empty) then perform the above search but use the special
2596 target .SOURCE.NULL instead. If at any point a match is
2597 found then terminate the search. If a directory in the
2598 prerequisite list is the special name `.NULL ' perform a
2599 search for the full target name without prepending any
2600 directory portion (ie. prepend the NULL directory).
2602 3. The search in step 2. failed. Repeat the same search but
2603 this time use the special target .SOURCE. (a default
2604 target of '.SOURCE : .NULL' is defined by dmake at
2605 startup, and is user redefinable)
2607 4. The search in step 3. failed. If the target has the
2608 library member attribute (.LIBMEMBER) set then try to
2609 find the target in the library which was passed along
2610 with the .LIBMEMBER attribute (see the MAKING LIBRARIES
2611 section). The bound file name assigned to a target which
2612 is successfully located in a library is the same name
2613 that would be assigned had the search failed (see 5.).
2615 5. The search failed. Either the target was not found in
2616 any of the search directories or no applicable .SOURCE
2617 special targets exist. If applicable .SOURCE special
2618 targets exist, but the target was not found, then dmake
2619 assigns the first name searched as the bound file name.
2620 If no applicable .SOURCE special targets exist, then the
2621 full original target name becomes the bound file name.
2623 There is potential here for a lot of search operations. The trick is
2624 to define .SOURCE.x special targets with short search lists and leave
2625 .SOURCE as short as possible. The search algorithm has the following
2626 useful side effect. When a target having the .LIBMEMBER (library mem-
2627 ber) attribute is searched for, it is first searched for as an ordinary
2628 file. When a number of library members require updating it is desir-
2629 able to compile all of them first and to update the library at the end
2630 in a single operation. If one of the members does not compile and
2631 dmake stops, then the user may fix the error and make again. dmake
2632 will not remake any of the targets whose object files have already been
2633 generated as long as none of their prerequisite files have been modi-
2634 fied as a result of the fix.
2636 When dmake constructs target (and prerequisite) pathnames they are nor-
2637 malized to the shortest (or most natural, see below for the cygwin
2638 case) representation. Substrings like './' or of the form 'baz/..' are
2639 removed and multiple slashes are collapsed to one unless they are at
2640 the beginning of the pathname. Leading slashes are normalized according
2641 to POSIX rules, i.e. more than two leading slashes are reduced to one
2642 slash and a leading '//' is kept as it might have a special meaning.
2643 For example "./foo", "bar/../foo" and foo are recognized as the same
2644 file. This may result in somewhat unexpected values of the macro
2645 expansion of runtime macros like $@, but is infact the corect result.
2647 NOTE: A cygwin dmake executable will accept DOS like pathnames with
2648 drive letters and cygwin POSIX pathnames and normalize them into its
2649 natural POSIX representation. This might result in even more surpris-
2650 ing values of runtime macros.
2654 Dmake Version 4.12 2008-02-26 38
2660 DMAKE(1) DMAKE(1)
2663 When defining .SOURCE and .SOURCE.x targets the construct
2665 .SOURCE :
2666 .SOURCE : fred gery
2668 is equivalent to
2670 .SOURCE :- fred gery
2672 dmake correctly handles the UNIX Make variable VPATH. By definition
2673 VPATH contains a list of ':' separated directories to search when look-
2674 ing for a target. dmake maps VPATH to the following special rule:
2676 .SOURCE :^ $(VPATH:s/:/ /)
2678 Which takes the value of VPATH and sets .SOURCE to the same set of
2679 directories as specified in VPATH.
2681 PERCENT(%) RULES AND MAKING INFERENCES
2682 When dmake makes a target, the target's set of prerequisites (if any)
2683 must exist and the target must have a recipe which dmake can use to
2684 make it. If the makefile does not specify an explicit recipe for the
2685 target then dmake uses special rules to try to infer a recipe which it
2686 can use to make the target. Previous versions of Make perform this
2687 task by using rules that are defined by targets of the form .<suf-
2688 fix>.<suffix> (this is still supported, see "AUGMAKE META RULES") or by
2689 using the not supported by dmake .SUFFIXES list of suffixes (see "SPE-
2690 CIAL TARGETS" for more details about .SUFFIXES). The exact workings of
2691 this mechanism were sometimes difficult to understand and often limit-
2692 ing in their usefulness. Instead, dmake supports the concept of %-meta
2693 rules. The syntax and semantics of these rules differ from standard
2694 rule lines as follows:
2696 <%-targets> [<attributes>] <ruleop> [<%-prereqs>] [;<recipe>]
2698 where %-targets are one or more targets containing exactly a single `%'
2699 sign, attributes is a list (possibly empty) of attributes, ruleop is
2700 the standard set of rule operators, %-prereqs , if present, is a list
2701 of prerequisites containing zero or more `%' signs, and recipe, if
2702 present, is the first line of the recipe.
2704 If more than one %-target is present this line is equivalent to a repe-
2705 tition of the whole [<attributes>] <ruleop> [<%-prereqs>] [;<recipe>]
2706 sequence for each %-target, i.e. it is possible to specify the same
2707 rule for multiple %-targets. Because of this following only speaks
2708 about <%-target> as %-targets are divided into multiple definitions
2709 with a single %-target.
2711 NOTE: As multiple %-targets didn't work reliably with dmake versions
2712 prior to 4.5 unless the rule operator `|:' was used we currently issue
2713 a warning stating that it now works.
2715 The %-target defines a pattern against which a target whose recipe is
2716 being inferred gets matched. The pattern match goes as follows: all
2717 chars are matched exactly from left to right up to but not including
2718 the % sign in the pattern, % then matches the longest string from the
2719 actual target name not ending in the suffix given after the % sign in
2720 the pattern. Consider the following examples:
2722 %.c matches fred.c but not joe.c.Z
2723 dir/%.c matches dir/fred.c but not dd/fred.c
2724 fred/% matches fred/joe.c but not f/joe.c
2725 % matches anything
2730 Dmake Version 4.12 2008-02-26 39
2736 DMAKE(1) DMAKE(1)
2739 In each case the part of the target name that matched the % sign is
2740 retained and is substituted for any % signs in the prerequisite list of
2741 the %-meta rule when the rule is selected during inference and dmake
2742 constructs the new dependency.
2744 Please note, that only the first, non-indirect, prerequisite of the
2745 list is used for the inference mechanism. If more than one non-indirect
2746 prerequisite is given a warning is issued and all but the first non-
2747 indirect prerequisites are ignored. See below for a description of
2748 indirect prerequisites.
2750 As an example the following %-meta rules describe the following:
2752 %.c : %.y ; recipe...
2754 describes how to make any file ending in .c if a corresponding file
2755 ending in .y can be found.
2757 foo%.o : fee%.k ; recipe...
2759 is used to describe how to make fooxxxx.o from feexxxx.k.
2761 %.a :; recipe...
2763 describes how to make a file whose suffix is .a without inferring any
2764 prerequisites.
2766 %.c : %.y 'yaccsrc/%.y' ; recipe...
2768 matches the corresponding .y file as prerequisite and additionally
2769 another .y file in the yaccsrc subdirectory as indirect prerequisite.
2770 Another interesting example is:
2772 % : RCS/%,v ; co $<
2774 which describes how to take any target and check it out of the RCS
2775 directory if the corresponding file exists in the RCS directory. The
2776 equivalent SCCS rule would be:
2778 % : s.% ; get $<
2781 The previous RCS example defines an infinite rule, because it says how
2782 to make anything from RCS/%,v, and anything also includes RCS/fred.c,v.
2783 To limit the size of the graph that results from such rules dmake uses
2784 the macro variable PREP (stands for % repetition). By default the
2785 value of this variable is 0, which says that no repetitions of a %-rule
2786 are to be generated. If it is set to something greater than 0, then
2787 that many repetitions of any infinite %-rule are allowed. If in the
2788 above example PREP was set to 1, then dmake would generate the depen-
2789 dency graph:
2791 % --> RCS/%,v --> RCS/RCS/%,v,v
2793 Where each link is assigned the same recipe as the first link. PREP
2794 should be used only in special cases, since it may result in a large
2795 increase in the number of possible prerequisites tested. dmake further
2796 assumes that any target that has no suffix can be made from a prerequi-
2797 site that has at least one suffix.
2799 dmake supports dynamic prerequisite generation for prerequisites of
2800 %-meta rules. This is best illustrated by an example. The RCS rule
2801 shown above can infer how to check out a file from a corresponding RCS
2802 file only if the target is a simple file name with no directory
2806 Dmake Version 4.12 2008-02-26 40
2812 DMAKE(1) DMAKE(1)
2815 information. That is, the above rule can infer how to find
2816 RCS/fred.c,v from the target fred.c, but cannot infer how to find
2817 srcdir/RCS/fred.c,v from srcdir/fred.c because the above rule will
2818 cause dmake to look for RCS/srcdir/fred.c,v; which does not exist
2819 (assume that srcdir has its own RCS directory as is the common case).
2821 A more versatile formulation of the above RCS check out rule is the
2822 following:
2824 % : $$(@:d)RCS/$$(@:f),v : co $@
2826 This rule uses the dynamic macro $@ to specify the prerequisite to try
2827 to infer. During inference of this rule the macro $@ is set to the
2828 value of the target of the %-meta rule and the appropriate prerequisite
2829 is generated by extracting the directory portion of the target name (if
2830 any), appending the string RCS/ to it, and appending the target file
2831 name with a trailing ,v attached to the previous result.
2833 dmake can also infer indirect prerequisites. An inferred target can
2834 have a list of prerequisites added that will not show up in the value
2835 of $< but will show up in the value of $? and $&. Indirect prerequi-
2836 sites are specified in an inference rule by quoting the prerequisite
2837 with single quotes. For example, if you had the explicit dependency:
2839 fred.o : fred.c ; rule to make fred.o
2840 fred.o : local.h
2842 then this can be inferred for fred.o from the following inference rule:
2844 %.o : %.c 'local.h' ; makes a .o from a .c
2846 You may infer indirect prerequisites that are a function of the value
2847 of '%' in the current rule. The meta-rule:
2849 %.o : %.c '$(INC)/%.h' ; rule to make a .o from a .c
2851 infers an indirect prerequisite found in the INC directory whose name
2852 is the same as the expansion of $(INC), and the prerequisite name
2853 depends on the base name of the current target. The set of indirect
2854 prerequisites is attached to the meta rule in which they are specified
2855 and are inferred only if the rule is used to infer a recipe for a tar-
2856 get. They do not play an active role in driving the inference algo-
2857 rithm. The construct:
2859 %.o :| %.c %.f 'local.h'; recipe
2861 is equivalent to:
2863 %.o : %.c 'local.h' ; recipe
2864 %.o : %.f 'local.h' ; recipe
2867 If any of the attributes .EPILOG, .IGNORE, .LIBRARY, .NOSTATE, .PHONY,
2868 .PRECIOUS, .PROLOG, .SETDIR, .SILENT, .SWAP, .USESHELL and .WINPATH are
2869 given for a %-rule then when that rule is bound to a target as the
2870 result of an inference, the target's set of attributes is augmented by
2871 the attributes from the above set that are specified in the bound
2872 %-rule. Other attributes specified for %-meta rules are not inherited
2873 by the target. The .SETDIR attribute is treated in a special way. If
2874 the target already had a .SETDIR attribute set then dmake changes to
2875 that directory prior to performing the inference. During inference any
2876 .SETDIR attributes for the inferred prerequisite are honored. The
2877 directories must exist for a %-meta rule to be selected as a possible
2878 inference path. If the directories do not exist no error message is
2882 Dmake Version 4.12 2008-02-26 41
2888 DMAKE(1) DMAKE(1)
2891 issued, instead the corresponding path in the inference graph is
2892 rejected.
2894 dmake bases all of its inferences on the inference graph constructed
2895 from the %-rules defined in the makefile. It knows exactly which tar-
2896 gets can be made from which prerequisites by making queries on the
2897 inference graph.
2899 For a %-meta rule to be inferred as the rule whose recipe will be used
2900 to make a target, the target's name must match the %-target pattern,
2901 and any inferred %-prerequisite must already exist or have an explicit
2902 recipe so that the prerequisite can be made. Without transitive clo-
2903 sure on the inference graph the above rule describes precisely when an
2904 inference match terminates the search. If transitive closure is
2905 enabled (the usual case), and a prerequisite does not exist or cannot
2906 be made, then dmake invokes the inference algorithm recursively on the
2907 prerequisite to see if there is some way the prerequisite can be manu-
2908 factured. For, if the prerequisite can be made then the current target
2909 can also be made using the current %-meta rule. This means that there
2910 is no longer a need to give a rule for making a .o from a .y if you
2911 have already given a rule for making a .o from a .c and a .c from a .y.
2912 In such cases dmake can infer how to make the .o from the .y via the
2913 intermediary .c and will remove the .c when the .o is made. Transitive
2914 closure can be disabled by giving the -T switch on the command line.
2916 A word of caution. dmake bases its transitive closure on the %-meta
2917 rule targets. When it performs transitive closure it infers how to
2918 make a target from a prerequisite by performing a pattern match as if
2919 the potential prerequisite were a new target. The set of rules:
2921 %.o : %.c ; rule for making .o from .c
2922 %.c : %.y ; rule for making .c from .y
2923 % : RCS/%,v ; check out of RCS file
2925 will, by performing transitive closure, allow dmake to infer how to
2926 make a .o from a .y using a .c as an intermediate temporary file.
2927 Additionally it will be able to infer how to make a .y from an RCS
2928 file, as long as that RCS file is in the RCS directory and has a name
2929 which ends in .y,v. The transitivity computation is performed dynami-
2930 cally for each target that does not have a recipe. This has potential
2931 to be costly if the %-meta rules are not carefully specified. The
2932 .NOINFER attribute is used to mark a %-meta node as being a final tar-
2933 get during inference. Any node with this attribute set will not be
2934 used for subsequent inferences. As an example the node RCS/%,v is
2935 marked as a final node since we know that if the RCS file does not
2936 exist there likely is no other way to make it. Thus the standard
2937 startup makefile contains an entry similar to:
2938 .NOINFER : RCS/%,v
2939 Thereby indicating that the RCS file is the end of the inference chain.
2940 Whenever the inference algorithm determines that a target can be made
2941 from more than one prerequisite and the inference chains for the two
2942 methods are the same length the algorithm reports an ambiguity and
2943 prints the ambiguous inference chains.
2945 dmake tries to remove intermediate files resulting from transitive clo-
2946 sure if the file is not marked as being PRECIOUS, or the -u flag was
2947 not given on the command line, and if the inferred intermediate did not
2948 previously exist. Intermediate targets that existed prior to being
2949 made are never removed. This is in keeping with the philosophy that
2950 dmake should never remove things from the file system that it did not
2951 add. If the special target .REMOVE is defined and has a recipe then
2952 dmake constructs a list of the intermediate files to be removed and
2953 makes them prerequisites of .REMOVE. It then makes .REMOVE thereby
2954 removing the prerequisites if the recipe of .REMOVE says to. Typically
2958 Dmake Version 4.12 2008-02-26 42
2964 DMAKE(1) DMAKE(1)
2967 .REMOVE is defined in the startup file as:
2969 .REMOVE :; $(RM) $<
2971 AUGMAKE META RULES
2972 As a subclass of the meta targets that is actually mapped to %-meta
2973 rules dmake understands several SYSV AUGMAKE targets transformations.
2974 This .<suffix> special target construct transforms into the following
2975 %-meta rules:
2977 .suff :; recipe
2979 gets mapped into:
2981 % : %.suff; recipe
2984 dmake also supports the old format special target .<suffix>.<suffix> by
2985 identifying any rules of this form and mapping them to the appropriate
2986 %-rule. So for example if an old makefile contains the construct:
2988 .c.o :; cc -c $< -o $@
2990 dmake maps this into the following %-rule:
2992 %.o : %.c; cc -c $< -o $@
2994 The following SYSV AUGMAKE special targets transformation must be
2995 enabled by providing the -A flag on the command line or by setting the
2996 value of AUGMAKE to non-NULL. The construct
2998 .c~.o :; recipe
3000 gets mapped into:
3002 %.o : s.%.c ; recipe
3004 In general, a special target of the form .<str>~ is replaced by the
3005 %-rule construct s.%.<str>, thereby providing support for the syntax
3006 used by SYSV AUGMAKE for providing SCCS support. When enabled, these
3007 mappings allow processing of existing SYSV makefiles without modifica-
3008 tions.
3010 MAKING TARGETS
3011 In order to update a target dmake must execute a recipe. When a recipe
3012 needs to be executed it is first expanded so that any macros in the
3013 recipe text are expanded, and it is then either executed directly or
3014 passed to a shell. dmake supports two types of recipes. The regular
3015 recipes and group recipes.
3017 When a regular recipe is invoked dmake executes each line of the recipe
3018 separately using a new copy of a shell if a shell is required. Thus
3019 effects of commands do not generally persist across recipe lines (e.g.
3020 cd requests in a recipe line do not carry over to the next recipe
3021 line). This is true even in environments such as MSDOS, where dmake
3022 internally sets the current working director to match the directory it
3023 was in before the command was executed.
3025 The decision on whether a shell is required to execute a command is
3026 based on the value of the macro SHELLMETAS or on the specification of
3027 '+' or .USESHELL for the current recipe or target respectively. If any
3028 character in the value of SHELLMETAS is found in the expanded recipe
3029 text-line or the use of a shell is requested explicitly via '+' or
3030 .USESHELL then the command is executed using a shell, otherwise the
3034 Dmake Version 4.12 2008-02-26 43
3040 DMAKE(1) DMAKE(1)
3043 command is executed directly. The shell that is used for execution is
3044 given by the value of the macro SHELL. The flags that are passed to
3045 the shell are given by the value of SHELLFLAGS. Thus dmake constructs
3046 the command line:
3048 $(SHELL) $(SHELLFLAGS) $(expanded_recipe_command)
3050 If the $(SHELLCMDQUOTE) macro is set its value is inserted before and
3051 after the $(expanded_recipe_command) string.
3053 Normally dmake writes the command line that it is about to invoke to
3054 standard output. If the .SILENT attribute is set for the target or for
3055 the recipe line (via @), then the recipe line is not echoed.
3057 Group recipe processing is similar to that of regular recipes, except
3058 that a shell is always invoked. The shell that is invoked is given by
3059 the value of the macro GROUPSHELL, and its flags are taken from the
3060 value of the macro GROUPFLAGS. If a target has the .PROLOG attribute
3061 set then dmake prepends to the shell script the recipe associated with
3062 the special target .GROUPPROLOG, and if the attribute .EPILOG is set as
3063 well, then the recipe associated with the special target .GROUPEPILOG
3064 is appended to the script file. This facility can be used to always
3065 prepend a common header and common trailer to group recipes. Group
3066 recipes are echoed to standard output just like standard recipes, but
3067 are enclosed by lines beginning with [ and ].
3069 The recipe flags [+,-,%,@] are recognized at the start of a recipe line
3070 even if they appear in a macro. For example:
3072 SH = +
3073 all:
3074 $(SH)echo hi
3076 is completely equivalent to writing
3078 SH = +
3079 all:
3080 +echo hi
3083 The last step performed by dmake prior to running a recipe is to set
3084 the macro CMNDNAME to the name of the command to execute (determined by
3085 finding the first white-space ending token in the command line). It
3086 then sets the macro CMNDARGS to be the remainder of the line. dmake
3087 then expands the macro COMMAND which by default is set to
3089 COMMAND = $(CMNDNAME) $(CMNDARGS)
3091 The result of this final expansion is the command that will be exe-
3092 cuted. The reason for this expansion is to allow for a different
3093 interface to the argument passing facilities (esp. under DOS) than that
3094 provided by dmake. You can for example define COMMAND to be
3096 COMMAND = $(CMNDNAME) @$(mktmp $(CMNDARGS))
3098 which dumps the arguments into a temporary file and runs the command
3100 $(CMNDNAME) @/tmp/ASAD23043
3102 which has a much shorter argument list. It is now up to the command to
3103 use the supplied argument as the source for all other arguments. As an
3104 optimization, if COMMAND is not defined dmake does not perform the
3105 above expansion. On systems, such as UNIX, that handle long command
3106 lines this provides a slight saving in processing the makefiles.
3110 Dmake Version 4.12 2008-02-26 44
3116 DMAKE(1) DMAKE(1)
3119 MAKING LIBRARIES
3120 Libraries are easy to maintain using dmake. A library is a file con-
3121 taining a collection of object files. Thus to make a library you sim-
3122 ply specify it as a target with the .LIBRARY attribute set and specify
3123 its list of prerequisites. The prerequisites should be the object mem-
3124 bers that are to go into the library. When dmake makes the library
3125 target it uses the .LIBRARY attribute to pass to the prerequisites the
3126 .LIBMEMBER attribute and the name of the library. This enables the
3127 file binding mechanism to look for the member in the library if an
3128 appropriate object file cannot be found. dmake now supports Elf
3129 libraries on systems that support Elf and hence supports, on those sys-
3130 tems, long member file names. A small example best illustrates this.
3132 mylib.a .LIBRARY : mem1.o mem2.o mem3.o
3133 rules for making library...
3134 # remember to remove .o's when lib is made
3136 # equivalent to: '%.o : %.c ; ...'
3137 .c.o :; rules for making .o from .c say
3139 dmake will use the .c.o rule for making the library members if appro-
3140 priate .c files can be found using the search rules. NOTE: this is
3141 not specific in any way to C programs, they are simply used as an exam-
3142 ple.
3144 dmake tries to handle the old library construct format in a sensible
3145 way. The construct lib(member.o) is separated and the lib portion is
3146 declared as a library target. The new target is defined with the
3147 .LIBRARY attribute set and the member.o portion of the construct is
3148 declared as a prerequisite of the lib target. If the construct
3149 lib(member.o) appears as a prerequisite of a target in the makefile,
3150 that target has the new name of the lib assigned as its prerequisite.
3151 Thus the following example:
3153 a.out : ml.a(a.o) ml.a(b.o); $(CC) -o $@ $<
3155 .c.o :; $(CC) -c $(CFLAGS) -o $@ $<
3156 %.a:
3157 ar rv $@ $?
3158 ranlib $@
3159 rm -rf $?
3161 constructs the following dependency graph.
3163 a.out : ml.a; $(CC) -o $@ $<
3164 ml.a .LIBRARY : a.o b.o
3166 %.o : %.c ; $(CC) -c $(CFLAGS) -o $@ $<
3167 %.a :
3168 ar rv $@ $?
3169 ranlib $@
3170 rm -rf $?
3172 and making a.out then works as expected.
3174 The same thing happens for any target of the form lib((entry)). These
3175 targets have an additional feature in that the entry target has the
3176 .SYMBOL attribute set automatically.
3178 NOTE: If the notion of entry points is supported by the archive and by
3179 dmake (currently not the case) then dmake will search the archive for
3180 the entry point and return not only the modification time of the member
3181 which defines the entry but also the name of the member file. This
3182 name will then replace entry and will be used for making the member
3186 Dmake Version 4.12 2008-02-26 45
3192 DMAKE(1) DMAKE(1)
3195 file. Once bound to an archive member the .SYMBOL attribute is removed
3196 from the target. This feature is presently disabled as there is little
3197 standardization among archive formats, and we have yet to find a make-
3198 file utilizing this feature (possibly due to the fact that it is unim-
3199 plemented in most versions of UNIX Make).
3201 Finally, when dmake looks for a library member it must first locate the
3202 library file. It does so by first looking for the library relative to
3203 the current directory and if it is not found it then looks relative to
3204 the current value of $(TMD). This allows commonly used libraries to be
3205 kept near the root of a source tree and to be easily found by dmake.
3207 KEEP STATE
3208 dmake supports the keeping of state information for targets that it
3209 makes whenever the macro .KEEP_STATE is assigned a value. The value of
3210 the macro should be the name of a state file that will contain the
3211 state information. If state keeping is enabled then each target that
3212 does not poses the .NOSTATE attribute will have a record written into
3213 the state file indicating the target's name, the current directory, the
3214 command used to update the target, and which, if any, :: rule is being
3215 used. When you make this target again if any of this information does
3216 not match the previous settings and the target is not out dated it will
3217 still be re-made. The assumption is that one of the conditions above
3218 has changed and that we wish to remake the target. For example, state
3219 keeping is used in the maintenance of dmake to test compile different
3220 versions of the source using different compilers. Changing the com-
3221 piler causes the compilation flags to be modified and hence all sources
3222 to be recompiled.
3224 The state file is an ascii file and is portable, however it is not in
3225 human readable form as the entries represent hash keys of the above
3226 information.
3228 The Sun Microsystem's Make construct
3230 .KEEP_STATE :
3232 is recognized and is mapped to .KEEP_STATE:=_state.mk. The dmake ver-
3233 sion of state keeping does not include scanning C source files for
3234 dependencies like Sun Make. This is specific to C programs and it was
3235 felt that it does not belong in make. dmake instead provides the tool,
3236 cdepend, to scan C source files and to produce depedency information.
3237 Users are free to modify cdepend to produce other dependency files.
3238 (NOTE: cdepend does not come with the distribution at this time, but
3239 will be available in a patch in the near future)
3241 MULTI PROCESSING
3242 If the architecture supports it then dmake is capable of making a tar-
3243 get's prerequisites in parallel. dmake will make as much in parallel
3244 as it can and use a number of child processes up to the maximum speci-
3245 fied by MAXPROCESS or by the value supplied to the -P command line
3246 flag. A parallel make is enabled by setting the value of MAXPROCESS
3247 (either directly or via -P option) to a value which is > 1. dmake
3248 guarantees that all dependencies as specified in the makefile are hon-
3249 ored. A target will not be made until all of its prerequisites have
3250 been made. Note that when you specify -P 4 then four child processes
3251 are run concurrently but dmake actually displays the fifth command it
3252 will run immediately upon a child process becomming free. This is an
3253 artifact of the method used to traverse the dependency graph and cannot
3254 be removed. If a parallel make is being performed then the following
3255 restrictions on parallelism are enforced.
3257 1. Individual recipe lines in a non-group recipe are per-
3258 formed sequentially in the order in which they are
3262 Dmake Version 4.12 2008-02-26 46
3268 DMAKE(1) DMAKE(1)
3271 specified within the makefile and in parallel with the
3272 recipes of other targets.
3274 2. If a target contains multiple recipe definitions (cf. ::
3275 rules) then these are performed sequentially in the order
3276 in which the :: rules are specified within the makefile
3277 and in parallel with the recipes of other targets.
3279 3. If a target rule contains the `!' modifier, then the
3280 recipe is performed sequentially for the list of outdated
3281 prerequisites and in parallel with the recipes of other
3282 targets.
3284 4. If a target has the .SEQUENTIAL attribute set then all of
3285 its prerequisites are made sequentially relative to one
3286 another (as if MAXPROCESS=1), but in parallel with other
3287 targets in the makefile.
3289 Note: If you specify a parallel make then the order of target update
3290 and the order in which the associated recipes are invoked will not cor-
3291 respond to that displayed by the -n flag.
3293 CONDITIONALS
3294 dmake supports a makefile construct called a conditional. It allows
3295 the user to conditionally select portions of makefile text for input
3296 processing and to discard other portions. This becomes useful for
3297 writing makefiles that are intended to function for more than one tar-
3298 get host and environment. The conditional expression is specified as
3299 follows:
3301 .IF expression
3302 ... if text ...
3303 .ELIF expression
3304 ... if text ...
3305 .ELSE
3306 ... else text ...
3307 .END
3309 The .ELSE and .ELIF portions are optional, and the conditionals may be
3310 nested (ie. the text may contain another conditional). .IF, .ELSE,
3311 and .END may appear anywhere in the makefile, but a single conditional
3312 expression may not span multiple makefiles.
3314 expression can be one of the following forms:
3316 String evaluation
3317 <text> | <text> == <text> | <text> != <text>
3319 Numeric evaluation
3320 <text> <= <text> | <text> >= <text>
3322 Boolean evaluation
3323 ( <text> ) | <text> || <text> | <text> && <text>
3325 where text is either text or a macro expression. In any case, before
3326 the comparison is made, the expression is expanded. The text portions
3327 are then selected and compared. In the case of the numeric comparisons
3328 enclosing quotes are removed after expanding the expressions and the
3329 leading numerical parts are converted to an integer number. If no
3330 numerical part is found this results to 0 (zero). The string "12ab" for
3331 example evaluates to the number 12. Expressions can be nested with ()
3332 and the use of || or &&. White space at the start and end of the text
3333 portion is discarded before the comparison. This means that a macro
3334 that evaluates to nothing but white space is considered a NULL value
3338 Dmake Version 4.12 2008-02-26 47
3344 DMAKE(1) DMAKE(1)
3347 for the purpose of the comparison. In the first case the expression
3348 evaluates TRUE if the text is not NULL otherwise it evaluates FALSE.
3349 The remaining two cases both evaluate the expression on the basis of a
3350 string comparison. If a macro expression needs to be equated to a NULL
3351 string then compare it to the value of the macro $(NULL). You can use
3352 the $(shell ...) macro to construct more complex test expressions.
3354 EXAMPLES
3355 # A simple example showing how to use make
3356 #
3357 prgm : a.o b.o
3358 cc a.o b.o -o prgm
3359 a.o : a.c g.h
3360 cc a.c -o $@
3361 b.o : b.c g.h
3362 cc b.c -o $@
3364 In the previous example prgm is remade only if a.o and/or b.o is out of
3365 date with respect to prgm. These dependencies can be stated more con-
3366 cisely by using the inference rules defined in the standard startup
3367 file. The default rule for making .o's from .c's looks something like
3368 this:
3370 %.o : %.c; cc -c $(CFLAGS) -o $@ $<
3372 Since there exists a rule (defined in the startup file) for making .o's
3373 from .c's dmake will use that rule for manufacturing a .o from a .c and
3374 we can specify our dependencies more concisely.
3376 prgm : a.o b.o
3377 cc -o prgm $<
3378 a.o b.o : g.h
3380 A more general way to say the above using the new macro expansions
3381 would be:
3383 SRC = a b
3384 OBJ = {$(SRC)}.o
3386 prgm : $(OBJ)
3387 cc -o $@ $<
3389 $(OBJ) : g.h
3391 If we want to keep the objects in a separate directory, called objdir,
3392 then we would write something like this.
3394 SRC = a b
3395 OBJ = {$(SRC)}.o
3397 prgm : $(OBJ)
3398 cc $< -o $@
3400 $(OBJ) : g.h
3401 %.o : %.c
3402 $(CC) -c $(CFLAGS) -o $(@:f) $<
3403 mv $(@:f) objdir
3405 .SOURCE.o : objdir # tell dmake to look here for .o's
3407 An example of building library members would go something like this:
3408 (NOTE: The same rules as above will be used to produce .o's from .c's)
3410 SRC= a b
3414 Dmake Version 4.12 2008-02-26 48
3420 DMAKE(1) DMAKE(1)
3423 LIB= lib
3424 LIBm= { $(SRC) }.o
3426 prgm: $(LIB)
3427 cc -o $@ $(LIB)
3429 $(LIB) .LIBRARY : $(LIBm)
3430 ar rv $@ $<
3431 rm $<
3433 Finally, suppose that each of the source files in the previous example
3434 had the `:' character in their target name. Then we would write the
3435 above example as:
3437 SRC= f:a f:b
3438 LIB= lib
3439 LIBm= "{ $(SRC) }.o" # put quotes around each token
3441 prgm: $(LIB)
3442 cc -o $@ $(LIB)
3444 $(LIB) .LIBRARY : $(LIBm)
3445 ar rv $@ $<
3446 rm $<
3448 COMPATIBILITY
3449 There are two notable differences between dmake and the standard ver-
3450 sion of BSD UNIX 4.2/4.3 Make.
3452 1. BSD UNIX 4.2/4.3 Make supports wild card filename expansion
3453 for prerequisite names. Thus if a directory contains a.h,
3454 b.h and c.h, then a line like
3456 target: *.h
3458 will cause UNIX make to expand the *.h into "a.h b.h c.h".
3459 dmake does not support this type of filename expansion.
3461 2. Unlike UNIX make, touching a library member causes dmake to
3462 search the library for the member name and to update the
3463 library time stamp. This is only implemented in the UNIX
3464 version. MSDOS and other versions may not have librarians
3465 that keep file time stamps, as a result dmake touches the
3466 library file itself, and prints a warning.
3468 dmake is not compatible with GNU Make. In particular it does not
3469 understand GNU Make's macro expansions that query the file system.
3471 dmake is fully compatible with SYSV AUGMAKE, and supports the following
3472 AUGMAKE features:
3474 1. GNU Make style include, and if/else/endif directives are
3475 allowed in non-group recipes. Thus, the word include appear-
3476 ing at the start of a line that is not part of a gruop recipe
3477 will be mapped to the ".INCLUDE" directive that damke uses.
3478 Similarly, the words ifeq,ifneq,elif,else, and endif are
3479 mapped to their corresponding dmake equivalents.
3481 2. The macro modifier expression $(macro:str=sub) is understood
3482 and is equivalent to the expression $(macro:s/str/sub), with
3483 the restriction that str must match the following regular
3484 expression:
3486 str[ |\t][ |\t]*
3490 Dmake Version 4.12 2008-02-26 49
3496 DMAKE(1) DMAKE(1)
3499 (ie. str only matches at the end of a token where str is a
3500 suffix and is terminated by a space, a tab, or end of line)
3501 Normally sub is expanded before the substitution is made, if
3502 you specify -A on the command line then sub is not expanded.
3504 3. The macro % is defined to be $@ (ie. $% expands to the same
3505 value as $@).
3507 4. The AUGMAKE notion of libraries is handled correctly.
3509 5. Directories are always made if you specify -A. This is con-
3510 sistent with other UNIX versions of Make.
3512 6. Makefiles that utilize virtual targets to force making of
3513 other targets work as expected if AUGMAKE special target han-
3514 dling is enabled. For example:
3516 FRC:
3517 myprog.o : myprog.c $(FRC) ; ...
3519 Works as expected if you issue the command
3521 'dmake -A FRC=FRC'
3523 but fails with a 'don't know how to make FRC' error message
3524 if you do not specify AUGMAKE special target handling via the
3525 -A flag (or by setting AUGMAKE:=yes internally).
3527 LIMITS
3528 In some environments the length of an argument string is restricted.
3529 (e.g. MSDOS command line arguments cannot be longer than 128 bytes if
3530 you are using the standard command.com command interpreter as your
3531 shell, dmake text diversions may help in these situations.)
3533 PORTABILITY
3534 To write makefiles that can be moved from one environment to another
3535 requires some forethought. In particular you must define as macros all
3536 those things that may be different in the new environment. dmake has
3537 two facilities that help to support writing portable makefiles, recur-
3538 sive macros and conditional expressions. The recursive macros, allow
3539 one to define environment configurations that allow different environ-
3540 ments for similar types of operating systems. For example the same
3541 make script can be used for SYSV and BSD but with different macro defi-
3542 nitions.
3544 To write a makefile that is portable between UNIX and MSDOS requires
3545 both features since in almost all cases you will need to define new
3546 recipes for making targets. The recipes will probably be quite differ-
3547 ent since the capabilities of the tools on each machine are different.
3548 Different macros will be needed to help handle the smaller differences
3549 in the two environments.
3551 FILES
3552 Makefile, makefile, startup.mk (use dmake -V to tell you where the
3553 startup file is)
3555 SEE ALSO
3556 sh(1), csh(1), touch(1), f77(1), pc(1), cc(1)
3557 S.I. Feldman Make - A Program for Maintaining Computer Programs
3559 AUTHOR
3560 Dennis Vadura, dvadura@wticorp.com
3561 Many thanks to Carl Seger for his helpful suggestions, and to Trevor
3562 John Thompson for his many excellent ideas and informative bug reports.
3566 Dmake Version 4.12 2008-02-26 50
3572 DMAKE(1) DMAKE(1)
3575 Many thanks also go to those on the NET that have helped in making
3576 dmake one of the best Make tools available.
3578 BUGS
3579 Some system commands return non-zero status inappropriately. Use -i
3580 (`-' within the makefile) to overcome the difficulty.
3582 Some systems do not have easily accessible time stamps for library mem-
3583 bers (MSDOS, AMIGA, etc) for these dmake uses the time stamp of the
3584 library instead and prints a warning the first time it does so. This
3585 is almost always ok, except when multiple makefiles update a single
3586 library file. In these instances it is possible to miss an update if
3587 one is not careful.
3589 This man page is way too long.
3591 WARNINGS
3592 Rules supported by make(1) may not work if transitive closure is turned
3593 off (-T, .NOINFER).
3595 PWD from csh/ksh will cause problems if a cd operation is performed and
3596 -e or -E option is used.
3598 Using internal macros such as COMMAND, may wreak havoc if you don't
3599 understand their functionality.
3642 Dmake Version 4.12 2008-02-26 51