diff options
Diffstat (limited to 'doc/make.texi')
| -rw-r--r-- | doc/make.texi | 478 |
1 files changed, 320 insertions, 158 deletions
diff --git a/doc/make.texi b/doc/make.texi index eba92c7..96d0f71 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -10,8 +10,8 @@ @set RCSID $Id$ @set EDITION 0.70 @set VERSION 3.81 -@set UPDATED 29 Jan 2006 -@set UPDATE-MONTH Jan 2006 +@set UPDATED 5 Feb 2006 +@set UPDATE-MONTH Feb 2006 @c ISBN provided by Lisa M. Opus Goldstein <opus@gnu.org>, 5 May 2004 @set ISBN 1-882114-83-5 @@ -39,7 +39,7 @@ This is Edition @value{EDITION}, last updated @value{UPDATED}, of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}. Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, -1998, 1999, 2000, 2002, 2003, 2004, 2005 +1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document @@ -173,8 +173,8 @@ Writing Rules * Directory Search:: Searching other directories for source files. * Phony Targets:: Using a target that is not a real file's name. * Force Targets:: You can use a target without commands - or prerequisites to mark other - targets as phony. + or prerequisites to mark other targets + as phony. * Empty Targets:: When only the date matters and the files are empty. * Special Targets:: Targets with special built-in meanings. @@ -214,6 +214,7 @@ Static Pattern Rules Writing the Commands in Rules +* Command Syntax:: Command syntax features and pitfalls. * Echoing:: How to control when commands are echoed. * Execution:: How commands are executed. * Parallel:: How commands can be executed in parallel. @@ -301,8 +302,8 @@ Using Implicit Rules * Implicit Variables:: How to change what predefined rules do. * Chained Rules:: How to use a chain of implicit rules. * Pattern Rules:: How to define new implicit rules. -* Last Resort:: How to defining commands for rules - which cannot find any. +* Last Resort:: How to define commands for rules which + cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. * Implicit Rule Search:: The precise algorithm for applying implicit rules. @@ -331,15 +332,6 @@ Implicit Rule for Archive Member Targets * Archive Symbols:: How to update archive symbol directories. -Makefile Conventions - -* Makefile Basics:: General Conventions for Makefiles -* Utilities in Makefiles:: Utilities in Makefiles -* Command Variables:: Variables for Specifying Commands -* Directory Variables:: Variables for Installation Directories -* Standard Targets:: Standard Targets for Users -* Install Command Categories:: Three categories of commands in the `install' - @end detailmenu @end menu @@ -1852,8 +1844,8 @@ the makefile (often with a target called @samp{all}). * Directory Search:: Searching other directories for source files. * Phony Targets:: Using a target that is not a real file's name. * Force Targets:: You can use a target without commands - or prerequisites to mark other - targets as phony. + or prerequisites to mark other targets + as phony. * Empty Targets:: When only the date matters and the files are empty. * Special Targets:: Targets with special built-in meanings. @@ -1937,19 +1929,23 @@ target per rule, but occasionally there is a reason to have more The @var{command} lines start with a tab character. The first command may appear on the line after the prerequisites, 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}. +same. There are other differences in the syntax of command lines. +@xref{Commands, ,Writing the Commands in Rules}. @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}). In prerequisite -lists you must actually write @emph{four} dollar signs (@samp{$$$$}), -due to secondary expansion (@pxref{Secondary Expansion}). -You may split a long line by inserting a backslash -followed by a newline, but this is not required, as @code{make} places no -limit on the length of a line in a makefile. +@cindex rules, and @code{$} +Because dollar signs are used to start @code{make} variable +references, if you really want a dollar sign in a target or +prerequisite you must write two of them, @samp{$$} (@pxref{Using +Variables, ,How to Use Variables}). If you have enabled secondary +expansion (@pxref{Secondary Expansion}) and you want a literal dollar +sign in the prerequisites lise, you must actually write @emph{four} +dollar signs (@samp{$$$$}). + +You may split a long line by inserting a backslash followed by a +newline, but this is not required, as @code{make} places no limit on +the length of a line in a makefile. A rule tells @code{make} two things: when the targets are out of date, and how to update them when necessary. @@ -3497,28 +3493,17 @@ object file become the default goal. @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 -command line may be attached to the target-and-prerequisites line with a -semicolon in between. Blank lines and lines of just comments may appear -among the command lines; they are ignored. (But beware, an apparently -``blank'' line that begins with a tab is @emph{not} blank! It is an -empty command; @pxref{Empty Commands}.) +The commands of a rule consist of one or more shell command lines to +be executed, one at a time, in the order they appear. Typically, the +result of executing these commands is that the target of the rule is +brought up to date. 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 @code{#} (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 -the line. The @samp{#} does not have to be at the beginning of a line. -Text on a line before a @samp{#} is not part of the comment. - @menu +* Command Syntax:: Command syntax features and pitfalls. * Echoing:: How to control when commands are echoed. * Execution:: How commands are executed. * Parallel:: How commands can be executed in parallel. @@ -3529,96 +3514,87 @@ Text on a line before a @samp{#} is not part of the comment. * Empty Commands:: Defining useful, do-nothing commands. @end menu -@node Echoing, Execution, Commands, Commands -@section Command Echoing -@cindex echoing of commands -@cindex silent operation -@cindex @code{@@} (in commands) -@cindex commands, 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 -are typing the commands yourself. - -When a line starts with @samp{@@}, the echoing of that line is suppressed. -The @samp{@@} is discarded before the command is passed to the shell. -Typically you would use this for a command whose only effect is to print -something, such as an @code{echo} command to indicate progress through -the makefile: - -@example -@@echo About to make distribution files -@end example +@node Command Syntax, Echoing, Commands, Commands +@section Command Syntax +@cindex command syntax +@cindex syntax of commands + +Makefiles have the unusual property that there are really two distinct +syntaxes in one file. Most of the makefile uses @code{make} syntax +(@pxref{Makefiles, ,Writing Makefiles}). However, commands are meant to be +interpreted by the shell and so they are written using shell syntax. +The @code{make} program does not try to understand shell syntax: it +performs only a very few specific translations on the content of the +command before handing it to the shell. + +Each command line must start with a tab, except that the first command +line may be attached to the target-and-prerequisites line with a +semicolon in between. @emph{Any} line in the makefile that begins +with a tab and appears in a ``rule context'' (that is, after a rule +has been started until another rule or variable definition) will be +considered a command line for that rule. Blank lines and lines of +just comments may appear among the command lines; they are ignored. + +Some consequences of these rules include: -@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} -it only echoes commands, it won't execute them. @xref{Options Summary, -,Summary of Options}. In this case and only this case, even the -commands starting with @samp{@@} are printed. This flag is useful for -finding out which commands @code{make} thinks are necessary without -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 -started with @samp{@@}. A rule in the makefile for the special target -@code{.SILENT} without prerequisites has the same effect -(@pxref{Special Targets, ,Special Built-in Target Names}). -@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill +@itemize @bullet +@item +A blank line that begins with a tab is not blank: it's an empty +command (@pxref{Empty Commands}). -@node Execution, Parallel, Echoing, Commands -@section Command Execution -@cindex commands, execution -@cindex execution, of commands -@cindex shell command, execution -@vindex SHELL @r{(command execution)} +@cindex comments, in commands +@cindex commands, comments in +@cindex @code{#} (comments), in commands +@item +A comment in a command line is not a @code{make} comment; it will be +passed to the shell as-is. Whether the shell treats it as a comment +or not depends on your shell. -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.) +@item +A variable definition in a ``rule context'' which is indented by a tab +as the first character on the line, will be considered a command line, +not a @code{make} variable definition, and passed to the shell. -@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.@footnote{On MS-DOS, the value of current -working directory is @strong{global}, so changing it @emph{will} -affect the following command lines on those systems.} If you want to -use @code{cd} to affect the next command, put them on a single line. -Then @code{make} will consider them a single command and pass them -both to a single shell which will execute them in sequence. For -example: +@item +A conditional expression (@code{ifdef}, @code{ifeq}, +etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule +context'' which is indented by a tab as the first character on the +line, will be considered a command line and be passed to the shell. -@example -foo : bar/lose - cd $(@@D) && gobble $(@@F) > ../$@@ -@end example +@end itemize -@noindent -Here we use the shell AND operator (@code{&&}) so that if the -@code{cd} command fails, the script will fail without trying to invoke -the @code{gobble} command in the wrong directory, which could very -easily cause problems (in this case it would certainly cause -@file{../foo} to be truncated, at least). +@menu +* Splitting Lines:: Breaking long command lines for readability. +* Variables in Commands:: Using @code{make} variables in commands. +@end menu +@node Splitting Lines, Variables in Commands, Command Syntax, Command Syntax +@subsection Splitting Command Lines +@cindex commands, splitting +@cindex splitting commands @cindex commands, backslash (@code{\}) in @cindex commands, quoting newlines in @cindex backslash (@code{\}), in commands @cindex @code{\} (backslash), in commands @cindex quoting newline, in commands @cindex newline, quoting, in commands -A shell command can be split into multiple lines of text by placing a -backslash before each newline. Such a sequence of lines is provided -to the shell as a single command script. The backslash and newline -are preserved in the shell command. If the first character on the -line after a backslash-newline is a tab, the tab will @emph{not} be -included in the shell command. So, this makefile: + +One of the few ways in which @code{make} does interpret command lines +is checking for a backslash just before the newline. As in normal +makefile syntax, a single command can be split into multiple lines in +the makefile by placing a backslash before each newline. A sequence +of lines like this is considered a single command, and one instance of +the shell will be invoked to run it. + +However, in contrast to how they are treated in other places in a +makefile, backslash-newline pairs are @emph{not} removed from the +command. Both the backslash and the newline characters are preserved +and passed to the shell. How the backslash-newline is interpreted +depends on your shell. If the first character of the next line +after the backslash-newline is a tab, then that tab (and only that +tab) is removed. Whitespace is never added to the command. + +For example, this makefile: @example @group @@ -3685,9 +3661,220 @@ quotes (@code{'...'}). This is the way the default shell (@file{/bin/sh}) handles backslash/newline pairs. If you specify a different shell in your makefiles it may treat them differently. +Sometimes you want to split a long line inside of single quotes, but +you don't want the backslash-newline to appear in the quoted content. +This is often the case when passing scripts to languages such as Perl, +where extraneous backslashes inside the script can change its meaning +or even be a syntax error. One simple way of handling this is to +place the quoted string, or even the entire command, into a +@code{make} variable then use the variable in the command. In this +situation the newline quoting rules for makefiles will be used, and +the backslash-newline will be removed. If we rewrite our example +above using this method: + +@example +@group +HELLO = 'hello \ +world' + +all : ; @@echo $(HELLO) +@end group +@end example + +@noindent +we will get output like this: + +@example +@group +hello world +@end group +@end example + +If you like, you can also use target-specific variables +(@pxref{Target-specific, ,Target-specific Variable Values}) to obtain +a tighter correspondence between the variable and the command that +uses it. + +@node Variables in Commands, , Splitting Lines, Command Syntax +@subsection Using Variables in Commands +@cindex variable references in commands +@cindex commands, using variables in + +The other way in which @code{make} processes commands is by expanding +any variable references in them (@pxref{Reference,Basics of Variable +References}). This occurs after make has finished reading all the +makefiles and the target is determined to be out of date; so, the +commands for targets which are not rebuilt are never expanded. + +Variable and function references in commands have identical syntax and +semantics to references elsewhere in the makefile. They also have the +same quoting rules: if you want a dollar sign to appear in your +command, you must double it (@samp{$$}). For shells like the default +shell, that use dollar signs to introduce variables, it's important to +keep clear in your mind whether the variable you want to reference is +a @code{make} variable (use a single dollar sign) or a shell variable +(use two dollar signs). For example: + +@example +@group +LIST = one two three +all: + for i in $(LIST); do \ + echo $$i; \ + done +@end group +@end example + +@noindent +results in the following command being passed to the shell: + +@example +@group +for i in one two three; do \ + echo $i; \ +done +@end group +@end example + +@noindent +which generates the expected result: + +@example +@group +one +two +three +@end group +@end example + +@node Echoing, Execution, Command Syntax, Commands +@section Command Echoing +@cindex echoing of commands +@cindex silent operation +@cindex @code{@@} (in commands) +@cindex commands, 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 +are typing the commands yourself. + +When a line starts with @samp{@@}, the echoing of that line is suppressed. +The @samp{@@} is discarded before the command is passed to the shell. +Typically you would use this for a command whose only effect is to print +something, such as an @code{echo} command to indicate progress through +the makefile: + +@example +@@echo About to make distribution files +@end example + +@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} +it only echoes commands, it won't execute them. @xref{Options Summary, +,Summary of Options}. In this case and only this case, even the +commands starting with @samp{@@} are printed. This flag is useful for +finding out which commands @code{make} thinks are necessary without +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 +started with @samp{@@}. A rule in the makefile for the special target +@code{.SILENT} without prerequisites has the same effect +(@pxref{Special Targets, ,Special Built-in Target Names}). +@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill + +@node Execution, Parallel, Echoing, Commands +@section Command Execution +@cindex commands, execution +@cindex execution, of commands +@cindex shell command, execution +@vindex @code{SHELL} @r{(command execution)} + +When it is time to execute commands to update a target, they are +executed by invoking a new subshell for each command line. (In +practice, @code{make} may take shortcuts that do not affect the +results.) + +@cindex @code{cd} (shell command) +@cindex shell variables, setting in commands +@cindex commands setting shell variables +@strong{Please note:} this implies that setting shell variables and +invoking shell commands such as @code{cd} that set a context local to +each process will not affect the following command lines.@footnote{On +MS-DOS, the value of current working directory is @strong{global}, so +changing it @emph{will} affect the following command lines on those +systems.} If you want to use @code{cd} to affect the next statement, +put both statements in a single command line. Then @code{make} will +invoke one shell to run the entire line, and the shell will execute +the statements in sequence. For example: + +@example +foo : bar/lose + cd $(@@D) && gobble $(@@F) > ../$@@ +@end example + +@noindent +Here we use the shell AND operator (@code{&&}) so that if the +@code{cd} command fails, the script will fail without trying to invoke +the @code{gobble} command in the wrong directory, which could cause +problems (in this case it would certainly cause @file{../foo} to be +truncated, at least). + +@menu +* Choosing the Shell:: How @code{make} chooses the shell used + to run commands. +@end menu + +@node Choosing the Shell, , Execution, Execution +@subsection Choosing the Shell +@cindex shell, choosing the +@cindex @code{SHELL}, value of + @vindex SHELL The program used as the shell is taken from the variable @code{SHELL}. -By default, the program @file{/bin/sh} is used. +If this variable is not set in your makefile, the program +@file{/bin/sh} is used as the shell. + +@cindex environment, @code{SHELL} in +Unlike most variables, the variable @code{SHELL} is never set from the +environment. This is because the @code{SHELL} environment variable is +used to specify your personal choice of shell program for interactive +use. It would be very bad for personal choices like this to affect the +functioning of makefiles. @xref{Environment, ,Variables from the +Environment}. + +Furthermore, when you do set @code{SHELL} in your makefile that value +is @emph{not} exported in the environment to commands that @code{make} +invokes. Instead, the value inherited from the user's environment, if +any, is exported. You can override this behavior by explicitly +exporting @code{SHELL} (@pxref{Variables/Recursion, ,Communicating +Variables to a Sub-@code{make}}), forcing it to be passed in the +environment to commands. + +@vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})} +However, on MS-DOS and MS-Windows the value of @code{SHELL} in the +environment @strong{is} used, since on those systems most users do not +set this variable, and therefore it is most likely set specifically to +be used by @code{make}. On MS-DOS, if the setting of @code{SHELL} is +not suitable for @code{make}, you can set the variable +@code{MAKESHELL} to the shell that @code{make} should use; if set it +will be used as the shell instead of the value of @code{SHELL}. + +@subsubheading Choosing a Shell in DOS and Windows +@cindex shell, in DOS and Windows +@cindex DOS, choosing a shell in +@cindex Windows, choosing a shell in + +Choosing a shell in MS-DOS and MS-Windows is much more complex than on +other systems. @vindex COMSPEC On MS-DOS, if @code{SHELL} is not set, the value of the variable @@ -3741,25 +3928,10 @@ environment or command line, you are expected to set it to the full pathname of the shell, exactly as things are on Unix. The effect of the above DOS-specific processing is that a Makefile that -says @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work +contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some directory along your @code{PATH}. -@cindex environment, @code{SHELL} in -@vindex MAKESHELL @r{(MS-DOS alternative to @code{SHELL})} -Unlike most variables, the variable @code{SHELL} is never set from the -environment. This is because the @code{SHELL} environment variable is -used to specify your personal choice of shell program for interactive -use. It would be very bad for personal choices like this to affect the -functioning of makefiles. @xref{Environment, ,Variables from the -Environment}. However, on MS-DOS and MS-Windows the value of -@code{SHELL} in the environment @strong{is} used, since on those systems -most users do not set this variable, and therefore it is most likely set -specifically to be used by @code{make}. On MS-DOS, if the setting of -@code{SHELL} is not suitable for @code{make}, you can set the variable -@code{MAKESHELL} to the shell that @code{make} should use; this will -override the value of @code{SHELL}. - @node Parallel, Errors, Execution, Commands @section Parallel Execution @cindex commands, execution in parallel @@ -4128,7 +4300,7 @@ The value of the @code{make} variable @code{SHELL} is not exported. Instead, the value of the @code{SHELL} variable from the invoking environment is passed to the sub-@code{make}. You can force @code{make} to export its value for @code{SHELL} by using the -@code{export} directive, described below. +@code{export} directive, described below. @xref{Choosing the Shell}. The special variable @code{MAKEFLAGS} is always exported (unless you unexport it). @code{MAKEFILES} is exported if you set it to anything. @@ -5564,22 +5736,12 @@ different results from the same makefile. This is against the whole purpose of most makefiles. @cindex SHELL, import from environment -Such problems would be especially likely with the variable @code{SHELL}, -which is normally present in the environment to specify the user's choice -of interactive shell. It would be very undesirable for this choice to -affect @code{make}. So @code{make} ignores the environment value of -@code{SHELL} (except on MS-DOS and MS-Windows, where @code{SHELL} is -usually not set. @xref{Execution, ,Special handling of SHELL on -MS-DOS}.)@refill - -@cindex SHELL, export to environment -The @code{SHELL} variable is special in another way: just as the value -of the @code{make} variable @code{SHELL} is not taken from the -environment, so also it is not placed into the environment of commands -that @code{make} invokes. Instead, the value of @code{SHELL} from the -invoking environment is provided to the command. You can use -@code{export SHELL} to force the value of the @code{make} variable -@code{SHELL} to be placed in the environment of commands. +Such problems would be especially likely with the variable +@code{SHELL}, which is normally present in the environment to specify +the user's choice of interactive shell. It would be very undesirable +for this choice to affect @code{make}; so, @code{make} handles the +@code{SHELL} environment variable in a special way; see @ref{Choosing +the Shell}.@refill @node Target-specific, Pattern-specific, Environment, Using Variables @section Target-specific Variable Values @@ -8067,7 +8229,7 @@ retained for compatibility. * Chained Rules:: How to use a chain of implicit rules. * Pattern Rules:: How to define new implicit rules. * Last Resort:: How to define commands for rules which - cannot find any. + cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. * Implicit Rule Search:: The precise algorithm for applying implicit rules. @@ -8491,7 +8653,7 @@ with spaces. The following tables describe of some of the more commonly-used predefined variables. This list is not exhaustive, and the default values shown here may -not be what is selected by @code{make} for your environment. To see the +not be what are selected by @code{make} for your environment. To see the complete list of predefined variables for your instance of GNU @code{make} you can run @samp{make -p} in a directory with no makefiles. @@ -10423,7 +10585,7 @@ The name of the system default command interpreter, usually @file{/bin/sh}. You can set @code{SHELL} in the makefile to change the shell used to run commands. @xref{Execution, ,Command Execution}. The @code{SHELL} variable is handled specially when importing from and exporting to the -environment. @xref{Environment, ,Using Variable from the Environment}. +environment. @xref{Choosing the Shell}. @item MAKESHELL |