summaryrefslogtreecommitdiff
path: root/make.texinfo
diff options
context:
space:
mode:
Diffstat (limited to 'make.texinfo')
-rw-r--r--make.texinfo138
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