Sun May 12 19:19:43 1996 Aaron Digulla <digulla@fh-konstanz.de>
[make.git] / make.texinfo
blob0aa346641dccbe5d980338c9e52a85820562d76c
1 \input texinfo                @c -*- Texinfo -*-
2 @c %**start of header
3 @setfilename make.info
4 @settitle GNU @code{make}
5 @setchapternewpage odd
6 @c %**end of header
8 @c FSF publishers: format makebook.texi instead of using this file directly.
10 @set RCSID $Id: make.texinfo,v 2.160 1996/05/09 17:25:54 roland Exp $
11 @set EDITION 0.51
12 @set VERSION 3.75 Beta
13 @set UPDATED 9 May 1996
14 @set UPDATE-MONTH May 1996
15 @comment The ISBN number might need to change on next publication.
16 @set ISBN 1-882114-78-7 @c CHANGE THIS BEFORE PRINTING AGAIN! --roland 9may96
18 @c finalout
20 @c ISPELL CHECK: done, 10 June 1993 --roland
22 @c Combine the variable and function indices:
23 @syncodeindex vr fn
24 @c Combine the program and concept indices:
25 @syncodeindex pg cp
27 @ifinfo
28 This file documents the GNU Make utility, which determines
29 automatically which pieces of a large program need to be recompiled,
30 and issues the commands to recompile them.
32 This is Edition @value{EDITION}, last updated @value{UPDATED},
33 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
35 Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96
36         Free Software Foundation, Inc.
38 Permission is granted to make and distribute verbatim copies of
39 this manual provided the copyright notice and this permission notice
40 are preserved on all copies.
42 @ignore
43 Permission is granted to process this file through TeX and print the
44 results, provided the printed document carries copying permission
45 notice identical to this one except for the removal of this paragraph
46 (this paragraph not being relevant to the printed manual).
48 @end ignore
49 Permission is granted to copy and distribute modified versions of this
50 manual under the conditions for verbatim copying, provided that the entire
51 resulting derived work is distributed under the terms of a permission
52 notice identical to this one.
54 Permission is granted to copy and distribute translations of this manual
55 into another language, under the above conditions for modified versions,
56 except that this permission notice may be stated in a translation approved
57 by the Free Software Foundation.
58 @end ifinfo
60 @iftex
61 @shorttitlepage GNU Make
62 @end iftex
63 @titlepage
64 @title GNU Make
65 @subtitle A Program for Directing Recompilation
66 @subtitle Edition @value{EDITION}, for @code{make} Version @value{VERSION}.
67 @subtitle @value{UPDATE-MONTH}
68 @author Richard M. Stallman and Roland McGrath
69 @page
70 @vskip 0pt plus 1filll
71 Copyright @copyright{} 1988, '89, '90, '91, '92, '93, '94, '95, '96 Free Software Foundation, Inc.
72 @sp 2
73 Published by the Free Software Foundation @*
74 59 Temple Place -- Suite 330, @*
75 Boston, MA 02111-1307 USA @*
76 Printed copies are available for $20 each. @*
77 ISBN @value{ISBN} @*
79 Permission is granted to make and distribute verbatim copies of
80 this manual provided the copyright notice and this permission notice
81 are preserved on all copies.
83 Permission is granted to copy and distribute modified versions of this
84 manual under the conditions for verbatim copying, provided that the entire
85 resulting derived work is distributed under the terms of a permission
86 notice identical to this one.
88 Permission is granted to copy and distribute translations of this manual
89 into another language, under the above conditions for modified versions,
90 except that this permission notice may be stated in a translation approved
91 by the Free Software Foundation.
92 @sp 2
93 Cover art by Etienne Suvasa.
94 @end titlepage
95 @page
97 @ifinfo
98 @node Top, Overview, (dir), (dir)
99 @top Make
101 The GNU @code{make} utility automatically determines which pieces of a
102 large program need to be recompiled, and issues the commands to
103 recompile them.@refill
105 This is Edition @value{EDITION} of the @cite{GNU Make Manual},
106 last updated @value{UPDATED}
107 for @code{make} Version @value{VERSION}.@refill
109 This manual describes @code{make} and contains the following chapters:@refill
110 @end ifinfo
112 @menu
113 * Overview::                    Overview of @code{make}.
114 * Introduction::                An introduction to @code{make}.
115 * Makefiles::                   Makefiles tell @code{make} what to do.
116 * Rules::                       Rules describe when a file must be remade.
117 * Commands::                    Commands say how to remake a file.
118 * Using Variables::             You can use variables to avoid repetition.
119 * Conditionals::                Use or ignore parts of the makefile based
120                                  on the values of variables.
121 * Functions::                   Many powerful ways to manipulate text.
122 * make Invocation: Running.     How to invoke @code{make} on the command line.
123 * Implicit Rules::              Use implicit rules to treat many files alike,
124                                  based on their file names.
125 * Archives::                    How @code{make} can update library archives.
126 * Features::                    Features GNU @code{make} has over other @code{make}s.
127 * Missing::                     What GNU @code{make} lacks from other @code{make}s.
128 * Makefile Conventions::        Conventions for makefiles in GNU programs.
129 * Quick Reference::             A quick reference for experienced users.
130 * Complex Makefile::            A real example of a straightforward,
131                                  but nontrivial, makefile.
132 * Concept Index::               Index of Concepts
133 * Name Index::                  Index of Functions, Variables, & Directives
135  --- The Detailed Node Listing ---
137 Overview of @code{make}
139 * Preparing::                   Preparing and Running Make
140 * Reading::                     On Reading this Text
141 * Bugs::                        Problems and Bugs
143 An Introduction to Makefiles
145 * Rule Introduction::           What a rule looks like.
146 * Simple Makefile::             A Simple Makefile
147 * How Make Works::              How @code{make} Processes This Makefile
148 * Variables Simplify::          Variables Make Makefiles Simpler
149 * make Deduces::                Letting @code{make} Deduce the Commands
150 * Combine By Dependency::       Another Style of Makefile
151 * Cleanup::                     Rules for Cleaning the Directory
153 Writing Makefiles
155 * Makefile Contents::           What makefiles contain.
156 * Makefile Names::              How to name your makefile.
157 * Include::                     How one makefile can use another makefile.
158 * MAKEFILES Variable::          The environment can specify extra makefiles.
159 * Remaking Makefiles::          How makefiles get remade.
160 * Overriding Makefiles::        How to override part of one makefile
161                                  with another makefile.
163 Writing Rules
165 * Rule Example::                An example explained.
166 * Rule Syntax::                 General syntax explained.
167 * Wildcards::                   Using wildcard characters such as `*'.
168 * Directory Search::            Searching other directories for source files.
169 * Phony Targets::               Using a target that is not a real file's name.
170 * Force Targets::               You can use a target without commands
171                                   or dependencies to mark other
172                                   targets as phony.
173 * Empty Targets::               When only the date matters and the
174                                   files are empty.
175 * Special Targets::             Targets with special built-in meanings.
176 * Multiple Targets::            When to make use of several targets in a rule.
177 * Multiple Rules::              How to use several rules with the same target.
178 * Static Pattern::              Static pattern rules apply to multiple targets
179                                   and can vary the dependencies according to
180                                   the target name.
181 * Double-Colon::                How to use a special kind of rule to allow
182                                   several independent rules for one target.
183 * Automatic Dependencies::      How to automatically generate rules giving
184                                  dependencies from the source files themselves.
186 Using Wildcard Characters in File Names
188 * Wildcard Examples::           Several examples
189 * Wildcard Pitfall::            Problems to avoid.
190 * Wildcard Function::           How to cause wildcard expansion where
191                                   it does not normally take place.
193 Searching Directories for Dependencies
195 * General Search::              Specifying a search path that applies
196                                   to every dependency.
197 * Selective Search::            Specifying a search path
198                                   for a specified class of names.
199 * Commands/Search::             How to write shell commands that work together
200                                   with search paths.
201 * Implicit/Search::             How search paths affect implicit rules.
202 * Libraries/Search::            Directory search for link libraries.
204 Static Pattern Rules
206 * Static Usage::                The syntax of static pattern rules.
207 * Static versus Implicit::      When are they better than implicit rules?
209 Writing the Commands in Rules
211 * Echoing::                     How to control when commands are echoed.
212 * Execution::                   How commands are executed.
213 * Parallel::                    How commands can be executed in parallel.
214 * Errors::                      What happens after a command execution error.
215 * Interrupts::                  What happens when a command is interrupted.
216 * Recursion::                   Invoking @code{make} from makefiles.
217 * Sequences::                   Defining canned sequences of commands.
218 * Empty Commands::              Defining useful, do-nothing commands.
220 Recursive Use of @code{make}
222 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
223 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
224 * Options/Recursion::           How to communicate options to a sub-@code{make}.
225 * -w Option::                   How the @samp{-w} or @samp{--print-directory} option
226                                  helps debug use of recursive @code{make} commands.
228 How to Use Variables
230 * Reference::                   How to use the value of a variable.
231 * Flavors::                     Variables come in two flavors.
232 * Advanced::                    Advanced features for referencing a variable.
233 * Values::                      All the ways variables get their values.
234 * Setting::                     How to set a variable in the makefile.
235 * Appending::                   How to append more text to the old value
236                                   of a variable.
237 * Override Directive::          How to set a variable in the makefile even if
238                                   the user has set it with a command argument.
239 * Defining::                    An alternate way to set a variable
240                                   to a verbatim string.
241 * Environment::                 Variable values can come from the environment.
243 Advanced Features for Reference to Variables
245 * Substitution Refs::           Referencing a variable with
246                                   substitutions on the value.
247 * Computed Names::              Computing the name of the variable to refer to.
249 Conditional Parts of Makefiles
251 * Conditional Example::         Example of a conditional
252 * Conditional Syntax::          The syntax of conditionals.
253 * Testing Flags::               Conditionals that test flags.
255 Functions for Transforming Text
257 * Syntax of Functions::         How to write a function call.
258 * Text Functions::              General-purpose text manipulation functions.
259 * Filename Functions::          Functions for manipulating file names.
260 * Foreach Function::            Repeat some text with controlled variation.
261 * Origin Function::             Find where a variable got its value.
262 * Shell Function::              Substitute the output of a shell command.
264 How to Run @code{make}
266 * Makefile Arguments::          How to specify which makefile to use.
267 * Goals::                       How to use goal arguments to specify which
268                                   parts of the makefile to use.
269 * Instead of Execution::        How to use mode flags to specify what
270                                   kind of thing to do with the commands
271                                   in the makefile other than simply
272                                   execute them.
273 * Avoiding Compilation::        How to avoid recompiling certain files.
274 * Overriding::                  How to override a variable to specify
275                                   an alternate compiler and other things.
276 * Testing::                     How to proceed past some errors, to
277                                   test compilation.
278 * Options Summary::             Summary of Options
280 Using Implicit Rules
282 * Using Implicit::              How to use an existing implicit rule
283                                   to get the commands for updating a file.
284 * Catalogue of Rules::          A list of built-in implicit rules.
285 * Implicit Variables::          How to change what predefined rules do.
286 * Chained Rules::               How to use a chain of implicit rules.
287 * Pattern Rules::               How to define new implicit rules.
288 * Last Resort::                 How to defining commands for rules
289                                   which cannot find any.
290 * Suffix Rules::                The old-fashioned style of implicit rule.
291 * Search Algorithm::            The precise algorithm for applying
292                                   implicit rules.
294 Defining and Redefining Pattern Rules
296 * Pattern Intro::               An introduction to pattern rules.
297 * Pattern Examples::            Examples of pattern rules.
298 * Automatic::                   How to use automatic variables in the
299                                   commands of implicit rules.
300 * Pattern Match::               How patterns match.
301 * Match-Anything Rules::        Precautions you should take prior to
302                                   defining rules that can match any
303                                   target file whatever.
304 * Canceling Rules::             How to override or cancel built-in rules.
306 Using @code{make} to Update Archive Files
308 * Archive Members::             Archive members as targets.
309 * Archive Update::              The implicit rule for archive member targets.
310 * Archive Suffix Rules::        You can write a special kind of suffix rule
311                                   for updating archives.
313 Implicit Rule for Archive Member Targets
315 * Archive Symbols::             How to update archive symbol directories.
316 @end menu
318 @node Overview, Introduction, Top, Top
319 @comment  node-name,  next,  previous,  up
320 @chapter Overview of @code{make}
322 The @code{make} utility automatically determines which pieces of a large
323 program need to be recompiled, and issues commands to recompile them.
324 This manual describes GNU @code{make}, which was implemented by Richard
325 Stallman and Roland McGrath.  GNU @code{make} conforms to section 6.2 of
326 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
327 @cindex POSIX
328 @cindex IEEE Standard 1003.2
329 @cindex standards conformance
331 Our examples show C programs, since they are most common, but you can use
332 @code{make} with any programming language whose compiler can be run with a
333 shell command.  Indeed, @code{make} is not limited to programs.  You can
334 use it to describe any task where some files must be updated automatically
335 from others whenever the others change.
337 @menu
338 * Preparing::                   Preparing and Running Make
339 * Reading::                     On Reading this Text
340 * Bugs::                        Problems and Bugs
341 @end menu
343 @node Preparing, Reading,  , Overview
344 @ifinfo
345 @heading Preparing and Running Make
346 @end ifinfo
348 To prepare to use @code{make}, you must write a file called
349 the @dfn{makefile} that describes the relationships among files
350 in your program and provides commands for updating each file.
351 In a program, typically, the executable file is updated from object
352 files, which are in turn made by compiling source files.@refill
354 Once a suitable makefile exists, each time you change some source files,
355 this simple shell command:
357 @example
358 make
359 @end example
361 @noindent
362 suffices to perform all necessary recompilations.  The @code{make} program
363 uses the makefile data base and the last-modification times of the files to
364 decide which of the files need to be updated.  For each of those files, it
365 issues the commands recorded in the data base.
367 You can provide command line arguments to @code{make} to control which
368 files should be recompiled, or how.  @xref{Running, ,How to Run
369 @code{make}}.
371 @node Reading, Bugs, Preparing, Overview
372 @section How to Read This Manual
374 If you are new to @code{make}, or are looking for a general
375 introduction, read the first few sections of each chapter, skipping the
376 later sections.  In each chapter, the first few sections contain
377 introductory or general information and the later sections contain
378 specialized or technical information.
379 @ifinfo
380 The exception is the second chapter, @ref{Introduction, ,An
381 Introduction to Makefiles}, all of which is introductory.
382 @end ifinfo
383 @iftex
384 The exception is @ref{Introduction, ,An Introduction to Makefiles},
385 all of which is introductory.
386 @end iftex
388 If you are familiar with other @code{make} programs, see @ref{Features,
389 ,Features of GNU @code{make}}, which lists the enhancements GNU
390 @code{make} has, and @ref{Missing, ,Incompatibilities and Missing
391 Features}, which explains the few things GNU @code{make} lacks that
392 others have.
394 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
395 and @ref{Special Targets}.
397 @node Bugs,  , Reading, Overview
398 @section Problems and Bugs
399 @cindex reporting bugs
400 @cindex bugs, reporting
401 @cindex problems and bugs, reporting
403 If you have problems with GNU @code{make} or think you've found a bug,
404 please report it to the developers; we cannot promise to do anything but
405 we might well want to fix it.
407 Before reporting a bug, make sure you've actually found a real bug.
408 Carefully reread the documentation and see if it really says you can do
409 what you're trying to do.  If it's not clear whether you should be able
410 to do something or not, report that too; it's a bug in the
411 documentation!
413 Before reporting a bug or trying to fix it yourself, try to isolate it
414 to the smallest possible makefile that reproduces the problem.  Then
415 send us the makefile and the exact results @code{make} gave you.  Also
416 say what you expected to occur; this will help us decide whether the
417 problem was really in the documentation.
419 Once you've got a precise problem, please send electronic mail either
420 through the Internet or via UUCP:
422 @example
423 @group
424 @r{Internet address:}
425     bug-gnu-utils@@prep.ai.mit.edu
427 @r{UUCP path:}
428     mit-eddie!prep.ai.mit.edu!bug-gnu-utils
429 @end group
430 @end example
432 @noindent
433 Please include the version number of @code{make} you are using.  You can
434 get this information with the command @samp{make --version}.
435 Be sure also to include the type of machine and operating system you are
436 using.  If possible, include the contents of the file @file{config.h}
437 that is generated by the configuration process.
439 @node Introduction, Makefiles, Overview, Top
440 @comment  node-name,  next,  previous,  up
441 @chapter An Introduction to Makefiles
443 You need a file called a @dfn{makefile} to tell @code{make} what to do.
444 Most often, the makefile tells @code{make} how to compile and link a
445 program.
446 @cindex makefile
448 In this chapter, we will discuss a simple makefile that describes how to
449 compile and link a text editor which consists of eight C source files
450 and three header files.  The makefile can also tell @code{make} how to
451 run miscellaneous commands when explicitly asked (for example, to remove
452 certain files as a clean-up operation).  To see a more complex example
453 of a makefile, see @ref{Complex Makefile}.
455 When @code{make} recompiles the editor, each changed C source file
456 must be recompiled.  If a header file has changed, each C source file
457 that includes the header file must be recompiled to be safe.  Each
458 compilation produces an object file corresponding to the source file.
459 Finally, if any source file has been recompiled, all the object files,
460 whether newly made or saved from previous compilations, must be linked
461 together to produce the new executable editor.
462 @cindex recompilation
463 @cindex editor
465 @menu
466 * Rule Introduction::           What a rule looks like.
467 * Simple Makefile::             A Simple Makefile
468 * How Make Works::              How @code{make} Processes This Makefile
469 * Variables Simplify::          Variables Make Makefiles Simpler
470 * make Deduces::                Letting @code{make} Deduce the Commands
471 * Combine By Dependency::       Another Style of Makefile
472 * Cleanup::                     Rules for Cleaning the Directory
473 @end menu
475 @node Rule Introduction, Simple Makefile,  , Introduction
476 @comment  node-name,  next,  previous,  up
477 @section What a Rule Looks Like
478 @cindex rule, introduction to
479 @cindex makefile rule parts
480 @cindex parts of makefile rule
482 A simple makefile consists of ``rules'' with the following shape:
484 @cindex targets, introduction to
485 @cindex dependencies, introduction to
486 @cindex commands, introduction to
487 @example
488 @group
489 @var{target} @dots{} : @var{dependencies} @dots{}
490         @var{command}
491         @dots{}
492         @dots{}
493 @end group
494 @end example
496 A @dfn{target} is usually the name of a file that is generated by a
497 program; examples of targets are executable or object files.  A target
498 can also be the name of an action to carry out, such as @samp{clean}
499 (@pxref{Phony Targets}).
501 A @dfn{dependency} is a file that is used as input to create the
502 target.  A target often depends on several files.
504 @cindex tabs in rules
505 A @dfn{command} is an action that @code{make} carries out.
506 A rule may have more than one command, each on its own line.
507 @strong{Please note:} you need to put a tab character at the beginning of
508 every command line!  This is an obscurity that catches the unwary.
510 Usually a command is in a rule with dependencies and serves to create a
511 target file if any of the dependencies change.  However, the rule that
512 specifies commands for the target need not have dependencies.  For
513 example, the rule containing the delete command associated with the
514 target @samp{clean} does not have dependencies.
516 A @dfn{rule}, then, explains how and when to remake certain files
517 which are the targets of the particular rule.  @code{make} carries out
518 the commands on the dependencies to create or update the target.  A
519 rule can also explain how and when to carry out an action.
520 @xref{Rules, , Writing Rules}.
522 A makefile may contain other text besides rules, but a simple makefile
523 need only contain rules.  Rules may look somewhat more complicated
524 than shown in this template, but all fit the pattern more or less.
526 @node Simple Makefile, How Make Works, Rule Introduction, Introduction
527 @section A Simple Makefile
528 @cindex simple makefile
529 @cindex makefile, simple
531 Here is a straightforward makefile that describes the way an
532 executable file called @code{edit} depends on eight object files
533 which, in turn, depend on eight C source and three header files.
535 In this example, all the C files include @file{defs.h}, but only those
536 defining editing commands include @file{command.h}, and only low
537 level files that change the editor buffer include @file{buffer.h}.
539 @example
540 @group
541 edit : main.o kbd.o command.o display.o \
542        insert.o search.o files.o utils.o
543         cc -o edit main.o kbd.o command.o display.o \
544                    insert.o search.o files.o utils.o
546 main.o : main.c defs.h
547         cc -c main.c
548 kbd.o : kbd.c defs.h command.h
549         cc -c kbd.c
550 command.o : command.c defs.h command.h
551         cc -c command.c
552 display.o : display.c defs.h buffer.h
553         cc -c display.c
554 insert.o : insert.c defs.h buffer.h
555         cc -c insert.c
556 search.o : search.c defs.h buffer.h
557         cc -c search.c
558 files.o : files.c defs.h buffer.h command.h
559         cc -c files.c
560 utils.o : utils.c defs.h
561         cc -c utils.c
562 clean :
563         rm edit main.o kbd.o command.o display.o \
564            insert.o search.o files.o utils.o
565 @end group
566 @end example
568 @noindent
569 We split each long line into two lines using backslash-newline; this is
570 like using one long line, but is easier to read.
571 @cindex continuation lines
572 @cindex @code{\} (backslash), for continuation lines
573 @cindex backslash (@code{\}), for continuation lines
574 @cindex quoting newline, in makefile
575 @cindex newline, quoting, in makefile
577 To use this makefile to create the executable file called @file{edit},
578 type:
580 @example
581 make
582 @end example
584 To use this makefile to delete the executable file and all the object
585 files from the directory, type:
587 @example
588 make clean
589 @end example
591 In the example makefile, the targets include the executable file
592 @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}.  The
593 dependencies are files such as @samp{main.c} and @samp{defs.h}.
594 In fact, each @samp{.o} file is both a target and a dependency.
595 Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
597 When a target is a file, it needs to be recompiled or relinked if any
598 of its dependencies change.  In addition, any dependencies that are
599 themselves automatically generated should be updated first.  In this
600 example, @file{edit} depends on each of the eight object files; the
601 object file @file{main.o} depends on the source file @file{main.c} and
602 on the header file @file{defs.h}.
604 A shell command follows each line that contains a target and
605 dependencies.  These shell commands say how to update the target file.
606 A tab character must come at the beginning of every command line to
607 distinguish commands lines from other lines in the makefile.  (Bear in
608 mind that @code{make} does not know anything about how the commands
609 work.  It is up to you to supply commands that will update the target
610 file properly.  All @code{make} does is execute the commands in the rule
611 you have specified when the target file needs to be updated.)
612 @cindex shell command
614 The target @samp{clean} is not a file, but merely the name of an
615 action.  Since you
616 normally
617 do not want to carry out the actions in this rule, @samp{clean} is not a dependency of any other rule.
618 Consequently, @code{make} never does anything with it unless you tell
619 it specifically.  Note that this rule not only is not a dependency, it
620 also does not have any dependencies, so the only purpose of the rule
621 is to run the specified commands.  Targets that do not refer to files
622 but are just actions are called @dfn{phony targets}.  @xref{Phony
623 Targets}, for information about this kind of target.  @xref{Errors, ,
624 Errors in Commands}, to see how to cause @code{make} to ignore errors
625 from @code{rm} or any other command.
626 @cindex @code{clean} target
627 @cindex @code{rm} (shell command)
629 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
630 @comment  node-name,  next,  previous,  up
631 @section How @code{make} Processes a Makefile
632 @cindex processing a makefile
633 @cindex makefile, how @code{make} processes
635 By default, @code{make} starts with the first target (not targets whose
636 names start with @samp{.}).  This is called the @dfn{default goal}.
637 (@dfn{Goals} are the targets that @code{make} strives ultimately to
638 update.  @xref{Goals, , Arguments to Specify the Goals}.)
639 @cindex default goal
640 @cindex goal, default
641 @cindex goal
643 In the simple example of the previous section, the default goal is to
644 update the executable program @file{edit}; therefore, we put that rule
645 first.
647 Thus, when you give the command:
649 @example
650 make
651 @end example
653 @noindent
654 @code{make} reads the makefile in the current directory and begins by
655 processing the first rule.  In the example, this rule is for relinking
656 @file{edit}; but before @code{make} can fully process this rule, it
657 must process the rules for the files that @file{edit} depends on,
658 which in this case are the object files.  Each of these files is
659 processed according to its own rule.  These rules say to update each
660 @samp{.o} file by compiling its source file.  The recompilation must
661 be done if the source file, or any of the header files named as
662 dependencies, is more recent than the object file, or if the object
663 file does not exist.
665 The other rules are processed because their targets appear as
666 dependencies of the goal.  If some other rule is not depended on by the
667 goal (or anything it depends on, etc.), that rule is not processed,
668 unless you tell @code{make} to do so (with a command such as
669 @w{@code{make clean}}).
671 Before recompiling an object file, @code{make} considers updating its
672 dependencies, the source file and header files.  This makefile does not
673 specify anything to be done for them---the @samp{.c} and @samp{.h} files
674 are not the targets of any rules---so @code{make} does nothing for these
675 files.  But @code{make} would update automatically generated C programs,
676 such as those made by Bison or Yacc, by their own rules at this time.
678 After recompiling whichever object files need it, @code{make} decides
679 whether to relink @file{edit}.  This must be done if the file
680 @file{edit} does not exist, or if any of the object files are newer than
681 it.  If an object file was just recompiled, it is now newer than
682 @file{edit}, so @file{edit} is relinked.
683 @cindex relinking
685 Thus, if we change the file @file{insert.c} and run @code{make},
686 @code{make} will compile that file to update @file{insert.o}, and then
687 link @file{edit}.  If we change the file @file{command.h} and run
688 @code{make}, @code{make} will recompile the object files @file{kbd.o},
689 @file{command.o} and @file{files.o} and then link the file @file{edit}.
691 @node Variables Simplify, make Deduces, How Make Works, Introduction
692 @section Variables Make Makefiles Simpler
693 @cindex variables
694 @cindex simplifying with variables
696 In our example, we had to list all the object files twice in the rule for
697 @file{edit} (repeated here):
699 @example
700 @group
701 edit : main.o kbd.o command.o display.o \
702               insert.o search.o files.o utils.o
703         cc -o edit main.o kbd.o command.o display.o \
704                    insert.o search.o files.o utils.o
705 @end group
706 @end example
708 @cindex @code{objects}
709 Such duplication is error-prone; if a new object file is added to the
710 system, we might add it to one list and forget the other.  We can eliminate
711 the risk and simplify the makefile by using a variable.  @dfn{Variables}
712 allow a text string to be defined once and substituted in multiple places
713 later (@pxref{Using Variables, ,How to Use Variables}).
715 @cindex @code{OBJECTS}
716 @cindex @code{objs}
717 @cindex @code{OBJS}
718 @cindex @code{obj}
719 @cindex @code{OBJ}
720 It is standard practice for every makefile to have a variable named
721 @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
722 or @code{OBJ} which is a list of all object file names.  We would
723 define such a variable @code{objects} with a line like this in the
724 makefile:@refill
726 @example
727 @group
728 objects = main.o kbd.o command.o display.o \
729           insert.o search.o files.o utils.o
730 @end group
731 @end example
733 @noindent
734 Then, each place we want to put a list of the object file names, we can
735 substitute the variable's value by writing @samp{$(objects)}
736 (@pxref{Using Variables, ,How to Use Variables}).
738 Here is how the complete simple makefile looks when you use a variable
739 for the object files:
741 @example
742 @group
743 objects = main.o kbd.o command.o display.o \
744           insert.o search.o files.o utils.o
746 edit : $(objects)
747         cc -o edit $(objects)
748 main.o : main.c defs.h
749         cc -c main.c
750 kbd.o : kbd.c defs.h command.h
751         cc -c kbd.c
752 command.o : command.c defs.h command.h
753         cc -c command.c
754 display.o : display.c defs.h buffer.h
755         cc -c display.c
756 insert.o : insert.c defs.h buffer.h
757         cc -c insert.c
758 search.o : search.c defs.h buffer.h
759         cc -c search.c
760 files.o : files.c defs.h buffer.h command.h
761         cc -c files.c
762 utils.o : utils.c defs.h
763         cc -c utils.c
764 clean :
765         rm edit $(objects)
766 @end group
767 @end example
769 @node make Deduces, Combine By Dependency, Variables Simplify, Introduction
770 @section Letting @code{make} Deduce the Commands
771 @cindex deducing commands (implicit rules)
772 @cindex implicit rule, introduction to
773 @cindex rule, implicit, introduction to
775 It is not necessary to spell out the commands for compiling the individual
776 C source files, because @code{make} can figure them out: it has an
777 @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
778 named @samp{.c} file using a @samp{cc -c} command.  For example, it will
779 use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
780 @file{main.o}.  We can therefore omit the commands from the rules for the
781 object files.  @xref{Implicit Rules, ,Using Implicit Rules}.@refill
783 When a @samp{.c} file is used automatically in this way, it is also
784 automatically added to the list of dependencies.  We can therefore omit
785 the @samp{.c} files from the dependencies, provided we omit the commands.
787 Here is the entire example, with both of these changes, and a variable
788 @code{objects} as suggested above:
790 @example
791 @group
792 objects = main.o kbd.o command.o display.o \
793           insert.o search.o files.o utils.o
795 edit : $(objects)
796         cc -o edit $(objects)
798 main.o : defs.h
799 kbd.o : defs.h command.h
800 command.o : defs.h command.h
801 display.o : defs.h buffer.h
802 insert.o : defs.h buffer.h
803 search.o : defs.h buffer.h
804 files.o : defs.h buffer.h command.h
805 utils.o : defs.h
807 .PHONY : clean
808 clean :
809         -rm edit $(objects)
810 @end group
811 @end example
813 @noindent
814 This is how we would write the makefile in actual practice.  (The
815 complications associated with @samp{clean} are described elsewhere.
816 See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
818 Because implicit rules are so convenient, they are important.  You
819 will see them used frequently.@refill
821 @node Combine By Dependency, Cleanup, make Deduces, Introduction
822 @section Another Style of Makefile
823 @cindex combining rules by dependency
825 When the objects of a makefile are created only by implicit rules, an
826 alternative style of makefile is possible.  In this style of makefile,
827 you group entries by their dependencies instead of by their targets.
828 Here is what one looks like:
830 @example
831 @group
832 objects = main.o kbd.o command.o display.o \
833           insert.o search.o files.o utils.o
835 edit : $(objects)
836         cc -o edit $(objects)
838 $(objects) : defs.h
839 kbd.o command.o files.o : command.h
840 display.o insert.o search.o files.o : buffer.h
841 @end group
842 @end example
844 @noindent
845 Here @file{defs.h} is given as a dependency of all the object files;
846 @file{command.h} and @file{buffer.h} are dependencies of the specific
847 object files listed for them.
849 Whether this is better is a matter of taste: it is more compact, but some
850 people dislike it because they find it clearer to put all the information
851 about each target in one place.
853 @node Cleanup,  , Combine By Dependency, Introduction
854 @section Rules for Cleaning the Directory
855 @cindex cleaning up
856 @cindex removing, to clean up
858 Compiling a program is not the only thing you might want to write rules
859 for.  Makefiles commonly tell how to do a few other things besides
860 compiling a program: for example, how to delete all the object files
861 and executables so that the directory is @samp{clean}.
863 @cindex @code{clean} target
864 Here is how we
865 could write a @code{make} rule for cleaning our example editor:
867 @example
868 @group
869 clean:
870         rm edit $(objects)
871 @end group
872 @end example
874 In practice, we might want to write the rule in a somewhat more
875 complicated manner to handle unanticipated situations.  We would do this:
877 @example
878 @group
879 .PHONY : clean
880 clean :
881         -rm edit $(objects)
882 @end group
883 @end example
885 @noindent
886 This prevents @code{make} from getting confused by an actual file
887 called @file{clean} and causes it to continue in spite of errors from
888 @code{rm}.  (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
889 Commands}.)
891 @noindent
892 A rule such as this should not be placed at the beginning of the
893 makefile, because we do not want it to run by default!  Thus, in the
894 example makefile, we want the rule for @code{edit}, which recompiles
895 the editor, to remain the default goal.
897 Since @code{clean} is not a dependency of @code{edit}, this rule will not
898 run at all if we give the command @samp{make} with no arguments.  In
899 order to make the rule run, we have to type @samp{make clean}.
900 @xref{Running, ,How to Run @code{make}}.
902 @node Makefiles, Rules, Introduction, Top
903 @chapter Writing Makefiles
905 @cindex makefile, how to write
906 The information that tells @code{make} how to recompile a system comes from
907 reading a data base called the @dfn{makefile}.
909 @menu
910 * Makefile Contents::           What makefiles contain.
911 * Makefile Names::              How to name your makefile.
912 * Include::                     How one makefile can use another makefile.
913 * MAKEFILES Variable::          The environment can specify extra makefiles.
914 * Remaking Makefiles::          How makefiles get remade.
915 * Overriding Makefiles::        How to override part of one makefile
916                                  with another makefile.
917 @end menu
919 @node Makefile Contents, Makefile Names,  , Makefiles
920 @section What Makefiles Contain
922 Makefiles contain five kinds of things: @dfn{explicit rules},
923 @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
924 and @dfn{comments}.  Rules, variables, and directives are described at
925 length in later chapters.@refill
927 @itemize @bullet
928 @cindex rule, explicit, definition of
929 @cindex explicit rule, definition of
930 @item
931 An @dfn{explicit rule} says when and how to remake one or more files,
932 called the rule's targets.  It lists the other files that the targets
933 @dfn{depend on}, and may also give commands to use to create or update
934 the targets.  @xref{Rules, ,Writing Rules}.
936 @cindex rule, implicit, definition of
937 @cindex implicit rule, definition of
938 @item
939 An @dfn{implicit rule} says when and how to remake a class of files
940 based on their names.  It describes how a target may depend on a file
941 with a name similar to the target and gives commands to create or
942 update such a target.  @xref{Implicit Rules, ,Using Implicit Rules}.
944 @cindex variable definition
945 @item
946 A @dfn{variable definition} is a line that specifies a text string
947 value for a variable that can be substituted into the text later.  The
948 simple makefile example shows a variable definition for @code{objects}
949 as a list of all object files (@pxref{Variables Simplify, , Variables
950 Make Makefiles Simpler}).
952 @cindex directive
953 @item
954 A @dfn{directive} is a command for @code{make} to do something special while
955 reading the makefile.  These include:
957 @itemize @bullet
958 @item
959 Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
961 @item
962 Deciding (based on the values of variables) whether to use or
963 ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
965 @item
966 Defining a variable from a verbatim string containing multiple lines
967 (@pxref{Defining, ,Defining Variables Verbatim}).
968 @end itemize
970 @cindex comments, in makefile
971 @cindex @code{#} (comments), in makefile
972 @item
973 @samp{#} in a line of a makefile starts a @dfn{comment}.  It and the rest of
974 the line are ignored, except that a trailing backslash not escaped by
975 another backslash will continue the comment across multiple lines.
976 Comments may appear on any of the lines in the makefile, except within a
977 @code{define} directive, and perhaps within commands (where the shell
978 decides what is a comment).  A line containing just a comment (with
979 perhaps spaces before it) is effectively blank, and is ignored.@refill
980 @end itemize
982 @node Makefile Names, Include, Makefile Contents, Makefiles
983 @section What Name to Give Your Makefile
984 @cindex makefile name
985 @cindex name of makefile
986 @cindex default makefile name
987 @cindex file name of makefile
989 @c following paragraph rewritten to avoid overfull hbox
990 By default, when @code{make} looks for the makefile, it tries the
991 following names, in order: @file{GNUmakefile}, @file{makefile}
992 and @file{Makefile}.@refill
993 @findex Makefile
994 @findex GNUmakefile
995 @findex makefile
997 @cindex @code{README}
998 Normally you should call your makefile either @file{makefile} or
999 @file{Makefile}.  (We recommend @file{Makefile} because it appears
1000 prominently near the beginning of a directory listing, right near other
1001 important files such as @file{README}.)  The first name checked,
1002 @file{GNUmakefile}, is not recommended for most makefiles.  You should
1003 use this name if you have a makefile that is specific to GNU
1004 @code{make}, and will not be understood by other versions of
1005 @code{make}.  Other @code{make} programs look for @file{makefile} and
1006 @file{Makefile}, but not @file{GNUmakefile}.
1008 If @code{make} finds none of these names, it does not use any makefile.
1009 Then you must specify a goal with a command argument, and @code{make}
1010 will attempt to figure out how to remake it using only its built-in
1011 implicit rules.  @xref{Implicit Rules, ,Using Implicit Rules}.
1013 @cindex @code{-f}
1014 @cindex @code{--file}
1015 @cindex @code{--makefile}
1016 If you want to use a nonstandard name for your makefile, you can specify
1017 the makefile name with the @samp{-f} or @samp{--file} option.  The
1018 arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1019 @code{make} to read the file @var{name} as the makefile.  If you use
1020 more than one @samp{-f} or @samp{--file} option, you can specify several
1021 makefiles.  All the makefiles are effectively concatenated in the order
1022 specified.  The default makefile names @file{GNUmakefile},
1023 @file{makefile} and @file{Makefile} are not checked automatically if you
1024 specify @samp{-f} or @samp{--file}.@refill
1025 @cindex specifying makefile name
1026 @cindex makefile name, how to specify
1027 @cindex name of makefile, how to specify
1028 @cindex file name of makefile, how to specify
1030 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
1031 @section Including Other Makefiles
1032 @cindex including other makefiles
1033 @cindex makefile, including
1035 @findex include
1036 The @code{include} directive tells @code{make} to suspend reading the
1037 current makefile and read one or more other makefiles before continuing.
1038 The directive is a line in the makefile that looks like this:
1040 @example
1041 include @var{filenames}@dots{}
1042 @end example
1044 @noindent
1045 @var{filenames} can contain shell file name patterns.
1046 @cindex shell file name pattern (in @code{include})
1047 @cindex shell wildcards (in @code{include})
1048 @cindex wildcard, in @code{include}
1050 Extra spaces are allowed and ignored at the beginning of the line, but
1051 a tab is not allowed.  (If the line begins with a tab, it will be
1052 considered a command line.)  Whitespace is required between
1053 @code{include} and the file names, and between file names; extra
1054 whitespace is ignored there and at the end of the directive.  A
1055 comment starting with @samp{#} is allowed at the end of the line.  If
1056 the file names contain any variable or function references, they are
1057 expanded.  @xref{Using Variables, ,How to Use Variables}.
1059 For example, if you have three @file{.mk} files, @file{a.mk},
1060 @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1061 @code{bish bash}, then the following expression
1063 @example
1064 include foo *.mk $(bar)
1065 @end example
1067 is equivalent to
1069 @example
1070 include foo a.mk b.mk c.mk bish bash
1071 @end example
1073 When @code{make} processes an @code{include} directive, it suspends
1074 reading of the containing makefile and reads from each listed file in
1075 turn.  When that is finished, @code{make} resumes reading the
1076 makefile in which the directive appears.
1078 One occasion for using @code{include} directives is when several programs,
1079 handled by individual makefiles in various directories, need to use a
1080 common set of variable definitions
1081 (@pxref{Setting, ,Setting Variables}) or pattern rules
1082 (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1084 Another such occasion is when you want to generate dependencies from
1085 source files automatically; the dependencies can be put in a file that
1086 is included by the main makefile.  This practice is generally cleaner
1087 than that of somehow appending the dependencies to the end of the main
1088 makefile as has been traditionally done with other versions of
1089 @code{make}.  @xref{Automatic Dependencies}.
1090 @cindex dependencies, automatic generation
1091 @cindex automatic generation of dependencies
1092 @cindex generating dependencies automatically
1094 @cindex @code{-I}
1095 @cindex @code{--include-dir}
1096 @findex /usr/gnu/include
1097 @findex /usr/local/include
1098 @findex /usr/include
1099 If the specified name does not start with a slash, and the file is not
1100 found in the current directory, several other directories are searched.
1101 First, any directories you have specified with the @samp{-I} or
1102 @samp{--include-dir} option are searched
1103 (@pxref{Options Summary, ,Summary of Options}).
1104 Then the following directories (if they exist)
1105 are searched, in this order:
1106 @file{@var{prefix}/include} (normally @file{/usr/local/include})
1107 @file{/usr/gnu/include},
1108 @file{/usr/local/include}, @file{/usr/include}.
1110 If an included makefile cannot be found in any of these directories, a
1111 warning message is generated, but it is not an immediately fatal error;
1112 processing of the makefile containing the @code{include} continues.
1113 Once it has finished reading makefiles, @code{make} will try to remake
1114 any that are out of date or don't exist.
1115 @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1116 Only after it has tried to find a way to remake a makefile and failed,
1117 will @code{make} diagnose the missing makefile as a fatal error.
1119 If you want @code{make} to simply ignore a makefile which does not exist
1120 and cannot be remade, with no error message, use the @w{@code{-include}}
1121 directive instead of @code{include}, like this:
1123 @example
1124 -include @var{filenames}@dots{}
1125 @end example
1127 This is acts like @code{include} in every way except that there is no
1128 error (not even a warning) if any of the @var{filenames} do not exist.
1129 For compatibility with some other @code{make} implementations,
1130 @code{sinclude} is another name for @w{@code{-include}}.
1132 @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
1133 @section The Variable @code{MAKEFILES}
1134 @cindex makefile, and @code{MAKEFILES} variable
1135 @cindex including (@code{MAKEFILES} variable)
1137 @vindex MAKEFILES
1138 If the environment variable @code{MAKEFILES} is defined, @code{make}
1139 considers its value as a list of names (separated by whitespace) of
1140 additional makefiles to be read before the others.  This works much like
1141 the @code{include} directive: various directories are searched for those
1142 files (@pxref{Include, ,Including Other Makefiles}).  In addition, the
1143 default goal is never taken from one of these makefiles and it is not an
1144 error if the files listed in @code{MAKEFILES} are not found.@refill
1146 @cindex recursion, and @code{MAKEFILES} variable
1147 The main use of @code{MAKEFILES} is in communication between recursive
1148 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1149 @code{make}}).  It usually is not desirable to set the environment
1150 variable before a top-level invocation of @code{make}, because it is
1151 usually better not to mess with a makefile from outside.  However, if
1152 you are running @code{make} without a specific makefile, a makefile in
1153 @code{MAKEFILES} can do useful things to help the built-in implicit
1154 rules work better, such as defining search paths (@pxref{Directory Search}).
1156 Some users are tempted to set @code{MAKEFILES} in the environment
1157 automatically on login, and program makefiles to expect this to be done.
1158 This is a very bad idea, because such makefiles will fail to work if run by
1159 anyone else.  It is much better to write explicit @code{include} directives
1160 in the makefiles.  @xref{Include, , Including Other Makefiles}.
1162 @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles
1163 @section How Makefiles Are Remade
1165 @cindex updating makefiles
1166 @cindex remaking makefiles
1167 @cindex makefile, remaking of
1168 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1169 files.  If a makefile can be remade from other files, you probably want
1170 @code{make} to get an up-to-date version of the makefile to read in.
1172 To this end, after reading in all makefiles, @code{make} will consider
1173 each as a goal target and attempt to update it.  If a makefile has a
1174 rule which says how to update it (found either in that very makefile or
1175 in another one) or if an implicit rule applies to it (@pxref{Implicit
1176 Rules, ,Using Implicit Rules}), it will be updated if necessary.  After
1177 all makefiles have been checked, if any have actually been changed,
1178 @code{make} starts with a clean slate and reads all the makefiles over
1179 again.  (It will also attempt to update each of them over again, but
1180 normally this will not change them again, since they are already up to
1181 date.)@refill
1183 If the makefiles specify a double-colon rule to remake a file with
1184 commands but no dependencies, that file will always be remade
1185 (@pxref{Double-Colon}).  In the case of makefiles, a makefile that has a
1186 double-colon rule with commands but no dependencies will be remade every
1187 time @code{make} is run, and then again after @code{make} starts over
1188 and reads the makefiles in again.  This would cause an infinite loop:
1189 @code{make} would constantly remake the makefile, and never do anything
1190 else.  So, to avoid this, @code{make} will @strong{not} attempt to
1191 remake makefiles which are specified as double-colon targets but have no
1192 dependencies.@refill
1194 If you do not specify any makefiles to be read with @samp{-f} or
1195 @samp{--file} options, @code{make} will try the default makefile names;
1196 @pxref{Makefile Names, ,What Name to Give Your Makefile}.  Unlike
1197 makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1198 @code{make} is not certain that these makefiles should exist.  However,
1199 if a default makefile does not exist but can be created by running
1200 @code{make} rules, you probably want the rules to be run so that the
1201 makefile can be used.
1203 Therefore, if none of the default makefiles exists, @code{make} will try
1204 to make each of them in the same order in which they are searched for
1205 (@pxref{Makefile Names, ,What Name to Give Your Makefile})
1206 until it succeeds in making one, or it runs out of names to try.  Note
1207 that it is not an error if @code{make} cannot find or make any makefile;
1208 a makefile is not always necessary.@refill
1210 When you use the @samp{-t} or @samp{--touch} option
1211 (@pxref{Instead of Execution, ,Instead of Executing the Commands}),
1212 you would not want to use an out-of-date makefile to decide which
1213 targets to touch.  So the @samp{-t} option has no effect on updating
1214 makefiles; they are really updated even if @samp{-t} is specified.
1215 Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1216 @samp{--just-print}) do not prevent updating of makefiles, because an
1217 out-of-date makefile would result in the wrong output for other targets.
1218 Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1219 and then print the commands to update @file{foo} and its dependencies
1220 without running them.  The commands printed for @file{foo} will be those
1221 specified in the updated contents of @file{mfile}.
1223 However, on occasion you might actually wish to prevent updating of even
1224 the makefiles.  You can do this by specifying the makefiles as goals in
1225 the command line as well as specifying them as makefiles.  When the
1226 makefile name is specified explicitly as a goal, the options @samp{-t}
1227 and so on do apply to them.
1229 Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1230 @file{mfile}, print the commands needed to update it without actually
1231 running them, and then print the commands needed to update @file{foo}
1232 without running them.  The commands for @file{foo} will be those
1233 specified by the existing contents of @file{mfile}.
1235 @node Overriding Makefiles,  , Remaking Makefiles, Makefiles
1236 @section Overriding Part of Another Makefile
1238 @cindex overriding makefiles
1239 @cindex makefile, overriding
1240 Sometimes it is useful to have a makefile that is mostly just like
1241 another makefile.  You can often use the @samp{include} directive to
1242 include one in the other, and add more targets or variable definitions.
1243 However, if the two makefiles give different commands for the same
1244 target, @code{make} will not let you just do this.  But there is another way.
1246 @cindex match-anything rule, used to override
1247 In the containing makefile (the one that wants to include the other),
1248 you can use a match-anything pattern rule to say that to remake any
1249 target that cannot be made from the information in the containing
1250 makefile, @code{make} should look in another makefile.
1251 @xref{Pattern Rules}, for more information on pattern rules.
1253 For example, if you have a makefile called @file{Makefile} that says how
1254 to make the target @samp{foo} (and other targets), you can write a
1255 makefile called @file{GNUmakefile} that contains:
1257 @example
1258 foo:
1259         frobnicate > foo
1261 %: force
1262         @@$(MAKE) -f Makefile $@@
1263 force: ;
1264 @end example
1266 If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1267 read it, and see that to make @file{foo}, it needs to run the command
1268 @samp{frobnicate > foo}.  If you say @samp{make bar}, @code{make} will
1269 find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1270 commands from the pattern rule: @samp{make -f Makefile bar}.  If
1271 @file{Makefile} provides a rule for updating @file{bar}, @code{make}
1272 will apply the rule.  And likewise for any other target that
1273 @file{GNUmakefile} does not say how to make.
1275 The way this works is that the pattern rule has a pattern of just
1276 @samp{%}, so it matches any target whatever.  The rule specifies a
1277 dependency @file{force}, to guarantee that the commands will be run even
1278 if the target file already exists.  We give @file{force} target empty
1279 commands to prevent @code{make} from searching for an implicit rule to
1280 build it---otherwise it would apply the same match-anything rule to
1281 @file{force} itself and create a dependency loop!
1283 @node Rules, Commands, Makefiles, Top
1284 @chapter Writing Rules
1285 @cindex writing rules
1286 @cindex rule, how to write
1287 @cindex target
1288 @cindex dependency
1290 A @dfn{rule} appears in the makefile and says when and how to remake
1291 certain files, called the rule's @dfn{targets} (most often only one per rule).
1292 It lists the other files that are the @dfn{dependencies} of the target, and
1293 @dfn{commands} to use to create or update the target.
1295 @cindex default goal
1296 @cindex goal, default
1297 The order of rules is not significant, except for determining the
1298 @dfn{default goal}: the target for @code{make} to consider, if you do
1299 not otherwise specify one.  The default goal is the target of the first
1300 rule in the first makefile.  If the first rule has multiple targets,
1301 only the first target is taken as the default.  There are two
1302 exceptions: a target starting with a period is not a default unless it
1303 contains one or more slashes, @samp{/}, as well; and, a target that
1304 defines a pattern rule has no effect on the default goal.
1305 (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1307 Therefore, we usually write the makefile so that the first rule is the
1308 one for compiling the entire program or all the programs described by
1309 the makefile (often with a target called @samp{all}).
1310 @xref{Goals, ,Arguments to Specify the Goals}.
1312 @menu
1313 * Rule Example::                An example explained.
1314 * Rule Syntax::                 General syntax explained.
1315 * Wildcards::                   Using wildcard characters such as `*'.
1316 * Directory Search::            Searching other directories for source files.
1317 * Phony Targets::               Using a target that is not a real file's name.
1318 * Force Targets::               You can use a target without commands
1319                                   or dependencies to mark other
1320                                   targets as phony.
1321 * Empty Targets::               When only the date matters and the
1322                                   files are empty.
1323 * Special Targets::             Targets with special built-in meanings.
1324 * Multiple Targets::            When to make use of several targets in a rule.
1325 * Multiple Rules::              How to use several rules with the same target.
1326 * Static Pattern::              Static pattern rules apply to multiple targets
1327                                   and can vary the dependencies according to
1328                                   the target name.
1329 * Double-Colon::                How to use a special kind of rule to allow
1330                                   several independent rules for one target.
1331 * Automatic Dependencies::      How to automatically generate rules giving
1332                                  dependencies from the source files themselves.
1333 @end menu
1335 @ifinfo
1336 @node Rule Example, Rule Syntax,  , Rules
1337 @section Rule Example
1339 Here is an example of a rule:
1341 @example
1342 foo.o : foo.c defs.h       # module for twiddling the frobs
1343         cc -c -g foo.c
1344 @end example
1346 Its target is @file{foo.o} and its dependencies are @file{foo.c} and
1347 @file{defs.h}.  It has one command, which is @samp{cc -c -g foo.c}.
1348 The command line starts with a tab to identify it as a command.
1350 This rule says two things:
1352 @itemize @bullet
1353 @item
1354 How to decide whether @file{foo.o} is out of date: it is out of date
1355 if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1356 more recent than it.
1358 @item
1359 How to update the file @file{foo.o}: by running @code{cc} as stated.
1360 The command does not explicitly mention @file{defs.h}, but we presume
1361 that @file{foo.c} includes it, and that that is why @file{defs.h} was
1362 added to the dependencies.
1363 @end itemize
1364 @end ifinfo
1366 @node Rule Syntax, Wildcards, Rule Example, Rules
1367 @section Rule Syntax
1369 @cindex rule syntax
1370 @cindex syntax of rules
1371 In general, a rule looks like this:
1373 @example
1374 @var{targets} : @var{dependencies}
1375         @var{command}
1376         @dots{}
1377 @end example
1379 @noindent
1380 or like this:
1382 @example
1383 @var{targets} : @var{dependencies} ; @var{command}
1384         @var{command}
1385         @dots{}
1386 @end example
1388 @cindex targets
1389 @cindex rule targets
1390 The @var{targets} are file names, separated by spaces.  Wildcard
1391 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1392 in File Names}) and a name of the form @file{@var{a}(@var{m})}
1393 represents member @var{m} in archive file @var{a}
1394 (@pxref{Archive Members, ,Archive Members as Targets}).
1395 Usually there is only one
1396 target per rule, but occasionally there is a reason to have more
1397 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1399 @cindex commands
1400 @cindex tab character (in commands)
1401 The @var{command} lines start with a tab character.  The first command may
1402 appear on the line after the dependencies, with a tab character, or may
1403 appear on the same line, with a semicolon.  Either way, the effect is the
1404 same.  @xref{Commands, ,Writing the Commands in Rules}.
1406 @cindex dollar sign (@code{$}), in rules
1407 @cindex @code{$}, in rules
1408 @cindex rule, and @code{$}
1409 Because dollar signs are used to start variable references, if you really
1410 want a dollar sign in a rule you must write two of them, @samp{$$}
1411 (@pxref{Using Variables, ,How to Use Variables}).
1412 You may split a long line by inserting a backslash
1413 followed by a newline, but this is not required, as @code{make} places no
1414 limit on the length of a line in a makefile.
1416 A rule tells @code{make} two things: when the targets are out of date,
1417 and how to update them when necessary.
1419 @cindex dependencies
1420 @cindex rule dependencies
1421 The criterion for being out of date is specified in terms of the
1422 @var{dependencies}, which consist of file names separated by spaces.
1423 (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1424 A target is out of date if it does not exist or if it is older than any
1425 of the dependencies (by comparison of last-modification times).  The
1426 idea is that the contents of the target file are computed based on
1427 information in the dependencies, so if any of the dependencies changes,
1428 the contents of the existing target file are no longer necessarily
1429 valid.
1431 How to update is specified by @var{commands}.  These are lines to be
1432 executed by the shell (normally @samp{sh}), but with some extra features
1433 (@pxref{Commands, ,Writing the Commands in Rules}).
1435 @node Wildcards, Directory Search, Rule Syntax, Rules
1436 @section Using Wildcard Characters in File Names
1437 @cindex wildcard
1438 @cindex file name with wildcards
1439 @cindex globbing (wildcards)
1441 @cindex @code{*} (wildcard character)
1442 @cindex @code{?} (wildcard character)
1443 @cindex @code{[@dots{}]} (wildcard characters)
1444 A single file name can specify many files using @dfn{wildcard characters}.
1445 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
1446 @samp{[@dots{}]}, the same as in the Bourne shell.  For example, @file{*.c}
1447 specifies a list of all the files (in the working directory) whose names
1448 end in @samp{.c}.@refill
1450 @cindex @code{~} (tilde)
1451 @cindex tilde (@code{~})
1452 @cindex home directory
1453 The character @samp{~} at the beginning of a file name also has special
1454 significance.  If alone, or followed by a slash, it represents your home
1455 directory.  For example @file{~/bin} expands to @file{/home/you/bin}.
1456 If the @samp{~} is followed by a word, the string represents the home
1457 directory of the user named by that word.  For example @file{~john/bin}
1458 expands to @file{/home/john/bin}.@refill
1460 Wildcard expansion happens automatically in targets, in dependencies,
1461 and in commands (where the shell does the expansion).  In other
1462 contexts, wildcard expansion happens only if you request it explicitly
1463 with the @code{wildcard} function.
1465 The special significance of a wildcard character can be turned off by
1466 preceding it with a backslash.  Thus, @file{foo\*bar} would refer to a
1467 specific file whose name consists of @samp{foo}, an asterisk, and
1468 @samp{bar}.@refill
1470 @menu
1471 * Wildcard Examples::           Several examples
1472 * Wildcard Pitfall::            Problems to avoid.
1473 * Wildcard Function::           How to cause wildcard expansion where
1474                                   it does not normally take place.
1475 @end menu
1477 @node Wildcard Examples, Wildcard Pitfall,  , Wildcards
1478 @subsection Wildcard Examples
1480 Wildcards can be used in the commands of a rule, where they are expanded
1481 by the shell.  For example, here is a rule to delete all the object files:
1483 @example
1484 @group
1485 clean:
1486         rm -f *.o
1487 @end group
1488 @end example
1489 @cindex @code{rm} (shell command)
1491 Wildcards are also useful in the dependencies of a rule.  With the
1492 following rule in the makefile, @samp{make print} will print all the
1493 @samp{.c} files that have changed since the last time you printed them:
1495 @example
1496 print: *.c
1497         lpr -p $?
1498         touch print
1499 @end example
1501 @cindex @code{print} target
1502 @cindex @code{lpr} (shell command)
1503 @cindex @code{touch} (shell command)
1504 @noindent
1505 This rule uses @file{print} as an empty target file; see @ref{Empty
1506 Targets, ,Empty Target Files to Record Events}.  (The automatic variable
1507 @samp{$?} is used to print only those files that have changed; see
1508 @ref{Automatic, ,Automatic Variables}.)@refill
1510 Wildcard expansion does not happen when you define a variable.  Thus, if
1511 you write this:
1513 @example
1514 objects = *.o
1515 @end example
1517 @noindent
1518 then the value of the variable @code{objects} is the actual string
1519 @samp{*.o}.  However, if you use the value of @code{objects} in a target,
1520 dependency or command, wildcard expansion will take place at that time.
1521 To set @code{objects} to the expansion, instead use:
1523 @example
1524 objects := $(wildcard *.o)
1525 @end example
1527 @noindent
1528 @xref{Wildcard Function}.
1530 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
1531 @subsection Pitfalls of Using Wildcards
1532 @cindex wildcard pitfalls
1533 @cindex pitfalls of wildcards
1534 @cindex mistakes with wildcards
1535 @cindex errors with wildcards
1536 @cindex problems with wildcards
1538 Now here is an example of a naive way of using wildcard expansion, that
1539 does not do what you would intend.  Suppose you would like to say that the
1540 executable file @file{foo} is made from all the object files in the
1541 directory, and you write this:
1543 @example
1544 objects = *.o
1546 foo : $(objects)
1547         cc -o foo $(CFLAGS) $(objects)
1548 @end example
1550 @noindent
1551 The value of @code{objects} is the actual string @samp{*.o}.  Wildcard
1552 expansion happens in the rule for @file{foo}, so that each @emph{existing}
1553 @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
1554 necessary.
1556 But what if you delete all the @samp{.o} files?  When a wildcard matches
1557 no files, it is left as it is, so then @file{foo} will depend on the
1558 oddly-named file @file{*.o}.  Since no such file is likely to exist,
1559 @code{make} will give you an error saying it cannot figure out how to
1560 make @file{*.o}.  This is not what you want!
1562 Actually it is possible to obtain the desired result with wildcard
1563 expansion, but you need more sophisticated techniques, including the
1564 @code{wildcard} function and string substitution.
1565 @ifinfo
1566 @xref{Wildcard Function, ,The Function @code{wildcard}}.
1567 @end ifinfo
1568 @iftex
1569 These are described in the following section.
1570 @end iftex
1572 @node Wildcard Function,  , Wildcard Pitfall, Wildcards
1573 @subsection The Function @code{wildcard}
1574 @findex wildcard
1576 Wildcard expansion happens automatically in rules.  But wildcard expansion
1577 does not normally take place when a variable is set, or inside the
1578 arguments of a function.  If you want to do wildcard expansion in such
1579 places, you need to use the @code{wildcard} function, like this:
1581 @example
1582 $(wildcard @var{pattern}@dots{})
1583 @end example
1585 @noindent
1586 This string, used anywhere in a makefile, is replaced by a
1587 space-separated list of names of existing files that match one of the
1588 given file name patterns.  If no existing file name matches a pattern,
1589 then that pattern is omitted from the output of the @code{wildcard}
1590 function.  Note that this is different from how unmatched wildcards
1591 behave in rules, where they are used verbatim rather than ignored
1592 (@pxref{Wildcard Pitfall}).
1594 One use of the @code{wildcard} function is to get a list of all the C source
1595 files in a directory, like this:
1597 @example
1598 $(wildcard *.c)
1599 @end example
1601 We can change the list of C source files into a list of object files by
1602 replacing the @samp{.o} suffix with @samp{.c} in the result, like this:
1604 @example
1605 $(patsubst %.c,%.o,$(wildcard *.c))
1606 @end example
1608 @noindent
1609 (Here we have used another function, @code{patsubst}.
1610 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
1612 Thus, a makefile to compile all C source files in the directory and then
1613 link them together could be written as follows:
1615 @example
1616 objects := $(patsubst %.c,%.o,$(wildcard *.c))
1618 foo : $(objects)
1619         cc -o foo $(objects)
1620 @end example
1622 @noindent
1623 (This takes advantage of the implicit rule for compiling C programs, so
1624 there is no need to write explicit rules for compiling the files.
1625 @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
1626 @samp{:=}, which is a variant of @samp{=}.)
1628 @node Directory Search, Phony Targets, Wildcards, Rules
1629 @section Searching Directories for Dependencies
1630 @vindex VPATH
1631 @findex vpath
1632 @cindex vpath
1633 @cindex search path for dependencies (@code{VPATH})
1634 @cindex directory search (@code{VPATH})
1636 For large systems, it is often desirable to put sources in a separate
1637 directory from the binaries.  The @dfn{directory search} features of
1638 @code{make} facilitate this by searching several directories
1639 automatically to find a dependency.  When you redistribute the files
1640 among directories, you do not need to change the individual rules,
1641 just the search paths.
1643 @menu
1644 * General Search::              Specifying a search path that applies
1645                                   to every dependency.
1646 * Selective Search::            Specifying a search path
1647                                   for a specified class of names.
1648 * Commands/Search::             How to write shell commands that work together
1649                                   with search paths.
1650 * Implicit/Search::             How search paths affect implicit rules.
1651 * Libraries/Search::            Directory search for link libraries.
1652 @end menu
1654 @node General Search, Selective Search,  , Directory Search
1655 @subsection @code{VPATH}: Search Path for All Dependencies
1656 @vindex VPATH
1658 The value of the @code{make} variable @code{VPATH} specifies a list of
1659 directories that @code{make} should search.  Most often, the
1660 directories are expected to contain dependency files that are not in the
1661 current directory; however, @code{VPATH} specifies a search list that
1662 @code{make} applies for all files, including files which are targets of
1663 rules.
1665 Thus, if a file that is listed as a target or dependency does not exist
1666 in the current directory, @code{make} searches the directories listed in
1667 @code{VPATH} for a file with that name.  If a file is found in one of
1668 them, that file becomes the dependency.  Rules may then specify the
1669 names of source files in the dependencies as if they all existed in the
1670 current directory.  @xref{Commands/Search, ,Writing Shell Commands with
1671 Directory Search}.
1673 In the @code{VPATH} variable, directory names are separated by colons or
1674 blanks.  The order in which directories are listed is the order followed
1675 by @code{make} in its search.
1677 For example,
1679 @example
1680 VPATH = src:../headers
1681 @end example
1683 @noindent
1684 specifies a path containing two directories, @file{src} and
1685 @file{../headers}, which @code{make} searches in that order.
1687 With this value of @code{VPATH}, the following rule,
1689 @example
1690 foo.o : foo.c
1691 @end example
1693 @noindent
1694 is interpreted as if it were written like this:
1696 @example
1697 foo.o : src/foo.c
1698 @end example
1700 @noindent
1701 assuming the file @file{foo.c} does not exist in the current directory but
1702 is found in the directory @file{src}.
1704 @node Selective Search, Commands/Search, General Search, Directory Search
1705 @subsection The @code{vpath} Directive
1706 @findex vpath
1708 Similar to the @code{VPATH} variable but more selective is the @code{vpath}
1709 directive (note lower case), which allows you to specify a search path for a particular class
1710 of file names, those that match a particular pattern.  Thus you can supply
1711 certain search directories for one class of file names and other directories
1712 (or none) for other file names.
1714 There are three forms of the @code{vpath} directive:
1716 @table @code
1717 @item vpath @var{pattern} @var{directories}
1718 Specify the search path @var{directories} for file names that match
1719 @var{pattern}.
1721 The search path, @var{directories}, is a list of directories to be
1722 searched, separated by colons or blanks, just like the search path used
1723 in the @code{VPATH} variable.
1725 @item vpath @var{pattern}
1726 Clear out the search path associated with @var{pattern}.
1728 @c Extra blank line makes sure this gets two lines.
1729 @item vpath
1731 Clear all search paths previously specified with @code{vpath} directives.
1732 @end table
1734 A @code{vpath} pattern is a string containing a @samp{%} character.  The
1735 string must match the file name of a dependency that is being searched
1736 for, the @samp{%} character matching any sequence of zero or more
1737 characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
1738 Redefining Pattern Rules}).  For example, @code{%.h} matches files that
1739 end in @code{.h}.  (If there is no @samp{%}, the pattern must match the
1740 dependency exactly, which is not useful very often.)
1742 @cindex @code{%}, quoting in @code{vpath}
1743 @cindex @code{%}, quoting with @code{\} (backslash)
1744 @cindex @code{\} (backslash), to quote @code{%}
1745 @cindex backslash (@code{\}), to quote @code{%}
1746 @cindex quoting @code{%}, in @code{vpath}
1747 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
1748 with preceding backslashes (@samp{\}).  Backslashes that would otherwise
1749 quote @samp{%} characters can be quoted with more backslashes.
1750 Backslashes that quote @samp{%} characters or other backslashes are
1751 removed from the pattern before it is compared to file names.  Backslashes
1752 that are not in danger of quoting @samp{%} characters go unmolested.@refill
1754 When a dependency fails to exist in the current directory, if the
1755 @var{pattern} in a @code{vpath} directive matches the name of the
1756 dependency file, then the @var{directories} in that directive are searched
1757 just like (and before) the directories in the @code{VPATH} variable.
1759 For example,
1761 @example
1762 vpath %.h ../headers
1763 @end example
1765 @noindent
1766 tells @code{make} to look for any dependency whose name ends in @file{.h}
1767 in the directory @file{../headers} if the file is not found in the current
1768 directory.
1770 If several @code{vpath} patterns match the dependency file's name, then
1771 @code{make} processes each matching @code{vpath} directive one by one,
1772 searching all the directories mentioned in each directive.  @code{make}
1773 handles multiple @code{vpath} directives in the order in which they
1774 appear in the makefile; multiple directives with the same pattern are
1775 independent of each other.
1777 @need 750
1778 Thus,
1780 @example
1781 @group
1782 vpath %.c foo
1783 vpath %   blish
1784 vpath %.c bar
1785 @end group
1786 @end example
1788 @noindent
1789 will look for a file ending in @samp{.c} in @file{foo}, then
1790 @file{blish}, then @file{bar}, while
1792 @example
1793 @group
1794 vpath %.c foo:bar
1795 vpath %   blish
1796 @end group
1797 @end example
1799 @noindent
1800 will look for a file ending in @samp{.c} in @file{foo}, then
1801 @file{bar}, then @file{blish}.
1803 @node Commands/Search, Implicit/Search, Selective Search, Directory Search
1804 @subsection Writing Shell Commands with Directory Search
1805 @cindex shell command, and directory search
1806 @cindex directory search (@code{VPATH}), and shell commands
1808 When a dependency is found in another directory through directory search,
1809 this cannot change the commands of the rule; they will execute as written.
1810 Therefore, you must write the commands with care so that they will look for
1811 the dependency in the directory where @code{make} finds it.
1813 This is done with the @dfn{automatic variables} such as @samp{$^}
1814 (@pxref{Automatic, ,Automatic Variables}).
1815 For instance, the value of @samp{$^} is a
1816 list of all the dependencies of the rule, including the names of
1817 the directories in which they were found, and the value of
1818 @samp{$@@} is the target.  Thus:@refill
1820 @example
1821 foo.o : foo.c
1822         cc -c $(CFLAGS) $^ -o $@@
1823 @end example
1825 @noindent
1826 (The variable @code{CFLAGS} exists so you can specify flags for C
1827 compilation by implicit rules; we use it here for consistency so it will
1828 affect all C compilations uniformly;
1829 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
1831 Often the dependencies include header files as well, which you do not
1832 want to mention in the commands.  The automatic variable @samp{$<} is
1833 just the first dependency:
1835 @example
1836 VPATH = src:../headers
1837 foo.o : foo.c defs.h hack.h
1838         cc -c $(CFLAGS) $< -o $@@
1839 @end example
1841 @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
1842 @subsection Directory Search and Implicit Rules
1843 @cindex @code{VPATH}, and implicit rules
1844 @cindex directory search (@code{VPATH}), and implicit rules
1845 @cindex search path for dependencies (@code{VPATH}), and implicit rules
1846 @cindex implicit rule, and directory search
1847 @cindex implicit rule, and @code{VPATH}
1848 @cindex rule, implicit, and directory search
1849 @cindex rule, implicit, and @code{VPATH}
1851 The search through the directories specified in @code{VPATH} or with
1852 @code{vpath} also happens during consideration of implicit rules
1853 (@pxref{Implicit Rules, ,Using Implicit Rules}).
1855 For example, when a file @file{foo.o} has no explicit rule, @code{make}
1856 considers implicit rules, such as the built-in rule to compile
1857 @file{foo.c} if that file exists.  If such a file is lacking in the
1858 current directory, the appropriate directories are searched for it.  If
1859 @file{foo.c} exists (or is mentioned in the makefile) in any of the
1860 directories, the implicit rule for C compilation is applied.
1862 The commands of implicit rules normally use automatic variables as a
1863 matter of necessity; consequently they will use the file names found by
1864 directory search with no extra effort.
1866 @node Libraries/Search,  , Implicit/Search, Directory Search
1867 @subsection Directory Search for Link Libraries
1868 @cindex link libraries, and directory search
1869 @cindex libraries for linking, directory search
1870 @cindex directory search (@code{VPATH}), and link libraries
1871 @cindex @code{VPATH}, and link libraries
1872 @cindex search path for dependencies (@code{VPATH}), and link libraries
1873 @cindex @code{-l} (library search)
1875 Directory search applies in a special way to libraries used with the
1876 linker.  This special feature comes into play when you write a dependency
1877 whose name is of the form @samp{-l@var{name}}.  (You can tell something
1878 strange is going on here because the dependency is normally the name of a
1879 file, and the @emph{file name} of the library looks like
1880 @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
1882 When a dependency's name has the form @samp{-l@var{name}}, @code{make}
1883 handles it specially by searching for the file @file{lib@var{name}.a} in
1884 the current directory, in directories specified by matching @code{vpath}
1885 search paths and the @code{VPATH} search path, and then in the
1886 directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
1887 (normally @file{/usr/local/lib}).
1889 For example,
1891 @example
1892 @group
1893 foo : foo.c -lcurses
1894         cc $^ -o $@@
1895 @end group
1896 @end example
1898 @noindent
1899 would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
1900 be executed when @file{foo} is older than @file{foo.c} or than
1901 @file{/usr/lib/libcurses.a}.@refill
1903 @node Phony Targets, Force Targets, Directory Search, Rules
1904 @section Phony Targets
1905 @cindex phony targets
1906 @cindex targets, phony
1907 @cindex targets without a file
1909 A phony target is one that is not really the name of a file.  It is just a
1910 name for some commands to be executed when you make an explicit request.
1911 There are two reasons to use a phony target: to avoid a conflict with
1912 a file of the same name, and to improve performance.
1914 If you write a rule whose commands will not create the target file, the
1915 commands will be executed every time the target comes up for remaking.
1916 Here is an example:
1918 @example
1919 @group
1920 clean:
1921         rm *.o temp
1922 @end group
1923 @end example
1925 @noindent
1926 Because the @code{rm} command does not create a file named @file{clean},
1927 probably no such file will ever exist.  Therefore, the @code{rm} command
1928 will be executed every time you say @samp{make clean}.
1929 @cindex @code{rm} (shell command)
1931 @findex .PHONY
1932 The phony target will cease to work if anything ever does create a file
1933 named @file{clean} in this directory.  Since it has no dependencies, the
1934 file @file{clean} would inevitably be considered up to date, and its
1935 commands would not be executed.  To avoid this problem, you can explicitly
1936 declare the target to be phony, using the special target @code{.PHONY}
1937 (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
1939 @example
1940 .PHONY : clean
1941 @end example
1943 @noindent
1944 Once this is done, @samp{make clean} will run the commands regardless of
1945 whether there is a file named @file{clean}.
1947 Since it knows that phony targets do not name actual files that could be
1948 remade from other files, @code{make} skips the implicit rule search for
1949 phony targets (@pxref{Implicit Rules}).  This is why declaring a target
1950 phony is good for performance, even if you are not worried about the
1951 actual file existing.
1953 Thus, you first write the line that states that @code{clean} is a
1954 phony target, then you write the rule, like this:
1956 @example
1957 @group
1958 .PHONY: clean
1959 clean:
1960         rm *.o temp
1961 @end group
1962 @end example
1964 A phony target should not be a dependency of a real target file; if it
1965 is, its commands are run every time @code{make} goes to update that
1966 file.  As long as a phony target is never a dependency of a real
1967 target, the phony target commands will be executed only when the phony
1968 target is a specified goal (@pxref{Goals, ,Arguments to Specify the
1969 Goals}).
1971 Phony targets can have dependencies.  When one directory contains multiple
1972 programs, it is most convenient to describe all of the programs in one
1973 makefile @file{./Makefile}.  Since the target remade by default will be the
1974 first one in the makefile, it is common to make this a phony target named
1975 @samp{all} and give it, as dependencies, all the individual programs.  For
1976 example:
1978 @example
1979 all : prog1 prog2 prog3
1980 .PHONY : all
1982 prog1 : prog1.o utils.o
1983         cc -o prog1 prog1.o utils.o
1985 prog2 : prog2.o
1986         cc -o prog2 prog2.o
1988 prog3 : prog3.o sort.o utils.o
1989         cc -o prog3 prog3.o sort.o utils.o
1990 @end example
1992 @noindent
1993 Now you can say just @samp{make} to remake all three programs, or specify
1994 as arguments the ones to remake (as in @samp{make prog1 prog3}).
1996 When one phony target is a dependency of another, it serves as a subroutine
1997 of the other.  For example, here @samp{make cleanall} will delete the
1998 object files, the difference files, and the file @file{program}:
2000 @example
2001 .PHONY: cleanall cleanobj cleandiff
2003 cleanall : cleanobj cleandiff
2004         rm program
2006 cleanobj :
2007         rm *.o
2009 cleandiff :
2010         rm *.diff
2011 @end example
2013 @node Force Targets, Empty Targets, Phony Targets, Rules
2014 @section Rules without Commands or Dependencies
2015 @cindex force targets
2016 @cindex targets, force
2017 @cindex @code{FORCE}
2018 @cindex rule, no commands or dependencies
2020 If a rule has no dependencies or commands, and the target of the rule
2021 is a nonexistent file, then @code{make} imagines this target to have
2022 been updated whenever its rule is run.  This implies that all targets
2023 depending on this one will always have their commands run.
2025 An example will illustrate this:
2027 @example
2028 @group
2029 clean: FORCE
2030         rm $(objects)
2031 FORCE:
2032 @end group
2033 @end example
2035 Here the target @samp{FORCE} satisfies the special conditions, so the
2036 target @file{clean} that depends on it is forced to run its commands.
2037 There is nothing special about the name @samp{FORCE}, but that is one name
2038 commonly used this way.
2040 As you can see, using @samp{FORCE} this way has the same results as using
2041 @samp{.PHONY: clean}.
2043 Using @samp{.PHONY} is more explicit and more efficient.  However,
2044 other versions of @code{make} do not support @samp{.PHONY}; thus
2045 @samp{FORCE} appears in many makefiles.  @xref{Phony Targets}.
2047 @node Empty Targets, Special Targets, Force Targets, Rules
2048 @section Empty Target Files to Record Events
2049 @cindex empty targets
2050 @cindex targets, empty
2051 @cindex recording events with empty targets
2053 The @dfn{empty target} is a variant of the phony target; it is used to hold
2054 commands for an action that you request explicitly from time to time.
2055 Unlike a phony target, this target file can really exist; but the file's
2056 contents do not matter, and usually are empty.
2058 The purpose of the empty target file is to record, with its
2059 last-modification time, when the rule's commands were last executed.  It
2060 does so because one of the commands is a @code{touch} command to update the
2061 target file.
2063 The empty target file must have some dependencies.  When you ask to remake
2064 the empty target, the commands are executed if any dependency is more
2065 recent than the target; in other words, if a dependency has changed since
2066 the last time you remade the target.  Here is an example:
2068 @example
2069 print: foo.c bar.c
2070         lpr -p $?
2071         touch print
2072 @end example
2073 @cindex @code{print} target
2074 @cindex @code{lpr} (shell command)
2075 @cindex @code{touch} (shell command)
2077 @noindent
2078 With this rule, @samp{make print} will execute the @code{lpr} command if
2079 either source file has changed since the last @samp{make print}.  The
2080 automatic variable @samp{$?} is used to print only those files that have
2081 changed (@pxref{Automatic, ,Automatic Variables}).
2083 @node Special Targets, Multiple Targets, Empty Targets, Rules
2084 @section Special Built-in Target Names
2085 @cindex special targets
2086 @cindex built-in special targets
2087 @cindex targets, built-in special
2089 Certain names have special meanings if they appear as targets.
2091 @table @code
2092 @findex .PHONY
2093 @item .PHONY
2095 The dependencies of the special target @code{.PHONY} are considered to
2096 be phony targets.  When it is time to consider such a target,
2097 @code{make} will run its commands unconditionally, regardless of
2098 whether a file with that name exists or what its last-modification
2099 time is.  @xref{Phony Targets, ,Phony Targets}.
2101 @findex .SUFFIXES
2102 @item .SUFFIXES
2104 The dependencies of the special target @code{.SUFFIXES} are the list
2105 of suffixes to be used in checking for suffix rules.
2106 @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2108 @findex .DEFAULT
2109 @item .DEFAULT
2111 The commands specified for @code{.DEFAULT} are used for any target for
2112 which no rules are found (either explicit rules or implicit rules).
2113 @xref{Last Resort}.  If @code{.DEFAULT} commands are specified, every
2114 file mentioned as a dependency, but not as a target in a rule, will have
2115 these commands executed on its behalf.  @xref{Search Algorithm,
2116 ,Implicit Rule Search Algorithm}.
2118 @findex .PRECIOUS
2119 @item .PRECIOUS
2120 @cindex precious targets
2121 @cindex preserving with @code{.PRECIOUS}
2123 The targets which @code{.PRECIOUS} depends on are given the following
2124 special treatment: if @code{make} is killed or interrupted during the
2125 execution of their commands, the target is not deleted.
2126 @xref{Interrupts, ,Interrupting or Killing @code{make}}.
2127 Also, if the target is an intermediate file, it will not be deleted
2128 after it is no longer needed, as is normally done.
2129 @xref{Chained Rules, ,Chains of Implicit Rules}.
2131 You can also list the target pattern of an implicit rule (such as
2132 @samp{%.o}) as a dependency file of the special target @code{.PRECIOUS}
2133 to preserve intermediate files created by rules whose target patterns
2134 match that file's name.
2136 @findex .INTERMEDIATE
2137 @item .INTERMEDIATE
2138 @cindex intermediate targets, explicit
2140 The targets which @code{.INTERMEDIATE} depends on are treated as
2141 intermediate files.  @xref{Chained Rules, ,Chains of Implicit Rules}.
2142 @code{.INTERMEDIATE} with no dependencies marks all file targets
2143 mentioned in the makefile as intermediate.
2145 @findex .SECONDARY
2146 @item .SECONDARY
2147 @cindex secondary targets
2148 @cindex preserving with @code{.SECONDARY}
2150 The targets which @code{.SECONDARY} depends on are treated as
2151 intermediate files, except that they are never automatically deleted.
2152 @xref{Chained Rules, ,Chains of Implicit Rules}.
2154 @code{.SECONDARY} with no dependencies marks all file targets mentioned
2155 in the makefile as secondary.
2157 @findex .IGNORE
2158 @item .IGNORE
2160 If you specify dependencies for @code{.IGNORE}, then @code{make} will
2161 ignore errors in execution of the commands run for those particular
2162 files.  The commands for @code{.IGNORE} are not meaningful.
2164 If mentioned as a target with no dependencies, @code{.IGNORE} says to
2165 ignore errors in execution of commands for all files.  This usage of
2166 @samp{.IGNORE} is supported only for historical compatibility.  Since
2167 this affects every command in the makefile, it is not very useful; we
2168 recommend you use the more selective ways to ignore errors in specific
2169 commands.  @xref{Errors, ,Errors in Commands}.
2171 @findex .SILENT
2172 @item .SILENT
2174 If you specify dependencies for @code{.SILENT}, then @code{make} will
2175 not the print commands to remake those particular files before executing
2176 them.  The commands for @code{.SILENT} are not meaningful.
2178 If mentioned as a target with no dependencies, @code{.SILENT} says not
2179 to print any commands before executing them.  This usage of
2180 @samp{.SILENT} is supported only for historical compatibility.  We
2181 recommend you use the more selective ways to silence specific commands.
2182 @xref{Echoing, ,Command Echoing}.  If you want to silence all commands
2183 for a particular run of @code{make}, use the @samp{-s} or
2184 @w{@samp{--silent}} option (@pxref{Options Summary}).
2186 @findex .EXPORT_ALL_VARIABLES
2187 @item .EXPORT_ALL_VARIABLES
2189 Simply by being mentioned as a target, this tells @code{make} to
2190 export all variables to child processes by default.
2191 @xref{Variables/Recursion, ,Communicating Variables to a
2192 Sub-@code{make}}.
2193 @end table
2195 Any defined implicit rule suffix also counts as a special target if it
2196 appears as a target, and so does the concatenation of two suffixes, such
2197 as @samp{.c.o}.  These targets are suffix rules, an obsolete way of
2198 defining implicit rules (but a way still widely used).  In principle, any
2199 target name could be special in this way if you break it in two and add
2200 both pieces to the suffix list.  In practice, suffixes normally begin with
2201 @samp{.}, so these special target names also begin with @samp{.}.
2202 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
2204 @node Multiple Targets, Multiple Rules, Special Targets, Rules
2205 @section Multiple Targets in a Rule
2206 @cindex multiple targets
2207 @cindex several targets in a rule
2208 @cindex targets, multiple
2209 @cindex rule, with multiple targets
2211 A rule with multiple targets is equivalent to writing many rules, each with
2212 one target, and all identical aside from that.  The same commands apply to
2213 all the targets, but their effects may vary because you can substitute the
2214 actual target name into the command using @samp{$@@}.  The rule contributes
2215 the same dependencies to all the targets also.
2217 This is useful in two cases.
2219 @itemize @bullet
2220 @item
2221 You want just dependencies, no commands.  For example:
2223 @example
2224 kbd.o command.o files.o: command.h
2225 @end example
2227 @noindent
2228 gives an additional dependency to each of the three object files
2229 mentioned.
2231 @item
2232 Similar commands work for all the targets.  The commands do not need
2233 to be absolutely identical, since the automatic variable @samp{$@@}
2234 can be used to substitute the particular target to be remade into the
2235 commands (@pxref{Automatic, ,Automatic Variables}).  For example:
2237 @example
2238 @group
2239 bigoutput littleoutput : text.g
2240         generate text.g -$(subst output,,$@@) > $@@
2241 @end group
2242 @end example
2243 @findex subst
2245 @noindent
2246 is equivalent to
2248 @example
2249 bigoutput : text.g
2250         generate text.g -big > bigoutput
2251 littleoutput : text.g
2252         generate text.g -little > littleoutput
2253 @end example
2255 @noindent
2256 Here we assume the hypothetical program @code{generate} makes two
2257 types of output, one if given @samp{-big} and one if given
2258 @samp{-little}.
2259 @xref{Text Functions, ,Functions for String Substitution and Analysis},
2260 for an explanation of the @code{subst} function.
2261 @end itemize
2263 Suppose you would like to vary the dependencies according to the target,
2264 much as the variable @samp{$@@} allows you to vary the commands.
2265 You cannot do this with multiple targets in an ordinary rule, but you can
2266 do it with a @dfn{static pattern rule}.
2267 @xref{Static Pattern, ,Static Pattern Rules}.
2269 @node Multiple Rules, Static Pattern, Multiple Targets, Rules
2270 @section Multiple Rules for One Target
2271 @cindex multiple rules for one target
2272 @cindex several rules for one target
2273 @cindex rule, multiple for one target
2274 @cindex target, multiple rules for one
2276 One file can be the target of several rules.  All the dependencies
2277 mentioned in all the rules are merged into one list of dependencies for
2278 the target.  If the target is older than any dependency from any rule,
2279 the commands are executed.
2281 There can only be one set of commands to be executed for a file.
2282 If more than one rule gives commands for the same file,
2283 @code{make} uses the last set given and prints an error message.
2284 (As a special case, if the file's name begins with a dot, no
2285 error message is printed.  This odd behavior is only for
2286 compatibility with other implementations of @code{make}.)
2287 There is no reason to
2288 write your makefiles this way; that is why @code{make} gives you
2289 an error message.@refill
2291 An extra rule with just dependencies can be used to give a few extra
2292 dependencies to many files at once.  For example, one usually has a
2293 variable named @code{objects} containing a list of all the compiler output
2294 files in the system being made.  An easy way to say that all of them must
2295 be recompiled if @file{config.h} changes is to write the following:
2297 @example
2298 objects = foo.o bar.o
2299 foo.o : defs.h
2300 bar.o : defs.h test.h
2301 $(objects) : config.h
2302 @end example
2304 This could be inserted or taken out without changing the rules that really
2305 specify how to make the object files, making it a convenient form to use if
2306 you wish to add the additional dependency intermittently.
2308 Another wrinkle is that the additional dependencies could be specified with
2309 a variable that you set with a command argument to @code{make}
2310 (@pxref{Overriding, ,Overriding Variables}).  For example,
2312 @example
2313 @group
2314 extradeps=
2315 $(objects) : $(extradeps)
2316 @end group
2317 @end example
2319 @noindent
2320 means that the command @samp{make extradeps=foo.h} will consider
2321 @file{foo.h} as a dependency of each object file, but plain @samp{make}
2322 will not.
2324 If none of the explicit rules for a target has commands, then @code{make}
2325 searches for an applicable implicit rule to find some commands
2326 @pxref{Implicit Rules, ,Using Implicit Rules}).
2328 @node Static Pattern, Double-Colon, Multiple Rules, Rules
2329 @section Static Pattern Rules
2330 @cindex static pattern rule
2331 @cindex rule, static pattern
2332 @cindex pattern rules, static (not implicit)
2333 @cindex varying dependencies
2334 @cindex dependencies, varying (static pattern)
2336 @dfn{Static pattern rules} are rules which specify multiple targets and
2337 construct the dependency names for each target based on the target name.
2338 They are more general than ordinary rules with multiple targets because the
2339 targets do not have to have identical dependencies.  Their dependencies must
2340 be @emph{analogous}, but not necessarily @emph{identical}.
2342 @menu
2343 * Static Usage::                The syntax of static pattern rules.
2344 * Static versus Implicit::      When are they better than implicit rules?
2345 @end menu
2347 @node Static Usage, Static versus Implicit,  , Static Pattern
2348 @subsection Syntax of Static Pattern Rules
2349 @cindex static pattern rule, syntax of
2350 @cindex pattern rules, static, syntax of
2352 Here is the syntax of a static pattern rule:
2354 @example
2355 @var{targets} @dots{}: @var{target-pattern}: @var{dep-patterns} @dots{}
2356         @var{commands}
2357         @dots{}
2358 @end example
2360 @noindent
2361 The @var{targets} list specifies the targets that the rule applies to.
2362 The targets can contain wildcard characters, just like the targets of
2363 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
2364 Names}).
2366 @cindex target pattern, static (not implicit)
2367 @cindex stem
2368 The @var{target-pattern} and @var{dep-patterns} say how to compute the
2369 dependencies of each target.  Each target is matched against the
2370 @var{target-pattern} to extract a part of the target name, called the
2371 @dfn{stem}.  This stem is substituted into each of the @var{dep-patterns}
2372 to make the dependency names (one from each @var{dep-pattern}).
2374 Each pattern normally contains the character @samp{%} just once.  When the
2375 @var{target-pattern} matches a target, the @samp{%} can match any part of
2376 the target name; this part is called the @dfn{stem}.  The rest of the
2377 pattern must match exactly.  For example, the target @file{foo.o} matches
2378 the pattern @samp{%.o}, with @samp{foo} as the stem.  The targets
2379 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
2381 @cindex dependency pattern, static (not implicit)
2382 The dependency names for each target are made by substituting the stem
2383 for the @samp{%} in each dependency pattern.  For example, if one
2384 dependency pattern is @file{%.c}, then substitution of the stem
2385 @samp{foo} gives the dependency name @file{foo.c}.  It is legitimate
2386 to write a dependency pattern that does not contain @samp{%}; then this
2387 dependency is the same for all targets.
2389 @cindex @code{%}, quoting in static pattern
2390 @cindex @code{%}, quoting with @code{\} (backslash)
2391 @cindex @code{\} (backslash), to quote @code{%}
2392 @cindex backslash (@code{\}), to quote @code{%}
2393 @cindex quoting @code{%}, in static pattern
2394 @samp{%} characters in pattern rules can be quoted with preceding
2395 backslashes (@samp{\}).  Backslashes that would otherwise quote @samp{%}
2396 characters can be quoted with more backslashes.  Backslashes that quote
2397 @samp{%} characters or other backslashes are removed from the pattern
2398 before it is compared to file names or has a stem substituted into it.
2399 Backslashes that are not in danger of quoting @samp{%} characters go
2400 unmolested.  For example, the pattern @file{the\%weird\\%pattern\\} has
2401 @samp{the%weird\} preceding the operative @samp{%} character, and
2402 @samp{pattern\\} following it.  The final two backslashes are left alone
2403 because they cannot affect any @samp{%} character.@refill
2405 Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
2406 from the corresponding @file{.c} file:
2408 @example
2409 @group
2410 objects = foo.o bar.o
2412 $(objects): %.o: %.c
2413         $(CC) -c $(CFLAGS) $< -o $@@
2414 @end group
2415 @end example
2417 @noindent
2418 Here @samp{$<} is the automatic variable that holds the name of the
2419 dependency and @samp{$@@} is the automatic variable that holds the name
2420 of the target; see @ref{Automatic, , Automatic Variables}.
2422 Each target specified must match the target pattern; a warning is issued
2423 for each target that does not.  If you have a list of files, only some of
2424 which will match the pattern, you can use the @code{filter} function to
2425 remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
2427 @example
2428 files = foo.elc bar.o lose.o
2430 $(filter %.o,$(files)): %.o: %.c
2431         $(CC) -c $(CFLAGS) $< -o $@@
2432 $(filter %.elc,$(files)): %.elc: %.el
2433         emacs -f batch-byte-compile $<
2434 @end example
2436 @noindent
2437 In this example the result of @samp{$(filter %.o,$(files))} is
2438 @file{bar.o lose.o}, and the first static pattern rule causes each of
2439 these object files to be updated by compiling the corresponding C source
2440 file.  The result of @w{@samp{$(filter %.elc,$(files))}} is
2441 @file{foo.elc}, so that file is made from @file{foo.el}.@refill
2443 Another example shows how to use @code{$*} in static pattern rules:
2444 @vindex $*@r{, and static pattern}
2446 @example
2447 @group
2448 bigoutput littleoutput : %output : text.g
2449         generate text.g -$* > $@@
2450 @end group
2451 @end example
2453 @noindent
2454 When the @code{generate} command is run, @code{$*} will expand to the
2455 stem, either @samp{big} or @samp{little}.
2457 @node Static versus Implicit,  , Static Usage, Static Pattern
2458 @subsection Static Pattern Rules versus Implicit Rules
2459 @cindex rule, static pattern versus implicit
2460 @cindex static pattern rule, versus implicit
2462 A static pattern rule has much in common with an implicit rule defined as a
2463 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
2464 Both have a pattern for the target and patterns for constructing the
2465 names of dependencies.  The difference is in how @code{make} decides
2466 @emph{when} the rule applies.
2468 An implicit rule @emph{can} apply to any target that matches its pattern,
2469 but it @emph{does} apply only when the target has no commands otherwise
2470 specified, and only when the dependencies can be found.  If more than one
2471 implicit rule appears applicable, only one applies; the choice depends on
2472 the order of rules.
2474 By contrast, a static pattern rule applies to the precise list of targets
2475 that you specify in the rule.  It cannot apply to any other target and it
2476 invariably does apply to each of the targets specified.  If two conflicting
2477 rules apply, and both have commands, that's an error.
2479 The static pattern rule can be better than an implicit rule for these
2480 reasons:
2482 @itemize @bullet
2483 @item
2484 You may wish to override the usual implicit rule for a few
2485 files whose names cannot be categorized syntactically but
2486 can be given in an explicit list.
2488 @item
2489 If you cannot be sure of the precise contents of the directories
2490 you are using, you may not be sure which other irrelevant files
2491 might lead @code{make} to use the wrong implicit rule.  The choice
2492 might depend on the order in which the implicit rule search is done.
2493 With static pattern rules, there is no uncertainty: each rule applies
2494 to precisely the targets specified.
2495 @end itemize
2497 @node Double-Colon, Automatic Dependencies, Static Pattern, Rules
2498 @section Double-Colon Rules
2499 @cindex double-colon rules
2500 @cindex rule, double-colon (@code{::})
2501 @cindex multiple rules for one target (@code{::})
2502 @cindex @code{::} rules (double-colon)
2504 @dfn{Double-colon} rules are rules written with @samp{::} instead of
2505 @samp{:} after the target names.  They are handled differently from
2506 ordinary rules when the same target appears in more than one rule.
2508 When a target appears in multiple rules, all the rules must be the same
2509 type: all ordinary, or all double-colon.  If they are double-colon, each of
2510 them is independent of the others.  Each double-colon rule's commands are
2511 executed if the target is older than any dependencies of that rule.  This
2512 can result in executing none, any, or all of the double-colon rules.
2514 Double-colon rules with the same target are in fact completely separate
2515 from one another.  Each double-colon rule is processed individually, just
2516 as rules with different targets are processed.
2518 The double-colon rules for a target are executed in the order they appear
2519 in the makefile.  However, the cases where double-colon rules really make
2520 sense are those where the order of executing the commands would not matter.
2522 Double-colon rules are somewhat obscure and not often very useful; they
2523 provide a mechanism for cases in which the method used to update a target
2524 differs depending on which dependency files caused the update, and such
2525 cases are rare.
2527 Each double-colon rule should specify commands; if it does not, an
2528 implicit rule will be used if one applies.
2529 @xref{Implicit Rules, ,Using Implicit Rules}.
2531 @node Automatic Dependencies,  , Double-Colon, Rules
2532 @section Generating Dependencies Automatically
2533 @cindex dependencies, automatic generation
2534 @cindex automatic generation of dependencies
2535 @cindex generating dependencies automatically
2537 In the makefile for a program, many of the rules you need to write often
2538 say only that some object file depends on some header
2539 file.  For example, if @file{main.c} uses @file{defs.h} via an
2540 @code{#include}, you would write:
2542 @example
2543 main.o: defs.h
2544 @end example
2546 @noindent
2547 You need this rule so that @code{make} knows that it must remake
2548 @file{main.o} whenever @file{defs.h} changes.  You can see that for a
2549 large program you would have to write dozens of such rules in your
2550 makefile.  And, you must always be very careful to update the makefile
2551 every time you add or remove an @code{#include}.
2552 @cindex @code{#include}
2554 @cindex @code{-M} (to compiler)
2555 To avoid this hassle, most modern C compilers can write these rules for
2556 you, by looking at the @code{#include} lines in the source files.
2557 Usually this is done with the @samp{-M} option to the compiler.
2558 For example, the command:
2560 @example
2561 cc -M main.c
2562 @end example
2564 @noindent
2565 generates the output:
2567 @example
2568 main.o : main.c defs.h
2569 @end example
2571 @noindent
2572 Thus you no longer have to write all those rules yourself.
2573 The compiler will do it for you.
2575 Note that such a dependency constitutes mentioning @file{main.o} in a
2576 makefile, so it can never be considered an intermediate file by implicit
2577 rule search.  This means that @code{make} won't ever remove the file
2578 after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}.
2580 @cindex @code{make depend}
2581 With old @code{make} programs, it was traditional practice to use this
2582 compiler feature to generate dependencies on demand with a command like
2583 @samp{make depend}.  That command would create a file @file{depend}
2584 containing all the automatically-generated dependencies; then the
2585 makefile could use @code{include} to read them in (@pxref{Include}).
2587 In GNU @code{make}, the feature of remaking makefiles makes this
2588 practice obsolete---you need never tell @code{make} explicitly to
2589 regenerate the dependencies, because it always regenerates any makefile
2590 that is out of date.  @xref{Remaking Makefiles}.
2592 The practice we recommend for automatic dependency generation is to have
2593 one makefile corresponding to each source file.  For each source file
2594 @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
2595 what files the object file @file{@var{name}.o} depends on.  That way
2596 only the source files that have changed need to be rescanned to produce
2597 the new dependencies.
2599 Here is the pattern rule to generate a file of dependencies (i.e., a makefile)
2600 called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
2602 @smallexample
2603 @group
2604 %.d: %.c
2605         $(SHELL) -ec '$(CC) -M $(CPPFLAGS) $< \
2606                       | sed '\''s/\($*\)\.o[ :]*/\1 $@@/g'\'' > $@@'
2607 @end group
2608 @end smallexample
2610 @noindent
2611 @xref{Pattern Rules}, for information on defining pattern rules.  The
2612 @samp{-e} flag to the shell makes it exit immediately if the
2613 @code{$(CC)} command fails (exits with a nonzero status).  Normally the
2614 shell exits with the status of the last command in the pipeline
2615 (@code{sed} in this case), so @code{make} would not notice a nonzero
2616 status from the compiler.
2617 @cindex @code{-e} (shell flag)
2619 @cindex @code{-MM} (to GNU compiler)
2620 With the GNU C compiler, you may wish to use the @samp{-MM} flag instead
2621 of @samp{-M}.  This omits dependencies on system header files.
2622 @xref{Preprocessor Options, , Options Controlling the Preprocessor,
2623 gcc.info, Using GNU CC}, for details.
2625 @cindex @code{sed} (shell command)
2626 The purpose of the @code{sed} command is to translate (for example):
2628 @example
2629 main.o : main.c defs.h
2630 @end example
2632 @noindent
2633 into:
2635 @example
2636 main.o main.d : main.c defs.h
2637 @end example
2639 @noindent
2640 @cindex @code{.d}
2641 This makes each @samp{.d} file depend on all the source and header files
2642 that the corresponding @samp{.o} file depends on.  @code{make} then
2643 knows it must regenerate the dependencies whenever any of the source or
2644 header files changes.
2646 Once you've defined the rule to remake the @samp{.d} files,
2647 you then use the @code{include} directive to read them all in.
2648 @xref{Include}.  For example:
2650 @example
2651 @group
2652 sources = foo.c bar.c
2654 include $(sources:.c=.d)
2655 @end group
2656 @end example
2658 @noindent
2659 (This example uses a substitution variable reference to translate the
2660 list of source files @samp{foo.c bar.c} into a list of dependency
2661 makefiles, @samp{foo.d bar.d}.  @xref{Substitution Refs}, for full
2662 information on substitution references.)  Since the @samp{.d} files are
2663 makefiles like any others, @code{make} will remake them as necessary
2664 with no further work from you.  @xref{Remaking Makefiles}.
2666 @node Commands, Using Variables, Rules, Top
2667 @chapter Writing the Commands in Rules
2668 @cindex commands, how to write
2669 @cindex rule commands
2670 @cindex writing rule commands
2672 The commands of a rule consist of shell command lines to be executed one
2673 by one.  Each command line must start with a tab, except that the first
2674 command line may be attached to the target-and-dependencies line with a
2675 semicolon in between.  Blank lines and lines of just comments may appear
2676 among the command lines; they are ignored.  (But beware, an apparently
2677 ``blank'' line that begins with a tab is @emph{not} blank!  It is an
2678 empty command; @pxref{Empty Commands}.)
2680 Users use many different shell programs, but commands in makefiles are
2681 always interpreted by @file{/bin/sh} unless the makefile specifies
2682 otherwise.  @xref{Execution, ,Command Execution}.
2684 @cindex comments, in commands
2685 @cindex commands, comments in
2686 @cindex @code{#} (comments), in commands
2687 The shell that is in use determines whether comments can be written on
2688 command lines, and what syntax they use.  When the shell is
2689 @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
2690 the line.  The @samp{#} does not have to be at the beginning of a line.
2691 Text on a line before a @samp{#} is not part of the comment.
2693 @menu
2694 * Echoing::                     How to control when commands are echoed.
2695 * Execution::                   How commands are executed.
2696 * Parallel::                    How commands can be executed in parallel.
2697 * Errors::                      What happens after a command execution error.
2698 * Interrupts::                  What happens when a command is interrupted.
2699 * Recursion::                   Invoking @code{make} from makefiles.
2700 * Sequences::                   Defining canned sequences of commands.
2701 * Empty Commands::              Defining useful, do-nothing commands.
2702 @end menu
2704 @node Echoing, Execution,  , Commands
2705 @section Command Echoing
2706 @cindex echoing of commands
2707 @cindex silent operation
2708 @cindex @code{@@} (in commands)
2709 @cindex commands, echoing
2710 @cindex printing of commands
2712 Normally @code{make} prints each command line before it is executed.
2713 We call this @dfn{echoing} because it gives the appearance that you
2714 are typing the commands yourself.
2716 When a line starts with @samp{@@}, the echoing of that line is suppressed.
2717 The @samp{@@} is discarded before the command is passed to the shell.
2718 Typically you would use this for a command whose only effect is to print
2719 something, such as an @code{echo} command to indicate progress through
2720 the makefile:
2722 @example
2723 @@echo About to make distribution files
2724 @end example
2726 @cindex @code{-n}
2727 @cindex @code{--just-print}
2728 @cindex @code{--dry-run}
2729 @cindex @code{--recon}
2730 When @code{make} is given the flag @samp{-n} or @samp{--just-print},
2731 echoing is all that happens, no execution.  @xref{Options Summary,
2732 ,Summary of Options}.  In this case and only this case, even the
2733 commands starting with @samp{@@} are printed.  This flag is useful for
2734 finding out which commands @code{make} thinks are necessary without
2735 actually doing them.
2737 @cindex @code{-s}
2738 @cindex @code{--silent}
2739 @cindex @code{--quiet}
2740 @findex .SILENT
2741 The @samp{-s} or @samp{--silent}
2742 flag to @code{make} prevents all echoing, as if all commands
2743 started with @samp{@@}.  A rule in the makefile for the special target
2744 @code{.SILENT} without dependencies has the same effect
2745 (@pxref{Special Targets, ,Special Built-in Target Names}).
2746 @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
2748 @node Execution, Parallel, Echoing, Commands
2749 @section Command Execution
2750 @cindex commands, execution
2751 @cindex execution, of commands
2752 @cindex shell command, execution
2753 @vindex SHELL @r{(command execution)}
2755 When it is time to execute commands to update a target, they are executed
2756 by making a new subshell for each line.  (In practice, @code{make} may
2757 take shortcuts that do not affect the results.)
2759 @cindex @code{cd} (shell command)
2760 @strong{Please note:} this implies that shell commands such as
2761 @code{cd} that set variables local to each process will not affect the
2762 following command lines.  If you want to use @code{cd} to affect the
2763 next command, put the two on a single line with a semicolon between
2764 them.  Then @code{make} will consider them a single command and pass
2765 them, together, to a shell which will execute them in sequence.  For
2766 example:
2768 @example
2769 foo : bar/lose
2770         cd bar; gobble lose > ../foo
2771 @end example
2773 @cindex commands, backslash (@code{\}) in
2774 @cindex commands, quoting newlines in
2775 @cindex backslash (@code{\}), in commands
2776 @cindex @code{\} (backslash), in commands
2777 @cindex quoting newline, in commands
2778 @cindex newline, quoting, in commands
2779 If you would like to split a single shell command into multiple lines of
2780 text, you must use a backslash at the end of all but the last subline.
2781 Such a sequence of lines is combined into a single line, by deleting the
2782 backslash-newline sequences, before passing it to the shell.  Thus, the
2783 following is equivalent to the preceding example:
2785 @example
2786 @group
2787 foo : bar/lose
2788         cd bar;  \
2789         gobble lose > ../foo
2790 @end group
2791 @end example
2793 @vindex SHELL
2794 The program used as the shell is taken from the variable @code{SHELL}.
2795 By default, the program @file{/bin/sh} is used.
2797 @cindex environment, @code{SHELL} in
2798 Unlike most variables, the variable @code{SHELL} is never set from the
2799 environment.  This is because the @code{SHELL} environment variable is
2800 used to specify your personal choice of shell program for interactive
2801 use.  It would be very bad for personal choices like this to affect
2802 the functioning of makefiles.  @xref{Environment, ,Variables from the
2803 Environment}.
2805 @node Parallel, Errors, Execution, Commands
2806 @section Parallel Execution
2807 @cindex commands, execution in parallel
2808 @cindex parallel execution
2809 @cindex execution, in parallel
2810 @cindex job slots
2811 @cindex @code{-j}
2812 @cindex @code{--jobs}
2814 GNU @code{make} knows how to execute several commands at once.
2815 Normally, @code{make} will execute only one command at a time, waiting
2816 for it to finish before executing the next.  However, the @samp{-j} or
2817 @samp{--jobs} option tells @code{make} to execute many commands
2818 simultaneously.@refill
2820 If the @samp{-j} option is followed by an integer, this is the number of
2821 commands to execute at once; this is called the number of @dfn{job slots}.
2822 If there is nothing looking like an integer after the @samp{-j} option,
2823 there is no limit on the number of job slots.  The default number of job
2824 slots is one, which means serial execution (one thing at a time).
2826 One unpleasant consequence of running several commands simultaneously is
2827 that output from all of the commands comes when the commands send it, so
2828 messages from different commands may be interspersed.
2830 Another problem is that two processes cannot both take input from the
2831 same device; so to make sure that only one command tries to take input
2832 from the terminal at once, @code{make} will invalidate the standard
2833 input streams of all but one running command.  This means that
2834 attempting to read from standard input will usually be a fatal error (a
2835 @samp{Broken pipe} signal) for most child processes if there are
2836 several.
2837 @cindex broken pipe
2838 @cindex standard input
2840 It is unpredictable which command will have a valid standard input stream
2841 (which will come from the terminal, or wherever you redirect the standard
2842 input of @code{make}).  The first command run will always get it first, and
2843 the first command started after that one finishes will get it next, and so
2846 We will change how this aspect of @code{make} works if we find a better
2847 alternative.  In the mean time, you should not rely on any command using
2848 standard input at all if you are using the parallel execution feature; but
2849 if you are not using this feature, then standard input works normally in
2850 all commands.
2852 If a command fails (is killed by a signal or exits with a nonzero
2853 status), and errors are not ignored for that command
2854 (@pxref{Errors, ,Errors in Commands}),
2855 the remaining command lines to remake the same target will not be run.
2856 If a command fails and the @samp{-k} or @samp{--keep-going}
2857 option was not given
2858 (@pxref{Options Summary, ,Summary of Options}),
2859 @code{make} aborts execution.  If make
2860 terminates for any reason (including a signal) with child processes
2861 running, it waits for them to finish before actually exiting.@refill
2863 @cindex load average
2864 @cindex limiting jobs based on load
2865 @cindex jobs, limiting based on load
2866 @cindex @code{-l} (load average)
2867 @cindex @code{--max-load}
2868 @cindex @code{--load-average}
2869 When the system is heavily loaded, you will probably want to run fewer jobs
2870 than when it is lightly loaded.  You can use the @samp{-l} option to tell
2871 @code{make} to limit the number of jobs to run at once, based on the load
2872 average.  The @samp{-l} or @samp{--max-load}
2873 option is followed by a floating-point number.  For
2874 example,
2876 @example
2877 -l 2.5
2878 @end example
2880 @noindent
2881 will not let @code{make} start more than one job if the load average is
2882 above 2.5.  The @samp{-l} option with no following number removes the
2883 load limit, if one was given with a previous @samp{-l} option.@refill
2885 More precisely, when @code{make} goes to start up a job, and it already has
2886 at least one job running, it checks the current load average; if it is not
2887 lower than the limit given with @samp{-l}, @code{make} waits until the load
2888 average goes below that limit, or until all the other jobs finish.
2890 By default, there is no load limit.
2892 @node Errors, Interrupts, Parallel, Commands
2893 @section Errors in Commands
2894 @cindex errors (in commands)
2895 @cindex commands, errors in
2896 @cindex exit status (errors)
2898 After each shell command returns, @code{make} looks at its exit status.
2899 If the command completed successfully, the next command line is executed
2900 in a new shell; after the last command line is finished, the rule is
2901 finished.
2903 If there is an error (the exit status is nonzero), @code{make} gives up on
2904 the current rule, and perhaps on all rules.
2906 Sometimes the failure of a certain command does not indicate a problem.
2907 For example, you may use the @code{mkdir} command to ensure that a
2908 directory exists.  If the directory already exists, @code{mkdir} will
2909 report an error, but you probably want @code{make} to continue regardless.
2911 @cindex @code{-} (in commands)
2912 To ignore errors in a command line, write a @samp{-} at the beginning of
2913 the line's text (after the initial tab).  The @samp{-} is discarded before
2914 the command is passed to the shell for execution.
2916 For example,
2918 @example
2919 @group
2920 clean:
2921         -rm -f *.o
2922 @end group
2923 @end example
2924 @cindex @code{rm} (shell command)
2926 @noindent
2927 This causes @code{rm} to continue even if it is unable to remove a file.
2929 @cindex @code{-i}
2930 @cindex @code{--ignore-errors}
2931 @findex .IGNORE
2932 When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
2933 flag, errors are ignored in all commands of all rules.  A rule in the
2934 makefile for the special target @code{.IGNORE} has the same effect, if
2935 there are no dependencies.  These ways of ignoring errors are obsolete
2936 because @samp{-} is more flexible.
2938 When errors are to be ignored, because of either a @samp{-} or the
2939 @samp{-i} flag, @code{make} treats an error return just like success,
2940 except that it prints out a message that tells you the status code
2941 the command exited with, and says that the error has been ignored.
2943 When an error happens that @code{make} has not been told to ignore,
2944 it implies that the current target cannot be correctly remade, and neither
2945 can any other that depends on it either directly or indirectly.  No further
2946 commands will be executed for these targets, since their preconditions
2947 have not been achieved.
2950 @cindex @code{-k}
2951 @cindex @code{--keep-going}
2952 Normally @code{make} gives up immediately in this circumstance, returning a
2953 nonzero status.  However, if the @samp{-k} or @samp{--keep-going}
2954 flag is specified, @code{make}
2955 continues to consider the other dependencies of the pending targets,
2956 remaking them if necessary, before it gives up and returns nonzero status.
2957 For example, after an error in compiling one object file, @samp{make -k}
2958 will continue compiling other object files even though it already knows
2959 that linking them will be impossible.  @xref{Options Summary, ,Summary of Options}.
2961 The usual behavior assumes that your purpose is to get the specified
2962 targets up to date; once @code{make} learns that this is impossible, it
2963 might as well report the failure immediately.  The @samp{-k} option says
2964 that the real purpose is to test as many of the changes made in the
2965 program as possible, perhaps to find several independent problems so
2966 that you can correct them all before the next attempt to compile.  This
2967 is why Emacs' @code{compile} command passes the @samp{-k} flag by
2968 default.
2969 @cindex Emacs (@code{M-x compile})
2971 @findex .DELETE_ON_ERROR
2972 @cindex deletion of target files
2973 @cindex removal of target files
2974 @cindex target, deleting on error
2975 Usually when a command fails, if it has changed the target file at all,
2976 the file is corrupted and cannot be used---or at least it is not
2977 completely updated.  Yet the file's timestamp says that it is now up to
2978 date, so the next time @code{make} runs, it will not try to update that
2979 file.  The situation is just the same as when the command is killed by a
2980 signal; @pxref{Interrupts}.  So generally the right thing to do is to
2981 delete the target file if the command fails after beginning to change
2982 the file.  @code{make} will do this if @code{.DELETE_ON_ERROR} appears
2983 as a target.  This is almost always what you want @code{make} to do, but
2984 it is not historical practice; so for compatibility, you must explicitly
2985 request it.
2987 @node Interrupts, Recursion, Errors, Commands
2988 @section Interrupting or Killing @code{make}
2989 @cindex interrupt
2990 @cindex signal
2991 @cindex deletion of target files
2992 @cindex removal of target files
2993 @cindex target, deleting on interrupt
2994 @cindex killing (interruption)
2996 If @code{make} gets a fatal signal while a command is executing, it may
2997 delete the target file that the command was supposed to update.  This is
2998 done if the target file's last-modification time has changed since
2999 @code{make} first checked it.
3001 The purpose of deleting the target is to make sure that it is remade from
3002 scratch when @code{make} is next run.  Why is this?  Suppose you type
3003 @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
3004 object file @file{foo.o}.  The @kbd{Ctrl-c} kills the compiler, resulting
3005 in an incomplete file whose last-modification time is newer than the source
3006 file @file{foo.c}.  But @code{make} also receives the @kbd{Ctrl-c} signal
3007 and deletes this incomplete file.  If @code{make} did not do this, the next
3008 invocation of @code{make} would think that @file{foo.o} did not require
3009 updating---resulting in a strange error message from the linker when it
3010 tries to link an object file half of which is missing.
3012 @findex .PRECIOUS
3013 You can prevent the deletion of a target file in this way by making the
3014 special target @code{.PRECIOUS} depend on it.  Before remaking a target,
3015 @code{make} checks to see whether it appears on the dependencies of
3016 @code{.PRECIOUS}, and thereby decides whether the target should be deleted
3017 if a signal happens.  Some reasons why you might do this are that the
3018 target is updated in some atomic fashion, or exists only to record a
3019 modification-time (its contents do not matter), or must exist at all
3020 times to prevent other sorts of trouble.
3022 @node Recursion, Sequences, Interrupts, Commands
3023 @section Recursive Use of @code{make}
3024 @cindex recursion
3025 @cindex subdirectories, recursion for
3027 Recursive use of @code{make} means using @code{make} as a command in a
3028 makefile.  This technique is useful when you want separate makefiles for
3029 various subsystems that compose a larger system.  For example, suppose you
3030 have a subdirectory @file{subdir} which has its own makefile, and you would
3031 like the containing directory's makefile to run @code{make} on the
3032 subdirectory.  You can do it by writing this:
3034 @example
3035 subsystem:
3036         cd subdir; $(MAKE)
3037 @end example
3039 @noindent
3040 or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
3042 @example
3043 subsystem:
3044         $(MAKE) -C subdir
3045 @end example
3046 @cindex @code{-C}
3047 @cindex @code{--directory}
3049 You can write recursive @code{make} commands just by copying this example,
3050 but there are many things to know about how they work and why, and about
3051 how the sub-@code{make} relates to the top-level @code{make}.
3053 @menu
3054 * MAKE Variable::               The special effects of using @samp{$(MAKE)}.
3055 * Variables/Recursion::         How to communicate variables to a sub-@code{make}.
3056 * Options/Recursion::           How to communicate options to a sub-@code{make}.
3057 * -w Option::                   How the @samp{-w} or @samp{--print-directory} option
3058                                  helps debug use of recursive @code{make} commands.
3059 @end menu
3061 @node MAKE Variable, Variables/Recursion,  , Recursion
3062 @subsection How the @code{MAKE} Variable Works
3063 @vindex MAKE
3064 @cindex recursion, and @code{MAKE} variable
3066 Recursive @code{make} commands should always use the variable @code{MAKE},
3067 not the explicit command name @samp{make}, as shown here:
3069 @example
3070 @group
3071 subsystem:
3072         cd subdir; $(MAKE)
3073 @end group
3074 @end example
3076 The value of this variable is the file name with which @code{make} was
3077 invoked.  If this file name was @file{/bin/make}, then the command executed
3078 is @samp{cd subdir; /bin/make}.  If you use a special version of
3079 @code{make} to run the top-level makefile, the same special version will be
3080 executed for recursive invocations.
3081 @cindex @code{cd} (shell command)
3083 As a special feature, using the variable @code{MAKE} in the commands of
3084 a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
3085 (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
3086 Using the @code{MAKE} variable has the same effect as using a @samp{+}
3087 character at the beginning of the command line.  @xref{Instead of
3088 Execution, ,Instead of Executing the Commands}.@refill
3090 Consider the command @samp{make -t} in the above example.  (The
3091 @samp{-t} option marks targets as up to date without actually running
3092 any commands; see @ref{Instead of Execution}.)  Following the usual
3093 definition of @samp{-t}, a @samp{make -t} command in the example would
3094 create a file named @file{subsystem} and do nothing else.  What you
3095 really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would
3096 require executing the command, and @samp{-t} says not to execute
3097 commands.@refill
3098 @cindex @code{-t}, and recursion
3099 @cindex recursion, and @code{-t}
3100 @cindex @code{--touch}, and recursion
3102 The special feature makes this do what you want: whenever a command
3103 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
3104 @samp{-n} and @samp{-q} do not apply to that line.  Command lines
3105 containing @code{MAKE} are executed normally despite the presence of a
3106 flag that causes most commands not to be run.  The usual
3107 @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
3108 (@pxref{Options/Recursion, ,Communicating Options to a
3109 Sub-@code{make}}), so your request to touch the files, or print the
3110 commands, is propagated to the subsystem.@refill
3112 @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
3113 @subsection Communicating Variables to a Sub-@code{make}
3114 @cindex sub-@code{make}
3115 @cindex environment, and recursion
3116 @cindex exporting variables
3117 @cindex variables, environment
3118 @cindex variables, exporting
3119 @cindex recursion, and environment
3120 @cindex recursion, and variables
3122 Variable values of the top-level @code{make} can be passed to the
3123 sub-@code{make} through the environment by explicit request.  These
3124 variables are defined in the sub-@code{make} as defaults, but do not
3125 override what is specified in the makefile used by the sub-@code{make}
3126 makefile unless you use the @samp{-e} switch (@pxref{Options Summary,
3127 ,Summary of Options}).@refill
3129 To pass down, or @dfn{export}, a variable, @code{make} adds the variable
3130 and its value to the environment for running each command.  The
3131 sub-@code{make}, in turn, uses the environment to initialize its table
3132 of variable values.  @xref{Environment, ,Variables from the
3133 Environment}.
3135 Except by explicit request, @code{make} exports a variable only if it
3136 is either defined in the environment initially or set on the command
3137 line, and if its name consists only of letters, numbers, and underscores.
3138 Some shells cannot cope with environment variable names consisting of
3139 characters other than letters, numbers, and underscores.
3141 The special variables @code{SHELL} and @code{MAKEFLAGS} are always
3142 exported (unless you unexport them).
3143 @code{MAKEFILES} is exported if you set it to anything.
3145 @code{make} automatically passes down variable values that were defined
3146 on the command line, by putting them in the @code{MAKEFLAGS} variable.
3147 @iftex
3148 See the next section.
3149 @end iftex
3150 @ifinfo
3151 @xref{Options/Recursion}.
3152 @end ifinfo
3154 Variables are @emph{not} normally passed down if they were created by
3155 default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
3156 Implicit Rules}).  The sub-@code{make} will define these for
3157 itself.@refill
3159 @findex export
3160 If you want to export specific variables to a sub-@code{make}, use the
3161 @code{export} directive, like this:
3163 @example
3164 export @var{variable} @dots{}
3165 @end example
3167 @noindent
3168 @findex unexport
3169 If you want to @emph{prevent} a variable from being exported, use the
3170 @code{unexport} directive, like this:
3172 @example
3173 unexport @var{variable} @dots{}
3174 @end example
3176 @noindent
3177 As a convenience, you can define a variable and export it at the same
3178 time by doing:
3180 @example
3181 export @var{variable} = value
3182 @end example
3184 @noindent
3185 has the same result as:
3187 @example
3188 @var{variable} = value
3189 export @var{variable}
3190 @end example
3192 @noindent
3195 @example
3196 export @var{variable} := value
3197 @end example
3199 @noindent
3200 has the same result as:
3202 @example
3203 @var{variable} := value
3204 export @var{variable}
3205 @end example
3207 Likewise,
3209 @example
3210 export @var{variable} += value
3211 @end example
3213 @noindent
3214 is just like:
3216 @example
3217 @var{variable} += value
3218 export @var{variable}
3219 @end example
3221 @noindent
3222 @xref{Appending, ,Appending More Text to Variables}.
3224 You may notice that the @code{export} and @code{unexport} directives
3225 work in @code{make} in the same way they work in the shell, @code{sh}.
3227 If you want all variables to be exported by default, you can use
3228 @code{export} by itself:
3230 @example
3231 export
3232 @end example
3234 @noindent
3235 This tells @code{make} that variables which are not explicitly mentioned
3236 in an @code{export} or @code{unexport} directive should be exported.
3237 Any variable given in an @code{unexport} directive will still @emph{not}
3238 be exported.  If you use @code{export} by itself to export variables by
3239 default, variables whose names contain characters other than
3240 alphanumerics and underscores will not be exported unless specifically
3241 mentioned in an @code{export} directive.@refill
3243 @findex .EXPORT_ALL_VARIABLES
3244 The behavior elicited by an @code{export} directive by itself was the
3245 default in older versions of GNU @code{make}.  If your makefiles depend
3246 on this behavior and you want to be compatible with old versions of
3247 @code{make}, you can write a rule for the special target
3248 @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
3249 This will be ignored by old @code{make}s, while the @code{export}
3250 directive will cause a syntax error.@refill
3251 @cindex compatibility in exporting
3253 Likewise, you can use @code{unexport} by itself to tell @code{make}
3254 @emph{not} to export variables by default.  Since this is the default
3255 behavior, you would only need to do this if @code{export} had been used
3256 by itself earlier (in an included makefile, perhaps).  You
3257 @strong{cannot} use @code{export} and @code{unexport} by themselves to
3258 have variables exported for some commands and not for others.  The last
3259 @code{export} or @code{unexport} directive that appears by itself
3260 determines the behavior for the entire run of @code{make}.@refill
3262 @vindex MAKELEVEL
3263 @cindex recursion, level of
3264 As a special feature, the variable @code{MAKELEVEL} is changed when it
3265 is passed down from level to level.  This variable's value is a string
3266 which is the depth of the level as a decimal number.  The value is
3267 @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
3268 @samp{2} for a sub-sub-@code{make}, and so on.  The incrementation
3269 happens when @code{make} sets up the environment for a command.@refill
3271 The main use of @code{MAKELEVEL} is to test it in a conditional
3272 directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
3273 way you can write a makefile that behaves one way if run recursively and
3274 another way if run directly by you.@refill
3276 @vindex MAKEFILES
3277 You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
3278 commands to use additional makefiles.  The value of @code{MAKEFILES} is
3279 a whitespace-separated list of file names.  This variable, if defined in
3280 the outer-level makefile, is passed down through the environment; then
3281 it serves as a list of extra makefiles for the sub-@code{make} to read
3282 before the usual or specified ones.  @xref{MAKEFILES Variable, ,The
3283 Variable @code{MAKEFILES}}.@refill
3285 @node Options/Recursion, -w Option, Variables/Recursion, Recursion
3286 @subsection Communicating Options to a Sub-@code{make}
3287 @cindex options, and recursion
3288 @cindex recursion, and options
3290 @vindex MAKEFLAGS
3291 Flags such as @samp{-s} and @samp{-k} are passed automatically to the
3292 sub-@code{make} through the variable @code{MAKEFLAGS}.  This variable is
3293 set up automatically by @code{make} to contain the flag letters that
3294 @code{make} received.  Thus, if you do @w{@samp{make -ks}} then
3295 @code{MAKEFLAGS} gets the value @samp{ks}.@refill
3297 As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
3298 in its environment.  In response, it takes the flags from that value and
3299 processes them as if they had been given as arguments.
3300 @xref{Options Summary, ,Summary of Options}.
3302 @cindex command line variable definitions, and recursion
3303 @cindex variables, command line, and recursion
3304 @cindex recursion, and command line variable definitions
3305 Likewise variables defined on the command line are passed to the
3306 sub-@code{make} through @code{MAKEFLAGS}.  Words in the value of
3307 @code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable
3308 definitions just as if they appeared on the command line.
3309 @xref{Overriding, ,Overriding Variables}.
3311 @cindex @code{-C}, and recursion
3312 @cindex @code{-f}, and recursion
3313 @cindex @code{-o}, and recursion
3314 @cindex @code{-W}, and recursion
3315 @cindex @code{--directory}, and recursion
3316 @cindex @code{--file}, and recursion
3317 @cindex @code{--old-file}, and recursion
3318 @cindex @code{--assume-old}, and recursion
3319 @cindex @code{--assume-new}, and recursion
3320 @cindex @code{--new-file}, and recursion
3321 @cindex recursion, and @code{-C}
3322 @cindex recursion, and @code{-f}
3323 @cindex recursion, and @code{-o}
3324 @cindex recursion, and @code{-W}
3325 The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put
3326 into @code{MAKEFLAGS}; these options are not passed down.@refill
3328 @cindex @code{-j}, and recursion
3329 @cindex @code{--jobs}, and recursion
3330 @cindex recursion, and @code{-j}
3331 @cindex job slots, and recursion
3332 The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
3333 If you set it to some numeric value, @samp{-j 1} is always put into
3334 @code{MAKEFLAGS} instead of the value you specified.  This is because if
3335 the @w{@samp{-j}} option were passed down to sub-@code{make}s, you would
3336 get many more jobs running in parallel than you asked for.  If you give
3337 @samp{-j} with no numeric argument, meaning to run as many jobs as
3338 possible in parallel, this is passed down, since multiple infinities are
3339 no more than one.@refill
3341 If you do not want to pass the other flags down, you must change the
3342 value of @code{MAKEFLAGS}, like this:
3344 @example
3345 subsystem:
3346         cd subdir; $(MAKE) MAKEFLAGS=
3347 @end example
3349 @vindex MAKEOVERRIDES
3350 The command line variable definitions really appear in the variable
3351 @code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this
3352 variable.  If you do want to pass flags down normally, but don't want to
3353 pass down the command line variable definitions, you can reset
3354 @code{MAKEOVERRIDES} to empty, like this:
3356 @example
3357 MAKEOVERRIDES =
3358 @end example
3360 @noindent
3361 @cindex Arg list too long
3362 @cindex E2BIG
3363 This is not usually useful to do.  However, some systems have a small
3364 fixed limit on the size of the environment, and putting so much
3365 information in into the value of @code{MAKEFLAGS} can exceed it.
3366 If you see the error message @samp{Arg list too long}, this may be the problem.
3367 @findex .POSIX
3368 @cindex POSIX.2
3369 (For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does
3370 not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears
3371 in the makefile.  You probably do not care about this.)
3373 @vindex MFLAGS
3374 A similar variable @code{MFLAGS} exists also, for historical
3375 compatibility.  It has the same value as @code{MAKEFLAGS} except that it
3376 does not contain the command line variable definitions, and it always
3377 begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a
3378 hyphen only when it begins with an option that has no single-letter
3379 version, such as @samp{--warn-undefined-variables}).  @code{MFLAGS} was
3380 traditionally used explicitly in the recursive @code{make} command, like
3381 this:
3383 @example
3384 subsystem:
3385         cd subdir; $(MAKE) $(MFLAGS)
3386 @end example
3388 @noindent
3389 but now @code{MAKEFLAGS} makes this usage redundant.  If you want your
3390 makefiles to be compatible with old @code{make} programs, use this
3391 technique; it will work fine with more modern @code{make} versions too.
3393 @cindex setting options from environment
3394 @cindex options, setting from environment
3395 @cindex setting options in makefiles
3396 @cindex options, setting in makefiles
3397 The @code{MAKEFLAGS} variable can also be useful if you want to have
3398 certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
3399 Options}), set each time you run @code{make}.  You simply put a value for
3400 @code{MAKEFLAGS} in your environment.  You can also set @code{MAKEFLAGS} in
3401 a makefile, to specify additional flags that should also be in effect for
3402 that makefile.  (Note that you cannot use @code{MFLAGS} this way.  That
3403 variable is set only for compatibility; @code{make} does not interpret a
3404 value you set for it in any way.)
3406 When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
3407 environment or from a makefile), it first prepends a hyphen if the value
3408 does not already begin with one.  Then it chops the value into words
3409 separated by blanks, and parses these words as if they were options given
3410 on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
3411 @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
3412 is no error for an invalid option).
3414 If you do put @code{MAKEFLAGS} in your environment, you should be sure not
3415 to include any options that will drastically affect the actions of
3416 @code{make} and undermine the purpose of makefiles and of @code{make}
3417 itself.  For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
3418 put in one of these variables, could have disastrous consequences and would
3419 certainly have at least surprising and probably annoying effects.@refill
3421 @node -w Option,  , Options/Recursion, Recursion
3422 @subsection The @samp{--print-directory} Option
3423 @cindex directories, printing them
3424 @cindex printing directories
3425 @cindex recursion, and printing directories
3427 If you use several levels of recursive @code{make} invocations, the
3428 @samp{-w} or @w{@samp{--print-directory}} option can make the output a
3429 lot easier to understand by showing each directory as @code{make}
3430 starts processing it and as @code{make} finishes processing it.  For
3431 example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
3432 @code{make} will print a line of the form:@refill
3434 @example
3435 make: Entering directory `/u/gnu/make'.
3436 @end example
3438 @noindent
3439 before doing anything else, and a line of the form:
3441 @example
3442 make: Leaving directory `/u/gnu/make'.
3443 @end example
3445 @noindent
3446 when processing is completed.
3448 @cindex @code{-C}, and @code{-w}
3449 @cindex @code{--directory}, and @code{--print-directory}
3450 @cindex recursion, and @code{-w}
3451 @cindex @code{-w}, and @code{-C}
3452 @cindex @code{-w}, and recursion
3453 @cindex @code{--print-directory}, and @code{--directory}
3454 @cindex @code{--print-directory}, and recursion
3455 @cindex @code{--no-print-directory}
3456 @cindex @code{--print-directory}, disabling
3457 @cindex @code{-w}, disabling
3458 Normally, you do not need to specify this option because @samp{make}
3459 does it for you: @samp{-w} is turned on automatically when you use the
3460 @samp{-C} option, and in sub-@code{make}s.  @code{make} will not
3461 automatically turn on @samp{-w} if you also use @samp{-s}, which says to
3462 be silent, or if you use @samp{--no-print-directory} to explicitly
3463 disable it.
3465 @node Sequences, Empty Commands, Recursion, Commands
3466 @section Defining Canned Command Sequences
3467 @cindex sequences of commands
3468 @cindex commands, sequences of
3470 When the same sequence of commands is useful in making various targets, you
3471 can define it as a canned sequence with the @code{define} directive, and
3472 refer to the canned sequence from the rules for those targets.  The canned
3473 sequence is actually a variable, so the name must not conflict with other
3474 variable names.
3476 Here is an example of defining a canned sequence of commands:
3478 @example
3479 define run-yacc
3480 yacc $(firstword $^)
3481 mv y.tab.c $@@
3482 endef
3483 @end example
3484 @cindex @code{yacc}
3486 @noindent
3487 Here @code{run-yacc} is the name of the variable being defined;
3488 @code{endef} marks the end of the definition; the lines in between are the
3489 commands.  The @code{define} directive does not expand variable references
3490 and function calls in the canned sequence; the @samp{$} characters,
3491 parentheses, variable names, and so on, all become part of the value of the
3492 variable you are defining.
3493 @xref{Defining, ,Defining Variables Verbatim},
3494 for a complete explanation of @code{define}.
3496 The first command in this example runs Yacc on the first dependency of
3497 whichever rule uses the canned sequence.  The output file from Yacc is
3498 always named @file{y.tab.c}.  The second command moves the output to the
3499 rule's target file name.
3501 To use the canned sequence, substitute the variable into the commands of a
3502 rule.  You can substitute it like any other variable
3503 (@pxref{Reference, ,Basics of Variable References}).
3504 Because variables defined by @code{define} are recursively expanded
3505 variables, all the variable references you wrote inside the @code{define}
3506 are expanded now.  For example:
3508 @example
3509 foo.c : foo.y
3510         $(run-yacc)
3511 @end example
3513 @noindent
3514 @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
3515 @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
3517 This is a realistic example, but this particular one is not needed in
3518 practice because @code{make} has an implicit rule to figure out these
3519 commands based on the file names involved
3520 (@pxref{Implicit Rules, ,Using Implicit Rules}).
3522 @cindex @@, and @code{define}
3523 @cindex -, and @code{define}
3524 @cindex +, and @code{define}
3525 In command execution, each line of a canned sequence is treated just as
3526 if the line appeared on its own in the rule, preceded by a tab.  In
3527 particular, @code{make} invokes a separate subshell for each line.  You
3528 can use the special prefix characters that affect command lines
3529 (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
3530 @xref{Commands, ,Writing the Commands in Rules}.
3531 For example, using this canned sequence:
3533 @example
3534 define frobnicate
3535 @@echo "frobnicating target $@@"
3536 frob-step-1 $< -o $@@-step-1
3537 frob-step-2 $@@-step-1 -o $@@
3538 endef
3539 @end example
3541 @noindent
3542 @code{make} will not echo the first line, the @code{echo} command.
3543 But it @emph{will} echo the following two command lines.
3545 On the other hand, prefix characters on the command line that refers to
3546 a canned sequence apply to every line in the sequence.  So the rule:
3548 @example
3549 frob.out: frob.in
3550         @@$(frobnicate)
3551 @end example
3553 @noindent
3554 does not echo @emph{any} commands.
3555 (@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.)
3557 @node Empty Commands,  , Sequences, Commands
3558 @section Using Empty Commands
3559 @cindex empty commands
3560 @cindex commands, empty
3562 It is sometimes useful to define commands which do nothing.  This is done
3563 simply by giving a command that consists of nothing but whitespace.  For
3564 example:
3566 @example
3567 target: ;
3568 @end example
3570 @noindent
3571 defines an empty command string for @file{target}.  You could also use a
3572 line beginning with a tab character to define an empty command string,
3573 but this would be confusing because such a line looks empty.
3575 @findex .DEFAULT@r{, and empty commands}
3576 You may be wondering why you would want to define a command string that
3577 does nothing.  The only reason this is useful is to prevent a target
3578 from getting implicit commands (from implicit rules or the
3579 @code{.DEFAULT} special target; @pxref{Implicit Rules} and
3580 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
3582 @c !!! another reason is for canonical stamp files:
3583 @ignore
3584 foo: stamp-foo ;
3585 stamp-foo: foo.in
3586         create foo frm foo.in
3587         touch $@
3588 @end ignore
3590 You may be inclined to define empty command strings for targets that are
3591 not actual files, but only exist so that their dependencies can be
3592 remade.  However, this is not the best way to do that, because the
3593 dependencies may not be remade properly if the target file actually does exist.
3594 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
3596 @node Using Variables, Conditionals, Commands, Top
3597 @chapter How to Use Variables
3598 @cindex variable
3599 @cindex value
3600 @cindex recursive variable expansion
3601 @cindex simple variable expansion
3603 A @dfn{variable} is a name defined in a makefile to represent a string
3604 of text, called the variable's @dfn{value}.  These values are
3605 substituted by explicit request into targets, dependencies, commands,
3606 and other parts of the makefile.  (In some other versions of @code{make},
3607 variables are called @dfn{macros}.)
3608 @cindex macro
3610 Variables and functions in all parts of a makefile are expanded when
3611 read, except for the shell commands in rules, the right-hand sides of
3612 variable definitions using @samp{=}, and the bodies of variable
3613 definitions using the @code{define} directive.@refill
3615 Variables can represent lists of file names, options to pass to compilers,
3616 programs to run, directories to look in for source files, directories to
3617 write output in, or anything else you can imagine.
3619 A variable name may be any sequence of characters not containing @samp{:},
3620 @samp{#}, @samp{=}, or leading or trailing whitespace.  However,
3621 variable names containing characters other than letters, numbers, and
3622 underscores should be avoided, as they may be given special meanings in the
3623 future, and with some shells they cannot be passed through the environment to a
3624 sub-@code{make}
3625 (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
3627 Variable names are case-sensitive.  The names @samp{foo}, @samp{FOO},
3628 and @samp{Foo} all refer to different variables.
3630 It is traditional to use upper case letters in variable names, but we
3631 recommend using lower case letters for variable names that serve internal
3632 purposes in the makefile, and reserving upper case for parameters that
3633 control implicit rules or for parameters that the user should override with
3634 command options (@pxref{Overriding, ,Overriding Variables}).
3636 A few variables have names that are a single punctuation character or
3637 just a few characters.  These are the @dfn{automatic variables}, and
3638 they have particular specialized uses.  @xref{Automatic, ,Automatic Variables}.
3640 @menu
3641 * Reference::                   How to use the value of a variable.
3642 * Flavors::                     Variables come in two flavors.
3643 * Advanced::                    Advanced features for referencing a variable.
3644 * Values::                      All the ways variables get their values.
3645 * Setting::                     How to set a variable in the makefile.
3646 * Appending::                   How to append more text to the old value
3647                                   of a variable.
3648 * Override Directive::          How to set a variable in the makefile even if
3649                                   the user has set it with a command argument.
3650 * Defining::                    An alternate way to set a variable
3651                                   to a verbatim string.
3652 * Environment::                 Variable values can come from the environment.
3653 * Automatic::                   Some special variables have predefined
3654                                   meanings for use with implicit rules.
3655 @end menu
3657 @node Reference, Flavors,  , Using Variables
3658 @section Basics of Variable References
3659 @cindex variables, how to reference
3660 @cindex reference to variables
3661 @cindex @code{$}, in variable reference
3662 @cindex dollar sign (@code{$}), in variable reference
3664 To substitute a variable's value, write a dollar sign followed by the name
3665 of the variable in parentheses or braces: either @samp{$(foo)} or
3666 @samp{$@{foo@}} is a valid reference to the variable @code{foo}.  This
3667 special significance of @samp{$} is why you must write @samp{$$} to have
3668 the effect of a single dollar sign in a file name or command.
3670 Variable references can be used in any context: targets, dependencies,
3671 commands, most directives, and new variable values.  Here is an
3672 example of a common case, where a variable holds the names of all the
3673 object files in a program:
3675 @example
3676 @group
3677 objects = program.o foo.o utils.o
3678 program : $(objects)
3679         cc -o program $(objects)
3681 $(objects) : defs.h
3682 @end group
3683 @end example
3685 Variable references work by strict textual substitution.  Thus, the rule
3687 @example
3688 @group
3689 foo = c
3690 prog.o : prog.$(foo)
3691         $(foo)$(foo) -$(foo) prog.$(foo)
3692 @end group
3693 @end example
3695 @noindent
3696 could be used to compile a C program @file{prog.c}.  Since spaces before
3697 the variable value are ignored in variable assignments, the value of
3698 @code{foo} is precisely @samp{c}.  (Don't actually write your makefiles
3699 this way!)
3701 A dollar sign followed by a character other than a dollar sign,
3702 open-parenthesis or open-brace treats that single character as the
3703 variable name.  Thus, you could reference the variable @code{x} with
3704 @samp{$x}.  However, this practice is strongly discouraged, except in
3705 the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}).
3707 @node Flavors, Advanced, Reference, Using Variables
3708 @section The Two Flavors of Variables
3709 @cindex flavors of variables
3710 @cindex recursive variable expansion
3711 @cindex variables, flavors
3712 @cindex recursively expanded variables
3713 @cindex variables, recursively expanded
3715 There are two ways that a variable in GNU @code{make} can have a value;
3716 we call them the two @dfn{flavors} of variables.  The two flavors are
3717 distinguished in how they are defined and in what they do when expanded.
3719 @cindex =
3720 The first flavor of variable is a @dfn{recursively expanded} variable.
3721 Variables of this sort are defined by lines using @samp{=}
3722 (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
3723 (@pxref{Defining, ,Defining Variables Verbatim}).  The value you specify
3724 is installed verbatim; if it contains references to other variables,
3725 these references are expanded whenever this variable is substituted (in
3726 the course of expanding some other string).  When this happens, it is
3727 called @dfn{recursive expansion}.@refill
3729 For example,
3731 @example
3732 foo = $(bar)
3733 bar = $(ugh)
3734 ugh = Huh?
3736 all:;echo $(foo)
3737 @end example
3739 @noindent
3740 will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
3741 expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
3743 This flavor of variable is the only sort supported by other versions of
3744 @code{make}.  It has its advantages and its disadvantages.  An advantage
3745 (most would say) is that:
3747 @example
3748 CFLAGS = $(include_dirs) -O
3749 include_dirs = -Ifoo -Ibar
3750 @end example
3752 @noindent
3753 will do what was intended: when @samp{CFLAGS} is expanded in a command,
3754 it will expand to @samp{-Ifoo -Ibar -O}.  A major disadvantage is that you
3755 cannot append something on the end of a variable, as in
3757 @example
3758 CFLAGS = $(CFLAGS) -O
3759 @end example
3761 @noindent
3762 because it will cause an infinite loop in the variable expansion.
3763 (Actually @code{make} detects the infinite loop and reports an error.)
3764 @cindex loops in variable expansion
3765 @cindex variables, loops in expansion
3767 Another disadvantage is that any functions
3768 (@pxref{Functions, ,Functions for Transforming Text})
3769 referenced in the definition will be executed every time the variable is
3770 expanded.  This makes @code{make} run slower; worse, it causes the
3771 @code{wildcard} and @code{shell} functions to give unpredictable results
3772 because you cannot easily control when they are called, or even how many
3773 times.
3775 To avoid all the problems and inconveniences of recursively expanded
3776 variables, there is another flavor: simply expanded variables.
3778 @cindex simply expanded variables
3779 @cindex variables, simply expanded
3780 @cindex :=
3781 @dfn{Simply expanded variables} are defined by lines using @samp{:=}
3782 (@pxref{Setting, ,Setting Variables}).
3783 The value of a simply expanded variable is scanned
3784 once and for all, expanding any references to other variables and
3785 functions, when the variable is defined.  The actual value of the simply
3786 expanded variable is the result of expanding the text that you write.
3787 It does not contain any references to other variables; it contains their
3788 values @emph{as of the time this variable was defined}.  Therefore,
3790 @example
3791 x := foo
3792 y := $(x) bar
3793 x := later
3794 @end example
3796 @noindent
3797 is equivalent to
3799 @example
3800 y := foo bar
3801 x := later
3802 @end example
3804 When a simply expanded variable is referenced, its value is substituted
3805 verbatim.
3807 Here is a somewhat more complicated example, illustrating the use of
3808 @samp{:=} in conjunction with the @code{shell} function.
3809 (@xref{Shell Function, , The @code{shell} Function}.)  This example
3810 also shows use of the variable @code{MAKELEVEL}, which is changed
3811 when it is passed down from level to level.
3812 (@xref{Variables/Recursion, , Communicating Variables to a
3813 Sub-@code{make}}, for information about @code{MAKELEVEL}.)
3815 @vindex MAKELEVEL
3816 @vindex MAKE
3817 @example
3818 @group
3819 ifeq (0,$@{MAKELEVEL@})
3820 cur-dir   := $(shell pwd)
3821 whoami    := $(shell whoami)
3822 host-type := $(shell arch)
3823 MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
3824 endif
3825 @end group
3826 @end example
3828 @noindent
3829 An advantage of this use of @samp{:=} is that a typical
3830 `descend into a directory' command then looks like this:
3832 @example
3833 @group
3834 $@{subdirs@}:
3835       $@{MAKE@} cur-dir=$@{cur-dir@}/$@@ -C $@@ all
3836 @end group
3837 @end example
3839 Simply expanded variables generally make complicated makefile programming
3840 more predictable because they work like variables in most programming
3841 languages.  They allow you to redefine a variable using its own value (or
3842 its value processed in some way by one of the expansion functions) and to
3843 use the expansion functions much more efficiently
3844 (@pxref{Functions, ,Functions for Transforming Text}).
3846 @cindex spaces, in variable values
3847 @cindex whitespace, in variable values
3848 @cindex variables, spaces in values
3849 You can also use them to introduce controlled leading whitespace into
3850 variable values.  Leading whitespace characters are discarded from your
3851 input before substitution of variable references and function calls;
3852 this means you can include leading spaces in a variable value by
3853 protecting them with variable references, like this:
3855 @example
3856 nullstring :=
3857 space := $(nullstring) # end of the line
3858 @end example
3860 @noindent
3861 Here the value of the variable @code{space} is precisely one space.  The
3862 comment @w{@samp{# end of the line}} is included here just for clarity.
3863 Since trailing space characters are @emph{not} stripped from variable
3864 values, just a space at the end of the line would have the same effect
3865 (but be rather hard to read).  If you put whitespace at the end of a
3866 variable value, it is a good idea to put a comment like that at the end
3867 of the line to make your intent clear.  Conversely, if you do @emph{not}
3868 want any whitespace characters at the end of your variable value, you
3869 must remember not to put a random comment on the end of the line after
3870 some whitespace, such as this:
3872 @example
3873 dir := /foo/bar    # directory to put the frobs in
3874 @end example
3876 @noindent
3877 Here the value of the variable @code{dir} is @w{@samp{/foo/bar    }}
3878 (with four trailing spaces), which was probably not the intention.
3879 (Imagine something like @w{@samp{$(dir)/file}} with this definition!)
3881 @node Advanced, Values, Flavors, Using Variables
3882 @section Advanced Features for Reference to Variables
3883 @cindex reference to variables
3885 This section describes some advanced features you can use to reference
3886 variables in more flexible ways.
3888 @menu
3889 * Substitution Refs::           Referencing a variable with
3890                                   substitutions on the value.
3891 * Computed Names::              Computing the name of the variable to refer to.
3892 @end menu
3894 @node Substitution Refs, Computed Names,  , Advanced
3895 @subsection Substitution References
3896 @cindex modified variable reference
3897 @cindex substitution variable reference
3898 @cindex variables, modified reference
3899 @cindex variables, substitution reference
3901 @cindex variables, substituting suffix in
3902 @cindex suffix, substituting in variables
3903 A @dfn{substitution reference} substitutes the value of a variable with
3904 alterations that you specify.  It has the form
3905 @samp{$(@var{var}:@var{a}=@var{b})} (or
3906 @samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
3907 of the variable @var{var}, replace every @var{a} at the end of a word with
3908 @var{b} in that value, and substitute the resulting string.
3910 When we say ``at the end of a word'', we mean that @var{a} must appear
3911 either followed by whitespace or at the end of the value in order to be
3912 replaced; other occurrences of @var{a} in the value are unaltered.  For
3913 example:@refill
3915 @example
3916 foo := a.o b.o c.o
3917 bar := $(foo:.o=.c)
3918 @end example
3920 @noindent
3921 sets @samp{bar} to @samp{a.c b.c c.c}.  @xref{Setting, ,Setting Variables}.
3923 A substitution reference is actually an abbreviation for use of the
3924 @code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}).  We provide
3925 substitution references as well as @code{patsubst} for compatibility with
3926 other implementations of @code{make}.
3928 @findex patsubst
3929 Another type of substitution reference lets you use the full power of
3930 the @code{patsubst} function.  It has the same form
3931 @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
3932 @var{a} must contain a single @samp{%} character.  This case is
3933 equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
3934 @xref{Text Functions, ,Functions for String Substitution and Analysis},
3935 for a description of the @code{patsubst} function.@refill
3937 @example
3938 @group
3939 @exdent For example:
3941 foo := a.o b.o c.o
3942 bar := $(foo:%.o=%.c)
3943 @end group
3944 @end example
3946 @noindent
3947 sets @samp{bar} to @samp{a.c b.c c.c}.
3949 @node Computed Names,  , Substitution Refs, Advanced
3950 @subsection Computed Variable Names
3951 @cindex nested variable reference
3952 @cindex computed variable name
3953 @cindex variables, computed names
3954 @cindex variables, nested references
3955 @cindex variables, @samp{$} in name
3956 @cindex @code{$}, in variable name
3957 @cindex dollar sign (@code{$}), in variable name
3959 Computed variable names are a complicated concept needed only for
3960 sophisticated makefile programming.  For most purposes you need not
3961 consider them, except to know that making a variable with a dollar sign
3962 in its name might have strange results.  However, if you are the type
3963 that wants to understand everything, or you are actually interested in
3964 what they do, read on.
3966 Variables may be referenced inside the name of a variable.  This is
3967 called a @dfn{computed variable name} or a @dfn{nested variable
3968 reference}.  For example,
3970 @example
3971 x = y
3972 y = z
3973 a := $($(x))
3974 @end example
3976 @noindent
3977 defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
3978 to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
3979 to @samp{z}.  Here the name of the variable to reference is not stated
3980 explicitly; it is computed by expansion of @samp{$(x)}.  The reference
3981 @samp{$(x)} here is nested within the outer variable reference.
3983 The previous example shows two levels of nesting, but any number of levels
3984 is possible.  For example, here are three levels:
3986 @example
3987 x = y
3988 y = z
3989 z = u
3990 a := $($($(x)))
3991 @end example
3993 @noindent
3994 Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
3995 expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
3996 @samp{$(z)}, which becomes @samp{u}.
3998 References to recursively-expanded variables within a variable name are
3999 reexpanded in the usual fashion.  For example:
4001 @example
4002 x = $(y)
4003 y = z
4004 z = Hello
4005 a := $($(x))
4006 @end example
4008 @noindent
4009 defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
4010 which becomes @samp{$(z)} which becomes @samp{Hello}.
4012 Nested variable references can also contain modified references and
4013 function invocations (@pxref{Functions, ,Functions for Transforming Text}),
4014 just like any other reference.
4015 For example, using the @code{subst} function
4016 (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
4018 @example
4019 @group
4020 x = variable1
4021 variable2 := Hello
4022 y = $(subst 1,2,$(x))
4023 z = y
4024 a := $($($(z)))
4025 @end group
4026 @end example
4028 @noindent
4029 eventually defines @code{a} as @samp{Hello}.  It is doubtful that anyone
4030 would ever want to write a nested reference as convoluted as this one, but
4031 it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
4032 @samp{$($(subst 1,2,$(x)))}.  This gets the value @samp{variable1} from
4033 @code{x} and changes it by substitution to @samp{variable2}, so that the
4034 entire string becomes @samp{$(variable2)}, a simple variable reference
4035 whose value is @samp{Hello}.@refill
4037 A computed variable name need not consist entirely of a single variable
4038 reference.  It can contain several variable references, as well as some
4039 invariant text.  For example,
4041 @example
4042 @group
4043 a_dirs := dira dirb
4044 1_dirs := dir1 dir2
4045 @end group
4047 @group
4048 a_files := filea fileb
4049 1_files := file1 file2
4050 @end group
4052 @group
4053 ifeq "$(use_a)" "yes"
4054 a1 := a
4055 else
4056 a1 := 1
4057 endif
4058 @end group
4060 @group
4061 ifeq "$(use_dirs)" "yes"
4062 df := dirs
4063 else
4064 df := files
4065 endif
4067 dirs := $($(a1)_$(df))
4068 @end group
4069 @end example
4071 @noindent
4072 will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
4073 @code{a_files} or @code{1_files} depending on the settings of @code{use_a}
4074 and @code{use_dirs}.@refill
4076 Computed variable names can also be used in substitution references:
4078 @example
4079 @group
4080 a_objects := a.o b.o c.o
4081 1_objects := 1.o 2.o 3.o
4083 sources := $($(a1)_objects:.o=.c)
4084 @end group
4085 @end example
4087 @noindent
4088 defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
4089 depending on the value of @code{a1}.
4091 The only restriction on this sort of use of nested variable references
4092 is that they cannot specify part of the name of a function to be called.
4093 This is because the test for a recognized function name is done before
4094 the expansion of nested references.  For example,
4096 @example
4097 @group
4098 ifdef do_sort
4099 func := sort
4100 else
4101 func := strip
4102 endif
4103 @end group
4105 @group
4106 bar := a d b g q c
4107 @end group
4109 @group
4110 foo := $($(func) $(bar))
4111 @end group
4112 @end example
4114 @noindent
4115 attempts to give @samp{foo} the value of the variable @samp{sort a d b g
4116 q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
4117 as the argument to either the @code{sort} or the @code{strip} function.
4118 This restriction could be removed in the future if that change is shown
4119 to be a good idea.
4121 You can also use computed variable names in the left-hand side of a
4122 variable assignment, or in a @code{define} directive, as in:
4124 @example
4125 dir = foo
4126 $(dir)_sources := $(wildcard $(dir)/*.c)
4127 define $(dir)_print
4128 lpr $($(dir)_sources)
4129 endef
4130 @end example
4132 @noindent
4133 This example defines the variables @samp{dir}, @samp{foo_sources}, and
4134 @samp{foo_print}.
4136 Note that @dfn{nested variable references} are quite different from
4137 @dfn{recursively expanded variables}
4138 (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
4139 used together in complex ways when doing makefile programming.@refill
4141 @node Values, Setting, Advanced, Using Variables
4142 @section How Variables Get Their Values
4143 @cindex variables, how they get their values
4144 @cindex value, how a variable gets it
4146 Variables can get values in several different ways:
4148 @itemize @bullet
4149 @item
4150 You can specify an overriding value when you run @code{make}.
4151 @xref{Overriding, ,Overriding Variables}.
4153 @item
4154 You can specify a value in the makefile, either
4155 with an assignment (@pxref{Setting, ,Setting Variables}) or with a
4156 verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
4158 @item
4159 Variables in the environment become @code{make} variables.
4160 @xref{Environment, ,Variables from the Environment}.
4162 @item
4163 Several @dfn{automatic} variables are given new values for each rule.
4164 Each of these has a single conventional use.
4165 @xref{Automatic, ,Automatic Variables}.
4167 @item
4168 Several variables have constant initial values.
4169 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
4170 @end itemize
4172 @node Setting, Appending, Values, Using Variables
4173 @section Setting Variables
4174 @cindex setting variables
4175 @cindex variables, setting
4176 @cindex =
4177 @cindex :=
4179 To set a variable from the makefile, write a line starting with the
4180 variable name followed by @samp{=} or @samp{:=}.  Whatever follows the
4181 @samp{=} or @samp{:=} on the line becomes the value.  For example,
4183 @example
4184 objects = main.o foo.o bar.o utils.o
4185 @end example
4187 @noindent
4188 defines a variable named @code{objects}.  Whitespace around the variable
4189 name and immediately after the @samp{=} is ignored.
4191 Variables defined with @samp{=} are @dfn{recursively expanded} variables.
4192 Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
4193 definitions can contain variable references which will be expanded before
4194 the definition is made.  @xref{Flavors, ,The Two Flavors of Variables}.
4196 The variable name may contain function and variable references, which
4197 are expanded when the line is read to find the actual variable name to use.
4199 There is no limit on the length of the value of a variable except the
4200 amount of swapping space on the computer.  When a variable definition is
4201 long, it is a good idea to break it into several lines by inserting
4202 backslash-newline at convenient places in the definition.  This will not
4203 affect the functioning of @code{make}, but it will make the makefile easier
4204 to read.
4206 Most variable names are considered to have the empty string as a value if
4207 you have never set them.  Several variables have built-in initial values
4208 that are not empty, but you can set them in the usual ways
4209 (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
4210 Several special variables are set
4211 automatically to a new value for each rule; these are called the
4212 @dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}).
4214 @node Appending, Override Directive, Setting, Using Variables
4215 @section Appending More Text to Variables
4216 @cindex +=
4217 @cindex appending to variables
4218 @cindex variables, appending to
4220 Often it is useful to add more text to the value of a variable already defined.
4221 You do this with a line containing @samp{+=}, like this:
4223 @example
4224 objects += another.o
4225 @end example
4227 @noindent
4228 This takes the value of the variable @code{objects}, and adds the text
4229 @samp{another.o} to it (preceded by a single space).  Thus:
4231 @example
4232 objects = main.o foo.o bar.o utils.o
4233 objects += another.o
4234 @end example
4236 @noindent
4237 sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
4239 Using @samp{+=} is similar to:
4241 @example
4242 objects = main.o foo.o bar.o utils.o
4243 objects := $(objects) another.o
4244 @end example
4246 @noindent
4247 but differs in ways that become important when you use more complex values.
4249 When the variable in question has not been defined before, @samp{+=}
4250 acts just like normal @samp{=}: it defines a recursively-expanded
4251 variable.  However, when there @emph{is} a previous definition, exactly
4252 what @samp{+=} does depends on what flavor of variable you defined
4253 originally.  @xref{Flavors, ,The Two Flavors of Variables}, for an
4254 explanation of the two flavors of variables.
4256 When you add to a variable's value with @samp{+=}, @code{make} acts
4257 essentially as if you had included the extra text in the initial
4258 definition of the variable.  If you defined it first with @samp{:=},
4259 making it a simply-expanded variable, @samp{+=} adds to that
4260 simply-expanded definition, and expands the new text before appending it
4261 to the old value just as @samp{:=} does
4262 (@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
4263 In fact,
4265 @example
4266 variable := value
4267 variable += more
4268 @end example
4270 @noindent
4271 is exactly equivalent to:
4273 @noindent
4274 @example
4275 variable := value
4276 variable := $(variable) more
4277 @end example
4279 On the other hand, when you use @samp{+=} with a variable that you defined
4280 first to be recursively-expanded using plain @samp{=}, @code{make} does
4281 something a bit different.  Recall that when you define a
4282 recursively-expanded variable, @code{make} does not expand the value you set
4283 for variable and function references immediately.  Instead it stores the text
4284 verbatim, and saves these variable and function references to be expanded
4285 later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
4286 of Variables}).  When you use @samp{+=} on a recursively-expanded variable,
4287 it is this unexpanded text to which @code{make} appends the new text you
4288 specify.
4290 @example
4291 @group
4292 variable = value
4293 variable += more
4294 @end group
4295 @end example
4297 @noindent
4298 is roughly equivalent to:
4300 @example
4301 @group
4302 temp = value
4303 variable = $(temp) more
4304 @end group
4305 @end example
4307 @noindent
4308 except that of course it never defines a variable called @code{temp}.
4309 The importance of this comes when the variable's old value contains
4310 variable references.  Take this common example:
4312 @example
4313 CFLAGS = $(includes) -O
4314 @dots{}
4315 CFLAGS += -pg # enable profiling
4316 @end example
4318 @noindent
4319 The first line defines the @code{CFLAGS} variable with a reference to another
4320 variable, @code{includes}.  (@code{CFLAGS} is used by the rules for C
4321 compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
4322 Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
4323 variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
4324 @code{make} processes the definition of @code{CFLAGS}.  Thus, @code{includes}
4325 need not be defined yet for its value to take effect.  It only has to be
4326 defined before any reference to @code{CFLAGS}.  If we tried to append to the
4327 value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
4329 @example
4330 CFLAGS := $(CFLAGS) -pg # enable profiling
4331 @end example
4333 @noindent
4334 This is pretty close, but not quite what we want.  Using @samp{:=}
4335 redefines @code{CFLAGS} as a simply-expanded variable; this means
4336 @code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
4337 variable.  If @code{includes} is not yet defined, we get @w{@samp{ -O
4338 -pg}}, and a later definition of @code{includes} will have no effect.
4339 Conversely, by using @samp{+=} we set @code{CFLAGS} to the
4340 @emph{unexpanded} value @w{@samp{$(includes) -O -pg}}.  Thus we preserve
4341 the reference to @code{includes}, so if that variable gets defined at
4342 any later point, a reference like @samp{$(CFLAGS)} still uses its
4343 value.
4345 @node Override Directive, Defining, Appending, Using Variables
4346 @section The @code{override} Directive
4347 @findex override
4348 @cindex overriding with @code{override}
4349 @cindex variables, overriding
4351 If a variable has been set with a command argument
4352 (@pxref{Overriding, ,Overriding Variables}),
4353 then ordinary assignments in the makefile are ignored.  If you want to set
4354 the variable in the makefile even though it was set with a command
4355 argument, you can use an @code{override} directive, which is a line that
4356 looks like this:@refill
4358 @example
4359 override @var{variable} = @var{value}
4360 @end example
4362 @noindent
4365 @example
4366 override @var{variable} := @var{value}
4367 @end example
4369 To append more text to a variable defined on the command line, use:
4371 @example
4372 override @var{variable} += @var{more text}
4373 @end example
4375 @noindent
4376 @xref{Appending, ,Appending More Text to Variables}.
4378 The @code{override} directive was not invented for escalation in the war
4379 between makefiles and command arguments.  It was invented so you can alter
4380 and add to values that the user specifies with command arguments.
4382 For example, suppose you always want the @samp{-g} switch when you run the
4383 C compiler, but you would like to allow the user to specify the other
4384 switches with a command argument just as usual.  You could use this
4385 @code{override} directive:
4387 @example
4388 override CFLAGS += -g
4389 @end example
4391 You can also use @code{override} directives with @code{define} directives.
4392 This is done as you might expect:
4394 @example
4395 override define foo
4397 endef
4398 @end example
4400 @noindent
4401 @iftex
4402 See the next section for information about @code{define}.
4403 @end iftex
4404 @ifinfo
4405 @xref{Defining, ,Defining Variables Verbatim}.
4406 @end ifinfo
4408 @node Defining, Environment, Override Directive, Using Variables
4409 @section Defining Variables Verbatim
4410 @findex define
4411 @findex endef
4412 @cindex verbatim variable definition
4413 @cindex defining variables verbatim
4414 @cindex variables, defining verbatim
4416 Another way to set the value of a variable is to use the @code{define}
4417 directive.  This directive has an unusual syntax which allows newline
4418 characters to be included in the value, which is convenient for defining
4419 canned sequences of commands
4420 (@pxref{Sequences, ,Defining Canned Command Sequences}).
4422 The @code{define} directive is followed on the same line by the name of the
4423 variable and nothing more.  The value to give the variable appears on the
4424 following lines.  The end of the value is marked by a line containing just
4425 the word @code{endef}.  Aside from this difference in syntax, @code{define}
4426 works just like @samp{=}: it creates a recursively-expanded variable
4427 (@pxref{Flavors, ,The Two Flavors of Variables}).
4428 The variable name may contain function and variable references, which
4429 are expanded when the directive is read to find the actual variable name
4430 to use.
4432 @example
4433 define two-lines
4434 echo foo
4435 echo $(bar)
4436 endef
4437 @end example
4439 The value in an ordinary assignment cannot contain a newline; but the
4440 newlines that separate the lines of the value in a @code{define} become
4441 part of the variable's value (except for the final newline which precedes
4442 the @code{endef} and is not considered part of the value).@refill
4444 @need 800
4445 The previous example is functionally equivalent to this:
4447 @example
4448 two-lines = echo foo; echo $(bar)
4449 @end example
4451 @noindent
4452 since two commands separated by semicolon behave much like two separate
4453 shell commands.  However, note that using two separate lines means
4454 @code{make} will invoke the shell twice, running an independent subshell
4455 for each line.  @xref{Execution, ,Command Execution}.
4457 If you want variable definitions made with @code{define} to take
4458 precedence over command-line variable definitions, you can use the
4459 @code{override} directive together with @code{define}:
4461 @example
4462 override define two-lines
4464 $(bar)
4465 endef
4466 @end example
4468 @noindent
4469 @xref{Override Directive, ,The @code{override} Directive}.
4471 @node Environment,  , Defining, Using Variables
4472 @section Variables from the Environment
4474 @cindex variables, environment
4475 @cindex environment
4476 Variables in @code{make} can come from the environment in which
4477 @code{make} is run.  Every environment variable that @code{make} sees when
4478 it starts up is transformed into a @code{make} variable with the same name
4479 and value.  But an explicit assignment in the makefile, or with a command
4480 argument, overrides the environment.  (If the @samp{-e} flag is specified,
4481 then values from the environment override assignments in the makefile.
4482 @xref{Options Summary, ,Summary of Options}.
4483 But this is not recommended practice.)
4485 Thus, by setting the variable @code{CFLAGS} in your environment, you can
4486 cause all C compilations in most makefiles to use the compiler switches you
4487 prefer.  This is safe for variables with standard or conventional meanings
4488 because you know that no makefile will use them for other things.  (But
4489 this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
4490 and therefore are not affected by the value in the environment.)
4492 When @code{make} is invoked recursively, variables defined in the
4493 outer invocation can be passed to inner invocations through the
4494 environment (@pxref{Recursion, ,Recursive Use of @code{make}}).  By
4495 default, only variables that came from the environment or the command
4496 line are passed to recursive invocations.  You can use the
4497 @code{export} directive to pass other variables.
4498 @xref{Variables/Recursion, , Communicating Variables to a
4499 Sub-@code{make}}, for full details.
4501 Other use of variables from the environment is not recommended.  It is not
4502 wise for makefiles to depend for their functioning on environment variables
4503 set up outside their control, since this would cause different users to get
4504 different results from the same makefile.  This is against the whole
4505 purpose of most makefiles.
4507 Such problems would be especially likely with the variable @code{SHELL},
4508 which is normally present in the environment to specify the user's choice
4509 of interactive shell.  It would be very undesirable for this choice to
4510 affect @code{make}.  So @code{make} ignores the environment value of
4511 @code{SHELL}.@refill
4513 @node Conditionals, Functions, Using Variables, Top
4514 @chapter Conditional Parts of Makefiles
4516 @cindex conditionals
4517 A @dfn{conditional} causes part of a makefile to be obeyed or ignored
4518 depending on the values of variables.  Conditionals can compare the
4519 value of one variable to another, or the value of a variable to
4520 a constant string.  Conditionals control what @code{make} actually
4521 ``sees'' in the makefile, so they @emph{cannot} be used to control shell
4522 commands at the time of execution.@refill
4524 @menu
4525 * Conditional Example::         Example of a conditional
4526 * Conditional Syntax::          The syntax of conditionals.
4527 * Testing Flags::               Conditionals that test flags.
4528 @end menu
4530 @node Conditional Example, Conditional Syntax,  , Conditionals
4531 @section Example of a Conditional
4533 The following example of a conditional tells @code{make} to use one set
4534 of libraries if the @code{CC} variable is @samp{gcc}, and a different
4535 set of libraries otherwise.  It works by controlling which of two
4536 command lines will be used as the command for a rule.  The result is
4537 that @samp{CC=gcc} as an argument to @code{make} changes not only which
4538 compiler is used but also which libraries are linked.
4540 @example
4541 libs_for_gcc = -lgnu
4542 normal_libs =
4544 foo: $(objects)
4545 ifeq ($(CC),gcc)
4546         $(CC) -o foo $(objects) $(libs_for_gcc)
4547 else
4548         $(CC) -o foo $(objects) $(normal_libs)
4549 endif
4550 @end example
4552 This conditional uses three directives: one @code{ifeq}, one @code{else}
4553 and one @code{endif}.
4555 The @code{ifeq} directive begins the conditional, and specifies the
4556 condition.  It contains two arguments, separated by a comma and surrounded
4557 by parentheses.  Variable substitution is performed on both arguments and
4558 then they are compared.  The lines of the makefile following the
4559 @code{ifeq} are obeyed if the two arguments match; otherwise they are
4560 ignored.
4562 The @code{else} directive causes the following lines to be obeyed if the
4563 previous conditional failed.  In the example above, this means that the
4564 second alternative linking command is used whenever the first alternative
4565 is not used.  It is optional to have an @code{else} in a conditional.
4567 The @code{endif} directive ends the conditional.  Every conditional must
4568 end with an @code{endif}.  Unconditional makefile text follows.
4570 As this example illustrates, conditionals work at the textual level:
4571 the lines of the conditional are treated as part of the makefile, or
4572 ignored, according to the condition.  This is why the larger syntactic
4573 units of the makefile, such as rules, may cross the beginning or the
4574 end of the conditional.
4576 When the variable @code{CC} has the value @samp{gcc}, the above example has
4577 this effect:
4579 @example
4580 foo: $(objects)
4581         $(CC) -o foo $(objects) $(libs_for_gcc)
4582 @end example
4584 @noindent
4585 When the variable @code{CC} has any other value, the effect is this:
4587 @example
4588 foo: $(objects)
4589         $(CC) -o foo $(objects) $(normal_libs)
4590 @end example
4592 Equivalent results can be obtained in another way by conditionalizing a
4593 variable assignment and then using the variable unconditionally:
4595 @example
4596 libs_for_gcc = -lgnu
4597 normal_libs =
4599 ifeq ($(CC),gcc)
4600   libs=$(libs_for_gcc)
4601 else
4602   libs=$(normal_libs)
4603 endif
4605 foo: $(objects)
4606         $(CC) -o foo $(objects) $(libs)
4607 @end example
4609 @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
4610 @section Syntax of Conditionals
4611 @findex ifdef
4612 @findex ifeq
4613 @findex ifndef
4614 @findex ifneq
4615 @findex else
4616 @findex endif
4618 The syntax of a simple conditional with no @code{else} is as follows:
4620 @example
4621 @var{conditional-directive}
4622 @var{text-if-true}
4623 endif
4624 @end example
4626 @noindent
4627 The @var{text-if-true} may be any lines of text, to be considered as part
4628 of the makefile if the condition is true.  If the condition is false, no
4629 text is used instead.
4631 The syntax of a complex conditional is as follows:
4633 @example
4634 @var{conditional-directive}
4635 @var{text-if-true}
4636 else
4637 @var{text-if-false}
4638 endif
4639 @end example
4641 @noindent
4642 If the condition is true, @var{text-if-true} is used; otherwise,
4643 @var{text-if-false} is used instead.  The @var{text-if-false} can be any
4644 number of lines of text.
4646 The syntax of the @var{conditional-directive} is the same whether the
4647 conditional is simple or complex.  There are four different directives that
4648 test different conditions.  Here is a table of them:
4650 @table @code
4651 @item ifeq (@var{arg1}, @var{arg2})
4652 @itemx ifeq '@var{arg1}' '@var{arg2}'
4653 @itemx ifeq "@var{arg1}" "@var{arg2}"
4654 @itemx ifeq "@var{arg1}" '@var{arg2}'
4655 @itemx ifeq '@var{arg1}' "@var{arg2}"
4656 Expand all variable references in @var{arg1} and @var{arg2} and
4657 compare them.  If they are identical, the @var{text-if-true} is
4658 effective; otherwise, the @var{text-if-false}, if any, is effective.
4660 Often you want to test if a variable has a non-empty value.  When the
4661 value results from complex expansions of variables and functions,
4662 expansions you would consider empty may actually contain whitespace
4663 characters and thus are not seen as empty.  However, you can use the
4664 @code{strip} function (@pxref{Text Functions}) to avoid interpreting
4665 whitespace as a non-empty value.  For example:
4667 @example
4668 @group
4669 ifeq ($(strip $(foo)),)
4670 @var{text-if-empty}
4671 endif
4672 @end group
4673 @end example
4675 @noindent
4676 will evaluate @var{text-if-empty} even if the expansion of
4677 @code{$(foo)} contains whitespace characters.
4679 @item ifneq (@var{arg1}, @var{arg2})
4680 @itemx ifneq '@var{arg1}' '@var{arg2}'
4681 @itemx ifneq "@var{arg1}" "@var{arg2}"
4682 @itemx ifneq "@var{arg1}" '@var{arg2}'
4683 @itemx ifneq '@var{arg1}' "@var{arg2}"
4684 Expand all variable references in @var{arg1} and @var{arg2} and
4685 compare them.  If they are different, the @var{text-if-true} is
4686 effective; otherwise, the @var{text-if-false}, if any, is effective.
4688 @item ifdef @var{variable-name}
4689 If the variable @var{variable-name} has a non-empty value, the
4690 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4691 if any, is effective.  Variables that have never been defined have an
4692 empty value.
4694 Note that @code{ifdef} only tests whether a variable has a value.  It
4695 does not expand the variable to see if that value is nonempty.
4696 Consequently, tests using @code{ifdef} return true for all definitions
4697 except those like @code{foo =}.  To test for an empty value, use
4698 @w{@code{ifeq ($(foo),)}}.  For example,
4700 @example
4701 bar =
4702 foo = $(bar)
4703 ifdef foo
4704 frobozz = yes
4705 else
4706 frobozz = no
4707 endif
4708 @end example
4710 @noindent
4711 sets @samp{frobozz} to @samp{yes}, while:
4713 @example
4714 foo =
4715 ifdef foo
4716 frobozz = yes
4717 else
4718 frobozz = no
4719 endif
4720 @end example
4722 @noindent
4723 sets @samp{frobozz} to @samp{no}.
4725 @item ifndef @var{variable-name}
4726 If the variable @var{variable-name} has an empty value, the
4727 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4728 if any, is effective.
4729 @end table
4731 Extra spaces are allowed and ignored at the beginning of the conditional
4732 directive line, but a tab is not allowed.  (If the line begins with a tab,
4733 it will be considered a command for a rule.)  Aside from this, extra spaces
4734 or tabs may be inserted with no effect anywhere except within the directive
4735 name or within an argument.  A comment starting with @samp{#} may appear at
4736 the end of the line.
4738 The other two directives that play a part in a conditional are @code{else}
4739 and @code{endif}.  Each of these directives is written as one word, with no
4740 arguments.  Extra spaces are allowed and ignored at the beginning of the
4741 line, and spaces or tabs at the end.  A comment starting with @samp{#} may
4742 appear at the end of the line.
4744 Conditionals affect which lines of the makefile @code{make} uses.  If
4745 the condition is true, @code{make} reads the lines of the
4746 @var{text-if-true} as part of the makefile; if the condition is false,
4747 @code{make} ignores those lines completely.  It follows that syntactic
4748 units of the makefile, such as rules, may safely be split across the
4749 beginning or the end of the conditional.@refill
4751 @code{make} evaluates conditionals when it reads a makefile.
4752 Consequently, you cannot use automatic variables in the tests of
4753 conditionals because they are not defined until commands are run
4754 (@pxref{Automatic, , Automatic Variables}).
4756 To prevent intolerable confusion, it is not permitted to start a
4757 conditional in one makefile and end it in another.  However, you may
4758 write an @code{include} directive within a conditional, provided you do
4759 not attempt to terminate the conditional inside the included file.
4761 @node Testing Flags,  , Conditional Syntax, Conditionals
4762 @section Conditionals that Test Flags
4764 You can write a conditional that tests @code{make} command flags such as
4765 @samp{-t} by using the variable @code{MAKEFLAGS} together with the
4766 @code{findstring} function
4767 (@pxref{Text Functions, , Functions for String Substitution and Analysis}).
4768 This is useful when @code{touch} is not enough to make a file appear up
4769 to date.
4771 The @code{findstring} function determines whether one string appears as a
4772 substring of another.  If you want to test for the @samp{-t} flag,
4773 use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
4774 the other.
4776 For example, here is how to arrange to use @samp{ranlib -t} to finish
4777 marking an archive file up to date:
4779 @example
4780 archive.a: @dots{}
4781 ifneq (,$(findstring t,$(MAKEFLAGS)))
4782         +touch archive.a
4783         +ranlib -t archive.a
4784 else
4785         ranlib archive.a
4786 endif
4787 @end example
4789 @noindent
4790 The @samp{+} prefix marks those command lines as ``recursive'' so
4791 that they will be executed despite use of the @samp{-t} flag.
4792 @xref{Recursion, ,Recursive Use of @code{make}}.
4794 @node Functions, Running, Conditionals, Top
4795 @chapter Functions for Transforming Text
4796 @cindex functions
4798 @dfn{Functions} allow you to do text processing in the makefile to compute
4799 the files to operate on or the commands to use.  You use a function in a
4800 @dfn{function call}, where you give the name of the function and some text
4801 (the @dfn{arguments}) for the function to operate on.  The result of the
4802 function's processing is substituted into the makefile at the point of the
4803 call, just as a variable might be substituted.
4805 @menu
4806 * Syntax of Functions::         How to write a function call.
4807 * Text Functions::              General-purpose text manipulation functions.
4808 * Filename Functions::          Functions for manipulating file names.
4809 * Foreach Function::            Repeat some text with controlled variation.
4810 * Origin Function::             Find where a variable got its value.
4811 * Shell Function::              Substitute the output of a shell command.
4812 @end menu
4814 @node Syntax of Functions, Text Functions,  , Functions
4815 @section Function Call Syntax
4816 @cindex @code{$}, in function call
4817 @cindex dollar sign (@code{$}), in function call
4818 @cindex arguments of functions
4819 @cindex functions, syntax of
4821 A function call resembles a variable reference.  It looks like this:
4823 @example
4824 $(@var{function} @var{arguments})
4825 @end example
4827 @noindent
4828 or like this:
4830 @example
4831 $@{@var{function} @var{arguments}@}
4832 @end example
4834 Here @var{function} is a function name; one of a short list of names that
4835 are part of @code{make}.  There is no provision for defining new functions.
4837 The @var{arguments} are the arguments of the function.  They are
4838 separated from the function name by one or more spaces or tabs, and if
4839 there is more than one argument, then they are separated by commas.
4840 Such whitespace and commas are not part of an argument's value.  The
4841 delimiters which you use to surround the function call, whether
4842 parentheses or braces, can appear in an argument only in matching pairs;
4843 the other kind of delimiters may appear singly.  If the arguments
4844 themselves contain other function calls or variable references, it is
4845 wisest to use the same kind of delimiters for all the references; write
4846 @w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}.  This
4847 is because it is clearer, and because only one type of delimiter is
4848 matched to find the end of the reference.
4850 The text written for each argument is processed by substitution of
4851 variables and function calls to produce the argument value, which
4852 is the text on which the function acts.  The substitution is done in the
4853 order in which the arguments appear.
4855 Commas and unmatched parentheses or braces cannot appear in the text of an
4856 argument as written; leading spaces cannot appear in the text of the first
4857 argument as written.  These characters can be put into the argument value
4858 by variable substitution.  First define variables @code{comma} and
4859 @code{space} whose values are isolated comma and space characters, then
4860 substitute these variables where such characters are wanted, like this:
4862 @example
4863 @group
4864 comma:= ,
4865 empty:=
4866 space:= $(empty) $(empty)
4867 foo:= a b c
4868 bar:= $(subst $(space),$(comma),$(foo))
4869 # @r{bar is now `a,b,c'.}
4870 @end group
4871 @end example
4873 @noindent
4874 Here the @code{subst} function replaces each space with a comma, through
4875 the value of @code{foo}, and substitutes the result.
4877 @node Text Functions, Filename Functions, Syntax of Functions, Functions
4878 @section Functions for String Substitution and Analysis
4879 @cindex functions, for text
4881 Here are some functions that operate on strings:
4883 @table @code
4884 @item $(subst @var{from},@var{to},@var{text})
4885 @findex subst
4886 Performs a textual replacement on the text @var{text}: each occurrence
4887 of @var{from} is replaced by @var{to}.  The result is substituted for
4888 the function call.  For example,
4890 @example
4891 $(subst ee,EE,feet on the street)
4892 @end example
4894 substitutes the string @samp{fEEt on the strEEt}.
4896 @item $(patsubst @var{pattern},@var{replacement},@var{text})
4897 @findex patsubst
4898 Finds whitespace-separated words in @var{text} that match
4899 @var{pattern} and replaces them with @var{replacement}.  Here
4900 @var{pattern} may contain a @samp{%} which acts as a wildcard,
4901 matching any number of any characters within a word.  If
4902 @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
4903 by the text that matched the @samp{%} in @var{pattern}.@refill
4905 @cindex @code{%}, quoting in @code{patsubst}
4906 @cindex @code{%}, quoting with @code{\} (backslash)
4907 @cindex @code{\} (backslash), to quote @code{%}
4908 @cindex backslash (@code{\}), to quote @code{%}
4909 @cindex quoting @code{%}, in @code{patsubst}
4910 @samp{%} characters in @code{patsubst} function invocations can be
4911 quoted with preceding backslashes (@samp{\}).  Backslashes that would
4912 otherwise quote @samp{%} characters can be quoted with more backslashes.
4913 Backslashes that quote @samp{%} characters or other backslashes are
4914 removed from the pattern before it is compared file names or has a stem
4915 substituted into it.  Backslashes that are not in danger of quoting
4916 @samp{%} characters go unmolested.  For example, the pattern
4917 @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
4918 operative @samp{%} character, and @samp{pattern\\} following it.  The
4919 final two backslashes are left alone because they cannot affect any
4920 @samp{%} character.@refill
4922 Whitespace between words is folded into single space characters;
4923 leading and trailing whitespace is discarded.
4925 For example,
4927 @example
4928 $(patsubst %.c,%.o,x.c.c bar.c)
4929 @end example
4931 @noindent
4932 produces the value @samp{x.c.o bar.o}.
4934 Substitution references (@pxref{Substitution Refs, ,Substitution
4935 References}) are a simpler way to get the effect of the @code{patsubst}
4936 function:
4938 @example
4939 $(@var{var}:@var{pattern}=@var{replacement})
4940 @end example
4942 @noindent
4943 is equivalent to
4945 @example
4946 $(patsubst @var{pattern},@var{replacement},$(@var{var}))
4947 @end example
4949 The second shorthand simplifies one of the most common uses of
4950 @code{patsubst}: replacing the suffix at the end of file names.
4952 @example
4953 $(@var{var}:@var{suffix}=@var{replacement})
4954 @end example
4956 @noindent
4957 is equivalent to
4959 @example
4960 $(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
4961 @end example
4963 @noindent
4964 For example, you might have a list of object files:
4966 @example
4967 objects = foo.o bar.o baz.o
4968 @end example
4970 @noindent
4971 To get the list of corresponding source files, you could simply write:
4973 @example
4974 $(objects:.o=.c)
4975 @end example
4977 @noindent
4978 instead of using the general form:
4980 @example
4981 $(patsubst %.o,%.c,$(objects))
4982 @end example
4984 @item $(strip @var{string})
4985 @cindex stripping whitespace
4986 @cindex whitespace, stripping
4987 @cindex spaces, stripping
4988 @findex strip
4989 Removes leading and trailing whitespace from @var{string} and replaces
4990 each internal sequence of one or more whitespace characters with a
4991 single space.  Thus, @samp{$(strip a b  c )} results in @w{@samp{a b c}}.
4993 The function @code{strip} can be very useful when used in conjunction
4994 with conditionals.  When comparing something with the empty string
4995 @samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
4996 just whitespace to match the empty string (@pxref{Conditionals}).
4998 Thus, the following may fail to have the desired results:
5000 @example
5001 .PHONY: all
5002 ifneq   "$(needs_made)" ""
5003 all: $(needs_made)
5004 else
5005 all:;@@echo 'Nothing to make!'
5006 endif
5007 @end example
5009 @noindent
5010 Replacing the variable reference @w{@samp{$(needs_made)}} with the
5011 function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
5012 directive would make it more robust.@refill
5014 @item $(findstring @var{find},@var{in})
5015 @findex findstring
5016 @cindex searching for strings
5017 @cindex finding strings
5018 @cindex strings, searching for
5019 Searches @var{in} for an occurrence of @var{find}.  If it occurs, the
5020 value is @var{find}; otherwise, the value is empty.  You can use this
5021 function in a conditional to test for the presence of a specific
5022 substring in a given string.  Thus, the two examples,
5024 @example
5025 $(findstring a,a b c)
5026 $(findstring a,b c)
5027 @end example
5029 @noindent
5030 produce the values @samp{a} and @samp{} (the empty string),
5031 respectively.  @xref{Testing Flags}, for a practical application of
5032 @code{findstring}.@refill
5034 @need 750
5035 @findex filter
5036 @cindex filtering words
5037 @cindex words, filtering
5038 @item $(filter @var{pattern}@dots{},@var{text})
5039 Removes all whitespace-separated words in @var{text} that do
5040 @emph{not} match any of the @var{pattern} words, returning only
5041 matching words.  The patterns are written using @samp{%}, just like
5042 the patterns used in the @code{patsubst} function above.@refill
5044 The @code{filter} function can be used to separate out different types
5045 of strings (such as file names) in a variable.  For example:
5047 @example
5048 sources := foo.c bar.c baz.s ugh.h
5049 foo: $(sources)
5050         cc $(filter %.c %.s,$(sources)) -o foo
5051 @end example
5053 @noindent
5054 says that @file{foo} depends of @file{foo.c}, @file{bar.c},
5055 @file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
5056 @file{baz.s} should be specified in the command to the
5057 compiler.@refill
5059 @item $(filter-out @var{pattern}@dots{},@var{text})
5060 @findex filter-out
5061 @cindex filtering out words
5062 @cindex words, filtering out
5063 Removes all whitespace-separated words in @var{text} that @emph{do}
5064 match the @var{pattern} words, returning only the words that @emph{do
5065 not} match.  This is the exact opposite of the @code{filter}
5066 function.@refill
5068 For example, given:
5070 @example
5071 @group
5072 objects=main1.o foo.o main2.o bar.o
5073 mains=main1.o main2.o
5074 @end group
5075 @end example
5077 @noindent
5078 the following generates a list which contains all the object files not
5079 in @samp{mains}:
5081 @example
5082 $(filter-out $(mains),$(objects))
5083 @end example
5085 @need 1500
5086 @findex sort
5087 @cindex sorting words
5088 @item $(sort @var{list})
5089 Sorts the words of @var{list} in lexical order, removing duplicate
5090 words.  The output is a list of words separated by single spaces.
5091 Thus,
5093 @example
5094 $(sort foo bar lose)
5095 @end example
5097 @noindent
5098 returns the value @samp{bar foo lose}.
5100 @cindex removing duplicate words
5101 @cindex duplicate words, removing
5102 @cindex words, removing duplicates
5103 Incidentally, since @code{sort} removes duplicate words, you can use
5104 it for this purpose even if you don't care about the sort order.
5105 @end table
5107 Here is a realistic example of the use of @code{subst} and
5108 @code{patsubst}.  Suppose that a makefile uses the @code{VPATH} variable
5109 to specify a list of directories that @code{make} should search for
5110 dependency files
5111 (@pxref{General Search, , @code{VPATH} Search Path for All Dependencies}).
5112 This example shows how to
5113 tell the C compiler to search for header files in the same list of
5114 directories.@refill
5116 The value of @code{VPATH} is a list of directories separated by colons,
5117 such as @samp{src:../headers}.  First, the @code{subst} function is used to
5118 change the colons to spaces:
5120 @example
5121 $(subst :, ,$(VPATH))
5122 @end example
5124 @noindent
5125 This produces @samp{src ../headers}.  Then @code{patsubst} is used to turn
5126 each directory name into a @samp{-I} flag.  These can be added to the
5127 value of the variable @code{CFLAGS}, which is passed automatically to the C
5128 compiler, like this:
5130 @example
5131 override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
5132 @end example
5134 @noindent
5135 The effect is to append the text @samp{-Isrc -I../headers} to the
5136 previously given value of @code{CFLAGS}.  The @code{override} directive is
5137 used so that the new value is assigned even if the previous value of
5138 @code{CFLAGS} was specified with a command argument (@pxref{Override
5139 Directive, , The @code{override} Directive}).
5141 @node Filename Functions, Foreach Function, Text Functions, Functions
5142 @section Functions for File Names
5143 @cindex functions, for file names
5144 @cindex file name functions
5146 Several of the built-in expansion functions relate specifically to
5147 taking apart file names or lists of file names.
5149 Each of the following functions performs a specific transformation on a
5150 file name.  The argument of the function is regarded as a series of file
5151 names, separated by whitespace.  (Leading and trailing whitespace is
5152 ignored.)  Each file name in the series is transformed in the same way and
5153 the results are concatenated with single spaces between them.
5155 @table @code
5156 @item $(dir @var{names}@dots{})
5157 @findex dir
5158 @cindex directory part
5159 @cindex file name, directory part
5160 Extracts the directory-part of each file name in @var{names}.  The
5161 directory-part of the file name is everything up through (and
5162 including) the last slash in it.  If the file name contains no slash,
5163 the directory part is the string @samp{./}.  For example,
5165 @example
5166 $(dir src/foo.c hacks)
5167 @end example
5169 @noindent
5170 produces the result @samp{src/ ./}.
5172 @item $(notdir @var{names}@dots{})
5173 @findex notdir
5174 @cindex file name, nondirectory part
5175 @cindex nondirectory part
5176 Extracts all but the directory-part of each file name in @var{names}.
5177 If the file name contains no slash, it is left unchanged.  Otherwise,
5178 everything through the last slash is removed from it.
5180 A file name that ends with a slash becomes an empty string.  This is
5181 unfortunate, because it means that the result does not always have the
5182 same number of whitespace-separated file names as the argument had;
5183 but we do not see any other valid alternative.
5185 For example,
5187 @example
5188 $(notdir src/foo.c hacks)
5189 @end example
5191 @noindent
5192 produces the result @samp{foo.c hacks}.
5194 @item $(suffix @var{names}@dots{})
5195 @findex suffix
5196 @cindex suffix, function to find
5197 @cindex file name suffix
5198 Extracts the suffix of each file name in @var{names}.  If the file name
5199 contains a period, the suffix is everything starting with the last
5200 period.  Otherwise, the suffix is the empty string.  This frequently
5201 means that the result will be empty when @var{names} is not, and if
5202 @var{names} contains multiple file names, the result may contain fewer
5203 file names.
5205 For example,
5207 @example
5208 $(suffix src/foo.c hacks)
5209 @end example
5211 @noindent
5212 produces the result @samp{.c}.
5214 @item $(basename @var{names}@dots{})
5215 @findex basename
5216 @cindex basename
5217 @cindex file name, basename of
5218 Extracts all but the suffix of each file name in @var{names}.  If the
5219 file name contains a period, the basename is everything starting up to
5220 (and not including) the last period.  Otherwise, the basename is the
5221 entire file name.  For example,
5223 @example
5224 $(basename src/foo.c hacks)
5225 @end example
5227 @noindent
5228 produces the result @samp{src/foo hacks}.
5230 @c plural convention with dots (be consistent)
5231 @item $(addsuffix @var{suffix},@var{names}@dots{})
5232 @findex addsuffix
5233 @cindex suffix, adding
5234 @cindex file name suffix, adding
5235 The argument @var{names} is regarded as a series of names, separated
5236 by whitespace; @var{suffix} is used as a unit.  The value of
5237 @var{suffix} is appended to the end of each individual name and the
5238 resulting larger names are concatenated with single spaces between
5239 them.  For example,
5241 @example
5242 $(addsuffix .c,foo bar)
5243 @end example
5245 @noindent
5246 produces the result @samp{foo.c bar.c}.
5248 @item $(addprefix @var{prefix},@var{names}@dots{})
5249 @findex addprefix
5250 @cindex prefix, adding
5251 @cindex file name prefix, adding
5252 The argument @var{names} is regarded as a series of names, separated
5253 by whitespace; @var{prefix} is used as a unit.  The value of
5254 @var{prefix} is prepended to the front of each individual name and the
5255 resulting larger names are concatenated with single spaces between
5256 them.  For example,
5258 @example
5259 $(addprefix src/,foo bar)
5260 @end example
5262 @noindent
5263 produces the result @samp{src/foo src/bar}.
5265 @item $(join @var{list1},@var{list2})
5266 @findex join
5267 @cindex joining lists of words
5268 @cindex words, joining lists
5269 Concatenates the two arguments word by word: the two first words (one
5270 from each argument) concatenated form the first word of the result, the
5271 two second words form the second word of the result, and so on.  So the
5272 @var{n}th word of the result comes from the @var{n}th word of each
5273 argument.  If one argument has more words that the other, the extra
5274 words are copied unchanged into the result.
5276 For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
5278 Whitespace between the words in the lists is not preserved; it is
5279 replaced with a single space.
5281 This function can merge the results of the @code{dir} and
5282 @code{notdir} functions, to produce the original list of files which
5283 was given to those two functions.@refill
5285 @item $(word @var{n},@var{text})
5286 @findex word
5287 @cindex words, selecting
5288 @cindex selecting words
5289 Returns the @var{n}th word of @var{text}.  The legitimate values of
5290 @var{n} start from 1.  If @var{n} is bigger than the number of words
5291 in @var{text}, the value is empty.  For example,
5293 @example
5294 $(word 2, foo bar baz)
5295 @end example
5297 @noindent
5298 returns @samp{bar}.
5300 @c Following item phrased to prevent overfull hbox.  --RJC 17 Jul 92
5301 @item $(words @var{text})
5302 @findex words
5303 @cindex words, finding number
5304 Returns the number of words in @var{text}.
5305 Thus, the last word of @var{text} is
5306 @w{@code{$(word $(words @var{text}),@var{text})}}.@refill
5308 @item $(firstword @var{names}@dots{})
5309 @findex firstword
5310 @cindex words, extracting first
5311 The argument @var{names} is regarded as a series of names, separated
5312 by whitespace.  The value is the first name in the series.  The rest
5313 of the names are ignored.
5315 For example,
5317 @example
5318 $(firstword foo bar)
5319 @end example
5321 @noindent
5322 produces the result @samp{foo}.  Although @code{$(firstword
5323 @var{text})} is the same as @code{$(word 1,@var{text})}, the
5324 @code{firstword} function is retained for its simplicity.@refill
5326 @item $(wildcard @var{pattern})
5327 @findex wildcard
5328 @cindex wildcard, function
5329 The argument @var{pattern} is a file name pattern, typically containing
5330 wildcard characters (as in shell file name patterns).  The result of
5331 @code{wildcard} is a space-separated list of the names of existing files
5332 that match the pattern.
5333 @xref{Wildcards, ,Using Wildcard Characters in File Names}.
5334 @end table
5336 @node Foreach Function, Origin Function, Filename Functions, Functions
5337 @section The @code{foreach} Function
5338 @findex foreach
5339 @cindex words, iterating over
5341 The @code{foreach} function is very different from other functions.  It
5342 causes one piece of text to be used repeatedly, each time with a different
5343 substitution performed on it.  It resembles the @code{for} command in the
5344 shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
5346 The syntax of the @code{foreach} function is:
5348 @example
5349 $(foreach @var{var},@var{list},@var{text})
5350 @end example
5352 @noindent
5353 The first two arguments, @var{var} and @var{list}, are expanded before
5354 anything else is done; note that the last argument, @var{text}, is
5355 @strong{not} expanded at the same time.  Then for each word of the expanded
5356 value of @var{list}, the variable named by the expanded value of @var{var}
5357 is set to that word, and @var{text} is expanded.  Presumably @var{text}
5358 contains references to that variable, so its expansion will be different
5359 each time.
5361 The result is that @var{text} is expanded as many times as there are
5362 whitespace-separated words in @var{list}.  The multiple expansions of
5363 @var{text} are concatenated, with spaces between them, to make the result
5364 of @code{foreach}.
5366 This simple example sets the variable @samp{files} to the list of all files
5367 in the directories in the list @samp{dirs}:
5369 @example
5370 dirs := a b c d
5371 files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
5372 @end example
5374 Here @var{text} is @samp{$(wildcard $(dir)/*)}.  The first repetition
5375 finds the value @samp{a} for @code{dir}, so it produces the same result
5376 as @samp{$(wildcard a/*)}; the second repetition produces the result
5377 of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
5379 This example has the same result (except for setting @samp{dirs}) as
5380 the following example:
5382 @example
5383 files := $(wildcard a/* b/* c/* d/*)
5384 @end example
5386 When @var{text} is complicated, you can improve readability by giving it
5387 a name, with an additional variable:
5389 @example
5390 find_files = $(wildcard $(dir)/*)
5391 dirs := a b c d
5392 files := $(foreach dir,$(dirs),$(find_files))
5393 @end example
5395 @noindent
5396 Here we use the variable @code{find_files} this way.  We use plain @samp{=}
5397 to define a recursively-expanding variable, so that its value contains an
5398 actual function call to be reexpanded under the control of @code{foreach};
5399 a simply-expanded variable would not do, since @code{wildcard} would be
5400 called only once at the time of defining @code{find_files}.
5402 The @code{foreach} function has no permanent effect on the variable
5403 @var{var}; its value and flavor after the @code{foreach} function call are
5404 the same as they were beforehand.  The other values which are taken from
5405 @var{list} are in effect only temporarily, during the execution of
5406 @code{foreach}.  The variable @var{var} is a simply-expanded variable
5407 during the execution of @code{foreach}.  If @var{var} was undefined
5408 before the @code{foreach} function call, it is undefined after the call.
5409 @xref{Flavors, ,The Two Flavors of Variables}.@refill
5411 You must take care when using complex variable expressions that result in
5412 variable names because many strange things are valid variable names, but
5413 are probably not what you intended.  For example,
5415 @smallexample
5416 files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
5417 @end smallexample
5419 @noindent
5420 might be useful if the value of @code{find_files} references the variable
5421 whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo,
5422 no?), but it is more likely to be a mistake.
5424 @node Origin Function, Shell Function, Foreach Function, Functions
5425 @section The @code{origin} Function
5426 @findex origin
5427 @cindex variables, origin of
5428 @cindex origin of variable
5430 The @code{origin} function is unlike most other functions in that it does
5431 not operate on the values of variables; it tells you something @emph{about}
5432 a variable.  Specifically, it tells you where it came from.
5434 The syntax of the @code{origin} function is:
5436 @example
5437 $(origin @var{variable})
5438 @end example
5440 Note that @var{variable} is the @emph{name} of a variable to inquire about;
5441 not a @emph{reference} to that variable.  Therefore you would not normally
5442 use a @samp{$} or parentheses when writing it.  (You can, however, use a
5443 variable reference in the name if you want the name not to be a constant.)
5445 The result of this function is a string telling you how the variable
5446 @var{variable} was defined:
5448 @table @samp
5449 @item undefined
5451 if @var{variable} was never defined.
5453 @item default
5455 if @var{variable} has a default definition, as is usual with @code{CC}
5456 and so on.  @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
5457 Note that if you have redefined a default variable, the @code{origin}
5458 function will return the origin of the later definition.
5460 @item environment
5462 if @var{variable} was defined as an environment variable and the
5463 @samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}).
5465 @item environment override
5467 if @var{variable} was defined as an environment variable and the
5468 @w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary,
5469 ,Summary of Options}).@refill
5471 @item file
5473 if @var{variable} was defined in a makefile.
5475 @item command line
5477 if @var{variable} was defined on the command line.
5479 @item override
5481 if @var{variable} was defined with an @code{override} directive in a
5482 makefile (@pxref{Override Directive, ,The @code{override} Directive}).
5484 @item automatic
5486 if @var{variable} is an automatic variable defined for the
5487 execution of the commands for each rule
5488 (@pxref{Automatic, , Automatic Variables}).
5489 @end table
5491 This information is primarily useful (other than for your curiosity) to
5492 determine if you want to believe the value of a variable.  For example,
5493 suppose you have a makefile @file{foo} that includes another makefile
5494 @file{bar}.  You want a variable @code{bletch} to be defined in @file{bar}
5495 if you run the command @w{@samp{make -f bar}}, even if the environment contains
5496 a definition of @code{bletch}.  However, if @file{foo} defined
5497 @code{bletch} before including @file{bar}, you do not want to override that
5498 definition.  This could be done by using an @code{override} directive in
5499 @file{foo}, giving that definition precedence over the later definition in
5500 @file{bar}; unfortunately, the @code{override} directive would also
5501 override any command line definitions.  So, @file{bar} could
5502 include:@refill
5504 @example
5505 @group
5506 ifdef bletch
5507 ifeq "$(origin bletch)" "environment"
5508 bletch = barf, gag, etc.
5509 endif
5510 endif
5511 @end group
5512 @end example
5514 @noindent
5515 If @code{bletch} has been defined from the environment, this will redefine
5518 If you want to override a previous definition of @code{bletch} if it came
5519 from the environment, even under @samp{-e}, you could instead write:
5521 @example
5522 @group
5523 ifneq "$(findstring environment,$(origin bletch))" ""
5524 bletch = barf, gag, etc.
5525 endif
5526 @end group
5527 @end example
5529 Here the redefinition takes place if @samp{$(origin bletch)} returns either
5530 @samp{environment} or @samp{environment override}.
5531 @xref{Text Functions, , Functions for String Substitution and Analysis}.
5533 @node Shell Function,  , Origin Function, Functions
5534 @section The @code{shell} Function
5535 @findex shell
5536 @cindex commands, expansion
5537 @cindex backquotes
5538 @cindex shell command, function for
5540 The @code{shell} function is unlike any other function except the
5541 @code{wildcard} function
5542 (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
5543 communicates with the world outside of @code{make}.
5545 The @code{shell} function performs the same function that backquotes
5546 (@samp{`}) perform in most shells: it does @dfn{command expansion}.  This
5547 means that it takes an argument that is a shell command and returns the
5548 output of the command.  The only processing @code{make} does on the result,
5549 before substituting it into the surrounding text, is to convert newlines to
5550 spaces.@refill
5552 The commands run by calls to the @code{shell} function are run when the
5553 function calls are expanded.  In most cases, this is when the makefile is
5554 read in.  The exception is that function calls in the commands of the rules
5555 are expanded when the commands are run, and this applies to @code{shell}
5556 function calls like all others.
5558 Here are some examples of the use of the @code{shell} function:
5560 @example
5561 contents := $(shell cat foo)
5562 @end example
5564 @noindent
5565 sets @code{contents} to the contents of the file @file{foo}, with a space
5566 (rather than a newline) separating each line.
5568 @example
5569 files := $(shell echo *.c)
5570 @end example
5572 @noindent
5573 sets @code{files} to the expansion of @samp{*.c}.  Unless @code{make} is
5574 using a very strange shell, this has the same result as
5575 @w{@samp{$(wildcard *.c)}}.@refill
5577 @node Running, Implicit Rules, Functions, Top
5578 @chapter How to Run @code{make}
5580 A makefile that says how to recompile a program can be used in more
5581 than one way.  The simplest use is to recompile every file that is out
5582 of date.  Usually, makefiles are written so that if you run
5583 @code{make} with no arguments, it does just that.
5585 But you might want to update only some of the files; you might want to use
5586 a different compiler or different compiler options; you might want just to
5587 find out which files are out of date without changing them.
5589 By giving arguments when you run @code{make}, you can do any of these
5590 things and many others.
5592 The exit status of @code{make} is always one of three values:
5593 @table @code
5594 @item 0
5595 The exit status is zero if @code{make} is successful.
5596 @item 2
5597 The exit status is two if @code{make} encounters any errors.
5598 It will print messages describing the particular errors.
5599 @item 1
5600 The exit status is one if you use the @samp{-q} flag and @code{make}
5601 determines that some target is not already up to date.
5602 @xref{Instead of Execution, ,Instead of Executing the Commands}.
5603 @end table
5605 @menu
5606 * Makefile Arguments::          How to specify which makefile to use.
5607 * Goals::                       How to use goal arguments to specify which
5608                                   parts of the makefile to use.
5609 * Instead of Execution::        How to use mode flags to specify what
5610                                   kind of thing to do with the commands
5611                                   in the makefile other than simply
5612                                   execute them.
5613 * Avoiding Compilation::        How to avoid recompiling certain files.
5614 * Overriding::                  How to override a variable to specify
5615                                   an alternate compiler and other things.
5616 * Testing::                     How to proceed past some errors, to
5617                                   test compilation.
5618 * Options Summary::             Summary of Options
5619 @end menu
5621 @node Makefile Arguments, Goals,  , Running
5622 @section Arguments to Specify the Makefile
5623 @cindex @code{--file}
5624 @cindex @code{--makefile}
5625 @cindex @code{-f}
5627 The way to specify the name of the makefile is with the @samp{-f} or
5628 @samp{--file} option (@samp{--makefile} also works).  For example,
5629 @samp{-f altmake} says to use the file @file{altmake} as the makefile.
5631 If you use the @samp{-f} flag several times and follow each @samp{-f}
5632 with an argument, all the specified files are used jointly as
5633 makefiles.
5635 If you do not use the @samp{-f} or @samp{--file} flag, the default is
5636 to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
5637 that order, and use the first of these three which exists or can be made
5638 (@pxref{Makefiles, ,Writing Makefiles}).@refill
5640 @node Goals, Instead of Execution, Makefile Arguments, Running
5641 @section Arguments to Specify the Goals
5642 @cindex goal, how to specify
5644 The @dfn{goals} are the targets that @code{make} should strive ultimately
5645 to update.  Other targets are updated as well if they appear as
5646 dependencies of goals, or dependencies of dependencies of goals, etc.
5648 By default, the goal is the first target in the makefile (not counting
5649 targets that start with a period).  Therefore, makefiles are usually
5650 written so that the first target is for compiling the entire program or
5651 programs they describe.  If the first rule in the makefile has several
5652 targets, only the first target in the rule becomes the default goal, not
5653 the whole list.
5655 You can specify a different goal or goals with arguments to @code{make}.
5656 Use the name of the goal as an argument.  If you specify several goals,
5657 @code{make} processes each of them in turn, in the order you name them.
5659 Any target in the makefile may be specified as a goal (unless it
5660 starts with @samp{-} or contains an @samp{=}, in which case it will be
5661 parsed as a switch or variable definition, respectively).  Even
5662 targets not in the makefile may be specified, if @code{make} can find
5663 implicit rules that say how to make them.
5665 One use of specifying a goal is if you want to compile only a part of
5666 the program, or only one of several programs.  Specify as a goal each
5667 file that you wish to remake.  For example, consider a directory containing
5668 several programs, with a makefile that starts like this:
5670 @example
5671 .PHONY: all
5672 all: size nm ld ar as
5673 @end example
5675 If you are working on the program @code{size}, you might want to say
5676 @w{@samp{make size}} so that only the files of that program are recompiled.
5678 Another use of specifying a goal is to make files that are not normally
5679 made.  For example, there may be a file of debugging output, or a
5680 version of the program that is compiled specially for testing, which has
5681 a rule in the makefile but is not a dependency of the default goal.
5683 Another use of specifying a goal is to run the commands associated with
5684 a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
5685 Targets, ,Empty Target Files to Record Events}).  Many makefiles contain
5686 a phony target named @file{clean} which deletes everything except source
5687 files.  Naturally, this is done only if you request it explicitly with
5688 @w{@samp{make clean}}.  Following is a list of typical phony and empty
5689 target names.  @xref{Standard Targets}, for a detailed list of all the
5690 standard target names which GNU software packages use.
5692 @table @file
5693 @item all
5694 @cindex @code{all} @r{(standard target)}
5695 Make all the top-level targets the makefile knows about.
5697 @item clean
5698 @cindex @code{clean} @r{(standard target)}
5699 Delete all files that are normally created by running @code{make}.
5701 @item mostlyclean
5702 @cindex @code{mostlyclean} @r{(standard target)}
5703 Like @samp{clean}, but may refrain from deleting a few files that people
5704 normally don't want to recompile.  For example, the @samp{mostlyclean}
5705 target for GCC does not delete @file{libgcc.a}, because recompiling it
5706 is rarely necessary and takes a lot of time.
5708 @item distclean
5709 @cindex @code{distclean} @r{(standard target)}
5710 @itemx realclean
5711 @cindex @code{realclean} @r{(standard target)}
5712 @itemx clobber
5713 @cindex @code{clobber} @r{(standard target)}
5714 Any of these targets might be defined to delete @emph{more} files than
5715 @samp{clean} does.  For example, this would delete configuration files
5716 or links that you would normally create as preparation for compilation,
5717 even if the makefile itself cannot create these files.
5719 @item install
5720 @cindex @code{install} @r{(standard target)}
5721 Copy the executable file into a directory that users typically search
5722 for commands; copy any auxiliary files that the executable uses into
5723 the directories where it will look for them.
5725 @item print
5726 @cindex @code{print} @r{(standard target)}
5727 Print listings of the source files that have changed.
5729 @item tar
5730 @cindex @code{tar} @r{(standard target)}
5731 Create a tar file of the source files.
5733 @item shar
5734 @cindex @code{shar} @r{(standard target)}
5735 Create a shell archive (shar file) of the source files.
5737 @item dist
5738 @cindex @code{dist} @r{(standard target)}
5739 Create a distribution file of the source files.  This might
5740 be a tar file, or a shar file, or a compressed version of one of the
5741 above, or even more than one of the above.
5743 @item TAGS
5744 @cindex @code{TAGS} @r{(standard target)}
5745 Update a tags table for this program.
5747 @item check
5748 @cindex @code{check} @r{(standard target)}
5749 @itemx test
5750 @cindex @code{test} @r{(standard target)}
5751 Perform self tests on the program this makefile builds.
5752 @end table
5754 @node Instead of Execution, Avoiding Compilation, Goals, Running
5755 @section Instead of Executing the Commands
5756 @cindex execution, instead of
5757 @cindex commands, instead of executing
5759 The makefile tells @code{make} how to tell whether a target is up to date,
5760 and how to update each target.  But updating the targets is not always
5761 what you want.  Certain options specify other activities for @code{make}.
5763 @comment Extra blank lines make it print better.
5764 @table @samp
5765 @item -n
5766 @itemx --just-print
5767 @itemx --dry-run
5768 @itemx --recon
5769 @cindex @code{--just-print}
5770 @cindex @code{--dry-run}
5771 @cindex @code{--recon}
5772 @cindex @code{-n}
5774 ``No-op''.  The activity is to print what commands would be used to make
5775 the targets up to date, but not actually execute them.
5777 @item -t
5778 @itemx --touch
5779 @cindex @code{--touch}
5780 @cindex touching files
5781 @cindex target, touching
5782 @cindex @code{-t}
5784 ``Touch''.  The activity is to mark the targets as up to date without
5785 actually changing them.  In other words, @code{make} pretends to compile
5786 the targets but does not really change their contents.
5788 @item -q
5789 @itemx --question
5790 @cindex @code{--question}
5791 @cindex @code{-q}
5792 @cindex question mode
5794 ``Question''.  The activity is to find out silently whether the targets
5795 are up to date already; but execute no commands in either case.  In other
5796 words, neither compilation nor output will occur.
5798 @item -W @var{file}
5799 @itemx --what-if=@var{file}
5800 @itemx --assume-new=@var{file}
5801 @itemx --new-file=@var{file}
5802 @cindex @code{--what-if}
5803 @cindex @code{-W}
5804 @cindex @code{--assume-new}
5805 @cindex @code{--new-file}
5806 @cindex what if
5807 @cindex files, assuming new
5809 ``What if''.  Each @samp{-W} flag is followed by a file name.  The given
5810 files' modification times are recorded by @code{make} as being the present
5811 time, although the actual modification times remain the same.
5812 You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
5813 to see what would happen if you were to modify specific files.@refill
5814 @end table
5816 With the @samp{-n} flag, @code{make} prints the commands that it would
5817 normally execute but does not execute them.
5819 With the @samp{-t} flag, @code{make} ignores the commands in the rules
5820 and uses (in effect) the command @code{touch} for each target that needs to
5821 be remade.  The @code{touch} command is also printed, unless @samp{-s} or
5822 @code{.SILENT} is used.  For speed, @code{make} does not actually invoke
5823 the program @code{touch}.  It does the work directly.
5825 With the @samp{-q} flag, @code{make} prints nothing and executes no
5826 commands, but the exit status code it returns is zero if and only if the
5827 targets to be considered are already up to date.  If the exit status is
5828 one, then some updating needs to be done.  If @code{make} encounters an
5829 error, the exit status is two, so you can distinguish an error from a
5830 target that is not up to date.
5832 It is an error to use more than one of these three flags in the same
5833 invocation of @code{make}.
5835 The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command
5836 lines that begin with @samp{+} characters or contain the strings
5837 @samp{$(MAKE)} or @samp{$@{MAKE@}}.  Note that only the line containing
5838 the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
5839 is run regardless of these options.  Other lines in the same rule are
5840 not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
5841 @samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
5843 The @samp{-W} flag provides two features:
5845 @itemize @bullet
5846 @item
5847 If you also use the @samp{-n} or @samp{-q} flag, you can see what
5848 @code{make} would do if you were to modify some files.
5850 @item
5851 Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
5852 executing commands, the @samp{-W} flag can direct @code{make} to act
5853 as if some files had been modified, without actually modifying the
5854 files.@refill
5855 @end itemize
5857 Note that the options @samp{-p} and @samp{-v} allow you to obtain other
5858 information about @code{make} or about the makefiles in use
5859 (@pxref{Options Summary, ,Summary of Options}).@refill
5861 @node Avoiding Compilation, Overriding, Instead of Execution, Running
5862 @section Avoiding Recompilation of Some Files
5863 @cindex @code{-o}
5864 @cindex @code{--old-file}
5865 @cindex @code{--assume-old}
5866 @cindex files, assuming old
5867 @cindex files, avoiding recompilation of
5868 @cindex recompilation, avoiding
5870 Sometimes you may have changed a source file but you do not want to
5871 recompile all the files that depend on it.  For example, suppose you add a
5872 macro or a declaration to a header file that many other files depend on.
5873 Being conservative, @code{make} assumes that any change in the header file
5874 requires recompilation of all dependent files, but you know that they do not
5875 need to be recompiled and you would rather not waste the time waiting for
5876 them to compile.
5878 If you anticipate the problem before changing the header file, you can
5879 use the @samp{-t} flag.  This flag tells @code{make} not to run the
5880 commands in the rules, but rather to mark the target up to date by
5881 changing its last-modification date.  You would follow this procedure:
5883 @enumerate
5884 @item
5885 Use the command @samp{make} to recompile the source files that really
5886 need recompilation.
5888 @item
5889 Make the changes in the header files.
5891 @item
5892 Use the command @samp{make -t} to mark all the object files as
5893 up to date.  The next time you run @code{make}, the changes in the
5894 header files will not cause any recompilation.
5895 @end enumerate
5897 If you have already changed the header file at a time when some files
5898 do need recompilation, it is too late to do this.  Instead, you can
5899 use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
5900 ``old'' (@pxref{Options Summary, ,Summary of Options}).  This means
5901 that the file itself will not be remade, and nothing else will be
5902 remade on its account.  Follow this procedure:
5904 @enumerate
5905 @item
5906 Recompile the source files that need compilation for reasons independent
5907 of the particular header file, with @samp{make -o @var{headerfile}}.
5908 If several header files are involved, use a separate @samp{-o} option
5909 for each header file.
5911 @item
5912 Touch all the object files with @samp{make -t}.
5913 @end enumerate
5915 @node Overriding, Testing, Avoiding Compilation, Running
5916 @section Overriding Variables
5917 @cindex overriding variables with arguments
5918 @cindex variables, overriding with arguments
5919 @cindex command line variables
5920 @cindex variables, command line
5922 An argument that contains @samp{=} specifies the value of a variable:
5923 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
5924 If you specify a value in this way, all ordinary assignments of the same
5925 variable in the makefile are ignored; we say they have been
5926 @dfn{overridden} by the command line argument.
5928 The most common way to use this facility is to pass extra flags to
5929 compilers.  For example, in a properly written makefile, the variable
5930 @code{CFLAGS} is included in each command that runs the C compiler, so a
5931 file @file{foo.c} would be compiled something like this:
5933 @example
5934 cc -c $(CFLAGS) foo.c
5935 @end example
5937 Thus, whatever value you set for @code{CFLAGS} affects each compilation
5938 that occurs.  The makefile probably specifies the usual value for
5939 @code{CFLAGS}, like this:
5941 @example
5942 CFLAGS=-g
5943 @end example
5945 Each time you run @code{make}, you can override this value if you
5946 wish.  For example, if you say @samp{make CFLAGS='-g -O'}, each C
5947 compilation will be done with @samp{cc -c -g -O}.  (This illustrates
5948 how you can use quoting in the shell to enclose spaces and other
5949 special characters in the value of a variable when you override it.)
5951 The variable @code{CFLAGS} is only one of many standard variables that
5952 exist just so that you can change them this way.  @xref{Implicit
5953 Variables, , Variables Used by Implicit Rules}, for a complete list.
5955 You can also program the makefile to look at additional variables of your
5956 own, giving the user the ability to control other aspects of how the
5957 makefile works by changing the variables.
5959 When you override a variable with a command argument, you can define either
5960 a recursively-expanded variable or a simply-expanded variable.  The
5961 examples shown above make a recursively-expanded variable; to make a
5962 simply-expanded variable, write @samp{:=} instead of @samp{=}.  But, unless
5963 you want to include a variable reference or function call in the
5964 @emph{value} that you specify, it makes no difference which kind of
5965 variable you create.
5967 There is one way that the makefile can change a variable that you have
5968 overridden.  This is to use the @code{override} directive, which is a line
5969 that looks like this: @samp{override @var{variable} = @var{value}}
5970 (@pxref{Override Directive, ,The @code{override} Directive}).
5972 @node Testing, Options Summary, Overriding, Running
5973 @section Testing the Compilation of a Program
5974 @cindex testing compilation
5975 @cindex compilation, testing
5977 Normally, when an error happens in executing a shell command, @code{make}
5978 gives up immediately, returning a nonzero status.  No further commands are
5979 executed for any target.  The error implies that the goal cannot be
5980 correctly remade, and @code{make} reports this as soon as it knows.
5982 When you are compiling a program that you have just changed, this is not
5983 what you want.  Instead, you would rather that @code{make} try compiling
5984 every file that can be tried, to show you as many compilation errors
5985 as possible.
5987 @cindex @code{-k}
5988 @cindex @code{--keep-going}
5989 On these occasions, you should use the @samp{-k} or
5990 @samp{--keep-going} flag.  This tells @code{make} to continue to
5991 consider the other dependencies of the pending targets, remaking them
5992 if necessary, before it gives up and returns nonzero status.  For
5993 example, after an error in compiling one object file, @samp{make -k}
5994 will continue compiling other object files even though it already
5995 knows that linking them will be impossible.  In addition to continuing
5996 after failed shell commands, @samp{make -k} will continue as much as
5997 possible after discovering that it does not know how to make a target
5998 or dependency file.  This will always cause an error message, but
5999 without @samp{-k}, it is a fatal error (@pxref{Options Summary,
6000 ,Summary of Options}).@refill
6002 The usual behavior of @code{make} assumes that your purpose is to get the
6003 goals up to date; once @code{make} learns that this is impossible, it might
6004 as well report the failure immediately.  The @samp{-k} flag says that the
6005 real purpose is to test as much as possible of the changes made in the
6006 program, perhaps to find several independent problems so that you can
6007 correct them all before the next attempt to compile.  This is why Emacs'
6008 @kbd{M-x compile} command passes the @samp{-k} flag by default.
6010 @node Options Summary,  , Testing, Running
6011 @section Summary of Options
6012 @cindex options
6013 @cindex flags
6014 @cindex switches
6016 Here is a table of all the options @code{make} understands:
6018 @table @samp
6019 @item -b
6020 @cindex @code{-b}
6021 @itemx -m
6022 @cindex @code{-m}
6023 These options are ignored for compatibility with other versions of @code{make}.
6025 @item -C @var{dir}
6026 @cindex @code{-C}
6027 @itemx --directory=@var{dir}
6028 @cindex @code{--directory}
6029 Change to directory @var{dir} before reading the makefiles.  If multiple
6030 @samp{-C} options are specified, each is interpreted relative to the
6031 previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
6032 This is typically used with recursive invocations of @code{make}
6033 (@pxref{Recursion, ,Recursive Use of @code{make}}).
6035 @item -d
6036 @cindex @code{-d}
6037 @itemx --debug
6038 @cindex @code{--debug}
6039 @c Extra blank line here makes the table look better.
6041 Print debugging information in addition to normal processing.  The
6042 debugging information says which files are being considered for
6043 remaking, which file-times are being compared and with what results,
6044 which files actually need to be remade, which implicit rules are
6045 considered and which are applied---everything interesting about how
6046 @code{make} decides what to do.
6048 @item -e
6049 @cindex @code{-e}
6050 @itemx --environment-overrides
6051 @cindex @code{--environment-overrides}
6052 Give variables taken from the environment precedence
6053 over variables from makefiles.
6054 @xref{Environment, ,Variables from the Environment}.
6056 @item -f @var{file}
6057 @cindex @code{-f}
6058 @itemx --file=@var{file}
6059 @cindex @code{--file}
6060 @itemx --makefile=@var{file}
6061 @cindex @code{--makefile}
6062 Read the file named @var{file} as a makefile.
6063 @xref{Makefiles, ,Writing Makefiles}.
6065 @item -h
6066 @cindex @code{-h}
6067 @itemx --help
6068 @cindex @code{--help}
6069 @c Extra blank line here makes the table look better.
6071 Remind you of the options that @code{make} understands and then exit.
6073 @item -i
6074 @cindex @code{-i}
6075 @itemx --ignore-errors
6076 @cindex @code{--ignore-errors}
6077 Ignore all errors in commands executed to remake files.
6078 @xref{Errors, ,Errors in Commands}.
6080 @item -I @var{dir}
6081 @cindex @code{-I}
6082 @itemx --include-dir=@var{dir}
6083 @cindex @code{--include-dir}
6084 Specifies a directory @var{dir} to search for included makefiles.
6085 @xref{Include, ,Including Other Makefiles}.  If several @samp{-I}
6086 options are used to specify several directories, the directories are
6087 searched in the order specified.
6089 @item -j [@var{jobs}]
6090 @cindex @code{-j}
6091 @itemx --jobs=[@var{jobs}]
6092 @cindex @code{--jobs}
6093 Specifies the number of jobs (commands) to run simultaneously.  With no
6094 argument, @code{make} runs as many jobs simultaneously as possible.  If
6095 there is more than one @samp{-j} option, the last one is effective.
6096 @xref{Parallel, ,Parallel Execution},
6097 for more information on how commands are run.
6099 @item -k
6100 @cindex @code{-k}
6101 @itemx --keep-going
6102 @cindex @code{--keep-going}
6103 Continue as much as possible after an error.  While the target that
6104 failed, and those that depend on it, cannot be remade, the other
6105 dependencies of these targets can be processed all the same.
6106 @xref{Testing, ,Testing the Compilation of a Program}.
6108 @item -l [@var{load}]
6109 @cindex @code{-l}
6110 @itemx --load-average[=@var{load}]
6111 @cindex @code{--load-average}
6112 @itemx --max-load[=@var{load}]
6113 @cindex @code{--max-load}
6114 Specifies that no new jobs (commands) should be started if there are
6115 other jobs running and the load average is at least @var{load} (a
6116 floating-point number).  With no argument, removes a previous load
6117 limit.  @xref{Parallel, ,Parallel Execution}.
6119 @item -n
6120 @cindex @code{-n}
6121 @itemx --just-print
6122 @cindex @code{--just-print}
6123 @itemx --dry-run
6124 @cindex @code{--dry-run}
6125 @itemx --recon
6126 @cindex @code{--recon}
6127 @c Extra blank line here makes the table look better.
6129 Print the commands that would be executed, but do not execute them.
6130 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6132 @item -o @var{file}
6133 @cindex @code{-o}
6134 @itemx --old-file=@var{file}
6135 @cindex @code{--old-file}
6136 @itemx --assume-old=@var{file}
6137 @cindex @code{--assume-old}
6138 Do not remake the file @var{file} even if it is older than its
6139 dependencies, and do not remake anything on account of changes in
6140 @var{file}.  Essentially the file is treated as very old and its rules
6141 are ignored.  @xref{Avoiding Compilation, ,Avoiding Recompilation of
6142 Some Files}.@refill
6144 @item -p
6145 @cindex @code{-p}
6146 @itemx --print-data-base
6147 @cindex @code{--print-data-base}
6148 Print the data base (rules and variable values) that results from
6149 reading the makefiles; then execute as usual or as otherwise
6150 specified.  This also prints the version information given by
6151 the @samp{-v} switch (see below).  To print the data base without
6152 trying to remake any files, use @w{@samp{make -p -f /dev/null}}.
6154 @item -q
6155 @cindex @code{-q}
6156 @itemx --question
6157 @cindex @code{--question}
6158 ``Question mode''.  Do not run any commands, or print anything; just
6159 return an exit status that is zero if the specified targets are already
6160 up to date, one if any remaking is required, or two if an error is
6161 encountered.  @xref{Instead of Execution, ,Instead of Executing the
6162 Commands}.@refill
6164 @item -r
6165 @cindex @code{-r}
6166 @itemx --no-builtin-rules
6167 @cindex @code{--no-builtin-rules}
6168 Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
6169 ,Using Implicit Rules}).  You can still define your own by writing
6170 pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
6171 Rules}).  The @samp{-r} option also clears out the default list of
6172 suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
6173 Rules}).  But you can still define your own suffixes with a rule for
6174 @code{.SUFFIXES}, and then define your own suffix rules.
6176 @item -s
6177 @cindex @code{-s}
6178 @itemx --silent
6179 @cindex @code{--silent}
6180 @itemx --quiet
6181 @cindex @code{--quiet}
6182 @c Extra blank line here makes the table look better.
6184 Silent operation; do not print the commands as they are executed.
6185 @xref{Echoing, ,Command Echoing}.
6187 @item -S
6188 @cindex @code{-S}
6189 @itemx --no-keep-going
6190 @cindex @code{--no-keep-going}
6191 @itemx --stop
6192 @cindex @code{--stop}
6193 @c Extra blank line here makes the table look better.
6195 Cancel the effect of the @samp{-k} option.  This is never necessary
6196 except in a recursive @code{make} where @samp{-k} might be inherited
6197 from the top-level @code{make} via @code{MAKEFLAGS}
6198 (@pxref{Recursion, ,Recursive Use of @code{make}})
6199 or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
6201 @item -t
6202 @cindex @code{-t}
6203 @itemx --touch
6204 @cindex @code{--touch}
6205 @c Extra blank line here makes the table look better.
6207 Touch files (mark them up to date without really changing them)
6208 instead of running their commands.  This is used to pretend that the
6209 commands were done, in order to fool future invocations of
6210 @code{make}.  @xref{Instead of Execution, ,Instead of Executing the Commands}.
6212 @item -v
6213 @cindex @code{-v}
6214 @itemx --version
6215 @cindex @code{--version}
6216 Print the version of the @code{make} program plus a copyright, a list
6217 of authors, and a notice that there is no warranty; then exit.
6219 @item -w
6220 @cindex @code{-w}
6221 @itemx --print-directory
6222 @cindex @code{--print-directory}
6223 Print a message containing the working directory both before and after
6224 executing the makefile.  This may be useful for tracking down errors
6225 from complicated nests of recursive @code{make} commands.
6226 @xref{Recursion, ,Recursive Use of @code{make}}.  (In practice, you
6227 rarely need to specify this option since @samp{make} does it for you;
6228 see @ref{-w Option, ,The @samp{--print-directory} Option}.)
6230 @itemx --no-print-directory
6231 @cindex @code{--no-print-directory}
6232 Disable printing of the working directory under @code{-w}.
6233 This option is useful when @code{-w} is turned on automatically,
6234 but you do not want to see the extra messages.
6235 @xref{-w Option, ,The @samp{--print-directory} Option}.
6237 @item -W @var{file}
6238 @cindex @code{-W}
6239 @itemx --what-if=@var{file}
6240 @cindex @code{--what-if}
6241 @itemx --new-file=@var{file}
6242 @cindex @code{--new-file}
6243 @itemx --assume-new=@var{file}
6244 @cindex @code{--assume-new}
6245 Pretend that the target @var{file} has just been modified.  When used
6246 with the @samp{-n} flag, this shows you what would happen if you were
6247 to modify that file.  Without @samp{-n}, it is almost the same as
6248 running a @code{touch} command on the given file before running
6249 @code{make}, except that the modification time is changed only in the
6250 imagination of @code{make}.
6251 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6253 @item --warn-undefined-variables
6254 @cindex @code{--warn-undefined-variables}
6255 @cindex variables, warning for undefined
6256 @cindex undefined variables, warning message
6257 Issue a warning message whenever @code{make} sees a reference to an
6258 undefined variable.  This can be helpful when you are trying to debug
6259 makefiles which use variables in complex ways.
6260 @end table
6262 @node Implicit Rules, Archives, Running, Top
6263 @chapter Using Implicit Rules
6264 @cindex implicit rule
6265 @cindex rule, implicit
6267 Certain standard ways of remaking target files are used very often.  For
6268 example, one customary way to make an object file is from a C source file
6269 using the C compiler, @code{cc}.
6271 @dfn{Implicit rules} tell @code{make} how to use customary techniques so
6272 that you do not have to specify them in detail when you want to use
6273 them.  For example, there is an implicit rule for C compilation.  File
6274 names determine which implicit rules are run.  For example, C
6275 compilation typically takes a @file{.c} file and makes a @file{.o} file.
6276 So @code{make} applies the implicit rule for C compilation when it sees
6277 this combination of file name endings.@refill
6279 A chain of implicit rules can apply in sequence; for example, @code{make}
6280 will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
6281 @iftex
6282 @xref{Chained Rules, ,Chains of Implicit Rules}.
6283 @end iftex
6285 The built-in implicit rules use several variables in their commands so
6286 that, by changing the values of the variables, you can change the way the
6287 implicit rule works.  For example, the variable @code{CFLAGS} controls the
6288 flags given to the C compiler by the implicit rule for C compilation.
6289 @iftex
6290 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
6291 @end iftex
6293 You can define your own implicit rules by writing @dfn{pattern rules}.
6294 @iftex
6295 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
6296 @end iftex
6298 @dfn{Suffix rules} are a more limited way to define implicit rules.
6299 Pattern rules are more general and clearer, but suffix rules are
6300 retained for compatibility.
6301 @iftex
6302 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
6303 @end iftex
6305 @menu
6306 * Using Implicit::              How to use an existing implicit rule
6307                                   to get the commands for updating a file.
6308 * Catalogue of Rules::          A list of built-in implicit rules.
6309 * Implicit Variables::          How to change what predefined rules do.
6310 * Chained Rules::               How to use a chain of implicit rules.
6311 * Pattern Rules::               How to define new implicit rules.
6312 * Last Resort::                 How to defining commands for rules
6313                                   which cannot find any.
6314 * Suffix Rules::                The old-fashioned style of implicit rule.
6315 * Search Algorithm::            The precise algorithm for applying
6316                                   implicit rules.
6317 @end menu
6319 @node Using Implicit, Catalogue of Rules,  , Implicit Rules
6320 @section Using Implicit Rules
6321 @cindex implicit rule, how to use
6322 @cindex rule, implicit, how to use
6324 To allow @code{make} to find a customary method for updating a target file,
6325 all you have to do is refrain from specifying commands yourself.  Either
6326 write a rule with no command lines, or don't write a rule at all.  Then
6327 @code{make} will figure out which implicit rule to use based on which
6328 kind of source file exists or can be made.
6330 For example, suppose the makefile looks like this:
6332 @example
6333 foo : foo.o bar.o
6334         cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
6335 @end example
6337 @noindent
6338 Because you mention @file{foo.o} but do not give a rule for it, @code{make}
6339 will automatically look for an implicit rule that tells how to update it.
6340 This happens whether or not the file @file{foo.o} currently exists.
6342 If an implicit rule is found, it can supply both commands and one or
6343 more dependencies (the source files).  You would want to write a rule
6344 for @file{foo.o} with no command lines if you need to specify additional
6345 dependencies, such as header files, that the implicit rule cannot
6346 supply.
6348 Each implicit rule has a target pattern and dependency patterns.  There may
6349 be many implicit rules with the same target pattern.  For example, numerous
6350 rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
6351 another, from a @samp{.p} file with the Pascal compiler; and so on.  The rule
6352 that actually applies is the one whose dependencies exist or can be made.
6353 So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
6354 otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
6355 compiler; and so on.
6357 Of course, when you write the makefile, you know which implicit rule you
6358 want @code{make} to use, and you know it will choose that one because you
6359 know which possible dependency files are supposed to exist.
6360 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
6361 for a catalogue of all the predefined implicit rules.
6363 Above, we said an implicit rule applies if the required dependencies ``exist
6364 or can be made''.  A file ``can be made'' if it is mentioned explicitly in
6365 the makefile as a target or a dependency, or if an implicit rule can be
6366 recursively found for how to make it.  When an implicit dependency is the
6367 result of another implicit rule, we say that @dfn{chaining} is occurring.
6368 @xref{Chained Rules, ,Chains of Implicit Rules}.
6370 In general, @code{make} searches for an implicit rule for each target, and
6371 for each double-colon rule, that has no commands.  A file that is mentioned
6372 only as a dependency is considered a target whose rule specifies nothing,
6373 so implicit rule search happens for it.  @xref{Search Algorithm, ,Implicit Rule Search Algorithm}, for the
6374 details of how the search is done.
6376 Note that explicit dependencies do not influence implicit rule search.
6377 For example, consider this explicit rule:
6379 @example
6380 foo.o: foo.p
6381 @end example
6383 @noindent
6384 The dependency on @file{foo.p} does not necessarily mean that
6385 @code{make} will remake @file{foo.o} according to the implicit rule to
6386 make an object file, a @file{.o} file, from a Pascal source file, a
6387 @file{.p} file.  For example, if @file{foo.c} also exists, the implicit
6388 rule to make an object file from a C source file is used instead,
6389 because it appears before the Pascal rule in the list of predefined
6390 implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
6391 Rules}).
6393 If you do not want an implicit rule to be used for a target that has no
6394 commands, you can give that target empty commands by writing a semicolon
6395 (@pxref{Empty Commands, ,Defining Empty Commands}).
6397 @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
6398 @section Catalogue of Implicit Rules
6399 @cindex implicit rule, predefined
6400 @cindex rule, implicit, predefined
6402 Here is a catalogue of predefined implicit rules which are always
6403 available unless the makefile explicitly overrides or cancels them.
6404 @xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
6405 canceling or overriding an implicit rule.  The @samp{-r} or
6406 @samp{--no-builtin-rules} option cancels all predefined rules.
6408 Not all of these rules will always be defined, even when the @samp{-r}
6409 option is not given.  Many of the predefined implicit rules are
6410 implemented in @code{make} as suffix rules, so which ones will be
6411 defined depends on the @dfn{suffix list} (the list of dependencies of
6412 the special target @code{.SUFFIXES}).  The default suffix list is:
6413 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
6414 @code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
6415 @code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
6416 @code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
6417 @code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
6418 @code{.sh}, @code{.elc}, @code{.el}.  All of the implicit rules
6419 described below whose dependencies have one of these suffixes are
6420 actually suffix rules.  If you modify the suffix list, the only
6421 predefined suffix rules in effect will be those named by one or two of
6422 the suffixes that are on the list you specify; rules whose suffixes fail
6423 to be on the list are disabled.  @xref{Suffix Rules, ,Old-Fashioned
6424 Suffix Rules}, for full details on suffix rules.
6426 @table @asis
6427 @item Compiling C programs
6428 @cindex C, rule to compile
6429 @pindex cc
6430 @pindex gcc
6431 @pindex .o
6432 @pindex .c
6433 @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
6434 a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
6436 @item Compiling C++ programs
6437 @cindex C++, rule to compile
6438 @pindex g++
6439 @pindex .C
6440 @pindex .cc
6441 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
6442 @file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
6443 $(CXXFLAGS)}.  We encourage you to use the suffix @samp{.cc} for C++
6444 source files instead of @samp{.C}.@refill
6446 @item Compiling Pascal programs
6447 @cindex Pascal, rule to compile
6448 @pindex pc
6449 @pindex .p
6450 @file{@var{n}.o} is made automatically from @file{@var{n}.p}
6451 with the command @samp{$(PC) -c $(PFLAGS)}.@refill
6453 @item Compiling Fortran and Ratfor programs
6454 @cindex Fortran, rule to compile
6455 @cindex Ratfor, rule to compile
6456 @pindex f77
6457 @pindex .f
6458 @pindex .r
6459 @pindex .F
6460 @file{@var{n}.o} is made automatically from @file{@var{n}.r},
6461 @file{@var{n}.F} or @file{@var{n}.f} by running the
6462 Fortran compiler.  The precise command used is as follows:@refill
6464 @table @samp
6465 @item .f
6466 @samp{$(FC) -c $(FFLAGS)}.
6467 @item .F
6468 @samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}.
6469 @item .r
6470 @samp{$(FC) -c $(FFLAGS) $(RFLAGS)}.
6471 @end table
6473 @item Preprocessing Fortran and Ratfor programs
6474 @file{@var{n}.f} is made automatically from @file{@var{n}.r} or
6475 @file{@var{n}.F}.  This rule runs just the preprocessor to convert a
6476 Ratfor or preprocessable Fortran program into a strict Fortran
6477 program.  The precise command used is as follows:@refill
6479 @table @samp
6480 @item .F
6481 @samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}.
6482 @item .r
6483 @samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
6484 @end table
6486 @item Compiling Modula-2 programs
6487 @cindex Modula-2, rule to compile
6488 @pindex m2c
6489 @pindex .sym
6490 @pindex .def
6491 @pindex .mod
6492 @file{@var{n}.sym} is made from @file{@var{n}.def} with a command
6493 of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}.  @file{@var{n}.o}
6494 is made from @file{@var{n}.mod}; the form is:
6495 @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
6497 @need 1200
6498 @item Assembling and preprocessing assembler programs
6499 @cindex assembly, rule to compile
6500 @pindex as
6501 @pindex .s
6502 @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
6503 running the assembler, @code{as}.  The precise command is
6504 @samp{$(AS) $(ASFLAGS)}.@refill
6506 @pindex .S
6507 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
6508 running the C preprocessor, @code{cpp}.  The precise command is
6509 @w{@samp{$(CPP) $(CPPFLAGS)}}.
6511 @item Linking a single object file
6512 @cindex linking, predefined rule for
6513 @pindex ld
6514 @pindex .o
6515 @file{@var{n}} is made automatically from @file{@var{n}.o} by running
6516 the linker (usually called @code{ld}) via the C compiler.  The precise
6517 command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}}.
6519 This rule does the right thing for a simple program with only one
6520 source file.  It will also do the right thing if there are multiple
6521 object files (presumably coming from various other source files), one
6522 of which has a name matching that of the executable file.  Thus,
6524 @example
6525 x: y.o z.o
6526 @end example
6528 @noindent
6529 when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
6531 @example
6532 @group
6533 cc -c x.c -o x.o
6534 cc -c y.c -o y.o
6535 cc -c z.c -o z.o
6536 cc x.o y.o z.o -o x
6537 rm -f x.o
6538 rm -f y.o
6539 rm -f z.o
6540 @end group
6541 @end example
6543 @noindent
6544 In more complicated cases, such as when there is no object file whose
6545 name derives from the executable file name, you must write an explicit
6546 command for linking.
6548 Each kind of file automatically made into @samp{.o} object files will
6549 be automatically linked by using the compiler (@samp{$(CC)},
6550 @samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
6551 assemble @samp{.s} files) without the @samp{-c} option.  This could be
6552 done by using the @samp{.o} object files as intermediates, but it is
6553 faster to do the compiling and linking in one step, so that's how it's
6554 done.@refill
6556 @item Yacc for C programs
6557 @pindex yacc
6558 @cindex Yacc, rule to run
6559 @pindex .y
6560 @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
6561 running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
6563 @item Lex for C programs
6564 @pindex lex
6565 @cindex Lex, rule to run
6566 @pindex .l
6567 @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
6568 by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
6570 @item Lex for Ratfor programs
6571 @file{@var{n}.r} is made automatically from @file{@var{n}.l} by
6572 by running Lex.  The actual command is @samp{$(LEX) $(LFLAGS)}.
6574 The convention of using the same suffix @samp{.l} for all Lex files
6575 regardless of whether they produce C code or Ratfor code makes it
6576 impossible for @code{make} to determine automatically which of the two
6577 languages you are using in any particular case.  If @code{make} is
6578 called upon to remake an object file from a @samp{.l} file, it must
6579 guess which compiler to use.  It will guess the C compiler, because
6580 that is more common.  If you are using Ratfor, make sure @code{make}
6581 knows this by mentioning @file{@var{n}.r} in the makefile.  Or, if you
6582 are using Ratfor exclusively, with no C files, remove @samp{.c} from
6583 the list of implicit rule suffixes with:@refill
6585 @example
6586 @group
6587 .SUFFIXES:
6588 .SUFFIXES: .o .r .f .l @dots{}
6589 @end group
6590 @end example
6592 @item Making Lint Libraries from C, Yacc, or Lex programs
6593 @pindex lint
6594 @cindex @code{lint}, rule to run
6595 @pindex .ln
6596 @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
6597 The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
6598 The same command is used on the C code produced from
6599 @file{@var{n}.y} or @file{@var{n}.l}.@refill
6601 @item @TeX{} and Web
6602 @cindex @TeX{}, rule to run
6603 @cindex Web, rule to run
6604 @pindex tex
6605 @pindex cweave
6606 @pindex weave
6607 @pindex tangle
6608 @pindex ctangle
6609 @pindex .dvi
6610 @pindex .tex
6611 @pindex .web
6612 @pindex .w
6613 @pindex .ch
6614 @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command
6615 @samp{$(TEX)}.  @file{@var{n}.tex} is made from @file{@var{n}.web} with
6616 @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
6617 it exists or can be made) with @samp{$(CWEAVE)}.  @file{@var{n}.p} is
6618 made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
6619 is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
6620 or can be made) with @samp{$(CTANGLE)}.@refill
6622 @item Texinfo and Info
6623 @cindex Texinfo, rule to format
6624 @cindex Info, rule to format
6625 @pindex texi2dvi
6626 @pindex makeinfo
6627 @pindex .texinfo
6628 @pindex .info
6629 @pindex .texi
6630 @pindex .txinfo
6631 @file{@var{n}.dvi} is made from @file{@var{n}.texinfo},
6632 @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command
6633 @w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}.  @file{@var{n}.info} is made from
6634 @file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with
6635 the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}.
6637 @item RCS
6638 @cindex RCS, rule to extract from
6639 @pindex co
6640 @pindex ,v @r{(RCS file extension)}
6641 Any file @file{@var{n}} is extracted if necessary from an RCS file
6642 named either @file{@var{n},v} or @file{RCS/@var{n},v}.  The precise
6643 command used is @w{@samp{$(CO) $(COFLAGS)}}.  @file{@var{n}} will not be
6644 extracted from RCS if it already exists, even if the RCS file is
6645 newer.  The rules for RCS are terminal
6646 (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6647 so RCS files cannot be generated from another source; they must
6648 actually exist.@refill
6650 @item SCCS
6651 @cindex SCCS, rule to extract from
6652 @pindex get
6653 @pindex s. @r{(SCCS file prefix)}
6654 Any file @file{@var{n}} is extracted if necessary from an SCCS file
6655 named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}.  The precise
6656 command used is @w{@samp{$(GET) $(GFLAGS)}}.  The rules for SCCS are
6657 terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6658 so SCCS files cannot be generated from another source; they must
6659 actually exist.@refill
6661 @pindex .sh
6662 For the benefit of SCCS, a file @file{@var{n}} is copied from
6663 @file{@var{n}.sh} and made executable (by everyone).  This is for
6664 shell scripts that are checked into SCCS.  Since RCS preserves the
6665 execution permission of a file, you do not need to use this feature
6666 with RCS.@refill
6668 We recommend that you avoid using of SCCS.  RCS is widely held to be
6669 superior, and is also free.  By choosing free software in place of
6670 comparable (or inferior) proprietary software, you support the free
6671 software movement.
6672 @end table
6674 Usually, you want to change only the variables listed in the table
6675 above, which are documented in the following section.
6677 However, the commands in built-in implicit rules actually use
6678 variables such as @code{COMPILE.c}, @code{LINK.p}, and
6679 @code{PREPROCESS.S}, whose values contain the commands listed above.
6681 @code{make} follows the convention that the rule to compile a
6682 @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
6683 Similarly, the rule to produce an executable from a @file{.@var{x}}
6684 file uses @code{LINK.@var{x}}; and the rule to preprocess a
6685 @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
6687 @vindex OUTPUT_OPTION
6688 Every rule that produces an object file uses the variable
6689 @code{OUTPUT_OPTION}.  @code{make} defines this variable either to
6690 contain @samp{-o $@@}, or to be empty, depending on a compile-time
6691 option.  You need the @samp{-o} option to ensure that the output goes
6692 into the right file when the source file is in a different directory,
6693 as when using @code{VPATH} (@pxref{Directory Search}).  However,
6694 compilers on some systems do not accept a @samp{-o} switch for object
6695 files.  If you use such a system, and use @code{VPATH}, some
6696 compilations will put their output in the wrong place.
6697 A possible workaround for this problem is to give @code{OUTPUT_OPTION}
6698 the value @w{@samp{; mv $*.o $@@}}.
6700 @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
6701 @section Variables Used by Implicit Rules
6702 @cindex flags for compilers
6704 The commands in built-in implicit rules make liberal use of certain
6705 predefined variables.  You can alter these variables in the makefile,
6706 with arguments to @code{make}, or in the environment to alter how the
6707 implicit rules work without redefining the rules themselves.
6709 For example, the command used to compile a C source file actually says
6710 @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}.  The default values of the variables
6711 used are @samp{cc} and nothing, resulting in the command @samp{cc -c}.  By
6712 redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
6713 used for all C compilations performed by the implicit rule.  By redefining
6714 @samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
6715 each compilation.  @emph{All} implicit rules that do C compilation use
6716 @samp{$(CC)} to get the program name for the compiler and @emph{all}
6717 include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
6719 The variables used in implicit rules fall into two classes: those that are
6720 names of programs (like @code{CC}) and those that contain arguments for the
6721 programs (like @code{CFLAGS}).  (The ``name of a program'' may also contain
6722 some command arguments, but it must start with an actual executable program
6723 name.)  If a variable value contains more than one argument, separate them
6724 with spaces.
6726 Here is a table of variables used as names of programs in built-in rules:
6728 @table @code
6729 @item AR
6730 @vindex AR
6731 Archive-maintaining program; default @samp{ar}.
6732 @pindex ar
6734 @item AS
6735 @vindex AS
6736 Program for doing assembly; default @samp{as}.
6737 @pindex as
6739 @item CC
6740 @vindex CC
6741 Program for compiling C programs; default @samp{cc}.
6742 @pindex cc
6744 @item CXX
6745 @vindex CXX
6746 Program for compiling C++ programs; default @samp{g++}.
6747 @pindex g++
6749 @item CO
6750 @vindex CO
6751 Program for extracting a file from RCS; default @samp{co}.
6752 @pindex co
6754 @item CPP
6755 @vindex CPP
6756 Program for running the C preprocessor, with results to standard output;
6757 default @samp{$(CC) -E}.
6759 @item FC
6760 @vindex FC
6761 Program for compiling or preprocessing Fortran and Ratfor programs;
6762 default @samp{f77}.
6763 @pindex f77
6765 @item GET
6766 @vindex GET
6767 Program for extracting a file from SCCS; default @samp{get}.
6768 @pindex get
6770 @item LEX
6771 @vindex LEX
6772 Program to use to turn Lex grammars into C programs or Ratfor programs;
6773 default @samp{lex}.
6774 @pindex lex
6776 @item PC
6777 @vindex PC
6778 Program for compiling Pascal programs; default @samp{pc}.
6779 @pindex pc
6781 @item YACC
6782 @vindex YACC
6783 Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
6784 @pindex yacc
6786 @item YACCR
6787 @vindex YACCR
6788 Program to use to turn Yacc grammars into Ratfor
6789 programs; default @samp{yacc -r}.
6791 @item MAKEINFO
6792 @vindex MAKEINFO
6793 Program to convert a Texinfo source file into an Info file; default
6794 @samp{makeinfo}.
6795 @pindex makeinfo
6797 @item TEX
6798 @vindex TEX
6799 Program to make @TeX{} @sc{dvi} files from @TeX{} source;
6800 default @samp{tex}.
6801 @pindex tex
6803 @item TEXI2DVI
6804 @vindex TEXI2DVI
6805 Program to make @TeX{} @sc{dvi} files from Texinfo source;
6806 default @samp{texi2dvi}.
6807 @pindex texi2dvi
6809 @item WEAVE
6810 @vindex WEAVE
6811 Program to translate Web into @TeX{}; default @samp{weave}.
6812 @pindex weave
6814 @item CWEAVE
6815 @vindex CWEAVE
6816 Program to translate C Web into @TeX{}; default @samp{cweave}.
6817 @pindex cweave
6819 @item TANGLE
6820 @vindex TANGLE
6821 Program to translate Web into Pascal; default @samp{tangle}.
6822 @pindex tangle
6824 @item CTANGLE
6825 @vindex CTANGLE
6826 Program to translate C Web into C; default @samp{ctangle}.
6827 @pindex ctangle
6829 @item RM
6830 @vindex RM
6831 Command to remove a file; default @samp{rm -f}.
6832 @pindex rm
6833 @end table
6835 Here is a table of variables whose values are additional arguments for the
6836 programs above.  The default values for all of these is the empty
6837 string, unless otherwise noted.
6839 @table @code
6840 @item ARFLAGS
6841 @vindex ARFLAGS
6842 Flags to give the archive-maintaining program; default @samp{rv}.
6844 @item ASFLAGS
6845 @vindex ASFLAGS
6846 Extra flags to give to the assembler (when explicitly
6847 invoked on a @samp{.s} or @samp{.S} file).
6849 @item CFLAGS
6850 @vindex CFLAGS
6851 Extra flags to give to the C compiler.
6853 @item CXXFLAGS
6854 @vindex CXXFLAGS
6855 Extra flags to give to the C++ compiler.
6857 @item COFLAGS
6858 @vindex COFLAGS
6859 Extra flags to give to the RCS @code{co} program.
6861 @item CPPFLAGS
6862 @vindex CPPFLAGS
6863 Extra flags to give to the C preprocessor and programs
6864 that use it (the C and Fortran compilers).
6866 @item FFLAGS
6867 @vindex FFLAGS
6868 Extra flags to give to the Fortran compiler.
6870 @item GFLAGS
6871 @vindex GFLAGS
6872 Extra flags to give to the SCCS @code{get} program.
6874 @item LDFLAGS
6875 @vindex LDFLAGS
6876 Extra flags to give to compilers when they are
6877 supposed to invoke the linker, @samp{ld}.
6879 @item LFLAGS
6880 @vindex LFLAGS
6881 Extra flags to give to Lex.
6883 @item PFLAGS
6884 @vindex PFLAGS
6885 Extra flags to give to the Pascal compiler.
6887 @item RFLAGS
6888 @vindex RFLAGS
6889 Extra flags to give to the Fortran compiler for Ratfor programs.
6891 @item YFLAGS
6892 @vindex YFLAGS
6893 Extra flags to give to Yacc.
6894 @end table
6896 @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
6897 @section Chains of Implicit Rules
6899 @cindex chains of rules
6900 @cindex rule, implicit, chains of
6901 Sometimes a file can be made by a sequence of implicit rules.  For example,
6902 a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
6903 first Yacc and then @code{cc}.  Such a sequence is called a @dfn{chain}.
6905 If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
6906 special searching is required: @code{make} finds that the object file can
6907 be made by C compilation from @file{@var{n}.c}; later on, when considering
6908 how to make @file{@var{n}.c}, the rule for running Yacc is
6909 used.  Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
6910 updated.@refill
6912 @cindex intermediate files
6913 @cindex files, intermediate
6914 However, even if @file{@var{n}.c} does not exist and is not mentioned,
6915 @code{make} knows how to envision it as the missing link between
6916 @file{@var{n}.o} and @file{@var{n}.y}!  In this case, @file{@var{n}.c} is
6917 called an @dfn{intermediate file}.  Once @code{make} has decided to use the
6918 intermediate file, it is entered in the data base as if it had been
6919 mentioned in the makefile, along with the implicit rule that says how to
6920 create it.@refill
6922 Intermediate files are remade using their rules just like all other
6923 files.  But intermediate files are treated differently in two ways.
6925 The first difference is what happens if the intermediate file does not
6926 exist.  If an ordinary file @var{b} does not exist, and @code{make}
6927 considers a target that depends on @var{b}, it invariably creates
6928 @var{b} and then updates the target from @var{b}.  But if @var{b} is an
6929 intermediate file, then @code{make} can leave well enough alone.  It
6930 won't bother updating @var{b}, or the ultimate target, unless some
6931 dependency of @var{b} is newer than that target or there is some other
6932 reason to update that target.
6934 The second difference is that if @code{make} @emph{does} create @var{b}
6935 in order to update something else, it deletes @var{b} later on after it
6936 is no longer needed.  Therefore, an intermediate file which did not
6937 exist before @code{make} also does not exist after @code{make}.
6938 @code{make} reports the deletion to you by printing a @samp{rm -f}
6939 command showing which file it is deleting.
6941 Ordinarily, a file cannot be intermediate if it is mentioned in the
6942 makefile as a target or dependency.  However, you can explicitly mark a
6943 file as intermediate by listing it as a dependency of the special target
6944 @code{.INTERMEDIATE}.  This takes effect even if the file is mentioned
6945 explicitly in some other way.
6947 @cindex intermediate files, preserving
6948 @cindex preserving intermediate files
6949 @cindex secondary files
6950 You can prevent automatic deletion of an intermediate file by marking it
6951 as a @dfn{secondary} file.  To do this, list it as a dependency of the
6952 special target @code{.SECONDARY}.  When a file is secondary, @code{make}
6953 will not create the file merely because it does not already exist, but
6954 @code{make} does not automatically delete the file.  Marking a file as
6955 secondary also marks it as intermediate.
6957 You can list the target pattern of an implicit rule (such as @samp{%.o})
6958 as a dependency of the special target @code{.PRECIOUS} to preserve
6959 intermediate files made by implicit rules whose target patterns match
6960 that file's name; see @ref{Interrupts}.@refill
6961 @cindex preserving with @code{.PRECIOUS}
6962 @cindex @code{.PRECIOUS} intermediate files
6964 A chain can involve more than two implicit rules.  For example, it is
6965 possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
6966 Yacc and @code{cc}.  Then both @file{foo.y} and @file{foo.c} are
6967 intermediate files that are deleted at the end.@refill
6969 No single implicit rule can appear more than once in a chain.  This means
6970 that @code{make} will not even consider such a ridiculous thing as making
6971 @file{foo} from @file{foo.o.o} by running the linker twice.  This
6972 constraint has the added benefit of preventing any infinite loop in the
6973 search for an implicit rule chain.
6975 There are some special implicit rules to optimize certain cases that would
6976 otherwise be handled by rule chains.  For example, making @file{foo} from
6977 @file{foo.c} could be handled by compiling and linking with separate
6978 chained rules, using @file{foo.o} as an intermediate file.  But what
6979 actually happens is that a special rule for this case does the compilation
6980 and linking with a single @code{cc} command.  The optimized rule is used in
6981 preference to the step-by-step chain because it comes earlier in the
6982 ordering of rules.
6984 @node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
6985 @section Defining and Redefining Pattern Rules
6987 You define an implicit rule by writing a @dfn{pattern rule}.  A pattern
6988 rule looks like an ordinary rule, except that its target contains the
6989 character @samp{%} (exactly one of them).  The target is considered a
6990 pattern for matching file names; the @samp{%} can match any nonempty
6991 substring, while other characters match only themselves.  The dependencies
6992 likewise use @samp{%} to show how their names relate to the target name.
6994 Thus, a pattern rule @samp{%.o : %.c} says how to make any file
6995 @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
6997 Note that expansion using @samp{%} in pattern rules occurs
6998 @strong{after} any variable or function expansions, which take place
6999 when the makefile is read.  @xref{Using Variables, , How to Use
7000 Variables}, and @ref{Functions, ,Functions for Transforming Text}.
7002 @menu
7003 * Pattern Intro::               An introduction to pattern rules.
7004 * Pattern Examples::            Examples of pattern rules.
7005 * Automatic::                   How to use automatic variables in the
7006                                   commands of implicit rules.
7007 * Pattern Match::               How patterns match.
7008 * Match-Anything Rules::        Precautions you should take prior to
7009                                   defining rules that can match any
7010                                   target file whatever.
7011 * Canceling Rules::             How to override or cancel built-in rules.
7012 @end menu
7014 @node Pattern Intro, Pattern Examples,  , Pattern Rules
7015 @subsection Introduction to Pattern Rules
7016 @cindex pattern rule
7017 @cindex rule, pattern
7019 A pattern rule contains the character @samp{%} (exactly one of them)
7020 in the target; otherwise, it looks exactly like an ordinary rule.  The
7021 target is a pattern for matching file names; the @samp{%} matches any
7022 nonempty substring, while other characters match only themselves.
7023 @cindex target pattern, implicit
7024 @cindex @code{%}, in pattern rules
7026 For example, @samp{%.c} as a pattern matches any file name that ends in
7027 @samp{.c}.  @samp{s.%.c} as a pattern matches any file name that starts
7028 with @samp{s.}, ends in @samp{.c} and is at least five characters long.
7029 (There must be at least one character to match the @samp{%}.)  The substring
7030 that the @samp{%} matches is called the @dfn{stem}.@refill
7032 @samp{%} in a dependency of a pattern rule stands for the same stem
7033 that was matched by the @samp{%} in the target.  In order for
7034 the pattern rule to apply, its target pattern must match the file name
7035 under consideration, and its dependency patterns must name files that
7036 exist or can be made.  These files become dependencies of the target.
7037 @cindex dependency pattern, implicit
7039 Thus, a rule of the form
7041 @example
7042 %.o : %.c ; @var{command}@dots{}
7043 @end example
7045 @noindent
7046 specifies how to make a file @file{@var{n}.o}, with another file
7047 @file{@var{n}.c} as its dependency, provided that @file{@var{n}.c}
7048 exists or can be made.
7050 There may also be dependencies that do not use @samp{%}; such a dependency
7051 attaches to every file made by this pattern rule.  These unvarying
7052 dependencies are useful occasionally.
7054 A pattern rule need not have any dependencies that contain @samp{%}, or
7055 in fact any dependencies at all.  Such a rule is effectively a general
7056 wildcard.  It provides a way to make any file that matches the target
7057 pattern.  @xref{Last Resort}.
7059 @c !!! The end of of this paragraph should be rewritten.  --bob
7060 Pattern rules may have more than one target.  Unlike normal rules, this
7061 does not act as many different rules with the same dependencies and
7062 commands.  If a pattern rule has multiple targets, @code{make} knows that
7063 the rule's commands are responsible for making all of the targets.  The
7064 commands are executed only once to make all the targets.  When searching
7065 for a pattern rule to match a target, the target patterns of a rule other
7066 than the one that matches the target in need of a rule are incidental:
7067 @code{make} worries only about giving commands and dependencies to the file
7068 presently in question.  However, when this file's commands are run, the
7069 other targets are marked as having been updated themselves.
7070 @cindex multiple targets, in pattern rule
7071 @cindex target, multiple in pattern rule
7073 The order in which pattern rules appear in the makefile is important
7074 since this is the order in which they are considered.
7075 Of equally applicable
7076 rules, only the first one found is used.  The rules you write take precedence
7077 over those that are built in.  Note however, that a rule whose
7078 dependencies actually exist or are mentioned always takes priority over a
7079 rule with dependencies that must be made by chaining other implicit rules.
7080 @cindex pattern rules, order of
7081 @cindex order of pattern rules
7083 @node Pattern Examples, Automatic, Pattern Intro, Pattern Rules
7084 @subsection Pattern Rule Examples
7086 Here are some examples of pattern rules actually predefined in
7087 @code{make}.  First, the rule that compiles @samp{.c} files into @samp{.o}
7088 files:@refill
7090 @example
7091 %.o : %.c
7092         $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
7093 @end example
7095 @noindent
7096 defines a rule that can make any file @file{@var{x}.o} from
7097 @file{@var{x}.c}.  The command uses the automatic variables @samp{$@@} and
7098 @samp{$<} to substitute the names of the target file and the source file
7099 in each case where the rule applies (@pxref{Automatic, ,Automatic Variables}).@refill
7101 Here is a second built-in rule:
7103 @example
7104 % :: RCS/%,v
7105         $(CO) $(COFLAGS) $<
7106 @end example
7108 @noindent
7109 defines a rule that can make any file @file{@var{x}} whatsoever from a
7110 corresponding file @file{@var{x},v} in the subdirectory @file{RCS}.  Since
7111 the target is @samp{%}, this rule will apply to any file whatever, provided
7112 the appropriate dependency file exists.  The double colon makes the rule
7113 @dfn{terminal}, which means that its dependency may not be an intermediate
7114 file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
7116 @need 500
7117 This pattern rule has two targets:
7119 @example
7120 @group
7121 %.tab.c %.tab.h: %.y
7122         bison -d $<
7123 @end group
7124 @end example
7126 @noindent
7127 @c The following paragraph is rewritten to avoid overfull hboxes
7128 This tells @code{make} that the command @samp{bison -d @var{x}.y} will
7129 make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}.  If the file
7130 @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
7131 and the file @file{scan.o} depends on the file @file{parse.tab.h},
7132 when @file{parse.y} is changed, the command @samp{bison -d parse.y}
7133 will be executed only once, and the dependencies of both
7134 @file{parse.tab.o} and @file{scan.o} will be satisfied.  (Presumably
7135 the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
7136 and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
7137 linked from @file{parse.tab.o}, @file{scan.o}, and its other
7138 dependencies, and it will execute happily ever after.)@refill
7140 @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
7141 @subsection Automatic Variables
7142 @cindex automatic variables
7143 @cindex variables, automatic
7144 @cindex variables, and implicit rule
7146 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
7147 @samp{.o} file: how do you write the @samp{cc} command so that it operates
7148 on the right source file name?  You cannot write the name in the command,
7149 because the name is different each time the implicit rule is applied.
7151 What you do is use a special feature of @code{make}, the @dfn{automatic
7152 variables}.  These variables have values computed afresh for each rule that
7153 is executed, based on the target and dependencies of the rule.  In this
7154 example, you would use @samp{$@@} for the object file name and @samp{$<}
7155 for the source file name.
7157 Here is a table of automatic variables:
7159 @table @code
7160 @vindex $@@
7161 @vindex @@ @r{(automatic variable)}
7162 @item $@@
7163 The file name of the target of the rule.  If the target is an archive
7164 member, then @samp{$@@} is the name of the archive file.  In a pattern
7165 rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
7166 Pattern Rules}), @samp{$@@} is the name of whichever target caused the
7167 rule's commands to be run.
7169 @vindex $%
7170 @vindex % @r{(automatic variable)}
7171 @item $%
7172 The target member name, when the target is an archive member.
7173 @xref{Archives}.  For example, if the target is @file{foo.a(bar.o)} then
7174 @samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}.  @samp{$%} is
7175 empty when the target is not an archive member.
7177 @vindex $<
7178 @vindex < @r{(automatic variable)}
7179 @item $<
7180 The name of the first dependency.  If the target got its commands from
7181 an implicit rule, this will be the first dependency added by the
7182 implicit rule (@pxref{Implicit Rules}).
7184 @vindex $?
7185 @vindex ? @r{(automatic variable)}
7186 @item $?
7187 The names of all the dependencies that are newer than the target, with
7188 spaces between them.  For dependencies which are archive members, only
7189 the member named is used (@pxref{Archives}).
7190 @cindex dependencies, list of changed
7191 @cindex list of changed dependencies
7193 @vindex $^
7194 @vindex ^ @r{(automatic variable)}
7195 @item $^
7196 The names of all the dependencies, with spaces between them.  For
7197 dependencies which are archive members, only the member named is used
7198 (@pxref{Archives}).  A target has only one dependency on each other file
7199 it depends on, no matter how many times each file is listed as a
7200 dependency.  So if you list a dependency more than once for a target,
7201 the value of @code{$^} contains just one copy of the name.
7202 @cindex dependencies, list of all
7203 @cindex list of all dependencies
7205 @vindex $+
7206 @vindex + @r{(automatic variable)}
7207 @item $+
7208 This is like @samp{$^}, but dependencies listed more than once are
7209 duplicated in the order they were listed in the makefile.  This is
7210 primarily useful for use in linking commands where it is meaningful to
7211 repeat library file names in a particular order.
7213 @vindex $*
7214 @vindex * @r{(automatic variable)}
7215 @item $*
7216 The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
7217 Patterns Match}).  If the target is @file{dir/a.foo.b} and the target
7218 pattern is @file{a.%.b} then the stem is @file{dir/foo}.  The stem is
7219 useful for constructing names of related files.@refill
7220 @cindex stem, variable for
7222 In a static pattern rule, the stem is part of the file name that matched
7223 the @samp{%} in the target pattern.
7225 In an explicit rule, there is no stem; so @samp{$*} cannot be determined
7226 in that way.  Instead, if the target name ends with a recognized suffix
7227 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
7228 the target name minus the suffix.  For example, if the target name is
7229 @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
7230 suffix.  GNU @code{make} does this bizarre thing only for compatibility
7231 with other implementations of @code{make}.  You should generally avoid
7232 using @samp{$*} except in implicit rules or static pattern rules.@refill
7234 If the target name in an explicit rule does not end with a recognized
7235 suffix, @samp{$*} is set to the empty string for that rule.
7236 @end table
7238 @samp{$?} is useful even in explicit rules when you wish to operate on only
7239 the dependencies that have changed.  For example, suppose that an archive
7240 named @file{lib} is supposed to contain copies of several object files.
7241 This rule copies just the changed object files into the archive:
7243 @example
7244 @group
7245 lib: foo.o bar.o lose.o win.o
7246         ar r lib $?
7247 @end group
7248 @end example
7250 Of the variables listed above, four have values that are single file
7251 names, and two have values that are lists of file names.  These six have
7252 variants that get just the file's directory name or just the file name
7253 within the directory.  The variant variables' names are formed by
7254 appending @samp{D} or @samp{F}, respectively.  These variants are
7255 semi-obsolete in GNU @code{make} since the functions @code{dir} and
7256 @code{notdir} can be used to get a similar effect (@pxref{Filename
7257 Functions, , Functions for File Names}).  Note, however, that the
7258 @samp{F} variants all omit the trailing slash which always appears in
7259 the output of the @code{dir} function.  Here is a table of the variants:
7261 @table @samp
7262 @vindex $(@@D)
7263 @vindex @@D @r{(automatic variable)}
7264 @item $(@@D)
7265 The directory part of the file name of the target, with the trailing
7266 slash removed.  If the value of @samp{$@@} is @file{dir/foo.o} then
7267 @samp{$(@@D)} is @file{dir}.  This value is @file{.} if @samp{$@@} does
7268 not contain a slash.
7270 @vindex $(@@F)
7271 @vindex @@F @r{(automatic variable)}
7272 @item $(@@F)
7273 The file-within-directory part of the file name of the target.  If the
7274 value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
7275 @file{foo.o}.  @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
7277 @vindex $(*D)
7278 @vindex *D @r{(automatic variable)}
7279 @item $(*D)
7280 @vindex $(*F)
7281 @vindex *F @r{(automatic variable)}
7282 @itemx $(*F)
7283 The directory part and the file-within-directory
7284 part of the stem; @file{dir} and @file{foo} in this example.
7286 @vindex $(%D)
7287 @vindex %D @r{(automatic variable)}
7288 @item $(%D)
7289 @vindex $(%F)
7290 @vindex %F @r{(automatic variable)}
7291 @itemx $(%F)
7292 The directory part and the file-within-directory part of the target
7293 archive member name.  This makes sense only for archive member targets
7294 of the form @file{@var{archive}(@var{member})} and is useful only when
7295 @var{member} may contain a directory name.  (@xref{Archive Members,
7296 ,Archive Members as Targets}.)
7298 @vindex $(<D)
7299 @vindex <D @r{(automatic variable)}
7300 @item $(<D)
7301 @vindex $(<F)
7302 @vindex <F @r{(automatic variable)}
7303 @itemx $(<F)
7304 The directory part and the file-within-directory
7305 part of the first dependency.
7307 @vindex $(^D)
7308 @vindex ^D @r{(automatic variable)}
7309 @item $(^D)
7310 @vindex $(^F)
7311 @vindex ^F @r{(automatic variable)}
7312 @itemx $(^F)
7313 Lists of the directory parts and the file-within-directory
7314 parts of all dependencies.
7316 @vindex $(?D)
7317 @vindex ?D @r{(automatic variable)}
7318 @item $(?D)
7319 @vindex $(?F)
7320 @vindex ?F @r{(automatic variable)}
7321 @itemx $(?F)
7322 Lists of the directory parts and the file-within-directory parts of
7323 all dependencies that are newer than the target.
7324 @end table
7326 Note that we use a special stylistic convention when we talk about these
7327 automatic variables; we write ``the value of @samp{$<}'', rather than
7328 @w{``the variable @code{<}''} as we would write for ordinary variables
7329 such as @code{objects} and @code{CFLAGS}.  We think this convention
7330 looks more natural in this special case.  Please do not assume it has a
7331 deep significance; @samp{$<} refers to the variable named @code{<} just
7332 as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
7333 You could just as well use @samp{$(<)} in place of @samp{$<}.
7335 @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
7336 @subsection How Patterns Match
7338 @cindex stem
7339 A target pattern is composed of a @samp{%} between a prefix and a suffix,
7340 either or both of which may be empty.  The pattern matches a file name only
7341 if the file name starts with the prefix and ends with the suffix, without
7342 overlap.  The text between the prefix and the suffix is called the
7343 @dfn{stem}.  Thus, when the pattern @samp{%.o} matches the file name
7344 @file{test.o}, the stem is @samp{test}.  The pattern rule dependencies are
7345 turned into actual file names by substituting the stem for the character
7346 @samp{%}.  Thus, if in the same example one of the dependencies is written
7347 as @samp{%.c}, it expands to @samp{test.c}.@refill
7349 When the target pattern does not contain a slash (and it usually does
7350 not), directory names in the file names are removed from the file name
7351 before it is compared with the target prefix and suffix.  After the
7352 comparison of the file name to the target pattern, the directory
7353 names, along with the slash that ends them, are added on to the
7354 dependency file names generated from the pattern rule's dependency
7355 patterns and the file name. The directories are ignored only for the
7356 purpose of finding an implicit rule to use, not in the application of
7357 that rule.  Thus, @samp{e%t} matches the file name @file{src/eat},
7358 with @samp{src/a} as the stem.  When dependencies are turned into file
7359 names, the directories from the stem are added at the front, while the
7360 rest of the stem is substituted for the @samp{%}.  The stem
7361 @samp{src/a} with a dependency pattern @samp{c%r} gives the file name
7362 @file{src/car}.@refill
7364 @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
7365 @subsection Match-Anything Pattern Rules
7367 @cindex match-anything rule
7368 @cindex terminal rule
7369 When a pattern rule's target is just @samp{%}, it matches any file name
7370 whatever.  We call these rules @dfn{match-anything} rules.  They are very
7371 useful, but it can take a lot of time for @code{make} to think about them,
7372 because it must consider every such rule for each file name listed either
7373 as a target or as a dependency.
7375 Suppose the makefile mentions @file{foo.c}.  For this target, @code{make}
7376 would have to consider making it by linking an object file @file{foo.c.o},
7377 or by C compilation-and-linking in one step from @file{foo.c.c}, or by
7378 Pascal compilation-and-linking from @file{foo.c.p}, and many other
7379 possibilities.
7381 We know these possibilities are ridiculous since @file{foo.c} is a C source
7382 file, not an executable.  If @code{make} did consider these possibilities,
7383 it would ultimately reject them, because files such as @file{foo.c.o} and
7384 @file{foo.c.p} would not exist.  But these possibilities are so
7385 numerous that @code{make} would run very slowly if it had to consider
7386 them.@refill
7388 To gain speed, we have put various constraints on the way @code{make}
7389 considers match-anything rules.  There are two different constraints that
7390 can be applied, and each time you define a match-anything rule you must
7391 choose one or the other for that rule.
7393 One choice is to mark the match-anything rule as @dfn{terminal} by defining
7394 it with a double colon.  When a rule is terminal, it does not apply unless
7395 its dependencies actually exist.  Dependencies that could be made with
7396 other implicit rules are not good enough.  In other words, no further
7397 chaining is allowed beyond a terminal rule.
7399 For example, the built-in implicit rules for extracting sources from RCS
7400 and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
7401 not exist, @code{make} will not even consider trying to make it as an
7402 intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
7403 RCS and SCCS files are generally ultimate source files, which should not be
7404 remade from any other files; therefore, @code{make} can save time by not
7405 looking for ways to remake them.@refill
7407 If you do not mark the match-anything rule as terminal, then it is
7408 nonterminal.  A nonterminal match-anything rule cannot apply to a file name
7409 that indicates a specific type of data.  A file name indicates a specific
7410 type of data if some non-match-anything implicit rule target matches it.
7412 For example, the file name @file{foo.c} matches the target for the pattern
7413 rule @samp{%.c : %.y} (the rule to run Yacc).  Regardless of whether this
7414 rule is actually applicable (which happens only if there is a file
7415 @file{foo.y}), the fact that its target matches is enough to prevent
7416 consideration of any nonterminal match-anything rules for the file
7417 @file{foo.c}.  Thus, @code{make} will not even consider trying to make
7418 @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
7419 @file{foo.c.p}, etc.@refill
7421 The motivation for this constraint is that nonterminal match-anything
7422 rules are used for making files containing specific types of data (such as
7423 executable files) and a file name with a recognized suffix indicates some
7424 other specific type of data (such as a C source file).
7426 Special built-in dummy pattern rules are provided solely to recognize
7427 certain file names so that nonterminal match-anything rules will not be
7428 considered.  These dummy rules have no dependencies and no commands, and
7429 they are ignored for all other purposes.  For example, the built-in
7430 implicit rule
7432 @example
7433 %.p :
7434 @end example
7436 @noindent
7437 exists to make sure that Pascal source files such as @file{foo.p} match a
7438 specific target pattern and thereby prevent time from being wasted looking
7439 for @file{foo.p.o} or @file{foo.p.c}.
7441 Dummy pattern rules such as the one for @samp{%.p} are made for every
7442 suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
7444 @node Canceling Rules,  , Match-Anything Rules, Pattern Rules
7445 @subsection Canceling Implicit Rules
7447 You can override a built-in implicit rule (or one you have defined
7448 yourself) by defining a new pattern rule with the same target and
7449 dependencies, but different commands.  When the new rule is defined, the
7450 built-in one is replaced.  The new rule's position in the sequence of
7451 implicit rules is determined by where you write the new rule.
7453 You can cancel a built-in implicit rule by defining a pattern rule with the
7454 same target and dependencies, but no commands.  For example, the following
7455 would cancel the rule that runs the assembler:
7457 @example
7458 %.o : %.s
7459 @end example
7461 @node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
7462 @section Defining Last-Resort Default Rules
7463 @cindex last-resort default rules
7464 @cindex default rules, last-resort
7466 You can define a last-resort implicit rule by writing a terminal
7467 match-anything pattern rule with no dependencies (@pxref{Match-Anything
7468 Rules}).  This is just like any other pattern rule; the only thing
7469 special about it is that it will match any target.  So such a rule's
7470 commands are used for all targets and dependencies that have no commands
7471 of their own and for which no other implicit rule applies.
7473 For example, when testing a makefile, you might not care if the source
7474 files contain real data, only that they exist.  Then you might do this:
7476 @example
7478         touch $@@
7479 @end example
7481 @noindent
7482 to cause all the source files needed (as dependencies) to be created
7483 automatically.
7485 @findex .DEFAULT
7486 You can instead define commands to be used for targets for which there
7487 are no rules at all, even ones which don't specify commands.  You do
7488 this by writing a rule for the target @code{.DEFAULT}.  Such a rule's
7489 commands are used for all dependencies which do not appear as targets in
7490 any explicit rule, and for which no implicit rule applies.  Naturally,
7491 there is no @code{.DEFAULT} rule unless you write one.
7493 If you use @code{.DEFAULT} with no commands or dependencies:
7495 @example
7496 .DEFAULT:
7497 @end example
7499 @noindent
7500 the commands previously stored for @code{.DEFAULT} are cleared.
7501 Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
7503 If you do not want a target to get the commands from a match-anything
7504 pattern rule or @code{.DEFAULT}, but you also do not want any commands
7505 to be run for the target, you can give it empty commands (@pxref{Empty
7506 Commands, ,Defining Empty Commands}).@refill
7508 You can use a last-resort rule to override part of another makefile.
7509 @xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
7511 @node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
7512 @section Old-Fashioned Suffix Rules
7513 @cindex old-fashioned suffix rules
7514 @cindex suffix rule
7516 @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
7517 @code{make}.  Suffix rules are obsolete because pattern rules are more
7518 general and clearer.  They are supported in GNU @code{make} for
7519 compatibility with old makefiles.  They come in two kinds:
7520 @dfn{double-suffix} and @dfn{single-suffix}.@refill
7522 A double-suffix rule is defined by a pair of suffixes: the target suffix
7523 and the source suffix.  It matches any file whose name ends with the
7524 target suffix.  The corresponding implicit dependency is made by
7525 replacing the target suffix with the source suffix in the file name.  A
7526 two-suffix rule whose target and source suffixes are @samp{.o} and
7527 @samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
7529 A single-suffix rule is defined by a single suffix, which is the source
7530 suffix.  It matches any file name, and the corresponding implicit
7531 dependency name is made by appending the source suffix.  A single-suffix
7532 rule whose source suffix is @samp{.c} is equivalent to the pattern rule
7533 @samp{% : %.c}.
7535 Suffix rule definitions are recognized by comparing each rule's target
7536 against a defined list of known suffixes.  When @code{make} sees a rule
7537 whose target is a known suffix, this rule is considered a single-suffix
7538 rule.  When @code{make} sees a rule whose target is two known suffixes
7539 concatenated, this rule is taken as a double-suffix rule.
7541 For example, @samp{.c} and @samp{.o} are both on the default list of
7542 known suffixes.  Therefore, if you define a rule whose target is
7543 @samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
7544 suffix @samp{.c} and target suffix @samp{.o}.  Here is the old-fashioned
7545 way to define the rule for compiling a C source file:@refill
7547 @example
7548 .c.o:
7549         $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7550 @end example
7552 Suffix rules cannot have any dependencies of their own.  If they have any,
7553 they are treated as normal files with funny names, not as suffix rules.
7554 Thus, the rule:
7556 @example
7557 .c.o: foo.h
7558         $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7559 @end example
7561 @noindent
7562 tells how to make the file @file{.c.o} from the dependency file
7563 @file{foo.h}, and is not at all like the pattern rule:
7565 @example
7566 %.o: %.c foo.h
7567         $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7568 @end example
7570 @noindent
7571 which tells how to make @samp{.o} files from @samp{.c} files, and makes all
7572 @samp{.o} files using this pattern rule also depend on @file{foo.h}.
7574 Suffix rules with no commands are also meaningless.  They do not remove
7575 previous rules as do pattern rules with no commands (@pxref{Canceling
7576 Rules, , Canceling Implicit Rules}).  They simply enter the suffix or pair of suffixes concatenated as
7577 a target in the data base.@refill
7579 @findex .SUFFIXES
7580 The known suffixes are simply the names of the dependencies of the special
7581 target @code{.SUFFIXES}.  You can add your own suffixes by writing a rule
7582 for @code{.SUFFIXES} that adds more dependencies, as in:
7584 @example
7585 .SUFFIXES: .hack .win
7586 @end example
7588 @noindent
7589 which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
7591 If you wish to eliminate the default known suffixes instead of just adding
7592 to them, write a rule for @code{.SUFFIXES} with no dependencies.  By
7593 special dispensation, this eliminates all existing dependencies of
7594 @code{.SUFFIXES}.  You can then write another rule to add the suffixes you
7595 want.  For example,
7597 @example
7598 @group
7599 .SUFFIXES:            # @r{Delete the default suffixes}
7600 .SUFFIXES: .c .o .h   # @r{Define our suffix list}
7601 @end group
7602 @end example
7604 The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
7605 list of suffixes to be empty.
7607 @vindex SUFFIXES
7608 The variable @code{SUFFIXES} is defined to the default list of suffixes
7609 before @code{make} reads any makefiles.  You can change the list of suffixes
7610 with a rule for the special target @code{.SUFFIXES}, but that does not alter
7611 this variable.
7613 @node Search Algorithm,  , Suffix Rules, Implicit Rules
7614 @section Implicit Rule Search Algorithm
7615 @cindex implicit rule, search algorithm
7616 @cindex search algorithm, implicit rule
7618 Here is the procedure @code{make} uses for searching for an implicit rule
7619 for a target @var{t}.  This procedure is followed for each double-colon
7620 rule with no commands, for each target of ordinary rules none of which have
7621 commands, and for each dependency that is not the target of any rule.  It
7622 is also followed recursively for dependencies that come from implicit
7623 rules, in the search for a chain of rules.
7625 Suffix rules are not mentioned in this algorithm because suffix rules are
7626 converted to equivalent pattern rules once the makefiles have been read in.
7628 For an archive member target of the form
7629 @samp{@var{archive}(@var{member})}, the following algorithm is run
7630 twice, first using the entire target name @var{t}, and second using
7631 @samp{(@var{member})} as the target @var{t} if the first run found no
7632 rule.@refill
7634 @enumerate
7635 @item
7636 Split @var{t} into a directory part, called @var{d}, and the rest,
7637 called @var{n}.  For example, if @var{t} is @samp{src/foo.o}, then
7638 @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
7640 @item
7641 Make a list of all the pattern rules one of whose targets matches
7642 @var{t} or @var{n}.  If the target pattern contains a slash, it is
7643 matched against @var{t}; otherwise, against @var{n}.
7645 @item
7646 If any rule in that list is @emph{not} a match-anything rule, then
7647 remove all nonterminal match-anything rules from the list.
7649 @item
7650 Remove from the list all rules with no commands.
7652 @item
7653 For each pattern rule in the list:
7655 @enumerate a
7656 @item
7657 Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
7658 matched by the @samp{%} in the target pattern.@refill
7660 @item
7661 Compute the dependency names by substituting @var{s} for @samp{%}; if
7662 the target pattern does not contain a slash, append @var{d} to
7663 the front of each dependency name.@refill
7665 @item
7666 Test whether all the dependencies exist or ought to exist.  (If a
7667 file name is mentioned in the makefile as a target or as an explicit
7668 dependency, then we say it ought to exist.)
7670 If all dependencies exist or ought to exist, or there are no dependencies,
7671 then this rule applies.
7672 @end enumerate
7674 @item
7675 If no pattern rule has been found so far, try harder.
7676 For each pattern rule in the list:
7678 @enumerate a
7679 @item
7680 If the rule is terminal, ignore it and go on to the next rule.
7682 @item
7683 Compute the dependency names as before.
7685 @item
7686 Test whether all the dependencies exist or ought to exist.
7688 @item
7689 For each dependency that does not exist, follow this algorithm
7690 recursively to see if the dependency can be made by an implicit
7691 rule.
7693 @item
7694 If all dependencies exist, ought to exist, or can be
7695 made by implicit rules, then this rule applies.
7696 @end enumerate
7698 @item
7699 If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
7700 applies.  In that case, give @var{t} the same commands that
7701 @code{.DEFAULT} has.  Otherwise, there are no commands for @var{t}.
7702 @end enumerate
7704 Once a rule that applies has been found, for each target pattern of the
7705 rule other than the one that matched @var{t} or @var{n}, the @samp{%} in
7706 the pattern is replaced with @var{s} and the resultant file name is stored
7707 until the commands to remake the target file @var{t} are executed.  After
7708 these commands are executed, each of these stored file names are entered
7709 into the data base and marked as having been updated and having the same
7710 update status as the file @var{t}.
7712 When the commands of a pattern rule are executed for @var{t}, the automatic
7713 variables are set corresponding to the target and dependencies.
7714 @xref{Automatic, ,Automatic Variables}.
7716 @node Archives, Features, Implicit Rules, Top
7717 @chapter Using @code{make} to Update Archive Files
7718 @cindex archive
7720 @dfn{Archive files} are files containing named subfiles called
7721 @dfn{members}; they are maintained with the program @code{ar} and their
7722 main use is as subroutine libraries for linking.
7724 @menu
7725 * Archive Members::             Archive members as targets.
7726 * Archive Update::              The implicit rule for archive member targets.
7727 * Archive Pitfalls::            Dangers to watch out for when using archives.
7728 * Archive Suffix Rules::        You can write a special kind of suffix rule
7729                                   for updating archives.
7730 @end menu
7732 @node Archive Members, Archive Update,  , Archives
7733 @section Archive Members as Targets
7734 @cindex archive member targets
7736 An individual member of an archive file can be used as a target or
7737 dependency in @code{make}.  You specify the member named @var{member} in
7738 archive file @var{archive} as follows:
7740 @example
7741 @var{archive}(@var{member})
7742 @end example
7744 @noindent
7745 This construct is available only in targets and dependencies, not in
7746 commands!  Most programs that you might use in commands do not support this
7747 syntax and cannot act directly on archive members.  Only @code{ar} and
7748 other programs specifically designed to operate on archives can do so.
7749 Therefore, valid commands to update an archive member target probably must
7750 use @code{ar}.  For example, this rule says to create a member
7751 @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
7753 @example
7754 foolib(hack.o) : hack.o
7755         ar cr foolib hack.o
7756 @end example
7758 In fact, nearly all archive member targets are updated in just this way
7759 and there is an implicit rule to do it for you.  @strong{Note:} The
7760 @samp{c} flag to @code{ar} is required if the archive file does not
7761 already exist.
7763 To specify several members in the same archive, you can write all the
7764 member names together between the parentheses.  For example:
7766 @example
7767 foolib(hack.o kludge.o)
7768 @end example
7770 @noindent
7771 is equivalent to:
7773 @example
7774 foolib(hack.o) foolib(kludge.o)
7775 @end example
7777 @cindex wildcard, in archive member
7778 You can also use shell-style wildcards in an archive member reference.
7779 @xref{Wildcards, ,Using Wildcard Characters in File Names}.  For
7780 example, @w{@samp{foolib(*.o)}} expands to all existing members of the
7781 @file{foolib} archive whose names end in @samp{.o}; perhaps
7782 @samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
7784 @node Archive Update
7785 @section Implicit Rule for Archive Member Targets
7787 Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
7788 member named @var{m} in the archive file @var{a}.
7790 When @code{make} looks for an implicit rule for such a target, as a special
7791 feature it considers implicit rules that match @file{(@var{m})}, as well as
7792 those that match the actual target @file{@var{a}(@var{m})}.
7794 This causes one special rule whose target is @file{(%)} to match.  This
7795 rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
7796 into the archive.  For example, it will update the archive member target
7797 @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
7798 archive @file{foo.a} as a @emph{member} named @file{bar.o}.
7800 When this rule is chained with others, the result is very powerful.
7801 Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
7802 @samp{(} and @samp{)} from being interpreted specially by the shell) in
7803 the presence of a file @file{bar.c} is enough to cause the following
7804 commands to be run, even without a makefile:
7806 @example
7807 cc -c bar.c -o bar.o
7808 ar r foo.a bar.o
7809 rm -f bar.o
7810 @end example
7812 @noindent
7813 Here @code{make} has envisioned the file @file{bar.o} as an intermediate
7814 file.  @xref{Chained Rules, ,Chains of Implicit Rules}.
7816 Implicit rules such as this one are written using the automatic variable
7817 @samp{$%}.  @xref{Automatic, ,Automatic Variables}.
7819 An archive member name in an archive cannot contain a directory name, but
7820 it may be useful in a makefile to pretend that it does.  If you write an
7821 archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
7822 automatic updating with this command:
7824 @example
7825 ar r foo.a dir/file.o
7826 @end example
7828 @noindent
7829 which has the effect of copying the file @file{dir/file.o} into a member
7830 named @file{file.o}.  In connection with such usage, the automatic variables
7831 @code{%D} and @code{%F} may be useful.
7833 @menu
7834 * Archive Symbols::             How to update archive symbol directories.
7835 @end menu
7837 @node Archive Symbols,  ,  , Archive Update
7838 @subsection Updating Archive Symbol Directories
7839 @cindex @code{__.SYMDEF}
7840 @cindex updating archive symbol directories
7841 @cindex archive symbol directory updating
7842 @cindex symbol directories, updating archive
7843 @cindex directories, updating archive symbol
7845 An archive file that is used as a library usually contains a special member
7846 named @file{__.SYMDEF} that contains a directory of the external symbol
7847 names defined by all the other members.  After you update any other
7848 members, you need to update @file{__.SYMDEF} so that it will summarize the
7849 other members properly.  This is done by running the @code{ranlib} program:
7851 @example
7852 ranlib @var{archivefile}
7853 @end example
7855 Normally you would put this command in the rule for the archive file,
7856 and make all the members of the archive file dependencies of that rule.
7857 For example,
7859 @example
7860 libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
7861         ranlib libfoo.a
7862 @end example
7864 @noindent
7865 The effect of this is to update archive members @file{x.o}, @file{y.o},
7866 etc., and then update the symbol directory member @file{__.SYMDEF} by
7867 running @code{ranlib}.  The rules for updating the members are not shown
7868 here; most likely you can omit them and use the implicit rule which copies
7869 files into the archive, as described in the preceding section.
7871 This is not necessary when using the GNU @code{ar} program, which
7872 updates the @file{__.SYMDEF} member automatically.
7874 @node Archive Pitfalls
7875 @section Dangers When Using Archives
7876 @cindex archive, and parallel execution
7877 @cindex parallel execution, and archive update
7878 @cindex archive, and @code{-j}
7879 @cindex @code{-j}, and archive update
7881 It is important to be careful when using parallel execution (the
7882 @code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives.
7883 If multiple @code{ar} commands run at the same time on the same archive
7884 file, they will not know about each other and can corrupt the file.
7886 Possibly a future version of @code{make} will provide a mechanism to
7887 circumvent this problem by serializing all commands that operate on the
7888 same archive file.  But for the time being, you must either write your
7889 makefiles to avoid this problem in some other way, or not use @code{-j}.
7891 @node Archive Suffix Rules, , Archive Pitfalls, Archives
7892 @section Suffix Rules for Archive Files
7893 @cindex suffix rule, for archive
7894 @cindex archive, suffix rule for
7895 @cindex library archive, suffix rule for
7896 @cindex @code{.a} (archives)
7898 You can write a special kind of suffix rule for dealing with archive
7899 files.  @xref{Suffix Rules}, for a full explanation of suffix rules.
7900 Archive suffix rules are obsolete in GNU @code{make}, because pattern
7901 rules for archives are a more general mechanism (@pxref{Archive
7902 Update}).  But they are retained for compatibility with other
7903 @code{make}s.
7905 To write a suffix rule for archives, you simply write a suffix rule
7906 using the target suffix @samp{.a} (the usual suffix for archive files).
7907 For example, here is the old-fashioned suffix rule to update a library
7908 archive from C source files:
7910 @example
7911 @group
7912 .c.a:
7913         $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7914         $(AR) r $@@ $*.o
7915         $(RM) $*.o
7916 @end group
7917 @end example
7919 @noindent
7920 This works just as if you had written the pattern rule:
7922 @example
7923 @group
7924 (%.o): %.c
7925         $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7926         $(AR) r $@@ $*.o
7927         $(RM) $*.o
7928 @end group
7929 @end example
7931 In fact, this is just what @code{make} does when it sees a suffix rule
7932 with @samp{.a} as the target suffix.  Any double-suffix rule
7933 @w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
7934 pattern @samp{(%.o)} and a dependency pattern of @samp{%.@var{x}}.
7936 Since you might want to use @samp{.a} as the suffix for some other kind
7937 of file, @code{make} also converts archive suffix rules to pattern rules
7938 in the normal way (@pxref{Suffix Rules}).  Thus a double-suffix rule
7939 @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
7940 @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
7942 @node Features, Missing, Archives, Top
7943 @chapter Features of GNU @code{make}
7944 @cindex features of GNU @code{make}
7945 @cindex portability
7946 @cindex compatibility
7948 Here is a summary of the features of GNU @code{make}, for comparison
7949 with and credit to other versions of @code{make}.  We consider the
7950 features of @code{make} in 4.2 BSD systems as a baseline.  If you are
7951 concerned with writing portable makefiles, you should use only the
7952 features of @code{make} @emph{not} listed here or in @ref{Missing}.
7954 Many features come from the version of @code{make} in System V.
7956 @itemize @bullet
7957 @item
7958 The @code{VPATH} variable and its special meaning.
7959 @xref{Directory Search, , Searching Directories for Dependencies}.
7960 This feature exists in System V @code{make}, but is undocumented.
7961 It is documented in 4.3 BSD @code{make} (which says it mimics System V's
7962 @code{VPATH} feature).@refill
7964 @item
7965 Included makefiles.  @xref{Include, ,Including Other Makefiles}.
7966 Allowing multiple files to be included with a single directive is a GNU
7967 extension.
7969 @item
7970 Variables are read from and communicated via the environment.
7971 @xref{Environment, ,Variables from the Environment}.
7973 @item
7974 Options passed through the variable @code{MAKEFLAGS} to recursive
7975 invocations of @code{make}.
7976 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
7978 @item
7979 The automatic variable @code{$%} is set to the member name
7980 in an archive reference.  @xref{Automatic, ,Automatic Variables}.
7982 @item
7983 The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
7984 and @code{$?} have corresponding forms like @code{$(@@F)} and
7985 @code{$(@@D)}.  We have generalized this to @code{$^} as an obvious
7986 extension.  @xref{Automatic, ,Automatic Variables}.@refill
7988 @item
7989 Substitution variable references.
7990 @xref{Reference, ,Basics of Variable References}.
7992 @item
7993 The command-line options @samp{-b} and @samp{-m}, accepted and
7994 ignored.  In System V @code{make}, these options actually do something.
7996 @item
7997 Execution of recursive commands to run @code{make} via the variable
7998 @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
7999 @xref{Recursion, ,Recursive Use of @code{make}}.
8001 @item
8002 Support for suffix @samp{.a} in suffix rules.  @xref{Archive Suffix
8003 Rules}.  This feature is obsolete in GNU @code{make}, because the
8004 general feature of rule chaining (@pxref{Chained Rules, ,Chains of
8005 Implicit Rules}) allows one pattern rule for installing members in an
8006 archive (@pxref{Archive Update}) to be sufficient.
8008 @item
8009 The arrangement of lines and backslash-newline combinations in
8010 commands is retained when the commands are printed, so they appear as
8011 they do in the makefile, except for the stripping of initial
8012 whitespace.
8013 @end itemize
8015 The following features were inspired by various other versions of
8016 @code{make}.  In some cases it is unclear exactly which versions inspired
8017 which others.
8019 @itemize @bullet
8020 @item
8021 Pattern rules using @samp{%}.
8022 This has been implemented in several versions of @code{make}.
8023 We're not sure who invented it first, but it's been spread around a bit.
8024 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
8026 @item
8027 Rule chaining and implicit intermediate files.
8028 This was implemented by Stu Feldman in his version of @code{make}
8029 for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
8030 AT&T Bell Labs in his @code{mk} program (where he terms it
8031 ``transitive closure'').  We do not really know if
8032 we got this from either of them or thought it up ourselves at the
8033 same time.  @xref{Chained Rules, ,Chains of Implicit Rules}.
8035 @item
8036 The automatic variable @code{$^} containing a list of all dependencies
8037 of the current target.  We did not invent this, but we have no idea who
8038 did.  @xref{Automatic, ,Automatic Variables}.  The automatic variable
8039 @code{$+} is a simple extension of @code{$^}.
8041 @item
8042 The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
8043 invented by Andrew Hume in @code{mk}.
8044 @xref{Instead of Execution, ,Instead of Executing the Commands}.
8046 @item
8047 The concept of doing several things at once (parallelism) exists in
8048 many incarnations of @code{make} and similar programs, though not in the
8049 System V or BSD implementations.  @xref{Execution, ,Command Execution}.
8051 @item
8052 Modified variable references using pattern substitution come from
8053 SunOS 4.  @xref{Reference, ,Basics of Variable References}.
8054 This functionality was provided in GNU @code{make} by the
8055 @code{patsubst} function before the alternate syntax was implemented
8056 for compatibility with SunOS 4.  It is not altogether clear who
8057 inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
8058 4 was released.@refill
8060 @item
8061 The special significance of @samp{+} characters preceding command lines
8062 (@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
8063 mandated by
8064 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
8066 @item
8067 The @samp{+=} syntax to append to the value of a variable comes from SunOS
8068 4 @code{make}.  @xref{Appending, , Appending More Text to Variables}.
8070 @item
8071 The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
8072 multiple members in a single archive file comes from SunOS 4 @code{make}.
8073 @xref{Archive Members}.
8075 @item
8076 The @code{-include} directive to include makefiles with no error for a
8077 nonexistent file comes from SunOS 4 @code{make}.  (But note that SunOS 4
8078 @code{make} does not allow multiple makefiles to be specified in one
8079 @code{-include} directive.)  The same feature appears with the name
8080 @code{sinclude} in SGI @code{make} and perhaps others.
8081 @end itemize
8083 The remaining features are inventions new in GNU @code{make}:
8085 @itemize @bullet
8086 @item
8087 Use the @samp{-v} or @samp{--version} option to print version and
8088 copyright information.
8090 @item
8091 Use the @samp{-h} or @samp{--help} option to summarize the options to
8092 @code{make}.
8094 @item
8095 Simply-expanded variables.  @xref{Flavors, ,The Two Flavors of Variables}.
8097 @item
8098 Pass command-line variable assignments automatically through the
8099 variable @code{MAKE} to recursive @code{make} invocations.
8100 @xref{Recursion, ,Recursive Use of @code{make}}.
8102 @item
8103 Use the @samp{-C} or @samp{--directory} command option to change
8104 directory.  @xref{Options Summary, ,Summary of Options}.
8106 @item
8107 Make verbatim variable definitions with @code{define}.
8108 @xref{Defining, ,Defining Variables Verbatim}.
8110 @item
8111 Declare phony targets with the special target @code{.PHONY}.
8113 Andrew Hume of AT&T Bell Labs implemented a similar feature with a
8114 different syntax in his @code{mk} program.  This seems to be a case of
8115 parallel discovery.  @xref{Phony Targets, ,Phony Targets}.
8117 @item
8118 Manipulate text by calling functions.
8119 @xref{Functions, ,Functions for Transforming Text}.
8121 @item
8122 Use the @samp{-o} or @samp{--old-file}
8123 option to pretend a file's modification-time is old.
8124 @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
8126 @item
8127 Conditional execution.
8129 This feature has been implemented numerous times in various versions
8130 of @code{make}; it seems a natural extension derived from the features
8131 of the C preprocessor and similar macro languages and is not a
8132 revolutionary concept.  @xref{Conditionals, ,Conditional Parts of Makefiles}.
8134 @item
8135 Specify a search path for included makefiles.
8136 @xref{Include, ,Including Other Makefiles}.
8138 @item
8139 Specify extra makefiles to read with an environment variable.
8140 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
8142 @item
8143 Strip leading sequences of @samp{./} from file names, so that
8144 @file{./@var{file}} and @file{@var{file}} are considered to be the
8145 same file.@refill
8147 @item
8148 Use a special search method for library dependencies written in the
8149 form @samp{-l@var{name}}.
8150 @xref{Libraries/Search, ,Directory Search for Link Libraries}.
8152 @item
8153 Allow suffixes for suffix rules
8154 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
8155 characters.  In other versions of @code{make}, they must begin with
8156 @samp{.} and not contain any @samp{/} characters.
8158 @item
8159 Keep track of the current level of @code{make} recursion using the
8160 variable @code{MAKELEVEL}.  @xref{Recursion, ,Recursive Use of @code{make}}.
8162 @item
8163 Specify static pattern rules.  @xref{Static Pattern, ,Static Pattern Rules}.
8165 @item
8166 Provide selective @code{vpath} search.
8167 @xref{Directory Search, ,Searching Directories for Dependencies}.
8169 @item
8170 Provide computed variable references.
8171 @xref{Reference, ,Basics of Variable References}.
8173 @item
8174 Update makefiles.  @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
8175 System V @code{make} has a very, very limited form of this
8176 functionality in that it will check out SCCS files for makefiles.
8178 @item
8179 Various new built-in implicit rules.
8180 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules}.
8182 @item
8183 The built-in variable @samp{MAKE_VERSION} gives the version number of
8184 @code{make}.
8185 @end itemize
8187 @node Missing, Makefile Conventions, Features, Top
8188 @chapter Incompatibilities and Missing Features
8189 @cindex incompatibilities
8190 @cindex missing features
8191 @cindex features, missing
8193 The @code{make} programs in various other systems support a few features
8194 that are not implemented in GNU @code{make}.  The POSIX.2 standard
8195 (@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
8196 require any of these features.@refill
8198 @itemize @bullet
8199 @item
8200 A target of the form @samp{@var{file}((@var{entry}))} stands for a member
8201 of archive file @var{file}.  The member is chosen, not by name, but by
8202 being an object file which defines the linker symbol @var{entry}.@refill
8204 This feature was not put into GNU @code{make} because of the
8205 nonmodularity of putting knowledge into @code{make} of the internal
8206 format of archive file symbol tables.
8207 @xref{Archive Symbols, ,Updating Archive Symbol Directories}.
8209 @item
8210 Suffixes (used in suffix rules) that end with the character @samp{~}
8211 have a special meaning to System V @code{make};
8212 they refer to the SCCS file that corresponds
8213 to the file one would get without the @samp{~}.  For example, the
8214 suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
8215 the SCCS file @file{s.@var{n}.c}.  For complete coverage, a whole
8216 series of such suffix rules is required.
8217 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
8219 In GNU @code{make}, this entire series of cases is handled by two
8220 pattern rules for extraction from SCCS, in combination with the
8221 general feature of rule chaining.
8222 @xref{Chained Rules, ,Chains of Implicit Rules}.
8224 @item
8225 In System V @code{make}, the string @samp{$$@@} has the strange meaning
8226 that, in the dependencies of a rule with multiple targets, it stands
8227 for the particular target that is being processed.
8229 This is not defined in GNU @code{make} because @samp{$$} should always
8230 stand for an ordinary @samp{$}.
8232 It is possible to get this functionality through the use of static pattern
8233 rules (@pxref{Static Pattern, ,Static Pattern Rules}).
8234 The System V @code{make} rule:
8236 @example
8237 $(targets): $$@@.o lib.a
8238 @end example
8240 @noindent
8241 can be replaced with the GNU @code{make} static pattern rule:
8243 @example
8244 $(targets): %: %.o lib.a
8245 @end example
8247 @item
8248 In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
8249 (@pxref{Directory Search, ,Searching Directories for Dependencies}) have their names changed inside command
8250 strings.  We feel it is much cleaner to always use automatic variables
8251 and thus make this feature obsolete.@refill
8253 @item
8254 In some Unix @code{make}s, the automatic variable @code{$*} appearing in
8255 the dependencies of a rule has the amazingly strange ``feature'' of
8256 expanding to the full name of the @emph{target of that rule}.  We cannot
8257 imagine what went on in the minds of Unix @code{make} developers to do
8258 this; it is utterly inconsistent with the normal definition of @code{$*}.
8259 @vindex * @r{(automatic variable), unsupported bizarre usage}
8261 @item
8262 In some Unix @code{make}s, implicit rule search
8263 (@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for
8264 @emph{all} targets, not just those without commands.  This means you can
8265 do:@refill
8267 @example
8268 @group
8269 foo.o:
8270         cc -c foo.c
8271 @end group
8272 @end example
8274 @noindent
8275 and Unix @code{make} will intuit that @file{foo.o} depends on
8276 @file{foo.c}.@refill
8278 We feel that such usage is broken.  The dependency properties of
8279 @code{make} are well-defined (for GNU @code{make}, at least),
8280 and doing such a thing simply does not fit the model.@refill
8282 @item
8283 GNU @code{make} does not include any built-in implicit rules for
8284 compiling or preprocessing EFL programs.  If we hear of anyone who is
8285 using EFL, we will gladly add them.
8287 @item
8288 It appears that in SVR4 @code{make}, a suffix rule can be specified with
8289 no commands, and it is treated as if it had empty commands
8290 (@pxref{Empty Commands}).  For example:
8292 @example
8293 .c.a:
8294 @end example
8296 @noindent
8297 will override the built-in @file{.c.a} suffix rule.
8299 We feel that it is cleaner for a rule without commands to always simply
8300 add to the dependency list for the target.  The above example can be
8301 easily rewritten to get the desired behavior in GNU @code{make}:
8303 @example
8304 .c.a: ;
8305 @end example
8307 @item
8308 Some versions of @code{make} invoke the shell with the @samp{-e} flag,
8309 except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
8310 Program}).  The @samp{-e} flag tells the shell to exit as soon as any
8311 program it runs returns a nonzero status.  We feel it is cleaner to
8312 write each shell command line to stand on its own and not require this
8313 special treatment.
8314 @end itemize
8316 @comment The makefile standards are in a separate file that is also
8317 @comment included by standards.texi.
8318 @include make-stds.texi
8320 @node Quick Reference, Complex Makefile, Makefile Conventions, Top
8321 @appendix Quick Reference
8323 This appendix summarizes the directives, text manipulation functions,
8324 and special variables which GNU @code{make} understands.
8325 @xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
8326 and @ref{Options Summary, ,Summary of Options},
8327 for other summaries.
8329 Here is a summary of the directives GNU @code{make} recognizes:
8331 @table @code
8332 @item define @var{variable}
8333 @itemx endef
8335 Define a multi-line, recursively-expanded variable.@*
8336 @xref{Sequences}.
8338 @item ifdef @var{variable}
8339 @itemx ifndef @var{variable}
8340 @itemx ifeq (@var{a},@var{b})
8341 @itemx ifeq "@var{a}" "@var{b}"
8342 @itemx ifeq '@var{a}' '@var{b}'
8343 @itemx ifneq (@var{a},@var{b})
8344 @itemx ifneq "@var{a}" "@var{b}"
8345 @itemx ifneq '@var{a}' '@var{b}'
8346 @itemx else
8347 @itemx endif
8349 Conditionally evaluate part of the makefile.@*
8350 @xref{Conditionals}.
8352 @item include @var{file}
8354 Include another makefile.@*
8355 @xref{Include, ,Including Other Makefiles}.
8357 @item override @var{variable} = @var{value}
8358 @itemx override @var{variable} := @var{value}
8359 @itemx override @var{variable} += @var{value}
8360 @itemx override define @var{variable}
8361 @itemx endef
8363 Define a variable, overriding any previous definition, even one from
8364 the command line.@*
8365 @xref{Override Directive, ,The @code{override} Directive}.
8367 @item export
8369 Tell @code{make} to export all variables to child processes by default.@*
8370 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8372 @item export @var{variable}
8373 @itemx export @var{variable} = @var{value}
8374 @itemx export @var{variable} := @var{value}
8375 @itemx export @var{variable} += @var{value}
8376 @itemx unexport @var{variable}
8377 Tell @code{make} whether or not to export a particular variable to child
8378 processes.@*
8379 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8381 @item vpath @var{pattern} @var{path}
8382 Specify a search path for files matching a @samp{%} pattern.@*
8383 @xref{Selective Search, , The @code{vpath} Directive}.
8385 @item vpath @var{pattern}
8386 Remove all search paths previously specified for @var{pattern}.
8388 @item vpath
8389 Remove all search paths previously specified in any @code{vpath}
8390 directive.
8391 @end table
8393 Here is a summary of the text manipulation functions (@pxref{Functions}):
8395 @table @code
8396 @item $(subst @var{from},@var{to},@var{text})
8397 Replace @var{from} with @var{to} in @var{text}.@*
8398 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8400 @item $(patsubst @var{pattern},@var{replacement},@var{text})
8401 Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
8402 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8404 @item $(strip @var{string})
8405 Remove excess whitespace characters from @var{string}.@*
8406 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8408 @item $(findstring @var{find},@var{text})
8409 Locate @var{find} in @var{text}.@*
8410 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8412 @item $(filter @var{pattern}@dots{},@var{text})
8413 Select words in @var{text} that match one of the @var{pattern} words.@*
8414 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8416 @item $(filter-out @var{pattern}@dots{},@var{text})
8417 Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
8418 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8420 @item $(sort @var{list})
8421 Sort the words in @var{list} lexicographically, removing duplicates.@*
8422 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8424 @item $(dir @var{names}@dots{})
8425 Extract the directory part of each file name.@*
8426 @xref{Filename Functions, ,Functions for File Names}.
8428 @item $(notdir @var{names}@dots{})
8429 Extract the non-directory part of each file name.@*
8430 @xref{Filename Functions, ,Functions for File Names}.
8432 @item $(suffix @var{names}@dots{})
8433 Extract the suffix (the last @samp{.} and following characters) of each file name.@*
8434 @xref{Filename Functions, ,Functions for File Names}.
8436 @item $(basename @var{names}@dots{})
8437 Extract the base name (name without suffix) of each file name.@*
8438 @xref{Filename Functions, ,Functions for File Names}.
8440 @item $(addsuffix @var{suffix},@var{names}@dots{})
8441 Append @var{suffix} to each word in @var{names}.@*
8442 @xref{Filename Functions, ,Functions for File Names}.
8444 @item $(addprefix @var{prefix},@var{names}@dots{})
8445 Prepend @var{prefix} to each word in @var{names}.@*
8446 @xref{Filename Functions, ,Functions for File Names}.
8448 @item $(join @var{list1},@var{list2})
8449 Join two parallel lists of words.@*
8450 @xref{Filename Functions, ,Functions for File Names}.
8452 @item $(word @var{n},@var{text})
8453 Extract the @var{n}th word (one-origin) of @var{text}.@*
8454 @xref{Filename Functions, ,Functions for File Names}.
8456 @item $(words @var{text})
8457 Count the number of words in @var{text}.@*
8458 @xref{Filename Functions, ,Functions for File Names}.
8460 @item $(firstword @var{names}@dots{})
8461 Extract the first word of @var{names}.@*
8462 @xref{Filename Functions, ,Functions for File Names}.
8464 @item $(wildcard @var{pattern}@dots{})
8465 Find file names matching a shell file name pattern (@emph{not} a
8466 @samp{%} pattern).@*
8467 @xref{Wildcard Function, ,The Function @code{wildcard}}.
8469 @item $(shell @var{command})
8471 Execute a shell command and return its output.@*
8472 @xref{Shell Function, , The @code{shell} Function}.
8474 @item $(origin @var{variable})
8476 Return a string describing how the @code{make} variable @var{variable} was
8477 defined.@*
8478 @xref{Origin Function, , The @code{origin} Function}.
8480 @item $(foreach @var{var},@var{words},@var{text})
8482 Evaluate @var{text} with @var{var} bound to each word in @var{words},
8483 and concatenate the results.@*
8484 @xref{Foreach Function, ,The @code{foreach} Function}.
8485 @end table
8487 Here is a summary of the automatic variables.
8488 @xref{Automatic, ,Automatic Variables},
8489 for full information.
8491 @table @code
8492 @item $@@
8493 The file name of the target.
8495 @item $%
8496 The target member name, when the target is an archive member.
8498 @item $<
8499 The name of the first dependency.
8501 @item $?
8502 The names of all the dependencies that are
8503 newer than the target, with spaces between them.
8504 For dependencies which are archive members, only
8505 the member named is used (@pxref{Archives}).
8507 @item $^
8508 @itemx $+
8509 The names of all the dependencies, with spaces between them.  For
8510 dependencies which are archive members, only the member named is used
8511 (@pxref{Archives}).  The value of @code{$^} omits duplicate
8512 dependencies, while @code{$+} retains them and preserves their order.
8514 @item $*
8515 The stem with which an implicit rule matches
8516 (@pxref{Pattern Match, ,How Patterns Match}).
8518 @item $(@@D)
8519 @itemx $(@@F)
8520 The directory part and the file-within-directory part of @code{$@@}.
8522 @item $(*D)
8523 @itemx $(*F)
8524 The directory part and the file-within-directory part of @code{$*}.
8526 @item $(%D)
8527 @itemx $(%F)
8528 The directory part and the file-within-directory part of @code{$%}.
8530 @item $(<D)
8531 @itemx $(<F)
8532 The directory part and the file-within-directory part of @code{$<}.
8534 @item $(^D)
8535 @itemx $(^F)
8536 The directory part and the file-within-directory part of @code{$^}.
8538 @item $(+D)
8539 @itemx $(+F)
8540 The directory part and the file-within-directory part of @code{$+}.
8542 @item $(?D)
8543 @itemx $(?F)
8544 The directory part and the file-within-directory part of @code{$?}.
8545 @end table
8547 These variables are used specially by GNU @code{make}:
8549 @table @code
8550 @item MAKEFILES
8552 Makefiles to be read on every invocation of @code{make}.@*
8553 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
8555 @item VPATH
8557 Directory search path for files not found in the current directory.@*
8558 @xref{General Search, , @code{VPATH} Search Path for All Dependencies}.
8560 @item SHELL
8562 The name of the system default command interpreter, usually @file{/bin/sh}.
8563 You can set @code{SHELL} in the makefile to change the shell used to run
8564 commands.  @xref{Execution, ,Command Execution}.
8566 @item MAKE
8568 The name with which @code{make} was invoked.
8569 Using this variable in commands has special meaning.
8570 @xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.
8572 @item MAKELEVEL
8574 The number of levels of recursion (sub-@code{make}s).@*
8575 @xref{Variables/Recursion}.
8577 @item MAKEFLAGS
8579 The flags given to @code{make}.  You can set this in the environment or
8580 a makefile to set flags.@*
8581 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
8583 @item SUFFIXES
8585 The default list of suffixes before @code{make} reads any makefiles.
8586 @end table
8588 @node Complex Makefile, Concept Index, Quick Reference, Top
8589 @appendix Complex Makefile Example
8591 Here is the makefile for the GNU @code{tar} program.  This is a
8592 moderately complex makefile.
8594 Because it is the first target, the default goal is @samp{all}.  An
8595 interesting feature of this makefile is that @file{testpad.h} is a
8596 source file automatically created by the @code{testpad} program,
8597 itself compiled from @file{testpad.c}.
8599 If you type @samp{make} or @samp{make all}, then @code{make} creates
8600 the @file{tar} executable, the @file{rmt} daemon that provides
8601 remote tape access, and the @file{tar.info} Info file.
8603 If you type @samp{make install}, then @code{make} not only creates
8604 @file{tar}, @file{rmt}, and @file{tar.info}, but also installs
8605 them.
8607 If you type @samp{make clean}, then @code{make} removes the @samp{.o}
8608 files, and the @file{tar}, @file{rmt}, @file{testpad},
8609 @file{testpad.h}, and @file{core} files.
8611 If you type @samp{make distclean}, then @code{make} not only removes
8612 the same files as does @samp{make clean} but also the
8613 @file{TAGS}, @file{Makefile}, and @file{config.status} files.
8614 (Although it is not evident, this makefile (and
8615 @file{config.status}) is generated by the user with the
8616 @code{configure} program, which is provided in the @code{tar}
8617 distribution, but is not shown here.)
8619 If you type @samp{make realclean}, then @code{make} removes the same
8620 files as does @samp{make distclean} and also removes the Info files
8621 generated from @file{tar.texinfo}.
8623 In addition, there are targets @code{shar} and @code{dist} that create
8624 distribution kits.
8626 @example
8627 @group
8628 # Generated automatically from Makefile.in by configure.
8629 # Un*x Makefile for GNU tar program.
8630 # Copyright (C) 1991 Free Software Foundation, Inc.
8631 @end group
8633 @group
8634 # This program is free software; you can redistribute
8635 # it and/or modify it under the terms of the GNU
8636 # General Public License @dots{}
8637 @dots{}
8638 @dots{}
8639 @end group
8641 SHELL = /bin/sh
8643 #### Start of system configuration section. ####
8645 srcdir = .
8647 @group
8648 # If you use gcc, you should either run the
8649 # fixincludes script that comes with it or else use
8650 # gcc with the -traditional option.  Otherwise ioctl
8651 # calls will be compiled incorrectly on some systems.
8652 CC = gcc -O
8653 YACC = bison -y
8654 INSTALL = /usr/local/bin/install -c
8655 INSTALLDATA = /usr/local/bin/install -c -m 644
8656 @end group
8658 # Things you might add to DEFS:
8659 # -DSTDC_HEADERS        If you have ANSI C headers and
8660 #                       libraries.
8661 # -DPOSIX               If you have POSIX.1 headers and
8662 #                       libraries.
8663 # -DBSD42               If you have sys/dir.h (unless
8664 #                       you use -DPOSIX), sys/file.h,
8665 #                       and st_blocks in `struct stat'.
8666 # -DUSG                 If you have System V/ANSI C
8667 #                       string and memory functions
8668 #                       and headers, sys/sysmacros.h,
8669 #                       fcntl.h, getcwd, no valloc,
8670 #                       and ndir.h (unless
8671 #                       you use -DDIRENT).
8672 # -DNO_MEMORY_H         If USG or STDC_HEADERS but do not
8673 #                       include memory.h.
8674 # -DDIRENT              If USG and you have dirent.h
8675 #                       instead of ndir.h.
8676 # -DSIGTYPE=int         If your signal handlers
8677 #                       return int, not void.
8678 # -DNO_MTIO             If you lack sys/mtio.h
8679 #                       (magtape ioctls).
8680 # -DNO_REMOTE           If you do not have a remote shell
8681 #                       or rexec.
8682 # -DUSE_REXEC           To use rexec for remote tape
8683 #                       operations instead of
8684 #                       forking rsh or remsh.
8685 # -DVPRINTF_MISSING     If you lack vprintf function
8686 #                       (but have _doprnt).
8687 # -DDOPRNT_MISSING      If you lack _doprnt function.
8688 #                       Also need to define
8689 #                       -DVPRINTF_MISSING.
8690 # -DFTIME_MISSING       If you lack ftime system call.
8691 # -DSTRSTR_MISSING      If you lack strstr function.
8692 # -DVALLOC_MISSING      If you lack valloc function.
8693 # -DMKDIR_MISSING       If you lack mkdir and
8694 #                       rmdir system calls.
8695 # -DRENAME_MISSING      If you lack rename system call.
8696 # -DFTRUNCATE_MISSING   If you lack ftruncate
8697 #                       system call.
8698 # -DV7                  On Version 7 Unix (not
8699 #                       tested in a long time).
8700 # -DEMUL_OPEN3          If you lack a 3-argument version
8701 #                       of open, and want to emulate it
8702 #                       with system calls you do have.
8703 # -DNO_OPEN3            If you lack the 3-argument open
8704 #                       and want to disable the tar -k
8705 #                       option instead of emulating open.
8706 # -DXENIX               If you have sys/inode.h
8707 #                       and need it 94 to be included.
8709 DEFS =  -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
8710         -DVPRINTF_MISSING -DBSD42
8711 # Set this to rtapelib.o unless you defined NO_REMOTE,
8712 # in which case make it empty.
8713 RTAPELIB = rtapelib.o
8714 LIBS =
8715 DEF_AR_FILE = /dev/rmt8
8716 DEFBLOCKING = 20
8718 @group
8719 CDEBUG = -g
8720 CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
8721         -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
8722         -DDEFBLOCKING=$(DEFBLOCKING)
8723 LDFLAGS = -g
8724 @end group
8726 @group
8727 prefix = /usr/local
8728 # Prefix for each installed program,
8729 # normally empty or `g'.
8730 binprefix =
8732 # The directory to install tar in.
8733 bindir = $(prefix)/bin
8735 # The directory to install the info files in.
8736 infodir = $(prefix)/info
8737 @end group
8739 #### End of system configuration section. ####
8741 SRC1 =  tar.c create.c extract.c buffer.c \
8742         getoldopt.c update.c gnu.c mangle.c
8743 SRC2 =  version.c list.c names.c diffarch.c \
8744         port.c wildmat.c getopt.c
8745 SRC3 =  getopt1.c regex.c getdate.y
8746 SRCS =  $(SRC1) $(SRC2) $(SRC3)
8747 OBJ1 =  tar.o create.o extract.o buffer.o \
8748         getoldopt.o update.o gnu.o mangle.o
8749 OBJ2 =  version.o list.o names.o diffarch.o \
8750         port.o wildmat.o getopt.o
8751 OBJ3 =  getopt1.o regex.o getdate.o $(RTAPELIB)
8752 OBJS =  $(OBJ1) $(OBJ2) $(OBJ3)
8753 @group
8754 AUX =   README COPYING ChangeLog Makefile.in  \
8755         makefile.pc configure configure.in \
8756         tar.texinfo tar.info* texinfo.tex \
8757         tar.h port.h open3.h getopt.h regex.h \
8758         rmt.h rmt.c rtapelib.c alloca.c \
8759         msd_dir.h msd_dir.c tcexparg.c \
8760         level-0 level-1 backup-specs testpad.c
8761 @end group
8763 all:    tar rmt tar.info
8765 @group
8766 tar:    $(OBJS)
8767         $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
8768 @end group
8770 @group
8771 rmt:    rmt.c
8772         $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
8773 @end group
8775 @group
8776 tar.info: tar.texinfo
8777         makeinfo tar.texinfo
8778 @end group
8780 @group
8781 install: all
8782         $(INSTALL) tar $(bindir)/$(binprefix)tar
8783         -test ! -f rmt || $(INSTALL) rmt /etc/rmt
8784         $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
8785 @end group
8787 @group
8788 $(OBJS): tar.h port.h testpad.h
8789 regex.o buffer.o tar.o: regex.h
8790 # getdate.y has 8 shift/reduce conflicts.
8791 @end group
8793 @group
8794 testpad.h: testpad
8795         ./testpad
8796 @end group
8798 @group
8799 testpad: testpad.o
8800         $(CC) -o $@@ testpad.o
8801 @end group
8803 @group
8804 TAGS:   $(SRCS)
8805         etags $(SRCS)
8806 @end group
8808 @group
8809 clean:
8810         rm -f *.o tar rmt testpad testpad.h core
8811 @end group
8813 @group
8814 distclean: clean
8815         rm -f TAGS Makefile config.status
8816 @end group
8818 @group
8819 realclean: distclean
8820         rm -f tar.info*
8821 @end group
8823 @group
8824 shar: $(SRCS) $(AUX)
8825         shar $(SRCS) $(AUX) | compress \
8826           > tar-`sed -e '/version_string/!d' \
8827                      -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8828                      -e q
8829                      version.c`.shar.Z
8830 @end group
8832 @group
8833 dist: $(SRCS) $(AUX)
8834         echo tar-`sed \
8835              -e '/version_string/!d' \
8836              -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8837              -e q
8838              version.c` > .fname
8839         -rm -rf `cat .fname`
8840         mkdir `cat .fname`
8841         ln $(SRCS) $(AUX) `cat .fname`
8842         -rm -rf `cat .fname` .fname
8843         tar chZf `cat .fname`.tar.Z `cat .fname`
8844 @end group
8846 @group
8847 tar.zoo: $(SRCS) $(AUX)
8848         -rm -rf tmp.dir
8849         -mkdir tmp.dir
8850         -rm tar.zoo
8851         for X in $(SRCS) $(AUX) ; do \
8852             echo $$X ; \
8853             sed 's/$$/^M/' $$X \
8854             > tmp.dir/$$X ; done
8855         cd tmp.dir ; zoo aM ../tar.zoo *
8856         -rm -rf tmp.dir
8857 @end group
8858 @end example
8860 @node Concept Index, Name Index, Complex Makefile, Top
8861 @unnumbered Index of Concepts
8863 @printindex cp
8865 @node Name Index,  , Concept Index, Top
8866 @unnumbered Index of Functions, Variables, & Directives
8868 @printindex fn
8870 @summarycontents
8871 @contents
8872 @bye