diff options
Diffstat (limited to 'make.texinfo')
| -rw-r--r-- | make.texinfo | 192 |
1 files changed, 137 insertions, 55 deletions
diff --git a/make.texinfo b/make.texinfo index cca6a13..d7114bd 100644 --- a/make.texinfo +++ b/make.texinfo @@ -356,9 +356,15 @@ If you are new to @code{make}, or are looking for a general introduction, read the first few sections of each chapter, skipping the later sections. In each chapter, the first few sections contain introductory or general information and the later sections contain -specialized or technical information. The exception is the second -chapter, @ref{Introduction, ,An Introduction to Makefiles}, all of which -is introductory. +specialized or technical information. +@ifinfo +The exception is the second chapter, @ref{Introduction, ,An +Introduction to Makefiles}, all of which is introductory. +@end ifinfo +@iftex +The exception is @ref{Introduction, ,An Introduction to Makefiles}, +all of which is introductory. +@end iftex If you are familiar with other @code{make} programs, see @ref{Features, ,Features of GNU @code{make}}, which lists the enhancements GNU @@ -371,6 +377,9 @@ and @ref{Special Targets}. @node Bugs, , Reading, Overview @section Problems and Bugs +@cindex reporting bugs +@cindex bugs, reporting +@cindex problems and bugs, reporting If you have problems with GNU @code{make} or think you've found a bug, please report it to the developers; we cannot promise to do anything but @@ -447,7 +456,7 @@ whether newly made or saved from previous compilations, must be linked together to produce the new executable editor. @menu -* Parts of Makefiles:: The Parts of a Makefile +* Rule Introduction:: What a rule looks like. * Simple Makefile:: A Simple Makefile * How Make Works:: How @code{make} Processes This Makefile * Variables Simplify:: Variables Make Makefiles Simpler @@ -457,17 +466,18 @@ together to produce the new executable editor. @end menu -@node Parts of Makefiles, Simple Makefile, , Introduction +@node Rule Introduction @comment node-name, next, previous, up -@section The Parts of a Makefile -@cindex parts of a makefile +@section What a Rule Looks Like +@cindex rule, introduction to +@cindex makefile rule parts +@cindex parts of makefile rule A simple makefile consists of ``rules'' with the following shape: -@cindex rule, part of makefile -@cindex target, part of makefile -@cindex dependencies, part of makefile -@cindex command, part of makefile +@cindex targets, introduction to +@cindex dependencies, introduction to +@cindex commands, introduction to @example @group @var{target} @dots{} : @var{dependencies} @dots{} @@ -485,6 +495,7 @@ can also be the name of an action to carry out, such as @samp{clean} A @dfn{dependency} is a file that is used as input to create the target. A target often depends on several files. +@cindex tabs in rules A @dfn{command} is an action that @code{make} carries out. A rule may have more than one command, each on its own line. @strong{Please note:} you need to put a tab character at the beginning of @@ -509,6 +520,8 @@ than shown in this template, but all fit the pattern more or less. @node Simple Makefile, How Make Works, Parts of Makefiles, Introduction @comment node-name, next, previous, up @section A Simple Makefile +@cindex simple makefile +@cindex makefile, simple Here is a straightforward makefile that describes the way an executable file called @code{edit} depends on eight object files @@ -679,9 +692,10 @@ allow a text string to be defined once and substituted in multiple places later (@pxref{Using Variables, ,How to Use Variables}). It is standard practice for every makefile to have a variable named -@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or -@code{OBJ} which is a list of all object file names. We would define -such a variable @code{objects} with a line like this in the makefile:@refill +@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj}, +or @code{OBJ} which is a list of all object file names. We would +define such a variable @code{objects} with a line like this in the +makefile:@refill @example @group @@ -897,12 +911,11 @@ update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. @cindex variable definition @item -A @dfn{variable definition} is a line that specifies a text string value for -a variable that can be substituted into the text later. The -simple makefile example (@pxref{Simple Makefile, , A Simple Makefile}) -shows a variable definition for @code{objects} as a list of all object -files. @xref{Using Variables, ,How to Use Variables}, for full -details. +A @dfn{variable definition} is a line that specifies a text string +value for a variable that can be substituted into the text later. The +simple makefile example shows a variable definition for @code{objects} +as a list of all object files (@pxref{Variables Simplify, , Variables +Make Makefiles Simpler}). @cindex directive @item @@ -1144,6 +1157,7 @@ include one in the other, and add more targets or variable definitions. However, if the two makefiles give different commands for the same target, @code{make} will not let you just do this. But there is another way. +@cindex @code{.DEFAULT}, used to override In the containing makefile (the one that wants to include the other), you can use the @code{.DEFAULT} special target to say that to remake any target that cannot be made from the information in the containing @@ -1287,6 +1301,8 @@ 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 @samp{$} in rules 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}). @@ -1314,7 +1330,8 @@ executed by the shell (normally @samp{sh}), but with some extra features @node Wildcards, Directory Search, Rule Syntax, Rules @section Using Wildcard Characters in File Names @cindex wildcard -@cindex file name +@cindex file name with wildcards +@cindex globbing (wildcards) @cindex * (wildcard character) @cindex ? (wildcard character) @@ -1359,8 +1376,10 @@ Wildcards can be used in the commands of a rule, where they are expanded by the shell. For example, here is a rule to delete all the object files: @example +@group clean: rm -f *.o +@end group @end example Wildcards are also useful in the dependencies of a rule. With the @@ -1401,6 +1420,11 @@ objects := $(wildcard *.o) @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards @subsection Pitfalls of Using Wildcards +@cindex wildcard pitfalls +@cindex pitfalls of wildcards +@cindex mistakes with wildcards +@cindex errors with wildcards +@cindex problems with wildcards Now here is an example of a naive way of using wildcard expansion, that does not do what you would intend. Suppose you would like to say that the @@ -1490,15 +1514,16 @@ there is no need to write explicit rules for compiling the files. @section Searching Directories for Dependencies @vindex VPATH @findex vpath -@cindex vpath -@cindex search path for dependencies -@cindex directory search +@cindex vpath +@cindex search path for dependencies (VPATH) +@cindex directory search (VPATH) For large systems, it is often desirable to put sources in a separate directory from the binaries. The @dfn{directory search} features of -@code{make} facilitate this by searching several directories automatically -to find a dependency. When you redistribute the files among directories, -you do not need to change the individual rules, just the search paths. +@code{make} facilitate this by searching several directories +automatically to find a dependency. When you redistribute the files +among directories, you do not need to change the individual rules, +just the search paths. @menu * General Search:: Specifying a search path that applies @@ -1692,6 +1717,9 @@ foo.o : foo.c defs.h hack.h @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search @subsection Directory Search and Implicit Rules +@cindex directory search (VPATH) and implicit rules +@cindex search in directories (VPATH) with implicit rules +@cindex implicit rules with directory search (VPATH) The search through the directories specified in @code{VPATH} or with @code{vpath} happens also during consideration of implicit rules @@ -1710,9 +1738,11 @@ directory search with no extra effort. @node Libraries/Search, , Implicit/Search, Directory Search @subsection Directory Search for Link Libraries -@cindex link libraries, directory search -@cindex libraries for linking, directory search -@cindex directory search, link libraries +@cindex link libraries, directory search (VPATH) +@cindex libraries for linking, directory search (VPATH) +@cindex directory search (VPATH), link libraries +@cindex search in directories (VPATH), link libraries +@cindex -l (library search) Directory search applies in a special way to libraries used with the linker. This special feature comes into play when you write a dependency @@ -1730,8 +1760,10 @@ search path.@refill For example, @example +@group foo : foo.c -lcurses cc $^ -o $@@ +@end group @end example @noindent @@ -1742,6 +1774,7 @@ be executed when @file{foo} is older than @file{foo.c} or than @node Phony Targets, Force Targets, Directory Search, Rules @section Phony Targets @cindex phony targets +@cindex targets, phony A phony target is one that is not really the name of a file. It is just a name for some commands to be executed when you make an explicit request. @@ -1753,8 +1786,10 @@ commands will be executed every time the target comes up for remaking. Here is an example: @example +@group clean: rm *.o temp +@end group @end example @noindent @@ -1767,7 +1802,7 @@ The phony target will cease to work if anything ever does create a file named @file{clean} in this directory. Since it has no dependencies, the file @file{clean} would inevitably be considered up to date, and its commands would not be executed. To avoid this problem, you can explicitly -declare the target to be phony, using the special target @code{.PHONY} +declare the target to be phony, using the special target @code{.PHONY (@pxref{Special Targets, ,Special Built-in Target Names}) as follows: @example @@ -1912,6 +1947,7 @@ changed (@pxref{Automatic, ,Automatic Variables}). Certain names have special meanings if they appear as targets. @table @code +@findex .PHONY special target @item .PHONY The dependencies of the special target @code{.PHONY} are considered to @@ -1920,12 +1956,14 @@ be phony targets. When it is time to consider such a target, whether a file with that name exists or what its last-modification time is. @xref{Phony Targets, ,Phony Targets}. +@findex .SUFFIXES special target @item .SUFFIXES The dependencies of the special target @code{.SUFFIXES} are the list of suffixes to be used in checking for suffix rules. @xref{Suffix Rules, , Old-Fashioned Suffix Rules}. +@findex .DEFAULT special target @item .DEFAULT The commands specified for @code{.DEFAULT} are used for any target for @@ -1935,6 +1973,7 @@ 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 special target @item .PRECIOUS @cindex precious targets @@ -1943,6 +1982,7 @@ treatment: if @code{make} is killed or interrupted during the execution of their commands, the target is not deleted. @xref{Interrupts, ,Interrupting or Killing @code{make}}. +@findex .IGNORE special target @item .IGNORE Simply by being mentioned as a target, @code{.IGNORE} says to ignore @@ -1954,6 +1994,7 @@ errors in execution of commands. The dependencies and commands for useful; we recommend you use the more selective ways to ignore errors in specific commands. @xref{Errors, ,Errors in Commands}. +@findex .SILENT special target @item .SILENT Simply by being mentioned as a target, @code{.SILENT} says not to @@ -1964,13 +2005,15 @@ for @code{.SILENT} are not meaningful. use the more selective ways to silence specific commands. @xref{Echoing, ,Command Echoing}. If you want to silence all commands for a particular run of @code{make}, use the @samp{-s} or -@samp{--silent} option (@pxref{Options Summary}). +@w{@samp{--silent}} option (@pxref{Options Summary}). +@findex .EXPORT_ALL_VARIABLES special target @item .EXPORT_ALL_VARIABLES -Simply by being mentioned as a target, @code{.EXPORT_ALL_VARIABLES} -tells @code{make} to export all variables to child processes by default. -@xref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}. +Simply by being mentioned as a target, this tells @code{make} to +export all variables to child processes by default. +@xref{Variables/Recursion, ,Communicating Variables to a +Sub-@code{make}}. @end table Any defined implicit rule suffix also counts as a special target if it @@ -1986,6 +2029,7 @@ both pieces to the suffix list. In practice, suffixes normally begin with @section Multiple Targets in a Rule @cindex multiple targets @cindex targets, multiple +@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 @@ -2043,8 +2087,13 @@ You cannot do this with multiple targets in an ordinary rule, but you can do it with a @dfn{static pattern rule}. @xref{Static Pattern, ,Static Pattern Rules}. @end ifinfo + + @node Multiple Rules, Double-Colon, Static Pattern, Rules @section Multiple Rules for One Target +@cindex multiple rules for one target +@cindex rules, multiple for one target +@cindex target, multiple rules One file can be the target of several rules. All the dependencies mentioned in all the rules are merged into one list of dependencies for @@ -2100,6 +2149,8 @@ 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 pattern rules, static (not implicit) @cindex varying dependencies @dfn{Static pattern rules} are rules which specify multiple targets and @@ -2238,7 +2289,10 @@ to precisely the targets specified. @node Double-Colon, , Multiple Rules, Rules @section Double-Colon Rules -@cindex double-colon rule +@cindex double-colon rules +@cindex rules, double-colon +@cindex multiple, independent rules for one target +@cindex @samp{::} rules (double-colon) @dfn{Double-colon} rules are rules written with @samp{::} instead of @samp{:} after the target names. They are handled differently from @@ -2270,6 +2324,8 @@ implicit rule will be used if one applies. @node Commands, Using Variables, Rules, Top @chapter Writing the Commands in Rules @cindex commands +@cindex rule commands +@cindex writing rule commands The commands of a rule consist of shell command lines to be executed one by one. Each command line must start with a tab, except that the first @@ -2281,6 +2337,9 @@ Users use many different shell programs, but commands in makefiles are always interpreted by @file{/bin/sh} unless the makefile specifies otherwise. @xref{Execution, ,Command Execution}. +@cindex comments in commands +@cindex commands, comments in +@cindex @samp{#} (comments) in commands The shell that is in use determines whether comments can be written on command lines, and what syntax they use. When the shell is @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of @@ -2304,6 +2363,7 @@ Text on a line before a @samp{#} is not part of the comment. @cindex silent operation @cindex @@ (in commands) @cindex command echoing +@cindex printing of commands Normally @code{make} prints each command line before it is executed. We call this @dfn{echoing} because it gives the appearance that you @@ -2342,7 +2402,8 @@ started with @samp{@@}. A rule in the makefile for the special target @section Command Execution @cindex command execution @cindex execution of commands -@cindex shell +@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 @@ -2388,12 +2449,12 @@ Environment}. @node Parallel, Errors, Execution, Commands @section Parallel Execution - @cindex parallel execution @cindex execution in parallel @cindex job slots @cindex @code{-j} @cindex @code{--jobs} + GNU @code{make} knows how to execute several commands at once. Normally, @code{make} will execute only one command at a time, waiting for it to finish before executing the next. However, the @samp{-j} or @@ -2441,6 +2502,11 @@ option was not given terminates for any reason (including a signal) with child processes running, it waits for them to finish before actually exiting.@refill +@cindex load average +@cindex limiting jobs based on load +@cindex @code{-l} (load average) +@cindex @code{--max-load} +@cindex @code{--load-average} When the system is heavily loaded, you will probably want to run fewer jobs than when it is lightly loaded. You can use the @samp{-l} option to tell @code{make} to limit the number of jobs to run at once, based on the load @@ -2466,8 +2532,10 @@ By default, there is no load limit. @node Errors, Interrupts, Parallel, Commands @section Errors in Commands - @cindex error (in commands) +@cindex command errors +@cindex exit status (errors) + After each shell command returns, @code{make} looks at its exit status. If the command completed successfully, the next command line is executed in a new shell; after the last command line is finished, the rule is @@ -2489,8 +2557,10 @@ the command is passed to the shell for execution. For example, @example +@group clean: -rm -f *.o +@end group @end example @noindent @@ -2629,7 +2699,7 @@ sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill As a special feature, using the variable @code{MAKE} in the commands of a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n} -(@samp{--just-print}), or @samp{-q} (@samp{--question}) +(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option. Using the @code{MAKE} variable has the same effect as using a @samp{+} character at the beginning of the command line. @xref{Instead of Execution, ,Instead of Executing the @@ -2677,7 +2747,7 @@ Environment}. Except by explicit request, @code{make} exports a variable only if it is either defined in the environment initially or set on the command -line, and if its name consists only of letters, numbers and underscores. +line, and if its name consists only of letters, numbers, and underscores. Some shells cannot cope with environment variable names consisting of characters other than letters, numbers, and underscores. @@ -2875,10 +2945,10 @@ probably annoying effects.@refill @cindex directories, printing them If you use several levels of recursive @code{make} invocations, the -@samp{-w} or @samp{--print-directory} option can make the output a lot -easier to understand by showing each directory as @code{make} starts -processing it and as @code{make} finishes processing it. For example, -if @samp{make -w} is run in the directory @file{/u/gnu/make}, +@samp{-w} or @w{@samp{--print-directory}} option can make the output a +lot easier to understand by showing each directory as @code{make} +starts processing it and as @code{make} finishes processing it. For +example, if @samp{make -w} is run in the directory @file{/u/gnu/make}, @code{make} will print a line of the form:@refill @example @@ -2990,12 +3060,12 @@ commands may not be run if the target file actually does exist. A @dfn{variable} is a name defined in a makefile to represent a string of text, called the variable's @dfn{value}. These values are -substituted by explicit request into targets, dependencies, commands +substituted by explicit request into targets, dependencies, commands, and other parts of the makefile. Variables and functions in all parts of a makefile are expanded when read, except for the shell commands in rules, the right-hand sides of -variable definitions using @samp{=} and the bodies of variable +variable definitions using @samp{=}, and the bodies of variable definitions using the @code{define} directive.@refill Variables can represent lists of file names, options to pass to compilers, @@ -3004,7 +3074,7 @@ write output in, or anything else you can imagine. A variable name may be any sequence of characters not containing @samp{:}, @samp{#}, @samp{=}, or leading or trailing whitespace. However, -variable names containing characters other than letters, numbers and +variable names containing characters other than letters, numbers, and underscores should be avoided, as they may be given special meanings in the future, and with some shells they cannot be passed through the environment to a sub-@code{make} @@ -3039,24 +3109,28 @@ special significance of @samp{$} is why you must write @samp{$$} to have the effect of a single dollar sign in a file name or command. Variable references can be used in any context: targets, dependencies, -commands, most directives, and new variable values. Here is a common kind -of example, where a variable holds the names of all the object files in a -program: +commands, most directives, and new variable values. Here is an +example of a common case, where a variable holds the names of all the +object files in a program: @example +@group objects = program.o foo.o utils.o program : $(objects) cc -o program $(objects) $(objects) : defs.h +@end group @end example Variable references work by strict textual substitution. Thus, the rule @example +@group foo = c prog.o : prog.c $(foo)$(foo) -$(foo) prog.c +@end group @end example @noindent @@ -3463,7 +3537,8 @@ with an assignment (@pxref{Setting, ,Setting Variables}) or with a verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill @item -Values are inherited from the environment. @xref{Environment, ,Variables from the Environment}. +Variables in the environment become @code{make} variables. +@xref{Environment, ,Variables from the Environment}. @item Several @dfn{automatic} variables are given new values for each rule. @@ -3981,6 +4056,7 @@ substitute those variables where such characters are wanted, like this: @example @group comma:= , +empty:= space:= $(empty) $(empty) foo:= a b c bar:= $(subst $(space),$(comma),$(foo)) @@ -4059,6 +4135,7 @@ is equivalent to $(patsubst %@var{pattern},@var{replacement},$(@var{var}) @end example +and @example $(@var{var}:@var{suffix}=@var{replacement}) @@ -4115,8 +4192,9 @@ produce the values @samp{a} and @samp{} (the empty string), respectively. @xref{Testing Flags}, for a practical application of @code{findstring}.@refill -@item $(filter @var{pattern}@dots{},@var{text}) +@need 750 @findex filter +@item $(filter @var{pattern}@dots{},@var{text}) Removes all whitespace-separated words in @var{text} that do @emph{not} match any of the @var{pattern} words, returning only matching words. The patterns are written using @samp{%}, just like @@ -4295,6 +4373,7 @@ $(basename src/foo.c hacks) @noindent produces the result @samp{src/foo hacks}. +@c !!! plural convention with dots (be consistent) @item $(addsuffix @var{suffix},@var{names}@dots{}) @findex addsuffix The argument @var{names} is regarded as a series of names, separated @@ -5379,7 +5458,7 @@ is made from @file{@var{n}.mod}; the form is: @need 1200 @item Assembling and preprocessing assembler programs @file{@var{n}.o} is made automatically from @file{@var{n}.s} by -running the assembler, @code{as}. The precise command used is +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 @@ -5824,7 +5903,7 @@ exist or can be made. These files become dependencies of the target. Thus, a rule of the form @example -%.o : %.c +%.o : %.c ; @var{command}@dots{} @end example @noindent @@ -6257,6 +6336,9 @@ pattern rule or @code{.DEFAULT}, but you also do not want any commands to be run for the target, you can give it empty commands (@pxref{Empty 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 @section Old-Fashioned Suffix Rules @cindex old-fashioned suffix rules |