diff options
| -rw-r--r-- | make.texinfo | 513 |
1 files changed, 330 insertions, 183 deletions
diff --git a/make.texinfo b/make.texinfo index a2c7173..80a14ba 100644 --- a/make.texinfo +++ b/make.texinfo @@ -15,8 +15,16 @@ @c Combine the variable and function indices: @synindex vr fn -@c Combine the program and function indices: -@synindex pg fn +@c Combine the program and concept indices: +@synindex pg cp + +@tex +% trying for a two-level index +\def\doindex#1{\message{FNORD!!!}\edef\indexname{#1}\parsearg\singleindexer} +\def\singleindexer #1{\message{frobozzing :{#1}:}\message{}\frobozz{#1}} +\def\frobozz[#1,#2]{\message{frobozzed :{#1}:{#2}:}\message{}\dosubind{\indexname}{#1}{#2}} + +@end tex @ifinfo This file documents the GNU Make utility, which determines @@ -419,7 +427,7 @@ Please include the version number of @code{make} you are using. You can get this information with the command @samp{make --version -f /dev/null}. Be sure also to include the type of machine and operating system you are using. If possible, include the contents of the file @file{config.h} -that is generated by the configuration process.@c !!! make this real +that is generated by the configuration process. Non-bug suggestions are always welcome as well. If you have questions about things that are unclear in the documentation or are just obscure @@ -572,6 +580,11 @@ clean : @noindent We split each long line into two lines using a backslash-newline; this is like using one long line, but is easier to read. +@cindex continuation lines +@cindex @code{\} (backslash), for continuation lines +@cindex backslash (@code{\}), for continuation lines +@cindex quoting newline, in makefile +@cindex newline, quoting, in makefile To use this makefile to create the executable file called @file{edit}, type: @@ -622,7 +635,7 @@ Targets}, for information about this kind of target. @xref{Errors, , Errors in Commands}, to see how to cause @code{make} to ignore errors from @code{rm}. @cindex @code{clean} target -@pindex rm @r{(shell command)} +@cindex @code{rm} (shell command) @node How Make Works, Variables Simplify, Simple Makefile, Introduction @comment node-name, next, previous, up @@ -924,16 +937,16 @@ and @dfn{comments}. Rules, variables, and directives are described at length in later chapters.@refill @itemize @bullet -@cindex rule, explicit (definition of) -@cindex explicit rule (definition of) +@cindex rule, explicit, definition of +@cindex explicit rule, definition of @item An @dfn{explicit rule} says when and how to remake one or more files, called the rule's targets. It lists the other files that the targets @dfn{depend on}, and may also give commands to use to create or update the targets. @xref{Rules, ,Writing Rules}. -@cindex rule, implicit (definition of) -@cindex implicit rule (definition of) +@cindex rule, implicit, definition of +@cindex implicit rule, definition of @item An @dfn{implicit rule} says when and how to remake a class of files based on their names. It describes how a target may depend on a file @@ -980,18 +993,18 @@ perhaps spaces before it) is effectively blank, and is ignored.@refill @node Makefile Names, Include, Makefile Contents, Makefiles @section What Name to Give Your Makefile -@cindex makefile names -@cindex names of makefiles -@cindex default makefile names -@cindex file names of makefiles +@cindex makefile name +@cindex name of makefile +@cindex default makefile name +@cindex file name of makefile @c following paragraph rewritten to avoid overfull hbox By default, when @code{make} looks for the makefile, it tries the following names, in order: @file{GNUmakefile}, @file{makefile} and @file{Makefile}.@refill -@pindex Makefile -@pindex GNUmakefile -@pindex makefile +@findex Makefile +@findex GNUmakefile +@findex makefile @cindex @code{README} Normally you should call your makefile either @file{makefile} or @@ -1024,12 +1037,12 @@ specify @samp{-f} or @samp{--file}.@refill @cindex specifying makefile name @cindex makefile name, how to specify @cindex name of makefile, how to specify -@cindex file names of makefiles, how to specify +@cindex file name of makefile, how to specify @node Include, MAKEFILES Variable, Makefile Names, Makefiles @section Including Other Makefiles @cindex including other makefiles -@cindex makefiles, including +@cindex makefile, including @findex include The @code{include} directive tells @code{make} to suspend reading the @@ -1044,7 +1057,7 @@ include @var{filenames}@dots{} @var{filenames} can contain shell file name patterns. @cindex shell file name pattern (in @code{include}) @cindex shell wildcards (in @code{include}) -@cindex wildcards (in @code{include}) +@cindex wildcard, in @code{include} Extra spaces are allowed and ignored at the beginning of the line, but a tab is not allowed. (If the line begins with a tab, it will be @@ -1089,24 +1102,27 @@ makefile as has been traditionally done with other versions of @cindex dependencies, automatic generation @cindex @code{-I} +@cindex @code{--include-dir} If the specified name does not start with a slash, and the file is not found in the current directory, several other directories are searched. -First, any directories you have specified with the @samp{-I} option are -searched -(@pxref{Options Summary, ,Summary of Options}). -Then the following directories (if they -exist) are searched, in this order: @file{/usr/gnu/include}, -@file{/usr/local/include}, @file{/usr/include}. -If an included makefile cannot be found in any of these directories, a -warning message is generated, but it is not a fatal error; processing -of the makefile containing the @code{include} continues.@refill -@pindex /usr/gnu/include -@pindex /usr/local/include -@pindex /usr/include +First, any directories you have specified with the @samp{-I} or +@samp{--include-dir} option are searched +(@pxref{Options Summary, ,Summary of Options}). +Then the following directories (if they exist) +are searched, in this order: +@file{@var{prefix}/include} (normally @file{/usr/local/include}) +@file{/usr/gnu/include}, +@file{/usr/local/include}, @file{/usr/include}. If an included makefile +cannot be found in any of these directories, a warning message is +generated, but it is not a fatal error; processing of the makefile +containing the @code{include} continues.@refill +@findex /usr/gnu/include +@findex /usr/local/include +@findex /usr/include @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles @section The Variable @code{MAKEFILES} -@cindex makefiles (@code{MAKEFILES} variable) +@cindex makefile, and @code{MAKEFILES} variable @cindex including (@code{MAKEFILES} variable) @vindex MAKEFILES @@ -1139,7 +1155,7 @@ in the makefiles. @xref{Include, , Including Other Makefiles}. @cindex updating makefiles @cindex remaking makefiles -@cindex makefiles, remaking of +@cindex makefile, remaking of Sometimes makefiles can be remade from other files, such as RCS or SCCS files. If a makefile can be remade from other files, you probably want @code{make} to get an up-to-date version of the makefile to read in. @@ -1166,10 +1182,10 @@ else. So, to avoid this, @code{make} will @strong{not} attempt to remake makefiles which are specified as double-colon targets but have no dependencies.@refill -If you do not specify any makefiles to be read with @samp{-f} options, -@code{make} will try the default makefile names; -@pxref{Makefile Names, ,What Name to Give Your Makefile}. -Unlike makefiles explicitly requested with @samp{-f} options, +If you do not specify any makefiles to be read with @samp{-f} or +@samp{--file} options, @code{make} will try the default makefile names; +@pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike +makefiles explicitly requested with @samp{-f} or @samp{--file} options, @code{make} is not certain that these makefiles should exist. However, if a default makefile does not exist but can be created by running @code{make} rules, you probably want the rules to be run so that the @@ -1211,7 +1227,7 @@ specified by the existing contents of @file{mfile}. @section Overriding Part of Another Makefile @cindex overriding makefiles -@cindex makefiles, overriding +@cindex makefile, overriding Sometimes it is useful to have a makefile that is mostly just like another makefile. You can often use the @samp{include} directive to include one in the other, and add more targets or variable definitions. @@ -1368,9 +1384,9 @@ appear on the line after the dependencies, with a tab character, or may appear on the same line, with a semicolon. Either way, the effect is the same. @xref{Commands, ,Writing the Commands in Rules}. -@cindex dollar signs in rules -@cindex @code{$} in rules -@cindex rules, and @code{$} +@cindex dollar sign (@code{$}) in rules +@cindex @code{$}, in rules +@cindex rule, and @code{$} Because dollar signs are used to start variable references, if you really want a dollar sign in a rule you must write two of them, @samp{$$} (@pxref{Using Variables, ,How to Use Variables}). @@ -1403,9 +1419,9 @@ executed by the shell (normally @samp{sh}), but with some extra features @cindex file name with wildcards @cindex globbing (wildcards) -@cindex * (wildcard character) -@cindex ? (wildcard character) -@cindex [@dots{}] (wildcard characters) +@cindex @code{*} (wildcard character) +@cindex @code{?} (wildcard character) +@cindex @code{[@dots{}]} (wildcard characters) A single file name can specify many files using @dfn{wildcard characters}. The wildcard characters in @code{make} are @samp{*}, @samp{?} and @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} @@ -1451,7 +1467,7 @@ clean: rm -f *.o @end group @end example -@pindex rm @r{(shell command)} +@cindex @code{rm} (shell command) Wildcards are also useful in the dependencies of a rule. With the following rule in the makefile, @samp{make print} will print all the @@ -1464,8 +1480,8 @@ print: *.c @end example @cindex @code{print} target -@pindex lpr @r{(shell command)} -@pindex touch @r{(shell command)} +@cindex @code{lpr} (shell command) +@cindex @code{touch} (shell command) @noindent This rule uses @file{print} as an empty target file; see @ref{Empty Targets, ,Empty Target Files to Record Events}. (The automatic variable @@ -1589,6 +1605,7 @@ there is no need to write explicit rules for compiling the files. @vindex VPATH @findex vpath @cindex vpath +@c !!! s/search path/search path for dependencies (@code{VPATH})/ @cindex search path for dependencies (@code{VPATH}) @cindex directory search (@code{VPATH}) @@ -1681,36 +1698,6 @@ The search path, @var{directories}, is a colon-separated list of directories to be searched, just like the search path used in the @code{VPATH} variable. -@code{make} handles multiple @code{vpath} directives in the order in -which they appear in the makefile; multiple directives with the same -pattern are independent of each other. - -@need 750 -Thus, - -@example -@group -vpath %.c foo -vpath % blish -vpath %.c bar -@end group -@end example - -@noindent -will look for a file ending in @samp{.c} in @file{foo}, then -@file{blish}, then @file{bar}, while - -@example -@group -vpath %.c foo:bar -vpath % blish -@end group -@end example - -@noindent -will look for a file ending in @samp{.c} in @file{foo}, then -@file{bar}, then @file{blish}. - @item vpath @var{pattern} Clear out the search path associated with @var{pattern}. @@ -1728,6 +1715,11 @@ Redefining Pattern Rules}). For example, @code{%.h} matches files that end in @code{.h}. (If there is no @samp{%}, the pattern must match the dependency exactly, which is not useful very often.) +@cindex @code{%}, quoting in @code{vpath} +@cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in @code{vpath} @samp{%} characters in a @code{vpath} directive's pattern can be quoted with preceding backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. @@ -1753,12 +1745,41 @@ directory. If several @code{vpath} patterns match the dependency file's name, then @code{make} processes each matching @code{vpath} directive one by one, -searching all the directories mentioned in each directive. The @code{vpath} -directives are processed in the order in which they appear in the makefiles. +searching all the directories mentioned in each directive. @code{make} +handles multiple @code{vpath} directives in the order in which they +appear in the makefile; multiple directives with the same pattern are +independent of each other. + +@need 750 +Thus, + +@example +@group +vpath %.c foo +vpath % blish +vpath %.c bar +@end group +@end example + +@noindent +will look for a file ending in @samp{.c} in @file{foo}, then +@file{blish}, then @file{bar}, while + +@example +@group +vpath %.c foo:bar +vpath % blish +@end group +@end example + +@noindent +will look for a file ending in @samp{.c} in @file{foo}, then +@file{bar}, then @file{blish}. @node Commands/Search, Implicit/Search, Selective Search, Directory Search @subsection Writing Shell Commands with Directory Search -@cindex shell commands, and directory search +@cindex shell command, and directory search +@c !!! s/directory search/& (VPATH)/ @cindex directory search, and shell commands When a dependency is found in another directory through directory search, @@ -1780,7 +1801,7 @@ foo.o : foo.c @noindent (The variable @code{CFLAGS} exists so you can specify flags for C -compilation by implicit rule; we use it here for consistency so it will +compilation by implicit rules; we use it here for consistency so it will affect all C compilations uniformly; @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) @@ -1799,8 +1820,10 @@ foo.o : foo.c defs.h hack.h @cindex @code{VPATH}, and implicit rules @cindex directory search, and implicit rules @cindex search path, and implicit rules -@cindex implicit rules, and directory search -@cindex implicit rules, and @code{VPATH} +@cindex implicit rule, and directory search +@cindex implicit rule, and @code{VPATH} +@cindex rule, implicit, and directory search +@cindex rule, implicit, and @code{VPATH} The search through the directories specified in @code{VPATH} or with @code{vpath} happens also during consideration of implicit rules @@ -1835,9 +1858,10 @@ file, and the @emph{file name} of the library looks like When a dependency's name has the form @samp{-l@var{name}}, @code{make} handles it specially by searching for the file @file{lib@var{name}.a} in -the directories @file{/lib}, @file{/usr/lib}, and @file{/usr/local/lib}, -and then using matching @code{vpath} search paths and the @code{VPATH} -search path.@refill +the current directory, in directories specified by matching @code{vpath} +search paths and the @code{VPATH} search path, and then in the +directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib} +(normally @file{/usr/local/lib}). For example, @@ -1879,7 +1903,7 @@ clean: Because the @code{rm} command does not create a file named @file{clean}, probably no such file will ever exist. Therefore, the @code{rm} command will be executed every time you say @samp{make clean}. -@pindex rm @r{(shell command)} +@cindex @code{rm} (shell command) @findex .PHONY The phony target will cease to work if anything ever does create a file @@ -1927,7 +1951,6 @@ makefile @file{./Makefile}. Since the target remade by default will be the first one in the makefile, it is common to make this a phony target named @samp{all} and give it, as dependencies, all the individual programs. For example: -@cindex @code{all} @example all : prog1 prog2 prog3 @@ -1952,6 +1975,8 @@ of the other. For example, here @samp{make cleanall} will delete the object files, the difference files, and the file @file{program}: @example +.PHONY: cleanall cleanobj cleandiff + cleanall : cleanobj cleandiff rm program @@ -1967,7 +1992,7 @@ cleandiff : @cindex force targets @cindex targets, force @cindex @code{FORCE} -@cindex rules, no commands or dependencies +@cindex rule, no commands or dependencies If a rule has no dependencies or commands, and the target of the rule is a nonexistent file, then @code{make} imagines this target to have @@ -2023,8 +2048,8 @@ print: foo.c bar.c touch print @end example @cindex @code{print} target -@pindex lpr @r{(shell command)} -@pindex touch @r{(shell command)} +@cindex @code{lpr} (shell command) +@cindex @code{touch} (shell command) @noindent With this rule, @samp{make print} will execute the @code{lpr} command if @@ -2061,15 +2086,16 @@ of suffixes to be used in checking for suffix rules. @item .DEFAULT The commands specified for @code{.DEFAULT} are used for any target for -which no rules are found (either explicit rules or implicit rules). If -@code{.DEFAULT} commands are specified, every file mentioned as a -dependency, but not as a target in a rule, will have these commands -executed on its behalf. @xref{Search Algorithm, ,Implicit Rule Search -Algorithm}. +which no rules are found (either explicit rules or implicit rules). +@xref{Last Resort}. If @code{.DEFAULT} commands are specified, every +file mentioned as a dependency, but not as a target in a rule, will have +these commands executed on its behalf. @xref{Search Algorithm, +,Implicit Rule Search Algorithm}. @findex .PRECIOUS @item .PRECIOUS @cindex precious targets +@cindex preserving with @code{.PRECIOUS} The targets which @code{.PRECIOUS} depends on are given this special treatment: if @code{make} is killed or interrupted during the @@ -2124,7 +2150,7 @@ both pieces to the suffix list. In practice, suffixes normally begin with @cindex multiple targets @cindex several targets in a rule @cindex targets, multiple -@cindex rules, with multiple targets +@cindex rule, with multiple targets A rule with multiple targets is equivalent to writing many rules, each with one target, and all identical aside from that. The same commands apply to @@ -2173,7 +2199,9 @@ littleoutput : text.g @noindent Here we assume the hypothetical program @code{generate} makes two types of output, one if given @samp{-big} and one if given -@samp{-little}.@refill +@samp{-little}. +@xref{Text Functions, ,Functions for String Substitution and Analysis}, +for an explanation of the @code{subst} function. @end itemize Suppose you would like to vary the dependencies according to the target, @@ -2186,7 +2214,7 @@ do it with a @dfn{static pattern rule}. @section Multiple Rules for One Target @cindex multiple rules for one target @cindex several rules for one target -@cindex rules, multiple for one target +@cindex rule, multiple for one target @cindex target, multiple rules for one One file can be the target of several rules. All the dependencies @@ -2242,11 +2270,11 @@ searches for an applicable implicit rule to find some commands @node Static Pattern, Multiple Rules, Multiple Targets, Rules @section Static Pattern Rules -@cindex static pattern rules -@cindex rules, static pattern +@cindex static pattern rule +@cindex rule, static pattern @cindex pattern rules, static (not implicit) @cindex varying dependencies -@cindex dependencies, varying +@cindex dependencies, varying (static pattern) @dfn{Static pattern rules} are rules which specify multiple targets and construct the dependency names for each target based on the target name. @@ -2278,6 +2306,8 @@ The targets can contain wildcard characters, just like the targets of ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File Names}). +@cindex target pattern, static (not implicit) +@cindex stem The @var{target-pattern} and @var{dep-patterns} say how to compute the dependencies of each target. Each target is matched against the @var{target-pattern} to extract a part of the target name, called the @@ -2291,6 +2321,7 @@ pattern must match exactly. For example, the target @file{foo.o} matches the pattern @samp{%.o}, with @samp{foo} as the stem. The targets @file{foo.c} and @file{foo.out} do not match that pattern.@refill +@cindex dependency pattern, static (not implicit) The dependency names for each target are made by substituting the stem for the @samp{%} in each dependency pattern. For example, if one dependency pattern is @file{%.c}, then substitution of the stem @@ -2298,10 +2329,11 @@ dependency pattern is @file{%.c}, then substitution of the stem to write a dependency pattern that does not contain @samp{%}; then this dependency is the same for all targets. -@cindex backslash (@code{\}), to quote @code{%} -@cindex @code{\} (backslash), to quote @code{%} -@cindex quoting @code{%} with @code{\} +@cindex @code{%}, quoting in static pattern @cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in static pattern @samp{%} characters in pattern rules can be quoted with preceding backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. Backslashes that quote @@ -2343,7 +2375,6 @@ $(filter %.o,$(files)): %.o: %.c $(filter %.elc,$(files)): %.elc: %.el emacs -f batch-byte-compile $< @end example -@pindex emacs @noindent Here the result of @samp{$(filter %.o,$(files))} is @file{bar.o lose.o}, @@ -2352,10 +2383,24 @@ be updated by compiling the corresponding C source file. The result of @w{@samp{$(filter %.elc,$(files))}} is @file{foo.elc}, so that file is made from @file{foo.el}.@refill +Another example shows how to use @code{$*} in static pattern rules: +@vindex $*@r{, and static pattern} + +@example +@group +bigoutput littleoutput : %output : text.g + generate text.g -$* > $@@ +@end group +@end example + +@noindent +When the @code{generate} command is run, @code{$*} will expand to the +stem, either @samp{big} or @samp{little}. + @node Static versus Implicit, , Static Usage, Static Pattern @subsection Static Pattern Rules versus Implicit Rules -@cindex rules, static pattern versus implicit -@cindex static pattern rules, versus implicit +@cindex rule, static pattern versus implicit +@cindex static pattern rule, versus implicit A static pattern rule has much in common with an implicit rule defined as a pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}). @@ -2395,7 +2440,7 @@ to precisely the targets specified. @node Double-Colon, , Multiple Rules, Rules @section Double-Colon Rules @cindex double-colon rules -@cindex rules, double-colon (@code{::}) +@cindex rule, double-colon (@code{::}) @cindex multiple rules for one target (@code{::}) @cindex @code{::} rules (double-colon) @@ -2467,7 +2512,7 @@ Text on a line before a @samp{#} is not part of the comment. @cindex echoing of commands @cindex silent operation @cindex @code{@@} (in commands) -@cindex command echoing +@cindex commands, echoing @cindex printing of commands Normally @code{make} prints each command line before it is executed. @@ -2486,6 +2531,8 @@ the makefile: @cindex @code{-n} @cindex @code{--just-print} +@cindex @code{--dry-run} +@cindex @code{--recon} When @code{make} is given the flag @samp{-n} or @samp{--just-print}, echoing is all that happens, no execution. @xref{Options Summary, ,Summary of Options}. In this case and only this case, even the @@ -2495,6 +2542,7 @@ actually doing them. @cindex @code{-s} @cindex @code{--silent} +@cindex @code{--quiet} @findex .SILENT The @samp{-s} or @samp{--silent} flag to @code{make} prevents all echoing, as if all commands @@ -2505,16 +2553,16 @@ started with @samp{@@}. A rule in the makefile for the special target @node Execution, Parallel, Echoing, Commands @section Command Execution -@cindex command execution -@cindex execution of commands -@cindex shell command execution +@cindex commands, execution +@cindex execution, of commands +@cindex shell command, execution @vindex SHELL @r{(command execution)} When it is time to execute commands to update a target, they are executed by making a new subshell for each line. (In practice, @code{make} may take shortcuts that do not affect the results.) -@pindex cd @r{(shell command)} +@cindex @code{cd} (shell command) @strong{Please note:} this implies that shell commands such as @code{cd} that set variables local to each process will not affect the following command lines. If you want to use @code{cd} to affect the @@ -2532,7 +2580,8 @@ foo : bar/lose @cindex commands, quoting newlines in @cindex backslash (@code{\}), in commands @cindex @code{\} (backslash), in commands -@cindex quoting newlines in commands +@cindex quoting newline, in commands +@cindex newline, quoting, in commands If you would like to split a single shell command into multiple lines of text, you must use a backslash at the end of all but the last subline. Such a sequence of lines is combined into a single line, by deleting the @@ -2563,7 +2612,7 @@ Environment}. @section Parallel Execution @cindex commands, execution in parallel @cindex parallel execution -@cindex execution in parallel +@cindex execution, in parallel @cindex job slots @cindex @code{-j} @cindex @code{--jobs} @@ -2678,7 +2727,7 @@ clean: -rm -f *.o @end group @end example -@pindex rm @r{(shell command)} +@cindex @code{rm} (shell command) @noindent This causes @code{rm} to continue even if it is unable to remove a file. @@ -2729,7 +2778,7 @@ default. @cindex interrupt @cindex signal @cindex deletion of target files -@cindex targets, deleting on interrupt +@cindex target, deleting on interrupt @cindex killing (interruption) If @code{make} gets a fatal signal while a command is executing, it may @@ -2783,11 +2832,14 @@ subsystem: $(MAKE) -C subdir @end example @cindex @code{-C} +@cindex @code{--directory} You can write recursive @code{make} commands just by copying this example, but there are many things to know about how they work and why, and about how the sub-@code{make} relates to the top-level @code{make}. +@c !!! example of many subdirs + many subdir targets + @menu * MAKE Variable:: The special effects of using @samp{$(MAKE)}. * Variables/Recursion:: How to communicate variables to a sub-@code{make}. @@ -2816,7 +2868,7 @@ invoked. If this file name was @file{/bin/make}, then the command executed is @samp{cd subdir; /bin/make}. If you use a special version of @code{make} to run the top-level makefile, the same special version will be executed for recursive invocations. -@pindex cd @r{(shell command)} +@cindex @code{cd} (shell command) Also, any arguments that define variable values are added to @code{MAKE}, so the sub-@code{make} gets them too. Thus, if you do @samp{make @@ -2839,7 +2891,8 @@ really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would require executing the command, and @samp{-t} says not to execute commands.@refill @cindex @code{-t}, and recursion -@cindex recursion, and @code{-t} +@cindex recursion, and @code{-t} +@cindex @code{--touch}, and recursion The special feature makes this do what you want: whenever a command line of a rule contains the variable @code{MAKE}, the flags @samp{-t}, @@ -3012,20 +3065,29 @@ processes them as if they had been given as arguments. @xref{Options Summary, ,Summary of Options}. @cindex @code{-C}, and recursion -@cindex recursion, and @code{-C} @cindex @code{-f}, and recursion -@cindex recursion, and @code{-f} @cindex @code{-I}, and recursion -@cindex recursion, and @code{-I} @cindex @code{-o}, and recursion -@cindex recursion, and @code{-o} @cindex @code{-W}, and recursion +@cindex @code{--directory}, and recursion +@cindex @code{--file}, and recursion +@cindex @code{--include-dir}, and recursion +@cindex @code{--old-file}, and recursion +@cindex @code{--assume-old}, and recursion +@cindex @code{--assume-new}, and recursion +@cindex @code{--new-file}, and recursion +@cindex recursion, and @code{-C} +@cindex recursion, and @code{-f} +@cindex recursion, and @code{-I} +@cindex recursion, and @code{-o} @cindex recursion, and @code{-W} The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W} are not put into @code{MAKEFLAGS}; these options are not passed down.@refill @cindex @code{-j}, and recursion +@cindex @code{--jobs}, and recursion @cindex recursion, and @code{-j} +@cindex job slots, and recursion The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}). If you set it to some numeric value, @samp{-j 1} is always put into @@ -3114,9 +3176,12 @@ make: Leaving directory `/u/gnu/make'. when processing is completed. @cindex @code{-C}, and @code{-w} +@cindex @code{--directory}, and @code{--print-directory} @cindex recursion, and @code{-w} @cindex @code{-w}, and @code{-C} @cindex @code{-w}, and recursion +@cindex @code{--print-directory}, and @code{--directory} +@cindex @code{--print-directory}, and recursion Normally, you do not need to specify this option because @samp{make} does it for you: @samp{-w} is turned on automatically when you use the @samp{-C} option, and in sub-@code{make}s (unless you also use @@ -3141,7 +3206,7 @@ yacc $(firstword $^) mv y.tab.c $@@ endef @end example -@pindex yacc +@cindex @code{yacc} @noindent Here @code{run-yacc} is the name of the variable being defined; @@ -3204,10 +3269,10 @@ from getting implicit commands (from implicit rules or the @code{.DEFAULT} special target; @pxref{Implicit Rules} and @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill -You may be inclined to define empty command strings for targets that -are not actual files, but only exist so that their dependencies can be -remade. However, this is not the best way to do that, because its -commands may not be run if the target file actually does exist. +You may be inclined to define empty command strings for targets that are +not actual files, but only exist so that their dependencies can be +remade. However, this is not the best way to do that, because the +dependencies may not be remade properly if the target file actually does exist. @xref{Phony Targets, ,Phony Targets}, for a better way to do this. @node Using Variables, Conditionals, Commands, Top @@ -3262,8 +3327,8 @@ command options (@pxref{Overriding, ,Overriding Variables}). @section Basics of Variable References @cindex variables, how to reference @cindex reference to variables -@cindex @code{$} (variables) -@cindex dollar sign (@code{$}), and variables +@cindex @code{$}, in variable reference +@cindex dollar sign (@code{$}), in variable reference To substitute a variable's value, write a dollar sign followed by the name of the variable in parentheses or braces: either @samp{$(foo)} or @@ -3291,8 +3356,8 @@ Variable references work by strict textual substitution. Thus, the rule @example @group foo = c -prog.o : prog.c - $(foo)$(foo) -$(foo) prog.c +prog.o : prog.$(foo) + $(foo)$(foo) -$(foo) prog.$(foo) @end group @end example @@ -3538,8 +3603,8 @@ sets @samp{bar} to @samp{a.c b.c c.c}. @cindex variables, computed names @cindex variables, nested references @cindex variables, @samp{$} in name -@cindex @code{$} in variable name -@cindex dollar sign (@code{$}) in variable name +@cindex @code{$}, in variable name +@cindex dollar sign (@code{$}), in variable name Computed variable names are a complicated concept needed only for sophisticated makefile programming. For most purposes you need not @@ -3701,6 +3766,21 @@ as the argument to either the @code{sort} or the @code{strip} function. This restriction could be removed in the future if that change is shown to be a good idea. +You can also use computed variable names in the left-hand side of a +variable assignment, or in a @code{define} directive, as in: + +@example +dir = foo +$(dir)_sources := $(wildcard $(dir)/*.c) +define $(dir)_print +lpr $($(dir)_sources) +endef +@end example + +@noindent +This example defines the variables @samp{dir}, @samp{foo_sources}, and +@samp{foo_print}. + Note that @dfn{nested variable references} are quite different from @dfn{recursively expanded variables} (@pxref{Flavors, ,The Two Flavors of Variables}), though both are @@ -3709,7 +3789,7 @@ used together in complex ways when doing makefile programming.@refill @node Values, Setting, Advanced, Using Variables @section How Variables Get Their Values @cindex variables, how they get their values -@cindex values, how variables get them +@cindex value, how a variable gets it Variables can get values in several different ways: @@ -3760,6 +3840,9 @@ Variables defined with @samp{:=} are @dfn{simply expanded} variables; these definitions can contain variable references which will be expanded before the definition is made. @xref{Flavors, ,The Two Flavors of Variables}. +The variable name may contain function and variable references, which +are expanded when the line is read to find the actual variable name to use. + There is no limit on the length of the value of a variable except the amount of swapping space on the computer. When a variable definition is long, it is a good idea to break it into several lines by inserting @@ -3779,7 +3862,7 @@ automatically to a new value for each rule; these are called the @section The @code{override} Directive @findex override @cindex overriding with @code{override} -@cindex variables, overriding +@cindex variable, overriding If a variable has been set with a command argument (@pxref{Overriding, ,Overriding Variables}), then ordinary assignments in the makefile are ignored. If you want to set @@ -3833,7 +3916,7 @@ See the next section for information about @code{define}. @findex endef @cindex verbatim variable definition @cindex defining variables verbatim -@cindex variables, defining verbatim +@cindex variable, defining verbatim Another way to set the value of a variable is to use the @code{define} directive. This directive has an unusual syntax which allows newline @@ -3847,6 +3930,9 @@ following lines. The end of the value is marked by a line containing just the word @code{endef}. Aside from this difference in syntax, @code{define} works just like @samp{=}: it creates a recursively-expanded variable (@pxref{Flavors, ,The Two Flavors of Variables}). +The variable name may contain function and variable references, which +are expanded when the directive is read to find the actual variable name +to use. @example define two-lines @@ -3886,7 +3972,7 @@ endef @node Environment, , Defining, Using Variables @section Variables from the Environment -@cindex variables, environment +@cindex variable, environment @cindex environment Variables in @code{make} can come from the environment in which @code{make} is run. Every environment variable that @code{make} sees when @@ -4109,8 +4195,33 @@ empty value. Note that @code{ifdef} only tests whether a variable has a value. It does not expand the variable to see if that value is nonempty. Consequently, tests using @code{ifdef} return true for all definitions -except those like @code{foo =}. To test for an empty value, use -@w{@code{ifeq ($(foo),)}}. +except those like @code{foo =}. To test for an empty value, use +@w{@code{ifeq ($(foo),)}}. For example, + +@example +bar = +foo = $(bar) +ifdef foo +frobozz = yes +else +frobozz = no +endif +@end example + +@noindent +sets @samp{frobozz} to @samp{yes}, while: + +@example +foo = +ifdef foo +frobozz = yes +else +frobozz = no +endif +@end example + +@noindent +sets @samp{frobozz} to @samp{no}. @item ifndef @var{variable-name} If the variable @var{variable-name} has an empty value, the @@ -4203,7 +4314,8 @@ call, just as a variable might be substituted. @node Syntax of Functions, Text Functions, , Functions @section Function Call Syntax -@cindex @code{$} (function call) +@cindex @code{$}, in function call +@cindex dollar sign (@code{$}), in function call @cindex arguments of functions @cindex functions, syntax of @@ -4291,10 +4403,11 @@ matching any number of any characters within a word. If @var{replacement} also contains a @samp{%}, the @samp{%} is replaced by the text that matched the @samp{%} in @var{pattern}.@refill -@cindex backslash (@code{\}), to quote @samp{%} -@cindex @code{\} (backslash), to quote @samp{%} -@cindex quoting @code{%} in @code{patsubst} @cindex @code{%}, quoting in @code{patsubst} +@cindex @code{%}, quoting with @code{\} (backslash) +@cindex @code{\} (backslash), to quote @code{%} +@cindex backslash (@code{\}), to quote @code{%} +@cindex quoting @code{%}, in @code{patsubst} @samp{%} characters in @code{patsubst} function invocations can be quoted with preceding backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%} characters can be quoted with more backslashes. @@ -4714,7 +4827,7 @@ produces the result @samp{foo}. Although @code{$(firstword @item $(wildcard @var{pattern}) @findex wildcard -@cindex wildcards, function +@cindex wildcard, function The argument @var{pattern} is a file name pattern, typically containing wildcard characters (as in shell file name patterns). The result of @code{wildcard} is a space-separated list of the names of existing files @@ -4813,7 +4926,7 @@ no?), but it is more likely to be a mistake. @node Origin Function, Shell Function, Foreach Function, Functions @section The @code{origin} Function @findex origin -@cindex variables, origin of +@cindex variable, origin of @cindex origin of variable The @code{origin} function is unlike most other functions in that it does @@ -4922,9 +5035,9 @@ Here the redefinition takes place if @samp{$(origin bletch)} returns either @node Shell Function, , Origin Function, Functions @section The @code{shell} Function @findex shell -@cindex command expansion +@cindex commands, expansion @cindex backquotes -@cindex shell commands, function for +@cindex shell command, function for The @code{shell} function is unlike any other function except the @code{wildcard} function @@ -4997,11 +5110,12 @@ things or many others. @node Makefile Arguments, Goals, , Running @section Arguments to Specify the Makefile @cindex @code{--file} -@cindex @code{--f} +@cindex @code{--makefile} +@cindex @code{-f} The way to specify the name of the makefile is with the @samp{-f} or -@samp{--file} option. For example, @samp{-f altmake} says to use the -file @file{altmake} as the makefile. +@samp{--file} option (@samp{--makefile} also works). For example, +@samp{-f altmake} says to use the file @file{altmake} as the makefile. If you use the @samp{-f} flag several times and follow each @samp{-f} with an argument, all the specified files are used jointly as @@ -5136,7 +5250,11 @@ what you want. Certain options specify other activities for @code{make}. @table @samp @item -n @itemx --just-print +@itemx --dry-run +@itemx --recon @cindex @code{--just-print} +@cindex @code{--dry-run} +@cindex @code{--recon} @cindex @code{-n} ``No-op''. The activity is to print what commands would be used to make the targets up to date, but not actually execute them. @@ -5145,7 +5263,7 @@ the targets up to date, but not actually execute them. @itemx --touch @cindex @code{--touch} @cindex touching files -@cindex targets, touching +@cindex target, touching @cindex @code{-t} ``Touch''. The activity is to mark the targets as up to date without actually changing them. In other words, @code{make} pretends to compile @@ -5162,8 +5280,12 @@ words, neither compilation nor output will occur. @item -W @itemx --what-if +@itemx --assume-new +@itemx --new-file @cindex @code{--what-if} @cindex @code{-W} +@cindex @code{--assume-new} +@cindex @code{--new-file} @cindex what if @cindex files, assuming new ``What if''. Each @samp{-W} flag is followed by a file name. The given @@ -5219,6 +5341,7 @@ information about @code{make} or about the makefiles in use @section Avoiding Recompilation of Some Files @cindex @code{-o} @cindex @code{--old-file} +@cindex @code{--assume-old} @cindex files, assuming old @cindex files, avoiding recompilation of @cindex recompilation, avoiding @@ -5271,9 +5394,9 @@ Touch all the object files with @samp{make -t}. @node Overriding, Testing, Avoiding Compilation, Running @section Overriding Variables @cindex overriding variables with arguments -@cindex variables, overriding with arguments +@cindex variable, overriding with arguments @cindex command line variables -@cindex variables, command line +@cindex variable, command line An argument that contains @samp{=} specifies the value of a variable: @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}. @@ -5392,6 +5515,8 @@ This is typically used with recursive invocations of @code{make} @cindex @code{-d} @itemx --debug @cindex @code{--debug} +@c Extra blank line here makes the table look better. + Print debugging information in addition to normal processing. The debugging information says which files are being considered for remaking, which file-times are being compared and with what results, @@ -5420,6 +5545,8 @@ Read the file named @var{file} as a makefile. @cindex @code{-h} @itemx --help @cindex @code{--help} +@c Extra blank line here makes the table look better. + Remind you of the options that @code{make} understands and then exit. @item -i @@ -5476,6 +5603,8 @@ limit. @xref{Parallel, ,Parallel Execution}. @cindex @code{--dry-run} @itemx --recon @cindex @code{--recon} +@c Extra blank line here makes the table look better. + Print the commands that would be executed, but do not execute them. @xref{Instead of Execution, ,Instead of Executing the Commands}. @@ -5528,6 +5657,8 @@ Rules}). But you can still define your own suffixes with a rule for @cindex @code{--silent} @itemx --quiet @cindex @code{--quiet} +@c Extra blank line here makes the table look better. + Silent operation; do not print the commands as they are executed. @xref{Echoing, ,Command Echoing}. @@ -5537,6 +5668,8 @@ Silent operation; do not print the commands as they are executed. @cindex @code{--no-keep-going} @itemx --stop @cindex @code{--stop} +@c Extra blank line here makes the table look better. + Cancel the effect of the @samp{-k} option. This is never necessary except in a recursive @code{make} where @samp{-k} might be inherited from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion, ,Recursive Use of @code{make}}) @@ -5546,6 +5679,8 @@ or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill @cindex @code{-t} @itemx --touch @cindex @code{--touch} +@c Extra blank line here makes the table look better. + Touch files (mark them up to date without really changing them) instead of running their commands. This is used to pretend that the commands were done, in order to fool future invocations of @@ -5576,8 +5711,8 @@ see @ref{-w Option, ,The @samp{--print-directory} Option}.) @cindex @code{-W} @itemx --what-if @var{file} @cindex @code{--what-if} -@itemx --new @var{file} -@cindex @code{--new} +@itemx --new-file @var{file} +@cindex @code{--new-file} @itemx --assume-new @var{file} @cindex @code{--assume-new} Pretend that the target @var{file} has just been modified. When used @@ -5765,8 +5900,8 @@ a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill @cindex C++, rule to compile @pindex g++ @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or -@file{@var{n}.C} with a command of the form @samp{$(C++) -c $(CPPFLAGS) -$(C++FLAGS)}. We encourage you to use the suffix @samp{.cc} for C++ +@file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS) +$(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill @item Compiling Pascal programs @@ -5822,7 +5957,7 @@ running the assembler, @code{as}. The precise command is @samp{$(AS) $(ASFLAGS)}.@refill @file{@var{n}.s} is made automatically from @file{@var{n}.S} by -running the C preprocessor, @code{cpp}. The precise command used is +running the C preprocessor, @code{cpp}. The precise command is @w{@samp{$(CPP) $(CPPFLAGS)}}. @item Linking a single object file @@ -6039,8 +6174,8 @@ Program for doing assembly; default @samp{as}. Program for compiling C programs; default @samp{cc}. @pindex cc -@item C++ -@vindex C++ +@item CXX +@vindex CXX Program for compiling C++ programs; default @samp{g++}. @pindex g++ @@ -6148,8 +6283,8 @@ invoked on a @samp{.s} or @samp{.S} file). @vindex CFLAGS Extra flags to give to the C compiler. -@item C++FLAGS -@vindex C++FLAGS +@item CXXFLAGS +@vindex CXXFLAGS Extra flags to give to the C++ compiler. @item COFLAGS @@ -6195,7 +6330,7 @@ Extra flags to give to Yacc. @section Chains of Implicit Rules @cindex chains of rules -@cindex rules, implicit, chains of +@cindex rule, implicit, chains of Sometimes a file can be made by a sequence of implicit rules. For example, a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. @@ -6230,7 +6365,7 @@ see @ref{Interrupts}.)@refill @cindex intermediate files, preserving @cindex preserving intermediate files @cindex preserving with .PRECIOUS -@cindex @code{.PRECIOUS} files +@cindex @code{.PRECIOUS} intermediate files A chain can involve more than two implicit rules. For example, it is possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, @@ -6291,7 +6426,7 @@ A pattern rule contains the character @samp{%} (exactly one of them) in the target; otherwise, it looks exactly like an ordinary rule. The target is a pattern for matching file names; the @samp{%} matches any nonempty substring, while other characters match only themselves. -@cindex target pattern +@cindex target pattern, implicit @cindex @code{%}, in pattern rules For example, @samp{%.c} as a pattern matches any file name that ends in @@ -6305,7 +6440,7 @@ that was matched by the @samp{%} in the target. In order for the pattern rule to apply, its target pattern must match the file name under consideration, and its dependency patterns must name files that exist or can be made. These files become dependencies of the target. -@cindex dependency pattern +@cindex dependency pattern, implicit Thus, a rule of the form @@ -6338,7 +6473,7 @@ than the one that matches the target in need of a rule are incidental: presently in question. However, when this file's commands are run, the other targets are marked as having been updated themselves. @cindex multiple targets, in pattern rule -@cindex targets, multiple in pattern rule +@cindex target, multiple in pattern rule The order in which pattern rules appear in the makefile is important because the rules are considered in that order. Of equally applicable @@ -6409,8 +6544,8 @@ dependencies, and it will execute happily ever after.)@refill @node Automatic, Pattern Match, Pattern Examples, Pattern Rules @subsection Automatic Variables @cindex automatic variables -@cindex variables, automatic -@cindex variables, and implicit rules +@cindex variable, automatic +@cindex variable, and implicit rule Suppose you are writing a pattern rule to compile a @samp{.c} file into a @samp{.o} file: how do you write the @samp{cc} command so that it operates @@ -6765,6 +6900,7 @@ You can use a last-resort rule to override part of another makefile. @node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules @section Old-Fashioned Suffix Rules @cindex old-fashioned suffix rules +@cindex suffix rule @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for @code{make}. Suffix rules are obsolete because pattern rules are more @@ -6865,7 +7001,7 @@ this variable. @node Search Algorithm, , Suffix Rules, Implicit Rules @section Implicit Rule Search Algorithm -@cindex implicit rule search algorithm +@cindex implicit rule, search algorithm @cindex search algorithm, implicit rule Here is the procedure @code{make} uses for searching for an implicit rule @@ -6976,7 +7112,8 @@ main use is as subroutine libraries for linking. @menu * Archive Members:: Archive members as targets. * Archive Update:: The implicit rule for archive member targets. -* !!! :: the .X.a kludge +* Archive Suffix Rules:: You can write a special kind of suffix rule + for updating archives. @end menu @node Archive Members, Archive Update, , Archives @@ -7026,7 +7163,7 @@ into the archive. For example, it will update the archive member target archive @file{foo.a} as a @emph{member} named @file{bar.o}. When this rule is chained with others, the result is very powerful. -Thus, @samp{make "foo.a(bar.o)"} (the quotes are need to protect the +Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the @samp{(} and @samp{)} from being interpreted specially by the shell) in the presence of a file @file{bar.c} is enough to cause the following commands to be run, even without a makefile: @@ -7062,6 +7199,10 @@ named @file{foo.o}. In connection with such usage, the automatic variables * Archive Symbols:: How to update archive symbol directories. @end menu +@node Archive Suffix Rules +@subsection +@c !!! new section here for .X.a + @node Archive Symbols, , , Archive Update @subsection Updating Archive Symbol Directories @cindex __.SYMDEF @@ -7102,10 +7243,14 @@ updates the @file{__.SYMDEF} member automatically. @node Features, Missing, Archives, Top @chapter Features of GNU @code{make} @cindex features of GNU @code{make} +@cindex portability +@cindex compatibility Here is a summary of the features of GNU @code{make}, for comparison -with and credit to other versions of @code{make}. We consider the features -of @code{make} in 4.2 BSD systems as a baseline. +with and credit to other versions of @code{make}. We consider the +features of @code{make} in 4.2 BSD systems as a baseline. If you are +concerned with writing portable makefiles, you should use only the +features of @code{make} @emph{not} listed here or in @ref{Missing}. Many features come from the version of @code{make} in System V. @@ -7119,6 +7264,8 @@ It is documented in 4.3 BSD @code{make} (which says it mimics System V's @item Included makefiles. @xref{Include, ,Including Other Makefiles}. +Allowing multiple files to be included with a single directive is a GNU +extension. @item Variables are read from and communicated via the environment. @@ -7323,7 +7470,7 @@ Various new built-in implicit rules. @cindex features, missing The @code{make} programs in various other systems support a few features -that are not implemented in GNU @code{make}. Draft 11.1 of the POSIX.2 +that are not implemented in GNU @code{make}. Draft 11.2 of the POSIX.2 standard which specifies @code{make} does not require any of these features.@refill @@ -7413,8 +7560,9 @@ using EFL, we will gladly add them. This appendix summarizes the directives, text manipulation functions, and special variables which GNU @code{make} understands. -@xref{Special Targets}, and @ref{Catalogue of Rules, ,Catalogue of -Implicit Rules}, for other summaries. +@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules}, +and @ref{Options Summary, ,Summary of Options}. +for other summaries. Here is a summary of the directives GNU @code{make} recognizes: @@ -7690,9 +7838,8 @@ a makefile to set flags.@* The default list of suffixes before @code{make} reads any makefiles. @end table -@c !!! this is a pretty lame example --roland @node Complex Makefile, Concept Index, Quick Reference, Top -@appendix A Complex Makefile Example +@appendix Complex Makefile Example Here is the makefile for the GNU @code{tar} program. This is a moderately complex makefile. @@ -7870,12 +8017,12 @@ all: tar rmt tar.info @group tar: $(OBJS) - $(CC) $(LDFLAGS) -o $@ $(OBJS) $(LIBS) + $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) @end group @group rmt: rmt.c - $(CC) $(CFLAGS) $(LDFLAGS) -o $@ rmt.c + $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c @end group @group @@ -7903,7 +8050,7 @@ testpad.h: testpad @group testpad: testpad.o - $(CC) -o $@ testpad.o + $(CC) -o $@@ testpad.o @end group @group |