diff options
| -rw-r--r-- | make.texinfo | 132 |
1 files changed, 73 insertions, 59 deletions
diff --git a/make.texinfo b/make.texinfo index 43a1eb4..0ddf8fc 100644 --- a/make.texinfo +++ b/make.texinfo @@ -19,7 +19,7 @@ automatically which pieces of a large program need to be recompiled, and issues the commands to recompile them. @c !!set edition, date, version -This is Edition 0.33 Beta, last updated 6 July 1992, +This is Edition 0.33 Beta, last updated 16 July 1992, of @cite{The GNU Make Manual}, for @code{make}, Version 3.63 Beta. Copyright (C) 1988, 1989, 1990, 1991, 1992 Free Software Foundation, Inc. @@ -54,7 +54,7 @@ by the Foundation. @title GNU Make @subtitle A Program for Directing Recompilation @subtitle Edition 0.33 Beta, for @code{make} Version 3.63 Beta. -@subtitle June 1992 +@subtitle July 1992 @author by Richard M. Stallman and Roland McGrath @page @vskip 0pt plus 1filll @@ -94,12 +94,13 @@ large program need to be recompiled, and issues the commands to recompile them.@refill This is Edition 0.33 Beta of the @cite{GNU Make Manual}, -last updated 12 June 1992, +last updated 16 July 1992 for @code{make} Version 3.63 Beta.@refill This manual describes @code{make} and contains the following chapters:@refill @end ifinfo +@c !!! Edit descriptions. @menu * Copying:: GNU GENERAL PUBLIC LICENSE * Overview:: Introducing @code{make}. @@ -1079,7 +1080,7 @@ without running them. The commands for @file{foo} will be those specified by the existing contents of @file{mfile}. @node Overriding Makefiles, , Remaking Makefiles, Makefiles -@section Overriding Part of One Makefile with Another Makefile +@section Overriding Part of Another Makefile @cindex overriding makefiles Sometimes it is useful to have a makefile that is mostly just like @@ -1648,6 +1649,8 @@ will repeat the appropriate search when it processes this argument.@refill 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. +There are two reasons to use a phony target: to avoid a conflict with +file of the same name, and to improve performance. If you write a rule whose commands will not create the target file, the commands will be executed every time the target comes up for remaking. @@ -1663,9 +1666,6 @@ 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}. -@c !!!! want to mention that using .PHONY is a performance win because -@c implicit rule serach is not done for phony targets --roland - @findex .PHONY 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 @@ -1682,6 +1682,12 @@ declare the target to be phony, using the special target @code{.PHONY} Once this is done, @samp{make clean} will run the commands regardless of whether there is a file named @file{clean}. +Since @code{make} knows that phony targets do not name actual files +that could be remade from other files, @code{make} skips the implicit +rule search for phony targets (@pxref{Implicit}). This is why +declaring a target phony is good for performance, even if you are not +worried about the actual file existing. + Thus, you first write the line that states that @code{clean} is a phony target, then you write the rule, like this: @@ -3439,12 +3445,14 @@ because you know that no makefile will use them for other things. (But this is not totally reliable; some makefiles set @code{CFLAGS} explicitly and therefore are not affected by the value in the environment.) -@c !!!! this is completely wrong --roland -When @code{make} is invoked recursively, variables defined in the outer -invocation are automatically passed to inner invocations through the -environment (@pxref{Recursion, ,Recursive Use of @code{make}}). This is the main purpose of turning -environment variables into @code{make} variables, and it requires no -attention from you.@refill +When @code{make} is invoked recursively, variables defined in the +outer invocation can be passed to inner invocations through the +environment (@pxref{Recursion, ,Recursive Use of @code{make}}). By +default, only variables that came from the environment or the command +line are passed to recursive invocations. You can use the +@code{export} directive to pass other variables. +@xref{Variables/Recursion, , Communicating Variables to a +Sub-@code{make}}, for full details. Other use of variables from the environment is not recommended. It is not wise for makefiles to depend for their functioning on environment variables @@ -3515,11 +3523,11 @@ is not used. It is optional to have an @code{else} in a conditional. The @code{endif} directive ends the conditional. Every conditional must end with an @code{endif}. Unconditional makefile text follows. -@c !!!! this is repeated below --roland -Conditionals work at the textual level: the lines of the conditional are -treated as part of the makefile, or ignored, according to the condition. -This is why the larger syntactic units of the makefile, such as rules, may -cross the beginning or the end of the conditional. +As this example illustrates, conditionals work at the textual level: +the lines of the conditional are treated as part of the makefile, or +ignored, according to the condition. This is why the larger syntactic +units of the makefile, such as rules, may cross the beginning or the +end of the conditional. When the variable @code{CC} has the value @samp{gcc}, the above example has this effect: @@ -3664,12 +3672,17 @@ arguments. Extra spaces are allowed and ignored at the beginning of the line, and spaces or tabs at the end. A comment starting with @samp{#} may appear at the end of the line. -@c !!!! repeated above -Conditionals work at the textual level. The lines of the -@var{text-if-true} are read as part of the makefile if the condition is -true; if the condition is false, those lines are ignored completely. It -follows that syntactic units of the makefile, such as rules, may safely be -split across the beginning or the end of the conditional.@refill +Conditionals affect which lines of the makefile @code{make} uses. If +the condition is true, @code{make} reads the lines of the +@var{text-if-true} as part of the makefile; if the condition is false, +@code{make} ignores those lines completely. It follows that syntactic +units of the makefile, such as rules, may safely be split across the +beginning or the end of the conditional.@refill + +@code{make} evaluates conditionals when it reads a makefile. +Consequently, you cannot use automatic variables in the tests of +conditionals because they are not defined until commands are run +(@pxref{Automatic}). To prevent intolerable confusion, it is not permitted to start a conditional in one makefile and end it in another. However, you may @@ -3894,7 +3907,6 @@ function.@refill For example, given: -@noindent @c !!!! will this do what I want? --roland @example @group objects=main1.o foo.o main2.o bar.o @@ -4135,7 +4147,6 @@ of the names are ignored. For example, -@noindent @c !!!! ? --roland @example $(firstword foo bar) @end example @@ -4385,10 +4396,10 @@ using a very strange shell, this has the same result as @samp{$(wildcard @node Running, Implicit Rules, Functions, Top @chapter How to Run @code{make} -A makefile that says how to recompile a program can be used in more than -one way. The simplest use is to recompile every file that is out of date. -This is what @code{make} will do if run with no arguments. -@c !!!! this is misleading --roland +A makefile that says how to recompile a program can be used in more +than one way. The simplest use is to recompile every file that is out +of date. Usually, makefiles are written so that if you run +@code{make} with no arguments, it does just that. But you might want to update only some of the files; you might want to use a different compiler or different compiler options; you might want just to @@ -5041,9 +5052,6 @@ only predefined suffix rules in effect will be those named by one or two of the suffixes that are on the list you specify; rules whose suffixes fail to be on the list are disabled.@refill -@c !!!! do we want to document $(COMPILE.c) et al? --roland -@c !!!! and $(TARGET_ARCH)? - @table @asis @item Compiling C programs @file{@var{n}.o} will be made automatically from @file{@var{n}.c} with @@ -5217,6 +5225,29 @@ comparable (or inferior) proprietary software, you support the free software movement. @end table +Usually, you want to change only the variables listed in the table +above, which are documented in the following section. + +However, the commands in built-in implicit rules actually use +variables such as @code{COMPILE.c}, @code{LINK.p}, and +@code{PREPROCESS.S}, whose values contain the commands listed above. + +@code{make} follows the convention that the rule to compile a +@file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}. +Similarly, the rule to produce an executable from a @file{.@var{x}} +file uses @code{LINK.@var{x}}; and the rule to preprocess a +@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}. + +Every rule that produces an object file uses the variable +@code{OUTPUT_OPTION}. @code{make} defines this variable either to +contain @samp{-o $@@}, or to be empty, depending on a compile-time +option. You need the @samp{-o} option to ensure that the output goes +into the right file when the source file is in a different directory, +as when using @code{VPATH} (@pxref{Directory Search}). However, +compilers on some systems do not accept a @samp{-o} switch for object +files. If you use such a system, and use @code{VPATH}, some +compilations will put their output in the wrong place. + @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules @section Variables Used by Implicit Rules @cindex flags for compilers @@ -5491,12 +5522,10 @@ Thus, a pattern rule @samp{%.o : %.c} says how to make any file @subsection Introduction to Pattern Rules @cindex pattern rule -@c !!!! this paragraph is a repeat of the first paragraph of prev node -You define an implicit rule by writing a @dfn{pattern rule}. A pattern -rule looks like an ordinary rule, except that its target contains the -character @samp{%} (exactly one of them). The target is considered a -pattern for matching file names; the @samp{%} can match any nonempty -substring, while other characters match only themselves. +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. For example, @samp{%.c} as a pattern matches any file name that ends in @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts @@ -6507,9 +6536,8 @@ We feel that such usage is broken. The dependency properties of and doing such a thing simply does not fit the model.@refill @end itemize -@node Summary, Complex Makefile, Missing, Top -@appendix Summary of Directives, Functions, and Special Variables -@c !!!! this title is too long for the page +@node Quick Reference, Complex Makefile, Missing, Top +@appendix Quick Reference This appendix summarizes the directives, text manipulation functions, and special variables which GNU @code{make} understands. @@ -6819,26 +6847,12 @@ distribution kits. # Copyright (C) 1991 Free Software Foundation, Inc. @end group -@c !!!! must we have all this copying info? --roland @group # This program is free software; you can redistribute # it and/or modify it under the terms of the GNU -# General Public License as published by the Free -# Software Foundation; either version 2, or (at your -# option) any later version. -@end group - -# This program is distributed in the hope that it will -# be useful, but WITHOUT ANY WARRANTY; without even -# the implied warranty of MERCHANTABILITY or FITNESS -# FOR A PARTICULAR PURPOSE. -# See the GNU General Public License for more details. - -@group -# You should have received a copy of the GNU General -# Public License along with this program; if not, -# write to the Free Software Foundation, Inc., -# 675 Mass Ave, Cambridge, MA 02139, USA. +# General Public License @dots{} +@dots{} +@dots{} @end group SHELL = /bin/sh |