@setfilename make.info
@synindex vr fn
-@ignore
-$Header$
-
-$Log$
-Revision 1.54 1988/06/10 11:43:00 mcgrath
-Added more stuff about `foreach'.
-
-Revision 1.53 88/06/03 00:07:30 mcgrath
-* Fixed a typo in the `Missing' section.
-* Added an example of how to replace the System V $$@ feature
- using static pattern rules.
-
-Revision 1.52 88/05/30 21:39:16 mcgrath
-Added `foreach' and `sort' functions.
-
-Revision 1.51 88/05/26 17:55:55 mcgrath
-* Removed built-in .? -> .s suffix rules.
-* Misc cleanup, etc.
-
-Revision 1.50 88/05/22 14:49:44 mcgrath
-Major Beta release before release 2.0.
-
-Revision 1.24 88/05/22 13:39:08 mcgrath
-Misc cleanup
-
-Revision 1.23 88/05/22 12:29:23 mcgrath
-Static pattern rules section rewritten by RMS.
-
-Revision 1.22 88/05/20 17:00:49 mcgrath
-Documented extended static rules.
-
-Revision 1.17 88/05/18 16:26:55 mcgrath
-Fixed a couple Texinfo bugs.
-
-Revision 1.16 88/05/15 18:58:00 mcgrath
-Miscellaneous changes by Richard Stallman, added `$$@' to the
-list of unsupported features.
-
-Revision 1.15 88/05/11 21:30:52 mcgrath
-* Made `$<' automatic variable be the first dependency of any rule.
-* Bumped revision number to correspond to `make.c'.
-
-Revision 1.9 88/05/04 17:56:07 mcgrath
-* Miscellaneous changes suggested by RMS.
-* The `define' directive makes recursive variables.
-* Removed the `expand' function.
-
-Revision 1.8 88/05/01 14:49:57 mcgrath
-Added Bugs section, replacing the paragraph in
-the Overview chapter (Top node).
-
-Revision 1.7 88/04/30 15:24:24 mcgrath
-* Removed `roland@rtsg.lbl.gov' address.
-* Doubled up @'s in addresses to fix Makeinfo errors.
-
-Revision 1.6 88/04/24 00:57:23 roland
-Removed $($@) automatic macro.
-
-Revision 1.5 88/04/23 22:01:48 roland
-* Added paragraph about reporting bugs.
-* Documented -v (print version info) flag.
-* Corrected a couple typos (probably made a couple more :-).
-* Given to RMS for beta-testing.
-
-Revision 1.4 88/04/23 18:28:02 roland
-* Changed RCS stuff slightly (added a keyword).
-* Changed date from February to April, 1988.
-* Given to RMS for beta-testing.
-
-Revision 1.3 88/04/23 17:40:09 roland
-* Bumped revision number to be the same as the source.
-* Note that the `patsubst' expansion function and expansions
- of the form `$(a:-b)', etc. (from Sun sh) were in revision
- 1.2 but were accidently omitted from the log entry.
-
-Revision 1.2 88/04/23 16:16:04 roland
-* Added RCS log.
-* Changed the copyrights from Richard Stallman to Free Software Foundation.
-* Added Roland McGrath to the authors on the title page.
-* Missing `include'd makefiles are warnings, not fatal errors.
-* Clarified that conditionals determine what is `seen' in the makefile,
- so they can't be used to determine commands based on macros that are
- defined when the commands are executed (such as `$@').
-* Added `-w' switch to log directories to stdout.
-* Added selective VPATH lists and the `vpath' directive.
-* Added the previously undocumented `-lLIB' dependency syntax.
-* Added the `filter', `filter-out', `strip' and `join' expansion functions.
-* Added simply expanded vs. recursively expanded variables, `:=' variable
- assignments and changed most examples to use `:=' rather than `='.
-* Corrected miscellaneous typos, grammatical errors, etc.
-
-This version of the documentation is accurate for revision 1.2 of the source.
-
-@end ignore
+@c $Header$
@ifinfo
This file documents the GNU Make utility.
The purpose of the @code{make} utility is to determine automatically which
pieces of a large program need to be recompiled, and issue the commands to
-recompile them. This manual describes the GNU implementation of @code{make}.
-
-GNU @code{make} was implemented by Richard Stallman and Roland McGrath.
+recompile them. This manual describes the GNU implementation of
+@code{make}, which was implemented by Richard Stallman and Roland McGrath.
Our examples show C programs, since they are most common, but you can use
@code{make} with any programming language whose compiler can be run with a
you expected to occur; this will help us decide whether the problem
was really in the documentation.
-Once you've got a precise problem, send electronic mail to
-Internet address @samp{bug-gnu-utils@@prep.ai.mit.edu} or UUCP path
+Once you've got a precise problem, send email to (Internet)
+@samp{bug-gnu-utils@@prep.ai.mit.edu} or (UUCP)
@samp{mit-eddie!prep.ai.mit.edu!bug-gnu-utils}. Please include the version
number of @code{make} you are using. You can get this information with the
command @samp{make -v -f /dev/null}.@refill
@example
edit : main.o kbd.o commands.o display.o \
insert.o search.o files.o utils.o
- cc -o edit main.o kbd.o commands.o display.o \
+ cc -o edit main.o kbd.o commands.o display.o \
insert.o search.o files.o utils.o
main.o : main.c defs.h
- cc -c main.c
+ cc -c main.c
kbd.o : kbd.c defs.h command.h
- cc -c kbd.c
+ cc -c kbd.c
commands.o : command.c defs.h command.h
- cc -c commands.c
+ cc -c commands.c
display.o : display.c defs.h buffer.h
- cc -c display.c
+ cc -c display.c
insert.o : insert.c defs.h buffer.h
- cc -c insert.c
+ cc -c insert.c
search.o : search.c defs.h buffer.h
- cc -c search.c
+ cc -c search.c
files.o : files.c defs.h buffer.h command.h
- cc -c files.c
+ cc -c files.c
utils.o : utils.c defs.h
- cc -c utils.c
+ cc -c utils.c
@end example
We split each long line into two lines using a backslash-newline; this is
@example
edit : main.o kbd.o commands.o display.o \
- insert.o search.o files.o utils.o
- cc -o edit main.o kbd.o commands.o display.o \
+ insert.o search.o files.o utils.o
+ cc -o edit main.o kbd.o commands.o display.o \
insert.o search.o files.o utils.o
@end example
@example
edit : $(objects)
- cc -o edit $(objects)
+ cc -o edit $(objects)
@end example
@subsection Letting @code{make} Deduce the Commands
insert.o search.o files.o utils.o
edit : $(objects)
- cc -o edit $(objects)
+ cc -o edit $(objects)
main.o : defs.h
kbd.o : defs.h command.h
insert.o search.o files.o utils.o
edit : $(objects)
- cc -o edit $(objects)
+ cc -o edit $(objects)
$(objects) : defs.h
kbd.o commands.o files.o : command.h
@menu
* Contents: Makefile Contents. Overview of what you put in a makefile.
* Names: Makefile Names. Where @code{make} finds the makefile.
+* MAKEFILES Variable:: The environment can specify extra makefiles.
* Include:: How one makefile can use another makefile.
@end menu
effectively blank, and is ignored.
@end itemize
-@node Makefile Names, Include, Makefile Contents, Makefiles
+@node Makefile Names, MAKEFILES Variable, Makefile Contents, Makefiles
@section What Name to Give Your Makefile
By default, when @code{make} looks for the makefile, it tries the names
If @code{make} finds neither of these two names, it does not use any
makefile. Then you must specify a goal with a command argument, and
@code{make} will attempt to figure out how to remake it using only its
-built-in implicit rules.@refill
+built-in implicit rules. @xref{Implicit}.
If you want to use a nonstandard name for your makefile, you can specify
the makefile name with the @samp{-f} option. The arguments @samp{-f
specified. The default makefile names @file{./makefile} and
@file{./Makefile} are not used if you specify @samp{-f}.@refill
+@node MAKEFILES Variable, Include, Makefile Names, Makefiles
+@section The Variable @code{MAKEFILES}
+
@vindex MAKEFILES
If the environment variable @code{MAKEFILES} is defined, @code{make}
considers its value as a list of names (separated by whitespace) of
anyone else. It is much better to write explicit @code{include} directives
in the makefiles.
-@node Include,, Makefile Names, Makefiles
+@node Include,, MAKEFILES Variable, Makefiles
@section Including Other Makefiles
@findex include
so if any of the dependencies changes the contents of the existing target
file are no longer necessarily valid.
-How to remake is specified by @var{commands}. These are lines to be
+How to update is specified by @var{commands}. These are lines to be
executed by the shell (normally @samp{sh}), but with some extra features
(@pxref{Commands}).
@noindent
The variable @code{CFLAGS} exists so you can specify flags for C
compilation by implicit rule; we use it here for consistency so it will
-affect all C compilations uniformly. (@pxref{Implicit Variables}).
+affect all C compilations uniformly (@pxref{Implicit Variables}).
Often the dependencies include header files as well, which you don't want
to mention in the commands. The function @code{firstword} can be used to
Directory search applies in a special way to libraries used with the
linker. This special feature comes into play when you write a dependency
-whose name is of the form @code{-l@var{name}}. (You can tell something
+whose name is of the form @samp{-l@var{name}}. (You can tell something
funny is going on here because the dependency is normally the name of a
file, and the @emph{file name} of the library looks like
-@file{lib@var{name}.a}, not like @code{-l@var{name}}.)@refill
+@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
-When a dependency's name has the form @code{-l@var{name}}, @code{make}
+When a dependency's name has the form @samp{-l@var{name}}, @code{make}
handles it specially by searching for the file @samp{lib@var{name}.a} in
the directories @samp{/lib} and @samp{/usr/lib}, and then using matching
@code{vpath} search paths and the @code{VPATH} search path.@refill
@example
foo : foo.c -lcurses
- cc $^ -o $@@
+ cc $^ -o $@@
@end example
@noindent
would cause the command @samp{cc foo.c -lcurses -o foo} to be executed when
@file{foo} is older than @file{foo.c} or than @file{libcurses.a} (which has
-probably been found by directory search in @file{/usr/lib/libcurses.a}).@refill
+probably been found by directory search in the file
+@file{/usr/lib/libcurses.a}).@refill
As shown by the example above, the file name found by directory search is
used only for comparing the file time with the target file's time. It
@node Phony Targets, Empty Targets, Directory Search, Rules
@section Phony Targets
+@cindex phony targets
A phony target is one that is not really the name of a file.
It is only a name for some commands to be executed when explicitly
@findex .PHONY
The phony target will cease to work if anything ever does create a file
named @file{clean} in this directory. Since there are no dependencies, the
-@file{clean} would be considered up-to-date and its commands would not be
+@file{clean} would 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} (@pxref{Special Targets})
as follows:
@end example
@noindent
-Now you can say @code{make} to remake all three programs, or specify
+Now you can say just @samp{make} to remake all three programs, or specify
as arguments the ones to remake (as in @samp{make prog1 prog3}).
When one phony target is a dependency of another, it serves as a subroutine
@node Empty Targets, Special Targets, Phony Targets, Rules
@section Empty Target Files to Record Events
-@cindex empty target
+@cindex empty targets
The @dfn{empty target} is a variant of the phony target; it is used to hold
commands for an action that you request explicitly from time to time.
The dependencies of the special target @code{.PHONY} are considered to
be phony targets. When it is time to consider such a target,
@code{make} will run its commands unconditionally, regardless of
-whether a file with that name exists or what its date is. @xref{Phony
-Targets}.
+whether a file with that name exists or what its last-modification
+time is. @xref{Phony Targets}.
@item .SUFFIXES
The dependencies of the special target @code{.SUFFIXES} are the list
executed on its behalf. @xref{Search Algorithm}.
@item .PRECIOUS
+@cindex precious targets
The targets which @code{.PRECIOUS} depends on are given this special
treatment: if @code{make} is killed or interrupted during the
execution of their commands, the target is not deleted.
can be used to substitute the particular target to be remade into the
commands (@pxref{Automatic}). For example:
+@group
@example
bigoutput littleoutput : text.g
generate text.g -$(subst output,,$@@) > $@@
@end example
+@end group
@noindent
is equivalent to
targets don't have to have identical dependencies. Their dependencies must
be @emph{analogous}, but not necessarily @emph{identical}.
+@menu
+* Usage: Static Usage. How to use static pattern rules.
+* Static vs Implicit:: When are they better than implicit rules?
+@end menu
+
+@node Static Usage, Static vs Implicit, Static Pattern, Static Pattern
+@subsection Syntax of Static Pattern Rules
+
Here is the syntax of a static pattern rule:
@example
@var{targets}: @var{target-pattern}: @var{dep-patterns} @dots{}
@var{commands}
- @dots{}
+ @dots{}
@end example
@noindent
-Here @var{targets} gives the list of targets that the rule applies to. The
+The @var{targets} gives the list of targets that the rule applies to. The
targets can contain wildcard characters, just like the targets of ordinary
rules (@pxref{Wildcards}).
objects := foo.o bar.o
$(objects): %.o: %.c
- $(CC) -c $(CFLAGS) $< -o $@@
+ $(CC) -c $(CFLAGS) $< -o $@@
@end example
Each target specified must match the target pattern; a warning is issued
for each that does not. If you have a list of files, only some of which
will match the pattern, you can use the @code{filter} function to remove
-nonmatching filenames (@pxref{Functions}):
+nonmatching filenames (@pxref{Text Functions}):
@example
files := foo.elc bar.o
emacs -f batch-byte-compile $<
@end example
+@noindent
+Here the result of @samp{$(filter %.o,$(files))} is just @file{bar.o}, and
+the first static pattern rule causes it to be made from @file{bar.c}. The
+result of @samp{$(filter %.elc,$(files))} is @file{foo.elc}, which is
+made from @file{foo.el}.@refill
+
+@node Static vs Implicit,, Static Usage, Static Pattern
@subsection Static Pattern Rules versus Implicit Rules
A static pattern rule has much in common with an implicit rule defined as a
@node Commands, Variables, Rules, Top
@chapter Writing the Commands in Rules
-@cindex command (in rules)
+@cindex 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
@end group
@vindex SHELL
-@vindex SHFLAGS
The program used as the shell is taken from the variable @code{SHELL}. By
default, the program @file{/bin/sh} is used.
choices like this to affect the functioning of makefiles.
@xref{Environment}.
-The value of the variable @code{SHFLAGS} is used as additional command
-arguments to give to the shell each time it is run. By default, the
-value is empty. This variable also is not set from the environment
-except in recursive use of @code{make}.
-
@node Errors, Interrupts, Execution, Commands
@section Errors in Commands
The usual behavior assumes that your purpose is to get the specified
targets up to date; once @code{make} learns that this is impossible, it
-might as well report the failure immediately. @samp{-k} says that the real
-purpose is to test as much as possible of the changes made in the program,
-perhaps to find several independent problems so that you can correct them
-all before the next attempt to compile. This is why Emacs's @code{compile}
-command passes the @samp{-k} flag by default.
+might as well report the failure immediately. The @samp{-k} option says
+that the real purpose is to test as much as possible of the changes made in
+the program, perhaps to find several independent problems so that you can
+correct them all before the next attempt to compile. This is why Emacs's
+@code{compile} command passes the @samp{-k} flag by default.
@node Interrupts, Recursion, Errors, Commands
@section Interrupting or Killing @code{make}
If @code{make} gets a fatal signal while a command is executing, it may
delete the target file that the command was supposed to update. This is
-done if the target file's date has changed since @code{make} first checked it.
+done if the target file's last-modification time has changed since
+@code{make} first checked it.
The purpose of deleting the target is to make sure that it is remade from
scratch when @code{make} is next run. Otherwise, a partially written file
You can prevent the deletion of a target file in this way by making the
special target @code{.PRECIOUS} depend on it. Before remaking a target,
@code{make} checks to see whether it appears on the dependencies of
-@code{.PRECIOUS}, and thereby decides whether the target should be
-deleted if a signal happens. Some reasons why you might do this are
-that the target is updated in some atomic fashion or exists only to
-record a date/time (its contents do not matter) or will cause trouble
-if it ever fails to exist.
+@code{.PRECIOUS}, and thereby decides whether the target should be deleted
+if a signal happens. Some reasons why you might do this are that the
+target is updated in some atomic fashion or exists only to record a
+modification-time (its contents do not matter) or will cause trouble if it
+ever fails to exist.
@node Recursion, Sequences, Interrupts, Commands
@section Recursive Use of @code{make}
@cindex recursion
-@vindex MAKE
Recursive use of @code{make} means using @code{make} as a command in a
makefile. This technique is useful when you want separate makefiles for
various subsystems that compose a larger system. For example, suppose you
have a subdirectory @file{subdir} which has its own makefile, and you would
like the containing directory's makefile to run @code{make} on the
-subdirectory.
-
-You can do it by writing this:
+subdirectory. You can do it by writing this:
@example
subsystem:
$(MAKE) -c subdir
@end example
-That's all you have to write in the makefile to cause the sub-@code{make}
-to be run if you do @code{make subsystem}, but there are other things you
-should know about how this does its job and how the sub-@code{make} relates
-to the top-level @code{make}.
-
-The commands above use the variable @code{MAKE}, whose value is the file
-name with which @code{make} was invoked. If this file name was
-@file{/bin/make}, then the command executed is @samp{cd subdir; /bin/make}.
-If you use a special version of @code{make} to run the top-level makefile,
-the same special version will be executed for recursive invocations. Also,
-any arguments that define variable values are added to @code{MAKE}, so the
-sub-@code{make} gets them too. Thus, if you do @samp{make CFLAGS=-O}, so
-that all C-compilations will be optimized, the sub-@code{make} is run with
-@samp{cd subdir; /bin/make CFLAGS=-O}.
-
-The flag options you give to the top-level @code{make} are passed down
-to the sub-@code{make} automatically, through the variable @code{MAKEFLAGS}
-as described below.
-
-All the other variable values of the top-level @code{make} are passed to
-the sub-@code{make} through the environment. These variables are defined
-in the sub-@code{make} as defaults, but do not override what is specified
-in the sub-@code{make}'s makefile. The way this works is that @code{make}
-adds each variable and its value to the environment for running each
-command. (Variables whose names start with non-alphanumeric characters are
-left out.) The sub-@code{make}, in turn, uses the environment to
-initialize its table of variable values. @xref{Environment}.
+You can write recursive @code{make} commands just by copying this example,
+but there are many things to know about how they work and why, and about
+how the sub-@code{make} relates to the top-level @code{make}.
+
+@menu
+* MAKE Variable:: Special effects of using @samp{$(MAKE)}.
+* Variables/Recursion:: How variables are communicated to a sub-@code{make}.
+* Options/Recursion:: How options are communicated to a sub-@code{make}.
+* -w Option:: The @samp{-w} option facilitates debugging
+ makefiles with recursive @code{make} commands.
+@end menu
+
+@node MAKE Variable, Variables/Recursion, Recursion, Recursion
+@subsection How the @code{MAKE} Variable Works
+@vindex MAKE
+
+Recursive @code{make} commands should always use the variable @code{MAKE},
+not the explicit command name @samp{make}, as shown here:
+
+@example
+subsystem:
+ cd subdir; $(MAKE)
+@end example
+
+The value of this variable is the file name with which @code{make} was
+invoked. If this file name was @file{/bin/make}, then the command executed
+is @samp{cd subdir; /bin/make}. If you use a special version of
+@code{make} to run the top-level makefile, the same special version will be
+executed for recursive invocations.
+
+Also, any arguments that define variable values are added to @code{MAKE},
+so the sub-@code{make} gets them too. Thus, if you do @samp{make
+CFLAGS=-O}, so that all C-compilations will be optimized, the
+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{-n} or @samp{-q} option.
+(@xref{Instead of Execution}.)@refill
+
+Consider the command @samp{make -t} in the above example. Following the
+usual definition of @samp{-t}, this would create a file named
+@file{subsystem} and do nothing else. What you really want it to do is run
+@samp{cd subdir; make -t}; but that would require executing the command,
+and @samp{-t} says not to execute commands.@refill
+
+The special feature makes this do what you want: whenever a rule's commands
+use the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or @samp{-q}
+do not apply to that rule. The commands of that rule are executed normally
+despite the presence of a flag that causes most commands not to be run.
+The usual @code{MAKEFLAGS} mechanism passes the flags to the
+sub-@code{make} (@pxref{Options/Recursion}), so your request to touch the
+files, or print the commands, is propagated to the subsystem.@refill
+
+@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
+@subsection Communicating Variables to a Sub-@code{make}
+@cindex environment and recursion
+
+Most variable values of the top-level @code{make} are passed to the
+sub-@code{make} through the environment. These variables are defined in
+the sub-@code{make} as defaults, but do not override what is specified in
+the sub-@code{make}'s makefile. (Variables are passed down if their names
+consist of letters, numbers and underscores.)
+
+The way this works is that @code{make} adds each variable and its value to
+the environment for running each command. (Variables whose names start
+with non-alphanumeric characters are left out.) The sub-@code{make}, in
+turn, uses the environment to initialize its table of variable values.
+@xref{Environment}.
@vindex MAKELEVEL
As a special feature, the variable @code{MAKELEVEL} is changed when it is
(@pxref{Conditionals}); this way you can write a makefile that behaves one
way if run recursively and another way if run directly by you.
+@vindex MAKEFILES
+You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
+commands to use additional makefiles. The value of @code{MAKEFILES} is a
+whitespace-separated list of filenames. This variable, if defined in the
+outer-level makefile, is passed down through the environment as usual; then
+it serves as a list of extra makefiles for the sub-@code{make} to read
+before the usual or specified ones. @xref{MAKEFILES Variable}.
+
+@node Options/Recursion, -w Option, Variables/Recursion, Recursion
+@subsection Communicating Options to a Sub-@code{make}
+@cindex options and recursion
+
@vindex MAKEFLAGS
Flags such as @samp{-s} and @samp{-k} are passed automatically to the
sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
set up automatically by @code{make} to contain the flag letters that
@code{make} received. Thus, if you do @samp{make -ks} then
-@code{MAKEFLAGS} gets the value @samp{ks}.
+@code{MAKEFLAGS} gets the value @samp{ks}.@refill
As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
in its environment. In response, it takes the flags from that value and
processes them as if they had been given as arguments. @xref{Options}.
The options @samp{-c}, @samp{-d}, @samp{-f}, @samp{-I}, @samp{-o}, and
-@samp{-p} are not put into @code{MAKEFLAGS}; these options are not
-passed down.@refill
+@samp{-p} are not put into @code{MAKEFLAGS}; these options are not passed
+down.@refill
If you don't want to pass the other the flags down, you must change the
value of @code{MAKEFLAGS}, like this:
@noindent
but now @code{MAKEFLAGS} makes this usage redundant.
-What about @samp{make -t}? (@xref{Instead of Execution}.) Following the
-usual definition of @samp{-t}, this would create a file named
-@file{subsystem}. What you really want it to do is run @samp{cd subdir;
-make -t}; but that would require executing the command, and @samp{-t} says
-not to execute commands.@refill
-
-The paradox is resolved by a special @code{make} feature: whenever a
-command uses the variable @code{MAKE}, the flags @samp{-t}, @samp{-n} or
-@samp{-q} do not apply to that rule. The commands of that rule are
-executed normally despite the presence of a flag that causes most
-commands not to be run. These flags are passed along via
-@code{MAKEFLAGS}, so your request to touch the files, or print the
-commands, is propagated to the subsystem.
+@node -w Option,, Options/Recursion, Recursion
+@subsection The @samp{-w} Option
-@vindex MAKEFILES
-If the environment variable @code{MAKEFILES} is defined, @code{make}
-considers its value as a list of names (separated by whitespace) of
-additional makefiles to be read before the others. This works much like
-the @code{include} directive: various directories are searched for those
-files and the default goal is never taken from them. @xref{Include}. In
-addition, it is not an error if the files listed in @code{MAKEFILES} are
-not found.
-
-The main use of @code{MAKEFILES} is with recursive invocation of @code{make}.
-The outer @code{make} can set @code{MAKEFILES} to influence recursive
-@code{make} levels.
-
-If you are running @code{make} over a large directory tree, the @code{-w}
-option can make understanding the output a lot easier by showing each
-directory as it is entered and exited. For example, if @code{make -w} is
+If you are running @code{make} over a large directory tree, the @samp{-w}
+option can make the output a lot easier to understand by showing each
+directory as it is entered and exited. For example, if @samp{make -w} is
run in the directory @file{/u/gnu/make}, @code{make} will print a line of
-the form:
+the form:@refill
@example
make: Entering directory `/u/gnu/make'.
A variable name may be any sequence characters not containing @samp{:},
@samp{#}, @samp{=}, tab characters or leading or trailing spaces. However,
variable names containing characters other than letters, numbers and
-underscores should be avoided, as they may be given special meanings in
-the future.
+underscores should be avoided, as they may be given special meanings in the
+future, and they are not passed through the environment to a
+sub-@code{make} (@pxref{Variables/Recursion}).
It is traditional to use upper case letters in variable names, but we
recommend using lower case letters for variable names that serve internal
@node Reference, Values, Variables, Variables
@section Reference to Variables
@cindex reference to variables
-@cindex $
+@cindex $ (variable reference)
To substitute a variable's value, write a dollar sign followed by the name
of the variable in parentheses or braces: either @samp{$(foo)} or
A @dfn{substitution reference} is really a simplified form of the
@code{patsubst} expansion function (@pxref{Functions}). It has the form
-@code{$(var:a=b)} (or @code{$@{var:a=b@}}) and is equivalent to
-@code{$(patsubst %a,%b,$(var))}. This means that it replaces every
+@samp{$(var:a=b)} (or @samp{$@{var:a=b@}}) and is equivalent to
+@samp{$(patsubst %a,%b,$(var))}. This means that it replaces every
@samp{a} at the end of a whitespace-separated word with a @samp{b}.
For example:@refill
@table @code
@item $(@var{a}:-@var{b})
-This expands to the value of the variable @var{a} if it is defined or to
-@samp{@var{b}} (a literal string) if it is not.
+This expands to the value of the variable @var{a} if it is defined or
+to @var{b} (a literal string) if it is not.
@item $(@var{a}:+@var{b})
-This expands to @samp{@var{b}} if the variable @var{a} is
-defined or to nothing (no characters) if it is not.
+This expands to @var{b} if the variable @var{a} is defined or to
+nothing (no characters) if it is not.
@item $(@var{a}:@var{b}-@var{c})
-This expands to @samp{@var{b}} if the variable @var{a} is defined or to
-@samp{@var{c}} (a literal string) if it is not.
+This expands to @var{b} if the variable @var{a} is defined or to
+@var{c} (a literal string) if it is not.
@end table
For the purpose of these conditional references, a variable is ``defined''
if it exists and is non-null.
-In the first two alternatives, the @samp{:} may be omitted. Then the
-variable @var{a} is considered ``defined'' if it has been assigned any
-value, even a null value.
+In the first two alternatives, the @samp{:} may be omitted to produce
+a slightly different effect: then the variable @var{a} is considered
+``defined'' if it has been assigned any value, even a null value.
Note that a variable value consisting solely of whitespace is @emph{not}
null.
distinguished by two things: how they are defined and how they are expanded.
The first flavor of variable is a @dfn{recursively expanded} variable.
-Variables of this sort are defined by lines using @samp{=}.
+Variables of this sort are defined by lines using @samp{=}
@ifinfo
-(@xref{Setting}.)
+(@pxref{Setting}).
@end ifinfo
@iftex
-(See the next section.)
+(see the next section).
@end iftex
The value you specify is installed verbatim; if it contains references to
other variables, these references are expanded whenever this variable is
To avoid all the problems and inconveniences of recursively expanded
variables, there is another flavor: @dfn{simply expanded} variables.
-Simply expanded variables are defined by lines using @samp{:=}.
+Simply expanded variables are defined by lines using @samp{:=}
@ifinfo
-(@xref{Setting}.)
+(@pxref{Setting}).
@end ifinfo
@iftex
-(See the next section.)
+(see the next section).
@end iftex
The value of a simply expanded variable is scanned once and for all,
expanding any references to other variables and functions, when the
verbatim.
Simply expanded variables generally make complicated makefile programming
-more predictable. This way you can redefine a variable using its own value
-(or its value processed in some way by one of the expansion functions;
-@pxref{Functions}) and use the expansion functions much more efficiently.
+more predictable because they work like variables in most programming
+languages. They allow you to redefine a variable using its own value (or
+its value processed in some way by one of the expansion functions) and to
+use the expansion functions much more efficiently (@pxref{Functions}).
You can also use them to introduce controlled leading or trailing spaces
into variable values. Such spaces are discarded from your input before
variable and nothing more. The value to give the variable appears on the
following lines. The end of the value is marked by a line containing just
the word @code{endef}. Aside from this difference in syntax, @code{define}
-works just like @code{=}; it creates a recursively-expanded variable
+works just like @samp{=}; it creates a recursively-expanded variable
(@pxref{Flavors}).
@example
part of the variable's value (except for the final newline which precedes
the @code{endef} and is not considered part of the value).@refill
-Thus the previous example is functionally equivalent to:
+The previous example is functionally equivalent to this:
@example
two-lines = echo foo; echo $(bar)
and value. But an explicit assignment in the makefile, or with a command
argument, overrides the environment. (If the @samp{-e} flag is specified,
then values from the environment override assignments in the makefile.
-@xref{Options}.)
+@xref{Options}. But this is not recommended practice.)
By setting the variable @code{CFLAGS} in your environment, you can cause
all C compilations in most makefiles to use the compiler switches you
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} (and @code{SHFLAGS}) if the value of @code{MAKELEVEL} is zero
-(which is normally true except in recursive invocations of
-@code{make}).@refill
+@code{SHELL} if the value of @code{MAKELEVEL} is zero (which is normally
+true except in recursive invocations of @code{make}).@refill
@node Conditionals, Functions, Variables, Top
@chapter Conditional Parts of Makefiles
ifneq (,$(findstring t,$(MAKEFLAGS)))
@@echo $(MAKE) > /dev/null
touch archive.a
- ranlib -t archive.a
+ ranlib -t archive.a
else
ranlib archive.a
endif
The @code{echo} command does nothing when executed; but its presence, with
a reference to the variable @code{MAKE}, marks the rule as ``recursive'' so
that its commands will be executed despite use of the @samp{-t} flag.
+@xref{Recursion}.
@node Functions, Running, Conditionals, Top
@chapter Functions for Transforming Text
@cindex function
-@dfn{Functions} allow you to do text processing in the makefile to
-compute the files to operate on or the commands to use.
+@dfn{Functions} allow you to do text processing in the makefile to compute
+the files to operate on or the commands to use. You use a function in a
+@dfn{function call}, where you give the name of the function and some text
+(the @dfn{arguments}) for the function to operate on. The result of the
+function's processing is substituted into the makefile at the point of the
+call, just as a variable might be substituted.
@menu
* Syntax: Function Syntax. Syntax of function calls in general.
@node Function Syntax, Text Functions, Functions, Functions
@section Function Call Syntax
-@cindex $
+@cindex $ (function call)
+@cindex arguments
A function call resembles a variable reference. It looks like this:
@example
sources := foo.c bar.c ugh.h
foo: $(sources)
- cc $(filter %.c,$(sources)) -o foo
+ cc $(filter %.c,$(sources)) -o foo
@end example
@noindent
passed automatically to the C compiler, like this:
@example
-CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))
+override CFLAGS:= $(CFLAGS) $(addprefix -I,$(subst :, ,$(VPATH)))
@end example
@noindent
The effect is to append the text @samp{-Isrc -I../headers} to the
-previously given value of @code{CFLAGS}.
+previously given value of @code{CFLAGS}. The @code{override} directive is
+used so that the new value is assigned even if the previous value of
+@code{CFLAGS} was specified with a command argument (@pxref{Override
+Directive}).
The function @code{strip} can be very useful when used in conjunction
with conditionals. When comparing something with the null string
@end example
@noindent
-might fail to have the desired results. Replacing
-@samp{"$(needs_made)"} with @samp{"$(strip $(needs_made))"} in the
-@code{ifneq} directive would make it more reliable.@refill
+might fail to have the desired results. Replacing the variable reference
+@samp{"$(needs_made)"} with the function call @samp{"$(strip
+$(needs_made))"} in the @code{ifneq} directive would make it more robust.
@node Foreach Function, Filename Functions, Text Functions, Functions
@section The @code{foreach} Function
+@findex foreach
-The @code{foreach} function is very different from other functions.
-It performs a specialized operation of a different nature.
+The @code{foreach} function is very different from other functions. It
+causes one piece of text to be used repeatedly, each time with a different
+substitution performed on it. It resembles the @code{for} command in the
+shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
The syntax of the @code{foreach} function is:
@end example
@noindent
-This function operates similarly to the @code{for} command in the shell
-@samp{sh} and the @code{foreach} command in the C-shell @samp{csh}.
The first two arguments, @var{var} and @var{list}, are expanded before
anything else is done; note that the last argument, @var{text}, is
@emph{not} expanded at the same time. Then for each word of the expanded
value of @var{list}, the variable named by the expanded value of @var{var}
is set to that word, and @var{text} is expanded. Presumably @var{text}
contains references to that variable, so the expansions will be different
-each time. The expansions of @var{text} for each word in the expanded
-value of @var{list} are separated by a single space in the output. The
-control variable (the one named by the expanded value of @var{var}) is
-restored to the value it had before the @code{foreach} function was
-executed when the function is finished. If it was not previously defined,
-the control variable is defined as a recursively expanded variable (as if
-defined with @samp{=} rather than @samp{:=}; @pxref{Flavors}).@refill
-
-To increase readability and lessen complexity, it is a good idea to put the
-@var{text} part of a @code{foreach} function invokation into a variable.
-For this to work properly, you must use a recursively expanded variable, so
-it will be expanded when the @code{foreach} function is invoked, not when
-the variable is defined.@refill
-
-This simple example sets the variable @samp{files} to the list of
-all files in the directories in the list @samp{dirs}.
+each time.
+
+The result is that @var{text} is expanded as many times as there are
+whitespace-separated words in @var{list}. The multiple expansions of
+@var{text} are concatenated, with spaces between them, to make the result
+of @code{foreach}.
+
+This simple example sets the variable @samp{files} to the list of all files
+in the directories in the list @samp{dirs}:
@example
find_files = $(wildcard $(dir)/*)
files := $(foreach dir,$(dirs),$(find_files))
@end example
-Note that the variable @samp{find_files} is made recursive. It is then
-used to perform a function that results in a value, rather than to simply
-@emph{be} a value. This example has the same result (except for setting
-@samp{find_files} and @samp{dirs}) as:
+For readability, it is a good idea to put the @var{text} part of a
+@code{foreach} function invokation into a variable. Here we use the
+variable @code{find_file} this way. We make this a recursively-expanding
+variable by using @samp{=} to define it. This is necessary so that when
+its value is substituted by @code{foreach} the value is rescanned for
+variable references and function calls. This is what causes the
+@code{wildcard} function actually to be called.
+
+This example has the same result (except for setting @samp{find_files},
+@samp{dirs} and @samp{dir}) as the following example:
@example
files := $(wildcard a/* b/* c/* d/*)
-dir =
@end example
-The variable @samp{dir} is made a recursive variable with a null value by
-virtue of not being set beforehand, and then being used in the
-@code{foreach} function. If, before the invokation of @code{foreach},
-@samp{dir} had been defined by the line:
+The value of the variable @var{var} after the @code{foreach} function call
+is the same as the value beforehand. Other values taken from @var{list}
+are in effect only temporarily, during the execution of @code{foreach}.
+The variable @var{var} is the same flavor (recursively expanded or not)
+during @code{foreach} as it was before. @xref{Flavors}.
-@example
-dir := foo
-@end example
+If @var{var} was previously undefined, then it is defined as a recursively
+expanded variable (@samp{=}, not @samp{:=}) during the @code{foreach} and
+remains so (with a null value) afterward.
-@noindent
-then it would have that same value and the property of being a simply
-expanded variable after the @code{foreach} function was finished.
-Note also that @samp{dir} would remain a simply expanded variable
-throughout the invokation of @code{foreach}.
-
-Because it is expanded before other processing is done, the @var{var}
-argument to @code{foreach} need not be a variable name. It can be a
+Because it is expanded before @code{foreach} runs, the @var{var} argument
+to @code{foreach} need not be a literal variable name. It can instead be a
variable expression resulting in the name. Thus,
@example
@end example
@noindent
-will work as expected if @samp{find_files} references the variable
-@samp{Es escrito en espanol!} (es un nombre bastante largo, no?), but
-somehow this seems unlikely (pero qualquiera cosa es posible).
-You might be inclined to use variable names such as this so as not to
-disturb other variables, because variables with names containing whitespace
-can be referenced but not defined in the conventional manner
-(@pxref{Defining}). But this is not necessary, since the @code{foreach}
-function always preserves the value and flavor (@pxref{Flavors}) of its
-control variable (the one named by the @var{var} argument).@refill
+might be useful if @samp{find_files} references the variable @samp{Es
+escrito en espanol!} (es un nombre bastante largo, no?), but it is more
+likely to be a mistake.
@node Filename Functions,, Foreach Function, Functions
@section Functions for File Names
argument. If one argument has more words that the other, the extra
words are copied unchanged into the result.
+For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
+
Whitespace between the words in the lists is not preserved; it is
replaced with a single space.
long time to remake).
@item install
-Copy the executable file into a directory that users typically search for
-commands.
+Copy the executable file into a directory that users typically search
+for commands; copy any auxiliary files that the executable uses into
+the directories where it will look for them.
@item print
Print listings of the source files that have changed.
@node Avoid Compilation, Instead of Execution, Goals, Running
@section Avoiding Recompilation of Some Files
+@cindex -o
Sometimes you may have changed a source file but you don't want to
recompile all the files that depend on it. For example, suppose you add a
If you anticipate the problem before making the change, you can use the
@samp{-t} flag. This flag tells @code{make} not to run the commands in the
-rules, but rather to mark the target up-to-date by changing its
+rules, but rather to mark the target up to date by changing its
last-modification date. You would follow this procedure:
@enumerate
@item
Use the command @samp{make -t} to mark all the object files as
-up-to-date. The next time you run @code{make}, the changes in the
+up to date. The next time you run @code{make}, the changes in the
header files will not cause any recompilation.
@end enumerate
There is one way that the makefile can change a variable that you have
overridden. This is to use the @code{override} directive, which is a line
-that looks like this:
-
-@example
-override @var{variable} = @var{value}
-@end example
-
-or
-
-@example
-override @var{variable} := @var{value}
-@end example
-
-@noindent
-This line acts like an ordinary variable assignment except that it is
-not ignored even if you have used a command option to set the variable.
+that looks like this: @samp{override @var{variable} = @var{value}}.
@xref{Override Directive}.
@node Testing, Options, Overriding, Running
Normally, when an error happens in executing a shell command, @code{make}
gives up immediately, returning a nonzero status. No further commands are
executed for any target. The error implies that the goal cannot be
-correctly remade, so @code{make} reports this as soon as it knows.
+correctly remade, and @code{make} reports this as soon as it knows.
When you are compiling a program that you have just changed, this is not
what you want. Instead, you would rather that @code{make} try compiling
every file that can be tried, to show you all the compilation errors.
@cindex -k
-Then you should use the @samp{-k} flag. If the @samp{-k} flag is
-specified, @code{make} continues to consider the other dependencies of the
-pending targets, remaking them if necessary, before it gives up and returns
-nonzero status. For example, after an error in compiling one object file,
+On these occasions, you should use the @samp{-k} flag. This tells
+@code{make} to continue to consider the other dependencies of the pending
+targets, remaking them if necessary, before it gives up and returns nonzero
+status. For example, after an error in compiling one object file,
@samp{make -k} will continue compiling other object files even though it
already knows that linking them will be impossible. @xref{Options}.
@file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.f} by running the
Fortran compiler. The precise command used is as follows:@refill
-@table @samp
+@table @code
@item .e
@samp{$(FC) -c $(EFLAGS)}.
@item .f
program into a strict Fortran program. The precise command used is as
follows:@refill
-@table @samp
+@table @code
@item .e
@samp{$(FC) -F $(EFLAGS)}.
@item .F
files. The difference is that the intermediate file is deleted when
@code{make} is finished. Therefore, the intermediate file which did
not exist before @code{make} also does not exist after @code{make}.
-The deletion is reported to you by printing a @code{rm -f} command
+The deletion is reported to you by printing a @samp{rm -f} command
that shows what @code{make} is doing. (You can optionally define an
implicit rule so as to preserve certain intermediate files. You can also
-list the target pattern of an implicit rule (such as @code{%.o}) as a
+list the target pattern of an implicit rule (such as @samp{%.o}) as a
dependency file of the special target @code{.PRECIOUS} to preserve intermediate
files whose target patterns match that file's name.)@refill
@node Automatic, Pattern Match, Pattern Examples, Pattern Rules
@subsection Automatic Variables
@cindex automatic variables
-@cindex $
Suppose you are writing a pattern rule to compile a @samp{.c} file into a
@samp{.o} file: how do you write the @samp{cc} command so that it operates
want. For example,
@example
-.SUFFIXES: @r{# Delete the default suffixes}
-.SUFFIXES: .c .o .h @r{# Define our suffix list}
+.SUFFIXES: # @r{Delete the default suffixes}
+.SUFFIXES: .c .o .h # @r{Define our suffix list}
@end example
The @samp{-r} flag causes the default list of suffixes to be empty.
@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
@item
-Make a list of the pattern rules whose target matches @var{d} or
+Make a list of the pattern rules whose target matches @var{t} or
@var{n}. If the target pattern contains a slash, it is matched
against @var{t}; otherwise, against @var{n}.
@enumerate
@item
-Find the stem @var{s}: the part of @var{d} or @var{n} that the
+Find the stem @var{s}: the part of @var{t} or @var{n} that the
@samp{%} in the target pattern matches.@refill
@item
@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
archive @file{foo.a} as a member named @file{bar.o}.
-When this rule is chained with others, the result is very powerful. The
-command @samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c}
-is enough to cause the following commands to be run, even without a
-makefile:
+When this rule is chained with others, the result is very powerful. Thus,
+@samp{make "foo.a(bar.o)"} in the presence of a file @file{bar.c} is enough
+to cause the following commands to be run, even without a makefile:
@example
cc -c bar.c -o bar.o
@end example
@noindent
-Here the file @file{bar.o} has been invented as an intermediate file.
+Here the file @file{bar.o} has been envisioned as an intermediate file.
@node Archive Symbols,, Archive Update, Archives
@subsection Updating Archive Symbol Directories
rules. The System V @code{make} rule:
In GNU @code{make}, this entire series of cases is handled by two
pattern rules for extraction from SCCS, in combination with the
-$(targets): $$@.o lib.a
+general feature of rule chaining. @xref{Chained Rules}.
@item
In System V @code{make}, the string @samp{$$@@} has the strange meaning
projects / platform / upstream / make.git / commitdiff