1 \input texinfo @c -*- Texinfo -*-
4 @settitle GNU @code{make}
8 @c FSF publishers: format makebook.texi instead of using this file directly.
12 @set VERSION 3.71 Beta
13 @set UPDATED 20 April 1994
14 @set UPDATE-MONTH April 1994
18 @c ISPELL CHECK: done, 10 June 1993 --roland
20 @c Combine the variable and function indices:
22 @c Combine the program and concept indices:
26 This file documents the GNU Make utility, which determines
27 automatically which pieces of a large program need to be recompiled,
28 and issues the commands to recompile them.
30 This is Edition @value{EDITION}, last updated @value{UPDATED},
31 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
33 Copyright (C) 1988, '89, '90, '91, '92, '93, '94 Free Software Foundation, Inc.
35 Permission is granted to make and distribute verbatim copies of
36 this manual provided the copyright notice and this permission notice
37 are preserved on all copies.
40 Permission is granted to process this file through TeX and print the
41 results, provided the printed document carries copying permission
42 notice identical to this one except for the removal of this paragraph
43 (this paragraph not being relevant to the printed manual).
46 Permission is granted to copy and distribute modified versions of this
47 manual under the conditions for verbatim copying, provided that the entire
48 resulting derived work is distributed under the terms of a permission
49 notice identical to this one.
51 Permission is granted to copy and distribute translations of this manual
52 into another language, under the above conditions for modified versions,
53 except that this permission notice may be stated in a translation approved
54 by the Free Software Foundation.
58 @shorttitlepage GNU Make
62 @subtitle A Program for Directing Recompilation
63 @subtitle Edition @value{EDITION}, for @code{make} Version @value{VERSION}.
64 @subtitle @value{UPDATE-MONTH}
65 @author Richard M. Stallman and Roland McGrath
67 @vskip 0pt plus 1filll
68 Copyright @copyright{} 1988, '89, '90, '91, '92, '93, '94 Free Software Foundation, Inc.
70 Published by the Free Software Foundation @*
71 675 Massachusetts Avenue, @*
72 Cambridge, MA 02139 USA @*
73 Printed copies are available for $20 each. @*
76 Permission is granted to make and distribute verbatim copies of
77 this manual provided the copyright notice and this permission notice
78 are preserved on all copies.
80 Permission is granted to copy and distribute modified versions of this
81 manual under the conditions for verbatim copying, provided that the entire
82 resulting derived work is distributed under the terms of a permission
83 notice identical to this one.
85 Permission is granted to copy and distribute translations of this manual
86 into another language, under the above conditions for modified versions,
87 except that this permission notice may be stated in a translation approved
88 by the Free Software Foundation.
90 Cover art by Etienne Suvasa.
95 @node Top, Overview, (dir), (dir)
98 The GNU @code{make} utility automatically determines which pieces of a
99 large program need to be recompiled, and issues the commands to
100 recompile them.@refill
102 This is Edition @value{EDITION} of the @cite{GNU Make Manual},
103 last updated @value{UPDATED}
104 for @code{make} Version @value{VERSION}.@refill
106 This manual describes @code{make} and contains the following chapters:@refill
110 * Overview:: Overview of @code{make}.
111 * Introduction:: An introduction to @code{make}.
112 * Makefiles:: Makefiles tell @code{make} what to do.
113 * Rules:: Rules describe when a file must be remade.
114 * Commands:: Commands say how to remake a file.
115 * Using Variables:: You can use variables to avoid repetition.
116 * Conditionals:: Use or ignore parts of the makefile based
117 on the values of variables.
118 * Functions:: Many powerful ways to manipulate text.
119 * make Invocation: Running. How to invoke @code{make} on the command line.
120 * Implicit Rules:: Use implicit rules to treat many files alike,
121 based on their file names.
122 * Archives:: How @code{make} can update library archives.
123 * Features:: Features GNU @code{make} has over other @code{make}s.
124 * Missing:: What GNU @code{make} lacks from other @code{make}s.
125 * Makefile Conventions:: Conventions for makefiles in GNU programs.
126 * Quick Reference:: A quick reference for experienced users.
127 * Complex Makefile:: A real example of a straightforward,
128 but nontrivial, makefile.
129 * Concept Index:: Index of Concepts
130 * Name Index:: Index of Functions, Variables, & Directives
132 --- The Detailed Node Listing ---
134 Overview of @code{make}
136 * Preparing:: Preparing and Running Make
137 * Reading:: On Reading this Text
138 * Bugs:: Problems and Bugs
140 An Introduction to Makefiles
142 * Rule Introduction:: What a rule looks like.
143 * Simple Makefile:: A Simple Makefile
144 * How Make Works:: How @code{make} Processes This Makefile
145 * Variables Simplify:: Variables Make Makefiles Simpler
146 * make Deduces:: Letting @code{make} Deduce the Commands
147 * Combine By Dependency:: Another Style of Makefile
148 * Cleanup:: Rules for Cleaning the Directory
152 * Makefile Contents:: What makefiles contain.
153 * Makefile Names:: How to name your makefile.
154 * Include:: How one makefile can use another makefile.
155 * MAKEFILES Variable:: The environment can specify extra makefiles.
156 * Remaking Makefiles:: How makefiles get remade.
157 * Overriding Makefiles:: How to override part of one makefile
158 with another makefile.
162 * Rule Example:: An example explained.
163 * Rule Syntax:: General syntax explained.
164 * Wildcards:: Using wildcard characters such as `*'.
165 * Directory Search:: Searching other directories for source files.
166 * Phony Targets:: Using a target that is not a real file's name.
167 * Force Targets:: You can use a target without commands
168 or dependencies to mark other
170 * Empty Targets:: When only the date matters and the
172 * Special Targets:: Targets with special built-in meanings.
173 * Multiple Targets:: When to make use of several targets in a rule.
174 * Multiple Rules:: How to use several rules with the same target.
175 * Static Pattern:: Static pattern rules apply to multiple targets
176 and can vary the dependencies according to
178 * Double-Colon:: How to use a special kind of rule to allow
179 several independent rules for one target.
180 * Automatic Dependencies:: How to automatically generate rules giving
181 dependencies from the source files themselves.
183 Using Wildcard Characters in File Names
185 * Wildcard Examples:: Several examples
186 * Wildcard Pitfall:: Problems to avoid.
187 * Wildcard Function:: How to cause wildcard expansion where
188 it does not normally take place.
190 Searching Directories for Dependencies
192 * General Search:: Specifying a search path that applies
194 * Selective Search:: Specifying a search path
195 for a specified class of names.
196 * Commands/Search:: How to write shell commands that work together
198 * Implicit/Search:: How search paths affect implicit rules.
199 * Libraries/Search:: Directory search for link libraries.
203 * Static Usage:: The syntax of static pattern rules.
204 * Static versus Implicit:: When are they better than implicit rules?
206 Writing the Commands in Rules
208 * Echoing:: How to control when commands are echoed.
209 * Execution:: How commands are executed.
210 * Parallel:: How commands can be executed in parallel.
211 * Errors:: What happens after a command execution error.
212 * Interrupts:: What happens when a command is interrupted.
213 * Recursion:: Invoking @code{make} from makefiles.
214 * Sequences:: Defining canned sequences of commands.
215 * Empty Commands:: Defining useful, do-nothing commands.
217 Recursive Use of @code{make}
219 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
220 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
221 * Options/Recursion:: How to communicate options to a sub-@code{make}.
222 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
223 helps debug use of recursive @code{make} commands.
227 * Reference:: How to use the value of a variable.
228 * Flavors:: Variables come in two flavors.
229 * Advanced:: Advanced features for referencing a variable.
230 * Values:: All the ways variables get their values.
231 * Setting:: How to set a variable in the makefile.
232 * Appending:: How to append more text to the old value
234 * Override Directive:: How to set a variable in the makefile even if
235 the user has set it with a command argument.
236 * Defining:: An alternate way to set a variable
237 to a verbatim string.
238 * Environment:: Variable values can come from the environment.
240 Advanced Features for Reference to Variables
242 * Substitution Refs:: Referencing a variable with
243 substitutions on the value.
244 * Computed Names:: Computing the name of the variable to refer to.
246 Conditional Parts of Makefiles
248 * Conditional Example:: Example of a conditional
249 * Conditional Syntax:: The syntax of conditionals.
250 * Testing Flags:: Conditionals that test flags.
252 Functions for Transforming Text
254 * Syntax of Functions:: How to write a function call.
255 * Text Functions:: General-purpose text manipulation functions.
256 * Filename Functions:: Functions for manipulating file names.
257 * Foreach Function:: Repeat some text with controlled variation.
258 * Origin Function:: Find where a variable got its value.
259 * Shell Function:: Substitute the output of a shell command.
261 How to Run @code{make}
263 * Makefile Arguments:: How to specify which makefile to use.
264 * Goals:: How to use goal arguments to specify which
265 parts of the makefile to use.
266 * Instead of Execution:: How to use mode flags to specify what
267 kind of thing to do with the commands
268 in the makefile other than simply
270 * Avoiding Compilation:: How to avoid recompiling certain files.
271 * Overriding:: How to override a variable to specify
272 an alternate compiler and other things.
273 * Testing:: How to proceed past some errors, to
275 * Options Summary:: Summary of Options
279 * Using Implicit:: How to use an existing implicit rule
280 to get the commands for updating a file.
281 * Catalogue of Rules:: A list of built-in implicit rules.
282 * Implicit Variables:: How to change what predefined rules do.
283 * Chained Rules:: How to use a chain of implicit rules.
284 * Pattern Rules:: How to define new implicit rules.
285 * Last Resort:: How to defining commands for rules
286 which cannot find any.
287 * Suffix Rules:: The old-fashioned style of implicit rule.
288 * Search Algorithm:: The precise algorithm for applying
291 Defining and Redefining Pattern Rules
293 * Pattern Intro:: An introduction to pattern rules.
294 * Pattern Examples:: Examples of pattern rules.
295 * Automatic:: How to use automatic variables in the
296 commands of implicit rules.
297 * Pattern Match:: How patterns match.
298 * Match-Anything Rules:: Precautions you should take prior to
299 defining rules that can match any
300 target file whatever.
301 * Canceling Rules:: How to override or cancel built-in rules.
303 Using @code{make} to Update Archive Files
305 * Archive Members:: Archive members as targets.
306 * Archive Update:: The implicit rule for archive member targets.
307 * Archive Suffix Rules:: You can write a special kind of suffix rule
308 for updating archives.
310 Implicit Rule for Archive Member Targets
312 * Archive Symbols:: How to update archive symbol directories.
315 @node Overview, Introduction, Top, Top
316 @comment node-name, next, previous, up
317 @chapter Overview of @code{make}
319 The @code{make} utility automatically determines which pieces of a large
320 program need to be recompiled, and issues commands to recompile them.
321 This manual describes GNU @code{make}, which was implemented by Richard
322 Stallman and Roland McGrath. GNU @code{make} conforms to section 6.2 of
323 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
325 @cindex IEEE Standard 1003.2
326 @cindex standards conformance
328 Our examples show C programs, since they are most common, but you can use
329 @code{make} with any programming language whose compiler can be run with a
330 shell command. Indeed, @code{make} is not limited to programs. You can
331 use it to describe any task where some files must be updated automatically
332 from others whenever the others change.
335 * Preparing:: Preparing and Running Make
336 * Reading:: On Reading this Text
337 * Bugs:: Problems and Bugs
340 @node Preparing, Reading, , Overview
342 @heading Preparing and Running Make
345 To prepare to use @code{make}, you must write a file called
346 the @dfn{makefile} that describes the relationships among files
347 in your program and provides commands for updating each file.
348 In a program, typically, the executable file is updated from object
349 files, which are in turn made by compiling source files.@refill
351 Once a suitable makefile exists, each time you change some source files,
352 this simple shell command:
359 suffices to perform all necessary recompilations. The @code{make} program
360 uses the makefile data base and the last-modification times of the files to
361 decide which of the files need to be updated. For each of those files, it
362 issues the commands recorded in the data base.
364 You can provide command line arguments to @code{make} to control which
365 files should be recompiled, or how. @xref{Running, ,How to Run
368 @node Reading, Bugs, Preparing, Overview
369 @section How to Read This Manual
371 If you are new to @code{make}, or are looking for a general
372 introduction, read the first few sections of each chapter, skipping the
373 later sections. In each chapter, the first few sections contain
374 introductory or general information and the later sections contain
375 specialized or technical information.
377 The exception is the second chapter, @ref{Introduction, ,An
378 Introduction to Makefiles}, all of which is introductory.
381 The exception is @ref{Introduction, ,An Introduction to Makefiles},
382 all of which is introductory.
385 If you are familiar with other @code{make} programs, see @ref{Features,
386 ,Features of GNU @code{make}}, which lists the enhancements GNU
387 @code{make} has, and @ref{Missing, ,Incompatibilities and Missing
388 Features}, which explains the few things GNU @code{make} lacks that
391 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
392 and @ref{Special Targets}.
394 @node Bugs, , Reading, Overview
395 @section Problems and Bugs
396 @cindex reporting bugs
397 @cindex bugs, reporting
398 @cindex problems and bugs, reporting
400 If you have problems with GNU @code{make} or think you've found a bug,
401 please report it to the developers; we cannot promise to do anything but
402 we might well want to fix it.
404 Before reporting a bug, make sure you've actually found a real bug.
405 Carefully reread the documentation and see if it really says you can do
406 what you're trying to do. If it's not clear whether you should be able
407 to do something or not, report that too; it's a bug in the
410 Before reporting a bug or trying to fix it yourself, try to isolate it
411 to the smallest possible makefile that reproduces the problem. Then
412 send us the makefile and the exact results @code{make} gave you. Also
413 say what you expected to occur; this will help us decide whether the
414 problem was really in the documentation.
416 Once you've got a precise problem, please send electronic mail either
417 through the Internet or via UUCP:
421 @r{Internet address:}
422 bug-gnu-utils@@prep.ai.mit.edu
425 mit-eddie!prep.ai.mit.edu!bug-gnu-utils
430 Please include the version number of @code{make} you are using. You can
431 get this information with the command @samp{make --version}.
432 Be sure also to include the type of machine and operating system you are
433 using. If possible, include the contents of the file @file{config.h}
434 that is generated by the configuration process.
436 Non-bug suggestions are always welcome as well. If you have questions
437 about things that are unclear in the documentation or are just obscure
438 features, send a message to the bug reporting address. We cannot
439 guarantee you'll get help with your problem, but many seasoned
440 @code{make} users read the mailing list and they will probably try to
441 help you out. The maintainers sometimes answer such questions as well,
444 @node Introduction, Makefiles, Overview, Top
445 @comment node-name, next, previous, up
446 @chapter An Introduction to Makefiles
448 You need a file called a @dfn{makefile} to tell @code{make} what to do.
449 Most often, the makefile tells @code{make} how to compile and link a
453 In this chapter, we will discuss a simple makefile that describes how to
454 compile and link a text editor which consists of eight C source files
455 and three header files. The makefile can also tell @code{make} how to
456 run miscellaneous commands when explicitly asked (for example, to remove
457 certain files as a clean-up operation). To see a more complex example
458 of a makefile, see @ref{Complex Makefile}.
460 When @code{make} recompiles the editor, each changed C source file
461 must be recompiled. If a header file has changed, each C source file
462 that includes the header file must be recompiled to be safe. Each
463 compilation produces an object file corresponding to the source file.
464 Finally, if any source file has been recompiled, all the object files,
465 whether newly made or saved from previous compilations, must be linked
466 together to produce the new executable editor.
467 @cindex recompilation
471 * Rule Introduction:: What a rule looks like.
472 * Simple Makefile:: A Simple Makefile
473 * How Make Works:: How @code{make} Processes This Makefile
474 * Variables Simplify:: Variables Make Makefiles Simpler
475 * make Deduces:: Letting @code{make} Deduce the Commands
476 * Combine By Dependency:: Another Style of Makefile
477 * Cleanup:: Rules for Cleaning the Directory
480 @node Rule Introduction, Simple Makefile, , Introduction
481 @comment node-name, next, previous, up
482 @section What a Rule Looks Like
483 @cindex rule, introduction to
484 @cindex makefile rule parts
485 @cindex parts of makefile rule
487 A simple makefile consists of ``rules'' with the following shape:
489 @cindex targets, introduction to
490 @cindex dependencies, introduction to
491 @cindex commands, introduction to
494 @var{target} @dots{} : @var{dependencies} @dots{}
501 A @dfn{target} is usually the name of a file that is generated by a
502 program; examples of targets are executable or object files. A target
503 can also be the name of an action to carry out, such as @samp{clean}
504 (@pxref{Phony Targets}).
506 A @dfn{dependency} is a file that is used as input to create the
507 target. A target often depends on several files.
509 @cindex tabs in rules
510 A @dfn{command} is an action that @code{make} carries out.
511 A rule may have more than one command, each on its own line.
512 @strong{Please note:} you need to put a tab character at the beginning of
513 every command line! This is an obscurity that catches the unwary.
515 Usually a command is in a rule with dependencies and serves to create a
516 target file if any of the dependencies change. However, the rule that
517 specifies commands for the target need not have dependencies. For
518 example, the rule containing the delete command associated with the
519 target @samp{clean} does not have dependencies.
521 A @dfn{rule}, then, explains how and when to remake certain files
522 which are the targets of the particular rule. @code{make} carries out
523 the commands on the dependencies to create or update the target. A
524 rule can also explain how and when to carry out an action.
525 @xref{Rules, , Writing Rules}.
527 A makefile may contain other text besides rules, but a simple makefile
528 need only contain rules. Rules may look somewhat more complicated
529 than shown in this template, but all fit the pattern more or less.
531 @node Simple Makefile, How Make Works, Rule Introduction, Introduction
532 @section A Simple Makefile
533 @cindex simple makefile
534 @cindex makefile, simple
536 Here is a straightforward makefile that describes the way an
537 executable file called @code{edit} depends on eight object files
538 which, in turn, depend on eight C source and three header files.
540 In this example, all the C files include @file{defs.h}, but only those
541 defining editing commands include @file{command.h}, and only low
542 level files that change the editor buffer include @file{buffer.h}.
546 edit : main.o kbd.o command.o display.o \
547 insert.o search.o files.o utils.o
548 cc -o edit main.o kbd.o command.o display.o \
549 insert.o search.o files.o utils.o
551 main.o : main.c defs.h
553 kbd.o : kbd.c defs.h command.h
555 command.o : command.c defs.h command.h
557 display.o : display.c defs.h buffer.h
559 insert.o : insert.c defs.h buffer.h
561 search.o : search.c defs.h buffer.h
563 files.o : files.c defs.h buffer.h command.h
565 utils.o : utils.c defs.h
568 rm edit main.o kbd.o command.o display.o \
569 insert.o search.o files.o utils.o
574 We split each long line into two lines using backslash-newline; this is
575 like using one long line, but is easier to read.
576 @cindex continuation lines
577 @cindex @code{\} (backslash), for continuation lines
578 @cindex backslash (@code{\}), for continuation lines
579 @cindex quoting newline, in makefile
580 @cindex newline, quoting, in makefile
582 To use this makefile to create the executable file called @file{edit},
589 To use this makefile to delete the executable file and all the object
590 files from the directory, type:
596 In the example makefile, the targets include the executable file
597 @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
598 dependencies are files such as @samp{main.c} and @samp{defs.h}.
599 In fact, each @samp{.o} file is both a target and a dependency.
600 Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
602 When a target is a file, it needs to be recompiled or relinked if any
603 of its dependencies change. In addition, any dependencies that are
604 themselves automatically generated should be updated first. In this
605 example, @file{edit} depends on each of the eight object files; the
606 object file @file{main.o} depends on the source file @file{main.c} and
607 on the header file @file{defs.h}.
609 A shell command follows each line that contains a target and
610 dependencies. These shell commands say how to update the target file.
611 A tab character must come at the beginning of every command line to
612 distinguish commands lines from other lines in the makefile. (Bear in
613 mind that @code{make} does not know anything about how the commands
614 work. It is up to you to supply commands that will update the target
615 file properly. All @code{make} does is execute the commands in the rule
616 you have specified when the target file needs to be updated.)
617 @cindex shell command
619 The target @samp{clean} is not a file, but merely the name of an
622 do not want to carry out the actions in this rule, @samp{clean} is not a dependency of any other rule.
623 Consequently, @code{make} never does anything with it unless you tell
624 it specifically. Note that this rule not only is not a dependency, it
625 also does not have any dependencies, so the only purpose of the rule
626 is to run the specified commands. Targets that do not refer to files
627 but are just actions are called @dfn{phony targets}. @xref{Phony
628 Targets}, for information about this kind of target. @xref{Errors, ,
629 Errors in Commands}, to see how to cause @code{make} to ignore errors
630 from @code{rm} or any other command.
631 @cindex @code{clean} target
632 @cindex @code{rm} (shell command)
634 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
635 @comment node-name, next, previous, up
636 @section How @code{make} Processes a Makefile
637 @cindex processing a makefile
638 @cindex makefile, how @code{make} processes
640 By default, @code{make} starts with the first rule (not counting rules
641 whose target names start with @samp{.}). This is called the
642 @dfn{default goal}. (@dfn{Goals} are the targets that @code{make}
643 strives ultimately to update. @xref{Goals, , Arguments to Specify the
646 @cindex goal, default
649 In the simple example of the previous section, the default goal is to
650 update the executable program @file{edit}; therefore, we put that rule
653 Thus, when you give the command:
660 @code{make} reads the makefile in the current directory and begins by
661 processing the first rule. In the example, this rule is for relinking
662 @file{edit}; but before @code{make} can fully process this rule, it
663 must process the rules for the files that @file{edit} depends on,
664 which in this case are the object files. Each of these files is
665 processed according to its own rule. These rules say to update each
666 @samp{.o} file by compiling its source file. The recompilation must
667 be done if the source file, or any of the header files named as
668 dependencies, is more recent than the object file, or if the object
671 The other rules are processed because their targets appear as
672 dependencies of the goal. If some other rule is not depended on by the
673 goal (or anything it depends on, etc.), that rule is not processed,
674 unless you tell @code{make} to do so (with a command such as
675 @w{@code{make clean}}).
677 Before recompiling an object file, @code{make} considers updating its
678 dependencies, the source file and header files. This makefile does not
679 specify anything to be done for them---the @samp{.c} and @samp{.h} files
680 are not the targets of any rules---so @code{make} does nothing for these
681 files. But @code{make} would update automatically generated C programs,
682 such as those made by Bison or Yacc, by their own rules at this time.
684 After recompiling whichever object files need it, @code{make} decides
685 whether to relink @file{edit}. This must be done if the file
686 @file{edit} does not exist, or if any of the object files are newer than
687 it. If an object file was just recompiled, it is now newer than
688 @file{edit}, so @file{edit} is relinked.
691 Thus, if we change the file @file{insert.c} and run @code{make},
692 @code{make} will compile that file to update @file{insert.o}, and then
693 link @file{edit}. If we change the file @file{command.h} and run
694 @code{make}, @code{make} will recompile the object files @file{kbd.o},
695 @file{command.o} and @file{files.o} and then link the file @file{edit}.
697 @node Variables Simplify, make Deduces, How Make Works, Introduction
698 @section Variables Make Makefiles Simpler
700 @cindex simplifying with variables
702 In our example, we had to list all the object files twice in the rule for
703 @file{edit} (repeated here):
707 edit : main.o kbd.o command.o display.o \
708 insert.o search.o files.o utils.o
709 cc -o edit main.o kbd.o command.o display.o \
710 insert.o search.o files.o utils.o
714 @cindex @code{objects}
715 Such duplication is error-prone; if a new object file is added to the
716 system, we might add it to one list and forget the other. We can eliminate
717 the risk and simplify the makefile by using a variable. @dfn{Variables}
718 allow a text string to be defined once and substituted in multiple places
719 later (@pxref{Using Variables, ,How to Use Variables}).
721 @cindex @code{OBJECTS}
726 It is standard practice for every makefile to have a variable named
727 @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
728 or @code{OBJ} which is a list of all object file names. We would
729 define such a variable @code{objects} with a line like this in the
734 objects = main.o kbd.o command.o display.o \
735 insert.o search.o files.o utils.o
740 Then, each place we want to put a list of the object file names, we can
741 substitute the variable's value by writing @samp{$(objects)}
742 (@pxref{Using Variables, ,How to Use Variables}).
744 Here is how the complete simple makefile looks when you use a variable
745 for the object files:
749 objects = main.o kbd.o command.o display.o \
750 insert.o search.o files.o utils.o
753 cc -o edit $(objects)
754 main.o : main.c defs.h
756 kbd.o : kbd.c defs.h command.h
758 command.o : command.c defs.h command.h
760 display.o : display.c defs.h buffer.h
762 insert.o : insert.c defs.h buffer.h
764 search.o : search.c defs.h buffer.h
766 files.o : files.c defs.h buffer.h command.h
768 utils.o : utils.c defs.h
775 @node make Deduces, Combine By Dependency, Variables Simplify, Introduction
776 @section Letting @code{make} Deduce the Commands
777 @cindex deducing commands (implicit rules)
778 @cindex implicit rule, introduction to
779 @cindex rule, implicit, introduction to
781 It is not necessary to spell out the commands for compiling the individual
782 C source files, because @code{make} can figure them out: it has an
783 @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
784 named @samp{.c} file using a @samp{cc -c} command. For example, it will
785 use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
786 @file{main.o}. We can therefore omit the commands from the rules for the
787 object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill
789 When a @samp{.c} file is used automatically in this way, it is also
790 automatically added to the list of dependencies. We can therefore omit
791 the @samp{.c} files from the dependencies, provided we omit the commands.
793 Here is the entire example, with both of these changes, and a variable
794 @code{objects} as suggested above:
798 objects = main.o kbd.o command.o display.o \
799 insert.o search.o files.o utils.o
802 cc -o edit $(objects)
805 kbd.o : defs.h command.h
806 command.o : defs.h command.h
807 display.o : defs.h buffer.h
808 insert.o : defs.h buffer.h
809 search.o : defs.h buffer.h
810 files.o : defs.h buffer.h command.h
820 This is how we would write the makefile in actual practice. (The
821 complications associated with @samp{clean} are described elsewhere.
822 See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
824 Because implicit rules are so convenient, they are important. You
825 will see them used frequently.@refill
827 @node Combine By Dependency, Cleanup, make Deduces, Introduction
828 @section Another Style of Makefile
829 @cindex combining rules by dependency
831 When the objects of a makefile are created only by implicit rules, an
832 alternative style of makefile is possible. In this style of makefile,
833 you group entries by their dependencies instead of by their targets.
834 Here is what one looks like:
838 objects = main.o kbd.o command.o display.o \
839 insert.o search.o files.o utils.o
842 cc -o edit $(objects)
845 kbd.o command.o files.o : command.h
846 display.o insert.o search.o files.o : buffer.h
851 Here @file{defs.h} is given as a dependency of all the object files;
852 @file{command.h} and @file{buffer.h} are dependencies of the specific
853 object files listed for them.
855 Whether this is better is a matter of taste: it is more compact, but some
856 people dislike it because they find it clearer to put all the information
857 about each target in one place.
859 @node Cleanup, , Combine By Dependency, Introduction
860 @section Rules for Cleaning the Directory
862 @cindex removing, to clean up
864 Compiling a program is not the only thing you might want to write rules
865 for. Makefiles commonly tell how to do a few other things besides
866 compiling a program: for example, how to delete all the object files
867 and executables so that the directory is @samp{clean}.
869 @cindex @code{clean} target
871 could write a @code{make} rule for cleaning our example editor:
880 In practice, we might want to write the rule in a somewhat more
881 complicated manner to handle unanticipated situations. We would do this:
892 This prevents @code{make} from getting confused by an actual file
893 called @file{clean} and causes it to continue in spite of errors from
894 @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
898 A rule such as this should not be placed at the beginning of the
899 makefile, because we do not want it to run by default! Thus, in the
900 example makefile, we want the rule for @code{edit}, which recompiles
901 the editor, to remain the default goal.
903 Since @code{clean} is not a dependency of @code{edit}, this rule will not
904 run at all if we give the command @samp{make} with no arguments. In
905 order to make the rule run, we have to type @samp{make clean}.
906 @xref{Running, ,How to Run @code{make}}.
908 @node Makefiles, Rules, Introduction, Top
909 @chapter Writing Makefiles
911 @cindex makefile, how to write
912 The information that tells @code{make} how to recompile a system comes from
913 reading a data base called the @dfn{makefile}.
916 * Makefile Contents:: What makefiles contain.
917 * Makefile Names:: How to name your makefile.
918 * Include:: How one makefile can use another makefile.
919 * MAKEFILES Variable:: The environment can specify extra makefiles.
920 * Remaking Makefiles:: How makefiles get remade.
921 * Overriding Makefiles:: How to override part of one makefile
922 with another makefile.
925 @node Makefile Contents, Makefile Names, , Makefiles
926 @section What Makefiles Contain
928 Makefiles contain five kinds of things: @dfn{explicit rules},
929 @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
930 and @dfn{comments}. Rules, variables, and directives are described at
931 length in later chapters.@refill
934 @cindex rule, explicit, definition of
935 @cindex explicit rule, definition of
937 An @dfn{explicit rule} says when and how to remake one or more files,
938 called the rule's targets. It lists the other files that the targets
939 @dfn{depend on}, and may also give commands to use to create or update
940 the targets. @xref{Rules, ,Writing Rules}.
942 @cindex rule, implicit, definition of
943 @cindex implicit rule, definition of
945 An @dfn{implicit rule} says when and how to remake a class of files
946 based on their names. It describes how a target may depend on a file
947 with a name similar to the target and gives commands to create or
948 update such a target. @xref{Implicit Rules, ,Using Implicit Rules}.
950 @cindex variable definition
952 A @dfn{variable definition} is a line that specifies a text string
953 value for a variable that can be substituted into the text later. The
954 simple makefile example shows a variable definition for @code{objects}
955 as a list of all object files (@pxref{Variables Simplify, , Variables
956 Make Makefiles Simpler}).
960 A @dfn{directive} is a command for @code{make} to do something special while
961 reading the makefile. These include:
965 Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
968 Deciding (based on the values of variables) whether to use or
969 ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
972 Defining a variable from a verbatim string containing multiple lines
973 (@pxref{Defining, ,Defining Variables Verbatim}).
976 @cindex comments, in makefile
977 @cindex @code{#} (comments), in makefile
979 @samp{#} in a line of a makefile starts a @dfn{comment}. It and the rest of
980 the line are ignored, except that a trailing backslash not escaped by
981 another backslash will continue the comment across multiple lines.
982 Comments may appear on any of the lines in the makefile, except within a
983 @code{define} directive, and perhaps within commands (where the shell
984 decides what is a comment). A line containing just a comment (with
985 perhaps spaces before it) is effectively blank, and is ignored.@refill
988 @node Makefile Names, Include, Makefile Contents, Makefiles
989 @section What Name to Give Your Makefile
990 @cindex makefile name
991 @cindex name of makefile
992 @cindex default makefile name
993 @cindex file name of makefile
995 @c following paragraph rewritten to avoid overfull hbox
996 By default, when @code{make} looks for the makefile, it tries the
997 following names, in order: @file{GNUmakefile}, @file{makefile}
998 and @file{Makefile}.@refill
1003 @cindex @code{README}
1004 Normally you should call your makefile either @file{makefile} or
1005 @file{Makefile}. (We recommend @file{Makefile} because it appears
1006 prominently near the beginning of a directory listing, right near other
1007 important files such as @file{README}.) The first name checked,
1008 @file{GNUmakefile}, is not recommended for most makefiles. You should
1009 use this name if you have a makefile that is specific to GNU
1010 @code{make}, and will not be understood by other versions of
1011 @code{make}. Other @code{make} programs look for @file{makefile} and
1012 @file{Makefile}, but not @file{GNUmakefile}.
1014 If @code{make} finds none of these names, it does not use any makefile.
1015 Then you must specify a goal with a command argument, and @code{make}
1016 will attempt to figure out how to remake it using only its built-in
1017 implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}.
1020 @cindex @code{--file}
1021 @cindex @code{--makefile}
1022 If you want to use a nonstandard name for your makefile, you can specify
1023 the makefile name with the @samp{-f} or @samp{--file} option. The
1024 arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1025 @code{make} to read the file @var{name} as the makefile. If you use
1026 more than one @samp{-f} or @samp{--file} option, you can specify several
1027 makefiles. All the makefiles are effectively concatenated in the order
1028 specified. The default makefile names @file{GNUmakefile},
1029 @file{makefile} and @file{Makefile} are not checked automatically if you
1030 specify @samp{-f} or @samp{--file}.@refill
1031 @cindex specifying makefile name
1032 @cindex makefile name, how to specify
1033 @cindex name of makefile, how to specify
1034 @cindex file name of makefile, how to specify
1036 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
1037 @section Including Other Makefiles
1038 @cindex including other makefiles
1039 @cindex makefile, including
1042 The @code{include} directive tells @code{make} to suspend reading the
1043 current makefile and read one or more other makefiles before continuing.
1044 The directive is a line in the makefile that looks like this:
1047 include @var{filenames}@dots{}
1051 @var{filenames} can contain shell file name patterns.
1052 @cindex shell file name pattern (in @code{include})
1053 @cindex shell wildcards (in @code{include})
1054 @cindex wildcard, in @code{include}
1056 Extra spaces are allowed and ignored at the beginning of the line, but
1057 a tab is not allowed. (If the line begins with a tab, it will be
1058 considered a command line.) Whitespace is required between
1059 @code{include} and the file names, and between file names; extra
1060 whitespace is ignored there and at the end of the directive. A
1061 comment starting with @samp{#} is allowed at the end of the line. If
1062 the file names contain any variable or function references, they are
1063 expanded. @xref{Using Variables, ,How to Use Variables}.
1065 For example, if you have three @file{.mk} files, @file{a.mk},
1066 @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1067 @code{bish bash}, then the following expression
1070 include foo *.mk $(bar)
1076 include foo a.mk b.mk c.mk bish bash
1079 When @code{make} processes an @code{include} directive, it suspends
1080 reading of the containing makefile and reads from each listed file in
1081 turn. When that is finished, @code{make} resumes reading the
1082 makefile in which the directive appears.
1084 One occasion for using @code{include} directives is when several programs,
1085 handled by individual makefiles in various directories, need to use a
1086 common set of variable definitions
1087 (@pxref{Setting, ,Setting Variables}) or pattern rules
1088 (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1090 Another such occasion is when you want to generate dependencies from
1091 source files automatically; the dependencies can be put in a file that
1092 is included by the main makefile. This practice is generally cleaner
1093 than that of somehow appending the dependencies to the end of the main
1094 makefile as has been traditionally done with other versions of
1095 @code{make}. @xref{Automatic Dependencies}.
1096 @cindex dependencies, automatic generation
1097 @cindex automatic generation of dependencies
1098 @cindex generating dependencies automatically
1101 @cindex @code{--include-dir}
1102 @findex /usr/gnu/include
1103 @findex /usr/local/include
1104 @findex /usr/include
1105 If the specified name does not start with a slash, and the file is not
1106 found in the current directory, several other directories are searched.
1107 First, any directories you have specified with the @samp{-I} or
1108 @samp{--include-dir} option are searched
1109 (@pxref{Options Summary, ,Summary of Options}).
1110 Then the following directories (if they exist)
1111 are searched, in this order:
1112 @file{@var{prefix}/include} (normally @file{/usr/local/include})
1113 @file{/usr/gnu/include},
1114 @file{/usr/local/include}, @file{/usr/include}.
1116 If an included makefile cannot be found in any of these directories, a
1117 warning message is generated, but it is not an immediately fatal error;
1118 processing of the makefile containing the @code{include} continues.
1119 Once it has finished reading makefiles, @code{make} will try to remake
1120 any that are out of date or don't exist.
1121 @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1122 Only after it has tried to find a way to remake a makefile and failed,
1123 will @code{make} diagnose the missing makefile as a fatal error.
1125 If you want @code{make} to simply ignore a makefile which does not exist
1126 and cannot be remade, with no error message, use the @w{@code{-include}}
1127 directive instead of @code{include}, like this:
1130 -include @var{filenames}@dots{}
1133 This is acts like @code{include} in every way except that there is no
1134 error (not even a warning) if any of the @var{filenames} do not exist.
1136 @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
1137 @section The Variable @code{MAKEFILES}
1138 @cindex makefile, and @code{MAKEFILES} variable
1139 @cindex including (@code{MAKEFILES} variable)
1142 If the environment variable @code{MAKEFILES} is defined, @code{make}
1143 considers its value as a list of names (separated by whitespace) of
1144 additional makefiles to be read before the others. This works much like
1145 the @code{include} directive: various directories are searched for those
1146 files (@pxref{Include, ,Including Other Makefiles}). In addition, the
1147 default goal is never taken from one of these makefiles and it is not an
1148 error if the files listed in @code{MAKEFILES} are not found.@refill
1150 @cindex recursion, and @code{MAKEFILES} variable
1151 The main use of @code{MAKEFILES} is in communication between recursive
1152 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1153 @code{make}}). It usually is not desirable to set the environment
1154 variable before a top-level invocation of @code{make}, because it is
1155 usually better not to mess with a makefile from outside. However, if
1156 you are running @code{make} without a specific makefile, a makefile in
1157 @code{MAKEFILES} can do useful things to help the built-in implicit
1158 rules work better, such as defining search paths (@pxref{Directory Search}).
1160 Some users are tempted to set @code{MAKEFILES} in the environment
1161 automatically on login, and program makefiles to expect this to be done.
1162 This is a very bad idea, because such makefiles will fail to work if run by
1163 anyone else. It is much better to write explicit @code{include} directives
1164 in the makefiles. @xref{Include, , Including Other Makefiles}.
1166 @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles
1167 @section How Makefiles Are Remade
1169 @cindex updating makefiles
1170 @cindex remaking makefiles
1171 @cindex makefile, remaking of
1172 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1173 files. If a makefile can be remade from other files, you probably want
1174 @code{make} to get an up-to-date version of the makefile to read in.
1176 To this end, after reading in all makefiles, @code{make} will consider
1177 each as a goal target and attempt to update it. If a makefile has a
1178 rule which says how to update it (found either in that very makefile or
1179 in another one) or if an implicit rule applies to it (@pxref{Implicit
1180 Rules, ,Using Implicit Rules}), it will be updated if necessary. After
1181 all makefiles have been checked, if any have actually been changed,
1182 @code{make} starts with a clean slate and reads all the makefiles over
1183 again. (It will also attempt to update each of them over again, but
1184 normally this will not change them again, since they are already up to
1187 If the makefiles specify a double-colon rule to remake a file with
1188 commands but no dependencies, that file will always be remade
1189 (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a
1190 double-colon rule with commands but no dependencies will be remade every
1191 time @code{make} is run, and then again after @code{make} starts over
1192 and reads the makefiles in again. This would cause an infinite loop:
1193 @code{make} would constantly remake the makefile, and never do anything
1194 else. So, to avoid this, @code{make} will @strong{not} attempt to
1195 remake makefiles which are specified as double-colon targets but have no
1196 dependencies.@refill
1198 If you do not specify any makefiles to be read with @samp{-f} or
1199 @samp{--file} options, @code{make} will try the default makefile names;
1200 @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike
1201 makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1202 @code{make} is not certain that these makefiles should exist. However,
1203 if a default makefile does not exist but can be created by running
1204 @code{make} rules, you probably want the rules to be run so that the
1205 makefile can be used.
1207 Therefore, if none of the default makefiles exists, @code{make} will try
1208 to make each of them in the same order in which they are searched for
1209 (@pxref{Makefile Names, ,What Name to Give Your Makefile})
1210 until it succeeds in making one, or it runs out of names to try. Note
1211 that it is not an error if @code{make} cannot find or make any makefile;
1212 a makefile is not always necessary.@refill
1214 When you use the @samp{-t} or @samp{--touch} option
1215 (@pxref{Instead of Execution, ,Instead of Executing the Commands}),
1216 you would not want to use an out-of-date makefile to decide which
1217 targets to touch. So the @samp{-t} option has no effect on updating
1218 makefiles; they are really updated even if @samp{-t} is specified.
1219 Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1220 @samp{--just-print}) do not prevent updating of makefiles, because an
1221 out-of-date makefile would result in the wrong output for other targets.
1222 Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1223 and then print the commands to update @file{foo} and its dependencies
1224 without running them. The commands printed for @file{foo} will be those
1225 specified in the updated contents of @file{mfile}.
1227 However, on occasion you might actually wish to prevent updating of even
1228 the makefiles. You can do this by specifying the makefiles as goals in
1229 the command line as well as specifying them as makefiles. When the
1230 makefile name is specified explicitly as a goal, the options @samp{-t}
1231 and so on do apply to them.
1233 Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1234 @file{mfile}, print the commands needed to update it without actually
1235 running them, and then print the commands needed to update @file{foo}
1236 without running them. The commands for @file{foo} will be those
1237 specified by the existing contents of @file{mfile}.
1239 @node Overriding Makefiles, , Remaking Makefiles, Makefiles
1240 @section Overriding Part of Another Makefile
1242 @cindex overriding makefiles
1243 @cindex makefile, overriding
1244 Sometimes it is useful to have a makefile that is mostly just like
1245 another makefile. You can often use the @samp{include} directive to
1246 include one in the other, and add more targets or variable definitions.
1247 However, if the two makefiles give different commands for the same
1248 target, @code{make} will not let you just do this. But there is another way.
1250 @cindex @code{.DEFAULT}, used to override
1251 In the containing makefile (the one that wants to include the other),
1252 you can use the @code{.DEFAULT} special target to say that to remake
1253 any target that cannot be made from the information in the containing
1254 makefile, @code{make} should look in another makefile.
1255 @xref{Last Resort, , Defining Last-Resort Default Rules},
1256 for more information on @code{.DEFAULT}.
1258 For example, if you have a makefile called @file{Makefile} that says how
1259 to make the target @samp{foo} (and other targets), you can write a
1260 makefile called @file{GNUmakefile} that contains:
1267 @@$(MAKE) -f Makefile $@@
1270 If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1271 read it, and see that to make @file{foo}, it needs to run the command
1272 @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will
1273 find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1274 commands from @code{.DEFAULT}: @samp{make -f Makefile bar}. If
1275 @file{Makefile} provides a rule for updating @file{bar}, @code{make}
1276 will apply the rule. And likewise for any other target that
1277 @file{GNUmakefile} does not say how to make.@refill
1279 @node Rules, Commands, Makefiles, Top
1280 @chapter Writing Rules
1281 @cindex writing rules
1282 @cindex rule, how to write
1286 A @dfn{rule} appears in the makefile and says when and how to remake
1287 certain files, called the rule's @dfn{targets} (most often only one per rule).
1288 It lists the other files that are the @dfn{dependencies} of the target, and
1289 @dfn{commands} to use to create or update the target.
1291 @cindex default goal
1292 @cindex goal, default
1293 The order of rules is not significant, except for determining the
1294 @dfn{default goal}: the target for @code{make} to consider, if you do
1295 not otherwise specify one. The default goal is the target of the first
1296 rule in the first makefile. If the first rule has multiple targets,
1297 only the first target is taken as the default. There are two
1298 exceptions: a target starting with a period is not a default unless it
1299 contains one or more slashes, @samp{/}, as well; and, a target that
1300 defines a pattern rule has no effect on the default goal.
1301 (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1303 Therefore, we usually write the makefile so that the first rule is the
1304 one for compiling the entire program or all the programs described by
1305 the makefile (often with a target called @samp{all}).
1306 @xref{Goals, ,Arguments to Specify the Goals}.
1309 * Rule Example:: An example explained.
1310 * Rule Syntax:: General syntax explained.
1311 * Wildcards:: Using wildcard characters such as `*'.
1312 * Directory Search:: Searching other directories for source files.
1313 * Phony Targets:: Using a target that is not a real file's name.
1314 * Force Targets:: You can use a target without commands
1315 or dependencies to mark other
1317 * Empty Targets:: When only the date matters and the
1319 * Special Targets:: Targets with special built-in meanings.
1320 * Multiple Targets:: When to make use of several targets in a rule.
1321 * Multiple Rules:: How to use several rules with the same target.
1322 * Static Pattern:: Static pattern rules apply to multiple targets
1323 and can vary the dependencies according to
1325 * Double-Colon:: How to use a special kind of rule to allow
1326 several independent rules for one target.
1327 * Automatic Dependencies:: How to automatically generate rules giving
1328 dependencies from the source files themselves.
1332 @node Rule Example, Rule Syntax, , Rules
1333 @section Rule Example
1335 Here is an example of a rule:
1338 foo.o : foo.c defs.h # module for twiddling the frobs
1342 Its target is @file{foo.o} and its dependencies are @file{foo.c} and
1343 @file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}.
1344 The command line starts with a tab to identify it as a command.
1346 This rule says two things:
1350 How to decide whether @file{foo.o} is out of date: it is out of date
1351 if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1352 more recent than it.
1355 How to update the file @file{foo.o}: by running @code{cc} as stated.
1356 The command does not explicitly mention @file{defs.h}, but we presume
1357 that @file{foo.c} includes it, and that that is why @file{defs.h} was
1358 added to the dependencies.
1362 @node Rule Syntax, Wildcards, Rule Example, Rules
1363 @section Rule Syntax
1366 @cindex syntax of rules
1367 In general, a rule looks like this:
1370 @var{targets} : @var{dependencies}
1379 @var{targets} : @var{dependencies} ; @var{command}
1385 @cindex rule targets
1386 The @var{targets} are file names, separated by spaces. Wildcard
1387 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1388 in File Names}) and a name of the form @file{@var{a}(@var{m})}
1389 represents member @var{m} in archive file @var{a}
1390 (@pxref{Archive Members, ,Archive Members as Targets}).
1391 Usually there is only one
1392 target per rule, but occasionally there is a reason to have more
1393 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1396 @cindex tab character (in commands)
1397 The @var{command} lines start with a tab character. The first command may
1398 appear on the line after the dependencies, with a tab character, or may
1399 appear on the same line, with a semicolon. Either way, the effect is the
1400 same. @xref{Commands, ,Writing the Commands in Rules}.
1402 @cindex dollar sign (@code{$}), in rules
1403 @cindex @code{$}, in rules
1404 @cindex rule, and @code{$}
1405 Because dollar signs are used to start variable references, if you really
1406 want a dollar sign in a rule you must write two of them, @samp{$$}
1407 (@pxref{Using Variables, ,How to Use Variables}).
1408 You may split a long line by inserting a backslash
1409 followed by a newline, but this is not required, as @code{make} places no
1410 limit on the length of a line in a makefile.
1412 A rule tells @code{make} two things: when the targets are out of date,
1413 and how to update them when necessary.
1415 @cindex dependencies
1416 @cindex rule dependencies
1417 The criterion for being out of date is specified in terms of the
1418 @var{dependencies}, which consist of file names separated by spaces.
1419 (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1420 A target is out of date if it does not exist or if it is older than any
1421 of the dependencies (by comparison of last-modification times). The
1422 idea is that the contents of the target file are computed based on
1423 information in the dependencies, so if any of the dependencies changes,
1424 the contents of the existing target file are no longer necessarily
1427 How to update is specified by @var{commands}. These are lines to be
1428 executed by the shell (normally @samp{sh}), but with some extra features
1429 (@pxref{Commands, ,Writing the Commands in Rules}).
1431 @node Wildcards, Directory Search, Rule Syntax, Rules
1432 @section Using Wildcard Characters in File Names
1434 @cindex file name with wildcards
1435 @cindex globbing (wildcards)
1437 @cindex @code{*} (wildcard character)
1438 @cindex @code{?} (wildcard character)
1439 @cindex @code{[@dots{}]} (wildcard characters)
1440 A single file name can specify many files using @dfn{wildcard characters}.
1441 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
1442 @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
1443 specifies a list of all the files (in the working directory) whose names
1444 end in @samp{.c}.@refill
1446 @cindex @code{~} (tilde)
1447 @cindex tilde (@code{~})
1448 @cindex home directory
1449 The character @samp{~} at the beginning of a file name also has special
1450 significance. If alone, or followed by a slash, it represents your home
1451 directory. For example @file{~/bin} expands to @file{/home/you/bin}.
1452 If the @samp{~} is followed by a word, the string represents the home
1453 directory of the user named by that word. For example @file{~john/bin}
1454 expands to @file{/home/john/bin}.@refill
1456 Wildcard expansion happens automatically in targets, in dependencies,
1457 and in commands (where the shell does the expansion). In other
1458 contexts, wildcard expansion happens only if you request it explicitly
1459 with the @code{wildcard} function.
1461 The special significance of a wildcard character can be turned off by
1462 preceding it with a backslash. Thus, @file{foo\*bar} would refer to a
1463 specific file whose name consists of @samp{foo}, an asterisk, and
1467 * Wildcard Examples:: Several examples
1468 * Wildcard Pitfall:: Problems to avoid.
1469 * Wildcard Function:: How to cause wildcard expansion where
1470 it does not normally take place.
1473 @node Wildcard Examples, Wildcard Pitfall, , Wildcards
1474 @subsection Wildcard Examples
1476 Wildcards can be used in the commands of a rule, where they are expanded
1477 by the shell. For example, here is a rule to delete all the object files:
1485 @cindex @code{rm} (shell command)
1487 Wildcards are also useful in the dependencies of a rule. With the
1488 following rule in the makefile, @samp{make print} will print all the
1489 @samp{.c} files that have changed since the last time you printed them:
1497 @cindex @code{print} target
1498 @cindex @code{lpr} (shell command)
1499 @cindex @code{touch} (shell command)
1501 This rule uses @file{print} as an empty target file; see @ref{Empty
1502 Targets, ,Empty Target Files to Record Events}. (The automatic variable
1503 @samp{$?} is used to print only those files that have changed; see
1504 @ref{Automatic, ,Automatic Variables}.)@refill
1506 Wildcard expansion does not happen when you define a variable. Thus, if
1514 then the value of the variable @code{objects} is the actual string
1515 @samp{*.o}. However, if you use the value of @code{objects} in a target,
1516 dependency or command, wildcard expansion will take place at that time.
1517 To set @code{objects} to the expansion, instead use:
1520 objects := $(wildcard *.o)
1524 @xref{Wildcard Function}.
1526 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
1527 @subsection Pitfalls of Using Wildcards
1528 @cindex wildcard pitfalls
1529 @cindex pitfalls of wildcards
1530 @cindex mistakes with wildcards
1531 @cindex errors with wildcards
1532 @cindex problems with wildcards
1534 Now here is an example of a naive way of using wildcard expansion, that
1535 does not do what you would intend. Suppose you would like to say that the
1536 executable file @file{foo} is made from all the object files in the
1537 directory, and you write this:
1543 cc -o foo $(CFLAGS) $(objects)
1547 The value of @code{objects} is the actual string @samp{*.o}. Wildcard
1548 expansion happens in the rule for @file{foo}, so that each @emph{existing}
1549 @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
1552 But what if you delete all the @samp{.o} files? When a wildcard matches
1553 no files, it is left as it is, so then @file{foo} will depend on the
1554 oddly-named file @file{*.o}. Since no such file is likely to exist,
1555 @code{make} will give you an error saying it cannot figure out how to
1556 make @file{*.o}. This is not what you want!
1558 Actually it is possible to obtain the desired result with wildcard
1559 expansion, but you need more sophisticated techniques, including the
1560 @code{wildcard} function and string substitution.
1562 @xref{Wildcard Function, ,The Function @code{wildcard}}.
1565 These are described in the following section.
1568 @node Wildcard Function, , Wildcard Pitfall, Wildcards
1569 @subsection The Function @code{wildcard}
1572 Wildcard expansion happens automatically in rules. But wildcard expansion
1573 does not normally take place when a variable is set, or inside the
1574 arguments of a function. If you want to do wildcard expansion in such
1575 places, you need to use the @code{wildcard} function, like this:
1578 $(wildcard @var{pattern}@dots{})
1582 This string, used anywhere in a makefile, is replaced by a
1583 space-separated list of names of existing files that match one of the
1584 given file name patterns. If no existing file name matches a pattern,
1585 then that pattern is omitted from the output of the @code{wildcard}
1586 function. Note that this is different from how unmatched wildcards
1587 behave in rules, where they are used verbatim rather than ignored
1588 (@pxref{Wildcard Pitfall}).
1590 One use of the @code{wildcard} function is to get a list of all the C source
1591 files in a directory, like this:
1597 We can change the list of C source files into a list of object files by
1598 replacing the @samp{.o} suffix with @samp{.c} in the result, like this:
1601 $(patsubst %.c,%.o,$(wildcard *.c))
1605 (Here we have used another function, @code{patsubst}.
1606 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
1608 Thus, a makefile to compile all C source files in the directory and then
1609 link them together could be written as follows:
1612 objects := $(patsubst %.c,%.o,$(wildcard *.c))
1615 cc -o foo $(objects)
1619 (This takes advantage of the implicit rule for compiling C programs, so
1620 there is no need to write explicit rules for compiling the files.
1621 @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
1622 @samp{:=}, which is a variant of @samp{=}.)
1624 @node Directory Search, Phony Targets, Wildcards, Rules
1625 @section Searching Directories for Dependencies
1629 @cindex search path for dependencies (@code{VPATH})
1630 @cindex directory search (@code{VPATH})
1632 For large systems, it is often desirable to put sources in a separate
1633 directory from the binaries. The @dfn{directory search} features of
1634 @code{make} facilitate this by searching several directories
1635 automatically to find a dependency. When you redistribute the files
1636 among directories, you do not need to change the individual rules,
1637 just the search paths.
1640 * General Search:: Specifying a search path that applies
1641 to every dependency.
1642 * Selective Search:: Specifying a search path
1643 for a specified class of names.
1644 * Commands/Search:: How to write shell commands that work together
1646 * Implicit/Search:: How search paths affect implicit rules.
1647 * Libraries/Search:: Directory search for link libraries.
1650 @node General Search, Selective Search, , Directory Search
1651 @subsection @code{VPATH}: Search Path for All Dependencies
1654 The value of the @code{make} variable @code{VPATH} specifies a list of
1655 directories that @code{make} should search. Most often, the
1656 directories are expected to contain dependency files that are not in the
1657 current directory; however, @code{VPATH} specifies a search list that
1658 @code{make} applies for all files, including files which are targets of
1661 Thus, if a file that is listed as a target or dependency does not exist
1662 in the current directory, @code{make} searches the directories listed in
1663 @code{VPATH} for a file with that name. If a file is found in one of
1664 them, that file becomes the dependency. Rules may then specify the
1665 names of source files in the dependencies as if they all existed in the
1666 current directory. @xref{Commands/Search, ,Writing Shell Commands with
1669 In the @code{VPATH} variable, directory names are separated by colons.
1670 The order in which directories are listed is the order followed by
1671 @code{make} in its search.
1676 VPATH = src:../headers
1680 specifies a path containing two directories, @file{src} and
1681 @file{../headers}, which @code{make} searches in that order.
1683 With this value of @code{VPATH}, the following rule,
1690 is interpreted as if it were written like this:
1697 assuming the file @file{foo.c} does not exist in the current directory but
1698 is found in the directory @file{src}.
1700 @node Selective Search, Commands/Search, General Search, Directory Search
1701 @subsection The @code{vpath} Directive
1704 Similar to the @code{VPATH} variable but more selective is the @code{vpath}
1705 directive (note lower case), which allows you to specify a search path for a particular class
1706 of file names, those that match a particular pattern. Thus you can supply
1707 certain search directories for one class of file names and other directories
1708 (or none) for other file names.
1710 There are three forms of the @code{vpath} directive:
1713 @item vpath @var{pattern} @var{directories}
1714 Specify the search path @var{directories} for file names that match
1717 The search path, @var{directories}, is a colon-separated list of
1718 directories to be searched, just like the search path used in the
1719 @code{VPATH} variable.
1721 @item vpath @var{pattern}
1722 Clear out the search path associated with @var{pattern}.
1724 @c Extra blank line makes sure this gets two lines.
1727 Clear all search paths previously specified with @code{vpath} directives.
1730 A @code{vpath} pattern is a string containing a @samp{%} character. The
1731 string must match the file name of a dependency that is being searched
1732 for, the @samp{%} character matching any sequence of zero or more
1733 characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
1734 Redefining Pattern Rules}). For example, @code{%.h} matches files that
1735 end in @code{.h}. (If there is no @samp{%}, the pattern must match the
1736 dependency exactly, which is not useful very often.)
1738 @cindex @code{%}, quoting in @code{vpath}
1739 @cindex @code{%}, quoting with @code{\} (backslash)
1740 @cindex @code{\} (backslash), to quote @code{%}
1741 @cindex backslash (@code{\}), to quote @code{%}
1742 @cindex quoting @code{%}, in @code{vpath}
1743 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
1744 with preceding backslashes (@samp{\}). Backslashes that would otherwise
1745 quote @samp{%} characters can be quoted with more backslashes.
1746 Backslashes that quote @samp{%} characters or other backslashes are
1747 removed from the pattern before it is compared to file names. Backslashes
1748 that are not in danger of quoting @samp{%} characters go unmolested.@refill
1750 When a dependency fails to exist in the current directory, if the
1751 @var{pattern} in a @code{vpath} directive matches the name of the
1752 dependency file, then the @var{directories} in that directive are searched
1753 just like (and before) the directories in the @code{VPATH} variable.
1758 vpath %.h ../headers
1762 tells @code{make} to look for any dependency whose name ends in @file{.h}
1763 in the directory @file{../headers} if the file is not found in the current
1766 If several @code{vpath} patterns match the dependency file's name, then
1767 @code{make} processes each matching @code{vpath} directive one by one,
1768 searching all the directories mentioned in each directive. @code{make}
1769 handles multiple @code{vpath} directives in the order in which they
1770 appear in the makefile; multiple directives with the same pattern are
1771 independent of each other.
1785 will look for a file ending in @samp{.c} in @file{foo}, then
1786 @file{blish}, then @file{bar}, while
1796 will look for a file ending in @samp{.c} in @file{foo}, then
1797 @file{bar}, then @file{blish}.
1799 @node Commands/Search, Implicit/Search, Selective Search, Directory Search
1800 @subsection Writing Shell Commands with Directory Search
1801 @cindex shell command, and directory search
1802 @cindex directory search (@code{VPATH}), and shell commands
1804 When a dependency is found in another directory through directory search,
1805 this cannot change the commands of the rule; they will execute as written.
1806 Therefore, you must write the commands with care so that they will look for
1807 the dependency in the directory where @code{make} finds it.
1809 This is done with the @dfn{automatic variables} such as @samp{$^}
1810 (@pxref{Automatic, ,Automatic Variables}).
1811 For instance, the value of @samp{$^} is a
1812 list of all the dependencies of the rule, including the names of
1813 the directories in which they were found, and the value of
1814 @samp{$@@} is the target. Thus:@refill
1818 cc -c $(CFLAGS) $^ -o $@@
1822 (The variable @code{CFLAGS} exists so you can specify flags for C
1823 compilation by implicit rules; we use it here for consistency so it will
1824 affect all C compilations uniformly;
1825 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
1827 Often the dependencies include header files as well, which you do not
1828 want to mention in the commands. The automatic variable @samp{$<} is
1829 just the first dependency:
1832 VPATH = src:../headers
1833 foo.o : foo.c defs.h hack.h
1834 cc -c $(CFLAGS) $< -o $@@
1837 @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
1838 @subsection Directory Search and Implicit Rules
1839 @cindex @code{VPATH}, and implicit rules
1840 @cindex directory search (@code{VPATH}), and implicit rules
1841 @cindex search path for dependencies (@code{VPATH}), and implicit rules
1842 @cindex implicit rule, and directory search
1843 @cindex implicit rule, and @code{VPATH}
1844 @cindex rule, implicit, and directory search
1845 @cindex rule, implicit, and @code{VPATH}
1847 The search through the directories specified in @code{VPATH} or with
1848 @code{vpath} also happens during consideration of implicit rules
1849 (@pxref{Implicit Rules, ,Using Implicit Rules}).
1851 For example, when a file @file{foo.o} has no explicit rule, @code{make}
1852 considers implicit rules, such as the built-in rule to compile
1853 @file{foo.c} if that file exists. If such a file is lacking in the
1854 current directory, the appropriate directories are searched for it. If
1855 @file{foo.c} exists (or is mentioned in the makefile) in any of the
1856 directories, the implicit rule for C compilation is applied.
1858 The commands of implicit rules normally use automatic variables as a
1859 matter of necessity; consequently they will use the file names found by
1860 directory search with no extra effort.
1862 @node Libraries/Search, , Implicit/Search, Directory Search
1863 @subsection Directory Search for Link Libraries
1864 @cindex link libraries, and directory search
1865 @cindex libraries for linking, directory search
1866 @cindex directory search (@code{VPATH}), and link libraries
1867 @cindex @code{VPATH}, and link libraries
1868 @cindex search path for dependencies (@code{VPATH}), and link libraries
1869 @cindex @code{-l} (library search)
1871 Directory search applies in a special way to libraries used with the
1872 linker. This special feature comes into play when you write a dependency
1873 whose name is of the form @samp{-l@var{name}}. (You can tell something
1874 strange is going on here because the dependency is normally the name of a
1875 file, and the @emph{file name} of the library looks like
1876 @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
1878 When a dependency's name has the form @samp{-l@var{name}}, @code{make}
1879 handles it specially by searching for the file @file{lib@var{name}.a} in
1880 the current directory, in directories specified by matching @code{vpath}
1881 search paths and the @code{VPATH} search path, and then in the
1882 directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
1883 (normally @file{/usr/local/lib}).
1889 foo : foo.c -lcurses
1895 would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
1896 be executed when @file{foo} is older than @file{foo.c} or than
1897 @file{/usr/lib/libcurses.a}.@refill
1899 @node Phony Targets, Force Targets, Directory Search, Rules
1900 @section Phony Targets
1901 @cindex phony targets
1902 @cindex targets, phony
1903 @cindex targets without a file
1905 A phony target is one that is not really the name of a file. It is just a
1906 name for some commands to be executed when you make an explicit request.
1907 There are two reasons to use a phony target: to avoid a conflict with
1908 a file of the same name, and to improve performance.
1910 If you write a rule whose commands will not create the target file, the
1911 commands will be executed every time the target comes up for remaking.
1922 Because the @code{rm} command does not create a file named @file{clean},
1923 probably no such file will ever exist. Therefore, the @code{rm} command
1924 will be executed every time you say @samp{make clean}.
1925 @cindex @code{rm} (shell command)
1928 The phony target will cease to work if anything ever does create a file
1929 named @file{clean} in this directory. Since it has no dependencies, the
1930 file @file{clean} would inevitably be considered up to date, and its
1931 commands would not be executed. To avoid this problem, you can explicitly
1932 declare the target to be phony, using the special target @code{.PHONY}
1933 (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
1940 Once this is done, @samp{make clean} will run the commands regardless of
1941 whether there is a file named @file{clean}.
1943 Since it knows that phony targets do not name actual files that could be
1944 remade from other files, @code{make} skips the implicit rule search for
1945 phony targets (@pxref{Implicit Rules}). This is why declaring a target
1946 phony is good for performance, even if you are not worried about the
1947 actual file existing.
1949 Thus, you first write the line that states that @code{clean} is a
1950 phony target, then you write the rule, like this:
1960 A phony target should not be a dependency of a real target file; if it
1961 is, its commands are run every time @code{make} goes to update that
1962 file. As long as a phony target is never a dependency of a real
1963 target, the phony target commands will be executed only when the phony
1964 target is a specified goal (@pxref{Goals, ,Arguments to Specify the
1967 Phony targets can have dependencies. When one directory contains multiple
1968 programs, it is most convenient to describe all of the programs in one
1969 makefile @file{./Makefile}. Since the target remade by default will be the
1970 first one in the makefile, it is common to make this a phony target named
1971 @samp{all} and give it, as dependencies, all the individual programs. For
1975 all : prog1 prog2 prog3
1978 prog1 : prog1.o utils.o
1979 cc -o prog1 prog1.o utils.o
1984 prog3 : prog3.o sort.o utils.o
1985 cc -o prog3 prog3.o sort.o utils.o
1989 Now you can say just @samp{make} to remake all three programs, or specify
1990 as arguments the ones to remake (as in @samp{make prog1 prog3}).
1992 When one phony target is a dependency of another, it serves as a subroutine
1993 of the other. For example, here @samp{make cleanall} will delete the
1994 object files, the difference files, and the file @file{program}:
1997 .PHONY: cleanall cleanobj cleandiff
1999 cleanall : cleanobj cleandiff
2009 @node Force Targets, Empty Targets, Phony Targets, Rules
2010 @section Rules without Commands or Dependencies
2011 @cindex force targets
2012 @cindex targets, force
2013 @cindex @code{FORCE}
2014 @cindex rule, no commands or dependencies
2016 If a rule has no dependencies or commands, and the target of the rule
2017 is a nonexistent file, then @code{make} imagines this target to have
2018 been updated whenever its rule is run. This implies that all targets
2019 depending on this one will always have their commands run.
2021 An example will illustrate this:
2031 Here the target @samp{FORCE} satisfies the special conditions, so the
2032 target @file{clean} that depends on it is forced to run its commands.
2033 There is nothing special about the name @samp{FORCE}, but that is one name
2034 commonly used this way.
2036 As you can see, using @samp{FORCE} this way has the same results as using
2037 @samp{.PHONY: clean}.
2039 Using @samp{.PHONY} is more explicit and more efficient. However,
2040 other versions of @code{make} do not support @samp{.PHONY}; thus
2041 @samp{FORCE} appears in many makefiles. @xref{Phony Targets}.
2043 @node Empty Targets, Special Targets, Force Targets, Rules
2044 @section Empty Target Files to Record Events
2045 @cindex empty targets
2046 @cindex targets, empty
2047 @cindex recording events with empty targets
2049 The @dfn{empty target} is a variant of the phony target; it is used to hold
2050 commands for an action that you request explicitly from time to time.
2051 Unlike a phony target, this target file can really exist; but the file's
2052 contents do not matter, and usually are empty.
2054 The purpose of the empty target file is to record, with its
2055 last-modification time, when the rule's commands were last executed. It
2056 does so because one of the commands is a @code{touch} command to update the
2059 The empty target file must have some dependencies. When you ask to remake
2060 the empty target, the commands are executed if any dependency is more
2061 recent than the target; in other words, if a dependency has changed since
2062 the last time you remade the target. Here is an example:
2069 @cindex @code{print} target
2070 @cindex @code{lpr} (shell command)
2071 @cindex @code{touch} (shell command)
2074 With this rule, @samp{make print} will execute the @code{lpr} command if
2075 either source file has changed since the last @samp{make print}. The
2076 automatic variable @samp{$?} is used to print only those files that have
2077 changed (@pxref{Automatic, ,Automatic Variables}).
2079 @node Special Targets, Multiple Targets, Empty Targets, Rules
2080 @section Special Built-in Target Names
2081 @cindex special targets
2082 @cindex built-in special targets
2083 @cindex targets, built-in special
2085 Certain names have special meanings if they appear as targets.
2091 The dependencies of the special target @code{.PHONY} are considered to
2092 be phony targets. When it is time to consider such a target,
2093 @code{make} will run its commands unconditionally, regardless of
2094 whether a file with that name exists or what its last-modification
2095 time is. @xref{Phony Targets, ,Phony Targets}.
2100 The dependencies of the special target @code{.SUFFIXES} are the list
2101 of suffixes to be used in checking for suffix rules.
2102 @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2107 The commands specified for @code{.DEFAULT} are used for any target for
2108 which no rules are found (either explicit rules or implicit rules).
2109 @xref{Last Resort}. If @code{.DEFAULT} commands are specified, every
2110 file mentioned as a dependency, but not as a target in a rule, will have
2111 these commands executed on its behalf. @xref{Search Algorithm,
2112 ,Implicit Rule Search Algorithm}.
2116 @cindex precious targets
2117 @cindex preserving with @code{.PRECIOUS}
2119 The targets which @code{.PRECIOUS} depends on are given the following
2120 special treatment: if @code{make} is killed or interrupted during the
2121 execution of their commands, the target is not deleted.
2122 @xref{Interrupts, ,Interrupting or Killing @code{make}}.
2123 Also, if the target is an intermediate file, it will not be deleted
2124 after it is no longer needed, as is normally done.
2125 @xref{Chained Rules, ,Chains of Implicit Rules}.
2127 You can also list the target pattern of an implicit rule (such as
2128 @samp{%.o}) as a dependency file of the special target @code{.PRECIOUS}
2129 to preserve intermediate files created by rules whose target patterns
2130 match that file's name.
2135 Simply by being mentioned as a target, @code{.IGNORE} says to ignore
2136 errors in execution of commands. The dependencies and commands for
2137 @code{.IGNORE} are not meaningful.
2139 @samp{.IGNORE} exists for historical compatibility. Since
2140 @code{.IGNORE} affects every command in the makefile, it is not very
2141 useful; we recommend you use the more selective ways to ignore errors
2142 in specific commands. @xref{Errors, ,Errors in Commands}.
2147 Simply by being mentioned as a target, @code{.SILENT} says not to
2148 print commands before executing them. The dependencies and commands
2149 for @code{.SILENT} are not meaningful.
2151 @samp{.SILENT} exists for historical compatibility. We recommend you
2152 use the more selective ways to silence specific commands.
2153 @xref{Echoing, ,Command Echoing}. If you want to silence all commands
2154 for a particular run of @code{make}, use the @samp{-s} or
2155 @w{@samp{--silent}} option (@pxref{Options Summary}).
2157 @findex .EXPORT_ALL_VARIABLES
2158 @item .EXPORT_ALL_VARIABLES
2160 Simply by being mentioned as a target, this tells @code{make} to
2161 export all variables to child processes by default.
2162 @xref{Variables/Recursion, ,Communicating Variables to a
2166 Any defined implicit rule suffix also counts as a special target if it
2167 appears as a target, and so does the concatenation of two suffixes, such
2168 as @samp{.c.o}. These targets are suffix rules, an obsolete way of
2169 defining implicit rules (but a way still widely used). In principle, any
2170 target name could be special in this way if you break it in two and add
2171 both pieces to the suffix list. In practice, suffixes normally begin with
2172 @samp{.}, so these special target names also begin with @samp{.}.
2173 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
2175 @node Multiple Targets, Multiple Rules, Special Targets, Rules
2176 @section Multiple Targets in a Rule
2177 @cindex multiple targets
2178 @cindex several targets in a rule
2179 @cindex targets, multiple
2180 @cindex rule, with multiple targets
2182 A rule with multiple targets is equivalent to writing many rules, each with
2183 one target, and all identical aside from that. The same commands apply to
2184 all the targets, but their effects may vary because you can substitute the
2185 actual target name into the command using @samp{$@@}. The rule contributes
2186 the same dependencies to all the targets also.
2188 This is useful in two cases.
2192 You want just dependencies, no commands. For example:
2195 kbd.o command.o files.o: command.h
2199 gives an additional dependency to each of the three object files
2203 Similar commands work for all the targets. The commands do not need
2204 to be absolutely identical, since the automatic variable @samp{$@@}
2205 can be used to substitute the particular target to be remade into the
2206 commands (@pxref{Automatic, ,Automatic Variables}). For example:
2210 bigoutput littleoutput : text.g
2211 generate text.g -$(subst output,,$@@) > $@@
2221 generate text.g -big > bigoutput
2222 littleoutput : text.g
2223 generate text.g -little > littleoutput
2227 Here we assume the hypothetical program @code{generate} makes two
2228 types of output, one if given @samp{-big} and one if given
2230 @xref{Text Functions, ,Functions for String Substitution and Analysis},
2231 for an explanation of the @code{subst} function.
2234 Suppose you would like to vary the dependencies according to the target,
2235 much as the variable @samp{$@@} allows you to vary the commands.
2236 You cannot do this with multiple targets in an ordinary rule, but you can
2237 do it with a @dfn{static pattern rule}.
2238 @xref{Static Pattern, ,Static Pattern Rules}.
2240 @node Multiple Rules, Static Pattern, Multiple Targets, Rules
2241 @section Multiple Rules for One Target
2242 @cindex multiple rules for one target
2243 @cindex several rules for one target
2244 @cindex rule, multiple for one target
2245 @cindex target, multiple rules for one
2247 One file can be the target of several rules. All the dependencies
2248 mentioned in all the rules are merged into one list of dependencies for
2249 the target. If the target is older than any dependency from any rule,
2250 the commands are executed.
2252 There can only be one set of commands to be executed for a file.
2253 If more than one rule gives commands for the same file,
2254 @code{make} uses the last set given and prints an error message.
2255 (As a special case, if the file's name begins with a dot, no
2256 error message is printed. This odd behavior is only for
2257 compatibility with other implementations of @code{make}.)
2258 There is no reason to
2259 write your makefiles this way; that is why @code{make} gives you
2260 an error message.@refill
2262 An extra rule with just dependencies can be used to give a few extra
2263 dependencies to many files at once. For example, one usually has a
2264 variable named @code{objects} containing a list of all the compiler output
2265 files in the system being made. An easy way to say that all of them must
2266 be recompiled if @file{config.h} changes is to write the following:
2269 objects = foo.o bar.o
2271 bar.o : defs.h test.h
2272 $(objects) : config.h
2275 This could be inserted or taken out without changing the rules that really
2276 specify how to make the object files, making it a convenient form to use if
2277 you wish to add the additional dependency intermittently.
2279 Another wrinkle is that the additional dependencies could be specified with
2280 a variable that you set with a command argument to @code{make}
2281 (@pxref{Overriding, ,Overriding Variables}). For example,
2286 $(objects) : $(extradeps)
2291 means that the command @samp{make extradeps=foo.h} will consider
2292 @file{foo.h} as a dependency of each object file, but plain @samp{make}
2295 If none of the explicit rules for a target has commands, then @code{make}
2296 searches for an applicable implicit rule to find some commands
2297 @pxref{Implicit Rules, ,Using Implicit Rules}).
2299 @node Static Pattern, Double-Colon, Multiple Rules, Rules
2300 @section Static Pattern Rules
2301 @cindex static pattern rule
2302 @cindex rule, static pattern
2303 @cindex pattern rules, static (not implicit)
2304 @cindex varying dependencies
2305 @cindex dependencies, varying (static pattern)
2307 @dfn{Static pattern rules} are rules which specify multiple targets and
2308 construct the dependency names for each target based on the target name.
2309 They are more general than ordinary rules with multiple targets because the
2310 targets do not have to have identical dependencies. Their dependencies must
2311 be @emph{analogous}, but not necessarily @emph{identical}.
2314 * Static Usage:: The syntax of static pattern rules.
2315 * Static versus Implicit:: When are they better than implicit rules?
2318 @node Static Usage, Static versus Implicit, , Static Pattern
2319 @subsection Syntax of Static Pattern Rules
2320 @cindex static pattern rule, syntax of
2321 @cindex pattern rules, static, syntax of
2323 Here is the syntax of a static pattern rule:
2326 @var{targets} @dots{}: @var{target-pattern}: @var{dep-patterns} @dots{}
2332 The @var{targets} list specifies the targets that the rule applies to.
2333 The targets can contain wildcard characters, just like the targets of
2334 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
2337 @cindex target pattern, static (not implicit)
2339 The @var{target-pattern} and @var{dep-patterns} say how to compute the
2340 dependencies of each target. Each target is matched against the
2341 @var{target-pattern} to extract a part of the target name, called the
2342 @dfn{stem}. This stem is substituted into each of the @var{dep-patterns}
2343 to make the dependency names (one from each @var{dep-pattern}).
2345 Each pattern normally contains the character @samp{%} just once. When the
2346 @var{target-pattern} matches a target, the @samp{%} can match any part of
2347 the target name; this part is called the @dfn{stem}. The rest of the
2348 pattern must match exactly. For example, the target @file{foo.o} matches
2349 the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
2350 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
2352 @cindex dependency pattern, static (not implicit)
2353 The dependency names for each target are made by substituting the stem
2354 for the @samp{%} in each dependency pattern. For example, if one
2355 dependency pattern is @file{%.c}, then substitution of the stem
2356 @samp{foo} gives the dependency name @file{foo.c}. It is legitimate
2357 to write a dependency pattern that does not contain @samp{%}; then this
2358 dependency is the same for all targets.
2360 @cindex @code{%}, quoting in static pattern
2361 @cindex @code{%}, quoting with @code{\} (backslash)
2362 @cindex @code{\} (backslash), to quote @code{%}
2363 @cindex backslash (@code{\}), to quote @code{%}
2364 @cindex quoting @code{%}, in static pattern
2365 @samp{%} characters in pattern rules can be quoted with preceding
2366 backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%}
2367 characters can be quoted with more backslashes. Backslashes that quote
2368 @samp{%} characters or other backslashes are removed from the pattern
2369 before it is compared to file names or has a stem substituted into it.
2370 Backslashes that are not in danger of quoting @samp{%} characters go
2371 unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has
2372 @samp{the%weird\} preceding the operative @samp{%} character, and
2373 @samp{pattern\\} following it. The final two backslashes are left alone
2374 because they cannot affect any @samp{%} character.@refill
2376 Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
2377 from the corresponding @file{.c} file:
2381 objects = foo.o bar.o
2383 $(objects): %.o: %.c
2384 $(CC) -c $(CFLAGS) $< -o $@@
2389 Here @samp{$<} is the automatic variable that holds the name of the
2390 dependency and @samp{$@@} is the automatic variable that holds the name
2391 of the target; see @ref{Automatic, , Automatic Variables}.
2393 Each target specified must match the target pattern; a warning is issued
2394 for each target that does not. If you have a list of files, only some of
2395 which will match the pattern, you can use the @code{filter} function to
2396 remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
2399 files = foo.elc bar.o lose.o
2401 $(filter %.o,$(files)): %.o: %.c
2402 $(CC) -c $(CFLAGS) $< -o $@@
2403 $(filter %.elc,$(files)): %.elc: %.el
2404 emacs -f batch-byte-compile $<
2408 In this example the result of @samp{$(filter %.o,$(files))} is
2409 @file{bar.o lose.o}, and the first static pattern rule causes each of
2410 these object files to be updated by compiling the corresponding C source
2411 file. The result of @w{@samp{$(filter %.elc,$(files))}} is
2412 @file{foo.elc}, so that file is made from @file{foo.el}.@refill
2414 Another example shows how to use @code{$*} in static pattern rules:
2415 @vindex $*@r{, and static pattern}
2419 bigoutput littleoutput : %output : text.g
2420 generate text.g -$* > $@@
2425 When the @code{generate} command is run, @code{$*} will expand to the
2426 stem, either @samp{big} or @samp{little}.
2428 @node Static versus Implicit, , Static Usage, Static Pattern
2429 @subsection Static Pattern Rules versus Implicit Rules
2430 @cindex rule, static pattern versus implicit
2431 @cindex static pattern rule, versus implicit
2433 A static pattern rule has much in common with an implicit rule defined as a
2434 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
2435 Both have a pattern for the target and patterns for constructing the
2436 names of dependencies. The difference is in how @code{make} decides
2437 @emph{when} the rule applies.
2439 An implicit rule @emph{can} apply to any target that matches its pattern,
2440 but it @emph{does} apply only when the target has no commands otherwise
2441 specified, and only when the dependencies can be found. If more than one
2442 implicit rule appears applicable, only one applies; the choice depends on
2445 By contrast, a static pattern rule applies to the precise list of targets
2446 that you specify in the rule. It cannot apply to any other target and it
2447 invariably does apply to each of the targets specified. If two conflicting
2448 rules apply, and both have commands, that's an error.
2450 The static pattern rule can be better than an implicit rule for these
2455 You may wish to override the usual implicit rule for a few
2456 files whose names cannot be categorized syntactically but
2457 can be given in an explicit list.
2460 If you cannot be sure of the precise contents of the directories
2461 you are using, you may not be sure which other irrelevant files
2462 might lead @code{make} to use the wrong implicit rule. The choice
2463 might depend on the order in which the implicit rule search is done.
2464 With static pattern rules, there is no uncertainty: each rule applies
2465 to precisely the targets specified.
2468 @node Double-Colon, Automatic Dependencies, Static Pattern, Rules
2469 @section Double-Colon Rules
2470 @cindex double-colon rules
2471 @cindex rule, double-colon (@code{::})
2472 @cindex multiple rules for one target (@code{::})
2473 @cindex @code{::} rules (double-colon)
2475 @dfn{Double-colon} rules are rules written with @samp{::} instead of
2476 @samp{:} after the target names. They are handled differently from
2477 ordinary rules when the same target appears in more than one rule.
2479 When a target appears in multiple rules, all the rules must be the same
2480 type: all ordinary, or all double-colon. If they are double-colon, each of
2481 them is independent of the others. Each double-colon rule's commands are
2482 executed if the target is older than any dependencies of that rule. This
2483 can result in executing none, any, or all of the double-colon rules.
2485 Double-colon rules with the same target are in fact completely separate
2486 from one another. Each double-colon rule is processed individually, just
2487 as rules with different targets are processed.
2489 The double-colon rules for a target are executed in the order they appear
2490 in the makefile. However, the cases where double-colon rules really make
2491 sense are those where the order of executing the commands would not matter.
2493 Double-colon rules are somewhat obscure and not often very useful; they
2494 provide a mechanism for cases in which the method used to update a target
2495 differs depending on which dependency files caused the update, and such
2498 Each double-colon rule should specify commands; if it does not, an
2499 implicit rule will be used if one applies.
2500 @xref{Implicit Rules, ,Using Implicit Rules}.
2502 @node Automatic Dependencies, , Double-Colon, Rules
2503 @section Generating Dependencies Automatically
2504 @cindex dependencies, automatic generation
2505 @cindex automatic generation of dependencies
2506 @cindex generating dependencies automatically
2508 In the makefile for a program, many of the rules you need to write often
2509 say only that some object file depends on some header
2510 file. For example, if @file{main.c} uses @file{defs.h} via an
2511 @code{#include}, you would write:
2518 You need this rule so that @code{make} knows that it must remake
2519 @file{main.o} whenever @file{defs.h} changes. You can see that for a
2520 large program you would have to write dozens of such rules in your
2521 makefile. And, you must always be very careful to update the makefile
2522 every time you add or remove an @code{#include}.
2523 @cindex @code{#include}
2525 @cindex @code{-M} (to compiler)
2526 To avoid this hassle, most modern C compilers can write these rules for
2527 you, by looking at the @code{#include} lines in the source files.
2528 Usually this is done with the @samp{-M} option to the compiler.
2529 For example, the command:
2536 generates the output:
2539 main.o : main.c defs.h
2543 Thus you no longer have to write all those rules yourself.
2544 The compiler will do it for you.
2546 Note that such a dependency constitutes mentioning @file{main.o} in a
2547 makefile, so it can never be considered an intermediate file by implicit
2548 rule search. This means that @code{make} won't ever remove the file
2549 after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}.
2551 @cindex @code{make depend}
2552 With old @code{make} programs, it was traditional practice to use this
2553 compiler feature to generate dependencies on demand with a command like
2554 @samp{make depend}. That command would create a file @file{depend}
2555 containing all the automatically-generated dependencies; then the
2556 makefile could use @code{include} to read them in (@pxref{Include}).
2558 In GNU @code{make}, the feature of remaking makefiles makes this
2559 practice obsolete---you need never tell @code{make} explicitly to
2560 regenerate the dependencies, because it always regenerates any makefile
2561 that is out of date. @xref{Remaking Makefiles}.
2563 The practice we recommend for automatic dependency generation is to have
2564 one makefile corresponding to each source file. For each source file
2565 @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
2566 what files the object file @file{@var{name}.o} depends on. That way
2567 only the source files that have changed need to be rescanned to produce
2568 the new dependencies.
2570 Here is the pattern rule to generate a file of dependencies (i.e., a makefile)
2571 called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
2576 $(SHELL) -ec '$(CC) -M $(CPPFLAGS) $< | sed '\''s/$*.o/& $@@/g'\'' > $@@'
2581 @xref{Pattern Rules}, for information on defining pattern rules. The
2582 @samp{-e} flag to the shell makes it exit immediately if the
2583 @code{$(CC)} command fails (exits with a nonzero status). Normally the
2584 shell exits with the status of the last command in the pipeline
2585 (@code{sed} in this case), so @code{make} would not notice a nonzero
2586 status from the compiler.
2587 @cindex @code{-e} (shell flag)
2589 @cindex @code{sed} (shell command)
2590 The purpose of the @code{sed} command is to translate (for example):
2593 main.o : main.c defs.h
2600 main.o main.d : main.c defs.h
2605 This makes each @samp{.d} file depend on all the source and header files
2606 that the corresponding @samp{.o} file depends on. @code{make} then
2607 knows it must regenerate the dependencies whenever any of the source or
2608 header files changes.
2610 Once you've defined the rule to remake the @samp{.d} files,
2611 you then use the @code{include} directive to read them all in.
2612 @xref{Include}. For example:
2616 sources = foo.c bar.c
2618 include $(sources:.c=.d)
2623 (This example uses a substitution variable reference to translate the
2624 list of source files @samp{foo.c bar.c} into a list of dependency
2625 makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full
2626 information on substitution references.) Since the @samp{.d} files are
2627 makefiles like any others, @code{make} will remake them as necessary
2628 with no further work from you. @xref{Remaking Makefiles}.
2630 @node Commands, Using Variables, Rules, Top
2631 @chapter Writing the Commands in Rules
2632 @cindex commands, how to write
2633 @cindex rule commands
2634 @cindex writing rule commands
2636 The commands of a rule consist of shell command lines to be executed one by
2637 one. Each command line must start with a tab, except that the first
2638 command line may be attached to the target-and-dependencies line with a
2639 semicolon in between. Blank lines and lines of just comments may appear
2640 among the command lines; they are ignored.
2642 Users use many different shell programs, but commands in makefiles are
2643 always interpreted by @file{/bin/sh} unless the makefile specifies
2644 otherwise. @xref{Execution, ,Command Execution}.
2646 @cindex comments, in commands
2647 @cindex commands, comments in
2648 @cindex @code{#} (comments), in commands
2649 The shell that is in use determines whether comments can be written on
2650 command lines, and what syntax they use. When the shell is
2651 @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
2652 the line. The @samp{#} does not have to be at the beginning of a line.
2653 Text on a line before a @samp{#} is not part of the comment.
2656 * Echoing:: How to control when commands are echoed.
2657 * Execution:: How commands are executed.
2658 * Parallel:: How commands can be executed in parallel.
2659 * Errors:: What happens after a command execution error.
2660 * Interrupts:: What happens when a command is interrupted.
2661 * Recursion:: Invoking @code{make} from makefiles.
2662 * Sequences:: Defining canned sequences of commands.
2663 * Empty Commands:: Defining useful, do-nothing commands.
2666 @node Echoing, Execution, , Commands
2667 @section Command Echoing
2668 @cindex echoing of commands
2669 @cindex silent operation
2670 @cindex @code{@@} (in commands)
2671 @cindex commands, echoing
2672 @cindex printing of commands
2674 Normally @code{make} prints each command line before it is executed.
2675 We call this @dfn{echoing} because it gives the appearance that you
2676 are typing the commands yourself.
2678 When a line starts with @samp{@@}, the echoing of that line is suppressed.
2679 The @samp{@@} is discarded before the command is passed to the shell.
2680 Typically you would use this for a command whose only effect is to print
2681 something, such as an @code{echo} command to indicate progress through
2685 @@echo About to make distribution files
2689 @cindex @code{--just-print}
2690 @cindex @code{--dry-run}
2691 @cindex @code{--recon}
2692 When @code{make} is given the flag @samp{-n} or @samp{--just-print},
2693 echoing is all that happens, no execution. @xref{Options Summary,
2694 ,Summary of Options}. In this case and only this case, even the
2695 commands starting with @samp{@@} are printed. This flag is useful for
2696 finding out which commands @code{make} thinks are necessary without
2697 actually doing them.
2700 @cindex @code{--silent}
2701 @cindex @code{--quiet}
2703 The @samp{-s} or @samp{--silent}
2704 flag to @code{make} prevents all echoing, as if all commands
2705 started with @samp{@@}. A rule in the makefile for the special target
2706 @code{.SILENT} has the same effect
2707 (@pxref{Special Targets, ,Special Built-in Target Names}).
2708 @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
2710 @node Execution, Parallel, Echoing, Commands
2711 @section Command Execution
2712 @cindex commands, execution
2713 @cindex execution, of commands
2714 @cindex shell command, execution
2715 @vindex SHELL @r{(command execution)}
2717 When it is time to execute commands to update a target, they are executed
2718 by making a new subshell for each line. (In practice, @code{make} may
2719 take shortcuts that do not affect the results.)
2721 @cindex @code{cd} (shell command)
2722 @strong{Please note:} this implies that shell commands such as
2723 @code{cd} that set variables local to each process will not affect the
2724 following command lines. If you want to use @code{cd} to affect the
2725 next command, put the two on a single line with a semicolon between
2726 them. Then @code{make} will consider them a single command and pass
2727 them, together, to a shell which will execute them in sequence. For
2732 cd bar; gobble lose > ../foo
2735 @cindex commands, backslash (@code{\}) in
2736 @cindex commands, quoting newlines in
2737 @cindex backslash (@code{\}), in commands
2738 @cindex @code{\} (backslash), in commands
2739 @cindex quoting newline, in commands
2740 @cindex newline, quoting, in commands
2741 If you would like to split a single shell command into multiple lines of
2742 text, you must use a backslash at the end of all but the last subline.
2743 Such a sequence of lines is combined into a single line, by deleting the
2744 backslash-newline sequences, before passing it to the shell. Thus, the
2745 following is equivalent to the preceding example:
2751 gobble lose > ../foo
2756 The program used as the shell is taken from the variable @code{SHELL}.
2757 By default, the program @file{/bin/sh} is used.
2759 @cindex environment, @code{SHELL} in
2760 Unlike most variables, the variable @code{SHELL} is never set from the
2761 environment. This is because the @code{SHELL} environment variable is
2762 used to specify your personal choice of shell program for interactive
2763 use. It would be very bad for personal choices like this to affect
2764 the functioning of makefiles. @xref{Environment, ,Variables from the
2767 @node Parallel, Errors, Execution, Commands
2768 @section Parallel Execution
2769 @cindex commands, execution in parallel
2770 @cindex parallel execution
2771 @cindex execution, in parallel
2774 @cindex @code{--jobs}
2776 GNU @code{make} knows how to execute several commands at once.
2777 Normally, @code{make} will execute only one command at a time, waiting
2778 for it to finish before executing the next. However, the @samp{-j} or
2779 @samp{--jobs} option tells @code{make} to execute many commands
2780 simultaneously.@refill
2782 If the @samp{-j} option is followed by an integer, this is the number of
2783 commands to execute at once; this is called the number of @dfn{job slots}.
2784 If there is nothing looking like an integer after the @samp{-j} option,
2785 there is no limit on the number of job slots. The default number of job
2786 slots is one, which means serial execution (one thing at a time).
2788 One unpleasant consequence of running several commands simultaneously is
2789 that output from all of the commands comes when the commands send it, so
2790 messages from different commands may be interspersed.
2792 Another problem is that two processes cannot both take input from the
2793 same device; so to make sure that only one command tries to take input
2794 from the terminal at once, @code{make} will invalidate the standard
2795 input streams of all but one running command. This means that
2796 attempting to read from standard input will usually be a fatal error (a
2797 @samp{Broken pipe} signal) for most child processes if there are
2800 @cindex standard input
2802 It is unpredictable which command will have a valid standard input stream
2803 (which will come from the terminal, or wherever you redirect the standard
2804 input of @code{make}). The first command run will always get it first, and
2805 the first command started after that one finishes will get it next, and so
2808 We will change how this aspect of @code{make} works if we find a better
2809 alternative. In the mean time, you should not rely on any command using
2810 standard input at all if you are using the parallel execution feature; but
2811 if you are not using this feature, then standard input works normally in
2814 If a command fails (is killed by a signal or exits with a nonzero
2815 status), and errors are not ignored for that command
2816 (@pxref{Errors, ,Errors in Commands}),
2817 the remaining command lines to remake the same target will not be run.
2818 If a command fails and the @samp{-k} or @samp{--keep-going}
2819 option was not given
2820 (@pxref{Options Summary, ,Summary of Options}),
2821 @code{make} aborts execution. If make
2822 terminates for any reason (including a signal) with child processes
2823 running, it waits for them to finish before actually exiting.@refill
2825 @cindex load average
2826 @cindex limiting jobs based on load
2827 @cindex jobs, limiting based on load
2828 @cindex @code{-l} (load average)
2829 @cindex @code{--max-load}
2830 @cindex @code{--load-average}
2831 When the system is heavily loaded, you will probably want to run fewer jobs
2832 than when it is lightly loaded. You can use the @samp{-l} option to tell
2833 @code{make} to limit the number of jobs to run at once, based on the load
2834 average. The @samp{-l} or @samp{--max-load}
2835 option is followed by a floating-point number. For
2843 will not let @code{make} start more than one job if the load average is
2844 above 2.5. The @samp{-l} option with no following number removes the
2845 load limit, if one was given with a previous @samp{-l} option.@refill
2847 More precisely, when @code{make} goes to start up a job, and it already has
2848 at least one job running, it checks the current load average; if it is not
2849 lower than the limit given with @samp{-l}, @code{make} waits until the load
2850 average goes below that limit, or until all the other jobs finish.
2852 By default, there is no load limit.
2854 @node Errors, Interrupts, Parallel, Commands
2855 @section Errors in Commands
2856 @cindex errors (in commands)
2857 @cindex commands, errors in
2858 @cindex exit status (errors)
2860 After each shell command returns, @code{make} looks at its exit status.
2861 If the command completed successfully, the next command line is executed
2862 in a new shell; after the last command line is finished, the rule is
2865 If there is an error (the exit status is nonzero), @code{make} gives up on
2866 the current rule, and perhaps on all rules.
2868 Sometimes the failure of a certain command does not indicate a problem.
2869 For example, you may use the @code{mkdir} command to ensure that a
2870 directory exists. If the directory already exists, @code{mkdir} will
2871 report an error, but you probably want @code{make} to continue regardless.
2873 @cindex @code{-} (in commands)
2874 To ignore errors in a command line, write a @samp{-} at the beginning of
2875 the line's text (after the initial tab). The @samp{-} is discarded before
2876 the command is passed to the shell for execution.
2886 @cindex @code{rm} (shell command)
2889 This causes @code{rm} to continue even if it is unable to remove a file.
2892 @cindex @code{--ignore-errors}
2894 When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
2895 flag, errors are ignored in
2896 all commands of all rules. A rule in the makefile for the special target
2897 @code{.IGNORE} has the same effect. These ways of ignoring errors are
2898 obsolete because @samp{-} is more flexible.
2900 When errors are to be ignored, because of either a @samp{-} or the
2901 @samp{-i} flag, @code{make} treats an error return just like success,
2902 except that it prints out a message that tells you the status code
2903 the command exited with, and says that the error has been ignored.
2905 When an error happens that @code{make} has not been told to ignore,
2906 it implies that the current target cannot be correctly remade, and neither
2907 can any other that depends on it either directly or indirectly. No further
2908 commands will be executed for these targets, since their preconditions
2909 have not been achieved.
2912 @cindex @code{--keep-going}
2913 Normally @code{make} gives up immediately in this circumstance, returning a
2914 nonzero status. However, if the @samp{-k} or @samp{--keep-going}
2915 flag is specified, @code{make}
2916 continues to consider the other dependencies of the pending targets,
2917 remaking them if necessary, before it gives up and returns nonzero status.
2918 For example, after an error in compiling one object file, @samp{make -k}
2919 will continue compiling other object files even though it already knows
2920 that linking them will be impossible. @xref{Options Summary, ,Summary of Options}.
2922 The usual behavior assumes that your purpose is to get the specified
2923 targets up to date; once @code{make} learns that this is impossible, it
2924 might as well report the failure immediately. The @samp{-k} option says
2925 that the real purpose is to test as many of the changes made in the
2926 program as possible, perhaps to find several independent problems so
2927 that you can correct them all before the next attempt to compile. This
2928 is why Emacs' @code{compile} command passes the @samp{-k} flag by
2930 @cindex Emacs (@code{M-x compile})
2932 @node Interrupts, Recursion, Errors, Commands
2933 @section Interrupting or Killing @code{make}
2936 @cindex deletion of target files
2937 @cindex target, deleting on interrupt
2938 @cindex killing (interruption)
2940 If @code{make} gets a fatal signal while a command is executing, it may
2941 delete the target file that the command was supposed to update. This is
2942 done if the target file's last-modification time has changed since
2943 @code{make} first checked it.
2945 The purpose of deleting the target is to make sure that it is remade from
2946 scratch when @code{make} is next run. Why is this? Suppose you type
2947 @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
2948 object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting
2949 in an incomplete file whose last-modification time is newer than the source
2950 file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal
2951 and deletes this incomplete file. If @code{make} did not do this, the next
2952 invocation of @code{make} would think that @file{foo.o} did not require
2953 updating---resulting in a strange error message from the linker when it
2954 tries to link an object file half of which is missing.
2957 You can prevent the deletion of a target file in this way by making the
2958 special target @code{.PRECIOUS} depend on it. Before remaking a target,
2959 @code{make} checks to see whether it appears on the dependencies of
2960 @code{.PRECIOUS}, and thereby decides whether the target should be deleted
2961 if a signal happens. Some reasons why you might do this are that the
2962 target is updated in some atomic fashion, or exists only to record a
2963 modification-time (its contents do not matter), or must exist at all
2964 times to prevent other sorts of trouble.
2966 @node Recursion, Sequences, Interrupts, Commands
2967 @section Recursive Use of @code{make}
2969 @cindex subdirectories, recursion for
2971 Recursive use of @code{make} means using @code{make} as a command in a
2972 makefile. This technique is useful when you want separate makefiles for
2973 various subsystems that compose a larger system. For example, suppose you
2974 have a subdirectory @file{subdir} which has its own makefile, and you would
2975 like the containing directory's makefile to run @code{make} on the
2976 subdirectory. You can do it by writing this:
2984 or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
2991 @cindex @code{--directory}
2993 You can write recursive @code{make} commands just by copying this example,
2994 but there are many things to know about how they work and why, and about
2995 how the sub-@code{make} relates to the top-level @code{make}.
2998 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
2999 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
3000 * Options/Recursion:: How to communicate options to a sub-@code{make}.
3001 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
3002 helps debug use of recursive @code{make} commands.
3005 @node MAKE Variable, Variables/Recursion, , Recursion
3006 @subsection How the @code{MAKE} Variable Works
3008 @cindex recursion, and @code{MAKE} variable
3010 Recursive @code{make} commands should always use the variable @code{MAKE},
3011 not the explicit command name @samp{make}, as shown here:
3020 The value of this variable is the file name with which @code{make} was
3021 invoked. If this file name was @file{/bin/make}, then the command executed
3022 is @samp{cd subdir; /bin/make}. If you use a special version of
3023 @code{make} to run the top-level makefile, the same special version will be
3024 executed for recursive invocations.
3025 @cindex @code{cd} (shell command)
3027 Also, any arguments that define variable values are added to @code{MAKE},
3028 so the sub-@code{make} gets them too. Thus, if you do @samp{make
3029 CFLAGS=-O}, so that all C compilations will be optimized, the
3030 sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill
3032 @vindex MAKE_COMMAND
3033 @vindex MAKEOVERRIDES
3034 The @code{MAKE} variable actually just refers to two other variables
3035 which contain these special values. In fact, @code{MAKE} is always
3036 defined as @samp{$(MAKE_COMMAND) $(MAKEOVERRIDES)}. The variable
3037 @code{MAKE_COMMAND} is the file name with which @code{make} was invoked
3038 (such as @file{/bin/make}, above). The variable @code{MAKEOVERRIDES}
3039 contains definitions for the variables defined on the command line; in
3040 the above example, its value is @samp{CFLAGS=-O}. If you @emph{do not}
3041 want these variable definitions done in all recursive @code{make}
3042 invocations, you can redefine the @code{MAKEOVERRIDES} variable to
3043 remove them. You do this in any of the normal ways for defining
3044 variables: in a makefile (@pxref{Setting, ,Setting Variables}); on the command
3045 line with an argument like @samp{MAKEOVERRIDES=}
3046 (@pxref{Overriding, ,Overriding Variables}); or with an environment variable
3047 (@pxref{Environment, ,Variables from the Environment}).
3049 As a special feature, using the variable @code{MAKE} in the commands of
3050 a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
3051 (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
3052 Using the @code{MAKE} variable has the same effect as using a @samp{+}
3053 character at the beginning of the command line. @xref{Instead of
3054 Execution, ,Instead of Executing the Commands}.@refill
3056 Consider the command @samp{make -t} in the above example. (The
3057 @samp{-t} option marks targets as up to date without actually running
3058 any commands; see @ref{Instead of Execution}.) Following the usual
3059 definition of @samp{-t}, a @samp{make -t} command in the example would
3060 create a file named @file{subsystem} and do nothing else. What you
3061 really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would
3062 require executing the command, and @samp{-t} says not to execute
3064 @cindex @code{-t}, and recursion
3065 @cindex recursion, and @code{-t}
3066 @cindex @code{--touch}, and recursion
3068 The special feature makes this do what you want: whenever a command
3069 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
3070 @samp{-n} and @samp{-q} do not apply to that line. Command lines
3071 containing @code{MAKE} are executed normally despite the presence of a
3072 flag that causes most commands not to be run. The usual
3073 @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
3074 (@pxref{Options/Recursion, ,Communicating Options to a
3075 Sub-@code{make}}), so your request to touch the files, or print the
3076 commands, is propagated to the subsystem.@refill
3078 @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
3079 @subsection Communicating Variables to a Sub-@code{make}
3080 @cindex sub-@code{make}
3081 @cindex environment, and recursion
3082 @cindex exporting variables
3083 @cindex variables, environment
3084 @cindex variables, exporting
3085 @cindex recursion, and environment
3086 @cindex recursion, and variables
3088 Variable values of the top-level @code{make} can be passed to the
3089 sub-@code{make} through the environment by explicit request. These
3090 variables are defined in the sub-@code{make} as defaults, but do not
3091 override what is specified in the sub-@code{make}'s makefile unless
3092 you use the @samp{-e} switch
3093 (@pxref{Options Summary, ,Summary of Options}).@refill
3095 To pass down, or @dfn{export}, a variable, @code{make} adds the variable
3096 and its value to the environment for running each command. The
3097 sub-@code{make}, in turn, uses the environment to initialize its table
3098 of variable values. @xref{Environment, ,Variables from the
3101 Except by explicit request, @code{make} exports a variable only if it
3102 is either defined in the environment initially or set on the command
3103 line, and if its name consists only of letters, numbers, and underscores.
3104 Some shells cannot cope with environment variable names consisting of
3105 characters other than letters, numbers, and underscores.
3107 The special variables @code{SHELL} and @code{MAKEFLAGS} are always
3108 exported (unless you unexport them).
3109 @code{MAKEFILES} is exported if you set it to anything.
3111 Variables are @emph{not} normally passed down if they were created by
3112 default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
3113 Implicit Rules}). The sub-@code{make} will define these for
3117 If you want to export specific variables to a sub-@code{make}, use the
3118 @code{export} directive, like this:
3121 export @var{variable} @dots{}
3126 If you want to @emph{prevent} a variable from being exported, use the
3127 @code{unexport} directive, like this:
3130 unexport @var{variable} @dots{}
3134 As a convenience, you can define a variable and export it at the same
3138 export @var{variable} = value
3142 has the same result as:
3145 @var{variable} = value
3146 export @var{variable}
3153 export @var{variable} := value
3157 has the same result as:
3160 @var{variable} := value
3161 export @var{variable}
3167 export @var{variable} += value
3174 @var{variable} += value
3175 export @var{variable}
3179 @xref{Appending, ,Appending More Text to Variables}.
3181 You may notice that the @code{export} and @code{unexport} directives
3182 work in @code{make} in the same way they work in the shell, @code{sh}.
3184 If you want all variables to be exported by default, you can use
3185 @code{export} by itself:
3192 This tells @code{make} that variables which are not explicitly mentioned
3193 in an @code{export} or @code{unexport} directive should be exported.
3194 Any variable given in an @code{unexport} directive will still @emph{not}
3195 be exported. If you use @code{export} by itself to export variables by
3196 default, variables whose names contain characters other than
3197 alphanumerics and underscores will not be exported unless specifically
3198 mentioned in an @code{export} directive.@refill
3200 @findex .EXPORT_ALL_VARIABLES
3201 The behavior elicited by an @code{export} directive by itself was the
3202 default in older versions of GNU @code{make}. If your makefiles depend
3203 on this behavior and you want to be compatible with old versions of
3204 @code{make}, you can write a rule for the special target
3205 @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
3206 This will be ignored by old @code{make}s, while the @code{export}
3207 directive will cause a syntax error.@refill
3208 @cindex compatibility in exporting
3210 Likewise, you can use @code{unexport} by itself to tell @code{make}
3211 @emph{not} to export variables by default. Since this is the default
3212 behavior, you would only need to do this if @code{export} had been used
3213 by itself earlier (in an included makefile, perhaps). You
3214 @strong{cannot} use @code{export} and @code{unexport} by themselves to
3215 have variables exported for some commands and not for others. The last
3216 @code{export} or @code{unexport} directive that appears by itself
3217 determines the behavior for the entire run of @code{make}.@refill
3220 @cindex recursion, level of
3221 As a special feature, the variable @code{MAKELEVEL} is changed when it
3222 is passed down from level to level. This variable's value is a string
3223 which is the depth of the level as a decimal number. The value is
3224 @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
3225 @samp{2} for a sub-sub-@code{make}, and so on. The incrementation
3226 happens when @code{make} sets up the environment for a command.@refill
3228 The main use of @code{MAKELEVEL} is to test it in a conditional
3229 directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
3230 way you can write a makefile that behaves one way if run recursively and
3231 another way if run directly by you.@refill
3234 You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
3235 commands to use additional makefiles. The value of @code{MAKEFILES} is
3236 a whitespace-separated list of file names. This variable, if defined in
3237 the outer-level makefile, is passed down through the environment; then
3238 it serves as a list of extra makefiles for the sub-@code{make} to read
3239 before the usual or specified ones. @xref{MAKEFILES Variable, ,The
3240 Variable @code{MAKEFILES}}.@refill
3242 @node Options/Recursion, -w Option, Variables/Recursion, Recursion
3243 @subsection Communicating Options to a Sub-@code{make}
3244 @cindex options, and recursion
3245 @cindex recursion, and options
3248 Flags such as @samp{-s} and @samp{-k} are passed automatically to the
3249 sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
3250 set up automatically by @code{make} to contain the flag letters that
3251 @code{make} received. Thus, if you do @w{@samp{make -ks}} then
3252 @code{MAKEFLAGS} gets the value @samp{ks}.@refill
3254 As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
3255 in its environment. In response, it takes the flags from that value and
3256 processes them as if they had been given as arguments.
3257 @xref{Options Summary, ,Summary of Options}.
3259 @cindex @code{-C}, and recursion
3260 @cindex @code{-f}, and recursion
3261 @cindex @code{-I}, and recursion
3262 @cindex @code{-o}, and recursion
3263 @cindex @code{-W}, and recursion
3264 @cindex @code{--directory}, and recursion
3265 @cindex @code{--file}, and recursion
3266 @cindex @code{--include-dir}, and recursion
3267 @cindex @code{--old-file}, and recursion
3268 @cindex @code{--assume-old}, and recursion
3269 @cindex @code{--assume-new}, and recursion
3270 @cindex @code{--new-file}, and recursion
3271 @cindex recursion, and @code{-C}
3272 @cindex recursion, and @code{-f}
3273 @cindex recursion, and @code{-I}
3274 @cindex recursion, and @code{-o}
3275 @cindex recursion, and @code{-W}
3276 The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W}
3277 are not put into @code{MAKEFLAGS}; these options are not passed down.@refill
3279 @cindex @code{-j}, and recursion
3280 @cindex @code{--jobs}, and recursion
3281 @cindex recursion, and @code{-j}
3282 @cindex job slots, and recursion
3283 The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
3284 If you set it to some numeric value, @samp{-j 1} is always put into
3285 @code{MAKEFLAGS} instead of the value you specified. This is because if
3286 the @w{@samp{-j}} option were passed down to sub-@code{make}s, you would
3287 get many more jobs running in parallel than you asked for. If you give
3288 @samp{-j} with no numeric argument, meaning to run as many jobs as
3289 possible in parallel, this is passed down, since multiple infinities are
3290 no more than one.@refill
3292 If you do not want to pass the other flags down, you must change the
3293 value of @code{MAKEFLAGS}, like this:
3305 cd subdir; $(MAKE) MAKEFLAGS=
3309 A similar variable @code{MFLAGS} exists also, for historical compatibility.
3310 It has the same value as @code{MAKEFLAGS} except that it always begins with
3311 a hyphen unless it is empty (@code{MAKEFLAGS} begins with a hyphen only when
3312 it begins with an option that has no single-letter version, such as
3313 @samp{--warn-undefined-variables}). @code{MFLAGS} was traditionally used
3314 explicitly in the recursive @code{make} command, like this:
3318 cd subdir; $(MAKE) $(MFLAGS)
3322 but now @code{MAKEFLAGS} makes this usage redundant. If you want your
3323 makefiles to be compatible with old @code{make} programs, use this
3324 technique; it will work fine with more modern @code{make} versions too.
3326 @cindex setting options from environment
3327 @cindex options, setting from environment
3328 @cindex setting options in makefiles
3329 @cindex options, setting in makefiles
3330 The @code{MAKEFLAGS} variable can also be useful if you want to have
3331 certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
3332 Options}), set each time you run @code{make}. You simply put a value for
3333 @code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in
3334 a makefile, to specify additional flags that should also be in effect for
3335 that makefile. (Note that you cannot use @code{MFLAGS} this way. That
3336 variable is set only for compatibility; @code{make} does not interpret a
3337 value you set for it in any way.)
3339 When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
3340 environment or from a makefile), it first prepends a hyphen if the value
3341 does not already begin with one. Then it chops the value into words
3342 separated by blanks, and parses these words as if they were options given
3343 on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
3344 @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
3345 is no error for an invalid option).
3347 If you do put @code{MAKEFLAGS} in your environment, you should be sure not
3348 to include any options that will drastically affect the actions of
3349 @code{make} and undermine the purpose of makefiles and of @code{make}
3350 itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
3351 put in one of these variables, could have disastrous consequences and would
3352 certainly have at least surprising and probably annoying effects.@refill
3354 @node -w Option, , Options/Recursion, Recursion
3355 @subsection The @samp{--print-directory} Option
3356 @cindex directories, printing them
3357 @cindex printing directories
3358 @cindex recursion, and printing directories
3360 If you use several levels of recursive @code{make} invocations, the
3361 @samp{-w} or @w{@samp{--print-directory}} option can make the output a
3362 lot easier to understand by showing each directory as @code{make}
3363 starts processing it and as @code{make} finishes processing it. For
3364 example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
3365 @code{make} will print a line of the form:@refill
3368 make: Entering directory `/u/gnu/make'.
3372 before doing anything else, and a line of the form:
3375 make: Leaving directory `/u/gnu/make'.
3379 when processing is completed.
3381 @cindex @code{-C}, and @code{-w}
3382 @cindex @code{--directory}, and @code{--print-directory}
3383 @cindex recursion, and @code{-w}
3384 @cindex @code{-w}, and @code{-C}
3385 @cindex @code{-w}, and recursion
3386 @cindex @code{--print-directory}, and @code{--directory}
3387 @cindex @code{--print-directory}, and recursion
3388 @cindex @code{--no-print-directory}
3389 @cindex @code{--print-directory}, disabling
3390 @cindex @code{-w}, disabling
3391 Normally, you do not need to specify this option because @samp{make}
3392 does it for you: @samp{-w} is turned on automatically when you use the
3393 @samp{-C} option, and in sub-@code{make}s. @code{make} will not
3394 automatically turn on @samp{-w} if you also use @samp{-s}, which says to
3395 be silent, or if you use @samp{--no-print-directory} to explicitly
3398 @node Sequences, Empty Commands, Recursion, Commands
3399 @section Defining Canned Command Sequences
3400 @cindex sequences of commands
3401 @cindex commands, sequences of
3403 When the same sequence of commands is useful in making various targets, you
3404 can define it as a canned sequence with the @code{define} directive, and
3405 refer to the canned sequence from the rules for those targets. The canned
3406 sequence is actually a variable, so the name must not conflict with other
3409 Here is an example of defining a canned sequence of commands:
3413 yacc $(firstword $^)
3420 Here @code{run-yacc} is the name of the variable being defined;
3421 @code{endef} marks the end of the definition; the lines in between are the
3422 commands. The @code{define} directive does not expand variable references
3423 and function calls in the canned sequence; the @samp{$} characters,
3424 parentheses, variable names, and so on, all become part of the value of the
3425 variable you are defining.
3426 @xref{Defining, ,Defining Variables Verbatim},
3427 for a complete explanation of @code{define}.
3429 The first command in this example runs Yacc on the first dependency of
3430 whichever rule uses the canned sequence. The output file from Yacc is
3431 always named @file{y.tab.c}. The second command moves the output to the
3432 rule's target file name.
3434 To use the canned sequence, substitute the variable into the commands of a
3435 rule. You can substitute it like any other variable
3436 (@pxref{Reference, ,Basics of Variable References}).
3437 Because variables defined by @code{define} are recursively expanded
3438 variables, all the variable references you wrote inside the @code{define}
3439 are expanded now. For example:
3447 @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
3448 @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
3450 This is a realistic example, but this particular one is not needed in
3451 practice because @code{make} has an implicit rule to figure out these
3452 commands based on the file names involved
3453 (@pxref{Implicit Rules, ,Using Implicit Rules}).
3455 @cindex @@, and @code{define}
3456 @cindex -, and @code{define}
3457 @cindex +, and @code{define}
3458 In command execution, each line of a canned sequence is treated just as
3459 if the line appeared on its own in the rule, preceded by a tab. In
3460 particular, @code{make} invokes a separate subshell for each line. You
3461 can use the special prefix characters that affect command lines
3462 (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
3463 @xref{Commands, ,Writing the Commands in Rules}.
3464 For example, using this canned sequence:
3468 @@echo "frobnicating target $@@"
3469 frob-step-1 $< -o $@@-step-1
3470 frob-step-2 $@@-step-1 -o $@@
3475 @code{make} will not echo the first line, the @code{echo} command.
3476 But it @emph{will} echo the following two command lines.
3478 On the other hand, prefix characters on the command line that refers to
3479 a canned sequence apply to every line in the sequence. So the rule:
3487 does not echo @emph{any} commands.
3488 (@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.)
3490 @node Empty Commands, , Sequences, Commands
3491 @section Using Empty Commands
3492 @cindex empty commands
3493 @cindex commands, empty
3495 It is sometimes useful to define commands which do nothing. This is done
3496 simply by giving a command that consists of nothing but whitespace. For
3504 defines an empty command string for @file{target}. You could also use a
3505 line beginning with a tab character to define an empty command string,
3506 but this would be confusing because such a line looks empty.
3508 @findex .DEFAULT@r{, and empty commands}
3509 You may be wondering why you would want to define a command string that
3510 does nothing. The only reason this is useful is to prevent a target
3511 from getting implicit commands (from implicit rules or the
3512 @code{.DEFAULT} special target; @pxref{Implicit Rules} and
3513 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
3515 You may be inclined to define empty command strings for targets that are
3516 not actual files, but only exist so that their dependencies can be
3517 remade. However, this is not the best way to do that, because the
3518 dependencies may not be remade properly if the target file actually does exist.
3519 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
3521 @node Using Variables, Conditionals, Commands, Top
3522 @chapter How to Use Variables
3525 @cindex recursive variable expansion
3526 @cindex simple variable expansion
3528 A @dfn{variable} is a name defined in a makefile to represent a string
3529 of text, called the variable's @dfn{value}. These values are
3530 substituted by explicit request into targets, dependencies, commands,
3531 and other parts of the makefile. (In some other versions of @code{make},
3532 variables are called @dfn{macros}.)
3535 Variables and functions in all parts of a makefile are expanded when
3536 read, except for the shell commands in rules, the right-hand sides of
3537 variable definitions using @samp{=}, and the bodies of variable
3538 definitions using the @code{define} directive.@refill
3540 Variables can represent lists of file names, options to pass to compilers,
3541 programs to run, directories to look in for source files, directories to
3542 write output in, or anything else you can imagine.
3544 A variable name may be any sequence of characters not containing @samp{:},
3545 @samp{#}, @samp{=}, or leading or trailing whitespace. However,
3546 variable names containing characters other than letters, numbers, and
3547 underscores should be avoided, as they may be given special meanings in the
3548 future, and with some shells they cannot be passed through the environment to a
3550 (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
3552 Variable names are case-sensitive. The names @samp{foo}, @samp{FOO},
3553 and @samp{Foo} all refer to different variables.
3555 It is traditional to use upper case letters in variable names, but we
3556 recommend using lower case letters for variable names that serve internal
3557 purposes in the makefile, and reserving upper case for parameters that
3558 control implicit rules or for parameters that the user should override with
3559 command options (@pxref{Overriding, ,Overriding Variables}).
3561 A few variables have names that are a single punctuation character or
3562 just a few characters. These are the @dfn{automatic variables}, and
3563 they have particular specialized uses. @xref{Automatic, ,Automatic Variables}.
3566 * Reference:: How to use the value of a variable.
3567 * Flavors:: Variables come in two flavors.
3568 * Advanced:: Advanced features for referencing a variable.
3569 * Values:: All the ways variables get their values.
3570 * Setting:: How to set a variable in the makefile.
3571 * Appending:: How to append more text to the old value
3573 * Override Directive:: How to set a variable in the makefile even if
3574 the user has set it with a command argument.
3575 * Defining:: An alternate way to set a variable
3576 to a verbatim string.
3577 * Environment:: Variable values can come from the environment.
3578 * Automatic:: Some special variables have predefined
3579 meanings for use with implicit rules.
3582 @node Reference, Flavors, , Using Variables
3583 @section Basics of Variable References
3584 @cindex variables, how to reference
3585 @cindex reference to variables
3586 @cindex @code{$}, in variable reference
3587 @cindex dollar sign (@code{$}), in variable reference
3589 To substitute a variable's value, write a dollar sign followed by the name
3590 of the variable in parentheses or braces: either @samp{$(foo)} or
3591 @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This
3592 special significance of @samp{$} is why you must write @samp{$$} to have
3593 the effect of a single dollar sign in a file name or command.
3595 Variable references can be used in any context: targets, dependencies,
3596 commands, most directives, and new variable values. Here is an
3597 example of a common case, where a variable holds the names of all the
3598 object files in a program:
3602 objects = program.o foo.o utils.o
3603 program : $(objects)
3604 cc -o program $(objects)
3610 Variable references work by strict textual substitution. Thus, the rule
3615 prog.o : prog.$(foo)
3616 $(foo)$(foo) -$(foo) prog.$(foo)
3621 could be used to compile a C program @file{prog.c}. Since spaces before
3622 the variable value are ignored in variable assignments, the value of
3623 @code{foo} is precisely @samp{c}. (Don't actually write your makefiles
3626 A dollar sign followed by a character other than a dollar sign,
3627 open-parenthesis or open-brace treats that single character as the
3628 variable name. Thus, you could reference the variable @code{x} with
3629 @samp{$x}. However, this practice is strongly discouraged, except in
3630 the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}).
3632 @node Flavors, Advanced, Reference, Using Variables
3633 @section The Two Flavors of Variables
3634 @cindex flavors of variables
3635 @cindex recursive variable expansion
3636 @cindex variables, flavors
3637 @cindex recursively expanded variables
3638 @cindex variables, recursively expanded
3640 There are two ways that a variable in GNU @code{make} can have a value;
3641 we call them the two @dfn{flavors} of variables. The two flavors are
3642 distinguished in how they are defined and in what they do when expanded.
3645 The first flavor of variable is a @dfn{recursively expanded} variable.
3646 Variables of this sort are defined by lines using @samp{=}
3647 (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
3648 (@pxref{Defining, ,Defining Variables Verbatim}). The value you specify
3649 is installed verbatim; if it contains references to other variables,
3650 these references are expanded whenever this variable is substituted (in
3651 the course of expanding some other string). When this happens, it is
3652 called @dfn{recursive expansion}.@refill
3665 will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
3666 expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
3668 This flavor of variable is the only sort supported by other versions of
3669 @code{make}. It has its advantages and its disadvantages. An advantage
3670 (most would say) is that:
3673 CFLAGS = $(include_dirs) -O
3674 include_dirs = -Ifoo -Ibar
3678 will do what was intended: when @samp{CFLAGS} is expanded in a command,
3679 it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you
3680 cannot append something on the end of a variable, as in
3683 CFLAGS = $(CFLAGS) -O
3687 because it will cause an infinite loop in the variable expansion.
3688 (Actually @code{make} detects the infinite loop and reports an error.)
3689 @cindex loops in variable expansion
3690 @cindex variables, loops in expansion
3692 Another disadvantage is that any functions
3693 (@pxref{Functions, ,Functions for Transforming Text})
3694 referenced in the definition will be executed every time the variable is
3695 expanded. This makes @code{make} run slower; worse, it causes the
3696 @code{wildcard} and @code{shell} functions to give unpredictable results
3697 because you cannot easily control when they are called, or even how many
3700 To avoid all the problems and inconveniences of recursively expanded
3701 variables, there is another flavor: simply expanded variables.
3703 @cindex simply expanded variables
3704 @cindex variables, simply expanded
3706 @dfn{Simply expanded variables} are defined by lines using @samp{:=}
3707 (@pxref{Setting, ,Setting Variables}).
3708 The value of a simply expanded variable is scanned
3709 once and for all, expanding any references to other variables and
3710 functions, when the variable is defined. The actual value of the simply
3711 expanded variable is the result of expanding the text that you write.
3712 It does not contain any references to other variables; it contains their
3713 values @emph{as of the time this variable was defined}. Therefore,
3729 When a simply expanded variable is referenced, its value is substituted
3732 Here is a somewhat more complicated example, illustrating the use of
3733 @samp{:=} in conjunction with the @code{shell} function.
3734 (@xref{Shell Function, , The @code{shell} Function}.) This example
3735 also shows use of the variable @code{MAKELEVEL}, which is changed
3736 when it is passed down from level to level.
3737 (@xref{Variables/Recursion, , Communicating Variables to a
3738 Sub-@code{make}}, for information about @code{MAKELEVEL}.)
3744 ifeq (0,$@{MAKELEVEL@})
3745 cur-dir := $(shell pwd)
3746 whoami := $(shell whoami)
3747 host-type := $(shell arch)
3748 MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
3754 An advantage of this use of @samp{:=} is that a typical
3755 `descend into a directory' command then looks like this:
3760 $@{MAKE@} cur-dir=$@{cur-dir@}/$@@ -C $@@ all
3764 Simply expanded variables generally make complicated makefile programming
3765 more predictable because they work like variables in most programming
3766 languages. They allow you to redefine a variable using its own value (or
3767 its value processed in some way by one of the expansion functions) and to
3768 use the expansion functions much more efficiently
3769 (@pxref{Functions, ,Functions for Transforming Text}).
3771 @cindex spaces, in variable values
3772 @cindex whitespace, in variable values
3773 @cindex variables, spaces in values
3774 You can also use them to introduce controlled leading whitespace into
3775 variable values. Leading whitespace characters are discarded from your
3776 input before substitution of variable references and function calls;
3777 this means you can include leading spaces in a variable value by
3778 protecting them with variable references, like this:
3782 space := $(nullstring) # end of the line
3786 Here the value of the variable @code{space} is precisely one space. The
3787 comment @w{@samp{# end of the line}} is included here just for clarity.
3788 Since trailing space characters are @emph{not} stripped from variable
3789 values, just a space at the end of the line would have the same effect
3790 (but be rather hard to read). If you put whitespace at the end of a
3791 variable value, it is a good idea to put a comment like that at the end
3792 of the line to make your intent clear. Conversely, if you do @emph{not}
3793 want any whitespace characters at the end of your variable value, you
3794 must remember not to put a random comment on the end of the line after
3795 some whitespace, such as this:
3798 dir := /foo/bar # directory to put the frobs in
3802 Here the value of the variable @code{dir} is @w{@samp{/foo/bar }}
3803 (with four trailing spaces), which was probably not the intention.
3804 (Imagine something like @w{@samp{$(dir)/file}} with this definition!)
3806 @node Advanced, Values, Flavors, Using Variables
3807 @section Advanced Features for Reference to Variables
3808 @cindex reference to variables
3810 This section describes some advanced features you can use to reference
3811 variables in more flexible ways.
3814 * Substitution Refs:: Referencing a variable with
3815 substitutions on the value.
3816 * Computed Names:: Computing the name of the variable to refer to.
3819 @node Substitution Refs, Computed Names, , Advanced
3820 @subsection Substitution References
3821 @cindex modified variable reference
3822 @cindex substitution variable reference
3823 @cindex variables, modified reference
3824 @cindex variables, substitution reference
3826 @cindex variables, substituting suffix in
3827 @cindex suffix, substituting in variables
3828 A @dfn{substitution reference} substitutes the value of a variable with
3829 alterations that you specify. It has the form
3830 @samp{$(@var{var}:@var{a}=@var{b})} (or
3831 @samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
3832 of the variable @var{var}, replace every @var{a} at the end of a word with
3833 @var{b} in that value, and substitute the resulting string.
3835 When we say ``at the end of a word'', we mean that @var{a} must appear
3836 either followed by whitespace or at the end of the value in order to be
3837 replaced; other occurrences of @var{a} in the value are unaltered. For
3846 sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}.
3848 A substitution reference is actually an abbreviation for use of the
3849 @code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide
3850 substitution references as well as @code{patsubst} for compatibility with
3851 other implementations of @code{make}.
3854 Another type of substitution reference lets you use the full power of
3855 the @code{patsubst} function. It has the same form
3856 @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
3857 @var{a} must contain a single @samp{%} character. This case is
3858 equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
3859 @xref{Text Functions, ,Functions for String Substitution and Analysis},
3860 for a description of the @code{patsubst} function.@refill
3864 @exdent For example:
3867 bar := $(foo:%.o=%.c)
3872 sets @samp{bar} to @samp{a.c b.c c.c}.
3874 @node Computed Names, , Substitution Refs, Advanced
3875 @subsection Computed Variable Names
3876 @cindex nested variable reference
3877 @cindex computed variable name
3878 @cindex variables, computed names
3879 @cindex variables, nested references
3880 @cindex variables, @samp{$} in name
3881 @cindex @code{$}, in variable name
3882 @cindex dollar sign (@code{$}), in variable name
3884 Computed variable names are a complicated concept needed only for
3885 sophisticated makefile programming. For most purposes you need not
3886 consider them, except to know that making a variable with a dollar sign
3887 in its name might have strange results. However, if you are the type
3888 that wants to understand everything, or you are actually interested in
3889 what they do, read on.
3891 Variables may be referenced inside the name of a variable. This is
3892 called a @dfn{computed variable name} or a @dfn{nested variable
3893 reference}. For example,
3902 defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
3903 to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
3904 to @samp{z}. Here the name of the variable to reference is not stated
3905 explicitly; it is computed by expansion of @samp{$(x)}. The reference
3906 @samp{$(x)} here is nested within the outer variable reference.
3908 The previous example shows two levels of nesting, but any number of levels
3909 is possible. For example, here are three levels:
3919 Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
3920 expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
3921 @samp{$(z)}, which becomes @samp{u}.
3923 References to recursively-expanded variables within a variable name are
3924 reexpanded in the usual fashion. For example:
3934 defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
3935 which becomes @samp{$(z)} which becomes @samp{Hello}.
3937 Nested variable references can also contain modified references and
3938 function invocations (@pxref{Functions, ,Functions for Transforming Text}),
3939 just like any other reference.
3940 For example, using the @code{subst} function
3941 (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
3947 y = $(subst 1,2,$(x))
3954 eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone
3955 would ever want to write a nested reference as convoluted as this one, but
3956 it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
3957 @samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from
3958 @code{x} and changes it by substitution to @samp{variable2}, so that the
3959 entire string becomes @samp{$(variable2)}, a simple variable reference
3960 whose value is @samp{Hello}.@refill
3962 A computed variable name need not consist entirely of a single variable
3963 reference. It can contain several variable references, as well as some
3964 invariant text. For example,
3973 a_files := filea fileb
3974 1_files := file1 file2
3978 ifeq "$(use_a)" "yes"
3986 ifeq "$(use_dirs)" "yes"
3992 dirs := $($(a1)_$(df))
3997 will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
3998 @code{a_files} or @code{1_files} depending on the settings of @code{use_a}
3999 and @code{use_dirs}.@refill
4001 Computed variable names can also be used in substitution references:
4005 a_objects := a.o b.o c.o
4006 1_objects := 1.o 2.o 3.o
4008 sources := $($(a1)_objects:.o=.c)
4013 defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
4014 depending on the value of @code{a1}.
4016 The only restriction on this sort of use of nested variable references
4017 is that they cannot specify part of the name of a function to be called.
4018 This is because the test for a recognized function name is done before
4019 the expansion of nested references. For example,
4035 foo := $($(func) $(bar))
4040 attempts to give @samp{foo} the value of the variable @samp{sort a d b g
4041 q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
4042 as the argument to either the @code{sort} or the @code{strip} function.
4043 This restriction could be removed in the future if that change is shown
4046 You can also use computed variable names in the left-hand side of a
4047 variable assignment, or in a @code{define} directive, as in:
4051 $(dir)_sources := $(wildcard $(dir)/*.c)
4053 lpr $($(dir)_sources)
4058 This example defines the variables @samp{dir}, @samp{foo_sources}, and
4061 Note that @dfn{nested variable references} are quite different from
4062 @dfn{recursively expanded variables}
4063 (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
4064 used together in complex ways when doing makefile programming.@refill
4066 @node Values, Setting, Advanced, Using Variables
4067 @section How Variables Get Their Values
4068 @cindex variables, how they get their values
4069 @cindex value, how a variable gets it
4071 Variables can get values in several different ways:
4075 You can specify an overriding value when you run @code{make}.
4076 @xref{Overriding, ,Overriding Variables}.
4079 You can specify a value in the makefile, either
4080 with an assignment (@pxref{Setting, ,Setting Variables}) or with a
4081 verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
4084 Variables in the environment become @code{make} variables.
4085 @xref{Environment, ,Variables from the Environment}.
4088 Several @dfn{automatic} variables are given new values for each rule.
4089 Each of these has a single conventional use.
4090 @xref{Automatic, ,Automatic Variables}.
4093 Several variables have constant initial values.
4094 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
4097 @node Setting, Appending, Values, Using Variables
4098 @section Setting Variables
4099 @cindex setting variables
4100 @cindex variables, setting
4104 To set a variable from the makefile, write a line starting with the
4105 variable name followed by @samp{=} or @samp{:=}. Whatever follows the
4106 @samp{=} or @samp{:=} on the line becomes the value. For example,
4109 objects = main.o foo.o bar.o utils.o
4113 defines a variable named @code{objects}. Whitespace around the variable
4114 name and immediately after the @samp{=} is ignored.
4116 Variables defined with @samp{=} are @dfn{recursively expanded} variables.
4117 Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
4118 definitions can contain variable references which will be expanded before
4119 the definition is made. @xref{Flavors, ,The Two Flavors of Variables}.
4121 The variable name may contain function and variable references, which
4122 are expanded when the line is read to find the actual variable name to use.
4124 There is no limit on the length of the value of a variable except the
4125 amount of swapping space on the computer. When a variable definition is
4126 long, it is a good idea to break it into several lines by inserting
4127 backslash-newline at convenient places in the definition. This will not
4128 affect the functioning of @code{make}, but it will make the makefile easier
4131 Most variable names are considered to have the empty string as a value if
4132 you have never set them. Several variables have built-in initial values
4133 that are not empty, but you can set them in the usual ways
4134 (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
4135 Several special variables are set
4136 automatically to a new value for each rule; these are called the
4137 @dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}).
4139 @node Appending, Override Directive, Setting, Using Variables
4140 @section Appending More Text to Variables
4142 @cindex appending to variables
4143 @cindex variables, appending to
4145 Often it is useful to add more text to the value of a variable already defined.
4146 You do this with a line containing @samp{+=}, like this:
4149 objects += another.o
4153 This takes the value of the variable @code{objects}, and adds the text
4154 @samp{another.o} to it (preceded by a single space). Thus:
4157 objects = main.o foo.o bar.o utils.o
4158 objects += another.o
4162 sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
4164 Using @samp{+=} is similar to:
4167 objects = main.o foo.o bar.o utils.o
4168 objects := $(objects) another.o
4172 but differs in ways that become important when you use more complex values.
4174 When the variable in question has not been defined before, @samp{+=}
4175 acts just like normal @samp{=}: it defines a recursively-expanded
4176 variable. However, when there @emph{is} a previous definition, exactly
4177 what @samp{+=} does depends on what flavor of variable you defined
4178 originally. @xref{Flavors, ,The Two Flavors of Variables}, for an
4179 explanation of the two flavors of variables.
4181 When you add to a variable's value with @samp{+=}, @code{make} acts
4182 essentially as if you had included the extra text in the initial
4183 definition of the variable. If you defined it first with @samp{:=},
4184 making it a simply-expanded variable, @samp{+=} adds to that
4185 simply-expanded definition, and expands the new text before appending it
4186 to the old value just as @samp{:=} does
4187 (@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
4196 is exactly equivalent to:
4201 variable := $(variable) more
4204 On the other hand, when you use @samp{+=} with a variable that you defined
4205 first to be recursively-expanded using plain @samp{=}, @code{make} does
4206 something a bit different. Recall that when you define a
4207 recursively-expanded variable, @code{make} does not expand the value you set
4208 for variable and function references immediately. Instead it stores the text
4209 verbatim, and saves these variable and function references to be expanded
4210 later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
4211 of Variables}). When you use @samp{+=} on a recursively-expanded variable,
4212 it is this unexpanded text to which @code{make} appends the new text you
4223 is roughly equivalent to:
4228 variable = $(temp) more
4233 except that of course it never defines a variable called @code{temp}.
4234 The importance of this comes when the variable's old value contains
4235 variable references. Take this common example:
4238 CFLAGS = $(includes) -O
4240 CFLAGS += -pg # enable profiling
4244 The first line defines the @code{CFLAGS} variable with a reference to another
4245 variable, @code{includes}. (@code{CFLAGS} is used by the rules for C
4246 compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
4247 Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
4248 variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
4249 @code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes}
4250 need not be defined yet for its value to take effect. It only has to be
4251 defined before any reference to @code{CFLAGS}. If we tried to append to the
4252 value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
4255 CFLAGS := $(CFLAGS) -pg # enable profiling
4259 This is pretty close, but not quite what we want. Using @samp{:=}
4260 redefines @code{CFLAGS} as a simply-expanded variable; this means
4261 @code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
4262 variable. If @code{includes} is not yet defined, we get @w{@samp{ -O
4263 -pg}}, and a later definition of @code{includes} will have no effect.
4264 Conversely, by using @samp{+=} we set @code{CFLAGS} to the
4265 @emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve
4266 the reference to @code{includes}, so if that variable gets defined at
4267 any later point, a reference like @samp{$(CFLAGS)} still uses its
4270 @node Override Directive, Defining, Appending, Using Variables
4271 @section The @code{override} Directive
4273 @cindex overriding with @code{override}
4274 @cindex variables, overriding
4276 If a variable has been set with a command argument
4277 (@pxref{Overriding, ,Overriding Variables}),
4278 then ordinary assignments in the makefile are ignored. If you want to set
4279 the variable in the makefile even though it was set with a command
4280 argument, you can use an @code{override} directive, which is a line that
4281 looks like this:@refill
4284 override @var{variable} = @var{value}
4291 override @var{variable} := @var{value}
4294 To append more text to a variable defined on the command line, use:
4297 override @var{variable} += @var{more text}
4301 @xref{Appending, ,Appending More Text to Variables}.
4303 The @code{override} directive was not invented for escalation in the war
4304 between makefiles and command arguments. It was invented so you can alter
4305 and add to values that the user specifies with command arguments.
4307 For example, suppose you always want the @samp{-g} switch when you run the
4308 C compiler, but you would like to allow the user to specify the other
4309 switches with a command argument just as usual. You could use this
4310 @code{override} directive:
4313 override CFLAGS += -g
4316 You can also use @code{override} directives with @code{define} directives.
4317 This is done as you might expect:
4327 See the next section for information about @code{define}.
4330 @xref{Defining, ,Defining Variables Verbatim}.
4333 @node Defining, Environment, Override Directive, Using Variables
4334 @section Defining Variables Verbatim
4337 @cindex verbatim variable definition
4338 @cindex defining variables verbatim
4339 @cindex variables, defining verbatim
4341 Another way to set the value of a variable is to use the @code{define}
4342 directive. This directive has an unusual syntax which allows newline
4343 characters to be included in the value, which is convenient for defining
4344 canned sequences of commands
4345 (@pxref{Sequences, ,Defining Canned Command Sequences}).
4347 The @code{define} directive is followed on the same line by the name of the
4348 variable and nothing more. The value to give the variable appears on the
4349 following lines. The end of the value is marked by a line containing just
4350 the word @code{endef}. Aside from this difference in syntax, @code{define}
4351 works just like @samp{=}: it creates a recursively-expanded variable
4352 (@pxref{Flavors, ,The Two Flavors of Variables}).
4353 The variable name may contain function and variable references, which
4354 are expanded when the directive is read to find the actual variable name
4364 The value in an ordinary assignment cannot contain a newline; but the
4365 newlines that separate the lines of the value in a @code{define} become
4366 part of the variable's value (except for the final newline which precedes
4367 the @code{endef} and is not considered part of the value).@refill
4370 The previous example is functionally equivalent to this:
4373 two-lines = echo foo; echo $(bar)
4377 since two commands separated by semicolon behave much like two separate
4378 shell commands. However, note that using two separate lines means
4379 @code{make} will invoke the shell twice, running an independent subshell
4380 for each line. @xref{Execution, ,Command Execution}.
4382 If you want variable definitions made with @code{define} to take
4383 precedence over command-line variable definitions, you can use the
4384 @code{override} directive together with @code{define}:
4387 override define two-lines
4394 @xref{Override Directive, ,The @code{override} Directive}.
4396 @node Environment, , Defining, Using Variables
4397 @section Variables from the Environment
4399 @cindex variables, environment
4401 Variables in @code{make} can come from the environment in which
4402 @code{make} is run. Every environment variable that @code{make} sees when
4403 it starts up is transformed into a @code{make} variable with the same name
4404 and value. But an explicit assignment in the makefile, or with a command
4405 argument, overrides the environment. (If the @samp{-e} flag is specified,
4406 then values from the environment override assignments in the makefile.
4407 @xref{Options Summary, ,Summary of Options}.
4408 But this is not recommended practice.)
4410 Thus, by setting the variable @code{CFLAGS} in your environment, you can
4411 cause all C compilations in most makefiles to use the compiler switches you
4412 prefer. This is safe for variables with standard or conventional meanings
4413 because you know that no makefile will use them for other things. (But
4414 this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
4415 and therefore are not affected by the value in the environment.)
4417 When @code{make} is invoked recursively, variables defined in the
4418 outer invocation can be passed to inner invocations through the
4419 environment (@pxref{Recursion, ,Recursive Use of @code{make}}). By
4420 default, only variables that came from the environment or the command
4421 line are passed to recursive invocations. You can use the
4422 @code{export} directive to pass other variables.
4423 @xref{Variables/Recursion, , Communicating Variables to a
4424 Sub-@code{make}}, for full details.
4426 Other use of variables from the environment is not recommended. It is not
4427 wise for makefiles to depend for their functioning on environment variables
4428 set up outside their control, since this would cause different users to get
4429 different results from the same makefile. This is against the whole
4430 purpose of most makefiles.
4432 Such problems would be especially likely with the variable @code{SHELL},
4433 which is normally present in the environment to specify the user's choice
4434 of interactive shell. It would be very undesirable for this choice to
4435 affect @code{make}. So @code{make} ignores the environment value of
4436 @code{SHELL}.@refill
4438 @node Conditionals, Functions, Using Variables, Top
4439 @chapter Conditional Parts of Makefiles
4441 @cindex conditionals
4442 A @dfn{conditional} causes part of a makefile to be obeyed or ignored
4443 depending on the values of variables. Conditionals can compare the
4444 value of one variable to another, or the value of a variable to
4445 a constant string. Conditionals control what @code{make} actually
4446 ``sees'' in the makefile, so they @emph{cannot} be used to control shell
4447 commands at the time of execution.@refill
4450 * Conditional Example:: Example of a conditional
4451 * Conditional Syntax:: The syntax of conditionals.
4452 * Testing Flags:: Conditionals that test flags.
4455 @node Conditional Example, Conditional Syntax, , Conditionals
4456 @section Example of a Conditional
4458 The following example of a conditional tells @code{make} to use one set
4459 of libraries if the @code{CC} variable is @samp{gcc}, and a different
4460 set of libraries otherwise. It works by controlling which of two
4461 command lines will be used as the command for a rule. The result is
4462 that @samp{CC=gcc} as an argument to @code{make} changes not only which
4463 compiler is used but also which libraries are linked.
4466 libs_for_gcc = -lgnu
4471 $(CC) -o foo $(objects) $(libs_for_gcc)
4473 $(CC) -o foo $(objects) $(normal_libs)
4477 This conditional uses three directives: one @code{ifeq}, one @code{else}
4478 and one @code{endif}.
4480 The @code{ifeq} directive begins the conditional, and specifies the
4481 condition. It contains two arguments, separated by a comma and surrounded
4482 by parentheses. Variable substitution is performed on both arguments and
4483 then they are compared. The lines of the makefile following the
4484 @code{ifeq} are obeyed if the two arguments match; otherwise they are
4487 The @code{else} directive causes the following lines to be obeyed if the
4488 previous conditional failed. In the example above, this means that the
4489 second alternative linking command is used whenever the first alternative
4490 is not used. It is optional to have an @code{else} in a conditional.
4492 The @code{endif} directive ends the conditional. Every conditional must
4493 end with an @code{endif}. Unconditional makefile text follows.
4495 As this example illustrates, conditionals work at the textual level:
4496 the lines of the conditional are treated as part of the makefile, or
4497 ignored, according to the condition. This is why the larger syntactic
4498 units of the makefile, such as rules, may cross the beginning or the
4499 end of the conditional.
4501 When the variable @code{CC} has the value @samp{gcc}, the above example has
4506 $(CC) -o foo $(objects) $(libs_for_gcc)
4510 When the variable @code{CC} has any other value, the effect is this:
4514 $(CC) -o foo $(objects) $(normal_libs)
4517 Equivalent results can be obtained in another way by conditionalizing a
4518 variable assignment and then using the variable unconditionally:
4521 libs_for_gcc = -lgnu
4525 libs=$(libs_for_gcc)
4531 $(CC) -o foo $(objects) $(libs)
4534 @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
4535 @section Syntax of Conditionals
4543 The syntax of a simple conditional with no @code{else} is as follows:
4546 @var{conditional-directive}
4552 The @var{text-if-true} may be any lines of text, to be considered as part
4553 of the makefile if the condition is true. If the condition is false, no
4554 text is used instead.
4556 The syntax of a complex conditional is as follows:
4559 @var{conditional-directive}
4567 If the condition is true, @var{text-if-true} is used; otherwise,
4568 @var{text-if-false} is used instead. The @var{text-if-false} can be any
4569 number of lines of text.
4571 The syntax of the @var{conditional-directive} is the same whether the
4572 conditional is simple or complex. There are four different directives that
4573 test different conditions. Here is a table of them:
4576 @item ifeq (@var{arg1}, @var{arg2})
4577 @itemx ifeq '@var{arg1}' '@var{arg2}'
4578 @itemx ifeq "@var{arg1}" "@var{arg2}"
4579 @itemx ifeq "@var{arg1}" '@var{arg2}'
4580 @itemx ifeq '@var{arg1}' "@var{arg2}"
4581 Expand all variable references in @var{arg1} and @var{arg2} and
4582 compare them. If they are identical, the @var{text-if-true} is
4583 effective; otherwise, the @var{text-if-false}, if any, is effective.
4585 Often you want to test if a variable has a non-empty value. When the
4586 value results from complex expansions of variables and functions,
4587 expansions you would consider empty may actually contain whitespace
4588 characters and thus are not seen as empty. However, you can use the
4589 @code{strip} function (@pxref{Text Functions}) to avoid interpreting
4590 whitespace as a non-empty value. For example:
4594 ifeq ($(strip $(foo)),)
4601 will evaluate @var{text-if-empty} even if the expansion of
4602 @code{$(foo)} contains whitespace characters.
4604 @item ifneq (@var{arg1}, @var{arg2})
4605 @itemx ifneq '@var{arg1}' '@var{arg2}'
4606 @itemx ifneq "@var{arg1}" "@var{arg2}"
4607 @itemx ifneq "@var{arg1}" '@var{arg2}'
4608 @itemx ifneq '@var{arg1}' "@var{arg2}"
4609 Expand all variable references in @var{arg1} and @var{arg2} and
4610 compare them. If they are different, the @var{text-if-true} is
4611 effective; otherwise, the @var{text-if-false}, if any, is effective.
4613 @item ifdef @var{variable-name}
4614 If the variable @var{variable-name} has a non-empty value, the
4615 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4616 if any, is effective. Variables that have never been defined have an
4619 Note that @code{ifdef} only tests whether a variable has a value. It
4620 does not expand the variable to see if that value is nonempty.
4621 Consequently, tests using @code{ifdef} return true for all definitions
4622 except those like @code{foo =}. To test for an empty value, use
4623 @w{@code{ifeq ($(foo),)}}. For example,
4636 sets @samp{frobozz} to @samp{yes}, while:
4648 sets @samp{frobozz} to @samp{no}.
4650 @item ifndef @var{variable-name}
4651 If the variable @var{variable-name} has an empty value, the
4652 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4653 if any, is effective.
4656 Extra spaces are allowed and ignored at the beginning of the conditional
4657 directive line, but a tab is not allowed. (If the line begins with a tab,
4658 it will be considered a command for a rule.) Aside from this, extra spaces
4659 or tabs may be inserted with no effect anywhere except within the directive
4660 name or within an argument. A comment starting with @samp{#} may appear at
4661 the end of the line.
4663 The other two directives that play a part in a conditional are @code{else}
4664 and @code{endif}. Each of these directives is written as one word, with no
4665 arguments. Extra spaces are allowed and ignored at the beginning of the
4666 line, and spaces or tabs at the end. A comment starting with @samp{#} may
4667 appear at the end of the line.
4669 Conditionals affect which lines of the makefile @code{make} uses. If
4670 the condition is true, @code{make} reads the lines of the
4671 @var{text-if-true} as part of the makefile; if the condition is false,
4672 @code{make} ignores those lines completely. It follows that syntactic
4673 units of the makefile, such as rules, may safely be split across the
4674 beginning or the end of the conditional.@refill
4676 @code{make} evaluates conditionals when it reads a makefile.
4677 Consequently, you cannot use automatic variables in the tests of
4678 conditionals because they are not defined until commands are run
4679 (@pxref{Automatic, , Automatic Variables}).
4681 To prevent intolerable confusion, it is not permitted to start a
4682 conditional in one makefile and end it in another. However, you may
4683 write an @code{include} directive within a conditional, provided you do
4684 not attempt to terminate the conditional inside the included file.
4686 @node Testing Flags, , Conditional Syntax, Conditionals
4687 @section Conditionals that Test Flags
4689 You can write a conditional that tests @code{make} command flags such as
4690 @samp{-t} by using the variable @code{MAKEFLAGS} together with the
4691 @code{findstring} function
4692 (@pxref{Text Functions, , Functions for String Substitution and Analysis}).
4693 This is useful when @code{touch} is not enough to make a file appear up
4696 The @code{findstring} function determines whether one string appears as a
4697 substring of another. If you want to test for the @samp{-t} flag,
4698 use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
4701 For example, here is how to arrange to use @samp{ranlib -t} to finish
4702 marking an archive file up to date:
4706 ifneq (,$(findstring t,$(MAKEFLAGS)))
4708 +ranlib -t archive.a
4715 The @samp{+} prefix marks those command lines as ``recursive'' so
4716 that they will be executed despite use of the @samp{-t} flag.
4717 @xref{Recursion, ,Recursive Use of @code{make}}.
4719 @node Functions, Running, Conditionals, Top
4720 @chapter Functions for Transforming Text
4723 @dfn{Functions} allow you to do text processing in the makefile to compute
4724 the files to operate on or the commands to use. You use a function in a
4725 @dfn{function call}, where you give the name of the function and some text
4726 (the @dfn{arguments}) for the function to operate on. The result of the
4727 function's processing is substituted into the makefile at the point of the
4728 call, just as a variable might be substituted.
4731 * Syntax of Functions:: How to write a function call.
4732 * Text Functions:: General-purpose text manipulation functions.
4733 * Filename Functions:: Functions for manipulating file names.
4734 * Foreach Function:: Repeat some text with controlled variation.
4735 * Origin Function:: Find where a variable got its value.
4736 * Shell Function:: Substitute the output of a shell command.
4739 @node Syntax of Functions, Text Functions, , Functions
4740 @section Function Call Syntax
4741 @cindex @code{$}, in function call
4742 @cindex dollar sign (@code{$}), in function call
4743 @cindex arguments of functions
4744 @cindex functions, syntax of
4746 A function call resembles a variable reference. It looks like this:
4749 $(@var{function} @var{arguments})
4756 $@{@var{function} @var{arguments}@}
4759 Here @var{function} is a function name; one of a short list of names that
4760 are part of @code{make}. There is no provision for defining new functions.
4762 The @var{arguments} are the arguments of the function. They are
4763 separated from the function name by one or more spaces or tabs, and if
4764 there is more than one argument, then they are separated by commas.
4765 Such whitespace and commas are not part of an argument's value. The
4766 delimiters which you use to surround the function call, whether
4767 parentheses or braces, can appear in an argument only in matching pairs;
4768 the other kind of delimiters may appear singly. If the arguments
4769 themselves contain other function calls or variable references, it is
4770 wisest to use the same kind of delimiters for all the references; write
4771 @w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This
4772 is because it is clearer, and because only one type of delimiter is
4773 matched to find the end of the reference.
4775 The text written for each argument is processed by substitution of
4776 variables and function calls to produce the argument value, which
4777 is the text on which the function acts. The substitution is done in the
4778 order in which the arguments appear.
4780 Commas and unmatched parentheses or braces cannot appear in the text of an
4781 argument as written; leading spaces cannot appear in the text of the first
4782 argument as written. These characters can be put into the argument value
4783 by variable substitution. First define variables @code{comma} and
4784 @code{space} whose values are isolated comma and space characters, then
4785 substitute these variables where such characters are wanted, like this:
4791 space:= $(empty) $(empty)
4793 bar:= $(subst $(space),$(comma),$(foo))
4794 # @r{bar is now `a,b,c'.}
4799 Here the @code{subst} function replaces each space with a comma, through
4800 the value of @code{foo}, and substitutes the result.
4802 @node Text Functions, Filename Functions, Syntax of Functions, Functions
4803 @section Functions for String Substitution and Analysis
4804 @cindex functions, for text
4806 Here are some functions that operate on strings:
4809 @item $(subst @var{from},@var{to},@var{text})
4811 Performs a textual replacement on the text @var{text}: each occurrence
4812 of @var{from} is replaced by @var{to}. The result is substituted for
4813 the function call. For example,
4816 $(subst ee,EE,feet on the street)
4819 substitutes the string @samp{fEEt on the strEEt}.
4821 @item $(patsubst @var{pattern},@var{replacement},@var{text})
4823 Finds whitespace-separated words in @var{text} that match
4824 @var{pattern} and replaces them with @var{replacement}. Here
4825 @var{pattern} may contain a @samp{%} which acts as a wildcard,
4826 matching any number of any characters within a word. If
4827 @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
4828 by the text that matched the @samp{%} in @var{pattern}.@refill
4830 @cindex @code{%}, quoting in @code{patsubst}
4831 @cindex @code{%}, quoting with @code{\} (backslash)
4832 @cindex @code{\} (backslash), to quote @code{%}
4833 @cindex backslash (@code{\}), to quote @code{%}
4834 @cindex quoting @code{%}, in @code{patsubst}
4835 @samp{%} characters in @code{patsubst} function invocations can be
4836 quoted with preceding backslashes (@samp{\}). Backslashes that would
4837 otherwise quote @samp{%} characters can be quoted with more backslashes.
4838 Backslashes that quote @samp{%} characters or other backslashes are
4839 removed from the pattern before it is compared file names or has a stem
4840 substituted into it. Backslashes that are not in danger of quoting
4841 @samp{%} characters go unmolested. For example, the pattern
4842 @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
4843 operative @samp{%} character, and @samp{pattern\\} following it. The
4844 final two backslashes are left alone because they cannot affect any
4845 @samp{%} character.@refill
4847 Whitespace between words is folded into single space characters;
4848 leading and trailing whitespace is discarded.
4853 $(patsubst %.c,%.o,x.c.c bar.c)
4857 produces the value @samp{x.c.o bar.o}.
4859 Substitution references (@pxref{Substitution Refs, ,Substitution
4860 References}) are a simpler way to get the effect of the @code{patsubst}
4864 $(@var{var}:@var{pattern}=@var{replacement})
4871 $(patsubst @var{pattern},@var{replacement},$(@var{var}))
4874 The second shorthand simplifies one of the most common uses of
4875 @code{patsubst}: replacing the suffix at the end of file names.
4878 $(@var{var}:@var{suffix}=@var{replacement})
4885 $(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
4889 For example, you might have a list of object files:
4892 objects = foo.o bar.o baz.o
4896 To get the list of corresponding source files, you could simply write:
4903 instead of using the general form:
4906 $(patsubst %.o,%.c,$(objects))
4909 @item $(strip @var{string})
4910 @cindex stripping whitespace
4911 @cindex whitespace, stripping
4912 @cindex spaces, stripping
4914 Removes leading and trailing whitespace from @var{string} and replaces
4915 each internal sequence of one or more whitespace characters with a
4916 single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}.
4918 The function @code{strip} can be very useful when used in conjunction
4919 with conditionals. When comparing something with the empty string
4920 @samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
4921 just whitespace to match the empty string (@pxref{Conditionals}).
4923 Thus, the following may fail to have the desired results:
4927 ifneq "$(needs_made)" ""
4930 all:;@@echo 'Nothing to make!'
4935 Replacing the variable reference @w{@samp{$(needs_made)}} with the
4936 function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
4937 directive would make it more robust.@refill
4939 @item $(findstring @var{find},@var{in})
4941 @cindex searching for strings
4942 @cindex finding strings
4943 @cindex strings, searching for
4944 Searches @var{in} for an occurrence of @var{find}. If it occurs, the
4945 value is @var{find}; otherwise, the value is empty. You can use this
4946 function in a conditional to test for the presence of a specific
4947 substring in a given string. Thus, the two examples,
4950 $(findstring a,a b c)
4955 produce the values @samp{a} and @samp{} (the empty string),
4956 respectively. @xref{Testing Flags}, for a practical application of
4957 @code{findstring}.@refill
4961 @cindex filtering words
4962 @cindex words, filtering
4963 @item $(filter @var{pattern}@dots{},@var{text})
4964 Removes all whitespace-separated words in @var{text} that do
4965 @emph{not} match any of the @var{pattern} words, returning only
4966 matching words. The patterns are written using @samp{%}, just like
4967 the patterns used in the @code{patsubst} function above.@refill
4969 The @code{filter} function can be used to separate out different types
4970 of strings (such as file names) in a variable. For example:
4973 sources := foo.c bar.c baz.s ugh.h
4975 cc $(filter %.c %.s,$(sources)) -o foo
4979 says that @file{foo} depends of @file{foo.c}, @file{bar.c},
4980 @file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
4981 @file{baz.s} should be specified in the command to the
4984 @item $(filter-out @var{pattern}@dots{},@var{text})
4986 @cindex filtering out words
4987 @cindex words, filtering out
4988 Removes all whitespace-separated words in @var{text} that @emph{do}
4989 match the @var{pattern} words, returning only the words that @emph{do
4990 not} match. This is the exact opposite of the @code{filter}
4997 objects=main1.o foo.o main2.o bar.o
4998 mains=main1.o main2.o
5003 the following generates a list which contains all the object files not
5007 $(filter-out $(mains),$(objects))
5012 @cindex sorting words
5013 @item $(sort @var{list})
5014 Sorts the words of @var{list} in lexical order, removing duplicate
5015 words. The output is a list of words separated by single spaces.
5019 $(sort foo bar lose)
5023 returns the value @samp{bar foo lose}.
5025 @cindex removing duplicate words
5026 @cindex duplicate words, removing
5027 @cindex words, removing duplicates
5028 Incidentally, since @code{sort} removes duplicate words, you can use
5029 it for this purpose even if you don't care about the sort order.
5032 Here is a realistic example of the use of @code{subst} and
5033 @code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable
5034 to specify a list of directories that @code{make} should search for
5036 (@pxref{General Search, , @code{VPATH} Search Path for All Dependencies}).
5037 This example shows how to
5038 tell the C compiler to search for header files in the same list of
5041 The value of @code{VPATH} is a list of directories separated by colons,
5042 such as @samp{src:../headers}. First, the @code{subst} function is used to
5043 change the colons to spaces:
5046 $(subst :, ,$(VPATH))
5050 This produces @samp{src ../headers}. Then @code{patsubst} is used to turn
5051 each directory name into a @samp{-I} flag. These can be added to the
5052 value of the variable @code{CFLAGS}, which is passed automatically to the C
5053 compiler, like this:
5056 override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
5060 The effect is to append the text @samp{-Isrc -I../headers} to the
5061 previously given value of @code{CFLAGS}. The @code{override} directive is
5062 used so that the new value is assigned even if the previous value of
5063 @code{CFLAGS} was specified with a command argument (@pxref{Override
5064 Directive, , The @code{override} Directive}).
5066 @node Filename Functions, Foreach Function, Text Functions, Functions
5067 @section Functions for File Names
5068 @cindex functions, for file names
5069 @cindex file name functions
5071 Several of the built-in expansion functions relate specifically to
5072 taking apart file names or lists of file names.
5074 Each of the following functions performs a specific transformation on a
5075 file name. The argument of the function is regarded as a series of file
5076 names, separated by whitespace. (Leading and trailing whitespace is
5077 ignored.) Each file name in the series is transformed in the same way and
5078 the results are concatenated with single spaces between them.
5081 @item $(dir @var{names}@dots{})
5083 @cindex directory part
5084 @cindex file name, directory part
5085 Extracts the directory-part of each file name in @var{names}. The
5086 directory-part of the file name is everything up through (and
5087 including) the last slash in it. If the file name contains no slash,
5088 the directory part is the string @samp{./}. For example,
5091 $(dir src/foo.c hacks)
5095 produces the result @samp{src/ ./}.
5097 @item $(notdir @var{names}@dots{})
5099 @cindex file name, nondirectory part
5100 @cindex nondirectory part
5101 Extracts all but the directory-part of each file name in @var{names}.
5102 If the file name contains no slash, it is left unchanged. Otherwise,
5103 everything through the last slash is removed from it.
5105 A file name that ends with a slash becomes an empty string. This is
5106 unfortunate, because it means that the result does not always have the
5107 same number of whitespace-separated file names as the argument had;
5108 but we do not see any other valid alternative.
5113 $(notdir src/foo.c hacks)
5117 produces the result @samp{foo.c hacks}.
5119 @item $(suffix @var{names}@dots{})
5121 @cindex suffix, function to find
5122 @cindex file name suffix
5123 Extracts the suffix of each file name in @var{names}. If the file name
5124 contains a period, the suffix is everything starting with the last
5125 period. Otherwise, the suffix is the empty string. This frequently
5126 means that the result will be empty when @var{names} is not, and if
5127 @var{names} contains multiple file names, the result may contain fewer
5133 $(suffix src/foo.c hacks)
5137 produces the result @samp{.c}.
5139 @item $(basename @var{names}@dots{})
5142 @cindex file name, basename of
5143 Extracts all but the suffix of each file name in @var{names}. If the
5144 file name contains a period, the basename is everything starting up to
5145 (and not including) the last period. Otherwise, the basename is the
5146 entire file name. For example,
5149 $(basename src/foo.c hacks)
5153 produces the result @samp{src/foo hacks}.
5155 @c plural convention with dots (be consistent)
5156 @item $(addsuffix @var{suffix},@var{names}@dots{})
5158 @cindex suffix, adding
5159 @cindex file name suffix, adding
5160 The argument @var{names} is regarded as a series of names, separated
5161 by whitespace; @var{suffix} is used as a unit. The value of
5162 @var{suffix} is appended to the end of each individual name and the
5163 resulting larger names are concatenated with single spaces between
5167 $(addsuffix .c,foo bar)
5171 produces the result @samp{foo.c bar.c}.
5173 @item $(addprefix @var{prefix},@var{names}@dots{})
5175 @cindex prefix, adding
5176 @cindex file name prefix, adding
5177 The argument @var{names} is regarded as a series of names, separated
5178 by whitespace; @var{prefix} is used as a unit. The value of
5179 @var{prefix} is prepended to the front of each individual name and the
5180 resulting larger names are concatenated with single spaces between
5184 $(addprefix src/,foo bar)
5188 produces the result @samp{src/foo src/bar}.
5190 @item $(join @var{list1},@var{list2})
5192 @cindex joining lists of words
5193 @cindex words, joining lists
5194 Concatenates the two arguments word by word: the two first words (one
5195 from each argument) concatenated form the first word of the result, the
5196 two second words form the second word of the result, and so on. So the
5197 @var{n}th word of the result comes from the @var{n}th word of each
5198 argument. If one argument has more words that the other, the extra
5199 words are copied unchanged into the result.
5201 For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
5203 Whitespace between the words in the lists is not preserved; it is
5204 replaced with a single space.
5206 This function can merge the results of the @code{dir} and
5207 @code{notdir} functions, to produce the original list of files which
5208 was given to those two functions.@refill
5210 @item $(word @var{n},@var{text})
5212 @cindex words, selecting
5213 @cindex selecting words
5214 Returns the @var{n}th word of @var{text}. The legitimate values of
5215 @var{n} start from 1. If @var{n} is bigger than the number of words
5216 in @var{text}, the value is empty. For example,
5219 $(word 2, foo bar baz)
5225 @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
5226 @item $(words @var{text})
5228 @cindex words, finding number
5229 Returns the number of words in @var{text}.
5230 Thus, the last word of @var{text} is
5231 @w{@code{$(word $(words @var{text}),@var{text})}}.@refill
5233 @item $(firstword @var{names}@dots{})
5235 @cindex words, extracting first
5236 The argument @var{names} is regarded as a series of names, separated
5237 by whitespace. The value is the first name in the series. The rest
5238 of the names are ignored.
5243 $(firstword foo bar)
5247 produces the result @samp{foo}. Although @code{$(firstword
5248 @var{text})} is the same as @code{$(word 1,@var{text})}, the
5249 @code{firstword} function is retained for its simplicity.@refill
5251 @item $(wildcard @var{pattern})
5253 @cindex wildcard, function
5254 The argument @var{pattern} is a file name pattern, typically containing
5255 wildcard characters (as in shell file name patterns). The result of
5256 @code{wildcard} is a space-separated list of the names of existing files
5257 that match the pattern.
5258 @xref{Wildcards, ,Using Wildcard Characters in File Names}.
5261 @node Foreach Function, Origin Function, Filename Functions, Functions
5262 @section The @code{foreach} Function
5264 @cindex words, iterating over
5266 The @code{foreach} function is very different from other functions. It
5267 causes one piece of text to be used repeatedly, each time with a different
5268 substitution performed on it. It resembles the @code{for} command in the
5269 shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
5271 The syntax of the @code{foreach} function is:
5274 $(foreach @var{var},@var{list},@var{text})
5278 The first two arguments, @var{var} and @var{list}, are expanded before
5279 anything else is done; note that the last argument, @var{text}, is
5280 @strong{not} expanded at the same time. Then for each word of the expanded
5281 value of @var{list}, the variable named by the expanded value of @var{var}
5282 is set to that word, and @var{text} is expanded. Presumably @var{text}
5283 contains references to that variable, so its expansion will be different
5286 The result is that @var{text} is expanded as many times as there are
5287 whitespace-separated words in @var{list}. The multiple expansions of
5288 @var{text} are concatenated, with spaces between them, to make the result
5291 This simple example sets the variable @samp{files} to the list of all files
5292 in the directories in the list @samp{dirs}:
5296 files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
5299 Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition
5300 finds the value @samp{a} for @code{dir}, so it produces the same result
5301 as @samp{$(wildcard a/*)}; the second repetition produces the result
5302 of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
5304 This example has the same result (except for setting @samp{dirs}) as
5305 the following example:
5308 files := $(wildcard a/* b/* c/* d/*)
5311 When @var{text} is complicated, you can improve readability by giving it
5312 a name, with an additional variable:
5315 find_files = $(wildcard $(dir)/*)
5317 files := $(foreach dir,$(dirs),$(find_files))
5321 Here we use the variable @code{find_files} this way. We use plain @samp{=}
5322 to define a recursively-expanding variable, so that its value contains an
5323 actual function call to be reexpanded under the control of @code{foreach};
5324 a simply-expanded variable would not do, since @code{wildcard} would be
5325 called only once at the time of defining @code{find_files}.
5327 The @code{foreach} function has no permanent effect on the variable
5328 @var{var}; its value and flavor after the @code{foreach} function call are
5329 the same as they were beforehand. The other values which are taken from
5330 @var{list} are in effect only temporarily, during the execution of
5331 @code{foreach}. The variable @var{var} is a simply-expanded variable
5332 during the execution of @code{foreach}. If @var{var} was undefined
5333 before the @code{foreach} function call, it is undefined after the call.
5334 @xref{Flavors, ,The Two Flavors of Variables}.@refill
5336 You must take care when using complex variable expressions that result in
5337 variable names because many strange things are valid variable names, but
5338 are probably not what you intended. For example,
5341 files := $(foreach Es escrito en espanol!,b c ch,$(find_files))
5345 might be useful if the value of @code{find_files} references the variable
5346 whose name is @samp{Es escrito en espanol!} (es un nombre bastante largo,
5347 no?), but it is more likely to be a mistake.
5349 @node Origin Function, Shell Function, Foreach Function, Functions
5350 @section The @code{origin} Function
5352 @cindex variables, origin of
5353 @cindex origin of variable
5355 The @code{origin} function is unlike most other functions in that it does
5356 not operate on the values of variables; it tells you something @emph{about}
5357 a variable. Specifically, it tells you where it came from.
5359 The syntax of the @code{origin} function is:
5362 $(origin @var{variable})
5365 Note that @var{variable} is the @emph{name} of a variable to inquire about;
5366 not a @emph{reference} to that variable. Therefore you would not normally
5367 use a @samp{$} or parentheses when writing it. (You can, however, use a
5368 variable reference in the name if you want the name not to be a constant.)
5370 The result of this function is a string telling you how the variable
5371 @var{variable} was defined:
5376 if @var{variable} was never defined.
5380 if @var{variable} has a default definition, as is usual with @code{CC}
5381 and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
5382 Note that if you have redefined a default variable, the @code{origin}
5383 function will return the origin of the later definition.
5387 if @var{variable} was defined as an environment variable and the
5388 @samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}).
5390 @item environment override
5392 if @var{variable} was defined as an environment variable and the
5393 @w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary,
5394 ,Summary of Options}).@refill
5398 if @var{variable} was defined in a makefile.
5402 if @var{variable} was defined on the command line.
5406 if @var{variable} was defined with an @code{override} directive in a
5407 makefile (@pxref{Override Directive, ,The @code{override} Directive}).
5411 if @var{variable} is an automatic variable defined for the
5412 execution of the commands for each rule
5413 (@pxref{Automatic, , Automatic Variables}).
5416 This information is primarily useful (other than for your curiosity) to
5417 determine if you want to believe the value of a variable. For example,
5418 suppose you have a makefile @file{foo} that includes another makefile
5419 @file{bar}. You want a variable @code{bletch} to be defined in @file{bar}
5420 if you run the command @w{@samp{make -f bar}}, even if the environment contains
5421 a definition of @code{bletch}. However, if @file{foo} defined
5422 @code{bletch} before including @file{bar}, you do not want to override that
5423 definition. This could be done by using an @code{override} directive in
5424 @file{foo}, giving that definition precedence over the later definition in
5425 @file{bar}; unfortunately, the @code{override} directive would also
5426 override any command line definitions. So, @file{bar} could
5432 ifeq "$(origin bletch)" "environment"
5433 bletch = barf, gag, etc.
5440 If @code{bletch} has been defined from the environment, this will redefine
5443 If you want to override a previous definition of @code{bletch} if it came
5444 from the environment, even under @samp{-e}, you could instead write:
5448 ifneq "$(findstring environment,$(origin bletch))" ""
5449 bletch = barf, gag, etc.
5454 Here the redefinition takes place if @samp{$(origin bletch)} returns either
5455 @samp{environment} or @samp{environment override}.
5456 @xref{Text Functions, , Functions for String Substitution and Analysis}.
5458 @node Shell Function, , Origin Function, Functions
5459 @section The @code{shell} Function
5461 @cindex commands, expansion
5463 @cindex shell command, function for
5465 The @code{shell} function is unlike any other function except the
5466 @code{wildcard} function
5467 (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
5468 communicates with the world outside of @code{make}.
5470 The @code{shell} function performs the same function that backquotes
5471 (@samp{`}) perform in most shells: it does @dfn{command expansion}. This
5472 means that it takes an argument that is a shell command and returns the
5473 output of the command. The only processing @code{make} does on the result,
5474 before substituting it into the surrounding text, is to convert newlines to
5477 The commands run by calls to the @code{shell} function are run when the
5478 function calls are expanded. In most cases, this is when the makefile is
5479 read in. The exception is that function calls in the commands of the rules
5480 are expanded when the commands are run, and this applies to @code{shell}
5481 function calls like all others.
5483 Here are some examples of the use of the @code{shell} function:
5486 contents := $(shell cat foo)
5490 sets @code{contents} to the contents of the file @file{foo}, with a space
5491 (rather than a newline) separating each line.
5494 files := $(shell echo *.c)
5498 sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is
5499 using a very strange shell, this has the same result as
5500 @w{@samp{$(wildcard *.c)}}.@refill
5502 @node Running, Implicit Rules, Functions, Top
5503 @chapter How to Run @code{make}
5505 A makefile that says how to recompile a program can be used in more
5506 than one way. The simplest use is to recompile every file that is out
5507 of date. Usually, makefiles are written so that if you run
5508 @code{make} with no arguments, it does just that.
5510 But you might want to update only some of the files; you might want to use
5511 a different compiler or different compiler options; you might want just to
5512 find out which files are out of date without changing them.
5514 By giving arguments when you run @code{make}, you can do any of these
5515 things and many others.
5517 The exit status of @code{make} is always one of three values:
5520 The exit status is zero if @code{make} is successful.
5522 The exit status is two if @code{make} encounters any errors.
5523 It will print messages describing the particular errors.
5525 The exit status is one if you use the @samp{-q} flag and @code{make}
5526 determines that some target is not already up to date.
5527 @xref{Instead of Execution, ,Instead of Executing the Commands}.
5531 * Makefile Arguments:: How to specify which makefile to use.
5532 * Goals:: How to use goal arguments to specify which
5533 parts of the makefile to use.
5534 * Instead of Execution:: How to use mode flags to specify what
5535 kind of thing to do with the commands
5536 in the makefile other than simply
5538 * Avoiding Compilation:: How to avoid recompiling certain files.
5539 * Overriding:: How to override a variable to specify
5540 an alternate compiler and other things.
5541 * Testing:: How to proceed past some errors, to
5543 * Options Summary:: Summary of Options
5546 @node Makefile Arguments, Goals, , Running
5547 @section Arguments to Specify the Makefile
5548 @cindex @code{--file}
5549 @cindex @code{--makefile}
5552 The way to specify the name of the makefile is with the @samp{-f} or
5553 @samp{--file} option (@samp{--makefile} also works). For example,
5554 @samp{-f altmake} says to use the file @file{altmake} as the makefile.
5556 If you use the @samp{-f} flag several times and follow each @samp{-f}
5557 with an argument, all the specified files are used jointly as
5560 If you do not use the @samp{-f} or @samp{--file} flag, the default is
5561 to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
5562 that order, and use the first of these three which exists or can be made
5563 (@pxref{Makefiles, ,Writing Makefiles}).@refill
5565 @node Goals, Instead of Execution, Makefile Arguments, Running
5566 @section Arguments to Specify the Goals
5567 @cindex goal, how to specify
5569 The @dfn{goals} are the targets that @code{make} should strive ultimately
5570 to update. Other targets are updated as well if they appear as
5571 dependencies of goals, or dependencies of dependencies of goals, etc.
5573 By default, the goal is the first target in the makefile (not counting
5574 targets that start with a period). Therefore, makefiles are usually
5575 written so that the first target is for compiling the entire program or
5576 programs they describe.
5578 You can specify a different goal or goals with arguments to @code{make}.
5579 Use the name of the goal as an argument. If you specify several goals,
5580 @code{make} processes each of them in turn, in the order you name them.
5582 Any target in the makefile may be specified as a goal (unless it
5583 starts with @samp{-} or contains an @samp{=}, in which case it will be
5584 parsed as a switch or variable definition, respectively). Even
5585 targets not in the makefile may be specified, if @code{make} can find
5586 implicit rules that say how to make them.
5588 One use of specifying a goal is if you want to compile only a part of
5589 the program, or only one of several programs. Specify as a goal each
5590 file that you wish to remake. For example, consider a directory containing
5591 several programs, with a makefile that starts like this:
5595 all: size nm ld ar as
5598 If you are working on the program @code{size}, you might want to say
5599 @w{@samp{make size}} so that only the files of that program are recompiled.
5601 Another use of specifying a goal is to make files that are not normally
5602 made. For example, there may be a file of debugging output, or a
5603 version of the program that is compiled specially for testing, which has
5604 a rule in the makefile but is not a dependency of the default goal.
5606 Another use of specifying a goal is to run the commands associated with
5607 a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
5608 Targets, ,Empty Target Files to Record Events}). Many makefiles contain
5609 a phony target named @file{clean} which deletes everything except source
5610 files. Naturally, this is done only if you request it explicitly with
5611 @w{@samp{make clean}}. Following is a list of typical phony and empty
5612 target names. @xref{Standard Targets}, for a detailed list of all the
5613 standard target names which GNU software packages use.
5617 @cindex @code{all} @r{(standard target)}
5618 Make all the top-level targets the makefile knows about.
5621 @cindex @code{clean} @r{(standard target)}
5622 Delete all files that are normally created by running @code{make}.
5625 @cindex @code{mostlyclean} @r{(standard target)}
5626 Like @samp{clean}, but may refrain from deleting a few files that people
5627 normally don't want to recompile. For example, the @samp{mostlyclean}
5628 target for GCC does not delete @file{libgcc.a}, because recompiling it
5629 is rarely necessary and takes a lot of time.
5632 @cindex @code{distclean} @r{(standard target)}
5634 @cindex @code{realclean} @r{(standard target)}
5636 @cindex @code{clobber} @r{(standard target)}
5637 Any of these targets might be defined to delete @emph{more} files than
5638 @samp{clean} does. For example, this would delete configuration files
5639 or links that you would normally create as preparation for compilation,
5640 even if the makefile itself cannot create these files.
5643 @cindex @code{install} @r{(standard target)}
5644 Copy the executable file into a directory that users typically search
5645 for commands; copy any auxiliary files that the executable uses into
5646 the directories where it will look for them.
5649 @cindex @code{print} @r{(standard target)}
5650 Print listings of the source files that have changed.
5653 @cindex @code{tar} @r{(standard target)}
5654 Create a tar file of the source files.
5657 @cindex @code{shar} @r{(standard target)}
5658 Create a shell archive (shar file) of the source files.
5661 @cindex @code{dist} @r{(standard target)}
5662 Create a distribution file of the source files. This might
5663 be a tar file, or a shar file, or a compressed version of one of the
5664 above, or even more than one of the above.
5667 @cindex @code{TAGS} @r{(standard target)}
5668 Update a tags table for this program.
5671 @cindex @code{check} @r{(standard target)}
5673 @cindex @code{test} @r{(standard target)}
5674 Perform self tests on the program this makefile builds.
5677 @node Instead of Execution, Avoiding Compilation, Goals, Running
5678 @section Instead of Executing the Commands
5679 @cindex execution, instead of
5680 @cindex commands, instead of executing
5682 The makefile tells @code{make} how to tell whether a target is up to date,
5683 and how to update each target. But updating the targets is not always
5684 what you want. Certain options specify other activities for @code{make}.
5686 @comment Extra blank lines make it print better.
5692 @cindex @code{--just-print}
5693 @cindex @code{--dry-run}
5694 @cindex @code{--recon}
5697 ``No-op''. The activity is to print what commands would be used to make
5698 the targets up to date, but not actually execute them.
5702 @cindex @code{--touch}
5703 @cindex touching files
5704 @cindex target, touching
5707 ``Touch''. The activity is to mark the targets as up to date without
5708 actually changing them. In other words, @code{make} pretends to compile
5709 the targets but does not really change their contents.
5713 @cindex @code{--question}
5715 @cindex question mode
5717 ``Question''. The activity is to find out silently whether the targets
5718 are up to date already; but execute no commands in either case. In other
5719 words, neither compilation nor output will occur.
5722 @itemx --what-if=@var{file}
5723 @itemx --assume-new=@var{file}
5724 @itemx --new-file=@var{file}
5725 @cindex @code{--what-if}
5727 @cindex @code{--assume-new}
5728 @cindex @code{--new-file}
5730 @cindex files, assuming new
5732 ``What if''. Each @samp{-W} flag is followed by a file name. The given
5733 files' modification times are recorded by @code{make} as being the present
5734 time, although the actual modification times remain the same.
5735 You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
5736 to see what would happen if you were to modify specific files.@refill
5739 With the @samp{-n} flag, @code{make} prints the commands that it would
5740 normally execute but does not execute them.
5742 With the @samp{-t} flag, @code{make} ignores the commands in the rules
5743 and uses (in effect) the command @code{touch} for each target that needs to
5744 be remade. The @code{touch} command is also printed, unless @samp{-s} or
5745 @code{.SILENT} is used. For speed, @code{make} does not actually invoke
5746 the program @code{touch}. It does the work directly.
5748 With the @samp{-q} flag, @code{make} prints nothing and executes no
5749 commands, but the exit status code it returns is zero if and only if the
5750 targets to be considered are already up to date. If the exit status is
5751 one, then some updating needs to be done. If @code{make} encounters an
5752 error, the exit status is two, so you can distinguish an error from a
5753 target that is not up to date.
5755 It is an error to use more than one of these three flags in the same
5756 invocation of @code{make}.
5758 The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command
5759 lines that begin with @samp{+} characters or contain the strings
5760 @samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing
5761 the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
5762 is run regardless of these options. Other lines in the same rule are
5763 not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
5764 @samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
5766 The @samp{-W} flag provides two features:
5770 If you also use the @samp{-n} or @samp{-q} flag, you can see what
5771 @code{make} would do if you were to modify some files.
5774 Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
5775 executing commands, the @samp{-W} flag can direct @code{make} to act
5776 as if some files had been modified, without actually modifying the
5780 Note that the options @samp{-p} and @samp{-v} allow you to obtain other
5781 information about @code{make} or about the makefiles in use
5782 (@pxref{Options Summary, ,Summary of Options}).@refill
5784 @node Avoiding Compilation, Overriding, Instead of Execution, Running
5785 @section Avoiding Recompilation of Some Files
5787 @cindex @code{--old-file}
5788 @cindex @code{--assume-old}
5789 @cindex files, assuming old
5790 @cindex files, avoiding recompilation of
5791 @cindex recompilation, avoiding
5793 Sometimes you may have changed a source file but you do not want to
5794 recompile all the files that depend on it. For example, suppose you add a
5795 macro or a declaration to a header file that many other files depend on.
5796 Being conservative, @code{make} assumes that any change in the header file
5797 requires recompilation of all dependent files, but you know that they do not
5798 need to be recompiled and you would rather not waste the time waiting for
5801 If you anticipate the problem before changing the header file, you can
5802 use the @samp{-t} flag. This flag tells @code{make} not to run the
5803 commands in the rules, but rather to mark the target up to date by
5804 changing its last-modification date. You would follow this procedure:
5808 Use the command @samp{make} to recompile the source files that really
5812 Make the changes in the header files.
5815 Use the command @samp{make -t} to mark all the object files as
5816 up to date. The next time you run @code{make}, the changes in the
5817 header files will not cause any recompilation.
5820 If you have already changed the header file at a time when some files
5821 do need recompilation, it is too late to do this. Instead, you can
5822 use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
5823 ``old'' (@pxref{Options Summary, ,Summary of Options}). This means
5824 that the file itself will not be remade, and nothing else will be
5825 remade on its account. Follow this procedure:
5829 Recompile the source files that need compilation for reasons independent
5830 of the particular header file, with @samp{make -o @var{headerfile}}.
5831 If several header files are involved, use a separate @samp{-o} option
5832 for each header file.
5835 Touch all the object files with @samp{make -t}.
5838 @node Overriding, Testing, Avoiding Compilation, Running
5839 @section Overriding Variables
5840 @cindex overriding variables with arguments
5841 @cindex variables, overriding with arguments
5842 @cindex command line variables
5843 @cindex variables, command line
5845 An argument that contains @samp{=} specifies the value of a variable:
5846 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
5847 If you specify a value in this way, all ordinary assignments of the same
5848 variable in the makefile are ignored; we say they have been
5849 @dfn{overridden} by the command line argument.
5851 The most common way to use this facility is to pass extra flags to
5852 compilers. For example, in a properly written makefile, the variable
5853 @code{CFLAGS} is included in each command that runs the C compiler, so a
5854 file @file{foo.c} would be compiled something like this:
5857 cc -c $(CFLAGS) foo.c
5860 Thus, whatever value you set for @code{CFLAGS} affects each compilation
5861 that occurs. The makefile probably specifies the usual value for
5862 @code{CFLAGS}, like this:
5868 Each time you run @code{make}, you can override this value if you
5869 wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C
5870 compilation will be done with @samp{cc -c -g -O}. (This illustrates
5871 how you can use quoting in the shell to enclose spaces and other
5872 special characters in the value of a variable when you override it.)
5874 The variable @code{CFLAGS} is only one of many standard variables that
5875 exist just so that you can change them this way. @xref{Implicit
5876 Variables, , Variables Used by Implicit Rules}, for a complete list.
5878 You can also program the makefile to look at additional variables of your
5879 own, giving the user the ability to control other aspects of how the
5880 makefile works by changing the variables.
5882 When you override a variable with a command argument, you can define either
5883 a recursively-expanded variable or a simply-expanded variable. The
5884 examples shown above make a recursively-expanded variable; to make a
5885 simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless
5886 you want to include a variable reference or function call in the
5887 @emph{value} that you specify, it makes no difference which kind of
5888 variable you create.
5890 There is one way that the makefile can change a variable that you have
5891 overridden. This is to use the @code{override} directive, which is a line
5892 that looks like this: @samp{override @var{variable} = @var{value}}
5893 (@pxref{Override Directive, ,The @code{override} Directive}).
5895 @node Testing, Options Summary, Overriding, Running
5896 @section Testing the Compilation of a Program
5897 @cindex testing compilation
5898 @cindex compilation, testing
5900 Normally, when an error happens in executing a shell command, @code{make}
5901 gives up immediately, returning a nonzero status. No further commands are
5902 executed for any target. The error implies that the goal cannot be
5903 correctly remade, and @code{make} reports this as soon as it knows.
5905 When you are compiling a program that you have just changed, this is not
5906 what you want. Instead, you would rather that @code{make} try compiling
5907 every file that can be tried, to show you as many compilation errors
5911 @cindex @code{--keep-going}
5912 On these occasions, you should use the @samp{-k} or
5913 @samp{--keep-going} flag. This tells @code{make} to continue to
5914 consider the other dependencies of the pending targets, remaking them
5915 if necessary, before it gives up and returns nonzero status. For
5916 example, after an error in compiling one object file, @samp{make -k}
5917 will continue compiling other object files even though it already
5918 knows that linking them will be impossible. In addition to continuing
5919 after failed shell commands, @samp{make -k} will continue as much as
5920 possible after discovering that it does not know how to make a target
5921 or dependency file. This will always cause an error message, but
5922 without @samp{-k}, it is a fatal error (@pxref{Options Summary,
5923 ,Summary of Options}).@refill
5925 The usual behavior of @code{make} assumes that your purpose is to get the
5926 goals up to date; once @code{make} learns that this is impossible, it might
5927 as well report the failure immediately. The @samp{-k} flag says that the
5928 real purpose is to test as much as possible of the changes made in the
5929 program, perhaps to find several independent problems so that you can
5930 correct them all before the next attempt to compile. This is why Emacs'
5931 @kbd{M-x compile} command passes the @samp{-k} flag by default.
5933 @node Options Summary, , Testing, Running
5934 @section Summary of Options
5939 Here is a table of all the options @code{make} understands:
5946 These options are ignored for compatibility with other versions of @code{make}.
5950 @itemx --directory=@var{dir}
5951 @cindex @code{--directory}
5952 Change to directory @var{dir} before reading the makefiles. If multiple
5953 @samp{-C} options are specified, each is interpreted relative to the
5954 previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
5955 This is typically used with recursive invocations of @code{make}
5956 (@pxref{Recursion, ,Recursive Use of @code{make}}).
5961 @cindex @code{--debug}
5962 @c Extra blank line here makes the table look better.
5964 Print debugging information in addition to normal processing. The
5965 debugging information says which files are being considered for
5966 remaking, which file-times are being compared and with what results,
5967 which files actually need to be remade, which implicit rules are
5968 considered and which are applied---everything interesting about how
5969 @code{make} decides what to do.
5973 @itemx --environment-overrides
5974 @cindex @code{--environment-overrides}
5975 Give variables taken from the environment precedence
5976 over variables from makefiles.
5977 @xref{Environment, ,Variables from the Environment}.
5981 @itemx --file=@var{file}
5982 @cindex @code{--file}
5983 @itemx --makefile=@var{file}
5984 @cindex @code{--makefile}
5985 Read the file named @var{file} as a makefile.
5986 @xref{Makefiles, ,Writing Makefiles}.
5991 @cindex @code{--help}
5992 @c Extra blank line here makes the table look better.
5994 Remind you of the options that @code{make} understands and then exit.
5998 @itemx --ignore-errors
5999 @cindex @code{--ignore-errors}
6000 Ignore all errors in commands executed to remake files.
6001 @xref{Errors, ,Errors in Commands}.
6005 @itemx --include-dir=@var{dir}
6006 @cindex @code{--include-dir}
6007 Specifies a directory @var{dir} to search for included makefiles.
6008 @xref{Include, ,Including Other Makefiles}. If several @samp{-I}
6009 options are used to specify several directories, the directories are
6010 searched in the order specified.
6012 @item -j [@var{jobs}]
6014 @itemx --jobs=[@var{jobs}]
6015 @cindex @code{--jobs}
6016 Specifies the number of jobs (commands) to run simultaneously. With no
6017 argument, @code{make} runs as many jobs simultaneously as possible. If
6018 there is more than one @samp{-j} option, the last one is effective.
6019 @xref{Parallel, ,Parallel Execution},
6020 for more information on how commands are run.
6025 @cindex @code{--keep-going}
6026 Continue as much as possible after an error. While the target that
6027 failed, and those that depend on it, cannot be remade, the other
6028 dependencies of these targets can be processed all the same.
6029 @xref{Testing, ,Testing the Compilation of a Program}.
6031 @item -l [@var{load}]
6033 @itemx --load-average[=@var{load}]
6034 @cindex @code{--load-average}
6035 @itemx --max-load[=@var{load}]
6036 @cindex @code{--max-load}
6037 Specifies that no new jobs (commands) should be started if there are
6038 other jobs running and the load average is at least @var{load} (a
6039 floating-point number). With no argument, removes a previous load
6040 limit. @xref{Parallel, ,Parallel Execution}.
6045 @cindex @code{--just-print}
6047 @cindex @code{--dry-run}
6049 @cindex @code{--recon}
6050 @c Extra blank line here makes the table look better.
6052 Print the commands that would be executed, but do not execute them.
6053 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6057 @itemx --old-file=@var{file}
6058 @cindex @code{--old-file}
6059 @itemx --assume-old=@var{file}
6060 @cindex @code{--assume-old}
6061 Do not remake the file @var{file} even if it is older than its
6062 dependencies, and do not remake anything on account of changes in
6063 @var{file}. Essentially the file is treated as very old and its rules
6064 are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of
6069 @itemx --print-data-base
6070 @cindex @code{--print-data-base}
6071 Print the data base (rules and variable values) that results from
6072 reading the makefiles; then execute as usual or as otherwise
6073 specified. This also prints the version information given by
6074 the @samp{-v} switch (see below). To print the data base without
6075 trying to remake any files, use @w{@samp{make -p -f /dev/null}}.
6080 @cindex @code{--question}
6081 ``Question mode''. Do not run any commands, or print anything; just
6082 return an exit status that is zero if the specified targets are already
6083 up to date, one if any remaking is required, or two if an error is
6084 encountered. @xref{Instead of Execution, ,Instead of Executing the
6089 @itemx --no-builtin-rules
6090 @cindex @code{--no-builtin-rules}
6091 Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
6092 ,Using Implicit Rules}). You can still define your own by writing
6093 pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
6094 Rules}). The @samp{-r} option also clears out the default list of
6095 suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
6096 Rules}). But you can still define your own suffixes with a rule for
6097 @code{.SUFFIXES}, and then define your own suffix rules.
6102 @cindex @code{--silent}
6104 @cindex @code{--quiet}
6105 @c Extra blank line here makes the table look better.
6107 Silent operation; do not print the commands as they are executed.
6108 @xref{Echoing, ,Command Echoing}.
6112 @itemx --no-keep-going
6113 @cindex @code{--no-keep-going}
6115 @cindex @code{--stop}
6116 @c Extra blank line here makes the table look better.
6118 Cancel the effect of the @samp{-k} option. This is never necessary
6119 except in a recursive @code{make} where @samp{-k} might be inherited
6120 from the top-level @code{make} via @code{MAKEFLAGS}
6121 (@pxref{Recursion, ,Recursive Use of @code{make}})
6122 or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
6127 @cindex @code{--touch}
6128 @c Extra blank line here makes the table look better.
6130 Touch files (mark them up to date without really changing them)
6131 instead of running their commands. This is used to pretend that the
6132 commands were done, in order to fool future invocations of
6133 @code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}.
6138 @cindex @code{--version}
6139 Print the version of the @code{make} program plus a copyright, a list
6140 of authors, and a notice that there is no warranty; then exit.
6144 @itemx --print-directory
6145 @cindex @code{--print-directory}
6146 Print a message containing the working directory both before and after
6147 executing the makefile. This may be useful for tracking down errors
6148 from complicated nests of recursive @code{make} commands.
6149 @xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you
6150 rarely need to specify this option since @samp{make} does it for you;
6151 see @ref{-w Option, ,The @samp{--print-directory} Option}.)
6153 @itemx --no-print-directory
6154 @cindex @code{--no-print-directory}
6155 Disable printing of the working directory under @code{-w}.
6156 This option is useful when @code{-w} is turned on automatically,
6157 but you do not want to see the extra messages.
6158 @xref{-w Option, ,The @samp{--print-directory} Option}.
6162 @itemx --what-if=@var{file}
6163 @cindex @code{--what-if}
6164 @itemx --new-file=@var{file}
6165 @cindex @code{--new-file}
6166 @itemx --assume-new=@var{file}
6167 @cindex @code{--assume-new}
6168 Pretend that the target @var{file} has just been modified. When used
6169 with the @samp{-n} flag, this shows you what would happen if you were
6170 to modify that file. Without @samp{-n}, it is almost the same as
6171 running a @code{touch} command on the given file before running
6172 @code{make}, except that the modification time is changed only in the
6173 imagination of @code{make}.
6174 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6176 @item --warn-undefined-variables
6177 @cindex @code{--warn-undefined-variables}
6178 @cindex variables, warning for undefined
6179 @cindex undefined variables, warning message
6180 Issue a warning message whenever @code{make} sees a reference to an
6181 undefined variable. This can be helpful when you are trying to debug
6182 makefiles which use variables in complex ways.
6185 @node Implicit Rules, Archives, Running, Top
6186 @chapter Using Implicit Rules
6187 @cindex implicit rule
6188 @cindex rule, implicit
6190 Certain standard ways of remaking target files are used very often. For
6191 example, one customary way to make an object file is from a C source file
6192 using the C compiler, @code{cc}.
6194 @dfn{Implicit rules} tell @code{make} how to use customary techniques so
6195 that you do not have to specify them in detail when you want to use
6196 them. For example, there is an implicit rule for C compilation. File
6197 names determine which implicit rules are run. For example, C
6198 compilation typically takes a @file{.c} file and makes a @file{.o} file.
6199 So @code{make} applies the implicit rule for C compilation when it sees
6200 this combination of file name endings.@refill
6202 A chain of implicit rules can apply in sequence; for example, @code{make}
6203 will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
6205 @xref{Chained Rules, ,Chains of Implicit Rules}.
6208 The built-in implicit rules use several variables in their commands so
6209 that, by changing the values of the variables, you can change the way the
6210 implicit rule works. For example, the variable @code{CFLAGS} controls the
6211 flags given to the C compiler by the implicit rule for C compilation.
6213 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
6216 You can define your own implicit rules by writing @dfn{pattern rules}.
6218 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
6221 @dfn{Suffix rules} are a more limited way to define implicit rules.
6222 Pattern rules are more general and clearer, but suffix rules are
6223 retained for compatibility.
6225 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
6229 * Using Implicit:: How to use an existing implicit rule
6230 to get the commands for updating a file.
6231 * Catalogue of Rules:: A list of built-in implicit rules.
6232 * Implicit Variables:: How to change what predefined rules do.
6233 * Chained Rules:: How to use a chain of implicit rules.
6234 * Pattern Rules:: How to define new implicit rules.
6235 * Last Resort:: How to defining commands for rules
6236 which cannot find any.
6237 * Suffix Rules:: The old-fashioned style of implicit rule.
6238 * Search Algorithm:: The precise algorithm for applying
6242 @node Using Implicit, Catalogue of Rules, , Implicit Rules
6243 @section Using Implicit Rules
6244 @cindex implicit rule, how to use
6245 @cindex rule, implicit, how to use
6247 To allow @code{make} to find a customary method for updating a target file,
6248 all you have to do is refrain from specifying commands yourself. Either
6249 write a rule with no command lines, or don't write a rule at all. Then
6250 @code{make} will figure out which implicit rule to use based on which
6251 kind of source file exists or can be made.
6253 For example, suppose the makefile looks like this:
6257 cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
6261 Because you mention @file{foo.o} but do not give a rule for it, @code{make}
6262 will automatically look for an implicit rule that tells how to update it.
6263 This happens whether or not the file @file{foo.o} currently exists.
6265 If an implicit rule is found, it can supply both commands and one or
6266 more dependencies (the source files). You would want to write a rule
6267 for @file{foo.o} with no command lines if you need to specify additional
6268 dependencies, such as header files, that the implicit rule cannot
6271 Each implicit rule has a target pattern and dependency patterns. There may
6272 be many implicit rules with the same target pattern. For example, numerous
6273 rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
6274 another, from a @samp{.p} file with the Pascal compiler; and so on. The rule
6275 that actually applies is the one whose dependencies exist or can be made.
6276 So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
6277 otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
6278 compiler; and so on.
6280 Of course, when you write the makefile, you know which implicit rule you
6281 want @code{make} to use, and you know it will choose that one because you
6282 know which possible dependency files are supposed to exist.
6283 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
6284 for a catalogue of all the predefined implicit rules.
6286 Above, we said an implicit rule applies if the required dependencies ``exist
6287 or can be made''. A file ``can be made'' if it is mentioned explicitly in
6288 the makefile as a target or a dependency, or if an implicit rule can be
6289 recursively found for how to make it. When an implicit dependency is the
6290 result of another implicit rule, we say that @dfn{chaining} is occurring.
6291 @xref{Chained Rules, ,Chains of Implicit Rules}.
6293 In general, @code{make} searches for an implicit rule for each target, and
6294 for each double-colon rule, that has no commands. A file that is mentioned
6295 only as a dependency is considered a target whose rule specifies nothing,
6296 so implicit rule search happens for it. @xref{Search Algorithm, ,Implicit Rule Search Algorithm}, for the
6297 details of how the search is done.
6299 Note that explicit dependencies do not influence implicit rule search.
6300 For example, consider this explicit rule:
6307 The dependency on @file{foo.p} does not necessarily mean that
6308 @code{make} will remake @file{foo.o} according to the implicit rule to
6309 make an object file, a @file{.o} file, from a Pascal source file, a
6310 @file{.p} file. For example, if @file{foo.c} also exists, the implicit
6311 rule to make an object file from a C source file is used instead,
6312 because it appears before the Pascal rule in the list of predefined
6313 implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
6316 If you do not want an implicit rule to be used for a target that has no
6317 commands, you can give that target empty commands by writing a semicolon
6318 (@pxref{Empty Commands, ,Defining Empty Commands}).
6320 @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
6321 @section Catalogue of Implicit Rules
6322 @cindex implicit rule, predefined
6323 @cindex rule, implicit, predefined
6325 Here is a catalogue of predefined implicit rules which are always
6326 available unless the makefile explicitly overrides or cancels them.
6327 @xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
6328 canceling or overriding an implicit rule. The @samp{-r} or
6329 @samp{--no-builtin-rules} option cancels all predefined rules.
6331 Not all of these rules will always be defined, even when the @samp{-r}
6332 option is not given. Many of the predefined implicit rules are
6333 implemented in @code{make} as suffix rules, so which ones will be
6334 defined depends on the @dfn{suffix list} (the list of dependencies of
6335 the special target @code{.SUFFIXES}). The default suffix list is:
6336 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
6337 @code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
6338 @code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
6339 @code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
6340 @code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
6341 @code{.sh}, @code{.elc}, @code{.el}. All of the implicit rules
6342 described below whose dependencies have one of these suffixes are
6343 actually suffix rules. If you modify the suffix list, the only
6344 predefined suffix rules in effect will be those named by one or two of
6345 the suffixes that are on the list you specify; rules whose suffixes fail
6346 to be on the list are disabled. @xref{Suffix Rules, ,Old-Fashioned
6347 Suffix Rules}, for full details on suffix rules.
6350 @item Compiling C programs
6351 @cindex C, rule to compile
6356 @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
6357 a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
6359 @item Compiling C++ programs
6360 @cindex C++, rule to compile
6364 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
6365 @file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
6366 $(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++
6367 source files instead of @samp{.C}.@refill
6369 @item Compiling Pascal programs
6370 @cindex Pascal, rule to compile
6373 @file{@var{n}.o} is made automatically from @file{@var{n}.p}
6374 with the command @samp{$(PC) -c $(PFLAGS)}.@refill
6376 @item Compiling Fortran and Ratfor programs
6377 @cindex Fortran, rule to compile
6378 @cindex Ratfor, rule to compile
6383 @file{@var{n}.o} is made automatically from @file{@var{n}.r},
6384 @file{@var{n}.F} or @file{@var{n}.f} by running the
6385 Fortran compiler. The precise command used is as follows:@refill
6389 @samp{$(FC) -c $(FFLAGS)}.
6391 @samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}.
6393 @samp{$(FC) -c $(FFLAGS) $(RFLAGS)}.
6396 @item Preprocessing Fortran and Ratfor programs
6397 @file{@var{n}.f} is made automatically from @file{@var{n}.r} or
6398 @file{@var{n}.F}. This rule runs just the preprocessor to convert a
6399 Ratfor or preprocessable Fortran program into a strict Fortran
6400 program. The precise command used is as follows:@refill
6404 @samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}.
6406 @samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
6409 @item Compiling Modula-2 programs
6410 @cindex Modula-2, rule to compile
6415 @file{@var{n}.sym} is made from @file{@var{n}.def} with a command
6416 of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o}
6417 is made from @file{@var{n}.mod}; the form is:
6418 @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
6421 @item Assembling and preprocessing assembler programs
6422 @cindex assembly, rule to compile
6425 @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
6426 running the assembler, @code{as}. The precise command is
6427 @samp{$(AS) $(ASFLAGS)}.@refill
6430 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
6431 running the C preprocessor, @code{cpp}. The precise command is
6432 @w{@samp{$(CPP) $(CPPFLAGS)}}.
6434 @item Linking a single object file
6435 @cindex linking, predefined rule for
6438 @file{@var{n}} is made automatically from @file{@var{n}.o} by running
6439 the linker (usually called @code{ld}) via the C compiler. The precise
6440 command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}}.
6442 This rule does the right thing for a simple program with only one
6443 source file. It will also do the right thing if there are multiple
6444 object files (presumably coming from various other source files), one
6445 of which has a name matching that of the executable file. Thus,
6452 when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
6467 In more complicated cases, such as when there is no object file whose
6468 name derives from the executable file name, you must write an explicit
6469 command for linking.
6471 Each kind of file automatically made into @samp{.o} object files will
6472 be automatically linked by using the compiler (@samp{$(CC)},
6473 @samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
6474 assemble @samp{.s} files) without the @samp{-c} option. This could be
6475 done by using the @samp{.o} object files as intermediates, but it is
6476 faster to do the compiling and linking in one step, so that's how it's
6479 @item Yacc for C programs
6481 @cindex Yacc, rule to run
6483 @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
6484 running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
6486 @item Lex for C programs
6488 @cindex Lex, rule to run
6490 @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
6491 by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
6493 @item Lex for Ratfor programs
6494 @file{@var{n}.r} is made automatically from @file{@var{n}.l} by
6495 by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
6497 The convention of using the same suffix @samp{.l} for all Lex files
6498 regardless of whether they produce C code or Ratfor code makes it
6499 impossible for @code{make} to determine automatically which of the two
6500 languages you are using in any particular case. If @code{make} is
6501 called upon to remake an object file from a @samp{.l} file, it must
6502 guess which compiler to use. It will guess the C compiler, because
6503 that is more common. If you are using Ratfor, make sure @code{make}
6504 knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you
6505 are using Ratfor exclusively, with no C files, remove @samp{.c} from
6506 the list of implicit rule suffixes with:@refill
6511 .SUFFIXES: .o .r .f .l @dots{}
6515 @item Making Lint Libraries from C, Yacc, or Lex programs
6517 @cindex @code{lint}, rule to run
6519 @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
6520 The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
6521 The same command is used on the C code produced from
6522 @file{@var{n}.y} or @file{@var{n}.l}.@refill
6524 @item @TeX{} and Web
6525 @cindex @TeX{}, rule to run
6526 @cindex Web, rule to run
6537 @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command
6538 @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with
6539 @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
6540 it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is
6541 made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
6542 is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
6543 or can be made) with @samp{$(CTANGLE)}.@refill
6545 @item Texinfo and Info
6546 @cindex Texinfo, rule to format
6547 @cindex Info, rule to format
6554 @file{@var{n}.dvi} is made from @file{@var{n}.texinfo},
6555 @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command
6556 @w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from
6557 @file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with
6558 the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}.
6561 @cindex RCS, rule to extract from
6563 @pindex ,v @r{(RCS file extension)}
6564 Any file @file{@var{n}} is extracted if necessary from an RCS file
6565 named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise
6566 command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be
6567 extracted from RCS if it already exists, even if the RCS file is
6568 newer. The rules for RCS are terminal
6569 (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6570 so RCS files cannot be generated from another source; they must
6571 actually exist.@refill
6574 @cindex SCCS, rule to extract from
6576 @pindex s. @r{(SCCS file prefix)}
6577 Any file @file{@var{n}} is extracted if necessary from an SCCS file
6578 named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise
6579 command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are
6580 terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6581 so SCCS files cannot be generated from another source; they must
6582 actually exist.@refill
6585 For the benefit of SCCS, a file @file{@var{n}} is copied from
6586 @file{@var{n}.sh} and made executable (by everyone). This is for
6587 shell scripts that are checked into SCCS. Since RCS preserves the
6588 execution permission of a file, you do not need to use this feature
6591 We recommend that you avoid using of SCCS. RCS is widely held to be
6592 superior, and is also free. By choosing free software in place of
6593 comparable (or inferior) proprietary software, you support the free
6597 Usually, you want to change only the variables listed in the table
6598 above, which are documented in the following section.
6600 However, the commands in built-in implicit rules actually use
6601 variables such as @code{COMPILE.c}, @code{LINK.p}, and
6602 @code{PREPROCESS.S}, whose values contain the commands listed above.
6604 @code{make} follows the convention that the rule to compile a
6605 @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
6606 Similarly, the rule to produce an executable from a @file{.@var{x}}
6607 file uses @code{LINK.@var{x}}; and the rule to preprocess a
6608 @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
6610 @vindex OUTPUT_OPTION
6611 Every rule that produces an object file uses the variable
6612 @code{OUTPUT_OPTION}. @code{make} defines this variable either to
6613 contain @samp{-o $@@}, or to be empty, depending on a compile-time
6614 option. You need the @samp{-o} option to ensure that the output goes
6615 into the right file when the source file is in a different directory,
6616 as when using @code{VPATH} (@pxref{Directory Search}). However,
6617 compilers on some systems do not accept a @samp{-o} switch for object
6618 files. If you use such a system, and use @code{VPATH}, some
6619 compilations will put their output in the wrong place.
6620 A possible workaround for this problem is to give @code{OUTPUT_OPTION}
6621 the value @w{@samp{; mv $*.o $@@}}.
6623 @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
6624 @section Variables Used by Implicit Rules
6625 @cindex flags for compilers
6627 The commands in built-in implicit rules make liberal use of certain
6628 predefined variables. You can alter these variables in the makefile,
6629 with arguments to @code{make}, or in the environment to alter how the
6630 implicit rules work without redefining the rules themselves.
6632 For example, the command used to compile a C source file actually says
6633 @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables
6634 used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By
6635 redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
6636 used for all C compilations performed by the implicit rule. By redefining
6637 @samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
6638 each compilation. @emph{All} implicit rules that do C compilation use
6639 @samp{$(CC)} to get the program name for the compiler and @emph{all}
6640 include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
6642 The variables used in implicit rules fall into two classes: those that are
6643 names of programs (like @code{CC}) and those that contain arguments for the
6644 programs (like @code{CFLAGS}). (The ``name of a program'' may also contain
6645 some command arguments, but it must start with an actual executable program
6646 name.) If a variable value contains more than one argument, separate them
6649 Here is a table of variables used as names of programs in built-in rules:
6654 Archive-maintaining program; default @samp{ar}.
6659 Program for doing assembly; default @samp{as}.
6664 Program for compiling C programs; default @samp{cc}.
6669 Program for compiling C++ programs; default @samp{g++}.
6674 Program for extracting a file from RCS; default @samp{co}.
6679 Program for running the C preprocessor, with results to standard output;
6680 default @samp{$(CC) -E}.
6684 Program for compiling or preprocessing Fortran and Ratfor programs;
6690 Program for extracting a file from SCCS; default @samp{get}.
6695 Program to use to turn Lex grammars into C programs or Ratfor programs;
6701 Program for compiling Pascal programs; default @samp{pc}.
6706 Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
6711 Program to use to turn Yacc grammars into Ratfor
6712 programs; default @samp{yacc -r}.
6716 Program to convert a Texinfo source file into an Info file; default
6722 Program to make @TeX{} @sc{dvi} files from @TeX{} source;
6728 Program to make @TeX{} @sc{dvi} files from Texinfo source;
6729 default @samp{texi2dvi}.
6734 Program to translate Web into @TeX{}; default @samp{weave}.
6739 Program to translate C Web into @TeX{}; default @samp{cweave}.
6744 Program to translate Web into Pascal; default @samp{tangle}.
6749 Program to translate C Web into C; default @samp{ctangle}.
6754 Command to remove a file; default @samp{rm -f}.
6758 Here is a table of variables whose values are additional arguments for the
6759 programs above. The default values for all of these is the empty
6760 string, unless otherwise noted.
6765 Flags to give the archive-maintaining program; default @samp{rv}.
6769 Extra flags to give to the assembler (when explicitly
6770 invoked on a @samp{.s} or @samp{.S} file).
6774 Extra flags to give to the C compiler.
6778 Extra flags to give to the C++ compiler.
6782 Extra flags to give to the RCS @code{co} program.
6786 Extra flags to give to the C preprocessor and programs
6787 that use it (the C and Fortran compilers).
6791 Extra flags to give to the Fortran compiler.
6795 Extra flags to give to the SCCS @code{get} program.
6799 Extra flags to give to compilers when they are
6800 supposed to invoke the linker, @samp{ld}.
6804 Extra flags to give to Lex.
6808 Extra flags to give to the Pascal compiler.
6812 Extra flags to give to the Fortran compiler for Ratfor programs.
6816 Extra flags to give to Yacc.
6819 @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
6820 @section Chains of Implicit Rules
6822 @cindex chains of rules
6823 @cindex rule, implicit, chains of
6824 Sometimes a file can be made by a sequence of implicit rules. For example,
6825 a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
6826 first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
6828 If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
6829 special searching is required: @code{make} finds that the object file can
6830 be made by C compilation from @file{@var{n}.c}; later on, when considering
6831 how to make @file{@var{n}.c}, the rule for running Yacc is
6832 used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
6835 @cindex intermediate files
6836 @cindex files, intermediate
6837 However, even if @file{@var{n}.c} does not exist and is not mentioned,
6838 @code{make} knows how to envision it as the missing link between
6839 @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
6840 called an @dfn{intermediate file}. Once @code{make} has decided to use the
6841 intermediate file, it is entered in the data base as if it had been
6842 mentioned in the makefile, along with the implicit rule that says how to
6845 Intermediate files are remade using their rules just like all other
6846 files. The difference is that the intermediate file is deleted when
6847 @code{make} is finished. Therefore, the intermediate file which did not
6848 exist before @code{make} also does not exist after @code{make}. The
6849 deletion is reported to you by printing a @samp{rm -f} command that
6850 shows what @code{make} is doing. (You can list the target pattern of an
6851 implicit rule (such as @samp{%.o}) as a dependency of the special
6852 target @code{.PRECIOUS} to preserve intermediate files made by implicit
6853 rules whose target patterns match that file's name;
6854 see @ref{Interrupts}.)@refill
6855 @cindex intermediate files, preserving
6856 @cindex preserving intermediate files
6857 @cindex preserving with @code{.PRECIOUS}
6858 @cindex @code{.PRECIOUS} intermediate files
6860 A chain can involve more than two implicit rules. For example, it is
6861 possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
6862 Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are
6863 intermediate files that are deleted at the end.@refill
6865 No single implicit rule can appear more than once in a chain. This means
6866 that @code{make} will not even consider such a ridiculous thing as making
6867 @file{foo} from @file{foo.o.o} by running the linker twice. This
6868 constraint has the added benefit of preventing any infinite loop in the
6869 search for an implicit rule chain.
6871 There are some special implicit rules to optimize certain cases that would
6872 otherwise be handled by rule chains. For example, making @file{foo} from
6873 @file{foo.c} could be handled by compiling and linking with separate
6874 chained rules, using @file{foo.o} as an intermediate file. But what
6875 actually happens is that a special rule for this case does the compilation
6876 and linking with a single @code{cc} command. The optimized rule is used in
6877 preference to the step-by-step chain because it comes earlier in the
6880 @node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
6881 @section Defining and Redefining Pattern Rules
6883 You define an implicit rule by writing a @dfn{pattern rule}. A pattern
6884 rule looks like an ordinary rule, except that its target contains the
6885 character @samp{%} (exactly one of them). The target is considered a
6886 pattern for matching file names; the @samp{%} can match any nonempty
6887 substring, while other characters match only themselves. The dependencies
6888 likewise use @samp{%} to show how their names relate to the target name.
6890 Thus, a pattern rule @samp{%.o : %.c} says how to make any file
6891 @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
6893 Note that expansion using @samp{%} in pattern rules occurs
6894 @strong{after} any variable or function expansions, which take place
6895 when the makefile is read. @xref{Using Variables, , How to Use
6896 Variables}, and @ref{Functions, ,Functions for Transforming Text}.
6899 * Pattern Intro:: An introduction to pattern rules.
6900 * Pattern Examples:: Examples of pattern rules.
6901 * Automatic:: How to use automatic variables in the
6902 commands of implicit rules.
6903 * Pattern Match:: How patterns match.
6904 * Match-Anything Rules:: Precautions you should take prior to
6905 defining rules that can match any
6906 target file whatever.
6907 * Canceling Rules:: How to override or cancel built-in rules.
6910 @node Pattern Intro, Pattern Examples, , Pattern Rules
6911 @subsection Introduction to Pattern Rules
6912 @cindex pattern rule
6913 @cindex rule, pattern
6915 A pattern rule contains the character @samp{%} (exactly one of them)
6916 in the target; otherwise, it looks exactly like an ordinary rule. The
6917 target is a pattern for matching file names; the @samp{%} matches any
6918 nonempty substring, while other characters match only themselves.
6919 @cindex target pattern, implicit
6920 @cindex @code{%}, in pattern rules
6922 For example, @samp{%.c} as a pattern matches any file name that ends in
6923 @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
6924 with @samp{s.}, ends in @samp{.c} and is at least five characters long.
6925 (There must be at least one character to match the @samp{%}.) The substring
6926 that the @samp{%} matches is called the @dfn{stem}.@refill
6928 @samp{%} in a dependency of a pattern rule stands for the same stem
6929 that was matched by the @samp{%} in the target. In order for
6930 the pattern rule to apply, its target pattern must match the file name
6931 under consideration, and its dependency patterns must name files that
6932 exist or can be made. These files become dependencies of the target.
6933 @cindex dependency pattern, implicit
6935 Thus, a rule of the form
6938 %.o : %.c ; @var{command}@dots{}
6942 specifies how to make a file @file{@var{n}.o}, with another file
6943 @file{@var{n}.c} as its dependency, provided that @file{@var{n}.c}
6944 exists or can be made.
6946 There may also be dependencies that do not use @samp{%}; such a dependency
6947 attaches to every file made by this pattern rule. These unvarying
6948 dependencies are useful occasionally.
6950 A pattern rule need not have any dependencies that contain @samp{%}, or
6951 in fact any dependencies at all. Such a rule is effectively a general
6952 wildcard. It provides a way to make any file that matches the target
6953 pattern. @xref{Last Resort}.
6955 @c !!! The end of of this paragraph should be rewritten. --bob
6956 Pattern rules may have more than one target. Unlike normal rules, this
6957 does not act as many different rules with the same dependencies and
6958 commands. If a pattern rule has multiple targets, @code{make} knows that
6959 the rule's commands are responsible for making all of the targets. The
6960 commands are executed only once to make all the targets. When searching
6961 for a pattern rule to match a target, the target patterns of a rule other
6962 than the one that matches the target in need of a rule are incidental:
6963 @code{make} worries only about giving commands and dependencies to the file
6964 presently in question. However, when this file's commands are run, the
6965 other targets are marked as having been updated themselves.
6966 @cindex multiple targets, in pattern rule
6967 @cindex target, multiple in pattern rule
6969 The order in which pattern rules appear in the makefile is important
6970 since this is the order in which they are considered.
6971 Of equally applicable
6972 rules, only the first one found is used. The rules you write take precedence
6973 over those that are built in. Note however, that a rule whose
6974 dependencies actually exist or are mentioned always takes priority over a
6975 rule with dependencies that must be made by chaining other implicit rules.
6976 @cindex pattern rules, order of
6977 @cindex order of pattern rules
6979 @node Pattern Examples, Automatic, Pattern Intro, Pattern Rules
6980 @subsection Pattern Rule Examples
6982 Here are some examples of pattern rules actually predefined in
6983 @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o}
6988 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
6992 defines a rule that can make any file @file{@var{x}.o} from
6993 @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and
6994 @samp{$<} to substitute the names of the target file and the source file
6995 in each case where the rule applies (@pxref{Automatic, ,Automatic Variables}).@refill
6997 Here is a second built-in rule:
7005 defines a rule that can make any file @file{@var{x}} whatsoever from a
7006 corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since
7007 the target is @samp{%}, this rule will apply to any file whatever, provided
7008 the appropriate dependency file exists. The double colon makes the rule
7009 @dfn{terminal}, which means that its dependency may not be an intermediate
7010 file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
7013 This pattern rule has two targets:
7017 %.tab.c %.tab.h: %.y
7023 @c The following paragraph is rewritten to avoid overfull hboxes
7024 This tells @code{make} that the command @samp{bison -d @var{x}.y} will
7025 make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file
7026 @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
7027 and the file @file{scan.o} depends on the file @file{parse.tab.h},
7028 when @file{parse.y} is changed, the command @samp{bison -d parse.y}
7029 will be executed only once, and the dependencies of both
7030 @file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably
7031 the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
7032 and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
7033 linked from @file{parse.tab.o}, @file{scan.o}, and its other
7034 dependencies, and it will execute happily ever after.)@refill
7036 @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
7037 @subsection Automatic Variables
7038 @cindex automatic variables
7039 @cindex variables, automatic
7040 @cindex variables, and implicit rule
7042 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
7043 @samp{.o} file: how do you write the @samp{cc} command so that it operates
7044 on the right source file name? You cannot write the name in the command,
7045 because the name is different each time the implicit rule is applied.
7047 What you do is use a special feature of @code{make}, the @dfn{automatic
7048 variables}. These variables have values computed afresh for each rule that
7049 is executed, based on the target and dependencies of the rule. In this
7050 example, you would use @samp{$@@} for the object file name and @samp{$<}
7051 for the source file name.
7053 Here is a table of automatic variables:
7057 @vindex @@ @r{(automatic variable)}
7059 The file name of the target of the rule. If the target is an archive
7060 member, then @samp{$@@} is the name of the archive file. In a pattern
7061 rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
7062 Pattern Rules}), @samp{$@@} is the name of whichever target caused the
7063 rule's commands to be run.
7066 @vindex % @r{(automatic variable)}
7068 The target member name, when the target is an archive member.
7069 @xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then
7070 @samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is
7071 empty when the target is not an archive member.
7074 @vindex < @r{(automatic variable)}
7076 The name of the first dependency. If the target got its commands from
7077 an implicit rule, this will be the first dependency added by the
7078 implicit rule (@pxref{Implicit Rules}).
7081 @vindex ? @r{(automatic variable)}
7083 The names of all the dependencies that are newer than the target, with
7084 spaces between them. For dependencies which are archive members, only
7085 the member named is used (@pxref{Archives}).
7086 @cindex dependencies, list of changed
7087 @cindex list of changed dependencies
7090 @vindex ^ @r{(automatic variable)}
7092 The names of all the dependencies, with spaces between them. For
7093 dependencies which are archive members, only the member named is used
7094 (@pxref{Archives}). A target has only one dependency on each other file
7095 it depends on, no matter how many times each file is listed as a
7096 dependency. So if you list a dependency more than once for a target,
7097 the value of @code{$^} contains just one copy of the name.
7098 @cindex dependencies, list of all
7099 @cindex list of all dependencies
7102 @vindex * @r{(automatic variable)}
7104 The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
7105 Patterns Match}). If the target is @file{dir/a.foo.b} and the target
7106 pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is
7107 useful for constructing names of related files.@refill
7108 @cindex stem, variable for
7110 In a static pattern rule, the stem is part of the file name that matched
7111 the @samp{%} in the target pattern.
7113 In an explicit rule, there is no stem; so @samp{$*} cannot be determined
7114 in that way. Instead, if the target name ends with a recognized suffix
7115 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
7116 the target name minus the suffix. For example, if the target name is
7117 @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
7118 suffix. GNU @code{make} does this bizarre thing only for compatibility
7119 with other implementations of @code{make}. You should generally avoid
7120 using @samp{$*} except in implicit rules or static pattern rules.@refill
7122 If the target name in an explicit rule does not end with a recognized
7123 suffix, @samp{$*} is set to the empty string for that rule.
7126 @samp{$?} is useful even in explicit rules when you wish to operate on only
7127 the dependencies that have changed. For example, suppose that an archive
7128 named @file{lib} is supposed to contain copies of several object files.
7129 This rule copies just the changed object files into the archive:
7133 lib: foo.o bar.o lose.o win.o
7138 Of the variables listed above, four have values that are single file
7139 names, and two have values that are lists of file names. These six have
7140 variants that get just the file's directory name or just the file name
7141 within the directory. The variant variables' names are formed by
7142 appending @samp{D} or @samp{F}, respectively. These variants are
7143 semi-obsolete in GNU @code{make} since the functions @code{dir} and
7144 @code{notdir} can be used to get a similar effect (@pxref{Filename
7145 Functions, , Functions for File Names}). Note, however, that the
7146 @samp{F} variants all omit the trailing slash which always appears in
7147 the output of the @code{dir} function. Here is a table of the variants:
7151 @vindex @@D @r{(automatic variable)}
7153 The directory part of the file name of the target, with the trailing
7154 slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then
7155 @samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does
7156 not contain a slash.
7159 @vindex @@F @r{(automatic variable)}
7161 The file-within-directory part of the file name of the target. If the
7162 value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
7163 @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
7166 @vindex *D @r{(automatic variable)}
7169 @vindex *F @r{(automatic variable)}
7171 The directory part and the file-within-directory
7172 part of the stem; @file{dir} and @file{foo} in this example.
7175 @vindex %D @r{(automatic variable)}
7178 @vindex %F @r{(automatic variable)}
7180 The directory part and the file-within-directory part of the target
7181 archive member name. This makes sense only for archive member targets
7182 of the form @file{@var{archive}(@var{member})} and is useful only when
7183 @var{member} may contain a directory name. (@xref{Archive Members,
7184 ,Archive Members as Targets}.)
7187 @vindex <D @r{(automatic variable)}
7190 @vindex <F @r{(automatic variable)}
7192 The directory part and the file-within-directory
7193 part of the first dependency.
7196 @vindex ^D @r{(automatic variable)}
7199 @vindex ^F @r{(automatic variable)}
7201 Lists of the directory parts and the file-within-directory
7202 parts of all dependencies.
7205 @vindex ?D @r{(automatic variable)}
7208 @vindex ?F @r{(automatic variable)}
7210 Lists of the directory parts and the file-within-directory parts of
7211 all dependencies that are newer than the target.
7214 Note that we use a special stylistic convention when we talk about these
7215 automatic variables; we write ``the value of @samp{$<}'', rather than
7216 @w{``the variable @code{<}''} as we would write for ordinary variables
7217 such as @code{objects} and @code{CFLAGS}. We think this convention
7218 looks more natural in this special case. Please do not assume it has a
7219 deep significance; @samp{$<} refers to the variable named @code{<} just
7220 as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
7221 You could just as well use @samp{$(<)} in place of @samp{$<}.
7223 @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
7224 @subsection How Patterns Match
7227 A target pattern is composed of a @samp{%} between a prefix and a suffix,
7228 either or both of which may be empty. The pattern matches a file name only
7229 if the file name starts with the prefix and ends with the suffix, without
7230 overlap. The text between the prefix and the suffix is called the
7231 @dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name
7232 @file{test.o}, the stem is @samp{test}. The pattern rule dependencies are
7233 turned into actual file names by substituting the stem for the character
7234 @samp{%}. Thus, if in the same example one of the dependencies is written
7235 as @samp{%.c}, it expands to @samp{test.c}.@refill
7237 When the target pattern does not contain a slash (and it usually does
7238 not), directory names in the file names are removed from the file name
7239 before it is compared with the target prefix and suffix. After the
7240 comparison of the file name to the target pattern, the directory
7241 names, along with the slash that ends them, are added on to the
7242 dependency file names generated from the pattern rule's dependency
7243 patterns and the file name. The directories are ignored only for the
7244 purpose of finding an implicit rule to use, not in the application of
7245 that rule. Thus, @samp{e%t} matches the file name @file{src/eat},
7246 with @samp{src/a} as the stem. When dependencies are turned into file
7247 names, the directories from the stem are added at the front, while the
7248 rest of the stem is substituted for the @samp{%}. The stem
7249 @samp{src/a} with a dependency pattern @samp{c%r} gives the file name
7250 @file{src/car}.@refill
7252 @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
7253 @subsection Match-Anything Pattern Rules
7255 @cindex match-anything rule
7256 @cindex terminal rule
7257 When a pattern rule's target is just @samp{%}, it matches any file name
7258 whatever. We call these rules @dfn{match-anything} rules. They are very
7259 useful, but it can take a lot of time for @code{make} to think about them,
7260 because it must consider every such rule for each file name listed either
7261 as a target or as a dependency.
7263 Suppose the makefile mentions @file{foo.c}. For this target, @code{make}
7264 would have to consider making it by linking an object file @file{foo.c.o},
7265 or by C compilation-and-linking in one step from @file{foo.c.c}, or by
7266 Pascal compilation-and-linking from @file{foo.c.p}, and many other
7269 We know these possibilities are ridiculous since @file{foo.c} is a C source
7270 file, not an executable. If @code{make} did consider these possibilities,
7271 it would ultimately reject them, because files such as @file{foo.c.o} and
7272 @file{foo.c.p} would not exist. But these possibilities are so
7273 numerous that @code{make} would run very slowly if it had to consider
7276 To gain speed, we have put various constraints on the way @code{make}
7277 considers match-anything rules. There are two different constraints that
7278 can be applied, and each time you define a match-anything rule you must
7279 choose one or the other for that rule.
7281 One choice is to mark the match-anything rule as @dfn{terminal} by defining
7282 it with a double colon. When a rule is terminal, it does not apply unless
7283 its dependencies actually exist. Dependencies that could be made with
7284 other implicit rules are not good enough. In other words, no further
7285 chaining is allowed beyond a terminal rule.
7287 For example, the built-in implicit rules for extracting sources from RCS
7288 and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
7289 not exist, @code{make} will not even consider trying to make it as an
7290 intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
7291 RCS and SCCS files are generally ultimate source files, which should not be
7292 remade from any other files; therefore, @code{make} can save time by not
7293 looking for ways to remake them.@refill
7295 If you do not mark the match-anything rule as terminal, then it is
7296 nonterminal. A nonterminal match-anything rule cannot apply to a file name
7297 that indicates a specific type of data. A file name indicates a specific
7298 type of data if some non-match-anything implicit rule target matches it.
7300 For example, the file name @file{foo.c} matches the target for the pattern
7301 rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this
7302 rule is actually applicable (which happens only if there is a file
7303 @file{foo.y}), the fact that its target matches is enough to prevent
7304 consideration of any nonterminal match-anything rules for the file
7305 @file{foo.c}. Thus, @code{make} will not even consider trying to make
7306 @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
7307 @file{foo.c.p}, etc.@refill
7309 The motivation for this constraint is that nonterminal match-anything
7310 rules are used for making files containing specific types of data (such as
7311 executable files) and a file name with a recognized suffix indicates some
7312 other specific type of data (such as a C source file).
7314 Special built-in dummy pattern rules are provided solely to recognize
7315 certain file names so that nonterminal match-anything rules will not be
7316 considered. These dummy rules have no dependencies and no commands, and
7317 they are ignored for all other purposes. For example, the built-in
7325 exists to make sure that Pascal source files such as @file{foo.p} match a
7326 specific target pattern and thereby prevent time from being wasted looking
7327 for @file{foo.p.o} or @file{foo.p.c}.
7329 Dummy pattern rules such as the one for @samp{%.p} are made for every
7330 suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
7332 @node Canceling Rules, , Match-Anything Rules, Pattern Rules
7333 @subsection Canceling Implicit Rules
7335 You can override a built-in implicit rule (or one you have defined
7336 yourself) by defining a new pattern rule with the same target and
7337 dependencies, but different commands. When the new rule is defined, the
7338 built-in one is replaced. The new rule's position in the sequence of
7339 implicit rules is determined by where you write the new rule.
7341 You can cancel a built-in implicit rule by defining a pattern rule with the
7342 same target and dependencies, but no commands. For example, the following
7343 would cancel the rule that runs the assembler:
7349 @node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
7350 @section Defining Last-Resort Default Rules
7351 @cindex last-resort default rules
7352 @cindex default rules, last-resort
7354 You can define a last-resort implicit rule by writing a terminal
7355 match-anything pattern rule with no dependencies (@pxref{Match-Anything
7356 Rules}). This is just like any other pattern rule; the only thing
7357 special about it is that it will match any target. So such a rule's
7358 commands are used for all targets and dependencies that have no commands
7359 of their own and for which no other implicit rule applies.
7361 For example, when testing a makefile, you might not care if the source
7362 files contain real data, only that they exist. Then you might do this:
7370 to cause all the source files needed (as dependencies) to be created
7374 You can instead define commands to be used for targets for which there
7375 are no rules at all, even ones which don't specify commands. You do
7376 this by writing a rule for the target @code{.DEFAULT}. Such a rule's
7377 commands are used for all dependencies which do not appear as targets in
7378 any explicit rule, and for which no implicit rule applies. Naturally,
7379 there is no @code{.DEFAULT} rule unless you write one.
7381 If you use @code{.DEFAULT} with no commands or dependencies:
7388 the commands previously stored for @code{.DEFAULT} are cleared.
7389 Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
7391 If you do not want a target to get the commands from a match-anything
7392 pattern rule or @code{.DEFAULT}, but you also do not want any commands
7393 to be run for the target, you can give it empty commands (@pxref{Empty
7394 Commands, ,Defining Empty Commands}).@refill
7396 You can use a last-resort rule to override part of another makefile.
7397 @xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
7399 @node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
7400 @section Old-Fashioned Suffix Rules
7401 @cindex old-fashioned suffix rules
7404 @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
7405 @code{make}. Suffix rules are obsolete because pattern rules are more
7406 general and clearer. They are supported in GNU @code{make} for
7407 compatibility with old makefiles. They come in two kinds:
7408 @dfn{double-suffix} and @dfn{single-suffix}.@refill
7410 A double-suffix rule is defined by a pair of suffixes: the target suffix
7411 and the source suffix. It matches any file whose name ends with the
7412 target suffix. The corresponding implicit dependency is made by
7413 replacing the target suffix with the source suffix in the file name. A
7414 two-suffix rule whose target and source suffixes are @samp{.o} and
7415 @samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
7417 A single-suffix rule is defined by a single suffix, which is the source
7418 suffix. It matches any file name, and the corresponding implicit
7419 dependency name is made by appending the source suffix. A single-suffix
7420 rule whose source suffix is @samp{.c} is equivalent to the pattern rule
7423 Suffix rule definitions are recognized by comparing each rule's target
7424 against a defined list of known suffixes. When @code{make} sees a rule
7425 whose target is a known suffix, this rule is considered a single-suffix
7426 rule. When @code{make} sees a rule whose target is two known suffixes
7427 concatenated, this rule is taken as a double-suffix rule.
7429 For example, @samp{.c} and @samp{.o} are both on the default list of
7430 known suffixes. Therefore, if you define a rule whose target is
7431 @samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
7432 suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned
7433 way to define the rule for compiling a C source file:@refill
7437 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7440 Suffix rules cannot have any dependencies of their own. If they have any,
7441 they are treated as normal files with funny names, not as suffix rules.
7446 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7450 tells how to make the file @file{.c.o} from the dependency file
7451 @file{foo.h}, and is not at all like the pattern rule:
7455 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7459 which tells how to make @samp{.o} files from @samp{.c} files, and makes all
7460 @samp{.o} files using this pattern rule also depend on @file{foo.h}.
7462 Suffix rules with no commands are also meaningless. They do not remove
7463 previous rules as do pattern rules with no commands (@pxref{Canceling
7464 Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as
7465 a target in the data base.@refill
7468 The known suffixes are simply the names of the dependencies of the special
7469 target @code{.SUFFIXES}. You can add your own suffixes by writing a rule
7470 for @code{.SUFFIXES} that adds more dependencies, as in:
7473 .SUFFIXES: .hack .win
7477 which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
7479 If you wish to eliminate the default known suffixes instead of just adding
7480 to them, write a rule for @code{.SUFFIXES} with no dependencies. By
7481 special dispensation, this eliminates all existing dependencies of
7482 @code{.SUFFIXES}. You can then write another rule to add the suffixes you
7487 .SUFFIXES: # @r{Delete the default suffixes}
7488 .SUFFIXES: .c .o .h # @r{Define our suffix list}
7492 The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
7493 list of suffixes to be empty.
7496 The variable @code{SUFFIXES} is defined to the default list of suffixes
7497 before @code{make} reads any makefiles. You can change the list of suffixes
7498 with a rule for the special target @code{.SUFFIXES}, but that does not alter
7501 @node Search Algorithm, , Suffix Rules, Implicit Rules
7502 @section Implicit Rule Search Algorithm
7503 @cindex implicit rule, search algorithm
7504 @cindex search algorithm, implicit rule
7506 Here is the procedure @code{make} uses for searching for an implicit rule
7507 for a target @var{t}. This procedure is followed for each double-colon
7508 rule with no commands, for each target of ordinary rules none of which have
7509 commands, and for each dependency that is not the target of any rule. It
7510 is also followed recursively for dependencies that come from implicit
7511 rules, in the search for a chain of rules.
7513 Suffix rules are not mentioned in this algorithm because suffix rules are
7514 converted to equivalent pattern rules once the makefiles have been read in.
7516 For an archive member target of the form
7517 @samp{@var{archive}(@var{member})}, the following algorithm is run
7518 twice, first using the entire target name @var{t}, and second using
7519 @samp{(@var{member})} as the target @var{t} if the first run found no
7524 Split @var{t} into a directory part, called @var{d}, and the rest,
7525 called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then
7526 @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
7529 Make a list of all the pattern rules one of whose targets matches
7530 @var{t} or @var{n}. If the target pattern contains a slash, it is
7531 matched against @var{t}; otherwise, against @var{n}.
7534 If any rule in that list is @emph{not} a match-anything rule, then
7535 remove all nonterminal match-anything rules from the list.
7538 Remove from the list all rules with no commands.
7541 For each pattern rule in the list:
7545 Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
7546 matched by the @samp{%} in the target pattern.@refill
7549 Compute the dependency names by substituting @var{s} for @samp{%}; if
7550 the target pattern does not contain a slash, append @var{d} to
7551 the front of each dependency name.@refill
7554 Test whether all the dependencies exist or ought to exist. (If a
7555 file name is mentioned in the makefile as a target or as an explicit
7556 dependency, then we say it ought to exist.)
7558 If all dependencies exist or ought to exist, or there are no dependencies,
7559 then this rule applies.
7563 If no pattern rule has been found so far, try harder.
7564 For each pattern rule in the list:
7568 If the rule is terminal, ignore it and go on to the next rule.
7571 Compute the dependency names as before.
7574 Test whether all the dependencies exist or ought to exist.
7577 For each dependency that does not exist, follow this algorithm
7578 recursively to see if the dependency can be made by an implicit
7582 If all dependencies exist, ought to exist, or can be
7583 made by implicit rules, then this rule applies.
7587 If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
7588 applies. In that case, give @var{t} the same commands that
7589 @code{.DEFAULT} has. Otherwise, there are no commands for @var{t}.
7592 Once a rule that applies has been found, for each target pattern of the
7593 rule other than the one that matched @var{t} or @var{n}, the @samp{%} in
7594 the pattern is replaced with @var{s} and the resultant file name is stored
7595 until the commands to remake the target file @var{t} are executed. After
7596 these commands are executed, each of these stored file names are entered
7597 into the data base and marked as having been updated and having the same
7598 update status as the file @var{t}.
7600 When the commands of a pattern rule are executed for @var{t}, the automatic
7601 variables are set corresponding to the target and dependencies.
7602 @xref{Automatic, ,Automatic Variables}.
7604 @node Archives, Features, Implicit Rules, Top
7605 @chapter Using @code{make} to Update Archive Files
7608 @dfn{Archive files} are files containing named subfiles called
7609 @dfn{members}; they are maintained with the program @code{ar} and their
7610 main use is as subroutine libraries for linking.
7613 * Archive Members:: Archive members as targets.
7614 * Archive Update:: The implicit rule for archive member targets.
7615 * Archive Suffix Rules:: You can write a special kind of suffix rule
7616 for updating archives.
7619 @node Archive Members, Archive Update, , Archives
7620 @section Archive Members as Targets
7621 @cindex archive member targets
7623 An individual member of an archive file can be used as a target or
7624 dependency in @code{make}. You specify the member named @var{member} in
7625 archive file @var{archive} as follows:
7628 @var{archive}(@var{member})
7632 This construct is available only in targets and dependencies, not in
7633 commands! Most programs that you might use in commands do not support this
7634 syntax and cannot act directly on archive members. Only @code{ar} and
7635 other programs specifically designed to operate on archives can do so.
7636 Therefore, valid commands to update an archive member target probably must
7637 use @code{ar}. For example, this rule says to create a member
7638 @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
7641 foolib(hack.o) : hack.o
7645 In fact, nearly all archive member targets are updated in just this way
7646 and there is an implicit rule to do it for you. @strong{Note:} The
7647 @samp{c} flag to @code{ar} is required if the archive file does not
7650 To specify several members in the same archive, you can write all the
7651 member names together between the parentheses. For example:
7654 foolib(hack.o kludge.o)
7661 foolib(hack.o) foolib(kludge.o)
7664 @cindex wildcard, in archive member
7665 You can also use shell-style wildcards in an archive member reference.
7666 @xref{Wildcards, ,Using Wildcard Characters in File Names}. For
7667 example, @w{@samp{foolib(*.o)}} expands to all existing members of the
7668 @file{foolib} archive whose names end in @samp{.o}; perhaps
7669 @samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
7671 @node Archive Update, Archive Suffix Rules, Archive Members, Archives
7672 @section Implicit Rule for Archive Member Targets
7674 Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
7675 member named @var{m} in the archive file @var{a}.
7677 When @code{make} looks for an implicit rule for such a target, as a special
7678 feature it considers implicit rules that match @file{(@var{m})}, as well as
7679 those that match the actual target @file{@var{a}(@var{m})}.
7681 This causes one special rule whose target is @file{(%)} to match. This
7682 rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
7683 into the archive. For example, it will update the archive member target
7684 @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
7685 archive @file{foo.a} as a @emph{member} named @file{bar.o}.
7687 When this rule is chained with others, the result is very powerful.
7688 Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
7689 @samp{(} and @samp{)} from being interpreted specially by the shell) in
7690 the presence of a file @file{bar.c} is enough to cause the following
7691 commands to be run, even without a makefile:
7694 cc -c bar.c -o bar.o
7700 Here @code{make} has envisioned the file @file{bar.o} as an intermediate
7701 file. @xref{Chained Rules, ,Chains of Implicit Rules}.
7703 Implicit rules such as this one are written using the automatic variable
7704 @samp{$%}. @xref{Automatic, ,Automatic Variables}.
7706 An archive member name in an archive cannot contain a directory name, but
7707 it may be useful in a makefile to pretend that it does. If you write an
7708 archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
7709 automatic updating with this command:
7712 ar r foo.a dir/file.o
7716 which has the effect of copying the file @file{dir/file.o} into a member
7717 named @file{file.o}. In connection with such usage, the automatic variables
7718 @code{%D} and @code{%F} may be useful.
7721 * Archive Symbols:: How to update archive symbol directories.
7724 @node Archive Symbols, , , Archive Update
7725 @subsection Updating Archive Symbol Directories
7726 @cindex @code{__.SYMDEF}
7727 @cindex updating archive symbol directories
7728 @cindex archive symbol directory updating
7729 @cindex symbol directories, updating archive
7730 @cindex directories, updating archive symbol
7732 An archive file that is used as a library usually contains a special member
7733 named @file{__.SYMDEF} that contains a directory of the external symbol
7734 names defined by all the other members. After you update any other
7735 members, you need to update @file{__.SYMDEF} so that it will summarize the
7736 other members properly. This is done by running the @code{ranlib} program:
7739 ranlib @var{archivefile}
7742 Normally you would put this command in the rule for the archive file,
7743 and make all the members of the archive file dependencies of that rule.
7747 libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
7752 The effect of this is to update archive members @file{x.o}, @file{y.o},
7753 etc., and then update the symbol directory member @file{__.SYMDEF} by
7754 running @code{ranlib}. The rules for updating the members are not shown
7755 here; most likely you can omit them and use the implicit rule which copies
7756 files into the archive, as described in the preceding section.
7758 This is not necessary when using the GNU @code{ar} program, which
7759 updates the @file{__.SYMDEF} member automatically.
7761 @node Archive Suffix Rules, , Archive Update, Archives
7762 @section Suffix Rules for Archive Files
7763 @cindex suffix rule, for archive
7764 @cindex archive, suffix rule for
7765 @cindex library archive, suffix rule for
7766 @cindex @code{.a} (archives)
7768 You can write a special kind of suffix rule for dealing with archive
7769 files. @xref{Suffix Rules}, for a full explanation of suffix rules.
7770 Archive suffix rules are obsolete in GNU @code{make}, because pattern
7771 rules for archives are a more general mechanism (@pxref{Archive
7772 Update}). But they are retained for compatibility with other
7775 To write a suffix rule for archives, you simply write a suffix rule
7776 using the target suffix @samp{.a} (the usual suffix for archive files).
7777 For example, here is the old-fashioned suffix rule to update a library
7778 archive from C source files:
7783 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7790 This works just as if you had written the pattern rule:
7795 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7801 In fact, this is just what @code{make} does when it sees a suffix rule
7802 with @samp{.a} as the target suffix. Any double-suffix rule
7803 @w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
7804 pattern @samp{(%.o)} and a dependency pattern of @samp{%.@var{x}}.
7806 Since you might want to use @samp{.a} as the suffix for some other kind
7807 of file, @code{make} also converts archive suffix rules to pattern rules
7808 in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule
7809 @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
7810 @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
7812 @node Features, Missing, Archives, Top
7813 @chapter Features of GNU @code{make}
7814 @cindex features of GNU @code{make}
7816 @cindex compatibility
7818 Here is a summary of the features of GNU @code{make}, for comparison
7819 with and credit to other versions of @code{make}. We consider the
7820 features of @code{make} in 4.2 BSD systems as a baseline. If you are
7821 concerned with writing portable makefiles, you should use only the
7822 features of @code{make} @emph{not} listed here or in @ref{Missing}.
7824 Many features come from the version of @code{make} in System V.
7828 The @code{VPATH} variable and its special meaning.
7829 @xref{Directory Search, , Searching Directories for Dependencies}.
7830 This feature exists in System V @code{make}, but is undocumented.
7831 It is documented in 4.3 BSD @code{make} (which says it mimics System V's
7832 @code{VPATH} feature).@refill
7835 Included makefiles. @xref{Include, ,Including Other Makefiles}.
7836 Allowing multiple files to be included with a single directive is a GNU
7840 Variables are read from and communicated via the environment.
7841 @xref{Environment, ,Variables from the Environment}.
7844 Options passed through the variable @code{MAKEFLAGS} to recursive
7845 invocations of @code{make}.
7846 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
7849 The automatic variable @code{$%} is set to the member name
7850 in an archive reference. @xref{Automatic, ,Automatic Variables}.
7853 The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
7854 and @code{$?} have corresponding forms like @code{$(@@F)} and
7855 @code{$(@@D)}. We have generalized this to @code{$^} as an obvious
7856 extension. @xref{Automatic, ,Automatic Variables}.@refill
7859 Substitution variable references.
7860 @xref{Reference, ,Basics of Variable References}.
7863 The command-line options @samp{-b} and @samp{-m}, accepted and
7864 ignored. In System V @code{make}, these options actually do something.
7867 Execution of recursive commands to run @code{make} via the variable
7868 @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
7869 @xref{Recursion, ,Recursive Use of @code{make}}.
7872 Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix
7873 Rules}. This feature is obsolete in GNU @code{make}, because the
7874 general feature of rule chaining (@pxref{Chained Rules, ,Chains of
7875 Implicit Rules}) allows one pattern rule for installing members in an
7876 archive (@pxref{Archive Update}) to be sufficient.
7879 The arrangement of lines and backslash-newline combinations in
7880 commands is retained when the commands are printed, so they appear as
7881 they do in the makefile, except for the stripping of initial
7885 The following features were inspired by various other versions of
7886 @code{make}. In some cases it is unclear exactly which versions inspired
7891 Pattern rules using @samp{%}.
7892 This has been implemented in several versions of @code{make}.
7893 We're not sure who invented it first, but it's been spread around a bit.
7894 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
7897 Rule chaining and implicit intermediate files.
7898 This was implemented by Stu Feldman in his version of @code{make}
7899 for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
7900 AT&T Bell Labs in his @code{mk} program (where he terms it
7901 ``transitive closure''). We do not really know if
7902 we got this from either of them or thought it up ourselves at the
7903 same time. @xref{Chained Rules, ,Chains of Implicit Rules}.
7906 The automatic variable @code{$^} containing a list of all dependencies
7907 of the current target. We did not invent this, but we have no idea who did.
7908 @xref{Automatic, ,Automatic Variables}.
7911 The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
7912 invented by Andrew Hume in @code{mk}.
7913 @xref{Instead of Execution, ,Instead of Executing the Commands}.
7916 The concept of doing several things at once (parallelism) exists in
7917 many incarnations of @code{make} and similar programs, though not in the
7918 System V or BSD implementations. @xref{Execution, ,Command Execution}.
7921 Modified variable references using pattern substitution come from
7922 SunOS 4. @xref{Reference, ,Basics of Variable References}.
7923 This functionality was provided in GNU @code{make} by the
7924 @code{patsubst} function before the alternate syntax was implemented
7925 for compatibility with SunOS 4. It is not altogether clear who
7926 inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
7927 4 was released.@refill
7930 The special significance of @samp{+} characters preceding command lines
7931 (@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
7933 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
7936 The @samp{+=} syntax to append to the value of a variable comes from SunOS
7937 4 @code{make}. @xref{Appending, , Appending More Text to Variables}.
7940 The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
7941 multiple members in a single archive file comes from SunOS 4 @code{make}.
7942 @xref{Archive Members}.
7945 The @code{-include} directive to include makefiles with no error for a
7946 nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4
7947 @code{make} does not allow multiple makefiles to be specified in one
7948 @code{-include} directive.)
7951 The remaining features are inventions new in GNU @code{make}:
7955 Use the @samp{-v} or @samp{--version} option to print version and
7956 copyright information.
7959 Use the @samp{-h} or @samp{--help} option to summarize the options to
7963 Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}.
7966 Pass command-line variable assignments automatically through the
7967 variable @code{MAKE} to recursive @code{make} invocations.
7968 @xref{Recursion, ,Recursive Use of @code{make}}.
7971 Use the @samp{-C} or @samp{--directory} command option to change
7972 directory. @xref{Options Summary, ,Summary of Options}.
7975 Make verbatim variable definitions with @code{define}.
7976 @xref{Defining, ,Defining Variables Verbatim}.
7979 Declare phony targets with the special target @code{.PHONY}.
7981 Andrew Hume of AT&T Bell Labs implemented a similar feature with a
7982 different syntax in his @code{mk} program. This seems to be a case of
7983 parallel discovery. @xref{Phony Targets, ,Phony Targets}.
7986 Manipulate text by calling functions.
7987 @xref{Functions, ,Functions for Transforming Text}.
7990 Use the @samp{-o} or @samp{--old-file}
7991 option to pretend a file's modification-time is old.
7992 @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
7995 Conditional execution.
7997 This feature has been implemented numerous times in various versions
7998 of @code{make}; it seems a natural extension derived from the features
7999 of the C preprocessor and similar macro languages and is not a
8000 revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}.
8003 Specify a search path for included makefiles.
8004 @xref{Include, ,Including Other Makefiles}.
8007 Specify extra makefiles to read with an environment variable.
8008 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
8011 Strip leading sequences of @samp{./} from file names, so that
8012 @file{./@var{file}} and @file{@var{file}} are considered to be the
8016 Use a special search method for library dependencies written in the
8017 form @samp{-l@var{name}}.
8018 @xref{Libraries/Search, ,Directory Search for Link Libraries}.
8021 Allow suffixes for suffix rules
8022 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
8023 characters. In other versions of @code{make}, they must begin with
8024 @samp{.} and not contain any @samp{/} characters.
8027 Keep track of the current level of @code{make} recursion using the
8028 variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}.
8031 Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}.
8034 Provide selective @code{vpath} search.
8035 @xref{Directory Search, ,Searching Directories for Dependencies}.
8038 Provide computed variable references.
8039 @xref{Reference, ,Basics of Variable References}.
8042 Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
8043 System V @code{make} has a very, very limited form of this
8044 functionality in that it will check out SCCS files for makefiles.
8047 Various new built-in implicit rules.
8048 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules}.
8051 The built-in variable @samp{MAKE_VERSION} gives the version number of
8055 @node Missing, Makefile Conventions, Features, Top
8056 @chapter Incompatibilities and Missing Features
8057 @cindex incompatibilities
8058 @cindex missing features
8059 @cindex features, missing
8061 The @code{make} programs in various other systems support a few features
8062 that are not implemented in GNU @code{make}. The POSIX.2 standard
8063 (@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
8064 require any of these features.@refill
8068 A target of the form @samp{@var{file}((@var{entry}))} stands for a member
8069 of archive file @var{file}. The member is chosen, not by name, but by
8070 being an object file which defines the linker symbol @var{entry}.@refill
8072 This feature was not put into GNU @code{make} because of the
8073 nonmodularity of putting knowledge into @code{make} of the internal
8074 format of archive file symbol tables.
8075 @xref{Archive Symbols, ,Updating Archive Symbol Directories}.
8078 Suffixes (used in suffix rules) that end with the character @samp{~}
8079 have a special meaning to System V @code{make};
8080 they refer to the SCCS file that corresponds
8081 to the file one would get without the @samp{~}. For example, the
8082 suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
8083 the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole
8084 series of such suffix rules is required.
8085 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
8087 In GNU @code{make}, this entire series of cases is handled by two
8088 pattern rules for extraction from SCCS, in combination with the
8089 general feature of rule chaining.
8090 @xref{Chained Rules, ,Chains of Implicit Rules}.
8093 In System V @code{make}, the string @samp{$$@@} has the strange meaning
8094 that, in the dependencies of a rule with multiple targets, it stands
8095 for the particular target that is being processed.
8097 This is not defined in GNU @code{make} because @samp{$$} should always
8098 stand for an ordinary @samp{$}.
8100 It is possible to get this functionality through the use of static pattern
8101 rules (@pxref{Static Pattern, ,Static Pattern Rules}).
8102 The System V @code{make} rule:
8105 $(targets): $$@@.o lib.a
8109 can be replaced with the GNU @code{make} static pattern rule:
8112 $(targets): %: %.o lib.a
8116 In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
8117 (@pxref{Directory Search, ,Searching Directories for Dependencies}) have their names changed inside command
8118 strings. We feel it is much cleaner to always use automatic variables
8119 and thus make this feature obsolete.@refill
8122 In some Unix @code{make}s, the automatic variable @code{$*} appearing in
8123 the dependencies of a rule has the amazingly strange ``feature'' of
8124 expanding to the full name of the @emph{target of that rule}. We cannot
8125 imagine what went on in the minds of Unix @code{make} developers to do
8126 this; it is utterly inconsistent with the normal definition of @code{$*}.
8127 @vindex * @r{(automatic variable), unsupported bizarre usage}
8130 In some Unix @code{make}s, implicit rule search
8131 (@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for
8132 @emph{all} targets, not just those without commands. This means you can
8143 and Unix @code{make} will intuit that @file{foo.o} depends on
8144 @file{foo.c}.@refill
8146 We feel that such usage is broken. The dependency properties of
8147 @code{make} are well-defined (for GNU @code{make}, at least),
8148 and doing such a thing simply does not fit the model.@refill
8151 GNU @code{make} does not include any built-in implicit rules for
8152 compiling or preprocessing EFL programs. If we hear of anyone who is
8153 using EFL, we will gladly add them.
8156 It appears that in SVR4 @code{make}, a suffix rule can be specified with
8157 no commands, and it is treated as if it had empty commands
8158 (@pxref{Empty Commands}). For example:
8165 will override the built-in @file{.c.a} suffix rule.
8167 We feel that it is cleaner for a rule without commands to always simply
8168 add to the dependency list for the target. The above example can be
8169 easily rewritten to get the desired behavior in GNU @code{make}:
8176 Some versions of @code{make} invoke the shell with the @samp{-e} flag,
8177 except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
8178 Program}). The @samp{-e} flag tells the shell to exit as soon as any
8179 program it runs returns a nonzero status. We feel it is cleaner to
8180 write each shell command line to stand on its own and not require this
8184 @comment The makefile standards are in a separate file that is also
8185 @comment included by standards.texi.
8186 @include make-stds.texi
8188 @node Quick Reference, Complex Makefile, Makefile Conventions, Top
8189 @appendix Quick Reference
8191 This appendix summarizes the directives, text manipulation functions,
8192 and special variables which GNU @code{make} understands.
8193 @xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
8194 and @ref{Options Summary, ,Summary of Options},
8195 for other summaries.
8197 Here is a summary of the directives GNU @code{make} recognizes:
8200 @item define @var{variable}
8203 Define a multi-line, recursively-expanded variable.@*
8206 @item ifdef @var{variable}
8207 @itemx ifndef @var{variable}
8208 @itemx ifeq (@var{a},@var{b})
8209 @itemx ifeq "@var{a}" "@var{b}"
8210 @itemx ifeq '@var{a}' '@var{b}'
8211 @itemx ifneq (@var{a},@var{b})
8212 @itemx ifneq "@var{a}" "@var{b}"
8213 @itemx ifneq '@var{a}' '@var{b}'
8217 Conditionally evaluate part of the makefile.@*
8218 @xref{Conditionals}.
8220 @item include @var{file}
8222 Include another makefile.@*
8223 @xref{Include, ,Including Other Makefiles}.
8225 @item override @var{variable} = @var{value}
8226 @itemx override @var{variable} := @var{value}
8227 @itemx override @var{variable} += @var{value}
8228 @itemx override define @var{variable}
8231 Define a variable, overriding any previous definition, even one from
8233 @xref{Override Directive, ,The @code{override} Directive}.
8237 Tell @code{make} to export all variables to child processes by default.@*
8238 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8240 @item export @var{variable}
8241 @itemx export @var{variable} = @var{value}
8242 @itemx export @var{variable} := @var{value}
8243 @itemx export @var{variable} += @var{value}
8244 @itemx unexport @var{variable}
8245 Tell @code{make} whether or not to export a particular variable to child
8247 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8249 @item vpath @var{pattern} @var{path}
8250 Specify a search path for files matching a @samp{%} pattern.@*
8251 @xref{Selective Search, , The @code{vpath} Directive}.
8253 @item vpath @var{pattern}
8254 Remove all search paths previously specified for @var{pattern}.
8257 Remove all search paths previously specified in any @code{vpath}
8261 Here is a summary of the text manipulation functions (@pxref{Functions}):
8264 @item $(subst @var{from},@var{to},@var{text})
8265 Replace @var{from} with @var{to} in @var{text}.@*
8266 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8268 @item $(patsubst @var{pattern},@var{replacement},@var{text})
8269 Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
8270 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8272 @item $(strip @var{string})
8273 Remove excess whitespace characters from @var{string}.@*
8274 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8276 @item $(findstring @var{find},@var{text})
8277 Locate @var{find} in @var{text}.@*
8278 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8280 @item $(filter @var{pattern}@dots{},@var{text})
8281 Select words in @var{text} that match one of the @var{pattern} words.@*
8282 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8284 @item $(filter-out @var{pattern}@dots{},@var{text})
8285 Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
8286 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8288 @item $(sort @var{list})
8289 Sort the words in @var{list} lexicographically, removing duplicates.@*
8290 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8292 @item $(dir @var{names}@dots{})
8293 Extract the directory part of each file name.@*
8294 @xref{Filename Functions, ,Functions for File Names}.
8296 @item $(notdir @var{names}@dots{})
8297 Extract the non-directory part of each file name.@*
8298 @xref{Filename Functions, ,Functions for File Names}.
8300 @item $(suffix @var{names}@dots{})
8301 Extract the suffix (the last @samp{.} and following characters) of each file name.@*
8302 @xref{Filename Functions, ,Functions for File Names}.
8304 @item $(basename @var{names}@dots{})
8305 Extract the base name (name without suffix) of each file name.@*
8306 @xref{Filename Functions, ,Functions for File Names}.
8308 @item $(addsuffix @var{suffix},@var{names}@dots{})
8309 Append @var{suffix} to each word in @var{names}.@*
8310 @xref{Filename Functions, ,Functions for File Names}.
8312 @item $(addprefix @var{prefix},@var{names}@dots{})
8313 Prepend @var{prefix} to each word in @var{names}.@*
8314 @xref{Filename Functions, ,Functions for File Names}.
8316 @item $(join @var{list1},@var{list2})
8317 Join two parallel lists of words.@*
8318 @xref{Filename Functions, ,Functions for File Names}.
8320 @item $(word @var{n},@var{text})
8321 Extract the @var{n}th word (one-origin) of @var{text}.@*
8322 @xref{Filename Functions, ,Functions for File Names}.
8324 @item $(words @var{text})
8325 Count the number of words in @var{text}.@*
8326 @xref{Filename Functions, ,Functions for File Names}.
8328 @item $(firstword @var{names}@dots{})
8329 Extract the first word of @var{names}.@*
8330 @xref{Filename Functions, ,Functions for File Names}.
8332 @item $(wildcard @var{pattern}@dots{})
8333 Find file names matching a shell file name pattern (@emph{not} a
8334 @samp{%} pattern).@*
8335 @xref{Wildcard Function, ,The Function @code{wildcard}}.
8337 @item $(shell @var{command})
8339 Execute a shell command and return its output.@*
8340 @xref{Shell Function, , The @code{shell} Function}.
8342 @item $(origin @var{variable})
8344 Return a string describing how the @code{make} variable @var{variable} was
8346 @xref{Origin Function, , The @code{origin} Function}.
8348 @item $(foreach @var{var},@var{words},@var{text})
8350 Evaluate @var{text} with @var{var} bound to each word in @var{words},
8351 and concatenate the results.@*
8352 @xref{Foreach Function, ,The @code{foreach} Function}.
8355 Here is a summary of the automatic variables.
8356 @xref{Automatic, ,Automatic Variables},
8357 for full information.
8361 The file name of the target.
8364 The target member name, when the target is an archive member.
8367 The name of the first dependency.
8370 The names of all the dependencies that are
8371 newer than the target, with spaces between them.
8372 For dependencies which are archive members, only
8373 the member named is used (@pxref{Archives}).
8376 The names of all the dependencies, with spaces between them. For
8377 dependencies which are archive members, only the member named is used
8381 The stem with which an implicit rule matches
8382 (@pxref{Pattern Match, ,How Patterns Match}).
8386 The directory part and the file-within-directory part of @code{$@@}.
8390 The directory part and the file-within-directory part of @code{$*}.
8394 The directory part and the file-within-directory part of @code{$%}.
8398 The directory part and the file-within-directory part of @code{$<}.
8402 The directory part and the file-within-directory part of @code{$^}.
8406 The directory part and the file-within-directory part of @code{$?}.
8409 These variables are used specially by GNU @code{make}:
8414 Makefiles to be read on every invocation of @code{make}.@*
8415 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
8419 Directory search path for files not found in the current directory.@*
8420 @xref{General Search, , @code{VPATH} Search Path for All Dependencies}.
8424 The name of the system default command interpreter, usually @file{/bin/sh}.
8425 You can set @code{SHELL} in the makefile to change the shell used to run
8426 commands. @xref{Execution, ,Command Execution}.
8430 The name with which @code{make} was invoked.
8431 Using this variable in commands has special meaning.
8432 @xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.
8436 The number of levels of recursion (sub-@code{make}s).@*
8437 @xref{Variables/Recursion}.
8441 The flags given to @code{make}. You can set this in the environment or
8442 a makefile to set flags.@*
8443 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
8447 The default list of suffixes before @code{make} reads any makefiles.
8450 @node Complex Makefile, Concept Index, Quick Reference, Top
8451 @appendix Complex Makefile Example
8453 Here is the makefile for the GNU @code{tar} program. This is a
8454 moderately complex makefile.
8456 Because it is the first target, the default goal is @samp{all}. An
8457 interesting feature of this makefile is that @file{testpad.h} is a
8458 source file automatically created by the @code{testpad} program,
8459 itself compiled from @file{testpad.c}.
8461 If you type @samp{make} or @samp{make all}, then @code{make} creates
8462 the @file{tar} executable, the @file{rmt} daemon that provides
8463 remote tape access, and the @file{tar.info} Info file.
8465 If you type @samp{make install}, then @code{make} not only creates
8466 @file{tar}, @file{rmt}, and @file{tar.info}, but also installs
8469 If you type @samp{make clean}, then @code{make} removes the @samp{.o}
8470 files, and the @file{tar}, @file{rmt}, @file{testpad},
8471 @file{testpad.h}, and @file{core} files.
8473 If you type @samp{make distclean}, then @code{make} not only removes
8474 the same files as does @samp{make clean} but also the
8475 @file{TAGS}, @file{Makefile}, and @file{config.status} files.
8476 (Although it is not evident, this makefile (and
8477 @file{config.status}) is generated by the user with the
8478 @code{configure} program, which is provided in the @code{tar}
8479 distribution, but is not shown here.)
8481 If you type @samp{make realclean}, then @code{make} removes the same
8482 files as does @samp{make distclean} and also removes the Info files
8483 generated from @file{tar.texinfo}.
8485 In addition, there are targets @code{shar} and @code{dist} that create
8490 # Generated automatically from Makefile.in by configure.
8491 # Un*x Makefile for GNU tar program.
8492 # Copyright (C) 1991 Free Software Foundation, Inc.
8496 # This program is free software; you can redistribute
8497 # it and/or modify it under the terms of the GNU
8498 # General Public License @dots{}
8505 #### Start of system configuration section. ####
8510 # If you use gcc, you should either run the
8511 # fixincludes script that comes with it or else use
8512 # gcc with the -traditional option. Otherwise ioctl
8513 # calls will be compiled incorrectly on some systems.
8516 INSTALL = /usr/local/bin/install -c
8517 INSTALLDATA = /usr/local/bin/install -c -m 644
8520 # Things you might add to DEFS:
8521 # -DSTDC_HEADERS If you have ANSI C headers and
8523 # -DPOSIX If you have POSIX.1 headers and
8525 # -DBSD42 If you have sys/dir.h (unless
8526 # you use -DPOSIX), sys/file.h,
8527 # and st_blocks in `struct stat'.
8528 # -DUSG If you have System V/ANSI C
8529 # string and memory functions
8530 # and headers, sys/sysmacros.h,
8531 # fcntl.h, getcwd, no valloc,
8532 # and ndir.h (unless
8533 # you use -DDIRENT).
8534 # -DNO_MEMORY_H If USG or STDC_HEADERS but do not
8536 # -DDIRENT If USG and you have dirent.h
8537 # instead of ndir.h.
8538 # -DSIGTYPE=int If your signal handlers
8539 # return int, not void.
8540 # -DNO_MTIO If you lack sys/mtio.h
8542 # -DNO_REMOTE If you do not have a remote shell
8544 # -DUSE_REXEC To use rexec for remote tape
8545 # operations instead of
8546 # forking rsh or remsh.
8547 # -DVPRINTF_MISSING If you lack vprintf function
8548 # (but have _doprnt).
8549 # -DDOPRNT_MISSING If you lack _doprnt function.
8550 # Also need to define
8551 # -DVPRINTF_MISSING.
8552 # -DFTIME_MISSING If you lack ftime system call.
8553 # -DSTRSTR_MISSING If you lack strstr function.
8554 # -DVALLOC_MISSING If you lack valloc function.
8555 # -DMKDIR_MISSING If you lack mkdir and
8556 # rmdir system calls.
8557 # -DRENAME_MISSING If you lack rename system call.
8558 # -DFTRUNCATE_MISSING If you lack ftruncate
8560 # -DV7 On Version 7 Unix (not
8561 # tested in a long time).
8562 # -DEMUL_OPEN3 If you lack a 3-argument version
8563 # of open, and want to emulate it
8564 # with system calls you do have.
8565 # -DNO_OPEN3 If you lack the 3-argument open
8566 # and want to disable the tar -k
8567 # option instead of emulating open.
8568 # -DXENIX If you have sys/inode.h
8569 # and need it 94 to be included.
8571 DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
8572 -DVPRINTF_MISSING -DBSD42
8573 # Set this to rtapelib.o unless you defined NO_REMOTE,
8574 # in which case make it empty.
8575 RTAPELIB = rtapelib.o
8577 DEF_AR_FILE = /dev/rmt8
8582 CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
8583 -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
8584 -DDEFBLOCKING=$(DEFBLOCKING)
8590 # Prefix for each installed program,
8591 # normally empty or `g'.
8594 # The directory to install tar in.
8595 bindir = $(prefix)/bin
8597 # The directory to install the info files in.
8598 infodir = $(prefix)/info
8601 #### End of system configuration section. ####
8603 SRC1 = tar.c create.c extract.c buffer.c \
8604 getoldopt.c update.c gnu.c mangle.c
8605 SRC2 = version.c list.c names.c diffarch.c \
8606 port.c wildmat.c getopt.c
8607 SRC3 = getopt1.c regex.c getdate.y
8608 SRCS = $(SRC1) $(SRC2) $(SRC3)
8609 OBJ1 = tar.o create.o extract.o buffer.o \
8610 getoldopt.o update.o gnu.o mangle.o
8611 OBJ2 = version.o list.o names.o diffarch.o \
8612 port.o wildmat.o getopt.o
8613 OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB)
8614 OBJS = $(OBJ1) $(OBJ2) $(OBJ3)
8616 AUX = README COPYING ChangeLog Makefile.in \
8617 makefile.pc configure configure.in \
8618 tar.texinfo tar.info* texinfo.tex \
8619 tar.h port.h open3.h getopt.h regex.h \
8620 rmt.h rmt.c rtapelib.c alloca.c \
8621 msd_dir.h msd_dir.c tcexparg.c \
8622 level-0 level-1 backup-specs testpad.c
8625 all: tar rmt tar.info
8629 $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
8634 $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
8638 tar.info: tar.texinfo
8639 makeinfo tar.texinfo
8644 $(INSTALL) tar $(bindir)/$(binprefix)tar
8645 -test ! -f rmt || $(INSTALL) rmt /etc/rmt
8646 $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
8650 $(OBJS): tar.h port.h testpad.h
8651 regex.o buffer.o tar.o: regex.h
8652 # getdate.y has 8 shift/reduce conflicts.
8662 $(CC) -o $@@ testpad.o
8672 rm -f *.o tar rmt testpad testpad.h core
8677 rm -f TAGS Makefile config.status
8681 realclean: distclean
8686 shar: $(SRCS) $(AUX)
8687 shar $(SRCS) $(AUX) | compress \
8688 > tar-`sed -e '/version_string/!d' \
8689 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8695 dist: $(SRCS) $(AUX)
8697 -e '/version_string/!d' \
8698 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8701 -rm -rf `cat .fname`
8703 ln $(SRCS) $(AUX) `cat .fname`
8704 -rm -rf `cat .fname` .fname
8705 tar chZf `cat .fname`.tar.Z `cat .fname`
8709 tar.zoo: $(SRCS) $(AUX)
8713 for X in $(SRCS) $(AUX) ; do \
8715 sed 's/$$/^M/' $$X \
8716 > tmp.dir/$$X ; done
8717 cd tmp.dir ; zoo aM ../tar.zoo *
8722 @node Concept Index, Name Index, Complex Makefile, Top
8723 @unnumbered Index of Concepts
8727 @node Name Index, , Concept Index, Top
8728 @unnumbered Index of Functions, Variables, & Directives