- Enhance .POSIX to set -e when invoking shells, as demanded by a
[make.git] / doc / make.texi
1 \input texinfo                @c -*- Texinfo -*-
2 @c %**start of header
3 @setfilename make.info
5 @include version.texi
6 @set EDITION 0.70
7 @set RCSID $Id: make.texi,v 1.65 2010/07/06 06:37:42 psmith Exp $
9 @settitle GNU @code{make}
10 @setchapternewpage odd
11 @c Combine the variable and function indices:
12 @syncodeindex vr fn
13 @c Combine the program and concept indices:
14 @syncodeindex pg cp
15 @c FSF publishers: format makebook.texi instead of using this file directly.
16 @c ISBN confirmed by Jasimin Huang <jasimin@fsf.org> on 25 Mar 2009
17 @set ISBN 1-882114-83-3
18 @c %**end of header
20 @copying
21 This file documents the GNU @code{make} utility, which determines
22 automatically which pieces of a large program need to be recompiled,
23 and issues the commands to recompile them.
25 This is Edition @value{EDITION}, last updated @value{UPDATED},
26 of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}.
28 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
29 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009
30 Free Software Foundation, Inc.
32 @quotation
33 Permission is granted to copy, distribute and/or modify this document
34 under the terms of the GNU Free Documentation License, Version 1.2 or
35 any later version published by the Free Software Foundation; with no
36 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
37 and with the Back-Cover Texts as in (a) below.  A copy of the
38 license is included in the section entitled ``GNU Free Documentation
39 License.''
41 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
42 modify this GNU manual.  Buying copies from the FSF supports it in
43 developing GNU and promoting software freedom.''
44 @end quotation
45 @end copying
47 @c finalout
49 @c ISPELL CHECK: done, 10 June 1993 --roland
50 @c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz
53 @dircategory Software development
54 @direntry
55 * Make: (make).            Remake files automatically.
56 @end direntry
58 @iftex
59 @shorttitlepage GNU Make
60 @end iftex
61 @titlepage
62 @title GNU Make
63 @subtitle A Program for Directing Recompilation
64 @subtitle GNU @code{make} Version @value{VERSION}
65 @subtitle @value{UPDATED-MONTH}
66 @author Richard M. Stallman, Roland McGrath, Paul D. Smith
67 @page
68 @vskip 0pt plus 1filll
69 @insertcopying
70 @sp 2
71 Published by the Free Software Foundation @*
72 51 Franklin St. -- Fifth Floor @*
73 Boston, MA 02110-1301 USA @*
74 ISBN @value{ISBN} @*
75 @sp 2
76 Cover art by Etienne Suvasa.
77 @end titlepage
79 @summarycontents
80 @contents
82 @ifnottex
83 @node Top, Overview, (dir), (dir)
84 @top GNU @code{make}
86 @insertcopying
87 @end ifnottex
89 @menu
90 * Overview::                    Overview of @code{make}.
91 * Introduction::                An introduction to @code{make}.
92 * Makefiles::                   Makefiles tell @code{make} what to do.
93 * Rules::                       Rules describe when a file must be remade.
94 * Recipes::                     Recipes say how to remake a file.
95 * Using Variables::             You can use variables to avoid repetition.
96 * Conditionals::                Use or ignore parts of the makefile based
97                                   on the values of variables.
98 * Functions::                   Many powerful ways to manipulate text.
99 * Invoking make: Running.       How to invoke @code{make} on the command line.
100 * Implicit Rules::              Use implicit rules to treat many files alike,
101                                   based on their file names.
102 * Archives::                    How @code{make} can update library archives.
103 * Features::                    Features GNU @code{make} has over other @code{make}s.
104 * Missing::                     What GNU @code{make} lacks from other @code{make}s.
105 * Makefile Conventions::        Conventions for writing makefiles for
106                                   GNU programs.
107 * Quick Reference::             A quick reference for experienced users.
108 * Error Messages::              A list of common errors generated by @code{make}.
109 * Complex Makefile::            A real example of a straightforward,
110                                   but nontrivial, makefile.
112 * GNU Free Documentation License::  License for copying this manual
113 * Concept Index::               Index of Concepts
114 * Name Index::                  Index of Functions, Variables, & Directives
116 @detailmenu
117  --- The Detailed Node Listing ---
119 Overview of @code{make}
121 * Preparing::                   Preparing and running make
122 * Reading::                     On reading this text
123 * Bugs::                        Problems and bugs
125 An Introduction to Makefiles
127 * Rule Introduction::           What a rule looks like.
128 * Simple Makefile::             A simple makefile
129 * How Make Works::              How @code{make} processes this makefile
130 * Variables Simplify::          Variables make makefiles simpler
131 * make Deduces::                Letting @code{make} deduce the recipe
132 * Combine By Prerequisite::     Another style of makefile
133 * Cleanup::                     Rules for cleaning the directory
135 Writing Makefiles
137 * Makefile Contents::           What makefiles contain.
138 * Makefile Names::              How to name your makefile.
139 * Include::                     How one makefile can use another makefile.
140 * MAKEFILES Variable::          The environment can specify extra makefiles.
141 * Remaking Makefiles::          How makefiles get remade.
142 * Overriding Makefiles::        How to override part of one makefile
143                                   with another makefile.
144 * Reading Makefiles::           How makefiles are parsed.
145 * Secondary Expansion::         How and when secondary expansion is performed.
147 Writing Rules
149 * Rule Example::                An example explained.
150 * Rule Syntax::                 General syntax explained.
151 * Prerequisite Types::          There are two types of prerequisites.
152 * Wildcards::                   Using wildcard characters such as `*'.
153 * Directory Search::            Searching other directories for source files.
154 * Phony Targets::               Using a target that is not a real file's name.
155 * Force Targets::               You can use a target without a recipe
156                                   or prerequisites to mark other targets
157                                   as phony.
158 * Empty Targets::               When only the date matters and the
159                                   files are empty.
160 * Special Targets::             Targets with special built-in meanings.
161 * Multiple Targets::            When to make use of several targets in a rule.
162 * Multiple Rules::              How to use several rules with the same target.
163 * Static Pattern::              Static pattern rules apply to multiple targets
164                                   and can vary the prerequisites according to
165                                   the target name.
166 * Double-Colon::                How to use a special kind of rule to allow
167                                   several independent rules for one target.
168 * Automatic Prerequisites::     How to automatically generate rules giving
169                                   prerequisites from source files themselves.
171 Using Wildcard Characters in File Names
173 * Wildcard Examples::           Several examples
174 * Wildcard Pitfall::            Problems to avoid.
175 * Wildcard Function::           How to cause wildcard expansion where
176                                   it does not normally take place.
178 Searching Directories for Prerequisites
180 * General Search::              Specifying a search path that applies
181                                   to every prerequisite.
182 * Selective Search::            Specifying a search path
183                                   for a specified class of names.
184 * Search Algorithm::            When and how search paths are applied.
185 * Recipes/Search::              How to write recipes that work together
186                                   with search paths.
187 * Implicit/Search::             How search paths affect implicit rules.
188 * Libraries/Search::            Directory search for link libraries.
190 Static Pattern Rules
192 * Static Usage::                The syntax of static pattern rules.
193 * Static versus Implicit::      When are they better than implicit rules?
195 Writing Recipes in Rules
197 * Recipe Syntax::               Recipe syntax features and pitfalls.
198 * Echoing::                     How to control when recipes are echoed.
199 * Execution::                   How recipes are executed.
200 * Parallel::                    How recipes can be executed in parallel.
201 * Errors::                      What happens after a recipe execution error.
202 * Interrupts::                  What happens when a recipe is interrupted.
203 * Recursion::                   Invoking @code{make} from makefiles.
204 * Canned Recipes::              Defining canned recipes.
205 * Empty Recipes::               Defining useful, do-nothing recipes.
207 Recipe Syntax
209 * Splitting Lines::             Breaking long recipe lines for readability.
210 * Variables in Recipes::        Using @code{make} variables in recipes.
212 Recipe Execution
214 * Choosing the Shell::          How @code{make} chooses the shell used
215                                   to run recipes.
217 Recursive Use of @code{make}
219 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
220 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
221 * Options/Recursion::           How to communicate options to a sub-@code{make}.
222 * -w Option::                   How the @samp{-w} or @samp{--print-directory} option
223                                   helps debug use of recursive @code{make} commands.
225 How to Use Variables
227 * Reference::                   How to use the value of a variable.
228 * Flavors::                     Variables come in two flavors.
229 * Advanced::                    Advanced features for referencing a variable.
230 * Values::                      All the ways variables get their values.
231 * Setting::                     How to set a variable in the makefile.
232 * Appending::                   How to append more text to the old value
233                                   of a variable.
234 * Override Directive::          How to set a variable in the makefile even if
235                                   the user has set it with a command argument.
236 * Multi-Line::                  An alternate way to set a variable
237                                   to a multi-line string.
238 * Environment::                 Variable values can come from the environment.
239 * Target-specific::             Variable values can be defined on a per-target
240                                   basis.
241 * Pattern-specific::            Target-specific variable values can be applied
242                                   to a group of targets that match a pattern.
243 * Suppressing Inheritance::     Suppress inheritance of variables.
244 * Special Variables::           Variables with special meaning or behavior.
246 Advanced Features for Reference to Variables
248 * Substitution Refs::           Referencing a variable with
249                                   substitutions on the value.
250 * Computed Names::              Computing the name of the variable to refer to.
252 Conditional Parts of Makefiles
254 * Conditional Example::         Example of a conditional
255 * Conditional Syntax::          The syntax of conditionals.
256 * Testing Flags::               Conditionals that test flags.
258 Functions for Transforming Text
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.
273 How to Run @code{make}
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 recipes
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
289 Using Implicit Rules
291 * Using Implicit::              How to use an existing implicit rule
292                                   to get the recipe 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 a recipe 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.
303 Defining and Redefining Pattern Rules
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                                   recipe 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.
315 Using @code{make} to Update Archive Files
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.
323 Implicit Rule for Archive Member Targets
325 * Archive Symbols::             How to update archive symbol directories.
327 @end detailmenu
328 @end menu
330 @node Overview, Introduction, Top, Top
331 @comment  node-name,  next,  previous,  up
332 @chapter Overview of @code{make}
334 The @code{make} utility automatically determines which pieces of a large
335 program need to be recompiled, and issues commands to recompile them.
336 This manual describes GNU @code{make}, which was implemented by Richard
337 Stallman and Roland McGrath.  Development since Version 3.76 has been
338 handled by Paul D. Smith.
340 GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard
341 1003.2-1992} (POSIX.2).
342 @cindex POSIX
343 @cindex IEEE Standard 1003.2
344 @cindex standards conformance
346 Our 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
348 shell command.  Indeed, @code{make} is not limited to programs.  You can
349 use it to describe any task where some files must be updated automatically
350 from others whenever the others change.
352 @menu
353 * Preparing::                   Preparing and Running Make
354 * Reading::                     On Reading this Text
355 * Bugs::                        Problems and Bugs
356 @end menu
358 @node Preparing, Reading, Overview, Overview
359 @ifnottex
360 @heading Preparing and Running Make
361 @end ifnottex
363 To prepare to use @code{make}, you must write a file called
364 the @dfn{makefile} that describes the relationships among files
365 in your program and provides commands for updating each file.
366 In a program, typically, the executable file is updated from object
367 files, which are in turn made by compiling source files.@refill
369 Once a suitable makefile exists, each time you change some source files,
370 this simple shell command:
372 @example
373 make
374 @end example
376 @noindent
377 suffices to perform all necessary recompilations.  The @code{make} program
378 uses the makefile data base and the last-modification times of the files to
379 decide which of the files need to be updated.  For each of those files, it
380 issues the recipes recorded in the data base.
382 You can provide command line arguments to @code{make} to control which
383 files should be recompiled, or how.  @xref{Running, ,How to Run
384 @code{make}}.
386 @node Reading, Bugs, Preparing, Overview
387 @section How to Read This Manual
389 If you are new to @code{make}, or are looking for a general
390 introduction, read the first few sections of each chapter, skipping the
391 later sections.  In each chapter, the first few sections contain
392 introductory or general information and the later sections contain
393 specialized or technical information.
394 @ifnottex
395 The exception is the second chapter, @ref{Introduction, ,An
396 Introduction to Makefiles}, all of which is introductory.
397 @end ifnottex
398 @iftex
399 The exception is @ref{Introduction, ,An Introduction to Makefiles},
400 all of which is introductory.
401 @end iftex
403 If 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
406 Features}, which explains the few things GNU @code{make} lacks that
407 others have.
409 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
410 and @ref{Special Targets}.
412 @node Bugs,  , Reading, Overview
413 @section Problems and Bugs
414 @cindex reporting bugs
415 @cindex bugs, reporting
416 @cindex problems and bugs, reporting
418 If you have problems with GNU @code{make} or think you've found a bug,
419 please report it to the developers; we cannot promise to do anything but
420 we might well want to fix it.
422 Before reporting a bug, make sure you've actually found a real bug.
423 Carefully reread the documentation and see if it really says you can do
424 what you're trying to do.  If it's not clear whether you should be able
425 to do something or not, report that too; it's a bug in the
426 documentation!
428 Before reporting a bug or trying to fix it yourself, try to isolate it
429 to the smallest possible makefile that reproduces the problem.  Then
430 send us the makefile and the exact results @code{make} gave you,
431 including any error or warning messages.  Please don't paraphrase
432 these messages: it's best to cut and paste them into your report.
433 When generating this small makefile, be sure to not use any non-free
434 or unusual tools in your recipes: you can almost always emulate what
435 such a tool would do with simple shell commands.  Finally, be sure to
436 explain what you expected to occur; this will help us decide whether
437 the problem was really in the documentation.
439 Once you have a precise problem you can report it in one of two ways.
440 Either send electronic mail to:
442 @example
443     bug-make@@gnu.org
444 @end example
446 @noindent
447 or use our Web-based project management tool, at:
449 @example
450     http://savannah.gnu.org/projects/make/
451 @end example
453 @noindent
454 In addition to the information above, please be careful to include the
455 version number of @code{make} you are using.  You can get this
456 information with the command @samp{make --version}.  Be sure also to
457 include the type of machine and operating system you are using.  One
458 way to obtain this information is by looking at the final lines of
459 output from the command @samp{make --help}.
461 @node Introduction, Makefiles, Overview, Top
462 @comment  node-name,  next,  previous,  up
463 @chapter An Introduction to Makefiles
465 You need a file called a @dfn{makefile} to tell @code{make} what to do.
466 Most often, the makefile tells @code{make} how to compile and link a
467 program.
468 @cindex makefile
470 In this chapter, we will discuss a simple makefile that describes how to
471 compile and link a text editor which consists of eight C source files
472 and three header files.  The makefile can also tell @code{make} how to
473 run miscellaneous commands when explicitly asked (for example, to remove
474 certain files as a clean-up operation).  To see a more complex example
475 of a makefile, see @ref{Complex Makefile}.
477 When @code{make} recompiles the editor, each changed C source file
478 must be recompiled.  If a header file has changed, each C source file
479 that includes the header file must be recompiled to be safe.  Each
480 compilation produces an object file corresponding to the source file.
481 Finally, if any source file has been recompiled, all the object files,
482 whether newly made or saved from previous compilations, must be linked
483 together to produce the new executable editor.
484 @cindex recompilation
485 @cindex editor
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 Recipes
493 * Combine By Prerequisite::     Another Style of Makefile
494 * Cleanup::                     Rules for Cleaning the Directory
495 @end menu
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
504 A simple makefile consists of ``rules'' with the following shape:
506 @cindex targets, introduction to
507 @cindex prerequisites, introduction to
508 @cindex recipes, introduction to
509 @example
510 @group
511 @var{target} @dots{} : @var{prerequisites} @dots{}
512         @var{recipe}
513         @dots{}
514         @dots{}
515 @end group
516 @end example
518 A @dfn{target} is usually the name of a file that is generated by a
519 program; examples of targets are executable or object files.  A target
520 can also be the name of an action to carry out, such as @samp{clean}
521 (@pxref{Phony Targets}).
523 A @dfn{prerequisite} is a file that is used as input to create the
524 target.  A target often depends on several files.
526 @cindex tabs in rules
527 A @dfn{recipe} is an action that @code{make} carries out.
528 A recipe 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
530 every command line!  This is an obscurity that catches the unwary.  If
531 you prefer to prefix your recipes with a character other than tab,
532 you can set the @code{.CMDPREFIX} variable to an alternate character
533 (@pxref{Special Variables}).
535 Usually a recipe is in a rule with prerequisites and serves to create a
536 target file if any of the prerequisites change.  However, the rule that
537 specifies a recipe for the target need not have prerequisites.  For
538 example, the rule containing the delete command associated with the
539 target @samp{clean} does not have prerequisites.
541 A @dfn{rule}, then, explains how and when to remake certain files
542 which are the targets of the particular rule.  @code{make} carries out
543 the recipe on the prerequisites to create or update the target.  A
544 rule can also explain how and when to carry out an action.
545 @xref{Rules, , Writing Rules}.
547 A makefile may contain other text besides rules, but a simple makefile
548 need only contain rules.  Rules may look somewhat more complicated
549 than shown in this template, but all fit the pattern more or less.
551 @node Simple Makefile, How Make Works, Rule Introduction, Introduction
552 @section A Simple Makefile
553 @cindex simple makefile
554 @cindex makefile, simple
556 Here is a straightforward makefile that describes the way an
557 executable file called @code{edit} depends on eight object files
558 which, in turn, depend on eight C source and three header files.
560 In this example, all the C files include @file{defs.h}, but only those
561 defining editing commands include @file{command.h}, and only low
562 level files that change the editor buffer include @file{buffer.h}.
564 @example
565 @group
566 edit : main.o kbd.o command.o display.o \
567        insert.o search.o files.o utils.o
568         cc -o edit main.o kbd.o command.o display.o \
569                    insert.o search.o files.o utils.o
571 main.o : main.c defs.h
572         cc -c main.c
573 kbd.o : kbd.c defs.h command.h
574         cc -c kbd.c
575 command.o : command.c defs.h command.h
576         cc -c command.c
577 display.o : display.c defs.h buffer.h
578         cc -c display.c
579 insert.o : insert.c defs.h buffer.h
580         cc -c insert.c
581 search.o : search.c defs.h buffer.h
582         cc -c search.c
583 files.o : files.c defs.h buffer.h command.h
584         cc -c files.c
585 utils.o : utils.c defs.h
586         cc -c utils.c
587 clean :
588         rm edit main.o kbd.o command.o display.o \
589            insert.o search.o files.o utils.o
590 @end group
591 @end example
593 @noindent
594 We split each long line into two lines using backslash-newline; this is
595 like using one long line, but is easier to read.
596 @cindex continuation lines
597 @cindex @code{\} (backslash), for continuation lines
598 @cindex backslash (@code{\}), for continuation lines
599 @cindex quoting newline, in makefile
600 @cindex newline, quoting, in makefile
602 To use this makefile to create the executable file called @file{edit},
603 type:
605 @example
606 make
607 @end example
609 To use this makefile to delete the executable file and all the object
610 files from the directory, type:
612 @example
613 make clean
614 @end example
616 In the example makefile, the targets include the executable file
617 @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}.  The
618 prerequisites are files such as @samp{main.c} and @samp{defs.h}.
619 In fact, each @samp{.o} file is both a target and a prerequisite.
620 Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
622 When a target is a file, it needs to be recompiled or relinked if any
623 of its prerequisites change.  In addition, any prerequisites that are
624 themselves automatically generated should be updated first.  In this
625 example, @file{edit} depends on each of the eight object files; the
626 object file @file{main.o} depends on the source file @file{main.c} and
627 on the header file @file{defs.h}.
629 A recipe may follow each line that contains a target and
630 prerequisites.  These recipes say how to update the target file.  A
631 tab character (or whatever character is specified by the
632 @code{.CMDPREFIX} variable; @pxref{Special Variables}) must come at
633 the beginning of every line in the recipe to distinguish recipes from
634 other lines in the makefile.  (Bear in mind that @code{make} does not
635 know anything about how the recipes work.  It is up to you to supply
636 recipes that will update the target file properly.  All @code{make}
637 does is execute the commands in the recipe you have specified when the
638 target file needs to be updated.)@refill
639 @cindex recipe
641 The target @samp{clean} is not a file, but merely the name of an
642 action.  Since you normally do not want to carry out the actions in
643 this rule, @samp{clean} is not a prerequisite of any other rule.
644 Consequently, @code{make} never does anything with it unless you tell
645 it specifically.  Note that this rule not only is not a prerequisite,
646 it also does not have any prerequisites, so the only purpose of the
647 rule is to run the specified recipe.  Targets that do not refer to
648 files but are just actions are called @dfn{phony targets}.
649 @xref{Phony Targets}, for information about this kind of target.
650 @xref{Errors, , Errors in Recipes}, to see how to cause @code{make}
651 to ignore errors from @code{rm} or any other command.
652 @cindex @code{clean} target
653 @cindex @code{rm} (shell command)
655 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
656 @comment  node-name,  next,  previous,  up
657 @section How @code{make} Processes a Makefile
658 @cindex processing a makefile
659 @cindex makefile, how @code{make} processes
661 By default, @code{make} starts with the first target (not targets whose
662 names start with @samp{.}).  This is called the @dfn{default goal}.
663 (@dfn{Goals} are the targets that @code{make} strives ultimately to
664 update.    You can override this behavior using the command line
665 (@pxref{Goals, , Arguments to Specify the Goals}) or with the
666 @code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, ,
667 Other Special Variables}).
668 @cindex default goal
669 @cindex goal, default
670 @cindex goal
672 In the simple example of the previous section, the default goal is to
673 update the executable program @file{edit}; therefore, we put that rule
674 first.
676 Thus, when you give the command:
678 @example
679 make
680 @end example
682 @noindent
683 @code{make} reads the makefile in the current directory and begins by
684 processing the first rule.  In the example, this rule is for relinking
685 @file{edit}; but before @code{make} can fully process this rule, it
686 must process the rules for the files that @file{edit} depends on,
687 which in this case are the object files.  Each of these files is
688 processed according to its own rule.  These rules say to update each
689 @samp{.o} file by compiling its source file.  The recompilation must
690 be done if the source file, or any of the header files named as
691 prerequisites, is more recent than the object file, or if the object
692 file does not exist.
694 The other rules are processed because their targets appear as
695 prerequisites of the goal.  If some other rule is not depended on by the
696 goal (or anything it depends on, etc.), that rule is not processed,
697 unless you tell @code{make} to do so (with a command such as
698 @w{@code{make clean}}).
700 Before recompiling an object file, @code{make} considers updating its
701 prerequisites, the source file and header files.  This makefile does not
702 specify anything to be done for them---the @samp{.c} and @samp{.h} files
703 are not the targets of any rules---so @code{make} does nothing for these
704 files.  But @code{make} would update automatically generated C programs,
705 such as those made by Bison or Yacc, by their own rules at this time.
707 After recompiling whichever object files need it, @code{make} decides
708 whether to relink @file{edit}.  This must be done if the file
709 @file{edit} does not exist, or if any of the object files are newer than
710 it.  If an object file was just recompiled, it is now newer than
711 @file{edit}, so @file{edit} is relinked.
712 @cindex relinking
714 Thus, if we change the file @file{insert.c} and run @code{make},
715 @code{make} will compile that file to update @file{insert.o}, and then
716 link @file{edit}.  If we change the file @file{command.h} and run
717 @code{make}, @code{make} will recompile the object files @file{kbd.o},
718 @file{command.o} and @file{files.o} and then link the file @file{edit}.
720 @node Variables Simplify, make Deduces, How Make Works, Introduction
721 @section Variables Make Makefiles Simpler
722 @cindex variables
723 @cindex simplifying with variables
725 In our example, we had to list all the object files twice in the rule for
726 @file{edit} (repeated here):
728 @example
729 @group
730 edit : main.o kbd.o command.o display.o \
731               insert.o search.o files.o utils.o
732         cc -o edit main.o kbd.o command.o display.o \
733                    insert.o search.o files.o utils.o
734 @end group
735 @end example
737 @cindex @code{objects}
738 Such duplication is error-prone; if a new object file is added to the
739 system, we might add it to one list and forget the other.  We can eliminate
740 the risk and simplify the makefile by using a variable.  @dfn{Variables}
741 allow a text string to be defined once and substituted in multiple places
742 later (@pxref{Using Variables, ,How to Use Variables}).
744 @cindex @code{OBJECTS}
745 @cindex @code{objs}
746 @cindex @code{OBJS}
747 @cindex @code{obj}
748 @cindex @code{OBJ}
749 It is standard practice for every makefile to have a variable named
750 @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
751 or @code{OBJ} which is a list of all object file names.  We would
752 define such a variable @code{objects} with a line like this in the
753 makefile:@refill
755 @example
756 @group
757 objects = main.o kbd.o command.o display.o \
758           insert.o search.o files.o utils.o
759 @end group
760 @end example
762 @noindent
763 Then, each place we want to put a list of the object file names, we can
764 substitute the variable's value by writing @samp{$(objects)}
765 (@pxref{Using Variables, ,How to Use Variables}).
767 Here is how the complete simple makefile looks when you use a variable
768 for the object files:
770 @example
771 @group
772 objects = main.o kbd.o command.o display.o \
773           insert.o search.o files.o utils.o
775 edit : $(objects)
776         cc -o edit $(objects)
777 main.o : main.c defs.h
778         cc -c main.c
779 kbd.o : kbd.c defs.h command.h
780         cc -c kbd.c
781 command.o : command.c defs.h command.h
782         cc -c command.c
783 display.o : display.c defs.h buffer.h
784         cc -c display.c
785 insert.o : insert.c defs.h buffer.h
786         cc -c insert.c
787 search.o : search.c defs.h buffer.h
788         cc -c search.c
789 files.o : files.c defs.h buffer.h command.h
790         cc -c files.c
791 utils.o : utils.c defs.h
792         cc -c utils.c
793 clean :
794         rm edit $(objects)
795 @end group
796 @end example
798 @node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction
799 @section Letting @code{make} Deduce the Recipes
800 @cindex deducing recipes (implicit rules)
801 @cindex implicit rule, introduction to
802 @cindex rule, implicit, introduction to
804 It is not necessary to spell out the recipes for compiling the individual
805 C source files, because @code{make} can figure them out: it has an
806 @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
807 named @samp{.c} file using a @samp{cc -c} command.  For example, it will
808 use the recipe @samp{cc -c main.c -o main.o} to compile @file{main.c} into
809 @file{main.o}.  We can therefore omit the recipes from the rules for the
810 object files.  @xref{Implicit Rules, ,Using Implicit Rules}.@refill
812 When a @samp{.c} file is used automatically in this way, it is also
813 automatically added to the list of prerequisites.  We can therefore omit
814 the @samp{.c} files from the prerequisites, provided we omit the recipe.
816 Here is the entire example, with both of these changes, and a variable
817 @code{objects} as suggested above:
819 @example
820 @group
821 objects = main.o kbd.o command.o display.o \
822           insert.o search.o files.o utils.o
824 edit : $(objects)
825         cc -o edit $(objects)
827 main.o : defs.h
828 kbd.o : defs.h command.h
829 command.o : defs.h command.h
830 display.o : defs.h buffer.h
831 insert.o : defs.h buffer.h
832 search.o : defs.h buffer.h
833 files.o : defs.h buffer.h command.h
834 utils.o : defs.h
836 .PHONY : clean
837 clean :
838         rm edit $(objects)
839 @end group
840 @end example
842 @noindent
843 This is how we would write the makefile in actual practice.  (The
844 complications associated with @samp{clean} are described elsewhere.
845 See @ref{Phony Targets}, and @ref{Errors, ,Errors in Recipes}.)
847 Because implicit rules are so convenient, they are important.  You
848 will see them used frequently.@refill
850 @node Combine By Prerequisite, Cleanup, make Deduces, Introduction
851 @section Another Style of Makefile
852 @cindex combining rules by prerequisite
854 When the objects of a makefile are created only by implicit rules, an
855 alternative style of makefile is possible.  In this style of makefile,
856 you group entries by their prerequisites instead of by their targets.
857 Here is what one looks like:
859 @example
860 @group
861 objects = main.o kbd.o command.o display.o \
862           insert.o search.o files.o utils.o
864 edit : $(objects)
865         cc -o edit $(objects)
867 $(objects) : defs.h
868 kbd.o command.o files.o : command.h
869 display.o insert.o search.o files.o : buffer.h
870 @end group
871 @end example
873 @noindent
874 Here @file{defs.h} is given as a prerequisite of all the object files;
875 @file{command.h} and @file{buffer.h} are prerequisites of the specific
876 object files listed for them.
878 Whether this is better is a matter of taste: it is more compact, but some
879 people dislike it because they find it clearer to put all the information
880 about each target in one place.
882 @node Cleanup,  , Combine By Prerequisite, Introduction
883 @section Rules for Cleaning the Directory
884 @cindex cleaning up
885 @cindex removing, to clean up
887 Compiling a program is not the only thing you might want to write rules
888 for.  Makefiles commonly tell how to do a few other things besides
889 compiling a program: for example, how to delete all the object files
890 and executables so that the directory is @samp{clean}.
892 @cindex @code{clean} target
893 Here is how we
894 could write a @code{make} rule for cleaning our example editor:
896 @example
897 @group
898 clean:
899         rm edit $(objects)
900 @end group
901 @end example
903 In practice, we might want to write the rule in a somewhat more
904 complicated manner to handle unanticipated situations.  We would do this:
906 @example
907 @group
908 .PHONY : clean
909 clean :
910         -rm edit $(objects)
911 @end group
912 @end example
914 @noindent
915 This prevents @code{make} from getting confused by an actual file
916 called @file{clean} and causes it to continue in spite of errors from
917 @code{rm}.  (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
918 Recipes}.)
920 @noindent
921 A rule such as this should not be placed at the beginning of the
922 makefile, because we do not want it to run by default!  Thus, in the
923 example makefile, we want the rule for @code{edit}, which recompiles
924 the editor, to remain the default goal.
926 Since @code{clean} is not a prerequisite of @code{edit}, this rule will not
927 run at all if we give the command @samp{make} with no arguments.  In
928 order to make the rule run, we have to type @samp{make clean}.
929 @xref{Running, ,How to Run @code{make}}.
931 @node Makefiles, Rules, Introduction, Top
932 @chapter Writing Makefiles
934 @cindex makefile, how to write
935 The information that tells @code{make} how to recompile a system comes from
936 reading a data base called the @dfn{makefile}.
938 @menu
939 * Makefile Contents::           What makefiles contain.
940 * Makefile Names::              How to name your makefile.
941 * Include::                     How one makefile can use another makefile.
942 * MAKEFILES Variable::          The environment can specify extra makefiles.
943 * Remaking Makefiles::          How makefiles get remade.
944 * Overriding Makefiles::        How to override part of one makefile
945                                   with another makefile.
946 * Reading Makefiles::           How makefiles are parsed.
947 * Secondary Expansion::         How and when secondary expansion is performed.
948 @end menu
950 @node Makefile Contents, Makefile Names, Makefiles, Makefiles
951 @section What Makefiles Contain
953 Makefiles contain five kinds of things: @dfn{explicit rules},
954 @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
955 and @dfn{comments}.  Rules, variables, and directives are described at
956 length in later chapters.@refill
958 @itemize @bullet
959 @cindex rule, explicit, definition of
960 @cindex explicit rule, definition of
961 @item
962 An @dfn{explicit rule} says when and how to remake one or more files,
963 called the rule's @dfn{targets}.  It lists the other files that the
964 targets depend on, called the @dfn{prerequisites} of the target, and
965 may also give a recipe to use to create or update the targets.
966 @xref{Rules, ,Writing Rules}.
968 @cindex rule, implicit, definition of
969 @cindex implicit rule, definition of
970 @item
971 An @dfn{implicit rule} says when and how to remake a class of files
972 based on their names.  It describes how a target may depend on a file
973 with a name similar to the target and gives a recipe to create or
974 update such a target.  @xref{Implicit Rules, ,Using Implicit Rules}.
976 @cindex variable definition
977 @item
978 A @dfn{variable definition} is a line that specifies a text string
979 value for a variable that can be substituted into the text later.  The
980 simple makefile example shows a variable definition for @code{objects}
981 as a list of all object files (@pxref{Variables Simplify, , Variables
982 Make Makefiles Simpler}).
984 @cindex directive
985 @item
986 A @dfn{directive} is an instruction for @code{make} to do something
987 special while reading the makefile.  These include:
989 @itemize @bullet
990 @item
991 Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
993 @item
994 Deciding (based on the values of variables) whether to use or
995 ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
997 @item
998 Defining a variable from a verbatim string containing multiple lines
999 (@pxref{Multi-Line, ,Defining Multi-Line Variables}).
1000 @end itemize
1002 @cindex comments, in makefile
1003 @cindex @code{#} (comments), in makefile
1004 @item
1005 @samp{#} in a line of a makefile starts a @dfn{comment}.  It and the
1006 rest of the line are ignored, except that a trailing backslash not
1007 escaped by another backslash will continue the comment across multiple
1008 lines.  A line containing just a comment (with perhaps spaces before
1009 it) is effectively blank, and is ignored.  If you want a literal
1010 @code{#}, escape it with a backslash (e.g., @code{\#}).  Comments may
1011 appear on any line in the makefile, although they are treated
1012 specially in certain situations.
1014 You cannot use comments within variable references or function calls:
1015 any instance of @code{#} will be treated literally (rather than as the
1016 start of a comment) inside a variable reference or function call.
1018 Comments within a recipe are passed to the shell, just as with any
1019 other recipe text.  The shell decides how to interpret it: whether or
1020 not this is a comment is up to the shell.
1022 Within a @code{define} directive, comments are not ignored during the
1023 definition of the variable, but rather kept intact in the value of the
1024 variable.  When the variable is expanded they will either be treated
1025 as @code{make} comments or as recipe text, depending on the context in
1026 which the variable is evaluated.
1027 @end itemize
1029 @node Makefile Names, Include, Makefile Contents, Makefiles
1030 @section What Name to Give Your Makefile
1031 @cindex makefile name
1032 @cindex name of makefile
1033 @cindex default makefile name
1034 @cindex file name of makefile
1036 @c following paragraph rewritten to avoid overfull hbox
1037 By default, when @code{make} looks for the makefile, it tries the
1038 following names, in order: @file{GNUmakefile}, @file{makefile}
1039 and @file{Makefile}.@refill
1040 @findex Makefile
1041 @findex GNUmakefile
1042 @findex makefile
1044 @cindex @code{README}
1045 Normally you should call your makefile either @file{makefile} or
1046 @file{Makefile}.  (We recommend @file{Makefile} because it appears
1047 prominently near the beginning of a directory listing, right near other
1048 important files such as @file{README}.)  The first name checked,
1049 @file{GNUmakefile}, is not recommended for most makefiles.  You should
1050 use this name if you have a makefile that is specific to GNU
1051 @code{make}, and will not be understood by other versions of
1052 @code{make}.  Other @code{make} programs look for @file{makefile} and
1053 @file{Makefile}, but not @file{GNUmakefile}.
1055 If @code{make} finds none of these names, it does not use any makefile.
1056 Then you must specify a goal with a command argument, and @code{make}
1057 will attempt to figure out how to remake it using only its built-in
1058 implicit rules.  @xref{Implicit Rules, ,Using Implicit Rules}.
1060 @cindex @code{-f}
1061 @cindex @code{--file}
1062 @cindex @code{--makefile}
1063 If you want to use a nonstandard name for your makefile, you can specify
1064 the makefile name with the @samp{-f} or @samp{--file} option.  The
1065 arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1066 @code{make} to read the file @var{name} as the makefile.  If you use
1067 more than one @samp{-f} or @samp{--file} option, you can specify several
1068 makefiles.  All the makefiles are effectively concatenated in the order
1069 specified.  The default makefile names @file{GNUmakefile},
1070 @file{makefile} and @file{Makefile} are not checked automatically if you
1071 specify @samp{-f} or @samp{--file}.@refill
1072 @cindex specifying makefile name
1073 @cindex makefile name, how to specify
1074 @cindex name of makefile, how to specify
1075 @cindex file name of makefile, how to specify
1077 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
1078 @section Including Other Makefiles
1079 @cindex including other makefiles
1080 @cindex makefile, including
1082 @findex include
1083 The @code{include} directive tells @code{make} to suspend reading the
1084 current makefile and read one or more other makefiles before continuing.
1085 The directive is a line in the makefile that looks like this:
1087 @example
1088 include @var{filenames}@dots{}
1089 @end example
1091 @noindent
1092 @var{filenames} can contain shell file name patterns.  If
1093 @var{filenames} is empty, nothing is included and no error is printed.
1094 @cindex shell file name pattern (in @code{include})
1095 @cindex shell wildcards (in @code{include})
1096 @cindex wildcard, in @code{include}
1098 Extra spaces are allowed and ignored at the beginning of the line, but
1099 the first character must not be a tab (or the value of
1100 @code{.CMDPREFIX})---if the line begins with a tab, it will be
1101 considered a recipe line.  Whitespace is required between
1102 @code{include} and the file names, and between file names; extra
1103 whitespace is ignored there and at the end of the directive.  A
1104 comment starting with @samp{#} is allowed at the end of the line.  If
1105 the file names contain any variable or function references, they are
1106 expanded.  @xref{Using Variables, ,How to Use Variables}.
1108 For example, if you have three @file{.mk} files, @file{a.mk},
1109 @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1110 @code{bish bash}, then the following expression
1112 @example
1113 include foo *.mk $(bar)
1114 @end example
1116 is equivalent to
1118 @example
1119 include foo a.mk b.mk c.mk bish bash
1120 @end example
1122 When @code{make} processes an @code{include} directive, it suspends
1123 reading of the containing makefile and reads from each listed file in
1124 turn.  When that is finished, @code{make} resumes reading the
1125 makefile in which the directive appears.
1127 One occasion for using @code{include} directives is when several programs,
1128 handled by individual makefiles in various directories, need to use a
1129 common set of variable definitions
1130 (@pxref{Setting, ,Setting Variables}) or pattern rules
1131 (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1133 Another such occasion is when you want to generate prerequisites from
1134 source files automatically; the prerequisites can be put in a file that
1135 is included by the main makefile.  This practice is generally cleaner
1136 than that of somehow appending the prerequisites to the end of the main
1137 makefile as has been traditionally done with other versions of
1138 @code{make}.  @xref{Automatic Prerequisites}.
1139 @cindex prerequisites, automatic generation
1140 @cindex automatic generation of prerequisites
1141 @cindex generating prerequisites automatically
1143 @cindex @code{-I}
1144 @cindex @code{--include-dir}
1145 @cindex included makefiles, default directories
1146 @cindex default directories for included makefiles
1147 @findex /usr/gnu/include
1148 @findex /usr/local/include
1149 @findex /usr/include
1150 If the specified name does not start with a slash, and the file is not
1151 found in the current directory, several other directories are searched.
1152 First, any directories you have specified with the @samp{-I} or
1153 @samp{--include-dir} option are searched
1154 (@pxref{Options Summary, ,Summary of Options}).
1155 Then the following directories (if they exist)
1156 are searched, in this order:
1157 @file{@var{prefix}/include} (normally @file{/usr/local/include}
1158 @footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if
1159 @var{prefix} has been defined to be the root of the DJGPP tree
1160 hierarchy.})
1161 @file{/usr/gnu/include},
1162 @file{/usr/local/include}, @file{/usr/include}.
1164 If an included makefile cannot be found in any of these directories, a
1165 warning message is generated, but it is not an immediately fatal error;
1166 processing of the makefile containing the @code{include} continues.
1167 Once it has finished reading makefiles, @code{make} will try to remake
1168 any that are out of date or don't exist.
1169 @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1170 Only after it has tried to find a way to remake a makefile and failed,
1171 will @code{make} diagnose the missing makefile as a fatal error.
1173 If you want @code{make} to simply ignore a makefile which does not exist
1174 or cannot be remade, with no error message, use the @w{@code{-include}}
1175 directive instead of @code{include}, like this:
1177 @example
1178 -include @var{filenames}@dots{}
1179 @end example
1181 This acts like @code{include} in every way except that there is no
1182 error (not even a warning) if any of the @var{filenames} (or any
1183 prerequisites of any of the @var{filenames}) do not exist or cannot be
1184 remade.
1186 For compatibility with some other @code{make} implementations,
1187 @code{sinclude} is another name for @w{@code{-include}}.
1189 @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
1190 @section The Variable @code{MAKEFILES}
1191 @cindex makefile, and @code{MAKEFILES} variable
1192 @cindex including (@code{MAKEFILES} variable)
1194 @vindex MAKEFILES
1195 If the environment variable @code{MAKEFILES} is defined, @code{make}
1196 considers its value as a list of names (separated by whitespace) of
1197 additional makefiles to be read before the others.  This works much
1198 like the @code{include} directive: various directories are searched
1199 for those files (@pxref{Include, ,Including Other Makefiles}).  In
1200 addition, the default goal is never taken from one of these makefiles
1201 (or any makefile included by them) and it is not an error if the files
1202 listed in @code{MAKEFILES} are not found.@refill
1204 @cindex recursion, and @code{MAKEFILES} variable
1205 The main use of @code{MAKEFILES} is in communication between recursive
1206 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1207 @code{make}}).  It usually is not desirable to set the environment
1208 variable before a top-level invocation of @code{make}, because it is
1209 usually better not to mess with a makefile from outside.  However, if
1210 you are running @code{make} without a specific makefile, a makefile in
1211 @code{MAKEFILES} can do useful things to help the built-in implicit
1212 rules work better, such as defining search paths (@pxref{Directory Search}).
1214 Some users are tempted to set @code{MAKEFILES} in the environment
1215 automatically on login, and program makefiles to expect this to be done.
1216 This is a very bad idea, because such makefiles will fail to work if run by
1217 anyone else.  It is much better to write explicit @code{include} directives
1218 in the makefiles.  @xref{Include, , Including Other Makefiles}.
1220 @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles
1221 @section How Makefiles Are Remade
1223 @cindex updating makefiles
1224 @cindex remaking makefiles
1225 @cindex makefile, remaking of
1226 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1227 files.  If a makefile can be remade from other files, you probably want
1228 @code{make} to get an up-to-date version of the makefile to read in.
1230 To this end, after reading in all makefiles, @code{make} will consider
1231 each as a goal target and attempt to update it.  If a makefile has a
1232 rule which says how to update it (found either in that very makefile or
1233 in another one) or if an implicit rule applies to it (@pxref{Implicit
1234 Rules, ,Using Implicit Rules}), it will be updated if necessary.  After
1235 all makefiles have been checked, if any have actually been changed,
1236 @code{make} starts with a clean slate and reads all the makefiles over
1237 again.  (It will also attempt to update each of them over again, but
1238 normally this will not change them again, since they are already up to
1239 date.)@refill
1241 If you know that one or more of your makefiles cannot be remade and
1242 you want to keep @code{make} from performing an implicit rule search
1243 on them, perhaps for efficiency reasons, you can use any normal method
1244 of preventing implicit rule lookup to do so.  For example, you can
1245 write an explicit rule with the makefile as the target, and an empty
1246 recipe (@pxref{Empty Recipes, ,Using Empty Recipes}).
1248 If the makefiles specify a double-colon rule to remake a file with
1249 a recipe but no prerequisites, that file will always be remade
1250 (@pxref{Double-Colon}).  In the case of makefiles, a makefile that has a
1251 double-colon rule with a recipe but no prerequisites will be remade every
1252 time @code{make} is run, and then again after @code{make} starts over
1253 and reads the makefiles in again.  This would cause an infinite loop:
1254 @code{make} would constantly remake the makefile, and never do anything
1255 else.  So, to avoid this, @code{make} will @strong{not} attempt to
1256 remake makefiles which are specified as targets of a double-colon rule
1257 with a recipe but no prerequisites.@refill
1259 If you do not specify any makefiles to be read with @samp{-f} or
1260 @samp{--file} options, @code{make} will try the default makefile names;
1261 @pxref{Makefile Names, ,What Name to Give Your Makefile}.  Unlike
1262 makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1263 @code{make} is not certain that these makefiles should exist.  However,
1264 if a default makefile does not exist but can be created by running
1265 @code{make} rules, you probably want the rules to be run so that the
1266 makefile can be used.
1268 Therefore, if none of the default makefiles exists, @code{make} will try
1269 to make each of them in the same order in which they are searched for
1270 (@pxref{Makefile Names, ,What Name to Give Your Makefile})
1271 until it succeeds in making one, or it runs out of names to try.  Note
1272 that it is not an error if @code{make} cannot find or make any makefile;
1273 a makefile is not always necessary.@refill
1275 When you use the @samp{-t} or @samp{--touch} option
1276 (@pxref{Instead of Execution, ,Instead of Executing Recipes}),
1277 you would not want to use an out-of-date makefile to decide which
1278 targets to touch.  So the @samp{-t} option has no effect on updating
1279 makefiles; they are really updated even if @samp{-t} is specified.
1280 Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1281 @samp{--just-print}) do not prevent updating of makefiles, because an
1282 out-of-date makefile would result in the wrong output for other targets.
1283 Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1284 and then print the recipe to update @file{foo} and its prerequisites
1285 without running it.  The recipe printed for @file{foo} will be the one
1286 specified in the updated contents of @file{mfile}.
1288 However, on occasion you might actually wish to prevent updating of even
1289 the makefiles.  You can do this by specifying the makefiles as goals in
1290 the command line as well as specifying them as makefiles.  When the
1291 makefile name is specified explicitly as a goal, the options @samp{-t}
1292 and so on do apply to them.
1294 Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1295 @file{mfile}, print the recipe needed to update it without actually
1296 running it, and then print the recipe needed to update @file{foo}
1297 without running that.  The recipe for @file{foo} will be the one
1298 specified by the existing contents of @file{mfile}.
1300 @node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles
1301 @section Overriding Part of Another Makefile
1303 @cindex overriding makefiles
1304 @cindex makefile, overriding
1305 Sometimes it is useful to have a makefile that is mostly just like
1306 another makefile.  You can often use the @samp{include} directive to
1307 include one in the other, and add more targets or variable definitions.
1308 However, it is illegal for two makefiles to give different recipes for
1309 the same target.  But there is another way.
1311 @cindex match-anything rule, used to override
1312 In the containing makefile (the one that wants to include the other),
1313 you can use a match-anything pattern rule to say that to remake any
1314 target that cannot be made from the information in the containing
1315 makefile, @code{make} should look in another makefile.
1316 @xref{Pattern Rules}, for more information on pattern rules.
1318 For example, if you have a makefile called @file{Makefile} that says how
1319 to make the target @samp{foo} (and other targets), you can write a
1320 makefile called @file{GNUmakefile} that contains:
1322 @example
1323 foo:
1324         frobnicate > foo
1326 %: force
1327         @@$(MAKE) -f Makefile $@@
1328 force: ;
1329 @end example
1331 If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1332 read it, and see that to make @file{foo}, it needs to run the recipe
1333 @samp{frobnicate > foo}.  If you say @samp{make bar}, @code{make} will
1334 find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1335 recipe from the pattern rule: @samp{make -f Makefile bar}.  If
1336 @file{Makefile} provides a rule for updating @file{bar}, @code{make}
1337 will apply the rule.  And likewise for any other target that
1338 @file{GNUmakefile} does not say how to make.
1340 The way this works is that the pattern rule has a pattern of just
1341 @samp{%}, so it matches any target whatever.  The rule specifies a
1342 prerequisite @file{force}, to guarantee that the recipe will be run even
1343 if the target file already exists.  We give the @file{force} target an
1344 empty recipe to prevent @code{make} from searching for an implicit rule to
1345 build it---otherwise it would apply the same match-anything rule to
1346 @file{force} itself and create a prerequisite loop!
1348 @node Reading Makefiles,  Secondary Expansion, Overriding Makefiles, Makefiles
1349 @section How @code{make} Reads a Makefile
1350 @cindex reading makefiles
1351 @cindex makefile, parsing
1353 GNU @code{make} does its work in two distinct phases.  During the first
1354 phase it reads all the makefiles, included makefiles, etc. and
1355 internalizes all the variables and their values, implicit and explicit
1356 rules, and constructs a dependency graph of all the targets and their
1357 prerequisites.  During the second phase, @code{make} uses these internal
1358 structures to determine what targets will need to be rebuilt and to
1359 invoke the rules necessary to do so.
1361 It's important to understand this two-phase approach because it has a
1362 direct impact on how variable and function expansion happens; this is
1363 often a source of some confusion when writing makefiles.  Here we will
1364 present a summary of the phases in which expansion happens for different
1365 constructs within the makefile.  We say that expansion is
1366 @dfn{immediate} if it happens during the first phase: in this case
1367 @code{make} will expand any variables or functions in that section of a
1368 construct as the makefile is parsed.  We say that expansion is
1369 @dfn{deferred} if expansion is not performed immediately.  Expansion of
1370 a deferred construct is not performed until either the construct appears
1371 later in an immediate context, or until the second phase.
1373 You may not be familiar with some of these constructs yet.  You can
1374 reference this section as you become familiar with them, in later
1375 chapters.
1377 @subheading Variable Assignment
1378 @cindex +=, expansion
1379 @cindex =, expansion
1380 @cindex ?=, expansion
1381 @cindex +=, expansion
1382 @cindex define, expansion
1384 Variable definitions are parsed as follows:
1386 @example
1387 @var{immediate} = @var{deferred}
1388 @var{immediate} ?= @var{deferred}
1389 @var{immediate} := @var{immediate}
1390 @var{immediate} += @var{deferred} or @var{immediate}
1392 define @var{immediate}
1393   @var{deferred}
1394 endef
1396 define @var{immediate} =
1397   @var{deferred}
1398 endef
1400 define @var{immediate} ?=
1401   @var{deferred}
1402 endef
1404 define @var{immediate} :=
1405   @var{immediate}
1406 endef
1408 define @var{immediate} +=
1409   @var{deferred} or @var{immediate}
1410 endef
1411 @end example
1413 For the append operator, @samp{+=}, the right-hand side is considered
1414 immediate if the variable was previously set as a simple variable
1415 (@samp{:=}), and deferred otherwise.
1417 @subheading Conditional Directives
1418 @cindex ifdef, expansion
1419 @cindex ifeq, expansion
1420 @cindex ifndef, expansion
1421 @cindex ifneq, expansion
1423 Conditional directives are parsed immediately.  This means, for
1424 example, that automatic variables cannot be used in conditional
1425 directives, as automatic variables are not set until the recipe for
1426 that rule is invoked.  If you need to use automatic variables in a
1427 conditional directive you @emph{must} move the condition into the
1428 recipe and use shell conditional syntax instead.
1430 @subheading Rule Definition
1431 @cindex target, expansion
1432 @cindex prerequisite, expansion
1433 @cindex implicit rule, expansion
1434 @cindex pattern rule, expansion
1435 @cindex explicit rule, expansion
1437 A rule is always expanded the same way, regardless of the form:
1439 @example
1440 @var{immediate} : @var{immediate} ; @var{deferred}
1441         @var{deferred}
1442 @end example
1444 That is, the target and prerequisite sections are expanded immediately,
1445 and the recipe used to construct the target is always deferred.  This
1446 general rule is true for explicit rules, pattern rules, suffix rules,
1447 static pattern rules, and simple prerequisite definitions.
1449 @node Secondary Expansion, , Reading Makefiles, Makefiles
1450 @section Secondary Expansion
1451 @cindex secondary expansion
1452 @cindex expansion, secondary
1455 In the previous section we learned that GNU @code{make} works in two
1456 distinct phases: a read-in phase and a target-update phase
1457 (@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}).  GNU
1458 make also has the ability to enable a @emph{second expansion} of the
1459 prerequisites (only) for some or all targets defined in the makefile.
1460 In order for this second expansion to occur, the special target
1461 @code{.SECONDEXPANSION} must be defined before the first prerequisite
1462 list that makes use of this feature.
1464 If that special target is defined then in between the two phases
1465 mentioned above, right at the end of the read-in phase, all the
1466 prerequisites of the targets defined after the special target are
1467 expanded a @emph{second time}.  In most circumstances this secondary
1468 expansion will have no effect, since all variable and function
1469 references will have been expanded during the initial parsing of the
1470 makefiles.  In order to take advantage of the secondary expansion
1471 phase of the parser, then, it's necessary to @emph{escape} the
1472 variable or function reference in the makefile.  In this case the
1473 first expansion merely un-escapes the reference but doesn't expand it,
1474 and expansion is left to the secondary expansion phase.  For example,
1475 consider this makefile:
1477 @example
1479 ONEVAR = onefile
1480 TWOVAR = twofile
1481 myfile: $(ONEVAR) $$(TWOVAR)
1482 @end example
1484 After the first expansion phase the prerequisites list of the
1485 @file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the
1486 first (unescaped) variable reference to @var{ONEVAR} is expanded,
1487 while the second (escaped) variable reference is simply unescaped,
1488 without being recognized as a variable reference.  Now during the
1489 secondary expansion the first word is expanded again but since it
1490 contains no variable or function references it remains the static
1491 value @file{onefile}, while the second word is now a normal reference
1492 to the variable @var{TWOVAR}, which is expanded to the value
1493 @file{twofile}.  The final result is that there are two prerequisites,
1494 @file{onefile} and @file{twofile}.
1496 Obviously, this is not a very interesting case since the same result
1497 could more easily have been achieved simply by having both variables
1498 appear, unescaped, in the prerequisites list.  One difference becomes
1499 apparent if the variables are reset; consider this example:
1501 @example
1503 AVAR = top
1504 onefile: $(AVAR)
1505 twofile: $$(AVAR)
1506 AVAR = bottom
1507 @end example
1509 Here the prerequisite of @file{onefile} will be expanded immediately,
1510 and resolve to the value @file{top}, while the prerequisite of
1511 @file{twofile} will not be full expanded until the secondary expansion
1512 and yield a value of @file{bottom}.
1514 This is marginally more exciting, but the true power of this feature
1515 only becomes apparent when you discover that secondary expansions
1516 always take place within the scope of the automatic variables for that
1517 target.  This means that you can use variables such as @code{$@@},
1518 @code{$*}, etc. during the second expansion and they will have their
1519 expected values, just as in the recipe.  All you have to do is defer
1520 the expansion by escaping the @code{$}.  Also, secondary expansion
1521 occurs for both explicit and implicit (pattern) rules.  Knowing this,
1522 the possible uses for this feature increase dramatically.  For
1523 example:
1525 @example
1527 main_OBJS := main.o try.o test.o
1528 lib_OBJS := lib.o api.o
1530 main lib: $$($$@@_OBJS)
1531 @end example
1533 Here, after the initial expansion the prerequisites of both the
1534 @file{main} and @file{lib} targets will be @code{$($@@_OBJS)}.  During
1535 the secondary expansion, the @code{$@@} variable is set to the name of
1536 the target and so the expansion for the @file{main} target will yield
1537 @code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the
1538 secondary expansion for the @file{lib} target will yield
1539 @code{$(lib_OBJS)}, or @code{lib.o api.o}.
1541 You can also mix in functions here, as long as they are properly escaped:
1543 @example
1544 main_SRCS := main.c try.c test.c
1545 lib_SRCS := lib.c api.c
1548 main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS))
1549 @end example
1551 This version allows users to specify source files rather than object
1552 files, but gives the same resulting prerequisites list as the previous
1553 example.
1555 Evaluation of automatic variables during the secondary expansion
1556 phase, especially of the target name variable @code{$$@@}, behaves
1557 similarly to evaluation within recipes.  However, there are some
1558 subtle differences and ``corner cases'' which come into play for the
1559 different types of rule definitions that @code{make} understands.  The
1560 subtleties of using the different automatic variables are described
1561 below.
1563 @subheading Secondary Expansion of Explicit Rules
1564 @cindex secondary expansion and explicit rules
1565 @cindex explicit rules, secondary expansion of
1567 During the secondary expansion of explicit rules, @code{$$@@} and
1568 @code{$$%} evaluate, respectively, to the file name of the target and,
1569 when the target is an archive member, the target member name.  The
1570 @code{$$<} variable evaluates to the first prerequisite in the first
1571 rule for this target.  @code{$$^} and @code{$$+} evaluate to the list
1572 of all prerequisites of rules @emph{that have already appeared} for
1573 the same target (@code{$$+} with repetitions and @code{$$^}
1574 without).  The following example will help illustrate these behaviors:
1576 @example
1579 foo: foo.1 bar.1 $$< $$^ $$+    # line #1
1581 foo: foo.2 bar.2 $$< $$^ $$+    # line #2
1583 foo: foo.3 bar.3 $$< $$^ $$+    # line #3
1584 @end example
1586 In the first prerequisite list, all three variables (@code{$$<},
1587 @code{$$^}, and @code{$$+}) expand to the empty string.  In the
1588 second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and
1589 @code{foo.1 bar.1} respectively.  In the third they will have values
1590 @code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1
1591 foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively.
1593 Rules undergo secondary expansion in makefile order, except that
1594 the rule with the recipe is always evaluated last.
1596 The variables @code{$$?} and @code{$$*} are not available and expand
1597 to the empty string.
1599 @subheading Secondary Expansion of Static Pattern Rules
1600 @cindex secondary expansion and static pattern rules
1601 @cindex static pattern rules, secondary expansion of
1603 Rules for secondary expansion of static pattern rules are identical to
1604 those for explicit rules, above, with one exception: for static
1605 pattern rules the @code{$$*} variable is set to the pattern stem.  As
1606 with explicit rules, @code{$$?} is not available and expands to the
1607 empty string.
1609 @subheading Secondary Expansion of Implicit Rules
1610 @cindex secondary expansion and implicit rules
1611 @cindex implicit rules, secondary expansion of
1613 As @code{make} searches for an implicit rule, it substitutes the stem
1614 and then performs secondary expansion for every rule with a matching
1615 target pattern.  The value of the automatic variables is derived in
1616 the same fashion as for static pattern rules.  As an example:
1618 @example
1621 foo: bar
1623 foo foz: fo%: bo%
1625 %oo: $$< $$^ $$+ $$*
1626 @end example
1628 When the implicit rule is tried for target @file{foo}, @code{$$<}
1629 expands to @file{bar}, @code{$$^} expands to @file{bar boo},
1630 @code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to
1631 @file{f}.
1633 Note that the directory prefix (D), as described in @ref{Implicit Rule
1634 Search, ,Implicit Rule Search Algorithm}, is appended (after
1635 expansion) to all the patterns in the prerequisites list.  As an
1636 example:
1638 @example
1641 /tmp/foo.o:
1643 %.o: $$(addsuffix /%.c,foo bar) foo.h
1644 @end example
1646 The prerequisite list after the secondary expansion and directory
1647 prefix reconstruction will be @file{/tmp/foo/foo.c /tmp/var/bar/foo.c
1648 foo.h}.  If you are not interested in this reconstruction, you can use
1649 @code{$$*} instead of @code{%} in the prerequisites list.
1651 @node Rules, Recipes, Makefiles, Top
1652 @chapter Writing Rules
1653 @cindex writing rules
1654 @cindex rule, how to write
1655 @cindex target
1656 @cindex prerequisite
1658 A @dfn{rule} appears in the makefile and says when and how to remake
1659 certain files, called the rule's @dfn{targets} (most often only one per rule).
1660 It lists the other files that are the @dfn{prerequisites} of the target, and
1661 the @dfn{recipe} to use to create or update the target.
1663 @cindex default goal
1664 @cindex goal, default
1665 The order of rules is not significant, except for determining the
1666 @dfn{default goal}: the target for @code{make} to consider, if you do
1667 not otherwise specify one.  The default goal is the target of the first
1668 rule in the first makefile.  If the first rule has multiple targets,
1669 only the first target is taken as the default.  There are two
1670 exceptions: a target starting with a period is not a default unless it
1671 contains one or more slashes, @samp{/}, as well; and, a target that
1672 defines a pattern rule has no effect on the default goal.
1673 (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1675 Therefore, we usually write the makefile so that the first rule is the
1676 one for compiling the entire program or all the programs described by
1677 the makefile (often with a target called @samp{all}).
1678 @xref{Goals, ,Arguments to Specify the Goals}.
1680 @menu
1681 * Rule Example::                An example explained.
1682 * Rule Syntax::                 General syntax explained.
1683 * Prerequisite Types::          There are two types of prerequisites.
1684 * Wildcards::                   Using wildcard characters such as `*'.
1685 * Directory Search::            Searching other directories for source files.
1686 * Phony Targets::               Using a target that is not a real file's name.
1687 * Force Targets::               You can use a target without recipes
1688                                   or prerequisites to mark other targets
1689                                   as phony.
1690 * Empty Targets::               When only the date matters and the
1691                                   files are empty.
1692 * Special Targets::             Targets with special built-in meanings.
1693 * Multiple Targets::            When to make use of several targets in a rule.
1694 * Multiple Rules::              How to use several rules with the same target.
1695 * Static Pattern::              Static pattern rules apply to multiple targets
1696                                   and can vary the prerequisites according to
1697                                   the target name.
1698 * Double-Colon::                How to use a special kind of rule to allow
1699                                   several independent rules for one target.
1700 * Automatic Prerequisites::     How to automatically generate rules giving
1701                                   prerequisites from source files themselves.
1702 @end menu
1704 @ifnottex
1705 @node Rule Example, Rule Syntax, Rules, Rules
1706 @section Rule Example
1708 Here is an example of a rule:
1710 @example
1711 foo.o : foo.c defs.h       # module for twiddling the frobs
1712         cc -c -g foo.c
1713 @end example
1715 Its target is @file{foo.o} and its prerequisites are @file{foo.c} and
1716 @file{defs.h}.  It has one command in the recipe: @samp{cc -c -g foo.c}.
1717 The recipe starts with a tab to identify it as a recipe.
1719 This rule says two things:
1721 @itemize @bullet
1722 @item
1723 How to decide whether @file{foo.o} is out of date: it is out of date
1724 if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1725 more recent than it.
1727 @item
1728 How to update the file @file{foo.o}: by running @code{cc} as stated.
1729 The recipe does not explicitly mention @file{defs.h}, but we presume
1730 that @file{foo.c} includes it, and that that is why @file{defs.h} was
1731 added to the prerequisites.
1732 @end itemize
1733 @end ifnottex
1735 @node Rule Syntax, Prerequisite Types, Rule Example, Rules
1736 @section Rule Syntax
1738 @cindex rule syntax
1739 @cindex syntax of rules
1740 In general, a rule looks like this:
1742 @example
1743 @var{targets} : @var{prerequisites}
1744         @var{recipe}
1745         @dots{}
1746 @end example
1748 @noindent
1749 or like this:
1751 @example
1752 @var{targets} : @var{prerequisites} ; @var{recipe}
1753         @var{recipe}
1754         @dots{}
1755 @end example
1757 @cindex targets
1758 @cindex rule targets
1759 The @var{targets} are file names, separated by spaces.  Wildcard
1760 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1761 in File Names}) and a name of the form @file{@var{a}(@var{m})}
1762 represents member @var{m} in archive file @var{a}
1763 (@pxref{Archive Members, ,Archive Members as Targets}).
1764 Usually there is only one
1765 target per rule, but occasionally there is a reason to have more
1766 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1768 @cindex recipes
1769 @cindex tab character (in commands)
1770 The @var{recipe} lines start with a tab character (or the first
1771 character in the value of the @code{.CMDPREFIX} variable;
1772 @pxref{Special Variables}).  The first recipe line may appear on the line
1773 after the prerequisites, with a tab character, or may appear on the
1774 same line, with a semicolon.  Either way, the effect is the same.
1775 There are other differences in the syntax of recipes.
1776 @xref{Recipes, ,Writing Recipes in Rules}.
1778 @cindex dollar sign (@code{$}), in rules
1779 @cindex @code{$}, in rules
1780 @cindex rules, and @code{$}
1781 Because dollar signs are used to start @code{make} variable
1782 references, if you really want a dollar sign in a target or
1783 prerequisite you must write two of them, @samp{$$} (@pxref{Using
1784 Variables, ,How to Use Variables}).  If you have enabled secondary
1785 expansion (@pxref{Secondary Expansion}) and you want a literal dollar
1786 sign in the prerequisites list, you must actually write @emph{four}
1787 dollar signs (@samp{$$$$}).
1789 You may split a long line by inserting a backslash followed by a
1790 newline, but this is not required, as @code{make} places no limit on
1791 the length of a line in a makefile.
1793 A rule tells @code{make} two things: when the targets are out of date,
1794 and how to update them when necessary.
1796 @cindex prerequisites
1797 @cindex rule prerequisites
1798 The criterion for being out of date is specified in terms of the
1799 @var{prerequisites}, which consist of file names separated by spaces.
1800 (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1801 A target is out of date if it does not exist or if it is older than any
1802 of the prerequisites (by comparison of last-modification times).  The
1803 idea is that the contents of the target file are computed based on
1804 information in the prerequisites, so if any of the prerequisites changes,
1805 the contents of the existing target file are no longer necessarily
1806 valid.
1808 How to update is specified by a @var{recipe}.  This is one or more
1809 lines to be executed by the shell (normally @samp{sh}), but with some
1810 extra features (@pxref{Recipes, ,Writing Recipes in Rules}).
1812 @node Prerequisite Types, Wildcards, Rule Syntax, Rules
1813 @comment  node-name,  next,  previous,  up
1814 @section Types of Prerequisites
1815 @cindex prerequisite types
1816 @cindex types of prerequisites
1818 @cindex prerequisites, normal
1819 @cindex normal prerequisites
1820 @cindex prerequisites, order-only
1821 @cindex order-only prerequisites
1822 There are actually two different types of prerequisites understood by
1823 GNU @code{make}: normal prerequisites such as described in the
1824 previous section, and @dfn{order-only} prerequisites.  A normal
1825 prerequisite makes two statements: first, it imposes an order of
1826 execution of recipes: any recipes necessary to build any of a
1827 target's prerequisites will be fully executed before any recipe
1828 necessary to build the target.  Second, it imposes a dependency
1829 relationship: if any prerequisite is newer than the target, then the
1830 target is considered out-of-date and must be rebuilt.
1832 Normally, this is exactly what you want: if a target's prerequisite is
1833 updated, then the target should also be updated.
1835 Occasionally, however, you have a situation where you want to impose a
1836 specific ordering on the rules to be invoked @emph{without} forcing
1837 the target to be updated if one of those rules is executed.  In that
1838 case, you want to define @dfn{order-only} prerequisites.  Order-only
1839 prerequisites can be specified by placing a pipe symbol (@code{|})
1840 in the prerequisites list: any prerequisites to the left of the pipe
1841 symbol are normal; any prerequisites to the right are order-only:
1843 @example
1844 @var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites}
1845 @end example
1847 The normal prerequisites section may of course be empty.  Also, you
1848 may still declare multiple lines of prerequisites for the same target:
1849 they are appended appropriately (normal prerequisites are appended to
1850 the list of normal prerequisites; order-only prerequisites are
1851 appended to the list of order-only prerequisites).  Note that if you
1852 declare the same file to be both a normal and an order-only
1853 prerequisite, the normal prerequisite takes precedence (since they
1854 have a strict superset of the behavior of an order-only prerequisite).
1856 Consider an example where your targets are to be placed in a separate
1857 directory, and that directory might not exist before @code{make} is
1858 run.  In this situation, you want the directory to be created before
1859 any targets are placed into it but, because the timestamps on
1860 directories change whenever a file is added, removed, or renamed, we
1861 certainly don't want to rebuild all the targets whenever the
1862 directory's timestamp changes.  One way to manage this is with
1863 order-only prerequisites: make the directory an order-only
1864 prerequisite on all the targets:
1866 @example
1867 OBJDIR := objdir
1868 OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)
1870 $(OBJDIR)/%.o : %.c
1871         $(COMPILE.c) $(OUTPUT_OPTION) $<
1873 all: $(OBJS)
1875 $(OBJS): | $(OBJDIR)
1877 $(OBJDIR):
1878         mkdir $(OBJDIR)
1879 @end example
1881 Now the rule to create the @file{objdir} directory will be run, if
1882 needed, before any @samp{.o} is built, but no @samp{.o} will be built
1883 because the @file{objdir} directory timestamp changed.
1885 @node Wildcards, Directory Search, Prerequisite Types, Rules
1886 @section Using Wildcard Characters in File Names
1887 @cindex wildcard
1888 @cindex file name with wildcards
1889 @cindex globbing (wildcards)
1891 @cindex @code{*} (wildcard character)
1892 @cindex @code{?} (wildcard character)
1893 @cindex @code{[@dots{}]} (wildcard characters)
1894 A single file name can specify many files using @dfn{wildcard characters}.
1895 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
1896 @samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
1897 specifies a list of all the files (in the working directory) whose names
1898 end in @samp{.c}.@refill
1900 @cindex @code{~} (tilde)
1901 @cindex tilde (@code{~})
1902 @cindex home directory
1903 The character @samp{~} at the beginning of a file name also has special
1904 significance.  If alone, or followed by a slash, it represents your home
1905 directory.  For example @file{~/bin} expands to @file{/home/you/bin}.
1906 If the @samp{~} is followed by a word, the string represents the home
1907 directory of the user named by that word.  For example @file{~john/bin}
1908 expands to @file{/home/john/bin}.  On systems which don't have a home
1909 directory for each user (such as MS-DOS or MS-Windows), this
1910 functionality can be simulated by setting the environment variable
1911 @var{HOME}.@refill
1913 Wildcard expansion is performed by @code{make} automatically in
1914 targets and in prerequisites.  In recipes, the shell is responsible
1915 for wildcard expansion.  In other contexts, wildcard expansion happens
1916 only if you request it explicitly with the @code{wildcard} function.
1918 The special significance of a wildcard character can be turned off by
1919 preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
1920 specific file whose name consists of @samp{foo}, an asterisk, and
1921 @samp{bar}.@refill
1923 @menu
1924 * Wildcard Examples::           Several examples
1925 * Wildcard Pitfall::            Problems to avoid.
1926 * Wildcard Function::           How to cause wildcard expansion where
1927                                   it does not normally take place.
1928 @end menu
1930 @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards
1931 @subsection Wildcard Examples
1933 Wildcards can be used in the recipe of a rule, where they are expanded
1934 by the shell.  For example, here is a rule to delete all the object files:
1936 @example
1937 @group
1938 clean:
1939         rm -f *.o
1940 @end group
1941 @end example
1942 @cindex @code{rm} (shell command)
1944 Wildcards are also useful in the prerequisites of a rule.  With the
1945 following rule in the makefile, @samp{make print} will print all the
1946 @samp{.c} files that have changed since the last time you printed them:
1948 @example
1949 print: *.c
1950         lpr -p $?
1951         touch print
1952 @end example
1954 @cindex @code{print} target
1955 @cindex @code{lpr} (shell command)
1956 @cindex @code{touch} (shell command)
1957 @noindent
1958 This rule uses @file{print} as an empty target file; see @ref{Empty
1959 Targets, ,Empty Target Files to Record Events}.  (The automatic variable
1960 @samp{$?} is used to print only those files that have changed; see
1961 @ref{Automatic Variables}.)@refill
1963 Wildcard expansion does not happen when you define a variable.  Thus, if
1964 you write this:
1966 @example
1967 objects = *.o
1968 @end example
1970 @noindent
1971 then the value of the variable @code{objects} is the actual string
1972 @samp{*.o}.  However, if you use the value of @code{objects} in a
1973 target or prerequisite, wildcard expansion will take place there.  If
1974 you use the value of @code{objects} in a recipe, the shell may perform
1975 wildcard expansion when the recipe runs.  To set @code{objects} to the
1976 expansion, instead use:
1978 @example
1979 objects := $(wildcard *.o)
1980 @end example
1982 @noindent
1983 @xref{Wildcard Function}.
1985 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
1986 @subsection Pitfalls of Using Wildcards
1987 @cindex wildcard pitfalls
1988 @cindex pitfalls of wildcards
1989 @cindex mistakes with wildcards
1990 @cindex errors with wildcards
1991 @cindex problems with wildcards
1993 Now here is an example of a naive way of using wildcard expansion, that
1994 does not do what you would intend.  Suppose you would like to say that the
1995 executable file @file{foo} is made from all the object files in the
1996 directory, and you write this:
1998 @example
1999 objects = *.o
2001 foo : $(objects)
2002         cc -o foo $(CFLAGS) $(objects)
2003 @end example
2005 @noindent
2006 The value of @code{objects} is the actual string @samp{*.o}.  Wildcard
2007 expansion happens in the rule for @file{foo}, so that each @emph{existing}
2008 @samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if
2009 necessary.
2011 But what if you delete all the @samp{.o} files?  When a wildcard matches
2012 no files, it is left as it is, so then @file{foo} will depend on the
2013 oddly-named file @file{*.o}.  Since no such file is likely to exist,
2014 @code{make} will give you an error saying it cannot figure out how to
2015 make @file{*.o}.  This is not what you want!
2017 Actually it is possible to obtain the desired result with wildcard
2018 expansion, but you need more sophisticated techniques, including the
2019 @code{wildcard} function and string substitution.
2020 @ifnottex
2021 @xref{Wildcard Function, ,The Function @code{wildcard}}.
2022 @end ifnottex
2023 @iftex
2024 These are described in the following section.
2025 @end iftex
2027 @cindex wildcards and MS-DOS/MS-Windows backslashes
2028 @cindex backslashes in pathnames and wildcard expansion
2030 Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to
2031 separate directories in pathnames, like so:
2033 @example
2034   c:\foo\bar\baz.c
2035 @end example
2037 This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the
2038 @file{c:} part is the so-called drive letter).  When @code{make} runs on
2039 these systems, it supports backslashes as well as the Unix-style forward
2040 slashes in pathnames.  However, this support does @emph{not} include the
2041 wildcard expansion, where backslash is a quote character.  Therefore,
2042 you @emph{must} use Unix-style slashes in these cases.
2045 @node Wildcard Function,  , Wildcard Pitfall, Wildcards
2046 @subsection The Function @code{wildcard}
2047 @findex wildcard
2049 Wildcard expansion happens automatically in rules.  But wildcard expansion
2050 does not normally take place when a variable is set, or inside the
2051 arguments of a function.  If you want to do wildcard expansion in such
2052 places, you need to use the @code{wildcard} function, like this:
2054 @example
2055 $(wildcard @var{pattern}@dots{})
2056 @end example
2058 @noindent
2059 This string, used anywhere in a makefile, is replaced by a
2060 space-separated list of names of existing files that match one of the
2061 given file name patterns.  If no existing file name matches a pattern,
2062 then that pattern is omitted from the output of the @code{wildcard}
2063 function.  Note that this is different from how unmatched wildcards
2064 behave in rules, where they are used verbatim rather than ignored
2065 (@pxref{Wildcard Pitfall}).
2067 One use of the @code{wildcard} function is to get a list of all the C source
2068 files in a directory, like this:
2070 @example
2071 $(wildcard *.c)
2072 @end example
2074 We can change the list of C source files into a list of object files by
2075 replacing the @samp{.c} suffix with @samp{.o} in the result, like this:
2077 @example
2078 $(patsubst %.c,%.o,$(wildcard *.c))
2079 @end example
2081 @noindent
2082 (Here we have used another function, @code{patsubst}.
2083 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
2085 Thus, a makefile to compile all C source files in the directory and then
2086 link them together could be written as follows:
2088 @example
2089 objects := $(patsubst %.c,%.o,$(wildcard *.c))
2091 foo : $(objects)
2092         cc -o foo $(objects)
2093 @end example
2095 @noindent
2096 (This takes advantage of the implicit rule for compiling C programs, so
2097 there is no need to write explicit rules for compiling the files.
2098 @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
2099 @samp{:=}, which is a variant of @samp{=}.)
2101 @node Directory Search, Phony Targets, Wildcards, Rules
2102 @section Searching Directories for Prerequisites
2103 @vindex VPATH
2104 @findex vpath
2105 @cindex vpath
2106 @cindex search path for prerequisites (@code{VPATH})
2107 @cindex directory search (@code{VPATH})
2109 For large systems, it is often desirable to put sources in a separate
2110 directory from the binaries.  The @dfn{directory search} features of
2111 @code{make} facilitate this by searching several directories
2112 automatically to find a prerequisite.  When you redistribute the files
2113 among directories, you do not need to change the individual rules,
2114 just the search paths.
2116 @menu
2117 * General Search::              Specifying a search path that applies
2118                                   to every prerequisite.
2119 * Selective Search::            Specifying a search path
2120                                   for a specified class of names.
2121 * Search Algorithm::            When and how search paths are applied.
2122 * Recipes/Search::             How to write recipes that work together
2123                                   with search paths.
2124 * Implicit/Search::             How search paths affect implicit rules.
2125 * Libraries/Search::            Directory search for link libraries.
2126 @end menu
2128 @node General Search, Selective Search, Directory Search, Directory Search
2129 @subsection @code{VPATH}: Search Path for All Prerequisites
2130 @vindex VPATH
2132 The value of the @code{make} variable @code{VPATH} specifies a list of
2133 directories that @code{make} should search.  Most often, the
2134 directories are expected to contain prerequisite files that are not in the
2135 current directory; however, @code{make} uses @code{VPATH} as a search
2136 list for both prerequisites and targets of rules.
2138 Thus, if a file that is listed as a target or prerequisite does not exist
2139 in the current directory, @code{make} searches the directories listed in
2140 @code{VPATH} for a file with that name.  If a file is found in one of
2141 them, that file may become the prerequisite (see below).  Rules may then
2142 specify the names of files in the prerequisite list as if they all
2143 existed in the current directory.  @xref{Recipes/Search, ,Writing Recipes with Directory Search}.
2145 In the @code{VPATH} variable, directory names are separated by colons or
2146 blanks.  The order in which directories are listed is the order followed
2147 by @code{make} in its search.  (On MS-DOS and MS-Windows, semi-colons
2148 are used as separators of directory names in @code{VPATH}, since the
2149 colon can be used in the pathname itself, after the drive letter.)
2151 For example,
2153 @example
2154 VPATH = src:../headers
2155 @end example
2157 @noindent
2158 specifies a path containing two directories, @file{src} and
2159 @file{../headers}, which @code{make} searches in that order.
2161 With this value of @code{VPATH}, the following rule,
2163 @example
2164 foo.o : foo.c
2165 @end example
2167 @noindent
2168 is interpreted as if it were written like this:
2170 @example
2171 foo.o : src/foo.c
2172 @end example
2174 @noindent
2175 assuming the file @file{foo.c} does not exist in the current directory but
2176 is found in the directory @file{src}.
2178 @node Selective Search, Search Algorithm, General Search, Directory Search
2179 @subsection The @code{vpath} Directive
2180 @findex vpath
2182 Similar to the @code{VPATH} variable, but more selective, is the
2183 @code{vpath} directive (note lower case), which allows you to specify a
2184 search path for a particular class of file names: those that match a
2185 particular pattern.  Thus you can supply certain search directories for
2186 one class of file names and other directories (or none) for other file
2187 names.
2189 There are three forms of the @code{vpath} directive:
2191 @table @code
2192 @item vpath @var{pattern} @var{directories}
2193 Specify the search path @var{directories} for file names that match
2194 @var{pattern}.
2196 The search path, @var{directories}, is a list of directories to be
2197 searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or
2198 blanks, just like the search path used in the @code{VPATH} variable.
2200 @item vpath @var{pattern}
2201 Clear out the search path associated with @var{pattern}.
2203 @c Extra blank line makes sure this gets two lines.
2204 @item vpath
2206 Clear all search paths previously specified with @code{vpath} directives.
2207 @end table
2209 A @code{vpath} pattern is a string containing a @samp{%} character.  The
2210 string must match the file name of a prerequisite that is being searched
2211 for, the @samp{%} character matching any sequence of zero or more
2212 characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
2213 Redefining Pattern Rules}).  For example, @code{%.h} matches files that
2214 end in @code{.h}.  (If there is no @samp{%}, the pattern must match the
2215 prerequisite exactly, which is not useful very often.)
2217 @cindex @code{%}, quoting in @code{vpath}
2218 @cindex @code{%}, quoting with @code{\} (backslash)
2219 @cindex @code{\} (backslash), to quote @code{%}
2220 @cindex backslash (@code{\}), to quote @code{%}
2221 @cindex quoting @code{%}, in @code{vpath}
2222 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
2223 with preceding backslashes (@samp{\}).  Backslashes that would otherwise
2224 quote @samp{%} characters can be quoted with more backslashes.
2225 Backslashes that quote @samp{%} characters or other backslashes are
2226 removed from the pattern before it is compared to file names.  Backslashes
2227 that are not in danger of quoting @samp{%} characters go unmolested.@refill
2229 When a prerequisite fails to exist in the current directory, if the
2230 @var{pattern} in a @code{vpath} directive matches the name of the
2231 prerequisite file, then the @var{directories} in that directive are searched
2232 just like (and before) the directories in the @code{VPATH} variable.
2234 For example,
2236 @example
2237 vpath %.h ../headers
2238 @end example
2240 @noindent
2241 tells @code{make} to look for any prerequisite whose name ends in @file{.h}
2242 in the directory @file{../headers} if the file is not found in the current
2243 directory.
2245 If several @code{vpath} patterns match the prerequisite file's name, then
2246 @code{make} processes each matching @code{vpath} directive one by one,
2247 searching all the directories mentioned in each directive.  @code{make}
2248 handles multiple @code{vpath} directives in the order in which they
2249 appear in the makefile; multiple directives with the same pattern are
2250 independent of each other.
2252 @need 750
2253 Thus,
2255 @example
2256 @group
2257 vpath %.c foo
2258 vpath %   blish
2259 vpath %.c bar
2260 @end group
2261 @end example
2263 @noindent
2264 will look for a file ending in @samp{.c} in @file{foo}, then
2265 @file{blish}, then @file{bar}, while
2267 @example
2268 @group
2269 vpath %.c foo:bar
2270 vpath %   blish
2271 @end group
2272 @end example
2274 @noindent
2275 will look for a file ending in @samp{.c} in @file{foo}, then
2276 @file{bar}, then @file{blish}.
2278 @node Search Algorithm, Recipes/Search, Selective Search, Directory Search
2279 @subsection How Directory Searches are Performed
2280 @cindex algorithm for directory search
2281 @cindex directory search algorithm
2283 When a prerequisite is found through directory search, regardless of type
2284 (general or selective), the pathname located may not be the one that
2285 @code{make} actually provides you in the prerequisite list.  Sometimes
2286 the path discovered through directory search is thrown away.
2288 The algorithm @code{make} uses to decide whether to keep or abandon a
2289 path found via directory search is as follows:
2291 @enumerate
2292 @item
2293 If a target file does not exist at the path specified in the makefile,
2294 directory search is performed.
2296 @item
2297 If the directory search is successful, that path is kept and this file
2298 is tentatively stored as the target.
2300 @item
2301 All prerequisites of this target are examined using this same method.
2303 @item
2304 After processing the prerequisites, the target may or may not need to be
2305 rebuilt:
2307 @enumerate a
2308 @item
2309 If the target does @emph{not} need to be rebuilt, the path to the file
2310 found during directory search is used for any prerequisite lists which
2311 contain this target.  In short, if @code{make} doesn't need to rebuild
2312 the target then you use the path found via directory search.
2314 @item
2315 If the target @emph{does} need to be rebuilt (is out-of-date), the
2316 pathname found during directory search is @emph{thrown away}, and the
2317 target is rebuilt using the file name specified in the makefile.  In
2318 short, if @code{make} must rebuild, then the target is rebuilt locally,
2319 not in the directory found via directory search.
2320 @end enumerate
2321 @end enumerate
2323 This algorithm may seem complex, but in practice it is quite often
2324 exactly what you want.
2326 @cindex traditional directory search (GPATH)
2327 @cindex directory search, traditional (GPATH)
2328 Other versions of @code{make} use a simpler algorithm: if the file does
2329 not exist, and it is found via directory search, then that pathname is
2330 always used whether or not the target needs to be built.  Thus, if the
2331 target is rebuilt it is created at the pathname discovered during
2332 directory search.
2334 @vindex GPATH
2335 If, in fact, this is the behavior you want for some or all of your
2336 directories, you can use the @code{GPATH} variable to indicate this to
2337 @code{make}.
2339 @code{GPATH} has the same syntax and format as @code{VPATH} (that is, a
2340 space- or colon-delimited list of pathnames).  If an out-of-date target
2341 is found by directory search in a directory that also appears in
2342 @code{GPATH}, then that pathname is not thrown away.  The target is
2343 rebuilt using the expanded path.
2345 @node Recipes/Search, Implicit/Search, Search Algorithm, Directory Search
2346 @subsection Writing Recipes with Directory Search
2347 @cindex recipes, and directory search
2348 @cindex directory search (@code{VPATH}), and recipes
2350 When a prerequisite is found in another directory through directory search,
2351 this cannot change the recipe of the rule; they will execute as written.
2352 Therefore, you must write the recipe with care so that it will look for
2353 the prerequisite in the directory where @code{make} finds it.
2355 This is done with the @dfn{automatic variables} such as @samp{$^}
2356 (@pxref{Automatic Variables}).
2357 For instance, the value of @samp{$^} is a
2358 list of all the prerequisites of the rule, including the names of
2359 the directories in which they were found, and the value of
2360 @samp{$@@} is the target.  Thus:@refill
2362 @example
2363 foo.o : foo.c
2364         cc -c $(CFLAGS) $^ -o $@@
2365 @end example
2367 @noindent
2368 (The variable @code{CFLAGS} exists so you can specify flags for C
2369 compilation by implicit rules; we use it here for consistency so it will
2370 affect all C compilations uniformly;
2371 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
2373 Often the prerequisites include header files as well, which you do not
2374 want to mention in the recipe.  The automatic variable @samp{$<} is
2375 just the first prerequisite:
2377 @example
2378 VPATH = src:../headers
2379 foo.o : foo.c defs.h hack.h
2380         cc -c $(CFLAGS) $< -o $@@
2381 @end example
2383 @node Implicit/Search, Libraries/Search, Recipes/Search, Directory Search
2384 @subsection Directory Search and Implicit Rules
2385 @cindex @code{VPATH}, and implicit rules
2386 @cindex directory search (@code{VPATH}), and implicit rules
2387 @cindex search path for prerequisites (@code{VPATH}), and implicit rules
2388 @cindex implicit rule, and directory search
2389 @cindex implicit rule, and @code{VPATH}
2390 @cindex rule, implicit, and directory search
2391 @cindex rule, implicit, and @code{VPATH}
2393 The search through the directories specified in @code{VPATH} or with
2394 @code{vpath} also happens during consideration of implicit rules
2395 (@pxref{Implicit Rules, ,Using Implicit Rules}).
2397 For example, when a file @file{foo.o} has no explicit rule, @code{make}
2398 considers implicit rules, such as the built-in rule to compile
2399 @file{foo.c} if that file exists.  If such a file is lacking in the
2400 current directory, the appropriate directories are searched for it.  If
2401 @file{foo.c} exists (or is mentioned in the makefile) in any of the
2402 directories, the implicit rule for C compilation is applied.
2404 The recipes of implicit rules normally use automatic variables as a
2405 matter of necessity; consequently they will use the file names found by
2406 directory search with no extra effort.
2408 @node Libraries/Search,  , Implicit/Search, Directory Search
2409 @subsection Directory Search for Link Libraries
2410 @cindex link libraries, and directory search
2411 @cindex libraries for linking, directory search
2412 @cindex directory search (@code{VPATH}), and link libraries
2413 @cindex @code{VPATH}, and link libraries
2414 @cindex search path for prerequisites (@code{VPATH}), and link libraries
2415 @cindex @code{-l} (library search)
2416 @cindex link libraries, patterns matching
2417 @cindex @code{.LIBPATTERNS}, and link libraries
2418 @vindex .LIBPATTERNS
2420 Directory search applies in a special way to libraries used with the
2421 linker.  This special feature comes into play when you write a prerequisite
2422 whose name is of the form @samp{-l@var{name}}.  (You can tell something
2423 strange is going on here because the prerequisite is normally the name of a
2424 file, and the @emph{file name} of a library generally looks like
2425 @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
2427 When a prerequisite's name has the form @samp{-l@var{name}}, @code{make}
2428 handles it specially by searching for the file @file{lib@var{name}.so},
2429 and, if it is not found, for the file @file{lib@var{name}.a} in the current
2430 directory, in directories specified by matching @code{vpath}
2431 search paths and the @code{VPATH} search path, and then in the
2432 directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
2433 (normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of
2434 @code{make} behave as if @var{prefix} is defined to be the root of the
2435 DJGPP installation tree).
2437 For example, if there is a @file{/usr/lib/libcurses.a} library on your
2438 system (and no @file{/usr/lib/libcurses.so} file), then
2440 @example
2441 @group
2442 foo : foo.c -lcurses
2443         cc $^ -o $@@
2444 @end group
2445 @end example
2447 @noindent
2448 would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
2449 be executed when @file{foo} is older than @file{foo.c} or than
2450 @file{/usr/lib/libcurses.a}.@refill
2452 Although the default set of files to be searched for is
2453 @file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable
2454 via the @code{.LIBPATTERNS} variable.  Each word in the value of this
2455 variable is a pattern string.  When a prerequisite like
2456 @samp{-l@var{name}} is seen, @code{make} will replace the percent in
2457 each pattern in the list with @var{name} and perform the above directory
2458 searches using each library filename.
2460 The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a},
2461 which provides the default behavior described above.
2463 You can turn off link library expansion completely by setting this
2464 variable to an empty value.
2466 @node Phony Targets, Force Targets, Directory Search, Rules
2467 @section Phony Targets
2468 @cindex phony targets
2469 @cindex targets, phony
2470 @cindex targets without a file
2472 A phony target is one that is not really the name of a file; rather it
2473 is just a name for a recipe to be executed when you make an explicit
2474 request.  There are two reasons to use a phony target: to avoid a
2475 conflict with a file of the same name, and to improve performance.
2477 If you write a rule whose recipe will not create the target file, the
2478 recipe will be executed every time the target comes up for remaking.
2479 Here is an example:
2481 @example
2482 @group
2483 clean:
2484         rm *.o temp
2485 @end group
2486 @end example
2488 @noindent
2489 Because the @code{rm} command does not create a file named @file{clean},
2490 probably no such file will ever exist.  Therefore, the @code{rm} command
2491 will be executed every time you say @samp{make clean}.
2492 @cindex @code{rm} (shell command)
2494 @findex .PHONY
2495 The phony target will cease to work if anything ever does create a file
2496 named @file{clean} in this directory.  Since it has no prerequisites, the
2497 file @file{clean} would inevitably be considered up to date, and its
2498 recipe would not be executed.  To avoid this problem, you can explicitly
2499 declare the target to be phony, using the special target @code{.PHONY}
2500 (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
2502 @example
2503 .PHONY : clean
2504 @end example
2506 @noindent
2507 Once this is done, @samp{make clean} will run the recipe regardless of
2508 whether there is a file named @file{clean}.
2510 Since it knows that phony targets do not name actual files that could be
2511 remade from other files, @code{make} skips the implicit rule search for
2512 phony targets (@pxref{Implicit Rules}).  This is why declaring a target
2513 phony is good for performance, even if you are not worried about the
2514 actual file existing.
2516 Thus, you first write the line that states that @code{clean} is a
2517 phony target, then you write the rule, like this:
2519 @example
2520 @group
2521 .PHONY: clean
2522 clean:
2523         rm *.o temp
2524 @end group
2525 @end example
2527 Another example of the usefulness of phony targets is in conjunction
2528 with recursive invocations of @code{make} (for more information, see
2529 @ref{Recursion, ,Recursive Use of @code{make}}).  In this case the
2530 makefile will often contain a variable which lists a number of
2531 subdirectories to be built.  One way to handle this is with one rule
2532 whose recipe is a shell loop over the subdirectories, like this:
2534 @example
2535 @group
2536 SUBDIRS = foo bar baz
2538 subdirs:
2539         for dir in $(SUBDIRS); do \
2540           $(MAKE) -C $$dir; \
2541         done
2542 @end group
2543 @end example
2545 There are problems with this method, however.  First, any error
2546 detected in a submake is ignored by this rule, so it will continue
2547 to build the rest of the directories even when one fails.  This can be
2548 overcome by adding shell commands to note the error and exit, but then
2549 it will do so even if @code{make} is invoked with the @code{-k}
2550 option, which is unfortunate.  Second, and perhaps more importantly,
2551 you cannot take advantage of @code{make}'s ability to build targets in
2552 parallel (@pxref{Parallel, ,Parallel Execution}), since there is only
2553 one rule.
2555 By declaring the subdirectories as phony targets (you must do this as
2556 the subdirectory obviously always exists; otherwise it won't be built)
2557 you can remove these problems:
2559 @example
2560 @group
2561 SUBDIRS = foo bar baz
2563 .PHONY: subdirs $(SUBDIRS)
2565 subdirs: $(SUBDIRS)
2567 $(SUBDIRS):
2568         $(MAKE) -C $@@
2570 foo: baz
2571 @end group
2572 @end example
2574 Here we've also declared that the @file{foo} subdirectory cannot be
2575 built until after the @file{baz} subdirectory is complete; this kind of
2576 relationship declaration is particularly important when attempting
2577 parallel builds.
2579 A phony target should not be a prerequisite of a real target file; if it
2580 is, its recipe will be run every time @code{make} goes to update that
2581 file.  As long as a phony target is never a prerequisite of a real
2582 target, the phony target recipe will be executed only when the phony
2583 target is a specified goal (@pxref{Goals, ,Arguments to Specify the
2584 Goals}).
2586 Phony targets can have prerequisites.  When one directory contains multiple
2587 programs, it is most convenient to describe all of the programs in one
2588 makefile @file{./Makefile}.  Since the target remade by default will be the
2589 first one in the makefile, it is common to make this a phony target named
2590 @samp{all} and give it, as prerequisites, all the individual programs.  For
2591 example:
2593 @example
2594 all : prog1 prog2 prog3
2595 .PHONY : all
2597 prog1 : prog1.o utils.o
2598         cc -o prog1 prog1.o utils.o
2600 prog2 : prog2.o
2601         cc -o prog2 prog2.o
2603 prog3 : prog3.o sort.o utils.o
2604         cc -o prog3 prog3.o sort.o utils.o
2605 @end example
2607 @noindent
2608 Now you can say just @samp{make} to remake all three programs, or
2609 specify as arguments the ones to remake (as in @samp{make prog1
2610 prog3}).  Phoniness is not inherited: the prerequisites of a phony
2611 target are not themselves phony, unless explicitly declared to be so.
2613 When one phony target is a prerequisite of another, it serves as a subroutine
2614 of the other.  For example, here @samp{make cleanall} will delete the
2615 object files, the difference files, and the file @file{program}:
2617 @example
2618 .PHONY: cleanall cleanobj cleandiff
2620 cleanall : cleanobj cleandiff
2621         rm program
2623 cleanobj :
2624         rm *.o
2626 cleandiff :
2627         rm *.diff
2628 @end example
2630 @node Force Targets, Empty Targets, Phony Targets, Rules
2631 @section Rules without Recipes or Prerequisites
2632 @cindex force targets
2633 @cindex targets, force
2634 @cindex @code{FORCE}
2635 @cindex rule, no recipe or prerequisites
2637 If a rule has no prerequisites or recipe, and the target of the rule
2638 is a nonexistent file, then @code{make} imagines this target to have
2639 been updated whenever its rule is run.  This implies that all targets
2640 depending on this one will always have their recipe run.
2642 An example will illustrate this:
2644 @example
2645 @group
2646 clean: FORCE
2647         rm $(objects)
2648 FORCE:
2649 @end group
2650 @end example
2652 Here the target @samp{FORCE} satisfies the special conditions, so the
2653 target @file{clean} that depends on it is forced to run its recipe.
2654 There is nothing special about the name @samp{FORCE}, but that is one
2655 name commonly used this way.
2657 As you can see, using @samp{FORCE} this way has the same results as using
2658 @samp{.PHONY: clean}.
2660 Using @samp{.PHONY} is more explicit and more efficient.  However,
2661 other versions of @code{make} do not support @samp{.PHONY}; thus
2662 @samp{FORCE} appears in many makefiles.  @xref{Phony Targets}.
2664 @node Empty Targets, Special Targets, Force Targets, Rules
2665 @section Empty Target Files to Record Events
2666 @cindex empty targets
2667 @cindex targets, empty
2668 @cindex recording events with empty targets
2670 The @dfn{empty target} is a variant of the phony target; it is used to hold
2671 recipes for an action that you request explicitly from time to time.
2672 Unlike a phony target, this target file can really exist; but the file's
2673 contents do not matter, and usually are empty.
2675 The purpose of the empty target file is to record, with its
2676 last-modification time, when the rule's recipe was last executed.  It
2677 does so because one of the commands in the recipe is a @code{touch}
2678 command to update the target file.
2680 The empty target file should have some prerequisites (otherwise it
2681 doesn't make sense).  When you ask to remake the empty target, the
2682 recipe is executed if any prerequisite is more recent than the target;
2683 in other words, if a prerequisite has changed since the last time you
2684 remade the target.  Here is an example:
2686 @example
2687 print: foo.c bar.c
2688         lpr -p $?
2689         touch print
2690 @end example
2691 @cindex @code{print} target
2692 @cindex @code{lpr} (shell command)
2693 @cindex @code{touch} (shell command)
2695 @noindent
2696 With this rule, @samp{make print} will execute the @code{lpr} command if
2697 either source file has changed since the last @samp{make print}.  The
2698 automatic variable @samp{$?} is used to print only those files that have
2699 changed (@pxref{Automatic Variables}).
2701 @node Special Targets, Multiple Targets, Empty Targets, Rules
2702 @section Special Built-in Target Names
2703 @cindex special targets
2704 @cindex built-in special targets
2705 @cindex targets, built-in special
2707 Certain names have special meanings if they appear as targets.
2709 @table @code
2710 @findex .PHONY
2711 @item .PHONY
2713 The prerequisites of the special target @code{.PHONY} are considered to
2714 be phony targets.  When it is time to consider such a target,
2715 @code{make} will run its recipe unconditionally, regardless of
2716 whether a file with that name exists or what its last-modification
2717 time is.  @xref{Phony Targets, ,Phony Targets}.
2719 @findex .SUFFIXES
2720 @item .SUFFIXES
2722 The prerequisites of the special target @code{.SUFFIXES} are the list
2723 of suffixes to be used in checking for suffix rules.
2724 @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2726 @findex .DEFAULT
2727 @item .DEFAULT
2729 The recipe specified for @code{.DEFAULT} is used for any target for
2730 which no rules are found (either explicit rules or implicit rules).
2731 @xref{Last Resort}.  If a @code{.DEFAULT} recipe is specified, every
2732 file mentioned as a prerequisite, but not as a target in a rule, will have
2733 that recipe executed on its behalf.  @xref{Implicit Rule Search,
2734 ,Implicit Rule Search Algorithm}.
2736 @findex .PRECIOUS
2737 @item .PRECIOUS
2738 @cindex precious targets
2739 @cindex preserving with @code{.PRECIOUS}
2741 The targets which @code{.PRECIOUS} depends on are given the following
2742 special treatment: if @code{make} is killed or interrupted during the
2743 execution of their recipes, the target is not deleted.
2744 @xref{Interrupts, ,Interrupting or Killing @code{make}}.  Also, if the
2745 target is an intermediate file, it will not be deleted after it is no
2746 longer needed, as is normally done.  @xref{Chained Rules, ,Chains of
2747 Implicit Rules}.  In this latter respect it overlaps with the
2748 @code{.SECONDARY} special target.
2750 You can also list the target pattern of an implicit rule (such as
2751 @samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS}
2752 to preserve intermediate files created by rules whose target patterns
2753 match that file's name.
2755 @findex .INTERMEDIATE
2756 @item .INTERMEDIATE
2757 @cindex intermediate targets, explicit
2759 The targets which @code{.INTERMEDIATE} depends on are treated as
2760 intermediate files.  @xref{Chained Rules, ,Chains of Implicit Rules}.
2761 @code{.INTERMEDIATE} with no prerequisites has no effect.
2763 @findex .SECONDARY
2764 @item .SECONDARY
2765 @cindex secondary targets
2766 @cindex preserving with @code{.SECONDARY}
2768 The targets which @code{.SECONDARY} depends on are treated as
2769 intermediate files, except that they are never automatically deleted.
2770 @xref{Chained Rules, ,Chains of Implicit Rules}.
2772 @code{.SECONDARY} with no prerequisites causes all targets to be treated
2773 as secondary (i.e., no target is removed because it is considered
2774 intermediate).
2779 If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the
2780 makefile, then all prerequisite lists defined @emph{after} it appears
2781 will be expanded a second time after all makefiles have been read in.
2782 @xref{Secondary Expansion, ,Secondary Expansion}.
2784 @findex .DELETE_ON_ERROR
2785 @item .DELETE_ON_ERROR
2786 @cindex removing targets on failure
2788 If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the
2789 makefile, then @code{make} will delete the target of a rule if it has
2790 changed and its recipe exits with a nonzero exit status, just as it
2791 does when it receives a signal.  @xref{Errors, ,Errors in Recipes}.
2793 @findex .IGNORE
2794 @item .IGNORE
2796 If you specify prerequisites for @code{.IGNORE}, then @code{make} will
2797 ignore errors in execution of the recipe for those particular files.
2798 The recipe for @code{.IGNORE} (if any) is ignored.
2800 If mentioned as a target with no prerequisites, @code{.IGNORE} says to
2801 ignore errors in execution of recipes for all files.  This usage of
2802 @samp{.IGNORE} is supported only for historical compatibility.  Since
2803 this affects every recipe in the makefile, it is not very useful; we
2804 recommend you use the more selective ways to ignore errors in specific
2805 recipes.  @xref{Errors, ,Errors in Recipes}.
2810 If you specify prerequisites for @code{.LOW_RESOLUTION_TIME},
2811 @command{make} assumes that these files are created by commands that
2812 generate low resolution time stamps.  The recipe for the
2813 @code{.LOW_RESOLUTION_TIME} target are ignored.
2815 The high resolution file time stamps of many modern file systems
2816 lessen the chance of @command{make} incorrectly concluding that a file
2817 is up to date.  Unfortunately, some hosts do not provide a way to set a
2818 high resolution file time stamp, so commands like @samp{cp -p} that
2819 explicitly set a file's time stamp must discard its subsecond part.
2820 If a file is created by such a command, you should list it as a
2821 prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make}
2822 does not mistakenly conclude that the file is out of date.  For
2823 example:
2825 @example
2826 @group
2828 dst: src
2829         cp -p src dst
2830 @end group
2831 @end example
2833 Since @samp{cp -p} discards the subsecond part of @file{src}'s time
2834 stamp, @file{dst} is typically slightly older than @file{src} even when
2835 it is up to date.  The @code{.LOW_RESOLUTION_TIME} line causes
2836 @command{make} to consider @file{dst} to be up to date if its time stamp
2837 is at the start of the same second that @file{src}'s time stamp is in.
2839 Due to a limitation of the archive format, archive member time stamps
2840 are always low resolution.  You need not list archive members as
2841 prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this
2842 automatically.
2844 @findex .SILENT
2845 @item .SILENT
2847 If you specify prerequisites for @code{.SILENT}, then @code{make} will
2848 not print the recipe used to remake those particular files before
2849 executing them.  The recipe for @code{.SILENT} is ignored.
2851 If mentioned as a target with no prerequisites, @code{.SILENT} says not
2852 to print any recipes before executing them.  This usage of
2853 @samp{.SILENT} is supported only for historical compatibility.  We
2854 recommend you use the more selective ways to silence specific recipes.
2855 @xref{Echoing, ,Recipe Echoing}.  If you want to silence all recipes
2856 for a particular run of @code{make}, use the @samp{-s} or
2857 @w{@samp{--silent}} option (@pxref{Options Summary}).
2862 Simply by being mentioned as a target, this tells @code{make} to
2863 export all variables to child processes by default.
2864 @xref{Variables/Recursion, ,Communicating Variables to a
2865 Sub-@code{make}}.
2867 @findex .NOTPARALLEL
2868 @item .NOTPARALLEL
2869 @cindex parallel execution, overriding
2871 If @code{.NOTPARALLEL} is mentioned as a target, then this invocation
2872 of @code{make} will be run serially, even if the @samp{-j} option is
2873 given.  Any recursively invoked @code{make} command will still run
2874 recipes in parallel (unless its makefile also contains this target).
2875 Any prerequisites on this target are ignored.
2877 @findex .POSIX
2878 @item .POSIX
2879 @cindex POSIX-conforming mode, setting
2881 If @code{.POSIX} is mentioned as a target, then the makefile will be
2882 parsed and run in POSIX-conforming mode.  This does @emph{not} mean
2883 that only POSIX-conforming makefiles will be accepted: all advanced
2884 GNU @code{make} features are still available.  Rather, this target
2885 causes @code{make} to behave as required by POSIX in those areas
2886 where @code{make}'s default behavior differs.
2888 In particular, if this target is mentioned then recipes will be
2889 invoked as if the shell had been passed the @code{-e} flag: the first
2890 failing command in a recipe will cause the recipe to fail immediately.
2891 @end table
2893 Any defined implicit rule suffix also counts as a special target if it
2894 appears as a target, and so does the concatenation of two suffixes, such
2895 as @samp{.c.o}.  These targets are suffix rules, an obsolete way of
2896 defining implicit rules (but a way still widely used).  In principle, any
2897 target name could be special in this way if you break it in two and add
2898 both pieces to the suffix list.  In practice, suffixes normally begin with
2899 @samp{.}, so these special target names also begin with @samp{.}.
2900 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
2902 @node Multiple Targets, Multiple Rules, Special Targets, Rules
2903 @section Multiple Targets in a Rule
2904 @cindex multiple targets
2905 @cindex several targets in a rule
2906 @cindex targets, multiple
2907 @cindex rule, with multiple targets
2909 A rule with multiple targets is equivalent to writing many rules, each with
2910 one target, and all identical aside from that.  The same recipe applies to
2911 all the targets, but its effect may vary because you can substitute the
2912 actual target name into the recipe using @samp{$@@}.  The rule contributes
2913 the same prerequisites to all the targets also.
2915 This is useful in two cases.
2917 @itemize @bullet
2918 @item
2919 You want just prerequisites, no recipe.  For example:
2921 @example
2922 kbd.o command.o files.o: command.h
2923 @end example
2925 @noindent
2926 gives an additional prerequisite to each of the three object files
2927 mentioned.
2929 @item
2930 Similar recipes work for all the targets.  The recipes do not need
2931 to be absolutely identical, since the automatic variable @samp{$@@}
2932 can be used to substitute the particular target to be remade into the
2933 commands (@pxref{Automatic Variables}).  For example:
2935 @example
2936 @group
2937 bigoutput littleoutput : text.g
2938         generate text.g -$(subst output,,$@@) > $@@
2939 @end group
2940 @end example
2941 @findex subst
2943 @noindent
2944 is equivalent to
2946 @example
2947 bigoutput : text.g
2948         generate text.g -big > bigoutput
2949 littleoutput : text.g
2950         generate text.g -little > littleoutput
2951 @end example
2953 @noindent
2954 Here we assume the hypothetical program @code{generate} makes two
2955 types of output, one if given @samp{-big} and one if given
2956 @samp{-little}.
2957 @xref{Text Functions, ,Functions for String Substitution and Analysis},
2958 for an explanation of the @code{subst} function.
2959 @end itemize
2961 Suppose you would like to vary the prerequisites according to the
2962 target, much as the variable @samp{$@@} allows you to vary the recipe.
2963 You cannot do this with multiple targets in an ordinary rule, but you
2964 can do it with a @dfn{static pattern rule}.  @xref{Static Pattern,
2965 ,Static Pattern Rules}.
2967 @node Multiple Rules, Static Pattern, Multiple Targets, Rules
2968 @section Multiple Rules for One Target
2969 @cindex multiple rules for one target
2970 @cindex several rules for one target
2971 @cindex rule, multiple for one target
2972 @cindex target, multiple rules for one
2974 One file can be the target of several rules.  All the prerequisites
2975 mentioned in all the rules are merged into one list of prerequisites for
2976 the target.  If the target is older than any prerequisite from any rule,
2977 the recipe is executed.
2979 There can only be one recipe to be executed for a file.  If more than
2980 one rule gives a recipe for the same file, @code{make} uses the last
2981 one given and prints an error message.  (As a special case, if the
2982 file's name begins with a dot, no error message is printed.  This odd
2983 behavior is only for compatibility with other implementations of
2984 @code{make}@dots{} you should avoid using it).  Occasionally it is
2985 useful to have the same target invoke multiple recipes which are
2986 defined in different parts of your makefile; you can use
2987 @dfn{double-colon rules} (@pxref{Double-Colon}) for this.
2989 An extra rule with just prerequisites can be used to give a few extra
2990 prerequisites to many files at once.  For example, makefiles often
2991 have a variable, such as @code{objects}, containing a list of all the
2992 compiler output files in the system being made.  An easy way to say
2993 that all of them must be recompiled if @file{config.h} changes is to
2994 write the following:
2996 @example
2997 objects = foo.o bar.o
2998 foo.o : defs.h
2999 bar.o : defs.h test.h
3000 $(objects) : config.h
3001 @end example
3003 This could be inserted or taken out without changing the rules that really
3004 specify how to make the object files, making it a convenient form to use if
3005 you wish to add the additional prerequisite intermittently.
3007 Another wrinkle is that the additional prerequisites could be
3008 specified with a variable that you set with a command line argument to
3009 @code{make} (@pxref{Overriding, ,Overriding Variables}).  For example,
3011 @example
3012 @group
3013 extradeps=
3014 $(objects) : $(extradeps)
3015 @end group
3016 @end example
3018 @noindent
3019 means that the command @samp{make extradeps=foo.h} will consider
3020 @file{foo.h} as a prerequisite of each object file, but plain @samp{make}
3021 will not.
3023 If none of the explicit rules for a target has a recipe, then @code{make}
3024 searches for an applicable implicit rule to find one
3025 @pxref{Implicit Rules, ,Using Implicit Rules}).
3027 @node Static Pattern, Double-Colon, Multiple Rules, Rules
3028 @section Static Pattern Rules
3029 @cindex static pattern rule
3030 @cindex rule, static pattern
3031 @cindex pattern rules, static (not implicit)
3032 @cindex varying prerequisites
3033 @cindex prerequisites, varying (static pattern)
3035 @dfn{Static pattern rules} are rules which specify multiple targets and
3036 construct the prerequisite names for each target based on the target name.
3037 They are more general than ordinary rules with multiple targets because the
3038 targets do not have to have identical prerequisites.  Their prerequisites must
3039 be @emph{analogous}, but not necessarily @emph{identical}.
3041 @menu
3042 * Static Usage::                The syntax of static pattern rules.
3043 * Static versus Implicit::      When are they better than implicit rules?
3044 @end menu
3046 @node Static Usage, Static versus Implicit, Static Pattern, Static Pattern
3047 @subsection Syntax of Static Pattern Rules
3048 @cindex static pattern rule, syntax of
3049 @cindex pattern rules, static, syntax of
3051 Here is the syntax of a static pattern rule:
3053 @example
3054 @var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{}
3055         @var{recipe}
3056         @dots{}
3057 @end example
3059 @noindent
3060 The @var{targets} list specifies the targets that the rule applies to.
3061 The targets can contain wildcard characters, just like the targets of
3062 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
3063 Names}).
3065 @cindex target pattern, static (not implicit)
3066 @cindex stem
3067 The @var{target-pattern} and @var{prereq-patterns} say how to compute the
3068 prerequisites of each target.  Each target is matched against the
3069 @var{target-pattern} to extract a part of the target name, called the
3070 @dfn{stem}.  This stem is substituted into each of the @var{prereq-patterns}
3071 to make the prerequisite names (one from each @var{prereq-pattern}).
3073 Each pattern normally contains the character @samp{%} just once.  When the
3074 @var{target-pattern} matches a target, the @samp{%} can match any part of
3075 the target name; this part is called the @dfn{stem}.  The rest of the
3076 pattern must match exactly.  For example, the target @file{foo.o} matches
3077 the pattern @samp{%.o}, with @samp{foo} as the stem.  The targets
3078 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
3080 @cindex prerequisite pattern, static (not implicit)
3081 The prerequisite names for each target are made by substituting the stem
3082 for the @samp{%} in each prerequisite pattern.  For example, if one
3083 prerequisite pattern is @file{%.c}, then substitution of the stem
3084 @samp{foo} gives the prerequisite name @file{foo.c}.  It is legitimate
3085 to write a prerequisite pattern that does not contain @samp{%}; then this
3086 prerequisite is the same for all targets.
3088 @cindex @code{%}, quoting in static pattern
3089 @cindex @code{%}, quoting with @code{\} (backslash)
3090 @cindex @code{\} (backslash), to quote @code{%}
3091 @cindex backslash (@code{\}), to quote @code{%}
3092 @cindex quoting @code{%}, in static pattern
3093 @samp{%} characters in pattern rules can be quoted with preceding
3094 backslashes (@samp{\}).  Backslashes that would otherwise quote @samp{%}
3095 characters can be quoted with more backslashes.  Backslashes that quote
3096 @samp{%} characters or other backslashes are removed from the pattern
3097 before it is compared to file names or has a stem substituted into it.
3098 Backslashes that are not in danger of quoting @samp{%} characters go
3099 unmolested.  For example, the pattern @file{the\%weird\\%pattern\\} has
3100 @samp{the%weird\} preceding the operative @samp{%} character, and
3101 @samp{pattern\\} following it.  The final two backslashes are left alone
3102 because they cannot affect any @samp{%} character.@refill
3104 Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
3105 from the corresponding @file{.c} file:
3107 @example
3108 @group
3109 objects = foo.o bar.o
3111 all: $(objects)
3113 $(objects): %.o: %.c
3114         $(CC) -c $(CFLAGS) $< -o $@@
3115 @end group
3116 @end example
3118 @noindent
3119 Here @samp{$<} is the automatic variable that holds the name of the
3120 prerequisite and @samp{$@@} is the automatic variable that holds the name
3121 of the target; see @ref{Automatic Variables}.
3123 Each target specified must match the target pattern; a warning is issued
3124 for each target that does not.  If you have a list of files, only some of
3125 which will match the pattern, you can use the @code{filter} function to
3126 remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
3128 @example
3129 files = foo.elc bar.o lose.o
3131 $(filter %.o,$(files)): %.o: %.c
3132         $(CC) -c $(CFLAGS) $< -o $@@
3133 $(filter %.elc,$(files)): %.elc: %.el
3134         emacs -f batch-byte-compile $<
3135 @end example
3137 @noindent
3138 In this example the result of @samp{$(filter %.o,$(files))} is
3139 @file{bar.o lose.o}, and the first static pattern rule causes each of
3140 these object files to be updated by compiling the corresponding C source
3141 file.  The result of @w{@samp{$(filter %.elc,$(files))}} is
3142 @file{foo.elc}, so that file is made from @file{foo.el}.@refill
3144 Another example shows how to use @code{$*} in static pattern rules:
3145 @vindex $*@r{, and static pattern}
3147 @example
3148 @group
3149 bigoutput littleoutput : %output : text.g
3150         generate text.g -$* > $@@
3151 @end group
3152 @end example
3154 @noindent
3155 When the @code{generate} command is run, @code{$*} will expand to the
3156 stem, either @samp{big} or @samp{little}.
3158 @node Static versus Implicit,  , Static Usage, Static Pattern
3159 @subsection Static Pattern Rules versus Implicit Rules
3160 @cindex rule, static pattern versus implicit
3161 @cindex static pattern rule, versus implicit
3163 A static pattern rule has much in common with an implicit rule defined as a
3164 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
3165 Both have a pattern for the target and patterns for constructing the
3166 names of prerequisites.  The difference is in how @code{make} decides
3167 @emph{when} the rule applies.
3169 An implicit rule @emph{can} apply to any target that matches its pattern,
3170 but it @emph{does} apply only when the target has no recipe otherwise
3171 specified, and only when the prerequisites can be found.  If more than one
3172 implicit rule appears applicable, only one applies; the choice depends on
3173 the order of rules.
3175 By contrast, a static pattern rule applies to the precise list of targets
3176 that you specify in the rule.  It cannot apply to any other target and it
3177 invariably does apply to each of the targets specified.  If two conflicting
3178 rules apply, and both have recipes, that's an error.
3180 The static pattern rule can be better than an implicit rule for these
3181 reasons:
3183 @itemize @bullet
3184 @item
3185 You may wish to override the usual implicit rule for a few
3186 files whose names cannot be categorized syntactically but
3187 can be given in an explicit list.
3189 @item
3190 If you cannot be sure of the precise contents of the directories
3191 you are using, you may not be sure which other irrelevant files
3192 might lead @code{make} to use the wrong implicit rule.  The choice
3193 might depend on the order in which the implicit rule search is done.
3194 With static pattern rules, there is no uncertainty: each rule applies
3195 to precisely the targets specified.
3196 @end itemize
3198 @node Double-Colon, Automatic Prerequisites, Static Pattern, Rules
3199 @section Double-Colon Rules
3200 @cindex double-colon rules
3201 @cindex rule, double-colon (@code{::})
3202 @cindex multiple rules for one target (@code{::})
3203 @cindex @code{::} rules (double-colon)
3205 @dfn{Double-colon} rules are explicit rules written with @samp{::}
3206 instead of @samp{:} after the target names.  They are handled
3207 differently from ordinary rules when the same target appears in more
3208 than one rule.  Pattern rules with double-colons have an entirely
3209 different meaning (@pxref{Match-Anything Rules}).
3211 When a target appears in multiple rules, all the rules must be the same
3212 type: all ordinary, or all double-colon.  If they are double-colon, each
3213 of them is independent of the others.  Each double-colon rule's recipe
3214 is executed if the target is older than any prerequisites of that rule.
3215 If there are no prerequisites for that rule, its recipe is always
3216 executed (even if the target already exists).  This can result in
3217 executing none, any, or all of the double-colon rules.
3219 Double-colon rules with the same target are in fact completely separate
3220 from one another.  Each double-colon rule is processed individually, just
3221 as rules with different targets are processed.
3223 The double-colon rules for a target are executed in the order they appear
3224 in the makefile.  However, the cases where double-colon rules really make
3225 sense are those where the order of executing the recipes would not matter.
3227 Double-colon rules are somewhat obscure and not often very useful; they
3228 provide a mechanism for cases in which the method used to update a target
3229 differs depending on which prerequisite files caused the update, and such
3230 cases are rare.
3232 Each double-colon rule should specify a recipe; if it does not, an
3233 implicit rule will be used if one applies.
3234 @xref{Implicit Rules, ,Using Implicit Rules}.
3236 @node Automatic Prerequisites,  , Double-Colon, Rules
3237 @section Generating Prerequisites Automatically
3238 @cindex prerequisites, automatic generation
3239 @cindex automatic generation of prerequisites
3240 @cindex generating prerequisites automatically
3242 In the makefile for a program, many of the rules you need to write often
3243 say only that some object file depends on some header
3244 file.  For example, if @file{main.c} uses @file{defs.h} via an
3245 @code{#include}, you would write:
3247 @example
3248 main.o: defs.h
3249 @end example
3251 @noindent
3252 You need this rule so that @code{make} knows that it must remake
3253 @file{main.o} whenever @file{defs.h} changes.  You can see that for a
3254 large program you would have to write dozens of such rules in your
3255 makefile.  And, you must always be very careful to update the makefile
3256 every time you add or remove an @code{#include}.
3257 @cindex @code{#include}
3259 @cindex @code{-M} (to compiler)
3260 To avoid this hassle, most modern C compilers can write these rules for
3261 you, by looking at the @code{#include} lines in the source files.
3262 Usually this is done with the @samp{-M} option to the compiler.
3263 For example, the command:
3265 @example
3266 cc -M main.c
3267 @end example
3269 @noindent
3270 generates the output:
3272 @example
3273 main.o : main.c defs.h
3274 @end example
3276 @noindent
3277 Thus you no longer have to write all those rules yourself.
3278 The compiler will do it for you.
3280 Note that such a prerequisite constitutes mentioning @file{main.o} in a
3281 makefile, so it can never be considered an intermediate file by implicit
3282 rule search.  This means that @code{make} won't ever remove the file
3283 after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}.
3285 @cindex @code{make depend}
3286 With old @code{make} programs, it was traditional practice to use this
3287 compiler feature to generate prerequisites on demand with a command like
3288 @samp{make depend}.  That command would create a file @file{depend}
3289 containing all the automatically-generated prerequisites; then the
3290 makefile could use @code{include} to read them in (@pxref{Include}).
3292 In GNU @code{make}, the feature of remaking makefiles makes this
3293 practice obsolete---you need never tell @code{make} explicitly to
3294 regenerate the prerequisites, because it always regenerates any makefile
3295 that is out of date.  @xref{Remaking Makefiles}.
3297 The practice we recommend for automatic prerequisite generation is to have
3298 one makefile corresponding to each source file.  For each source file
3299 @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
3300 what files the object file @file{@var{name}.o} depends on.  That way
3301 only the source files that have changed need to be rescanned to produce
3302 the new prerequisites.
3304 Here is the pattern rule to generate a file of prerequisites (i.e., a makefile)
3305 called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
3307 @smallexample
3308 @group
3309 %.d: %.c
3310         @@set -e; rm -f $@@; \
3311          $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \
3312          sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \
3313          rm -f $@@.$$$$
3314 @end group
3315 @end smallexample
3317 @noindent
3318 @xref{Pattern Rules}, for information on defining pattern rules.  The
3319 @samp{-e} flag to the shell causes it to exit immediately if the
3320 @code{$(CC)} command (or any other command) fails (exits with a
3321 nonzero status).
3322 @cindex @code{-e} (shell flag)
3324 @cindex @code{-MM} (to GNU compiler)
3325 With the GNU C compiler, you may wish to use the @samp{-MM} flag instead
3326 of @samp{-M}.  This omits prerequisites on system header files.
3327 @xref{Preprocessor Options, , Options Controlling the Preprocessor,
3328 gcc.info, Using GNU CC}, for details.
3330 @cindex @code{sed} (shell command)
3331 The purpose of the @code{sed} command is to translate (for example):
3333 @example
3334 main.o : main.c defs.h
3335 @end example
3337 @noindent
3338 into:
3340 @example
3341 main.o main.d : main.c defs.h
3342 @end example
3344 @noindent
3345 @cindex @code{.d}
3346 This makes each @samp{.d} file depend on all the source and header files
3347 that the corresponding @samp{.o} file depends on.  @code{make} then
3348 knows it must regenerate the prerequisites whenever any of the source or
3349 header files changes.
3351 Once you've defined the rule to remake the @samp{.d} files,
3352 you then use the @code{include} directive to read them all in.
3353 @xref{Include}.  For example:
3355 @example
3356 @group
3357 sources = foo.c bar.c
3359 include $(sources:.c=.d)
3360 @end group
3361 @end example
3363 @noindent
3364 (This example uses a substitution variable reference to translate the
3365 list of source files @samp{foo.c bar.c} into a list of prerequisite
3366 makefiles, @samp{foo.d bar.d}.  @xref{Substitution Refs}, for full
3367 information on substitution references.)  Since the @samp{.d} files are
3368 makefiles like any others, @code{make} will remake them as necessary
3369 with no further work from you.  @xref{Remaking Makefiles}.
3371 Note that the @samp{.d} files contain target definitions; you should
3372 be sure to place the @code{include} directive @emph{after} the first,
3373 default goal in your makefiles or run the risk of having a random
3374 object file become the default goal.
3375 @xref{How Make Works}.
3377 @node Recipes, Using Variables, Rules, Top
3378 @chapter Writing Recipes in Rules
3379 @cindex recipes
3380 @cindex recipes, how to write
3381 @cindex writing recipes
3383 The recipe of a rule consists of one or more shell command lines to
3384 be executed, one at a time, in the order they appear.  Typically, the
3385 result of executing these commands is that the target of the rule is
3386 brought up to date.
3388 Users use many different shell programs, but recipes in makefiles are
3389 always interpreted by @file{/bin/sh} unless the makefile specifies
3390 otherwise.  @xref{Execution, ,Command Execution}.
3392 @menu
3393 * Recipe Syntax::               Recipe syntax features and pitfalls.
3394 * Echoing::                     How to control when recipes are echoed.
3395 * Execution::                   How recipes are executed.
3396 * Parallel::                    How recipes can be executed in parallel.
3397 * Errors::                      What happens after a recipe execution error.
3398 * Interrupts::                  What happens when a recipe is interrupted.
3399 * Recursion::                   Invoking @code{make} from makefiles.
3400 * Canned Recipes::              Defining canned recipes.
3401 * Empty Recipes::               Defining useful, do-nothing recipes.
3402 @end menu
3404 @node Recipe Syntax, Echoing, Recipes, Recipes
3405 @section Recipe Syntax
3406 @cindex recipe syntax
3407 @cindex syntax of recipe
3409 Makefiles have the unusual property that there are really two distinct
3410 syntaxes in one file.  Most of the makefile uses @code{make} syntax
3411 (@pxref{Makefiles, ,Writing Makefiles}).  However, recipes are meant
3412 to be interpreted by the shell and so they are written using shell
3413 syntax.  The @code{make} program does not try to understand shell
3414 syntax: it performs only a very few specific translations on the
3415 content of the recipe before handing it to the shell.
3417 Each line in the recipe must start with a tab (or the first character
3418 in the value of the @code{.CMDPREFIX} variable; @pxref{Special
3419 Variables}), except that the first recipe line may be attached to the
3420 target-and-prerequisites line with a semicolon in between.  @emph{Any}
3421 line in the makefile that begins with a tab and appears in a ``rule
3422 context'' (that is, after a rule has been started until another rule
3423 or variable definition) will be considered part of a recipe for that
3424 rule.  Blank lines and lines of just comments may appear among the
3425 recipe lines; they are ignored.
3427 Some consequences of these rules include:
3429 @itemize @bullet
3430 @item
3431 A blank line that begins with a tab is not blank: it's an empty
3432 recipe (@pxref{Empty Recipes}).
3434 @cindex comments, in recipes
3435 @cindex recipes, comments in
3436 @cindex @code{#} (comments), in recipes
3437 @item
3438 A comment in a recipe is not a @code{make} comment; it will be
3439 passed to the shell as-is.  Whether the shell treats it as a comment
3440 or not depends on your shell.
3442 @item
3443 A variable definition in a ``rule context'' which is indented by a tab
3444 as the first character on the line, will be considered part of a
3445 recipe, not a @code{make} variable definition, and passed to the
3446 shell.
3448 @item
3449 A conditional expression (@code{ifdef}, @code{ifeq},
3450 etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule
3451 context'' which is indented by a tab as the first character on the
3452 line, will be considered part of a recipe and be passed to the shell.
3454 @end itemize
3456 @menu
3457 * Splitting Lines::             Breaking long recipe lines for readability.
3458 * Variables in Recipes::        Using @code{make} variables in recipes.
3459 @end menu
3461 @node Splitting Lines, Variables in Recipes, Recipe Syntax, Recipe Syntax
3462 @subsection Splitting Recipe Lines
3463 @cindex recipes, splitting
3464 @cindex splitting recipes
3465 @cindex recipes, backslash (@code{\}) in
3466 @cindex recipes, quoting newlines in
3467 @cindex backslash (@code{\}), in recipes
3468 @cindex @code{\} (backslash), in recipes
3469 @cindex quoting newline, in recipes
3470 @cindex newline, quoting, in recipes
3472 One of the few ways in which @code{make} does interpret recipes is
3473 checking for a backslash just before the newline.  As in normal
3474 makefile syntax, a single logical recipe line can be split into
3475 multiple physical lines in the makefile by placing a backslash before
3476 each newline.  A sequence of lines like this is considered a single
3477 recipe line, and one instance of the shell will be invoked to run it.
3479 However, in contrast to how they are treated in other places in a
3480 makefile, backslash-newline pairs are @emph{not} removed from the
3481 recipe.  Both the backslash and the newline characters are preserved
3482 and passed to the shell.  How the backslash-newline is interpreted
3483 depends on your shell.  If the first character of the next line after
3484 the backslash-newline is the recipe prefix character (a tab by
3485 default; @pxref{Special Variables}), then that character (and only
3486 that character) is removed.  Whitespace is never added to the recipe.
3488 For example, the recipe for the all target in this makefile:
3490 @example
3491 @group
3492 all :
3493         @@echo no\
3494 space
3495         @@echo no\
3496         space
3497         @@echo one \
3498         space
3499         @@echo one\
3500          space
3501 @end group
3502 @end example
3504 @noindent
3505 consists of four separate shell commands where the output is:
3507 @example
3508 @group
3509 nospace
3510 nospace
3511 one space
3512 one space
3513 @end group
3514 @end example
3516 As a more complex example, this makefile:
3518 @example
3519 @group
3520 all : ; @@echo 'hello \
3521         world' ; echo "hello \
3522     world"
3523 @end group
3524 @end example
3526 @noindent
3527 will invoke one shell with a command of:
3529 @example
3530 @group
3531 echo 'hello \
3532 world' ; echo "hello \
3533     world"
3534 @end group
3535 @end example
3537 @noindent
3538 which, according to shell quoting rules, will yield the following output:
3540 @example
3541 @group
3542 hello \
3543 world
3544 hello     world
3545 @end group
3546 @end example
3548 @noindent
3549 Notice how the backslash/newline pair was removed inside the string
3550 quoted with double quotes (@code{"@dots{}"}), but not from the string
3551 quoted with single quotes (@code{'@dots{}'}).  This is the way the
3552 default shell (@file{/bin/sh}) handles backslash/newline pairs.  If
3553 you specify a different shell in your makefiles it may treat them
3554 differently.
3556 Sometimes you want to split a long line inside of single quotes, but
3557 you don't want the backslash-newline to appear in the quoted content.
3558 This is often the case when passing scripts to languages such as Perl,
3559 where extraneous backslashes inside the script can change its meaning
3560 or even be a syntax error.  One simple way of handling this is to
3561 place the quoted string, or even the entire command, into a
3562 @code{make} variable then use the variable in the recipe.  In this
3563 situation the newline quoting rules for makefiles will be used, and
3564 the backslash-newline will be removed.  If we rewrite our example
3565 above using this method:
3567 @example
3568 @group
3569 HELLO = 'hello \
3570 world'
3572 all : ; @@echo $(HELLO)
3573 @end group
3574 @end example
3576 @noindent
3577 we will get output like this:
3579 @example
3580 @group
3581 hello world
3582 @end group
3583 @end example
3585 If you like, you can also use target-specific variables
3586 (@pxref{Target-specific, ,Target-specific Variable Values}) to obtain
3587 a tighter correspondence between the variable and the recipe that
3588 uses it.
3590 @node Variables in Recipes,  , Splitting Lines, Recipe Syntax
3591 @subsection Using Variables in Recipes
3592 @cindex variable references in recipes
3593 @cindex recipes, using variables in
3595 The other way in which @code{make} processes recipes is by expanding
3596 any variable references in them (@pxref{Reference,Basics of Variable
3597 References}).  This occurs after make has finished reading all the
3598 makefiles and the target is determined to be out of date; so, the
3599 recipes for targets which are not rebuilt are never expanded.
3601 Variable and function references in recipes have identical syntax and
3602 semantics to references elsewhere in the makefile.  They also have the
3603 same quoting rules: if you want a dollar sign to appear in your
3604 recipe, you must double it (@samp{$$}).  For shells like the default
3605 shell, that use dollar signs to introduce variables, it's important to
3606 keep clear in your mind whether the variable you want to reference is
3607 a @code{make} variable (use a single dollar sign) or a shell variable
3608 (use two dollar signs).  For example:
3610 @example
3611 @group
3612 LIST = one two three
3613 all:
3614         for i in $(LIST); do \
3615             echo $$i; \
3616         done
3617 @end group
3618 @end example
3620 @noindent
3621 results in the following command being passed to the shell:
3623 @example
3624 @group
3625 for i in one two three; do \
3626     echo $i; \
3627 done
3628 @end group
3629 @end example
3631 @noindent
3632 which generates the expected result:
3634 @example
3635 @group
3638 three
3639 @end group
3640 @end example
3642 @node Echoing, Execution, Recipe Syntax, Recipes
3643 @section Recipe Echoing
3644 @cindex echoing of recipes
3645 @cindex silent operation
3646 @cindex @code{@@} (in recipes)
3647 @cindex recipes, echoing
3648 @cindex printing of recipes
3650 Normally @code{make} prints each line of the recipe before it is
3651 executed.  We call this @dfn{echoing} because it gives the appearance
3652 that you are typing the lines yourself.
3654 When a line starts with @samp{@@}, the echoing of that line is suppressed.
3655 The @samp{@@} is discarded before the line is passed to the shell.
3656 Typically you would use this for a command whose only effect is to print
3657 something, such as an @code{echo} command to indicate progress through
3658 the makefile:
3660 @example
3661 @@echo About to make distribution files
3662 @end example
3664 @cindex @code{-n}
3665 @cindex @code{--just-print}
3666 @cindex @code{--dry-run}
3667 @cindex @code{--recon}
3668 When @code{make} is given the flag @samp{-n} or @samp{--just-print} it
3669 only echoes most recipes, without executing them.  @xref{Options
3670 Summary, ,Summary of Options}.  In this case even the recipe lines
3671 starting with @samp{@@} are printed.  This flag is useful for finding
3672 out which recipes @code{make} thinks are necessary without actually
3673 doing them.
3675 @cindex @code{-s}
3676 @cindex @code{--silent}
3677 @cindex @code{--quiet}
3678 @findex .SILENT
3679 The @samp{-s} or @samp{--silent}
3680 flag to @code{make} prevents all echoing, as if all recipes
3681 started with @samp{@@}.  A rule in the makefile for the special target
3682 @code{.SILENT} without prerequisites has the same effect
3683 (@pxref{Special Targets, ,Special Built-in Target Names}).
3684 @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
3686 @node Execution, Parallel, Echoing, Recipes
3687 @section Recipe Execution
3688 @cindex recipe, execution
3689 @cindex execution, of recipes
3690 @vindex @code{SHELL} @r{(recipe execution)}
3692 When it is time to execute recipes to update a target, they are
3693 executed by invoking a new subshell for each line of the recipe.  (In
3694 practice, @code{make} may take shortcuts that do not affect the
3695 results.)
3697 @cindex @code{cd} (shell command)
3698 @cindex shell variables, setting in recipes
3699 @cindex recipes setting shell variables
3700 @strong{Please note:} this implies that setting shell variables and
3701 invoking shell commands such as @code{cd} that set a context local to
3702 each process will not affect the following lines in the recipe.@footnote{On
3703 MS-DOS, the value of current working directory is @strong{global}, so
3704 changing it @emph{will} affect the following recipe lines on those
3705 systems.}  If you want to use @code{cd} to affect the next statement,
3706 put both statements in a single recipe line.  Then @code{make} will
3707 invoke one shell to run the entire line, and the shell will execute
3708 the statements in sequence.  For example:
3710 @example
3711 foo : bar/lose
3712         cd $(@@D) && gobble $(@@F) > ../$@@
3713 @end example
3715 @noindent
3716 Here we use the shell AND operator (@code{&&}) so that if the
3717 @code{cd} command fails, the script will fail without trying to invoke
3718 the @code{gobble} command in the wrong directory, which could cause
3719 problems (in this case it would certainly cause @file{../foo} to be
3720 truncated, at least).
3722 @menu
3723 * Choosing the Shell::          How @code{make} chooses the shell used
3724                                   to run recipes.
3725 @end menu
3727 @node Choosing the Shell,  , Execution, Execution
3728 @subsection Choosing the Shell
3729 @cindex shell, choosing the
3730 @cindex @code{SHELL}, value of
3731 @cindex @code{.SHELLFLAGS}, value of
3733 @vindex SHELL
3734 @vindex .SHELLFLAGS
3735 The program used as the shell is taken from the variable @code{SHELL}.
3736 If this variable is not set in your makefile, the program
3737 @file{/bin/sh} is used as the shell.  The argument(s) passed to the
3738 shell are taken from the variable @code{.SHELLFLAGS}.  The default
3739 value of @code{.SHELLFLAGS} is @code{-c} normally, or @code{-ec} in
3740 POSIX-conforming mode.
3742 @cindex environment, @code{SHELL} in
3743 Unlike most variables, the variable @code{SHELL} is never set from the
3744 environment.  This is because the @code{SHELL} environment variable is
3745 used to specify your personal choice of shell program for interactive
3746 use.  It would be very bad for personal choices like this to affect the
3747 functioning of makefiles.  @xref{Environment, ,Variables from the
3748 Environment}.
3750 Furthermore, when you do set @code{SHELL} in your makefile that value
3751 is @emph{not} exported in the environment to recipe lines that
3752 @code{make} invokes.  Instead, the value inherited from the user's
3753 environment, if any, is exported.  You can override this behavior by
3754 explicitly exporting @code{SHELL} (@pxref{Variables/Recursion,
3755 ,Communicating Variables to a Sub-@code{make}}), forcing it to be
3756 passed in the environment to recipe lines.
3758 @vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})}
3759 However, on MS-DOS and MS-Windows the value of @code{SHELL} in the
3760 environment @strong{is} used, since on those systems most users do not
3761 set this variable, and therefore it is most likely set specifically to
3762 be used by @code{make}.  On MS-DOS, if the setting of @code{SHELL} is
3763 not suitable for @code{make}, you can set the variable
3764 @code{MAKESHELL} to the shell that @code{make} should use; if set it
3765 will be used as the shell instead of the value of @code{SHELL}.
3767 @subsubheading Choosing a Shell in DOS and Windows
3768 @cindex shell, in DOS and Windows
3769 @cindex DOS, choosing a shell in
3770 @cindex Windows, choosing a shell in
3772 Choosing a shell in MS-DOS and MS-Windows is much more complex than on
3773 other systems.
3775 @vindex COMSPEC
3776 On MS-DOS, if @code{SHELL} is not set, the value of the variable
3777 @code{COMSPEC} (which is always set) is used instead.
3779 @cindex @code{SHELL}, MS-DOS specifics
3780 The processing of lines that set the variable @code{SHELL} in Makefiles
3781 is different on MS-DOS.  The stock shell, @file{command.com}, is
3782 ridiculously limited in its functionality and many users of @code{make}
3783 tend to install a replacement shell.  Therefore, on MS-DOS, @code{make}
3784 examines the value of @code{SHELL}, and changes its behavior based on
3785 whether it points to a Unix-style or DOS-style shell.  This allows
3786 reasonable functionality even if @code{SHELL} points to
3787 @file{command.com}.
3789 If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS
3790 additionally checks whether that shell can indeed be found; if not, it
3791 ignores the line that sets @code{SHELL}.  In MS-DOS, GNU @code{make}
3792 searches for the shell in the following places:
3794 @enumerate
3795 @item
3796 In the precise place pointed to by the value of @code{SHELL}.  For
3797 example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make}
3798 will look in the directory @file{/bin} on the current drive.
3800 @item
3801 In the current directory.
3803 @item
3804 In each of the directories in the @code{PATH} variable, in order.
3806 @end enumerate
3808 In every directory it examines, @code{make} will first look for the
3809 specific file (@file{sh} in the example above).  If this is not found,
3810 it will also look in that directory for that file with one of the known
3811 extensions which identify executable files.  For example @file{.exe},
3812 @file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others.
3814 If any of these attempts is successful, the value of @code{SHELL} will
3815 be set to the full pathname of the shell as found.  However, if none of
3816 these is found, the value of @code{SHELL} will not be changed, and thus
3817 the line that sets it will be effectively ignored.  This is so
3818 @code{make} will only support features specific to a Unix-style shell if
3819 such a shell is actually installed on the system where @code{make} runs.
3821 Note that this extended search for the shell is limited to the cases
3822 where @code{SHELL} is set from the Makefile; if it is set in the
3823 environment or command line, you are expected to set it to the full
3824 pathname of the shell, exactly as things are on Unix.
3826 The effect of the above DOS-specific processing is that a Makefile that
3827 contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
3828 on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some
3829 directory along your @code{PATH}.
3831 @node Parallel, Errors, Execution, Recipes
3832 @section Parallel Execution
3833 @cindex recipes, execution in parallel
3834 @cindex parallel execution
3835 @cindex execution, in parallel
3836 @cindex job slots
3837 @cindex @code{-j}
3838 @cindex @code{--jobs}
3840 GNU @code{make} knows how to execute several recipes at once.
3841 Normally, @code{make} will execute only one recipe at a time, waiting
3842 for it to finish before executing the next.  However, the @samp{-j} or
3843 @samp{--jobs} option tells @code{make} to execute many recipes
3844 simultaneously.  You can inhibit parallelism in a particular makefile
3845 with the @code{.NOTPARALLEL} pseudo-target (@pxref{Special
3846 Targets,Special Built-in Target Names}).@refill
3848 On MS-DOS, the @samp{-j} option has no effect, since that system doesn't
3849 support multi-processing.
3851 If the @samp{-j} option is followed by an integer, this is the number of
3852 recipes to execute at once; this is called the number of @dfn{job slots}.
3853 If there is nothing looking like an integer after the @samp{-j} option,
3854 there is no limit on the number of job slots.  The default number of job
3855 slots is one, which means serial execution (one thing at a time).
3857 One unpleasant consequence of running several recipes simultaneously is
3858 that output generated by the recipes appears whenever each recipe
3859 sends it, so messages from different recipes may be interspersed.
3861 Another problem is that two processes cannot both take input from the
3862 same device; so to make sure that only one recipe tries to take input
3863 from the terminal at once, @code{make} will invalidate the standard
3864 input streams of all but one running recipe.  This means that
3865 attempting to read from standard input will usually be a fatal error (a
3866 @samp{Broken pipe} signal) for most child processes if there are
3867 several.
3868 @cindex broken pipe
3869 @cindex standard input
3871 It is unpredictable which recipe will have a valid standard input stream
3872 (which will come from the terminal, or wherever you redirect the standard
3873 input of @code{make}).  The first recipe run will always get it first, and
3874 the first recipe started after that one finishes will get it next, and so
3877 We will change how this aspect of @code{make} works if we find a better
3878 alternative.  In the mean time, you should not rely on any recipe using
3879 standard input at all if you are using the parallel execution feature; but
3880 if you are not using this feature, then standard input works normally in
3881 all recipes.
3883 Finally, handling recursive @code{make} invocations raises issues.  For
3884 more information on this, see
3885 @ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
3887 If a recipe fails (is killed by a signal or exits with a nonzero
3888 status), and errors are not ignored for that recipe
3889 (@pxref{Errors, ,Errors in Recipes}),
3890 the remaining recipe lines to remake the same target will not be run.
3891 If a recipe fails and the @samp{-k} or @samp{--keep-going}
3892 option was not given
3893 (@pxref{Options Summary, ,Summary of Options}),
3894 @code{make} aborts execution.  If make
3895 terminates for any reason (including a signal) with child processes
3896 running, it waits for them to finish before actually exiting.@refill
3898 @cindex load average
3899 @cindex limiting jobs based on load
3900 @cindex jobs, limiting based on load
3901 @cindex @code{-l} (load average)
3902 @cindex @code{--max-load}
3903 @cindex @code{--load-average}
3904 When the system is heavily loaded, you will probably want to run fewer jobs
3905 than when it is lightly loaded.  You can use the @samp{-l} option to tell
3906 @code{make} to limit the number of jobs to run at once, based on the load
3907 average.  The @samp{-l} or @samp{--max-load}
3908 option is followed by a floating-point number.  For
3909 example,
3911 @example
3912 -l 2.5
3913 @end example
3915 @noindent
3916 will not let @code{make} start more than one job if the load average is
3917 above 2.5.  The @samp{-l} option with no following number removes the
3918 load limit, if one was given with a previous @samp{-l} option.@refill
3920 More precisely, when @code{make} goes to start up a job, and it already has
3921 at least one job running, it checks the current load average; if it is not
3922 lower than the limit given with @samp{-l}, @code{make} waits until the load
3923 average goes below that limit, or until all the other jobs finish.
3925 By default, there is no load limit.
3927 @node Errors, Interrupts, Parallel, Recipes
3928 @section Errors in Recipes
3929 @cindex errors (in recipes)
3930 @cindex recipes, errors in
3931 @cindex exit status (errors)
3933 After each shell invocation returns, @code{make} looks at its exit
3934 status.  If the shell completed successfully (the exit status is
3935 zero), the next line in the recipe is executed in a new shell; after
3936 the last line is finished, the rule is finished.
3938 If there is an error (the exit status is nonzero), @code{make} gives up on
3939 the current rule, and perhaps on all rules.
3941 Sometimes the failure of a certain recipe line does not indicate a problem.
3942 For example, you may use the @code{mkdir} command to ensure that a
3943 directory exists.  If the directory already exists, @code{mkdir} will
3944 report an error, but you probably want @code{make} to continue regardless.
3946 @cindex @code{-} (in recipes)
3947 To ignore errors in a recipe line, write a @samp{-} at the beginning
3948 of the line's text (after the initial tab).  The @samp{-} is discarded
3949 before the line is passed to the shell for execution.
3951 For example,
3953 @example
3954 @group
3955 clean:
3956         -rm -f *.o
3957 @end group
3958 @end example
3959 @cindex @code{rm} (shell command)
3961 @noindent
3962 This causes @code{make} to continue even if @code{rm} is unable to
3963 remove a file.
3965 @cindex @code{-i}
3966 @cindex @code{--ignore-errors}
3967 @findex .IGNORE
3968 When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
3969 flag, errors are ignored in all recipes of all rules.  A rule in the
3970 makefile for the special target @code{.IGNORE} has the same effect, if
3971 there are no prerequisites.  These ways of ignoring errors are obsolete
3972 because @samp{-} is more flexible.
3974 When errors are to be ignored, because of either a @samp{-} or the
3975 @samp{-i} flag, @code{make} treats an error return just like success,
3976 except that it prints out a message that tells you the status code
3977 the shell exited with, and says that the error has been ignored.
3979 When an error happens that @code{make} has not been told to ignore,
3980 it implies that the current target cannot be correctly remade, and neither
3981 can any other that depends on it either directly or indirectly.  No further
3982 recipes will be executed for these targets, since their preconditions
3983 have not been achieved.
3986 @cindex @code{-k}
3987 @cindex @code{--keep-going}
3988 Normally @code{make} gives up immediately in this circumstance, returning a
3989 nonzero status.  However, if the @samp{-k} or @samp{--keep-going}
3990 flag is specified, @code{make}
3991 continues to consider the other prerequisites of the pending targets,
3992 remaking them if necessary, before it gives up and returns nonzero status.
3993 For example, after an error in compiling one object file, @samp{make -k}
3994 will continue compiling other object files even though it already knows
3995 that linking them will be impossible.  @xref{Options Summary, ,Summary of Options}.
3997 The usual behavior assumes that your purpose is to get the specified
3998 targets up to date; once @code{make} learns that this is impossible, it
3999 might as well report the failure immediately.  The @samp{-k} option says
4000 that the real purpose is to test as many of the changes made in the
4001 program as possible, perhaps to find several independent problems so
4002 that you can correct them all before the next attempt to compile.  This
4003 is why Emacs' @code{compile} command passes the @samp{-k} flag by
4004 default.
4005 @cindex Emacs (@code{M-x compile})
4007 @findex .DELETE_ON_ERROR
4008 @cindex deletion of target files
4009 @cindex removal of target files
4010 @cindex target, deleting on error
4011 Usually when a recipe line fails, if it has changed the target file at all,
4012 the file is corrupted and cannot be used---or at least it is not
4013 completely updated.  Yet the file's time stamp says that it is now up to
4014 date, so the next time @code{make} runs, it will not try to update that
4015 file.  The situation is just the same as when the shell is killed by a
4016 signal; @pxref{Interrupts}.  So generally the right thing to do is to
4017 delete the target file if the recipe fails after beginning to change
4018 the file.  @code{make} will do this if @code{.DELETE_ON_ERROR} appears
4019 as a target.  This is almost always what you want @code{make} to do, but
4020 it is not historical practice; so for compatibility, you must explicitly
4021 request it.
4023 @node Interrupts, Recursion, Errors, Recipes
4024 @section Interrupting or Killing @code{make}
4025 @cindex interrupt
4026 @cindex signal
4027 @cindex deletion of target files
4028 @cindex removal of target files
4029 @cindex target, deleting on interrupt
4030 @cindex killing (interruption)
4032 If @code{make} gets a fatal signal while a shell is executing, it may
4033 delete the target file that the recipe was supposed to update.  This is
4034 done if the target file's last-modification time has changed since
4035 @code{make} first checked it.
4037 The purpose of deleting the target is to make sure that it is remade from
4038 scratch when @code{make} is next run.  Why is this?  Suppose you type
4039 @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
4040 object file @file{foo.o}.  The @kbd{Ctrl-c} kills the compiler, resulting
4041 in an incomplete file whose last-modification time is newer than the source
4042 file @file{foo.c}.  But @code{make} also receives the @kbd{Ctrl-c} signal
4043 and deletes this incomplete file.  If @code{make} did not do this, the next
4044 invocation of @code{make} would think that @file{foo.o} did not require
4045 updating---resulting in a strange error message from the linker when it
4046 tries to link an object file half of which is missing.
4048 @findex .PRECIOUS
4049 You can prevent the deletion of a target file in this way by making the
4050 special target @code{.PRECIOUS} depend on it.  Before remaking a target,
4051 @code{make} checks to see whether it appears on the prerequisites of
4052 @code{.PRECIOUS}, and thereby decides whether the target should be deleted
4053 if a signal happens.  Some reasons why you might do this are that the
4054 target is updated in some atomic fashion, or exists only to record a
4055 modification-time (its contents do not matter), or must exist at all
4056 times to prevent other sorts of trouble.
4058 @node Recursion, Canned Recipes, Interrupts, Recipes
4059 @section Recursive Use of @code{make}
4060 @cindex recursion
4061 @cindex subdirectories, recursion for
4063 Recursive use of @code{make} means using @code{make} as a command in a
4064 makefile.  This technique is useful when you want separate makefiles for
4065 various subsystems that compose a larger system.  For example, suppose you
4066 have a subdirectory @file{subdir} which has its own makefile, and you would
4067 like the containing directory's makefile to run @code{make} on the
4068 subdirectory.  You can do it by writing this:
4070 @example
4071 subsystem:
4072         cd subdir && $(MAKE)
4073 @end example
4075 @noindent
4076 or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
4078 @example
4079 subsystem:
4080         $(MAKE) -C subdir
4081 @end example
4082 @cindex @code{-C}
4083 @cindex @code{--directory}
4085 You can write recursive @code{make} commands just by copying this example,
4086 but there are many things to know about how they work and why, and about
4087 how the sub-@code{make} relates to the top-level @code{make}.  You may
4088 also find it useful to declare targets that invoke recursive
4089 @code{make} commands as @samp{.PHONY} (for more discussion on when
4090 this is useful, see @ref{Phony Targets}).
4092 @vindex @code{CURDIR}
4093 For your convenience, when GNU @code{make} starts (after it has
4094 processed any @code{-C} options) it sets the variable @code{CURDIR} to
4095 the pathname of the current working directory.  This value is never
4096 touched by @code{make} again: in particular note that if you include
4097 files from other directories the value of @code{CURDIR} does not
4098 change.  The value has the same precedence it would have if it were
4099 set in the makefile (by default, an environment variable @code{CURDIR}
4100 will not override this value).  Note that setting this variable has no
4101 impact on the operation of @code{make} (it does not cause @code{make}
4102 to change its working directory, for example).
4104 @menu
4105 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
4106 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
4107 * Options/Recursion::           How to communicate options to a sub-@code{make}.
4108 * -w Option::                   How the @samp{-w} or @samp{--print-directory} option
4109                                   helps debug use of recursive @code{make} commands.
4110 @end menu
4112 @node MAKE Variable, Variables/Recursion, Recursion, Recursion
4113 @subsection How the @code{MAKE} Variable Works
4114 @vindex MAKE
4115 @cindex recursion, and @code{MAKE} variable
4117 Recursive @code{make} commands should always use the variable @code{MAKE},
4118 not the explicit command name @samp{make}, as shown here:
4120 @example
4121 @group
4122 subsystem:
4123         cd subdir && $(MAKE)
4124 @end group
4125 @end example
4127 The value of this variable is the file name with which @code{make} was
4128 invoked.  If this file name was @file{/bin/make}, then the recipe executed
4129 is @samp{cd subdir && /bin/make}.  If you use a special version of
4130 @code{make} to run the top-level makefile, the same special version will be
4131 executed for recursive invocations.
4132 @cindex @code{cd} (shell command)
4134 @cindex +, and recipes
4135 As a special feature, using the variable @code{MAKE} in the recipe of
4136 a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
4137 (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
4138 Using the @code{MAKE} variable has the same effect as using a @samp{+}
4139 character at the beginning of the recipe line.  @xref{Instead of
4140 Execution, ,Instead of Executing the Recipes}.  This special feature
4141 is only enabled if the @code{MAKE} variable appears directly in the
4142 recipe: it does not apply if the @code{MAKE} variable is referenced
4143 through expansion of another variable.  In the latter case you must
4144 use the @samp{+} token to get these special effects.@refill
4146 Consider the command @samp{make -t} in the above example.  (The
4147 @samp{-t} option marks targets as up to date without actually running
4148 any recipes; see @ref{Instead of Execution}.)  Following the usual
4149 definition of @samp{-t}, a @samp{make -t} command in the example would
4150 create a file named @file{subsystem} and do nothing else.  What you
4151 really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but
4152 that would require executing the recipe, and @samp{-t} says not to
4153 execute recipes.@refill
4154 @cindex @code{-t}, and recursion
4155 @cindex recursion, and @code{-t}
4156 @cindex @code{--touch}, and recursion
4158 The special feature makes this do what you want: whenever a recipe
4159 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
4160 @samp{-n} and @samp{-q} do not apply to that line.  Recipe lines
4161 containing @code{MAKE} are executed normally despite the presence of a
4162 flag that causes most recipes not to be run.  The usual
4163 @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
4164 (@pxref{Options/Recursion, ,Communicating Options to a
4165 Sub-@code{make}}), so your request to touch the files, or print the
4166 recipes, is propagated to the subsystem.@refill
4168 @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
4169 @subsection Communicating Variables to a Sub-@code{make}
4170 @cindex sub-@code{make}
4171 @cindex environment, and recursion
4172 @cindex exporting variables
4173 @cindex variables, environment
4174 @cindex variables, exporting
4175 @cindex recursion, and environment
4176 @cindex recursion, and variables
4178 Variable values of the top-level @code{make} can be passed to the
4179 sub-@code{make} through the environment by explicit request.  These
4180 variables are defined in the sub-@code{make} as defaults, but do not
4181 override what is specified in the makefile used by the sub-@code{make}
4182 makefile unless you use the @samp{-e} switch (@pxref{Options Summary,
4183 ,Summary of Options}).@refill
4185 To pass down, or @dfn{export}, a variable, @code{make} adds the
4186 variable and its value to the environment for running each line of the
4187 recipe.  The sub-@code{make}, in turn, uses the environment to
4188 initialize its table of variable values.  @xref{Environment,
4189 ,Variables from the Environment}.
4191 Except by explicit request, @code{make} exports a variable only if it
4192 is either defined in the environment initially or set on the command
4193 line, and if its name consists only of letters, numbers, and underscores.
4194 Some shells cannot cope with environment variable names consisting of
4195 characters other than letters, numbers, and underscores.
4197 @cindex SHELL, exported value
4198 The value of the @code{make} variable @code{SHELL} is not exported.
4199 Instead, the value of the @code{SHELL} variable from the invoking
4200 environment is passed to the sub-@code{make}.  You can force
4201 @code{make} to export its value for @code{SHELL} by using the
4202 @code{export} directive, described below.  @xref{Choosing the Shell}.
4204 The special variable @code{MAKEFLAGS} is always exported (unless you
4205 unexport it).  @code{MAKEFILES} is exported if you set it to anything.
4207 @code{make} automatically passes down variable values that were defined
4208 on the command line, by putting them in the @code{MAKEFLAGS} variable.
4209 @iftex
4210 See the next section.
4211 @end iftex
4212 @ifnottex
4213 @xref{Options/Recursion}.
4214 @end ifnottex
4216 Variables are @emph{not} normally passed down if they were created by
4217 default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
4218 Implicit Rules}).  The sub-@code{make} will define these for
4219 itself.@refill
4221 @findex export
4222 If you want to export specific variables to a sub-@code{make}, use the
4223 @code{export} directive, like this:
4225 @example
4226 export @var{variable} @dots{}
4227 @end example
4229 @noindent
4230 @findex unexport
4231 If you want to @emph{prevent} a variable from being exported, use the
4232 @code{unexport} directive, like this:
4234 @example
4235 unexport @var{variable} @dots{}
4236 @end example
4238 @noindent
4239 In both of these forms, the arguments to @code{export} and
4240 @code{unexport} are expanded, and so could be variables or functions
4241 which expand to a (list of) variable names to be (un)exported.
4243 As a convenience, you can define a variable and export it at the same
4244 time by doing:
4246 @example
4247 export @var{variable} = value
4248 @end example
4250 @noindent
4251 has the same result as:
4253 @example
4254 @var{variable} = value
4255 export @var{variable}
4256 @end example
4258 @noindent
4261 @example
4262 export @var{variable} := value
4263 @end example
4265 @noindent
4266 has the same result as:
4268 @example
4269 @var{variable} := value
4270 export @var{variable}
4271 @end example
4273 Likewise,
4275 @example
4276 export @var{variable} += value
4277 @end example
4279 @noindent
4280 is just like:
4282 @example
4283 @var{variable} += value
4284 export @var{variable}
4285 @end example
4287 @noindent
4288 @xref{Appending, ,Appending More Text to Variables}.
4290 You may notice that the @code{export} and @code{unexport} directives
4291 work in @code{make} in the same way they work in the shell, @code{sh}.
4293 If you want all variables to be exported by default, you can use
4294 @code{export} by itself:
4296 @example
4297 export
4298 @end example
4300 @noindent
4301 This tells @code{make} that variables which are not explicitly mentioned
4302 in an @code{export} or @code{unexport} directive should be exported.
4303 Any variable given in an @code{unexport} directive will still @emph{not}
4304 be exported.  If you use @code{export} by itself to export variables by
4305 default, variables whose names contain characters other than
4306 alphanumerics and underscores will not be exported unless specifically
4307 mentioned in an @code{export} directive.@refill
4310 The behavior elicited by an @code{export} directive by itself was the
4311 default in older versions of GNU @code{make}.  If your makefiles depend
4312 on this behavior and you want to be compatible with old versions of
4313 @code{make}, you can write a rule for the special target
4314 @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
4315 This will be ignored by old @code{make}s, while the @code{export}
4316 directive will cause a syntax error.@refill
4317 @cindex compatibility in exporting
4319 Likewise, you can use @code{unexport} by itself to tell @code{make}
4320 @emph{not} to export variables by default.  Since this is the default
4321 behavior, you would only need to do this if @code{export} had been used
4322 by itself earlier (in an included makefile, perhaps).  You
4323 @strong{cannot} use @code{export} and @code{unexport} by themselves to
4324 have variables exported for some recipes and not for others.  The last
4325 @code{export} or @code{unexport} directive that appears by itself
4326 determines the behavior for the entire run of @code{make}.@refill
4328 @vindex MAKELEVEL
4329 @cindex recursion, level of
4330 As a special feature, the variable @code{MAKELEVEL} is changed when it
4331 is passed down from level to level.  This variable's value is a string
4332 which is the depth of the level as a decimal number.  The value is
4333 @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
4334 @samp{2} for a sub-sub-@code{make}, and so on.  The incrementation
4335 happens when @code{make} sets up the environment for a recipe.@refill
4337 The main use of @code{MAKELEVEL} is to test it in a conditional
4338 directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
4339 way you can write a makefile that behaves one way if run recursively and
4340 another way if run directly by you.@refill
4342 @vindex MAKEFILES
4343 You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
4344 commands to use additional makefiles.  The value of @code{MAKEFILES} is
4345 a whitespace-separated list of file names.  This variable, if defined in
4346 the outer-level makefile, is passed down through the environment; then
4347 it serves as a list of extra makefiles for the sub-@code{make} to read
4348 before the usual or specified ones.  @xref{MAKEFILES Variable, ,The
4349 Variable @code{MAKEFILES}}.@refill
4351 @node Options/Recursion, -w Option, Variables/Recursion, Recursion
4352 @subsection Communicating Options to a Sub-@code{make}
4353 @cindex options, and recursion
4354 @cindex recursion, and options
4356 @vindex MAKEFLAGS
4357 Flags such as @samp{-s} and @samp{-k} are passed automatically to the
4358 sub-@code{make} through the variable @code{MAKEFLAGS}.  This variable is
4359 set up automatically by @code{make} to contain the flag letters that
4360 @code{make} received.  Thus, if you do @w{@samp{make -ks}} then
4361 @code{MAKEFLAGS} gets the value @samp{ks}.@refill
4363 As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
4364 in its environment.  In response, it takes the flags from that value and
4365 processes them as if they had been given as arguments.
4366 @xref{Options Summary, ,Summary of Options}.
4368 @cindex command line variable definitions, and recursion
4369 @cindex variables, command line, and recursion
4370 @cindex recursion, and command line variable definitions
4371 Likewise variables defined on the command line are passed to the
4372 sub-@code{make} through @code{MAKEFLAGS}.  Words in the value of
4373 @code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable
4374 definitions just as if they appeared on the command line.
4375 @xref{Overriding, ,Overriding Variables}.
4377 @cindex @code{-C}, and recursion
4378 @cindex @code{-f}, and recursion
4379 @cindex @code{-o}, and recursion
4380 @cindex @code{-W}, and recursion
4381 @cindex @code{--directory}, and recursion
4382 @cindex @code{--file}, and recursion
4383 @cindex @code{--old-file}, and recursion
4384 @cindex @code{--assume-old}, and recursion
4385 @cindex @code{--assume-new}, and recursion
4386 @cindex @code{--new-file}, and recursion
4387 @cindex recursion, and @code{-C}
4388 @cindex recursion, and @code{-f}
4389 @cindex recursion, and @code{-o}
4390 @cindex recursion, and @code{-W}
4391 The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put
4392 into @code{MAKEFLAGS}; these options are not passed down.@refill
4394 @cindex @code{-j}, and recursion
4395 @cindex @code{--jobs}, and recursion
4396 @cindex recursion, and @code{-j}
4397 @cindex job slots, and recursion
4398 The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
4399 If you set it to some numeric value @samp{N} and your operating system
4400 supports it (most any UNIX system will; others typically won't), the
4401 parent @code{make} and all the sub-@code{make}s will communicate to
4402 ensure that there are only @samp{N} jobs running at the same time
4403 between them all.  Note that any job that is marked recursive
4404 (@pxref{Instead of Execution, ,Instead of Executing Recipes})
4405 doesn't count against the total jobs (otherwise we could get @samp{N}
4406 sub-@code{make}s running and have no slots left over for any real work!)
4408 If your operating system doesn't support the above communication, then
4409 @samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you
4410 specified.  This is because if the @w{@samp{-j}} option were passed down
4411 to sub-@code{make}s, you would get many more jobs running in parallel
4412 than you asked for.  If you give @samp{-j} with no numeric argument,
4413 meaning to run as many jobs as possible in parallel, this is passed
4414 down, since multiple infinities are no more than one.@refill
4416 If you do not want to pass the other flags down, you must change the
4417 value of @code{MAKEFLAGS}, like this:
4419 @example
4420 subsystem:
4421         cd subdir && $(MAKE) MAKEFLAGS=
4422 @end example
4424 @vindex MAKEOVERRIDES
4425 The command line variable definitions really appear in the variable
4426 @code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this
4427 variable.  If you do want to pass flags down normally, but don't want to
4428 pass down the command line variable definitions, you can reset
4429 @code{MAKEOVERRIDES} to empty, like this:
4431 @example
4433 @end example
4435 @noindent
4436 @cindex Arg list too long
4437 @cindex E2BIG
4438 This is not usually useful to do.  However, some systems have a small
4439 fixed limit on the size of the environment, and putting so much
4440 information into the value of @code{MAKEFLAGS} can exceed it.  If you
4441 see the error message @samp{Arg list too long}, this may be the problem.
4442 @findex .POSIX
4443 @cindex POSIX.2
4444 (For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does
4445 not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears
4446 in the makefile.  You probably do not care about this.)
4448 @vindex MFLAGS
4449 A similar variable @code{MFLAGS} exists also, for historical
4450 compatibility.  It has the same value as @code{MAKEFLAGS} except that it
4451 does not contain the command line variable definitions, and it always
4452 begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a
4453 hyphen only when it begins with an option that has no single-letter
4454 version, such as @samp{--warn-undefined-variables}).  @code{MFLAGS} was
4455 traditionally used explicitly in the recursive @code{make} command, like
4456 this:
4458 @example
4459 subsystem:
4460         cd subdir && $(MAKE) $(MFLAGS)
4461 @end example
4463 @noindent
4464 but now @code{MAKEFLAGS} makes this usage redundant.  If you want your
4465 makefiles to be compatible with old @code{make} programs, use this
4466 technique; it will work fine with more modern @code{make} versions too.
4468 @cindex setting options from environment
4469 @cindex options, setting from environment
4470 @cindex setting options in makefiles
4471 @cindex options, setting in makefiles
4472 The @code{MAKEFLAGS} variable can also be useful if you want to have
4473 certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
4474 Options}), set each time you run @code{make}.  You simply put a value for
4475 @code{MAKEFLAGS} in your environment.  You can also set @code{MAKEFLAGS} in
4476 a makefile, to specify additional flags that should also be in effect for
4477 that makefile.  (Note that you cannot use @code{MFLAGS} this way.  That
4478 variable is set only for compatibility; @code{make} does not interpret a
4479 value you set for it in any way.)
4481 When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
4482 environment or from a makefile), it first prepends a hyphen if the value
4483 does not already begin with one.  Then it chops the value into words
4484 separated by blanks, and parses these words as if they were options given
4485 on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
4486 @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
4487 is no error for an invalid option).
4489 If you do put @code{MAKEFLAGS} in your environment, you should be sure not
4490 to include any options that will drastically affect the actions of
4491 @code{make} and undermine the purpose of makefiles and of @code{make}
4492 itself.  For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
4493 put in one of these variables, could have disastrous consequences and would
4494 certainly have at least surprising and probably annoying effects.@refill
4496 @node -w Option,  , Options/Recursion, Recursion
4497 @subsection The @samp{--print-directory} Option
4498 @cindex directories, printing them
4499 @cindex printing directories
4500 @cindex recursion, and printing directories
4502 If you use several levels of recursive @code{make} invocations, the
4503 @samp{-w} or @w{@samp{--print-directory}} option can make the output a
4504 lot easier to understand by showing each directory as @code{make}
4505 starts processing it and as @code{make} finishes processing it.  For
4506 example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
4507 @code{make} will print a line of the form:@refill
4509 @example
4510 make: Entering directory `/u/gnu/make'.
4511 @end example
4513 @noindent
4514 before doing anything else, and a line of the form:
4516 @example
4517 make: Leaving directory `/u/gnu/make'.
4518 @end example
4520 @noindent
4521 when processing is completed.
4523 @cindex @code{-C}, and @code{-w}
4524 @cindex @code{--directory}, and @code{--print-directory}
4525 @cindex recursion, and @code{-w}
4526 @cindex @code{-w}, and @code{-C}
4527 @cindex @code{-w}, and recursion
4528 @cindex @code{--print-directory}, and @code{--directory}
4529 @cindex @code{--print-directory}, and recursion
4530 @cindex @code{--no-print-directory}
4531 @cindex @code{--print-directory}, disabling
4532 @cindex @code{-w}, disabling
4533 Normally, you do not need to specify this option because @samp{make}
4534 does it for you: @samp{-w} is turned on automatically when you use the
4535 @samp{-C} option, and in sub-@code{make}s.  @code{make} will not
4536 automatically turn on @samp{-w} if you also use @samp{-s}, which says to
4537 be silent, or if you use @samp{--no-print-directory} to explicitly
4538 disable it.
4540 @node Canned Recipes, Empty Recipes, Recursion, Recipes
4541 @section Defining Canned Recipes
4542 @cindex canned recipes
4543 @cindex recipes, canned
4544 @cindex sequences of commands
4545 @cindex commands, sequences of
4547 When the same sequence of commands is useful in making various
4548 targets, you can define it as a canned sequence with the @code{define}
4549 directive, and refer to the canned sequence from the recipes for those
4550 targets.  The canned sequence is actually a variable, so the name must
4551 not conflict with other variable names.
4553 Here is an example of defining a canned recipe:
4555 @example
4556 define run-yacc =
4557 yacc $(firstword $^)
4558 mv y.tab.c $@@
4559 endef
4560 @end example
4561 @cindex @code{yacc}
4563 @noindent
4564 Here @code{run-yacc} is the name of the variable being defined;
4565 @code{endef} marks the end of the definition; the lines in between are the
4566 commands.  The @code{define} directive does not expand variable references
4567 and function calls in the canned sequence; the @samp{$} characters,
4568 parentheses, variable names, and so on, all become part of the value of the
4569 variable you are defining.
4570 @xref{Multi-Line, ,Defining Multi-Line Variables},
4571 for a complete explanation of @code{define}.
4573 The first command in this example runs Yacc on the first prerequisite of
4574 whichever rule uses the canned sequence.  The output file from Yacc is
4575 always named @file{y.tab.c}.  The second command moves the output to the
4576 rule's target file name.
4578 To use the canned sequence, substitute the variable into the recipe of a
4579 rule.  You can substitute it like any other variable
4580 (@pxref{Reference, ,Basics of Variable References}).
4581 Because variables defined by @code{define} are recursively expanded
4582 variables, all the variable references you wrote inside the @code{define}
4583 are expanded now.  For example:
4585 @example
4586 foo.c : foo.y
4587         $(run-yacc)
4588 @end example
4590 @noindent
4591 @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
4592 @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
4594 This is a realistic example, but this particular one is not needed in
4595 practice because @code{make} has an implicit rule to figure out these
4596 commands based on the file names involved
4597 (@pxref{Implicit Rules, ,Using Implicit Rules}).
4599 @cindex @@, and @code{define}
4600 @cindex -, and @code{define}
4601 @cindex +, and @code{define}
4602 In recipe execution, each line of a canned sequence is treated just as
4603 if the line appeared on its own in the rule, preceded by a tab.  In
4604 particular, @code{make} invokes a separate subshell for each line.  You
4605 can use the special prefix characters that affect command lines
4606 (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
4607 @xref{Recipes, ,Writing Recipes in Rules}.
4608 For example, using this canned sequence:
4610 @example
4611 define frobnicate =
4612 @@echo "frobnicating target $@@"
4613 frob-step-1 $< -o $@@-step-1
4614 frob-step-2 $@@-step-1 -o $@@
4615 endef
4616 @end example
4618 @noindent
4619 @code{make} will not echo the first line, the @code{echo} command.
4620 But it @emph{will} echo the following two recipe lines.
4622 On the other hand, prefix characters on the recipe line that refers to
4623 a canned sequence apply to every line in the sequence.  So the rule:
4625 @example
4626 frob.out: frob.in
4627         @@$(frobnicate)
4628 @end example
4630 @noindent
4631 does not echo @emph{any} recipe lines.
4632 (@xref{Echoing, ,Recipe Echoing}, for a full explanation of @samp{@@}.)
4634 @node Empty Recipes,  , Canned Recipes, Recipes
4635 @section Using Empty Recipes
4636 @cindex empty recipes
4637 @cindex recipes, empty
4639 It is sometimes useful to define recipes which do nothing.  This is done
4640 simply by giving a recipe that consists of nothing but whitespace.  For
4641 example:
4643 @example
4644 target: ;
4645 @end example
4647 @noindent
4648 defines an empty recipe for @file{target}.  You could also use a line
4649 beginning with a recipe prefix character to define an empty recipe,
4650 but this would be confusing because such a line looks empty.
4652 @findex .DEFAULT@r{, and empty recipes}
4653 You may be wondering why you would want to define a recipe that
4654 does nothing.  The only reason this is useful is to prevent a target
4655 from getting implicit recipes (from implicit rules or the
4656 @code{.DEFAULT} special target; @pxref{Implicit Rules} and
4657 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
4659 @c !!! another reason is for canonical stamp files:
4660 @ignore
4661 @example
4662 foo: stamp-foo ;
4663 stamp-foo: foo.in
4664         create foo frm foo.in
4665         touch $@
4666 @end example
4667 @end ignore
4669 You may be inclined to define empty recipes for targets that are
4670 not actual files, but only exist so that their prerequisites can be
4671 remade.  However, this is not the best way to do that, because the
4672 prerequisites may not be remade properly if the target file actually does exist.
4673 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
4675 @node Using Variables, Conditionals, Recipes, Top
4676 @chapter How to Use Variables
4677 @cindex variable
4678 @cindex value
4679 @cindex recursive variable expansion
4680 @cindex simple variable expansion
4682 A @dfn{variable} is a name defined in a makefile to represent a string
4683 of text, called the variable's @dfn{value}.  These values are
4684 substituted by explicit request into targets, prerequisites, recipes,
4685 and other parts of the makefile.  (In some other versions of @code{make},
4686 variables are called @dfn{macros}.)
4687 @cindex macro
4689 Variables and functions in all parts of a makefile are expanded when
4690 read, except for in recipes, the right-hand sides of variable
4691 definitions using @samp{=}, and the bodies of variable definitions
4692 using the @code{define} directive.@refill
4694 Variables can represent lists of file names, options to pass to compilers,
4695 programs to run, directories to look in for source files, directories to
4696 write output in, or anything else you can imagine.
4698 A variable name may be any sequence of characters not containing @samp{:},
4699 @samp{#}, @samp{=}, or leading or trailing whitespace.  However,
4700 variable names containing characters other than letters, numbers, and
4701 underscores should be avoided, as they may be given special meanings in the
4702 future, and with some shells they cannot be passed through the environment to a
4703 sub-@code{make}
4704 (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
4706 Variable names are case-sensitive.  The names @samp{foo}, @samp{FOO},
4707 and @samp{Foo} all refer to different variables.
4709 It is traditional to use upper case letters in variable names, but we
4710 recommend using lower case letters for variable names that serve internal
4711 purposes in the makefile, and reserving upper case for parameters that
4712 control implicit rules or for parameters that the user should override with
4713 command options (@pxref{Overriding, ,Overriding Variables}).
4715 A few variables have names that are a single punctuation character or
4716 just a few characters.  These are the @dfn{automatic variables}, and
4717 they have particular specialized uses.  @xref{Automatic Variables}.
4719 @menu
4720 * Reference::                   How to use the value of a variable.
4721 * Flavors::                     Variables come in two flavors.
4722 * Advanced::                    Advanced features for referencing a variable.
4723 * Values::                      All the ways variables get their values.
4724 * Setting::                     How to set a variable in the makefile.
4725 * Appending::                   How to append more text to the old value
4726                                   of a variable.
4727 * Override Directive::          How to set a variable in the makefile even if
4728                                   the user has set it with a command argument.
4729 * Multi-Line::                  An alternate way to set a variable
4730                                   to a multi-line string.
4731 * Undefine Directive::          How to undefine a variable so that it appears
4732                                   as if it was never set.
4733 * Environment::                 Variable values can come from the environment.
4734 * Target-specific::             Variable values can be defined on a per-target
4735                                   basis.
4736 * Pattern-specific::            Target-specific variable values can be applied
4737                                   to a group of targets that match a pattern.
4738 * Suppressing Inheritance::     Suppress inheritance of variables.
4739 * Special Variables::           Variables with special meaning or behavior.
4740 @end menu
4742 @node Reference, Flavors, Using Variables, Using Variables
4743 @section Basics of Variable References
4744 @cindex variables, how to reference
4745 @cindex reference to variables
4746 @cindex @code{$}, in variable reference
4747 @cindex dollar sign (@code{$}), in variable reference
4749 To substitute a variable's value, write a dollar sign followed by the name
4750 of the variable in parentheses or braces: either @samp{$(foo)} or
4751 @samp{$@{foo@}} is a valid reference to the variable @code{foo}.  This
4752 special significance of @samp{$} is why you must write @samp{$$} to have
4753 the effect of a single dollar sign in a file name or recipe.
4755 Variable references can be used in any context: targets, prerequisites,
4756 recipes, most directives, and new variable values.  Here is an
4757 example of a common case, where a variable holds the names of all the
4758 object files in a program:
4760 @example
4761 @group
4762 objects = program.o foo.o utils.o
4763 program : $(objects)
4764         cc -o program $(objects)
4766 $(objects) : defs.h
4767 @end group
4768 @end example
4770 Variable references work by strict textual substitution.  Thus, the rule
4772 @example
4773 @group
4774 foo = c
4775 prog.o : prog.$(foo)
4776         $(foo)$(foo) -$(foo) prog.$(foo)
4777 @end group
4778 @end example
4780 @noindent
4781 could be used to compile a C program @file{prog.c}.  Since spaces before
4782 the variable value are ignored in variable assignments, the value of
4783 @code{foo} is precisely @samp{c}.  (Don't actually write your makefiles
4784 this way!)
4786 A dollar sign followed by a character other than a dollar sign,
4787 open-parenthesis or open-brace treats that single character as the
4788 variable name.  Thus, you could reference the variable @code{x} with
4789 @samp{$x}.  However, this practice is strongly discouraged, except in
4790 the case of the automatic variables (@pxref{Automatic Variables}).
4792 @node Flavors, Advanced, Reference, Using Variables
4793 @section The Two Flavors of Variables
4794 @cindex flavors of variables
4795 @cindex recursive variable expansion
4796 @cindex variables, flavors
4797 @cindex recursively expanded variables
4798 @cindex variables, recursively expanded
4800 There are two ways that a variable in GNU @code{make} can have a value;
4801 we call them the two @dfn{flavors} of variables.  The two flavors are
4802 distinguished in how they are defined and in what they do when expanded.
4804 @cindex =
4805 The first flavor of variable is a @dfn{recursively expanded} variable.
4806 Variables of this sort are defined by lines using @samp{=}
4807 (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
4808 (@pxref{Multi-Line, ,Defining Multi-Line Variables}).  The value you specify
4809 is installed verbatim; if it contains references to other variables,
4810 these references are expanded whenever this variable is substituted (in
4811 the course of expanding some other string).  When this happens, it is
4812 called @dfn{recursive expansion}.@refill
4814 For example,
4816 @example
4817 foo = $(bar)
4818 bar = $(ugh)
4819 ugh = Huh?
4821 all:;echo $(foo)
4822 @end example
4824 @noindent
4825 will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
4826 expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
4828 This flavor of variable is the only sort supported by other versions of
4829 @code{make}.  It has its advantages and its disadvantages.  An advantage
4830 (most would say) is that:
4832 @example
4833 CFLAGS = $(include_dirs) -O
4834 include_dirs = -Ifoo -Ibar