diff options
author | Roland McGrath <roland@redhat.com> | 1988-04-23 16:12:14 +0000 |
---|---|---|
committer | Roland McGrath <roland@redhat.com> | 1988-04-23 16:12:14 +0000 |
commit | d5998dcec13c4d3f5efe9584008b8dbfabc28f09 (patch) | |
tree | 61b3e6ee2b2e1985eae6b640a540c5f1093d44d5 | |
download | make-Release1.tar.gz make-Release1.tar.bz2 make-Release1.zip |
Initial revisionRelease1
This version was distributed by RMS in `binutils.tar'.
-rw-r--r-- | make.texinfo | 3705 |
1 files changed, 3705 insertions, 0 deletions
diff --git a/make.texinfo b/make.texinfo new file mode 100644 index 0000000..1c4d5b2 --- /dev/null +++ b/make.texinfo @@ -0,0 +1,3705 @@ +\input texinfo +@setfilename make.info +@synindex vr fn + +@ifinfo +This file documents the GNU Make utility. + +Copyright (C) 1988 Richard M. Stallman. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +@ignore +Permission is granted to process this file through Tex and print the +results, provided the printed document carries copying permission +notice identical to this one except for the removal of this paragraph +(this paragraph not being relevant to the printed manual). + +@end ignore +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end ifinfo +@c +@setchapternewpage odd +@settitle Make + +@titlepage +@sp 6 +@center @titlefont{GNU Make} +@sp 1 +@center A Program for Directing Recompilation +@sp 2 +@center February 1988 +@sp 5 +@center Richard M. Stallman +@page +@vskip 0pt plus 1filll +Copyright @copyright{} 1988 Richard M. Stallman. + +Permission is granted to make and distribute verbatim copies of +this manual provided the copyright notice and this permission notice +are preserved on all copies. + +Permission is granted to copy and distribute modified versions of this +manual under the conditions for verbatim copying, provided that the entire +resulting derived work is distributed under the terms of a permission +notice identical to this one. + +Permission is granted to copy and distribute translations of this manual +into another language, under the above conditions for modified versions. +@end titlepage +@page + +@node Top, Simple,, (DIR) +@chapter Overview of @code{make} + +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}. + +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 +shell command. In fact, @code{make} is not limited to programs. You can +use it to describe any task where some files must be updated automatically +from others whenever the others change. + +To prepare to use @code{make}, you must write a file called the +@dfn{makefile} that describes the relationships among files in your +program, and the states the commands for updating each file. In a program, +typically the executable file is updated from object files, which are in +turn made by compiling source files. + +Once a suitable makefile exists, each time you change some source files, this +simple shell command: + +@example +make +@end example + +@noindent +suffices to perform all necessary recompilations. The @code{make} program +uses the makefile data base and the last-modification times of the files to +decide which of the files need to be updated. For each of those files, it +issues the commands recorded in the data base. + +@iftex +Command arguments to @code{make} can be used to control which files should +be recompiled, or how. @xref{Running}. +@end iftex + +GNU @code{make} was implemented by Richard Stallman and Roland McGrath. + +@menu +* Simple:: A simple example explained. +* Makefiles:: The data base contains rules and variable definitions. +* Rules:: A rule says how and when to remake one file. +* Commands:: A rule contains shell commands that say how to remake. +* Variables:: A variable holds a text string for substitution into rules. +* Conditionals::Makefiles that do one thing or another depending on + variable values. +* Functions:: Functions can do text-processing within @code{make}. + +* Running:: How to run @code{make}; how you can adjust the way + @code{make} uses the makefile. + +* Implicit:: Implicit rules take over if the makefile doesn't say + how a file is to be remade. +* Archives:: How to use @code{make} to update archive files. +* Missing:: Features of other @code{make}s not supported by GNU @code{make}. +* Concept Index::Index of cross-references to where concepts are discussed. +* Name Index:: Index of cross-references for names of @code{make}'s + variables, functions, special targets and directives. +@end menu + +@node Simple,,Top, Top +@section Simple Example of @code{make} + +Suppose we have a text editor consisting of eight C source files and three +header files. We need a makefile to tell @code{make} how to compile and +link the editor. Assume that all the C files include @file{defs.h}, but +only those defining editing commands include @file{commands.h} and only low +level files that change the editor buffer include @file{buffer.h}. + +To recompile the editor, each changed C source file must be recompiled. If +a header file has changed, in order to be safe each C source file that +includes the header file must be recompiled. Each compilation produces an +object file corresponding to the source file. Finally, if any source file +has been recompiled, all the object files, whether newly made or saved from +previous compilations, must be linked together to produce the new +executable editor. + +Here is a straightforward makefile that describes these criteria and says +how to compile and link when the time comes: + +@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 + +main.o : main.c defs.h + cc -c main.c +kbd.o : kbd.c defs.h command.h + cc -c kbd.c +commands.o : command.c defs.h command.h + cc -c commands.c +display.o : display.c defs.h buffer.h + cc -c display.c +insert.o : insert.c defs.h buffer.h + cc -c insert.c +search.o : search.c defs.h buffer.h + cc -c search.c +files.o : files.c defs.h buffer.h command.h + cc -c files.c +utils.o : utils.c defs.h + cc -c utils.c +@end example + +We split each long line into two lines using a backslash-newline; this is +like using one long line, but is easier to read. + +Each file that is generated by a program---that is to say, each file except +for source files---is the @dfn{target} of a @dfn{rule} (@pxref{Rules}). +(In this example, these are the object files such as @file{main.o}, +@file{kbd.o}, etc., and the executable file @file{edit}.) The target +appears at the beginning of a line, followed by a colon. + +After the colon come the target's @dfn{dependencies}: all the files that +are used as input when the target file is updated. A target file needs to +be recompiled or relinked if any of its dependencies changes. In addition, +any dependencies that are themselves automatically generated should be +updated first. In this example, @file{edit} depends on each of the +eight object files; the object file @file{main.o} depends on the source +file @file{main.c} and on the header file @file{defs.h}. + +By default, @code{make} starts with the first rule (not counting rules +whose target names start with @samp{.}). This is called the @dfn{default +goal}. Therefore, we put the rule for the executable program @file{edit} +first. The other rules are processed because their targets appear as +dependencies in the goal. + +After each line containing a target and dependencies come one or more lines +of shell commands that say how to update the target file. These lines +start with a tab to tell @code{make} that they are command lines. +But @code{make} does not know anything about how the commands work. It is up +to you to supply commands that will update the target file properly. All +@code{make} does is execute the commands you have specified when the target +file needs to be updated. + +@subsection How @code{make} Processes This Makefile + +After reading the makefile, @code{make} begins its real work by processing +the first rule, the one for relinking @file{edit}; but before it can fully +process this rule, it must process the rules for the files @file{edit} +depends on: all the object files. Each of these files is processed +according to its own rule. These rules say to update the @samp{.o} file by +compiling its source file. The recompilation must be done if the source +file, or any of the header files named as dependencies, is more recent than +the object file, or if the object file does not exist. + +Before recompiling an object file, @code{make} considers updating its +dependencies, the source file and header files. This makefile does not +specify anything to be done for them---the @samp{.c} and @samp{.h} files +are not the targets of any rules---so nothing needs to be done. But +automatically generated C programs, such as made by Yacc, would be updated +by their own rules at this time. + +After recompiling whichever object files need it, @code{make} can now +decide whether to relink @file{edit}. This must be done if the file +@file{edit} does not exist, or if any of the object files are newer than +it. If an object file was just recompiled, it is now newer than +@file{edit}, so @file{edit} will be relinked. + +@subsection Variables Make Makefiles Simpler + +In our example, we had to list all the object files twice in the rule for +@file{edit} (repeated here): + +@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 +@end example + +@vindex objects +Such duplication is error-prone; if a new object file is added to the +system, we might add it to one list and forget the other. We can eliminate +the risk and simplify the makefile by using a @dfn{variable}. Variables +allow a text string to be defined once and substituted in multiple places +later (@pxref{Variables}). + +It's standard practice for every makefile to have a variable named +@code{objects}, @code{OBJECTS} 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: + +@example +objects = main.o kbd.o commands.o display.o \ + insert.o search.o files.o utils.o +@end example + +@noindent +Then, each place we want to put a list of the object file names, we can +substitute the variable's value by writing @samp{$(objects)} +(@pxref{Variables}). Here is how the rule for @code{edit} looks as a +result: + +@example +edit : $(objects) + cc -o edit $(objects) +@end example + +@subsection Letting @code{make} Deduce the Commands + +It is not necessary to spell out the commands for compiling the individual +C source files, because @code{make} can figure them out: it has an +@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly +named @samp{.c} file using a @samp{cc -c} command. For example, it will +use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into +@file{main.o}. We can therefore omit the commands from the rules for the +object files. @xref{Implicit}.@refill + +When a @samp{.c} file is used automatically in this way, it is also +automatically added to the list of dependencies. We can therefore omit the +@samp{.c} files from the dependencies, provided we omit the commands. + +Here is the entire example, with both of these changes, and a variable +@code{objects} as suggested above: + +@example +objects = main.o kbd.o commands.o display.o \ + insert.o search.o files.o utils.o + +edit : $(objects) + cc -o edit $(objects) + +main.o : defs.h +kbd.o : defs.h command.h +commands.o : defs.h command.h +display.o : defs.h buffer.h +insert.o : defs.h buffer.h +search.o : defs.h buffer.h +files.o : defs.h buffer.h command.h +utils.o : defs.h +@end example + +@noindent +This is how we would write the makefile in actual practice. + +@subsection Another Style of Makefile + +Since the rules for the object files specify only dependencies, no +commands, one can alternatively combine them by dependency instead of by +target. Here is what it looks like: + +@example +objects = main.o kbd.o commands.o display.o \ + insert.o search.o files.o utils.o + +edit : $(objects) + cc -o edit $(objects) + +$(objects): defs.h +kbd.o commands.o files.o : command.h +display.o insert.o search.o files.o : buffer.h +@end example + +@noindent +Here @file{defs.h} is given as a dependency of all the object files; +@file{commands.h} and @file{buffer.h} are dependencies of the specific +object files listed for them. + +Whether this is better is a matter of taste: it is more compact, but some +people dislike it because they find it clearer to put all the information +about each target in one place. + +@node Makefiles, Rules, Simple, Top +@chapter Writing Makefiles + +@cindex makefile +The information that tells @code{make} how to recompile a system comes from +reading a data base called the @dfn{makefile}. + +@menu +* Contents: Makefile Contents. Overview of what you put in a makefile. +* Names: Makefile Names. Where @code{make} finds the makefile. +* Include:: How one makefile can use another makefile. +@end menu + +@node Makefile Contents, Makefile Names, Makefiles, Makefiles +@section What Makefiles Contain + +Makefiles contain four kinds of things: @dfn{rules}, @dfn{variable +definitions}, @dfn{directives} and @dfn{comments}. Rules, variables and +directives are described at length in later chapters.@refill + +@itemize @bullet +@item +A rule says when and how to remake one or more files, called the rule's +@dfn{targets}. It lists the other files that the targets @dfn{depend on}, +and may also give commands to use to create or update the targets. +@xref{Rules}. + +@item +A variable definition is a line that specifies a text string value for +a @dfn{variable} that can be substituted into the text later. The +simple makefile example (@pxref{Simple}) shows a variable definition +for @code{objects} as a list of all object files. @xref{Variables}, +for full details. + +@item +A directive is a command for @code{make} to do something special while +reading the makefile. These include: + +@itemize @bullet +@item +Reading another makefile (@pxref{Include}). + +@item +Deciding (based on the values of variables) whether to use or ignore a +part of the makefile (@pxref{Conditionals}). + +@item +Defining a variable from a verbatim string containing multiple lines +(@pxref{Defining}). +@end itemize + +@item +@cindex comments +@samp{#} in a line of a makefile starts a comment. It and the rest of +the line are ignored. Comments may appear on any of the lines in the +makefile, except within a @code{define} directive, and perhaps within +commands (where the shell decides what is a comment). A line +containing just a comment (with perhaps spaces before it) is +effectively blank, and is ignored. +@end itemize + +@node Makefile Names, Include, Makefile Contents, Makefiles +@section What Name to Give Your Makefile + +By default, when @code{make} looks for the makefile, it tries the names +@file{./makefile} or @file{./Makefile} in that order. So normally you call +your makefile by one of these two names, and @code{make} finds it +automatically. We recommend @file{Makefile} because it appears prominently +near the beginning of a directory listing. + +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 + +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 +@var{name}} tell @code{make} to read the file @var{name} as the makefile. +If you use more than one @samp{-f} option, you can specify several +makefiles. All the makefiles are effectively concatenated in the order +specified. The default makefile names @file{./makefile} and +@file{./Makefile} are not used if you specify @samp{-f}.@refill + +@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 in communication between recursive +invocations of @code{make} (@pxref{Recursion}). It usually isn't +desirable to set the environment variable before a top-level invocation +of @code{make}, because it is usually better not to mess with a makefile +from outside. + +Some users are tempted to set @code{MAKEFILES} in the environment +automatically on login, and program makefiles to expect this to be done. +This is a very bad idea, because such makefiles will fail to work if run by +anyone else. It is much better to write explicit @code{include} directives +in the makefiles. + +@node Include,, Makefile Names, Makefiles +@section Including Other Makefiles + +@findex include +The @code{include} directive tells @code{make} to suspend reading the +current makefile and read another makefile before continuing. The +directive is a line in the makefile that looks like this: + +@example +include @var{filename} +@end example + +Extra spaces are allowed and ignored at the beginning of the line, but a +tab is not allowed. (If the line begins with a tab, it will be considered +a command line.) Whitespace is required between @code{include} and +@var{filename}; extra whitespace is ignored there and at the end of the +directive. A comment starting with @samp{#} is allowed at the end of the +line. + +Reading of the containing makefile is temporarily suspended while the file +@var{filename} is read as a makefile. When that is finished, @code{make} +goes on with reading the makefile in which the directive appears. + +The default goal target is never taken from an included makefile +(@pxref{Goals}). + +One occasion for using @code{include} directives is when several programs, +handled by individual makefiles in various directories, need to use a +common set of variable definitions (@pxref{Setting}) or pattern rules +(@pxref{Pattern Rules}). + +If the specified name does not start with a slash, and the file is not +found in the current directory, several other directories are searched. +First, any directories you have specified with the @samp{-I} option are +searched (@pxref{Options}). Then the following directories (if they +exist) are searched, in this order: @file{/usr/gnu/include}, +@file{/usr/local/include}, @file{/usr/include}.@refill + +@node Rules, Commands, Makefiles, Top +@chapter Writing Rules + +@cindex rule +@cindex target +@cindex dependency +A @dfn{rule} appears in the makefile and says when and how to remake +certain files, called the rule's @dfn{targets} (usually only one per rule). +It lists the other files that are the @dfn{dependencies} of the target, and +@dfn{commands} to use to create or update the target. + +The order of rules is not significant, except for determining the +@dfn{default goal}: the target for @code{make} to consider, if you do not +otherwise specify one. The default goal comes from the first rule (not +counting included makefiles) whose target does not start with a period. +Therefore, the first rule is normally one for compiling the entire program +or all the programs described by the makefile. @xref{Goals}. + +@menu +* Rule Example:: An explained example of a rule. +* Rule Syntax:: General syntax of rules, with explanation. + +* Wildcards:: Using wildcard characters like `*' in file names. +* Directory Search:: Searching other directories for source files. + +* Phony Targets:: Using a target that isn't a real file's name. +* Special Targets:: Targets with special built-in meanings. +* Empty Targets:: Real files that are empty--only the date matters. +* Multiple Targets:: When it is useful to have several targets in a rule. +* Multiple Rules:: Using several rules with the same target. +* Double-Colon:: Special kind of rule allowing + several independent rules for one target. +* Commands:: Special features and details of how commands + in a rule are executed. +@end menu + +@ifinfo +@node Rule Example, Rule Syntax, Rules, Rules +@isubsection Rule Example + +Here is an example of a rule: + +@example +foo.o : foo.c defs.h # module for twiddling the frobs + cc -c -g foo.c +@end example + +Its target is @file{foo.o} and its dependencies are @file{foo.c} and +@file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}. +The command line starts with a tab to identify it as a command. + +This rule says two things: + +@itemize @bullet +@item +How to decide whether @file{foo.o} is out of date: it is out of date +if it does not exist, or if either @file{foo.c} or @file{defs.h} is +more recent than it. + +@item +How to update the file @file{foo.o}: by running @code{cc} as stated. +The command does not explicitly mention @file{defs.h}, but we presume +that @file{foo.c} includes it, and that that is why @file{defs.h} was +added to the dependencies. +@end itemize +@end ifinfo + +@node Rule Syntax, Wildcards, Rule Example, Rules +@section Rule Syntax + +In general, a rule looks like this: + +@example +@var{targets} : @var{dependencies} + @var{command} + @var{command} + ... +@end example + +@noindent +or like this: + +@example +@var{targets} : @var{dependencies} ; @var{command} + @var{command} + @var{command} + ... +@end example + +The @var{targets} are file names, separated by spaces. Wild card +characters may be used (@pxref{Wildcards}) and a name of the form +@file{@var{a}(@var{m})} represents member @var{m} in archive file @var{a} +(@pxref{Archive Members}). Usually there is only one target per rule, but +occasionally there is a reason to have more (@pxref{Multiple Targets}). + +The @var{command} lines start with a tab character. The first command may +appear on the line after the dependencies, with a tab character, or may +appear on the same line, with a semicolon. Either way, the effect is the +same. @xref{Commands}. + +Because dollar signs are used to start variable references, if you really +want a dollar sign in the rule you must write two of them (@samp{$$}). +@xref{Variables}. A long line may be split by inserting a backslash +followed by a newline, but this is not required, as there is no limit on +the length of a line. + +A rule tells @code{make} two things: when the targets are out of date, +and how to update them when necessary. + +The criterion for being out of date is specified in terms of the +@var{dependencies}, which consist of file names separated by spaces. +(Wildcards and archive members are allowed here too.) A target is out of +date if it does not exist or if it is older than any of the dependencies +(by comparison of last-modification times). The idea is that the contents +of the target file are computed based on information in the dependencies, +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 +executed by the shell (normally @samp{sh}), but with some extra features +(@pxref{Commands}). + +@node Wildcards, Directory Search, Rule Syntax, Rules +@section Using Wildcards Characters in File Names +@cindex wildcard +@cindex file name + +A single file name can specify many files using @dfn{wildcard characters}. +The wildcard characters in @code{make} are @samp{*}, @samp{?} and +@samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c} +specifies a list of all the files (in the working directory) whose names +end in @samp{.c}.@refill + +Wildcard expansion happens automatically in targets, in dependencies, and +in commands. In other contexts, wildcard expansion happens only if you +request it explicitly with the @code{wildcard} function. + +The special significance of a wildcard character can be turned off by +preceding it with a backslash. Thus, @file{foo\*bar} would refer to a +specific file whose name consists of @samp{foo}, an asterisk, and +@samp{bar}.@refill + +@menu +* Examples: Wildcard Examples. Some simple examples. +* Pitfall: Wildcard Pitfall. @code{*.o} won't do what you want! +* Function: Wildcard Function. + How to do wildcard expansion when defining a variable + using the function @code{wildcard}. +@end menu + +@node Wildcard Examples, Wildcard Function, Wildcards, Wildcards +@subsection Wildcard Examples + +Wildcards can be used in the commands of a rule. For example, here is a +rule to delete all the object files: + +@example +clean: + rm -f *.o +@end example + +Wildcards are also useful in the dependencies of a rule. With the +following rule in the makefile, @samp{make print} will print all the +@samp{.c} files that have changed since the last time you printed them: + +@example +print: *.c + lpr -p $? + touch print +@end example + +@noindent +This rule uses @file{print} as an empty target file; @pxref{Empty Targets}. + +Wildcard expansion does not happen when you define a variable. Thus, if +you write this: + +@example +objects=*.o +@end example + +@noindent +then the value of the variable @code{objects} is the actual string +@samp{*.o}. However, if you use the value of @code{objects} in a target, +dependency or command, wildcard expansion will take place at that time. + +@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards +@subsection Pitfalls of Using 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 +executable file @file{foo} is made from all the object files in the +directory, and you write this: + +@example +objects=*.o + +foo : $(objects) + cc -o foo $(CFLAGS) $(objects) +@end example + +@noindent +The value of @code{objects} is the actual string @samp{*.o}. Wildcard +expansion happens in the rule for @file{foo}, so that each @emph{existing} +@samp{.o} file becomes a dependency of @file{foo} and will be recompiled if +necessary. + +But what if you delete all the @samp{.o} files? Then @samp{*.o} will +expand into @emph{nothing}. The target @file{foo} will have no +dependencies and would be remade by linking no object files. This is not +what you want! + +Actually you can use wildcard expansion for this purpose, but you need more +sophisticated techniques, including the @code{wildcard} function and string +substitution. +@ifinfo +@xref{Wildcard Function}. +@end ifinfo +@iftex +These are described in the following section. +@end iftex + +@node Wildcard Function,, Wildcard Pitfall, Wildcards +@subsection The Function @code{wildcard} +@findex wildcard + +Wildcard expansion happens automatically in rules. But wildcard expansion +does not normally take place when a variable is set, or inside the +arguments of a function. If you want to do wildcard expansion in such +places, you need to use the @code{wildcard} function, like this: + +@example +$(wildcard @var{pattern}) +@end example + +This string, used anywhere in a makefile, is replaced by a space-separated +list of names of existing files that match the pattern @var{pattern}. + +One use of the @code{wildcard} function is to get a list of all the C source +files in a directory, like this: + +@example +$(wildcard *.c) +@end example + +We can change the list of C source files into a list of object files by +substituting @samp{.o} for @samp{.c} in the result, like this: + +@example +$(subst .c,.o,$(wildcard *.c)) +@end example + +Here we have used another function, @code{subst} (@pxref{Text Functions}). + +Thus, a makefile to compile all C source files in the directory and then +link them together could be written as follows: + +@example +objects=$(subst .c,.o,$(wildcard *.c)) + +foo : $(objects) + cc -o foo $(LDFLAGS) $(objects) +@end example + +@noindent +(This takes advantage of the implicit rule for compiling C programs, so +there is no need to write explicit rules for compiling the files.) + +@node Directory Search, Phony Targets, Wildcards, Rules +@section Searching Directories for Dependencies +@vindex VPATH +@cindex directory search + +For large systems, it is often desirable to put sources in a separate +directory from the binaries. The @code{VPATH} feature makes this easier. + +The value of the variable @code{VPATH} is a list of directories which +@code{make} should search (in the order specified) for dependency files. +The directory names are separated by colons. For example: + +@example +VPATH = src:../headers +@end example + +@noindent +specifies a path containing two directories, @file{src} and @file{../headers}. + +When a file listed as a dependency does not exist in the current directory, +the directories listed in @code{VPATH} are searched for a file with that +name. If a file is found in one of them, that file becomes the dependency. +Rules may then specify the names of source files as if they all existed in +the current directory. + +Using the value of @code{VPATH} set in the previous example, a rule like this: + +@example +foo.o : foo.c +@end example + +@noindent +is interpreted as if it were written like this: + +@example +foo.o : src/foo.c +@end example + +@noindent +assuming the file @file{foo.c} does not exist in the current directory but +is found in the directory @file{src}. + +But what about the rule's commands? The @code{VPATH} directory search +cannot change the commands; they will execute as written. You need to +write the commands so that they will use the file names that @code{make} +finds. This is done with the @dfn{automatic variables} such as @samp{$^} +(@pxref{Automatic}). For instance, the value of @samp{$^} is a list of all +the dependencies of the rule, including the names of the directories in +which they were found, and the value of @samp{$@@} is the target. Thus: + +@example +foo.o : foo.c + cc -c $(CFLAGS) $^ -o $@@ +@end example + +@noindent +The variable @code{CFLAGS} exists so you can specify flags for C +compilation by changing its value; we use it here for consistency so it +will 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 +extract just the first dependency from the entire list, as shown here +(@pxref{Filename Functions}): + +@example +foo.o : foo.c defs.h hack.h + cc -c $(CFLAGS) $(firstword $^) -o $@@ +@end example + +@noindent +Here the value of @samp{$^} is something like @samp{src/foo.c +../headers/defs.h hack.h}, from which @samp{$(firstword $^)} extracts just +@samp{src/foo.c}.@refill + +@subsection Directory Search and Implicit Rules + +The search through the directories in @code{VPATH} happens also during +consideration of implicit rules (@pxref{Implicit}). + +For example, when a file @file{foo.o} has no explicit rule, @code{make} +considers implicit rules, such as to compile @file{foo.c} if that file +exists. If such a file is lacking in the current directory, the +directories in @code{VPATH} are searched for it. If @file{foo.c} exists +(or is mentioned in the makefile) in any of the directories, the implicit +rule for C compilation is applicable. + +The commands of all the built-in implicit rules normally use automatic +variables as a matter of necessity; consequently they will use the file +names found by directory search with no extra effort. + +@node Phony Targets, Empty Targets, Directory Search, Rules +@section 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 +requested. + +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. +Here is an example: + +@example +clean: + rm *.o temp +@end example + +@noindent +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}. + +@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 +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: + +@example +.PHONY : clean +@end example + +@noindent +Once this is done, @code{make} will run the commands regardless of whether +there is a file named @file{clean}. + +A phony target should not be a dependency of a real target file; strange +things can result from that. As long as you don't do that, the phony +target commands will be executed only when the phony target is a goal +(@pxref{Goals}). + +Phony targets can have dependencies. When one directory contains multiple +programs, it is most convenient to describe all of the programs in one +makefile @file{./Makefile}. Since the target remade by default will be the +first one in the makefile, it is common to make this a phony target named +@samp{all} and give it, as dependencies, all the individual programs. For +example: + +@example +all : prog1 prog2 prog3 +.PHONY : all + +prog1 : prog1.o utils.o + cc -o prog1 prog1.o utils.o + +prog2 : prog2.o + cc -o prog2 prog2.o + +prog3 : prog3.o sort.o utils.o + cc -o prog3 prog3.o sort.o utils.o +@end example + +@noindent +Now you can say @code{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 +of the other. For example, here @samp{make cleanall} will delete the +object files, the difference files, and the file @file{program}: + +@example +cleanall : cleanobj cleandiff + rm program + +cleanobj : + rm *.o + +cleandiff : + rm *.diff +@end example + +@node Empty Targets, Special Targets, Phony Targets, Rules +@section Empty Target Files to Record Events +@cindex empty target + +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. +Unlike a phony target, this target file can really exist; but the file's +contents do not matter, and usually are empty. + +The purpose of the empty target file is to record, with its +last-modification-time, when the rule's commands were last executed. It +does so because one of the commands is a @code{touch} command to update the +target file. + +The empty target file must have some dependencies. When you ask to remake +the empty target, the commands are executed if any dependency is more +recent than the target; in other words, if a dependency has changed since +the last time you remade the target. Here is an example: + +@example +print: foo.c bar.c + lpr -p $? + touch print +@end example + +@noindent +With this rule, @samp{make print} will execute the @code{lpr} command if +either source file has changed since the last @samp{make print}. The +automatic variable @samp{$?} is used to print only those files that have +changed (@pxref{Automatic}). + +@node Special Targets, Multiple Targets, Empty Targets, Rules +@section Special Built-in Target Names +@cindex special targets + +Certain names have special meanings if they appear as targets. + +@table @code +@item .PHONY +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}. + +@item .SUFFIXES +The dependencies of the special target @code{.SUFFIXES} are the list +of suffixes to be used in checking for suffix rules (@pxref{Suffix +Rules}). + +@item .DEFAULT +The commands specified for @code{.DEFAULT} are used for any target for +which no other commands are known (either explicitly or through an +implicit rule). If @code{.DEFAULT} commands are specified, every +nonexistent file mentioned as a dependency will have these commands +executed on its behalf. @xref{Search Algorithm}. + +@item .PRECIOUS +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. +@xref{Interrupts}. + +@item .IGNORE +Simply by being mentioned as a target, @code{.IGNORE} says to ignore +errors in execution of commands. The dependencies and commands for +@code{.IGNORE} are not meaningful. + +@samp{.IGNORE} exists for historical compatibility. Since +@code{.IGNORE} affects every command in the makefile, it is not very +useful; we recommend you use the more selective ways to ignore errors +in specific commands (@pxref{Errors}). + +@item .SILENT +Simply by being mentioned as a target, @code{.SILENT} says not to +print commands before executing them. The dependencies and commands +for @code{.SILENT} are not meaningful. + +@samp{.SILENT} exists for historical compatibility. We recommend you +use the more selective ways to silence specific commands +(@pxref{Echoing}). +@end table + +An entire class of special targets have names made of the concatenation of +two implicit rule suffixes (two members of the list of dependencies of +@code{.SUFFIXES}). Such special targets are suffix rules, an obsolete way +of defining implicit rules (but a way still widely used). In principle, +any target name could be special in this way if you break it in two and add +both pieces to the suffix list. In practice, suffixes normally begin with +@samp{.}, so these special target names also begin with @samp{.}. +@xref{Suffix Rules}. + +@node Multiple Targets, Multiple Rules, Special Targets, Rules +@section Multiple Targets in a Rule + +A rule with multiple targets is equivalent to writing many rules, each with +one target, and all identical aside from that. This is useful in two cases. + +@itemize @bullet +@item +You want just dependencies, no commands. For example: + +@example +kbd.o commands.o files.o: command.h +@end example + +@noindent +gives an additional dependency to each of the three object files +mentioned. + +@item +Identical commands work for all the targets. The automatic variable +@samp{$@@} can be used to substitute the target to be remade into the +commands (@pxref{Automatic}). For example: + +@example +bigoutput littleoutput : text.g + generate text.g -$(subst output,,$@@) > $@@ +@end example + +@noindent +is equivalent to + +@example +bigoutput : text.g + generate text.g -big > bigoutput +littleoutput : text.g + generate text.g -little > littleoutput +@end example + +@noindent +Here we assume the hypothetical program @code{generate} makes two +types of output, one if given @samp{-big} and one if given +@samp{-little}.@refill +@end itemize + +@node Multiple Rules, Double-Colon, Multiple Targets, Rules +@section Multiple Rules for One Target + +One file can be the target of several rules if at most one rule has commands. +The other rules can only have dependencies. All the dependencies mentioned +in all the rules are merged into one list of dependencies for the target. +If the target is older than any dependency from any rule, the commands are +executed. + +An extra rule with just dependencies can be used to give a few extra +dependencies to many files at once. For example, one usually has a +variable named @code{objects} containing a list of all the compiler output +files in the system being made. An easy way to say that all of them must +be recompiled if @file{config.h} changes is to write + +@example +objects = foo.o bar.o +foo.o : defs.h +bar.o : defs.h test.h +$(objects) : config.h +@end example + +This could be inserted or taken out without changing the rules that really +say how to make the object files, making it a convenient form to use if +you wish to add the additional dependency intermittently. + +Another wrinkle is that the additional dependencies could be specified with +a variable that you could set with a command argument to @code{make} +(@pxref{Overriding}). For example, + +@example +extradeps= +$(objects) : $(extradeps) +@end example + +@noindent +means that the command @samp{make extradeps=foo.h} will consider +@file{foo.h} as a dependency of each object file, but plain @samp{make} +will not. + +If none of the explicit rules for a target has commands, then @code{make} +searches for an applicable implicit rule to find some commands. +@xref{Implicit}. + +@node Double-Colon,, Multiple Rules, Rules +@section Double-Colon Rules +@cindex double-colon rule + +@dfn{Double-colon} rules are rules written with @samp{::} instead of +@samp{:} after the target names. They are handled differently from +ordinary rules when the same target appears in more than one rule. + +When a target appears in multiple rules, all the rules must be the same +type: all ordinary, or all double-colon. If they are double-colon, each of +them is independent of the others. Each double-colon rule's commands are +executed if the target is older than any dependencies of that rule. This +can result in executing none, any or all of the double-colon rules. + +The double-colon rules for a target are executed in the order they appear +in the makefile. However, the cases where double-colon rules really make +sense are those where the order of executing the commands would not matter. + +Each double-colon rule should specify commands; if it does not, an +implicit rule will be used if one applies. @xref{Implicit}. + +@node Commands, Variables, Rules, Top +@chapter Writing the Commands in Rules +@cindex command (in rules) + +The commands of a rule consist of shell command lines to be executed one by +one. Each command line must start with a tab, except that the first +command line may be attached to the target-and-dependencies line with a +semicolon in between. Blank lines and lines of just comments may appear +among the command lines; they are ignored. + +Users use many different shell programs, but commands in makefiles are +always interpreted by @file{/bin/sh} unless the makefile specifies otherwise. + +Whether comments can be written on command lines, and what syntax they use, +is under the control of the shell that is in use. If it is @file{/bin/sh}, +a @samp{#} at the start of a word starts a comment. + +@menu +* Echoing:: Normally commands are echoed before execution, + but you can control this in several ways. +* Execution:: How commands are executed. +* Errors:: What happens after an error in command execution. + How to ignore errors in certain commands. +* Interrupts:: If a command is interrupted or killed, + the target may be deleted. +* Recursion:: Invoking @code{make} from commands in makefiles. +* Sequences:: Defining canned sequences of commands. +@end menu + +@node Echoing, Execution, Commands, Commands +@section Command Echoing + +@cindex echoing (of commands) +@cindex silent operation +@cindex @@ (in commands) +@cindex -n +Normally @code{make} prints each command line before it is executed. We +call this @dfn{echoing} because it gives the appearance that you are typing +the commands yourself. + +When a line starts with @samp{@@}, it is normally not echoed. The +@samp{@@} is discarded before the command is passed to the shell. Typically +you would use this for a command whose only effect is to print something, +such as an @code{echo} command. + +When @code{make} is given the flag @samp{-n}, echoing is all that happens, +no execution. @xref{Options}. In this case and only this case, even the +commands starting with @samp{@@} are printed. This flag is useful for +finding out which commands @code{make} thinks are necessary without +actually doing them. + +@cindex -s +@findex .SILENT +The @samp{-s} flag to @code{make} prevents all echoing, as if all commands +started with @samp{@@}. A rule in the makefile for the special target +@code{.SILENT} has the same effect (@pxref{Special Targets}). +@code{.SILENT} is essentially obsolete since @samp{@@} is more +general.@refill + +@node Execution, Errors, Echoing, Commands +@section Command Execution +@cindex execution +@cindex shell + +When it is time to execute commands to update a target, they are executed +one at a time by making a new subshell for each line. (In practice, +@code{make} may take shortcuts that do not affect the results.) + +This implies that shell commands such as @code{cd} that set variables local +to each process will not affect the following command lines. If you want +to use @code{cd} to affect the next command, put the two on a single line +with a semicolon between them. Then @code{make} will consider them a +single command and pass them, together, to a shell which will execute them +in sequence. For example: + +@example +foo : bar/lose + cd bar; gobble lose > ../foo +@end example + +If you would like to split a single shell command into multiple lines of +text, you must use a backslash at the end of all but the last subline. +Such a sequence of lines is combined into a single line, by deleting the +backslash-newline sequences, before passing it to the shell. Thus, the +following is equivalent to the preceding example: + +@group +@example +foo : bar/lose + cd bar; \ + gobble lose > ../foo +@end example +@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. + +Unlike most variables, the variable @code{SHELL} will not be set from the +environment, except in a recursive @code{make}. This is because the +environment variable @code{SHELL} is used to specify your personal choice +of shell program for interactive use. It would be very bad for personal +choices like this to affect the functioning of makefiles. +@xref{Environment}. + +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 + +@cindex error (in commands) +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, or after the last command line the rule is finished. + +If there is an error (the exit status is nonzero), @code{make} gives up on +the current rule, and perhaps on all rules. + +Sometimes it does not matter whether a command fails. For example, you +may use the @code{mkdir} command to insure that a directory exists. If +the directory already exists, @code{mkdir} will report an error, but you +probably want @code{make} to continue regardless. + +@cindex - (in commands) +To ignore errors in a command line, write a @samp{-} at the beginning of +the line's text (after the initial tab). The @samp{-} is discarded before +the command is passed to the shell for execution. + +@cindex -i +@findex .IGNORE +When @code{make} is run with the @samp{-i} flag, errors are ignored in +all commands of all rules. A rule in the makefile for the special target +@code{.IGNORE} has the same effect. These ways of ignoring errors are +obsolete because @samp{-} is more general. + +When errors are to be ignored, because of either a @samp{-} or the +@samp{-i} flag, @code{make} treats an error return just like success. + +@cindex -k +When an error happens that @code{make} has not been told to ignore, +it implies that the current target cannot be correctly remade, and neither +can any other that depends on it either directly or indirectly. No further +commands will be executed for these targets, since their preconditions +have not been achieved. + +Normally @code{make} gives up immediately in this circumstance, returning a +nonzero status. However, 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, @samp{make -k} +will continue compiling other object files even though it already knows +that linking them will be impossible. @xref{Options}. + +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. + +@node Interrupts, Recursion, Errors, Commands +@section Interrupting or Killing @code{make} +@cindex interrupt +@cindex signal +@cindex deletion of target files + +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. + +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 +could appear to be valid, since it is more recent than the dependencies. + +@findex .PRECIOUS +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. + +@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: + +@example +subsystem: + cd subdir; $(MAKE) +@end example + +@noindent +or, equivalently, this (@pxref{Options}): + +@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}. + +@vindex MAKELEVEL +As a special feature, the variable @code{MAKELEVEL} is changed when it is +passed down from level to level. This variable's value is a string which +is the depth of the level as a decimal number. The value is @samp{0} for +the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a +sub-sub-@code{make}, and so on. The incrementation happens when +@code{make} sets up the environment for a command.@refill + +The main use of @code{MAKELEVEL} is to test it in a conditional directive +(@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 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}. + +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 + +If you don't want to pass the other the flags down, you must change the +value of @code{MAKEFLAGS}, like this: + +@example +subsystem: + cd subdir; $(MAKE) MAKEFLAGS= +@end example + +@vindex MFLAGS +A similar variable @code{MFLAGS} exists also, for historical compatibility. +It has the same value as @code{MAKEFLAGS} except that a hyphen is added at +the beginning if it is not empty. @code{MFLAGS} was traditionally used +explicitly in the recursive @code{make} command, like this: + +@example +subsystem: + cd subdir; $(MAKE) $(MFLAGS) +@end example + +@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. + +@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. + +@node Sequences,, Recursion, Commands +@section Defining Canned Command Sequences +@cindex sequences of commands + +When the same sequence of commands is useful in making various targets, you +can define it as a canned sequence with the @code{define} directive, and +refer to the canned sequence from the rules for those targets. The canned +sequence is actually a variable, so the name must not conflict with other +variable names. + +Here is an example of defining a canned sequence of commands: + +@example +define run-yacc +yacc $(firstword $^) +mv y.tab.c $@@ +endef +@end example + +@noindent +Here @code{run-yacc} is the name of the variable being defined; +@code{endef} marks the end of the definition; the lines in between are the +commands. The @code{define} directive does not expand variable references +and function calls in the canned sequence; the @samp{$} characters, +parentheses, variable names, and so on, all become part of the value of the +variable you are defining. @xref{Defining}, for a complete explanation of +@code{define}. + +The first command in this example runs Yacc on the first dependency (of +whichever rule uses the canned sequence). The output file from Yacc is +always named @file{y.tab.c}. The second command moves the output to the +rule's target file name. + +To use the canned sequence, substitute the variable into the commands of a +rule. You can substitute it like any other variable (@pxref{Reference}). +But usually substitution alone is not enough, because the commands in a +canned sequence typically contain variable references that should be +expanded each time the canned sequence is used. To make this work, you +need to use the @code{expand} function when you substitute the sequence +(@pxref{Expand Function}). Here is how it looks: + +@example +foo.c : foo.y + $(expand $(run-yacc)) +@end example + +@noindent +The @code{expand} function will substitute @samp{foo.y} for the variable +@samp{$^} when it occurs in @code{run-yacc}'s value, and @samp{foo.c} for +@samp{$@@}.@refill + +This is a realistic example, but this particular one is not needed in +practice because @code{make} has an implicit rule to figure out these +commands based on the file names involved. @xref{Implicit}. + +@node Variables, Conditionals, Commands, Top +@chapter How to Use Variables +@cindex variable +@cindex value + +A @dfn{variable} is a name defined within @code{make} to represent a string +of text, called the variable's @dfn{value}. These values can be +substituted by explicit request into targets, dependencies, commands and +other parts of the makefile. + +Variables can represent lists of file names, options to pass to compilers, +programs to run, directories to look in for source files, directories to +write output in, or anything else you can imagine. + +A variable name may be any sequence characters not containing @samp{:}, +@samp{#}, @samp{=}, tab characters or leading or trailing spaces. However, +variable names containing nonalphanumeric characters should be avoided, as +they may be given special meanings in the future. + +It is traditional to use upper case letters in variable names, but we +recommend using lower case letters for variable names that serve internal +purposes in the makefile, and reserving upper case for parameters that +control implicit rules or for parameters that the user should override with +command options (@pxref{Overriding}). + +@menu +* Reference:: How to use the value of a variable. +* Values:: All the ways variables get their values. +* Setting:: How to set a variable in the makefile. +* Override Directive:: Setting a variable in the makefile + even if the user has set it with a command argument. +* Defining:: An alternate way to set a variable to a verbatim string. +* Environment:: Variable values can come from the environment. +@end menu + +@node Reference, Values, Variables, Variables +@section Reference to Variables +@cindex reference to variables +@cindex $ + +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 +@samp{$@{foo@}} is a valid reference to the variable @code{foo}. This +special significance of @samp{$} is why you must write @samp{$$} to have +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: + +@example +objects = program.o foo.o utils.o +program : $(objects) + cc -o program $(objects) + +$(objects) : defs.h +@end example + +Variable references work by strict textual substitution. Thus, the rule + +@example +foo = c +prog.o : prog.c + $(foo)$(foo) prog.c +@end example + +@noindent +could be used to compile a C program @file{prog.c}. (Since spaces around +the variable value are ignored in variable assignments, the value of +@code{foo} is precisely @samp{c}.) + +A dollar sign followed by a character other than a dollar sign, +open-parenthesis or open-brace treats that single character as the variable +name. Thus, you could reference the variable @code{x} with @samp{$x}. +However, this practice is strongly discouraged, except with the automatic +variables (@pxref{Automatic}). + +@node Values, Setting, Reference, Variables +@section How Variables Get Their Values + +Variables can get values in several different ways: + +@itemize @bullet +@item +You can specify an overriding value when you run @code{make}. +@xref{Overriding}. + +@item +You can specify a value in the makefile, either with an assignment +(@pxref{Setting}) or with a verbatim definition (@pxref{Defining}). + +@item +Values are inherited from the environment. @xref{Environment}. + +@item +Several @dfn{automatic} variables are given new values for each rule. +@xref{Automatic}. + +@item +Several variables have constant initial values. @xref{Implicit +Variables}. +@end itemize + +@node Setting, Override Directive, Values, Variables +@section Setting Variables +@cindex setting variables + +To set a variable from the makefile, write a line starting with the +variable name followed by @samp{=}. Whatever follows the @samp{=} on the +line becomes the value. For example, + +@example +objects = main.o foo.o bar.o utils.o +@end example + +@noindent +defines a variable named @code{objects}. Spaces around the variable name +are ignored, and so are spaces after the @samp{=} or at the end of the +line. + +The line that sets the variable can contain variable references. Such +references are replaced by their values before the new variable is set. +The value given to the new variable does not contain variable references; +it contains the substuted values. Thus, + +@example +x = foo +y = $(x) bar +@end example + +@noindent +is equivalent to + +@example +x = foo +y = foo bar +@end example + +This gives you a way to introduce leading or trailing spaces into variable +values. Such spaces are discarded from your input before substitution of +variable references and function calls; this means you can include leading +or trailing spaces in a variable value by protecting them with variable +references, like this: + +@example +nullstring= +space=$(nullstring) $(nullstring) +@end example + +@noindent +Here the value of the variable @code{space} is precisely one space. + +There is no limit on the length of the value of a variable except the +amount of swapping space on the computer. When a variable definition is +long, it is a good idea to break it into several lines by inserting +backslash-newline at convenient places in the definition. This will not +affect the functioning of @code{make}, but it will make the makefile easier +to read. + +Most variable names are considered to have the empty string as a value if +you have never set them. Several variables have built-in initial values +that are not empty, but can be set by you in the usual ways +(@pxref{Implicit Variables}). Several special variables are set +automatically to a new value for each rule; these are called the +@dfn{automatic} variables (@pxref{Automatic}). + +@node Override Directive, Defining, Setting, Variables +@section The @code{override} Directive +@findex override + +If a variable has been set with a command argument (@pxref{Overriding}), +then ordinary assignments in the makefile are ignored. If you want to set +the variable in the makefile even though it was set with a command +argument, you can use an @code{override} directive, which is a line that +looks like this: + +@example +override @var{variable} = @var{value} +@end example + +The @code{override} directive was not invented for escalation in the war +between makefiles and command arguments. It was invented so you can alter +and add to values that the user specifies with command arguments. + +For example, suppose you always want the @samp{-g} switch when you run the +C compiler, but you would like to allow the user to specify the other +switches with a command argument just as usual. You could use this +@code{override} directive: + +@example +override CFLAGS = $(CFLAGS) -g +@end example + +@node Defining, Environment, Override Directive, Variables +@section Defining Variables Verbatim +@findex define +@findex endef + +Another way to set the value of a variable is to use the @code{define} +directive. This directive has a different syntax and provides different +features, and its intended use is for defining canned sequences of commands +(@pxref{Sequences}). But the variables made with @code{define} are just +like those made the usual way. Only the variable's value matters. + +The @code{define} directive is followed on the same line the name of the +variable and nothing more. The value to give the variable appears on the +following lines. These lines are used verbatim; the character @samp{$} is +not treated specially and whitespace is not changed. The end of the value +is marked by a line containing just the word @code{endef}. + +@example +define two-lines +echo foo +echo $100 +endef +@end example + +Aside from syntax, there are two differences between @code{define} and +ordinary variable assignments: + +@itemize @bullet +@item +The value assigned in an ordinary variable assignment is scanned for +variable references and function calls, which are expanded. The +@code{define} commands are used verbatim, with no replacement. + +@item +The value in an ordinary assignment cannot contain a newline. The text in +a @code{define} can be multiple lines; the newlines that separate the lines +become part of the variable's value. (The final newline which is always +present does not become part of the variable value.) +@end itemize + +@node Environment,, Defining, Variables +@section Variables from the Environment + +@cindex environment +Variables in @code{make} can come from the environment with which +@code{make} is run. Every environment variable that @code{make} sees when +it starts up is transformed into a @code{make} variable with the same name +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}.) + +By setting the variable @code{CFLAGS} in your environment, you can cause +all C compilations in most makefiles to use the compiler switches you +prefer. This is safe for variables with standard or conventional meanings +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.) + +When @code{make} is invoked recursively, variables defined in the outer +invocation are automatically passed to inner invocations through the +environment (@pxref{Recursion}). This is the main purpose of turning +environment variables into @code{make} variables, and it requires no +attention from you. + +Other use of variables from the environment is not recommended. It is not +wise for makefiles to depend for their functioning on environment variables +set up outside their control, since this would cause different users to get +different results from the same makefile. This is against the whole +purpose of most makefiles. + +Such problems would be especially likely with the variable @code{SHELL}, +which is normally present in the environment to specify the user's choice +of interactive shell. It would be very undesirable for this choice to +affect @code{make}. So @code{make} ignores the environment value of +@code{SHELL} (and @code{SHFLAGS}) 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 + +@cindex conditionals +A @dfn{conditional} causes part of a makefile to be obeyed or ignored +depending on the values of variables. Conditionals can compare the value +of one variable with another, or the value of a variable with a constant +string. + +@menu +* Example: Conditional Example. An annotated example. +* Syntax: Conditional Syntax. Precise rules for syntax of conditionals. +* Flags: Testing Flags. Conditionals testing flags such as @samp{-t}. +@end menu + +@node Conditional Example, Conditional Syntax, Conditionals, Conditionals +@section Example of a Conditional + +This conditional tells @code{make} to use one set of libraries if the +@code{CC} variable is @samp{gcc}, and a different set of libraries +otherwise. It works by controlling which of two command lines will be used +as the command for a rule. The result is that @samp{CC=gcc} as an argument +to @code{make} not only changes which compiler is used but also which +libraries are linked. + +@example +libs_for_gcc = -lgnu +normal_libs = + +foo: $(objects) +ifeq ($(CC),gcc) + $(CC) -o foo $(objects) $(libs_for_gcc) +else + $(CC) -o foo $(objects) $(normal_libs) +endif +@end example + +@noindent +This conditional uses three directives: one @code{ifeq}, one @code{else} +and one @code{endif}. + +The @code{ifeq} directive contains two arguments, separated by a comma and +surrounded by parentheses. Variable substitution is performed on both +arguments and then they are compared. The lines of the makefile following +the @code{ifeq} are obeyed if the two arguments match; otherwise they are +ignored. + +The @code{else} directive causes the following lines to be obeyed if the +previous conditional failed. In the example above, this means that the +second alternative linking command is used whenever the first alternative +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. + +When the variable @code{CC} has the value @samp{gcc}, the above example has +this effect: + +@example +foo: $(objects) + $(CC) -o foo $(objects) $(libs_for_gcc) +@end example + +@noindent +When the variable @code{CC} has any other value, this effect is this: + +@example +foo: $(objects) + $(CC) -o foo $(objects) $(normal_libs) +@end example + +Equivalent results can be obtained in another way by conditionalizing a +variable assignment and then using the variable unconditionally: + +@example +libs_for_gcc = -lgnu +normal_libs = + +ifeq ($(CC),gcc) + libs=$(libs_for_gcc) +else + libs=$(normal_libs) +endif + +foo: $(objects) + $(CC) -o foo $(objects) $(libs) +@end example + +@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals +@section Syntax of Conditionals +@findex ifdef +@findex ifeq +@findex else +@findex endif + +The syntax of a simple conditional with no @code{else} is as follows: + +@example +@var{conditional-directive} +@var{text-if-true} +endif +@end example + +@noindent +The @var{text-if-true} may be any lines of text, to be considered as part +of the makefile if the condition is true. If the condition is false, no +text is used instead. + +The syntax of a complex conditional is as follows: + +@example +@var{conditional-directive} +@var{text-if-true} +else +@var{text-if-false} +endif +@end example + +@noindent +If the condition is true, @var{text-if-true} is used; otherwise, +@var{text-if-false} is used instead. The @var{text-if-false} can be any +number of lines of text. + +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 + +You may use an @code{include} directive within a conditional, but you may +not start a conditional in one file and end it in another. + +The syntax of the @var{conditional-directive} is the same whether the +conditional is simple or complex. There are four different directives that +test different conditions. Here is a table of them: + +@table @code +@item ifeq (@var{arg1}, @var{arg2}) +Expand all variable references in @var{arg1} and @var{arg2} and +compare them. If they are identical, the @var{text-if-true} is +effective; otherwise, the @var{text-if-false}, if any, is effective. + +@item ifneq (@var{arg1}, @var{arg2}) +Expand all variable references in @var{arg1} and @var{arg2} and +compare them. If they are different, the @var{text-if-true} is +effective; otherwise, the @var{text-if-false}, if any, is effective. + +@item ifdef @var{variable-name} +If the variable @var{variable-name} has a non-empty value, the +@var{text-if-true} is effective; otherwise, the @var{text-if-false}, +if any, is effective. Variables that have never been defined have an +empty value. + +@item ifndef @var{variable-name} +If the variable @var{variable-name} has an empty value, the +@var{text-if-true} is effective; otherwise, the @var{text-if-false}, +if any, is effective. +@end table + +Extra spaces are allowed and ignored at the beginning of the conditional +directive line, but a tab is not allowed. (If the line begins with a tab, +it will be considered a command for a rule.) Aside from this, extra spaces +or tabs may be inserted with no effect anywhere except within the directive +name or within an argument. A comment starting with @samp{#} may appear at +the end of the line. + +The other two directives that play a part in a conditional are @code{else} +and @code{endif}. Each of these directives is written as one word, with no +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. + +@node Testing Flags,, Conditional Syntax, Conditionals +@section Conditionals that Test Flags + +You can write a conditional that tests @code{make} command flags such as +@samp{-t} by using the variable @code{MAKEFLAGS} together with the +@code{findstring} function. This is useful when @code{touch} is not +enough to make a file appear up to date. + +The @code{findstring} function determines whether one string appears as a +substring of another. If you want to test for the @samp{-t} flag, +use @samp{t} as the first string and the value of @code{MAKEFLAGS} as +the other. + +For example, here is how to arrange to use @samp{ranlib -t} to finish +marking an archive file up to date: + +@example +archive.a: @dots{} +ifneq (,$(findstring t,$(MAKEFLAGS))) + @@echo $(MAKE) > /dev/null + touch archive.a + ranlib -t archive.a +else + ranlib archive.a +endif +@end example + +@noindent +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. + +@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. + +@menu +* Syntax: Function Syntax. Syntax of function calls in general. +* Text Functions:: Text manipulation functions. +* Expand Function:: The function @code{expand} can search a variable's + value for variable references. +* Filename Functions:: Functions for manipulating file names. +@end menu + +@node Function Syntax, Text Functions, Functions, Functions +@section Function Call Syntax +@cindex $ + +A function call resembles a variable reference. It looks like this: + +@example +$(@var{function} @var{arguments}) +@end example + +@noindent +or like this: + +@example +$@{@var{function} @var{arguments}@} +@end example + +Here @var{function} is a function name; one of a short list of names that +are part of @code{make}. There is no provision for defining new functions. + +The @var{arguments} are the arguments of the function. They are separated +from the function name by one or more spaces and/or tabs, and if there are +more than one argument they are separated by commas. Such whitespace and +commas are not part of any argument's value. Parentheses or braces, +whichever you use to surround the function call, can appear in an argument +only in matching pairs; the ones that were not used to surround the +function call can appear freely. If the arguments contain other function +calls or variable references, it is wisest to surround them with the same +delimiters used for the containing function call. + +The text written for each argument is processed by substitution of +variables and function calls in order to produce the argument value, which +is the text on which the function acts. + +Commas and unmatched parentheses or braces cannot appear in the text of an +argument as written; leading spaces cannot appear in the text of the first +argument as written. These characters can be put into the argument value +by variable substitution. First define variables @code{comma} and +@code{space} whose values are isolated comma and space characters, then +substitute those variables where such characters are wanted, like this: + +@example +comma= , +space= $(empty) $(empty) +foo= a b c +bar= $(subst $(space),$(comma),$(foo)) +@r{# bar is now `a,b,c'.} +@end example + +@noindent +Here the @code{subst} function replaces each space with a comma, through +the value of @code{foo}, and substitutes the result. + +@node Text Functions, Expand Function, Function Syntax, Functions +@section Functions for String Substitution and Analysis + +Here are two functions that operate on substrings of a string: +@code{subst} and @code{findstring}. + +@table @code +@item $(subst @var{from},@var{to},@var{text}) +@findex subst +Performs a textual replacement on the text @var{text}: each occurrence +of @var{from} is replaced by @var{to}. The result is substituted for +the function call. For example, + +@example +$(subst ee,EE,feet on the street) +@end example + +substitutes the string @samp{fEEt on the strEEt}. + +@item $(findstring @var{find},@var{in}) +@findex findstring +Searches @var{in} for an occurrence of @var{find}. If it occurs, the +value is @var{find}; otherwise, the value is empty. You can use this +function in a conditional to test for the presence of a specific +substring in a given string. @xref{Testing Flags}, for a practical +application of @code{findstring}. +@end table + +Here is a realistic example of use of @code{subst}. Suppose that a +makefile uses the @code{VPATH} variable to specify a list of directories +that @code{make} should search for dependency files. This example shows +how to tell the C compiler to search for header files in the same list of +directories. + +The value of @code{VPATH} is a list of directories separated by colons, +such as @samp{src:../headers}. First, the @code{subst} function is used to +change the colons to spaces: + +@example +$(subst :, ,$(VPATH)) +@end example + +@noindent +This produces @samp{src ../headers}. Then another function, +@code{addprefix}, can turn each directory name into an @samp{-I} flag. +These can be added to the value of the variable @code{CFLAGS}, which is +passed automatically to the C compiler, like this: + +@example +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}. + +@node Expand Function, Filename Functions, Text Functions, Functions +@section Rescanning Text for Variable References + +@table @code +@item $(expand @var{text}) +@findex expand +Expands the text @var{text} twice. This is to say, after variable +references and function calls written in @var{text} are expanded, +producing the argument text, that text is scanned over again for +variable references and function calls. +@end table + +For an example, suppose the following variable values have been set up: + +@example +foo=cross$$(intermediate) +intermediate=bar +@end example + +@noindent +where the double @samp{$} is used in setting @code{foo} in order to prevent +variable substitution from occurring when @code{foo} is set, thus getting +an actual dollar sign into the value of @code{foo}. + +Now if we expand @code{foo} in the usual way, with @samp{$(foo)}, the +result is @samp{cross$(intermediate)}. + +The effect of @samp{$(expand $(foo))} is to rescan that string +@samp{cross$(intermediate)}, which appears as the expanded argument string. +In the process, variable substitution operates on the variable +@code{intermediate}. The ultimate result is @samp{crossbar}. + +The @code{expand} function is most often useful with canned sequences of +commands (@xref{Sequences}). + +@node Filename Functions,, Expand Function, Functions +@section Functions for File Names + +Several of the built-in expansion functions relate specifically to +taking apart file names or lists of file names. + +Each of these functions performs a specific transformation on a file name. +The argument of the function is regarded as a series of file names, +separated by whitespace. (Leading and trailing whitespace is ignored.) +Each file name in the series is transformed in the same way and the results +are concatenated with single spaces between them. + +@table @code +@item $(dir @var{names}) +@findex dir +Extracts the directory-part of each file name in @var{names}. The +directory-part of the file name is everything up through (and +including) the last slash in it. If the file name contains no slash, +the directory part is the string @samp{./}. For example, + +@example +$(dir src/foo.c hacks) +@end example + +@noindent +produces the result @samp{src/ ./}. + +@item $(notdir @var{names}) +@findex notdir +Extracts all but the directory-part of each file name in @var{names}. +If the file name contains no slash, it is left unchanged. Otherwise, +everything through the last slash is removed from it. A file name +that ends with a slash becomes an empty string. This is unfortunate, +because it means that the result does not always have the same number +of whitespace-separated file names as the argument had; but we do not +see any other valid alternative. + +For example, + +@example +$(notdir src/foo.c hacks) +@end example + +@noindent +produces the result @samp{foo.c hacks}. + +@item $(suffix @var{names}) +@findex suffix +Extracts the suffix of each file name in @var{names}. If the file name +contains a period, the suffix is everything starting with the last +period. Otherwise, the suffix is the empty string. This frequently +means that the result will be empty when @var{names} is not, and if +@var{names} contains multiple file names, the result may contain fewer +file names. + +For example, + +@example +$(notdir src/foo.c hacks) +@end example + +@noindent +produces the result @samp{.c}. + +@item $(basename @var{names}) +@findex basename +Extracts all but the suffix of each file name in @var{names}. If the +file name contains a period, the basename is everything starting up to +(and not including) the last period. Otherwise, the basename is the +entire file name. For example, + +@example +$(basename src/foo.c hacks) +@end example + +@noindent +produces the result @samp{src/foo hacks}. + +@item $(addsuffix @var{suffix},@var{names}) +@findex addsuffix +The argument @var{names} is regarded as a series of names, separated +by whitespace; @var{suffix} is used as a unit. The value of +@var{suffix} is appended to the end of each individual name and the +resulting larger names are concatenated with single spaces between +them. For example, + +@example +$(addsuffix .c,foo bar) +@end example + +@noindent +produces the result @samp{foo.c bar.c}. + +@item $(addprefix @var{prefix},@var{names}) +@findex addprefix +The argument @var{names} is regarded as a series of names, separated +by whitespace; @var{prefix} is used as a unit. The value of +@var{prefix} is appended to the front of each individual name and the +resulting larger names are concatenated with single spaces between +them. For example, + +@example +$(addprefix src/,foo bar) +@end example + +@noindent +produces the result @samp{src/foo src/bar}. + +@item $(firstword @var{names}) +@findex firstword +The argument @var{names} is regarded as a series of names, separated +by whitespace. The value is the first name in the series. The rest +of the names are ignored. For example, + +@example +$(firstword foo bar) +@end example + +@noindent +produces the result @samp{foo}. + +@item $(wildcard @var{pattern}) +@findex wildcard +The argument @var{pattern} is a file name pattern, typically +containing wildcards characters. The result of @code{wildcard} is a +space-separated list of the names of existing files that match the +pattern. + +Wildcard are expanded automatically in rules (@pxref{Wildcards}). But +it does not normally take place when a variable is set, or inside the +arguments of other functions. Those occasions are when the +@code{wildcard} function is useful. +@end table + +@node Running, Implicit, 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. + +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 +find out which files are out of date without changing them. + +By specifying arguments when you run @code{make}, you can do any of these +things or many others. + +@menu +* Makefile Arguments:: Arguments to specify which makefile to use. + +* Goals:: Goal arguments specify which parts of the makefile + should be used. + +* Avoid Compilation:: How to avoid recompiling certain files. + +* Instead of Execution:: Mode flags specify what kind of thing to do + with the commands in the makefile + other than simply execute them. + +* Overriding:: Overriding a variable can specify an alternate + compiler, or alternate flags for the compiler, + or whatever else you program into the makefile. + +* Testing:: How to proceed past some errors, to test compilation. + +* Options:: Summary of all options @code{make} accepts. +@end menu + +@node Makefile Arguments, Goals, Running, Running +@section Arguments to Specify the Makefile + +The way to specify the name of the makefile is with the @samp{-f} option. +For example, @samp{-f altmake} says to use the file @file{altmake} as +the makefile. + +If you use the @samp{-f} flag several times (each time with a +following argument), all the specified files are used jointly as +makefiles. + +If you do not use the @samp{-f} flag, the default is to use +@file{./makefile}, or, if that does not exist, @file{./Makefile}. +@xref{Makefiles}.@refill + +@node Goals, Avoid Compilation, Makefile Arguments, Running +@section Goals +@cindex goal + +The @dfn{goals} are the targets that @code{make} should strive ultimately +to update. Other targets are updated as well if they appear as +dependencies of goals, or dependencies of dependencies of goals, etc. + +By default, the goal is the first target in the makefile (not counting +targets that start with a period or that appear in included makefiles). +Therefore, makefiles are usually written so that the first target is for +compiling the entire program or programs they describe. + +You can specify a different goal or goal with arguments to @code{make}. +Use the name of the goal as an argument. If you specify several goals, +@code{make} processes each of them in turn, in the order you name them. + +Any target in the makefile may be specified as a goal (unless it starts +with @samp{-} or contains an @samp{=}). Even targets not in the makefile +may be specified, if @code{make} can find implicit rules that say how to +make them. + +One use of specifying a goal is if you want to compile only a part of +the program, or only one of several programs. Specify as a goal each +file that you wish to remake. For example, consider a directory containing +a several programs, with a makefile that starts like this: + +@example +all: size nm ld ar as +@end example + +If you are working on the program @code{size}, you might want to say +@samp{make size} so that only the files of that program are recompiled. + +Another use of specifying a goal is to make files that aren't normally +made. For example, there may be a file of debugging output, or a version +of the program that is compiled specially for testing, which has a rule +in the makefile but isn't a dependency of the default goal. + +Another use of specifying a goal is to run the commands associated with a +phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets}). +Many makefiles contain a phony target named @file{clean} which deletes +everything except source files. Naturally, this is done only if you +request it explicitly with @samp{make clean}. Here is a list of typical +phony and empty target names: + +@table @file +@item clean +Delete all files that the makefile could remake. + +@item install +Copy the executable file into a directory that users typically search for +commands. + +@item print +Print listings of the source files that have changed. + +@item tar +Create a tar file of the source files. +@end table + +@node Avoid Compilation, Instead of Execution, Goals, Running +@section Avoiding Recompilation of Some Files + +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 +macro or a declaration to a header file that many other files depend on. +Being conservative, @code{make} assumes that any change in the header file +requires recompilation of all dependent files, but you know that they don't +need to be recompiled and you would rather not waste the time waiting. + +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 +last-modification date. You would follow this procedure: + +@enumerate +@item +Use the command @samp{make} to recompile the source files that really +need recompilation. + +@item +Make the changes in the header files. + +@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 +header files will not cause any recompilation. +@end enumerate + +If you have already changed the header file at a time when some files do +need recompilation, it is too late to do this. Instead, you can use the +@samp{-o @var{file}} flag, which marks a specified file as ``old'' +(@pxref{Options}). This means that the file itself won't be remade, +and nothing else will be remade on its account. Follow this procedure: + +@enumerate +@item +Recompile the source files that need compilation for reasons independent +of the particular header file, with @samp{make -o @var{headerfile}}. +If several header files are involved, use a separate @samp{-o} option +for each header file. + +@item +Touch all the object files with @samp{make -t}. +@end enumerate + +@node Instead of Execution, Overriding, Avoid Compilation, Running +@section Instead of Executing the Commands +@cindex -t +@cindex touch +@cindex -q +@cindex -n + +The makefile tells @code{make} how to tell whether a target is up to date, +and how to update each target. But updating the targets is not always +what you want. Certain options specify other activities for @code{make}. + +@table @samp +@item -t +``Touch''. The activity is to mark the targets as up to date without +actually changing them. In other words, @code{make} pretends to compile +the targets but does not really change their contents. + +@item -n +``No-op''. The activity is to print what commands would be used to make +the targets up to date, but not actually execute them. + +@item -q +``Question''. The activity is to find out silently whether the targets +are up to date already; but execute no commands in either case. In other +words, neither compilation nor output will occur. +@end table + +With the @samp{-n} flag, @code{make} prints without execution the commands +that it would normally execute. + +With the @samp{-t} flag, @code{make} ignores the commands in the rules +and uses (in effect) the command @code{touch} for each target that needs to +be remade. The @code{touch} command is also printed, unless @samp{-s} or +@code{.SILENT} is used. For speed, @code{make} does not actually invoke +the program @code{touch}. It does the work directly. + +With the @samp{-q} flag, @code{make} prints nothing and executes no +commands, but the exit status code it returns is zero if and only if the +targets to be considered are already up to date. + +It is an error to use more than one of these three flags in the same +invocation of @code{make}. + +@node Overriding, Testing, Instead of Execution, Running +@section Overriding Variables + +You can override the value of a variable using an arguments to @code{make} +that contains a @samp{=}. The argument @samp{@var{v}=@var{x}} sets the +value of the variable @var{v} to @var{x}. + +Values specified this way override all values specified in the makefile +itself; once you have set a variable with a command argument, any ordinary +attempt in the makefile to change that variable is simply ignored. + +One way to use this facility is to pass extra flags to compilers. +For example, in a properly written makefile, the variable @code{CFLAGS} +is included in each command that runs the C compiler, so a file +@file{foo.c} would be compiled like this: + +@example +cc -c $(CFLAGS) foo.c +@end example + +Thus, whatever value you set for @code{CFLAGS} affects each compilation +that occurs. The makefile probably specifies the usual value for +@code{CFLAGS}, like this: + +@example +CFLAGS=-g +@end example + +Each time you run @code{make}, you can override this value and specify a +different value. For example, if you say @samp{make CFLAGS='-g -O'}, each +C compilation will be done with @samp{cc -c -g -O}. (This illustrates how +you can enclose spaces and other special characters in the value of a +variable when you override it.) + +The variable @code{CFLAGS} is only one of many standard variables that +exist just so that you can change them this way. @xref{Implicit +Variables}, for a complete list. + +You can also program the makefile to look at additional variables of your +own, giving the user ability to control other aspects of how the makefile +works by changing the variables. + +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 + +@noindent +This line acts like an ordinary variable assignment except that it is +not ignored even if you have used a commadn option to set the variable. +@xref{Override Directive}. + +@node Testing, Options, Overriding, Running +@section Testing the Compilation of a Program + +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. + +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, +@samp{make -k} will continue compiling other object files even though it +already knows that linking them will be impossible. @xref{Options}. + +The usual behavior of @code{make} assumes that your purpose is to get the +goals up to date; once @code{make} learns that this is impossible, it might +as well report the failure immediately. The @samp{-k} flag 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 Options,, Testing, Running +@section Summary of Options +@cindex options +@cindex flags + +Here is a table of all the options @code{make} understands: + +@table @samp +@item -b +This option is ignored for compatibility with other versions of +@code{make}. + +@item -c @var{dir} +Change to directory @var{dir} before executing the rules. If multiple +@samp{-c} options are specified, each is interpreted relative to the +previous one: @samp{-c / -c etc} is equivalent to @samp{-c /etc}. +This is typically used with recursive invocations of @code{make} +(@pxref{Recursion}). + +@item -d +Print debugging information in addition to normal processing. The +debugging information says which files are being considered for +remaking, which file-times are being compared and with what results, +which files actually need to be remade, which implicit rules are +considered and which are applied---everything interesting about how +@code{make} decides what to do. + +@item -f @var{file} +Use file @var{file} as a makefile. @xref{Makefiles}. + +@item -i +Ignore all errors in commands executed to remake files. +@xref{Errors}. + +@item -I @var{dir} +Specifies a directory @var{dir} to search for included makefiles. +@xref{Include}. If several @samp{-I} options are used to specify +several directories, the directories are searched in the order +specified. + +@item -k +Continue as much as possible after an error. While the target that +failed, and those that depend on it, cannot be remade, the other +dependencies of these targets can be processed all the same. +@xref{Testing}. + +@item -n +Print the commands that would be executed, but do not execute them. +@xref{Instead of Execution}. + +@item -o @var{file} +Do not remake the file @var{file} even if it is older than its +dependencies, and do not remake anything on account of changes in +@var{file}. Essentially the file is treated as very old and its rules +are ignored. @xref{Avoid Compilation}. + +@item -p +Print the data base (rules and variable values) that results from +reading the makefiles; then execute as usual or as otherwise +specified. + +@item -q +``Question mode''. Do not run any commands, or print anything; just +return an exit status that is zero if the specified targets are +already up to date, nonzero otherwise. @xref{Instead of Execution}. + +@item -r +Eliminate use of the built-in implicit rules (@pxref{Implicit}). +Also clear out the default list of suffixes for suffix rules +(@pxref{Suffix Rules}). + +@item -s +Silent operation; do not print the commands as they are executed. +@xref{Echoing}. + +@item -S +Cancel the effect of the @samp{-k} option. This is never necessary +except in a recursive @code{make} where @samp{-k} might be inherited +from the top-level @code{make} via @code{MAKEFLAGS}. @xref{Recursion}. + +@item -t +Touch files (mark them up to date without really changing them) +instead of running their commands. This is used to pretend (to fool +future invocations of @code{make}) that the commands were done. +@xref{Instead of Execution}. +@end table + +@node Implicit, Archives, Running, Top +@chapter Using Implicit Rules +@cindex implicit rule + +Certain standard ways of remaking target files are used very often. For +example, one customary way to make an object file is from a C source file +using the C compiler, @code{cc}. + +@dfn{Implicit rules} tell @code{make} how to use customary techniques so +that you don't have to specify them in detail when you want to use them. +For example, there is an implicit rule for C compilation. + +Implicit rules work based on file names. For example, C compilation typically +takes a @file{.c} file and makes a @file{.o} file. So @code{make} applies +the implicit rule when it sees this combination of file-name endings. + +A chain of implicit rules can apply in sequence; for example, @code{make} +will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. +@iftex +@xref{Chained Rules}. +@end iftex + +The built-in implicit rules use several variables in their commands so +that, by changing the values of the variables, you can change the way the +implicit rule works. For example, the variable @code{CFLAGS} controls the +flags given to the C compiler by the implicit rule for C compilation. +@iftex +@xref{Implicit Variables}. +@end iftex + +You can define your own implicit rules by writing @dfn{pattern rules}. +@iftex +@xref{Pattern Rules}. +@end iftex + +@menu +* Using Implicit:: How to use an existing implicit rule + to get the commands for updating a file. + +* Catalogue of Rules:: Catalogue of built-in implicit rules. + +* Implicit Variables:: By changing certain variables, you can + change what the predefined implicit rules do. + +* Chained Rules:: Using a chain of implicit rules. + +* Pattern Rules:: Defining new implicit rules. + +* Search Algorithm:: Precise algorithm for applying implicit rules. +@end menu + +@node Using Implicit, Catalogue of Rules, Implicit, Implicit +@section Using Implicit Rules + +To allow @code{make} to find a customary method for updating a target file, +all you have to do is refrain from specifying commands yourself. Either +write a rule with no command lines, or don't write a rule at all. Then +@code{make} will figure out which implicit rule to use based on which +kind of source file exists. + +For example, suppose the makefile looks like this: + +@example +foo : foo.o bar.o + cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) +@end example + +@noindent +Because you mention @file{foo.o} but do not give a rule for it, @code{make} +will automatically look for an implicit rule that tells how to update it. +This happens whether or not the file @file{foo.o} currently exists. + +If an implicit rule is found, it supplies both commands and a dependency +(the source file). You would want to write a rule for @file{foo.o} with no +command lines if you need to specify additional dependencies, such as +header files, that the implicit rule cannot supply. + +Each implicit rule has a target pattern and dependency patterns. There may +be many implicit rules with the same target pattern. For example, numerous +rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler; +another, from a @samp{.p} file with the Pascal compiler; and so on. The rule +that actually applies is the one whose dependency exists or can be made. + +So, if you have a file @file{foo.c}, @code{make} will run the C compiler; +otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal +compiler; and so on. + +Of course, when you write the makefile, you know which implicit rule you +want @code{make} to use, and you know it will choose that one because you +know which other files are supposed to exist. @xref{Catalogue of Rules}, +for a catalogue of all the predefined implicit rules. + +Above, we said an implicit rule applies if the required dependency ``exists +or can be made''. A file ``can be made'' if it is mentioned explicitly in +the makefile as a target or a dependency, or if an implicit rule can be +recursively found for how to make it. When the implicit dependency is the +result of another implicit rule, we say that @dfn{chaining} is occurring. +@xref{Chained Rules}. + +In general, @code{make} searches for an implicit rule for each target, and +for each double-colon rule, that has no commands. A file that is mentioned +only as a dependency is considered a target whose rule specifies nothing, +so implicit rule search happens for it. @xref{Search Algorithm}, for the +details of how the search is done. + +@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit +@section Catalogue of Implicit Rules + +Here is a catalogue of predefined implicit rules which are always available +unless the makefile explicitly overrides or cancels them. +(@xref{Cancelling Rules}, for information on cancelling or overriding an +implicit rule. The @samp{-r} option cancels all predefined rules.) + +@table @asis +@item Compiling C programs +@file{@var{n}.o} will be made automatically from @file{@var{n}.c} +with the command @samp{$(CC) -c $(CFLAGS)}.@refill + +@item Compiling Pascal programs +@file{@var{n}.o} will be made automatically from @file{@var{n}.p} +with the command @samp{$(PC) -c $(PFLAGS)}.@refill + +@item Compiling Fortran, EFL and Ratfor programs +@file{@var{n}.o} will be made automatically from @file{@var{n}.e}, +@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 +@item .e +@samp{$(FC) -c $(EFLAGS)}. +@item .f +@samp{$(FC) -c $(FFLAGS)}. +@item .F +@samp{$(FC) -c $(FFLAGS)}. +@item .r +@samp{$(FC) -c $(RFLAGS)}. +@end table + +@item Preprocessing Fortran, EFL and Ratfor programs +@file{@var{n}.f} will be made automatically from @file{@var{n}.e}, +@file{@var{n}.r} or @file{@var{n}.F}. This rule runs just the +preprocessor to convert a Ratfor, EFL or preprocessable Fortran +program into a strict Fortran program. The precise command used is as +follows:@refill + +@table @samp +@item .e +@samp{$(FC) -F $(EFLAGS)}. +@item .F +@samp{$(FC) -F $(FFLAGS)}. +@item .r +@samp{$(FC) -F $(RFLAGS)}. +@end table + +@item Assembling assembler programs +@file{@var{n}.o} will be made automatically from @file{@var{n}.s} by +running the assembler @code{as}. The precise command used is +@samp{$(AS) $(ASFLAGS)}.@refill + +@item Linking a single object file +@file{@var{n}} will be made automatically from @file{@var{n}.o} by +running the linker @code{ld} via the C compiler. The precise command +used is @samp{$(CC) $(LDFLAGS) @dots{} $(LOADLIBES)}.@refill + +This rule does the right thing for a simple program with only one source +file. In more complicated cases, you must write an explicit command for +linking. + +@item Compiling C into assembler code +@file{@var{n}.s} will be made automatically from @file{@var{n}.c} +with the command @samp{$(CC) -S $(CFLAGS)}.@refill + +It would be possible for @code{make} to convert @file{@var{n}.c} into +@file{@var{n}.o} by way of @file{@var{n}.s}, using this rule and the +rule for running the assembler. But that is not what @code{make} +does, because the rule for compiling @file{@var{n}.c} into +@file{@var{n}.o} directly comes earlier in the order of rules. The +upshot is that the file @file{@var{n}.s} is not created or changed +when @file{@var{n}.o} is being remade. This rule is used only if you +explicitly specify @file{@var{n}.s} as a goal or needed dependency. + +This is a deliberate decision, for the sake of compatibility with Unix +@code{make}.@refill + +If you want @code{make} update @file{@var{n}.s} on the way to updating +@file{@var{n}.o}, you can request this by cancelling the other rule +that allows direct compilation. @xref{Cancelling Rules}.@refill + +@item Compiling Pascal, Fortran, EFL or Ratfor into assembler code +@file{@var{n}.s} will be made automatically from @file{@var{n}.p}, +@file{@var{n}.e}, @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.F} +by running the appropriate compiler with the @samp{-S} flag +instead of the @samp{-c} flag.@refill + +For compatibility with Unix @code{make}, these rules apply only if you +expressly request @code{make} to update @file{@var{n}.s}. See the +information immediately above. + +@item Yacc for C programs +@file{@var{n}.c} will be made automatically from @file{@var{n}.y} by +running Yacc with the command @samp{$(YACC) $(YFLAGS)}. + +@item Yacc for Ratfor programs +@file{@var{n}.r} will be made automatically from @file{@var{n}.yr} by +running Yacc with the command @samp{$(YACCR) $(YFLAGS)}. + +@item Yacc for EFL programs +@file{@var{n}.e} will be made automatically from @file{@var{n}.ye} by +running Yacc with the command @samp{$(YACCE) $(YFLAGS)}. + +@item Lex for C programs +@file{@var{n}.c} will be made automatically from @file{@var{n}.l} by +by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. + +@item Lex for Ratfor programs +@file{@var{n}.r} will be made automatically from @file{@var{n}.l} by +by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. + +The traditional custom of using the same suffix @samp{.l} for all Lex +files regardless of whether they produce C code or Ratfor code makes +it impossible for @code{make} to determine autmatically which of the +two languages you are using in any particular case. If @code{make} is +called upon to remake an object file from a @samp{.l} file, it must +guess which compiler to use. It will guess the C compiler, because +that is more common. If you are using Ratfor, make sure @code{make} +knows this by mentioning @file{@var{n}.r} in the makefile. + +@item RCS +Any file @file{@var{n}} will be extracted if necessary from an RCS +file named either @file{@var{n},v} or @file{RCS/@var{n},v}. The +precise command used is @samp{$(CO) $(COFLAGS)}. The variable +@code{CO} has default value @samp{co}. + +@item SCCS +Any file @file{@var{n}} will be extracted if necessary from an SCCS +file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The +precise command used is @samp{$(GET) $(GFLAGS)}. + +I recommend that you avoid the use of SCCS. RCS is widely held to be +superior, and RCS is also free. By choosing free software in place of +comparable proprietary software, you support the free software +movement. +@end table + +@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit +@section Variables Used by Implicit Rules +@cindex flags for compilers + +The commands in built-in implicit rules make liberal use of certain +predefined variables. You can redefine these variables, either in the +makefile or with arguments to @code{make}, to alter how the implicit rules +work without actually redefining them. + +For example, the command used to compile a C source file actually says +@samp{$(CC) -c $(CFLAGS)}. The default values of the variables used +are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By +redefining @samp{$(CC)} to @samp{ncc}, you could cause @samp{ncc} to +be used for all C compilations performed by the implicit rule. By +redefining @samp{$(CFLAGS)} to be @samp{-g}, you could pass the +@samp{-g} option to each compilation. @emph{All} implicit rules that +do C compilation use @samp{$(CC)} to get the program name for the +compiler and @emph{all} include @samp{$(CFLAGS)} among the arguments +given to the compiler.@refill + +The variables used in implicit rules fall into two classes: those that are +names of programs (like @code{CC}) and those that contain arguments for the +programs (like @code{CFLAGS}). (The ``name of a program'' may also contain +some command arguments, but it must start with an actual executable program +name.) If a variable value contains more than one argument, separate them +with spaces. + +Here is a table of variables used as names of programs: + +@table @code +@item AS +@vindex AS +Program for doing assembly; default @samp{as}. + +@item CC +@vindex CC +Program for compiling C programs; default @samp{cc}. + +@item CO +@vindex CO +Program for extracting a file from RCS; default @samp{co}. + +@item FC +@vindex FC +Program for compiling or preprocessing Fortran programs (or Ratfor or +EFL programs); default @samp{f77}. + +@item GET +@vindex GET +Program for extracting a file from SCCS; default @samp{get}. + +@item LEX +@vindex LEX +Program to use to turn Lex grammars into C programs or Ratfor programs; +default @samp{lex}. + +@item PC +@vindex PC +Program for compiling Pascal programs; default @samp{pc}. + +@item YACC +@vindex YACC +Program to use to turn Yacc grammars into C programs; default +@samp{yacc}. + +@item YACCR +@vindex YACCR +Program to use to turn Yacc grammars into Ratfor programs; default +@samp{yacc -r}. + +@item YACCE +@vindex YACCE +Program to use to turn Yacc grammars into EFL programs; default +@samp{yacc -e}. + +@item RANLIB +@vindex RANLIB +Program to use to update the symbol-directory of an archive +(the @file{__.SYMDEF} member); default @samp{ranlib}. +@end table + +Here is a table of variables whose values are additional arguments for the +programs above: + +@table @code +@item ASFLAGS +@vindex ASFLAGS +Extra flags to give to the assembler (when explicitly invoked +on a @samp{.s} file). + +@item CFLAGS +@vindex CFLAGS +Extra flags to give to the C compiler; default is empty. + +@item EFLAGS +@vindex EFLAGS +Extra flags to give to the Fortran compiler for EFL programs; default +is empty. + +@item FFLAGS +@vindex FFLAGS +Extra flags to give to the Fortran compiler; default is empty. + +@item LFLAGS +@vindex LFLAGS +Extra flags to give to Lex; default is empty. + +@item LDFLAGS +@vindex LDFLAGS +Extra flags to give to compilers when they are supposed to invoke the +linker, @samp{ld}; default is empty. + +@item PFLAGS +@vindex PFLAGS +Extra flags to give to the Pascal compiler; default is empty. + +@item RFLAGS +@vindex RFLAGS +Extra flags to give to the Fortran compiler for Ratfor programs; +default is empty. + +@item YFLAGS +@vindex YFLAGS +Extra flags to give to Yacc; default is empty. +@end table + +@node Chained Rules, Pattern Rules, Implicit Variables, Implicit +@section Chains of Implicit Rules + +@cindex chains of rules +Sometimes a file can be made by a sequence of implicit rules. For example, +a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running +first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}. + +If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no +special searching is required: @code{make} finds that the object file can +be made by C compilation from @file{@var{n}.c}; later on, when considering +how to make @file{@var{n}.c}, the rule for running Yacc will be +used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are +updated.@refill + +@cindex intermediate file +However, even if @file{@var{n}.c} does not exist and is not mentioned, +@code{make} knows how to envision it as the missing link between +@file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is +called an @dfn{intermediate file}. Once @code{make} has decided to use the +intermediate file, it is entered in the data base as if it had been +mentioned in the makefile, along with the implicit rule that says how to +create it.@refill + +Intermediate files are remade using their rules just like all other +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 +that shows what @code{make} is doing. (You can optionally define an +implicit rule so as to preserve certain intermediate files.) + +A chain can involve more than two implicit rules. For example, it is +possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS, +Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are +intermediate files that are deleted at the end.@refill + +No single implicit rule can appear more than once in a chain. This means +that @code{make} will not even consider such a ridiculous thing as making +@file{foo} from @file{foo.o.o} by running the linker twice. This +constraint has the added benefit of preventing any infinite loop in the +search for an implicit rule chain. + +There are some special implicit rules to optimize certain cases that would +otherwise by handled by rule chains. For example, making @file{foo} from +@file{foo.c} could be handled by compiling and linking with separate rules, +using @file{foo.o} as an intermediate file. But what actually happens is +that a special rule for this case does the compilation and linking with a +single @code{cc} command. The optimized rule is used in preference to the +step-by-step chain because it comes earlier in the ordering of rules. + +@node Pattern Rules, Last Resort, Chained Rules, Implicit +@section Defining and Redefining Pattern Rules + +@cindex pattern rule +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 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 +with @samp{s.}, ends in @samp{.c} and is at least five characters long. +(There must be at least one character to match the @samp{%}.) The substring +that the @samp{%} matches is called the @dfn{stem}.@refill + +A pattern rule must have at least one dependency that uses @samp{%}. +@samp{%} in a dependency of a pattern rule stands for the same stem +that was matched by the @samp{%} in the target. In order for +the pattern rule to apply, its target pattern must match the file name +under consideration, and its dependency patterns must name files that +exist or can be made. These files become dependencies of the target. + +There may also be dependencies that do not use @samp{%}; such a dependency +attaches to every file made by this pattern rule. These unvarying +dependencies are rarely useful. + +The order in which pattern rules appear in the makefile is important +because the rules are considered in that order. Of equally applicable +rules, the first one found is used. The rules you write take precedence +over those that are built in. Note, however, that a rule whose +dependencies actually exist or are mentioned always takes priority over a +rule with dependencies that must be made by chaining other implicit rules. + +@menu +* Examples: Pattern Examples. Real examples of pattern rule definitions. + +* Vars: Automatic. The automatic variables enable the commands + in pattern rules to act on the right files. + +* Matching: Pattern Match. Details of how patterns match. + +* Match-Anything Rules:: Precautions in defining a rules that can + match any target file whatever. + +* Cancelling Rules:: Overriding or cancelling built-in rules. + +* Last Resort:: How to define a last-resort rule + that applies to any target that no other + rule applies to. + +* Suffix Rules:: The old-fashioned way to define implicit rules. +@end menu + +@node Pattern Examples, Automatic, Pattern Rules, Pattern Rules +@subsection Pattern Rule Examples + +Here are some examples of pattern rules actually predefined in +@code{make}. First, the rule that compiles @samp{.c} files into @samp{.o} +files:@refill + +@example +%.o : %.c + $(CC) -c $(CFLAGS) $< -o $@@ +@end example + +@noindent +defines a rule that can make any file @file{@var{x}.o} from +@file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and +@samp{$<} to substitute the names of the target file and the source file +as they are in each case where the rule apply (@pxref{Automatic}).@refill + +Here is a second built-in rule: + +@example +% :: RCS/%,v + $(CO) $(COFLAGS) $< +@end example + +@noindent +defines a rule that can make any file @file{@var{x}} whatever from a +corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since +the target is @samp{%}, this rule will apply to any file whatever, provided +the appropriate dependency file exists. The double colon makes the rule +@dfn{terminal}, which means that its dependency may not be an intermediate +file (@pxref{Match-Anything Rules}).@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 +on the right source file name? You can't write the name in the command, +because the name is different each time the implicit rule is applied. + +What you do is use a special feature of @code{make}, the @dfn{automatic +variables}. These variables have values computed afresh for each rule that +is executed, based on the target and dependencies of the rule. In this +example, you would use @samp{$@@} for the object file name and @samp{$<} +for the source file name. + +Here is a table of automatic variables: + +@table @code +@item $@@ +The file name of the target of the rule. If the target is an archive +member, then @samp{$@@} is the name of the archive file. + +@item $% +The target member name, when the target is an archive member. For +example, if the target is @file{foo.a(bar.o)} then @samp{$%} is +@file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is empty +when the target is not an archive member. + +@item $< +The name of the first implicit dependency, when an implicit rule is +being applied. + +@item $? +The names of all the dependencies that are newer than the target, with +spaces between them. + +@item $^ +The names of all the dependencies, with spaces between them. + +@item $* +The stem with which an implicit rule matches (@pxref{Pattern Match}). +If the target is @file{dir/a.foo.b} and the target pattern is +@file{a.%.b} then the stem is @file{dir/foo}. The stem is useful for +constructing names of related files.@refill + +@item $($@@) +The same as @code{$@@}, for compatibility with some other versions +of @code{make}. +@end table + +@samp{$?} is useful even in explicit rules when you wish to operate on only +the dependencies that have changed. For example, suppose that an archive +named @file{lib} is supposed to contain copies of several object files. +This rule copies just the changed object files into the archive: + +@example +lib: foo.o bar.o lose.o win.o + ar c lib $? +@end example + +Of the variables listed above, four have values that are single file names. +These four have variants that get just the file's directory name or just +the file name within the directory. The variant variables' names are +formed by appending @samp{D} or @samp{F}, respectively. These variants are +semi-obsolete in GNU @code{make} since the functions @code{dir} and +@code{notdir} can be used to get an equivalent effect (@pxref{Filename +Functions}). Here is a table of the variants:@refill + +@table @samp +@item $(@@D) +The directory part of the file name of the target. If the value of +@samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}. +This value is @file{./} if @samp{$@@} does not contain a slash. +@samp{$(@@D)} is equivalent to @samp{$(dir $@@)}.@refill + +@item $(@@F) +The file-within-directory part of the file name of the target. If the +value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is +@file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}. + +@item $($/) +The same as @code{$(@@F)}, for compatibility with some other versions +of @code{make}. + +@item $(%D) +@itemx $(%F) +The directory part and the file-within-directory part of the archive +member name. + +@item $(*D) +@itemx $(*F) +The directory part and the file-within-directory part of the stem; +@file{dir/} in this example. + +@item $(<D) +@itemx $(<F) +The directory part and the file-within-directory part of the first +implicit dependency. +@end table + +@node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules +@subsection How Patterns Match + +@cindex stem +A target pattern is composed of a @samp{%} between a prefix and a suffix, +either of which may be empty. The pattern matches a file name only if the +file name starts with the prefix and ends with the suffix, without overlap. +The text between the prefix and the suffix is called the @dfn{stem}. Thus, +when the pattern @samp{%.o} matches the file name @file{test.o}, the stem +is @samp{test}. The pattern rule dependencies are turned into actual file +names by substituting the stem for the character @samp{%}. Thus, if in the +same example one of the dependencies is written as @samp{%.c}, it expands +to @samp{test.c}.@refill + +When the target pattern does not contain a slash (and usually it does not), +directory names in the file names are removed from the file name before it +is compared with the target prefix and suffix. The directory names, along +with the slash that ends them, are added back to the stem. Thus, +@samp{e%t} does match the file name @file{src/eat}, with @samp{src/a} as +the stem. When dependencies are turned into file names, the directories +from the stem are added at the front, while the rest of the stem is +substituted for the @samp{%}. The stem @samp{src/a} with a dependency +pattern @samp{c%r} gives the file name @file{src/car}.@refill + +@node Match-Anything Rules, Cancelling Rules, Pattern Match, Pattern Rules +@subsection Match-Anything Pattern Rules + +@cindex match-anything rule +@cindex terminal rule +When a pattern rule's target is just @samp{%}, it matches any filename +whatever. We call these rules @dfn{match-anything} rules. They are very +useful, but it can take a lot of time for @code{make} to think about them, +because it must consider every such rule for each file name listed either +as a target or as a dependency. + +Suppose the makefile mentions @file{foo.c}. For this target, @code{make} +would have to consider making it by linking an object file @file{foo.c.o}, +or by C compilation-and-linking in one step from @file{foo.c.c}, or by +Pascal compilation-and-linking from @file{foo.c.p}, and many other +possibilities. We know these possibilities are ridiculous since +@file{foo.c} is a C source file, not an executable.@refill + +If @code{make} did consider these possibilities, it would ultimately reject +them, because files such as @file{foo.c.o}, @file{foo.c.p}, etc. would not +exist. But these possibilities are so numerous that @code{make} would run +very slowly if it had to consider them.@refill + +To gain speed, we have put various constraints on the way @code{make} +considers match-anything rules. There are two different constraints that +can be applied, and each time you define a match-anything rule you must +choose one or the other for that rule. + +One choice is to mark the match-anything rule as @dfn{terminal} by defining +it with a double colon. When a rule is terminal, it does not apply +unless its dependencies actually exist. Dependencies that could be made +with other implicit rules are not good enough. + +For example, the built-in implicit rules for extracting sources from RCS +and SCCS files are terminal; as a result, if the file @file{foo.c,v} does +not exist, @code{make} will not even consider trying to make it as an +intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}. +RCS and SCCS files are generally ultimate source files, which should not be +remade from any other files; therefore, @code{make} can save time by not +looking for ways to remake them.@refill + +If you do not mark the match-anything rule as terminal, then it is +nonterminal. A nonterminal match-anything rule cannot apply to a file name +that indicates a specific type of data. A file name indicates a specific +type of data if some non-match-anything implicit rule target matches it. + +For example, the file name @file{foo.c} matches the target for the pattern +rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this +rule is actually applicable (which happens only if there is a file +@file{foo.y}), the fact that its target matches is enough to prevent +consideration of any nonterminal match-everything rules for the file +@file{foo.c}. Thus, @code{make} will not even consider trying to make +@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c}, +@file{foo.c.p}, etc.@refill + +The motivation for this constraint is that nonterminal match-everything +rules are used for making files containing specific types of data (such as +executable files) and a file name with a recognized suffix indicates a +specific different type of data (such as a C source file). + +Special built-in dummy pattern rules are provided solely to recognize +certain file names so that nonterminal match-everything rules won't be +considered. These dummy rules have no dependencies and no commands, and +they are ignored for all other purposes. For example, the built-in +implicit rule + +@example +%.p : +@end example + +@noindent +exists to make sure that Pascal source files such as @file{foo.p} match a +specific target pattern and thereby prevent time from being wasted looking +for @file{foo.p.o} or @file{foo.p.c}. + +@node Cancelling Rules,, Match-Anything Rules, Pattern Rules +@subsection Cancelling Implicit Rules + +You can override a built-in implicit rule by defining a new pattern rule +with the same target and dependencies, but different commands. When the +new rule is defined, the built-in one is replaced. The new rule's position +in the sequence of implicit rules is determined by where you write the new +rule. + +You can cancel a built-in implicit rule by defining a pattern rule with the +same target and dependencies, but no commands. For example, the following +would cancel the rule that runs the assembler: + +@example +%.o : %.s +@end example + +@node Last Resort, Suffix Rules, Pattern Rules, Implicit +@section Defining Last-Resort Default Rules + +@findex .DEFAULT +You can define a last-resort implicit rule by writing a rule for the target +@code{.DEFAULT}. Such a rule's commands are used for all targets and +dependencies that have no commands of their own and for which no other +implicit rule applies. Naturally, there is no @code{.DEFAULT} rule unless +you write one. + +For example, when testing a makefile, you might not care if the source +files contain real data, only that they exist. Then you might do this: + +@example +.DEFAULT: + touch $@@ +@end example + +@noindent +to cause all the source files needed (as dependencies) to be created +silently. + +@node Suffix Rules, Search Algorithm, Last Resort, Implicit +@section Old-Fashioned Suffix Rules +@cindex suffix rules + +@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for +@code{make}. Suffix rules are obsolete because pattern rules are more +general and clearer. They are supported in GNU @code{make} for +compatibility with old makefiles. They come in two kinds: +@dfn{double-suffix} and @dfn{single-suffix}.@refill + +A double-suffix rule is defined by a pair of suffixes: the target suffix +and the source suffix. It matches any file whose name ends with the target +suffix. The corresponding implicit dependency is to the file name made by +replacing the target suffix with the source suffix. A two-suffix rule +whose target and source suffixes are @samp{.o} and @samp{.c} is equivalent +to the pattern rule @samp{%.o : %.c}. + +A single-suffix rule is defined by a single suffix, which is the source +suffix. It matches any file name, and the corresponding implicit +dependency name is made by appending the source suffix. A single-suffix +rule whose source suffix is @samp{.c} is equivalent to the pattern rule +@samp{% : %.c}. + +Suffix rule definitions are recognized by comparing each rule's target +against a defined list of known suffixes. When @code{make} sees a rule +whose target is a known suffix, this rule is considered a single-suffix +rule. When @code{make} sees a rule whose target is two known suffixes +concatenated, this rule is taken as a double-suffix rule. + +For example, @samp{.c} and @samp{.o} are both on the default list of known +suffixes. Therefore, if you define a rule whose target is @samp{.c.o}, +@code{make} takes it to be a double-suffix rule with source suffix +@samp{.c} and target suffix @samp{.o}. For example, here is the old +fashioned way to define the rule for compiling a C source:@refill + +@example +.c.o: + $(CC) -c $(CFLAGS) -o $@@ $< +@end example + +@findex .SUFFIXES +The known suffixes are simply the names of the dependencies of the special +target @code{.SUFFIXES}. You can add your own suffixes by writing a rule +for @code{.SUFFIXES} that adds more dependencies, as in + +@example +.SUFFIXES: .hack .win +@end example + +@noindent +which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes. + +If you wish to eliminate the default known suffixes instead of just adding +to them, write a rule for @code{.SUFFIXES} with no dependencies. By +special dispensation, this eliminates all existing dependencies of +@code{.SUFFIXES}. You can then write another rule to add the suffixes you +want. For example, + +@example +.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. + +@node Search Algorithm,, Last Resort, Implicit +@section Implicit Rule Search Algorithm + +Here is the procedure @code{make} uses for searching for an implicit rule +for a target @var{t}. This procedure is followed for each double-colon +rule with no commands, for each target of ordinary rules none of which have +commands, and for each dependency that is not the target of any rule. It +is also followed recursively for dependencies that come from implicit +rules, in the search for a chain of rules. + +Suffix rules are not mentioned in this algorithm because suffix rules are +converted to equivalent pattern rules after the makefiles have been read +in. + +For an archive member target of the form +@samp{@var{archive}(@var{member})}, the following algorithm is run twice, +first using @samp{(@var{member})} as the target @var{t}, and second using +the entire target if the first run found no rule.@refill + +@enumerate +@item +Split @var{t} into a directory part, called @var{d}, and the rest, +called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then +@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 +@var{n}. If the target pattern contains a slash, it is matched +against @var{t}; otherwise, against @var{n}. + +@item +If any rule in that list is @emph{not} a match-anything rule, then +remove all nonterminal match-anything rules from the list. + +@item +Remove any rules with no dependencies from the list. + +@item +For each pattern rule in the list: + +@enumerate +@item +Find the stem @var{s}: the part of @var{d} or @var{n} that the +@samp{%} in the target pattern matches.@refill + +@item +Compute the dependency names by substituting @var{s} for @samp{%}; if +the target pattern does not contain a slash, @var{d} is appended to +the front of each dependency name. + +@item +Test whether all the dependencies exist or ought to exist. (If a +file name mentioned in the makefile as a target or as an explicit +dependency then we say it ought to exist.) + +If all dependencies exist or ought to exist, then this rule applies. +@end enumerate + +@item +If no pattern rule has been found so far, try harder. For +each pattern rule in the list: + +@enumerate +@item +If the rule is a terminal match-anything rule, ignore it and go +on to the next rule. + +@item +Compute the dependency names as before. + +@item +Test whether all the dependencies exist or ought to exist. + +@item +For each dependency that does not exist, follow this algorithm +recursively to see if the dependency can be made by an implicit +rule. + +@item +If all dependencies exist, ought to exist, or can be made by +implicit rules, then this rule applies. +@end enumerate + +@item +If no rule has been found so far, this target cannot be made by an +implicit rule. Return failure. + +@item +If no implicit rule applies, the rule for @code{.DEFAULT}, if any, +applies. In that case, give @var{t} the same commands that +@code{.DEFAULT} has. Otherwise, there are no commands for @var{t}. +@end enumerate + +When the commands of a pattern rule are executed for @var{t}, the automatic +variables @samp{$@@}, @samp{$*} and @samp{$<} are set as follows: + +@table @samp +@item $@@ +@var{t} +@item $* +If the target pattern contains a slash, this is @var{s}; otherwise, it +is @var{d}@var{s}. +@item $< +The name of the first dependency that came via the implicit rule. +@end table + +For @code{.DEFAULT} commands, as for non-implicit commands, @samp{$*} +and @samp{$<} are empty. @samp{$@@} is @var{t}, as always. + +@node Archives, Missing, Implicit, Top +@chapter Using @code{make} to Update Archive Files +@cindex archive + +@dfn{Archive files} are files containing named subfiles called +@dfn{members}; they are maintained with the program @code{ar} and their +main use is as subroutine libraries for linking. + +@menu +* Members: Archive Members. How to name an archive member + as a target or dependency. +* Update: Archive Update. An implicit rule can update + most archive member targets just right. +* Symbols: Archive Symbols. Another implicit rule runs @code{ranlib} + to update the special member @file{__.SYMDEF}. +@end menu + +@node Archive Members, Archive Update, Archives, Archives +@section Archive Members as Targets +@cindex archive member targets + +An individual member of an archive file can be used as a target or +dependency in @code{make}. The archive file must already exist, but the +member need not exist. You specify the member named @var{member} in +archive file @var{archive} as follows: + +@example +@var{archive}(@var{member}) +@end example + +@noindent +This construct is available only in targets and dependencies, not in +commands! Most programs that you might use in commands do not support this +syntax and cannot act directly on archive members. Only @code{ar} and +other programs specifically designed to operate on archives can do so. +Therefore, valid commands to update an archive member target probably must +use @code{ar}. For example, this rule says to create a member +@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}: + +@example +foolib(hack.o) : hack.o + ar r foolib hack.o +@end example + +In fact, nearly all archive member targets are updated in just this way +and there is an implicit rule to do it for you. + +@node Archive Update, Archive Symbols, Archive Members, Archives +@section Implicit Rule for Archive Member Targets + +Recall that a target that looks like @file{@var{a}(@var{m})} stands for the +member named @var{m} in the archive file @var{a}. + +When @code{make} looks for an implicit rule for such a target, as a special +feature it considers implicit rules that match @file{(@var{m})}, as well as +those that match the actual target @file{@var{a}(@var{m})}. + +This causes one special rule whose target is @file{(%)} to match. This +rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m} +into the archive. For example, it will update the archive member target +@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: + +@example +cc -c bar.c -o bar.o +ar r foo.a bar.o +rm -f bar.o +@end example + +@noindent +Here the file @file{bar.o} has been invented as an intermediate file. + +@node Archive Symbols,, Archive Update, Archives +@subsection Updating Archive Symbol Directories +@cindex __.SYMDEF + +An archive file that is used as a library usually contains a special member +named @file{__.SYMDEF} that contains a directory of the external symbol +names defined by all the other members. After you update any other +members, you need to update @file{__.SYMDEF} so that it will summarize the +other members properly. This is done by running the @code{ranlib} program: + +@example +ranlib @var{archivefile} +@end example + +Normally you would put this command in the rule for the archive file, +and make all the members of the archive file dependents of that rule. +For example, + +@example +libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{} + ranlib libfoo.a +@end example + +@noindent +The effect of this is to update archive members @file{x.o}, @file{y.o}, +etc., and then update the symbol directory member @file{__.SYMDEF} by +running @code{ranlib}. The rules for updating the members are not shown +here; most likely you can omit them and use the implicit rule which copies +files into the archive, as described in the preceding section. + +@node Missing, Concept Index, Archives, Top +The variable @code{MAKELEVEL} which keeps track of the current level +of @code{make} recursion. @xref{Recursion}. +The @code{make} programs in various other systems support two features that +are not implemented in GNU @code{make}. +Static pattern rules. @xref{Static Pattern}. + +@item +Selective @code{vpath} search. @xref{Directory Search}. + +@item +Recursive variable references. @xref{Reference}. +@end itemize + +@node Missing, Concept Index, Features, Top +@chapter Missing Features in GNU @code{make} + +The @code{make} programs in various other systems support a few features +that are not implemented in GNU @code{make}. + +suffix rule @samp{.c~.o} would make files @file{@var{n}.o} file from +@item +A target of the form @samp{@var{file}((@var{entry}))} stands for a member +of archive file @var{file}. The member is chosen, not by name, but by +being an object file which defines the linker symbol @var{entry}.@refill + +This feature was not put into GNU @code{make} because of the +@noindent +can be replaced with the GNU @code{make} static pattern rule: + +@example +$(targets): %: %.o lib.a +@end example + +@item +In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search +(@pxref{Directory Search}) have their names changed inside command strings. +We feel it is much cleaner to always use automatic variables and thus +obviate the need for this feature. We are still debating whether to +implement this to be compatible or to leave it out to avoid such ugliness. +@end itemize + +@node Concept Index, Name Index, Missing, Top +@unnumbered Index of Concepts + +@printindex cp + +@node Name Index,, Concept Index, Top +@unnumbered Index of Functions, Directives and Variables + +@printindex fn + +@contents +@bye |