diff options
Diffstat (limited to 'make.texinfo')
| -rw-r--r-- | make.texinfo | 138 |
1 files changed, 122 insertions, 16 deletions
diff --git a/make.texinfo b/make.texinfo index 9b43b48..14b38fc 100644 --- a/make.texinfo +++ b/make.texinfo @@ -25,6 +25,11 @@ @syncodeindex pg cp @ifinfo +@dircategory The GNU make utility +@direntry + * GNU make: (make.info). The GNU make utility. +@end direntry + This file documents the GNU Make utility, which determines automatically which pieces of a large program need to be recompiled, and issues the commands to recompile them. @@ -95,7 +100,7 @@ Cover art by Etienne Suvasa. @page @ifinfo -@node Top, Overview, (dir), (dir) +@node Top, Overview, , (dir) @top Make The GNU @code{make} utility automatically determines which pieces of a @@ -196,6 +201,7 @@ Searching Directories for Dependencies to every dependency. * Selective Search:: Specifying a search path for a specified class of names. +* Search Algorithm:: When and how search paths are applied. * Commands/Search:: How to write shell commands that work together with search paths. * Implicit/Search:: How search paths affect implicit rules. @@ -239,6 +245,8 @@ How to Use Variables * Defining:: An alternate way to set a variable to a verbatim string. * Environment:: Variable values can come from the environment. +* Automatic:: Some special variables have predefined + meanings for use with implicit rules. Advanced Features for Reference to Variables @@ -288,7 +296,7 @@ Using Implicit Rules * Last Resort:: How to defining commands for rules which cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. -* Search Algorithm:: The precise algorithm for applying +* Implicit Rule Search:: The precise algorithm for applying implicit rules. Defining and Redefining Pattern Rules @@ -307,6 +315,7 @@ Using @code{make} to Update Archive Files * Archive Members:: Archive members as targets. * Archive Update:: The implicit rule for archive member targets. +* Archive Pitfalls:: Dangers to watch out for when using archives. * Archive Suffix Rules:: You can write a special kind of suffix rule for updating archives. @@ -1645,6 +1654,7 @@ just the search paths. to every dependency. * Selective Search:: Specifying a search path for a specified class of names. +* Search Algorithm:: When and how search paths are applied. * Commands/Search:: How to write shell commands that work together with search paths. * Implicit/Search:: How search paths affect implicit rules. @@ -1665,10 +1675,10 @@ rules. Thus, if a file that is listed as a target or dependency does not exist in the current directory, @code{make} searches the directories listed in @code{VPATH} for a file with that name. If a file is found in one of -them, that file becomes the dependency. Rules may then specify the -names of source files in the dependencies as if they all existed in the -current directory. @xref{Commands/Search, ,Writing Shell Commands with -Directory Search}. +them, that file may become the dependency (see below). Rules may then +specify the names of source files in the dependencies as if they all +existed in the current directory. @xref{Commands/Search, ,Writing Shell +Commands with Directory Search}. In the @code{VPATH} variable, directory names are separated by colons or blanks. The order in which directories are listed is the order followed @@ -1701,7 +1711,7 @@ foo.o : src/foo.c assuming the file @file{foo.c} does not exist in the current directory but is found in the directory @file{src}. -@node Selective Search, Commands/Search, General Search, Directory Search +@node Selective Search, Search Algorithm, General Search, Directory Search @subsection The @code{vpath} Directive @findex vpath @@ -1800,7 +1810,71 @@ vpath % blish 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 +@node Search Algorithm, Commands/Search, Selective Search, Directory Search +@subsection How Directory Searches are Performed +@cindex algorithm for directory search +@cindex directory search algorithm + +When a dependency is found through directory search, regardless of type +(general or selective), the pathname located may not be the one that +@code{make} actually provides you in the dependency list. Sometimes, +the path discovered through directory search is thrown away. + +The algorithm @code{make} uses to decide whether to keep or abandon a +path found via directory search is as follows: + +@enumerate +@item +If a target file does not exist at the path specified in the makefile, +directory search is performed. + +@item +If the directory search is successful that path is kept, and this file +is tentatively stored as the target. + +@item +All dependencies of this target are examined using this same method. + +@item +After processing the dependencies, the target may or may not need to be +rebuilt: + +@enumerate a +@item +If the target does @emph{not} need to be rebuilt, the path to the file +found during directory search is used for any dependency lists which +contain this target. + +@item +If the target @emph{does} need to be rebuilt (is out-of-date), the +pathname found during directory search is @emph{thrown away}, and the +target is rebuilt using the filename specified in the makefile. +@end enumerate +@end enumerate + +This may seem overly complex, but in fact it is almost always exactly +what you want. + +@cindex traditional directory search +@cindex directory search, traditional +Other versions of @code{make} use a simpler algorithm: if the file does +not exist, and it is found via directory search, then that pathname is +always used whether or not the target needs to be built. Thus, if the +target is rebuilt it is created at the pathname discovered during +directory search. + +@vindex GPATH +If, in fact, this is the behavior you want for some or all of your +directories, you can use the @code{GPATH} variable to indicate this to +@code{make}. + +@code{GPATH} has the same syntax and format as @code{VPATH} (that is, a +space- or colon-delimited list of pathnames). If an out-of-date target +is found by directory search in a directory that also appears in +@code{GPATH}, then that pathname is not thrown away. The target is +rebuilt using the expanded path. + +@node Commands/Search, Implicit/Search, Search Algorithm, Directory Search @subsection Writing Shell Commands with Directory Search @cindex shell command, and directory search @cindex directory search (@code{VPATH}), and shell commands @@ -2112,7 +2186,7 @@ The commands specified for @code{.DEFAULT} are used for any target for 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, +these commands executed on its behalf. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}. @findex .PRECIOUS @@ -2409,6 +2483,8 @@ from the corresponding @file{.c} file: @group objects = foo.o bar.o +all: $(objects) + $(objects): %.o: %.c $(CC) -c $(CFLAGS) $< -o $@@ @end group @@ -2603,7 +2679,8 @@ called @file{@var{name}.d} from a C source file called @file{@var{name}.c}: @group %.d: %.c $(SHELL) -ec '$(CC) -M $(CPPFLAGS) $< \ - | sed '\''s/\($*\)\.o[ :]*/\1 $@@/g'\'' > $@@' + | sed '\''s/\($*\)\.o[ :]*/\1.o $@@ : /g'\'' > $@@; \ + [ -s $@@ ] || rm -f $@@' @end group @end smallexample @@ -5284,8 +5361,8 @@ was given to those two functions.@refill @item $(word @var{n},@var{text}) @findex word -@cindex words, selecting -@cindex selecting words +@cindex word, selecting a +@cindex selecting a word Returns the @var{n}th word of @var{text}. The legitimate values of @var{n} start from 1. If @var{n} is bigger than the number of words in @var{text}, the value is empty. For example, @@ -5297,6 +5374,25 @@ $(word 2, foo bar baz) @noindent returns @samp{bar}. +@item $(wordlist @var{s},@var{e},@var{text}) +@findex wordlist +@cindex words, selecting lists of +@cindex selecting word lists +Returns the list of words in @var{text} starting with word @var{s} and +ending with word @var{e} (inclusive). The legitimate values of @var{s} +and @var{e} start from 1. If @var{s} is bigger than the number of words +in @var{text}, the value is empty. If @var{e} is bigger than the number +of words in @var{text}, words up to the end of @var{text} are returned. +If @var{s} is greater than @var{e}, @code{make} swaps them for you. For +example, + +@example +$(wordlist 2, 3, foo bar baz) +@end example + +@noindent +returns @samp{bar baz}. + @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92 @item $(words @var{text}) @findex words @@ -5656,6 +5752,12 @@ You can specify a different goal or goals with arguments to @code{make}. Use the name of the goal as an argument. If you specify several goals, @code{make} processes each of them in turn, in the order you name them. +@cindex @code{MAKECMDGOALS} +@vindex MAKECMDGOALS +@code{Make} will set the special variable @code{MAKECMDGOALS} to the +list of goals you specified on the command line. If no goals were given +on the command line, this variable is empty. + Any target in the makefile may be specified as a goal (unless it starts with @samp{-} or contains an @samp{=}, in which case it will be parsed as a switch or variable definition, respectively). Even @@ -6312,7 +6414,7 @@ retained for compatibility. * Last Resort:: How to defining commands for rules which cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. -* Search Algorithm:: The precise algorithm for applying +* Implicit Rule Search:: The precise algorithm for applying implicit rules. @end menu @@ -6370,7 +6472,7 @@ result of another implicit rule, we say that @dfn{chaining} is occurring. In general, @code{make} searches for an implicit rule for each target, and for each double-colon rule, that has no commands. A file that is mentioned only as a dependency is considered a target whose rule specifies nothing, -so implicit rule search happens for it. @xref{Search Algorithm, ,Implicit Rule Search Algorithm}, for the +so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the details of how the search is done. Note that explicit dependencies do not influence implicit rule search. @@ -7508,7 +7610,7 @@ Commands, ,Defining Empty Commands}).@refill You can use a last-resort rule to override part of another makefile. @xref{Overriding Makefiles, , Overriding Part of Another Makefile}. -@node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules +@node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules @section Old-Fashioned Suffix Rules @cindex old-fashioned suffix rules @cindex suffix rule @@ -7610,7 +7712,7 @@ before @code{make} reads any makefiles. You can change the list of suffixes with a rule for the special target @code{.SUFFIXES}, but that does not alter this variable. -@node Search Algorithm, , Suffix Rules, Implicit Rules +@node Implicit Rule Search, , Suffix Rules, Implicit Rules @section Implicit Rule Search Algorithm @cindex implicit rule, search algorithm @cindex search algorithm, implicit rule @@ -8160,6 +8262,10 @@ Keep track of the current level of @code{make} recursion using the variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}. @item +Provide any goals given on the command line in the variable +@code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}. + +@item Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}. @item |