introduction, read the first few sections of each chapter, skipping the
later sections. In each chapter, the first few sections contain
introductory or general information and the later sections contain
-specialized or technical information. The exception is the second
-chapter, @ref{Introduction, ,An Introduction to Makefiles}, all of which
-is introductory.
+specialized or technical information.
+@ifinfo
+The exception is the second chapter, @ref{Introduction, ,An
+Introduction to Makefiles}, all of which is introductory.
+@end ifinfo
+@iftex
+The exception is @ref{Introduction, ,An Introduction to Makefiles},
+all of which is introductory.
+@end iftex
If you are familiar with other @code{make} programs, see @ref{Features,
,Features of GNU @code{make}}, which lists the enhancements GNU
@node Bugs, , Reading, Overview
@section Problems and Bugs
+@cindex reporting bugs
+@cindex bugs, reporting
+@cindex problems and bugs, reporting
If you have problems with GNU @code{make} or think you've found a bug,
please report it to the developers; we cannot promise to do anything but
together to produce the new executable editor.
@menu
-* Parts of Makefiles:: The Parts of a Makefile
+* Rule Introduction:: What a rule looks like.
* Simple Makefile:: A Simple Makefile
* How Make Works:: How @code{make} Processes This Makefile
* Variables Simplify:: Variables Make Makefiles Simpler
@end menu
-@node Parts of Makefiles, Simple Makefile, , Introduction
+@node Rule Introduction
@comment node-name, next, previous, up
-@section The Parts of a Makefile
-@cindex parts of a makefile
+@section What a Rule Looks Like
+@cindex rule, introduction to
+@cindex makefile rule parts
+@cindex parts of makefile rule
A simple makefile consists of ``rules'' with the following shape:
-@cindex rule, part of makefile
-@cindex target, part of makefile
-@cindex dependencies, part of makefile
-@cindex command, part of makefile
+@cindex targets, introduction to
+@cindex dependencies, introduction to
+@cindex commands, introduction to
@example
@group
@var{target} @dots{} : @var{dependencies} @dots{}
A @dfn{dependency} is a file that is used as input to create the
target. A target often depends on several files.
+@cindex tabs in rules
A @dfn{command} is an action that @code{make} carries out.
A rule may have more than one command, each on its own line.
@strong{Please note:} you need to put a tab character at the beginning of
@node Simple Makefile, How Make Works, Parts of Makefiles, Introduction
@comment node-name, next, previous, up
@section A Simple Makefile
+@cindex simple makefile
+@cindex makefile, simple
Here is a straightforward makefile that describes the way an
executable file called @code{edit} depends on eight object files
later (@pxref{Using Variables, ,How to Use Variables}).
It is standard practice for every makefile to have a variable named
-@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj} or
-@code{OBJ} which is a list of all object file names. We would define
-such a variable @code{objects} with a line like this in the makefile:@refill
+@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
+or @code{OBJ} which is a list of all object file names. We would
+define such a variable @code{objects} with a line like this in the
+makefile:@refill
@example
@group
@cindex variable definition
@item
-A @dfn{variable definition} is a line that specifies a text string value for
-a variable that can be substituted into the text later. The
-simple makefile example (@pxref{Simple Makefile, , A Simple Makefile})
-shows a variable definition for @code{objects} as a list of all object
-files. @xref{Using Variables, ,How to Use Variables}, for full
-details.
+A @dfn{variable definition} is a line that specifies a text string
+value for a variable that can be substituted into the text later. The
+simple makefile example shows a variable definition for @code{objects}
+as a list of all object files (@pxref{Variables Simplify, , Variables
+Make Makefiles Simpler}).
@cindex directive
@item
However, if the two makefiles give different commands for the same
target, @code{make} will not let you just do this. But there is another way.
+@cindex @code{.DEFAULT}, used to override
In the containing makefile (the one that wants to include the other),
you can use the @code{.DEFAULT} special target to say that to remake
any target that cannot be made from the information in the containing
appear on the same line, with a semicolon. Either way, the effect is the
same. @xref{Commands, ,Writing the Commands in Rules}.
+@cindex dollar signs in rules
+@cindex @samp{$} in rules
Because dollar signs are used to start variable references, if you really
want a dollar sign in a rule you must write two of them, @samp{$$}
(@pxref{Using Variables, ,How to Use Variables}).
@node Wildcards, Directory Search, Rule Syntax, Rules
@section Using Wildcard Characters in File Names
@cindex wildcard
-@cindex file name
+@cindex file name with wildcards
+@cindex globbing (wildcards)
@cindex * (wildcard character)
@cindex ? (wildcard character)
by the shell. For example, here is a rule to delete all the object files:
@example
+@group
clean:
rm -f *.o
+@end group
@end example
Wildcards are also useful in the dependencies of a rule. With the
@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
@subsection Pitfalls of Using Wildcards
+@cindex wildcard pitfalls
+@cindex pitfalls of wildcards
+@cindex mistakes with wildcards
+@cindex errors with wildcards
+@cindex problems with wildcards
Now here is an example of a naive way of using wildcard expansion, that
does not do what you would intend. Suppose you would like to say that the
@section Searching Directories for Dependencies
@vindex VPATH
@findex vpath
-@cindex vpath
-@cindex search path for dependencies
-@cindex directory search
+@cindex vpath
+@cindex search path for dependencies (VPATH)
+@cindex directory search (VPATH)
For large systems, it is often desirable to put sources in a separate
directory from the binaries. The @dfn{directory search} features of
-@code{make} facilitate this by searching several directories automatically
-to find a dependency. When you redistribute the files among directories,
-you do not need to change the individual rules, just the search paths.
+@code{make} facilitate this by searching several directories
+automatically to find a dependency. When you redistribute the files
+among directories, you do not need to change the individual rules,
+just the search paths.
@menu
* General Search:: Specifying a search path that applies
@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
@subsection Directory Search and Implicit Rules
+@cindex directory search (VPATH) and implicit rules
+@cindex search in directories (VPATH) with implicit rules
+@cindex implicit rules with directory search (VPATH)
The search through the directories specified in @code{VPATH} or with
@code{vpath} happens also during consideration of implicit rules
@node Libraries/Search, , Implicit/Search, Directory Search
@subsection Directory Search for Link Libraries
-@cindex link libraries, directory search
-@cindex libraries for linking, directory search
-@cindex directory search, link libraries
+@cindex link libraries, directory search (VPATH)
+@cindex libraries for linking, directory search (VPATH)
+@cindex directory search (VPATH), link libraries
+@cindex search in directories (VPATH), link libraries
+@cindex -l (library search)
Directory search applies in a special way to libraries used with the
linker. This special feature comes into play when you write a dependency
For example,
@example
+@group
foo : foo.c -lcurses
cc $^ -o $@@
+@end group
@end example
@noindent
@node Phony Targets, Force Targets, Directory Search, Rules
@section Phony Targets
@cindex phony targets
+@cindex targets, phony
A phony target is one that is not really the name of a file. It is just a
name for some commands to be executed when you make an explicit request.
Here is an example:
@example
+@group
clean:
rm *.o temp
+@end group
@end example
@noindent
named @file{clean} in this directory. Since it has no dependencies, the
file @file{clean} would inevitably be considered up to date, and its
commands would not be executed. To avoid this problem, you can explicitly
-declare the target to be phony, using the special target @code{.PHONY}
+declare the target to be phony, using the special target @code{.PHONY
(@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
@example
Certain names have special meanings if they appear as targets.
@table @code
+@findex .PHONY special target
@item .PHONY
The dependencies of the special target @code{.PHONY} are considered to
whether a file with that name exists or what its last-modification
time is. @xref{Phony Targets, ,Phony Targets}.
+@findex .SUFFIXES special target
@item .SUFFIXES
The dependencies of the special target @code{.SUFFIXES} are the list
of suffixes to be used in checking for suffix rules.
@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
+@findex .DEFAULT special target
@item .DEFAULT
The commands specified for @code{.DEFAULT} are used for any target for
executed on its behalf. @xref{Search Algorithm, ,Implicit Rule Search
Algorithm}.
+@findex .PRECIOUS special target
@item .PRECIOUS
@cindex precious targets
execution of their commands, the target is not deleted.
@xref{Interrupts, ,Interrupting or Killing @code{make}}.
+@findex .IGNORE special target
@item .IGNORE
Simply by being mentioned as a target, @code{.IGNORE} says to ignore
useful; we recommend you use the more selective ways to ignore errors
in specific commands. @xref{Errors, ,Errors in Commands}.
+@findex .SILENT special target
@item .SILENT
Simply by being mentioned as a target, @code{.SILENT} says not to
use the more selective ways to silence specific commands.
@xref{Echoing, ,Command Echoing}. If you want to silence all commands
for a particular run of @code{make}, use the @samp{-s} or
-@samp{--silent} option (@pxref{Options Summary}).
+@w{@samp{--silent}} option (@pxref{Options Summary}).
+@findex .EXPORT_ALL_VARIABLES special target
@item .EXPORT_ALL_VARIABLES
-Simply by being mentioned as a target, @code{.EXPORT_ALL_VARIABLES}
-tells @code{make} to export all variables to child processes by default.
-@xref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}.
+Simply by being mentioned as a target, this tells @code{make} to
+export all variables to child processes by default.
+@xref{Variables/Recursion, ,Communicating Variables to a
+Sub-@code{make}}.
@end table
Any defined implicit rule suffix also counts as a special target if it
@section Multiple Targets in a Rule
@cindex multiple targets
@cindex targets, multiple
+@cindex rule with multiple targets
A rule with multiple targets is equivalent to writing many rules, each with
one target, and all identical aside from that. The same commands apply to
do it with a @dfn{static pattern rule}. @xref{Static Pattern, ,Static Pattern Rules}.
@end ifinfo
+
+
@node Multiple Rules, Double-Colon, Static Pattern, Rules
@section Multiple Rules for One Target
+@cindex multiple rules for one target
+@cindex rules, multiple for one target
+@cindex target, multiple rules
One file can be the target of several rules. All the dependencies
mentioned in all the rules are merged into one list of dependencies for
@node Static Pattern, Multiple Rules, Multiple Targets, Rules
@section Static Pattern Rules
@cindex static pattern rules
+@cindex rules, static pattern
+@cindex pattern rules, static (not implicit)
@cindex varying dependencies
@dfn{Static pattern rules} are rules which specify multiple targets and
@node Double-Colon, , Multiple Rules, Rules
@section Double-Colon Rules
-@cindex double-colon rule
+@cindex double-colon rules
+@cindex rules, double-colon
+@cindex multiple, independent rules for one target
+@cindex @samp{::} rules (double-colon)
@dfn{Double-colon} rules are rules written with @samp{::} instead of
@samp{:} after the target names. They are handled differently from
@node Commands, Using Variables, Rules, Top
@chapter Writing the Commands in Rules
@cindex commands
+@cindex rule commands
+@cindex writing rule commands
The commands of a rule consist of shell command lines to be executed one by
one. Each command line must start with a tab, except that the first
always interpreted by @file{/bin/sh} unless the makefile specifies
otherwise. @xref{Execution, ,Command Execution}.
+@cindex comments in commands
+@cindex commands, comments in
+@cindex @samp{#} (comments) in commands
The shell that is in use determines whether comments can be written on
command lines, and what syntax they use. When the shell is
@file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
@cindex silent operation
@cindex @@ (in commands)
@cindex command echoing
+@cindex printing of commands
Normally @code{make} prints each command line before it is executed.
We call this @dfn{echoing} because it gives the appearance that you
@section Command Execution
@cindex command execution
@cindex execution of commands
-@cindex shell
+@cindex shell command execution
+@vindex SHELL @r{(command execution)}
When it is time to execute commands to update a target, they are executed
by making a new subshell for each line. (In practice, @code{make} may
@node Parallel, Errors, Execution, Commands
@section Parallel Execution
-
@cindex parallel execution
@cindex execution in parallel
@cindex job slots
@cindex @code{-j}
@cindex @code{--jobs}
+
GNU @code{make} knows how to execute several commands at once.
Normally, @code{make} will execute only one command at a time, waiting
for it to finish before executing the next. However, the @samp{-j} or
terminates for any reason (including a signal) with child processes
running, it waits for them to finish before actually exiting.@refill
+@cindex load average
+@cindex limiting jobs based on load
+@cindex @code{-l} (load average)
+@cindex @code{--max-load}
+@cindex @code{--load-average}
When the system is heavily loaded, you will probably want to run fewer jobs
than when it is lightly loaded. You can use the @samp{-l} option to tell
@code{make} to limit the number of jobs to run at once, based on the load
@node Errors, Interrupts, Parallel, Commands
@section Errors in Commands
-
@cindex error (in commands)
+@cindex command errors
+@cindex exit status (errors)
+
After each shell command returns, @code{make} looks at its exit status.
If the command completed successfully, the next command line is executed
in a new shell; after the last command line is finished, the rule is
For example,
@example
+@group
clean:
-rm -f *.o
+@end group
@end example
@noindent
As a special feature, using the variable @code{MAKE} in the commands
of a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
-(@samp{--just-print}), or @samp{-q} (@samp{--question})
+(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}})
option. Using the @code{MAKE} variable has the same effect as using a
@samp{+} character at the beginning of the command line.
@xref{Instead of Execution, ,Instead of Executing the
Except by explicit request, @code{make} exports a variable only if it
is either defined in the environment initially or set on the command
-line, and if its name consists only of letters, numbers and underscores.
+line, and if its name consists only of letters, numbers, and underscores.
Some shells cannot cope with environment variable names consisting of
characters other than letters, numbers, and underscores.
@cindex directories, printing them
If you use several levels of recursive @code{make} invocations, the
-@samp{-w} or @samp{--print-directory} option can make the output a lot
-easier to understand by showing each directory as @code{make} starts
-processing it and as @code{make} finishes processing it. For example,
-if @samp{make -w} is run in the directory @file{/u/gnu/make},
+@samp{-w} or @w{@samp{--print-directory}} option can make the output a
+lot easier to understand by showing each directory as @code{make}
+starts processing it and as @code{make} finishes processing it. For
+example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
@code{make} will print a line of the form:@refill
@example
A @dfn{variable} is a name defined in a makefile to represent a string
of text, called the variable's @dfn{value}. These values are
-substituted by explicit request into targets, dependencies, commands
+substituted by explicit request into targets, dependencies, commands,
and other parts of the makefile.
Variables and functions in all parts of a makefile are expanded when
read, except for the shell commands in rules, the right-hand sides of
-variable definitions using @samp{=} and the bodies of variable
+variable definitions using @samp{=}, and the bodies of variable
definitions using the @code{define} directive.@refill
Variables can represent lists of file names, options to pass to compilers,
A variable name may be any sequence of characters not containing @samp{:},
@samp{#}, @samp{=}, or leading or trailing whitespace. However,
-variable names containing characters other than letters, numbers and
+variable names containing characters other than letters, numbers, and
underscores should be avoided, as they may be given special meanings in the
future, and with some shells they cannot be passed through the environment to a
sub-@code{make}
the effect of a single dollar sign in a file name or command.
Variable references can be used in any context: targets, dependencies,
-commands, most directives, and new variable values. Here is a common kind
-of example, where a variable holds the names of all the object files in a
-program:
+commands, most directives, and new variable values. Here is an
+example of a common case, where a variable holds the names of all the
+object files in a program:
@example
+@group
objects = program.o foo.o utils.o
program : $(objects)
cc -o program $(objects)
$(objects) : defs.h
+@end group
@end example
Variable references work by strict textual substitution. Thus, the rule
@example
+@group
foo = c
prog.o : prog.c
$(foo)$(foo) -$(foo) prog.c
+@end group
@end example
@noindent
verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
@item
-Values are inherited from the environment. @xref{Environment, ,Variables from the Environment}.
+Variables in the environment become @code{make} variables.
+@xref{Environment, ,Variables from the Environment}.
@item
Several @dfn{automatic} variables are given new values for each rule.
@example
@group
comma:= ,
+empty:=
space:= $(empty) $(empty)
foo:= a b c
bar:= $(subst $(space),$(comma),$(foo))
$(patsubst %@var{pattern},@var{replacement},$(@var{var})
@end example
+and
@example
$(@var{var}:@var{suffix}=@var{replacement})
respectively. @xref{Testing Flags}, for a practical application of
@code{findstring}.@refill
-@item $(filter @var{pattern}@dots{},@var{text})
+@need 750
@findex filter
+@item $(filter @var{pattern}@dots{},@var{text})
Removes all whitespace-separated words in @var{text} that do
@emph{not} match any of the @var{pattern} words, returning only
matching words. The patterns are written using @samp{%}, just like
@noindent
produces the result @samp{src/foo hacks}.
+@c !!! plural convention with dots (be consistent)
@item $(addsuffix @var{suffix},@var{names}@dots{})
@findex addsuffix
The argument @var{names} is regarded as a series of names, separated
@need 1200
@item Assembling and preprocessing assembler programs
@file{@var{n}.o} is made automatically from @file{@var{n}.s} by
-running the assembler, @code{as}. The precise command used is
+running the assembler, @code{as}. The precise command is
@samp{$(AS) $(ASFLAGS)}.@refill
@file{@var{n}.s} is made automatically from @file{@var{n}.S} by
Thus, a rule of the form
@example
-%.o : %.c
+%.o : %.c ; @var{command}@dots{}
@end example
@noindent
to be run for the target, you can give it empty commands (@pxref{Empty
Commands, ,Defining Empty Commands}).@refill
+You can use a last-resort rule to override part of another makefile.
+@xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
+
@node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
@section Old-Fashioned Suffix Rules
@cindex old-fashioned suffix rules
projects / thirdparty / make.git / commitdiff
