1251881Speter\input texinfo                @c -*- Texinfo -*-
2251881Speter@c %**start of header
3251881Speter@setfilename make.info
4251881Speter
5251881Speter@include version.texi
6251881Speter@set EDITION 0.70
7251881Speter@set RCSID $Id: make.texi,v 1.1.1.1 2014/08/18 06:47:47 christos Exp $
8251881Speter
9251881Speter@settitle GNU @code{make}
10251881Speter@setchapternewpage odd
11251881Speter@c Combine the variable and function indices:
12251881Speter@syncodeindex vr fn
13251881Speter@c Combine the program and concept indices:
14251881Speter@syncodeindex pg cp
15251881Speter@c FSF publishers: format makebook.texi instead of using this file directly.
16251881Speter@c ISBN provided by Lisa M. Opus Goldstein <opus@gnu.org>, 5 May 2004
17251881Speter@set ISBN 1-882114-83-5
18251881Speter@c %**end of header
19251881Speter
20251881Speter@copying
21251881SpeterThis file documents the GNU @code{make} utility, which determines
22251881Speterautomatically which pieces of a large program need to be recompiled,
23251881Speterand issues the commands to recompile them.
24251881Speter
25251881SpeterThis is Edition @value{EDITION}, last updated @value{UPDATED},
26251881Speterof @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}.
27251881Speter
28251881SpeterCopyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
29251881Speter1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006
30251881SpeterFree Software Foundation, Inc.
31251881Speter
32251881Speter@quotation
33251881SpeterPermission is granted to copy, distribute and/or modify this document
34251881Speterunder the terms of the GNU Free Documentation License, Version 1.2 or
35251881Speterany later version published by the Free Software Foundation; with no
36251881SpeterInvariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
37251881Speterand with the Back-Cover Texts as in (a) below.  A copy of the
38251881Speterlicense is included in the section entitled ``GNU Free Documentation
39251881SpeterLicense.''
40251881Speter
41251881Speter(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
42251881Speterthis GNU Manual, like GNU software.  Copies published by the Free
43251881SpeterSoftware Foundation raise funds for GNU development.''
44251881Speter@end quotation
45251881Speter@end copying
46251881Speter
47251881Speter@c finalout
48251881Speter
49251881Speter@c ISPELL CHECK: done, 10 June 1993 --roland
50251881Speter@c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz
51251881Speter
52251881Speter
53251881Speter@dircategory GNU Packages
54251881Speter@direntry
55251881Speter* Make: (make).            Remake files automatically.
56251881Speter@end direntry
57251881Speter
58251881Speter@iftex
59251881Speter@shorttitlepage GNU Make
60251881Speter@end iftex
61251881Speter@titlepage
62251881Speter@title GNU Make
63251881Speter@subtitle A Program for Directing Recompilation
64251881Speter@subtitle GNU @code{make} Version @value{VERSION}
65251881Speter@subtitle @value{UPDATED-MONTH}
66251881Speter@author Richard M. Stallman, Roland McGrath, Paul D. Smith
67251881Speter@page
68251881Speter@vskip 0pt plus 1filll
69251881Speter@insertcopying
70251881Speter@sp 2
71251881SpeterPublished by the Free Software Foundation @*
72251881Speter51 Franklin St. -- Fifth Floor @*
73251881SpeterBoston, MA 02110-1301 USA @*
74251881SpeterISBN @value{ISBN} @*
75251881Speter@sp 2
76251881SpeterCover art by Etienne Suvasa.
77251881Speter@end titlepage
78251881Speter
79251881Speter@summarycontents
80251881Speter@contents
81251881Speter
82251881Speter@ifnottex
83251881Speter@node Top, Overview, (dir), (dir)
84251881Speter@top GNU @code{make}
85251881Speter
86251881Speter@insertcopying
87251881Speter@end ifnottex
88251881Speter
89251881Speter@menu
90251881Speter* Overview::                    Overview of @code{make}.
91251881Speter* Introduction::                An introduction to @code{make}.
92251881Speter* Makefiles::                   Makefiles tell @code{make} what to do.
93251881Speter* Rules::                       Rules describe when a file must be remade.
94251881Speter* Commands::                    Commands say how to remake a file.
95251881Speter* Using Variables::             You can use variables to avoid repetition.
96251881Speter* Conditionals::                Use or ignore parts of the makefile based
97251881Speter                                  on the values of variables.
98251881Speter* Functions::                   Many powerful ways to manipulate text.
99251881Speter* Invoking make: Running.       How to invoke @code{make} on the command line.
100251881Speter* Implicit Rules::              Use implicit rules to treat many files alike,
101251881Speter                                  based on their file names.
102251881Speter* Archives::                    How @code{make} can update library archives.
103251881Speter* Features::                    Features GNU @code{make} has over other @code{make}s.
104251881Speter* Missing::                     What GNU @code{make} lacks from other @code{make}s.
105251881Speter* Makefile Conventions::        Conventions for writing makefiles for
106251881Speter                                  GNU programs.
107251881Speter* Quick Reference::             A quick reference for experienced users.
108251881Speter* Error Messages::              A list of common errors generated by @code{make}.
109251881Speter* Complex Makefile::            A real example of a straightforward,
110251881Speter                                  but nontrivial, makefile.
111251881Speter
112251881Speter* GNU Free Documentation License::  License for copying this manual
113251881Speter* Concept Index::               Index of Concepts
114251881Speter* Name Index::                  Index of Functions, Variables, & Directives
115251881Speter
116251881Speter@detailmenu
117251881Speter --- The Detailed Node Listing ---
118251881Speter
119251881SpeterOverview of @code{make}
120251881Speter
121251881Speter* Preparing::                   Preparing and Running Make
122251881Speter* Reading::                     On Reading this Text
123251881Speter* Bugs::                        Problems and Bugs
124251881Speter
125251881SpeterAn Introduction to Makefiles
126251881Speter
127251881Speter* Rule Introduction::           What a rule looks like.
128251881Speter* Simple Makefile::             A Simple Makefile
129251881Speter* How Make Works::              How @code{make} Processes This Makefile
130251881Speter* Variables Simplify::          Variables Make Makefiles Simpler
131251881Speter* make Deduces::                Letting @code{make} Deduce the Commands
132251881Speter* Combine By Prerequisite::     Another Style of Makefile
133251881Speter* Cleanup::                     Rules for Cleaning the Directory
134251881Speter
135251881SpeterWriting Makefiles
136251881Speter
137251881Speter* Makefile Contents::           What makefiles contain.
138251881Speter* Makefile Names::              How to name your makefile.
139251881Speter* Include::                     How one makefile can use another makefile.
140251881Speter* MAKEFILES Variable::          The environment can specify extra makefiles.
141251881Speter* MAKEFILE_LIST Variable::      Discover which makefiles have been read.
142251881Speter* Special Variables::           Other special variables.
143251881Speter* Remaking Makefiles::          How makefiles get remade.
144251881Speter* Overriding Makefiles::        How to override part of one makefile
145251881Speter                                  with another makefile.
146251881Speter* Reading Makefiles::           How makefiles are parsed.
147251881Speter* Secondary Expansion::         How and when secondary expansion is performed.
148251881Speter
149251881SpeterWriting Rules
150251881Speter
151251881Speter* Rule Example::                An example explained.
152251881Speter* Rule Syntax::                 General syntax explained.
153251881Speter* Prerequisite Types::          There are two types of prerequisites.
154251881Speter* Wildcards::                   Using wildcard characters such as `*'.
155251881Speter* Directory Search::            Searching other directories for source files.
156251881Speter* Phony Targets::               Using a target that is not a real file's name.
157251881Speter* Force Targets::               You can use a target without commands
158251881Speter                                  or prerequisites to mark other targets
159251881Speter                                  as phony.
160251881Speter* Empty Targets::               When only the date matters and the
161251881Speter                                  files are empty.
162251881Speter* Special Targets::             Targets with special built-in meanings.
163251881Speter* Multiple Targets::            When to make use of several targets in a rule.
164251881Speter* Multiple Rules::              How to use several rules with the same target.
165251881Speter* Static Pattern::              Static pattern rules apply to multiple targets
166251881Speter                                  and can vary the prerequisites according to
167251881Speter                                  the target name.
168251881Speter* Double-Colon::                How to use a special kind of rule to allow
169251881Speter                                  several independent rules for one target.
170251881Speter* Automatic Prerequisites::     How to automatically generate rules giving
171251881Speter                                  prerequisites from source files themselves.
172251881Speter
173251881SpeterUsing Wildcard Characters in File Names
174251881Speter
175251881Speter* Wildcard Examples::           Several examples
176251881Speter* Wildcard Pitfall::            Problems to avoid.
177251881Speter* Wildcard Function::           How to cause wildcard expansion where
178251881Speter                                  it does not normally take place.
179251881Speter
180251881SpeterSearching Directories for Prerequisites
181251881Speter
182251881Speter* General Search::              Specifying a search path that applies
183251881Speter                                  to every prerequisite.
184251881Speter* Selective Search::            Specifying a search path
185251881Speter                                  for a specified class of names.
186251881Speter* Search Algorithm::            When and how search paths are applied.
187251881Speter* Commands/Search::             How to write shell commands that work together
188251881Speter                                  with search paths.
189251881Speter* Implicit/Search::             How search paths affect implicit rules.
190251881Speter* Libraries/Search::            Directory search for link libraries.
191251881Speter
192251881SpeterStatic Pattern Rules
193251881Speter
194251881Speter* Static Usage::                The syntax of static pattern rules.
195251881Speter* Static versus Implicit::      When are they better than implicit rules?
196251881Speter
197251881SpeterWriting the Commands in Rules
198251881Speter
199251881Speter* Command Syntax::              Command syntax features and pitfalls.
200251881Speter* Echoing::                     How to control when commands are echoed.
201251881Speter* Execution::                   How commands are executed.
202251881Speter* Parallel::                    How commands can be executed in parallel.
203251881Speter* Errors::                      What happens after a command execution error.
204251881Speter* Interrupts::                  What happens when a command is interrupted.
205251881Speter* Recursion::                   Invoking @code{make} from makefiles.
206251881Speter* Sequences::                   Defining canned sequences of commands.
207251881Speter* Empty Commands::              Defining useful, do-nothing commands.
208251881Speter
209251881SpeterCommand Syntax
210251881Speter
211251881Speter* Splitting Lines::             Breaking long command lines for readability.
212251881Speter* Variables in Commands::       Using @code{make} variables in commands.
213251881Speter
214251881SpeterCommand Execution
215251881Speter
216251881Speter* Choosing the Shell::          How @code{make} chooses the shell used
217251881Speter                                  to run commands.
218
219Recursive Use of @code{make}
220
221* MAKE Variable::               The special effects of using @samp{$(MAKE)}.
222* Variables/Recursion::         How to communicate variables to a sub-@code{make}.
223* Options/Recursion::           How to communicate options to a sub-@code{make}.
224* -w Option::                   How the @samp{-w} or @samp{--print-directory} option
225                                  helps debug use of recursive @code{make} commands.
226
227How to Use Variables
228
229* Reference::                   How to use the value of a variable.
230* Flavors::                     Variables come in two flavors.
231* Advanced::                    Advanced features for referencing a variable.
232* Values::                      All the ways variables get their values.
233* Setting::                     How to set a variable in the makefile.
234* Appending::                   How to append more text to the old value
235                                  of a variable.
236* Override Directive::          How to set a variable in the makefile even if
237                                  the user has set it with a command argument.
238* Defining::                    An alternate way to set a variable
239                                  to a verbatim string.
240* Environment::                 Variable values can come from the environment.
241* Target-specific::             Variable values can be defined on a per-target
242                                  basis.
243* Pattern-specific::            Target-specific variable values can be applied
244                                  to a group of targets that match a pattern.
245
246Advanced Features for Reference to Variables
247
248* Substitution Refs::           Referencing a variable with
249                                  substitutions on the value.
250* Computed Names::              Computing the name of the variable to refer to.
251
252Conditional Parts of Makefiles
253
254* Conditional Example::         Example of a conditional
255* Conditional Syntax::          The syntax of conditionals.
256* Testing Flags::               Conditionals that test flags.
257
258Functions for Transforming Text
259
260* Syntax of Functions::         How to write a function call.
261* Text Functions::              General-purpose text manipulation functions.
262* File Name Functions::         Functions for manipulating file names.
263* Conditional Functions::       Functions that implement conditions.
264* Foreach Function::            Repeat some text with controlled variation.
265* Call Function::               Expand a user-defined function.
266* Value Function::              Return the un-expanded value of a variable.
267* Eval Function::               Evaluate the arguments as makefile syntax.
268* Origin Function::             Find where a variable got its value.
269* Flavor Function::             Find out the flavor of a variable.
270* Shell Function::              Substitute the output of a shell command.
271* Make Control Functions::      Functions that control how make runs.
272
273How to Run @code{make}
274
275* Makefile Arguments::          How to specify which makefile to use.
276* Goals::                       How to use goal arguments to specify which
277                                  parts of the makefile to use.
278* Instead of Execution::        How to use mode flags to specify what
279                                  kind of thing to do with the commands
280                                  in the makefile other than simply
281                                  execute them.
282* Avoiding Compilation::        How to avoid recompiling certain files.
283* Overriding::                  How to override a variable to specify
284                                  an alternate compiler and other things.
285* Testing::                     How to proceed past some errors, to
286                                  test compilation.
287* Options Summary::             Summary of Options
288
289Using Implicit Rules
290
291* Using Implicit::              How to use an existing implicit rule
292                                  to get the commands for updating a file.
293* Catalogue of Rules::          A list of built-in implicit rules.
294* Implicit Variables::          How to change what predefined rules do.
295* Chained Rules::               How to use a chain of implicit rules.
296* Pattern Rules::               How to define new implicit rules.
297* Last Resort::                 How to define commands for rules which
298                                  cannot find any.
299* Suffix Rules::                The old-fashioned style of implicit rule.
300* Implicit Rule Search::        The precise algorithm for applying
301                                  implicit rules.
302
303Defining and Redefining Pattern Rules
304
305* Pattern Intro::               An introduction to pattern rules.
306* Pattern Examples::            Examples of pattern rules.
307* Automatic Variables::         How to use automatic variables in the
308                                  commands of implicit rules.
309* Pattern Match::               How patterns match.
310* Match-Anything Rules::        Precautions you should take prior to
311                                  defining rules that can match any
312                                  target file whatever.
313* Canceling Rules::             How to override or cancel built-in rules.
314
315Using @code{make} to Update Archive Files
316
317* Archive Members::             Archive members as targets.
318* Archive Update::              The implicit rule for archive member targets.
319* Archive Pitfalls::            Dangers to watch out for when using archives.
320* Archive Suffix Rules::        You can write a special kind of suffix rule
321                                  for updating archives.
322
323Implicit Rule for Archive Member Targets
324
325* Archive Symbols::             How to update archive symbol directories.
326
327@end detailmenu
328@end menu
329
330@node Overview, Introduction, Top, Top
331@comment  node-name,  next,  previous,  up
332@chapter Overview of @code{make}
333
334The @code{make} utility automatically determines which pieces of a large
335program need to be recompiled, and issues commands to recompile them.
336This manual describes GNU @code{make}, which was implemented by Richard
337Stallman and Roland McGrath.  Development since Version 3.76 has been
338handled by Paul D. Smith.
339
340GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard
3411003.2-1992} (POSIX.2).
342@cindex POSIX
343@cindex IEEE Standard 1003.2
344@cindex standards conformance
345
346Our examples show C programs, since they are most common, but you can use
347@code{make} with any programming language whose compiler can be run with a
348shell command.  Indeed, @code{make} is not limited to programs.  You can
349use it to describe any task where some files must be updated automatically
350from others whenever the others change.
351
352@menu
353* Preparing::                   Preparing and Running Make
354* Reading::                     On Reading this Text
355* Bugs::                        Problems and Bugs
356@end menu
357
358@node Preparing, Reading, Overview, Overview
359@ifnottex
360@heading Preparing and Running Make
361@end ifnottex
362
363To prepare to use @code{make}, you must write a file called
364the @dfn{makefile} that describes the relationships among files
365in your program and provides commands for updating each file.
366In a program, typically, the executable file is updated from object
367files, which are in turn made by compiling source files.@refill
368
369Once a suitable makefile exists, each time you change some source files,
370this simple shell command:
371
372@example
373make
374@end example
375
376@noindent
377suffices to perform all necessary recompilations.  The @code{make} program
378uses the makefile data base and the last-modification times of the files to
379decide which of the files need to be updated.  For each of those files, it
380issues the commands recorded in the data base.
381
382You can provide command line arguments to @code{make} to control which
383files should be recompiled, or how.  @xref{Running, ,How to Run
384@code{make}}.
385
386@node Reading, Bugs, Preparing, Overview
387@section How to Read This Manual
388
389If you are new to @code{make}, or are looking for a general
390introduction, read the first few sections of each chapter, skipping the
391later sections.  In each chapter, the first few sections contain
392introductory or general information and the later sections contain
393specialized or technical information.
394@ifnottex
395The exception is the second chapter, @ref{Introduction, ,An
396Introduction to Makefiles}, all of which is introductory.
397@end ifnottex
398@iftex
399The exception is @ref{Introduction, ,An Introduction to Makefiles},
400all of which is introductory.
401@end iftex
402
403If you are familiar with other @code{make} programs, see @ref{Features,
404,Features of GNU @code{make}}, which lists the enhancements GNU
405@code{make} has, and @ref{Missing, ,Incompatibilities and Missing
406Features}, which explains the few things GNU @code{make} lacks that
407others have.
408
409For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
410and @ref{Special Targets}.
411
412@node Bugs,  , Reading, Overview
413@section Problems and Bugs
414@cindex reporting bugs
415@cindex bugs, reporting
416@cindex problems and bugs, reporting
417
418If you have problems with GNU @code{make} or think you've found a bug,
419please report it to the developers; we cannot promise to do anything but
420we might well want to fix it.
421
422Before reporting a bug, make sure you've actually found a real bug.
423Carefully reread the documentation and see if it really says you can do
424what you're trying to do.  If it's not clear whether you should be able
425to do something or not, report that too; it's a bug in the
426documentation!
427
428Before reporting a bug or trying to fix it yourself, try to isolate it
429to the smallest possible makefile that reproduces the problem.  Then
430send us the makefile and the exact results @code{make} gave you,
431including any error or warning messages.  Please don't paraphrase
432these messages: it's best to cut and paste them into your report.
433When generating this small makefile, be sure to not use any non-free
434or unusual tools in your commands: you can almost always emulate what
435such a tool would do with simple shell commands.  Finally, be sure to
436explain what you expected to occur; this will help us decide whether
437the problem was really in the documentation.
438
439Once you have a precise problem you can report it in one of two ways.
440Either send electronic mail to:
441
442@example
443    bug-make@@gnu.org
444@end example
445
446@noindent
447or use our Web-based project management tool, at:
448
449@example
450    http://savannah.gnu.org/projects/make/
451@end example
452
453@noindent
454In addition to the information above, please be careful to include the
455version number of @code{make} you are using.  You can get this
456information with the command @samp{make --version}.  Be sure also to
457include the type of machine and operating system you are using.  One
458way to obtain this information is by looking at the final lines of
459output from the command @samp{make --help}.
460
461@node Introduction, Makefiles, Overview, Top
462@comment  node-name,  next,  previous,  up
463@chapter An Introduction to Makefiles
464
465You need a file called a @dfn{makefile} to tell @code{make} what to do.
466Most often, the makefile tells @code{make} how to compile and link a
467program.
468@cindex makefile
469
470In this chapter, we will discuss a simple makefile that describes how to
471compile and link a text editor which consists of eight C source files
472and three header files.  The makefile can also tell @code{make} how to
473run miscellaneous commands when explicitly asked (for example, to remove
474certain files as a clean-up operation).  To see a more complex example
475of a makefile, see @ref{Complex Makefile}.
476
477When @code{make} recompiles the editor, each changed C source file
478must be recompiled.  If a header file has changed, each C source file
479that includes the header file must be recompiled to be safe.  Each
480compilation produces an object file corresponding to the source file.
481Finally, if any source file has been recompiled, all the object files,
482whether newly made or saved from previous compilations, must be linked
483together to produce the new executable editor.
484@cindex recompilation
485@cindex editor
486
487@menu
488* Rule Introduction::           What a rule looks like.
489* Simple Makefile::             A Simple Makefile
490* How Make Works::              How @code{make} Processes This Makefile
491* Variables Simplify::          Variables Make Makefiles Simpler
492* make Deduces::                Letting @code{make} Deduce the Commands
493* Combine By Prerequisite::     Another Style of Makefile
494* Cleanup::                     Rules for Cleaning the Directory
495@end menu
496
497@node Rule Introduction, Simple Makefile, Introduction, Introduction
498@comment  node-name,  next,  previous,  up
499@section What a Rule Looks Like
500@cindex rule, introduction to
501@cindex makefile rule parts
502@cindex parts of makefile rule
503
504A simple makefile consists of ``rules'' with the following shape:
505
506@cindex targets, introduction to
507@cindex prerequisites, introduction to
508@cindex commands, introduction to
509@example
510@group
511@var{target} @dots{} : @var{prerequisites} @dots{}
512        @var{command}
513        @dots{}
514        @dots{}
515@end group
516@end example
517
518A @dfn{target} is usually the name of a file that is generated by a
519program; examples of targets are executable or object files.  A target
520can also be the name of an action to carry out, such as @samp{clean}
521(@pxref{Phony Targets}).
522
523A @dfn{prerequisite} is a file that is used as input to create the
524target.  A target often depends on several files.
525
526@cindex tabs in rules
527A @dfn{command} is an action that @code{make} carries out.
528A rule may have more than one command, each on its own line.
529@strong{Please note:} you need to put a tab character at the beginning of
530every command line!  This is an obscurity that catches the unwary.
531
532Usually a command is in a rule with prerequisites and serves to create a
533target file if any of the prerequisites change.  However, the rule that
534specifies commands for the target need not have prerequisites.  For
535example, the rule containing the delete command associated with the
536target @samp{clean} does not have prerequisites.
537
538A @dfn{rule}, then, explains how and when to remake certain files
539which are the targets of the particular rule.  @code{make} carries out
540the commands on the prerequisites to create or update the target.  A
541rule can also explain how and when to carry out an action.
542@xref{Rules, , Writing Rules}.
543
544A makefile may contain other text besides rules, but a simple makefile
545need only contain rules.  Rules may look somewhat more complicated
546than shown in this template, but all fit the pattern more or less.
547
548@node Simple Makefile, How Make Works, Rule Introduction, Introduction
549@section A Simple Makefile
550@cindex simple makefile
551@cindex makefile, simple
552
553Here is a straightforward makefile that describes the way an
554executable file called @code{edit} depends on eight object files
555which, in turn, depend on eight C source and three header files.
556
557In this example, all the C files include @file{defs.h}, but only those
558defining editing commands include @file{command.h}, and only low
559level files that change the editor buffer include @file{buffer.h}.
560
561@example
562@group
563edit : main.o kbd.o command.o display.o \
564       insert.o search.o files.o utils.o
565        cc -o edit main.o kbd.o command.o display.o \
566                   insert.o search.o files.o utils.o
567
568main.o : main.c defs.h
569        cc -c main.c
570kbd.o : kbd.c defs.h command.h
571        cc -c kbd.c
572command.o : command.c defs.h command.h
573        cc -c command.c
574display.o : display.c defs.h buffer.h
575        cc -c display.c
576insert.o : insert.c defs.h buffer.h
577        cc -c insert.c
578search.o : search.c defs.h buffer.h
579        cc -c search.c
580files.o : files.c defs.h buffer.h command.h
581        cc -c files.c
582utils.o : utils.c defs.h
583        cc -c utils.c
584clean :
585        rm edit main.o kbd.o command.o display.o \
586           insert.o search.o files.o utils.o
587@end group
588@end example
589
590@noindent
591We split each long line into two lines using backslash-newline; this is
592like using one long line, but is easier to read.
593@cindex continuation lines
594@cindex @code{\} (backslash), for continuation lines
595@cindex backslash (@code{\}), for continuation lines
596@cindex quoting newline, in makefile
597@cindex newline, quoting, in makefile
598
599To use this makefile to create the executable file called @file{edit},
600type:
601
602@example
603make
604@end example
605
606To use this makefile to delete the executable file and all the object
607files from the directory, type:
608
609@example
610make clean
611@end example
612
613In the example makefile, the targets include the executable file
614@samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}.  The
615prerequisites are files such as @samp{main.c} and @samp{defs.h}.
616In fact, each @samp{.o} file is both a target and a prerequisite.
617Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
618
619When a target is a file, it needs to be recompiled or relinked if any
620of its prerequisites change.  In addition, any prerequisites that are
621themselves automatically generated should be updated first.  In this
622example, @file{edit} depends on each of the eight object files; the
623object file @file{main.o} depends on the source file @file{main.c} and
624on the header file @file{defs.h}.
625
626A shell command follows each line that contains a target and
627prerequisites.  These shell commands say how to update the target file.
628A tab character must come at the beginning of every command line to
629distinguish command lines from other lines in the makefile.  (Bear in
630mind that @code{make} does not know anything about how the commands
631work.  It is up to you to supply commands that will update the target
632file properly.  All @code{make} does is execute the commands in the rule
633you have specified when the target file needs to be updated.)
634@cindex shell command
635
636The target @samp{clean} is not a file, but merely the name of an
637action.  Since you
638normally
639do not want to carry out the actions in this rule, @samp{clean} is not a prerequisite of any other rule.
640Consequently, @code{make} never does anything with it unless you tell
641it specifically.  Note that this rule not only is not a prerequisite, it
642also does not have any prerequisites, so the only purpose of the rule
643is to run the specified commands.  Targets that do not refer to files
644but are just actions are called @dfn{phony targets}.  @xref{Phony
645Targets}, for information about this kind of target.  @xref{Errors, ,
646Errors in Commands}, to see how to cause @code{make} to ignore errors
647from @code{rm} or any other command.
648@cindex @code{clean} target
649@cindex @code{rm} (shell command)
650
651@node How Make Works, Variables Simplify, Simple Makefile, Introduction
652@comment  node-name,  next,  previous,  up
653@section How @code{make} Processes a Makefile
654@cindex processing a makefile
655@cindex makefile, how @code{make} processes
656
657By default, @code{make} starts with the first target (not targets whose
658names start with @samp{.}).  This is called the @dfn{default goal}.
659(@dfn{Goals} are the targets that @code{make} strives ultimately to
660update.    You can override this behavior using the command line
661(@pxref{Goals, , Arguments to Specify the Goals}) or with the
662@code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, ,
663Other Special Variables}).
664@cindex default goal
665@cindex goal, default
666@cindex goal
667
668In the simple example of the previous section, the default goal is to
669update the executable program @file{edit}; therefore, we put that rule
670first.
671
672Thus, when you give the command:
673
674@example
675make
676@end example
677
678@noindent
679@code{make} reads the makefile in the current directory and begins by
680processing the first rule.  In the example, this rule is for relinking
681@file{edit}; but before @code{make} can fully process this rule, it
682must process the rules for the files that @file{edit} depends on,
683which in this case are the object files.  Each of these files is
684processed according to its own rule.  These rules say to update each
685@samp{.o} file by compiling its source file.  The recompilation must
686be done if the source file, or any of the header files named as
687prerequisites, is more recent than the object file, or if the object
688file does not exist.
689
690The other rules are processed because their targets appear as
691prerequisites of the goal.  If some other rule is not depended on by the
692goal (or anything it depends on, etc.), that rule is not processed,
693unless you tell @code{make} to do so (with a command such as
694@w{@code{make clean}}).
695
696Before recompiling an object file, @code{make} considers updating its
697prerequisites, the source file and header files.  This makefile does not
698specify anything to be done for them---the @samp{.c} and @samp{.h} files
699are not the targets of any rules---so @code{make} does nothing for these
700files.  But @code{make} would update automatically generated C programs,
701such as those made by Bison or Yacc, by their own rules at this time.
702
703After recompiling whichever object files need it, @code{make} decides
704whether to relink @file{edit}.  This must be done if the file
705@file{edit} does not exist, or if any of the object files are newer than
706it.  If an object file was just recompiled, it is now newer than
707@file{edit}, so @file{edit} is relinked.
708@cindex relinking
709
710Thus, if we change the file @file{insert.c} and run @code{make},
711@code{make} will compile that file to update @file{insert.o}, and then
712link @file{edit}.  If we change the file @file{command.h} and run
713@code{make}, @code{make} will recompile the object files @file{kbd.o},
714@file{command.o} and @file{files.o} and then link the file @file{edit}.
715
716@node Variables Simplify, make Deduces, How Make Works, Introduction
717@section Variables Make Makefiles Simpler
718@cindex variables
719@cindex simplifying with variables
720
721In our example, we had to list all the object files twice in the rule for
722@file{edit} (repeated here):
723
724@example
725@group
726edit : main.o kbd.o command.o display.o \
727              insert.o search.o files.o utils.o
728        cc -o edit main.o kbd.o command.o display.o \
729                   insert.o search.o files.o utils.o
730@end group
731@end example
732
733@cindex @code{objects}
734Such duplication is error-prone; if a new object file is added to the
735system, we might add it to one list and forget the other.  We can eliminate
736the risk and simplify the makefile by using a variable.  @dfn{Variables}
737allow a text string to be defined once and substituted in multiple places
738later (@pxref{Using Variables, ,How to Use Variables}).
739
740@cindex @code{OBJECTS}
741@cindex @code{objs}
742@cindex @code{OBJS}
743@cindex @code{obj}
744@cindex @code{OBJ}
745It is standard practice for every makefile to have a variable named
746@code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
747or @code{OBJ} which is a list of all object file names.  We would
748define such a variable @code{objects} with a line like this in the
749makefile:@refill
750
751@example
752@group
753objects = main.o kbd.o command.o display.o \
754          insert.o search.o files.o utils.o
755@end group
756@end example
757
758@noindent
759Then, each place we want to put a list of the object file names, we can
760substitute the variable's value by writing @samp{$(objects)}
761(@pxref{Using Variables, ,How to Use Variables}).
762
763Here is how the complete simple makefile looks when you use a variable
764for the object files:
765
766@example
767@group
768objects = main.o kbd.o command.o display.o \
769          insert.o search.o files.o utils.o
770
771edit : $(objects)
772        cc -o edit $(objects)
773main.o : main.c defs.h
774        cc -c main.c
775kbd.o : kbd.c defs.h command.h
776        cc -c kbd.c
777command.o : command.c defs.h command.h
778        cc -c command.c
779display.o : display.c defs.h buffer.h
780        cc -c display.c
781insert.o : insert.c defs.h buffer.h
782        cc -c insert.c
783search.o : search.c defs.h buffer.h
784        cc -c search.c
785files.o : files.c defs.h buffer.h command.h
786        cc -c files.c
787utils.o : utils.c defs.h
788        cc -c utils.c
789clean :
790        rm edit $(objects)
791@end group
792@end example
793
794@node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction
795@section Letting @code{make} Deduce the Commands
796@cindex deducing commands (implicit rules)
797@cindex implicit rule, introduction to
798@cindex rule, implicit, introduction to
799
800It is not necessary to spell out the commands for compiling the individual
801C source files, because @code{make} can figure them out: it has an
802@dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
803named @samp{.c} file using a @samp{cc -c} command.  For example, it will
804use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
805@file{main.o}.  We can therefore omit the commands from the rules for the
806object files.  @xref{Implicit Rules, ,Using Implicit Rules}.@refill
807
808When a @samp{.c} file is used automatically in this way, it is also
809automatically added to the list of prerequisites.  We can therefore omit
810the @samp{.c} files from the prerequisites, provided we omit the commands.
811
812Here is the entire example, with both of these changes, and a variable
813@code{objects} as suggested above:
814
815@example
816@group
817objects = main.o kbd.o command.o display.o \
818          insert.o search.o files.o utils.o
819
820edit : $(objects)
821        cc -o edit $(objects)
822
823main.o : defs.h
824kbd.o : defs.h command.h
825command.o : defs.h command.h
826display.o : defs.h buffer.h
827insert.o : defs.h buffer.h
828search.o : defs.h buffer.h
829files.o : defs.h buffer.h command.h
830utils.o : defs.h
831
832.PHONY : clean
833clean :
834        rm edit $(objects)
835@end group
836@end example
837
838@noindent
839This is how we would write the makefile in actual practice.  (The
840complications associated with @samp{clean} are described elsewhere.
841See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
842
843Because implicit rules are so convenient, they are important.  You
844will see them used frequently.@refill
845
846@node Combine By Prerequisite, Cleanup, make Deduces, Introduction
847@section Another Style of Makefile
848@cindex combining rules by prerequisite
849
850When the objects of a makefile are created only by implicit rules, an
851alternative style of makefile is possible.  In this style of makefile,
852you group entries by their prerequisites instead of by their targets.
853Here is what one looks like:
854
855@example
856@group
857objects = main.o kbd.o command.o display.o \
858          insert.o search.o files.o utils.o
859
860edit : $(objects)
861        cc -o edit $(objects)
862
863$(objects) : defs.h
864kbd.o command.o files.o : command.h
865display.o insert.o search.o files.o : buffer.h
866@end group
867@end example
868
869@noindent
870Here @file{defs.h} is given as a prerequisite of all the object files;
871@file{command.h} and @file{buffer.h} are prerequisites of the specific
872object files listed for them.
873
874Whether this is better is a matter of taste: it is more compact, but some
875people dislike it because they find it clearer to put all the information
876about each target in one place.
877
878@node Cleanup,  , Combine By Prerequisite, Introduction
879@section Rules for Cleaning the Directory
880@cindex cleaning up
881@cindex removing, to clean up
882
883Compiling a program is not the only thing you might want to write rules
884for.  Makefiles commonly tell how to do a few other things besides
885compiling a program: for example, how to delete all the object files
886and executables so that the directory is @samp{clean}.
887
888@cindex @code{clean} target
889Here is how we
890could write a @code{make} rule for cleaning our example editor:
891
892@example
893@group
894clean:
895        rm edit $(objects)
896@end group
897@end example
898
899In practice, we might want to write the rule in a somewhat more
900complicated manner to handle unanticipated situations.  We would do this:
901
902@example
903@group
904.PHONY : clean
905clean :
906        -rm edit $(objects)
907@end group
908@end example
909
910@noindent
911This prevents @code{make} from getting confused by an actual file
912called @file{clean} and causes it to continue in spite of errors from
913@code{rm}.  (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
914Commands}.)
915
916@noindent
917A rule such as this should not be placed at the beginning of the
918makefile, because we do not want it to run by default!  Thus, in the
919example makefile, we want the rule for @code{edit}, which recompiles
920the editor, to remain the default goal.
921
922Since @code{clean} is not a prerequisite of @code{edit}, this rule will not
923run at all if we give the command @samp{make} with no arguments.  In
924order to make the rule run, we have to type @samp{make clean}.
925@xref{Running, ,How to Run @code{make}}.
926
927@node Makefiles, Rules, Introduction, Top
928@chapter Writing Makefiles
929
930@cindex makefile, how to write
931The information that tells @code{make} how to recompile a system comes from
932reading a data base called the @dfn{makefile}.
933
934@menu
935* Makefile Contents::           What makefiles contain.
936* Makefile Names::              How to name your makefile.
937* Include::                     How one makefile can use another makefile.
938* MAKEFILES Variable::          The environment can specify extra makefiles.
939* MAKEFILE_LIST Variable::      Discover which makefiles have been read.
940* Special Variables::           Other special variables.
941* Remaking Makefiles::          How makefiles get remade.
942* Overriding Makefiles::        How to override part of one makefile
943                                  with another makefile.
944* Reading Makefiles::           How makefiles are parsed.
945* Secondary Expansion::         How and when secondary expansion is performed.
946@end menu
947
948@node Makefile Contents, Makefile Names, Makefiles, Makefiles
949@section What Makefiles Contain
950
951Makefiles contain five kinds of things: @dfn{explicit rules},
952@dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
953and @dfn{comments}.  Rules, variables, and directives are described at
954length in later chapters.@refill
955
956@itemize @bullet
957@cindex rule, explicit, definition of
958@cindex explicit rule, definition of
959@item
960An @dfn{explicit rule} says when and how to remake one or more files,
961called the rule's @dfn{targets}.  It lists the other files that the
962targets depend on, called the @dfn{prerequisites} of the target, and
963may also give commands to use to create or update the targets.
964@xref{Rules, ,Writing Rules}.
965
966@cindex rule, implicit, definition of
967@cindex implicit rule, definition of
968@item
969An @dfn{implicit rule} says when and how to remake a class of files
970based on their names.  It describes how a target may depend on a file
971with a name similar to the target and gives commands to create or
972update such a target.  @xref{Implicit Rules, ,Using Implicit Rules}.
973
974@cindex variable definition
975@item
976A @dfn{variable definition} is a line that specifies a text string
977value for a variable that can be substituted into the text later.  The
978simple makefile example shows a variable definition for @code{objects}
979as a list of all object files (@pxref{Variables Simplify, , Variables
980Make Makefiles Simpler}).
981
982@cindex directive
983@item
984A @dfn{directive} is a command for @code{make} to do something special while
985reading the makefile.  These include:
986
987@itemize @bullet
988@item
989Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
990
991@item
992Deciding (based on the values of variables) whether to use or
993ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
994
995@item
996Defining a variable from a verbatim string containing multiple lines
997(@pxref{Defining, ,Defining Variables Verbatim}).
998@end itemize
999
1000@cindex comments, in makefile
1001@cindex @code{#} (comments), in makefile
1002@item
1003@samp{#} in a line of a makefile starts a @dfn{comment}.  It and the
1004rest of the line are ignored, except that a trailing backslash not
1005escaped by another backslash will continue the comment across multiple
1006lines.  A line containing just a comment (with perhaps spaces before
1007it) is effectively blank, and is ignored.  If you want a literal
1008@code{#}, escape it with a backslash (e.g., @code{\#}).  Comments may
1009appear on any line in the makefile, although they are treated
1010specially in certain situations.
1011
1012Within a command script (if the line begins with a TAB character) the
1013entire line is passed to the shell, just as with any other line that
1014begins with a TAB.  The shell decides how to interpret the text:
1015whether or not this is a comment is up to the shell.
1016
1017Within a @code{define} directive, comments are not ignored during the
1018definition of the variable, but rather kept intact in the value of the
1019variable.  When the variable is expanded they will either be treated
1020as @code{make} comments or as command script text, depending on the
1021context in which the variable is evaluated.
1022@end itemize
1023
1024@node Makefile Names, Include, Makefile Contents, Makefiles
1025@section What Name to Give Your Makefile
1026@cindex makefile name
1027@cindex name of makefile
1028@cindex default makefile name
1029@cindex file name of makefile
1030
1031@c following paragraph rewritten to avoid overfull hbox
1032By default, when @code{make} looks for the makefile, it tries the
1033following names, in order: @file{GNUmakefile}, @file{makefile}
1034and @file{Makefile}.@refill
1035@findex Makefile
1036@findex GNUmakefile
1037@findex makefile
1038
1039@cindex @code{README}
1040Normally you should call your makefile either @file{makefile} or
1041@file{Makefile}.  (We recommend @file{Makefile} because it appears
1042prominently near the beginning of a directory listing, right near other
1043important files such as @file{README}.)  The first name checked,
1044@file{GNUmakefile}, is not recommended for most makefiles.  You should
1045use this name if you have a makefile that is specific to GNU
1046@code{make}, and will not be understood by other versions of
1047@code{make}.  Other @code{make} programs look for @file{makefile} and
1048@file{Makefile}, but not @file{GNUmakefile}.
1049
1050If @code{make} finds none of these names, it does not use any makefile.
1051Then you must specify a goal with a command argument, and @code{make}
1052will attempt to figure out how to remake it using only its built-in
1053implicit rules.  @xref{Implicit Rules, ,Using Implicit Rules}.
1054
1055@cindex @code{-f}
1056@cindex @code{--file}
1057@cindex @code{--makefile}
1058If you want to use a nonstandard name for your makefile, you can specify
1059the makefile name with the @samp{-f} or @samp{--file} option.  The
1060arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1061@code{make} to read the file @var{name} as the makefile.  If you use
1062more than one @samp{-f} or @samp{--file} option, you can specify several
1063makefiles.  All the makefiles are effectively concatenated in the order
1064specified.  The default makefile names @file{GNUmakefile},
1065@file{makefile} and @file{Makefile} are not checked automatically if you
1066specify @samp{-f} or @samp{--file}.@refill
1067@cindex specifying makefile name
1068@cindex makefile name, how to specify
1069@cindex name of makefile, how to specify
1070@cindex file name of makefile, how to specify
1071
1072@node Include, MAKEFILES Variable, Makefile Names, Makefiles
1073@section Including Other Makefiles
1074@cindex including other makefiles
1075@cindex makefile, including
1076
1077@findex include
1078The @code{include} directive tells @code{make} to suspend reading the
1079current makefile and read one or more other makefiles before continuing.
1080The directive is a line in the makefile that looks like this:
1081
1082@example
1083include @var{filenames}@dots{}
1084@end example
1085
1086@noindent
1087@var{filenames} can contain shell file name patterns.  If
1088@var{filenames} is empty, nothing is included and no error is printed.
1089@cindex shell file name pattern (in @code{include})
1090@cindex shell wildcards (in @code{include})
1091@cindex wildcard, in @code{include}
1092
1093Extra spaces are allowed and ignored at the beginning of the line, but
1094a tab is not allowed.  (If the line begins with a tab, it will be
1095considered a command line.)  Whitespace is required between
1096@code{include} and the file names, and between file names; extra
1097whitespace is ignored there and at the end of the directive.  A
1098comment starting with @samp{#} is allowed at the end of the line.  If
1099the file names contain any variable or function references, they are
1100expanded.  @xref{Using Variables, ,How to Use Variables}.
1101
1102For example, if you have three @file{.mk} files, @file{a.mk},
1103@file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1104@code{bish bash}, then the following expression
1105
1106@example
1107include foo *.mk $(bar)
1108@end example
1109
1110is equivalent to
1111
1112@example
1113include foo a.mk b.mk c.mk bish bash
1114@end example
1115
1116When @code{make} processes an @code{include} directive, it suspends
1117reading of the containing makefile and reads from each listed file in
1118turn.  When that is finished, @code{make} resumes reading the
1119makefile in which the directive appears.
1120
1121One occasion for using @code{include} directives is when several programs,
1122handled by individual makefiles in various directories, need to use a
1123common set of variable definitions
1124(@pxref{Setting, ,Setting Variables}) or pattern rules
1125(@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1126
1127Another such occasion is when you want to generate prerequisites from
1128source files automatically; the prerequisites can be put in a file that
1129is included by the main makefile.  This practice is generally cleaner
1130than that of somehow appending the prerequisites to the end of the main
1131makefile as has been traditionally done with other versions of
1132@code{make}.  @xref{Automatic Prerequisites}.
1133@cindex prerequisites, automatic generation
1134@cindex automatic generation of prerequisites
1135@cindex generating prerequisites automatically
1136
1137@cindex @code{-I}
1138@cindex @code{--include-dir}
1139@cindex included makefiles, default directories
1140@cindex default directories for included makefiles
1141@findex /usr/gnu/include
1142@findex /usr/local/include
1143@findex /usr/include
1144If the specified name does not start with a slash, and the file is not
1145found in the current directory, several other directories are searched.
1146First, any directories you have specified with the @samp{-I} or
1147@samp{--include-dir} option are searched
1148(@pxref{Options Summary, ,Summary of Options}).
1149Then the following directories (if they exist)
1150are searched, in this order:
1151@file{@var{prefix}/include} (normally @file{/usr/local/include}
1152@footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if
1153@var{prefix} has been defined to be the root of the DJGPP tree
1154hierarchy.})
1155@file{/usr/gnu/include},
1156@file{/usr/local/include}, @file{/usr/include}.
1157
1158If an included makefile cannot be found in any of these directories, a
1159warning message is generated, but it is not an immediately fatal error;
1160processing of the makefile containing the @code{include} continues.
1161Once it has finished reading makefiles, @code{make} will try to remake
1162any that are out of date or don't exist.
1163@xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1164Only after it has tried to find a way to remake a makefile and failed,
1165will @code{make} diagnose the missing makefile as a fatal error.
1166
1167If you want @code{make} to simply ignore a makefile which does not exist
1168and cannot be remade, with no error message, use the @w{@code{-include}}
1169directive instead of @code{include}, like this:
1170
1171@example
1172-include @var{filenames}@dots{}
1173@end example
1174
1175This acts like @code{include} in every way except that there is no
1176error (not even a warning) if any of the @var{filenames} do not exist.
1177For compatibility with some other @code{make} implementations,
1178@code{sinclude} is another name for @w{@code{-include}}.
1179
1180@node MAKEFILES Variable, MAKEFILE_LIST Variable, Include, Makefiles
1181@section The Variable @code{MAKEFILES}
1182@cindex makefile, and @code{MAKEFILES} variable
1183@cindex including (@code{MAKEFILES} variable)
1184
1185@vindex MAKEFILES
1186If the environment variable @code{MAKEFILES} is defined, @code{make}
1187considers its value as a list of names (separated by whitespace) of
1188additional makefiles to be read before the others.  This works much like
1189the @code{include} directive: various directories are searched for those
1190files (@pxref{Include, ,Including Other Makefiles}).  In addition, the
1191default goal is never taken from one of these makefiles and it is not an
1192error if the files listed in @code{MAKEFILES} are not found.@refill
1193
1194@cindex recursion, and @code{MAKEFILES} variable
1195The main use of @code{MAKEFILES} is in communication between recursive
1196invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1197@code{make}}).  It usually is not desirable to set the environment
1198variable before a top-level invocation of @code{make}, because it is
1199usually better not to mess with a makefile from outside.  However, if
1200you are running @code{make} without a specific makefile, a makefile in
1201@code{MAKEFILES} can do useful things to help the built-in implicit
1202rules work better, such as defining search paths (@pxref{Directory Search}).
1203
1204Some users are tempted to set @code{MAKEFILES} in the environment
1205automatically on login, and program makefiles to expect this to be done.
1206This is a very bad idea, because such makefiles will fail to work if run by
1207anyone else.  It is much better to write explicit @code{include} directives
1208in the makefiles.  @xref{Include, , Including Other Makefiles}.
1209
1210@node MAKEFILE_LIST Variable, Special Variables, MAKEFILES Variable, Makefiles
1211@comment  node-name,  next,  previous,  up
1212@section The Variable @code{MAKEFILE_LIST}
1213@cindex makefiles, and @code{MAKEFILE_LIST} variable
1214@cindex including (@code{MAKEFILE_LIST} variable)
1215@vindex MAKEFILE_LIST
1216
1217As @code{make} reads various makefiles, including any obtained from the
1218@code{MAKEFILES} variable, the command line, the default files, or
1219from @code{include} directives, their names will be automatically
1220appended to the @code{MAKEFILE_LIST} variable.  They are added right
1221before @code{make} begins to parse them.
1222
1223This means that if the first thing a makefile does is examine the last
1224word in this variable, it will be the name of the current makefile.
1225Once the current makefile has used @code{include}, however, the last
1226word will be the just-included makefile.
1227
1228If a makefile named @code{Makefile} has this content:
1229
1230@example
1231@group
1232name1 := $(lastword $(MAKEFILE_LIST))
1233
1234include inc.mk
1235
1236name2 := $(lastword $(MAKEFILE_LIST))
1237
1238all:
1239        @@echo name1 = $(name1)
1240        @@echo name2 = $(name2)
1241@end group
1242@end example
1243
1244@noindent
1245then you would expect to see this output:
1246
1247@example
1248@group
1249name1 = Makefile
1250name2 = inc.mk
1251@end group
1252@end example
1253
1254@xref{Text Functions}, for more information on the @code{word} and
1255@code{words} functions used above.  @xref{Flavors, The Two Flavors of
1256Variables}, for more information on simply-expanded (@code{:=})
1257variable definitions.
1258
1259@node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles
1260@comment  node-name,  next,  previous,  up
1261@section Other Special Variables
1262@cindex makefiles, and special variables
1263@cindex special variables
1264
1265GNU @code{make} also supports other special variables.  Unless
1266otherwise documented here, these values lose their special properties
1267if they are set by a makefile or on the command line.
1268
1269@table @code
1270
1271@vindex .DEFAULT_GOAL @r{(define default goal)}
1272@item .DEFAULT_GOAL
1273Sets the default goal to be used if no targets were specified on the
1274command line (@pxref{Goals, , Arguments to Specify the Goals}).  The
1275@code{.DEFAULT_GOAL} variable allows you to discover the current
1276default goal, restart the default goal selection algorithm by clearing
1277its value, or to explicitly set the default goal.  The following
1278example illustrates these cases:
1279
1280@example
1281@group
1282# Query the default goal.
1283ifeq ($(.DEFAULT_GOAL),)
1284  $(warning no default goal is set)
1285endif
1286
1287.PHONY: foo
1288foo: ; @@echo $@@
1289
1290$(warning default goal is $(.DEFAULT_GOAL))
1291
1292# Reset the default goal.
1293.DEFAULT_GOAL :=
1294
1295.PHONY: bar
1296bar: ; @@echo $@@
1297
1298$(warning default goal is $(.DEFAULT_GOAL))
1299
1300# Set our own.
1301.DEFAULT_GOAL := foo
1302@end group
1303@end example
1304
1305This makefile prints:
1306
1307@example
1308@group
1309no default goal is set
1310default goal is foo
1311default goal is bar
1312foo
1313@end group
1314@end example
1315
1316Note that assigning more than one target name to @code{.DEFAULT_GOAL} is
1317illegal and will result in an error.
1318
1319@vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)}
1320@item MAKE_RESTARTS
1321This variable is set only if this instance of @code{make} has
1322restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it
1323will contain the number of times this instance has restarted.  Note
1324this is not the same as recursion (counted by the @code{MAKELEVEL}
1325variable).  You should not set, modify, or export this variable.
1326
1327@vindex .VARIABLES @r{(list of variables)}
1328@item .VARIABLES
1329Expands to a list of the @emph{names} of all global variables defined
1330so far.  This includes variables which have empty values, as well as
1331built-in variables (@pxref{Implicit Variables, , Variables Used by
1332Implicit Rules}), but does not include any variables which are only
1333defined in a target-specific context.  Note that any value you assign
1334to this variable will be ignored; it will always return its special
1335value.
1336
1337@c @vindex .TARGETS @r{(list of targets)}
1338@c @item .TARGETS
1339@c The second special variable is @code{.TARGETS}.  When expanded, the
1340@c value consists of a list of all targets defined in all makefiles read
1341@c up until that point.  Note it's not enough for a file to be simply
1342@c mentioned in the makefile to be listed in this variable, even if it
1343@c would match an implicit rule and become an ``implicit target''.  The
1344@c file must appear as a target, on the left-hand side of a ``:'', to be
1345@c considered a target for the purposes of this variable.
1346
1347@vindex .FEATURES @r{(list of supported features)}
1348@item .FEATURES
1349Expands to a list of special features supported by this version of
1350@code{make}.  Possible values include:
1351
1352@table @samp
1353
1354@item archives
1355Supports @code{ar} (archive) files using special filename syntax.
1356@xref{Archives, ,Using @code{make} to Update Archive Files}.
1357
1358@item check-symlink
1359Supports the @code{-L} (@code{--check-symlink-times}) flag.
1360@xref{Options Summary, ,Summary of Options}.
1361
1362@item else-if
1363Supports ``else if'' non-nested conditionals.  @xref{Conditional
1364Syntax, ,Syntax of Conditionals}.
1365
1366@item jobserver
1367Supports ``job server'' enhanced parallel builds.  @xref{Parallel,
1368,Parallel Execution}.
1369
1370@item second-expansion
1371Supports secondary expansion of prerequisite lists.
1372
1373@item order-only
1374Supports order-only prerequisites.  @xref{Prerequisite Types, ,Types
1375of Prerequisites}.
1376
1377@item target-specific
1378Supports target-specific and pattern-specific variable assignments.
1379@xref{Target-specific, ,Target-specific Variable Values}.
1380
1381@end table
1382
1383@vindex .INCLUDE_DIRS @r{(list of include directories)}
1384@item .INCLUDE_DIRS
1385Expands to a list of directories that @code{make} searches for
1386included makefiles (@pxref{Include, , Including Other Makefiles}).
1387
1388@end table
1389
1390@node Remaking Makefiles, Overriding Makefiles, Special Variables, Makefiles
1391@section How Makefiles Are Remade
1392
1393@cindex updating makefiles
1394@cindex remaking makefiles
1395@cindex makefile, remaking of
1396Sometimes makefiles can be remade from other files, such as RCS or SCCS
1397files.  If a makefile can be remade from other files, you probably want
1398@code{make} to get an up-to-date version of the makefile to read in.
1399
1400To this end, after reading in all makefiles, @code{make} will consider
1401each as a goal target and attempt to update it.  If a makefile has a
1402rule which says how to update it (found either in that very makefile or
1403in another one) or if an implicit rule applies to it (@pxref{Implicit
1404Rules, ,Using Implicit Rules}), it will be updated if necessary.  After
1405all makefiles have been checked, if any have actually been changed,
1406@code{make} starts with a clean slate and reads all the makefiles over
1407again.  (It will also attempt to update each of them over again, but
1408normally this will not change them again, since they are already up to
1409date.)@refill
1410
1411If you know that one or more of your makefiles cannot be remade and you
1412want to keep @code{make} from performing an implicit rule search on
1413them, perhaps for efficiency reasons, you can use any normal method of
1414preventing implicit rule lookup to do so.  For example, you can write an
1415explicit rule with the makefile as the target, and an empty command
1416string (@pxref{Empty Commands, ,Using Empty Commands}).
1417
1418If the makefiles specify a double-colon rule to remake a file with
1419commands but no prerequisites, that file will always be remade
1420(@pxref{Double-Colon}).  In the case of makefiles, a makefile that has a
1421double-colon rule with commands but no prerequisites will be remade every
1422time @code{make} is run, and then again after @code{make} starts over
1423and reads the makefiles in again.  This would cause an infinite loop:
1424@code{make} would constantly remake the makefile, and never do anything
1425else.  So, to avoid this, @code{make} will @strong{not} attempt to
1426remake makefiles which are specified as targets of a double-colon rule
1427with commands but no prerequisites.@refill
1428
1429If you do not specify any makefiles to be read with @samp{-f} or
1430@samp{--file} options, @code{make} will try the default makefile names;
1431@pxref{Makefile Names, ,What Name to Give Your Makefile}.  Unlike
1432makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1433@code{make} is not certain that these makefiles should exist.  However,
1434if a default makefile does not exist but can be created by running
1435@code{make} rules, you probably want the rules to be run so that the
1436makefile can be used.
1437
1438Therefore, if none of the default makefiles exists, @code{make} will try
1439to make each of them in the same order in which they are searched for
1440(@pxref{Makefile Names, ,What Name to Give Your Makefile})
1441until it succeeds in making one, or it runs out of names to try.  Note
1442that it is not an error if @code{make} cannot find or make any makefile;
1443a makefile is not always necessary.@refill
1444
1445When you use the @samp{-t} or @samp{--touch} option
1446(@pxref{Instead of Execution, ,Instead of Executing the Commands}),
1447you would not want to use an out-of-date makefile to decide which
1448targets to touch.  So the @samp{-t} option has no effect on updating
1449makefiles; they are really updated even if @samp{-t} is specified.
1450Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1451@samp{--just-print}) do not prevent updating of makefiles, because an
1452out-of-date makefile would result in the wrong output for other targets.
1453Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1454and then print the commands to update @file{foo} and its prerequisites
1455without running them.  The commands printed for @file{foo} will be those
1456specified in the updated contents of @file{mfile}.
1457
1458However, on occasion you might actually wish to prevent updating of even
1459the makefiles.  You can do this by specifying the makefiles as goals in
1460the command line as well as specifying them as makefiles.  When the
1461makefile name is specified explicitly as a goal, the options @samp{-t}
1462and so on do apply to them.
1463
1464Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1465@file{mfile}, print the commands needed to update it without actually
1466running them, and then print the commands needed to update @file{foo}
1467without running them.  The commands for @file{foo} will be those
1468specified by the existing contents of @file{mfile}.
1469
1470@node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles
1471@section Overriding Part of Another Makefile
1472
1473@cindex overriding makefiles
1474@cindex makefile, overriding
1475Sometimes it is useful to have a makefile that is mostly just like
1476another makefile.  You can often use the @samp{include} directive to
1477include one in the other, and add more targets or variable definitions.
1478However, if the two makefiles give different commands for the same
1479target, @code{make} will not let you just do this.  But there is another way.
1480
1481@cindex match-anything rule, used to override
1482In the containing makefile (the one that wants to include the other),
1483you can use a match-anything pattern rule to say that to remake any
1484target that cannot be made from the information in the containing
1485makefile, @code{make} should look in another makefile.
1486@xref{Pattern Rules}, for more information on pattern rules.
1487
1488For example, if you have a makefile called @file{Makefile} that says how
1489to make the target @samp{foo} (and other targets), you can write a
1490makefile called @file{GNUmakefile} that contains:
1491
1492@example
1493foo:
1494        frobnicate > foo
1495
1496%: force
1497        @@$(MAKE) -f Makefile $@@
1498force: ;
1499@end example
1500
1501If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1502read it, and see that to make @file{foo}, it needs to run the command
1503@samp{frobnicate > foo}.  If you say @samp{make bar}, @code{make} will
1504find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1505commands from the pattern rule: @samp{make -f Makefile bar}.  If
1506@file{Makefile} provides a rule for updating @file{bar}, @code{make}
1507will apply the rule.  And likewise for any other target that
1508@file{GNUmakefile} does not say how to make.
1509
1510The way this works is that the pattern rule has a pattern of just
1511@samp{%}, so it matches any target whatever.  The rule specifies a
1512prerequisite @file{force}, to guarantee that the commands will be run even
1513if the target file already exists.  We give @file{force} target empty
1514commands to prevent @code{make} from searching for an implicit rule to
1515build it---otherwise it would apply the same match-anything rule to
1516@file{force} itself and create a prerequisite loop!
1517
1518@node Reading Makefiles,  Secondary Expansion, Overriding Makefiles, Makefiles
1519@section How @code{make} Reads a Makefile
1520@cindex reading makefiles
1521@cindex makefile, parsing
1522
1523GNU @code{make} does its work in two distinct phases.  During the first
1524phase it reads all the makefiles, included makefiles, etc. and
1525internalizes all the variables and their values, implicit and explicit
1526rules, and constructs a dependency graph of all the targets and their
1527prerequisites.  During the second phase, @code{make} uses these internal
1528structures to determine what targets will need to be rebuilt and to
1529invoke the rules necessary to do so.
1530
1531It's important to understand this two-phase approach because it has a
1532direct impact on how variable and function expansion happens; this is
1533often a source of some confusion when writing makefiles.  Here we will
1534present a summary of the phases in which expansion happens for different
1535constructs within the makefile.  We say that expansion is
1536@dfn{immediate} if it happens during the first phase: in this case
1537@code{make} will expand any variables or functions in that section of a
1538construct as the makefile is parsed.  We say that expansion is
1539@dfn{deferred} if expansion is not performed immediately.  Expansion of
1540deferred construct is not performed until either the construct appears
1541later in an immediate context, or until the second phase.
1542
1543You may not be familiar with some of these constructs yet.  You can
1544reference this section as you become familiar with them, in later
1545chapters.
1546
1547@subheading Variable Assignment
1548@cindex +=, expansion
1549@cindex =, expansion
1550@cindex ?=, expansion
1551@cindex +=, expansion
1552@cindex define, expansion
1553
1554Variable definitions are parsed as follows:
1555
1556@example
1557@var{immediate} = @var{deferred}
1558@var{immediate} ?= @var{deferred}
1559@var{immediate} := @var{immediate}
1560@var{immediate} += @var{deferred} or @var{immediate}
1561
1562define @var{immediate}
1563  @var{deferred}
1564endef
1565@end example
1566
1567For the append operator, @samp{+=}, the right-hand side is considered
1568immediate if the variable was previously set as a simple variable
1569(@samp{:=}), and deferred otherwise.
1570
1571@subheading Conditional Statements
1572@cindex ifdef, expansion
1573@cindex ifeq, expansion
1574@cindex ifndef, expansion
1575@cindex ifneq, expansion
1576
1577All instances of conditional syntax are parsed immediately, in their
1578entirety; this includes the @code{ifdef}, @code{ifeq}, @code{ifndef},
1579and @code{ifneq} forms.  Of course this means that automatic variables
1580cannot be used in conditional statements, as automatic variables are
1581not set until the command script for that rule is invoked.  If you
1582need to use automatic variables in a conditional you @emph{must} use
1583shell conditional syntax, in your command script proper, for these
1584tests, not @code{make} conditionals.
1585
1586@subheading Rule Definition
1587@cindex target, expansion
1588@cindex prerequisite, expansion
1589@cindex implicit rule, expansion
1590@cindex pattern rule, expansion
1591@cindex explicit rule, expansion
1592
1593A rule is always expanded the same way, regardless of the form:
1594
1595@example
1596@var{immediate} : @var{immediate} ; @var{deferred}
1597	@var{deferred}
1598@end example
1599
1600That is, the target and prerequisite sections are expanded immediately,
1601and the commands used to construct the target are always deferred.  This
1602general rule is true for explicit rules, pattern rules, suffix rules,
1603static pattern rules, and simple prerequisite definitions.
1604
1605@node Secondary Expansion, , Reading Makefiles, Makefiles
1606@section Secondary Expansion
1607@cindex secondary expansion
1608@cindex expansion, secondary
1609
1610@findex .SECONDEXPANSION
1611In the previous section we learned that GNU @code{make} works in two
1612distinct phases: a read-in phase and a target-update phase
1613(@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}).  GNU
1614make also has the ability to enable a @emph{second expansion} of the
1615prerequisites (only) for some or all targets defined in the makefile.
1616In order for this second expansion to occur, the special target
1617@code{.SECONDEXPANSION} must be defined before the first prerequisite
1618list that makes use of this feature.
1619
1620If that special target is defined then in between the two phases
1621mentioned above, right at the end of the read-in phase, all the
1622prerequisites of the targets defined after the special target are
1623expanded a @emph{second time}.  In most circumstances this secondary
1624expansion will have no effect, since all variable and function
1625references will have been expanded during the initial parsing of the
1626makefiles.  In order to take advantage of the secondary expansion
1627phase of the parser, then, it's necessary to @emph{escape} the
1628variable or function reference in the makefile.  In this case the
1629first expansion merely un-escapes the reference but doesn't expand it,
1630and expansion is left to the secondary expansion phase.  For example,
1631consider this makefile:
1632
1633@example
1634.SECONDEXPANSION:
1635ONEVAR = onefile
1636TWOVAR = twofile
1637myfile: $(ONEVAR) $$(TWOVAR)
1638@end example
1639
1640After the first expansion phase the prerequisites list of the
1641@file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the
1642first (unescaped) variable reference to @var{ONEVAR} is expanded,
1643while the second (escaped) variable reference is simply unescaped,
1644without being recognized as a variable reference.  Now during the
1645secondary expansion the first word is expanded again but since it
1646contains no variable or function references it remains the static
1647value @file{onefile}, while the second word is now a normal reference
1648to the variable @var{TWOVAR}, which is expanded to the value
1649@file{twofile}.  The final result is that there are two prerequisites,
1650@file{onefile} and @file{twofile}.
1651
1652Obviously, this is not a very interesting case since the same result
1653could more easily have been achieved simply by having both variables
1654appear, unescaped, in the prerequisites list.  One difference becomes
1655apparent if the variables are reset; consider this example:
1656
1657@example
1658.SECONDEXPANSION:
1659AVAR = top
1660onefile: $(AVAR)
1661twofile: $$(AVAR)
1662AVAR = bottom
1663@end example
1664
1665Here the prerequisite of @file{onefile} will be expanded immediately,
1666and resolve to the value @file{top}, while the prerequisite of
1667@file{twofile} will not be full expanded until the secondary expansion
1668and yield a value of @file{bottom}.
1669
1670This is marginally more exciting, but the true power of this feature
1671only becomes apparent when you discover that secondary expansions
1672always take place within the scope of the automatic variables for that
1673target.  This means that you can use variables such as @code{$@@},
1674@code{$*}, etc. during the second expansion and they will have their
1675expected values, just as in the command script.  All you have to do is
1676defer the expansion by escaping the @code{$}.  Also, secondary
1677expansion occurs for both explicit and implicit (pattern) rules.
1678Knowing this, the possible uses for this feature increase
1679dramatically.  For example:
1680
1681@example
1682.SECONDEXPANSION:
1683main_OBJS := main.o try.o test.o
1684lib_OBJS := lib.o api.o
1685
1686main lib: $$($$@@_OBJS)
1687@end example
1688
1689Here, after the initial expansion the prerequisites of both the
1690@file{main} and @file{lib} targets will be @code{$($@@_OBJS)}.  During
1691the secondary expansion, the @code{$@@} variable is set to the name of
1692the target and so the expansion for the @file{main} target will yield
1693@code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the
1694secondary expansion for the @file{lib} target will yield
1695@code{$(lib_OBJS)}, or @code{lib.o api.o}.
1696
1697You can also mix functions here, as long as they are properly escaped:
1698
1699@example
1700main_SRCS := main.c try.c test.c
1701lib_SRCS := lib.c api.c
1702
1703.SECONDEXPANSION:
1704main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS))
1705@end example
1706
1707This version allows users to specify source files rather than object
1708files, but gives the same resulting prerequisites list as the previous
1709example.
1710
1711Evaluation of automatic variables during the secondary expansion
1712phase, especially of the target name variable @code{$$@@}, behaves
1713similarly to evaluation within command scripts.  However, there are
1714some subtle differences and ``corner cases'' which come into play for
1715the different types of rule definitions that @code{make} understands.
1716The subtleties of using the different automatic variables are
1717described below.
1718
1719@subheading Secondary Expansion of Explicit Rules
1720@cindex secondary expansion and explicit rules
1721@cindex explicit rules, secondary expansion of
1722
1723During the secondary expansion of explicit rules, @code{$$@@} and
1724@code{$$%} evaluate, respectively, to the file name of the target and,
1725when the target is an archive member, the target member name.  The
1726@code{$$<} variable evaluates to the first prerequisite in the first
1727rule for this target.  @code{$$^} and @code{$$+} evaluate to the list
1728of all prerequisites of rules @emph{that have already appeared} for
1729the same target (@code{$$+} with repetitions and @code{$$^}
1730without).  The following example will help illustrate these behaviors:
1731
1732@example
1733.SECONDEXPANSION:
1734
1735foo: foo.1 bar.1 $$< $$^ $$+    # line #1
1736
1737foo: foo.2 bar.2 $$< $$^ $$+    # line #2
1738
1739foo: foo.3 bar.3 $$< $$^ $$+    # line #3
1740@end example
1741
1742In the first prerequisite list, all three variables (@code{$$<},
1743@code{$$^}, and @code{$$+}) expand to the empty string.  In the
1744second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and
1745@code{foo.1 bar.1} respectively.  In the third they will have values
1746@code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1
1747foo.2 bar.2} respectively.
1748
1749Rules undergo secondary expansion in makefile order, except that
1750the rule with the command script is always evaluated last.
1751
1752The variables @code{$$?} and @code{$$*} are not available and expand
1753to the empty string.
1754
1755@subheading Secondary Expansion of Static Pattern Rules
1756@cindex secondary expansion and static pattern rules
1757@cindex static pattern rules, secondary expansion of
1758
1759Rules for secondary expansion of static pattern rules are identical to
1760those for explicit rules, above, with one exception: for static
1761pattern rules the @code{$$*} variable is set to the pattern stem.  As
1762with explicit rules, @code{$$?} is not available and expands to the
1763empty string.
1764
1765@subheading Secondary Expansion of Implicit Rules
1766@cindex secondary expansion and implicit rules
1767@cindex implicit rules, secondary expansion of
1768
1769As @code{make} searches for an implicit rule, it substitutes the stem
1770and then performs secondary expansion for every rule with a matching
1771target pattern.  The value of the automatic variables is derived in
1772the same fashion as for static pattern rules.  As an example:
1773
1774@example
1775.SECONDEXPANSION:
1776
1777foo: bar
1778
1779foo foz: fo%: bo%
1780
1781%oo: $$< $$^ $$+ $$*
1782@end example
1783
1784When the implicit rule is tried for target @file{foo}, @code{$$<}
1785expands to @file{bar}, @code{$$^} expands to @file{bar boo},
1786@code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to
1787@file{f}.
1788
1789Note that the directory prefix (D), as described in @ref{Implicit Rule
1790Search, ,Implicit Rule Search Algorithm}, is appended (after
1791expansion) to all the patterns in the prerequisites list.  As an
1792example:
1793
1794@example
1795.SECONDEXPANSION:
1796
1797/tmp/foo.o:
1798
1799%.o: $$(addsuffix /%.c,foo bar) foo.h
1800@end example
1801
1802The prerequisite list after the secondary expansion and directory
1803prefix reconstruction will be @file{/tmp/foo/foo.c /tmp/var/bar/foo.c
1804foo.h}.  If you are not interested in this reconstruction, you can use
1805@code{$$*} instead of @code{%} in the prerequisites list.
1806
1807@node Rules, Commands, Makefiles, Top
1808@chapter Writing Rules
1809@cindex writing rules
1810@cindex rule, how to write
1811@cindex target
1812@cindex prerequisite
1813
1814A @dfn{rule} appears in the makefile and says when and how to remake
1815certain files, called the rule's @dfn{targets} (most often only one per rule).
1816It lists the other files that are the @dfn{prerequisites} of the target, and
1817@dfn{commands} to use to create or update the target.
1818
1819@cindex default goal
1820@cindex goal, default
1821The order of rules is not significant, except for determining the
1822@dfn{default goal}: the target for @code{make} to consider, if you do
1823not otherwise specify one.  The default goal is the target of the first
1824rule in the first makefile.  If the first rule has multiple targets,
1825only the first target is taken as the default.  There are two
1826exceptions: a target starting with a period is not a default unless it
1827contains one or more slashes, @samp{/}, as well; and, a target that
1828defines a pattern rule has no effect on the default goal.
1829(@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1830
1831Therefore, we usually write the makefile so that the first rule is the
1832one for compiling the entire program or all the programs described by
1833the makefile (often with a target called @samp{all}).
1834@xref{Goals, ,Arguments to Specify the Goals}.
1835
1836@menu
1837* Rule Example::                An example explained.
1838* Rule Syntax::                 General syntax explained.
1839* Prerequisite Types::          There are two types of prerequisites.
1840* Wildcards::                   Using wildcard characters such as `*'.
1841* Directory Search::            Searching other directories for source files.
1842* Phony Targets::               Using a target that is not a real file's name.
1843* Force Targets::               You can use a target without commands
1844                                  or prerequisites to mark other targets
1845                                  as phony.
1846* Empty Targets::               When only the date matters and the
1847                                  files are empty.
1848* Special Targets::             Targets with special built-in meanings.
1849* Multiple Targets::            When to make use of several targets in a rule.
1850* Multiple Rules::              How to use several rules with the same target.
1851* Static Pattern::              Static pattern rules apply to multiple targets
1852                                  and can vary the prerequisites according to
1853                                  the target name.
1854* Double-Colon::                How to use a special kind of rule to allow
1855                                  several independent rules for one target.
1856* Automatic Prerequisites::     How to automatically generate rules giving
1857                                  prerequisites from source files themselves.
1858@end menu
1859
1860@ifnottex
1861@node Rule Example, Rule Syntax, Rules, Rules
1862@section Rule Example
1863
1864Here is an example of a rule:
1865
1866@example
1867foo.o : foo.c defs.h       # module for twiddling the frobs
1868        cc -c -g foo.c
1869@end example
1870
1871Its target is @file{foo.o} and its prerequisites are @file{foo.c} and
1872@file{defs.h}.  It has one command, which is @samp{cc -c -g foo.c}.
1873The command line starts with a tab to identify it as a command.
1874
1875This rule says two things:
1876
1877@itemize @bullet
1878@item
1879How to decide whether @file{foo.o} is out of date: it is out of date
1880if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1881more recent than it.
1882
1883@item
1884How to update the file @file{foo.o}: by running @code{cc} as stated.
1885The command does not explicitly mention @file{defs.h}, but we presume
1886that @file{foo.c} includes it, and that that is why @file{defs.h} was
1887added to the prerequisites.
1888@end itemize
1889@end ifnottex
1890
1891@node Rule Syntax, Prerequisite Types, Rule Example, Rules
1892@section Rule Syntax
1893
1894@cindex rule syntax
1895@cindex syntax of rules
1896In general, a rule looks like this:
1897
1898@example
1899@var{targets} : @var{prerequisites}
1900        @var{command}
1901        @dots{}
1902@end example
1903
1904@noindent
1905or like this:
1906
1907@example
1908@var{targets} : @var{prerequisites} ; @var{command}
1909        @var{command}
1910        @dots{}
1911@end example
1912
1913@cindex targets
1914@cindex rule targets
1915The @var{targets} are file names, separated by spaces.  Wildcard
1916characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1917in File Names}) and a name of the form @file{@var{a}(@var{m})}
1918represents member @var{m} in archive file @var{a}
1919(@pxref{Archive Members, ,Archive Members as Targets}).
1920Usually there is only one
1921target per rule, but occasionally there is a reason to have more
1922(@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1923
1924@cindex commands
1925@cindex tab character (in commands)
1926The @var{command} lines start with a tab character.  The first command may
1927appear on the line after the prerequisites, with a tab character, or may
1928appear on the same line, with a semicolon.  Either way, the effect is the
1929same.  There are other differences in the syntax of command lines.
1930@xref{Commands, ,Writing the Commands in Rules}.
1931
1932@cindex dollar sign (@code{$}), in rules
1933@cindex @code{$}, in rules
1934@cindex rules, and @code{$}
1935Because dollar signs are used to start @code{make} variable
1936references, if you really want a dollar sign in a target or
1937prerequisite you must write two of them, @samp{$$} (@pxref{Using
1938Variables, ,How to Use Variables}).  If you have enabled secondary
1939expansion (@pxref{Secondary Expansion}) and you want a literal dollar
1940sign in the prerequisites lise, you must actually write @emph{four}
1941dollar signs (@samp{$$$$}).
1942
1943You may split a long line by inserting a backslash followed by a
1944newline, but this is not required, as @code{make} places no limit on
1945the length of a line in a makefile.
1946
1947A rule tells @code{make} two things: when the targets are out of date,
1948and how to update them when necessary.
1949
1950@cindex prerequisites
1951@cindex rule prerequisites
1952The criterion for being out of date is specified in terms of the
1953@var{prerequisites}, which consist of file names separated by spaces.
1954(Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1955A target is out of date if it does not exist or if it is older than any
1956of the prerequisites (by comparison of last-modification times).  The
1957idea is that the contents of the target file are computed based on
1958information in the prerequisites, so if any of the prerequisites changes,
1959the contents of the existing target file are no longer necessarily
1960valid.
1961
1962How to update is specified by @var{commands}.  These are lines to be
1963executed by the shell (normally @samp{sh}), but with some extra features
1964(@pxref{Commands, ,Writing the Commands in Rules}).
1965
1966@node Prerequisite Types, Wildcards, Rule Syntax, Rules
1967@comment  node-name,  next,  previous,  up
1968@section Types of Prerequisites
1969@cindex prerequisite types
1970@cindex types of prerequisites
1971
1972@cindex prerequisites, normal
1973@cindex normal prerequisites
1974@cindex prerequisites, order-only
1975@cindex order-only prerequisites
1976There are actually two different types of prerequisites understood by
1977GNU @code{make}: normal prerequisites such as described in the
1978previous section, and @dfn{order-only} prerequisites.  A normal
1979prerequisite makes two statements: first, it imposes an order of
1980execution of build commands: any commands necessary to build any of a
1981target's prerequisites will be fully executed before any commands
1982necessary to build the target.  Second, it imposes a dependency
1983relationship: if any prerequisite is newer than the target, then the
1984target is considered out-of-date and must be rebuilt.
1985
1986Normally, this is exactly what you want: if a target's prerequisite is
1987updated, then the target should also be updated.
1988
1989Occasionally, however, you have a situation where you want to impose a
1990specific ordering on the rules to be invoked @emph{without} forcing
1991the target to be updated if one of those rules is executed.  In that
1992case, you want to define @dfn{order-only} prerequisites.  Order-only
1993prerequisites can be specified by placing a pipe symbol (@code{|})
1994in the prerequisites list: any prerequisites to the left of the pipe
1995symbol are normal; any prerequisites to the right are order-only:
1996
1997@example
1998@var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites}
1999@end example
2000
2001The normal prerequisites section may of course be empty.  Also, you
2002may still declare multiple lines of prerequisites for the same target:
2003they are appended appropriately.  Note that if you declare the same
2004file to be both a normal and an order-only prerequisite, the normal
2005prerequisite takes precedence (since they are a strict superset of the
2006behavior of an order-only prerequisite).
2007
2008@node Wildcards, Directory Search, Prerequisite Types, Rules
2009@section Using Wildcard Characters in File Names
2010@cindex wildcard
2011@cindex file name with wildcards
2012@cindex globbing (wildcards)
2013
2014@cindex @code{*} (wildcard character)
2015@cindex @code{?} (wildcard character)
2016@cindex @code{[@dots{}]} (wildcard characters)
2017A single file name can specify many files using @dfn{wildcard characters}.
2018The wildcard characters in @code{make} are @samp{*}, @samp{?} and
2019@samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
2020specifies a list of all the files (in the working directory) whose names
2021end in @samp{.c}.@refill
2022
2023@cindex @code{~} (tilde)
2024@cindex tilde (@code{~})
2025@cindex home directory
2026The character @samp{~} at the beginning of a file name also has special
2027significance.  If alone, or followed by a slash, it represents your home
2028directory.  For example @file{~/bin} expands to @file{/home/you/bin}.
2029If the @samp{~} is followed by a word, the string represents the home
2030directory of the user named by that word.  For example @file{~john/bin}
2031expands to @file{/home/john/bin}.  On systems which don't have a home
2032directory for each user (such as MS-DOS or MS-Windows), this
2033functionality can be simulated by setting the environment variable
2034@var{HOME}.@refill
2035
2036Wildcard expansion is performed by @code{make} automatically in
2037targets and in prerequisites.  In commands the shell is responsible
2038for wildcard expansion.  In other contexts, wildcard expansion happens
2039only if you request it explicitly with the @code{wildcard} function.
2040
2041The special significance of a wildcard character can be turned off by
2042preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
2043specific file whose name consists of @samp{foo}, an asterisk, and
2044@samp{bar}.@refill
2045
2046@menu
2047* Wildcard Examples::           Several examples
2048* Wildcard Pitfall::            Problems to avoid.
2049* Wildcard Function::           How to cause wildcard expansion where
2050                                  it does not normally take place.
2051@end menu
2052
2053@node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards
2054@subsection Wildcard Examples
2055
2056Wildcards can be used in the commands of a rule, where they are expanded
2057by the shell.  For example, here is a rule to delete all the object files:
2058
2059@example
2060@group
2061clean:
2062        rm -f *.o
2063@end group
2064@end example
2065@cindex @code{rm} (shell command)
2066
2067Wildcards are also useful in the prerequisites of a rule.  With the
2068following rule in the makefile, @samp{make print} will print all the
2069@samp{.c} files that have changed since the last time you printed them:
2070
2071@example
2072print: *.c
2073        lpr -p $?
2074        touch print
2075@end example
2076
2077@cindex @code{print} target
2078@cindex @code{lpr} (shell command)
2079@cindex @code{touch} (shell command)
2080@noindent
2081This rule uses @file{print} as an empty target file; see @ref{Empty
2082Targets, ,Empty Target Files to Record Events}.  (The automatic variable
2083@samp{$?} is used to print only those files that have changed; see
2084@ref{Automatic Variables}.)@refill
2085
2086Wildcard expansion does not happen when you define a variable.  Thus, if
2087you write this:
2088
2089@example
2090objects = *.o
2091@end example
2092
2093@noindent
2094then the value of the variable @code{objects} is the actual string
2095@samp{*.o}.  However, if you use the value of @code{objects} in a target,
2096prerequisite or command, wildcard expansion will take place at that time.
2097To set @code{objects} to the expansion, instead use:
2098
2099@example
2100objects := $(wildcard *.o)
2101@end example
2102
2103@noindent
2104@xref{Wildcard Function}.
2105
2106@node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
2107@subsection Pitfalls of Using Wildcards
2108@cindex wildcard pitfalls
2109@cindex pitfalls of wildcards
2110@cindex mistakes with wildcards
2111@cindex errors with wildcards
2112@cindex problems with wildcards
2113
2114Now here is an example of a naive way of using wildcard expansion, that
2115does not do what you would intend.  Suppose you would like to say that the
2116executable file @file{foo} is made from all the object files in the
2117directory, and you write this:
2118
2119@example
2120objects = *.o
2121
2122foo : $(objects)
2123        cc -o foo $(CFLAGS) $(objects)
2124@end example
2125
2126@noindent
2127The value of @code{objects} is the actual string @samp{*.o}.  Wildcard
2128expansion happens in the rule for @file{foo}, so that each @emph{existing}
2129@samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if
2130necessary.
2131
2132But what if you delete all the @samp{.o} files?  When a wildcard matches
2133no files, it is left as it is, so then @file{foo} will depend on the
2134oddly-named file @file{*.o}.  Since no such file is likely to exist,
2135@code{make} will give you an error saying it cannot figure out how to
2136make @file{*.o}.  This is not what you want!
2137
2138Actually it is possible to obtain the desired result with wildcard
2139expansion, but you need more sophisticated techniques, including the
2140@code{wildcard} function and string substitution.
2141@ifnottex
2142@xref{Wildcard Function, ,The Function @code{wildcard}}.
2143@end ifnottex
2144@iftex
2145These are described in the following section.
2146@end iftex
2147
2148@cindex wildcards and MS-DOS/MS-Windows backslashes
2149@cindex backslashes in pathnames and wildcard expansion
2150
2151Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to
2152separate directories in pathnames, like so:
2153
2154@example
2155  c:\foo\bar\baz.c
2156@end example
2157
2158This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the
2159@file{c:} part is the so-called drive letter).  When @code{make} runs on
2160these systems, it supports backslashes as well as the Unix-style forward
2161slashes in pathnames.  However, this support does @emph{not} include the
2162wildcard expansion, where backslash is a quote character.  Therefore,
2163you @emph{must} use Unix-style slashes in these cases.
2164
2165
2166@node Wildcard Function,  , Wildcard Pitfall, Wildcards
2167@subsection The Function @code{wildcard}
2168@findex wildcard
2169
2170Wildcard expansion happens automatically in rules.  But wildcard expansion
2171does not normally take place when a variable is set, or inside the
2172arguments of a function.  If you want to do wildcard expansion in such
2173places, you need to use the @code{wildcard} function, like this:
2174
2175@example
2176$(wildcard @var{pattern}@dots{})
2177@end example
2178
2179@noindent
2180This string, used anywhere in a makefile, is replaced by a
2181space-separated list of names of existing files that match one of the
2182given file name patterns.  If no existing file name matches a pattern,
2183then that pattern is omitted from the output of the @code{wildcard}
2184function.  Note that this is different from how unmatched wildcards
2185behave in rules, where they are used verbatim rather than ignored
2186(@pxref{Wildcard Pitfall}).
2187
2188One use of the @code{wildcard} function is to get a list of all the C source
2189files in a directory, like this:
2190
2191@example
2192$(wildcard *.c)
2193@end example
2194
2195We can change the list of C source files into a list of object files by
2196replacing the @samp{.c} suffix with @samp{.o} in the result, like this:
2197
2198@example
2199$(patsubst %.c,%.o,$(wildcard *.c))
2200@end example
2201
2202@noindent
2203(Here we have used another function, @code{patsubst}.
2204@xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
2205
2206Thus, a makefile to compile all C source files in the directory and then
2207link them together could be written as follows:
2208
2209@example
2210objects := $(patsubst %.c,%.o,$(wildcard *.c))
2211
2212foo : $(objects)
2213        cc -o foo $(objects)
2214@end example
2215
2216@noindent
2217(This takes advantage of the implicit rule for compiling C programs, so
2218there is no need to write explicit rules for compiling the files.
2219@xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
2220@samp{:=}, which is a variant of @samp{=}.)
2221
2222@node Directory Search, Phony Targets, Wildcards, Rules
2223@section Searching Directories for Prerequisites
2224@vindex VPATH
2225@findex vpath
2226@cindex vpath
2227@cindex search path for prerequisites (@code{VPATH})
2228@cindex directory search (@code{VPATH})
2229
2230For large systems, it is often desirable to put sources in a separate
2231directory from the binaries.  The @dfn{directory search} features of
2232@code{make} facilitate this by searching several directories
2233automatically to find a prerequisite.  When you redistribute the files
2234among directories, you do not need to change the individual rules,
2235just the search paths.
2236
2237@menu
2238* General Search::              Specifying a search path that applies
2239                                  to every prerequisite.
2240* Selective Search::            Specifying a search path
2241                                  for a specified class of names.
2242* Search Algorithm::            When and how search paths are applied.
2243* Commands/Search::             How to write shell commands that work together
2244                                  with search paths.
2245* Implicit/Search::             How search paths affect implicit rules.
2246* Libraries/Search::            Directory search for link libraries.
2247@end menu
2248
2249@node General Search, Selective Search, Directory Search, Directory Search
2250@subsection @code{VPATH}: Search Path for All Prerequisites
2251@vindex VPATH
2252
2253The value of the @code{make} variable @code{VPATH} specifies a list of
2254directories that @code{make} should search.  Most often, the
2255directories are expected to contain prerequisite files that are not in the
2256current directory; however, @code{make} uses @code{VPATH} as a search
2257list for both prerequisites and targets of rules.
2258
2259Thus, if a file that is listed as a target or prerequisite does not exist
2260in the current directory, @code{make} searches the directories listed in
2261@code{VPATH} for a file with that name.  If a file is found in one of
2262them, that file may become the prerequisite (see below).  Rules may then
2263specify the names of files in the prerequisite list as if they all
2264existed in the current directory.  @xref{Commands/Search, ,Writing Shell
2265Commands with Directory Search}.
2266
2267In the @code{VPATH} variable, directory names are separated by colons or
2268blanks.  The order in which directories are listed is the order followed
2269by @code{make} in its search.  (On MS-DOS and MS-Windows, semi-colons
2270are used as separators of directory names in @code{VPATH}, since the
2271colon can be used in the pathname itself, after the drive letter.)
2272
2273For example,
2274
2275@example
2276VPATH = src:../headers
2277@end example
2278
2279@noindent
2280specifies a path containing two directories, @file{src} and
2281@file{../headers}, which @code{make} searches in that order.
2282
2283With this value of @code{VPATH}, the following rule,
2284
2285@example
2286foo.o : foo.c
2287@end example
2288
2289@noindent
2290is interpreted as if it were written like this:
2291
2292@example
2293foo.o : src/foo.c
2294@end example
2295
2296@noindent
2297assuming the file @file{foo.c} does not exist in the current directory but
2298is found in the directory @file{src}.
2299
2300@node Selective Search, Search Algorithm, General Search, Directory Search
2301@subsection The @code{vpath} Directive
2302@findex vpath
2303
2304Similar to the @code{VPATH} variable, but more selective, is the
2305@code{vpath} directive (note lower case), which allows you to specify a
2306search path for a particular class of file names: those that match a
2307particular pattern.  Thus you can supply certain search directories for
2308one class of file names and other directories (or none) for other file
2309names.
2310
2311There are three forms of the @code{vpath} directive:
2312
2313@table @code
2314@item vpath @var{pattern} @var{directories}
2315Specify the search path @var{directories} for file names that match
2316@var{pattern}.
2317
2318The search path, @var{directories}, is a list of directories to be
2319searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or
2320blanks, just like the search path used in the @code{VPATH} variable.
2321
2322@item vpath @var{pattern}
2323Clear out the search path associated with @var{pattern}.
2324
2325@c Extra blank line makes sure this gets two lines.
2326@item vpath
2327
2328Clear all search paths previously specified with @code{vpath} directives.
2329@end table
2330
2331A @code{vpath} pattern is a string containing a @samp{%} character.  The
2332string must match the file name of a prerequisite that is being searched
2333for, the @samp{%} character matching any sequence of zero or more
2334characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
2335Redefining Pattern Rules}).  For example, @code{%.h} matches files that
2336end in @code{.h}.  (If there is no @samp{%}, the pattern must match the
2337prerequisite exactly, which is not useful very often.)
2338
2339@cindex @code{%}, quoting in @code{vpath}
2340@cindex @code{%}, quoting with @code{\} (backslash)
2341@cindex @code{\} (backslash), to quote @code{%}
2342@cindex backslash (@code{\}), to quote @code{%}
2343@cindex quoting @code{%}, in @code{vpath}
2344@samp{%} characters in a @code{vpath} directive's pattern can be quoted
2345with preceding backslashes (@samp{\}).  Backslashes that would otherwise
2346quote @samp{%} characters can be quoted with more backslashes.
2347Backslashes that quote @samp{%} characters or other backslashes are
2348removed from the pattern before it is compared to file names.  Backslashes
2349that are not in danger of quoting @samp{%} characters go unmolested.@refill
2350
2351When a prerequisite fails to exist in the current directory, if the
2352@var{pattern} in a @code{vpath} directive matches the name of the
2353prerequisite file, then the @var{directories} in that directive are searched
2354just like (and before) the directories in the @code{VPATH} variable.
2355
2356For example,
2357
2358@example
2359vpath %.h ../headers
2360@end example
2361
2362@noindent
2363tells @code{make} to look for any prerequisite whose name ends in @file{.h}
2364in the directory @file{../headers} if the file is not found in the current
2365directory.
2366
2367If several @code{vpath} patterns match the prerequisite file's name, then
2368@code{make} processes each matching @code{vpath} directive one by one,
2369searching all the directories mentioned in each directive.  @code{make}
2370handles multiple @code{vpath} directives in the order in which they
2371appear in the makefile; multiple directives with the same pattern are
2372independent of each other.
2373
2374@need 750
2375Thus,
2376
2377@example
2378@group
2379vpath %.c foo
2380vpath %   blish
2381vpath %.c bar
2382@end group
2383@end example
2384
2385@noindent
2386will look for a file ending in @samp{.c} in @file{foo}, then
2387@file{blish}, then @file{bar}, while
2388
2389@example
2390@group
2391vpath %.c foo:bar
2392vpath %   blish
2393@end group
2394@end example
2395
2396@noindent
2397will look for a file ending in @samp{.c} in @file{foo}, then
2398@file{bar}, then @file{blish}.
2399
2400@node Search Algorithm, Commands/Search, Selective Search, Directory Search
2401@subsection How Directory Searches are Performed
2402@cindex algorithm for directory search
2403@cindex directory search algorithm
2404
2405When a prerequisite is found through directory search, regardless of type
2406(general or selective), the pathname located may not be the one that
2407@code{make} actually provides you in the prerequisite list.  Sometimes
2408the path discovered through directory search is thrown away.
2409
2410The algorithm @code{make} uses to decide whether to keep or abandon a
2411path found via directory search is as follows:
2412
2413@enumerate
2414@item
2415If a target file does not exist at the path specified in the makefile,
2416directory search is performed.
2417
2418@item
2419If the directory search is successful, that path is kept and this file
2420is tentatively stored as the target.
2421
2422@item
2423All prerequisites of this target are examined using this same method.
2424
2425@item
2426After processing the prerequisites, the target may or may not need to be
2427rebuilt:
2428
2429@enumerate a
2430@item
2431If the target does @emph{not} need to be rebuilt, the path to the file
2432found during directory search is used for any prerequisite lists which
2433contain this target.  In short, if @code{make} doesn't need to rebuild
2434the target then you use the path found via directory search.
2435
2436@item
2437If the target @emph{does} need to be rebuilt (is out-of-date), the
2438pathname found during directory search is @emph{thrown away}, and the
2439target is rebuilt using the file name specified in the makefile.  In
2440short, if @code{make} must rebuild, then the target is rebuilt locally,
2441not in the directory found via directory search.
2442@end enumerate
2443@end enumerate
2444
2445This algorithm may seem complex, but in practice it is quite often
2446exactly what you want.
2447
2448@cindex traditional directory search (GPATH)
2449@cindex directory search, traditional (GPATH)
2450Other versions of @code{make} use a simpler algorithm: if the file does
2451not exist, and it is found via directory search, then that pathname is
2452always used whether or not the target needs to be built.  Thus, if the
2453target is rebuilt it is created at the pathname discovered during
2454directory search.
2455
2456@vindex GPATH
2457If, in fact, this is the behavior you want for some or all of your
2458directories, you can use the @code{GPATH} variable to indicate this to
2459@code{make}.
2460
2461@code{GPATH} has the same syntax and format as @code{VPATH} (that is, a
2462space- or colon-delimited list of pathnames).  If an out-of-date target
2463is found by directory search in a directory that also appears in
2464@code{GPATH}, then that pathname is not thrown away.  The target is
2465rebuilt using the expanded path.
2466
2467@node Commands/Search, Implicit/Search, Search Algorithm, Directory Search
2468@subsection Writing Shell Commands with Directory Search
2469@cindex shell command, and directory search
2470@cindex directory search (@code{VPATH}), and shell commands
2471
2472When a prerequisite is found in another directory through directory search,
2473this cannot change the commands of the rule; they will execute as written.
2474Therefore, you must write the commands with care so that they will look for
2475the prerequisite in the directory where @code{make} finds it.
2476
2477This is done with the @dfn{automatic variables} such as @samp{$^}
2478(@pxref{Automatic Variables}).
2479For instance, the value of @samp{$^} is a
2480list of all the prerequisites of the rule, including the names of
2481the directories in which they were found, and the value of
2482@samp{$@@} is the target.  Thus:@refill
2483
2484@example
2485foo.o : foo.c
2486        cc -c $(CFLAGS) $^ -o $@@
2487@end example
2488
2489@noindent
2490(The variable @code{CFLAGS} exists so you can specify flags for C
2491compilation by implicit rules; we use it here for consistency so it will
2492affect all C compilations uniformly;
2493@pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
2494
2495Often the prerequisites include header files as well, which you do not
2496want to mention in the commands.  The automatic variable @samp{$<} is
2497just the first prerequisite:
2498
2499@example
2500VPATH = src:../headers
2501foo.o : foo.c defs.h hack.h
2502        cc -c $(CFLAGS) $< -o $@@
2503@end example
2504
2505@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
2506@subsection Directory Search and Implicit Rules
2507@cindex @code{VPATH}, and implicit rules
2508@cindex directory search (@code{VPATH}), and implicit rules
2509@cindex search path for prerequisites (@code{VPATH}), and implicit rules
2510@cindex implicit rule, and directory search
2511@cindex implicit rule, and @code{VPATH}
2512@cindex rule, implicit, and directory search
2513@cindex rule, implicit, and @code{VPATH}
2514
2515The search through the directories specified in @code{VPATH} or with
2516@code{vpath} also happens during consideration of implicit rules
2517(@pxref{Implicit Rules, ,Using Implicit Rules}).
2518
2519For example, when a file @file{foo.o} has no explicit rule, @code{make}
2520considers implicit rules, such as the built-in rule to compile
2521@file{foo.c} if that file exists.  If such a file is lacking in the
2522current directory, the appropriate directories are searched for it.  If
2523@file{foo.c} exists (or is mentioned in the makefile) in any of the
2524directories, the implicit rule for C compilation is applied.
2525
2526The commands of implicit rules normally use automatic variables as a
2527matter of necessity; consequently they will use the file names found by
2528directory search with no extra effort.
2529
2530@node Libraries/Search,  , Implicit/Search, Directory Search
2531@subsection Directory Search for Link Libraries
2532@cindex link libraries, and directory search
2533@cindex libraries for linking, directory search
2534@cindex directory search (@code{VPATH}), and link libraries
2535@cindex @code{VPATH}, and link libraries
2536@cindex search path for prerequisites (@code{VPATH}), and link libraries
2537@cindex @code{-l} (library search)
2538@cindex link libraries, patterns matching
2539@cindex @code{.LIBPATTERNS}, and link libraries
2540@vindex .LIBPATTERNS
2541
2542Directory search applies in a special way to libraries used with the
2543linker.  This special feature comes into play when you write a prerequisite
2544whose name is of the form @samp{-l@var{name}}.  (You can tell something
2545strange is going on here because the prerequisite is normally the name of a
2546file, and the @emph{file name} of a library generally looks like
2547@file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
2548
2549When a prerequisite's name has the form @samp{-l@var{name}}, @code{make}
2550handles it specially by searching for the file @file{lib@var{name}.so} in
2551the current directory, in directories specified by matching @code{vpath}
2552search paths and the @code{VPATH} search path, and then in the
2553directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
2554(normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of
2555@code{make} behave as if @var{prefix} is defined to be the root of the
2556DJGPP installation tree).
2557
2558If that file is not found, then the file @file{lib@var{name}.a} is
2559searched for, in the same directories as above.
2560
2561For example, if there is a @file{/usr/lib/libcurses.a} library on your
2562system (and no @file{/usr/lib/libcurses.so} file), then
2563
2564@example
2565@group
2566foo : foo.c -lcurses
2567        cc $^ -o $@@
2568@end group
2569@end example
2570
2571@noindent
2572would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
2573be executed when @file{foo} is older than @file{foo.c} or than
2574@file{/usr/lib/libcurses.a}.@refill
2575
2576Although the default set of files to be searched for is
2577@file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable
2578via the @code{.LIBPATTERNS} variable.  Each word in the value of this
2579variable is a pattern string.  When a prerequisite like
2580@samp{-l@var{name}} is seen, @code{make} will replace the percent in
2581each pattern in the list with @var{name} and perform the above directory
2582searches using that library filename.  If no library is found, the next
2583word in the list will be used.
2584
2585The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a},
2586which provides the default behavior described above.
2587
2588You can turn off link library expansion completely by setting this
2589variable to an empty value.
2590
2591@node Phony Targets, Force Targets, Directory Search, Rules
2592@section Phony Targets
2593@cindex phony targets
2594@cindex targets, phony
2595@cindex targets without a file
2596
2597A phony target is one that is not really the name of a file.  It is just a
2598name for some commands to be executed when you make an explicit request.
2599There are two reasons to use a phony target: to avoid a conflict with
2600a file of the same name, and to improve performance.
2601
2602If you write a rule whose commands will not create the target file, the
2603commands will be executed every time the target comes up for remaking.
2604Here is an example:
2605
2606@example
2607@group
2608clean:
2609        rm *.o temp
2610@end group
2611@end example
2612
2613@noindent
2614Because the @code{rm} command does not create a file named @file{clean},
2615probably no such file will ever exist.  Therefore, the @code{rm} command
2616will be executed every time you say @samp{make clean}.
2617@cindex @code{rm} (shell command)
2618
2619@findex .PHONY
2620The phony target will cease to work if anything ever does create a file
2621named @file{clean} in this directory.  Since it has no prerequisites, the
2622file @file{clean} would inevitably be considered up to date, and its
2623commands would not be executed.  To avoid this problem, you can explicitly
2624declare the target to be phony, using the special target @code{.PHONY}
2625(@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
2626
2627@example
2628.PHONY : clean
2629@end example
2630
2631@noindent
2632Once this is done, @samp{make clean} will run the commands regardless of
2633whether there is a file named @file{clean}.
2634
2635Since it knows that phony targets do not name actual files that could be
2636remade from other files, @code{make} skips the implicit rule search for
2637phony targets (@pxref{Implicit Rules}).  This is why declaring a target
2638phony is good for performance, even if you are not worried about the
2639actual file existing.
2640
2641Thus, you first write the line that states that @code{clean} is a
2642phony target, then you write the rule, like this:
2643
2644@example
2645@group
2646.PHONY: clean
2647clean:
2648        rm *.o temp
2649@end group
2650@end example
2651
2652Another example of the usefulness of phony targets is in conjunction
2653with recursive invocations of @code{make} (for more information, see
2654@ref{Recursion, ,Recursive Use of @code{make}}).  In this case the
2655makefile will often contain a variable which lists a number of
2656subdirectories to be built.  One way to handle this is with one rule
2657whose command is a shell loop over the subdirectories, like this:
2658
2659@example
2660@group
2661SUBDIRS = foo bar baz
2662
2663subdirs:
2664        for dir in $(SUBDIRS); do \
2665          $(MAKE) -C $$dir; \
2666        done
2667@end group
2668@end example
2669
2670There are a few problems with this method, however.  First, any error
2671detected in a submake is not noted by this rule, so it will continue to
2672build the rest of the directories even when one fails.  This can be
2673overcome by adding shell commands to note the error and exit, but then
2674it will do so even if @code{make} is invoked with the @code{-k} option,
2675which is unfortunate.  Second, and perhaps more importantly, you cannot
2676take advantage of @code{make}'s ability to build targets in parallel
2677(@pxref{Parallel, ,Parallel Execution}), since there is only one rule.
2678
2679By declaring the subdirectories as phony targets (you must do this as
2680the subdirectory obviously always exists; otherwise it won't be built)
2681you can remove these problems:
2682
2683@example
2684@group
2685SUBDIRS = foo bar baz
2686
2687.PHONY: subdirs $(SUBDIRS)
2688
2689subdirs: $(SUBDIRS)
2690
2691$(SUBDIRS):
2692        $(MAKE) -C $@@
2693
2694foo: baz
2695@end group
2696@end example
2697
2698Here we've also declared that the @file{foo} subdirectory cannot be
2699built until after the @file{baz} subdirectory is complete; this kind of
2700relationship declaration is particularly important when attempting
2701parallel builds.
2702
2703A phony target should not be a prerequisite of a real target file; if it
2704is, its commands are run every time @code{make} goes to update that
2705file.  As long as a phony target is never a prerequisite of a real
2706target, the phony target commands will be executed only when the phony
2707target is a specified goal (@pxref{Goals, ,Arguments to Specify the
2708Goals}).
2709
2710Phony targets can have prerequisites.  When one directory contains multiple
2711programs, it is most convenient to describe all of the programs in one
2712makefile @file{./Makefile}.  Since the target remade by default will be the
2713first one in the makefile, it is common to make this a phony target named
2714@samp{all} and give it, as prerequisites, all the individual programs.  For
2715example:
2716
2717@example
2718all : prog1 prog2 prog3
2719.PHONY : all
2720
2721prog1 : prog1.o utils.o
2722        cc -o prog1 prog1.o utils.o
2723
2724prog2 : prog2.o
2725        cc -o prog2 prog2.o
2726
2727prog3 : prog3.o sort.o utils.o
2728        cc -o prog3 prog3.o sort.o utils.o
2729@end example
2730
2731@noindent
2732Now you can say just @samp{make} to remake all three programs, or
2733specify as arguments the ones to remake (as in @samp{make prog1
2734prog3}).  Phoniness is not inherited: the prerequisites of a phony
2735target are not themselves phony, unless explicitly declared to be so.
2736
2737When one phony target is a prerequisite of another, it serves as a subroutine
2738of the other.  For example, here @samp{make cleanall} will delete the
2739object files, the difference files, and the file @file{program}:
2740
2741@example
2742.PHONY: cleanall cleanobj cleandiff
2743
2744cleanall : cleanobj cleandiff
2745        rm program
2746
2747cleanobj :
2748        rm *.o
2749
2750cleandiff :
2751        rm *.diff
2752@end example
2753
2754@node Force Targets, Empty Targets, Phony Targets, Rules
2755@section Rules without Commands or Prerequisites
2756@cindex force targets
2757@cindex targets, force
2758@cindex @code{FORCE}
2759@cindex rule, no commands or prerequisites
2760
2761If a rule has no prerequisites or commands, and the target of the rule
2762is a nonexistent file, then @code{make} imagines this target to have
2763been updated whenever its rule is run.  This implies that all targets
2764depending on this one will always have their commands run.
2765
2766An example will illustrate this:
2767
2768@example
2769@group
2770clean: FORCE
2771        rm $(objects)
2772FORCE:
2773@end group
2774@end example
2775
2776Here the target @samp{FORCE} satisfies the special conditions, so the
2777target @file{clean} that depends on it is forced to run its commands.
2778There is nothing special about the name @samp{FORCE}, but that is one name
2779commonly used this way.
2780
2781As you can see, using @samp{FORCE} this way has the same results as using
2782@samp{.PHONY: clean}.
2783
2784Using @samp{.PHONY} is more explicit and more efficient.  However,
2785other versions of @code{make} do not support @samp{.PHONY}; thus
2786@samp{FORCE} appears in many makefiles.  @xref{Phony Targets}.
2787
2788@node Empty Targets, Special Targets, Force Targets, Rules
2789@section Empty Target Files to Record Events
2790@cindex empty targets
2791@cindex targets, empty
2792@cindex recording events with empty targets
2793
2794The @dfn{empty target} is a variant of the phony target; it is used to hold
2795commands for an action that you request explicitly from time to time.
2796Unlike a phony target, this target file can really exist; but the file's
2797contents do not matter, and usually are empty.
2798
2799The purpose of the empty target file is to record, with its
2800last-modification time, when the rule's commands were last executed.  It
2801does so because one of the commands is a @code{touch} command to update the
2802target file.
2803
2804The empty target file should have some prerequisites (otherwise it
2805doesn't make sense).  When you ask to remake the empty target, the
2806commands are executed if any prerequisite is more recent than the target;
2807in other words, if a prerequisite has changed since the last time you
2808remade the target.  Here is an example:
2809
2810@example
2811print: foo.c bar.c
2812        lpr -p $?
2813        touch print
2814@end example
2815@cindex @code{print} target
2816@cindex @code{lpr} (shell command)
2817@cindex @code{touch} (shell command)
2818
2819@noindent
2820With this rule, @samp{make print} will execute the @code{lpr} command if
2821either source file has changed since the last @samp{make print}.  The
2822automatic variable @samp{$?} is used to print only those files that have
2823changed (@pxref{Automatic Variables}).
2824
2825@node Special Targets, Multiple Targets, Empty Targets, Rules
2826@section Special Built-in Target Names
2827@cindex special targets
2828@cindex built-in special targets
2829@cindex targets, built-in special
2830
2831Certain names have special meanings if they appear as targets.
2832
2833@table @code
2834@findex .PHONY
2835@item .PHONY
2836
2837The prerequisites of the special target @code{.PHONY} are considered to
2838be phony targets.  When it is time to consider such a target,
2839@code{make} will run its commands unconditionally, regardless of
2840whether a file with that name exists or what its last-modification
2841time is.  @xref{Phony Targets, ,Phony Targets}.
2842
2843@findex .SUFFIXES
2844@item .SUFFIXES
2845
2846The prerequisites of the special target @code{.SUFFIXES} are the list
2847of suffixes to be used in checking for suffix rules.
2848@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2849
2850@findex .DEFAULT
2851@item .DEFAULT
2852
2853The commands specified for @code{.DEFAULT} are used for any target for
2854which no rules are found (either explicit rules or implicit rules).
2855@xref{Last Resort}.  If @code{.DEFAULT} commands are specified, every
2856file mentioned as a prerequisite, but not as a target in a rule, will have
2857these commands executed on its behalf.  @xref{Implicit Rule Search,
2858,Implicit Rule Search Algorithm}.
2859
2860@findex .PRECIOUS
2861@item .PRECIOUS
2862@cindex precious targets
2863@cindex preserving with @code{.PRECIOUS}
2864
2865The targets which @code{.PRECIOUS} depends on are given the following
2866special treatment: if @code{make} is killed or interrupted during the
2867execution of their commands, the target is not deleted.
2868@xref{Interrupts, ,Interrupting or Killing @code{make}}.  Also, if the
2869target is an intermediate file, it will not be deleted after it is no
2870longer needed, as is normally done.  @xref{Chained Rules, ,Chains of
2871Implicit Rules}.  In this latter respect it overlaps with the
2872@code{.SECONDARY} special target.
2873
2874You can also list the target pattern of an implicit rule (such as
2875@samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS}
2876to preserve intermediate files created by rules whose target patterns
2877match that file's name.
2878
2879@findex .INTERMEDIATE
2880@item .INTERMEDIATE
2881@cindex intermediate targets, explicit
2882
2883The targets which @code{.INTERMEDIATE} depends on are treated as
2884intermediate files.  @xref{Chained Rules, ,Chains of Implicit Rules}.
2885@code{.INTERMEDIATE} with no prerequisites has no effect.
2886
2887@findex .SECONDARY
2888@item .SECONDARY
2889@cindex secondary targets
2890@cindex preserving with @code{.SECONDARY}
2891
2892The targets which @code{.SECONDARY} depends on are treated as
2893intermediate files, except that they are never automatically deleted.
2894@xref{Chained Rules, ,Chains of Implicit Rules}.
2895
2896@code{.SECONDARY} with no prerequisites causes all targets to be treated
2897as secondary (i.e., no target is removed because it is considered
2898intermediate).
2899
2900@findex .SECONDEXPANSION
2901@item .SECONDEXPANSION
2902
2903If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the
2904makefile, then all prerequisite lists defined @emph{after} it appears
2905will be expanded a second time after all makefiles have been read in.
2906@xref{Secondary Expansion, ,Secondary Expansion}.
2907
2908The prerequisites of the special target @code{.SUFFIXES} are the list
2909of suffixes to be used in checking for suffix rules.
2910@xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2911
2912@findex .DELETE_ON_ERROR
2913@item .DELETE_ON_ERROR
2914@cindex removing targets on failure
2915
2916If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the
2917makefile, then @code{make} will delete the target of a rule if it has
2918changed and its commands exit with a nonzero exit status, just as it
2919does when it receives a signal.  @xref{Errors, ,Errors in Commands}.
2920
2921@findex .IGNORE
2922@item .IGNORE
2923
2924If you specify prerequisites for @code{.IGNORE}, then @code{make} will
2925ignore errors in execution of the commands run for those particular
2926files.  The commands for @code{.IGNORE} are not meaningful.
2927
2928If mentioned as a target with no prerequisites, @code{.IGNORE} says to
2929ignore errors in execution of commands for all files.  This usage of
2930@samp{.IGNORE} is supported only for historical compatibility.  Since
2931this affects every command in the makefile, it is not very useful; we
2932recommend you use the more selective ways to ignore errors in specific
2933commands.  @xref{Errors, ,Errors in Commands}.
2934
2935@findex .LOW_RESOLUTION_TIME
2936@item .LOW_RESOLUTION_TIME
2937
2938If you specify prerequisites for @code{.LOW_RESOLUTION_TIME},
2939@command{make} assumes that these files are created by commands that
2940generate low resolution time stamps.  The commands for
2941@code{.LOW_RESOLUTION_TIME} are not meaningful.
2942
2943The high resolution file time stamps of many modern hosts lessen the
2944chance of @command{make} incorrectly concluding that a file is up to
2945date.  Unfortunately, these hosts provide no way to set a high
2946resolution file time stamp, so commands like @samp{cp -p} that
2947explicitly set a file's time stamp must discard its subsecond part.  If
2948a file is created by such a command, you should list it as a
2949prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} does
2950not mistakenly conclude that the file is out of date.  For example:
2951
2952@example
2953@group
2954.LOW_RESOLUTION_TIME: dst
2955dst: src
2956        cp -p src dst
2957@end group
2958@end example
2959
2960Since @samp{cp -p} discards the subsecond part of @file{src}'s time
2961stamp, @file{dst} is typically slightly older than @file{src} even when
2962it is up to date.  The @code{.LOW_RESOLUTION_TIME} line causes
2963@command{make} to consider @file{dst} to be up to date if its time stamp
2964is at the start of the same second that @file{src}'s time stamp is in.
2965
2966Due to a limitation of the archive format, archive member time stamps
2967are always low resolution.  You need not list archive members as
2968prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this
2969automatically.
2970
2971@findex .SILENT
2972@item .SILENT
2973
2974If you specify prerequisites for @code{.SILENT}, then @code{make} will
2975not print the commands to remake those particular files before executing
2976them.  The commands for @code{.SILENT} are not meaningful.
2977
2978If mentioned as a target with no prerequisites, @code{.SILENT} says not
2979to print any commands before executing them.  This usage of
2980@samp{.SILENT} is supported only for historical compatibility.  We
2981recommend you use the more selective ways to silence specific commands.
2982@xref{Echoing, ,Command Echoing}.  If you want to silence all commands
2983for a particular run of @code{make}, use the @samp{-s} or
2984@w{@samp{--silent}} option (@pxref{Options Summary}).
2985
2986@findex .EXPORT_ALL_VARIABLES
2987@item .EXPORT_ALL_VARIABLES
2988
2989Simply by being mentioned as a target, this tells @code{make} to
2990export all variables to child processes by default.
2991@xref{Variables/Recursion, ,Communicating Variables to a
2992Sub-@code{make}}.
2993
2994@findex .NOTPARALLEL
2995@item .NOTPARALLEL
2996@cindex parallel execution, overriding
2997
2998If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of
2999@code{make} will be run serially, even if the @samp{-j} option is
3000given.  Any recursively invoked @code{make} command will still be run in
3001parallel (unless its makefile contains this target).  Any prerequisites
3002on this target are ignored.
3003@end table
3004
3005Any defined implicit rule suffix also counts as a special target if it
3006appears as a target, and so does the concatenation of two suffixes, such
3007as @samp{.c.o}.  These targets are suffix rules, an obsolete way of
3008defining implicit rules (but a way still widely used).  In principle, any
3009target name could be special in this way if you break it in two and add
3010both pieces to the suffix list.  In practice, suffixes normally begin with
3011@samp{.}, so these special target names also begin with @samp{.}.
3012@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
3013
3014@node Multiple Targets, Multiple Rules, Special Targets, Rules
3015@section Multiple Targets in a Rule
3016@cindex multiple targets
3017@cindex several targets in a rule
3018@cindex targets, multiple
3019@cindex rule, with multiple targets
3020
3021A rule with multiple targets is equivalent to writing many rules, each with
3022one target, and all identical aside from that.  The same commands apply to
3023all the targets, but their effects may vary because you can substitute the
3024actual target name into the command using @samp{$@@}.  The rule contributes
3025the same prerequisites to all the targets also.
3026
3027This is useful in two cases.
3028
3029@itemize @bullet
3030@item
3031You want just prerequisites, no commands.  For example:
3032
3033@example
3034kbd.o command.o files.o: command.h
3035@end example
3036
3037@noindent
3038gives an additional prerequisite to each of the three object files
3039mentioned.
3040
3041@item
3042Similar commands work for all the targets.  The commands do not need
3043to be absolutely identical, since the automatic variable @samp{$@@}
3044can be used to substitute the particular target to be remade into the
3045commands (@pxref{Automatic Variables}).  For example:
3046
3047@example
3048@group
3049bigoutput littleoutput : text.g
3050        generate text.g -$(subst output,,$@@) > $@@
3051@end group
3052@end example
3053@findex subst
3054
3055@noindent
3056is equivalent to
3057
3058@example
3059bigoutput : text.g
3060        generate text.g -big > bigoutput
3061littleoutput : text.g
3062        generate text.g -little > littleoutput
3063@end example
3064
3065@noindent
3066Here we assume the hypothetical program @code{generate} makes two
3067types of output, one if given @samp{-big} and one if given
3068@samp{-little}.
3069@xref{Text Functions, ,Functions for String Substitution and Analysis},
3070for an explanation of the @code{subst} function.
3071@end itemize
3072
3073Suppose you would like to vary the prerequisites according to the target,
3074much as the variable @samp{$@@} allows you to vary the commands.
3075You cannot do this with multiple targets in an ordinary rule, but you can
3076do it with a @dfn{static pattern rule}.
3077@xref{Static Pattern, ,Static Pattern Rules}.
3078
3079@node Multiple Rules, Static Pattern, Multiple Targets, Rules
3080@section Multiple Rules for One Target
3081@cindex multiple rules for one target
3082@cindex several rules for one target
3083@cindex rule, multiple for one target
3084@cindex target, multiple rules for one
3085
3086One file can be the target of several rules.  All the prerequisites
3087mentioned in all the rules are merged into one list of prerequisites for
3088the target.  If the target is older than any prerequisite from any rule,
3089the commands are executed.
3090
3091There can only be one set of commands to be executed for a file.  If
3092more than one rule gives commands for the same file, @code{make} uses
3093the last set given and prints an error message.  (As a special case,
3094if the file's name begins with a dot, no error message is printed.
3095This odd behavior is only for compatibility with other implementations
3096of @code{make}... you should avoid using it).  Occasionally it is
3097useful to have the same target invoke multiple commands which are
3098defined in different parts of your makefile; you can use
3099@dfn{double-colon rules} (@pxref{Double-Colon}) for this.
3100
3101An extra rule with just prerequisites can be used to give a few extra
3102prerequisites to many files at once.  For example, makefiles often
3103have a variable, such as @code{objects}, containing a list of all the
3104compiler output files in the system being made.  An easy way to say
3105that all of them must be recompiled if @file{config.h} changes is to
3106write the following:
3107
3108@example
3109objects = foo.o bar.o
3110foo.o : defs.h
3111bar.o : defs.h test.h
3112$(objects) : config.h
3113@end example
3114
3115This could be inserted or taken out without changing the rules that really
3116specify how to make the object files, making it a convenient form to use if
3117you wish to add the additional prerequisite intermittently.
3118
3119Another wrinkle is that the additional prerequisites could be specified with
3120a variable that you set with a command argument to @code{make}
3121(@pxref{Overriding, ,Overriding Variables}).  For example,
3122
3123@example
3124@group
3125extradeps=
3126$(objects) : $(extradeps)
3127@end group
3128@end example
3129
3130@noindent
3131means that the command @samp{make extradeps=foo.h} will consider
3132@file{foo.h} as a prerequisite of each object file, but plain @samp{make}
3133will not.
3134
3135If none of the explicit rules for a target has commands, then @code{make}
3136searches for an applicable implicit rule to find some commands
3137@pxref{Implicit Rules, ,Using Implicit Rules}).
3138
3139@node Static Pattern, Double-Colon, Multiple Rules, Rules
3140@section Static Pattern Rules
3141@cindex static pattern rule
3142@cindex rule, static pattern
3143@cindex pattern rules, static (not implicit)
3144@cindex varying prerequisites
3145@cindex prerequisites, varying (static pattern)
3146
3147@dfn{Static pattern rules} are rules which specify multiple targets and
3148construct the prerequisite names for each target based on the target name.
3149They are more general than ordinary rules with multiple targets because the
3150targets do not have to have identical prerequisites.  Their prerequisites must
3151be @emph{analogous}, but not necessarily @emph{identical}.
3152
3153@menu
3154* Static Usage::                The syntax of static pattern rules.
3155* Static versus Implicit::      When are they better than implicit rules?
3156@end menu
3157
3158@node Static Usage, Static versus Implicit, Static Pattern, Static Pattern
3159@subsection Syntax of Static Pattern Rules
3160@cindex static pattern rule, syntax of
3161@cindex pattern rules, static, syntax of
3162
3163Here is the syntax of a static pattern rule:
3164
3165@example
3166@var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{}
3167        @var{commands}
3168        @dots{}
3169@end example
3170
3171@noindent
3172The @var{targets} list specifies the targets that the rule applies to.
3173The targets can contain wildcard characters, just like the targets of
3174ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
3175Names}).
3176
3177@cindex target pattern, static (not implicit)
3178@cindex stem
3179The @var{target-pattern} and @var{prereq-patterns} say how to compute the
3180prerequisites of each target.  Each target is matched against the
3181@var{target-pattern} to extract a part of the target name, called the
3182@dfn{stem}.  This stem is substituted into each of the @var{prereq-patterns}
3183to make the prerequisite names (one from each @var{prereq-pattern}).
3184
3185Each pattern normally contains the character @samp{%} just once.  When the
3186@var{target-pattern} matches a target, the @samp{%} can match any part of
3187the target name; this part is called the @dfn{stem}.  The rest of the
3188pattern must match exactly.  For example, the target @file{foo.o} matches
3189the pattern @samp{%.o}, with @samp{foo} as the stem.  The targets
3190@file{foo.c} and @file{foo.out} do not match that pattern.@refill
3191
3192@cindex prerequisite pattern, static (not implicit)
3193The prerequisite names for each target are made by substituting the stem
3194for the @samp{%} in each prerequisite pattern.  For example, if one
3195prerequisite pattern is @file{%.c}, then substitution of the stem
3196@samp{foo} gives the prerequisite name @file{foo.c}.  It is legitimate
3197to write a prerequisite pattern that does not contain @samp{%}; then this
3198prerequisite is the same for all targets.
3199
3200@cindex @code{%}, quoting in static pattern
3201@cindex @code{%}, quoting with @code{\} (backslash)
3202@cindex @code{\} (backslash), to quote @code{%}
3203@cindex backslash (@code{\}), to quote @code{%}
3204@cindex quoting @code{%}, in static pattern
3205@samp{%} characters in pattern rules can be quoted with preceding
3206backslashes (@samp{\}).  Backslashes that would otherwise quote @samp{%}
3207characters can be quoted with more backslashes.  Backslashes that quote
3208@samp{%} characters or other backslashes are removed from the pattern
3209before it is compared to file names or has a stem substituted into it.
3210Backslashes that are not in danger of quoting @samp{%} characters go
3211unmolested.  For example, the pattern @file{the\%weird\\%pattern\\} has
3212@samp{the%weird\} preceding the operative @samp{%} character, and
3213@samp{pattern\\} following it.  The final two backslashes are left alone
3214because they cannot affect any @samp{%} character.@refill
3215
3216Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
3217from the corresponding @file{.c} file:
3218
3219@example
3220@group
3221objects = foo.o bar.o
3222
3223all: $(objects)
3224
3225$(objects): %.o: %.c
3226        $(CC) -c $(CFLAGS) $< -o $@@
3227@end group
3228@end example
3229
3230@noindent
3231Here @samp{$<} is the automatic variable that holds the name of the
3232prerequisite and @samp{$@@} is the automatic variable that holds the name
3233of the target; see @ref{Automatic Variables}.
3234
3235Each target specified must match the target pattern; a warning is issued
3236for each target that does not.  If you have a list of files, only some of
3237which will match the pattern, you can use the @code{filter} function to
3238remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
3239
3240@example
3241files = foo.elc bar.o lose.o
3242
3243$(filter %.o,$(files)): %.o: %.c
3244        $(CC) -c $(CFLAGS) $< -o $@@
3245$(filter %.elc,$(files)): %.elc: %.el
3246        emacs -f batch-byte-compile $<
3247@end example
3248
3249@noindent
3250In this example the result of @samp{$(filter %.o,$(files))} is
3251@file{bar.o lose.o}, and the first static pattern rule causes each of
3252these object files to be updated by compiling the corresponding C source
3253file.  The result of @w{@samp{$(filter %.elc,$(files))}} is
3254@file{foo.elc}, so that file is made from @file{foo.el}.@refill
3255
3256Another example shows how to use @code{$*} in static pattern rules:
3257@vindex $*@r{, and static pattern}
3258
3259@example
3260@group
3261bigoutput littleoutput : %output : text.g
3262        generate text.g -$* > $@@
3263@end group
3264@end example
3265
3266@noindent
3267When the @code{generate} command is run, @code{$*} will expand to the
3268stem, either @samp{big} or @samp{little}.
3269
3270@node Static versus Implicit,  , Static Usage, Static Pattern
3271@subsection Static Pattern Rules versus Implicit Rules
3272@cindex rule, static pattern versus implicit
3273@cindex static pattern rule, versus implicit
3274
3275A static pattern rule has much in common with an implicit rule defined as a
3276pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
3277Both have a pattern for the target and patterns for constructing the
3278names of prerequisites.  The difference is in how @code{make} decides
3279@emph{when} the rule applies.
3280
3281An implicit rule @emph{can} apply to any target that matches its pattern,
3282but it @emph{does} apply only when the target has no commands otherwise
3283specified, and only when the prerequisites can be found.  If more than one
3284implicit rule appears applicable, only one applies; the choice depends on
3285the order of rules.
3286
3287By contrast, a static pattern rule applies to the precise list of targets
3288that you specify in the rule.  It cannot apply to any other target and it
3289invariably does apply to each of the targets specified.  If two conflicting
3290rules apply, and both have commands, that's an error.
3291
3292The static pattern rule can be better than an implicit rule for these
3293reasons:
3294
3295@itemize @bullet
3296@item
3297You may wish to override the usual implicit rule for a few
3298files whose names cannot be categorized syntactically but
3299can be given in an explicit list.
3300
3301@item
3302If you cannot be sure of the precise contents of the directories
3303you are using, you may not be sure which other irrelevant files
3304might lead @code{make} to use the wrong implicit rule.  The choice
3305might depend on the order in which the implicit rule search is done.
3306With static pattern rules, there is no uncertainty: each rule applies
3307to precisely the targets specified.
3308@end itemize
3309
3310@node Double-Colon, Automatic Prerequisites, Static Pattern, Rules
3311@section Double-Colon Rules
3312@cindex double-colon rules
3313@cindex rule, double-colon (@code{::})
3314@cindex multiple rules for one target (@code{::})
3315@cindex @code{::} rules (double-colon)
3316
3317@dfn{Double-colon} rules are rules written with @samp{::} instead of
3318@samp{:} after the target names.  They are handled differently from
3319ordinary rules when the same target appears in more than one rule.
3320
3321When a target appears in multiple rules, all the rules must be the same
3322type: all ordinary, or all double-colon.  If they are double-colon, each
3323of them is independent of the others.  Each double-colon rule's commands
3324are executed if the target is older than any prerequisites of that rule.
3325If there are no prerequisites for that rule, its commands are always
3326executed (even if the target already exists).  This can result in
3327executing none, any, or all of the double-colon rules.
3328
3329Double-colon rules with the same target are in fact completely separate
3330from one another.  Each double-colon rule is processed individually, just
3331as rules with different targets are processed.
3332
3333The double-colon rules for a target are executed in the order they appear
3334in the makefile.  However, the cases where double-colon rules really make
3335sense are those where the order of executing the commands would not matter.
3336
3337Double-colon rules are somewhat obscure and not often very useful; they
3338provide a mechanism for cases in which the method used to update a target
3339differs depending on which prerequisite files caused the update, and such
3340cases are rare.
3341
3342Each double-colon rule should specify commands; if it does not, an
3343implicit rule will be used if one applies.
3344@xref{Implicit Rules, ,Using Implicit Rules}.
3345
3346@node Automatic Prerequisites,  , Double-Colon, Rules
3347@section Generating Prerequisites Automatically
3348@cindex prerequisites, automatic generation
3349@cindex automatic generation of prerequisites
3350@cindex generating prerequisites automatically
3351
3352In the makefile for a program, many of the rules you need to write often
3353say only that some object file depends on some header
3354file.  For example, if @file{main.c} uses @file{defs.h} via an
3355@code{#include}, you would write:
3356
3357@example
3358main.o: defs.h
3359@end example
3360
3361@noindent
3362You need this rule so that @code{make} knows that it must remake
3363@file{main.o} whenever @file{defs.h} changes.  You can see that for a
3364large program you would have to write dozens of such rules in your
3365makefile.  And, you must always be very careful to update the makefile
3366every time you add or remove an @code{#include}.
3367@cindex @code{#include}
3368
3369@cindex @code{-M} (to compiler)
3370To avoid this hassle, most modern C compilers can write these rules for
3371you, by looking at the @code{#include} lines in the source files.
3372Usually this is done with the @samp{-M} option to the compiler.
3373For example, the command:
3374
3375@example
3376cc -M main.c
3377@end example
3378
3379@noindent
3380generates the output:
3381
3382@example
3383main.o : main.c defs.h
3384@end example
3385
3386@noindent
3387Thus you no longer have to write all those rules yourself.
3388The compiler will do it for you.
3389
3390Note that such a prerequisite constitutes mentioning @file{main.o} in a
3391makefile, so it can never be considered an intermediate file by implicit
3392rule search.  This means that @code{make} won't ever remove the file
3393after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}.
3394
3395@cindex @code{make depend}
3396With old @code{make} programs, it was traditional practice to use this
3397compiler feature to generate prerequisites on demand with a command like
3398@samp{make depend}.  That command would create a file @file{depend}
3399containing all the automatically-generated prerequisites; then the
3400makefile could use @code{include} to read them in (@pxref{Include}).
3401
3402In GNU @code{make}, the feature of remaking makefiles makes this
3403practice obsolete---you need never tell @code{make} explicitly to
3404regenerate the prerequisites, because it always regenerates any makefile
3405that is out of date.  @xref{Remaking Makefiles}.
3406
3407The practice we recommend for automatic prerequisite generation is to have
3408one makefile corresponding to each source file.  For each source file
3409@file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
3410what files the object file @file{@var{name}.o} depends on.  That way
3411only the source files that have changed need to be rescanned to produce
3412the new prerequisites.
3413
3414Here is the pattern rule to generate a file of prerequisites (i.e., a makefile)
3415called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
3416
3417@smallexample
3418@group
3419%.d: %.c
3420        @@set -e; rm -f $@@; \
3421         $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \
3422         sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \
3423         rm -f $@@.$$$$
3424@end group
3425@end smallexample
3426
3427@noindent
3428@xref{Pattern Rules}, for information on defining pattern rules.  The
3429@samp{-e} flag to the shell causes it to exit immediately if the
3430@code{$(CC)} command (or any other command) fails (exits with a
3431nonzero status).
3432@cindex @code{-e} (shell flag)
3433
3434@cindex @code{-MM} (to GNU compiler)
3435With the GNU C compiler, you may wish to use the @samp{-MM} flag instead
3436of @samp{-M}.  This omits prerequisites on system header files.
3437@xref{Preprocessor Options, , Options Controlling the Preprocessor,
3438gcc.info, Using GNU CC}, for details.
3439
3440@cindex @code{sed} (shell command)
3441The purpose of the @code{sed} command is to translate (for example):
3442
3443@example
3444main.o : main.c defs.h
3445@end example
3446
3447@noindent
3448into:
3449
3450@example
3451main.o main.d : main.c defs.h
3452@end example
3453
3454@noindent
3455@cindex @code{.d}
3456This makes each @samp{.d} file depend on all the source and header files
3457that the corresponding @samp{.o} file depends on.  @code{make} then
3458knows it must regenerate the prerequisites whenever any of the source or
3459header files changes.
3460
3461Once you've defined the rule to remake the @samp{.d} files,
3462you then use the @code{include} directive to read them all in.
3463@xref{Include}.  For example:
3464
3465@example
3466@group
3467sources = foo.c bar.c
3468
3469include $(sources:.c=.d)
3470@end group
3471@end example
3472
3473@noindent
3474(This example uses a substitution variable reference to translate the
3475list of source files @samp{foo.c bar.c} into a list of prerequisite
3476makefiles, @samp{foo.d bar.d}.  @xref{Substitution Refs}, for full
3477information on substitution references.)  Since the @samp{.d} files are
3478makefiles like any others, @code{make} will remake them as necessary
3479with no further work from you.  @xref{Remaking Makefiles}.
3480
3481Note that the @samp{.d} files contain target definitions; you should
3482be sure to place the @code{include} directive @emph{after} the first,
3483default goal in your makefiles or run the risk of having a random
3484object file become the default goal.
3485@xref{How Make Works}.
3486
3487@node Commands, Using Variables, Rules, Top
3488@chapter Writing the Commands in Rules
3489@cindex commands, how to write
3490@cindex rule commands
3491@cindex writing rule commands
3492
3493The commands of a rule consist of one or more shell command lines to
3494be executed, one at a time, in the order they appear.  Typically, the
3495result of executing these commands is that the target of the rule is
3496brought up to date.
3497
3498Users use many different shell programs, but commands in makefiles are
3499always interpreted by @file{/bin/sh} unless the makefile specifies
3500otherwise.  @xref{Execution, ,Command Execution}.
3501
3502@menu
3503* Command Syntax::              Command syntax features and pitfalls.
3504* Echoing::                     How to control when commands are echoed.
3505* Execution::                   How commands are executed.
3506* Parallel::                    How commands can be executed in parallel.
3507* Errors::                      What happens after a command execution error.
3508* Interrupts::                  What happens when a command is interrupted.
3509* Recursion::                   Invoking @code{make} from makefiles.
3510* Sequences::                   Defining canned sequences of commands.
3511* Empty Commands::              Defining useful, do-nothing commands.
3512@end menu
3513
3514@node Command Syntax, Echoing, Commands, Commands
3515@section Command Syntax
3516@cindex command syntax
3517@cindex syntax of commands
3518
3519Makefiles have the unusual property that there are really two distinct
3520syntaxes in one file.  Most of the makefile uses @code{make} syntax
3521(@pxref{Makefiles, ,Writing Makefiles}).  However, commands are meant to be
3522interpreted by the shell and so they are written using shell syntax.
3523The @code{make} program does not try to understand shell syntax: it
3524performs only a very few specific translations on the content of the
3525command before handing it to the shell.
3526
3527Each command line must start with a tab, except that the first command
3528line may be attached to the target-and-prerequisites line with a
3529semicolon in between.  @emph{Any} line in the makefile that begins
3530with a tab and appears in a ``rule context'' (that is, after a rule
3531has been started until another rule or variable definition) will be
3532considered a command line for that rule.  Blank lines and lines of
3533just comments may appear among the command lines; they are ignored.
3534
3535Some consequences of these rules include:
3536
3537@itemize @bullet
3538@item
3539A blank line that begins with a tab is not blank: it's an empty
3540command (@pxref{Empty Commands}).
3541
3542@cindex comments, in commands
3543@cindex commands, comments in
3544@cindex @code{#} (comments), in commands
3545@item
3546A comment in a command line is not a @code{make} comment; it will be
3547passed to the shell as-is.  Whether the shell treats it as a comment
3548or not depends on your shell.
3549
3550@item
3551A variable definition in a ``rule context'' which is indented by a tab
3552as the first character on the line, will be considered a command line,
3553not a @code{make} variable definition, and passed to the shell.
3554
3555@item
3556A conditional expression (@code{ifdef}, @code{ifeq},
3557etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule
3558context'' which is indented by a tab as the first character on the
3559line, will be considered a command line and be passed to the shell.
3560
3561@end itemize
3562
3563@menu
3564* Splitting Lines::             Breaking long command lines for readability.
3565* Variables in Commands::       Using @code{make} variables in commands.
3566@end menu
3567
3568@node Splitting Lines, Variables in Commands, Command Syntax, Command Syntax
3569@subsection Splitting Command Lines
3570@cindex commands, splitting
3571@cindex splitting commands
3572@cindex commands, backslash (@code{\}) in
3573@cindex commands, quoting newlines in
3574@cindex backslash (@code{\}), in commands
3575@cindex @code{\} (backslash), in commands
3576@cindex quoting newline, in commands
3577@cindex newline, quoting, in commands
3578
3579One of the few ways in which @code{make} does interpret command lines
3580is checking for a backslash just before the newline.  As in normal
3581makefile syntax, a single command can be split into multiple lines in
3582the makefile by placing a backslash before each newline.  A sequence
3583of lines like this is considered a single command, and one instance of
3584the shell will be invoked to run it.
3585
3586However, in contrast to how they are treated in other places in a
3587makefile, backslash-newline pairs are @emph{not} removed from the
3588command.  Both the backslash and the newline characters are preserved
3589and passed to the shell.  How the backslash-newline is interpreted
3590depends on your shell.  If the first character of the next line
3591after the backslash-newline is a tab, then that tab (and only that
3592tab) is removed.  Whitespace is never added to the command.
3593
3594For example, this makefile:
3595
3596@example
3597@group
3598all :
3599        @@echo no\
3600space
3601        @@echo no\
3602        space
3603        @@echo one \
3604        space
3605        @@echo one\
3606         space
3607@end group
3608@end example
3609
3610@noindent
3611consists of four separate shell commands where the output is:
3612
3613@example
3614@group
3615nospace
3616nospace
3617one space
3618one space
3619@end group
3620@end example
3621
3622As a more complex example, this makefile:
3623
3624@example
3625@group
3626all : ; @@echo 'hello \
3627        world' ; echo "hello \
3628    world"
3629@end group
3630@end example
3631
3632@noindent
3633will run one shell with a command script of:
3634
3635@example
3636@group
3637echo 'hello \
3638world' ; echo "hello \
3639    world"
3640@end group
3641@end example
3642
3643@noindent
3644which, according to shell quoting rules, will yield the following output:
3645
3646@example
3647@group
3648hello \
3649world
3650hello     world
3651@end group
3652@end example
3653
3654@noindent
3655Notice how the backslash/newline pair was removed inside the string quoted
3656with double quotes (@code{"..."}), but not from the string quoted with single
3657quotes (@code{'...'}).  This is the way the default shell (@file{/bin/sh})
3658handles backslash/newline pairs.  If you specify a different shell in your
3659makefiles it may treat them differently.
3660
3661Sometimes you want to split a long line inside of single quotes, but
3662you don't want the backslash-newline to appear in the quoted content.
3663This is often the case when passing scripts to languages such as Perl,
3664where extraneous backslashes inside the script can change its meaning
3665or even be a syntax error.  One simple way of handling this is to
3666place the quoted string, or even the entire command, into a
3667@code{make} variable then use the variable in the command.  In this
3668situation the newline quoting rules for makefiles will be used, and
3669the backslash-newline will be removed.  If we rewrite our example
3670above using this method:
3671
3672@example
3673@group
3674HELLO = 'hello \
3675world'
3676
3677all : ; @@echo $(HELLO)
3678@end group
3679@end example
3680
3681@noindent
3682we will get output like this:
3683
3684@example
3685@group
3686hello world
3687@end group
3688@end example
3689
3690If you like, you can also use target-specific variables
3691(@pxref{Target-specific, ,Target-specific Variable Values}) to obtain
3692a tighter correspondence between the variable and the command that
3693uses it.
3694
3695@node Variables in Commands,  , Splitting Lines, Command Syntax
3696@subsection Using Variables in Commands
3697@cindex variable references in commands
3698@cindex commands, using variables in
3699
3700The other way in which @code{make} processes commands is by expanding
3701any variable references in them (@pxref{Reference,Basics of Variable
3702References}).  This occurs after make has finished reading all the
3703makefiles and the target is determined to be out of date; so, the
3704commands for targets which are not rebuilt are never expanded.
3705
3706Variable and function references in commands have identical syntax and
3707semantics to references elsewhere in the makefile.  They also have the
3708same quoting rules: if you want a dollar sign to appear in your
3709command, you must double it (@samp{$$}).  For shells like the default
3710shell, that use dollar signs to introduce variables, it's important to
3711keep clear in your mind whether the variable you want to reference is
3712a @code{make} variable (use a single dollar sign) or a shell variable
3713(use two dollar signs).  For example:
3714
3715@example
3716@group
3717LIST = one two three
3718all:
3719        for i in $(LIST); do \
3720            echo $$i; \
3721        done
3722@end group
3723@end example
3724
3725@noindent
3726results in the following command being passed to the shell:
3727
3728@example
3729@group
3730for i in one two three; do \
3731    echo $i; \
3732done
3733@end group
3734@end example
3735
3736@noindent
3737which generates the expected result:
3738
3739@example
3740@group
3741one
3742two
3743three
3744@end group
3745@end example
3746
3747@node Echoing, Execution, Command Syntax, Commands
3748@section Command Echoing
3749@cindex echoing of commands
3750@cindex silent operation
3751@cindex @code{@@} (in commands)
3752@cindex commands, echoing
3753@cindex printing of commands
3754
3755Normally @code{make} prints each command line before it is executed.
3756We call this @dfn{echoing} because it gives the appearance that you
3757are typing the commands yourself.
3758
3759When a line starts with @samp{@@}, the echoing of that line is suppressed.
3760The @samp{@@} is discarded before the command is passed to the shell.
3761Typically you would use this for a command whose only effect is to print
3762something, such as an @code{echo} command to indicate progress through
3763the makefile:
3764
3765@example
3766@@echo About to make distribution files
3767@end example
3768
3769@cindex @code{-n}
3770@cindex @code{--just-print}
3771@cindex @code{--dry-run}
3772@cindex @code{--recon}
3773When @code{make} is given the flag @samp{-n} or @samp{--just-print}
3774it only echoes commands, it won't execute them.  @xref{Options Summary,
3775,Summary of Options}.  In this case and only this case, even the
3776commands starting with @samp{@@} are printed.  This flag is useful for
3777finding out which commands @code{make} thinks are necessary without
3778actually doing them.
3779
3780@cindex @code{-s}
3781@cindex @code{--silent}
3782@cindex @code{--quiet}
3783@findex .SILENT
3784The @samp{-s} or @samp{--silent}
3785flag to @code{make} prevents all echoing, as if all commands
3786started with @samp{@@}.  A rule in the makefile for the special target
3787@code{.SILENT} without prerequisites has the same effect
3788(@pxref{Special Targets, ,Special Built-in Target Names}).
3789@code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
3790
3791@node Execution, Parallel, Echoing, Commands
3792@section Command Execution
3793@cindex commands, execution
3794@cindex execution, of commands
3795@cindex shell command, execution
3796@vindex @code{SHELL} @r{(command execution)}
3797
3798When it is time to execute commands to update a target, they are
3799executed by invoking a new subshell for each command line.  (In
3800practice, @code{make} may take shortcuts that do not affect the
3801results.)
3802
3803@cindex @code{cd} (shell command)
3804@cindex shell variables, setting in commands
3805@cindex commands setting shell variables
3806@strong{Please note:} this implies that setting shell variables and
3807invoking shell commands such as @code{cd} that set a context local to
3808each process will not affect the following command lines.@footnote{On
3809MS-DOS, the value of current working directory is @strong{global}, so
3810changing it @emph{will} affect the following command lines on those
3811systems.}  If you want to use @code{cd} to affect the next statement,
3812put both statements in a single command line.  Then @code{make} will
3813invoke one shell to run the entire line, and the shell will execute
3814the statements in sequence.  For example:
3815
3816@example
3817foo : bar/lose
3818        cd $(@@D) && gobble $(@@F) > ../$@@
3819@end example
3820
3821@noindent
3822Here we use the shell AND operator (@code{&&}) so that if the
3823@code{cd} command fails, the script will fail without trying to invoke
3824the @code{gobble} command in the wrong directory, which could cause
3825problems (in this case it would certainly cause @file{../foo} to be
3826truncated, at least).
3827
3828@menu
3829* Choosing the Shell::          How @code{make} chooses the shell used
3830                                  to run commands.
3831@end menu
3832
3833@node Choosing the Shell,  , Execution, Execution
3834@subsection Choosing the Shell
3835@cindex shell, choosing the
3836@cindex @code{SHELL}, value of
3837
3838@vindex SHELL
3839The program used as the shell is taken from the variable @code{SHELL}.
3840If this variable is not set in your makefile, the program
3841@file{/bin/sh} is used as the shell.
3842
3843@cindex environment, @code{SHELL} in
3844Unlike most variables, the variable @code{SHELL} is never set from the
3845environment.  This is because the @code{SHELL} environment variable is
3846used to specify your personal choice of shell program for interactive
3847use.  It would be very bad for personal choices like this to affect the
3848functioning of makefiles.  @xref{Environment, ,Variables from the
3849Environment}.
3850
3851Furthermore, when you do set @code{SHELL} in your makefile that value
3852is @emph{not} exported in the environment to commands that @code{make}
3853invokes.  Instead, the value inherited from the user's environment, if
3854any, is exported.  You can override this behavior by explicitly
3855exporting @code{SHELL} (@pxref{Variables/Recursion, ,Communicating
3856Variables to a Sub-@code{make}}), forcing it to be passed in the
3857environment to commands.
3858
3859@vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})}
3860However, on MS-DOS and MS-Windows the value of @code{SHELL} in the
3861environment @strong{is} used, since on those systems most users do not
3862set this variable, and therefore it is most likely set specifically to
3863be used by @code{make}.  On MS-DOS, if the setting of @code{SHELL} is
3864not suitable for @code{make}, you can set the variable
3865@code{MAKESHELL} to the shell that @code{make} should use; if set it
3866will be used as the shell instead of the value of @code{SHELL}.
3867
3868@subsubheading Choosing a Shell in DOS and Windows
3869@cindex shell, in DOS and Windows
3870@cindex DOS, choosing a shell in
3871@cindex Windows, choosing a shell in
3872
3873Choosing a shell in MS-DOS and MS-Windows is much more complex than on
3874other systems.
3875
3876@vindex COMSPEC
3877On MS-DOS, if @code{SHELL} is not set, the value of the variable
3878@code{COMSPEC} (which is always set) is used instead.
3879
3880@cindex @code{SHELL}, MS-DOS specifics
3881The processing of lines that set the variable @code{SHELL} in Makefiles
3882is different on MS-DOS.  The stock shell, @file{command.com}, is
3883ridiculously limited in its functionality and many users of @code{make}
3884tend to install a replacement shell.  Therefore, on MS-DOS, @code{make}
3885examines the value of @code{SHELL}, and changes its behavior based on
3886whether it points to a Unix-style or DOS-style shell.  This allows
3887reasonable functionality even if @code{SHELL} points to
3888@file{command.com}.
3889
3890If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS
3891additionally checks whether that shell can indeed be found; if not, it
3892ignores the line that sets @code{SHELL}.  In MS-DOS, GNU @code{make}
3893searches for the shell in the following places:
3894
3895@enumerate
3896@item
3897In the precise place pointed to by the value of @code{SHELL}.  For
3898example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make}
3899will look in the directory @file{/bin} on the current drive.
3900
3901@item
3902In the current directory.
3903
3904@item
3905In each of the directories in the @code{PATH} variable, in order.
3906
3907@end enumerate
3908
3909In every directory it examines, @code{make} will first look for the
3910specific file (@file{sh} in the example above).  If this is not found,
3911it will also look in that directory for that file with one of the known
3912extensions which identify executable files.  For example @file{.exe},
3913@file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others.
3914
3915If any of these attempts is successful, the value of @code{SHELL} will
3916be set to the full pathname of the shell as found.  However, if none of
3917these is found, the value of @code{SHELL} will not be changed, and thus
3918the line that sets it will be effectively ignored.  This is so
3919@code{make} will only support features specific to a Unix-style shell if
3920such a shell is actually installed on the system where @code{make} runs.
3921
3922Note that this extended search for the shell is limited to the cases
3923where @code{SHELL} is set from the Makefile; if it is set in the
3924environment or command line, you are expected to set it to the full
3925pathname of the shell, exactly as things are on Unix.
3926
3927The effect of the above DOS-specific processing is that a Makefile that
3928contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
3929on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some
3930directory along your @code{PATH}.
3931
3932@node Parallel, Errors, Execution, Commands
3933@section Parallel Execution
3934@cindex commands, execution in parallel
3935@cindex parallel execution
3936@cindex execution, in parallel
3937@cindex job slots
3938@cindex @code{-j}
3939@cindex @code{--jobs}
3940
3941GNU @code{make} knows how to execute several commands at once.
3942Normally, @code{make} will execute only one command at a time, waiting
3943for it to finish before executing the next.  However, the @samp{-j} or
3944@samp{--jobs} option tells @code{make} to execute many commands
3945simultaneously.@refill
3946
3947On MS-DOS, the @samp{-j} option has no effect, since that system doesn't
3948support multi-processing.
3949
3950If the @samp{-j} option is followed by an integer, this is the number of
3951commands to execute at once; this is called the number of @dfn{job slots}.
3952If there is nothing looking like an integer after the @samp{-j} option,
3953there is no limit on the number of job slots.  The default number of job
3954slots is one, which means serial execution (one thing at a time).
3955
3956One unpleasant consequence of running several commands simultaneously is
3957that output generated by the commands appears whenever each command
3958sends it, so messages from different commands may be interspersed.
3959
3960Another problem is that two processes cannot both take input from the
3961same device; so to make sure that only one command tries to take input
3962from the terminal at once, @code{make} will invalidate the standard
3963input streams of all but one running command.  This means that
3964attempting to read from standard input will usually be a fatal error (a
3965@samp{Broken pipe} signal) for most child processes if there are
3966several.
3967@cindex broken pipe
3968@cindex standard input
3969
3970It is unpredictable which command will have a valid standard input stream
3971(which will come from the terminal, or wherever you redirect the standard
3972input of @code{make}).  The first command run will always get it first, and
3973the first command started after that one finishes will get it next, and so
3974on.
3975
3976We will change how this aspect of @code{make} works if we find a better
3977alternative.  In the mean time, you should not rely on any command using
3978standard input at all if you are using the parallel execution feature; but
3979if you are not using this feature, then standard input works normally in
3980all commands.
3981
3982Finally, handling recursive @code{make} invocations raises issues.  For
3983more information on this, see
3984@ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
3985
3986If a command fails (is killed by a signal or exits with a nonzero
3987status), and errors are not ignored for that command
3988(@pxref{Errors, ,Errors in Commands}),
3989the remaining command lines to remake the same target will not be run.
3990If a command fails and the @samp{-k} or @samp{--keep-going}
3991option was not given
3992(@pxref{Options Summary, ,Summary of Options}),
3993@code{make} aborts execution.  If make
3994terminates for any reason (including a signal) with child processes
3995running, it waits for them to finish before actually exiting.@refill
3996
3997@cindex load average
3998@cindex limiting jobs based on load
3999@cindex jobs, limiting based on load
4000@cindex @code{-l} (load average)
4001@cindex @code{--max-load}
4002@cindex @code{--load-average}
4003When the system is heavily loaded, you will probably want to run fewer jobs
4004than when it is lightly loaded.  You can use the @samp{-l} option to tell
4005@code{make} to limit the number of jobs to run at once, based on the load
4006average.  The @samp{-l} or @samp{--max-load}
4007option is followed by a floating-point number.  For
4008example,
4009
4010@example
4011-l 2.5
4012@end example
4013
4014@noindent
4015will not let @code{make} start more than one job if the load average is
4016above 2.5.  The @samp{-l} option with no following number removes the
4017load limit, if one was given with a previous @samp{-l} option.@refill
4018
4019More precisely, when @code{make} goes to start up a job, and it already has
4020at least one job running, it checks the current load average; if it is not
4021lower than the limit given with @samp{-l}, @code{make} waits until the load
4022average goes below that limit, or until all the other jobs finish.
4023
4024By default, there is no load limit.
4025
4026@node Errors, Interrupts, Parallel, Commands
4027@section Errors in Commands
4028@cindex errors (in commands)
4029@cindex commands, errors in
4030@cindex exit status (errors)
4031
4032After each shell command returns, @code{make} looks at its exit status.
4033If the command completed successfully, the next command line is executed
4034in a new shell; after the last command line is finished, the rule is
4035finished.
4036
4037If there is an error (the exit status is nonzero), @code{make} gives up on
4038the current rule, and perhaps on all rules.
4039
4040Sometimes the failure of a certain command does not indicate a problem.
4041For example, you may use the @code{mkdir} command to ensure that a
4042directory exists.  If the directory already exists, @code{mkdir} will
4043report an error, but you probably want @code{make} to continue regardless.
4044
4045@cindex @code{-} (in commands)
4046To ignore errors in a command line, write a @samp{-} at the beginning of
4047the line's text (after the initial tab).  The @samp{-} is discarded before
4048the command is passed to the shell for execution.
4049
4050For example,
4051
4052@example
4053@group
4054clean:
4055        -rm -f *.o
4056@end group
4057@end example
4058@cindex @code{rm} (shell command)
4059
4060@noindent
4061This causes @code{rm} to continue even if it is unable to remove a file.
4062
4063@cindex @code{-i}
4064@cindex @code{--ignore-errors}
4065@findex .IGNORE
4066When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
4067flag, errors are ignored in all commands of all rules.  A rule in the
4068makefile for the special target @code{.IGNORE} has the same effect, if
4069there are no prerequisites.  These ways of ignoring errors are obsolete
4070because @samp{-} is more flexible.
4071
4072When errors are to be ignored, because of either a @samp{-} or the
4073@samp{-i} flag, @code{make} treats an error return just like success,
4074except that it prints out a message that tells you the status code
4075the command exited with, and says that the error has been ignored.
4076
4077When an error happens that @code{make} has not been told to ignore,
4078it implies that the current target cannot be correctly remade, and neither
4079can any other that depends on it either directly or indirectly.  No further
4080commands will be executed for these targets, since their preconditions
4081have not been achieved.
4082
4083
4084@cindex @code{-k}
4085@cindex @code{--keep-going}
4086Normally @code{make} gives up immediately in this circumstance, returning a
4087nonzero status.  However, if the @samp{-k} or @samp{--keep-going}
4088flag is specified, @code{make}
4089continues to consider the other prerequisites of the pending targets,
4090remaking them if necessary, before it gives up and returns nonzero status.
4091For example, after an error in compiling one object file, @samp{make -k}
4092will continue compiling other object files even though it already knows
4093that linking them will be impossible.  @xref{Options Summary, ,Summary of Options}.
4094
4095The usual behavior assumes that your purpose is to get the specified
4096targets up to date; once @code{make} learns that this is impossible, it
4097might as well report the failure immediately.  The @samp{-k} option says
4098that the real purpose is to test as many of the changes made in the
4099program as possible, perhaps to find several independent problems so
4100that you can correct them all before the next attempt to compile.  This
4101is why Emacs' @code{compile} command passes the @samp{-k} flag by
4102default.
4103@cindex Emacs (@code{M-x compile})
4104
4105@findex .DELETE_ON_ERROR
4106@cindex deletion of target files
4107@cindex removal of target files
4108@cindex target, deleting on error
4109Usually when a command fails, if it has changed the target file at all,
4110the file is corrupted and cannot be used---or at least it is not
4111completely updated.  Yet the file's time stamp says that it is now up to
4112date, so the next time @code{make} runs, it will not try to update that
4113file.  The situation is just the same as when the command is killed by a
4114signal; @pxref{Interrupts}.  So generally the right thing to do is to
4115delete the target file if the command fails after beginning to change
4116the file.  @code{make} will do this if @code{.DELETE_ON_ERROR} appears
4117as a target.  This is almost always what you want @code{make} to do, but
4118it is not historical practice; so for compatibility, you must explicitly
4119request it.
4120
4121@node Interrupts, Recursion, Errors, Commands
4122@section Interrupting or Killing @code{make}
4123@cindex interrupt
4124@cindex signal
4125@cindex deletion of target files
4126@cindex removal of target files
4127@cindex target, deleting on interrupt
4128@cindex killing (interruption)
4129
4130If @code{make} gets a fatal signal while a command is executing, it may
4131delete the target file that the command was supposed to update.  This is
4132done if the target file's last-modification time has changed since
4133@code{make} first checked it.
4134
4135The purpose of deleting the target is to make sure that it is remade from
4136scratch when @code{make} is next run.  Why is this?  Suppose you type
4137@kbd{Ctrl-c} while a compiler is running, and it has begun to write an
4138object file @file{foo.o}.  The @kbd{Ctrl-c} kills the compiler, resulting
4139in an incomplete file whose last-modification time is newer than the source
4140file @file{foo.c}.  But @code{make} also receives the @kbd{Ctrl-c} signal
4141and deletes this incomplete file.  If @code{make} did not do this, the next
4142invocation of @code{make} would think that @file{foo.o} did not require
4143updating---resulting in a strange error message from the linker when it
4144tries to link an object file half of which is missing.
4145
4146@findex .PRECIOUS
4147You can prevent the deletion of a target file in this way by making the
4148special target @code{.PRECIOUS} depend on it.  Before remaking a target,
4149@code{make} checks to see whether it appears on the prerequisites of
4150@code{.PRECIOUS}, and thereby decides whether the target should be deleted
4151if a signal happens.  Some reasons why you might do this are that the
4152target is updated in some atomic fashion, or exists only to record a
4153modification-time (its contents do not matter), or must exist at all
4154times to prevent other sorts of trouble.
4155
4156@node Recursion, Sequences, Interrupts, Commands
4157@section Recursive Use of @code{make}
4158@cindex recursion
4159@cindex subdirectories, recursion for
4160
4161Recursive use of @code{make} means using @code{make} as a command in a
4162makefile.  This technique is useful when you want separate makefiles for
4163various subsystems that compose a larger system.  For example, suppose you
4164have a subdirectory @file{subdir} which has its own makefile, and you would
4165like the containing directory's makefile to run @code{make} on the
4166subdirectory.  You can do it by writing this:
4167
4168@example
4169subsystem:
4170        cd subdir && $(MAKE)
4171@end example
4172
4173@noindent
4174or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
4175
4176@example
4177subsystem:
4178        $(MAKE) -C subdir
4179@end example
4180@cindex @code{-C}
4181@cindex @code{--directory}
4182
4183You can write recursive @code{make} commands just by copying this example,
4184but there are many things to know about how they work and why, and about
4185how the sub-@code{make} relates to the top-level @code{make}.  You may
4186also find it useful to declare targets that invoke recursive
4187@code{make} commands as @samp{.PHONY} (for more discussion on when
4188this is useful, see @ref{Phony Targets}).
4189
4190@vindex @code{CURDIR}
4191For your convenience, when GNU @code{make} starts (after it has
4192processed any @code{-C} options) it sets the variable @code{CURDIR} to
4193the pathname of the current working directory.  This value is never
4194touched by @code{make} again: in particular note that if you include
4195files from other directories the value of @code{CURDIR} does not
4196change.  The value has the same precedence it would have if it were
4197set in the makefile (by default, an environment variable @code{CURDIR}
4198will not override this value).  Note that setting this variable has no
4199impact on the operation of @code{make} (it does not cause @code{make}
4200to change its working directory, for example).
4201
4202@menu
4203* MAKE Variable::               The special effects of using @samp{$(MAKE)}.
4204* Variables/Recursion::         How to communicate variables to a sub-@code{make}.
4205* Options/Recursion::           How to communicate options to a sub-@code{make}.
4206* -w Option::                   How the @samp{-w} or @samp{--print-directory} option
4207                                  helps debug use of recursive @code{make} commands.
4208@end menu
4209
4210@node MAKE Variable, Variables/Recursion, Recursion, Recursion
4211@subsection How the @code{MAKE} Variable Works
4212@vindex MAKE
4213@cindex recursion, and @code{MAKE} variable
4214
4215Recursive @code{make} commands should always use the variable @code{MAKE},
4216not the explicit command name @samp{make}, as shown here:
4217
4218@example
4219@group
4220subsystem:
4221        cd subdir && $(MAKE)
4222@end group
4223@end example
4224
4225The value of this variable is the file name with which @code{make} was
4226invoked.  If this file name was @file{/bin/make}, then the command executed
4227is @samp{cd subdir && /bin/make}.  If you use a special version of
4228@code{make} to run the top-level makefile, the same special version will be
4229executed for recursive invocations.
4230@cindex @code{cd} (shell command)
4231
4232@cindex +, and commands
4233As a special feature, using the variable @code{MAKE} in the commands of
4234a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
4235(@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
4236Using the @code{MAKE} variable has the same effect as using a @samp{+}
4237character at the beginning of the command line.  @xref{Instead of
4238Execution, ,Instead of Executing the Commands}.  This special feature
4239is only enabled if the @code{MAKE} variable appears directly in the
4240command script: it does not apply if the @code{MAKE} variable is
4241referenced through expansion of another variable.  In the latter case
4242you must use the @samp{+} token to get these special effects.@refill
4243
4244Consider the command @samp{make -t} in the above example.  (The
4245@samp{-t} option marks targets as up to date without actually running
4246any commands; see @ref{Instead of Execution}.)  Following the usual
4247definition of @samp{-t}, a @samp{make -t} command in the example would
4248create a file named @file{subsystem} and do nothing else.  What you
4249really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would
4250require executing the command, and @samp{-t} says not to execute
4251commands.@refill
4252@cindex @code{-t}, and recursion
4253@cindex recursion, and @code{-t}
4254@cindex @code{--touch}, and recursion
4255
4256The special feature makes this do what you want: whenever a command
4257line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
4258@samp{-n} and @samp{-q} do not apply to that line.  Command lines
4259containing @code{MAKE} are executed normally despite the presence of a
4260flag that causes most commands not to be run.  The usual
4261@code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
4262(@pxref{Options/Recursion, ,Communicating Options to a
4263Sub-@code{make}}), so your request to touch the files, or print the
4264commands, is propagated to the subsystem.@refill
4265
4266@node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
4267@subsection Communicating Variables to a Sub-@code{make}
4268@cindex sub-@code{make}
4269@cindex environment, and recursion
4270@cindex exporting variables
4271@cindex variables, environment
4272@cindex variables, exporting
4273@cindex recursion, and environment
4274@cindex recursion, and variables
4275
4276Variable values of the top-level @code{make} can be passed to the
4277sub-@code{make} through the environment by explicit request.  These
4278variables are defined in the sub-@code{make} as defaults, but do not
4279override what is specified in the makefile used by the sub-@code{make}
4280makefile unless you use the @samp{-e} switch (@pxref{Options Summary,
4281,Summary of Options}).@refill
4282
4283To pass down, or @dfn{export}, a variable, @code{make} adds the variable
4284and its value to the environment for running each command.  The
4285sub-@code{make}, in turn, uses the environment to initialize its table
4286of variable values.  @xref{Environment, ,Variables from the
4287Environment}.
4288
4289Except by explicit request, @code{make} exports a variable only if it
4290is either defined in the environment initially or set on the command
4291line, and if its name consists only of letters, numbers, and underscores.
4292Some shells cannot cope with environment variable names consisting of
4293characters other than letters, numbers, and underscores.
4294
4295@cindex SHELL, exported value
4296The value of the @code{make} variable @code{SHELL} is not exported.
4297Instead, the value of the @code{SHELL} variable from the invoking
4298environment is passed to the sub-@code{make}.  You can force
4299@code{make} to export its value for @code{SHELL} by using the
4300@code{export} directive, described below.  @xref{Choosing the Shell}.
4301
4302The special variable @code{MAKEFLAGS} is always exported (unless you
4303unexport it).  @code{MAKEFILES} is exported if you set it to anything.
4304
4305@code{make} automatically passes down variable values that were defined
4306on the command line, by putting them in the @code{MAKEFLAGS} variable.
4307@iftex
4308See the next section.
4309@end iftex
4310@ifnottex
4311@xref{Options/Recursion}.
4312@end ifnottex
4313
4314Variables are @emph{not} normally passed down if they were created by
4315default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
4316Implicit Rules}).  The sub-@code{make} will define these for
4317itself.@refill
4318
4319@findex export
4320If you want to export specific variables to a sub-@code{make}, use the
4321@code{export} directive, like this:
4322
4323@example
4324export @var{variable} @dots{}
4325@end example
4326
4327@noindent
4328@findex unexport
4329If you want to @emph{prevent} a variable from being exported, use the
4330@code{unexport} directive, like this:
4331
4332@example
4333unexport @var{variable} @dots{}
4334@end example
4335
4336@noindent
4337In both of these forms, the arguments to @code{export} and
4338@code{unexport} are expanded, and so could be variables or functions
4339which expand to a (list of) variable names to be (un)exported.
4340
4341As a convenience, you can define a variable and export it at the same
4342time by doing:
4343
4344@example
4345export @var{variable} = value
4346@end example
4347
4348@noindent
4349has the same result as:
4350
4351@example
4352@var{variable} = value
4353export @var{variable}
4354@end example
4355
4356@noindent
4357and
4358
4359@example
4360export @var{variable} := value
4361@end example
4362
4363@noindent
4364has the same result as:
4365
4366@example
4367@var{variable} := value
4368export @var{variable}
4369@end example
4370
4371Likewise,
4372
4373@example
4374export @var{variable} += value
4375@end example
4376
4377@noindent
4378is just like:
4379
4380@example
4381@var{variable} += value
4382export @var{variable}
4383@end example
4384
4385@noindent
4386@xref{Appending, ,Appending More Text to Variables}.
4387
4388You may notice that the @code{export} and @code{unexport} directives
4389work in @code{make} in the same way they work in the shell, @code{sh}.
4390
4391If you want all variables to be exported by default, you can use
4392@code{export} by itself:
4393
4394@example
4395export
4396@end example
4397
4398@noindent
4399This tells @code{make} that variables which are not explicitly mentioned
4400in an @code{export} or @code{unexport} directive should be exported.
4401Any variable given in an @code{unexport} directive will still @emph{not}
4402be exported.  If you use @code{export} by itself to export variables by
4403default, variables whose names contain characters other than
4404alphanumerics and underscores will not be exported unless specifically
4405mentioned in an @code{export} directive.@refill
4406
4407@findex .EXPORT_ALL_VARIABLES
4408The behavior elicited by an @code{export} directive by itself was the
4409default in older versions of GNU @code{make}.  If your makefiles depend
4410on this behavior and you want to be compatible with old versions of
4411@code{make}, you can write a rule for the special target
4412@code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
4413This will be ignored by old @code{make}s, while the @code{export}
4414directive will cause a syntax error.@refill
4415@cindex compatibility in exporting
4416
4417Likewise, you can use @code{unexport} by itself to tell @code{make}
4418@emph{not} to export variables by default.  Since this is the default
4419behavior, you would only need to do this if @code{export} had been used
4420by itself earlier (in an included makefile, perhaps).  You
4421@strong{cannot} use @code{export} and @code{unexport} by themselves to
4422have variables exported for some commands and not for others.  The last
4423@code{export} or @code{unexport} directive that appears by itself
4424determines the behavior for the entire run of @code{make}.@refill
4425
4426@vindex MAKELEVEL
4427@cindex recursion, level of
4428As a special feature, the variable @code{MAKELEVEL} is changed when it
4429is passed down from level to level.  This variable's value is a string
4430which is the depth of the level as a decimal number.  The value is
4431@samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
4432@samp{2} for a sub-sub-@code{make}, and so on.  The incrementation
4433happens when @code{make} sets up the environment for a command.@refill
4434
4435The main use of @code{MAKELEVEL} is to test it in a conditional
4436directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
4437way you can write a makefile that behaves one way if run recursively and
4438another way if run directly by you.@refill
4439
4440@vindex MAKEFILES
4441You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
4442commands to use additional makefiles.  The value of @code{MAKEFILES} is
4443a whitespace-separated list of file names.  This variable, if defined in
4444the outer-level makefile, is passed down through the environment; then
4445it serves as a list of extra makefiles for the sub-@code{make} to read
4446before the usual or specified ones.  @xref{MAKEFILES Variable, ,The
4447Variable @code{MAKEFILES}}.@refill
4448
4449@node Options/Recursion, -w Option, Variables/Recursion, Recursion
4450@subsection Communicating Options to a Sub-@code{make}
4451@cindex options, and recursion
4452@cindex recursion, and options
4453
4454@vindex MAKEFLAGS
4455Flags such as @samp{-s} and @samp{-k} are passed automatically to the
4456sub-@code{make} through the variable @code{MAKEFLAGS}.  This variable is
4457set up automatically by @code{make} to contain the flag letters that
4458@code{make} received.  Thus, if you do @w{@samp{make -ks}} then
4459@code{MAKEFLAGS} gets the value @samp{ks}.@refill
4460
4461As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
4462in its environment.  In response, it takes the flags from that value and
4463processes them as if they had been given as arguments.
4464@xref{Options Summary, ,Summary of Options}.
4465
4466@cindex command line variable definitions, and recursion
4467@cindex variables, command line, and recursion
4468@cindex recursion, and command line variable definitions
4469Likewise variables defined on the command line are passed to the
4470sub-@code{make} through @code{MAKEFLAGS}.  Words in the value of
4471@code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable
4472definitions just as if they appeared on the command line.
4473@xref{Overriding, ,Overriding Variables}.
4474
4475@cindex @code{-C}, and recursion
4476@cindex @code{-f}, and recursion
4477@cindex @code{-o}, and recursion
4478@cindex @code{-W}, and recursion
4479@cindex @code{--directory}, and recursion
4480@cindex @code{--file}, and recursion
4481@cindex @code{--old-file}, and recursion
4482@cindex @code{--assume-old}, and recursion
4483@cindex @code{--assume-new}, and recursion
4484@cindex @code{--new-file}, and recursion
4485@cindex recursion, and @code{-C}
4486@cindex recursion, and @code{-f}
4487@cindex recursion, and @code{-o}
4488@cindex recursion, and @code{-W}
4489The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put
4490into @code{MAKEFLAGS}; these options are not passed down.@refill
4491
4492@cindex @code{-j}, and recursion
4493@cindex @code{--jobs}, and recursion
4494@cindex recursion, and @code{-j}
4495@cindex job slots, and recursion
4496The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
4497If you set it to some numeric value @samp{N} and your operating system
4498supports it (most any UNIX system will; others typically won't), the
4499parent @code{make} and all the sub-@code{make}s will communicate to
4500ensure that there are only @samp{N} jobs running at the same time
4501between them all.  Note that any job that is marked recursive
4502(@pxref{Instead of Execution, ,Instead of Executing the Commands})
4503doesn't count against the total jobs (otherwise we could get @samp{N}
4504sub-@code{make}s running and have no slots left over for any real work!)
4505
4506If your operating system doesn't support the above communication, then
4507@samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you
4508specified.  This is because if the @w{@samp{-j}} option were passed down
4509to sub-@code{make}s, you would get many more jobs running in parallel
4510than you asked for.  If you give @samp{-j} with no numeric argument,
4511meaning to run as many jobs as possible in parallel, this is passed
4512down, since multiple infinities are no more than one.@refill
4513
4514If you do not want to pass the other flags down, you must change the
4515value of @code{MAKEFLAGS}, like this:
4516
4517@example
4518subsystem:
4519        cd subdir && $(MAKE) MAKEFLAGS=
4520@end example
4521
4522@vindex MAKEOVERRIDES
4523The command line variable definitions really appear in the variable
4524@code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this
4525variable.  If you do want to pass flags down normally, but don't want to
4526pass down the command line variable definitions, you can reset
4527@code{MAKEOVERRIDES} to empty, like this:
4528
4529@example
4530MAKEOVERRIDES =
4531@end example
4532
4533@noindent
4534@cindex Arg list too long
4535@cindex E2BIG
4536This is not usually useful to do.  However, some systems have a small
4537fixed limit on the size of the environment, and putting so much
4538information into the value of @code{MAKEFLAGS} can exceed it.  If you
4539see the error message @samp{Arg list too long}, this may be the problem.
4540@findex .POSIX
4541@cindex POSIX.2
4542(For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does
4543not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears
4544in the makefile.  You probably do not care about this.)
4545
4546@vindex MFLAGS
4547A similar variable @code{MFLAGS} exists also, for historical
4548compatibility.  It has the same value as @code{MAKEFLAGS} except that it
4549does not contain the command line variable definitions, and it always
4550begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a
4551hyphen only when it begins with an option that has no single-letter
4552version, such as @samp{--warn-undefined-variables}).  @code{MFLAGS} was
4553traditionally used explicitly in the recursive @code{make} command, like
4554this:
4555
4556@example
4557subsystem:
4558        cd subdir && $(MAKE) $(MFLAGS)
4559@end example
4560
4561@noindent
4562but now @code{MAKEFLAGS} makes this usage redundant.  If you want your
4563makefiles to be compatible with old @code{make} programs, use this
4564technique; it will work fine with more modern @code{make} versions too.
4565
4566@cindex setting options from environment
4567@cindex options, setting from environment
4568@cindex setting options in makefiles
4569@cindex options, setting in makefiles
4570The @code{MAKEFLAGS} variable can also be useful if you want to have
4571certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
4572Options}), set each time you run @code{make}.  You simply put a value for
4573@code{MAKEFLAGS} in your environment.  You can also set @code{MAKEFLAGS} in
4574a makefile, to specify additional flags that should also be in effect for
4575that makefile.  (Note that you cannot use @code{MFLAGS} this way.  That
4576variable is set only for compatibility; @code{make} does not interpret a
4577value you set for it in any way.)
4578
4579When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
4580environment or from a makefile), it first prepends a hyphen if the value
4581does not already begin with one.  Then it chops the value into words
4582separated by blanks, and parses these words as if they were options given
4583on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
4584@samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
4585is no error for an invalid option).
4586
4587If you do put @code{MAKEFLAGS} in your environment, you should be sure not
4588to include any options that will drastically affect the actions of
4589@code{make} and undermine the purpose of makefiles and of @code{make}
4590itself.  For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
4591put in one of these variables, could have disastrous consequences and would
4592certainly have at least surprising and probably annoying effects.@refill
4593
4594@node -w Option,  , Options/Recursion, Recursion
4595@subsection The @samp{--print-directory} Option
4596@cindex directories, printing them
4597@cindex printing directories
4598@cindex recursion, and printing directories
4599
4600If you use several levels of recursive @code{make} invocations, the
4601@samp{-w} or @w{@samp{--print-directory}} option can make the output a
4602lot easier to understand by showing each directory as @code{make}
4603starts processing it and as @code{make} finishes processing it.  For
4604example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
4605@code{make} will print a line of the form:@refill
4606
4607@example
4608make: Entering directory `/u/gnu/make'.
4609@end example
4610
4611@noindent
4612before doing anything else, and a line of the form:
4613
4614@example
4615make: Leaving directory `/u/gnu/make'.
4616@end example
4617
4618@noindent
4619when processing is completed.
4620
4621@cindex @code{-C}, and @code{-w}
4622@cindex @code{--directory}, and @code{--print-directory}
4623@cindex recursion, and @code{-w}
4624@cindex @code{-w}, and @code{-C}
4625@cindex @code{-w}, and recursion
4626@cindex @code{--print-directory}, and @code{--directory}
4627@cindex @code{--print-directory}, and recursion
4628@cindex @code{--no-print-directory}
4629@cindex @code{--print-directory}, disabling
4630@cindex @code{-w}, disabling
4631Normally, you do not need to specify this option because @samp{make}
4632does it for you: @samp{-w} is turned on automatically when you use the
4633@samp{-C} option, and in sub-@code{make}s.  @code{make} will not
4634automatically turn on @samp{-w} if you also use @samp{-s}, which says to
4635be silent, or if you use @samp{--no-print-directory} to explicitly
4636disable it.
4637
4638@node Sequences, Empty Commands, Recursion, Commands
4639@section Defining Canned Command Sequences
4640@cindex sequences of commands
4641@cindex commands, sequences of
4642
4643When the same sequence of commands is useful in making various targets, you
4644can define it as a canned sequence with the @code{define} directive, and
4645refer to the canned sequence from the rules for those targets.  The canned
4646sequence is actually a variable, so the name must not conflict with other
4647variable names.
4648
4649Here is an example of defining a canned sequence of commands:
4650
4651@example
4652define run-yacc
4653yacc $(firstword $^)
4654mv y.tab.c $@@
4655endef
4656@end example
4657@cindex @code{yacc}
4658
4659@noindent
4660Here @code{run-yacc} is the name of the variable being defined;
4661@code{endef} marks the end of the definition; the lines in between are the
4662commands.  The @code{define} directive does not expand variable references
4663and function calls in the canned sequence; the @samp{$} characters,
4664parentheses, variable names, and so on, all become part of the value of the
4665variable you are defining.
4666@xref{Defining, ,Defining Variables Verbatim},
4667for a complete explanation of @code{define}.
4668
4669The first command in this example runs Yacc on the first prerequisite of
4670whichever rule uses the canned sequence.  The output file from Yacc is
4671always named @file{y.tab.c}.  The second command moves the output to the
4672rule's target file name.
4673
4674To use the canned sequence, substitute the variable into the commands of a
4675rule.  You can substitute it like any other variable
4676(@pxref{Reference, ,Basics of Variable References}).
4677Because variables defined by @code{define} are recursively expanded
4678variables, all the variable references you wrote inside the @code{define}
4679are expanded now.  For example:
4680
4681@example
4682foo.c : foo.y
4683        $(run-yacc)
4684@end example
4685
4686@noindent
4687@samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
4688@code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
4689
4690This is a realistic example, but this particular one is not needed in
4691practice because @code{make} has an implicit rule to figure out these
4692commands based on the file names involved
4693(@pxref{Implicit Rules, ,Using Implicit Rules}).
4694
4695@cindex @@, and @code{define}
4696@cindex -, and @code{define}
4697@cindex +, and @code{define}
4698In command execution, each line of a canned sequence is treated just as
4699if the line appeared on its own in the rule, preceded by a tab.  In
4700particular, @code{make} invokes a separate subshell for each line.  You
4701can use the special prefix characters that affect command lines
4702(@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
4703@xref{Commands, ,Writing the Commands in Rules}.
4704For example, using this canned sequence:
4705
4706@example
4707define frobnicate
4708@@echo "frobnicating target $@@"
4709frob-step-1 $< -o $@@-step-1
4710frob-step-2 $@@-step-1 -o $@@
4711endef
4712@end example
4713
4714@noindent
4715@code{make} will not echo the first line, the @code{echo} command.
4716But it @emph{will} echo the following two command lines.
4717
4718On the other hand, prefix characters on the command line that refers to
4719a canned sequence apply to every line in the sequence.  So the rule:
4720
4721@example
4722frob.out: frob.in
4723        @@$(frobnicate)
4724@end example
4725
4726@noindent
4727does not echo @emph{any} commands.
4728(@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.)
4729
4730@node Empty Commands,  , Sequences, Commands
4731@section Using Empty Commands
4732@cindex empty commands
4733@cindex commands, empty
4734
4735It is sometimes useful to define commands which do nothing.  This is done
4736simply by giving a command that consists of nothing but whitespace.  For
4737example:
4738
4739@example
4740target: ;
4741@end example
4742
4743@noindent
4744defines an empty command string for @file{target}.  You could also use a
4745line beginning with a tab character to define an empty command string,
4746but this would be confusing because such a line looks empty.
4747
4748@findex .DEFAULT@r{, and empty commands}
4749You may be wondering why you would want to define a command string that
4750does nothing.  The only reason this is useful is to prevent a target
4751from getting implicit commands (from implicit rules or the
4752@code{.DEFAULT} special target; @pxref{Implicit Rules} and
4753@pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
4754
4755@c !!! another reason is for canonical stamp files:
4756@ignore
4757@example
4758foo: stamp-foo ;
4759stamp-foo: foo.in
4760        create foo frm foo.in
4761        touch $@
4762@end example
4763@end ignore
4764
4765You may be inclined to define empty command strings for targets that are
4766not actual files, but only exist so that their prerequisites can be
4767remade.  However, this is not the best way to do that, because the
4768prerequisites may not be remade properly if the target file actually does exist.
4769@xref{Phony Targets, ,Phony Targets}, for a better way to do this.
4770
4771@node Using Variables, Conditionals, Commands, Top
4772@chapter How to Use Variables
4773@cindex variable
4774@cindex value
4775@cindex recursive variable expansion
4776@cindex simple variable expansion
4777
4778A @dfn{variable} is a name defined in a makefile to represent a string
4779of text, called the variable's @dfn{value}.  These values are
4780substituted by explicit request into targets, prerequisites, commands,
4781and other parts of the makefile.  (In some other versions of @code{make},
4782variables are called @dfn{macros}.)
4783@cindex macro
4784
4785Variables and functions in all parts of a makefile are expanded when
4786read, except for the shell commands in rules, the right-hand sides of
4787variable definitions using @samp{=}, and the bodies of variable
4788definitions using the @code{define} directive.@refill
4789
4790Variables can represent lists of file names, options to pass to compilers,
4791programs to run, directories to look in for source files, directories to
4792write output in, or anything else you can imagine.
4793
4794A variable name may be any sequence of characters not containing @samp{:},
4795@samp{#}, @samp{=}, or leading or trailing whitespace.  However,
4796variable names containing characters other than letters, numbers, and
4797underscores should be avoided, as they may be given special meanings in the
4798future, and with some shells they cannot be passed through the environment to a
4799sub-@code{make}
4800(@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
4801
4802Variable names are case-sensitive.  The names @samp{foo}, @samp{FOO},
4803and @samp{Foo} all refer to different variables.
4804
4805It is traditional to use upper case letters in variable names, but we
4806recommend using lower case letters for variable names that serve internal
4807purposes in the makefile, and reserving upper case for parameters that
4808control implicit rules or for parameters that the user should override with
4809command options (@pxref{Overriding, ,Overriding Variables}).
4810
4811A few variables have names that are a single punctuation character or
4812just a few characters.  These are the @dfn{automatic variables}, and
4813they have particular specialized uses.  @xref{Automatic Variables}.
4814
4815@menu
4816* Reference::                   How to use the value of a variable.
4817* Flavors::                     Variables come in two flavors.
4818* Advanced::                    Advanced features for referencing a variable.
4819* Values::                      All the ways variables get their values.
4820* Setting::                     How to set a variable in the makefile.
4821* Appending::                   How to append more text to the old value
4822                                  of a variable.
4823* Override Directive::          How to set a variable in the makefile even if
4824                                  the user has set it with a command argument.
4825* Defining::                    An alternate way to set a variable
4826                                  to a verbatim string.
4827* Environment::                 Variable values can come from the environment.
4828* Target-specific::             Variable values can be defined on a per-target
4829                                  basis.
4830* Pattern-specific::            Target-specific variable values can be applied
4831                                  to a group of targets that match a pattern.
4832@end menu
4833
4834@node Reference, Flavors, Using Variables, Using Variables
4835@section Basics of Variable References
4836@cindex variables, how to reference
4837@cindex reference to variables
4838@cindex @code{$}, in variable reference
4839@cindex dollar sign (@code{$}), in variable reference
4840
4841To substitute a variable's value, write a dollar sign followed by the name
4842of the variable in parentheses or braces: either @samp{$(foo)} or
4843@samp{$@{foo@}} is a valid reference to the variable @code{foo}.  This
4844special significance of @samp{$} is why you must write @samp{$$} to have
4845the effect of a single dollar sign in a file name or command.
4846
4847Variable references can be used in any context: targets, prerequisites,
4848commands, most directives, and new variable values.  Here is an
4849example of a common case, where a variable holds the names of all the
4850object files in a program:
4851
4852@example
4853@group
4854objects = program.o foo.o utils.o
4855program : $(objects)
4856        cc -o program $(objects)
4857
4858$(objects) : defs.h
4859@end group
4860@end example
4861
4862Variable references work by strict textual substitution.  Thus, the rule
4863
4864@example
4865@group
4866foo = c
4867prog.o : prog.$(foo)
4868        $(foo)$(foo) -$(foo) prog.$(foo)
4869@end group
4870@end example
4871
4872@noindent
4873could be used to compile a C program @file{prog.c}.  Since spaces before
4874the variable value are ignored in variable assignments, the value of
4875@code{foo} is precisely @samp{c}.  (Don't actually write your makefiles
4876this way!)
4877
4878A dollar sign followed by a character other than a dollar sign,
4879open-parenthesis or open-brace treats that single character as the
4880variable name.  Thus, you could reference the variable @code{x} with
4881@samp{$x}.  However, this practice is strongly discouraged, except in
4882the case of the automatic variables (@pxref{Automatic Variables}).
4883
4884@node Flavors, Advanced, Reference, Using Variables
4885@section The Two Flavors of Variables
4886@cindex flavors of variables
4887@cindex recursive variable expansion
4888@cindex variables, flavors
4889@cindex recursively expanded variables
4890@cindex variables, recursively expanded
4891
4892There are two ways that a variable in GNU @code{make} can have a value;
4893we call them the two @dfn{flavors} of variables.  The two flavors are
4894distinguished in how they are defined and in what they do when expanded.
4895
4896@cindex =
4897The first flavor of variable is a @dfn{recursively expanded} variable.
4898Variables of this sort are defined by lines using @samp{=}
4899(@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
4900(@pxref{Defining, ,Defining Variables Verbatim}).  The value you specify
4901is installed verbatim; if it contains references to other variables,
4902these references are expanded whenever this variable is substituted (in
4903the course of expanding some other string).  When this happens, it is
4904called @dfn{recursive expansion}.@refill
4905
4906For example,
4907
4908@example
4909foo = $(bar)
4910bar = $(ugh)
4911ugh = Huh?
4912
4913all:;echo $(foo)
4914@end example
4915
4916@noindent
4917will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
4918expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
4919
4920This flavor of variable is the only sort supported by other versions of
4921@code{make}.  It has its advantages and its disadvantages.  An advantage
4922(most would say) is that:
4923
4924@example
4925CFLAGS = $(include_dirs) -O
4926include_dirs = -Ifoo -Ibar
4927@end example
4928
4929@noindent
4930will do what was intended: when @samp{CFLAGS} is expanded in a command,
4931it will expand to @samp{-Ifoo -Ibar -O}.  A major disadvantage is that you
4932cannot append something on the end of a variable, as in
4933
4934@example
4935CFLAGS = $(CFLAGS) -O
4936@end example
4937
4938@noindent
4939because it will cause an infinite loop in the variable expansion.
4940(Actually @code{make} detects the infinite loop and reports an error.)
4941@cindex loops in variable expansion
4942@cindex variables, loops in expansion
4943
4944Another disadvantage is that any functions
4945(@pxref{Functions, ,Functions for Transforming Text})
4946referenced in the definition will be executed every time the variable is
4947expanded.  This makes @code{make} run slower; worse, it causes the
4948@code{wildcard} and @code{shell} functions to give unpredictable results
4949because you cannot easily control when they are called, or even how many
4950times.
4951
4952To avoid all the problems and inconveniences of recursively expanded
4953variables, there is another flavor: simply expanded variables.
4954
4955@cindex simply expanded variables
4956@cindex variables, simply expanded
4957@cindex :=
4958@dfn{Simply expanded variables} are defined by lines using @samp{:=}
4959(@pxref{Setting, ,Setting Variables}).
4960The value of a simply expanded variable is scanned
4961once and for all, expanding any references to other variables and
4962functions, when the variable is defined.  The actual value of the simply
4963expanded variable is the result of expanding the text that you write.
4964It does not contain any references to other variables; it contains their
4965values @emph{as of the time this variable was defined}.  Therefore,
4966
4967@example
4968x := foo
4969y := $(x) bar
4970x := later
4971@end example
4972
4973@noindent
4974is equivalent to
4975
4976@example
4977y := foo bar
4978x := later
4979@end example
4980
4981When a simply expanded variable is referenced, its value is substituted
4982verbatim.
4983
4984Here is a somewhat more complicated example, illustrating the use of
4985@samp{:=} in conjunction with the @code{shell} function.
4986(@xref{Shell Function, , The @code{shell} Function}.)  This example
4987also shows use of the variable @code{MAKELEVEL}, which is changed
4988when it is passed down from level to level.
4989(@xref{Variables/Recursion, , Communicating Variables to a
4990Sub-@code{make}}, for information about @code{MAKELEVEL}.)
4991
4992@vindex MAKELEVEL
4993@vindex MAKE
4994@example
4995@group
4996ifeq (0,$@{MAKELEVEL@})
4997whoami    := $(shell whoami)
4998host-type := $(shell arch)
4999MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
5000endif
5001@end group
5002@end example
5003
5004@noindent
5005An advantage of this use of @samp{:=} is that a typical
5006`descend into a directory' command then looks like this:
5007
5008@example
5009@group
5010$@{subdirs@}:
5011        $@{MAKE@} -C $@@ all
5012@end group
5013@end example
5014
5015Simply expanded variables generally make complicated makefile programming
5016more predictable because they work like variables in most programming
5017languages.  They allow you to redefine a variable using its own value (or
5018its value processed in some way by one of the expansion functions) and to
5019use the expansion functions much more efficiently
5020(@pxref{Functions, ,Functions for Transforming Text}).
5021
5022@cindex spaces, in variable values
5023@cindex whitespace, in variable values
5024@cindex variables, spaces in values
5025You can also use them to introduce controlled leading whitespace into
5026variable values.  Leading whitespace characters are discarded from your
5027input before substitution of variable references and function calls;
5028this means you can include leading spaces in a variable value by
5029protecting them with variable references, like this:
5030
5031@example
5032nullstring :=
5033space := $(nullstring) # end of the line
5034@end example
5035
5036@noindent
5037Here the value of the variable @code{space} is precisely one space.  The
5038comment @w{@samp{# end of the line}} is included here just for clarity.
5039Since trailing space characters are @emph{not} stripped from variable
5040values, just a space at the end of the line would have the same effect
5041(but be rather hard to read).  If you put whitespace at the end of a
5042variable value, it is a good idea to put a comment like that at the end
5043of the line to make your intent clear.  Conversely, if you do @emph{not}
5044want any whitespace characters at the end of your variable value, you
5045must remember not to put a random comment on the end of the line after
5046some whitespace, such as this:
5047
5048@example
5049dir := /foo/bar    # directory to put the frobs in
5050@end example
5051
5052@noindent
5053Here the value of the variable @code{dir} is @w{@samp{/foo/bar    }}
5054(with four trailing spaces), which was probably not the intention.
5055(Imagine something like @w{@samp{$(dir)/file}} with this definition!)
5056
5057@cindex conditional variable assignment
5058@cindex variables, conditional assignment
5059@cindex ?=
5060There is another assignment operator for variables, @samp{?=}.  This
5061is called a conditional variable assignment operator, because it only
5062has an effect if the variable is not yet defined.  This statement:
5063
5064@example
5065FOO ?= bar
5066@end example
5067
5068@noindent
5069is exactly equivalent to this
5070(@pxref{Origin Function, ,The @code{origin} Function}):
5071
5072@example
5073ifeq ($(origin FOO), undefined)
5074  FOO = bar
5075endif
5076@end example
5077
5078Note that a variable set to an empty value is still defined, so
5079@samp{?=} will not set that variable.
5080
5081@node Advanced, Values, Flavors, Using Variables
5082@section Advanced Features for Reference to Variables
5083@cindex reference to variables
5084
5085This section describes some advanced features you can use to reference
5086variables in more flexible ways.
5087
5088@menu
5089* Substitution Refs::           Referencing a variable with
5090                                  substitutions on the value.
5091* Computed Names::              Computing the name of the variable to refer to.
5092@end menu
5093
5094@node Substitution Refs, Computed Names, Advanced, Advanced
5095@subsection Substitution References
5096@cindex modified variable reference
5097@cindex substitution variable reference
5098@cindex variables, modified reference
5099@cindex variables, substitution reference
5100
5101@cindex variables, substituting suffix in
5102@cindex suffix, substituting in variables
5103A @dfn{substitution reference} substitutes the value of a variable with
5104alterations that you specify.  It has the form
5105@samp{$(@var{var}:@var{a}=@var{b})} (or
5106@samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
5107of the variable @var{var}, replace every @var{a} at the end of a word with
5108@var{b} in that value, and substitute the resulting string.
5109
5110When we say ``at the end of a word'', we mean that @var{a} must appear
5111either followed by whitespace or at the end of the value in order to be
5112replaced; other occurrences of @var{a} in the value are unaltered.  For
5113example:@refill
5114
5115@example
5116foo := a.o b.o c.o
5117bar := $(foo:.o=.c)
5118@end example
5119
5120@noindent
5121sets @samp{bar} to @samp{a.c b.c c.c}.  @xref{Setting, ,Setting Variables}.
5122
5123A substitution reference is actually an abbreviation for use of the
5124@code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}).  We provide
5125substitution references as well as @code{patsubst} for compatibility with
5126other implementations of @code{make}.
5127
5128@findex patsubst
5129Another type of substitution reference lets you use the full power of
5130the @code{patsubst} function.  It has the same form
5131@samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
5132@var{a} must contain a single @samp{%} character.  This case is
5133equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
5134@xref{Text Functions, ,Functions for String Substitution and Analysis},
5135for a description of the @code{patsubst} function.@refill
5136
5137@example
5138@group
5139@exdent For example:
5140
5141foo := a.o b.o c.o
5142bar := $(foo:%.o=%.c)
5143@end group
5144@end example
5145
5146@noindent
5147sets @samp{bar} to @samp{a.c b.c c.c}.
5148
5149@node Computed Names,  , Substitution Refs, Advanced
5150@subsection Computed Variable Names
5151@cindex nested variable reference
5152@cindex computed variable name
5153@cindex variables, computed names
5154@cindex variables, nested references
5155@cindex variables, @samp{$} in name
5156@cindex @code{$}, in variable name
5157@cindex dollar sign (@code{$}), in variable name
5158
5159Computed variable names are a complicated concept needed only for
5160sophisticated makefile programming.  For most purposes you need not
5161consider them, except to know that making a variable with a dollar sign
5162in its name might have strange results.  However, if you are the type
5163that wants to understand everything, or you are actually interested in
5164what they do, read on.
5165
5166Variables may be referenced inside the name of a variable.  This is
5167called a @dfn{computed variable name} or a @dfn{nested variable
5168reference}.  For example,
5169
5170@example
5171x = y
5172y = z
5173a := $($(x))
5174@end example
5175
5176@noindent
5177defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
5178to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
5179to @samp{z}.  Here the name of the variable to reference is not stated
5180explicitly; it is computed by expansion of @samp{$(x)}.  The reference
5181@samp{$(x)} here is nested within the outer variable reference.
5182
5183The previous example shows two levels of nesting, but any number of levels
5184is possible.  For example, here are three levels:
5185
5186@example
5187x = y
5188y = z
5189z = u
5190a := $($($(x)))
5191@end example
5192
5193@noindent
5194Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
5195expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
5196@samp{$(z)}, which becomes @samp{u}.
5197
5198References to recursively-expanded variables within a variable name are
5199reexpanded in the usual fashion.  For example:
5200
5201@example
5202x = $(y)
5203y = z
5204z = Hello
5205a := $($(x))
5206@end example
5207
5208@noindent
5209defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
5210which becomes @samp{$(z)} which becomes @samp{Hello}.
5211
5212Nested variable references can also contain modified references and
5213function invocations (@pxref{Functions, ,Functions for Transforming Text}),
5214just like any other reference.
5215For example, using the @code{subst} function
5216(@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
5217
5218@example
5219@group
5220x = variable1
5221variable2 := Hello
5222y = $(subst 1,2,$(x))
5223z = y
5224a := $($($(z)))
5225@end group
5226@end example
5227
5228@noindent
5229eventually defines @code{a} as @samp{Hello}.  It is doubtful that anyone
5230would ever want to write a nested reference as convoluted as this one, but
5231it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
5232@samp{$($(subst 1,2,$(x)))}.  This gets the value @samp{variable1} from
5233@code{x} and changes it by substitution to @samp{variable2}, so that the
5234entire string becomes @samp{$(variable2)}, a simple variable reference
5235whose value is @samp{Hello}.@refill
5236
5237A computed variable name need not consist entirely of a single variable
5238reference.  It can contain several variable references, as well as some
5239invariant text.  For example,
5240
5241@example
5242@group
5243a_dirs := dira dirb
52441_dirs := dir1 dir2
5245@end group
5246
5247@group
5248a_files := filea fileb
52491_files := file1 file2
5250@end group
5251
5252@group
5253ifeq "$(use_a)" "yes"
5254a1 := a
5255else
5256a1 := 1
5257endif
5258@end group
5259
5260@group
5261ifeq "$(use_dirs)" "yes"
5262df := dirs
5263else
5264df := files
5265endif
5266
5267dirs := $($(a1)_$(df))
5268@end group
5269@end example
5270
5271@noindent
5272will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
5273@code{a_files} or @code{1_files} depending on the settings of @code{use_a}
5274and @code{use_dirs}.@refill
5275
5276Computed variable names can also be used in substitution references:
5277
5278@example
5279@group
5280a_objects := a.o b.o c.o
52811_objects := 1.o 2.o 3.o
5282
5283sources := $($(a1)_objects:.o=.c)
5284@end group
5285@end example
5286
5287@noindent
5288defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
5289depending on the value of @code{a1}.
5290
5291The only restriction on this sort of use of nested variable references
5292is that they cannot specify part of the name of a function to be called.
5293This is because the test for a recognized function name is done before
5294the expansion of nested references.  For example,
5295
5296@example
5297@group
5298ifdef do_sort
5299func := sort
5300else
5301func := strip
5302endif
5303@end group
5304
5305@group
5306bar := a d b g q c
5307@end group
5308
5309@group
5310foo := $($(func) $(bar))
5311@end group
5312@end example
5313
5314@noindent
5315attempts to give @samp{foo} the value of the variable @samp{sort a d b g
5316q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
5317as the argument to either the @code{sort} or the @code{strip} function.
5318This restriction could be removed in the future if that change is shown
5319to be a good idea.
5320
5321You can also use computed variable names in the left-hand side of a
5322variable assignment, or in a @code{define} directive, as in:
5323
5324@example
5325dir = foo
5326$(dir)_sources := $(wildcard $(dir)/*.c)
5327define $(dir)_print
5328lpr $($(dir)_sources)
5329endef
5330@end example
5331
5332@noindent
5333This example defines the variables @samp{dir}, @samp{foo_sources}, and
5334@samp{foo_print}.
5335
5336Note that @dfn{nested variable references} are quite different from
5337@dfn{recursively expanded variables}
5338(@pxref{Flavors, ,The Two Flavors of Variables}), though both are
5339used together in complex ways when doing makefile programming.@refill
5340
5341@node Values, Setting, Advanced, Using Variables
5342@section How Variables Get Their Values
5343@cindex variables, how they get their values
5344@cindex value, how a variable gets it
5345
5346Variables can get values in several different ways:
5347
5348@itemize @bullet
5349@item
5350You can specify an overriding value when you run @code{make}.
5351@xref{Overriding, ,Overriding Variables}.
5352
5353@item
5354You can specify a value in the makefile, either
5355with an assignment (@pxref{Setting, ,Setting Variables}) or with a
5356verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
5357
5358@item
5359Variables in the environment become @code{make} variables.
5360@xref{Environment, ,Variables from the Environment}.
5361
5362@item
5363Several @dfn{automatic} variables are given new values for each rule.
5364Each of these has a single conventional use.
5365@xref{Automatic Variables}.
5366
5367@item
5368Several variables have constant initial values.
5369@xref{Implicit Variables, ,Variables Used by Implicit Rules}.
5370@end itemize
5371
5372@node Setting, Appending, Values, Using Variables
5373@section Setting Variables
5374@cindex setting variables
5375@cindex variables, setting
5376@cindex =
5377@cindex :=
5378@cindex ?=
5379
5380To set a variable from the makefile, write a line starting with the
5381variable name followed by @samp{=} or @samp{:=}.  Whatever follows the
5382@samp{=} or @samp{:=} on the line becomes the value.  For example,
5383
5384@example
5385objects = main.o foo.o bar.o utils.o
5386@end example
5387
5388@noindent
5389defines a variable named @code{objects}.  Whitespace around the variable
5390name and immediately after the @samp{=} is ignored.
5391
5392Variables defined with @samp{=} are @dfn{recursively expanded} variables.
5393Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
5394definitions can contain variable references which will be expanded before
5395the definition is made.  @xref{Flavors, ,The Two Flavors of Variables}.
5396
5397The variable name may contain function and variable references, which
5398are expanded when the line is read to find the actual variable name to use.
5399
5400There is no limit on the length of the value of a variable except the
5401amount of swapping space on the computer.  When a variable definition is
5402long, it is a good idea to break it into several lines by inserting
5403backslash-newline at convenient places in the definition.  This will not
5404affect the functioning of @code{make}, but it will make the makefile easier
5405to read.
5406
5407Most variable names are considered to have the empty string as a value if
5408you have never set them.  Several variables have built-in initial values
5409that are not empty, but you can set them in the usual ways
5410(@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
5411Several special variables are set
5412automatically to a new value for each rule; these are called the
5413@dfn{automatic} variables (@pxref{Automatic Variables}).
5414
5415If you'd like a variable to be set to a value only if it's not already
5416set, then you can use the shorthand operator @samp{?=} instead of
5417@samp{=}.  These two settings of the variable @samp{FOO} are identical
5418(@pxref{Origin Function, ,The @code{origin} Function}):
5419
5420@example
5421FOO ?= bar
5422@end example
5423
5424@noindent
5425and
5426
5427@example
5428ifeq ($(origin FOO), undefined)
5429FOO = bar
5430endif
5431@end example
5432
5433@node Appending, Override Directive, Setting, Using Variables
5434@section Appending More Text to Variables
5435@cindex +=
5436@cindex appending to variables
5437@cindex variables, appending to
5438
5439Often it is useful to add more text to the value of a variable already defined.
5440You do this with a line containing @samp{+=}, like this:
5441
5442@example
5443objects += another.o
5444@end example
5445
5446@noindent
5447This takes the value of the variable @code{objects}, and adds the text
5448@samp{another.o} to it (preceded by a single space).  Thus:
5449
5450@example
5451objects = main.o foo.o bar.o utils.o
5452objects += another.o
5453@end example
5454
5455@noindent
5456sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
5457
5458Using @samp{+=} is similar to:
5459
5460@example
5461objects = main.o foo.o bar.o utils.o
5462objects := $(objects) another.o
5463@end example
5464
5465@noindent
5466but differs in ways that become important when you use more complex values.
5467
5468When the variable in question has not been defined before, @samp{+=}
5469acts just like normal @samp{=}: it defines a recursively-expanded
5470variable.  However, when there @emph{is} a previous definition, exactly
5471what @samp{+=} does depends on what flavor of variable you defined
5472originally.  @xref{Flavors, ,The Two Flavors of Variables}, for an
5473explanation of the two flavors of variables.
5474
5475When you add to a variable's value with @samp{+=}, @code{make} acts
5476essentially as if you had included the extra text in the initial
5477definition of the variable.  If you defined it first with @samp{:=},
5478making it a simply-expanded variable, @samp{+=} adds to that
5479simply-expanded definition, and expands the new text before appending it
5480to the old value just as @samp{:=} does
5481(see @ref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
5482In fact,
5483
5484@example
5485variable := value
5486variable += more
5487@end example
5488
5489@noindent
5490is exactly equivalent to:
5491
5492@noindent
5493@example
5494variable := value
5495variable := $(variable) more
5496@end example
5497
5498On the other hand, when you use @samp{+=} with a variable that you defined
5499first to be recursively-expanded using plain @samp{=}, @code{make} does
5500something a bit different.  Recall that when you define a
5501recursively-expanded variable, @code{make} does not expand the value you set
5502for variable and function references immediately.  Instead it stores the text
5503verbatim, and saves these variable and function references to be expanded
5504later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
5505of Variables}).  When you use @samp{+=} on a recursively-expanded variable,
5506it is this unexpanded text to which @code{make} appends the new text you
5507specify.
5508
5509@example
5510@group
5511variable = value
5512variable += more
5513@end group
5514@end example
5515
5516@noindent
5517is roughly equivalent to:
5518
5519@example
5520@group
5521temp = value
5522variable = $(temp) more
5523@end group
5524@end example
5525
5526@noindent
5527except that of course it never defines a variable called @code{temp}.
5528The importance of this comes when the variable's old value contains
5529variable references.  Take this common example:
5530
5531@example
5532CFLAGS = $(includes) -O
5533@dots{}
5534CFLAGS += -pg # enable profiling
5535@end example
5536
5537@noindent
5538The first line defines the @code{CFLAGS} variable with a reference to another
5539variable, @code{includes}.  (@code{CFLAGS} is used by the rules for C
5540compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
5541Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
5542variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
5543@code{make} processes the definition of @code{CFLAGS}.  Thus, @code{includes}
5544need not be defined yet for its value to take effect.  It only has to be
5545defined before any reference to @code{CFLAGS}.  If we tried to append to the
5546value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
5547
5548@example
5549CFLAGS := $(CFLAGS) -pg # enable profiling
5550@end example
5551
5552@noindent
5553This is pretty close, but not quite what we want.  Using @samp{:=}
5554redefines @code{CFLAGS} as a simply-expanded variable; this means
5555@code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
5556variable.  If @code{includes} is not yet defined, we get @w{@samp{ -O
5557-pg}}, and a later definition of @code{includes} will have no effect.
5558Conversely, by using @samp{+=} we set @code{CFLAGS} to the
5559@emph{unexpanded} value @w{@samp{$(includes) -O -pg}}.  Thus we preserve
5560the reference to @code{includes}, so if that variable gets defined at
5561any later point, a reference like @samp{$(CFLAGS)} still uses its
5562value.
5563
5564@node Override Directive, Defining, Appending, Using Variables
5565@section The @code{override} Directive
5566@findex override
5567@cindex overriding with @code{override}
5568@cindex variables, overriding
5569
5570If a variable has been set with a command argument
5571(@pxref{Overriding, ,Overriding Variables}),
5572then ordinary assignments in the makefile are ignored.  If you want to set
5573the variable in the makefile even though it was set with a command
5574argument, you can use an @code{override} directive, which is a line that
5575looks like this:@refill
5576
5577@example
5578override @var{variable} = @var{value}
5579@end example
5580
5581@noindent
5582or
5583
5584@example
5585override @var{variable} := @var{value}
5586@end example
5587
5588To append more text to a variable defined on the command line, use:
5589
5590@example
5591override @var{variable} += @var{more text}
5592@end example
5593
5594@noindent
5595@xref{Appending, ,Appending More Text to Variables}.
5596
5597The @code{override} directive was not invented for escalation in the war
5598between makefiles and command arguments.  It was invented so you can alter
5599and add to values that the user specifies with command arguments.
5600
5601For example, suppose you always want the @samp{-g} switch when you run the
5602C compiler, but you would like to allow the user to specify the other
5603switches with a command argument just as usual.  You could use this
5604@code{override} directive:
5605
5606@example
5607override CFLAGS += -g
5608@end example
5609
5610You can also use @code{override} directives with @code{define} directives.
5611This is done as you might expect:
5612
5613@example
5614override define foo
5615bar
5616endef
5617@end example
5618
5619@noindent
5620@iftex
5621See the next section for information about @code{define}.
5622@end iftex
5623@ifnottex
5624@xref{Defining, ,Defining Variables Verbatim}.
5625@end ifnottex
5626
5627@node Defining, Environment, Override Directive, Using Variables
5628@section Defining Variables Verbatim
5629@findex define
5630@findex endef
5631@cindex verbatim variable definition
5632@cindex defining variables verbatim
5633@cindex variables, defining verbatim
5634
5635Another way to set the value of a variable is to use the @code{define}
5636directive.  This directive has an unusual syntax which allows newline
5637characters to be included in the value, which is convenient for defining
5638both canned sequences of commands
5639(@pxref{Sequences, ,Defining Canned Command Sequences}), and also
5640sections of makefile syntax to use with @code{eval} (@pxref{Eval Function}).
5641
5642The @code{define} directive is followed on the same line by the name of the
5643variable and nothing more.  The value to give the variable appears on the
5644following lines.  The end of the value is marked by a line containing just
5645the word @code{endef}.  Aside from this difference in syntax, @code{define}
5646works just like @samp{=}: it creates a recursively-expanded variable
5647(@pxref{Flavors, ,The Two Flavors of Variables}).
5648The variable name may contain function and variable references, which
5649are expanded when the directive is read to find the actual variable name
5650to use.
5651
5652You may nest @code{define} directives: @code{make} will keep track of
5653nested directives and report an error if they are not all properly
5654closed with @code{endef}.  Note that lines beginning with tab
5655characters are considered part of a command script, so any
5656@code{define} or @code{endef} strings appearing on such a line will
5657not be considered @code{make} operators.
5658
5659@example
5660define two-lines
5661echo foo
5662echo $(bar)
5663endef
5664@end example
5665
5666The value in an ordinary assignment cannot contain a newline; but the
5667newlines that separate the lines of the value in a @code{define} become
5668part of the variable's value (except for the final newline which precedes
5669the @code{endef} and is not considered part of the value).@refill
5670
5671@need 800
5672When used in a command script, the previous example is functionally
5673equivalent to this:
5674
5675@example
5676two-lines = echo foo; echo $(bar)
5677@end example
5678
5679@noindent
5680since two commands separated by semicolon behave much like two separate
5681shell commands.  However, note that using two separate lines means
5682@code{make} will invoke the shell twice, running an independent subshell
5683for each line.  @xref{Execution, ,Command Execution}.
5684
5685If you want variable definitions made with @code{define} to take
5686precedence over command-line variable definitions, you can use the
5687@code{override} directive together with @code{define}:
5688
5689@example
5690override define two-lines
5691foo
5692$(bar)
5693endef
5694@end example
5695
5696@noindent
5697@xref{Override Directive, ,The @code{override} Directive}.
5698
5699@node Environment, Target-specific, Defining, Using Variables
5700@section Variables from the Environment
5701
5702@cindex variables, environment
5703@cindex environment
5704Variables in @code{make} can come from the environment in which
5705@code{make} is run.  Every environment variable that @code{make} sees
5706when it starts up is transformed into a @code{make} variable with the
5707same name and value.  However, an explicit assignment in the makefile,
5708or with a command argument, overrides the environment.  (If the
5709@samp{-e} flag is specified, then values from the environment override
5710assignments in the makefile.  @xref{Options Summary, ,Summary of
5711Options}.  But this is not recommended practice.)
5712
5713Thus, by setting the variable @code{CFLAGS} in your environment, you can
5714cause all C compilations in most makefiles to use the compiler switches you
5715prefer.  This is safe for variables with standard or conventional meanings
5716because you know that no makefile will use them for other things.  (Note
5717this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
5718and therefore are not affected by the value in the environment.)
5719
5720When @code{make} runs a command script, variables defined in the
5721makefile are placed into the environment of that command.  This allows
5722you to pass values to sub-@code{make} invocations (@pxref{Recursion,
5723,Recursive Use of @code{make}}).  By default, only variables that came
5724from the environment or the command line are passed to recursive
5725invocations.  You can use the @code{export} directive to pass other
5726variables.  @xref{Variables/Recursion, , Communicating Variables to a
5727Sub-@code{make}}, for full details.
5728
5729Other use of variables from the environment is not recommended.  It is not
5730wise for makefiles to depend for their functioning on environment variables
5731set up outside their control, since this would cause different users to get
5732different results from the same makefile.  This is against the whole
5733purpose of most makefiles.
5734
5735@cindex SHELL, import from environment
5736Such problems would be especially likely with the variable
5737@code{SHELL}, which is normally present in the environment to specify
5738the user's choice of interactive shell.  It would be very undesirable
5739for this choice to affect @code{make}; so, @code{make} handles the
5740@code{SHELL} environment variable in a special way; see @ref{Choosing
5741the Shell}.@refill
5742
5743@node Target-specific, Pattern-specific, Environment, Using Variables
5744@section Target-specific Variable Values
5745@cindex target-specific variables
5746@cindex variables, target-specific
5747
5748Variable values in @code{make} are usually global; that is, they are the
5749same regardless of where they are evaluated (unless they're reset, of
5750course).  One exception to that is automatic variables
5751(@pxref{Automatic Variables}).
5752
5753The other exception is @dfn{target-specific variable values}.  This
5754feature allows you to define different values for the same variable,
5755based on the target that @code{make} is currently building.  As with
5756automatic variables, these values are only available within the context
5757of a target's command script (and in other target-specific assignments).
5758
5759Set a target-specific variable value like this:
5760
5761@example
5762@var{target} @dots{} : @var{variable-assignment}
5763@end example
5764
5765@noindent
5766or like this:
5767
5768@example
5769@var{target} @dots{} : override @var{variable-assignment}
5770@end example
5771
5772@noindent
5773or like this:
5774
5775@example
5776@var{target} @dots{} : export @var{variable-assignment}
5777@end example
5778
5779Multiple @var{target} values create a target-specific variable value for
5780each member of the target list individually.
5781
5782The @var{variable-assignment} can be any valid form of assignment;
5783recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or
5784conditional (@samp{?=}).  All variables that appear within the
5785@var{variable-assignment} are evaluated within the context of the
5786target: thus, any previously-defined target-specific variable values
5787will be in effect.  Note that this variable is actually distinct from
5788any ``global'' value: the two variables do not have to have the same
5789flavor (recursive vs.@: static).
5790
5791Target-specific variables have the same priority as any other makefile
5792variable.  Variables provided on the command-line (and in the
5793environment if the @samp{-e} option is in force) will take precedence.
5794Specifying the @code{override} directive will allow the target-specific
5795variable value to be preferred.
5796
5797There is one more special feature of target-specific variables: when
5798you define a target-specific variable that variable value is also in
5799effect for all prerequisites of this target, and all their
5800prerequisites, etc.@: (unless those prerequisites override that variable
5801with their own target-specific variable value).  So, for example, a
5802statement like this:
5803
5804@example
5805prog : CFLAGS = -g
5806prog : prog.o foo.o bar.o
5807@end example
5808
5809@noindent
5810will set @code{CFLAGS} to @samp{-g} in the command script for
5811@file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the
5812command scripts that create @file{prog.o}, @file{foo.o}, and
5813@file{bar.o}, and any command scripts which create their
5814prerequisites.
5815
5816Be aware that a given prerequisite will only be built once per
5817invocation of make, at most.  If the same file is a prerequisite of
5818multiple targets, and each of those targets has a different value for
5819the same target-specific variable, then the first target to be built
5820will cause that prerequisite to be built and the prerequisite will
5821inherit the target-specific value from the first target.  It will
5822ignore the target-specific values from any other targets.
5823
5824@node Pattern-specific,  , Target-specific, Using Variables
5825@section Pattern-specific Variable Values
5826@cindex pattern-specific variables
5827@cindex variables, pattern-specific
5828
5829In addition to target-specific variable values
5830(@pxref{Target-specific, ,Target-specific Variable Values}), GNU
5831@code{make} supports pattern-specific variable values.  In this form,
5832the variable is defined for any target that matches the pattern
5833specified.  If a target matches more than one pattern, all the
5834matching pattern-specific variables are interpreted in the order in
5835which they were defined in the makefile, and collected together into
5836one set.  Variables defined in this way are searched after any
5837target-specific variables defined explicitly for that target, and
5838before target-specific variables defined for the parent target.
5839
5840Set a pattern-specific variable value like this:
5841
5842@example
5843@var{pattern} @dots{} : @var{variable-assignment}
5844@end example
5845
5846@noindent
5847or like this:
5848
5849@example
5850@var{pattern} @dots{} : override @var{variable-assignment}
5851@end example
5852
5853@noindent
5854where @var{pattern} is a %-pattern.  As with target-specific variable
5855values, multiple @var{pattern} values create a pattern-specific variable
5856value for each pattern individually.  The @var{variable-assignment} can
5857be any valid form of assignment.  Any command-line variable setting will
5858take precedence, unless @code{override} is specified.
5859
5860For example:
5861
5862@example
5863%.o : CFLAGS = -O
5864@end example
5865
5866@noindent
5867will assign @code{CFLAGS} the value of @samp{-O} for all targets
5868matching the pattern @code{%.o}.
5869
5870@node Conditionals, Functions, Using Variables, Top
5871@chapter Conditional Parts of Makefiles
5872
5873@cindex conditionals
5874A @dfn{conditional} causes part of a makefile to be obeyed or ignored
5875depending on the values of variables.  Conditionals can compare the
5876value of one variable to another, or the value of a variable to
5877a constant string.  Conditionals control what @code{make} actually
5878``sees'' in the makefile, so they @emph{cannot} be used to control shell
5879commands at the time of execution.@refill
5880
5881@menu
5882* Conditional Example::         Example of a conditional
5883* Conditional Syntax::          The syntax of conditionals.
5884* Testing Flags::               Conditionals that test flags.
5885@end menu
5886
5887@node Conditional Example, Conditional Syntax, Conditionals, Conditionals
5888@section Example of a Conditional
5889
5890The following example of a conditional tells @code{make} to use one set
5891of libraries if the @code{CC} variable is @samp{gcc}, and a different
5892set of libraries otherwise.  It works by controlling which of two
5893command lines will be used as the command for a rule.  The result is
5894that @samp{CC=gcc} as an argument to @code{make} changes not only which
5895compiler is used but also which libraries are linked.
5896
5897@example
5898libs_for_gcc = -lgnu
5899normal_libs =
5900
5901foo: $(objects)
5902ifeq ($(CC),gcc)
5903        $(CC) -o foo $(objects) $(libs_for_gcc)
5904else
5905        $(CC) -o foo $(objects) $(normal_libs)
5906endif
5907@end example
5908
5909This conditional uses three directives: one @code{ifeq}, one @code{else}
5910and one @code{endif}.
5911
5912The @code{ifeq} directive begins the conditional, and specifies the
5913condition.  It contains two arguments, separated by a comma and surrounded
5914by parentheses.  Variable substitution is performed on both arguments and
5915then they are compared.  The lines of the makefile following the
5916@code{ifeq} are obeyed if the two arguments match; otherwise they are
5917ignored.
5918
5919The @code{else} directive causes the following lines to be obeyed if the
5920previous conditional failed.  In the example above, this means that the
5921second alternative linking command is used whenever the first alternative
5922is not used.  It is optional to have an @code{else} in a conditional.
5923
5924The @code{endif} directive ends the conditional.  Every conditional must
5925end with an @code{endif}.  Unconditional makefile text follows.
5926
5927As this example illustrates, conditionals work at the textual level:
5928the lines of the conditional are treated as part of the makefile, or
5929ignored, according to the condition.  This is why the larger syntactic
5930units of the makefile, such as rules, may cross the beginning or the
5931end of the conditional.
5932
5933When the variable @code{CC} has the value @samp{gcc}, the above example has
5934this effect:
5935
5936@example
5937foo: $(objects)
5938        $(CC) -o foo $(objects) $(libs_for_gcc)
5939@end example
5940
5941@noindent
5942When the variable @code{CC} has any other value, the effect is this:
5943
5944@example
5945foo: $(objects)
5946        $(CC) -o foo $(objects) $(normal_libs)
5947@end example
5948
5949Equivalent results can be obtained in another way by conditionalizing a
5950variable assignment and then using the variable unconditionally:
5951
5952@example
5953libs_for_gcc = -lgnu
5954normal_libs =
5955
5956ifeq ($(CC),gcc)
5957  libs=$(libs_for_gcc)
5958else
5959  libs=$(normal_libs)
5960endif
5961
5962foo: $(objects)
5963        $(CC) -o foo $(objects) $(libs)
5964@end example
5965
5966@node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
5967@section Syntax of Conditionals
5968@findex ifdef
5969@findex ifeq
5970@findex ifndef
5971@findex ifneq
5972@findex else
5973@findex endif
5974
5975The syntax of a simple conditional with no @code{else} is as follows:
5976
5977@example
5978@var{conditional-directive}
5979@var{text-if-true}
5980endif
5981@end example
5982
5983@noindent
5984The @var{text-if-true} may be any lines of text, to be considered as part
5985of the makefile if the condition is true.  If the condition is false, no
5986text is used instead.
5987
5988The syntax of a complex conditional is as follows:
5989
5990@example
5991@var{conditional-directive}
5992@var{text-if-true}
5993else
5994@var{text-if-false}
5995endif
5996@end example
5997
5998or:
5999
6000@example
6001@var{conditional-directive}
6002@var{text-if-one-is-true}
6003else @var{conditional-directive}
6004@var{text-if-true}
6005else
6006@var{text-if-false}
6007endif
6008@end example
6009
6010@noindent
6011There can be as many ``@code{else} @var{conditional-directive}''
6012clauses as necessary.  Once a given condition is true,
6013@var{text-if-true} is used and no other clause is used; if no
6014condition is true then @var{text-if-false} is used.  The
6015@var{text-if-true} and @var{text-if-false} can be any number of lines
6016of text.
6017
6018The syntax of the @var{conditional-directive} is the same whether the
6019conditional is simple or complex; after an @code{else} or not.  There
6020are four different directives that test different conditions.  Here is
6021a table of them:
6022
6023@table @code
6024@item ifeq (@var{arg1}, @var{arg2})
6025@itemx ifeq '@var{arg1}' '@var{arg2}'
6026@itemx ifeq "@var{arg1}" "@var{arg2}"
6027@itemx ifeq "@var{arg1}" '@var{arg2}'
6028@itemx ifeq '@var{arg1}' "@var{arg2}"
6029Expand all variable references in @var{arg1} and @var{arg2} and
6030compare them.  If they are identical, the @var{text-if-true} is
6031effective; otherwise, the @var{text-if-false}, if any, is effective.
6032
6033Often you want to test if a variable has a non-empty value.  When the
6034value results from complex expansions of variables and functions,
6035expansions you would consider empty may actually contain whitespace
6036characters and thus are not seen as empty.  However, you can use the
6037@code{strip} function (@pxref{Text Functions}) to avoid interpreting
6038whitespace as a non-empty value.  For example:
6039
6040@example
6041@group
6042ifeq ($(strip $(foo)),)
6043@var{text-if-empty}
6044endif
6045@end group
6046@end example
6047
6048@noindent
6049will evaluate @var{text-if-empty} even if the expansion of
6050@code{$(foo)} contains whitespace characters.
6051
6052@item ifneq (@var{arg1}, @var{arg2})
6053@itemx ifneq '@var{arg1}' '@var{arg2}'
6054@itemx ifneq "@var{arg1}" "@var{arg2}"
6055@itemx ifneq "@var{arg1}" '@var{arg2}'
6056@itemx ifneq '@var{arg1}' "@var{arg2}"
6057Expand all variable references in @var{arg1} and @var{arg2} and
6058compare them.  If they are different, the @var{text-if-true} is
6059effective; otherwise, the @var{text-if-false}, if any, is effective.
6060
6061@item ifdef @var{variable-name}
6062The @code{ifdef} form takes the @emph{name} of a variable as its
6063argument, not a reference to a variable.  The value of that variable
6064has a non-empty value, the @var{text-if-true} is effective; otherwise,
6065the @var{text-if-false}, if any, is effective.  Variables that have
6066never been defined have an empty value.  The text @var{variable-name}
6067is expanded, so it could be a variable or function that expands
6068to the name of a variable.  For example:
6069
6070@example
6071bar = true
6072foo = bar
6073ifdef $(foo)
6074frobozz = yes
6075endif
6076@end example
6077
6078The variable reference @code{$(foo)} is expanded, yielding @code{bar},
6079which is considered to be the name of a variable.  The variable
6080@code{bar} is not expanded, but its value is examined to determine if
6081it is non-empty.
6082
6083Note that @code{ifdef} only tests whether a variable has a value.  It
6084does not expand the variable to see if that value is nonempty.
6085Consequently, tests using @code{ifdef} return true for all definitions
6086except those like @code{foo =}.  To test for an empty value, use
6087@w{@code{ifeq ($(foo),)}}.  For example,
6088
6089@example
6090bar =
6091foo = $(bar)
6092ifdef foo
6093frobozz = yes
6094else
6095frobozz = no
6096endif
6097@end example
6098
6099@noindent
6100sets @samp{frobozz} to @samp{yes}, while:
6101
6102@example
6103foo =
6104ifdef foo
6105frobozz = yes
6106else
6107frobozz = no
6108endif
6109@end example
6110
6111@noindent
6112sets @samp{frobozz} to @samp{no}.
6113
6114@item ifndef @var{variable-name}
6115If the variable @var{variable-name} has an empty value, the
6116@var{text-if-true} is effective; otherwise, the @var{text-if-false},
6117if any, is effective.  The rules for expansion and testing of
6118@var{variable-name} are identical to the @code{ifdef} directive.
6119@end table
6120
6121Extra spaces are allowed and ignored at the beginning of the conditional
6122directive line, but a tab is not allowed.  (If the line begins with a tab,
6123it will be considered a command for a rule.)  Aside from this, extra spaces
6124or tabs may be inserted with no effect anywhere except within the directive
6125name or within an argument.  A comment starting with @samp{#} may appear at
6126the end of the line.
6127
6128The other two directives that play a part in a conditional are @code{else}
6129and @code{endif}.  Each of these directives is written as one word, with no
6130arguments.  Extra spaces are allowed and ignored at the beginning of the
6131line, and spaces or tabs at the end.  A comment starting with @samp{#} may
6132appear at the end of the line.
6133
6134Conditionals affect which lines of the makefile @code{make} uses.  If
6135the condition is true, @code{make} reads the lines of the
6136@var{text-if-true} as part of the makefile; if the condition is false,
6137@code{make} ignores those lines completely.  It follows that syntactic
6138units of the makefile, such as rules, may safely be split across the
6139beginning or the end of the conditional.@refill
6140
6141@code{make} evaluates conditionals when it reads a makefile.
6142Consequently, you cannot use automatic variables in the tests of
6143conditionals because they are not defined until commands are run
6144(@pxref{Automatic Variables}).
6145
6146To prevent intolerable confusion, it is not permitted to start a
6147conditional in one makefile and end it in another.  However, you may
6148write an @code{include} directive within a conditional, provided you do
6149not attempt to terminate the conditional inside the included file.
6150
6151@node Testing Flags,  , Conditional Syntax, Conditionals
6152@section Conditionals that Test Flags
6153
6154You can write a conditional that tests @code{make} command flags such as
6155@samp{-t} by using the variable @code{MAKEFLAGS} together with the
6156@code{findstring} function
6157(@pxref{Text Functions, , Functions for String Substitution and Analysis}).
6158This is useful when @code{touch} is not enough to make a file appear up
6159to date.
6160
6161The @code{findstring} function determines whether one string appears as a
6162substring of another.  If you want to test for the @samp{-t} flag,
6163use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
6164the other.
6165
6166For example, here is how to arrange to use @samp{ranlib -t} to finish
6167marking an archive file up to date:
6168
6169@example
6170archive.a: @dots{}
6171ifneq (,$(findstring t,$(MAKEFLAGS)))
6172        +touch archive.a
6173        +ranlib -t archive.a
6174else
6175        ranlib archive.a
6176endif
6177@end example
6178
6179@noindent
6180The @samp{+} prefix marks those command lines as ``recursive'' so
6181that they will be executed despite use of the @samp{-t} flag.
6182@xref{Recursion, ,Recursive Use of @code{make}}.
6183
6184@node Functions, Running, Conditionals, Top
6185@chapter Functions for Transforming Text
6186@cindex functions
6187
6188@dfn{Functions} allow you to do text processing in the makefile to compute
6189the files to operate on or the commands to use.  You use a function in a
6190@dfn{function call}, where you give the name of the function and some text
6191(the @dfn{arguments}) for the function to operate on.  The result of the
6192function's processing is substituted into the makefile at the point of the
6193call, just as a variable might be substituted.
6194
6195@menu
6196* Syntax of Functions::         How to write a function call.
6197* Text Functions::              General-purpose text manipulation functions.
6198* File Name Functions::         Functions for manipulating file names.
6199* Conditional Functions::       Functions that implement conditions.
6200* Foreach Function::            Repeat some text with controlled variation.
6201* Call Function::               Expand a user-defined function.
6202* Value Function::              Return the un-expanded value of a variable.
6203* Eval Function::               Evaluate the arguments as makefile syntax.
6204* Origin Function::             Find where a variable got its value.
6205* Flavor Function::             Find out the flavor of a variable.
6206* Shell Function::              Substitute the output of a shell command.
6207* Make Control Functions::      Functions that control how make runs.
6208@end menu
6209
6210@node Syntax of Functions, Text Functions, Functions, Functions
6211@section Function Call Syntax
6212@cindex @code{$}, in function call
6213@cindex dollar sign (@code{$}), in function call
6214@cindex arguments of functions
6215@cindex functions, syntax of
6216
6217A function call resembles a variable reference.  It looks like this:
6218
6219@example
6220$(@var{function} @var{arguments})
6221@end example
6222
6223@noindent
6224or like this:
6225
6226@example
6227$@{@var{function} @var{arguments}@}
6228@end example
6229
6230Here @var{function} is a function name; one of a short list of names
6231that are part of @code{make}.  You can also essentially create your own
6232functions by using the @code{call} builtin function.
6233
6234The @var{arguments} are the arguments of the function.  They are
6235separated from the function name by one or more spaces or tabs, and if
6236there is more than one argument, then they are separated by commas.
6237Such whitespace and commas are not part of an argument's value.  The
6238delimiters which you use to surround the function call, whether
6239parentheses or braces, can appear in an argument only in matching pairs;
6240the other kind of delimiters may appear singly.  If the arguments
6241themselves contain other function calls or variable references, it is
6242wisest to use the same kind of delimiters for all the references; write
6243@w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}.  This
6244is because it is clearer, and because only one type of delimiter is
6245matched to find the end of the reference.
6246
6247The text written for each argument is processed by substitution of
6248variables and function calls to produce the argument value, which
6249is the text on which the function acts.  The substitution is done in the
6250order in which the arguments appear.
6251
6252Commas and unmatched parentheses or braces cannot appear in the text of an
6253argument as written; leading spaces cannot appear in the text of the first
6254argument as written.  These characters can be put into the argument value
6255by variable substitution.  First define variables @code{comma} and
6256@code{space} whose values are isolated comma and space characters, then
6257substitute these variables where such characters are wanted, like this:
6258
6259@example
6260@group
6261comma:= ,
6262empty:=
6263space:= $(empty) $(empty)
6264foo:= a b c
6265bar:= $(subst $(space),$(comma),$(foo))
6266# @r{bar is now `a,b,c'.}
6267@end group
6268@end example
6269
6270@noindent
6271Here the @code{subst} function replaces each space with a comma, through
6272the value of @code{foo}, and substitutes the result.
6273
6274@node Text Functions, File Name Functions, Syntax of Functions, Functions
6275@section Functions for String Substitution and Analysis
6276@cindex functions, for text
6277
6278Here are some functions that operate on strings:
6279
6280@table @code
6281@item $(subst @var{from},@var{to},@var{text})
6282@findex subst
6283Performs a textual replacement on the text @var{text}: each occurrence
6284of @var{from} is replaced by @var{to}.  The result is substituted for
6285the function call.  For example,
6286
6287@example
6288$(subst ee,EE,feet on the street)
6289@end example
6290
6291substitutes the string @samp{fEEt on the strEEt}.
6292
6293@item $(patsubst @var{pattern},@var{replacement},@var{text})
6294@findex patsubst
6295Finds whitespace-separated words in @var{text} that match
6296@var{pattern} and replaces them with @var{replacement}.  Here
6297@var{pattern} may contain a @samp{%} which acts as a wildcard,
6298matching any number of any characters within a word.  If
6299@var{replacement} also contains a @samp{%}, the @samp{%} is replaced
6300by the text that matched the @samp{%} in @var{pattern}.  Only the first
6301@samp{%} in the @var{pattern} and @var{replacement} is treated this
6302way; any subsequent @samp{%} is unchanged.@refill
6303
6304@cindex @code{%}, quoting in @code{patsubst}
6305@cindex @code{%}, quoting with @code{\} (backslash)
6306@cindex @code{\} (backslash), to quote @code{%}
6307@cindex backslash (@code{\}), to quote @code{%}
6308@cindex quoting @code{%}, in @code{patsubst}
6309@samp{%} characters in @code{patsubst} function invocations can be
6310quoted with preceding backslashes (@samp{\}).  Backslashes that would
6311otherwise quote @samp{%} characters can be quoted with more backslashes.
6312Backslashes that quote @samp{%} characters or other backslashes are
6313removed from the pattern before it is compared file names or has a stem
6314substituted into it.  Backslashes that are not in danger of quoting
6315@samp{%} characters go unmolested.  For example, the pattern
6316@file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
6317operative @samp{%} character, and @samp{pattern\\} following it.  The
6318final two backslashes are left alone because they cannot affect any
6319@samp{%} character.@refill
6320
6321Whitespace between words is folded into single space characters;
6322leading and trailing whitespace is discarded.
6323
6324For example,
6325
6326@example
6327$(patsubst %.c,%.o,x.c.c bar.c)
6328@end example
6329
6330@noindent
6331produces the value @samp{x.c.o bar.o}.
6332
6333Substitution references (@pxref{Substitution Refs, ,Substitution
6334References}) are a simpler way to get the effect of the @code{patsubst}
6335function:
6336
6337@example
6338$(@var{var}:@var{pattern}=@var{replacement})
6339@end example
6340
6341@noindent
6342is equivalent to
6343
6344@example
6345$(patsubst @var{pattern},@var{replacement},$(@var{var}))
6346@end example
6347
6348The second shorthand simplifies one of the most common uses of
6349@code{patsubst}: replacing the suffix at the end of file names.
6350
6351@example
6352$(@var{var}:@var{suffix}=@var{replacement})
6353@end example
6354
6355@noindent
6356is equivalent to
6357
6358@example
6359$(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
6360@end example
6361
6362@noindent
6363For example, you might have a list of object files:
6364
6365@example
6366objects = foo.o bar.o baz.o
6367@end example
6368
6369@noindent
6370To get the list of corresponding source files, you could simply write:
6371
6372@example
6373$(objects:.o=.c)
6374@end example
6375
6376@noindent
6377instead of using the general form:
6378
6379@example
6380$(patsubst %.o,%.c,$(objects))
6381@end example
6382
6383@item $(strip @var{string})
6384@cindex stripping whitespace
6385@cindex whitespace, stripping
6386@cindex spaces, stripping
6387@findex strip
6388Removes leading and trailing whitespace from @var{string} and replaces
6389each internal sequence of one or more whitespace characters with a
6390single space.  Thus, @samp{$(strip a b  c )} results in @w{@samp{a b c}}.
6391
6392The function @code{strip} can be very useful when used in conjunction
6393with conditionals.  When comparing something with the empty string
6394@samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
6395just whitespace to match the empty string (@pxref{Conditionals}).
6396
6397Thus, the following may fail to have the desired results:
6398
6399@example
6400.PHONY: all
6401ifneq   "$(needs_made)" ""
6402all: $(needs_made)
6403else
6404all:;@@echo 'Nothing to make!'
6405endif
6406@end example
6407
6408@noindent
6409Replacing the variable reference @w{@samp{$(needs_made)}} with the
6410function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
6411directive would make it more robust.@refill
6412
6413@item $(findstring @var{find},@var{in})
6414@findex findstring
6415@cindex searching for strings
6416@cindex finding strings
6417@cindex strings, searching for
6418Searches @var{in} for an occurrence of @var{find}.  If it occurs, the
6419value is @var{find}; otherwise, the value is empty.  You can use this
6420function in a conditional to test for the presence of a specific
6421substring in a given string.  Thus, the two examples,
6422
6423@example
6424$(findstring a,a b c)
6425$(findstring a,b c)
6426@end example
6427
6428@noindent
6429produce the values @samp{a} and @samp{} (the empty string),
6430respectively.  @xref{Testing Flags}, for a practical application of
6431@code{findstring}.@refill
6432
6433@need 750
6434@findex filter
6435@cindex filtering words
6436@cindex words, filtering
6437@item $(filter @var{pattern}@dots{},@var{text})
6438Returns all whitespace-separated words in @var{text} that @emph{do} match
6439any of the @var{pattern} words, removing any words that @emph{do not}
6440match.  The patterns are written using @samp{%}, just like the patterns
6441used in the @code{patsubst} function above.@refill
6442
6443The @code{filter} function can be used to separate out different types
6444of strings (such as file names) in a variable.  For example:
6445
6446@example
6447sources := foo.c bar.c baz.s ugh.h
6448foo: $(sources)
6449        cc $(filter %.c %.s,$(sources)) -o foo
6450@end example
6451
6452@noindent
6453says that @file{foo} depends of @file{foo.c}, @file{bar.c},
6454@file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
6455@file{baz.s} should be specified in the command to the
6456compiler.@refill
6457
6458@item $(filter-out @var{pattern}@dots{},@var{text})
6459@findex filter-out
6460@cindex filtering out words
6461@cindex words, filtering out
6462Returns all whitespace-separated words in @var{text} that @emph{do not}
6463match any of the @var{pattern} words, removing the words that @emph{do}
6464match one or more.  This is the exact opposite of the @code{filter}
6465function.@refill
6466
6467For example, given:
6468
6469@example
6470@group
6471objects=main1.o foo.o main2.o bar.o
6472mains=main1.o main2.o
6473@end group
6474@end example
6475
6476@noindent
6477the following generates a list which contains all the object files not
6478in @samp{mains}:
6479
6480@example
6481$(filter-out $(mains),$(objects))
6482@end example
6483
6484@need 1500
6485@findex sort
6486@cindex sorting words
6487@item $(sort @var{list})
6488Sorts the words of @var{list} in lexical order, removing duplicate
6489words.  The output is a list of words separated by single spaces.
6490Thus,
6491
6492@example
6493$(sort foo bar lose)
6494@end example
6495
6496@noindent
6497returns the value @samp{bar foo lose}.
6498
6499@cindex removing duplicate words
6500@cindex duplicate words, removing
6501@cindex words, removing duplicates
6502Incidentally, since @code{sort} removes duplicate words, you can use
6503it for this purpose even if you don't care about the sort order.
6504
6505@item $(word @var{n},@var{text})
6506@findex word
6507@cindex word, selecting a
6508@cindex selecting a word
6509Returns the @var{n}th word of @var{text}.  The legitimate values of
6510@var{n} start from 1.  If @var{n} is bigger than the number of words
6511in @var{text}, the value is empty.  For example,
6512
6513@example
6514$(word 2, foo bar baz)
6515@end example
6516
6517@noindent
6518returns @samp{bar}.
6519
6520@item $(wordlist @var{s},@var{e},@var{text})
6521@findex wordlist
6522@cindex words, selecting lists of
6523@cindex selecting word lists
6524Returns the list of words in @var{text} starting with word @var{s} and
6525ending with word @var{e} (inclusive).  The legitimate values of @var{s}
6526start from 1; @var{e} may start from 0.  If @var{s} is bigger than the
6527number of words in @var{text}, the value is empty.  If @var{e} is
6528bigger than the number of words in @var{text}, words up to the end of
6529@var{text} are returned.  If @var{s} is greater than @var{e}, nothing
6530is returned.  For example,
6531
6532@example
6533$(wordlist 2, 3, foo bar baz)
6534@end example
6535
6536@noindent
6537returns @samp{bar baz}.
6538
6539@c Following item phrased to prevent overfull hbox.  --RJC 17 Jul 92
6540@item $(words @var{text})
6541@findex words
6542@cindex words, finding number
6543Returns the number of words in @var{text}.
6544Thus, the last word of @var{text} is
6545@w{@code{$(word $(words @var{text}),@var{text})}}.@refill
6546
6547@item $(firstword @var{names}@dots{})
6548@findex firstword
6549@cindex words, extracting first
6550The argument @var{names} is regarded as a series of names, separated
6551by whitespace.  The value is the first name in the series.  The rest
6552of the names are ignored.
6553
6554For example,
6555
6556@example
6557$(firstword foo bar)
6558@end example
6559
6560@noindent
6561produces the result @samp{foo}.  Although @code{$(firstword
6562@var{text})} is the same as @code{$(word 1,@var{text})}, the
6563@code{firstword} function is retained for its simplicity.@refill
6564
6565
6566@item $(lastword @var{names}@dots{})
6567@findex lastword
6568@cindex words, extracting last
6569The argument @var{names} is regarded as a series of names, separated
6570by whitespace.  The value is the last name in the series.
6571
6572For example,
6573
6574@example
6575$(lastword foo bar)
6576@end example
6577
6578@noindent
6579produces the result @samp{bar}.  Although @code{$(lastword
6580@var{text})} is the same as @code{$(word $(words @var{text}),@var{text})},
6581the @code{lastword} function was added for its simplicity and better
6582performance.@refill
6583@end table
6584
6585
6586Here is a realistic example of the use of @code{subst} and
6587@code{patsubst}.  Suppose that a makefile uses the @code{VPATH} variable
6588to specify a list of directories that @code{make} should search for
6589prerequisite files
6590(@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}).
6591This example shows how to
6592tell the C compiler to search for header files in the same list of
6593directories.@refill
6594
6595The value of @code{VPATH} is a list of directories separated by colons,
6596such as @samp{src:../headers}.  First, the @code{subst} function is used to
6597change the colons to spaces:
6598
6599@example
6600$(subst :, ,$(VPATH))
6601@end example
6602
6603@noindent
6604This produces @samp{src ../headers}.  Then @code{patsubst} is used to turn
6605each directory name into a @samp{-I} flag.  These can be added to the
6606value of the variable @code{CFLAGS}, which is passed automatically to the C
6607compiler, like this:
6608
6609@example
6610override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
6611@end example
6612
6613@noindent
6614The effect is to append the text @samp{-Isrc -I../headers} to the
6615previously given value of @code{CFLAGS}.  The @code{override} directive is
6616used so that the new value is assigned even if the previous value of
6617@code{CFLAGS} was specified with a command argument (@pxref{Override
6618Directive, , The @code{override} Directive}).
6619
6620@node File Name Functions, Conditional Functions, Text Functions, Functions
6621@section Functions for File Names
6622@cindex functions, for file names
6623@cindex file name functions
6624
6625Several of the built-in expansion functions relate specifically to
6626taking apart file names or lists of file names.
6627
6628Each of the following functions performs a specific transformation on a
6629file name.  The argument of the function is regarded as a series of file
6630names, separated by whitespace.  (Leading and trailing whitespace is
6631ignored.)  Each file name in the series is transformed in the same way and
6632the results are concatenated with single spaces between them.
6633
6634@table @code
6635@item $(dir @var{names}@dots{})
6636@findex dir
6637@cindex directory part
6638@cindex file name, directory part
6639Extracts the directory-part of each file name in @var{names}.  The
6640directory-part of the file name is everything up through (and
6641including) the last slash in it.  If the file name contains no slash,
6642the directory part is the string @samp{./}.  For example,
6643
6644@example
6645$(dir src/foo.c hacks)
6646@end example
6647
6648@noindent
6649produces the result @samp{src/ ./}.
6650
6651@item $(notdir @var{names}@dots{})
6652@findex notdir
6653@cindex file name, nondirectory part
6654@cindex nondirectory part
6655Extracts all but the directory-part of each file name in @var{names}.
6656If the file name contains no slash, it is left unchanged.  Otherwise,
6657everything through the last slash is removed from it.
6658
6659A file name that ends with a slash becomes an empty string.  This is
6660unfortunate, because it means that the result does not always have the
6661same number of whitespace-separated file names as the argument had;
6662but we do not see any other valid alternative.
6663
6664For example,
6665
6666@example
6667$(notdir src/foo.c hacks)
6668@end example
6669
6670@noindent
6671produces the result @samp{foo.c hacks}.
6672
6673@item $(suffix @var{names}@dots{})
6674@findex suffix
6675@cindex suffix, function to find
6676@cindex file name suffix
6677Extracts the suffix of each file name in @var{names}.  If the file name
6678contains a period, the suffix is everything starting with the last
6679period.  Otherwise, the suffix is the empty string.  This frequently
6680means that the result will be empty when @var{names} is not, and if
6681@var{names} contains multiple file names, the result may contain fewer
6682file names.
6683
6684For example,
6685
6686@example
6687$(suffix src/foo.c src-1.0/bar.c hacks)
6688@end example
6689
6690@noindent
6691produces the result @samp{.c .c}.
6692
6693@item $(basename @var{names}@dots{})
6694@findex basename
6695@cindex basename
6696@cindex file name, basename of
6697Extracts all but the suffix of each file name in @var{names}.  If the
6698file name contains a period, the basename is everything starting up to
6699(and not including) the last period.  Periods in the directory part are
6700ignored.  If there is no period, the basename is the entire file name.
6701For example,
6702
6703@example
6704$(basename src/foo.c src-1.0/bar hacks)
6705@end example
6706
6707@noindent
6708produces the result @samp{src/foo src-1.0/bar hacks}.
6709
6710@c plural convention with dots (be consistent)
6711@item $(addsuffix @var{suffix},@var{names}@dots{})
6712@findex addsuffix
6713@cindex suffix, adding
6714@cindex file name suffix, adding
6715The argument @var{names} is regarded as a series of names, separated
6716by whitespace; @var{suffix} is used as a unit.  The value of
6717@var{suffix} is appended to the end of each individual name and the
6718resulting larger names are concatenated with single spaces between
6719them.  For example,
6720
6721@example
6722$(addsuffix .c,foo bar)
6723@end example
6724
6725@noindent
6726produces the result @samp{foo.c bar.c}.
6727
6728@item $(addprefix @var{prefix},@var{names}@dots{})
6729@findex addprefix
6730@cindex prefix, adding
6731@cindex file name prefix, adding
6732The argument @var{names} is regarded as a series of names, separated
6733by whitespace; @var{prefix} is used as a unit.  The value of
6734@var{prefix} is prepended to the front of each individual name and the
6735resulting larger names are concatenated with single spaces between
6736them.  For example,
6737
6738@example
6739$(addprefix src/,foo bar)
6740@end example
6741
6742@noindent
6743produces the result @samp{src/foo src/bar}.
6744
6745@item $(join @var{list1},@var{list2})
6746@findex join
6747@cindex joining lists of words
6748@cindex words, joining lists
6749Concatenates the two arguments word by word: the two first words (one
6750from each argument) concatenated form the first word of the result, the
6751two second words form the second word of the result, and so on.  So the
6752@var{n}th word of the result comes from the @var{n}th word of each
6753argument.  If one argument has more words that the other, the extra
6754words are copied unchanged into the result.
6755
6756For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
6757
6758Whitespace between the words in the lists is not preserved; it is
6759replaced with a single space.
6760
6761This function can merge the results of the @code{dir} and
6762@code{notdir} functions, to produce the original list of files which
6763was given to those two functions.@refill
6764
6765@item $(wildcard @var{pattern})
6766@findex wildcard
6767@cindex wildcard, function
6768The argument @var{pattern} is a file name pattern, typically containing
6769wildcard characters (as in shell file name patterns).  The result of
6770@code{wildcard} is a space-separated list of the names of existing files
6771that match the pattern.
6772@xref{Wildcards, ,Using Wildcard Characters in File Names}.
6773
6774@item $(realpath @var{names}@dots{})
6775@findex realpath
6776@cindex realpath
6777@cindex file name, realpath of
6778For each file name in @var{names} return the canonical absolute name.
6779A canonical name does not contain any @code{.} or @code{..} components,
6780nor any repeated path separators (@code{/}) or symlinks.  In case of a
6781failure the empty string is returned.  Consult the @code{realpath(3)}
6782documentation for a list of possible failure causes.
6783
6784@item $(abspath @var{names}@dots{})
6785@findex abspath
6786@cindex abspath
6787@cindex file name, abspath of
6788For each file name in @var{names} return an absolute name that does
6789not contain any @code{.} or @code{..} components, nor any repeated path
6790separators (@code{/}).  Note that, in contrast to @code{realpath}
6791function, @code{abspath} does not resolve symlinks and does not require
6792the file names to refer to an existing file or directory.  Use the
6793@code{wildcard} function to test for existence.
6794@end table
6795
6796@node Conditional Functions, Foreach Function, File Name Functions, Functions
6797@section Functions for Conditionals
6798@findex if
6799@cindex conditional expansion
6800There are three functions that provide conditional expansion.  A key
6801aspect of these functions is that not all of the arguments are
6802expanded initially.  Only those arguments which need to be expanded,
6803will be expanded.
6804
6805@table @code
6806@item $(if @var{condition},@var{then-part}[,@var{else-part}])
6807@findex if
6808The @code{if} function provides support for conditional expansion in a
6809functional context (as opposed to the GNU @code{make} makefile
6810conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of
6811Conditionals}).
6812
6813The first argument, @var{condition}, first has all preceding and
6814trailing whitespace stripped, then is expanded.  If it expands to any
6815non-empty string, then the condition is considered to be true.  If it
6816expands to an empty string, the condition is considered to be false.
6817
6818If the condition is true then the second argument, @var{then-part}, is
6819evaluated and this is used as the result of the evaluation of the entire
6820@code{if} function.
6821
6822If the condition is false then the third argument, @var{else-part}, is
6823evaluated and this is the result of the @code{if} function.  If there is
6824no third argument, the @code{if} function evaluates to nothing (the
6825empty string).
6826
6827Note that only one of the @var{then-part} or the @var{else-part} will be
6828evaluated, never both.  Thus, either can contain side-effects (such as
6829@code{shell} function calls, etc.)
6830
6831@item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
6832@findex or
6833The @code{or} function provides a ``short-circuiting'' OR operation.
6834Each argument is expanded, in order.  If an argument expands to a
6835non-empty string the processing stops and the result of the expansion
6836is that string.  If, after all arguments are expanded, all of them are
6837false (empty), then the result of the expansion is the empty string.
6838
6839@item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
6840@findex and
6841The @code{and} function provides a ``short-circuiting'' AND operation.
6842Each argument is expanded, in order.  If an argument expands to an
6843empty string the processing stops and the result of the expansion is
6844the empty string.  If all arguments expand to a non-empty string then
6845the result of the expansion is the expansion of the last argument.
6846
6847@end table
6848
6849@node Foreach Function, Call Function, Conditional Functions, Functions
6850@section The @code{foreach} Function
6851@findex foreach
6852@cindex words, iterating over
6853
6854The @code{foreach} function is very different from other functions.  It
6855causes one piece of text to be used repeatedly, each time with a different
6856substitution performed on it.  It resembles the @code{for} command in the
6857shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
6858
6859The syntax of the @code{foreach} function is:
6860
6861@example
6862$(foreach @var{var},@var{list},@var{text})
6863@end example
6864
6865@noindent
6866The first two arguments, @var{var} and @var{list}, are expanded before
6867anything else is done; note that the last argument, @var{text}, is
6868@strong{not} expanded at the same time.  Then for each word of the expanded
6869value of @var{list}, the variable named by the expanded value of @var{var}
6870is set to that word, and @var{text} is expanded.  Presumably @var{text}
6871contains references to that variable, so its expansion will be different
6872each time.
6873
6874The result is that @var{text} is expanded as many times as there are
6875whitespace-separated words in @var{list}.  The multiple expansions of
6876@var{text} are concatenated, with spaces between them, to make the result
6877of @code{foreach}.
6878
6879This simple example sets the variable @samp{files} to the list of all files
6880in the directories in the list @samp{dirs}:
6881
6882@example
6883dirs := a b c d
6884files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
6885@end example
6886
6887Here @var{text} is @samp{$(wildcard $(dir)/*)}.  The first repetition
6888finds the value @samp{a} for @code{dir}, so it produces the same result
6889as @samp{$(wildcard a/*)}; the second repetition produces the result
6890of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
6891
6892This example has the same result (except for setting @samp{dirs}) as
6893the following example:
6894
6895@example
6896files := $(wildcard a/* b/* c/* d/*)
6897@end example
6898
6899When @var{text} is complicated, you can improve readability by giving it
6900a name, with an additional variable:
6901
6902@example
6903find_files = $(wildcard $(dir)/*)
6904dirs := a b c d
6905files := $(foreach dir,$(dirs),$(find_files))
6906@end example
6907
6908@noindent
6909Here we use the variable @code{find_files} this way.  We use plain @samp{=}
6910to define a recursively-expanding variable, so that its value contains an
6911actual function call to be reexpanded under the control of @code{foreach};
6912a simply-expanded variable would not do, since @code{wildcard} would be
6913called only once at the time of defining @code{find_files}.
6914
6915The @code{foreach} function has no permanent effect on the variable
6916@var{var}; its value and flavor after the @code{foreach} function call are
6917the same as they were beforehand.  The other values which are taken from
6918@var{list} are in effect only temporarily, during the execution of
6919@code{foreach}.  The variable @var{var} is a simply-expanded variable
6920during the execution of @code{foreach}.  If @var{var} was undefined
6921before the @code{foreach} function call, it is undefined after the call.
6922@xref{Flavors, ,The Two Flavors of Variables}.@refill
6923
6924You must take care when using complex variable expressions that result in
6925variable names because many strange things are valid variable names, but
6926are probably not what you intended.  For example,
6927
6928@smallexample
6929files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
6930@end smallexample
6931
6932@noindent
6933might be useful if the value of @code{find_files} references the variable
6934whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo,
6935no?), but it is more likely to be a mistake.
6936
6937@node Call Function, Value Function, Foreach Function, Functions
6938@section The @code{call} Function
6939@findex call
6940@cindex functions, user defined
6941@cindex user defined functions
6942
6943The @code{call} function is unique in that it can be used to create new
6944parameterized functions.  You can write a complex expression as the
6945value of a variable, then use @code{call} to expand it with different
6946values.
6947
6948The syntax of the @code{call} function is:
6949
6950@example
6951$(call @var{variable},@var{param},@var{param},@dots{})
6952@end example
6953
6954When @code{make} expands this function, it assigns each @var{param} to
6955temporary variables @code{$(1)}, @code{$(2)}, etc.  The variable
6956@code{$(0)} will contain @var{variable}.  There is no maximum number of
6957parameter arguments.  There is no minimum, either, but it doesn't make
6958sense to use @code{call} with no parameters.
6959
6960Then @var{variable} is expanded as a @code{make} variable in the context
6961of these temporary assignments.  Thus, any reference to @code{$(1)} in
6962the value of @var{variable} will resolve to the first @var{param} in the
6963invocation of @code{call}.
6964
6965Note that @var{variable} is the @emph{name} of a variable, not a
6966@emph{reference} to that variable.  Therefore you would not normally use
6967a @samp{$} or parentheses when writing it.  (You can, however, use a
6968variable reference in the name if you want the name not to be a
6969constant.)
6970
6971If @var{variable} is the name of a builtin function, the builtin function
6972is always invoked (even if a @code{make} variable by that name also
6973exists).
6974
6975The @code{call} function expands the @var{param} arguments before
6976assigning them to temporary variables.  This means that @var{variable}
6977values containing references to builtin functions that have special
6978expansion rules, like @code{foreach} or @code{if}, may not work as you
6979expect.
6980
6981Some examples may make this clearer.
6982
6983This macro simply reverses its arguments:
6984
6985@smallexample
6986reverse = $(2) $(1)
6987
6988foo = $(call reverse,a,b)
6989@end smallexample
6990
6991@noindent
6992Here @var{foo} will contain @samp{b a}.
6993
6994This one is slightly more interesting: it defines a macro to search for
6995the first instance of a program in @code{PATH}:
6996
6997@smallexample
6998pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
6999
7000LS := $(call pathsearch,ls)
7001@end smallexample
7002
7003@noindent
7004Now the variable LS contains @code{/bin/ls} or similar.
7005
7006The @code{call} function can be nested.  Each recursive invocation gets
7007its own local values for @code{$(1)}, etc.@: that mask the values of
7008higher-level @code{call}.  For example, here is an implementation of a
7009@dfn{map} function:
7010
7011@smallexample
7012map = $(foreach a,$(2),$(call $(1),$(a)))
7013@end smallexample
7014
7015Now you can @var{map} a function that normally takes only one argument,
7016such as @code{origin}, to multiple values in one step:
7017
7018@smallexample
7019o = $(call map,origin,o map MAKE)
7020@end smallexample
7021
7022and end up with @var{o} containing something like @samp{file file default}.
7023
7024A final caution: be careful when adding whitespace to the arguments to
7025@code{call}.  As with other functions, any whitespace contained in the
7026second and subsequent arguments is kept; this can cause strange
7027effects.  It's generally safest to remove all extraneous whitespace when
7028providing parameters to @code{call}.
7029
7030@node Value Function, Eval Function, Call Function, Functions
7031@comment  node-name,  next,  previous,  up
7032@section The @code{value} Function
7033@findex value
7034@cindex variables, unexpanded value
7035
7036The @code{value} function provides a way for you to use the value of a
7037variable @emph{without} having it expanded.  Please note that this
7038does not undo expansions which have already occurred; for example if
7039you create a simply expanded variable its value is expanded during the
7040definition; in that case the @code{value} function will return the
7041same result as using the variable directly.
7042
7043The syntax of the @code{value} function is:
7044
7045@example
7046$(value @var{variable})
7047@end example
7048
7049Note that @var{variable} is the @emph{name} of a variable; not a
7050@emph{reference} to that variable.  Therefore you would not normally
7051use a @samp{$} or parentheses when writing it.  (You can, however, use
7052a variable reference in the name if you want the name not to be a
7053constant.)
7054
7055The result of this function is a string containing the value of
7056@var{variable}, without any expansion occurring.  For example, in this
7057makefile:
7058
7059@example
7060@group
7061FOO = $PATH
7062
7063all:
7064        @@echo $(FOO)
7065        @@echo $(value FOO)
7066@end group
7067@end example
7068
7069@noindent
7070The first output line would be @code{ATH}, since the ``$P'' would be
7071expanded as a @code{make} variable, while the second output line would
7072be the current value of your @code{$PATH} environment variable, since
7073the @code{value} function avoided the expansion.
7074
7075The @code{value} function is most often used in conjunction with the
7076@code{eval} function (@pxref{Eval Function}).
7077
7078@node Eval Function, Origin Function, Value Function, Functions
7079@comment  node-name,  next,  previous,  up
7080@section The @code{eval} Function
7081@findex eval
7082@cindex evaluating makefile syntax
7083@cindex makefile syntax, evaluating
7084
7085The @code{eval} function is very special: it allows you to define new
7086makefile constructs that are not constant; which are the result of
7087evaluating other variables and functions.  The argument to the
7088@code{eval} function is expanded, then the results of that expansion
7089are parsed as makefile syntax.  The expanded results can define new
7090@code{make} variables, targets, implicit or explicit rules, etc.
7091
7092The result of the @code{eval} function is always the empty string;
7093thus, it can be placed virtually anywhere in a makefile without
7094causing syntax errors.
7095
7096It's important to realize that the @code{eval} argument is expanded
7097@emph{twice}; first by the @code{eval} function, then the results of
7098that expansion are expanded again when they are parsed as makefile
7099syntax.  This means you may need to provide extra levels of escaping
7100for ``$'' characters when using @code{eval}.  The @code{value}
7101function (@pxref{Value Function}) can sometimes be useful in these
7102situations, to circumvent unwanted expansions.
7103
7104Here is an example of how @code{eval} can be used; this example
7105combines a number of concepts and other functions.  Although it might
7106seem overly complex to use @code{eval} in this example, rather than
7107just writing out the rules, consider two things: first, the template
7108definition (in @code{PROGRAM_template}) could need to be much more
7109complex than it is here; and second, you might put the complex,
7110``generic'' part of this example into another makefile, then include
7111it in all the individual makefiles.  Now your individual makefiles are
7112quite straightforward.
7113
7114@example
7115@group
7116PROGRAMS    = server client
7117
7118server_OBJS = server.o server_priv.o server_access.o
7119server_LIBS = priv protocol
7120
7121client_OBJS = client.o client_api.o client_mem.o
7122client_LIBS = protocol
7123
7124# Everything after this is generic
7125
7126.PHONY: all
7127all: $(PROGRAMS)
7128
7129define PROGRAM_template
7130 $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
7131 ALL_OBJS   += $$($(1)_OBJS)
7132endef
7133
7134$(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
7135
7136$(PROGRAMS):
7137        $(LINK.o) $^ $(LDLIBS) -o $@@
7138
7139clean:
7140        rm -f $(ALL_OBJS) $(PROGRAMS)
7141@end group
7142@end example
7143
7144@node Origin Function, Flavor Function, Eval Function, Functions
7145@section The @code{origin} Function
7146@findex origin
7147@cindex variables, origin of
7148@cindex origin of variable
7149
7150The @code{origin} function is unlike most other functions in that it does
7151not operate on the values of variables; it tells you something @emph{about}
7152a variable.  Specifically, it tells you where it came from.
7153
7154The syntax of the @code{origin} function is:
7155
7156@example
7157$(origin @var{variable})
7158@end example
7159
7160Note that @var{variable} is the @emph{name} of a variable to inquire about;
7161not a @emph{reference} to that variable.  Therefore you would not normally
7162use a @samp{$} or parentheses when writing it.  (You can, however, use a
7163variable reference in the name if you want the name not to be a constant.)
7164
7165The result of this function is a string telling you how the variable
7166@var{variable} was defined:
7167
7168@table @samp
7169@item undefined
7170
7171if @var{variable} was never defined.
7172
7173@item default
7174
7175if @var{variable} has a default definition, as is usual with @code{CC}
7176and so on.  @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
7177Note that if you have redefined a default variable, the @code{origin}
7178function will return the origin of the later definition.
7179
7180@item environment
7181
7182if @var{variable} was defined as an environment variable and the
7183@samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}).
7184
7185@item environment override
7186
7187if @var{variable} was defined as an environment variable and the
7188@w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary,
7189,Summary of Options}).@refill
7190
7191@item file
7192
7193if @var{variable} was defined in a makefile.
7194
7195@item command line
7196
7197if @var{variable} was defined on the command line.
7198
7199@item override
7200
7201if @var{variable} was defined with an @code{override} directive in a
7202makefile (@pxref{Override Directive, ,The @code{override} Directive}).
7203
7204@item automatic
7205
7206if @var{variable} is an automatic variable defined for the
7207execution of the commands for each rule
7208(@pxref{Automatic Variables}).
7209@end table
7210
7211This information is primarily useful (other than for your curiosity) to
7212determine if you want to believe the value of a variable.  For example,
7213suppose you have a makefile @file{foo} that includes another makefile
7214@file{bar}.  You want a variable @code{bletch} to be defined in @file{bar}
7215if you run the command @w{@samp{make -f bar}}, even if the environment contains
7216a definition of @code{bletch}.  However, if @file{foo} defined
7217@code{bletch} before including @file{bar}, you do not want to override that
7218definition.  This could be done by using an @code{override} directive in
7219@file{foo}, giving that definition precedence over the later definition in
7220@file{bar}; unfortunately, the @code{override} directive would also
7221override any command line definitions.  So, @file{bar} could
7222include:@refill
7223
7224@example
7225@group
7226ifdef bletch
7227ifeq "$(origin bletch)" "environment"
7228bletch = barf, gag, etc.
7229endif
7230endif
7231@end group
7232@end example
7233
7234@noindent
7235If @code{bletch} has been defined from the environment, this will redefine
7236it.
7237
7238If you want to override a previous definition of @code{bletch} if it came
7239from the environment, even under @samp{-e}, you could instead write:
7240
7241@example
7242@group
7243ifneq "$(findstring environment,$(origin bletch))" ""
7244bletch = barf, gag, etc.
7245endif
7246@end group
7247@end example
7248
7249Here the redefinition takes place if @samp{$(origin bletch)} returns either
7250@samp{environment} or @samp{environment override}.
7251@xref{Text Functions, , Functions for String Substitution and Analysis}.
7252
7253@node Flavor Function, Shell Function, Origin Function, Functions
7254@section The @code{flavor} Function
7255@findex flavor
7256@cindex variables, flavor of
7257@cindex flavor of variable
7258
7259The @code{flavor} function is unlike most other functions (and like
7260@code{origin} function) in that it does not operate on the values of
7261variables; it tells you something @emph{about} a variable.
7262Specifically, it tells you the flavor of a variable (@pxref{Flavors,
7263,The Two Flavors of Variables}).
7264
7265The syntax of the @code{flavor} function is:
7266
7267@example
7268$(flavor @var{variable})
7269@end example
7270
7271Note that @var{variable} is the @emph{name} of a variable to inquire about;
7272not a @emph{reference} to that variable.  Therefore you would not normally
7273use a @samp{$} or parentheses when writing it.  (You can, however, use a
7274variable reference in the name if you want the name not to be a constant.)
7275
7276The result of this function is a string that identifies the flavor of the
7277variable @var{variable}:
7278
7279@table @samp
7280@item undefined
7281
7282if @var{variable} was never defined.
7283
7284@item recursive
7285
7286if @var{variable} is a recursively expanded variable.
7287
7288@item simple
7289
7290if @var{variable} is a simply expanded variable.
7291
7292@end table
7293
7294
7295@node Shell Function, Make Control Functions, Flavor Function, Functions
7296@section The @code{shell} Function
7297@findex shell
7298@cindex commands, expansion
7299@cindex backquotes
7300@cindex shell command, function for
7301
7302The @code{shell} function is unlike any other function other than the
7303@code{wildcard} function
7304(@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
7305communicates with the world outside of @code{make}.
7306
7307The @code{shell} function performs the same function that backquotes
7308(@samp{`}) perform in most shells: it does @dfn{command expansion}.
7309This means that it takes as an argument a shell command and evaluates
7310to the output of the command.  The only processing @code{make} does on
7311the result is to convert each newline (or carriage-return / newline
7312pair) to a single space.  If there is a trailing (carriage-return
7313and) newline it will simply be removed.@refill
7314
7315The commands run by calls to the @code{shell} function are run when the
7316function calls are expanded (@pxref{Reading Makefiles, , How
7317@code{make} Reads a Makefile}).  Because this function involves
7318spawning a new shell, you should carefully consider the performance
7319implications of using the @code{shell} function within recursively
7320expanded variables vs.@: simply expanded variables (@pxref{Flavors, ,The
7321Two Flavors of Variables}).
7322
7323Here are some examples of the use of the @code{shell} function:
7324
7325@example
7326contents := $(shell cat foo)
7327@end example
7328
7329@noindent
7330sets @code{contents} to the contents of the file @file{foo}, with a space
7331(rather than a newline) separating each line.
7332
7333@example
7334files := $(shell echo *.c)
7335@end example
7336
7337@noindent
7338sets @code{files} to the expansion of @samp{*.c}.  Unless @code{make} is
7339using a very strange shell, this has the same result as
7340@w{@samp{$(wildcard *.c)}} (as long as at least one @samp{.c} file
7341exists).@refill
7342
7343@node Make Control Functions,  , Shell Function, Functions
7344@section Functions That Control Make
7345@cindex functions, for controlling make
7346@cindex controlling make
7347
7348These functions control the way make runs.  Generally, they are used to
7349provide information to the user of the makefile or to cause make to stop
7350if some sort of environmental error is detected.
7351
7352@table @code
7353@item $(error @var{text}@dots{})
7354@findex error
7355@cindex error, stopping on
7356@cindex stopping make
7357Generates a fatal error where the message is @var{text}.  Note that the
7358error is generated whenever this function is evaluated.  So, if you put
7359it inside a command script or on the right side of a recursive variable
7360assignment, it won't be evaluated until later.  The @var{text} will be
7361expanded before the error is generated.
7362
7363For example,
7364
7365@example
7366ifdef ERROR1
7367$(error error is $(ERROR1))
7368endif
7369@end example
7370
7371@noindent
7372will generate a fatal error during the read of the makefile if the
7373@code{make} variable @code{ERROR1} is defined.  Or,
7374
7375@example
7376ERR = $(error found an error!)
7377
7378.PHONY: err
7379err: ; $(ERR)
7380@end example
7381
7382@noindent
7383will generate a fatal error while @code{make} is running, if the
7384@code{err} target is invoked.
7385
7386@item $(warning @var{text}@dots{})
7387@findex warning
7388@cindex warnings, printing
7389@cindex printing user warnings
7390This function works similarly to the @code{error} function, above,
7391except that @code{make} doesn't exit.  Instead, @var{text} is expanded
7392and the resulting message is displayed, but processing of the makefile
7393continues.
7394
7395The result of the expansion of this function is the empty string.
7396
7397@item $(info @var{text}@dots{})
7398@findex info
7399@cindex printing messages
7400This function does nothing more than print its (expanded) argument(s)
7401to standard output.  No makefile name or line number is added.  The
7402result of the expansion of this function is the empty string.
7403@end table
7404
7405@node Running, Implicit Rules, Functions, Top
7406@chapter How to Run @code{make}
7407
7408A makefile that says how to recompile a program can be used in more
7409than one way.  The simplest use is to recompile every file that is out
7410of date.  Usually, makefiles are written so that if you run
7411@code{make} with no arguments, it does just that.
7412
7413But you might want to update only some of the files; you might want to use
7414a different compiler or different compiler options; you might want just to
7415find out which files are out of date without changing them.
7416
7417By giving arguments when you run @code{make}, you can do any of these
7418things and many others.
7419
7420@cindex exit status of make
7421The exit status of @code{make} is always one of three values:
7422@table @code
7423@item 0
7424The exit status is zero if @code{make} is successful.
7425@item 2
7426The exit status is two if @code{make} encounters any errors.
7427It will print messages describing the particular errors.
7428@item 1
7429The exit status is one if you use the @samp{-q} flag and @code{make}
7430determines that some target is not already up to date.
7431@xref{Instead of Execution, ,Instead of Executing the Commands}.
7432@end table
7433
7434@menu
7435* Makefile Arguments::          How to specify which makefile to use.
7436* Goals::                       How to use goal arguments to specify which
7437                                  parts of the makefile to use.
7438* Instead of Execution::        How to use mode flags to specify what
7439                                  kind of thing to do with the commands
7440                                  in the makefile other than simply
7441                                  execute them.
7442* Avoiding Compilation::        How to avoid recompiling certain files.
7443* Overriding::                  How to override a variable to specify
7444                                  an alternate compiler and other things.
7445* Testing::                     How to proceed past some errors, to
7446                                  test compilation.
7447* Options Summary::             Summary of Options
7448@end menu
7449
7450@node Makefile Arguments, Goals, Running, Running
7451@section Arguments to Specify the Makefile
7452@cindex @code{--file}
7453@cindex @code{--makefile}
7454@cindex @code{-f}
7455
7456The way to specify the name of the makefile is with the @samp{-f} or
7457@samp{--file} option (@samp{--makefile} also works).  For example,
7458@samp{-f altmake} says to use the file @file{altmake} as the makefile.
7459
7460If you use the @samp{-f} flag several times and follow each @samp{-f}
7461with an argument, all the specified files are used jointly as
7462makefiles.
7463
7464If you do not use the @samp{-f} or @samp{--file} flag, the default is
7465to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
7466that order, and use the first of these three which exists or can be made
7467(@pxref{Makefiles, ,Writing Makefiles}).@refill
7468
7469@node Goals, Instead of Execution, Makefile Arguments, Running
7470@section Arguments to Specify the Goals
7471@cindex goal, how to specify
7472
7473The @dfn{goals} are the targets that @code{make} should strive ultimately
7474to update.  Other targets are updated as well if they appear as
7475prerequisites of goals, or prerequisites of prerequisites of goals, etc.
7476
7477By default, the goal is the first target in the makefile (not counting
7478targets that start with a period).  Therefore, makefiles are usually
7479written so that the first target is for compiling the entire program or
7480programs they describe.  If the first rule in the makefile has several
7481targets, only the first target in the rule becomes the default goal, not
7482the whole list.  You can manage the selection of the default goal from
7483within your makefile using the @code{.DEFAULT_GOAL} variable
7484(@pxref{Special Variables, , Other Special Variables}).
7485
7486You can also specify a different goal or goals with command-line
7487arguments to @code{make}.  Use the name of the goal as an argument.
7488If you specify several goals, @code{make} processes each of them in
7489turn, in the order you name them.
7490
7491Any target in the makefile may be specified as a goal (unless it
7492starts with @samp{-} or contains an @samp{=}, in which case it will be
7493parsed as a switch or variable definition, respectively).  Even
7494targets not in the makefile may be specified, if @code{make} can find
7495implicit rules that say how to make them.
7496
7497@vindex MAKECMDGOALS
7498@code{Make} will set the special variable @code{MAKECMDGOALS} to the
7499list of goals you specified on the command line.  If no goals were given
7500on the command line, this variable is empty.  Note that this variable
7501should be used only in special circumstances.
7502
7503An example of appropriate use is to avoid including @file{.d} files
7504during @code{clean} rules (@pxref{Automatic Prerequisites}), so
7505@code{make} won't create them only to immediately remove them
7506again:@refill
7507
7508@example
7509@group
7510sources = foo.c bar.c
7511
7512ifneq ($(MAKECMDGOALS),clean)
7513include $(sources:.c=.d)
7514endif
7515@end group
7516@end example
7517
7518One use of specifying a goal is if you want to compile only a part of
7519the program, or only one of several programs.  Specify as a goal each
7520file that you wish to remake.  For example, consider a directory containing
7521several programs, with a makefile that starts like this:
7522
7523@example
7524.PHONY: all
7525all: size nm ld ar as
7526@end example
7527
7528If you are working on the program @code{size}, you might want to say
7529@w{@samp{make size}} so that only the files of that program are recompiled.
7530
7531Another use of specifying a goal is to make files that are not normally
7532made.  For example, there may be a file of debugging output, or a
7533version of the program that is compiled specially for testing, which has
7534a rule in the makefile but is not a prerequisite of the default goal.
7535
7536Another use of specifying a goal is to run the commands associated with
7537a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
7538Targets, ,Empty Target Files to Record Events}).  Many makefiles contain
7539a phony target named @file{clean} which deletes everything except source
7540files.  Naturally, this is done only if you request it explicitly with
7541@w{@samp{make clean}}.  Following is a list of typical phony and empty
7542target names.  @xref{Standard Targets}, for a detailed list of all the
7543standard target names which GNU software packages use.
7544
7545@table @file
7546@item all
7547@cindex @code{all} @r{(standard target)}
7548Make all the top-level targets the makefile knows about.
7549
7550@item clean
7551@cindex @code{clean} @r{(standard target)}
7552Delete all files that are normally created by running @code{make}.
7553
7554@item mostlyclean
7555@cindex @code{mostlyclean} @r{(standard target)}
7556Like @samp{clean}, but may refrain from deleting a few files that people
7557normally don't want to recompile.  For example, the @samp{mostlyclean}
7558target for GCC does not delete @file{libgcc.a}, because recompiling it
7559is rarely necessary and takes a lot of time.
7560
7561@item distclean
7562@cindex @code{distclean} @r{(standard target)}
7563@itemx realclean
7564@cindex @code{realclean} @r{(standard target)}
7565@itemx clobber
7566@cindex @code{clobber} @r{(standard target)}
7567Any of these targets might be defined to delete @emph{more} files than
7568@samp{clean} does.  For example, this would delete configuration files
7569or links that you would normally create as preparation for compilation,
7570even if the makefile itself cannot create these files.
7571
7572@item install
7573@cindex @code{install} @r{(standard target)}
7574Copy the executable file into a directory that users typically search
7575for commands; copy any auxiliary files that the executable uses into
7576the directories where it will look for them.
7577
7578@item print
7579@cindex @code{print} @r{(standard target)}
7580Print listings of the source files that have changed.
7581
7582@item tar
7583@cindex @code{tar} @r{(standard target)}
7584Create a tar file of the source files.
7585
7586@item shar
7587@cindex @code{shar} @r{(standard target)}
7588Create a shell archive (shar file) of the source files.
7589
7590@item dist
7591@cindex @code{dist} @r{(standard target)}
7592Create a distribution file of the source files.  This might
7593be a tar file, or a shar file, or a compressed version of one of the
7594above, or even more than one of the above.
7595
7596@item TAGS
7597@cindex @code{TAGS} @r{(standard target)}
7598Update a tags table for this program.
7599
7600@item check
7601@cindex @code{check} @r{(standard target)}
7602@itemx test
7603@cindex @code{test} @r{(standard target)}
7604Perform self tests on the program this makefile builds.
7605@end table
7606
7607@node Instead of Execution, Avoiding Compilation, Goals, Running
7608@section Instead of Executing the Commands
7609@cindex execution, instead of
7610@cindex commands, instead of executing
7611
7612The makefile tells @code{make} how to tell whether a target is up to date,
7613and how to update each target.  But updating the targets is not always
7614what you want.  Certain options specify other activities for @code{make}.
7615
7616@comment Extra blank lines make it print better.
7617@table @samp
7618@item -n
7619@itemx --just-print
7620@itemx --dry-run
7621@itemx --recon
7622@cindex @code{--just-print}
7623@cindex @code{--dry-run}
7624@cindex @code{--recon}
7625@cindex @code{-n}
7626
7627``No-op''.  The activity is to print what commands would be used to make
7628the targets up to date, but not actually execute them.
7629
7630@item -t
7631@itemx --touch
7632@cindex @code{--touch}
7633@cindex touching files
7634@cindex target, touching
7635@cindex @code{-t}
7636
7637``Touch''.  The activity is to mark the targets as up to date without
7638actually changing them.  In other words, @code{make} pretends to compile
7639the targets but does not really change their contents.
7640
7641@item -q
7642@itemx --question
7643@cindex @code{--question}
7644@cindex @code{-q}
7645@cindex question mode
7646
7647``Question''.  The activity is to find out silently whether the targets
7648are up to date already; but execute no commands in either case.  In other
7649words, neither compilation nor output will occur.
7650
7651@item -W @var{file}
7652@itemx --what-if=@var{file}
7653@itemx --assume-new=@var{file}
7654@itemx --new-file=@var{file}
7655@cindex @code{--what-if}
7656@cindex @code{-W}
7657@cindex @code{--assume-new}
7658@cindex @code{--new-file}
7659@cindex what if
7660@cindex files, assuming new
7661
7662``What if''.  Each @samp{-W} flag is followed by a file name.  The given
7663files' modification times are recorded by @code{make} as being the present
7664time, although the actual modification times remain the same.
7665You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
7666to see what would happen if you were to modify specific files.@refill
7667@end table
7668
7669With the @samp{-n} flag, @code{make} prints the commands that it would
7670normally execute but does not execute them.
7671
7672With the @samp{-t} flag, @code{make} ignores the commands in the rules
7673and uses (in effect) the command @code{touch} for each target that needs to
7674be remade.  The @code{touch} command is also printed, unless @samp{-s} or
7675@code{.SILENT} is used.  For speed, @code{make} does not actually invoke
7676the program @code{touch}.  It does the work directly.
7677
7678With the @samp{-q} flag, @code{make} prints nothing and executes no
7679commands, but the exit status code it returns is zero if and only if the
7680targets to be considered are already up to date.  If the exit status is
7681one, then some updating needs to be done.  If @code{make} encounters an
7682error, the exit status is two, so you can distinguish an error from a
7683target that is not up to date.
7684
7685It is an error to use more than one of these three flags in the same
7686invocation of @code{make}.
7687
7688@cindex +, and command execution
7689The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command
7690lines that begin with @samp{+} characters or contain the strings
7691@samp{$(MAKE)} or @samp{$@{MAKE@}}.  Note that only the line containing
7692the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
7693is run regardless of these options.  Other lines in the same rule are
7694not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
7695@samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
7696
7697The @samp{-W} flag provides two features:
7698
7699@itemize @bullet
7700@item
7701If you also use the @samp{-n} or @samp{-q} flag, you can see what
7702@code{make} would do if you were to modify some files.
7703
7704@item
7705Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
7706executing commands, the @samp{-W} flag can direct @code{make} to act
7707as if some files had been modified, without actually modifying the
7708files.@refill
7709@end itemize
7710
7711Note that the options @samp{-p} and @samp{-v} allow you to obtain other
7712information about @code{make} or about the makefiles in use
7713(@pxref{Options Summary, ,Summary of Options}).@refill
7714
7715@node Avoiding Compilation, Overriding, Instead of Execution, Running
7716@section Avoiding Recompilation of Some Files
7717@cindex @code{-o}
7718@cindex @code{--old-file}
7719@cindex @code{--assume-old}
7720@cindex files, assuming old
7721@cindex files, avoiding recompilation of
7722@cindex recompilation, avoiding
7723
7724Sometimes you may have changed a source file but you do not want to
7725recompile all the files that depend on it.  For example, suppose you add
7726a macro or a declaration to a header file that many other files depend
7727on.  Being conservative, @code{make} assumes that any change in the
7728header file requires recompilation of all dependent files, but you know
7729that they do not need to be recompiled and you would rather not waste
7730the time waiting for them to compile.
7731
7732If you anticipate the problem before changing the header file, you can
7733use the @samp{-t} flag.  This flag tells @code{make} not to run the
7734commands in the rules, but rather to mark the target up to date by
7735changing its last-modification date.  You would follow this procedure:
7736
7737@enumerate
7738@item
7739Use the command @samp{make} to recompile the source files that really
7740need recompilation, ensuring that the object files are up-to-date
7741before you begin.
7742
7743@item
7744Make the changes in the header files.
7745
7746@item
7747Use the command @samp{make -t} to mark all the object files as
7748up to date.  The next time you run @code{make}, the changes in the
7749header files will not cause any recompilation.
7750@end enumerate
7751
7752If you have already changed the header file at a time when some files
7753do need recompilation, it is too late to do this.  Instead, you can
7754use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
7755``old'' (@pxref{Options Summary, ,Summary of Options}).  This means
7756that the file itself will not be remade, and nothing else will be
7757remade on its account.  Follow this procedure:
7758
7759@enumerate
7760@item
7761Recompile the source files that need compilation for reasons independent
7762of the particular header file, with @samp{make -o @var{headerfile}}.
7763If several header files are involved, use a separate @samp{-o} option
7764for each header file.
7765
7766@item
7767Touch all the object files with @samp{make -t}.
7768@end enumerate
7769
7770@node Overriding, Testing, Avoiding Compilation, Running
7771@section Overriding Variables
7772@cindex overriding variables with arguments
7773@cindex variables, overriding with arguments
7774@cindex command line variables
7775@cindex variables, command line
7776
7777An argument that contains @samp{=} specifies the value of a variable:
7778@samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
7779If you specify a value in this way, all ordinary assignments of the same
7780variable in the makefile are ignored; we say they have been
7781@dfn{overridden} by the command line argument.
7782
7783The most common way to use this facility is to pass extra flags to
7784compilers.  For example, in a properly written makefile, the variable
7785@code{CFLAGS} is included in each command that runs the C compiler, so a
7786file @file{foo.c} would be compiled something like this:
7787
7788@example
7789cc -c $(CFLAGS) foo.c
7790@end example
7791
7792Thus, whatever value you set for @code{CFLAGS} affects each compilation
7793that occurs.  The makefile probably specifies the usual value for
7794@code{CFLAGS}, like this:
7795
7796@example
7797CFLAGS=-g
7798@end example
7799
7800Each time you run @code{make}, you can override this value if you
7801wish.  For example, if you say @samp{make CFLAGS='-g -O'}, each C
7802compilation will be done with @samp{cc -c -g -O}.  (This also
7803illustrates how you can use quoting in the shell to enclose spaces and
7804other special characters in the value of a variable when you override
7805it.)
7806
7807The variable @code{CFLAGS} is only one of many standard variables that
7808exist just so that you can change them this way.  @xref{Implicit
7809Variables, , Variables Used by Implicit Rules}, for a complete list.
7810
7811You can also program the makefile to look at additional variables of your
7812own, giving the user the ability to control other aspects of how the
7813makefile works by changing the variables.
7814
7815When you override a variable with a command argument, you can define either
7816a recursively-expanded variable or a simply-expanded variable.  The
7817examples shown above make a recursively-expanded variable; to make a
7818simply-expanded variable, write @samp{:=} instead of @samp{=}.  But, unless
7819you want to include a variable reference or function call in the
7820@emph{value} that you specify, it makes no difference which kind of
7821variable you create.
7822
7823There is one way that the makefile can change a variable that you have
7824overridden.  This is to use the @code{override} directive, which is a line
7825that looks like this: @samp{override @var{variable} = @var{value}}
7826(@pxref{Override Directive, ,The @code{override} Directive}).
7827
7828@node Testing, Options Summary, Overriding, Running
7829@section Testing the Compilation of a Program
7830@cindex testing compilation
7831@cindex compilation, testing
7832
7833Normally, when an error happens in executing a shell command, @code{make}
7834gives up immediately, returning a nonzero status.  No further commands are
7835executed for any target.  The error implies that the goal cannot be
7836correctly remade, and @code{make} reports this as soon as it knows.
7837
7838When you are compiling a program that you have just changed, this is not
7839what you want.  Instead, you would rather that @code{make} try compiling
7840every file that can be tried, to show you as many compilation errors
7841as possible.
7842
7843@cindex @code{-k}
7844@cindex @code{--keep-going}
7845On these occasions, you should use the @samp{-k} or
7846@samp{--keep-going} flag.  This tells @code{make} to continue to
7847consider the other prerequisites of the pending targets, remaking them
7848if necessary, before it gives up and returns nonzero status.  For
7849example, after an error in compiling one object file, @samp{make -k}
7850will continue compiling other object files even though it already
7851knows that linking them will be impossible.  In addition to continuing
7852after failed shell commands, @samp{make -k} will continue as much as
7853possible after discovering that it does not know how to make a target
7854or prerequisite file.  This will always cause an error message, but
7855without @samp{-k}, it is a fatal error (@pxref{Options Summary,
7856,Summary of Options}).@refill
7857
7858The usual behavior of @code{make} assumes that your purpose is to get the
7859goals up to date; once @code{make} learns that this is impossible, it might
7860as well report the failure immediately.  The @samp{-k} flag says that the
7861real purpose is to test as much as possible of the changes made in the
7862program, perhaps to find several independent problems so that you can
7863correct them all before the next attempt to compile.  This is why Emacs'
7864@kbd{M-x compile} command passes the @samp{-k} flag by default.
7865
7866@node Options Summary,  , Testing, Running
7867@section Summary of Options
7868@cindex options
7869@cindex flags
7870@cindex switches
7871
7872Here is a table of all the options @code{make} understands:
7873
7874@table @samp
7875@item -b
7876@cindex @code{-b}
7877@itemx -m
7878@cindex @code{-m}
7879These options are ignored for compatibility with other versions of @code{make}.
7880
7881@item -B
7882@cindex @code{-B}
7883@itemx --always-make
7884@cindex @code{--always-make}
7885Consider all targets out-of-date.  GNU @code{make} proceeds to
7886consider targets and their prerequisites using the normal algorithms;
7887however, all targets so considered are always remade regardless of the
7888status of their prerequisites.  To avoid infinite recursion, if
7889@code{MAKE_RESTARTS} (@pxref{Special Variables, , Other Special
7890Variables}) is set to a number greater than 0 this option is disabled
7891when considering whether to remake makefiles (@pxref{Remaking
7892Makefiles, , How Makefiles Are Remade}).
7893
7894@item -C @var{dir}
7895@cindex @code{-C}
7896@itemx --directory=@var{dir}
7897@cindex @code{--directory}
7898Change to directory @var{dir} before reading the makefiles.  If multiple
7899@samp{-C} options are specified, each is interpreted relative to the
7900previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
7901This is typically used with recursive invocations of @code{make}
7902(@pxref{Recursion, ,Recursive Use of @code{make}}).
7903
7904@item -d
7905@cindex @code{-d}
7906@c Extra blank line here makes the table look better.
7907
7908Print debugging information in addition to normal processing.  The
7909debugging information says which files are being considered for
7910remaking, which file-times are being compared and with what results,
7911which files actually need to be remade, which implicit rules are
7912considered and which are applied---everything interesting about how
7913@code{make} decides what to do.  The @code{-d} option is equivalent to
7914@samp{--debug=a} (see below).
7915
7916@item --debug[=@var{options}]
7917@cindex @code{--debug}
7918@c Extra blank line here makes the table look better.
7919
7920Print debugging information in addition to normal processing.  Various
7921levels and types of output can be chosen.  With no arguments, print the
7922``basic'' level of debugging.  Possible arguments are below; only the
7923first character is considered, and values must be comma- or
7924space-separated.
7925
7926@table @code
7927@item a (@i{all})
7928All types of debugging output are enabled.  This is equivalent to using
7929@samp{-d}.
7930
7931@item b (@i{basic})
7932Basic debugging prints each target that was found to be out-of-date, and
7933whether the build was successful or not.
7934
7935@item v (@i{verbose})
7936A level above @samp{basic}; includes messages about which makefiles were
7937parsed, prerequisites that did not need to be rebuilt, etc.  This option
7938also enables @samp{basic} messages.
7939
7940@item i (@i{implicit})
7941Prints messages describing the implicit rule searches for each target.
7942This option also enables @samp{basic} messages.
7943
7944@item j (@i{jobs})
7945Prints messages giving details on the invocation of specific subcommands.
7946
7947@item m (@i{makefile})
7948By default, the above messages are not enabled while trying to remake
7949the makefiles.  This option enables messages while rebuilding makefiles,
7950too.  Note that the @samp{all} option does enable this option.  This
7951option also enables @samp{basic} messages.
7952@end table
7953
7954@item -e
7955@cindex @code{-e}
7956@itemx --environment-overrides
7957@cindex @code{--environment-overrides}
7958Give variables taken from the environment precedence
7959over variables from makefiles.
7960@xref{Environment, ,Variables from the Environment}.
7961
7962@item -f @var{file}
7963@cindex @code{-f}
7964@itemx --file=@var{file}
7965@cindex @code{--file}
7966@itemx --makefile=@var{file}
7967@cindex @code{--makefile}
7968Read the file named @var{file} as a makefile.
7969@xref{Makefiles, ,Writing Makefiles}.
7970
7971@item -h
7972@cindex @code{-h}
7973@itemx --help
7974@cindex @code{--help}
7975@c Extra blank line here makes the table look better.
7976
7977Remind you of the options that @code{make} understands and then exit.
7978
7979@item -i
7980@cindex @code{-i}
7981@itemx --ignore-errors
7982@cindex @code{--ignore-errors}
7983Ignore all errors in commands executed to remake files.
7984@xref{Errors, ,Errors in Commands}.
7985
7986@item -I @var{dir}
7987@cindex @code{-I}
7988@itemx --include-dir=@var{dir}
7989@cindex @code{--include-dir}
7990Specifies a directory @var{dir} to search for included makefiles.
7991@xref{Include, ,Including Other Makefiles}.  If several @samp{-I}
7992options are used to specify several directories, the directories are
7993searched in the order specified.
7994
7995@item -j [@var{jobs}]
7996@cindex @code{-j}
7997@itemx --jobs[=@var{jobs}]
7998@cindex @code{--jobs}
7999Specifies the number of jobs (commands) to run simultaneously.  With no
8000argument, @code{make} runs as many jobs simultaneously as possible.  If
8001there is more than one @samp{-j} option, the last one is effective.
8002@xref{Parallel, ,Parallel Execution},
8003for more information on how commands are run.
8004Note that this option is ignored on MS-DOS.
8005
8006@item -k
8007@cindex @code{-k}
8008@itemx --keep-going
8009@cindex @code{--keep-going}
8010Continue as much as possible after an error.  While the target that
8011failed, and those that depend on it, cannot be remade, the other
8012prerequisites of these targets can be processed all the same.
8013@xref{Testing, ,Testing the Compilation of a Program}.
8014
8015@item -l [@var{load}]
8016@cindex @code{-l}
8017@itemx --load-average[=@var{load}]
8018@cindex @code{--load-average}
8019@itemx --max-load[=@var{load}]
8020@cindex @code{--max-load}
8021Specifies that no new jobs (commands) should be started if there are
8022other jobs running and the load average is at least @var{load} (a
8023floating-point number).  With no argument, removes a previous load
8024limit.  @xref{Parallel, ,Parallel Execution}.
8025
8026@item -L
8027@cindex @code{-L}
8028@itemx --check-symlink-times
8029@cindex @code{--check-symlink-times}
8030On systems that support symbolic links, this option causes @code{make}
8031to consider the timestamps on any symbolic links in addition to the
8032timestamp on the file referenced by those links.  When this option is
8033provided, the most recent timestamp among the file and the symbolic
8034links is taken as the modification time for this target file.
8035
8036@item -n
8037@cindex @code{-n}
8038@itemx --just-print
8039@cindex @code{--just-print}
8040@itemx --dry-run
8041@cindex @code{--dry-run}
8042@itemx --recon
8043@cindex @code{--recon}
8044@c Extra blank line here makes the table look better.
8045
8046Print the commands that would be executed, but do not execute them.
8047@xref{Instead of Execution, ,Instead of Executing the Commands}.
8048
8049@item -o @var{file}
8050@cindex @code{-o}
8051@itemx --old-file=@var{file}
8052@cindex @code{--old-file}
8053@itemx --assume-old=@var{file}
8054@cindex @code{--assume-old}
8055Do not remake the file @var{file} even if it is older than its
8056prerequisites, and do not remake anything on account of changes in
8057@var{file}.  Essentially the file is treated as very old and its rules
8058are ignored.  @xref{Avoiding Compilation, ,Avoiding Recompilation of
8059Some Files}.@refill
8060
8061@item -p
8062@cindex @code{-p}
8063@itemx --print-data-base
8064@cindex @code{--print-data-base}
8065@cindex data base of @code{make} rules
8066@cindex predefined rules and variables, printing
8067Print the data base (rules and variable values) that results from
8068reading the makefiles; then execute as usual or as otherwise specified.
8069This also prints the version information given by the @samp{-v} switch
8070(see below).  To print the data base without trying to remake any files,
8071use @w{@samp{make -qp}}.  To print the data base of predefined rules and
8072variables, use @w{@samp{make -p -f /dev/null}}.  The data base output
8073contains filename and linenumber information for command and variable
8074definitions, so it can be a useful debugging tool in complex environments.
8075
8076@item -q
8077@cindex @code{-q}
8078@itemx --question
8079@cindex @code{--question}
8080``Question mode''.  Do not run any commands, or print anything; just
8081return an exit status that is zero if the specified targets are already
8082up to date, one if any remaking is required, or two if an error is
8083encountered.  @xref{Instead of Execution, ,Instead of Executing the
8084Commands}.@refill
8085
8086@item -r
8087@cindex @code{-r}
8088@itemx --no-builtin-rules
8089@cindex @code{--no-builtin-rules}
8090Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
8091,Using Implicit Rules}).  You can still define your own by writing
8092pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
8093Rules}).  The @samp{-r} option also clears out the default list of
8094suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
8095Rules}).  But you can still define your own suffixes with a rule for
8096@code{.SUFFIXES}, and then define your own suffix rules.  Note that only
8097@emph{rules} are affected by the @code{-r} option; default variables
8098remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit
8099Rules}); see the @samp{-R} option below.
8100
8101@item -R
8102@cindex @code{-R}
8103@itemx --no-builtin-variables
8104@cindex @code{--no-builtin-variables}
8105Eliminate use of the built-in rule-specific variables (@pxref{Implicit
8106Variables, ,Variables Used by Implicit Rules}).  You can still define
8107your own, of course.  The @samp{-R} option also automatically enables
8108the @samp{-r} option (see above), since it doesn't make sense to have
8109implicit rules without any definitions for the variables that they use.
8110
8111@item -s
8112@cindex @code{-s}
8113@itemx --silent
8114@cindex @code{--silent}
8115@itemx --quiet
8116@cindex @code{--quiet}
8117@c Extra blank line here makes the table look better.
8118
8119Silent operation; do not print the commands as they are executed.
8120@xref{Echoing, ,Command Echoing}.
8121
8122@item -S
8123@cindex @code{-S}
8124@itemx --no-keep-going
8125@cindex @code{--no-keep-going}
8126@itemx --stop
8127@cindex @code{--stop}
8128@c Extra blank line here makes the table look better.
8129
8130Cancel the effect of the @samp{-k} option.  This is never necessary
8131except in a recursive @code{make} where @samp{-k} might be inherited
8132from the top-level @code{make} via @code{MAKEFLAGS}
8133(@pxref{Recursion, ,Recursive Use of @code{make}})
8134or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
8135
8136@item -t
8137@cindex @code{-t}
8138@itemx --touch
8139@cindex @code{--touch}
8140@c Extra blank line here makes the table look better.
8141
8142Touch files (mark them up to date without really changing them)
8143instead of running their commands.  This is used to pretend that the
8144commands were done, in order to fool future invocations of
8145@code{make}.  @xref{Instead of Execution, ,Instead of Executing the Commands}.
8146
8147@item -v
8148@cindex @code{-v}
8149@itemx --version
8150@cindex @code{--version}
8151Print the version of the @code{make} program plus a copyright, a list
8152of authors, and a notice that there is no warranty; then exit.
8153
8154@item -w
8155@cindex @code{-w}
8156@itemx --print-directory
8157@cindex @code{--print-directory}
8158Print a message containing the working directory both before and after
8159executing the makefile.  This may be useful for tracking down errors
8160from complicated nests of recursive @code{make} commands.
8161@xref{Recursion, ,Recursive Use of @code{make}}.  (In practice, you
8162rarely need to specify this option since @samp{make} does it for you;
8163see @ref{-w Option, ,The @samp{--print-directory} Option}.)
8164
8165@itemx --no-print-directory
8166@cindex @code{--no-print-directory}
8167Disable printing of the working directory under @code{-w}.
8168This option is useful when @code{-w} is turned on automatically,
8169but you do not want to see the extra messages.
8170@xref{-w Option, ,The @samp{--print-directory} Option}.
8171
8172@item -W @var{file}
8173@cindex @code{-W}
8174@itemx --what-if=@var{file}
8175@cindex @code{--what-if}
8176@itemx --new-file=@var{file}
8177@cindex @code{--new-file}
8178@itemx --assume-new=@var{file}
8179@cindex @code{--assume-new}
8180Pretend that the target @var{file} has just been modified.  When used
8181with the @samp{-n} flag, this shows you what would happen if you were
8182to modify that file.  Without @samp{-n}, it is almost the same as
8183running a @code{touch} command on the given file before running
8184@code{make}, except that the modification time is changed only in the
8185imagination of @code{make}.
8186@xref{Instead of Execution, ,Instead of Executing the Commands}.
8187
8188@item --warn-undefined-variables
8189@cindex @code{--warn-undefined-variables}
8190@cindex variables, warning for undefined
8191@cindex undefined variables, warning message
8192Issue a warning message whenever @code{make} sees a reference to an
8193undefined variable.  This can be helpful when you are trying to debug
8194makefiles which use variables in complex ways.
8195@end table
8196
8197@node Implicit Rules, Archives, Running, Top
8198@chapter Using Implicit Rules
8199@cindex implicit rule
8200@cindex rule, implicit
8201
8202Certain standard ways of remaking target files are used very often.  For
8203example, one customary way to make an object file is from a C source file
8204using the C compiler, @code{cc}.
8205
8206@dfn{Implicit rules} tell @code{make} how to use customary techniques so
8207that you do not have to specify them in detail when you want to use
8208them.  For example, there is an implicit rule for C compilation.  File
8209names determine which implicit rules are run.  For example, C
8210compilation typically takes a @file{.c} file and makes a @file{.o} file.
8211So @code{make} applies the implicit rule for C compilation when it sees
8212this combination of file name endings.@refill
8213
8214A chain of implicit rules can apply in sequence; for example, @code{make}
8215will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
8216@iftex
8217@xref{Chained Rules, ,Chains of Implicit Rules}.
8218@end iftex
8219
8220The built-in implicit rules use several variables in their commands so
8221that, by changing the values of the variables, you can change the way the
8222implicit rule works.  For example, the variable @code{CFLAGS} controls the
8223flags given to the C compiler by the implicit rule for C compilation.
8224@iftex
8225@xref{Implicit Variables, ,Variables Used by Implicit Rules}.
8226@end iftex
8227
8228You can define your own implicit rules by writing @dfn{pattern rules}.
8229@iftex
8230@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
8231@end iftex
8232
8233@dfn{Suffix rules} are a more limited way to define implicit rules.
8234Pattern rules are more general and clearer, but suffix rules are
8235retained for compatibility.
8236@iftex
8237@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
8238@end iftex
8239
8240@menu
8241* Using Implicit::              How to use an existing implicit rule
8242                                  to get the commands for updating a file.
8243* Catalogue of Rules::          A list of built-in implicit rules.
8244* Implicit Variables::          How to change what predefined rules do.
8245* Chained Rules::               How to use a chain of implicit rules.
8246* Pattern Rules::               How to define new implicit rules.
8247* Last Resort::                 How to define commands for rules which
8248                                  cannot find any.
8249* Suffix Rules::                The old-fashioned style of implicit rule.
8250* Implicit Rule Search::        The precise algorithm for applying
8251                                  implicit rules.
8252@end menu
8253
8254@node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules
8255@section Using Implicit Rules
8256@cindex implicit rule, how to use
8257@cindex rule, implicit, how to use
8258
8259To allow @code{make} to find a customary method for updating a target file,
8260all you have to do is refrain from specifying commands yourself.  Either
8261write a rule with no command lines, or don't write a rule at all.  Then
8262@code{make} will figure out which implicit rule to use based on which
8263kind of source file exists or can be made.
8264
8265For example, suppose the makefile looks like this:
8266
8267@example
8268foo : foo.o bar.o
8269        cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
8270@end example
8271
8272@noindent
8273Because you mention @file{foo.o} but do not give a rule for it, @code{make}
8274will automatically look for an implicit rule that tells how to update it.
8275This happens whether or not the file @file{foo.o} currently exists.
8276
8277If an implicit rule is found, it can supply both commands and one or
8278more prerequisites (the source files).  You would want to write a rule
8279for @file{foo.o} with no command lines if you need to specify additional
8280prerequisites, such as header files, that the implicit rule cannot
8281supply.
8282
8283Each implicit rule has a target pattern and prerequisite patterns.  There may
8284be many implicit rules with the same target pattern.  For example, numerous
8285rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
8286another, from a @samp{.p} file with the Pascal compiler; and so on.  The rule
8287that actually applies is the one whose prerequisites exist or can be made.
8288So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
8289otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
8290compiler; and so on.
8291
8292Of course, when you write the makefile, you know which implicit rule you
8293want @code{make} to use, and you know it will choose that one because you
8294know which possible prerequisite files are supposed to exist.
8295@xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
8296for a catalogue of all the predefined implicit rules.
8297
8298Above, we said an implicit rule applies if the required prerequisites ``exist
8299or can be made''.  A file ``can be made'' if it is mentioned explicitly in
8300the makefile as a target or a prerequisite, or if an implicit rule can be
8301recursively found for how to make it.  When an implicit prerequisite is the
8302result of another implicit rule, we say that @dfn{chaining} is occurring.
8303@xref{Chained Rules, ,Chains of Implicit Rules}.
8304
8305In general, @code{make} searches for an implicit rule for each target, and
8306for each double-colon rule, that has no commands.  A file that is mentioned
8307only as a prerequisite is considered a target whose rule specifies nothing,
8308so implicit rule search happens for it.  @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the
8309details of how the search is done.
8310
8311Note that explicit prerequisites do not influence implicit rule search.
8312For example, consider this explicit rule:
8313
8314@example
8315foo.o: foo.p
8316@end example
8317
8318@noindent
8319The prerequisite on @file{foo.p} does not necessarily mean that
8320@code{make} will remake @file{foo.o} according to the implicit rule to
8321make an object file, a @file{.o} file, from a Pascal source file, a
8322@file{.p} file.  For example, if @file{foo.c} also exists, the implicit
8323rule to make an object file from a C source file is used instead,
8324because it appears before the Pascal rule in the list of predefined
8325implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
8326Rules}).
8327
8328If you do not want an implicit rule to be used for a target that has no
8329commands, you can give that target empty commands by writing a semicolon
8330(@pxref{Empty Commands, ,Defining Empty Commands}).
8331
8332@node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
8333@section Catalogue of Implicit Rules
8334@cindex implicit rule, predefined
8335@cindex rule, implicit, predefined
8336
8337Here is a catalogue of predefined implicit rules which are always
8338available unless the makefile explicitly overrides or cancels them.
8339@xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
8340canceling or overriding an implicit rule.  The @samp{-r} or
8341@samp{--no-builtin-rules} option cancels all predefined rules.
8342
8343This manual only documents the default rules available on POSIX-based
8344operating systems.  Other operating systems, such as VMS, Windows,
8345OS/2, etc. may have different sets of default rules.  To see the full
8346list of default rules and variables available in your version of GNU
8347@code{make}, run @samp{make -p} in a directory with no makefile.
8348
8349Not all of these rules will always be defined, even when the @samp{-r}
8350option is not given.  Many of the predefined implicit rules are
8351implemented in @code{make} as suffix rules, so which ones will be
8352defined depends on the @dfn{suffix list} (the list of prerequisites of
8353the special target @code{.SUFFIXES}).  The default suffix list is:
8354@code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
8355@code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
8356@code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
8357@code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
8358@code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
8359@code{.sh}, @code{.elc}, @code{.el}.  All of the implicit rules
8360described below whose prerequisites have one of these suffixes are
8361actually suffix rules.  If you modify the suffix list, the only
8362predefined suffix rules in effect will be those named by one or two of
8363the suffixes that are on the list you specify; rules whose suffixes fail
8364to be on the list are disabled.  @xref{Suffix Rules, ,Old-Fashioned
8365Suffix Rules}, for full details on suffix rules.
8366
8367@table @asis
8368@item Compiling C programs
8369@cindex C, rule to compile
8370@pindex cc
8371@pindex gcc
8372@pindex .o
8373@pindex .c
8374@file{@var{n}.o} is made automatically from @file{@var{n}.c} with
8375a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
8376
8377@item Compiling C++ programs
8378@cindex C++, rule to compile
8379@pindex g++
8380@pindex .cc
8381@pindex .cpp
8382@pindex .C
8383@file{@var{n}.o} is made automatically from @file{@var{n}.cc},
8384@file{@var{n}.cpp}, or @file{@var{n}.C} with a command of the form
8385@samp{$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)}.  We encourage you to use the
8386suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill
8387
8388@item Compiling Pascal programs
8389@cindex Pascal, rule to compile
8390@pindex pc
8391@pindex .p
8392@file{@var{n}.o} is made automatically from @file{@var{n}.p}
8393with the command @samp{$(PC) -c $(PFLAGS)}.@refill
8394
8395@item Compiling Fortran and Ratfor programs
8396@cindex Fortran, rule to compile
8397@cindex Ratfor, rule to compile
8398@pindex f77
8399@pindex .f
8400@pindex .r
8401@pindex .F
8402@file{@var{n}.o} is made automatically from @file{@var{n}.r},
8403@file{@var{n}.F} or @file{@var{n}.f} by running the
8404Fortran compiler.  The precise command used is as follows:@refill
8405
8406@table @samp
8407@item .f
8408@samp{$(FC) -c $(FFLAGS)}.
8409@item .F
8410@samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}.
8411@item .r
8412@samp{$(FC) -c $(FFLAGS) $(RFLAGS)}.
8413@end table
8414
8415@item Preprocessing Fortran and Ratfor programs
8416@file{@var{n}.f} is made automatically from @file{@var{n}.r} or
8417@file{@var{n}.F}.  This rule runs just the preprocessor to convert a
8418Ratfor or preprocessable Fortran program into a strict Fortran
8419program.  The precise command used is as follows:@refill
8420
8421@table @samp
8422@item .F
8423@samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}.
8424@item .r
8425@samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
8426@end table
8427
8428@item Compiling Modula-2 programs
8429@cindex Modula-2, rule to compile
8430@pindex m2c
8431@pindex .sym
8432@pindex .def
8433@pindex .mod
8434@file{@var{n}.sym} is made from @file{@var{n}.def} with a command
8435of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}.  @file{@var{n}.o}
8436is made from @file{@var{n}.mod}; the form is:
8437@w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
8438
8439@need 1200
8440@item Assembling and preprocessing assembler programs
8441@cindex assembly, rule to compile
8442@pindex as
8443@pindex .s
8444@file{@var{n}.o} is made automatically from @file{@var{n}.s} by
8445running the assembler, @code{as}.  The precise command is
8446@samp{$(AS) $(ASFLAGS)}.@refill
8447
8448@pindex .S
8449@file{@var{n}.s} is made automatically from @file{@var{n}.S} by
8450running the C preprocessor, @code{cpp}.  The precise command is
8451@w{@samp{$(CPP) $(CPPFLAGS)}}.
8452
8453@item Linking a single object file
8454@cindex linking, predefined rule for
8455@pindex ld
8456@pindex .o
8457@file{@var{n}} is made automatically from @file{@var{n}.o} by running
8458the linker (usually called @code{ld}) via the C compiler.  The precise
8459command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}.
8460
8461This rule does the right thing for a simple program with only one
8462source file.  It will also do the right thing if there are multiple
8463object files (presumably coming from various other source files), one
8464of which has a name matching that of the executable file.  Thus,
8465
8466@example
8467x: y.o z.o
8468@end example
8469
8470@noindent
8471when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
8472
8473@example
8474@group
8475cc -c x.c -o x.o
8476cc -c y.c -o y.o
8477cc -c z.c -o z.o
8478cc x.o y.o z.o -o x
8479rm -f x.o
8480rm -f y.o
8481rm -f z.o
8482@end group
8483@end example
8484
8485@noindent
8486In more complicated cases, such as when there is no object file whose
8487name derives from the executable file name, you must write an explicit
8488command for linking.
8489
8490Each kind of file automatically made into @samp{.o} object files will
8491be automatically linked by using the compiler (@samp{$(CC)},
8492@samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
8493assemble @samp{.s} files) without the @samp{-c} option.  This could be
8494done by using the @samp{.o} object files as intermediates, but it is
8495faster to do the compiling and linking in one step, so that's how it's
8496done.@refill
8497
8498@item Yacc for C programs
8499@pindex yacc
8500@cindex Yacc, rule to run
8501@pindex .y
8502@file{@var{n}.c} is made automatically from @file{@var{n}.y} by
8503running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
8504
8505@item Lex for C programs
8506@pindex lex
8507@cindex Lex, rule to run
8508@pindex .l
8509@file{@var{n}.c} is made automatically from @file{@var{n}.l} by
8510running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
8511
8512@item Lex for Ratfor programs
8513@file{@var{n}.r} is made automatically from @file{@var{n}.l} by
8514running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
8515
8516The convention of using the same suffix @samp{.l} for all Lex files
8517regardless of whether they produce C code or Ratfor code makes it
8518impossible for @code{make} to determine automatically which of the two
8519languages you are using in any particular case.  If @code{make} is
8520called upon to remake an object file from a @samp{.l} file, it must
8521guess which compiler to use.  It will guess the C compiler, because
8522that is more common.  If you are using Ratfor, make sure @code{make}
8523knows this by mentioning @file{@var{n}.r} in the makefile.  Or, if you
8524are using Ratfor exclusively, with no C files, remove @samp{.c} from
8525the list of implicit rule suffixes with:@refill
8526
8527@example
8528@group
8529.SUFFIXES:
8530.SUFFIXES: .o .r .f .l @dots{}
8531@end group
8532@end example
8533
8534@item Making Lint Libraries from C, Yacc, or Lex programs
8535@pindex lint
8536@cindex @code{lint}, rule to run
8537@pindex .ln
8538@file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
8539The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
8540The same command is used on the C code produced from
8541@file{@var{n}.y} or @file{@var{n}.l}.@refill
8542
8543@item @TeX{} and Web
8544@cindex @TeX{}, rule to run
8545@cindex Web, rule to run
8546@pindex tex
8547@pindex cweave
8548@pindex weave
8549@pindex tangle
8550@pindex ctangle
8551@pindex .dvi
8552@pindex .tex
8553@pindex .web
8554@pindex .w
8555@pindex .ch
8556@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command
8557@samp{$(TEX)}.  @file{@var{n}.tex} is made from @file{@var{n}.web} with
8558@samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
8559it exists or can be made) with @samp{$(CWEAVE)}.  @file{@var{n}.p} is
8560made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
8561is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
8562or can be made) with @samp{$(CTANGLE)}.@refill
8563
8564@item Texinfo and Info
8565@cindex Texinfo, rule to format
8566@cindex Info, rule to format
8567@pindex texi2dvi
8568@pindex makeinfo
8569@pindex .texinfo
8570@pindex .info
8571@pindex .texi
8572@pindex .txinfo
8573@file{@var{n}.dvi} is made from @file{@var{n}.texinfo},
8574@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command
8575@w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}.  @file{@var{n}.info} is made from
8576@file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with
8577the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}.
8578
8579@item RCS
8580@cindex RCS, rule to extract from
8581@pindex co
8582@pindex ,v @r{(RCS file extension)}
8583Any file @file{@var{n}} is extracted if necessary from an RCS file
8584named either @file{@var{n},v} or @file{RCS/@var{n},v}.  The precise
8585command used is @w{@samp{$(CO) $(COFLAGS)}}.  @file{@var{n}} will not be
8586extracted from RCS if it already exists, even if the RCS file is
8587newer.  The rules for RCS are terminal
8588(@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
8589so RCS files cannot be generated from another source; they must
8590actually exist.@refill
8591
8592@item SCCS
8593@cindex SCCS, rule to extract from
8594@pindex get
8595@pindex s. @r{(SCCS file prefix)}
8596Any file @file{@var{n}} is extracted if necessary from an SCCS file
8597named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}.  The precise
8598command used is @w{@samp{$(GET) $(GFLAGS)}}.  The rules for SCCS are
8599terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
8600so SCCS files cannot be generated from another source; they must
8601actually exist.@refill
8602
8603@pindex .sh
8604For the benefit of SCCS, a file @file{@var{n}} is copied from
8605@file{@var{n}.sh} and made executable (by everyone).  This is for
8606shell scripts that are checked into SCCS.  Since RCS preserves the
8607execution permission of a file, you do not need to use this feature
8608with RCS.@refill
8609
8610We recommend that you avoid using of SCCS.  RCS is widely held to be
8611superior, and is also free.  By choosing free software in place of
8612comparable (or inferior) proprietary software, you support the free
8613software movement.
8614@end table
8615
8616Usually, you want to change only the variables listed in the table
8617above, which are documented in the following section.
8618
8619However, the commands in built-in implicit rules actually use
8620variables such as @code{COMPILE.c}, @code{LINK.p}, and
8621@code{PREPROCESS.S}, whose values contain the commands listed above.
8622
8623@code{make} follows the convention that the rule to compile a
8624@file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
8625Similarly, the rule to produce an executable from a @file{.@var{x}}
8626file uses @code{LINK.@var{x}}; and the rule to preprocess a
8627@file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
8628
8629@vindex OUTPUT_OPTION
8630Every rule that produces an object file uses the variable
8631@code{OUTPUT_OPTION}.  @code{make} defines this variable either to
8632contain @samp{-o $@@}, or to be empty, depending on a compile-time
8633option.  You need the @samp{-o} option to ensure that the output goes
8634into the right file when the source file is in a different directory,
8635as when using @code{VPATH} (@pxref{Directory Search}).  However,
8636compilers on some systems do not accept a @samp{-o} switch for object
8637files.  If you use such a system, and use @code{VPATH}, some
8638compilations will put their output in the wrong place.
8639A possible workaround for this problem is to give @code{OUTPUT_OPTION}
8640the value @w{@samp{; mv $*.o $@@}}.
8641
8642@node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
8643@section Variables Used by Implicit Rules
8644@cindex flags for compilers
8645
8646The commands in built-in implicit rules make liberal use of certain
8647predefined variables.  You can alter the values of these variables in
8648the makefile, with arguments to @code{make}, or in the environment to
8649alter how the implicit rules work without redefining the rules
8650themselves.  You can cancel all variables used by implicit rules with
8651the @samp{-R} or @samp{--no-builtin-variables} option.
8652
8653For example, the command used to compile a C source file actually says
8654@samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}.  The default values of the variables
8655used are @samp{cc} and nothing, resulting in the command @samp{cc -c}.  By
8656redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
8657used for all C compilations performed by the implicit rule.  By redefining
8658@samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
8659each compilation.  @emph{All} implicit rules that do C compilation use
8660@samp{$(CC)} to get the program name for the compiler and @emph{all}
8661include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
8662
8663The variables used in implicit rules fall into two classes: those that are
8664names of programs (like @code{CC}) and those that contain arguments for the
8665programs (like @code{CFLAGS}).  (The ``name of a program'' may also contain
8666some command arguments, but it must start with an actual executable program
8667name.)  If a variable value contains more than one argument, separate them
8668with spaces.
8669
8670The following tables describe of some of the more commonly-used predefined
8671variables.  This list is not exhaustive, and the default values shown here may
8672not be what are selected by @code{make} for your environment.  To see the
8673complete list of predefined variables for your instance of GNU @code{make} you
8674can run @samp{make -p} in a directory with no makefiles.
8675
8676Here is a table of some of the more common variables used as names of
8677programs in built-in rules:
8678makefiles.
8679
8680@table @code
8681@item AR
8682@vindex AR
8683Archive-maintaining program; default @samp{ar}.
8684@pindex ar
8685
8686@item AS
8687@vindex AS
8688Program for compiling assembly files; default @samp{as}.
8689@pindex as
8690
8691@item CC
8692@vindex CC
8693Program for compiling C programs; default @samp{cc}.
8694@pindex cc
8695
8696@item CO
8697@vindex CO
8698Program for checking out files from RCS; default @samp{co}.
8699@pindex cc
8700
8701@item CXX
8702@vindex CXX
8703Program for compiling C++ programs; default @samp{g++}.
8704@pindex g++
8705
8706@item CO
8707@vindex CO
8708Program for extracting a file from RCS; default @samp{co}.
8709@pindex co
8710
8711@item CPP
8712@vindex CPP
8713Program for running the C preprocessor, with results to standard output;
8714default @samp{$(CC) -E}.
8715
8716@item FC
8717@vindex FC
8718Program for compiling or preprocessing Fortran and Ratfor programs;
8719default @samp{f77}.
8720@pindex f77
8721
8722@item GET
8723@vindex GET
8724Program for extracting a file from SCCS; default @samp{get}.
8725@pindex get
8726
8727@item LEX
8728@vindex LEX
8729Program to use to turn Lex grammars into source code; default @samp{lex}.
8730@pindex lex
8731
8732@item YACC
8733@vindex YACC
8734Program to use to turn Yacc grammars into source code; default @samp{yacc}.
8735@pindex yacc
8736
8737@item LINT
8738@vindex LINT
8739Program to use to run lint on source code; default @samp{lint}.
8740@pindex lint
8741
8742@item M2C
8743@vindex M2C
8744Program to use to compile Modula-2 source code; default @samp{m2c}.
8745@pindex m2c
8746
8747@item PC
8748@vindex PC
8749Program for compiling Pascal programs; default @samp{pc}.
8750@pindex pc
8751
8752@item MAKEINFO
8753@vindex MAKEINFO
8754Program to convert a Texinfo source file into an Info file; default
8755@samp{makeinfo}.
8756@pindex makeinfo
8757
8758@item TEX
8759@vindex TEX
8760Program to make @TeX{} @sc{dvi} files from @TeX{} source;
8761default @samp{tex}.
8762@pindex tex
8763
8764@item TEXI2DVI
8765@vindex TEXI2DVI
8766Program to make @TeX{} @sc{dvi} files from Texinfo source;
8767default @samp{texi2dvi}.
8768@pindex texi2dvi
8769
8770@item WEAVE
8771@vindex WEAVE
8772Program to translate Web into @TeX{}; default @samp{weave}.
8773@pindex weave
8774
8775@item CWEAVE
8776@vindex CWEAVE
8777Program to translate C Web into @TeX{}; default @samp{cweave}.
8778@pindex cweave
8779
8780@item TANGLE
8781@vindex TANGLE
8782Program to translate Web into Pascal; default @samp{tangle}.
8783@pindex tangle
8784
8785@item CTANGLE
8786@vindex CTANGLE
8787Program to translate C Web into C; default @samp{ctangle}.
8788@pindex ctangle
8789
8790@item RM
8791@vindex RM
8792Command to remove a file; default @samp{rm -f}.
8793@pindex rm
8794@end table
8795
8796Here is a table of variables whose values are additional arguments for the
8797programs above.  The default values for all of these is the empty
8798string, unless otherwise noted.
8799
8800@table @code
8801@item ARFLAGS
8802@vindex ARFLAGS
8803Flags to give the archive-maintaining program; default @samp{rv}.
8804
8805@item ASFLAGS
8806@vindex ASFLAGS
8807Extra flags to give to the assembler (when explicitly
8808invoked on a @samp{.s} or @samp{.S} file).
8809
8810@item CFLAGS
8811@vindex CFLAGS
8812Extra flags to give to the C compiler.
8813
8814@item CXXFLAGS
8815@vindex CXXFLAGS
8816Extra flags to give to the C++ compiler.
8817
8818@item COFLAGS
8819@vindex COFLAGS
8820Extra flags to give to the RCS @code{co} program.
8821
8822@item CPPFLAGS
8823@vindex CPPFLAGS
8824Extra flags to give to the C preprocessor and programs
8825that use it (the C and Fortran compilers).
8826
8827@item FFLAGS
8828@vindex FFLAGS
8829Extra flags to give to the Fortran compiler.
8830
8831@item GFLAGS
8832@vindex GFLAGS
8833Extra flags to give to the SCCS @code{get} program.
8834
8835@item LDFLAGS
8836@vindex LDFLAGS
8837Extra flags to give to compilers when they are supposed to invoke the linker,
8838@samp{ld}.
8839
8840@item LFLAGS
8841@vindex LFLAGS
8842Extra flags to give to Lex.
8843
8844@item YFLAGS
8845@vindex YFLAGS
8846Extra flags to give to Yacc.
8847
8848@item PFLAGS
8849@vindex PFLAGS
8850Extra flags to give to the Pascal compiler.
8851
8852@item RFLAGS
8853@vindex RFLAGS
8854Extra flags to give to the Fortran compiler for Ratfor programs.
8855
8856@item LINTFLAGS
8857@vindex LINTFLAGS
8858Extra flags to give to lint.
8859@end table
8860
8861@node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
8862@section Chains of Implicit Rules
8863
8864@cindex chains of rules
8865@cindex rule, implicit, chains of
8866Sometimes a file can be made by a sequence of implicit rules.  For example,
8867a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
8868first Yacc and then @code{cc}.  Such a sequence is called a @dfn{chain}.
8869
8870If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
8871special searching is required: @code{make} finds that the object file can
8872be made by C compilation from @file{@var{n}.c}; later on, when considering
8873how to make @file{@var{n}.c}, the rule for running Yacc is
8874used.  Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
8875updated.@refill
8876
8877@cindex intermediate files
8878@cindex files, intermediate
8879However, even if @file{@var{n}.c} does not exist and is not mentioned,
8880@code{make} knows how to envision it as the missing link between
8881@file{@var{n}.o} and @file{@var{n}.y}!  In this case, @file{@var{n}.c} is
8882called an @dfn{intermediate file}.  Once @code{make} has decided to use the
8883intermediate file, it is entered in the data base as if it had been
8884mentioned in the makefile, along with the implicit rule that says how to
8885create it.@refill
8886
8887Intermediate files are remade using their rules just like all other
8888files.  But intermediate files are treated differently in two ways.
8889
8890The first difference is what happens if the intermediate file does not
8891exist.  If an ordinary file @var{b} does not exist, and @code{make}
8892considers a target that depends on @var{b}, it invariably creates
8893@var{b} and then updates the target from @var{b}.  But if @var{b} is an
8894intermediate file, then @code{make} can leave well enough alone.  It
8895won't bother updating @var{b}, or the ultimate target, unless some
8896prerequisite of @var{b} is newer than that target or there is some other
8897reason to update that target.
8898
8899The second difference is that if @code{make} @emph{does} create @var{b}
8900in order to update something else, it deletes @var{b} later on after it
8901is no longer needed.  Therefore, an intermediate file which did not
8902exist before @code{make} also does not exist after @code{make}.
8903@code{make} reports the deletion to you by printing a @samp{rm -f}
8904command showing which file it is deleting.
8905
8906Ordinarily, a file cannot be intermediate if it is mentioned in the
8907makefile as a target or prerequisite.  However, you can explicitly mark a
8908file as intermediate by listing it as a prerequisite of the special target
8909@code{.INTERMEDIATE}.  This takes effect even if the file is mentioned
8910explicitly in some other way.
8911
8912@cindex intermediate files, preserving
8913@cindex preserving intermediate files
8914@cindex secondary files
8915You can prevent automatic deletion of an intermediate file by marking it
8916as a @dfn{secondary} file.  To do this, list it as a prerequisite of the
8917special target @code{.SECONDARY}.  When a file is secondary, @code{make}
8918will not create the file merely because it does not already exist, but
8919@code{make} does not automatically delete the file.  Marking a file as
8920secondary also marks it as intermediate.
8921
8922You can list the target pattern of an implicit rule (such as @samp{%.o})
8923as a prerequisite of the special target @code{.PRECIOUS} to preserve
8924intermediate files made by implicit rules whose target patterns match
8925that file's name; see @ref{Interrupts}.@refill
8926@cindex preserving with @code{.PRECIOUS}
8927@cindex @code{.PRECIOUS} intermediate files
8928
8929A chain can involve more than two implicit rules.  For example, it is
8930possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
8931Yacc and @code{cc}.  Then both @file{foo.y} and @file{foo.c} are
8932intermediate files that are deleted at the end.@refill
8933
8934No single implicit rule can appear more than once in a chain.  This means
8935that @code{make} will not even consider such a ridiculous thing as making
8936@file{foo} from @file{foo.o.o} by running the linker twice.  This
8937constraint has the added benefit of preventing any infinite loop in the
8938search for an implicit rule chain.
8939
8940There are some special implicit rules to optimize certain cases that would
8941otherwise be handled by rule chains.  For example, making @file{foo} from
8942@file{foo.c} could be handled by compiling and linking with separate
8943chained rules, using @file{foo.o} as an intermediate file.  But what
8944actually happens is that a special rule for this case does the compilation
8945and linking with a single @code{cc} command.  The optimized rule is used in
8946preference to the step-by-step chain because it comes earlier in the
8947ordering of rules.
8948
8949@node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
8950@section Defining and Redefining Pattern Rules
8951
8952You define an implicit rule by writing a @dfn{pattern rule}.  A pattern
8953rule looks like an ordinary rule, except that its target contains the
8954character @samp{%} (exactly one of them).  The target is considered a
8955pattern for matching file names; the @samp{%} can match any nonempty
8956substring, while other characters match only themselves.  The prerequisites
8957likewise use @samp{%} to show how their names relate to the target name.
8958
8959Thus, a pattern rule @samp{%.o : %.c} says how to make any file
8960@file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
8961
8962Note that expansion using @samp{%} in pattern rules occurs
8963@strong{after} any variable or function expansions, which take place
8964when the makefile is read.  @xref{Using Variables, , How to Use
8965Variables}, and @ref{Functions, ,Functions for Transforming Text}.
8966
8967@menu
8968* Pattern Intro::               An introduction to pattern rules.
8969* Pattern Examples::            Examples of pattern rules.
8970* Automatic Variables::         How to use automatic variables in the
8971                                  commands of implicit rules.
8972* Pattern Match::               How patterns match.
8973* Match-Anything Rules::        Precautions you should take prior to
8974                                  defining rules that can match any
8975                                  target file whatever.
8976* Canceling Rules::             How to override or cancel built-in rules.
8977@end menu
8978
8979@node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules
8980@subsection Introduction to Pattern Rules
8981@cindex pattern rule
8982@cindex rule, pattern
8983
8984A pattern rule contains the character @samp{%} (exactly one of them)
8985in the target; otherwise, it looks exactly like an ordinary rule.  The
8986target is a pattern for matching file names; the @samp{%} matches any
8987nonempty substring, while other characters match only themselves.
8988@cindex target pattern, implicit
8989@cindex @code{%}, in pattern rules
8990
8991For example, @samp{%.c} as a pattern matches any file name that ends in
8992@samp{.c}.  @samp{s.%.c} as a pattern matches any file name that starts
8993with @samp{s.}, ends in @samp{.c} and is at least five characters long.
8994(There must be at least one character to match the @samp{%}.)  The substring
8995that the @samp{%} matches is called the @dfn{stem}.@refill
8996
8997@samp{%} in a prerequisite of a pattern rule stands for the same stem
8998that was matched by the @samp{%} in the target.  In order for the
8999pattern rule to apply, its target pattern must match the file name
9000under consideration and all of its prerequisites (after pattern
9001substitution) must name files that exist or can be made.  These files
9002become prerequisites of the target.
9003@cindex prerequisite pattern, implicit
9004
9005Thus, a rule of the form
9006
9007@example
9008%.o : %.c ; @var{command}@dots{}
9009@end example
9010
9011@noindent
9012specifies how to make a file @file{@var{n}.o}, with another file
9013@file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c}
9014exists or can be made.
9015
9016There may also be prerequisites that do not use @samp{%}; such a prerequisite
9017attaches to every file made by this pattern rule.  These unvarying
9018prerequisites are useful occasionally.
9019
9020A pattern rule need not have any prerequisites that contain @samp{%}, or
9021in fact any prerequisites at all.  Such a rule is effectively a general
9022wildcard.  It provides a way to make any file that matches the target
9023pattern.  @xref{Last Resort}.
9024
9025@c !!! The end of of this paragraph should be rewritten.  --bob
9026Pattern rules may have more than one target.  Unlike normal rules, this
9027does not act as many different rules with the same prerequisites and
9028commands.  If a pattern rule has multiple targets, @code{make} knows that
9029the rule's commands are responsible for making all of the targets.  The
9030commands are executed only once to make all the targets.  When searching
9031for a pattern rule to match a target, the target patterns of a rule other
9032than the one that matches the target in need of a rule are incidental:
9033@code{make} worries only about giving commands and prerequisites to the file
9034presently in question.  However, when this file's commands are run, the
9035other targets are marked as having been updated themselves.
9036@cindex multiple targets, in pattern rule
9037@cindex target, multiple in pattern rule
9038
9039The order in which pattern rules appear in the makefile is important
9040since this is the order in which they are considered.
9041Of equally applicable
9042rules, only the first one found is used.  The rules you write take precedence
9043over those that are built in.  Note however, that a rule whose
9044prerequisites actually exist or are mentioned always takes priority over a
9045rule with prerequisites that must be made by chaining other implicit rules.
9046@cindex pattern rules, order of
9047@cindex order of pattern rules
9048
9049@node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules
9050@subsection Pattern Rule Examples
9051
9052Here are some examples of pattern rules actually predefined in
9053@code{make}.  First, the rule that compiles @samp{.c} files into @samp{.o}
9054files:@refill
9055
9056@example
9057%.o : %.c
9058        $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
9059@end example
9060
9061@noindent
9062defines a rule that can make any file @file{@var{x}.o} from
9063@file{@var{x}.c}.  The command uses the automatic variables @samp{$@@} and
9064@samp{$<} to substitute the names of the target file and the source file
9065in each case where the rule applies (@pxref{Automatic Variables}).@refill
9066
9067Here is a second built-in rule:
9068
9069@example
9070% :: RCS/%,v
9071        $(CO) $(COFLAGS) $<
9072@end example
9073
9074@noindent
9075defines a rule that can make any file @file{@var{x}} whatsoever from a
9076corresponding file @file{@var{x},v} in the subdirectory @file{RCS}.  Since
9077the target is @samp{%}, this rule will apply to any file whatever, provided
9078the appropriate prerequisite file exists.  The double colon makes the rule
9079@dfn{terminal}, which means that its prerequisite may not be an intermediate
9080file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
9081
9082@need 500
9083This pattern rule has two targets:
9084
9085@example
9086@group
9087%.tab.c %.tab.h: %.y
9088        bison -d $<
9089@end group
9090@end example
9091
9092@noindent
9093@c The following paragraph is rewritten to avoid overfull hboxes
9094This tells @code{make} that the command @samp{bison -d @var{x}.y} will
9095make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}.  If the file
9096@file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
9097and the file @file{scan.o} depends on the file @file{parse.tab.h},
9098when @file{parse.y} is changed, the command @samp{bison -d parse.y}
9099will be executed only once, and the prerequisites of both
9100@file{parse.tab.o} and @file{scan.o} will be satisfied.  (Presumably
9101the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
9102and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
9103linked from @file{parse.tab.o}, @file{scan.o}, and its other
9104prerequisites, and it will execute happily ever after.)@refill
9105
9106@node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules
9107@subsection Automatic Variables
9108@cindex automatic variables
9109@cindex variables, automatic
9110@cindex variables, and implicit rule
9111
9112Suppose you are writing a pattern rule to compile a @samp{.c} file into a
9113@samp{.o} file: how do you write the @samp{cc} command so that it operates
9114on the right source file name?  You cannot write the name in the command,
9115because the name is different each time the implicit rule is applied.
9116
9117What you do is use a special feature of @code{make}, the @dfn{automatic
9118variables}.  These variables have values computed afresh for each rule that
9119is executed, based on the target and prerequisites of the rule.  In this
9120example, you would use @samp{$@@} for the object file name and @samp{$<}
9121for the source file name.
9122
9123@cindex automatic variables in prerequisites
9124@cindex prerequisites, and automatic variables
9125It's very important that you recognize the limited scope in which
9126automatic variable values are available: they only have values within
9127the command script.  In particular, you cannot use them anywhere
9128within the target list of a rule; they have no value there and will
9129expand to the empty string.  Also, they cannot be accessed directly
9130within the prerequisite list of a rule.  A common mistake is
9131attempting to use @code{$@@} within the prerequisites list; this will
9132not work.  However, there is a special feature of GNU @code{make},
9133secondary expansion (@pxref{Secondary Expansion}), which will allow
9134automatic variable values to be used in prerequisite lists.
9135
9136Here is a table of automatic variables:
9137
9138@table @code
9139@vindex $@@
9140@vindex @@ @r{(automatic variable)}
9141@item $@@
9142The file name of the target of the rule.  If the target is an archive
9143member, then @samp{$@@} is the name of the archive file.  In a pattern
9144rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
9145Pattern Rules}), @samp{$@@} is the name of whichever target caused the
9146rule's commands to be run.
9147
9148@vindex $%
9149@vindex % @r{(automatic variable)}
9150@item $%
9151The target member name, when the target is an archive member.
9152@xref{Archives}.  For example, if the target is @file{foo.a(bar.o)} then
9153@samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}.  @samp{$%} is
9154empty when the target is not an archive member.
9155
9156@vindex $<
9157@vindex < @r{(automatic variable)}
9158@item $<
9159The name of the first prerequisite.  If the target got its commands from
9160an implicit rule, this will be the first prerequisite added by the
9161implicit rule (@pxref{Implicit Rules}).
9162
9163@vindex $?
9164@vindex ? @r{(automatic variable)}
9165@item $?
9166The names of all the prerequisites that are newer than the target, with
9167spaces between them.  For prerequisites which are archive members, only
9168the member named is used (@pxref{Archives}).
9169@cindex prerequisites, list of changed
9170@cindex list of changed prerequisites
9171
9172@vindex $^
9173@vindex ^ @r{(automatic variable)}
9174@item $^
9175The names of all the prerequisites, with spaces between them.  For
9176prerequisites which are archive members, only the member named is used
9177(@pxref{Archives}).  A target has only one prerequisite on each other file
9178it depends on, no matter how many times each file is listed as a
9179prerequisite.  So if you list a prerequisite more than once for a target,
9180the value of @code{$^} contains just one copy of the name.  This list
9181does @strong{not} contain any of the order-only prerequisites; for those
9182see the @samp{$|} variable, below.
9183@cindex prerequisites, list of all
9184@cindex list of all prerequisites
9185
9186@vindex $+
9187@vindex + @r{(automatic variable)}
9188@item $+
9189This is like @samp{$^}, but prerequisites listed more than once are
9190duplicated in the order they were listed in the makefile.  This is
9191primarily useful for use in linking commands where it is meaningful to
9192repeat library file names in a particular order.
9193
9194@vindex $|
9195@vindex | @r{(automatic variable)}
9196@item $|
9197The names of all the order-only prerequisites, with spaces between
9198them.
9199
9200@vindex $*
9201@vindex * @r{(automatic variable)}
9202@item $*
9203The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
9204Patterns Match}).  If the target is @file{dir/a.foo.b} and the target
9205pattern is @file{a.%.b} then the stem is @file{dir/foo}.  The stem is
9206useful for constructing names of related files.@refill
9207@cindex stem, variable for
9208
9209In a static pattern rule, the stem is part of the file name that matched
9210the @samp{%} in the target pattern.
9211
9212In an explicit rule, there is no stem; so @samp{$*} cannot be determined
9213in that way.  Instead, if the target name ends with a recognized suffix
9214(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
9215the target name minus the suffix.  For example, if the target name is
9216@samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
9217suffix.  GNU @code{make} does this bizarre thing only for compatibility
9218with other implementations of @code{make}.  You should generally avoid
9219using @samp{$*} except in implicit rules or static pattern rules.@refill
9220
9221If the target name in an explicit rule does not end with a recognized
9222suffix, @samp{$*} is set to the empty string for that rule.
9223@end table
9224
9225@samp{$?} is useful even in explicit rules when you wish to operate on only
9226the prerequisites that have changed.  For example, suppose that an archive
9227named @file{lib} is supposed to contain copies of several object files.
9228This rule copies just the changed object files into the archive:
9229
9230@example
9231@group
9232lib: foo.o bar.o lose.o win.o
9233        ar r lib $?
9234@end group
9235@end example
9236
9237Of the variables listed above, four have values that are single file
9238names, and three have values that are lists of file names.  These seven
9239have variants that get just the file's directory name or just the file
9240name within the directory.  The variant variables' names are formed by
9241appending @samp{D} or @samp{F}, respectively.  These variants are
9242semi-obsolete in GNU @code{make} since the functions @code{dir} and
9243@code{notdir} can be used to get a similar effect (@pxref{File Name
9244Functions, , Functions for File Names}).  Note, however, that the
9245@samp{D} variants all omit the trailing slash which always appears in
9246the output of the @code{dir} function.  Here is a table of the variants:
9247
9248@table @samp
9249@vindex $(@@D)
9250@vindex @@D @r{(automatic variable)}
9251@item $(@@D)
9252The directory part of the file name of the target, with the trailing
9253slash removed.  If the value of @samp{$@@} is @file{dir/foo.o} then
9254@samp{$(@@D)} is @file{dir}.  This value is @file{.} if @samp{$@@} does
9255not contain a slash.
9256
9257@vindex $(@@F)
9258@vindex @@F @r{(automatic variable)}
9259@item $(@@F)
9260The file-within-directory part of the file name of the target.  If the
9261value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
9262@file{foo.o}.  @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
9263
9264@vindex $(*D)
9265@vindex *D @r{(automatic variable)}
9266@item $(*D)
9267@vindex $(*F)
9268@vindex *F @r{(automatic variable)}
9269@itemx $(*F)
9270The directory part and the file-within-directory
9271part of the stem; @file{dir} and @file{foo} in this example.
9272
9273@vindex $(%D)
9274@vindex %D @r{(automatic variable)}
9275@item $(%D)
9276@vindex $(%F)
9277@vindex %F @r{(automatic variable)}
9278@itemx $(%F)
9279The directory part and the file-within-directory part of the target
9280archive member name.  This makes sense only for archive member targets
9281of the form @file{@var{archive}(@var{member})} and is useful only when
9282@var{member} may contain a directory name.  (@xref{Archive Members,
9283,Archive Members as Targets}.)
9284
9285@vindex $(<D)
9286@vindex <D @r{(automatic variable)}
9287@item $(<D)
9288@vindex $(<F)
9289@vindex <F @r{(automatic variable)}
9290@itemx $(<F)
9291The directory part and the file-within-directory
9292part of the first prerequisite.
9293
9294@vindex $(^D)
9295@vindex ^D @r{(automatic variable)}
9296@item $(^D)
9297@vindex $(^F)
9298@vindex ^F @r{(automatic variable)}
9299@itemx $(^F)
9300Lists of the directory parts and the file-within-directory
9301parts of all prerequisites.
9302
9303@vindex $(+D)
9304@vindex +D @r{(automatic variable)}
9305@item $(+D)
9306@vindex $(+F)
9307@vindex +F @r{(automatic variable)}
9308@itemx $(+F)
9309Lists of the directory parts and the file-within-directory
9310parts of all prerequisites, including multiple instances of duplicated
9311prerequisites.
9312
9313@vindex $(?D)
9314@vindex ?D @r{(automatic variable)}
9315@item $(?D)
9316@vindex $(?F)
9317@vindex ?F @r{(automatic variable)}
9318@itemx $(?F)
9319Lists of the directory parts and the file-within-directory parts of
9320all prerequisites that are newer than the target.
9321@end table
9322
9323Note that we use a special stylistic convention when we talk about these
9324automatic variables; we write ``the value of @samp{$<}'', rather than
9325@w{``the variable @code{<}''} as we would write for ordinary variables
9326such as @code{objects} and @code{CFLAGS}.  We think this convention
9327looks more natural in this special case.  Please do not assume it has a
9328deep significance; @samp{$<} refers to the variable named @code{<} just
9329as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
9330You could just as well use @samp{$(<)} in place of @samp{$<}.
9331
9332@node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules
9333@subsection How Patterns Match
9334
9335@cindex stem
9336A target pattern is composed of a @samp{%} between a prefix and a suffix,
9337either or both of which may be empty.  The pattern matches a file name only
9338if the file name starts with the prefix and ends with the suffix, without
9339overlap.  The text between the prefix and the suffix is called the
9340@dfn{stem}.  Thus, when the pattern @samp{%.o} matches the file name
9341@file{test.o}, the stem is @samp{test}.  The pattern rule prerequisites are
9342turned into actual file names by substituting the stem for the character
9343@samp{%}.  Thus, if in the same example one of the prerequisites is written
9344as @samp{%.c}, it expands to @samp{test.c}.@refill
9345
9346When the target pattern does not contain a slash (and it usually does
9347not), directory names in the file names are removed from the file name
9348before it is compared with the target prefix and suffix.  After the
9349comparison of the file name to the target pattern, the directory
9350names, along with the slash that ends them, are added on to the
9351prerequisite file names generated from the pattern rule's prerequisite
9352patterns and the file name.  The directories are ignored only for the
9353purpose of finding an implicit rule to use, not in the application of
9354that rule.  Thus, @samp{e%t} matches the file name @file{src/eat},
9355with @samp{src/a} as the stem.  When prerequisites are turned into file
9356names, the directories from the stem are added at the front, while the
9357rest of the stem is substituted for the @samp{%}.  The stem
9358@samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name
9359@file{src/car}.@refill
9360
9361@node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
9362@subsection Match-Anything Pattern Rules
9363
9364@cindex match-anything rule
9365@cindex terminal rule
9366When a pattern rule's target is just @samp{%}, it matches any file name
9367whatever.  We call these rules @dfn{match-anything} rules.  They are very
9368useful, but it can take a lot of time for @code{make} to think about them,
9369because it must consider every such rule for each file name listed either
9370as a target or as a prerequisite.
9371
9372Suppose the makefile mentions @file{foo.c}.  For this target, @code{make}
9373would have to consider making it by linking an object file @file{foo.c.o},
9374or by C compilation-and-linking in one step from @file{foo.c.c}, or by
9375Pascal compilation-and-linking from @file{foo.c.p}, and many other
9376possibilities.
9377
9378We know these possibilities are ridiculous since @file{foo.c} is a C source
9379file, not an executable.  If @code{make} did consider these possibilities,
9380it would ultimately reject them, because files such as @file{foo.c.o} and
9381@file{foo.c.p} would not exist.  But these possibilities are so
9382numerous that @code{make} would run very slowly if it had to consider
9383them.@refill
9384
9385To gain speed, we have put various constraints on the way @code{make}
9386considers match-anything rules.  There are two different constraints that
9387can be applied, and each time you define a match-anything rule you must
9388choose one or the other for that rule.
9389
9390One choice is to mark the match-anything rule as @dfn{terminal} by defining
9391it with a double colon.  When a rule is terminal, it does not apply unless
9392its prerequisites actually exist.  Prerequisites that could be made with
9393other implicit rules are not good enough.  In other words, no further
9394chaining is allowed beyond a terminal rule.
9395
9396For example, the built-in implicit rules for extracting sources from RCS
9397and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
9398not exist, @code{make} will not even consider trying to make it as an
9399intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
9400RCS and SCCS files are generally ultimate source files, which should not be
9401remade from any other files; therefore, @code{make} can save time by not
9402looking for ways to remake them.@refill
9403
9404If you do not mark the match-anything rule as terminal, then it is
9405nonterminal.  A nonterminal match-anything rule cannot apply to a file name
9406that indicates a specific type of data.  A file name indicates a specific
9407type of data if some non-match-anything implicit rule target matches it.
9408
9409For example, the file name @file{foo.c} matches the target for the pattern
9410rule @samp{%.c : %.y} (the rule to run Yacc).  Regardless of whether this
9411rule is actually applicable (which happens only if there is a file
9412@file{foo.y}), the fact that its target matches is enough to prevent
9413consideration of any nonterminal match-anything rules for the file
9414@file{foo.c}.  Thus, @code{make} will not even consider trying to make
9415@file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
9416@file{foo.c.p}, etc.@refill
9417
9418The motivation for this constraint is that nonterminal match-anything
9419rules are used for making files containing specific types of data (such as
9420executable files) and a file name with a recognized suffix indicates some
9421other specific type of data (such as a C source file).
9422
9423Special built-in dummy pattern rules are provided solely to recognize
9424certain file names so that nonterminal match-anything rules will not be
9425considered.  These dummy rules have no prerequisites and no commands, and
9426they are ignored for all other purposes.  For example, the built-in
9427implicit rule
9428
9429@example
9430%.p :
9431@end example
9432
9433@noindent
9434exists to make sure that Pascal source files such as @file{foo.p} match a
9435specific target pattern and thereby prevent time from being wasted looking
9436for @file{foo.p.o} or @file{foo.p.c}.
9437
9438Dummy pattern rules such as the one for @samp{%.p} are made for every
9439suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
9440
9441@node Canceling Rules,  , Match-Anything Rules, Pattern Rules
9442@subsection Canceling Implicit Rules
9443
9444You can override a built-in implicit rule (or one you have defined
9445yourself) by defining a new pattern rule with the same target and
9446prerequisites, but different commands.  When the new rule is defined, the
9447built-in one is replaced.  The new rule's position in the sequence of
9448implicit rules is determined by where you write the new rule.
9449
9450You can cancel a built-in implicit rule by defining a pattern rule with the
9451same target and prerequisites, but no commands.  For example, the following
9452would cancel the rule that runs the assembler:
9453
9454@example
9455%.o : %.s
9456@end example
9457
9458@node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
9459@section Defining Last-Resort Default Rules
9460@cindex last-resort default rules
9461@cindex default rules, last-resort
9462
9463You can define a last-resort implicit rule by writing a terminal
9464match-anything pattern rule with no prerequisites (@pxref{Match-Anything
9465Rules}).  This is just like any other pattern rule; the only thing
9466special about it is that it will match any target.  So such a rule's
9467commands are used for all targets and prerequisites that have no commands
9468of their own and for which no other implicit rule applies.
9469
9470For example, when testing a makefile, you might not care if the source
9471files contain real data, only that they exist.  Then you might do this:
9472
9473@example
9474%::
9475        touch $@@
9476@end example
9477
9478@noindent
9479to cause all the source files needed (as prerequisites) to be created
9480automatically.
9481
9482@findex .DEFAULT
9483You can instead define commands to be used for targets for which there
9484are no rules at all, even ones which don't specify commands.  You do
9485this by writing a rule for the target @code{.DEFAULT}.  Such a rule's
9486commands are used for all prerequisites which do not appear as targets in
9487any explicit rule, and for which no implicit rule applies.  Naturally,
9488there is no @code{.DEFAULT} rule unless you write one.
9489
9490If you use @code{.DEFAULT} with no commands or prerequisites:
9491
9492@example
9493.DEFAULT:
9494@end example
9495
9496@noindent
9497the commands previously stored for @code{.DEFAULT} are cleared.
9498Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
9499
9500If you do not want a target to get the commands from a match-anything
9501pattern rule or @code{.DEFAULT}, but you also do not want any commands
9502to be run for the target, you can give it empty commands (@pxref{Empty
9503Commands, ,Defining Empty Commands}).@refill
9504
9505You can use a last-resort rule to override part of another makefile.
9506@xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
9507
9508@node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules
9509@section Old-Fashioned Suffix Rules
9510@cindex old-fashioned suffix rules
9511@cindex suffix rule
9512
9513@dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
9514@code{make}.  Suffix rules are obsolete because pattern rules are more
9515general and clearer.  They are supported in GNU @code{make} for
9516compatibility with old makefiles.  They come in two kinds:
9517@dfn{double-suffix} and @dfn{single-suffix}.@refill
9518
9519A double-suffix rule is defined by a pair of suffixes: the target suffix
9520and the source suffix.  It matches any file whose name ends with the
9521target suffix.  The corresponding implicit prerequisite is made by
9522replacing the target suffix with the source suffix in the file name.  A
9523two-suffix rule whose target and source suffixes are @samp{.o} and
9524@samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
9525
9526A single-suffix rule is defined by a single suffix, which is the source
9527suffix.  It matches any file name, and the corresponding implicit
9528prerequisite name is made by appending the source suffix.  A single-suffix
9529rule whose source suffix is @samp{.c} is equivalent to the pattern rule
9530@samp{% : %.c}.
9531
9532Suffix rule definitions are recognized by comparing each rule's target
9533against a defined list of known suffixes.  When @code{make} sees a rule
9534whose target is a known suffix, this rule is considered a single-suffix
9535rule.  When @code{make} sees a rule whose target is two known suffixes
9536concatenated, this rule is taken as a double-suffix rule.
9537
9538For example, @samp{.c} and @samp{.o} are both on the default list of
9539known suffixes.  Therefore, if you define a rule whose target is
9540@samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
9541suffix @samp{.c} and target suffix @samp{.o}.  Here is the old-fashioned
9542way to define the rule for compiling a C source file:@refill
9543
9544@example
9545.c.o:
9546        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
9547@end example
9548
9549Suffix rules cannot have any prerequisites of their own.  If they have any,
9550they are treated as normal files with funny names, not as suffix rules.
9551Thus, the rule:
9552
9553@example
9554.c.o: foo.h
9555        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
9556@end example
9557
9558@noindent
9559tells how to make the file @file{.c.o} from the prerequisite file
9560@file{foo.h}, and is not at all like the pattern rule:
9561
9562@example
9563%.o: %.c foo.h
9564        $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
9565@end example
9566
9567@noindent
9568which tells how to make @samp{.o} files from @samp{.c} files, and makes all
9569@samp{.o} files using this pattern rule also depend on @file{foo.h}.
9570
9571Suffix rules with no commands are also meaningless.  They do not remove
9572previous rules as do pattern rules with no commands (@pxref{Canceling
9573Rules, , Canceling Implicit Rules}).  They simply enter the suffix or pair of suffixes concatenated as
9574a target in the data base.@refill
9575
9576@findex .SUFFIXES
9577The known suffixes are simply the names of the prerequisites of the special
9578target @code{.SUFFIXES}.  You can add your own suffixes by writing a rule
9579for @code{.SUFFIXES} that adds more prerequisites, as in:
9580
9581@example
9582.SUFFIXES: .hack .win
9583@end example
9584
9585@noindent
9586which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
9587
9588If you wish to eliminate the default known suffixes instead of just adding
9589to them, write a rule for @code{.SUFFIXES} with no prerequisites.  By
9590special dispensation, this eliminates all existing prerequisites of
9591@code{.SUFFIXES}.  You can then write another rule to add the suffixes you
9592want.  For example,
9593
9594@example
9595@group
9596.SUFFIXES:            # @r{Delete the default suffixes}
9597.SUFFIXES: .c .o .h   # @r{Define our suffix list}
9598@end group
9599@end example
9600
9601The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
9602list of suffixes to be empty.
9603
9604@vindex SUFFIXES
9605The variable @code{SUFFIXES} is defined to the default list of suffixes
9606before @code{make} reads any makefiles.  You can change the list of suffixes
9607with a rule for the special target @code{.SUFFIXES}, but that does not alter
9608this variable.
9609
9610@node Implicit Rule Search,  , Suffix Rules, Implicit Rules
9611@section Implicit Rule Search Algorithm
9612@cindex implicit rule, search algorithm
9613@cindex search algorithm, implicit rule
9614
9615Here is the procedure @code{make} uses for searching for an implicit rule
9616for a target @var{t}.  This procedure is followed for each double-colon
9617rule with no commands, for each target of ordinary rules none of which have
9618commands, and for each prerequisite that is not the target of any rule.  It
9619is also followed recursively for prerequisites that come from implicit
9620rules, in the search for a chain of rules.
9621
9622Suffix rules are not mentioned in this algorithm because suffix rules are
9623converted to equivalent pattern rules once the makefiles have been read in.
9624
9625For an archive member target of the form
9626@samp{@var{archive}(@var{member})}, the following algorithm is run
9627twice, first using the entire target name @var{t}, and second using
9628@samp{(@var{member})} as the target @var{t} if the first run found no
9629rule.@refill
9630
9631@enumerate
9632@item
9633Split @var{t} into a directory part, called @var{d}, and the rest,
9634called @var{n}.  For example, if @var{t} is @samp{src/foo.o}, then
9635@var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
9636
9637@item
9638Make a list of all the pattern rules one of whose targets matches
9639@var{t} or @var{n}.  If the target pattern contains a slash, it is
9640matched against @var{t}; otherwise, against @var{n}.
9641
9642@item
9643If any rule in that list is @emph{not} a match-anything rule, then
9644remove all nonterminal match-anything rules from the list.
9645
9646@item
9647Remove from the list all rules with no commands.
9648
9649@item
9650For each pattern rule in the list:
9651
9652@enumerate a
9653@item
9654Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
9655matched by the @samp{%} in the target pattern.@refill
9656
9657@item
9658Compute the prerequisite names by substituting @var{s} for @samp{%}; if
9659the target pattern does not contain a slash, append @var{d} to
9660the front of each prerequisite name.@refill
9661
9662@item
9663Test whether all the prerequisites exist or ought to exist.  (If a
9664file name is mentioned in the makefile as a target or as an explicit
9665prerequisite, then we say it ought to exist.)
9666
9667If all prerequisites exist or ought to exist, or there are no prerequisites,
9668then this rule applies.
9669@end enumerate
9670
9671@item
9672If no pattern rule has been found so far, try harder.
9673For each pattern rule in the list:
9674
9675@enumerate a
9676@item
9677If the rule is terminal, ignore it and go on to the next rule.
9678
9679@item
9680Compute the prerequisite names as before.
9681
9682@item
9683Test whether all the prerequisites exist or ought to exist.
9684
9685@item
9686For each prerequisite that does not exist, follow this algorithm
9687recursively to see if the prerequisite can be made by an implicit
9688rule.
9689
9690@item
9691If all prerequisites exist, ought to exist, or can be
9692made by implicit rules, then this rule applies.
9693@end enumerate
9694
9695@item
9696If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
9697applies.  In that case, give @var{t} the same commands that
9698@code{.DEFAULT} has.  Otherwise, there are no commands for @var{t}.
9699@end enumerate
9700
9701Once a rule that applies has been found, for each target pattern of the
9702rule other than the one that matched @var{t} or @var{n}, the @samp{%} in
9703the pattern is replaced with @var{s} and the resultant file name is stored
9704until the commands to remake the target file @var{t} are executed.  After
9705these commands are executed, each of these stored file names are entered
9706into the data base and marked as having been updated and having the same
9707update status as the file @var{t}.
9708
9709When the commands of a pattern rule are executed for @var{t}, the automatic
9710variables are set corresponding to the target and prerequisites.
9711@xref{Automatic Variables}.
9712
9713@node Archives, Features, Implicit Rules, Top
9714@chapter Using @code{make} to Update Archive Files
9715@cindex archive
9716
9717@dfn{Archive files} are files containing named subfiles called
9718@dfn{members}; they are maintained with the program @code{ar} and their
9719main use is as subroutine libraries for linking.
9720
9721@menu
9722* Archive Members::             Archive members as targets.
9723* Archive Update::              The implicit rule for archive member targets.
9724* Archive Pitfalls::            Dangers to watch out for when using archives.
9725* Archive Suffix Rules::        You can write a special kind of suffix rule
9726                                  for updating archives.
9727@end menu
9728
9729@node Archive Members, Archive Update, Archives, Archives
9730@section Archive Members as Targets
9731@cindex archive member targets
9732
9733An individual member of an archive file can be used as a target or
9734prerequisite in @code{make}.  You specify the member named @var{member} in
9735archive file @var{archive} as follows:
9736
9737@example
9738@var{archive}(@var{member})
9739@end example
9740
9741@noindent
9742This construct is available only in targets and prerequisites, not in
9743commands!  Most programs that you might use in commands do not support this
9744syntax and cannot act directly on archive members.  Only @code{ar} and
9745other programs specifically designed to operate on archives can do so.
9746Therefore, valid commands to update an archive member target probably must
9747use @code{ar}.  For example, this rule says to create a member
9748@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
9749
9750@example
9751foolib(hack.o) : hack.o
9752        ar cr foolib hack.o
9753@end example
9754
9755In fact, nearly all archive member targets are updated in just this way
9756and there is an implicit rule to do it for you.  @strong{Please note:} The
9757@samp{c} flag to @code{ar} is required if the archive file does not
9758already exist.
9759
9760To specify several members in the same archive, you can write all the
9761member names together between the parentheses.  For example:
9762
9763@example
9764foolib(hack.o kludge.o)
9765@end example
9766
9767@noindent
9768is equivalent to:
9769
9770@example
9771foolib(hack.o) foolib(kludge.o)
9772@end example
9773
9774@cindex wildcard, in archive member
9775You can also use shell-style wildcards in an archive member reference.
9776@xref{Wildcards, ,Using Wildcard Characters in File Names}.  For
9777example, @w{@samp{foolib(*.o)}} expands to all existing members of the
9778@file{foolib} archive whose names end in @samp{.o}; perhaps
9779@samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
9780
9781@node Archive Update, Archive Pitfalls, Archive Members, Archives
9782@section Implicit Rule for Archive Member Targets
9783
9784Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
9785member named @var{m} in the archive file @var{a}.
9786
9787When @code{make} looks for an implicit rule for such a target, as a special
9788feature it considers implicit rules that match @file{(@var{m})}, as well as
9789those that match the actual target @file{@var{a}(@var{m})}.
9790
9791This causes one special rule whose target is @file{(%)} to match.  This
9792rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
9793into the archive.  For example, it will update the archive member target
9794@file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
9795archive @file{foo.a} as a @emph{member} named @file{bar.o}.
9796
9797When this rule is chained with others, the result is very powerful.
9798Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
9799@samp{(} and @samp{)} from being interpreted specially by the shell) in
9800the presence of a file @file{bar.c} is enough to cause the following
9801commands to be run, even without a makefile:
9802
9803@example
9804cc -c bar.c -o bar.o
9805ar r foo.a bar.o
9806rm -f bar.o
9807@end example
9808
9809@noindent
9810Here @code{make} has envisioned the file @file{bar.o} as an intermediate
9811file.  @xref{Chained Rules, ,Chains of Implicit Rules}.
9812
9813Implicit rules such as this one are written using the automatic variable
9814@samp{$%}.  @xref{Automatic Variables}.
9815
9816An archive member name in an archive cannot contain a directory name, but
9817it may be useful in a makefile to pretend that it does.  If you write an
9818archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
9819automatic updating with this command:
9820
9821@example
9822ar r foo.a dir/file.o
9823@end example
9824
9825@noindent
9826which has the effect of copying the file @file{dir/file.o} into a member
9827named @file{file.o}.  In connection with such usage, the automatic variables
9828@code{%D} and @code{%F} may be useful.
9829
9830@menu
9831* Archive Symbols::             How to update archive symbol directories.
9832@end menu
9833
9834@node Archive Symbols,  , Archive Update, Archive Update
9835@subsection Updating Archive Symbol Directories
9836@cindex @code{__.SYMDEF}
9837@cindex updating archive symbol directories
9838@cindex archive symbol directory updating
9839@cindex symbol directories, updating archive
9840@cindex directories, updating archive symbol
9841
9842An archive file that is used as a library usually contains a special member
9843named @file{__.SYMDEF} that contains a directory of the external symbol
9844names defined by all the other members.  After you update any other
9845members, you need to update @file{__.SYMDEF} so that it will summarize the
9846other members properly.  This is done by running the @code{ranlib} program:
9847
9848@example
9849ranlib @var{archivefile}
9850@end example
9851
9852Normally you would put this command in the rule for the archive file,
9853and make all the members of the archive file prerequisites of that rule.
9854For example,
9855
9856@example
9857libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
9858        ranlib libfoo.a
9859@end example
9860
9861@noindent
9862The effect of this is to update archive members @file{x.o}, @file{y.o},
9863etc., and then update the symbol directory member @file{__.SYMDEF} by
9864running @code{ranlib}.  The rules for updating the members are not shown
9865here; most likely you can omit them and use the implicit rule which copies
9866files into the archive, as described in the preceding section.
9867
9868This is not necessary when using the GNU @code{ar} program, which
9869updates the @file{__.SYMDEF} member automatically.
9870
9871@node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives
9872@section Dangers When Using Archives
9873@cindex archive, and parallel execution
9874@cindex parallel execution, and archive update
9875@cindex archive, and @code{-j}
9876@cindex @code{-j}, and archive update
9877
9878It is important to be careful when using parallel execution (the
9879@code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives.
9880If multiple @code{ar} commands run at the same time on the same archive
9881file, they will not know about each other and can corrupt the file.
9882
9883Possibly a future version of @code{make} will provide a mechanism to
9884circumvent this problem by serializing all commands that operate on the
9885same archive file.  But for the time being, you must either write your
9886makefiles to avoid this problem in some other way, or not use @code{-j}.
9887
9888@node Archive Suffix Rules,  , Archive Pitfalls, Archives
9889@section Suffix Rules for Archive Files
9890@cindex suffix rule, for archive
9891@cindex archive, suffix rule for
9892@cindex library archive, suffix rule for
9893@cindex @code{.a} (archives)
9894
9895You can write a special kind of suffix rule for dealing with archive
9896files.  @xref{Suffix Rules}, for a full explanation of suffix rules.
9897Archive suffix rules are obsolete in GNU @code{make}, because pattern
9898rules for archives are a more general mechanism (@pxref{Archive
9899Update}).  But they are retained for compatibility with other
9900@code{make}s.
9901
9902To write a suffix rule for archives, you simply write a suffix rule
9903using the target suffix @samp{.a} (the usual suffix for archive files).
9904For example, here is the old-fashioned suffix rule to update a library
9905archive from C source files:
9906
9907@example
9908@group
9909.c.a:
9910        $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
9911        $(AR) r $@@ $*.o
9912        $(RM) $*.o
9913@end group
9914@end example
9915
9916@noindent
9917This works just as if you had written the pattern rule:
9918
9919@example
9920@group
9921(%.o): %.c
9922        $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
9923        $(AR) r $@@ $*.o
9924        $(RM) $*.o
9925@end group
9926@end example
9927
9928In fact, this is just what @code{make} does when it sees a suffix rule
9929with @samp{.a} as the target suffix.  Any double-suffix rule
9930@w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
9931pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}.
9932
9933Since you might want to use @samp{.a} as the suffix for some other kind
9934of file, @code{make} also converts archive suffix rules to pattern rules
9935in the normal way (@pxref{Suffix Rules}).  Thus a double-suffix rule
9936@w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
9937@w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
9938
9939@node Features, Missing, Archives, Top
9940@chapter Features of GNU @code{make}
9941@cindex features of GNU @code{make}
9942@cindex portability
9943@cindex compatibility
9944
9945Here is a summary of the features of GNU @code{make}, for comparison
9946with and credit to other versions of @code{make}.  We consider the
9947features of @code{make} in 4.2 BSD systems as a baseline.  If you are
9948concerned with writing portable makefiles, you should not use the
9949features of @code{make} listed here, nor the ones in @ref{Missing}.
9950
9951Many features come from the version of @code{make} in System V.
9952
9953@itemize @bullet
9954@item
9955The @code{VPATH} variable and its special meaning.
9956@xref{Directory Search, , Searching Directories for Prerequisites}.
9957This feature exists in System V @code{make}, but is undocumented.
9958It is documented in 4.3 BSD @code{make} (which says it mimics System V's
9959@code{VPATH} feature).@refill
9960
9961@item
9962Included makefiles.  @xref{Include, ,Including Other Makefiles}.
9963Allowing multiple files to be included with a single directive is a GNU
9964extension.
9965
9966@item
9967Variables are read from and communicated via the environment.
9968@xref{Environment, ,Variables from the Environment}.
9969
9970@item
9971Options passed through the variable @code{MAKEFLAGS} to recursive
9972invocations of @code{make}.
9973@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
9974
9975@item
9976The automatic variable @code{$%} is set to the member name
9977in an archive reference.  @xref{Automatic Variables}.
9978
9979@item
9980The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
9981and @code{$?} have corresponding forms like @code{$(@@F)} and
9982@code{$(@@D)}.  We have generalized this to @code{$^} as an obvious
9983extension.  @xref{Automatic Variables}.@refill
9984
9985@item
9986Substitution variable references.
9987@xref{Reference, ,Basics of Variable References}.
9988
9989@item
9990The command-line options @samp{-b} and @samp{-m}, accepted and
9991ignored.  In System V @code{make}, these options actually do something.
9992
9993@item
9994Execution of recursive commands to run @code{make} via the variable
9995@code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
9996@xref{Recursion, ,Recursive Use of @code{make}}.
9997
9998@item
9999Support for suffix @samp{.a} in suffix rules.  @xref{Archive Suffix
10000Rules}.  This feature is obsolete in GNU @code{make}, because the
10001general feature of rule chaining (@pxref{Chained Rules, ,Chains of
10002Implicit Rules}) allows one pattern rule for installing members in an
10003archive (@pxref{Archive Update}) to be sufficient.
10004
10005@item
10006The arrangement of lines and backslash-newline combinations in
10007commands is retained when the commands are printed, so they appear as
10008they do in the makefile, except for the stripping of initial
10009whitespace.
10010@end itemize
10011
10012The following features were inspired by various other versions of
10013@code{make}.  In some cases it is unclear exactly which versions inspired
10014which others.
10015
10016@itemize @bullet
10017@item
10018Pattern rules using @samp{%}.
10019This has been implemented in several versions of @code{make}.
10020We're not sure who invented it first, but it's been spread around a bit.
10021@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
10022
10023@item
10024Rule chaining and implicit intermediate files.
10025This was implemented by Stu Feldman in his version of @code{make}
10026for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
10027AT&T Bell Labs in his @code{mk} program (where he terms it
10028``transitive closure'').  We do not really know if
10029we got this from either of them or thought it up ourselves at the
10030same time.  @xref{Chained Rules, ,Chains of Implicit Rules}.
10031
10032@item
10033The automatic variable @code{$^} containing a list of all prerequisites
10034of the current target.  We did not invent this, but we have no idea who
10035did.  @xref{Automatic Variables}.  The automatic variable
10036@code{$+} is a simple extension of @code{$^}.
10037
10038@item
10039The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
10040invented by Andrew Hume in @code{mk}.
10041@xref{Instead of Execution, ,Instead of Executing the Commands}.
10042
10043@item
10044The concept of doing several things at once (parallelism) exists in
10045many incarnations of @code{make} and similar programs, though not in the
10046System V or BSD implementations.  @xref{Execution, ,Command Execution}.
10047
10048@item
10049Modified variable references using pattern substitution come from
10050SunOS 4.  @xref{Reference, ,Basics of Variable References}.
10051This functionality was provided in GNU @code{make} by the
10052@code{patsubst} function before the alternate syntax was implemented
10053for compatibility with SunOS 4.  It is not altogether clear who
10054inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
100554 was released.@refill
10056
10057@item
10058The special significance of @samp{+} characters preceding command lines
10059(@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
10060mandated by
10061@cite{IEEE Standard 1003.2-1992} (POSIX.2).
10062
10063@item
10064The @samp{+=} syntax to append to the value of a variable comes from SunOS
100654 @code{make}.  @xref{Appending, , Appending More Text to Variables}.
10066
10067@item
10068The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
10069multiple members in a single archive file comes from SunOS 4 @code{make}.
10070@xref{Archive Members}.
10071
10072@item
10073The @code{-include} directive to include makefiles with no error for a
10074nonexistent file comes from SunOS 4 @code{make}.  (But note that SunOS 4
10075@code{make} does not allow multiple makefiles to be specified in one
10076@code{-include} directive.)  The same feature appears with the name
10077@code{sinclude} in SGI @code{make} and perhaps others.
10078@end itemize
10079
10080The remaining features are inventions new in GNU @code{make}:
10081
10082@itemize @bullet
10083@item
10084Use the @samp{-v} or @samp{--version} option to print version and
10085copyright information.
10086
10087@item
10088Use the @samp{-h} or @samp{--help} option to summarize the options to
10089@code{make}.
10090
10091@item
10092Simply-expanded variables.  @xref{Flavors, ,The Two Flavors of Variables}.
10093
10094@item
10095Pass command-line variable assignments automatically through the
10096variable @code{MAKE} to recursive @code{make} invocations.
10097@xref{Recursion, ,Recursive Use of @code{make}}.
10098
10099@item
10100Use the @samp{-C} or @samp{--directory} command option to change
10101directory.  @xref{Options Summary, ,Summary of Options}.
10102
10103@item
10104Make verbatim variable definitions with @code{define}.
10105@xref{Defining, ,Defining Variables Verbatim}.
10106
10107@item
10108Declare phony targets with the special target @code{.PHONY}.
10109
10110Andrew Hume of AT&T Bell Labs implemented a similar feature with a
10111different syntax in his @code{mk} program.  This seems to be a case of
10112parallel discovery.  @xref{Phony Targets, ,Phony Targets}.
10113
10114@item
10115Manipulate text by calling functions.
10116@xref{Functions, ,Functions for Transforming Text}.
10117
10118@item
10119Use the @samp{-o} or @samp{--old-file}
10120option to pretend a file's modification-time is old.
10121@xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
10122
10123@item
10124Conditional execution.
10125
10126This feature has been implemented numerous times in various versions
10127of @code{make}; it seems a natural extension derived from the features
10128of the C preprocessor and similar macro languages and is not a
10129revolutionary concept.  @xref{Conditionals, ,Conditional Parts of Makefiles}.
10130
10131@item
10132Specify a search path for included makefiles.
10133@xref{Include, ,Including Other Makefiles}.
10134
10135@item
10136Specify extra makefiles to read with an environment variable.
10137@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
10138
10139@item
10140Strip leading sequences of @samp{./} from file names, so that
10141@file{./@var{file}} and @file{@var{file}} are considered to be the
10142same file.@refill
10143
10144@item
10145Use a special search method for library prerequisites written in the
10146form @samp{-l@var{name}}.
10147@xref{Libraries/Search, ,Directory Search for Link Libraries}.
10148
10149@item
10150Allow suffixes for suffix rules
10151(@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
10152characters.  In other versions of @code{make}, they must begin with
10153@samp{.} and not contain any @samp{/} characters.
10154
10155@item
10156Keep track of the current level of @code{make} recursion using the
10157variable @code{MAKELEVEL}.  @xref{Recursion, ,Recursive Use of @code{make}}.
10158
10159@item
10160Provide any goals given on the command line in the variable
10161@code{MAKECMDGOALS}.  @xref{Goals, ,Arguments to Specify the Goals}.
10162
10163@item
10164Specify static pattern rules.  @xref{Static Pattern, ,Static Pattern Rules}.
10165
10166@item
10167Provide selective @code{vpath} search.
10168@xref{Directory Search, ,Searching Directories for Prerequisites}.
10169
10170@item
10171Provide computed variable references.
10172@xref{Reference, ,Basics of Variable References}.
10173
10174@item
10175Update makefiles.  @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
10176System V @code{make} has a very, very limited form of this
10177functionality in that it will check out SCCS files for makefiles.
10178
10179@item
10180Various new built-in implicit rules.
10181@xref{Catalogue of Rules, ,Catalogue of Implicit Rules}.
10182
10183@item
10184The built-in variable @samp{MAKE_VERSION} gives the version number of
10185@code{make}.
10186@vindex MAKE_VERSION
10187@end itemize
10188
10189@node Missing, Makefile Conventions, Features, Top
10190@chapter Incompatibilities and Missing Features
10191@cindex incompatibilities
10192@cindex missing features
10193@cindex features, missing
10194
10195The @code{make} programs in various other systems support a few features
10196that are not implemented in GNU @code{make}.  The POSIX.2 standard
10197(@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
10198require any of these features.@refill
10199
10200@itemize @bullet
10201@item
10202A target of the form @samp{@var{file}((@var{entry}))} stands for a member
10203of archive file @var{file}.  The member is chosen, not by name, but by
10204being an object file which defines the linker symbol @var{entry}.@refill
10205
10206This feature was not put into GNU @code{make} because of the
10207nonmodularity of putting knowledge into @code{make} of the internal
10208format of archive file symbol tables.
10209@xref{Archive Symbols, ,Updating Archive Symbol Directories}.
10210
10211@item
10212Suffixes (used in suffix rules) that end with the character @samp{~}
10213have a special meaning to System V @code{make};
10214they refer to the SCCS file that corresponds
10215to the file one would get without the @samp{~}.  For example, the
10216suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
10217the SCCS file @file{s.@var{n}.c}.  For complete coverage, a whole
10218series of such suffix rules is required.
10219@xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
10220
10221In GNU @code{make}, this entire series of cases is handled by two
10222pattern rules for extraction from SCCS, in combination with the
10223general feature of rule chaining.
10224@xref{Chained Rules, ,Chains of Implicit Rules}.
10225
10226@item
10227In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
10228(@pxref{Directory Search, ,Searching Directories for Prerequisites}) have their names changed inside command
10229strings.  We feel it is much cleaner to always use automatic variables
10230and thus make this feature obsolete.@refill
10231
10232@item
10233In some Unix @code{make}s, the automatic variable @code{$*} appearing in
10234the prerequisites of a rule has the amazingly strange ``feature'' of
10235expanding to the full name of the @emph{target of that rule}.  We cannot
10236imagine what went on in the minds of Unix @code{make} developers to do
10237this; it is utterly inconsistent with the normal definition of @code{$*}.
10238@vindex * @r{(automatic variable), unsupported bizarre usage}
10239
10240@item
10241In some Unix @code{make}s, implicit rule search
10242(@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for
10243@emph{all} targets, not just those without commands.  This means you can
10244do:@refill
10245
10246@example
10247@group
10248foo.o:
10249        cc -c foo.c
10250@end group
10251@end example
10252
10253@noindent
10254and Unix @code{make} will intuit that @file{foo.o} depends on
10255@file{foo.c}.@refill
10256
10257We feel that such usage is broken.  The prerequisite properties of
10258@code{make} are well-defined (for GNU @code{make}, at least),
10259and doing such a thing simply does not fit the model.@refill
10260
10261@item
10262GNU @code{make} does not include any built-in implicit rules for
10263compiling or preprocessing EFL programs.  If we hear of anyone who is
10264using EFL, we will gladly add them.
10265
10266@item
10267It appears that in SVR4 @code{make}, a suffix rule can be specified with
10268no commands, and it is treated as if it had empty commands
10269(@pxref{Empty Commands}).  For example:
10270
10271@example
10272.c.a:
10273@end example
10274
10275@noindent
10276will override the built-in @file{.c.a} suffix rule.
10277
10278We feel that it is cleaner for a rule without commands to always simply
10279add to the prerequisite list for the target.  The above example can be
10280easily rewritten to get the desired behavior in GNU @code{make}:
10281
10282@example
10283.c.a: ;
10284@end example
10285
10286@item
10287Some versions of @code{make} invoke the shell with the @samp{-e} flag,
10288except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
10289Program}).  The @samp{-e} flag tells the shell to exit as soon as any
10290program it runs returns a nonzero status.  We feel it is cleaner to
10291write each shell command line to stand on its own and not require this
10292special treatment.
10293@end itemize
10294
10295@comment The makefile standards are in a separate file that is also
10296@comment included by standards.texi.
10297@include make-stds.texi
10298
10299@node Quick Reference, Error Messages, Makefile Conventions, Top
10300@appendix Quick Reference
10301
10302This appendix summarizes the directives, text manipulation functions,
10303and special variables which GNU @code{make} understands.
10304@xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
10305and @ref{Options Summary, ,Summary of Options},
10306for other summaries.
10307
10308Here is a summary of the directives GNU @code{make} recognizes:
10309
10310@table @code
10311@item define @var{variable}
10312@itemx endef
10313
10314Define a multi-line, recursively-expanded variable.@*
10315@xref{Sequences}.
10316
10317@item ifdef @var{variable}
10318@itemx ifndef @var{variable}
10319@itemx ifeq (@var{a},@var{b})
10320@itemx ifeq "@var{a}" "@var{b}"
10321@itemx ifeq '@var{a}' '@var{b}'
10322@itemx ifneq (@var{a},@var{b})
10323@itemx ifneq "@var{a}" "@var{b}"
10324@itemx ifneq '@var{a}' '@var{b}'
10325@itemx else
10326@itemx endif
10327
10328Conditionally evaluate part of the makefile.@*
10329@xref{Conditionals}.
10330
10331@item include @var{file}
10332@itemx -include @var{file}
10333@itemx sinclude @var{file}
10334
10335Include another makefile.@*
10336@xref{Include, ,Including Other Makefiles}.
10337
10338@item override @var{variable} = @var{value}
10339@itemx override @var{variable} := @var{value}
10340@itemx override @var{variable} += @var{value}
10341@itemx override @var{variable} ?= @var{value}
10342@itemx override define @var{variable}
10343@itemx endef
10344
10345Define a variable, overriding any previous definition, even one from
10346the command line.@*
10347@xref{Override Directive, ,The @code{override} Directive}.
10348
10349@item export
10350
10351Tell @code{make} to export all variables to child processes by default.@*
10352@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
10353
10354@item export @var{variable}
10355@itemx export @var{variable} = @var{value}
10356@itemx export @var{variable} := @var{value}
10357@itemx export @var{variable} += @var{value}
10358@itemx export @var{variable} ?= @var{value}
10359@itemx unexport @var{variable}
10360Tell @code{make} whether or not to export a particular variable to child
10361processes.@*
10362@xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
10363
10364@item vpath @var{pattern} @var{path}
10365Specify a search path for files matching a @samp{%} pattern.@*
10366@xref{Selective Search, , The @code{vpath} Directive}.
10367
10368@item vpath @var{pattern}
10369Remove all search paths previously specified for @var{pattern}.
10370
10371@item vpath
10372Remove all search paths previously specified in any @code{vpath}
10373directive.
10374@end table
10375
10376Here is a summary of the built-in functions (@pxref{Functions}):
10377
10378@table @code
10379@item $(subst @var{from},@var{to},@var{text})
10380Replace @var{from} with @var{to} in @var{text}.@*
10381@xref{Text Functions, , Functions for String Substitution and Analysis}.
10382
10383@item $(patsubst @var{pattern},@var{replacement},@var{text})
10384Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
10385@xref{Text Functions, , Functions for String Substitution and Analysis}.
10386
10387@item $(strip @var{string})
10388Remove excess whitespace characters from @var{string}.@*
10389@xref{Text Functions, , Functions for String Substitution and Analysis}.
10390
10391@item $(findstring @var{find},@var{text})
10392Locate @var{find} in @var{text}.@*
10393@xref{Text Functions, , Functions for String Substitution and Analysis}.
10394
10395@item $(filter @var{pattern}@dots{},@var{text})
10396Select words in @var{text} that match one of the @var{pattern} words.@*
10397@xref{Text Functions, , Functions for String Substitution and Analysis}.
10398
10399@item $(filter-out @var{pattern}@dots{},@var{text})
10400Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
10401@xref{Text Functions, , Functions for String Substitution and Analysis}.
10402
10403@item $(sort @var{list})
10404Sort the words in @var{list} lexicographically, removing duplicates.@*
10405@xref{Text Functions, , Functions for String Substitution and Analysis}.
10406
10407@item $(word @var{n},@var{text})
10408Extract the @var{n}th word (one-origin) of @var{text}.@*
10409@xref{Text Functions, , Functions for String Substitution and Analysis}.
10410
10411@item $(words @var{text})
10412Count the number of words in @var{text}.@*
10413@xref{Text Functions, , Functions for String Substitution and Analysis}.
10414
10415@item $(wordlist @var{s},@var{e},@var{text})
10416Returns the list of words in @var{text} from @var{s} to @var{e}.@*
10417@xref{Text Functions, , Functions for String Substitution and Analysis}.
10418
10419@item $(firstword @var{names}@dots{})
10420Extract the first word of @var{names}.@*
10421@xref{Text Functions, , Functions for String Substitution and Analysis}.
10422
10423@item $(lastword @var{names}@dots{})
10424Extract the last word of @var{names}.@*
10425@xref{Text Functions, , Functions for String Substitution and Analysis}.
10426
10427@item $(dir @var{names}@dots{})
10428Extract the directory part of each file name.@*
10429@xref{File Name Functions, ,Functions for File Names}.
10430
10431@item $(notdir @var{names}@dots{})
10432Extract the non-directory part of each file name.@*
10433@xref{File Name Functions, ,Functions for File Names}.
10434
10435@item $(suffix @var{names}@dots{})
10436Extract the suffix (the last @samp{.} and following characters) of each file name.@*
10437@xref{File Name Functions, ,Functions for File Names}.
10438
10439@item $(basename @var{names}@dots{})
10440Extract the base name (name without suffix) of each file name.@*
10441@xref{File Name Functions, ,Functions for File Names}.
10442
10443@item $(addsuffix @var{suffix},@var{names}@dots{})
10444Append @var{suffix} to each word in @var{names}.@*
10445@xref{File Name Functions, ,Functions for File Names}.
10446
10447@item $(addprefix @var{prefix},@var{names}@dots{})
10448Prepend @var{prefix} to each word in @var{names}.@*
10449@xref{File Name Functions, ,Functions for File Names}.
10450
10451@item $(join @var{list1},@var{list2})
10452Join two parallel lists of words.@*
10453@xref{File Name Functions, ,Functions for File Names}.
10454
10455@item $(wildcard @var{pattern}@dots{})
10456Find file names matching a shell file name pattern (@emph{not} a
10457@samp{%} pattern).@*
10458@xref{Wildcard Function, ,The Function @code{wildcard}}.
10459
10460@item $(realpath @var{names}@dots{})
10461For each file name in @var{names}, expand to an absolute name that
10462does not contain any @code{.}, @code{..}, nor symlinks.@*
10463@xref{File Name Functions, ,Functions for File Names}.
10464
10465@item $(abspath @var{names}@dots{})
10466For each file name in @var{names}, expand to an absolute name that
10467does not contain any @code{.} or @code{..} components, but preserves
10468symlinks.@*
10469@xref{File Name Functions, ,Functions for File Names}.
10470
10471@item $(error @var{text}@dots{})
10472
10473When this function is evaluated, @code{make} generates a fatal error
10474with the message @var{text}.@*
10475@xref{Make Control Functions, ,Functions That Control Make}.
10476
10477@item $(warning @var{text}@dots{})
10478
10479When this function is evaluated, @code{make} generates a warning with
10480the message @var{text}.@*
10481@xref{Make Control Functions, ,Functions That Control Make}.
10482
10483@item $(shell @var{command})
10484
10485Execute a shell command and return its output.@*
10486@xref{Shell Function, , The @code{shell} Function}.
10487
10488@item $(origin @var{variable})
10489
10490Return a string describing how the @code{make} variable @var{variable} was
10491defined.@*
10492@xref{Origin Function, , The @code{origin} Function}.
10493
10494@item $(flavor @var{variable})
10495
10496Return a string describing the flavor of the @code{make} variable
10497@var{variable}.@*
10498@xref{Flavor Function, , The @code{flavor} Function}.
10499
10500@item $(foreach @var{var},@var{words},@var{text})
10501
10502Evaluate @var{text} with @var{var} bound to each word in @var{words},
10503and concatenate the results.@*
10504@xref{Foreach Function, ,The @code{foreach} Function}.
10505
10506@item $(call @var{var},@var{param},@dots{})
10507
10508Evaluate the variable @var{var} replacing any references to @code{$(1)},
10509@code{$(2)} with the first, second, etc.@: @var{param} values.@*
10510@xref{Call Function, ,The @code{call} Function}.
10511
10512@item $(eval @var{text})
10513
10514Evaluate @var{text} then read the results as makefile commands.
10515Expands to the empty string.@*
10516@xref{Eval Function, ,The @code{eval} Function}.
10517
10518@item $(value @var{var})
10519
10520Evaluates to the contents of the variable @var{var}, with no expansion
10521performed on it.@*
10522@xref{Value Function, ,The @code{value} Function}.
10523@end table
10524
10525Here is a summary of the automatic variables.
10526@xref{Automatic Variables},
10527for full information.
10528
10529@table @code
10530@item $@@
10531The file name of the target.
10532
10533@item $%
10534The target member name, when the target is an archive member.
10535
10536@item $<
10537The name of the first prerequisite.
10538
10539@item $?
10540The names of all the prerequisites that are
10541newer than the target, with spaces between them.
10542For prerequisites which are archive members, only
10543the member named is used (@pxref{Archives}).
10544
10545@item $^
10546@itemx $+
10547The names of all the prerequisites, with spaces between them.  For
10548prerequisites which are archive members, only the member named is used
10549(@pxref{Archives}).  The value of @code{$^} omits duplicate
10550prerequisites, while @code{$+} retains them and preserves their order.
10551
10552@item $*
10553The stem with which an implicit rule matches
10554(@pxref{Pattern Match, ,How Patterns Match}).
10555
10556@item $(@@D)
10557@itemx $(@@F)
10558The directory part and the file-within-directory part of @code{$@@}.
10559
10560@item $(*D)
10561@itemx $(*F)
10562The directory part and the file-within-directory part of @code{$*}.
10563
10564@item $(%D)
10565@itemx $(%F)
10566The directory part and the file-within-directory part of @code{$%}.
10567
10568@item $(<D)
10569@itemx $(<F)
10570The directory part and the file-within-directory part of @code{$<}.
10571
10572@item $(^D)
10573@itemx $(^F)
10574The directory part and the file-within-directory part of @code{$^}.
10575
10576@item $(+D)
10577@itemx $(+F)
10578The directory part and the file-within-directory part of @code{$+}.
10579
10580@item $(?D)
10581@itemx $(?F)
10582The directory part and the file-within-directory part of @code{$?}.
10583@end table
10584
10585These variables are used specially by GNU @code{make}:
10586
10587@table @code
10588@item MAKEFILES
10589
10590Makefiles to be read on every invocation of @code{make}.@*
10591@xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
10592
10593@item VPATH
10594
10595Directory search path for files not found in the current directory.@*
10596@xref{General Search, , @code{VPATH} Search Path for All Prerequisites}.
10597
10598@item SHELL
10599
10600The name of the system default command interpreter, usually @file{/bin/sh}.
10601You can set @code{SHELL} in the makefile to change the shell used to run
10602commands.  @xref{Execution, ,Command Execution}.  The @code{SHELL}
10603variable is handled specially when importing from and exporting to the
10604environment.  @xref{Choosing the Shell}.
10605
10606@item MAKESHELL
10607
10608On MS-DOS only, the name of the command interpreter that is to be used
10609by @code{make}.  This value takes precedence over the value of
10610@code{SHELL}.  @xref{Execution, ,MAKESHELL variable}.
10611
10612@item MAKE
10613
10614The name with which @code{make} was invoked.
10615Using this variable in commands has special meaning.
10616@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.
10617
10618@item MAKELEVEL
10619
10620The number of levels of recursion (sub-@code{make}s).@*
10621@xref{Variables/Recursion}.
10622
10623@item MAKEFLAGS
10624
10625The flags given to @code{make}.  You can set this in the environment or
10626a makefile to set flags.@*
10627@xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
10628
10629It is @emph{never} appropriate to use @code{MAKEFLAGS} directly on a
10630command line: its contents may not be quoted correctly for use in the
10631shell.  Always allow recursive @code{make}'s to obtain these values
10632through the environment from its parent.
10633
10634@item MAKECMDGOALS
10635
10636The targets given to @code{make} on the command line.  Setting this
10637variable has no effect on the operation of @code{make}.@*
10638@xref{Goals, ,Arguments to Specify the Goals}.
10639
10640@item CURDIR
10641
10642Set to the pathname of the current working directory (after all
10643@code{-C} options are processed, if any).  Setting this variable has no
10644effect on the operation of @code{make}.@*
10645@xref{Recursion, ,Recursive Use of @code{make}}.
10646
10647@item SUFFIXES
10648
10649The default list of suffixes before @code{make} reads any makefiles.
10650
10651@item .LIBPATTERNS
10652Defines the naming of the libraries @code{make} searches for, and their
10653order.@*
10654@xref{Libraries/Search, ,Directory Search for Link Libraries}.
10655@end table
10656
10657@node Error Messages, Complex Makefile, Quick Reference, Top
10658@comment  node-name,  next,  previous,  up
10659@appendix Errors Generated by Make
10660
10661Here is a list of the more common errors you might see generated by
10662@code{make}, and some information about what they mean and how to fix
10663them.
10664
10665Sometimes @code{make} errors are not fatal, especially in the presence
10666of a @code{-} prefix on a command script line, or the @code{-k} command
10667line option.  Errors that are fatal are prefixed with the string
10668@code{***}.
10669
10670Error messages are all either prefixed with the name of the program
10671(usually @samp{make}), or, if the error is found in a makefile, the name
10672of the file and linenumber containing the problem.
10673
10674In the table below, these common prefixes are left off.
10675
10676@table @samp
10677
10678@item [@var{foo}] Error @var{NN}
10679@itemx [@var{foo}] @var{signal description}
10680These errors are not really @code{make} errors at all.  They mean that a
10681program that @code{make} invoked as part of a command script returned a
10682non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets
10683as failure, or it exited in some other abnormal fashion (with a
10684signal of some type).  @xref{Errors, ,Errors in Commands}.
10685
10686If no @code{***} is attached to the message, then the subprocess failed
10687but the rule in the makefile was prefixed with the @code{-} special
10688character, so @code{make} ignored the error.
10689
10690@item missing separator.  Stop.
10691@itemx missing separator (did you mean TAB instead of 8 spaces?).  Stop.
10692This means that @code{make} could not understand much of anything about
10693the command line it just read.  GNU @code{make} looks for various kinds
10694of separators (@code{:}, @code{=}, TAB characters, etc.) to help it
10695decide what kind of commandline it's seeing.  This means it couldn't
10696find a valid one.
10697
10698One of the most common reasons for this message is that you (or perhaps
10699your oh-so-helpful editor, as is the case with many MS-Windows editors)
10700have attempted to indent your command scripts with spaces instead of a
10701TAB character.  In this case, @code{make} will use the second form of
10702the error above.  Remember that every line in the command script must
10703begin with a TAB character.  Eight spaces do not count.  @xref{Rule
10704Syntax}.
10705
10706@item commands commence before first target.  Stop.
10707@itemx missing rule before commands.  Stop.
10708This means the first thing in the makefile seems to be part of a command
10709script: it begins with a TAB character and doesn't appear to be a legal
10710@code{make} command (such as a variable assignment).  Command scripts
10711must always be associated with a target.
10712
10713The second form is generated if the line has a semicolon as the first
10714non-whitespace character; @code{make} interprets this to mean you left
10715out the "target: prerequisite" section of a rule.  @xref{Rule Syntax}.
10716
10717@item No rule to make target `@var{xxx}'.
10718@itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'.
10719This means that @code{make} decided it needed to build a target, but
10720then couldn't find any instructions in the makefile on how to do that,
10721either explicit or implicit (including in the default rules database).
10722
10723If you want that file to be built, you will need to add a rule to your
10724makefile describing how that target can be built.  Other possible
10725sources of this problem are typos in the makefile (if that filename is
10726wrong) or a corrupted source tree (if that file is not supposed to be
10727built, but rather only a prerequisite).
10728
10729@item No targets specified and no makefile found.  Stop.
10730@itemx No targets.  Stop.
10731The former means that you didn't provide any targets to be built on the
10732command line, and @code{make} couldn't find any makefiles to read in.
10733The latter means that some makefile was found, but it didn't contain any
10734default goal and none was given on the command line.  GNU @code{make}
10735has nothing to do in these situations.
10736@xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill
10737
10738@item Makefile `@var{xxx}' was not found.
10739@itemx Included makefile `@var{xxx}' was not found.
10740A makefile specified on the command line (first form) or included
10741(second form) was not found.
10742
10743@item warning: overriding commands for target `@var{xxx}'
10744@itemx warning: ignoring old commands for target `@var{xxx}'
10745GNU @code{make} allows commands to be specified only once per target
10746(except for double-colon rules).  If you give commands for a target
10747which already has been defined to have commands, this warning is issued
10748and the second set of commands will overwrite the first set.
10749@xref{Multiple Rules, ,Multiple Rules for One Target}.
10750
10751@item Circular @var{xxx} <- @var{yyy} dependency dropped.
10752This means that @code{make} detected a loop in the dependency graph:
10753after tracing the prerequisite @var{yyy} of target @var{xxx}, and its
10754prerequisites, etc., one of them depended on @var{xxx} again.
10755
10756@item Recursive variable `@var{xxx}' references itself (eventually).  Stop.
10757This means you've defined a normal (recursive) @code{make} variable
10758@var{xxx} that, when it's expanded, will refer to itself (@var{xxx}).
10759This is not allowed; either use simply-expanded variables (@code{:=}) or
10760use the append operator (@code{+=}).  @xref{Using Variables, ,How to Use
10761Variables}.
10762
10763@item Unterminated variable reference.  Stop.
10764This means you forgot to provide the proper closing parenthesis
10765or brace in your variable or function reference.
10766
10767@item insufficient arguments to function `@var{xxx}'.  Stop.
10768This means you haven't provided the requisite number of arguments for
10769this function.  See the documentation of the function for a description
10770of its arguments.  @xref{Functions, ,Functions for Transforming Text}.
10771
10772@item missing target pattern.  Stop.
10773@itemx multiple target patterns.  Stop.
10774@itemx target pattern contains no `%'.  Stop.
10775@itemx mixed implicit and static pattern rules.  Stop.
10776These are generated for malformed static pattern rules.  The first means
10777there's no pattern in the target section of the rule; the second means
10778there are multiple patterns in the target section; the third means
10779the target doesn't contain a pattern character (@code{%}); and the
10780fourth means that all three parts of the static pattern rule contain
10781pattern characters (@code{%})--only the first two parts should.
10782@xref{Static Usage, ,Syntax of Static Pattern Rules}.
10783
10784@item warning: -jN forced in submake: disabling jobserver mode.
10785This warning and the next are generated if @code{make} detects error
10786conditions related to parallel processing on systems where
10787sub-@code{make}s can communicate (@pxref{Options/Recursion,
10788,Communicating Options to a Sub-@code{make}}).  This warning is
10789generated if a recursive invocation of a @code{make} process is forced
10790to have @samp{-j@var{N}} in its argument list (where @var{N} is greater
10791than one).  This could happen, for example, if you set the @code{MAKE}
10792environment variable to @samp{make -j2}.  In this case, the
10793sub-@code{make} doesn't communicate with other @code{make} processes and
10794will simply pretend it has two jobs of its own.
10795
10796@item warning: jobserver unavailable: using -j1.  Add `+' to parent make rule.
10797In order for @code{make} processes to communicate, the parent will pass
10798information to the child.  Since this could result in problems if the
10799child process isn't actually a @code{make}, the parent will only do this
10800if it thinks the child is a @code{make}.  The parent uses the normal
10801algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE}
10802Variable Works}).  If the makefile is constructed such that the parent
10803doesn't know the child is a @code{make} process, then the child will
10804receive only part of the information necessary.  In this case, the child
10805will generate this warning message and proceed with its build in a
10806sequential manner.
10807
10808@end table
10809
10810@node Complex Makefile, GNU Free Documentation License, Error Messages, Top
10811@appendix Complex Makefile Example
10812
10813Here is the makefile for the GNU @code{tar} program.  This is a
10814moderately complex makefile.
10815
10816Because it is the first target, the default goal is @samp{all}.  An
10817interesting feature of this makefile is that @file{testpad.h} is a
10818source file automatically created by the @code{testpad} program,
10819itself compiled from @file{testpad.c}.
10820
10821If you type @samp{make} or @samp{make all}, then @code{make} creates
10822the @file{tar} executable, the @file{rmt} daemon that provides
10823remote tape access, and the @file{tar.info} Info file.
10824
10825If you type @samp{make install}, then @code{make} not only creates
10826@file{tar}, @file{rmt}, and @file{tar.info}, but also installs
10827them.
10828
10829If you type @samp{make clean}, then @code{make} removes the @samp{.o}
10830files, and the @file{tar}, @file{rmt}, @file{testpad},
10831@file{testpad.h}, and @file{core} files.
10832
10833If you type @samp{make distclean}, then @code{make} not only removes
10834the same files as does @samp{make clean} but also the
10835@file{TAGS}, @file{Makefile}, and @file{config.status} files.
10836(Although it is not evident, this makefile (and
10837@file{config.status}) is generated by the user with the
10838@code{configure} program, which is provided in the @code{tar}
10839distribution, but is not shown here.)
10840
10841If you type @samp{make realclean}, then @code{make} removes the same
10842files as does @samp{make distclean} and also removes the Info files
10843generated from @file{tar.texinfo}.
10844
10845In addition, there are targets @code{shar} and @code{dist} that create
10846distribution kits.
10847
10848@example
10849@group
10850# Generated automatically from Makefile.in by configure.
10851# Un*x Makefile for GNU tar program.
10852# Copyright (C) 1991 Free Software Foundation, Inc.
10853@end group
10854
10855@group
10856# This program is free software; you can redistribute
10857# it and/or modify it under the terms of the GNU
10858# General Public License @dots{}
10859@dots{}
10860@dots{}
10861@end group
10862
10863SHELL = /bin/sh
10864
10865#### Start of system configuration section. ####
10866
10867srcdir = .
10868
10869@group
10870# If you use gcc, you should either run the
10871# fixincludes script that comes with it or else use
10872# gcc with the -traditional option.  Otherwise ioctl
10873# calls will be compiled incorrectly on some systems.
10874CC = gcc -O
10875YACC = bison -y
10876INSTALL = /usr/local/bin/install -c
10877INSTALLDATA = /usr/local/bin/install -c -m 644
10878@end group
10879
10880# Things you might add to DEFS:
10881# -DSTDC_HEADERS        If you have ANSI C headers and
10882#                       libraries.
10883# -DPOSIX               If you have POSIX.1 headers and
10884#                       libraries.
10885# -DBSD42               If you have sys/dir.h (unless
10886#                       you use -DPOSIX), sys/file.h,
10887#                       and st_blocks in `struct stat'.
10888# -DUSG                 If you have System V/ANSI C
10889#                       string and memory functions
10890#                       and headers, sys/sysmacros.h,
10891#                       fcntl.h, getcwd, no valloc,
10892#                       and ndir.h (unless
10893#                       you use -DDIRENT).
10894# -DNO_MEMORY_H         If USG or STDC_HEADERS but do not
10895#                       include memory.h.
10896# -DDIRENT              If USG and you have dirent.h
10897#                       instead of ndir.h.
10898# -DSIGTYPE=int         If your signal handlers
10899#                       return int, not void.
10900# -DNO_MTIO             If you lack sys/mtio.h
10901#                       (magtape ioctls).
10902# -DNO_REMOTE           If you do not have a remote shell
10903#                       or rexec.
10904# -DUSE_REXEC           To use rexec for remote tape
10905#                       operations instead of
10906#                       forking rsh or remsh.
10907# -DVPRINTF_MISSING     If you lack vprintf function
10908#                       (but have _doprnt).
10909# -DDOPRNT_MISSING      If you lack _doprnt function.
10910#                       Also need to define
10911#                       -DVPRINTF_MISSING.
10912# -DFTIME_MISSING       If you lack ftime system call.
10913# -DSTRSTR_MISSING      If you lack strstr function.
10914# -DVALLOC_MISSING      If you lack valloc function.
10915# -DMKDIR_MISSING       If you lack mkdir and
10916#                       rmdir system calls.
10917# -DRENAME_MISSING      If you lack rename system call.
10918# -DFTRUNCATE_MISSING   If you lack ftruncate
10919#                       system call.
10920# -DV7                  On Version 7 Unix (not
10921#                       tested in a long time).
10922# -DEMUL_OPEN3          If you lack a 3-argument version
10923#                       of open, and want to emulate it
10924#                       with system calls you do have.
10925# -DNO_OPEN3            If you lack the 3-argument open
10926#                       and want to disable the tar -k
10927#                       option instead of emulating open.
10928# -DXENIX               If you have sys/inode.h
10929#                       and need it 94 to be included.
10930
10931DEFS =  -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
10932        -DVPRINTF_MISSING -DBSD42
10933# Set this to rtapelib.o unless you defined NO_REMOTE,
10934# in which case make it empty.
10935RTAPELIB = rtapelib.o
10936LIBS =
10937DEF_AR_FILE = /dev/rmt8
10938DEFBLOCKING = 20
10939
10940@group
10941CDEBUG = -g
10942CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
10943        -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
10944        -DDEFBLOCKING=$(DEFBLOCKING)
10945LDFLAGS = -g
10946@end group
10947
10948@group
10949prefix = /usr/local
10950# Prefix for each installed program,
10951# normally empty or `g'.
10952binprefix =
10953
10954# The directory to install tar in.
10955bindir = $(prefix)/bin
10956
10957# The directory to install the info files in.
10958infodir = $(prefix)/info
10959@end group
10960
10961#### End of system configuration section. ####
10962
10963SRC1 =  tar.c create.c extract.c buffer.c \
10964        getoldopt.c update.c gnu.c mangle.c
10965SRC2 =  version.c list.c names.c diffarch.c \
10966        port.c wildmat.c getopt.c
10967SRC3 =  getopt1.c regex.c getdate.y
10968SRCS =  $(SRC1) $(SRC2) $(SRC3)
10969OBJ1 =  tar.o create.o extract.o buffer.o \
10970        getoldopt.o update.o gnu.o mangle.o
10971OBJ2 =  version.o list.o names.o diffarch.o \
10972        port.o wildmat.o getopt.o
10973OBJ3 =  getopt1.o regex.o getdate.o $(RTAPELIB)
10974OBJS =  $(OBJ1) $(OBJ2) $(OBJ3)
10975@group
10976AUX =   README COPYING ChangeLog Makefile.in  \
10977        makefile.pc configure configure.in \
10978        tar.texinfo tar.info* texinfo.tex \
10979        tar.h port.h open3.h getopt.h regex.h \
10980        rmt.h rmt.c rtapelib.c alloca.c \
10981        msd_dir.h msd_dir.c tcexparg.c \
10982        level-0 level-1 backup-specs testpad.c
10983@end group
10984
10985.PHONY: all
10986all:    tar rmt tar.info
10987
10988@group
10989.PHONY: tar
10990tar:    $(OBJS)
10991        $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
10992@end group
10993
10994@group
10995rmt:    rmt.c
10996        $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
10997@end group
10998
10999@group
11000tar.info: tar.texinfo
11001        makeinfo tar.texinfo
11002@end group
11003
11004@group
11005.PHONY: install
11006install: all
11007        $(INSTALL) tar $(bindir)/$(binprefix)tar
11008        -test ! -f rmt || $(INSTALL) rmt /etc/rmt
11009        $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
11010@end group
11011
11012@group
11013$(OBJS): tar.h port.h testpad.h
11014regex.o buffer.o tar.o: regex.h
11015# getdate.y has 8 shift/reduce conflicts.
11016@end group
11017
11018@group
11019testpad.h: testpad
11020        ./testpad
11021@end group
11022
11023@group
11024testpad: testpad.o
11025        $(CC) -o $@@ testpad.o
11026@end group
11027
11028@group
11029TAGS:   $(SRCS)
11030        etags $(SRCS)
11031@end group
11032
11033@group
11034.PHONY: clean
11035clean:
11036        rm -f *.o tar rmt testpad testpad.h core
11037@end group
11038
11039@group
11040.PHONY: distclean
11041distclean: clean
11042        rm -f TAGS Makefile config.status
11043@end group
11044
11045@group
11046.PHONY: realclean
11047realclean: distclean
11048        rm -f tar.info*
11049@end group
11050
11051@group
11052.PHONY: shar
11053shar: $(SRCS) $(AUX)
11054        shar $(SRCS) $(AUX) | compress \
11055          > tar-`sed -e '/version_string/!d' \
11056                     -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
11057                     -e q
11058                     version.c`.shar.Z
11059@end group
11060
11061@group
11062.PHONY: dist
11063dist: $(SRCS) $(AUX)
11064        echo tar-`sed \
11065             -e '/version_string/!d' \
11066             -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
11067             -e q
11068             version.c` > .fname
11069        -rm -rf `cat .fname`
11070        mkdir `cat .fname`
11071        ln $(SRCS) $(AUX) `cat .fname`
11072        tar chZf `cat .fname`.tar.Z `cat .fname`
11073        -rm -rf `cat .fname` .fname
11074@end group
11075
11076@group
11077tar.zoo: $(SRCS) $(AUX)
11078        -rm -rf tmp.dir
11079        -mkdir tmp.dir
11080        -rm tar.zoo
11081        for X in $(SRCS) $(AUX) ; do \
11082            echo $$X ; \
11083            sed 's/$$/^M/' $$X \
11084            > tmp.dir/$$X ; done
11085        cd tmp.dir ; zoo aM ../tar.zoo *
11086        -rm -rf tmp.dir
11087@end group
11088@end example
11089
11090@raisesections
11091@include fdl.texi
11092@lowersections
11093
11094@node Concept Index, Name Index, GNU Free Documentation License, Top
11095@unnumbered Index of Concepts
11096
11097@printindex cp
11098
11099@node Name Index,  , Concept Index, Top
11100@unnumbered Index of Functions, Variables, & Directives
11101
11102@printindex fn
11103
11104@bye
11105