summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorRobert J. Chassell <bob@rattlesnake.com>1992-07-17 17:05:55 +0000
committerRobert J. Chassell <bob@rattlesnake.com>1992-07-17 17:05:55 +0000
commitc29174d96b8d24e3785c18ad05842e976df9a4c6 (patch)
treeec20c788c26987b686608d99f3e680cd9a524aa0
parentcda455684c87efa81b6ebe7b211f4e4342741a3f (diff)
downloadgunmake-c29174d96b8d24e3785c18ad05842e976df9a4c6.tar.gz
Formerly make.texinfo.~35~
-rw-r--r--make.texinfo132
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