1 \input texinfo @c -*- Texinfo -*-
4 @settitle GNU @code{make}
8 @c For publication, format makebook.texi instead of using this file directly.
11 @set VERSION 3.69 Beta
12 @set UPDATED 1 August 1993
13 @set UPDATE-MONTH August 1993
17 @c ISPELL CHECK: done, 10 June 1993 --roland
19 @c Combine the variable and function indices:
21 @c Combine the program and concept indices:
25 This file documents the GNU Make utility, which determines
26 automatically which pieces of a large program need to be recompiled,
27 and issues the commands to recompile them.
29 This is Edition @value{EDITION}, last updated @value{UPDATED},
30 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
32 Copyright (C) 1988, '89, '90, '91, '92, '93 Free Software Foundation, Inc.
34 Permission is granted to make and distribute verbatim copies of
35 this manual provided the copyright notice and this permission notice
36 are preserved on all copies.
39 Permission is granted to process this file through TeX and print the
40 results, provided the printed document carries copying permission
41 notice identical to this one except for the removal of this paragraph
42 (this paragraph not being relevant to the printed manual).
45 Permission is granted to copy and distribute modified versions of this
46 manual under the conditions for verbatim copying, provided that the entire
47 resulting derived work is distributed under the terms of a permission
48 notice identical to this one.
50 Permission is granted to copy and distribute translations of this manual
51 into another language, under the above conditions for modified versions,
52 except that this permission notice may be stated in a translation approved
53 by the Free Software Foundation.
57 @shorttitlepage GNU Make
61 @subtitle A Program for Directing Recompilation
62 @subtitle Edition @value{EDITION}, for @code{make} Version @value{VERSION}.
63 @subtitle @value{UPDATE-MONTH}
64 @author Richard M. Stallman and Roland McGrath
66 @vskip 0pt plus 1filll
67 Copyright @copyright{} 1988, '89, '90, '91, '92, '93 Free Software Foundation, Inc.
69 Published by the Free Software Foundation @*
70 675 Massachusetts Avenue, @*
71 Cambridge, MA 02139 USA @*
72 Printed copies are available for $20 each. @*
75 Permission is granted to make and distribute verbatim copies of
76 this manual provided the copyright notice and this permission notice
77 are preserved on all copies.
79 Permission is granted to copy and distribute modified versions of this
80 manual under the conditions for verbatim copying, provided that the entire
81 resulting derived work is distributed under the terms of a permission
82 notice identical to this one.
84 Permission is granted to copy and distribute translations of this manual
85 into another language, under the above conditions for modified versions,
86 except that this permission notice may be stated in a translation approved
87 by the Free Software Foundation.
89 Cover art by Etienne Suvasa.
94 @node Top, Overview, (dir), (dir)
97 The GNU @code{make} utility automatically determines which pieces of a
98 large program need to be recompiled, and issues the commands to
99 recompile them.@refill
101 This is Edition @value{EDITION} of the @cite{GNU Make Manual},
102 last updated @value{UPDATED}
103 for @code{make} Version @value{VERSION}.@refill
105 This manual describes @code{make} and contains the following chapters:@refill
109 * Overview:: Overview of @code{make}.
110 * Introduction:: An introduction to @code{make}.
111 * Makefiles:: Makefiles tell @code{make} what to do.
112 * Rules:: Rules describe when a file must be remade.
113 * Commands:: Commands say how to remake a file.
114 * Using Variables:: You can use variables to avoid repetition.
115 * Conditionals:: Use or ignore parts of the makefile based
116 on the values of variables.
117 * Functions:: Many powerful ways to manipulate text.
118 * make Invocation: Running. How to invoke @code{make} on the command line.
119 * Implicit Rules:: Use implicit rules to treat many files alike,
120 based on their file names.
121 * Archives:: How @code{make} can update library archives.
122 * Features:: Features GNU @code{make} has over other @code{make}s.
123 * Missing:: What GNU @code{make} lacks from other @code{make}s.
124 * Makefile Conventions:: Conventions for makefiles in GNU programs.
125 * Quick Reference:: A quick reference for experienced users.
126 * Complex Makefile:: A real example of a straightforward,
127 but nontrivial, makefile.
128 * Concept Index:: Index of Concepts
129 * Name Index:: Index of Functions, Variables, & Directives
131 --- The Detailed Node Listing ---
133 Overview of @code{make}
135 * Preparing:: Preparing and Running Make
136 * Reading:: On Reading this Text
137 * Bugs:: Problems and Bugs
139 An Introduction to Makefiles
141 * Rule Introduction:: What a rule looks like.
142 * Simple Makefile:: A Simple Makefile
143 * How Make Works:: How @code{make} Processes This Makefile
144 * Variables Simplify:: Variables Make Makefiles Simpler
145 * make Deduces:: Letting @code{make} Deduce the Commands
146 * Combine By Dependency:: Another Style of Makefile
147 * Cleanup:: Rules for Cleaning the Directory
151 * Makefile Contents:: What makefiles contain.
152 * Makefile Names:: How to name your makefile.
153 * Include:: How one makefile can use another makefile.
154 * MAKEFILES Variable:: The environment can specify extra makefiles.
155 * Remaking Makefiles:: How makefiles get remade.
156 * Overriding Makefiles:: How to override part of one makefile
157 with another makefile.
161 * Rule Example:: An example explained.
162 * Rule Syntax:: General syntax explained.
163 * Wildcards:: Using wildcard characters such as `*'.
164 * Directory Search:: Searching other directories for source files.
165 * Phony Targets:: Using a target that is not a real file's name.
166 * Force Targets:: You can use a target without commands
167 or dependencies to mark other
169 * Empty Targets:: When only the date matters and the
171 * Special Targets:: Targets with special built-in meanings.
172 * Multiple Targets:: When to make use of several targets in a rule.
173 * Multiple Rules:: How to use several rules with the same target.
174 * Static Pattern:: Static pattern rules apply to multiple targets
175 and can vary the dependencies according to
177 * Double-Colon:: How to use a special kind of rule to allow
178 several independent rules for one target.
179 * Automatic Dependencies:: How to automatically generate rules giving
180 dependencies from the source files themselves.
182 Using Wildcard Characters in File Names
184 * Wildcard Examples:: Several examples
185 * Wildcard Pitfall:: Problems to avoid.
186 * Wildcard Function:: How to cause wildcard expansion where
187 it does not normally take place.
189 Searching Directories for Dependencies
191 * General Search:: Specifying a search path that applies
193 * Selective Search:: Specifying a search path
194 for a specified class of names.
195 * Commands/Search:: How to write shell commands that work together
197 * Implicit/Search:: How search paths affect implicit rules.
198 * Libraries/Search:: Directory search for link libraries.
202 * Static Usage:: The syntax of static pattern rules.
203 * Static versus Implicit:: When are they better than implicit rules?
205 Writing the Commands in Rules
207 * Echoing:: How to control when commands are echoed.
208 * Execution:: How commands are executed.
209 * Parallel:: How commands can be executed in parallel.
210 * Errors:: What happens after a command execution error.
211 * Interrupts:: What happens when a command is interrupted.
212 * Recursion:: Invoking @code{make} from makefiles.
213 * Sequences:: Defining canned sequences of commands.
214 * Empty Commands:: Defining useful, do-nothing commands.
216 Recursive Use of @code{make}
218 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
219 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
220 * Options/Recursion:: How to communicate options to a sub-@code{make}.
221 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
222 helps debug use of recursive @code{make} commands.
226 * Reference:: How to use the value of a variable.
227 * Flavors:: Variables come in two flavors.
228 * Advanced:: Advanced features for referencing a variable.
229 * Values:: All the ways variables get their values.
230 * Setting:: How to set a variable in the makefile.
231 * Appending:: How to append more text to the old value
233 * Override Directive:: How to set a variable in the makefile even if
234 the user has set it with a command argument.
235 * Defining:: An alternate way to set a variable
236 to a verbatim string.
237 * Environment:: Variable values can come from the environment.
239 Advanced Features for Reference to Variables
241 * Substitution Refs:: Referencing a variable with
242 substitutions on the value.
243 * Computed Names:: Computing the name of the variable to refer to.
245 Conditional Parts of Makefiles
247 * Conditional Example:: Example of a conditional
248 * Conditional Syntax:: The syntax of conditionals.
249 * Testing Flags:: Conditionals that test flags.
251 Functions for Transforming Text
253 * Syntax of Functions:: How to write a function call.
254 * Text Functions:: General-purpose text manipulation functions.
255 * Filename Functions:: Functions for manipulating file names.
256 * Foreach Function:: Repeat some text with controlled variation.
257 * Origin Function:: Find where a variable got its value.
258 * Shell Function:: Substitute the output of a shell command.
260 How to Run @code{make}
262 * Makefile Arguments:: How to specify which makefile to use.
263 * Goals:: How to use goal arguments to specify which
264 parts of the makefile to use.
265 * Instead of Execution:: How to use mode flags to specify what
266 kind of thing to do with the commands
267 in the makefile other than simply
269 * Avoiding Compilation:: How to avoid recompiling certain files.
270 * Overriding:: How to override a variable to specify
271 an alternate compiler and other things.
272 * Testing:: How to proceed past some errors, to
274 * Options Summary:: Summary of Options
278 * Using Implicit:: How to use an existing implicit rule
279 to get the commands for updating a file.
280 * Catalogue of Rules:: A list of built-in implicit rules.
281 * Implicit Variables:: How to change what predefined rules do.
282 * Chained Rules:: How to use a chain of implicit rules.
283 * Pattern Rules:: How to define new implicit rules.
284 * Last Resort:: How to defining commands for rules
285 which cannot find any.
286 * Suffix Rules:: The old-fashioned style of implicit rule.
287 * Search Algorithm:: The precise algorithm for applying
290 Defining and Redefining Pattern Rules
292 * Pattern Intro:: An introduction to pattern rules.
293 * Pattern Examples:: Examples of pattern rules.
294 * Automatic:: How to use automatic variables in the
295 commands of implicit rules.
296 * Pattern Match:: How patterns match.
297 * Match-Anything Rules:: Precautions you should take prior to
298 defining rules that can match any
299 target file whatever.
300 * Canceling Rules:: How to override or cancel built-in rules.
302 Using @code{make} to Update Archive Files
304 * Archive Members:: Archive members as targets.
305 * Archive Update:: The implicit rule for archive member targets.
306 * Archive Suffix Rules:: You can write a special kind of suffix rule
307 for updating archives.
309 Implicit Rule for Archive Member Targets
311 * Archive Symbols:: How to update archive symbol directories.
314 @node Overview, Introduction, Top, Top
315 @comment node-name, next, previous, up
316 @chapter Overview of @code{make}
318 The @code{make} utility automatically determines which pieces of a large
319 program need to be recompiled, and issues commands to recompile them.
320 This manual describes GNU @code{make}, which was implemented by Richard
321 Stallman and Roland McGrath. GNU @code{make} conforms to section 6.2 of
322 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
324 @cindex IEEE Standard 1003.2
325 @cindex standards conformance
327 Our examples show C programs, since they are most common, but you can use
328 @code{make} with any programming language whose compiler can be run with a
329 shell command. Indeed, @code{make} is not limited to programs. You can
330 use it to describe any task where some files must be updated automatically
331 from others whenever the others change.
334 * Preparing:: Preparing and Running Make
335 * Reading:: On Reading this Text
336 * Bugs:: Problems and Bugs
339 @node Preparing, Reading, , Overview
341 @heading Preparing and Running Make
344 To prepare to use @code{make}, you must write a file called
345 the @dfn{makefile} that describes the relationships among files
346 in your program and provides commands for updating each file.
347 In a program, typically, the executable file is updated from object
348 files, which are in turn made by compiling source files.@refill
350 Once a suitable makefile exists, each time you change some source files,
351 this simple shell command:
358 suffices to perform all necessary recompilations. The @code{make} program
359 uses the makefile data base and the last-modification times of the files to
360 decide which of the files need to be updated. For each of those files, it
361 issues the commands recorded in the data base.
363 You can provide command line arguments to @code{make} to control which
364 files should be recompiled, or how. @xref{Running, ,How to Run
367 @node Reading, Bugs, Preparing, Overview
368 @section How to Read This Manual
370 If you are new to @code{make}, or are looking for a general
371 introduction, read the first few sections of each chapter, skipping the
372 later sections. In each chapter, the first few sections contain
373 introductory or general information and the later sections contain
374 specialized or technical information.
376 The exception is the second chapter, @ref{Introduction, ,An
377 Introduction to Makefiles}, all of which is introductory.
380 The exception is @ref{Introduction, ,An Introduction to Makefiles},
381 all of which is introductory.
384 If you are familiar with other @code{make} programs, see @ref{Features,
385 ,Features of GNU @code{make}}, which lists the enhancements GNU
386 @code{make} has, and @ref{Missing, ,Incompatibilities and Missing
387 Features}, which explains the few things GNU @code{make} lacks that
390 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
391 and @ref{Special Targets}.
393 @node Bugs, , Reading, Overview
394 @section Problems and Bugs
395 @cindex reporting bugs
396 @cindex bugs, reporting
397 @cindex problems and bugs, reporting
399 If you have problems with GNU @code{make} or think you've found a bug,
400 please report it to the developers; we cannot promise to do anything but
401 we might well want to fix it.
403 Before reporting a bug, make sure you've actually found a real bug.
404 Carefully reread the documentation and see if it really says you can do
405 what you're trying to do. If it's not clear whether you should be able
406 to do something or not, report that too; it's a bug in the
409 Before reporting a bug or trying to fix it yourself, try to isolate it
410 to the smallest possible makefile that reproduces the problem. Then
411 send us the makefile and the exact results @code{make} gave you. Also
412 say what you expected to occur; this will help us decide whether the
413 problem was really in the documentation.
415 Once you've got a precise problem, please send electronic mail either
416 through the Internet or via UUCP:
420 @r{Internet address:}
421 bug-gnu-utils@@prep.ai.mit.edu
424 mit-eddie!prep.ai.mit.edu!bug-gnu-utils
429 Please include the version number of @code{make} you are using. You can
430 get this information with the command @samp{make --version}.
431 Be sure also to include the type of machine and operating system you are
432 using. If possible, include the contents of the file @file{config.h}
433 that is generated by the configuration process.
435 Non-bug suggestions are always welcome as well. If you have questions
436 about things that are unclear in the documentation or are just obscure
437 features, contact Roland McGrath; he will try to help you out, although
438 he may not have time to fix the problem.@refill
440 You can send electronic mail to Roland McGrath either through the
441 @w{Internet} or via UUCP:
445 @r{Internet address:}
446 roland@@prep.ai.mit.edu
449 mit-eddie!prep.ai.mit.edu!roland
453 @node Introduction, Makefiles, Overview, Top
454 @comment node-name, next, previous, up
455 @chapter An Introduction to Makefiles
457 You need a file called a @dfn{makefile} to tell @code{make} what to do.
458 Most often, the makefile tells @code{make} how to compile and link a
462 In this chapter, we will discuss a simple makefile that describes how to
463 compile and link a text editor which consists of eight C source files
464 and three header files. The makefile can also tell @code{make} how to
465 run miscellaneous commands when explicitly asked (for example, to remove
466 certain files as a clean-up operation). To see a more complex example
467 of a makefile, see @ref{Complex Makefile}.
469 When @code{make} recompiles the editor, each changed C source file
470 must be recompiled. If a header file has changed, each C source file
471 that includes the header file must be recompiled to be safe. Each
472 compilation produces an object file corresponding to the source file.
473 Finally, if any source file has been recompiled, all the object files,
474 whether newly made or saved from previous compilations, must be linked
475 together to produce the new executable editor.
476 @cindex recompilation
480 * Rule Introduction:: What a rule looks like.
481 * Simple Makefile:: A Simple Makefile
482 * How Make Works:: How @code{make} Processes This Makefile
483 * Variables Simplify:: Variables Make Makefiles Simpler
484 * make Deduces:: Letting @code{make} Deduce the Commands
485 * Combine By Dependency:: Another Style of Makefile
486 * Cleanup:: Rules for Cleaning the Directory
489 @node Rule Introduction, Simple Makefile, , Introduction
490 @comment node-name, next, previous, up
491 @section What a Rule Looks Like
492 @cindex rule, introduction to
493 @cindex makefile rule parts
494 @cindex parts of makefile rule
496 A simple makefile consists of ``rules'' with the following shape:
498 @cindex targets, introduction to
499 @cindex dependencies, introduction to
500 @cindex commands, introduction to
503 @var{target} @dots{} : @var{dependencies} @dots{}
510 A @dfn{target} is usually the name of a file that is generated by a
511 program; examples of targets are executable or object files. A target
512 can also be the name of an action to carry out, such as @samp{clean}
513 (@pxref{Phony Targets}).
515 A @dfn{dependency} is a file that is used as input to create the
516 target. A target often depends on several files.
518 @cindex tabs in rules
519 A @dfn{command} is an action that @code{make} carries out.
520 A rule may have more than one command, each on its own line.
521 @strong{Please note:} you need to put a tab character at the beginning of
522 every command line! This is an obscurity that catches the unwary.
524 Usually a command is in a rule with dependencies and serves to create a
525 target file if any of the dependencies change. However, the rule that
526 specifies commands for the target need not have dependencies. For
527 example, the rule containing the delete command associated with the
528 target @samp{clean} does not have dependencies.
530 A @dfn{rule}, then, explains how and when to remake certain files
531 which are the targets of the particular rule. @code{make} carries out
532 the commands on the dependencies to create or update the target. A
533 rule can also explain how and when to carry out an action.
534 @xref{Rules, , Writing Rules}.
536 A makefile may contain other text besides rules, but a simple makefile
537 need only contain rules. Rules may look somewhat more complicated
538 than shown in this template, but all fit the pattern more or less.
540 @node Simple Makefile, How Make Works, Rule Introduction, Introduction
541 @section A Simple Makefile
542 @cindex simple makefile
543 @cindex makefile, simple
545 Here is a straightforward makefile that describes the way an
546 executable file called @code{edit} depends on eight object files
547 which, in turn, depend on eight C source and three header files.
549 In this example, all the C files include @file{defs.h}, but only those
550 defining editing commands include @file{command.h}, and only low
551 level files that change the editor buffer include @file{buffer.h}.
555 edit : main.o kbd.o command.o display.o \
556 insert.o search.o files.o utils.o
557 cc -o edit main.o kbd.o command.o display.o \
558 insert.o search.o files.o utils.o
560 main.o : main.c defs.h
562 kbd.o : kbd.c defs.h command.h
564 command.o : command.c defs.h command.h
566 display.o : display.c defs.h buffer.h
568 insert.o : insert.c defs.h buffer.h
570 search.o : search.c defs.h buffer.h
572 files.o : files.c defs.h buffer.h command.h
574 utils.o : utils.c defs.h
577 rm edit main.o kbd.o command.o display.o \
578 insert.o search.o files.o utils.o
583 We split each long line into two lines using backslash-newline; this is
584 like using one long line, but is easier to read.
585 @cindex continuation lines
586 @cindex @code{\} (backslash), for continuation lines
587 @cindex backslash (@code{\}), for continuation lines
588 @cindex quoting newline, in makefile
589 @cindex newline, quoting, in makefile
591 To use this makefile to create the executable file called @file{edit},
598 To use this makefile to delete the executable file and all the object
599 files from the directory, type:
605 In the example makefile, the targets include the executable file
606 @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
607 dependencies are files such as @samp{main.c} and @samp{defs.h}.
608 In fact, each @samp{.o} file is both a target and a dependency.
609 Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
611 When a target is a file, it needs to be recompiled or relinked if any
612 of its dependencies change. In addition, any dependencies that are
613 themselves automatically generated should be updated first. In this
614 example, @file{edit} depends on each of the eight object files; the
615 object file @file{main.o} depends on the source file @file{main.c} and
616 on the header file @file{defs.h}.
618 A shell command follows each line that contains a target and
619 dependencies. These shell commands say how to update the target file.
620 A tab character must come at the beginning of every command line to
621 distinguish commands lines from other lines in the makefile. (Bear in
622 mind that @code{make} does not know anything about how the commands
623 work. It is up to you to supply commands that will update the target
624 file properly. All @code{make} does is execute the commands in the rule
625 you have specified when the target file needs to be updated.)
626 @cindex shell command
628 The target @samp{clean} is not a file, but merely the name of an
631 do not want to carry out the actions in this rule, @samp{clean} is not a dependency of any other rule.
632 Consequently, @code{make} never does anything with it unless you tell
633 it specifically. Note that this rule not only is not a dependency, it
634 also does not have any dependencies, so the only purpose of the rule
635 is to run the specified commands. Targets that do not refer to files
636 but are just actions are called @dfn{phony targets}. @xref{Phony
637 Targets}, for information about this kind of target. @xref{Errors, ,
638 Errors in Commands}, to see how to cause @code{make} to ignore errors
639 from @code{rm} or any other command.
640 @cindex @code{clean} target
641 @cindex @code{rm} (shell command)
643 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
644 @comment node-name, next, previous, up
645 @section How @code{make} Processes a Makefile
646 @cindex processing a makefile
647 @cindex makefile, how @code{make} processes
649 By default, @code{make} starts with the first rule (not counting rules
650 whose target names start with @samp{.}). This is called the
651 @dfn{default goal}. (@dfn{Goals} are the targets that @code{make}
652 strives ultimately to update. @xref{Goals, , Arguments to Specify the
655 @cindex goal, default
658 In the simple example of the previous section, the default goal is to
659 update the executable program @file{edit}; therefore, we put that rule
662 Thus, when you give the command:
669 @code{make} reads the makefile in the current directory and begins by
670 processing the first rule. In the example, this rule is for relinking
671 @file{edit}; but before @code{make} can fully process this rule, it
672 must process the rules for the files that @file{edit} depends on,
673 which in this case are the object files. Each of these files is
674 processed according to its own rule. These rules say to update each
675 @samp{.o} file by compiling its source file. The recompilation must
676 be done if the source file, or any of the header files named as
677 dependencies, is more recent than the object file, or if the object
680 The other rules are processed because their targets appear as
681 dependencies of the goal. If some other rule is not depended on by the
682 goal (or anything it depends on, etc.), that rule is not processed,
683 unless you tell @code{make} to do so (with a command such as
684 @w{@code{make clean}}).
686 Before recompiling an object file, @code{make} considers updating its
687 dependencies, the source file and header files. This makefile does not
688 specify anything to be done for them---the @samp{.c} and @samp{.h} files
689 are not the targets of any rules---so @code{make} does nothing for these
690 files. But @code{make} would update automatically generated C programs,
691 such as those made by Bison or Yacc, by their own rules at this time.
693 After recompiling whichever object files need it, @code{make} decides
694 whether to relink @file{edit}. This must be done if the file
695 @file{edit} does not exist, or if any of the object files are newer than
696 it. If an object file was just recompiled, it is now newer than
697 @file{edit}, so @file{edit} is relinked.
700 Thus, if we change the file @file{insert.c} and run @code{make},
701 @code{make} will compile that file to update @file{insert.o}, and then
702 link @file{edit}. If we change the file @file{command.h} and run
703 @code{make}, @code{make} will recompile the object files @file{kbd.o},
704 @file{command.o} and @file{files.o} and then link the file @file{edit}.
706 @node Variables Simplify, make Deduces, How Make Works, Introduction
707 @section Variables Make Makefiles Simpler
709 @cindex simplifying with variables
711 In our example, we had to list all the object files twice in the rule for
712 @file{edit} (repeated here):
716 edit : main.o kbd.o command.o display.o \
717 insert.o search.o files.o utils.o
718 cc -o edit main.o kbd.o command.o display.o \
719 insert.o search.o files.o utils.o
723 @cindex @code{objects}
724 Such duplication is error-prone; if a new object file is added to the
725 system, we might add it to one list and forget the other. We can eliminate
726 the risk and simplify the makefile by using a variable. @dfn{Variables}
727 allow a text string to be defined once and substituted in multiple places
728 later (@pxref{Using Variables, ,How to Use Variables}).
730 @cindex @code{OBJECTS}
735 It is standard practice for every makefile to have a variable named
736 @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
737 or @code{OBJ} which is a list of all object file names. We would
738 define such a variable @code{objects} with a line like this in the
743 objects = main.o kbd.o command.o display.o \
744 insert.o search.o files.o utils.o
749 Then, each place we want to put a list of the object file names, we can
750 substitute the variable's value by writing @samp{$(objects)}
751 (@pxref{Using Variables, ,How to Use Variables}).
753 Here is how the complete simple makefile looks when you use a variable
754 for the object files:
758 objects = main.o kbd.o command.o display.o \
759 insert.o search.o files.o utils.o
762 cc -o edit $(objects)
763 main.o : main.c defs.h
765 kbd.o : kbd.c defs.h command.h
767 command.o : command.c defs.h command.h
769 display.o : display.c defs.h buffer.h
771 insert.o : insert.c defs.h buffer.h
773 search.o : search.c defs.h buffer.h
775 files.o : files.c defs.h buffer.h command.h
777 utils.o : utils.c defs.h
784 @node make Deduces, Combine By Dependency, Variables Simplify, Introduction
785 @section Letting @code{make} Deduce the Commands
786 @cindex deducing commands (implicit rules)
787 @cindex implicit rule, introduction to
788 @cindex rule, implicit, introduction to
790 It is not necessary to spell out the commands for compiling the individual
791 C source files, because @code{make} can figure them out: it has an
792 @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
793 named @samp{.c} file using a @samp{cc -c} command. For example, it will
794 use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
795 @file{main.o}. We can therefore omit the commands from the rules for the
796 object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill
798 When a @samp{.c} file is used automatically in this way, it is also
799 automatically added to the list of dependencies. We can therefore omit
800 the @samp{.c} files from the dependencies, provided we omit the commands.
802 Here is the entire example, with both of these changes, and a variable
803 @code{objects} as suggested above:
807 objects = main.o kbd.o command.o display.o \
808 insert.o search.o files.o utils.o
811 cc -o edit $(objects)
814 kbd.o : defs.h command.h
815 command.o : defs.h command.h
816 display.o : defs.h buffer.h
817 insert.o : defs.h buffer.h
818 search.o : defs.h buffer.h
819 files.o : defs.h buffer.h command.h
829 This is how we would write the makefile in actual practice. (The
830 complications associated with @samp{clean} are described elsewhere.
831 See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
833 Because implicit rules are so convenient, they are important. You
834 will see them used frequently.@refill
836 @node Combine By Dependency, Cleanup, make Deduces, Introduction
837 @section Another Style of Makefile
838 @cindex combining rules by dependency
840 When the objects of a makefile are created only by implicit rules, an
841 alternative style of makefile is possible. In this style of makefile,
842 you group entries by their dependencies instead of by their targets.
843 Here is what one looks like:
847 objects = main.o kbd.o command.o display.o \
848 insert.o search.o files.o utils.o
851 cc -o edit $(objects)
854 kbd.o command.o files.o : command.h
855 display.o insert.o search.o files.o : buffer.h
860 Here @file{defs.h} is given as a dependency of all the object files;
861 @file{command.h} and @file{buffer.h} are dependencies of the specific
862 object files listed for them.
864 Whether this is better is a matter of taste: it is more compact, but some
865 people dislike it because they find it clearer to put all the information
866 about each target in one place.
868 @node Cleanup, , Combine By Dependency, Introduction
869 @section Rules for Cleaning the Directory
871 @cindex removing, to clean up
873 Compiling a program is not the only thing you might want to write rules
874 for. Makefiles commonly tell how to do a few other things besides
875 compiling a program: for example, how to delete all the object files
876 and executables so that the directory is @samp{clean}.
878 @cindex @code{clean} target
880 could write a @code{make} rule for cleaning our example editor:
889 In practice, we might want to write the rule in a somewhat more
890 complicated manner to handle unanticipated situations. We would do this:
901 This prevents @code{make} from getting confused by an actual file
902 called @file{clean} and causes it to continue in spite of errors from
903 @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
907 A rule such as this should not be placed at the beginning of the
908 makefile, because we do not want it to run by default! Thus, in the
909 example makefile, we want the rule for @code{edit}, which recompiles
910 the editor, to remain the default goal.
912 Since @code{clean} is not a dependency of @code{edit}, this rule will not
913 run at all if we give the command @samp{make} with no arguments. In
914 order to make the rule run, we have to type @samp{make clean}.
915 @xref{Running, ,How to Run @code{make}}.
917 @node Makefiles, Rules, Introduction, Top
918 @chapter Writing Makefiles
920 @cindex makefile, how to write
921 The information that tells @code{make} how to recompile a system comes from
922 reading a data base called the @dfn{makefile}.
925 * Makefile Contents:: What makefiles contain.
926 * Makefile Names:: How to name your makefile.
927 * Include:: How one makefile can use another makefile.
928 * MAKEFILES Variable:: The environment can specify extra makefiles.
929 * Remaking Makefiles:: How makefiles get remade.
930 * Overriding Makefiles:: How to override part of one makefile
931 with another makefile.
934 @node Makefile Contents, Makefile Names, , Makefiles
935 @section What Makefiles Contain
937 Makefiles contain five kinds of things: @dfn{explicit rules},
938 @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
939 and @dfn{comments}. Rules, variables, and directives are described at
940 length in later chapters.@refill
943 @cindex rule, explicit, definition of
944 @cindex explicit rule, definition of
946 An @dfn{explicit rule} says when and how to remake one or more files,
947 called the rule's targets. It lists the other files that the targets
948 @dfn{depend on}, and may also give commands to use to create or update
949 the targets. @xref{Rules, ,Writing Rules}.
951 @cindex rule, implicit, definition of
952 @cindex implicit rule, definition of
954 An @dfn{implicit rule} says when and how to remake a class of files
955 based on their names. It describes how a target may depend on a file
956 with a name similar to the target and gives commands to create or
957 update such a target. @xref{Implicit Rules, ,Using Implicit Rules}.
959 @cindex variable definition
961 A @dfn{variable definition} is a line that specifies a text string
962 value for a variable that can be substituted into the text later. The
963 simple makefile example shows a variable definition for @code{objects}
964 as a list of all object files (@pxref{Variables Simplify, , Variables
965 Make Makefiles Simpler}).
969 A @dfn{directive} is a command for @code{make} to do something special while
970 reading the makefile. These include:
974 Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
977 Deciding (based on the values of variables) whether to use or
978 ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
981 Defining a variable from a verbatim string containing multiple lines
982 (@pxref{Defining, ,Defining Variables Verbatim}).
985 @cindex comments, in makefile
986 @cindex @code{#} (comments), in makefile
988 @samp{#} in a line of a makefile starts a @dfn{comment}. It and the rest of
989 the line are ignored, except that a trailing backslash not escaped by
990 another backslash will continue the comment across multiple lines.
991 Comments may appear on any of the lines in the makefile, except within a
992 @code{define} directive, and perhaps within commands (where the shell
993 decides what is a comment). A line containing just a comment (with
994 perhaps spaces before it) is effectively blank, and is ignored.@refill
997 @node Makefile Names, Include, Makefile Contents, Makefiles
998 @section What Name to Give Your Makefile
999 @cindex makefile name
1000 @cindex name of makefile
1001 @cindex default makefile name
1002 @cindex file name of makefile
1004 @c following paragraph rewritten to avoid overfull hbox
1005 By default, when @code{make} looks for the makefile, it tries the
1006 following names, in order: @file{GNUmakefile}, @file{makefile}
1007 and @file{Makefile}.@refill
1012 @cindex @code{README}
1013 Normally you should call your makefile either @file{makefile} or
1014 @file{Makefile}. (We recommend @file{Makefile} because it appears
1015 prominently near the beginning of a directory listing, right near other
1016 important files such as @file{README}.) The first name checked,
1017 @file{GNUmakefile}, is not recommended for most makefiles. You should
1018 use this name if you have a makefile that is specific to GNU
1019 @code{make}, and will not be understood by other versions of
1020 @code{make}. Other @code{make} programs look for @file{makefile} and
1021 @file{Makefile}, but not @file{GNUmakefile}.
1023 If @code{make} finds none of these names, it does not use any makefile.
1024 Then you must specify a goal with a command argument, and @code{make}
1025 will attempt to figure out how to remake it using only its built-in
1026 implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}.
1029 @cindex @code{--file}
1030 @cindex @code{--makefile}
1031 If you want to use a nonstandard name for your makefile, you can specify
1032 the makefile name with the @samp{-f} or @samp{--file} option. The
1033 arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1034 @code{make} to read the file @var{name} as the makefile. If you use
1035 more than one @samp{-f} or @samp{--file} option, you can specify several
1036 makefiles. All the makefiles are effectively concatenated in the order
1037 specified. The default makefile names @file{GNUmakefile},
1038 @file{makefile} and @file{Makefile} are not checked automatically if you
1039 specify @samp{-f} or @samp{--file}.@refill
1040 @cindex specifying makefile name
1041 @cindex makefile name, how to specify
1042 @cindex name of makefile, how to specify
1043 @cindex file name of makefile, how to specify
1045 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
1046 @section Including Other Makefiles
1047 @cindex including other makefiles
1048 @cindex makefile, including
1051 The @code{include} directive tells @code{make} to suspend reading the
1052 current makefile and read one or more other makefiles before continuing.
1053 The directive is a line in the makefile that looks like this:
1056 include @var{filenames}@dots{}
1060 @var{filenames} can contain shell file name patterns.
1061 @cindex shell file name pattern (in @code{include})
1062 @cindex shell wildcards (in @code{include})
1063 @cindex wildcard, in @code{include}
1065 Extra spaces are allowed and ignored at the beginning of the line, but
1066 a tab is not allowed. (If the line begins with a tab, it will be
1067 considered a command line.) Whitespace is required between
1068 @code{include} and the file names, and between file names; extra
1069 whitespace is ignored there and at the end of the directive. A
1070 comment starting with @samp{#} is allowed at the end of the line. If
1071 the file names contain any variable or function references, they are
1072 expanded. @xref{Using Variables, ,How to Use Variables}.
1074 For example, if you have three @file{.mk} files, @file{a.mk},
1075 @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1076 @code{bish bash}, then the following expression
1079 include foo *.mk $(bar)
1085 include foo a.mk b.mk c.mk bish bash
1088 When @code{make} processes an @code{include} directive, it suspends
1089 reading of the containing makefile and reads from each listed file in
1090 turn. When that is finished, @code{make} resumes reading the
1091 makefile in which the directive appears.
1093 One occasion for using @code{include} directives is when several programs,
1094 handled by individual makefiles in various directories, need to use a
1095 common set of variable definitions
1096 (@pxref{Setting, ,Setting Variables}) or pattern rules
1097 (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1099 Another such occasion is when you want to generate dependencies from
1100 source files automatically; the dependencies can be put in a file that
1101 is included by the main makefile. This practice is generally cleaner
1102 than that of somehow appending the dependencies to the end of the main
1103 makefile as has been traditionally done with other versions of
1104 @code{make}. @xref{Automatic Dependencies}.
1105 @cindex dependencies, automatic generation
1106 @cindex automatic generation of dependencies
1107 @cindex generating dependencies automatically
1110 @cindex @code{--include-dir}
1111 @findex /usr/gnu/include
1112 @findex /usr/local/include
1113 @findex /usr/include
1114 If the specified name does not start with a slash, and the file is not
1115 found in the current directory, several other directories are searched.
1116 First, any directories you have specified with the @samp{-I} or
1117 @samp{--include-dir} option are searched
1118 (@pxref{Options Summary, ,Summary of Options}).
1119 Then the following directories (if they exist)
1120 are searched, in this order:
1121 @file{@var{prefix}/include} (normally @file{/usr/local/include})
1122 @file{/usr/gnu/include},
1123 @file{/usr/local/include}, @file{/usr/include}.
1125 If an included makefile cannot be found in any of these directories, a
1126 warning message is generated, but it is not an immediately fatal error;
1127 processing of the makefile containing the @code{include} continues.
1128 Once it has finished reading makefiles, @code{make} will try to remake
1129 any that are out of date or don't exist.
1130 @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1131 Only after it has tried to find a way to remake a makefile and failed,
1132 will @code{make} diagnose the missing makefile as a fatal error.
1134 If you want @code{make} to simply ignore a makefile which does not exist
1135 and cannot be remade, with no error message, use the @w{@code{-include}}
1136 directive instead of @code{include}, like this:
1139 -include @var{filenames}@dots{}
1142 This is acts like @code{include} in every way except that there is no
1143 error (not even a warning) if any of the @var{filenames} do not exist.
1145 @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
1146 @section The Variable @code{MAKEFILES}
1147 @cindex makefile, and @code{MAKEFILES} variable
1148 @cindex including (@code{MAKEFILES} variable)
1151 If the environment variable @code{MAKEFILES} is defined, @code{make}
1152 considers its value as a list of names (separated by whitespace) of
1153 additional makefiles to be read before the others. This works much like
1154 the @code{include} directive: various directories are searched for those
1155 files (@pxref{Include, ,Including Other Makefiles}). In addition, the
1156 default goal is never taken from one of these makefiles and it is not an
1157 error if the files listed in @code{MAKEFILES} are not found.@refill
1159 @cindex recursion, and @code{MAKEFILES} variable
1160 The main use of @code{MAKEFILES} is in communication between recursive
1161 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1162 @code{make}}). It usually is not desirable to set the environment
1163 variable before a top-level invocation of @code{make}, because it is
1164 usually better not to mess with a makefile from outside. However, if
1165 you are running @code{make} without a specific makefile, a makefile in
1166 @code{MAKEFILES} can do useful things to help the built-in implicit
1167 rules work better, such as defining search paths (@pxref{Directory Search}).
1169 Some users are tempted to set @code{MAKEFILES} in the environment
1170 automatically on login, and program makefiles to expect this to be done.
1171 This is a very bad idea, because such makefiles will fail to work if run by
1172 anyone else. It is much better to write explicit @code{include} directives
1173 in the makefiles. @xref{Include, , Including Other Makefiles}.
1175 @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles
1176 @section How Makefiles Are Remade
1178 @cindex updating makefiles
1179 @cindex remaking makefiles
1180 @cindex makefile, remaking of
1181 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1182 files. If a makefile can be remade from other files, you probably want
1183 @code{make} to get an up-to-date version of the makefile to read in.
1185 To this end, after reading in all makefiles, @code{make} will consider
1186 each as a goal target and attempt to update it. If a makefile has a
1187 rule which says how to update it (found either in that very makefile or
1188 in another one) or if an implicit rule applies to it (@pxref{Implicit
1189 Rules, ,Using Implicit Rules}), it will be updated if necessary. After
1190 all makefiles have been checked, if any have actually been changed,
1191 @code{make} starts with a clean slate and reads all the makefiles over
1192 again. (It will also attempt to update each of them over again, but
1193 normally this will not change them again, since they are already up to
1196 If the makefiles specify a double-colon rule to remake a file with
1197 commands but no dependencies, that file will always be remade
1198 (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a
1199 double-colon rule with commands but no dependencies will be remade every
1200 time @code{make} is run, and then again after @code{make} starts over
1201 and reads the makefiles in again. This would cause an infinite loop:
1202 @code{make} would constantly remake the makefile, and never do anything
1203 else. So, to avoid this, @code{make} will @strong{not} attempt to
1204 remake makefiles which are specified as double-colon targets but have no
1205 dependencies.@refill
1207 If you do not specify any makefiles to be read with @samp{-f} or
1208 @samp{--file} options, @code{make} will try the default makefile names;
1209 @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike
1210 makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1211 @code{make} is not certain that these makefiles should exist. However,
1212 if a default makefile does not exist but can be created by running
1213 @code{make} rules, you probably want the rules to be run so that the
1214 makefile can be used.
1216 Therefore, if none of the default makefiles exists, @code{make} will try
1217 to make each of them in the same order in which they are searched for
1218 (@pxref{Makefile Names, ,What Name to Give Your Makefile})
1219 until it succeeds in making one, or it runs out of names to try. Note
1220 that it is not an error if @code{make} cannot find or make any makefile;
1221 a makefile is not always necessary.@refill
1223 When you use the @samp{-t} or @samp{--touch} option
1224 (@pxref{Instead of Execution, ,Instead of Executing the Commands}),
1225 you would not want to use an out-of-date makefile to decide which
1226 targets to touch. So the @samp{-t} option has no effect on updating
1227 makefiles; they are really updated even if @samp{-t} is specified.
1228 Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1229 @samp{--just-print}) do not prevent updating of makefiles, because an
1230 out-of-date makefile would result in the wrong output for other targets.
1231 Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1232 and then print the commands to update @file{foo} and its dependencies
1233 without running them. The commands printed for @file{foo} will be those
1234 specified in the updated contents of @file{mfile}.
1236 However, on occasion you might actually wish to prevent updating of even
1237 the makefiles. You can do this by specifying the makefiles as goals in
1238 the command line as well as specifying them as makefiles. When the
1239 makefile name is specified explicitly as a goal, the options @samp{-t}
1240 and so on do apply to them.
1242 Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1243 @file{mfile}, print the commands needed to update it without actually
1244 running them, and then print the commands needed to update @file{foo}
1245 without running them. The commands for @file{foo} will be those
1246 specified by the existing contents of @file{mfile}.
1248 @node Overriding Makefiles, , Remaking Makefiles, Makefiles
1249 @section Overriding Part of Another Makefile
1251 @cindex overriding makefiles
1252 @cindex makefile, overriding
1253 Sometimes it is useful to have a makefile that is mostly just like
1254 another makefile. You can often use the @samp{include} directive to
1255 include one in the other, and add more targets or variable definitions.
1256 However, if the two makefiles give different commands for the same
1257 target, @code{make} will not let you just do this. But there is another way.
1259 @cindex @code{.DEFAULT}, used to override
1260 In the containing makefile (the one that wants to include the other),
1261 you can use the @code{.DEFAULT} special target to say that to remake
1262 any target that cannot be made from the information in the containing
1263 makefile, @code{make} should look in another makefile.
1264 @xref{Last Resort, , Defining Last-Resort Default Rules},
1265 for more information on @code{.DEFAULT}.
1267 For example, if you have a makefile called @file{Makefile} that says how
1268 to make the target @samp{foo} (and other targets), you can write a
1269 makefile called @file{GNUmakefile} that contains:
1276 @@$(MAKE) -f Makefile $@@
1279 If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1280 read it, and see that to make @file{foo}, it needs to run the command
1281 @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will
1282 find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1283 commands from @code{.DEFAULT}: @samp{make -f Makefile bar}. If
1284 @file{Makefile} provides a rule for updating @file{bar}, @code{make}
1285 will apply the rule. And likewise for any other target that
1286 @file{GNUmakefile} does not say how to make.@refill
1288 @node Rules, Commands, Makefiles, Top
1289 @chapter Writing Rules
1290 @cindex writing rules
1291 @cindex rule, how to write
1295 A @dfn{rule} appears in the makefile and says when and how to remake
1296 certain files, called the rule's @dfn{targets} (most often only one per rule).
1297 It lists the other files that are the @dfn{dependencies} of the target, and
1298 @dfn{commands} to use to create or update the target.
1300 @cindex default goal
1301 @cindex goal, default
1302 The order of rules is not significant, except for determining the
1303 @dfn{default goal}: the target for @code{make} to consider, if you do
1304 not otherwise specify one. The default goal is the target of the first
1305 rule in the first makefile. If the first rule has multiple targets,
1306 only the first target is taken as the default. There are two
1307 exceptions: a target starting with a period is not a default unless it
1308 contains one or more slashes, @samp{/}, as well; and, a target that
1309 defines a pattern rule has no effect on the default goal.
1310 (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1312 Therefore, we usually write the makefile so that the first rule is the
1313 one for compiling the entire program or all the programs described by
1314 the makefile (often with a target called @samp{all}).
1315 @xref{Goals, ,Arguments to Specify the Goals}.
1318 * Rule Example:: An example explained.
1319 * Rule Syntax:: General syntax explained.
1320 * Wildcards:: Using wildcard characters such as `*'.
1321 * Directory Search:: Searching other directories for source files.
1322 * Phony Targets:: Using a target that is not a real file's name.
1323 * Force Targets:: You can use a target without commands
1324 or dependencies to mark other
1326 * Empty Targets:: When only the date matters and the
1328 * Special Targets:: Targets with special built-in meanings.
1329 * Multiple Targets:: When to make use of several targets in a rule.
1330 * Multiple Rules:: How to use several rules with the same target.
1331 * Static Pattern:: Static pattern rules apply to multiple targets
1332 and can vary the dependencies according to
1334 * Double-Colon:: How to use a special kind of rule to allow
1335 several independent rules for one target.
1336 * Automatic Dependencies:: How to automatically generate rules giving
1337 dependencies from the source files themselves.
1341 @node Rule Example, Rule Syntax, , Rules
1342 @section Rule Example
1344 Here is an example of a rule:
1347 foo.o : foo.c defs.h # module for twiddling the frobs
1351 Its target is @file{foo.o} and its dependencies are @file{foo.c} and
1352 @file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}.
1353 The command line starts with a tab to identify it as a command.
1355 This rule says two things:
1359 How to decide whether @file{foo.o} is out of date: it is out of date
1360 if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1361 more recent than it.
1364 How to update the file @file{foo.o}: by running @code{cc} as stated.
1365 The command does not explicitly mention @file{defs.h}, but we presume
1366 that @file{foo.c} includes it, and that that is why @file{defs.h} was
1367 added to the dependencies.
1371 @node Rule Syntax, Wildcards, Rule Example, Rules
1372 @section Rule Syntax
1375 @cindex syntax of rules
1376 In general, a rule looks like this:
1379 @var{targets} : @var{dependencies}
1388 @var{targets} : @var{dependencies} ; @var{command}
1394 @cindex rule targets
1395 The @var{targets} are file names, separated by spaces. Wildcard
1396 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1397 in File Names}) and a name of the form @file{@var{a}(@var{m})}
1398 represents member @var{m} in archive file @var{a}
1399 (@pxref{Archive Members, ,Archive Members as Targets}).
1400 Usually there is only one
1401 target per rule, but occasionally there is a reason to have more
1402 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1405 @cindex tab character (in commands)
1406 The @var{command} lines start with a tab character. The first command may
1407 appear on the line after the dependencies, with a tab character, or may
1408 appear on the same line, with a semicolon. Either way, the effect is the
1409 same. @xref{Commands, ,Writing the Commands in Rules}.
1411 @cindex dollar sign (@code{$}), in rules
1412 @cindex @code{$}, in rules
1413 @cindex rule, and @code{$}
1414 Because dollar signs are used to start variable references, if you really
1415 want a dollar sign in a rule you must write two of them, @samp{$$}
1416 (@pxref{Using Variables, ,How to Use Variables}).
1417 You may split a long line by inserting a backslash
1418 followed by a newline, but this is not required, as @code{make} places no
1419 limit on the length of a line in a makefile.
1421 A rule tells @code{make} two things: when the targets are out of date,
1422 and how to update them when necessary.
1424 @cindex dependencies
1425 @cindex rule dependencies
1426 The criterion for being out of date is specified in terms of the
1427 @var{dependencies}, which consist of file names separated by spaces.
1428 (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1429 A target is out of date if it does not exist or if it is older than any
1430 of the dependencies (by comparison of last-modification times). The
1431 idea is that the contents of the target file are computed based on
1432 information in the dependencies, so if any of the dependencies changes,
1433 the contents of the existing target file are no longer necessarily
1436 How to update is specified by @var{commands}. These are lines to be
1437 executed by the shell (normally @samp{sh}), but with some extra features
1438 (@pxref{Commands, ,Writing the Commands in Rules}).
1440 @node Wildcards, Directory Search, Rule Syntax, Rules
1441 @section Using Wildcard Characters in File Names
1443 @cindex file name with wildcards
1444 @cindex globbing (wildcards)
1446 @cindex @code{*} (wildcard character)
1447 @cindex @code{?} (wildcard character)
1448 @cindex @code{[@dots{}]} (wildcard characters)
1449 A single file name can specify many files using @dfn{wildcard characters}.
1450 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
1451 @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
1452 specifies a list of all the files (in the working directory) whose names
1453 end in @samp{.c}.@refill
1455 @cindex @code{~} (tilde)
1456 @cindex tilde (@code{~})
1457 @cindex home directory
1458 The character @samp{~} at the beginning of a file name also has special
1459 significance. If alone, or followed by a slash, it represents your home
1460 directory. For example @file{~/bin} expands to @file{/home/you/bin}.
1461 If the @samp{~} is followed by a word, the string represents the home
1462 directory of the user named by that word. For example @file{~john/bin}
1463 expands to @file{/home/john/bin}.@refill
1465 Wildcard expansion happens automatically in targets, in dependencies,
1466 and in commands (where the shell does the expansion). In other
1467 contexts, wildcard expansion happens only if you request it explicitly
1468 with the @code{wildcard} function.
1470 The special significance of a wildcard character can be turned off by
1471 preceding it with a backslash. Thus, @file{foo\*bar} would refer to a
1472 specific file whose name consists of @samp{foo}, an asterisk, and
1476 * Wildcard Examples:: Several examples
1477 * Wildcard Pitfall:: Problems to avoid.
1478 * Wildcard Function:: How to cause wildcard expansion where
1479 it does not normally take place.
1482 @node Wildcard Examples, Wildcard Pitfall, , Wildcards
1483 @subsection Wildcard Examples
1485 Wildcards can be used in the commands of a rule, where they are expanded
1486 by the shell. For example, here is a rule to delete all the object files:
1494 @cindex @code{rm} (shell command)
1496 Wildcards are also useful in the dependencies of a rule. With the
1497 following rule in the makefile, @samp{make print} will print all the
1498 @samp{.c} files that have changed since the last time you printed them:
1506 @cindex @code{print} target
1507 @cindex @code{lpr} (shell command)
1508 @cindex @code{touch} (shell command)
1510 This rule uses @file{print} as an empty target file; see @ref{Empty
1511 Targets, ,Empty Target Files to Record Events}. (The automatic variable
1512 @samp{$?} is used to print only those files that have changed; see
1513 @ref{Automatic, ,Automatic Variables}.)@refill
1515 Wildcard expansion does not happen when you define a variable. Thus, if
1523 then the value of the variable @code{objects} is the actual string
1524 @samp{*.o}. However, if you use the value of @code{objects} in a target,
1525 dependency or command, wildcard expansion will take place at that time.
1526 To set @code{objects} to the expansion, instead use:
1529 objects := $(wildcard *.o)
1533 @xref{Wildcard Function}.
1535 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
1536 @subsection Pitfalls of Using Wildcards
1537 @cindex wildcard pitfalls
1538 @cindex pitfalls of wildcards
1539 @cindex mistakes with wildcards
1540 @cindex errors with wildcards
1541 @cindex problems with wildcards
1543 Now here is an example of a naive way of using wildcard expansion, that
1544 does not do what you would intend. Suppose you would like to say that the
1545 executable file @file{foo} is made from all the object files in the
1546 directory, and you write this:
1552 cc -o foo $(CFLAGS) $(objects)
1556 The value of @code{objects} is the actual string @samp{*.o}. Wildcard
1557 expansion happens in the rule for @file{foo}, so that each @emph{existing}
1558 @samp{.o} file becomes a dependency of @file{foo} and will be recompiled if
1561 But what if you delete all the @samp{.o} files? Then @samp{*.o} will
1562 expand into @emph{nothing}. The target @file{foo} will have no
1563 dependencies and would be remade by linking no object files. This is not
1566 Actually it is possible to obtain the desired result with wildcard
1567 expansion, but you need more sophisticated techniques, including the
1568 @code{wildcard} function and string substitution.
1570 @xref{Wildcard Function, ,The Function @code{wildcard}}.
1573 These are described in the following section.
1576 @node Wildcard Function, , Wildcard Pitfall, Wildcards
1577 @subsection The Function @code{wildcard}
1580 Wildcard expansion happens automatically in rules. But wildcard expansion
1581 does not normally take place when a variable is set, or inside the
1582 arguments of a function. If you want to do wildcard expansion in such
1583 places, you need to use the @code{wildcard} function, like this:
1586 $(wildcard @var{pattern})
1590 This string, used anywhere in a makefile, is replaced by a space-separated
1591 list of names of existing files that match the pattern @var{pattern}.
1593 One use of the @code{wildcard} function is to get a list of all the C source
1594 files in a directory, like this:
1600 We can change the list of C source files into a list of object files by
1601 replacing the @samp{.o} suffix with @samp{.c} in the result, like this:
1604 $(patsubst %.c,%.o,$(wildcard *.c))
1608 (Here we have used another function, @code{patsubst}.
1609 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
1611 Thus, a makefile to compile all C source files in the directory and then
1612 link them together could be written as follows:
1615 objects := $(patsubst %.c,%.o,$(wildcard *.c))
1618 cc -o foo $(objects)
1622 (This takes advantage of the implicit rule for compiling C programs, so
1623 there is no need to write explicit rules for compiling the files.
1624 @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
1625 @samp{:=}, which is a variant of @samp{=}.)
1627 @node Directory Search, Phony Targets, Wildcards, Rules
1628 @section Searching Directories for Dependencies
1632 @cindex search path for dependencies (@code{VPATH})
1633 @cindex directory search (@code{VPATH})
1635 For large systems, it is often desirable to put sources in a separate
1636 directory from the binaries. The @dfn{directory search} features of
1637 @code{make} facilitate this by searching several directories
1638 automatically to find a dependency. When you redistribute the files
1639 among directories, you do not need to change the individual rules,
1640 just the search paths.
1643 * General Search:: Specifying a search path that applies
1644 to every dependency.
1645 * Selective Search:: Specifying a search path
1646 for a specified class of names.
1647 * Commands/Search:: How to write shell commands that work together
1649 * Implicit/Search:: How search paths affect implicit rules.
1650 * Libraries/Search:: Directory search for link libraries.
1653 @node General Search, Selective Search, , Directory Search
1654 @subsection @code{VPATH}: Search Path for All Dependencies
1657 The value of the @code{make} variable @code{VPATH} specifies a list of
1658 directories that @code{make} should search. Most often, the
1659 directories are expected to contain dependency files that are not in the
1660 current directory; however, @code{VPATH} specifies a search list that
1661 @code{make} applies for all files, including files which are targets of
1664 Thus, if a file that is listed as a target or dependency does not exist
1665 in the current directory, @code{make} searches the directories listed in
1666 @code{VPATH} for a file with that name. If a file is found in one of
1667 them, that file becomes the dependency. Rules may then specify the
1668 names of source files in the dependencies as if they all existed in the
1669 current directory. @xref{Commands/Search, ,Writing Shell Commands with
1672 In the @code{VPATH} variable, directory names are separated by colons.
1673 The order in which directories are listed is the order followed by
1674 @code{make} in its search.
1679 VPATH = src:../headers
1683 specifies a path containing two directories, @file{src} and
1684 @file{../headers}, which @code{make} searches in that order.
1686 With this value of @code{VPATH}, the following rule,
1693 is interpreted as if it were written like this:
1700 assuming the file @file{foo.c} does not exist in the current directory but
1701 is found in the directory @file{src}.
1703 @node Selective Search, Commands/Search, General Search, Directory Search
1704 @subsection The @code{vpath} Directive
1707 Similar to the @code{VPATH} variable but more selective is the @code{vpath}
1708 directive (note lower case), which allows you to specify a search path for a particular class
1709 of file names, those that match a particular pattern. Thus you can supply
1710 certain search directories for one class of file names and other directories
1711 (or none) for other file names.
1713 There are three forms of the @code{vpath} directive:
1716 @item vpath @var{pattern} @var{directories}
1717 Specify the search path @var{directories} for file names that match
1720 The search path, @var{directories}, is a colon-separated list of
1721 directories to be searched, just like the search path used in the
1722 @code{VPATH} variable.
1724 @item vpath @var{pattern}
1725 Clear out the search path associated with @var{pattern}.
1727 @c Extra blank line makes sure this gets two lines.
1730 Clear all search paths previously specified with @code{vpath} directives.
1733 A @code{vpath} pattern is a string containing a @samp{%} character. The
1734 string must match the file name of a dependency that is being searched
1735 for, the @samp{%} character matching any sequence of zero or more
1736 characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
1737 Redefining Pattern Rules}). For example, @code{%.h} matches files that
1738 end in @code{.h}. (If there is no @samp{%}, the pattern must match the
1739 dependency exactly, which is not useful very often.)
1741 @cindex @code{%}, quoting in @code{vpath}
1742 @cindex @code{%}, quoting with @code{\} (backslash)
1743 @cindex @code{\} (backslash), to quote @code{%}
1744 @cindex backslash (@code{\}), to quote @code{%}
1745 @cindex quoting @code{%}, in @code{vpath}
1746 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
1747 with preceding backslashes (@samp{\}). Backslashes that would otherwise
1748 quote @samp{%} characters can be quoted with more backslashes.
1749 Backslashes that quote @samp{%} characters or other backslashes are
1750 removed from the pattern before it is compared to file names. Backslashes
1751 that are not in danger of quoting @samp{%} characters go unmolested.@refill
1753 When a dependency fails to exist in the current directory, if the
1754 @var{pattern} in a @code{vpath} directive matches the name of the
1755 dependency file, then the @var{directories} in that directive are searched
1756 just like (and before) the directories in the @code{VPATH} variable.
1761 vpath %.h ../headers
1765 tells @code{make} to look for any dependency whose name ends in @file{.h}
1766 in the directory @file{../headers} if the file is not found in the current
1769 If several @code{vpath} patterns match the dependency file's name, then
1770 @code{make} processes each matching @code{vpath} directive one by one,
1771 searching all the directories mentioned in each directive. @code{make}
1772 handles multiple @code{vpath} directives in the order in which they
1773 appear in the makefile; multiple directives with the same pattern are
1774 independent of each other.
1788 will look for a file ending in @samp{.c} in @file{foo}, then
1789 @file{blish}, then @file{bar}, while
1799 will look for a file ending in @samp{.c} in @file{foo}, then
1800 @file{bar}, then @file{blish}.
1802 @node Commands/Search, Implicit/Search, Selective Search, Directory Search
1803 @subsection Writing Shell Commands with Directory Search
1804 @cindex shell command, and directory search
1805 @cindex directory search (@code{VPATH}), and shell commands
1807 When a dependency is found in another directory through directory search,
1808 this cannot change the commands of the rule; they will execute as written.
1809 Therefore, you must write the commands with care so that they will look for
1810 the dependency in the directory where @code{make} finds it.
1812 This is done with the @dfn{automatic variables} such as @samp{$^}
1813 (@pxref{Automatic, ,Automatic Variables}).
1814 For instance, the value of @samp{$^} is a
1815 list of all the dependencies of the rule, including the names of
1816 the directories in which they were found, and the value of
1817 @samp{$@@} is the target. Thus:@refill
1821 cc -c $(CFLAGS) $^ -o $@@
1825 (The variable @code{CFLAGS} exists so you can specify flags for C
1826 compilation by implicit rules; we use it here for consistency so it will
1827 affect all C compilations uniformly;
1828 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
1830 Often the dependencies include header files as well, which you do not
1831 want to mention in the commands. The automatic variable @samp{$<} is
1832 just the first dependency:
1835 VPATH = src:../headers
1836 foo.o : foo.c defs.h hack.h
1837 cc -c $(CFLAGS) $< -o $@@
1840 @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
1841 @subsection Directory Search and Implicit Rules
1842 @cindex @code{VPATH}, and implicit rules
1843 @cindex directory search (@code{VPATH}), and implicit rules
1844 @cindex search path for dependencies (@code{VPATH}), and implicit rules
1845 @cindex implicit rule, and directory search
1846 @cindex implicit rule, and @code{VPATH}
1847 @cindex rule, implicit, and directory search
1848 @cindex rule, implicit, and @code{VPATH}
1850 The search through the directories specified in @code{VPATH} or with
1851 @code{vpath} also happens during consideration of implicit rules
1852 (@pxref{Implicit Rules, ,Using Implicit Rules}).
1854 For example, when a file @file{foo.o} has no explicit rule, @code{make}
1855 considers implicit rules, such as the built-in rule to compile
1856 @file{foo.c} if that file exists. If such a file is lacking in the
1857 current directory, the appropriate directories are searched for it. If
1858 @file{foo.c} exists (or is mentioned in the makefile) in any of the
1859 directories, the implicit rule for C compilation is applied.
1861 The commands of implicit rules normally use automatic variables as a
1862 matter of necessity; consequently they will use the file names found by
1863 directory search with no extra effort.
1865 @node Libraries/Search, , Implicit/Search, Directory Search
1866 @subsection Directory Search for Link Libraries
1867 @cindex link libraries, and directory search
1868 @cindex libraries for linking, directory search
1869 @cindex directory search (@code{VPATH}), and link libraries
1870 @cindex @code{VPATH}, and link libraries
1871 @cindex search path for dependencies (@code{VPATH}), and link libraries
1872 @cindex @code{-l} (library search)
1874 Directory search applies in a special way to libraries used with the
1875 linker. This special feature comes into play when you write a dependency
1876 whose name is of the form @samp{-l@var{name}}. (You can tell something
1877 strange is going on here because the dependency is normally the name of a
1878 file, and the @emph{file name} of the library looks like
1879 @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
1881 When a dependency's name has the form @samp{-l@var{name}}, @code{make}
1882 handles it specially by searching for the file @file{lib@var{name}.a} in
1883 the current directory, in directories specified by matching @code{vpath}
1884 search paths and the @code{VPATH} search path, and then in the
1885 directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
1886 (normally @file{/usr/local/lib}).
1892 foo : foo.c -lcurses
1898 would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
1899 be executed when @file{foo} is older than @file{foo.c} or than
1900 @file{/usr/lib/libcurses.a}.@refill
1902 @node Phony Targets, Force Targets, Directory Search, Rules
1903 @section Phony Targets
1904 @cindex phony targets
1905 @cindex targets, phony
1906 @cindex targets without a file
1908 A phony target is one that is not really the name of a file. It is just a
1909 name for some commands to be executed when you make an explicit request.
1910 There are two reasons to use a phony target: to avoid a conflict with
1911 a file of the same name, and to improve performance.
1913 If you write a rule whose commands will not create the target file, the
1914 commands will be executed every time the target comes up for remaking.
1925 Because the @code{rm} command does not create a file named @file{clean},
1926 probably no such file will ever exist. Therefore, the @code{rm} command
1927 will be executed every time you say @samp{make clean}.
1928 @cindex @code{rm} (shell command)
1931 The phony target will cease to work if anything ever does create a file
1932 named @file{clean} in this directory. Since it has no dependencies, the
1933 file @file{clean} would inevitably be considered up to date, and its
1934 commands would not be executed. To avoid this problem, you can explicitly
1935 declare the target to be phony, using the special target @code{.PHONY}
1936 (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
1943 Once this is done, @samp{make clean} will run the commands regardless of
1944 whether there is a file named @file{clean}.
1946 Since it knows that phony targets do not name actual files that could be
1947 remade from other files, @code{make} skips the implicit rule search for
1948 phony targets (@pxref{Implicit Rules}). This is why declaring a target
1949 phony is good for performance, even if you are not worried about the
1950 actual file existing.
1952 Thus, you first write the line that states that @code{clean} is a
1953 phony target, then you write the rule, like this:
1963 A phony target should not be a dependency of a real target file; if it
1964 is, its commands are run every time @code{make} goes to update that
1965 file. As long as a phony target is never a dependency of a real
1966 target, the phony target commands will be executed only when the phony
1967 target is a specified goal (@pxref{Goals, ,Arguments to Specify the
1970 Phony targets can have dependencies. When one directory contains multiple
1971 programs, it is most convenient to describe all of the programs in one
1972 makefile @file{./Makefile}. Since the target remade by default will be the
1973 first one in the makefile, it is common to make this a phony target named
1974 @samp{all} and give it, as dependencies, all the individual programs. For
1978 all : prog1 prog2 prog3
1981 prog1 : prog1.o utils.o
1982 cc -o prog1 prog1.o utils.o
1987 prog3 : prog3.o sort.o utils.o
1988 cc -o prog3 prog3.o sort.o utils.o
1992 Now you can say just @samp{make} to remake all three programs, or specify
1993 as arguments the ones to remake (as in @samp{make prog1 prog3}).
1995 When one phony target is a dependency of another, it serves as a subroutine
1996 of the other. For example, here @samp{make cleanall} will delete the
1997 object files, the difference files, and the file @file{program}:
2000 .PHONY: cleanall cleanobj cleandiff
2002 cleanall : cleanobj cleandiff
2012 @node Force Targets, Empty Targets, Phony Targets, Rules
2013 @section Rules without Commands or Dependencies
2014 @cindex force targets
2015 @cindex targets, force
2016 @cindex @code{FORCE}
2017 @cindex rule, no commands or dependencies
2019 If a rule has no dependencies or commands, and the target of the rule
2020 is a nonexistent file, then @code{make} imagines this target to have
2021 been updated whenever its rule is run. This implies that all targets
2022 depending on this one will always have their commands run.
2024 An example will illustrate this:
2034 Here the target @samp{FORCE} satisfies the special conditions, so the
2035 target @file{clean} that depends on it is forced to run its commands.
2036 There is nothing special about the name @samp{FORCE}, but that is one name
2037 commonly used this way.
2039 As you can see, using @samp{FORCE} this way has the same results as using
2040 @samp{.PHONY: clean}.
2042 Using @samp{.PHONY} is more explicit and more efficient. However,
2043 other versions of @code{make} do not support @samp{.PHONY}; thus
2044 @samp{FORCE} appears in many makefiles. @xref{Phony Targets}.
2046 @node Empty Targets, Special Targets, Force Targets, Rules
2047 @section Empty Target Files to Record Events
2048 @cindex empty targets
2049 @cindex targets, empty
2050 @cindex recording events with empty targets
2052 The @dfn{empty target} is a variant of the phony target; it is used to hold
2053 commands for an action that you request explicitly from time to time.
2054 Unlike a phony target, this target file can really exist; but the file's
2055 contents do not matter, and usually are empty.
2057 The purpose of the empty target file is to record, with its
2058 last-modification time, when the rule's commands were last executed. It
2059 does so because one of the commands is a @code{touch} command to update the
2062 The empty target file must have some dependencies. When you ask to remake
2063 the empty target, the commands are executed if any dependency is more
2064 recent than the target; in other words, if a dependency has changed since
2065 the last time you remade the target. Here is an example:
2072 @cindex @code{print} target
2073 @cindex @code{lpr} (shell command)
2074 @cindex @code{touch} (shell command)
2077 With this rule, @samp{make print} will execute the @code{lpr} command if
2078 either source file has changed since the last @samp{make print}. The
2079 automatic variable @samp{$?} is used to print only those files that have
2080 changed (@pxref{Automatic, ,Automatic Variables}).
2082 @node Special Targets, Multiple Targets, Empty Targets, Rules
2083 @section Special Built-in Target Names
2084 @cindex special targets
2085 @cindex built-in special targets
2086 @cindex targets, built-in special
2088 Certain names have special meanings if they appear as targets.
2094 The dependencies of the special target @code{.PHONY} are considered to
2095 be phony targets. When it is time to consider such a target,
2096 @code{make} will run its commands unconditionally, regardless of
2097 whether a file with that name exists or what its last-modification
2098 time is. @xref{Phony Targets, ,Phony Targets}.
2103 The dependencies of the special target @code{.SUFFIXES} are the list
2104 of suffixes to be used in checking for suffix rules.
2105 @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2110 The commands specified for @code{.DEFAULT} are used for any target for
2111 which no rules are found (either explicit rules or implicit rules).
2112 @xref{Last Resort}. If @code{.DEFAULT} commands are specified, every
2113 file mentioned as a dependency, but not as a target in a rule, will have
2114 these commands executed on its behalf. @xref{Search Algorithm,
2115 ,Implicit Rule Search Algorithm}.
2119 @cindex precious targets
2120 @cindex preserving with @code{.PRECIOUS}
2122 The targets which @code{.PRECIOUS} depends on are given the following
2123 special treatment: if @code{make} is killed or interrupted during the
2124 execution of their commands, the target is not deleted.
2125 @xref{Interrupts, ,Interrupting or Killing @code{make}}.
2126 Also, if the target is an intermediate file, it will not be deleted
2127 after it is no longer needed, as is normally done.
2128 @xref{Chained Rules, ,Chains of Implicit Rules}.
2130 You can also list the target pattern of an implicit rule (such as
2131 @samp{%.o}) as a dependency file of the special target @code{.PRECIOUS}
2132 to preserve intermediate files created by rules whose target patterns
2133 match that file's name.
2138 Simply by being mentioned as a target, @code{.IGNORE} says to ignore
2139 errors in execution of commands. The dependencies and commands for
2140 @code{.IGNORE} are not meaningful.
2142 @samp{.IGNORE} exists for historical compatibility. Since
2143 @code{.IGNORE} affects every command in the makefile, it is not very
2144 useful; we recommend you use the more selective ways to ignore errors
2145 in specific commands. @xref{Errors, ,Errors in Commands}.
2150 Simply by being mentioned as a target, @code{.SILENT} says not to
2151 print commands before executing them. The dependencies and commands
2152 for @code{.SILENT} are not meaningful.
2154 @samp{.SILENT} exists for historical compatibility. We recommend you
2155 use the more selective ways to silence specific commands.
2156 @xref{Echoing, ,Command Echoing}. If you want to silence all commands
2157 for a particular run of @code{make}, use the @samp{-s} or
2158 @w{@samp{--silent}} option (@pxref{Options Summary}).
2160 @findex .EXPORT_ALL_VARIABLES
2161 @item .EXPORT_ALL_VARIABLES
2163 Simply by being mentioned as a target, this tells @code{make} to
2164 export all variables to child processes by default.
2165 @xref{Variables/Recursion, ,Communicating Variables to a
2169 Any defined implicit rule suffix also counts as a special target if it
2170 appears as a target, and so does the concatenation of two suffixes, such
2171 as @samp{.c.o}. These targets are suffix rules, an obsolete way of
2172 defining implicit rules (but a way still widely used). In principle, any
2173 target name could be special in this way if you break it in two and add
2174 both pieces to the suffix list. In practice, suffixes normally begin with
2175 @samp{.}, so these special target names also begin with @samp{.}.
2176 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
2178 @node Multiple Targets, Multiple Rules, Special Targets, Rules
2179 @section Multiple Targets in a Rule
2180 @cindex multiple targets
2181 @cindex several targets in a rule
2182 @cindex targets, multiple
2183 @cindex rule, with multiple targets
2185 A rule with multiple targets is equivalent to writing many rules, each with
2186 one target, and all identical aside from that. The same commands apply to
2187 all the targets, but their effects may vary because you can substitute the
2188 actual target name into the command using @samp{$@@}. The rule contributes
2189 the same dependencies to all the targets also.
2191 This is useful in two cases.
2195 You want just dependencies, no commands. For example:
2198 kbd.o command.o files.o: command.h
2202 gives an additional dependency to each of the three object files
2206 Similar commands work for all the targets. The commands do not need
2207 to be absolutely identical, since the automatic variable @samp{$@@}
2208 can be used to substitute the particular target to be remade into the
2209 commands (@pxref{Automatic, ,Automatic Variables}). For example:
2213 bigoutput littleoutput : text.g
2214 generate text.g -$(subst output,,$@@) > $@@
2224 generate text.g -big > bigoutput
2225 littleoutput : text.g
2226 generate text.g -little > littleoutput
2230 Here we assume the hypothetical program @code{generate} makes two
2231 types of output, one if given @samp{-big} and one if given
2233 @xref{Text Functions, ,Functions for String Substitution and Analysis},
2234 for an explanation of the @code{subst} function.
2237 Suppose you would like to vary the dependencies according to the target,
2238 much as the variable @samp{$@@} allows you to vary the commands.
2239 You cannot do this with multiple targets in an ordinary rule, but you can
2240 do it with a @dfn{static pattern rule}.
2241 @xref{Static Pattern, ,Static Pattern Rules}.
2243 @node Multiple Rules, Static Pattern, Multiple Targets, Rules
2244 @section Multiple Rules for One Target
2245 @cindex multiple rules for one target
2246 @cindex several rules for one target
2247 @cindex rule, multiple for one target
2248 @cindex target, multiple rules for one
2250 One file can be the target of several rules. All the dependencies
2251 mentioned in all the rules are merged into one list of dependencies for
2252 the target. If the target is older than any dependency from any rule,
2253 the commands are executed.
2255 There can only be one set of commands to be executed for a file.
2256 If more than one rule gives commands for the same file,
2257 @code{make} uses the last set given and prints an error message.
2258 (As a special case, if the file's name begins with a dot, no
2259 error message is printed. This odd behavior is only for
2260 compatibility with other implementations of @code{make}.)
2261 There is no reason to
2262 write your makefiles this way; that is why @code{make} gives you
2263 an error message.@refill
2265 An extra rule with just dependencies can be used to give a few extra
2266 dependencies to many files at once. For example, one usually has a
2267 variable named @code{objects} containing a list of all the compiler output
2268 files in the system being made. An easy way to say that all of them must
2269 be recompiled if @file{config.h} changes is to write the following:
2272 objects = foo.o bar.o
2274 bar.o : defs.h test.h
2275 $(objects) : config.h
2278 This could be inserted or taken out without changing the rules that really
2279 specify how to make the object files, making it a convenient form to use if
2280 you wish to add the additional dependency intermittently.
2282 Another wrinkle is that the additional dependencies could be specified with
2283 a variable that you set with a command argument to @code{make}
2284 (@pxref{Overriding, ,Overriding Variables}). For example,
2289 $(objects) : $(extradeps)
2294 means that the command @samp{make extradeps=foo.h} will consider
2295 @file{foo.h} as a dependency of each object file, but plain @samp{make}
2298 If none of the explicit rules for a target has commands, then @code{make}
2299 searches for an applicable implicit rule to find some commands
2300 @pxref{Implicit Rules, ,Using Implicit Rules}).
2302 @node Static Pattern, Double-Colon, Multiple Rules, Rules
2303 @section Static Pattern Rules
2304 @cindex static pattern rule
2305 @cindex rule, static pattern
2306 @cindex pattern rules, static (not implicit)
2307 @cindex varying dependencies
2308 @cindex dependencies, varying (static pattern)
2310 @dfn{Static pattern rules} are rules which specify multiple targets and
2311 construct the dependency names for each target based on the target name.
2312 They are more general than ordinary rules with multiple targets because the
2313 targets do not have to have identical dependencies. Their dependencies must
2314 be @emph{analogous}, but not necessarily @emph{identical}.
2317 * Static Usage:: The syntax of static pattern rules.
2318 * Static versus Implicit:: When are they better than implicit rules?
2321 @node Static Usage, Static versus Implicit, , Static Pattern
2322 @subsection Syntax of Static Pattern Rules
2323 @cindex static pattern rule, syntax of
2324 @cindex pattern rules, static, syntax of
2326 Here is the syntax of a static pattern rule:
2329 @var{targets} @dots{}: @var{target-pattern}: @var{dep-patterns} @dots{}
2335 The @var{targets} list specifies the targets that the rule applies to.
2336 The targets can contain wildcard characters, just like the targets of
2337 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
2340 @cindex target pattern, static (not implicit)
2342 The @var{target-pattern} and @var{dep-patterns} say how to compute the
2343 dependencies of each target. Each target is matched against the
2344 @var{target-pattern} to extract a part of the target name, called the
2345 @dfn{stem}. This stem is substituted into each of the @var{dep-patterns}
2346 to make the dependency names (one from each @var{dep-pattern}).
2348 Each pattern normally contains the character @samp{%} just once. When the
2349 @var{target-pattern} matches a target, the @samp{%} can match any part of
2350 the target name; this part is called the @dfn{stem}. The rest of the
2351 pattern must match exactly. For example, the target @file{foo.o} matches
2352 the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
2353 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
2355 @cindex dependency pattern, static (not implicit)
2356 The dependency names for each target are made by substituting the stem
2357 for the @samp{%} in each dependency pattern. For example, if one
2358 dependency pattern is @file{%.c}, then substitution of the stem
2359 @samp{foo} gives the dependency name @file{foo.c}. It is legitimate
2360 to write a dependency pattern that does not contain @samp{%}; then this
2361 dependency is the same for all targets.
2363 @cindex @code{%}, quoting in static pattern
2364 @cindex @code{%}, quoting with @code{\} (backslash)
2365 @cindex @code{\} (backslash), to quote @code{%}
2366 @cindex backslash (@code{\}), to quote @code{%}
2367 @cindex quoting @code{%}, in static pattern
2368 @samp{%} characters in pattern rules can be quoted with preceding
2369 backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%}
2370 characters can be quoted with more backslashes. Backslashes that quote
2371 @samp{%} characters or other backslashes are removed from the pattern
2372 before it is compared to file names or has a stem substituted into it.
2373 Backslashes that are not in danger of quoting @samp{%} characters go
2374 unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has
2375 @samp{the%weird\} preceding the operative @samp{%} character, and
2376 @samp{pattern\\} following it. The final two backslashes are left alone
2377 because they cannot affect any @samp{%} character.@refill
2379 Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
2380 from the corresponding @file{.c} file:
2384 objects = foo.o bar.o
2386 $(objects): %.o: %.c
2387 $(CC) -c $(CFLAGS) $< -o $@@
2392 Here @samp{$<} is the automatic variable that holds the name of the
2393 dependency and @samp{$@@} is the automatic variable that holds the name
2394 of the target; see @ref{Automatic, , Automatic Variables}.
2396 Each target specified must match the target pattern; a warning is issued
2397 for each target that does not. If you have a list of files, only some of
2398 which will match the pattern, you can use the @code{filter} function to
2399 remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
2402 files = foo.elc bar.o lose.o
2404 $(filter %.o,$(files)): %.o: %.c
2405 $(CC) -c $(CFLAGS) $< -o $@@
2406 $(filter %.elc,$(files)): %.elc: %.el
2407 emacs -f batch-byte-compile $<
2411 In this example the result of @samp{$(filter %.o,$(files))} is
2412 @file{bar.o lose.o}, and the first static pattern rule causes each of
2413 these object files to be updated by compiling the corresponding C source
2414 file. The result of @w{@samp{$(filter %.elc,$(files))}} is
2415 @file{foo.elc}, so that file is made from @file{foo.el}.@refill
2417 Another example shows how to use @code{$*} in static pattern rules:
2418 @vindex $*@r{, and static pattern}
2422 bigoutput littleoutput : %output : text.g
2423 generate text.g -$* > $@@
2428 When the @code{generate} command is run, @code{$*} will expand to the
2429 stem, either @samp{big} or @samp{little}.
2431 @node Static versus Implicit, , Static Usage, Static Pattern
2432 @subsection Static Pattern Rules versus Implicit Rules
2433 @cindex rule, static pattern versus implicit
2434 @cindex static pattern rule, versus implicit
2436 A static pattern rule has much in common with an implicit rule defined as a
2437 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
2438 Both have a pattern for the target and patterns for constructing the
2439 names of dependencies. The difference is in how @code{make} decides
2440 @emph{when} the rule applies.
2442 An implicit rule @emph{can} apply to any target that matches its pattern,
2443 but it @emph{does} apply only when the target has no commands otherwise
2444 specified, and only when the dependencies can be found. If more than one
2445 implicit rule appears applicable, only one applies; the choice depends on
2448 By contrast, a static pattern rule applies to the precise list of targets
2449 that you specify in the rule. It cannot apply to any other target and it
2450 invariably does apply to each of the targets specified. If two conflicting
2451 rules apply, and both have commands, that's an error.
2453 The static pattern rule can be better than an implicit rule for these
2458 You may wish to override the usual implicit rule for a few
2459 files whose names cannot be categorized syntactically but
2460 can be given in an explicit list.
2463 If you cannot be sure of the precise contents of the directories
2464 you are using, you may not be sure which other irrelevant files
2465 might lead @code{make} to use the wrong implicit rule. The choice
2466 might depend on the order in which the implicit rule search is done.
2467 With static pattern rules, there is no uncertainty: each rule applies
2468 to precisely the targets specified.
2471 @node Double-Colon, Automatic Dependencies, Static Pattern, Rules
2472 @section Double-Colon Rules
2473 @cindex double-colon rules
2474 @cindex rule, double-colon (@code{::})
2475 @cindex multiple rules for one target (@code{::})
2476 @cindex @code{::} rules (double-colon)
2478 @dfn{Double-colon} rules are rules written with @samp{::} instead of
2479 @samp{:} after the target names. They are handled differently from
2480 ordinary rules when the same target appears in more than one rule.
2482 When a target appears in multiple rules, all the rules must be the same
2483 type: all ordinary, or all double-colon. If they are double-colon, each of
2484 them is independent of the others. Each double-colon rule's commands are
2485 executed if the target is older than any dependencies of that rule. This
2486 can result in executing none, any, or all of the double-colon rules.
2488 Double-colon rules with the same target are in fact completely separate
2489 from one another. Each double-colon rule is processed individually, just
2490 as rules with different targets are processed.
2492 The double-colon rules for a target are executed in the order they appear
2493 in the makefile. However, the cases where double-colon rules really make
2494 sense are those where the order of executing the commands would not matter.
2496 Double-colon rules are somewhat obscure and not often very useful; they
2497 provide a mechanism for cases in which the method used to update a target
2498 differs depending on which dependency files caused the update, and such
2501 Each double-colon rule should specify commands; if it does not, an
2502 implicit rule will be used if one applies.
2503 @xref{Implicit Rules, ,Using Implicit Rules}.
2505 @node Automatic Dependencies, , Double-Colon, Rules
2506 @section Generating Dependencies Automatically
2507 @cindex dependencies, automatic generation
2508 @cindex automatic generation of dependencies
2509 @cindex generating dependencies automatically
2511 In the makefile for a program, many of the rules you need to write often
2512 say only that some object file depends on some header
2513 file. For example, if @file{main.c} uses @file{defs.h} via an
2514 @code{#include}, you would write:
2521 You need this rule so that @code{make} knows that it must remake
2522 @file{main.o} whenever @file{defs.h} changes. You can see that for a
2523 large program you would have to write dozens of such rules in your
2524 makefile. And, you must always be very careful to update the makefile
2525 every time you add or remove an @code{#include}.
2526 @cindex @code{#include}
2528 @cindex @code{-M} (to compiler)
2529 To avoid this hassle, most modern C compilers can write these rules for
2530 you, by looking at the @code{#include} lines in the source files.
2531 Usually this is done with the @samp{-M} option to the compiler.
2532 For example, the command:
2539 generates the output:
2542 main.o : main.c defs.h
2546 Thus you no longer have to write all those rules yourself.
2547 The compiler will do it for you.
2549 @cindex @code{make depend}
2550 With old @code{make} programs, it was traditional practice to use this
2551 compiler feature to generate dependencies on demand with a command like
2552 @samp{make depend}. That command would create a file @file{depend}
2553 containing all the automatically-generated dependencies; then the
2554 makefile could use @code{include} to read them in (@pxref{Include}).
2556 In GNU @code{make}, the feature of remaking makefiles makes this
2557 practice obsolete---you need never tell @code{make} explicitly to
2558 regenerate the dependencies, because it always regenerates any makefile
2559 that is out of date. @xref{Remaking Makefiles}.
2561 The practice we recommend for automatic dependency generation is to have
2562 one makefile corresponding to each source file. For each source file
2563 @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
2564 what files the object file @file{@var{name}.o} depends on. That way
2565 only the source files that have changed need to be rescanned to produce
2566 the new dependencies.
2568 Here is the pattern rule to generate a file of dependencies (i.e., a makefile)
2569 called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
2574 $(CC) -M $(CPPFLAGS) $< | sed 's/$*.o/& $@@/g' > $@@
2579 @xref{Pattern Rules}, for information on defining pattern rules.
2580 @cindex @code{sed} (shell command)
2581 The purpose of the @code{sed} command is to translate (for example):
2584 main.o : main.c defs.h
2591 main.o main.d : main.c defs.h
2596 This makes each @samp{.d} file depend on all the source and header files
2597 that the corresponding @samp{.o} file depends on. @code{make} then
2598 knows it must regenerate the dependencies whenever any of the source or
2599 header files changes.
2601 Once you've defined the rule to remake the @samp{.d} files,
2602 you then use the @code{include} directive to read them all in.
2603 @xref{Include}. For example:
2607 sources = foo.c bar.c
2609 include $(sources:.c=.d)
2614 (This example uses a substitution variable reference to translate the
2615 list of source files @samp{foo.c bar.c} into a list of dependency
2616 makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full
2617 information on substitution references.) Since the @samp{.d} files are
2618 makefiles like any others, @code{make} will remake them as necessary
2619 with no further work from you. @xref{Remaking Makefiles}.
2621 @node Commands, Using Variables, Rules, Top
2622 @chapter Writing the Commands in Rules
2623 @cindex commands, how to write
2624 @cindex rule commands
2625 @cindex writing rule commands
2627 The commands of a rule consist of shell command lines to be executed one by
2628 one. Each command line must start with a tab, except that the first
2629 command line may be attached to the target-and-dependencies line with a
2630 semicolon in between. Blank lines and lines of just comments may appear
2631 among the command lines; they are ignored.
2633 Users use many different shell programs, but commands in makefiles are
2634 always interpreted by @file{/bin/sh} unless the makefile specifies
2635 otherwise. @xref{Execution, ,Command Execution}.
2637 @cindex comments, in commands
2638 @cindex commands, comments in
2639 @cindex @code{#} (comments), in commands
2640 The shell that is in use determines whether comments can be written on
2641 command lines, and what syntax they use. When the shell is
2642 @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
2643 the line. The @samp{#} does not have to be at the beginning of a line.
2644 Text on a line before a @samp{#} is not part of the comment.
2647 * Echoing:: How to control when commands are echoed.
2648 * Execution:: How commands are executed.
2649 * Parallel:: How commands can be executed in parallel.
2650 * Errors:: What happens after a command execution error.
2651 * Interrupts:: What happens when a command is interrupted.
2652 * Recursion:: Invoking @code{make} from makefiles.
2653 * Sequences:: Defining canned sequences of commands.
2654 * Empty Commands:: Defining useful, do-nothing commands.
2657 @node Echoing, Execution, , Commands
2658 @section Command Echoing
2659 @cindex echoing of commands
2660 @cindex silent operation
2661 @cindex @code{@@} (in commands)
2662 @cindex commands, echoing
2663 @cindex printing of commands
2665 Normally @code{make} prints each command line before it is executed.
2666 We call this @dfn{echoing} because it gives the appearance that you
2667 are typing the commands yourself.
2669 When a line starts with @samp{@@}, the echoing of that line is suppressed.
2670 The @samp{@@} is discarded before the command is passed to the shell.
2671 Typically you would use this for a command whose only effect is to print
2672 something, such as an @code{echo} command to indicate progress through
2676 @@echo About to make distribution files
2680 @cindex @code{--just-print}
2681 @cindex @code{--dry-run}
2682 @cindex @code{--recon}
2683 When @code{make} is given the flag @samp{-n} or @samp{--just-print},
2684 echoing is all that happens, no execution. @xref{Options Summary,
2685 ,Summary of Options}. In this case and only this case, even the
2686 commands starting with @samp{@@} are printed. This flag is useful for
2687 finding out which commands @code{make} thinks are necessary without
2688 actually doing them.
2691 @cindex @code{--silent}
2692 @cindex @code{--quiet}
2694 The @samp{-s} or @samp{--silent}
2695 flag to @code{make} prevents all echoing, as if all commands
2696 started with @samp{@@}. A rule in the makefile for the special target
2697 @code{.SILENT} has the same effect
2698 (@pxref{Special Targets, ,Special Built-in Target Names}).
2699 @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
2701 @node Execution, Parallel, Echoing, Commands
2702 @section Command Execution
2703 @cindex commands, execution
2704 @cindex execution, of commands
2705 @cindex shell command, execution
2706 @vindex SHELL @r{(command execution)}
2708 When it is time to execute commands to update a target, they are executed
2709 by making a new subshell for each line. (In practice, @code{make} may
2710 take shortcuts that do not affect the results.)
2712 @cindex @code{cd} (shell command)
2713 @strong{Please note:} this implies that shell commands such as
2714 @code{cd} that set variables local to each process will not affect the
2715 following command lines. If you want to use @code{cd} to affect the
2716 next command, put the two on a single line with a semicolon between
2717 them. Then @code{make} will consider them a single command and pass
2718 them, together, to a shell which will execute them in sequence. For
2723 cd bar; gobble lose > ../foo
2726 @cindex commands, backslash (@code{\}) in
2727 @cindex commands, quoting newlines in
2728 @cindex backslash (@code{\}), in commands
2729 @cindex @code{\} (backslash), in commands
2730 @cindex quoting newline, in commands
2731 @cindex newline, quoting, in commands
2732 If you would like to split a single shell command into multiple lines of
2733 text, you must use a backslash at the end of all but the last subline.
2734 Such a sequence of lines is combined into a single line, by deleting the
2735 backslash-newline sequences, before passing it to the shell. Thus, the
2736 following is equivalent to the preceding example:
2742 gobble lose > ../foo
2747 The program used as the shell is taken from the variable @code{SHELL}.
2748 By default, the program @file{/bin/sh} is used.
2750 @cindex environment, @code{SHELL} in
2751 Unlike most variables, the variable @code{SHELL} is never set from the
2752 environment. This is because the @code{SHELL} environment variable is
2753 used to specify your personal choice of shell program for interactive
2754 use. It would be very bad for personal choices like this to affect
2755 the functioning of makefiles. @xref{Environment, ,Variables from the
2758 @node Parallel, Errors, Execution, Commands
2759 @section Parallel Execution
2760 @cindex commands, execution in parallel
2761 @cindex parallel execution
2762 @cindex execution, in parallel
2765 @cindex @code{--jobs}
2767 GNU @code{make} knows how to execute several commands at once.
2768 Normally, @code{make} will execute only one command at a time, waiting
2769 for it to finish before executing the next. However, the @samp{-j} or
2770 @samp{--jobs} option tells @code{make} to execute many commands
2771 simultaneously.@refill
2773 If the @samp{-j} option is followed by an integer, this is the number of
2774 commands to execute at once; this is called the number of @dfn{job slots}.
2775 If there is nothing looking like an integer after the @samp{-j} option,
2776 there is no limit on the number of job slots. The default number of job
2777 slots is one, which means serial execution (one thing at a time).
2779 One unpleasant consequence of running several commands simultaneously is
2780 that output from all of the commands comes when the commands send it, so
2781 messages from different commands may be interspersed.
2783 Another problem is that two processes cannot both take input from the
2784 same device; so to make sure that only one command tries to take input
2785 from the terminal at once, @code{make} will invalidate the standard
2786 input streams of all but one running command. This means that
2787 attempting to read from standard input will usually be a fatal error (a
2788 @samp{Broken pipe} signal) for most child processes if there are
2791 @cindex standard input
2793 It is unpredictable which command will have a valid standard input stream
2794 (which will come from the terminal, or wherever you redirect the standard
2795 input of @code{make}). The first command run will always get it first, and
2796 the first command started after that one finishes will get it next, and so
2799 We will change how this aspect of @code{make} works if we find a better
2800 alternative. In the mean time, you should not rely on any command using
2801 standard input at all if you are using the parallel execution feature; but
2802 if you are not using this feature, then standard input works normally in
2805 If a command fails (is killed by a signal or exits with a nonzero
2806 status), and errors are not ignored for that command
2807 (@pxref{Errors, ,Errors in Commands}),
2808 the remaining command lines to remake the same target will not be run.
2809 If a command fails and the @samp{-k} or @samp{--keep-going}
2810 option was not given
2811 (@pxref{Options Summary, ,Summary of Options}),
2812 @code{make} aborts execution. If make
2813 terminates for any reason (including a signal) with child processes
2814 running, it waits for them to finish before actually exiting.@refill
2816 @cindex load average
2817 @cindex limiting jobs based on load
2818 @cindex jobs, limiting based on load
2819 @cindex @code{-l} (load average)
2820 @cindex @code{--max-load}
2821 @cindex @code{--load-average}
2822 When the system is heavily loaded, you will probably want to run fewer jobs
2823 than when it is lightly loaded. You can use the @samp{-l} option to tell
2824 @code{make} to limit the number of jobs to run at once, based on the load
2825 average. The @samp{-l} or @samp{--max-load}
2826 option is followed by a floating-point number. For
2834 will not let @code{make} start more than one job if the load average is
2835 above 2.5. The @samp{-l} option with no following number removes the
2836 load limit, if one was given with a previous @samp{-l} option.@refill
2838 More precisely, when @code{make} goes to start up a job, and it already has
2839 at least one job running, it checks the current load average; if it is not
2840 lower than the limit given with @samp{-l}, @code{make} waits until the load
2841 average goes below that limit, or until all the other jobs finish.
2843 By default, there is no load limit.
2845 @node Errors, Interrupts, Parallel, Commands
2846 @section Errors in Commands
2847 @cindex errors (in commands)
2848 @cindex commands, errors in
2849 @cindex exit status (errors)
2851 After each shell command returns, @code{make} looks at its exit status.
2852 If the command completed successfully, the next command line is executed
2853 in a new shell; after the last command line is finished, the rule is
2856 If there is an error (the exit status is nonzero), @code{make} gives up on
2857 the current rule, and perhaps on all rules.
2859 Sometimes the failure of a certain command does not indicate a problem.
2860 For example, you may use the @code{mkdir} command to ensure that a
2861 directory exists. If the directory already exists, @code{mkdir} will
2862 report an error, but you probably want @code{make} to continue regardless.
2864 @cindex @code{-} (in commands)
2865 To ignore errors in a command line, write a @samp{-} at the beginning of
2866 the line's text (after the initial tab). The @samp{-} is discarded before
2867 the command is passed to the shell for execution.
2877 @cindex @code{rm} (shell command)
2880 This causes @code{rm} to continue even if it is unable to remove a file.
2883 @cindex @code{--ignore-errors}
2885 When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
2886 flag, errors are ignored in
2887 all commands of all rules. A rule in the makefile for the special target
2888 @code{.IGNORE} has the same effect. These ways of ignoring errors are
2889 obsolete because @samp{-} is more flexible.
2891 When errors are to be ignored, because of either a @samp{-} or the
2892 @samp{-i} flag, @code{make} treats an error return just like success,
2893 except that it prints out a message that tells you the status code
2894 the command exited with, and says that the error has been ignored.
2896 When an error happens that @code{make} has not been told to ignore,
2897 it implies that the current target cannot be correctly remade, and neither
2898 can any other that depends on it either directly or indirectly. No further
2899 commands will be executed for these targets, since their preconditions
2900 have not been achieved.
2903 @cindex @code{--keep-going}
2904 Normally @code{make} gives up immediately in this circumstance, returning a
2905 nonzero status. However, if the @samp{-k} or @samp{--keep-going}
2906 flag is specified, @code{make}
2907 continues to consider the other dependencies of the pending targets,
2908 remaking them if necessary, before it gives up and returns nonzero status.
2909 For example, after an error in compiling one object file, @samp{make -k}
2910 will continue compiling other object files even though it already knows
2911 that linking them will be impossible. @xref{Options Summary, ,Summary of Options}.
2913 The usual behavior assumes that your purpose is to get the specified
2914 targets up to date; once @code{make} learns that this is impossible, it
2915 might as well report the failure immediately. The @samp{-k} option says
2916 that the real purpose is to test as many of the changes made in the
2917 program as possible, perhaps to find several independent problems so
2918 that you can correct them all before the next attempt to compile. This
2919 is why Emacs' @code{compile} command passes the @samp{-k} flag by
2921 @cindex Emacs (@code{M-x compile})
2923 @node Interrupts, Recursion, Errors, Commands
2924 @section Interrupting or Killing @code{make}
2927 @cindex deletion of target files
2928 @cindex target, deleting on interrupt
2929 @cindex killing (interruption)
2931 If @code{make} gets a fatal signal while a command is executing, it may
2932 delete the target file that the command was supposed to update. This is
2933 done if the target file's last-modification time has changed since
2934 @code{make} first checked it.
2936 The purpose of deleting the target is to make sure that it is remade from
2937 scratch when @code{make} is next run. Why is this? Suppose you type
2938 @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
2939 object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting
2940 in an incomplete file whose last-modification time is newer than the source
2941 file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal
2942 and deletes this incomplete file. If @code{make} did not do this, the next
2943 invocation of @code{make} would think that @file{foo.o} did not require
2944 updating---resulting in a strange error message from the linker when it
2945 tries to link an object file half of which is missing.
2948 You can prevent the deletion of a target file in this way by making the
2949 special target @code{.PRECIOUS} depend on it. Before remaking a target,
2950 @code{make} checks to see whether it appears on the dependencies of
2951 @code{.PRECIOUS}, and thereby decides whether the target should be deleted
2952 if a signal happens. Some reasons why you might do this are that the
2953 target is updated in some atomic fashion, or exists only to record a
2954 modification-time (its contents do not matter), or must exist at all
2955 times to prevent other sorts of trouble.
2957 @node Recursion, Sequences, Interrupts, Commands
2958 @section Recursive Use of @code{make}
2960 @cindex subdirectories, recursion for
2962 Recursive use of @code{make} means using @code{make} as a command in a
2963 makefile. This technique is useful when you want separate makefiles for
2964 various subsystems that compose a larger system. For example, suppose you
2965 have a subdirectory @file{subdir} which has its own makefile, and you would
2966 like the containing directory's makefile to run @code{make} on the
2967 subdirectory. You can do it by writing this:
2975 or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
2982 @cindex @code{--directory}
2984 You can write recursive @code{make} commands just by copying this example,
2985 but there are many things to know about how they work and why, and about
2986 how the sub-@code{make} relates to the top-level @code{make}.
2989 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
2990 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
2991 * Options/Recursion:: How to communicate options to a sub-@code{make}.
2992 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
2993 helps debug use of recursive @code{make} commands.
2996 @node MAKE Variable, Variables/Recursion, , Recursion
2997 @subsection How the @code{MAKE} Variable Works
2999 @cindex recursion, and @code{MAKE} variable
3001 Recursive @code{make} commands should always use the variable @code{MAKE},
3002 not the explicit command name @samp{make}, as shown here:
3011 The value of this variable is the file name with which @code{make} was
3012 invoked. If this file name was @file{/bin/make}, then the command executed
3013 is @samp{cd subdir; /bin/make}. If you use a special version of
3014 @code{make} to run the top-level makefile, the same special version will be
3015 executed for recursive invocations.
3016 @cindex @code{cd} (shell command)
3018 Also, any arguments that define variable values are added to @code{MAKE},
3019 so the sub-@code{make} gets them too. Thus, if you do @samp{make
3020 CFLAGS=-O}, so that all C compilations will be optimized, the
3021 sub-@code{make} is run with @samp{cd subdir; /bin/make CFLAGS=-O}.@refill
3023 @vindex MAKE_COMMAND
3024 @vindex MAKEOVERRIDES
3025 The @code{MAKE} variable actually just refers to two other variables
3026 which contain these special values. In fact, @code{MAKE} is always
3027 defined as @samp{$(MAKE_COMMAND) $(MAKEOVERRIDES)}. The variable
3028 @code{MAKE_COMMAND} is the file name with which @code{make} was invoked
3029 (such as @file{/bin/make}, above). The variable @code{MAKEOVERRIDES}
3030 contains definitions for the variables defined on the command line; in
3031 the above example, its value is @samp{CFLAGS=-O}. If you @emph{do not}
3032 want these variable definitions done in all recursive @code{make}
3033 invocations, you can redefine the @code{MAKEOVERRIDES} variable to
3034 remove them. You do this in any of the normal ways for defining
3035 variables: in a makefile (@pxref{Setting, ,Setting Variables}); on the command
3036 line with an argument like @samp{MAKEOVERRIDES=}
3037 (@pxref{Overriding, ,Overriding Variables}); or with an environment variable
3038 (@pxref{Environment, ,Variables from the Environment}).
3040 As a special feature, using the variable @code{MAKE} in the commands of
3041 a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
3042 (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
3043 Using the @code{MAKE} variable has the same effect as using a @samp{+}
3044 character at the beginning of the command line. @xref{Instead of
3045 Execution, ,Instead of Executing the Commands}.@refill
3047 Consider the command @samp{make -t} in the above example. (The
3048 @samp{-t} option marks targets as up to date without actually running
3049 any commands; see @ref{Instead of Execution}.) Following the usual
3050 definition of @samp{-t}, a @samp{make -t} command in the example would
3051 create a file named @file{subsystem} and do nothing else. What you
3052 really want it to do is run @samp{@w{cd subdir;} @w{make -t}}; but that would
3053 require executing the command, and @samp{-t} says not to execute
3055 @cindex @code{-t}, and recursion
3056 @cindex recursion, and @code{-t}
3057 @cindex @code{--touch}, and recursion
3059 The special feature makes this do what you want: whenever a command
3060 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
3061 @samp{-n} and @samp{-q} do not apply to that line. Command lines
3062 containing @code{MAKE} are executed normally despite the presence of a
3063 flag that causes most commands not to be run. The usual
3064 @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
3065 (@pxref{Options/Recursion, ,Communicating Options to a
3066 Sub-@code{make}}), so your request to touch the files, or print the
3067 commands, is propagated to the subsystem.@refill
3069 @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
3070 @subsection Communicating Variables to a Sub-@code{make}
3071 @cindex sub-@code{make}
3072 @cindex environment, and recursion
3073 @cindex exporting variables
3074 @cindex variables, environment
3075 @cindex variables, exporting
3076 @cindex recursion, and environment
3077 @cindex recursion, and variables
3079 Variable values of the top-level @code{make} can be passed to the
3080 sub-@code{make} through the environment by explicit request. These
3081 variables are defined in the sub-@code{make} as defaults, but do not
3082 override what is specified in the sub-@code{make}'s makefile unless
3083 you use the @samp{-e} switch
3084 (@pxref{Options Summary, ,Summary of Options}).@refill
3086 To pass down, or @dfn{export}, a variable, @code{make} adds the variable
3087 and its value to the environment for running each command. The
3088 sub-@code{make}, in turn, uses the environment to initialize its table
3089 of variable values. @xref{Environment, ,Variables from the
3092 Except by explicit request, @code{make} exports a variable only if it
3093 is either defined in the environment initially or set on the command
3094 line, and if its name consists only of letters, numbers, and underscores.
3095 Some shells cannot cope with environment variable names consisting of
3096 characters other than letters, numbers, and underscores.
3098 The special variables @code{SHELL} and @code{MAKEFLAGS} are always
3099 exported (unless you unexport them).
3100 @code{MAKEFILES} is exported if you set it to anything.
3102 Variables are @emph{not} normally passed down if they were created by
3103 default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
3104 Implicit Rules}). The sub-@code{make} will define these for
3108 If you want to export specific variables to a sub-@code{make}, use the
3109 @code{export} directive, like this:
3112 export @var{variable} @dots{}
3117 If you want to @emph{prevent} a variable from being exported, use the
3118 @code{unexport} directive, like this:
3121 unexport @var{variable} @dots{}
3125 As a convenience, you can define a variable and export it at the same
3129 export @var{variable} = value
3133 has the same result as:
3136 @var{variable} = value
3137 export @var{variable}
3144 export @var{variable} := value
3148 has the same result as:
3151 @var{variable} := value
3152 export @var{variable}
3158 export @var{variable} += value
3165 @var{variable} += value
3166 export @var{variable}
3170 @xref{Appending, ,Appending More Text to Variables}.
3172 You may notice that the @code{export} and @code{unexport} directives
3173 work in @code{make} in the same way they work in the shell, @code{sh}.
3175 If you want all variables to be exported by default, you can use
3176 @code{export} by itself:
3183 This tells @code{make} that variables which are not explicitly mentioned
3184 in an @code{export} or @code{unexport} directive should be exported.
3185 Any variable given in an @code{unexport} directive will still @emph{not}
3186 be exported. If you use @code{export} by itself to export variables by
3187 default, variables whose names contain characters other than
3188 alphanumerics and underscores will not be exported unless specifically
3189 mentioned in an @code{export} directive.@refill
3191 @findex .EXPORT_ALL_VARIABLES
3192 The behavior elicited by an @code{export} directive by itself was the
3193 default in older versions of GNU @code{make}. If your makefiles depend
3194 on this behavior and you want to be compatible with old versions of
3195 @code{make}, you can write a rule for the special target
3196 @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
3197 This will be ignored by old @code{make}s, while the @code{export}
3198 directive will cause a syntax error.@refill
3199 @cindex compatibility in exporting
3201 Likewise, you can use @code{unexport} by itself to tell @code{make}
3202 @emph{not} to export variables by default. Since this is the default
3203 behavior, you would only need to do this if @code{export} had been used
3204 by itself earlier (in an included makefile, perhaps). You
3205 @strong{cannot} use @code{export} and @code{unexport} by themselves to
3206 have variables exported for some commands and not for others. The last
3207 @code{export} or @code{unexport} directive that appears by itself
3208 determines the behavior for the entire run of @code{make}.@refill
3211 @cindex recursion, level of
3212 As a special feature, the variable @code{MAKELEVEL} is changed when it
3213 is passed down from level to level. This variable's value is a string
3214 which is the depth of the level as a decimal number. The value is
3215 @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
3216 @samp{2} for a sub-sub-@code{make}, and so on. The incrementation
3217 happens when @code{make} sets up the environment for a command.@refill
3219 The main use of @code{MAKELEVEL} is to test it in a conditional
3220 directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
3221 way you can write a makefile that behaves one way if run recursively and
3222 another way if run directly by you.@refill
3225 You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
3226 commands to use additional makefiles. The value of @code{MAKEFILES} is
3227 a whitespace-separated list of file names. This variable, if defined in
3228 the outer-level makefile, is passed down through the environment; then
3229 it serves as a list of extra makefiles for the sub-@code{make} to read
3230 before the usual or specified ones. @xref{MAKEFILES Variable, ,The
3231 Variable @code{MAKEFILES}}.@refill
3233 @node Options/Recursion, -w Option, Variables/Recursion, Recursion
3234 @subsection Communicating Options to a Sub-@code{make}
3235 @cindex options, and recursion
3236 @cindex recursion, and options
3239 Flags such as @samp{-s} and @samp{-k} are passed automatically to the
3240 sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
3241 set up automatically by @code{make} to contain the flag letters that
3242 @code{make} received. Thus, if you do @w{@samp{make -ks}} then
3243 @code{MAKEFLAGS} gets the value @samp{ks}.@refill
3245 As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
3246 in its environment. In response, it takes the flags from that value and
3247 processes them as if they had been given as arguments.
3248 @xref{Options Summary, ,Summary of Options}.
3250 @cindex @code{-C}, and recursion
3251 @cindex @code{-f}, and recursion
3252 @cindex @code{-I}, and recursion
3253 @cindex @code{-o}, and recursion
3254 @cindex @code{-W}, and recursion
3255 @cindex @code{--directory}, and recursion
3256 @cindex @code{--file}, and recursion
3257 @cindex @code{--include-dir}, and recursion
3258 @cindex @code{--old-file}, and recursion
3259 @cindex @code{--assume-old}, and recursion
3260 @cindex @code{--assume-new}, and recursion
3261 @cindex @code{--new-file}, and recursion
3262 @cindex recursion, and @code{-C}
3263 @cindex recursion, and @code{-f}
3264 @cindex recursion, and @code{-I}
3265 @cindex recursion, and @code{-o}
3266 @cindex recursion, and @code{-W}
3267 The options @samp{-C}, @samp{-f}, @samp{-I}, @samp{-o}, and @samp{-W}
3268 are not put into @code{MAKEFLAGS}; these options are not passed down.@refill
3270 @cindex @code{-j}, and recursion
3271 @cindex @code{--jobs}, and recursion
3272 @cindex recursion, and @code{-j}
3273 @cindex job slots, and recursion
3274 The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
3275 If you set it to some numeric value, @samp{-j 1} is always put into
3276 @code{MAKEFLAGS} instead of the value you specified. This is because if
3277 the @w{@samp{-j}} option were passed down to sub-@code{make}s, you would
3278 get many more jobs running in parallel than you asked for. If you give
3279 @samp{-j} with no numeric argument, meaning to run as many jobs as
3280 possible in parallel, this is passed down, since multiple infinities are
3281 no more than one.@refill
3283 If you do not want to pass the other flags down, you must change the
3284 value of @code{MAKEFLAGS}, like this:
3296 cd subdir; $(MAKE) MAKEFLAGS=
3300 A similar variable @code{MFLAGS} exists also, for historical compatibility.
3301 It has the same value as @code{MAKEFLAGS} except that it always begins with
3302 a hyphen unless it is empty (@code{MAKEFLAGS} begins with a hyphen only when
3303 it begins with an option that has no single-letter version, such as
3304 @samp{--warn-undefined-variables}). @code{MFLAGS} was traditionally used
3305 explicitly in the recursive @code{make} command, like this:
3309 cd subdir; $(MAKE) $(MFLAGS)
3313 but now @code{MAKEFLAGS} makes this usage redundant.
3315 @cindex setting options from environment
3316 @cindex options, setting from environment
3317 @cindex setting options in makefiles
3318 @cindex options, setting in makefiles
3319 The @code{MAKEFLAGS} and @code{MFLAGS} variables can also be useful if you
3320 want to have certain options, such as @samp{-k} (@pxref{Options Summary,
3321 ,Summary of Options}), set each time you run @code{make}. You simply put a
3322 value for @code{MAKEFLAGS} or @code{MFLAGS} in your environment. These
3323 variables may also be set in makefiles, so a makefile can specify additional
3324 flags that should also be in effect for that makefile.
3326 When @code{make} interprets the value of @code{MAKEFLAGS} or @code{MFLAGS}
3327 (either from the environment or from a makefile), it first prepends a hyphen
3328 if the value does not already begin with one. Then it chops the value into
3329 words separated by blanks, and parses these words as if they were options
3330 given on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
3331 @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
3332 is no error for an invalid option).
3334 If you do put @code{MAKEFLAGS} or @code{MFLAGS} in your environment, you
3335 should be sure not to include any options that will drastically affect
3336 the actions of @code{make} and undermine the purpose of makefiles and of
3337 @code{make} itself. For instance, the @samp{-t}, @samp{-n}, and
3338 @samp{-q} options, if put in one of these variables, could have
3339 disastrous consequences and would certainly have at least surprising and
3340 probably annoying effects.@refill
3342 @node -w Option, , Options/Recursion, Recursion
3343 @subsection The @samp{--print-directory} Option
3344 @cindex directories, printing them
3345 @cindex printing directories
3346 @cindex recursion, and printing directories
3348 If you use several levels of recursive @code{make} invocations, the
3349 @samp{-w} or @w{@samp{--print-directory}} option can make the output a
3350 lot easier to understand by showing each directory as @code{make}
3351 starts processing it and as @code{make} finishes processing it. For
3352 example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
3353 @code{make} will print a line of the form:@refill
3356 make: Entering directory `/u/gnu/make'.
3360 before doing anything else, and a line of the form:
3363 make: Leaving directory `/u/gnu/make'.
3367 when processing is completed.
3369 @cindex @code{-C}, and @code{-w}
3370 @cindex @code{--directory}, and @code{--print-directory}
3371 @cindex recursion, and @code{-w}
3372 @cindex @code{-w}, and @code{-C}
3373 @cindex @code{-w}, and recursion
3374 @cindex @code{--print-directory}, and @code{--directory}
3375 @cindex @code{--print-directory}, and recursion
3376 @cindex @code{--no-print-directory}
3377 @cindex @code{--print-directory}, disabling
3378 @cindex @code{-w}, disabling
3379 Normally, you do not need to specify this option because @samp{make}
3380 does it for you: @samp{-w} is turned on automatically when you use the
3381 @samp{-C} option, and in sub-@code{make}s. @code{make} will not
3382 automatically turn on @samp{-w} if you also use @samp{-s}, which says to
3383 be silent, or if you use @samp{--no-print-directory} to explicitly
3386 @node Sequences, Empty Commands, Recursion, Commands
3387 @section Defining Canned Command Sequences
3388 @cindex sequences of commands
3389 @cindex commands, sequences of
3391 When the same sequence of commands is useful in making various targets, you
3392 can define it as a canned sequence with the @code{define} directive, and
3393 refer to the canned sequence from the rules for those targets. The canned
3394 sequence is actually a variable, so the name must not conflict with other
3397 Here is an example of defining a canned sequence of commands:
3401 yacc $(firstword $^)
3408 Here @code{run-yacc} is the name of the variable being defined;
3409 @code{endef} marks the end of the definition; the lines in between are the
3410 commands. The @code{define} directive does not expand variable references
3411 and function calls in the canned sequence; the @samp{$} characters,
3412 parentheses, variable names, and so on, all become part of the value of the
3413 variable you are defining.
3414 @xref{Defining, ,Defining Variables Verbatim},
3415 for a complete explanation of @code{define}.
3417 The first command in this example runs Yacc on the first dependency of
3418 whichever rule uses the canned sequence. The output file from Yacc is
3419 always named @file{y.tab.c}. The second command moves the output to the
3420 rule's target file name.
3422 To use the canned sequence, substitute the variable into the commands of a
3423 rule. You can substitute it like any other variable
3424 (@pxref{Reference, ,Basics of Variable References}).
3425 Because variables defined by @code{define} are recursively expanded
3426 variables, all the variable references you wrote inside the @code{define}
3427 are expanded now. For example:
3435 @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
3436 @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
3438 This is a realistic example, but this particular one is not needed in
3439 practice because @code{make} has an implicit rule to figure out these
3440 commands based on the file names involved
3441 (@pxref{Implicit Rules, ,Using Implicit Rules}).
3443 @cindex @@, and @code{define}
3444 @cindex -, and @code{define}
3445 @cindex +, and @code{define}
3446 In command execution, each line of a canned sequence is treated just as
3447 if the line appeared on its own in the rule, preceded by a tab. In
3448 particular, @code{make} invokes a separate subshell for each line. You
3449 can use the special prefix characters that affect command lines
3450 (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
3451 @xref{Commands, ,Writing the Commands in Rules}.
3452 For example, using this canned sequence:
3456 @@echo "frobnicating target $@@"
3457 frob-step-1 $< -o $@@-step-1
3458 frob-step-2 $@@-step-1 -o $@@
3463 @code{make} will not echo the first line, the @code{echo} command.
3464 But it @emph{will} echo the following two command lines.
3466 On the other hand, prefix characters on the command line that refers to
3467 a canned sequence apply to every line in the sequence. So the rule:
3475 does not echo @emph{any} commands.
3476 (@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.)
3478 @node Empty Commands, , Sequences, Commands
3479 @section Using Empty Commands
3480 @cindex empty commands
3481 @cindex commands, empty
3483 It is sometimes useful to define commands which do nothing. This is done
3484 simply by giving a command that consists of nothing but whitespace. For
3492 defines an empty command string for @file{target}. You could also use a
3493 line beginning with a tab character to define an empty command string,
3494 but this would be confusing because such a line looks empty.
3496 @findex .DEFAULT@r{, and empty commands}
3497 You may be wondering why you would want to define a command string that
3498 does nothing. The only reason this is useful is to prevent a target
3499 from getting implicit commands (from implicit rules or the
3500 @code{.DEFAULT} special target; @pxref{Implicit Rules} and
3501 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
3503 You may be inclined to define empty command strings for targets that are
3504 not actual files, but only exist so that their dependencies can be
3505 remade. However, this is not the best way to do that, because the
3506 dependencies may not be remade properly if the target file actually does exist.
3507 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
3509 @node Using Variables, Conditionals, Commands, Top
3510 @chapter How to Use Variables
3513 @cindex recursive variable expansion
3514 @cindex simple variable expansion
3516 A @dfn{variable} is a name defined in a makefile to represent a string
3517 of text, called the variable's @dfn{value}. These values are
3518 substituted by explicit request into targets, dependencies, commands,
3519 and other parts of the makefile. (In some other versions of @code{make},
3520 variables are called @dfn{macros}.)
3523 Variables and functions in all parts of a makefile are expanded when
3524 read, except for the shell commands in rules, the right-hand sides of
3525 variable definitions using @samp{=}, and the bodies of variable
3526 definitions using the @code{define} directive.@refill
3528 Variables can represent lists of file names, options to pass to compilers,
3529 programs to run, directories to look in for source files, directories to
3530 write output in, or anything else you can imagine.
3532 A variable name may be any sequence of characters not containing @samp{:},
3533 @samp{#}, @samp{=}, or leading or trailing whitespace. However,
3534 variable names containing characters other than letters, numbers, and
3535 underscores should be avoided, as they may be given special meanings in the
3536 future, and with some shells they cannot be passed through the environment to a
3538 (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
3540 Variable names are case-sensitive. The names @samp{foo}, @samp{FOO},
3541 and @samp{Foo} all refer to different variables.
3543 It is traditional to use upper case letters in variable names, but we
3544 recommend using lower case letters for variable names that serve internal
3545 purposes in the makefile, and reserving upper case for parameters that
3546 control implicit rules or for parameters that the user should override with
3547 command options (@pxref{Overriding, ,Overriding Variables}).
3550 * Reference:: How to use the value of a variable.
3551 * Flavors:: Variables come in two flavors.
3552 * Advanced:: Advanced features for referencing a variable.
3553 * Values:: All the ways variables get their values.
3554 * Setting:: How to set a variable in the makefile.
3555 * Appending:: How to append more text to the old value
3557 * Override Directive:: How to set a variable in the makefile even if
3558 the user has set it with a command argument.
3559 * Defining:: An alternate way to set a variable
3560 to a verbatim string.
3561 * Environment:: Variable values can come from the environment.
3564 @node Reference, Flavors, , Using Variables
3565 @section Basics of Variable References
3566 @cindex variables, how to reference
3567 @cindex reference to variables
3568 @cindex @code{$}, in variable reference
3569 @cindex dollar sign (@code{$}), in variable reference
3571 To substitute a variable's value, write a dollar sign followed by the name
3572 of the variable in parentheses or braces: either @samp{$(foo)} or
3573 @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This
3574 special significance of @samp{$} is why you must write @samp{$$} to have
3575 the effect of a single dollar sign in a file name or command.
3577 Variable references can be used in any context: targets, dependencies,
3578 commands, most directives, and new variable values. Here is an
3579 example of a common case, where a variable holds the names of all the
3580 object files in a program:
3584 objects = program.o foo.o utils.o
3585 program : $(objects)
3586 cc -o program $(objects)
3592 Variable references work by strict textual substitution. Thus, the rule
3597 prog.o : prog.$(foo)
3598 $(foo)$(foo) -$(foo) prog.$(foo)
3603 could be used to compile a C program @file{prog.c}. Since spaces before
3604 the variable value are ignored in variable assignments, the value of
3605 @code{foo} is precisely @samp{c}. (Don't actually write your makefiles
3608 A dollar sign followed by a character other than a dollar sign,
3609 open-parenthesis or open-brace treats that single character as the
3610 variable name. Thus, you could reference the variable @code{x} with
3611 @samp{$x}. However, this practice is strongly discouraged, except in
3612 the case of the automatic variables (@pxref{Automatic, ,Automatic Variables}).
3614 @node Flavors, Advanced, Reference, Using Variables
3615 @section The Two Flavors of Variables
3616 @cindex flavors of variables
3617 @cindex recursive variable expansion
3618 @cindex variables, flavors
3619 @cindex recursively expanded variables
3620 @cindex variables, recursively expanded
3622 There are two ways that a variable in GNU @code{make} can have a value;
3623 we call them the two @dfn{flavors} of variables. The two flavors are
3624 distinguished in how they are defined and in what they do when expanded.
3627 The first flavor of variable is a @dfn{recursively expanded} variable.
3628 Variables of this sort are defined by lines using @samp{=}
3629 (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
3630 (@pxref{Defining, ,Defining Variables Verbatim}). The value you specify
3631 is installed verbatim; if it contains references to other variables,
3632 these references are expanded whenever this variable is substituted (in
3633 the course of expanding some other string). When this happens, it is
3634 called @dfn{recursive expansion}.@refill
3647 will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
3648 expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
3650 This flavor of variable is the only sort supported by other versions of
3651 @code{make}. It has its advantages and its disadvantages. An advantage
3652 (most would say) is that:
3655 CFLAGS = $(include_dirs) -O
3656 include_dirs = -Ifoo -Ibar
3660 will do what was intended: when @samp{CFLAGS} is expanded in a command,
3661 it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you
3662 cannot append something on the end of a variable, as in
3665 CFLAGS = $(CFLAGS) -O
3669 because it will cause an infinite loop in the variable expansion.
3670 (Actually @code{make} detects the infinite loop and reports an error.)
3671 @cindex loops in variable expansion
3672 @cindex variables, loops in expansion
3674 Another disadvantage is that any functions
3675 (@pxref{Functions, ,Functions for Transforming Text})
3676 referenced in the definition will be executed every time the variable is
3677 expanded. This makes @code{make} run slower; worse, it causes the
3678 @code{wildcard} and @code{shell} functions to give unpredictable results
3679 because you cannot easily control when they are called, or even how many
3682 To avoid all the problems and inconveniences of recursively expanded
3683 variables, there is another flavor: simply expanded variables.
3685 @cindex simply expanded variables
3686 @cindex variables, simply expanded
3688 @dfn{Simply expanded variables} are defined by lines using @samp{:=}
3689 (@pxref{Setting, ,Setting Variables}).
3690 The value of a simply expanded variable is scanned
3691 once and for all, expanding any references to other variables and
3692 functions, when the variable is defined. The actual value of the simply
3693 expanded variable is the result of expanding the text that you write.
3694 It does not contain any references to other variables; it contains their
3695 values @emph{as of the time this variable was defined}. Therefore,
3711 When a simply expanded variable is referenced, its value is substituted
3714 Here is a somewhat more complicated example, illustrating the use of
3715 @samp{:=} in conjunction with the @code{shell} function.
3716 (@xref{Shell Function, , The @code{shell} Function}.) This example
3717 also shows use of the variable @code{MAKELEVEL}, which is changed
3718 when it is passed down from level to level.
3719 (@xref{Variables/Recursion, , Communicating Variables to a
3720 Sub-@code{make}}, for information about @code{MAKELEVEL}.)
3726 ifeq (0,$@{MAKELEVEL@})
3727 cur-dir := $(shell pwd)
3728 whoami := $(shell whoami)
3729 host-type := $(shell arch)
3730 MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
3736 An advantage of this use of @samp{:=} is that a typical
3737 `descend into a directory' command then looks like this:
3742 $@{MAKE@} cur-dir=$@{cur-dir@}/$@@ -C $@@ all
3746 Simply expanded variables generally make complicated makefile programming
3747 more predictable because they work like variables in most programming
3748 languages. They allow you to redefine a variable using its own value (or
3749 its value processed in some way by one of the expansion functions) and to
3750 use the expansion functions much more efficiently
3751 (@pxref{Functions, ,Functions for Transforming Text}).
3753 @cindex spaces, in variable values
3754 @cindex variables, spaces in values
3755 You can also use them to introduce controlled leading or trailing spaces
3756 into variable values. Such spaces are discarded from your input before
3757 substitution of variable references and function calls; this means you can
3758 include leading or trailing spaces in a variable value by protecting them
3759 with variable references, like this:
3763 space := $(nullstring) $(nullstring)
3767 Here the value of the variable @code{space} is precisely one space.
3769 @node Advanced, Values, Flavors, Using Variables
3770 @section Advanced Features for Reference to Variables
3771 @cindex reference to variables
3773 This section describes some advanced features you can use to reference
3774 variables in more flexible ways.
3777 * Substitution Refs:: Referencing a variable with
3778 substitutions on the value.
3779 * Computed Names:: Computing the name of the variable to refer to.
3782 @node Substitution Refs, Computed Names, , Advanced
3783 @subsection Substitution References
3784 @cindex modified variable reference
3785 @cindex substitution variable reference
3786 @cindex variables, modified reference
3787 @cindex variables, substitution reference
3789 @cindex variables, substituting suffix in
3790 @cindex suffix, substituting in variables
3791 A @dfn{substitution reference} substitutes the value of a variable with
3792 alterations that you specify. It has the form
3793 @samp{$(@var{var}:@var{a}=@var{b})} (or
3794 @samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
3795 of the variable @var{var}, replace every @var{a} at the end of a word with
3796 @var{b} in that value, and substitute the resulting string.
3798 When we say ``at the end of a word'', we mean that @var{a} must appear
3799 either followed by whitespace or at the end of the value in order to be
3800 replaced; other occurrences of @var{a} in the value are unaltered. For
3809 sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}.
3811 A substitution reference is actually an abbreviation for use of the
3812 @code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide
3813 substitution references as well as @code{patsubst} for compatibility with
3814 other implementations of @code{make}.
3817 Another type of substitution reference lets you use the full power of
3818 the @code{patsubst} function. It has the same form
3819 @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
3820 @var{a} must contain a single @samp{%} character. This case is
3821 equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
3822 @xref{Text Functions, ,Functions for String Substitution and Analysis},
3823 for a description of the @code{patsubst} function.@refill
3827 @exdent For example:
3830 bar := $(foo:%.o=%.c)
3835 sets @samp{bar} to @samp{a.c b.c c.c}.
3837 @node Computed Names, , Substitution Refs, Advanced
3838 @subsection Computed Variable Names
3839 @cindex nested variable reference
3840 @cindex computed variable name
3841 @cindex variables, computed names
3842 @cindex variables, nested references
3843 @cindex variables, @samp{$} in name
3844 @cindex @code{$}, in variable name
3845 @cindex dollar sign (@code{$}), in variable name
3847 Computed variable names are a complicated concept needed only for
3848 sophisticated makefile programming. For most purposes you need not
3849 consider them, except to know that making a variable with a dollar sign
3850 in its name might have strange results. However, if you are the type
3851 that wants to understand everything, or you are actually interested in
3852 what they do, read on.
3854 Variables may be referenced inside the name of a variable. This is
3855 called a @dfn{computed variable name} or a @dfn{nested variable
3856 reference}. For example,
3865 defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
3866 to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
3867 to @samp{z}. Here the name of the variable to reference is not stated
3868 explicitly; it is computed by expansion of @samp{$(x)}. The reference
3869 @samp{$(x)} here is nested within the outer variable reference.
3871 The previous example shows two levels of nesting, but any number of levels
3872 is possible. For example, here are three levels:
3882 Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
3883 expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
3884 @samp{$(z)}, which becomes @samp{u}.
3886 References to recursively-expanded variables within a variable name are
3887 reexpanded in the usual fashion. For example:
3897 defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
3898 which becomes @samp{$(z)} which becomes @samp{Hello}.
3900 Nested variable references can also contain modified references and
3901 function invocations (@pxref{Functions, ,Functions for Transforming Text}),
3902 just like any other reference.
3903 For example, using the @code{subst} function
3904 (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
3910 y = $(subst 1,2,$(x))
3917 eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone
3918 would ever want to write a nested reference as convoluted as this one, but
3919 it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
3920 @samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from
3921 @code{x} and changes it by substitution to @samp{variable2}, so that the
3922 entire string becomes @samp{$(variable2)}, a simple variable reference
3923 whose value is @samp{Hello}.@refill
3925 A computed variable name need not consist entirely of a single variable
3926 reference. It can contain several variable references, as well as some
3927 invariant text. For example,
3936 a_files := filea fileb
3937 1_files := file1 file2
3941 ifeq "$(use_a)" "yes"
3949 ifeq "$(use_dirs)" "yes"
3955 dirs := $($(a1)_$(df))
3960 will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
3961 @code{a_files} or @code{1_files} depending on the settings of @code{use_a}
3962 and @code{use_dirs}.@refill
3964 Computed variable names can also be used in substitution references:
3968 a_objects := a.o b.o c.o
3969 1_objects := 1.o 2.o 3.o
3971 sources := $($(a1)_objects:.o=.c)
3976 defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
3977 depending on the value of @code{a1}.
3979 The only restriction on this sort of use of nested variable references
3980 is that they cannot specify part of the name of a function to be called.
3981 This is because the test for a recognized function name is done before
3982 the expansion of nested references. For example,
3998 foo := $($(func) $(bar))
4003 attempts to give @samp{foo} the value of the variable @samp{sort a d b g
4004 q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
4005 as the argument to either the @code{sort} or the @code{strip} function.
4006 This restriction could be removed in the future if that change is shown
4009 You can also use computed variable names in the left-hand side of a
4010 variable assignment, or in a @code{define} directive, as in:
4014 $(dir)_sources := $(wildcard $(dir)/*.c)
4016 lpr $($(dir)_sources)
4021 This example defines the variables @samp{dir}, @samp{foo_sources}, and
4024 Note that @dfn{nested variable references} are quite different from
4025 @dfn{recursively expanded variables}
4026 (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
4027 used together in complex ways when doing makefile programming.@refill
4029 @node Values, Setting, Advanced, Using Variables
4030 @section How Variables Get Their Values
4031 @cindex variables, how they get their values
4032 @cindex value, how a variable gets it
4034 Variables can get values in several different ways:
4038 You can specify an overriding value when you run @code{make}.
4039 @xref{Overriding, ,Overriding Variables}.
4042 You can specify a value in the makefile, either
4043 with an assignment (@pxref{Setting, ,Setting Variables}) or with a
4044 verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
4047 Variables in the environment become @code{make} variables.
4048 @xref{Environment, ,Variables from the Environment}.
4051 Several @dfn{automatic} variables are given new values for each rule.
4052 Each of these has a single conventional use.
4053 @xref{Automatic, ,Automatic Variables}.
4056 Several variables have constant initial values.
4057 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
4060 @node Setting, Appending, Values, Using Variables
4061 @section Setting Variables
4062 @cindex setting variables
4063 @cindex variables, setting
4067 To set a variable from the makefile, write a line starting with the
4068 variable name followed by @samp{=} or @samp{:=}. Whatever follows the
4069 @samp{=} or @samp{:=} on the line becomes the value. For example,
4072 objects = main.o foo.o bar.o utils.o
4076 defines a variable named @code{objects}. Whitespace around the variable
4077 name and immediately after the @samp{=} is ignored.
4079 Variables defined with @samp{=} are @dfn{recursively expanded} variables.
4080 Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
4081 definitions can contain variable references which will be expanded before
4082 the definition is made. @xref{Flavors, ,The Two Flavors of Variables}.
4084 The variable name may contain function and variable references, which
4085 are expanded when the line is read to find the actual variable name to use.
4087 There is no limit on the length of the value of a variable except the
4088 amount of swapping space on the computer. When a variable definition is
4089 long, it is a good idea to break it into several lines by inserting
4090 backslash-newline at convenient places in the definition. This will not
4091 affect the functioning of @code{make}, but it will make the makefile easier
4094 Most variable names are considered to have the empty string as a value if
4095 you have never set them. Several variables have built-in initial values
4096 that are not empty, but you can set them in the usual ways
4097 (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
4098 Several special variables are set
4099 automatically to a new value for each rule; these are called the
4100 @dfn{automatic} variables (@pxref{Automatic, ,Automatic Variables}).
4102 @node Appending, Override Directive, Setting, Using Variables
4103 @section Appending More Text to Variables
4105 @cindex appending to variables
4106 @cindex variables, appending to
4108 Often it is useful to add more text to the value of a variable already defined.
4109 You do this with a line containing @samp{+=}, like this:
4112 objects += another.o
4116 This takes the value of the variable @code{objects}, and adds the text
4117 @samp{another.o} to it (preceded by a single space). Thus:
4120 objects = main.o foo.o bar.o utils.o
4121 objects += another.o
4125 sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
4127 Using @samp{+=} is similar to:
4130 objects = main.o foo.o bar.o utils.o
4131 objects := $(objects) another.o
4135 but differs in ways that become important when you use more complex values.
4137 When the variable in question has not been defined before, @samp{+=}
4138 acts just like normal @samp{=}: it defines a recursively-expanded
4139 variable. However, when there @emph{is} a previous definition, exactly
4140 what @samp{+=} does depends on what flavor of variable you defined
4141 originally. @xref{Flavors, ,The Two Flavors of Variables}, for an
4142 explanation of the two flavors of variables.
4144 When you add to a variable's value with @samp{+=}, @code{make} acts
4145 essentially as if you had included the extra text in the initial
4146 definition of the variable. If you defined it first with @samp{:=},
4147 making it a simply-expanded variable, @samp{+=} adds to that
4148 simply-expanded definition, and expands the new text before appending it
4149 to the old value just as @samp{:=} does
4150 (@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
4159 is exactly equivalent to:
4164 variable := $(variable) more
4167 On the other hand, when you use @samp{+=} with a variable that you defined
4168 first to be recursively-expanded using plain @samp{=}, @code{make} does
4169 something a bit different. Recall that when you define a
4170 recursively-expanded variable, @code{make} does not expand the value you set
4171 for variable and function references immediately. Instead it stores the text
4172 verbatim, and saves these variable and function references to be expanded
4173 later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
4174 of Variables}). When you use @samp{+=} on a recursively-expanded variable,
4175 it is this unexpanded text to which @code{make} appends the new text you
4186 is roughly equivalent to:
4191 variable = $(temp) more
4196 except that of course it never defines a variable called @code{temp}.
4197 The importance of this comes when the variable's old value contains
4198 variable references. Take this common example:
4201 CFLAGS = $(includes) -O
4203 CFLAGS += -pg # enable profiling
4207 The first line defines the @code{CFLAGS} variable with a reference to another
4208 variable, @code{includes}. (@code{CFLAGS} is used by the rules for C
4209 compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
4210 Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
4211 variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
4212 @code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes}
4213 need not be defined yet for its value to take effect. It only has to be
4214 defined before any reference to @code{CFLAGS}. If we tried to append to the
4215 value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
4218 CFLAGS := $(CFLAGS) -pg # enable profiling
4222 This is pretty close, but not quite what we want. Using @samp{:=}
4223 redefines @code{CFLAGS} as a simply-expanded variable; this means
4224 @code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
4225 variable. If @code{includes} is not yet defined, we get @w{@samp{ -O
4226 -pg}}, and a later definition of @code{includes} will have no effect.
4227 Conversely, by using @samp{+=} we set @code{CFLAGS} to the
4228 @emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve
4229 the reference to @code{includes}, so if that variable gets defined at
4230 any later point, a reference like @samp{$(CFLAGS)} still uses its
4233 @node Override Directive, Defining, Appending, Using Variables
4234 @section The @code{override} Directive
4236 @cindex overriding with @code{override}
4237 @cindex variables, overriding
4239 If a variable has been set with a command argument
4240 (@pxref{Overriding, ,Overriding Variables}),
4241 then ordinary assignments in the makefile are ignored. If you want to set
4242 the variable in the makefile even though it was set with a command
4243 argument, you can use an @code{override} directive, which is a line that
4244 looks like this:@refill
4247 override @var{variable} = @var{value}
4254 override @var{variable} := @var{value}
4257 To append more text to a variable defined on the command line, use:
4260 override @var{variable} += @var{more text}
4264 @xref{Appending, ,Appending More Text to Variables}.
4266 The @code{override} directive was not invented for escalation in the war
4267 between makefiles and command arguments. It was invented so you can alter
4268 and add to values that the user specifies with command arguments.
4270 For example, suppose you always want the @samp{-g} switch when you run the
4271 C compiler, but you would like to allow the user to specify the other
4272 switches with a command argument just as usual. You could use this
4273 @code{override} directive:
4276 override CFLAGS += -g
4279 You can also use @code{override} directives with @code{define} directives.
4280 This is done as you might expect:
4290 See the next section for information about @code{define}.
4293 @xref{Defining, ,Defining Variables Verbatim}.
4296 @node Defining, Environment, Override Directive, Using Variables
4297 @section Defining Variables Verbatim
4300 @cindex verbatim variable definition
4301 @cindex defining variables verbatim
4302 @cindex variables, defining verbatim
4304 Another way to set the value of a variable is to use the @code{define}
4305 directive. This directive has an unusual syntax which allows newline
4306 characters to be included in the value, which is convenient for defining
4307 canned sequences of commands
4308 (@pxref{Sequences, ,Defining Canned Command Sequences}).
4310 The @code{define} directive is followed on the same line by the name of the
4311 variable and nothing more. The value to give the variable appears on the
4312 following lines. The end of the value is marked by a line containing just
4313 the word @code{endef}. Aside from this difference in syntax, @code{define}
4314 works just like @samp{=}: it creates a recursively-expanded variable
4315 (@pxref{Flavors, ,The Two Flavors of Variables}).
4316 The variable name may contain function and variable references, which
4317 are expanded when the directive is read to find the actual variable name
4327 The value in an ordinary assignment cannot contain a newline; but the
4328 newlines that separate the lines of the value in a @code{define} become
4329 part of the variable's value (except for the final newline which precedes
4330 the @code{endef} and is not considered part of the value).@refill
4333 The previous example is functionally equivalent to this:
4336 two-lines = echo foo; echo $(bar)
4340 since two commands separated by semicolon behave much like two separate
4341 shell commands. However, note that using two separate lines means
4342 @code{make} will invoke the shell twice, running an independent subshell
4343 for each line. @xref{Execution, ,Command Execution}.
4345 If you want variable definitions made with @code{define} to take
4346 precedence over command-line variable definitions, you can use the
4347 @code{override} directive together with @code{define}:
4350 override define two-lines
4357 @xref{Override Directive, ,The @code{override} Directive}.
4359 @node Environment, , Defining, Using Variables
4360 @section Variables from the Environment
4362 @cindex variables, environment
4364 Variables in @code{make} can come from the environment in which
4365 @code{make} is run. Every environment variable that @code{make} sees when
4366 it starts up is transformed into a @code{make} variable with the same name
4367 and value. But an explicit assignment in the makefile, or with a command
4368 argument, overrides the environment. (If the @samp{-e} flag is specified,
4369 then values from the environment override assignments in the makefile.
4370 @xref{Options Summary, ,Summary of Options}.
4371 But this is not recommended practice.)
4373 Thus, by setting the variable @code{CFLAGS} in your environment, you can
4374 cause all C compilations in most makefiles to use the compiler switches you
4375 prefer. This is safe for variables with standard or conventional meanings
4376 because you know that no makefile will use them for other things. (But
4377 this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
4378 and therefore are not affected by the value in the environment.)
4380 When @code{make} is invoked recursively, variables defined in the
4381 outer invocation can be passed to inner invocations through the
4382 environment (@pxref{Recursion, ,Recursive Use of @code{make}}). By
4383 default, only variables that came from the environment or the command
4384 line are passed to recursive invocations. You can use the
4385 @code{export} directive to pass other variables.
4386 @xref{Variables/Recursion, , Communicating Variables to a
4387 Sub-@code{make}}, for full details.
4389 Other use of variables from the environment is not recommended. It is not
4390 wise for makefiles to depend for their functioning on environment variables
4391 set up outside their control, since this would cause different users to get
4392 different results from the same makefile. This is against the whole
4393 purpose of most makefiles.
4395 Such problems would be especially likely with the variable @code{SHELL},
4396 which is normally present in the environment to specify the user's choice
4397 of interactive shell. It would be very undesirable for this choice to
4398 affect @code{make}. So @code{make} ignores the environment value of
4399 @code{SHELL}.@refill
4401 @node Conditionals, Functions, Using Variables, Top
4402 @chapter Conditional Parts of Makefiles
4404 @cindex conditionals
4405 A @dfn{conditional} causes part of a makefile to be obeyed or ignored
4406 depending on the values of variables. Conditionals can compare the
4407 value of one variable to another, or the value of a variable to
4408 a constant string. Conditionals control what @code{make} actually
4409 ``sees'' in the makefile, so they @emph{cannot} be used to control shell
4410 commands at the time of execution.@refill
4413 * Conditional Example:: Example of a conditional
4414 * Conditional Syntax:: The syntax of conditionals.
4415 * Testing Flags:: Conditionals that test flags.
4418 @node Conditional Example, Conditional Syntax, , Conditionals
4419 @section Example of a Conditional
4421 The following example of a conditional tells @code{make} to use one set
4422 of libraries if the @code{CC} variable is @samp{gcc}, and a different
4423 set of libraries otherwise. It works by controlling which of two
4424 command lines will be used as the command for a rule. The result is
4425 that @samp{CC=gcc} as an argument to @code{make} changes not only which
4426 compiler is used but also which libraries are linked.
4429 libs_for_gcc = -lgnu
4434 $(CC) -o foo $(objects) $(libs_for_gcc)
4436 $(CC) -o foo $(objects) $(normal_libs)
4440 This conditional uses three directives: one @code{ifeq}, one @code{else}
4441 and one @code{endif}.
4443 The @code{ifeq} directive begins the conditional, and specifies the
4444 condition. It contains two arguments, separated by a comma and surrounded
4445 by parentheses. Variable substitution is performed on both arguments and
4446 then they are compared. The lines of the makefile following the
4447 @code{ifeq} are obeyed if the two arguments match; otherwise they are
4450 The @code{else} directive causes the following lines to be obeyed if the
4451 previous conditional failed. In the example above, this means that the
4452 second alternative linking command is used whenever the first alternative
4453 is not used. It is optional to have an @code{else} in a conditional.
4455 The @code{endif} directive ends the conditional. Every conditional must
4456 end with an @code{endif}. Unconditional makefile text follows.
4458 As this example illustrates, conditionals work at the textual level:
4459 the lines of the conditional are treated as part of the makefile, or
4460 ignored, according to the condition. This is why the larger syntactic
4461 units of the makefile, such as rules, may cross the beginning or the
4462 end of the conditional.
4464 When the variable @code{CC} has the value @samp{gcc}, the above example has
4469 $(CC) -o foo $(objects) $(libs_for_gcc)
4473 When the variable @code{CC} has any other value, the effect is this:
4477 $(CC) -o foo $(objects) $(normal_libs)
4480 Equivalent results can be obtained in another way by conditionalizing a
4481 variable assignment and then using the variable unconditionally:
4484 libs_for_gcc = -lgnu
4488 libs=$(libs_for_gcc)
4494 $(CC) -o foo $(objects) $(libs)
4497 @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
4498 @section Syntax of Conditionals
4506 The syntax of a simple conditional with no @code{else} is as follows:
4509 @var{conditional-directive}
4515 The @var{text-if-true} may be any lines of text, to be considered as part
4516 of the makefile if the condition is true. If the condition is false, no
4517 text is used instead.
4519 The syntax of a complex conditional is as follows:
4522 @var{conditional-directive}
4530 If the condition is true, @var{text-if-true} is used; otherwise,
4531 @var{text-if-false} is used instead. The @var{text-if-false} can be any
4532 number of lines of text.
4534 The syntax of the @var{conditional-directive} is the same whether the
4535 conditional is simple or complex. There are four different directives that
4536 test different conditions. Here is a table of them:
4539 @item ifeq (@var{arg1}, @var{arg2})
4540 @itemx ifeq '@var{arg1}' '@var{arg2}'
4541 @itemx ifeq "@var{arg1}" "@var{arg2}"
4542 @itemx ifeq "@var{arg1}" '@var{arg2}'
4543 @itemx ifeq '@var{arg1}' "@var{arg2}"
4544 Expand all variable references in @var{arg1} and @var{arg2} and
4545 compare them. If they are identical, the @var{text-if-true} is
4546 effective; otherwise, the @var{text-if-false}, if any, is effective.
4548 Often you want to test if a variable has a non-empty value. When the
4549 value results from complex expansions of variables and functions,
4550 expansions you would consider empty may actually contain whitespace
4551 characters and thus are not seen as empty. However, you can use the
4552 @code{strip} function (@pxref{Text Functions}) to avoid interpreting
4553 whitespace as a non-empty value. For example:
4557 ifeq ($(strip $(foo)),)
4564 will evaluate @var{text-if-empty} even if the expansion of
4565 @code{$(foo)} contains whitespace characters.
4567 @item ifneq (@var{arg1}, @var{arg2})
4568 @itemx ifneq '@var{arg1}' '@var{arg2}'
4569 @itemx ifneq "@var{arg1}" "@var{arg2}"
4570 @itemx ifneq "@var{arg1}" '@var{arg2}'
4571 @itemx ifneq '@var{arg1}' "@var{arg2}"
4572 Expand all variable references in @var{arg1} and @var{arg2} and
4573 compare them. If they are different, the @var{text-if-true} is
4574 effective; otherwise, the @var{text-if-false}, if any, is effective.
4576 @item ifdef @var{variable-name}
4577 If the variable @var{variable-name} has a non-empty value, the
4578 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4579 if any, is effective. Variables that have never been defined have an
4582 Note that @code{ifdef} only tests whether a variable has a value. It
4583 does not expand the variable to see if that value is nonempty.
4584 Consequently, tests using @code{ifdef} return true for all definitions
4585 except those like @code{foo =}. To test for an empty value, use
4586 @w{@code{ifeq ($(foo),)}}. For example,
4599 sets @samp{frobozz} to @samp{yes}, while:
4611 sets @samp{frobozz} to @samp{no}.
4613 @item ifndef @var{variable-name}
4614 If the variable @var{variable-name} has an empty value, the
4615 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
4616 if any, is effective.
4619 Extra spaces are allowed and ignored at the beginning of the conditional
4620 directive line, but a tab is not allowed. (If the line begins with a tab,
4621 it will be considered a command for a rule.) Aside from this, extra spaces
4622 or tabs may be inserted with no effect anywhere except within the directive
4623 name or within an argument. A comment starting with @samp{#} may appear at
4624 the end of the line.
4626 The other two directives that play a part in a conditional are @code{else}
4627 and @code{endif}. Each of these directives is written as one word, with no
4628 arguments. Extra spaces are allowed and ignored at the beginning of the
4629 line, and spaces or tabs at the end. A comment starting with @samp{#} may
4630 appear at the end of the line.
4632 Conditionals affect which lines of the makefile @code{make} uses. If
4633 the condition is true, @code{make} reads the lines of the
4634 @var{text-if-true} as part of the makefile; if the condition is false,
4635 @code{make} ignores those lines completely. It follows that syntactic
4636 units of the makefile, such as rules, may safely be split across the
4637 beginning or the end of the conditional.@refill
4639 @code{make} evaluates conditionals when it reads a makefile.
4640 Consequently, you cannot use automatic variables in the tests of
4641 conditionals because they are not defined until commands are run
4642 (@pxref{Automatic, , Automatic Variables}).
4644 To prevent intolerable confusion, it is not permitted to start a
4645 conditional in one makefile and end it in another. However, you may
4646 write an @code{include} directive within a conditional, provided you do
4647 not attempt to terminate the conditional inside the included file.
4649 @node Testing Flags, , Conditional Syntax, Conditionals
4650 @section Conditionals that Test Flags
4652 You can write a conditional that tests @code{make} command flags such as
4653 @samp{-t} by using the variable @code{MAKEFLAGS} together with the
4654 @code{findstring} function
4655 (@pxref{Text Functions, , Functions for String Substitution and Analysis}).
4656 This is useful when @code{touch} is not enough to make a file appear up
4659 The @code{findstring} function determines whether one string appears as a
4660 substring of another. If you want to test for the @samp{-t} flag,
4661 use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
4664 For example, here is how to arrange to use @samp{ranlib -t} to finish
4665 marking an archive file up to date:
4669 ifneq (,$(findstring t,$(MAKEFLAGS)))
4671 +ranlib -t archive.a
4678 The @samp{+} prefix marks those command lines as ``recursive'' so
4679 that they will be executed despite use of the @samp{-t} flag.
4680 @xref{Recursion, ,Recursive Use of @code{make}}.
4682 @node Functions, Running, Conditionals, Top
4683 @chapter Functions for Transforming Text
4686 @dfn{Functions} allow you to do text processing in the makefile to compute
4687 the files to operate on or the commands to use. You use a function in a
4688 @dfn{function call}, where you give the name of the function and some text
4689 (the @dfn{arguments}) for the function to operate on. The result of the
4690 function's processing is substituted into the makefile at the point of the
4691 call, just as a variable might be substituted.
4694 * Syntax of Functions:: How to write a function call.
4695 * Text Functions:: General-purpose text manipulation functions.
4696 * Filename Functions:: Functions for manipulating file names.
4697 * Foreach Function:: Repeat some text with controlled variation.
4698 * Origin Function:: Find where a variable got its value.
4699 * Shell Function:: Substitute the output of a shell command.
4702 @node Syntax of Functions, Text Functions, , Functions
4703 @section Function Call Syntax
4704 @cindex @code{$}, in function call
4705 @cindex dollar sign (@code{$}), in function call
4706 @cindex arguments of functions
4707 @cindex functions, syntax of
4709 A function call resembles a variable reference. It looks like this:
4712 $(@var{function} @var{arguments})
4719 $@{@var{function} @var{arguments}@}
4722 Here @var{function} is a function name; one of a short list of names that
4723 are part of @code{make}. There is no provision for defining new functions.
4725 The @var{arguments} are the arguments of the function. They are
4726 separated from the function name by one or more spaces or tabs, and if
4727 there is more than one argument, then they are separated by commas.
4728 Such whitespace and commas are not part of an argument's value. The
4729 delimiters which you use to surround the function call, whether
4730 parentheses or braces, can appear in an argument only in matching pairs;
4731 the other kind of delimiters may appear singly. If the arguments
4732 themselves contain other function calls or variable references, it is
4733 wisest to use the same kind of delimiters for all the references; write
4734 @w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This
4735 is because it is clearer, and because only one type of delimiter is
4736 matched to find the end of the reference.
4738 The text written for each argument is processed by substitution of
4739 variables and function calls to produce the argument value, which
4740 is the text on which the function acts. The substitution is done in the
4741 order in which the arguments appear.
4743 Commas and unmatched parentheses or braces cannot appear in the text of an
4744 argument as written; leading spaces cannot appear in the text of the first
4745 argument as written. These characters can be put into the argument value
4746 by variable substitution. First define variables @code{comma} and
4747 @code{space} whose values are isolated comma and space characters, then
4748 substitute these variables where such characters are wanted, like this:
4754 space:= $(empty) $(empty)
4756 bar:= $(subst $(space),$(comma),$(foo))
4757 # @r{bar is now `a,b,c'.}
4762 Here the @code{subst} function replaces each space with a comma, through
4763 the value of @code{foo}, and substitutes the result.
4765 @node Text Functions, Filename Functions, Syntax of Functions, Functions
4766 @section Functions for String Substitution and Analysis
4767 @cindex functions, for text
4769 Here are some functions that operate on strings:
4772 @item $(subst @var{from},@var{to},@var{text})
4774 Performs a textual replacement on the text @var{text}: each occurrence
4775 of @var{from} is replaced by @var{to}. The result is substituted for
4776 the function call. For example,
4779 $(subst ee,EE,feet on the street)
4782 substitutes the string @samp{fEEt on the strEEt}.
4784 @item $(patsubst @var{pattern},@var{replacement},@var{text})
4786 Finds whitespace-separated words in @var{text} that match
4787 @var{pattern} and replaces them with @var{replacement}. Here
4788 @var{pattern} may contain a @samp{%} which acts as a wildcard,
4789 matching any number of any characters within a word. If
4790 @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
4791 by the text that matched the @samp{%} in @var{pattern}.@refill
4793 @cindex @code{%}, quoting in @code{patsubst}
4794 @cindex @code{%}, quoting with @code{\} (backslash)
4795 @cindex @code{\} (backslash), to quote @code{%}
4796 @cindex backslash (@code{\}), to quote @code{%}
4797 @cindex quoting @code{%}, in @code{patsubst}
4798 @samp{%} characters in @code{patsubst} function invocations can be
4799 quoted with preceding backslashes (@samp{\}). Backslashes that would
4800 otherwise quote @samp{%} characters can be quoted with more backslashes.
4801 Backslashes that quote @samp{%} characters or other backslashes are
4802 removed from the pattern before it is compared file names or has a stem
4803 substituted into it. Backslashes that are not in danger of quoting
4804 @samp{%} characters go unmolested. For example, the pattern
4805 @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
4806 operative @samp{%} character, and @samp{pattern\\} following it. The
4807 final two backslashes are left alone because they cannot affect any
4808 @samp{%} character.@refill
4810 Whitespace between words is folded into single space characters;
4811 leading and trailing whitespace is discarded.
4816 $(patsubst %.c,%.o,x.c.c bar.c)
4820 produces the value @samp{x.c.o bar.o}.
4822 Substitution references (@pxref{Substitution Refs, ,Substitution
4823 References}) are a simpler way to get the effect of the @code{patsubst}
4827 $(@var{var}:@var{pattern}=@var{replacement})
4834 $(patsubst @var{pattern},@var{replacement},$(@var{var}))
4837 The second shorthand simplifies one of the most common uses of
4838 @code{patsubst}: replacing the suffix at the end of file names.
4841 $(@var{var}:@var{suffix}=@var{replacement})
4848 $(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
4852 For example, you might have a list of object files:
4855 objects = foo.o bar.o baz.o
4859 To get the list of corresponding source files, you could simply write:
4866 instead of using the general form:
4869 $(patsubst %.o,%.c,$(objects))
4872 @item $(strip @var{string})
4873 @cindex stripping whitespace
4874 @cindex whitespace, stripping
4875 @cindex spaces, stripping
4877 Removes leading and trailing whitespace from @var{string} and replaces
4878 each internal sequence of one or more whitespace characters with a
4879 single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}.
4881 The function @code{strip} can be very useful when used in conjunction
4882 with conditionals. When comparing something with the empty string
4883 @samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
4884 just whitespace to match the empty string (@pxref{Conditionals}).
4886 Thus, the following may fail to have the desired results:
4890 ifneq "$(needs_made)" ""
4893 all:;@@echo 'Nothing to make!'
4898 Replacing the variable reference @w{@samp{$(needs_made)}} with the
4899 function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
4900 directive would make it more robust.@refill
4902 @item $(findstring @var{find},@var{in})
4904 @cindex searching for strings
4905 @cindex finding strings
4906 @cindex strings, searching for
4907 Searches @var{in} for an occurrence of @var{find}. If it occurs, the
4908 value is @var{find}; otherwise, the value is empty. You can use this
4909 function in a conditional to test for the presence of a specific
4910 substring in a given string. Thus, the two examples,
4913 $(findstring a,a b c)
4918 produce the values @samp{a} and @samp{} (the empty string),
4919 respectively. @xref{Testing Flags}, for a practical application of
4920 @code{findstring}.@refill
4924 @cindex filtering words
4925 @cindex words, filtering
4926 @item $(filter @var{pattern}@dots{},@var{text})
4927 Removes all whitespace-separated words in @var{text} that do
4928 @emph{not} match any of the @var{pattern} words, returning only
4929 matching words. The patterns are written using @samp{%}, just like
4930 the patterns used in the @code{patsubst} function above.@refill
4932 The @code{filter} function can be used to separate out different types
4933 of strings (such as file names) in a variable. For example:
4936 sources := foo.c bar.c baz.s ugh.h
4938 cc $(filter %.c %.s,$(sources)) -o foo
4942 says that @file{foo} depends of @file{foo.c}, @file{bar.c},
4943 @file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
4944 @file{baz.s} should be specified in the command to the
4947 @item $(filter-out @var{pattern}@dots{},@var{text})
4949 @cindex filtering out words
4950 @cindex words, filtering out
4951 Removes all whitespace-separated words in @var{text} that @emph{do}
4952 match the @var{pattern} words, returning only the words that @emph{do
4953 not} match. This is the exact opposite of the @code{filter}
4960 objects=main1.o foo.o main2.o bar.o
4961 mains=main1.o main2.o
4966 the following generates a list which contains all the object files not
4970 $(filter-out $(mains),$(objects))
4975 @cindex sorting words
4976 @item $(sort @var{list})
4977 Sorts the words of @var{list} in lexical order, removing duplicate
4978 words. The output is a list of words separated by single spaces.
4982 $(sort foo bar lose)
4986 returns the value @samp{bar foo lose}.
4988 @cindex removing duplicate words
4989 @cindex duplicate words, removing
4990 @cindex words, removing duplicates
4991 Incidentally, since @code{sort} removes duplicate words, you can use
4992 it for this purpose even if you don't care about the sort order.
4995 Here is a realistic example of the use of @code{subst} and
4996 @code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable
4997 to specify a list of directories that @code{make} should search for
4999 (@pxref{General Search, , @code{VPATH} Search Path for All Dependencies}).
5000 This example shows how to
5001 tell the C compiler to search for header files in the same list of
5004 The value of @code{VPATH} is a list of directories separated by colons,
5005 such as @samp{src:../headers}. First, the @code{subst} function is used to
5006 change the colons to spaces:
5009 $(subst :, ,$(VPATH))
5013 This produces @samp{src ../headers}. Then @code{patsubst} is used to turn
5014 each directory name into a @samp{-I} flag. These can be added to the
5015 value of the variable @code{CFLAGS}, which is passed automatically to the C
5016 compiler, like this:
5019 override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
5023 The effect is to append the text @samp{-Isrc -I../headers} to the
5024 previously given value of @code{CFLAGS}. The @code{override} directive is
5025 used so that the new value is assigned even if the previous value of
5026 @code{CFLAGS} was specified with a command argument (@pxref{Override
5027 Directive, , The @code{override} Directive}).
5029 @node Filename Functions, Foreach Function, Text Functions, Functions
5030 @section Functions for File Names
5031 @cindex functions, for file names
5032 @cindex file name functions
5034 Several of the built-in expansion functions relate specifically to
5035 taking apart file names or lists of file names.
5037 Each of the following functions performs a specific transformation on a
5038 file name. The argument of the function is regarded as a series of file
5039 names, separated by whitespace. (Leading and trailing whitespace is
5040 ignored.) Each file name in the series is transformed in the same way and
5041 the results are concatenated with single spaces between them.
5044 @item $(dir @var{names}@dots{})
5046 @cindex directory part
5047 @cindex file name, directory part
5048 Extracts the directory-part of each file name in @var{names}. The
5049 directory-part of the file name is everything up through (and
5050 including) the last slash in it. If the file name contains no slash,
5051 the directory part is the string @samp{./}. For example,
5054 $(dir src/foo.c hacks)
5058 produces the result @samp{src/ ./}.
5060 @item $(notdir @var{names}@dots{})
5062 @cindex file name, nondirectory part
5063 @cindex nondirectory part
5064 Extracts all but the directory-part of each file name in @var{names}.
5065 If the file name contains no slash, it is left unchanged. Otherwise,
5066 everything through the last slash is removed from it.
5068 A file name that ends with a slash becomes an empty string. This is
5069 unfortunate, because it means that the result does not always have the
5070 same number of whitespace-separated file names as the argument had;
5071 but we do not see any other valid alternative.
5076 $(notdir src/foo.c hacks)
5080 produces the result @samp{foo.c hacks}.
5082 @item $(suffix @var{names}@dots{})
5084 @cindex suffix, function to find
5085 @cindex file name suffix
5086 Extracts the suffix of each file name in @var{names}. If the file name
5087 contains a period, the suffix is everything starting with the last
5088 period. Otherwise, the suffix is the empty string. This frequently
5089 means that the result will be empty when @var{names} is not, and if
5090 @var{names} contains multiple file names, the result may contain fewer
5096 $(suffix src/foo.c hacks)
5100 produces the result @samp{.c}.
5102 @item $(basename @var{names}@dots{})
5105 @cindex file name, basename of
5106 Extracts all but the suffix of each file name in @var{names}. If the
5107 file name contains a period, the basename is everything starting up to
5108 (and not including) the last period. Otherwise, the basename is the
5109 entire file name. For example,
5112 $(basename src/foo.c hacks)
5116 produces the result @samp{src/foo hacks}.
5118 @c plural convention with dots (be consistent)
5119 @item $(addsuffix @var{suffix},@var{names}@dots{})
5121 @cindex suffix, adding
5122 @cindex file name suffix, adding
5123 The argument @var{names} is regarded as a series of names, separated
5124 by whitespace; @var{suffix} is used as a unit. The value of
5125 @var{suffix} is appended to the end of each individual name and the
5126 resulting larger names are concatenated with single spaces between
5130 $(addsuffix .c,foo bar)
5134 produces the result @samp{foo.c bar.c}.
5136 @item $(addprefix @var{prefix},@var{names}@dots{})
5138 @cindex prefix, adding
5139 @cindex file name prefix, adding
5140 The argument @var{names} is regarded as a series of names, separated
5141 by whitespace; @var{prefix} is used as a unit. The value of
5142 @var{prefix} is prepended to the front of each individual name and the
5143 resulting larger names are concatenated with single spaces between
5147 $(addprefix src/,foo bar)
5151 produces the result @samp{src/foo src/bar}.
5153 @item $(join @var{list1},@var{list2})
5155 @cindex joining lists of words
5156 @cindex words, joining lists
5157 Concatenates the two arguments word by word: the two first words (one
5158 from each argument) concatenated form the first word of the result, the
5159 two second words form the second word of the result, and so on. So the
5160 @var{n}th word of the result comes from the @var{n}th word of each
5161 argument. If one argument has more words that the other, the extra
5162 words are copied unchanged into the result.
5164 For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
5166 Whitespace between the words in the lists is not preserved; it is
5167 replaced with a single space.
5169 This function can merge the results of the @code{dir} and
5170 @code{notdir} functions, to produce the original list of files which
5171 was given to those two functions.@refill
5173 @item $(word @var{n},@var{text})
5175 @cindex words, selecting
5176 @cindex selecting words
5177 Returns the @var{n}th word of @var{text}. The legitimate values of
5178 @var{n} start from 1. If @var{n} is bigger than the number of words
5179 in @var{text}, the value is empty. For example,
5182 $(word 2, foo bar baz)
5188 @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
5189 @item $(words @var{text})
5191 @cindex words, finding number
5192 Returns the number of words in @var{text}.
5193 Thus, the last word of @var{text} is
5194 @w{@code{$(word $(words @var{text}),@var{text})}}.@refill
5196 @item $(firstword @var{names}@dots{})
5198 @cindex words, extracting first
5199 The argument @var{names} is regarded as a series of names, separated
5200 by whitespace. The value is the first name in the series. The rest
5201 of the names are ignored.
5206 $(firstword foo bar)
5210 produces the result @samp{foo}. Although @code{$(firstword
5211 @var{text})} is the same as @code{$(word 1,@var{text})}, the
5212 @code{firstword} function is retained for its simplicity.@refill
5214 @item $(wildcard @var{pattern})
5216 @cindex wildcard, function
5217 The argument @var{pattern} is a file name pattern, typically containing
5218 wildcard characters (as in shell file name patterns). The result of
5219 @code{wildcard} is a space-separated list of the names of existing files
5220 that match the pattern.
5221 @xref{Wildcards, ,Using Wildcard Characters in File Names}.
5224 @node Foreach Function, Origin Function, Filename Functions, Functions
5225 @section The @code{foreach} Function
5227 @cindex words, iterating over
5229 The @code{foreach} function is very different from other functions. It
5230 causes one piece of text to be used repeatedly, each time with a different
5231 substitution performed on it. It resembles the @code{for} command in the
5232 shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
5234 The syntax of the @code{foreach} function is:
5237 $(foreach @var{var},@var{list},@var{text})
5241 The first two arguments, @var{var} and @var{list}, are expanded before
5242 anything else is done; note that the last argument, @var{text}, is
5243 @strong{not} expanded at the same time. Then for each word of the expanded
5244 value of @var{list}, the variable named by the expanded value of @var{var}
5245 is set to that word, and @var{text} is expanded. Presumably @var{text}
5246 contains references to that variable, so its expansion will be different
5249 The result is that @var{text} is expanded as many times as there are
5250 whitespace-separated words in @var{list}. The multiple expansions of
5251 @var{text} are concatenated, with spaces between them, to make the result
5254 This simple example sets the variable @samp{files} to the list of all files
5255 in the directories in the list @samp{dirs}:
5259 files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
5262 Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition
5263 finds the value @samp{a} for @code{dir}, so it produces the same result
5264 as @samp{$(wildcard a/*)}; the second repetition produces the result
5265 of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
5267 This example has the same result (except for setting @samp{dirs}) as
5268 the following example:
5271 files := $(wildcard a/* b/* c/* d/*)
5274 When @var{text} is complicated, you can improve readability by giving it
5275 a name, with an additional variable:
5278 find_files = $(wildcard $(dir)/*)
5280 files := $(foreach dir,$(dirs),$(find_files))
5284 Here we use the variable @code{find_files} this way. We use plain @samp{=}
5285 to define a recursively-expanding variable, so that its value contains an
5286 actual function call to be reexpanded under the control of @code{foreach};
5287 a simply-expanded variable would not do, since @code{wildcard} would be
5288 called only once at the time of defining @code{find_files}.
5290 The @code{foreach} function has no permanent effect on the variable
5291 @var{var}; its value and flavor after the @code{foreach} function call are
5292 the same as they were beforehand. The other values which are taken from
5293 @var{list} are in effect only temporarily, during the execution of
5294 @code{foreach}. The variable @var{var} is a simply-expanded variable
5295 during the execution of @code{foreach}. If @var{var} was undefined
5296 before the @code{foreach} function call, it is undefined after the call.
5297 @xref{Flavors, ,The Two Flavors of Variables}.@refill
5299 You must take care when using complex variable expressions that result in
5300 variable names because many strange things are valid variable names, but
5301 are probably not what you intended. For example,
5304 files := $(foreach Es escrito en espanol!,b c ch,$(find_files))
5308 might be useful if the value of @code{find_files} references the variable
5309 whose name is @samp{Es escrito en espanol!} (es un nombre bastante largo,
5310 no?), but it is more likely to be a mistake.
5312 @node Origin Function, Shell Function, Foreach Function, Functions
5313 @section The @code{origin} Function
5315 @cindex variables, origin of
5316 @cindex origin of variable
5318 The @code{origin} function is unlike most other functions in that it does
5319 not operate on the values of variables; it tells you something @emph{about}
5320 a variable. Specifically, it tells you where it came from.
5322 The syntax of the @code{origin} function is:
5325 $(origin @var{variable})
5328 Note that @var{variable} is the @emph{name} of a variable to inquire about;
5329 not a @emph{reference} to that variable. Therefore you would not normally
5330 use a @samp{$} or parentheses when writing it. (You can, however, use a
5331 variable reference in the name if you want the name not to be a constant.)
5333 The result of this function is a string telling you how the variable
5334 @var{variable} was defined:
5339 if @var{variable} was never defined.
5343 if @var{variable} has a default definition, as is usual with @code{CC}
5344 and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
5345 Note that if you have redefined a default variable, the @code{origin}
5346 function will return the origin of the later definition.
5350 if @var{variable} was defined as an environment variable and the
5351 @samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}).
5353 @item environment override
5355 if @var{variable} was defined as an environment variable and the
5356 @w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary,
5357 ,Summary of Options}).@refill
5361 if @var{variable} was defined in a makefile.
5365 if @var{variable} was defined on the command line.
5369 if @var{variable} was defined with an @code{override} directive in a
5370 makefile (@pxref{Override Directive, ,The @code{override} Directive}).
5374 if @var{variable} is an automatic variable defined for the
5375 execution of the commands for each rule
5376 (@pxref{Automatic, , Automatic Variables}).
5379 This information is primarily useful (other than for your curiosity) to
5380 determine if you want to believe the value of a variable. For example,
5381 suppose you have a makefile @file{foo} that includes another makefile
5382 @file{bar}. You want a variable @code{bletch} to be defined in @file{bar}
5383 if you run the command @w{@samp{make -f bar}}, even if the environment contains
5384 a definition of @code{bletch}. However, if @file{foo} defined
5385 @code{bletch} before including @file{bar}, you do not want to override that
5386 definition. This could be done by using an @code{override} directive in
5387 @file{foo}, giving that definition precedence over the later definition in
5388 @file{bar}; unfortunately, the @code{override} directive would also
5389 override any command line definitions. So, @file{bar} could
5395 ifeq "$(origin bletch)" "environment"
5396 bletch = barf, gag, etc.
5403 If @code{bletch} has been defined from the environment, this will redefine
5406 If you want to override a previous definition of @code{bletch} if it came
5407 from the environment, even under @samp{-e}, you could instead write:
5411 ifneq "$(findstring environment,$(origin bletch))" ""
5412 bletch = barf, gag, etc.
5417 Here the redefinition takes place if @samp{$(origin bletch)} returns either
5418 @samp{environment} or @samp{environment override}.
5419 @xref{Text Functions, , Functions for String Substitution and Analysis}.
5421 @node Shell Function, , Origin Function, Functions
5422 @section The @code{shell} Function
5424 @cindex commands, expansion
5426 @cindex shell command, function for
5428 The @code{shell} function is unlike any other function except the
5429 @code{wildcard} function
5430 (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
5431 communicates with the world outside of @code{make}.
5433 The @code{shell} function performs the same function that backquotes
5434 (@samp{`}) perform in most shells: it does @dfn{command expansion}. This
5435 means that it takes an argument that is a shell command and returns the
5436 output of the command. The only processing @code{make} does on the result,
5437 before substituting it into the surrounding text, is to convert newlines to
5440 The commands run by calls to the @code{shell} function are run when the
5441 function calls are expanded. In most cases, this is when the makefile is
5442 read in. The exception is that function calls in the commands of the rules
5443 are expanded when the commands are run, and this applies to @code{shell}
5444 function calls like all others.
5446 Here are some examples of the use of the @code{shell} function:
5449 contents := $(shell cat foo)
5453 sets @code{contents} to the contents of the file @file{foo}, with a space
5454 (rather than a newline) separating each line.
5457 files := $(shell echo *.c)
5461 sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is
5462 using a very strange shell, this has the same result as
5463 @w{@samp{$(wildcard *.c)}}.@refill
5465 @node Running, Implicit Rules, Functions, Top
5466 @chapter How to Run @code{make}
5468 A makefile that says how to recompile a program can be used in more
5469 than one way. The simplest use is to recompile every file that is out
5470 of date. Usually, makefiles are written so that if you run
5471 @code{make} with no arguments, it does just that.
5473 But you might want to update only some of the files; you might want to use
5474 a different compiler or different compiler options; you might want just to
5475 find out which files are out of date without changing them.
5477 By giving arguments when you run @code{make}, you can do any of these
5478 things and many others.
5481 * Makefile Arguments:: How to specify which makefile to use.
5482 * Goals:: How to use goal arguments to specify which
5483 parts of the makefile to use.
5484 * Instead of Execution:: How to use mode flags to specify what
5485 kind of thing to do with the commands
5486 in the makefile other than simply
5488 * Avoiding Compilation:: How to avoid recompiling certain files.
5489 * Overriding:: How to override a variable to specify
5490 an alternate compiler and other things.
5491 * Testing:: How to proceed past some errors, to
5493 * Options Summary:: Summary of Options
5496 @node Makefile Arguments, Goals, , Running
5497 @section Arguments to Specify the Makefile
5498 @cindex @code{--file}
5499 @cindex @code{--makefile}
5502 The way to specify the name of the makefile is with the @samp{-f} or
5503 @samp{--file} option (@samp{--makefile} also works). For example,
5504 @samp{-f altmake} says to use the file @file{altmake} as the makefile.
5506 If you use the @samp{-f} flag several times and follow each @samp{-f}
5507 with an argument, all the specified files are used jointly as
5510 If you do not use the @samp{-f} or @samp{--file} flag, the default is
5511 to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
5512 that order, and use the first of these three which exists or can be made
5513 (@pxref{Makefiles, ,Writing Makefiles}).@refill
5515 @node Goals, Instead of Execution, Makefile Arguments, Running
5516 @section Arguments to Specify the Goals
5517 @cindex goal, how to specify
5519 The @dfn{goals} are the targets that @code{make} should strive ultimately
5520 to update. Other targets are updated as well if they appear as
5521 dependencies of goals, or dependencies of dependencies of goals, etc.
5523 By default, the goal is the first target in the makefile (not counting
5524 targets that start with a period). Therefore, makefiles are usually
5525 written so that the first target is for compiling the entire program or
5526 programs they describe.
5528 You can specify a different goal or goals with arguments to @code{make}.
5529 Use the name of the goal as an argument. If you specify several goals,
5530 @code{make} processes each of them in turn, in the order you name them.
5532 Any target in the makefile may be specified as a goal (unless it
5533 starts with @samp{-} or contains an @samp{=}, in which case it will be
5534 parsed as a switch or variable definition, respectively). Even
5535 targets not in the makefile may be specified, if @code{make} can find
5536 implicit rules that say how to make them.
5538 One use of specifying a goal is if you want to compile only a part of
5539 the program, or only one of several programs. Specify as a goal each
5540 file that you wish to remake. For example, consider a directory containing
5541 several programs, with a makefile that starts like this:
5545 all: size nm ld ar as
5548 If you are working on the program @code{size}, you might want to say
5549 @w{@samp{make size}} so that only the files of that program are recompiled.
5551 Another use of specifying a goal is to make files that are not normally
5552 made. For example, there may be a file of debugging output, or a
5553 version of the program that is compiled specially for testing, which has
5554 a rule in the makefile but is not a dependency of the default goal.
5556 Another use of specifying a goal is to run the commands associated with
5557 a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
5558 Targets, ,Empty Target Files to Record Events}). Many makefiles contain
5559 a phony target named @file{clean} which deletes everything except source
5560 files. Naturally, this is done only if you request it explicitly with
5561 @w{@samp{make clean}}. Here is a list of typical phony and empty target
5566 @cindex @code{all} @r{(standard target)}
5567 Make all the top-level targets the makefile knows about.
5570 @cindex @code{clean} @r{(standard target)}
5571 Delete all files that are normally created by running @code{make}.
5574 @cindex @code{mostlyclean} @r{(standard target)}
5575 Like @samp{clean}, but may refrain from deleting a few files that people
5576 normally don't want to recompile. For example, the @samp{mostlyclean}
5577 target for GCC does not delete @file{libgcc.a}, because recompiling it
5578 is rarely necessary and takes a lot of time.
5581 @cindex @code{distclean} @r{(standard target)}
5583 @cindex @code{realclean} @r{(standard target)}
5585 @cindex @code{clobber} @r{(standard target)}
5586 Any of these three might be defined to delete everything that would
5587 not be part of a standard distribution. For example, this would
5588 delete configuration files or links that you would normally create as
5589 preparation for compilation, even if the makefile itself cannot create
5593 @cindex @code{install} @r{(standard target)}
5594 Copy the executable file into a directory that users typically search
5595 for commands; copy any auxiliary files that the executable uses into
5596 the directories where it will look for them.
5599 @cindex @code{print} @r{(standard target)}
5600 Print listings of the source files that have changed.
5603 @cindex @code{tar} @r{(standard target)}
5604 Create a tar file of the source files.
5607 @cindex @code{shar} @r{(standard target)}
5608 Create a shell archive (shar file) of the source files.
5611 @cindex @code{dist} @r{(standard target)}
5612 Create a distribution file of the source files. This might
5613 be a tar file, or a shar file, or a compressed version of one of the
5614 above, or even more than one of the above.
5617 @cindex @code{TAGS} @r{(standard target)}
5618 Update a tags table for this program.
5621 @cindex @code{check} @r{(standard target)}
5623 @cindex @code{test} @r{(standard target)}
5624 Perform self tests on the program this makefile builds.
5627 @node Instead of Execution, Avoiding Compilation, Goals, Running
5628 @section Instead of Executing the Commands
5629 @cindex execution, instead of
5630 @cindex commands, instead of executing
5632 The makefile tells @code{make} how to tell whether a target is up to date,
5633 and how to update each target. But updating the targets is not always
5634 what you want. Certain options specify other activities for @code{make}.
5636 @comment Extra blank lines make it print better.
5642 @cindex @code{--just-print}
5643 @cindex @code{--dry-run}
5644 @cindex @code{--recon}
5647 ``No-op''. The activity is to print what commands would be used to make
5648 the targets up to date, but not actually execute them.
5652 @cindex @code{--touch}
5653 @cindex touching files
5654 @cindex target, touching
5657 ``Touch''. The activity is to mark the targets as up to date without
5658 actually changing them. In other words, @code{make} pretends to compile
5659 the targets but does not really change their contents.
5663 @cindex @code{--question}
5665 @cindex question mode
5667 ``Question''. The activity is to find out silently whether the targets
5668 are up to date already; but execute no commands in either case. In other
5669 words, neither compilation nor output will occur.
5672 @itemx --what-if=@var{file}
5673 @itemx --assume-new=@var{file}
5674 @itemx --new-file=@var{file}
5675 @cindex @code{--what-if}
5677 @cindex @code{--assume-new}
5678 @cindex @code{--new-file}
5680 @cindex files, assuming new
5682 ``What if''. Each @samp{-W} flag is followed by a file name. The given
5683 files' modification times are recorded by @code{make} as being the present
5684 time, although the actual modification times remain the same.
5685 You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
5686 to see what would happen if you were to modify specific files.@refill
5689 With the @samp{-n} flag, @code{make} prints the commands that it would
5690 normally execute but does not execute them.
5692 With the @samp{-t} flag, @code{make} ignores the commands in the rules
5693 and uses (in effect) the command @code{touch} for each target that needs to
5694 be remade. The @code{touch} command is also printed, unless @samp{-s} or
5695 @code{.SILENT} is used. For speed, @code{make} does not actually invoke
5696 the program @code{touch}. It does the work directly.
5698 With the @samp{-q} flag, @code{make} prints nothing and executes no
5699 commands, but the exit status code it returns is zero if and only if the
5700 targets to be considered are already up to date.
5702 It is an error to use more than one of these three flags in the same
5703 invocation of @code{make}.
5705 The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command
5706 lines that begin with @samp{+} characters or contain the strings
5707 @samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing
5708 the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
5709 is run regardless of these options. Other lines in the same rule are
5710 not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
5711 @samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
5713 The @samp{-W} flag provides two features:
5717 If you also use the @samp{-n} or @samp{-q} flag, you can see what
5718 @code{make} would do if you were to modify some files.
5721 Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
5722 executing commands, the @samp{-W} flag can direct @code{make} to act
5723 as if some files had been modified, without actually modifying the
5727 Note that the options @samp{-p} and @samp{-v} allow you to obtain other
5728 information about @code{make} or about the makefiles in use
5729 (@pxref{Options Summary, ,Summary of Options}).@refill
5731 @node Avoiding Compilation, Overriding, Instead of Execution, Running
5732 @section Avoiding Recompilation of Some Files
5734 @cindex @code{--old-file}
5735 @cindex @code{--assume-old}
5736 @cindex files, assuming old
5737 @cindex files, avoiding recompilation of
5738 @cindex recompilation, avoiding
5740 Sometimes you may have changed a source file but you do not want to
5741 recompile all the files that depend on it. For example, suppose you add a
5742 macro or a declaration to a header file that many other files depend on.
5743 Being conservative, @code{make} assumes that any change in the header file
5744 requires recompilation of all dependent files, but you know that they do not
5745 need to be recompiled and you would rather not waste the time waiting for
5748 If you anticipate the problem before changing the header file, you can
5749 use the @samp{-t} flag. This flag tells @code{make} not to run the
5750 commands in the rules, but rather to mark the target up to date by
5751 changing its last-modification date. You would follow this procedure:
5755 Use the command @samp{make} to recompile the source files that really
5759 Make the changes in the header files.
5762 Use the command @samp{make -t} to mark all the object files as
5763 up to date. The next time you run @code{make}, the changes in the
5764 header files will not cause any recompilation.
5767 If you have already changed the header file at a time when some files
5768 do need recompilation, it is too late to do this. Instead, you can
5769 use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
5770 ``old'' (@pxref{Options Summary, ,Summary of Options}). This means
5771 that the file itself will not be remade, and nothing else will be
5772 remade on its account. Follow this procedure:
5776 Recompile the source files that need compilation for reasons independent
5777 of the particular header file, with @samp{make -o @var{headerfile}}.
5778 If several header files are involved, use a separate @samp{-o} option
5779 for each header file.
5782 Touch all the object files with @samp{make -t}.
5785 @node Overriding, Testing, Avoiding Compilation, Running
5786 @section Overriding Variables
5787 @cindex overriding variables with arguments
5788 @cindex variables, overriding with arguments
5789 @cindex command line variables
5790 @cindex variables, command line
5792 An argument that contains @samp{=} specifies the value of a variable:
5793 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
5794 If you specify a value in this way, all ordinary assignments of the same
5795 variable in the makefile are ignored; we say they have been
5796 @dfn{overridden} by the command line argument.
5798 The most common way to use this facility is to pass extra flags to
5799 compilers. For example, in a properly written makefile, the variable
5800 @code{CFLAGS} is included in each command that runs the C compiler, so a
5801 file @file{foo.c} would be compiled something like this:
5804 cc -c $(CFLAGS) foo.c
5807 Thus, whatever value you set for @code{CFLAGS} affects each compilation
5808 that occurs. The makefile probably specifies the usual value for
5809 @code{CFLAGS}, like this:
5815 Each time you run @code{make}, you can override this value if you
5816 wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C
5817 compilation will be done with @samp{cc -c -g -O}. (This illustrates
5818 how you can use quoting in the shell to enclose spaces and other
5819 special characters in the value of a variable when you override it.)
5821 The variable @code{CFLAGS} is only one of many standard variables that
5822 exist just so that you can change them this way. @xref{Implicit
5823 Variables, , Variables Used by Implicit Rules}, for a complete list.
5825 You can also program the makefile to look at additional variables of your
5826 own, giving the user the ability to control other aspects of how the
5827 makefile works by changing the variables.
5829 When you override a variable with a command argument, you can define either
5830 a recursively-expanded variable or a simply-expanded variable. The
5831 examples shown above make a recursively-expanded variable; to make a
5832 simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless
5833 you want to include a variable reference or function call in the
5834 @emph{value} that you specify, it makes no difference which kind of
5835 variable you create.
5837 There is one way that the makefile can change a variable that you have
5838 overridden. This is to use the @code{override} directive, which is a line
5839 that looks like this: @samp{override @var{variable} = @var{value}}
5840 (@pxref{Override Directive, ,The @code{override} Directive}).
5842 @node Testing, Options Summary, Overriding, Running
5843 @section Testing the Compilation of a Program
5844 @cindex testing compilation
5845 @cindex compilation, testing
5847 Normally, when an error happens in executing a shell command, @code{make}
5848 gives up immediately, returning a nonzero status. No further commands are
5849 executed for any target. The error implies that the goal cannot be
5850 correctly remade, and @code{make} reports this as soon as it knows.
5852 When you are compiling a program that you have just changed, this is not
5853 what you want. Instead, you would rather that @code{make} try compiling
5854 every file that can be tried, to show you as many compilation errors
5858 @cindex @code{--keep-going}
5859 On these occasions, you should use the @samp{-k} or
5860 @samp{--keep-going} flag. This tells @code{make} to continue to
5861 consider the other dependencies of the pending targets, remaking them
5862 if necessary, before it gives up and returns nonzero status. For
5863 example, after an error in compiling one object file, @samp{make -k}
5864 will continue compiling other object files even though it already
5865 knows that linking them will be impossible. In addition to continuing
5866 after failed shell commands, @samp{make -k} will continue as much as
5867 possible after discovering that it does not know how to make a target
5868 or dependency file. This will always cause an error message, but
5869 without @samp{-k}, it is a fatal error (@pxref{Options Summary,
5870 ,Summary of Options}).@refill
5872 The usual behavior of @code{make} assumes that your purpose is to get the
5873 goals up to date; once @code{make} learns that this is impossible, it might
5874 as well report the failure immediately. The @samp{-k} flag says that the
5875 real purpose is to test as much as possible of the changes made in the
5876 program, perhaps to find several independent problems so that you can
5877 correct them all before the next attempt to compile. This is why Emacs'
5878 @kbd{M-x compile} command passes the @samp{-k} flag by default.
5880 @node Options Summary, , Testing, Running
5881 @section Summary of Options
5886 Here is a table of all the options @code{make} understands:
5893 These options are ignored for compatibility with other versions of @code{make}.
5897 @itemx --directory=@var{dir}
5898 @cindex @code{--directory}
5899 Change to directory @var{dir} before reading the makefiles. If multiple
5900 @samp{-C} options are specified, each is interpreted relative to the
5901 previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
5902 This is typically used with recursive invocations of @code{make}
5903 (@pxref{Recursion, ,Recursive Use of @code{make}}).
5908 @cindex @code{--debug}
5909 @c Extra blank line here makes the table look better.
5911 Print debugging information in addition to normal processing. The
5912 debugging information says which files are being considered for
5913 remaking, which file-times are being compared and with what results,
5914 which files actually need to be remade, which implicit rules are
5915 considered and which are applied---everything interesting about how
5916 @code{make} decides what to do.
5920 @itemx --environment-overrides
5921 @cindex @code{--environment-overrides}
5922 Give variables taken from the environment precedence
5923 over variables from makefiles.
5924 @xref{Environment, ,Variables from the Environment}.
5928 @itemx --file=@var{file}
5929 @cindex @code{--file}
5930 @itemx --makefile=@var{file}
5931 @cindex @code{--makefile}
5932 Read the file named @var{file} as a makefile.
5933 @xref{Makefiles, ,Writing Makefiles}.
5938 @cindex @code{--help}
5939 @c Extra blank line here makes the table look better.
5941 Remind you of the options that @code{make} understands and then exit.
5945 @itemx --ignore-errors
5946 @cindex @code{--ignore-errors}
5947 Ignore all errors in commands executed to remake files.
5948 @xref{Errors, ,Errors in Commands}.
5952 @itemx --include-dir=@var{dir}
5953 @cindex @code{--include-dir}
5954 Specifies a directory @var{dir} to search for included makefiles.
5955 @xref{Include, ,Including Other Makefiles}. If several @samp{-I}
5956 options are used to specify several directories, the directories are
5957 searched in the order specified.
5959 @item -j [@var{jobs}]
5961 @itemx --jobs=[@var{jobs}]
5962 @cindex @code{--jobs}
5963 Specifies the number of jobs (commands) to run simultaneously. With no
5964 argument, @code{make} runs as many jobs simultaneously as possible. If
5965 there is more than one @samp{-j} option, the last one is effective.
5966 @xref{Parallel, ,Parallel Execution},
5967 for more information on how commands are run.
5972 @cindex @code{--keep-going}
5973 Continue as much as possible after an error. While the target that
5974 failed, and those that depend on it, cannot be remade, the other
5975 dependencies of these targets can be processed all the same.
5976 @xref{Testing, ,Testing the Compilation of a Program}.
5978 @item -l [@var{load}]
5980 @itemx --load-average[=@var{load}]
5981 @cindex @code{--load-average}
5982 @itemx --max-load[=@var{load}]
5983 @cindex @code{--max-load}
5984 Specifies that no new jobs (commands) should be started if there are
5985 other jobs running and the load average is at least @var{load} (a
5986 floating-point number). With no argument, removes a previous load
5987 limit. @xref{Parallel, ,Parallel Execution}.
5992 @cindex @code{--just-print}
5994 @cindex @code{--dry-run}
5996 @cindex @code{--recon}
5997 @c Extra blank line here makes the table look better.
5999 Print the commands that would be executed, but do not execute them.
6000 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6004 @itemx --old-file=@var{file}
6005 @cindex @code{--old-file}
6006 @itemx --assume-old=@var{file}
6007 @cindex @code{--assume-old}
6008 Do not remake the file @var{file} even if it is older than its
6009 dependencies, and do not remake anything on account of changes in
6010 @var{file}. Essentially the file is treated as very old and its rules
6011 are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of
6016 @itemx --print-data-base
6017 @cindex @code{--print-data-base}
6018 Print the data base (rules and variable values) that results from
6019 reading the makefiles; then execute as usual or as otherwise
6020 specified. This also prints the version information given by
6021 the @samp{-v} switch (see below). To print the data base without
6022 trying to remake any files, use @w{@samp{make -p -f /dev/null}}.
6027 @cindex @code{--question}
6028 ``Question mode''. Do not run any commands, or print anything; just
6029 return an exit status that is zero if the specified targets are already
6030 up to date, nonzero otherwise. @xref{Instead of Execution, ,Instead of
6031 Executing the Commands}.@refill
6035 @itemx --no-builtin-rules
6036 @cindex @code{--no-builtin-rules}
6037 Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
6038 ,Using Implicit Rules}). You can still define your own by writing
6039 pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
6040 Rules}). The @samp{-r} option also clears out the default list of
6041 suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
6042 Rules}). But you can still define your own suffixes with a rule for
6043 @code{.SUFFIXES}, and then define your own suffix rules.
6048 @cindex @code{--silent}
6050 @cindex @code{--quiet}
6051 @c Extra blank line here makes the table look better.
6053 Silent operation; do not print the commands as they are executed.
6054 @xref{Echoing, ,Command Echoing}.
6058 @itemx --no-keep-going
6059 @cindex @code{--no-keep-going}
6061 @cindex @code{--stop}
6062 @c Extra blank line here makes the table look better.
6064 Cancel the effect of the @samp{-k} option. This is never necessary
6065 except in a recursive @code{make} where @samp{-k} might be inherited
6066 from the top-level @code{make} via @code{MAKEFLAGS} (@pxref{Recursion, ,Recursive Use of @code{make}})
6067 or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
6072 @cindex @code{--touch}
6073 @c Extra blank line here makes the table look better.
6075 Touch files (mark them up to date without really changing them)
6076 instead of running their commands. This is used to pretend that the
6077 commands were done, in order to fool future invocations of
6078 @code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}.
6083 @cindex @code{--version}
6084 Print the version of the @code{make} program plus a copyright, a list
6085 of authors, and a notice that there is no warranty; then exit.
6089 @itemx --print-directory
6090 @cindex @code{--print-directory}
6091 Print a message containing the working directory both before and after
6092 executing the makefile. This may be useful for tracking down errors
6093 from complicated nests of recursive @code{make} commands.
6094 @xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you
6095 rarely need to specify this option since @samp{make} does it for you;
6096 see @ref{-w Option, ,The @samp{--print-directory} Option}.)
6098 @itemx --no-print-directory
6099 @cindex @code{--no-print-directory}
6100 Disable printing of the working directory under @code{-w}.
6101 This option is useful when @code{-w} is turned on automatically,
6102 but you do not want to see the extra messages.
6103 @xref{-w Option, ,The @samp{--print-directory} Option}.
6107 @itemx --what-if=@var{file}
6108 @cindex @code{--what-if}
6109 @itemx --new-file=@var{file}
6110 @cindex @code{--new-file}
6111 @itemx --assume-new=@var{file}
6112 @cindex @code{--assume-new}
6113 Pretend that the target @var{file} has just been modified. When used
6114 with the @samp{-n} flag, this shows you what would happen if you were
6115 to modify that file. Without @samp{-n}, it is almost the same as
6116 running a @code{touch} command on the given file before running
6117 @code{make}, except that the modification time is changed only in the
6118 imagination of @code{make}.
6119 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6121 @item --warn-undefined-variables
6122 @cindex @code{--warn-undefined-variables}
6123 @cindex variables, warning for undefined
6124 @cindex undefined variables, warning message
6125 Issue a warning message whenever @code{make} sees a reference to an
6126 undefined variable. This can be helpful when you are trying to debug
6127 makefiles which use variables in complex ways.
6130 @node Implicit Rules, Archives, Running, Top
6131 @chapter Using Implicit Rules
6132 @cindex implicit rule
6133 @cindex rule, implicit
6135 Certain standard ways of remaking target files are used very often. For
6136 example, one customary way to make an object file is from a C source file
6137 using the C compiler, @code{cc}.
6139 @dfn{Implicit rules} tell @code{make} how to use customary techniques so
6140 that you do not have to specify them in detail when you want to use
6141 them. For example, there is an implicit rule for C compilation. File
6142 names determine which implicit rules are run. For example, C
6143 compilation typically takes a @file{.c} file and makes a @file{.o} file.
6144 So @code{make} applies the implicit rule for C compilation when it sees
6145 this combination of file name endings.@refill
6147 A chain of implicit rules can apply in sequence; for example, @code{make}
6148 will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
6150 @xref{Chained Rules, ,Chains of Implicit Rules}.
6153 The built-in implicit rules use several variables in their commands so
6154 that, by changing the values of the variables, you can change the way the
6155 implicit rule works. For example, the variable @code{CFLAGS} controls the
6156 flags given to the C compiler by the implicit rule for C compilation.
6158 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
6161 You can define your own implicit rules by writing @dfn{pattern rules}.
6163 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
6166 @dfn{Suffix rules} are a more limited way to define implicit rules.
6167 Pattern rules are more general and clearer, but suffix rules are
6168 retained for compatibility.
6170 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
6174 * Using Implicit:: How to use an existing implicit rule
6175 to get the commands for updating a file.
6176 * Catalogue of Rules:: A list of built-in implicit rules.
6177 * Implicit Variables:: How to change what predefined rules do.
6178 * Chained Rules:: How to use a chain of implicit rules.
6179 * Pattern Rules:: How to define new implicit rules.
6180 * Last Resort:: How to defining commands for rules
6181 which cannot find any.
6182 * Suffix Rules:: The old-fashioned style of implicit rule.
6183 * Search Algorithm:: The precise algorithm for applying
6187 @node Using Implicit, Catalogue of Rules, , Implicit Rules
6188 @section Using Implicit Rules
6189 @cindex implicit rule, how to use
6190 @cindex rule, implicit, how to use
6192 To allow @code{make} to find a customary method for updating a target file,
6193 all you have to do is refrain from specifying commands yourself. Either
6194 write a rule with no command lines, or don't write a rule at all. Then
6195 @code{make} will figure out which implicit rule to use based on which
6196 kind of source file exists or can be made.
6198 For example, suppose the makefile looks like this:
6202 cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
6206 Because you mention @file{foo.o} but do not give a rule for it, @code{make}
6207 will automatically look for an implicit rule that tells how to update it.
6208 This happens whether or not the file @file{foo.o} currently exists.
6210 If an implicit rule is found, it can supply both commands and one or
6211 more dependencies (the source files). You would want to write a rule
6212 for @file{foo.o} with no command lines if you need to specify additional
6213 dependencies, such as header files, that the implicit rule cannot
6216 Each implicit rule has a target pattern and dependency patterns. There may
6217 be many implicit rules with the same target pattern. For example, numerous
6218 rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
6219 another, from a @samp{.p} file with the Pascal compiler; and so on. The rule
6220 that actually applies is the one whose dependencies exist or can be made.
6221 So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
6222 otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
6223 compiler; and so on.
6225 Of course, when you write the makefile, you know which implicit rule you
6226 want @code{make} to use, and you know it will choose that one because you
6227 know which possible dependency files are supposed to exist.
6228 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
6229 for a catalogue of all the predefined implicit rules.
6231 Above, we said an implicit rule applies if the required dependencies ``exist
6232 or can be made''. A file ``can be made'' if it is mentioned explicitly in
6233 the makefile as a target or a dependency, or if an implicit rule can be
6234 recursively found for how to make it. When an implicit dependency is the
6235 result of another implicit rule, we say that @dfn{chaining} is occurring.
6236 @xref{Chained Rules, ,Chains of Implicit Rules}.
6238 In general, @code{make} searches for an implicit rule for each target, and
6239 for each double-colon rule, that has no commands. A file that is mentioned
6240 only as a dependency is considered a target whose rule specifies nothing,
6241 so implicit rule search happens for it. @xref{Search Algorithm, ,Implicit Rule Search Algorithm}, for the
6242 details of how the search is done.
6244 Note that explicit dependencies do not influence implicit rule search.
6245 For example, consider this explicit rule:
6252 The dependency on @file{foo.p} does not necessarily mean that
6253 @code{make} will remake @file{foo.o} according to the implicit rule to
6254 make an object file, a @file{.o} file, from a Pascal source file, a
6255 @file{.p} file. For example, if @file{foo.c} also exists, the implicit
6256 rule to make an object file from a C source file is used instead,
6257 because it appears before the Pascal rule in the list of predefined
6258 implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
6261 If you do not want an implicit rule to be used for a target that has no
6262 commands, you can give that target empty commands by writing a semicolon
6263 (@pxref{Empty Commands, ,Defining Empty Commands}).
6265 @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
6266 @section Catalogue of Implicit Rules
6267 @cindex implicit rule, predefined
6268 @cindex rule, implicit, predefined
6270 Here is a catalogue of predefined implicit rules which are always
6271 available unless the makefile explicitly overrides or cancels them.
6272 @xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
6273 canceling or overriding an implicit rule. The @samp{-r} or
6274 @samp{--no-builtin-rules} option cancels all predefined rules.
6276 Not all of these rules will always be defined, even when the @samp{-r}
6277 option is not given. Many of the predefined implicit rules are
6278 implemented in @code{make} as suffix rules, so which ones will be
6279 defined depends on the @dfn{suffix list} (the list of dependencies of
6280 the special target @code{.SUFFIXES}). The default suffix list is:
6281 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
6282 @code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
6283 @code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
6284 @code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
6285 @code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
6286 @code{.sh}, @code{.elc}, @code{.el}. All of the implicit rules
6287 described below whose dependencies have one of these suffixes are
6288 actually suffix rules. If you modify the suffix list, the only
6289 predefined suffix rules in effect will be those named by one or two of
6290 the suffixes that are on the list you specify; rules whose suffixes fail
6291 to be on the list are disabled. @xref{Suffix Rules, ,Old-Fashioned
6292 Suffix Rules}, for full details on suffix rules.
6295 @item Compiling C programs
6296 @cindex C, rule to compile
6301 @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
6302 a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
6304 @item Compiling C++ programs
6305 @cindex C++, rule to compile
6309 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
6310 @file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
6311 $(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++
6312 source files instead of @samp{.C}.@refill
6314 @item Compiling Pascal programs
6315 @cindex Pascal, rule to compile
6318 @file{@var{n}.o} is made automatically from @file{@var{n}.p}
6319 with the command @samp{$(PC) -c $(PFLAGS)}.@refill
6321 @item Compiling Fortran and Ratfor programs
6322 @cindex Fortran, rule to compile
6323 @cindex Ratfor, rule to compile
6328 @file{@var{n}.o} is made automatically from @file{@var{n}.r},
6329 @file{@var{n}.F} or @file{@var{n}.f} by running the
6330 Fortran compiler. The precise command used is as follows:@refill
6334 @samp{$(FC) -c $(FFLAGS)}.
6336 @samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}.
6338 @samp{$(FC) -c $(FFLAGS) $(RFLAGS)}.
6341 @item Preprocessing Fortran and Ratfor programs
6342 @file{@var{n}.f} is made automatically from @file{@var{n}.r} or
6343 @file{@var{n}.F}. This rule runs just the preprocessor to convert a
6344 Ratfor or preprocessable Fortran program into a strict Fortran
6345 program. The precise command used is as follows:@refill
6349 @samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}.
6351 @samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
6354 @item Compiling Modula-2 programs
6355 @cindex Modula-2, rule to compile
6360 @file{@var{n}.sym} is made from @file{@var{n}.def} with a command
6361 of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o}
6362 is made from @file{@var{n}.mod}; the form is:
6363 @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
6366 @item Assembling and preprocessing assembler programs
6367 @cindex assembly, rule to compile
6370 @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
6371 running the assembler, @code{as}. The precise command is
6372 @samp{$(AS) $(ASFLAGS)}.@refill
6375 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
6376 running the C preprocessor, @code{cpp}. The precise command is
6377 @w{@samp{$(CPP) $(CPPFLAGS)}}.
6379 @item Linking a single object file
6380 @cindex linking, predefined rule for
6383 @file{@var{n}} is made automatically from @file{@var{n}.o} by running
6384 the linker (usually called @code{ld}) via the C compiler. The precise
6385 command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES)}}.
6387 This rule does the right thing for a simple program with only one
6388 source file. It will also do the right thing if there are multiple
6389 object files (presumably coming from various other source files), one
6390 of which has a name matching that of the executable file. Thus,
6397 when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
6412 In more complicated cases, such as when there is no object file whose
6413 name derives from the executable file name, you must write an explicit
6414 command for linking.
6416 Each kind of file automatically made into @samp{.o} object files will
6417 be automatically linked by using the compiler (@samp{$(CC)},
6418 @samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
6419 assemble @samp{.s} files) without the @samp{-c} option. This could be
6420 done by using the @samp{.o} object files as intermediates, but it is
6421 faster to do the compiling and linking in one step, so that's how it's
6424 @item Yacc for C programs
6426 @cindex Yacc, rule to run
6428 @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
6429 running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
6431 @item Lex for C programs
6433 @cindex Lex, rule to run
6435 @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
6436 by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
6438 @item Lex for Ratfor programs
6439 @file{@var{n}.r} is made automatically from @file{@var{n}.l} by
6440 by running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
6442 The convention of using the same suffix @samp{.l} for all Lex files
6443 regardless of whether they produce C code or Ratfor code makes it
6444 impossible for @code{make} to determine automatically which of the two
6445 languages you are using in any particular case. If @code{make} is
6446 called upon to remake an object file from a @samp{.l} file, it must
6447 guess which compiler to use. It will guess the C compiler, because
6448 that is more common. If you are using Ratfor, make sure @code{make}
6449 knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you
6450 are using Ratfor exclusively, with no C files, remove @samp{.c} from
6451 the list of implicit rule suffixes with:@refill
6456 .SUFFIXES: .o .r .f .l @dots{}
6460 @item Making Lint Libraries from C, Yacc, or Lex programs
6462 @cindex @code{lint}, rule to run
6464 @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
6465 The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
6466 The same command is used on the C code produced from
6467 @file{@var{n}.y} or @file{@var{n}.l}.@refill
6469 @item @TeX{} and Web
6470 @cindex @TeX{}, rule to run
6471 @cindex Web, rule to run
6482 @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command
6483 @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with
6484 @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
6485 it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is
6486 made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
6487 is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
6488 or can be made) with @samp{$(CTANGLE)}.@refill
6490 @item Texinfo and Info
6491 @cindex Texinfo, rule to format
6492 @cindex Info, rule to format
6499 @file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, @file{@var{n}.texi},
6500 or @file{@var{n}.txinfo}, with the @samp{$(TEXI2DVI)} command.
6501 @file{@var{n}.info} is made from @file{@var{n}.texinfo}, @file{@var{n}.texi},
6502 or @file{@var{n}.txinfo}, with the @samp{$(MAKEINFO)} command.@refill
6505 @cindex RCS, rule to extract from
6507 @pindex ,v @r{(RCS file extension)}
6508 Any file @file{@var{n}} is extracted if necessary from an RCS file
6509 named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise
6510 command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be
6511 extracted from RCS if it already exists, even if the RCS file is
6512 newer. The rules for RCS are terminal
6513 (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6514 so RCS files cannot be generated from another source; they must
6515 actually exist.@refill
6518 @cindex SCCS, rule to extract from
6520 @pindex s. @r{(SCCS file prefix)}
6521 Any file @file{@var{n}} is extracted if necessary from an SCCS file
6522 named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise
6523 command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are
6524 terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
6525 so SCCS files cannot be generated from another source; they must
6526 actually exist.@refill
6529 For the benefit of SCCS, a file @file{@var{n}} is copied from
6530 @file{@var{n}.sh} and made executable (by everyone). This is for
6531 shell scripts that are checked into SCCS. Since RCS preserves the
6532 execution permission of a file, you do not need to use this feature
6535 We recommend that you avoid using of SCCS. RCS is widely held to be
6536 superior, and is also free. By choosing free software in place of
6537 comparable (or inferior) proprietary software, you support the free
6541 Usually, you want to change only the variables listed in the table
6542 above, which are documented in the following section.
6544 However, the commands in built-in implicit rules actually use
6545 variables such as @code{COMPILE.c}, @code{LINK.p}, and
6546 @code{PREPROCESS.S}, whose values contain the commands listed above.
6548 @code{make} follows the convention that the rule to compile a
6549 @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
6550 Similarly, the rule to produce an executable from a @file{.@var{x}}
6551 file uses @code{LINK.@var{x}}; and the rule to preprocess a
6552 @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
6554 @vindex OUTPUT_OPTION
6555 Every rule that produces an object file uses the variable
6556 @code{OUTPUT_OPTION}. @code{make} defines this variable either to
6557 contain @samp{-o $@@}, or to be empty, depending on a compile-time
6558 option. You need the @samp{-o} option to ensure that the output goes
6559 into the right file when the source file is in a different directory,
6560 as when using @code{VPATH} (@pxref{Directory Search}). However,
6561 compilers on some systems do not accept a @samp{-o} switch for object
6562 files. If you use such a system, and use @code{VPATH}, some
6563 compilations will put their output in the wrong place.
6564 A possible workaround for this problem is to give @code{OUTPUT_OPTION}
6565 the value @w{@samp{; mv $*.o $@@}}.
6567 @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
6568 @section Variables Used by Implicit Rules
6569 @cindex flags for compilers
6571 The commands in built-in implicit rules make liberal use of certain
6572 predefined variables. You can alter these variables in the makefile,
6573 with arguments to @code{make}, or in the environment to alter how the
6574 implicit rules work without redefining the rules themselves.
6576 For example, the command used to compile a C source file actually says
6577 @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables
6578 used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By
6579 redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
6580 used for all C compilations performed by the implicit rule. By redefining
6581 @samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
6582 each compilation. @emph{All} implicit rules that do C compilation use
6583 @samp{$(CC)} to get the program name for the compiler and @emph{all}
6584 include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
6586 The variables used in implicit rules fall into two classes: those that are
6587 names of programs (like @code{CC}) and those that contain arguments for the
6588 programs (like @code{CFLAGS}). (The ``name of a program'' may also contain
6589 some command arguments, but it must start with an actual executable program
6590 name.) If a variable value contains more than one argument, separate them
6593 Here is a table of variables used as names of programs in built-in rules:
6598 Archive-maintaining program; default @samp{ar}.
6603 Program for doing assembly; default @samp{as}.
6608 Program for compiling C programs; default @samp{cc}.
6613 Program for compiling C++ programs; default @samp{g++}.
6618 Program for extracting a file from RCS; default @samp{co}.
6623 Program for running the C preprocessor, with results to standard output;
6624 default @samp{$(CC) -E}.
6628 Program for compiling or preprocessing Fortran and Ratfor programs;
6634 Program for extracting a file from SCCS; default @samp{get}.
6639 Program to use to turn Lex grammars into C programs or Ratfor programs;
6645 Program for compiling Pascal programs; default @samp{pc}.
6650 Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
6655 Program to use to turn Yacc grammars into Ratfor
6656 programs; default @samp{yacc -r}.
6660 Program to convert a Texinfo source file into an Info file; default
6666 Program to make @TeX{} @sc{dvi} files from @TeX{} source;
6672 Program to make @TeX{} @sc{dvi} files from Texinfo source;
6673 default @samp{texi2dvi}.
6678 Program to translate Web into @TeX{}; default @samp{weave}.
6683 Program to translate C Web into @TeX{}; default @samp{cweave}.
6688 Program to translate Web into Pascal; default @samp{tangle}.
6693 Program to translate C Web into C; default @samp{ctangle}.
6698 Command to remove a file; default @samp{rm -f}.
6702 Here is a table of variables whose values are additional arguments for the
6703 programs above. The default values for all of these is the empty
6704 string, unless otherwise noted.
6709 Flags to give the archive-maintaining program; default @samp{rv}.
6713 Extra flags to give to the assembler (when explicitly
6714 invoked on a @samp{.s} or @samp{.S} file).
6718 Extra flags to give to the C compiler.
6722 Extra flags to give to the C++ compiler.
6726 Extra flags to give to the RCS @code{co} program.
6730 Extra flags to give to the C preprocessor and programs
6731 that use it (the C and Fortran compilers).
6735 Extra flags to give to the Fortran compiler.
6739 Extra flags to give to the SCCS @code{get} program.
6743 Extra flags to give to compilers when they are
6744 supposed to invoke the linker, @samp{ld}.
6748 Extra flags to give to Lex.
6752 Extra flags to give to the Pascal compiler.
6756 Extra flags to give to the Fortran compiler for Ratfor programs.
6760 Extra flags to give to Yacc.
6763 @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
6764 @section Chains of Implicit Rules
6766 @cindex chains of rules
6767 @cindex rule, implicit, chains of
6768 Sometimes a file can be made by a sequence of implicit rules. For example,
6769 a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
6770 first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
6772 If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
6773 special searching is required: @code{make} finds that the object file can
6774 be made by C compilation from @file{@var{n}.c}; later on, when considering
6775 how to make @file{@var{n}.c}, the rule for running Yacc is
6776 used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
6779 @cindex intermediate files
6780 @cindex files, intermediate
6781 However, even if @file{@var{n}.c} does not exist and is not mentioned,
6782 @code{make} knows how to envision it as the missing link between
6783 @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
6784 called an @dfn{intermediate file}. Once @code{make} has decided to use the
6785 intermediate file, it is entered in the data base as if it had been
6786 mentioned in the makefile, along with the implicit rule that says how to
6789 Intermediate files are remade using their rules just like all other
6790 files. The difference is that the intermediate file is deleted when
6791 @code{make} is finished. Therefore, the intermediate file which did not
6792 exist before @code{make} also does not exist after @code{make}. The
6793 deletion is reported to you by printing a @samp{rm -f} command that
6794 shows what @code{make} is doing. (You can list the target pattern of an
6795 implicit rule (such as @samp{%.o}) as a dependency of the special
6796 target @code{.PRECIOUS} to preserve intermediate files made by implicit
6797 rules whose target patterns match that file's name;
6798 see @ref{Interrupts}.)@refill
6799 @cindex intermediate files, preserving
6800 @cindex preserving intermediate files
6801 @cindex preserving with @code{.PRECIOUS}
6802 @cindex @code{.PRECIOUS} intermediate files
6804 A chain can involve more than two implicit rules. For example, it is
6805 possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
6806 Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are
6807 intermediate files that are deleted at the end.@refill
6809 No single implicit rule can appear more than once in a chain. This means
6810 that @code{make} will not even consider such a ridiculous thing as making
6811 @file{foo} from @file{foo.o.o} by running the linker twice. This
6812 constraint has the added benefit of preventing any infinite loop in the
6813 search for an implicit rule chain.
6815 There are some special implicit rules to optimize certain cases that would
6816 otherwise be handled by rule chains. For example, making @file{foo} from
6817 @file{foo.c} could be handled by compiling and linking with separate
6818 chained rules, using @file{foo.o} as an intermediate file. But what
6819 actually happens is that a special rule for this case does the compilation
6820 and linking with a single @code{cc} command. The optimized rule is used in
6821 preference to the step-by-step chain because it comes earlier in the
6824 @node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
6825 @section Defining and Redefining Pattern Rules
6827 You define an implicit rule by writing a @dfn{pattern rule}. A pattern
6828 rule looks like an ordinary rule, except that its target contains the
6829 character @samp{%} (exactly one of them). The target is considered a
6830 pattern for matching file names; the @samp{%} can match any nonempty
6831 substring, while other characters match only themselves. The dependencies
6832 likewise use @samp{%} to show how their names relate to the target name.
6834 Thus, a pattern rule @samp{%.o : %.c} says how to make any file
6835 @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
6837 Note that expansion using @samp{%} in pattern rules occurs
6838 @strong{after} any variable or function expansions, which take place
6839 when the makefile is read. @xref{Using Variables, , How to Use
6840 Variables}, and @ref{Functions, ,Functions for Transforming Text}.
6843 * Pattern Intro:: An introduction to pattern rules.
6844 * Pattern Examples:: Examples of pattern rules.
6845 * Automatic:: How to use automatic variables in the
6846 commands of implicit rules.
6847 * Pattern Match:: How patterns match.
6848 * Match-Anything Rules:: Precautions you should take prior to
6849 defining rules that can match any
6850 target file whatever.
6851 * Canceling Rules:: How to override or cancel built-in rules.
6854 @node Pattern Intro, Pattern Examples, , Pattern Rules
6855 @subsection Introduction to Pattern Rules
6856 @cindex pattern rule
6857 @cindex rule, pattern
6859 A pattern rule contains the character @samp{%} (exactly one of them)
6860 in the target; otherwise, it looks exactly like an ordinary rule. The
6861 target is a pattern for matching file names; the @samp{%} matches any
6862 nonempty substring, while other characters match only themselves.
6863 @cindex target pattern, implicit
6864 @cindex @code{%}, in pattern rules
6866 For example, @samp{%.c} as a pattern matches any file name that ends in
6867 @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
6868 with @samp{s.}, ends in @samp{.c} and is at least five characters long.
6869 (There must be at least one character to match the @samp{%}.) The substring
6870 that the @samp{%} matches is called the @dfn{stem}.@refill
6872 @samp{%} in a dependency of a pattern rule stands for the same stem
6873 that was matched by the @samp{%} in the target. In order for
6874 the pattern rule to apply, its target pattern must match the file name
6875 under consideration, and its dependency patterns must name files that
6876 exist or can be made. These files become dependencies of the target.
6877 @cindex dependency pattern, implicit
6879 Thus, a rule of the form
6882 %.o : %.c ; @var{command}@dots{}
6886 specifies how to make a file @file{@var{n}.o}, with another file
6887 @file{@var{n}.c} as its dependency, provided that @file{@var{n}.c}
6888 exists or can be made.
6890 There may also be dependencies that do not use @samp{%}; such a dependency
6891 attaches to every file made by this pattern rule. These unvarying
6892 dependencies are useful occasionally.
6894 A pattern rule need not have any dependencies that contain @samp{%}, or
6895 in fact any dependencies at all. Such a rule is effectively a general
6896 wildcard. It provides a way to make any file that matches the target
6897 pattern. @xref{Last Resort}.
6899 @c !!! The end of of this paragraph should be rewritten. --bob
6900 Pattern rules may have more than one target. Unlike normal rules, this
6901 does not act as many different rules with the same dependencies and
6902 commands. If a pattern rule has multiple targets, @code{make} knows that
6903 the rule's commands are responsible for making all of the targets. The
6904 commands are executed only once to make all the targets. When searching
6905 for a pattern rule to match a target, the target patterns of a rule other
6906 than the one that matches the target in need of a rule are incidental:
6907 @code{make} worries only about giving commands and dependencies to the file
6908 presently in question. However, when this file's commands are run, the
6909 other targets are marked as having been updated themselves.
6910 @cindex multiple targets, in pattern rule
6911 @cindex target, multiple in pattern rule
6913 The order in which pattern rules appear in the makefile is important
6914 since this is the order in which they are considered.
6915 Of equally applicable
6916 rules, only the first one found is used. The rules you write take precedence
6917 over those that are built in. Note however, that a rule whose
6918 dependencies actually exist or are mentioned always takes priority over a
6919 rule with dependencies that must be made by chaining other implicit rules.
6920 @cindex pattern rules, order of
6921 @cindex order of pattern rules
6923 @node Pattern Examples, Automatic, Pattern Intro, Pattern Rules
6924 @subsection Pattern Rule Examples
6926 Here are some examples of pattern rules actually predefined in
6927 @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o}
6932 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
6936 defines a rule that can make any file @file{@var{x}.o} from
6937 @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and
6938 @samp{$<} to substitute the names of the target file and the source file
6939 in each case where the rule applies (@pxref{Automatic, ,Automatic Variables}).@refill
6941 Here is a second built-in rule:
6949 defines a rule that can make any file @file{@var{x}} whatsoever from a
6950 corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since
6951 the target is @samp{%}, this rule will apply to any file whatever, provided
6952 the appropriate dependency file exists. The double colon makes the rule
6953 @dfn{terminal}, which means that its dependency may not be an intermediate
6954 file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
6957 This pattern rule has two targets:
6961 %.tab.c %.tab.h: %.y
6967 @c The following paragraph is rewritten to avoid overfull hboxes
6968 This tells @code{make} that the command @samp{bison -d @var{x}.y} will
6969 make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file
6970 @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
6971 and the file @file{scan.o} depends on the file @file{parse.tab.h},
6972 when @file{parse.y} is changed, the command @samp{bison -d parse.y}
6973 will be executed only once, and the dependencies of both
6974 @file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably
6975 the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
6976 and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
6977 linked from @file{parse.tab.o}, @file{scan.o}, and its other
6978 dependencies, and it will execute happily ever after.)@refill
6980 @node Automatic, Pattern Match, Pattern Examples, Pattern Rules
6981 @subsection Automatic Variables
6982 @cindex automatic variables
6983 @cindex variables, automatic
6984 @cindex variables, and implicit rule
6986 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
6987 @samp{.o} file: how do you write the @samp{cc} command so that it operates
6988 on the right source file name? You cannot write the name in the command,
6989 because the name is different each time the implicit rule is applied.
6991 What you do is use a special feature of @code{make}, the @dfn{automatic
6992 variables}. These variables have values computed afresh for each rule that
6993 is executed, based on the target and dependencies of the rule. In this
6994 example, you would use @samp{$@@} for the object file name and @samp{$<}
6995 for the source file name.
6997 Here is a table of automatic variables:
7001 @vindex @@ @r{(automatic variable)}
7003 The file name of the target of the rule. If the target is an archive
7004 member, then @samp{$@@} is the name of the archive file. In a pattern
7005 rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
7006 Pattern Rules}), @samp{$@@} is the name of whichever target caused the
7007 rule's commands to be run.
7010 @vindex % @r{(automatic variable)}
7012 The target member name, when the target is an archive member.
7013 @xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then
7014 @samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is
7015 empty when the target is not an archive member.
7018 @vindex < @r{(automatic variable)}
7020 The name of the first dependency. If the target got its commands from
7021 an implicit rule, this will be the first dependency added by the
7022 implicit rule (@pxref{Implicit Rules}).
7025 @vindex ? @r{(automatic variable)}
7027 The names of all the dependencies that are newer than the target, with
7028 spaces between them. For dependencies which are archive members, only
7029 the member named is used (@pxref{Archives}).
7030 @cindex dependencies, list of changed
7031 @cindex list of changed dependencies
7034 @vindex ^ @r{(automatic variable)}
7036 The names of all the dependencies, with spaces between them. For
7037 dependencies which are archive members, only the member named is used
7039 @cindex dependencies, list of all
7040 @cindex list of all dependencies
7043 @vindex * @r{(automatic variable)}
7045 The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
7046 Patterns Match}). If the target is @file{dir/a.foo.b} and the target
7047 pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is
7048 useful for constructing names of related files.@refill
7049 @cindex stem, variable for
7051 In a static pattern rule, the stem is part of the file name that matched
7052 the @samp{%} in the target pattern.
7054 In an explicit rule, there is no stem; so @samp{$*} cannot be determined
7055 in that way. Instead, if the target name ends with a recognized suffix
7056 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
7057 the target name minus the suffix. For example, if the target name is
7058 @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
7059 suffix. GNU @code{make} does this bizarre thing only for compatibility
7060 with other implementations of @code{make}. You should generally never use
7061 @samp{$*} except in implicit rules or static pattern rules.@refill
7063 If the target name in an explicit rule does not end with a recognized
7064 suffix, @samp{$*} is set to the empty string for that rule.
7067 @samp{$?} is useful even in explicit rules when you wish to operate on only
7068 the dependencies that have changed. For example, suppose that an archive
7069 named @file{lib} is supposed to contain copies of several object files.
7070 This rule copies just the changed object files into the archive:
7074 lib: foo.o bar.o lose.o win.o
7079 Of the variables listed above, four have values that are single file
7080 names, and two have values that are lists of file names. These six
7081 have variants that get just the file's directory name or just the file
7082 name within the directory. The variant variables' names are formed by
7083 appending @samp{D} or @samp{F}, respectively. These variants are
7084 semi-obsolete in GNU @code{make} since the functions @code{dir} and
7085 @code{notdir} can be used to get an equivalent effect (@pxref{Filename
7086 Functions, , Functions for File Names}). Here is a table of the
7091 @vindex @@D @r{(automatic variable)}
7093 The directory part of the file name of the target. If the value of
7094 @samp{$@@} is @file{dir/foo.o} then @samp{$(@@D)} is @file{dir/}.
7095 This value is @file{./} if @samp{$@@} does not contain a slash.
7096 @samp{$(@@D)} is equivalent to @w{@samp{$(dir $@@)}}.@refill
7099 @vindex @@F @r{(automatic variable)}
7101 The file-within-directory part of the file name of the target. If the
7102 value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
7103 @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
7106 @vindex *D @r{(automatic variable)}
7109 @vindex *F @r{(automatic variable)}
7111 The directory part and the file-within-directory
7112 part of the stem; @file{dir/} and @file{foo} in this example.
7115 @vindex %D @r{(automatic variable)}
7118 @vindex %F @r{(automatic variable)}
7120 The directory part and the file-within-directory part of the target
7121 archive member name. This makes sense only for archive member targets
7122 of the form @file{@var{archive}(@var{member})} and is useful only when
7123 @var{member} may contain a directory name. (@xref{Archive Members,
7124 ,Archive Members as Targets}.)
7127 @vindex <D @r{(automatic variable)}
7130 @vindex <F @r{(automatic variable)}
7132 The directory part and the file-within-directory
7133 part of the first dependency.
7136 @vindex ^D @r{(automatic variable)}
7139 @vindex ^F @r{(automatic variable)}
7141 Lists of the directory parts and the file-within-directory
7142 parts of all dependencies.
7145 @vindex ?D @r{(automatic variable)}
7148 @vindex ?F @r{(automatic variable)}
7150 Lists of the directory parts and the file-within-directory parts of
7151 all dependencies that are newer than the target.
7154 Note that we use a special stylistic convention when we talk about these
7155 automatic variables; we write ``the value of @samp{$<}'', rather than
7156 @w{``the variable @code{<}''} as we would write for ordinary variables
7157 such as @code{objects} and @code{CFLAGS}. We think this convention
7158 looks more natural in this special case. Please do not assume it has a
7159 deep significance; @samp{$<} refers to the variable named @code{<} just
7160 as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
7161 You could just as well use @samp{$(<)} in place of @samp{$<}.
7163 @node Pattern Match, Match-Anything Rules, Automatic, Pattern Rules
7164 @subsection How Patterns Match
7167 A target pattern is composed of a @samp{%} between a prefix and a suffix,
7168 either or both of which may be empty. The pattern matches a file name only
7169 if the file name starts with the prefix and ends with the suffix, without
7170 overlap. The text between the prefix and the suffix is called the
7171 @dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name
7172 @file{test.o}, the stem is @samp{test}. The pattern rule dependencies are
7173 turned into actual file names by substituting the stem for the character
7174 @samp{%}. Thus, if in the same example one of the dependencies is written
7175 as @samp{%.c}, it expands to @samp{test.c}.@refill
7177 When the target pattern does not contain a slash (and it usually does
7178 not), directory names in the file names are removed from the file name
7179 before it is compared with the target prefix and suffix. After the
7180 comparison of the file name to the target pattern, the directory
7181 names, along with the slash that ends them, are added on to the
7182 dependency file names generated from the pattern rule's dependency
7183 patterns and the file name. The directories are ignored only for the
7184 purpose of finding an implicit rule to use, not in the application of
7185 that rule. Thus, @samp{e%t} matches the file name @file{src/eat},
7186 with @samp{src/a} as the stem. When dependencies are turned into file
7187 names, the directories from the stem are added at the front, while the
7188 rest of the stem is substituted for the @samp{%}. The stem
7189 @samp{src/a} with a dependency pattern @samp{c%r} gives the file name
7190 @file{src/car}.@refill
7192 @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
7193 @subsection Match-Anything Pattern Rules
7195 @cindex match-anything rule
7196 @cindex terminal rule
7197 When a pattern rule's target is just @samp{%}, it matches any file name
7198 whatever. We call these rules @dfn{match-anything} rules. They are very
7199 useful, but it can take a lot of time for @code{make} to think about them,
7200 because it must consider every such rule for each file name listed either
7201 as a target or as a dependency.
7203 Suppose the makefile mentions @file{foo.c}. For this target, @code{make}
7204 would have to consider making it by linking an object file @file{foo.c.o},
7205 or by C compilation-and-linking in one step from @file{foo.c.c}, or by
7206 Pascal compilation-and-linking from @file{foo.c.p}, and many other
7209 We know these possibilities are ridiculous since @file{foo.c} is a C source
7210 file, not an executable. If @code{make} did consider these possibilities,
7211 it would ultimately reject them, because files such as @file{foo.c.o} and
7212 @file{foo.c.p} would not exist. But these possibilities are so
7213 numerous that @code{make} would run very slowly if it had to consider
7216 To gain speed, we have put various constraints on the way @code{make}
7217 considers match-anything rules. There are two different constraints that
7218 can be applied, and each time you define a match-anything rule you must
7219 choose one or the other for that rule.
7221 One choice is to mark the match-anything rule as @dfn{terminal} by defining
7222 it with a double colon. When a rule is terminal, it does not apply unless
7223 its dependencies actually exist. Dependencies that could be made with
7224 other implicit rules are not good enough. In other words, no further
7225 chaining is allowed beyond a terminal rule.
7227 For example, the built-in implicit rules for extracting sources from RCS
7228 and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
7229 not exist, @code{make} will not even consider trying to make it as an
7230 intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
7231 RCS and SCCS files are generally ultimate source files, which should not be
7232 remade from any other files; therefore, @code{make} can save time by not
7233 looking for ways to remake them.@refill
7235 If you do not mark the match-anything rule as terminal, then it is
7236 nonterminal. A nonterminal match-anything rule cannot apply to a file name
7237 that indicates a specific type of data. A file name indicates a specific
7238 type of data if some non-match-anything implicit rule target matches it.
7240 For example, the file name @file{foo.c} matches the target for the pattern
7241 rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this
7242 rule is actually applicable (which happens only if there is a file
7243 @file{foo.y}), the fact that its target matches is enough to prevent
7244 consideration of any nonterminal match-anything rules for the file
7245 @file{foo.c}. Thus, @code{make} will not even consider trying to make
7246 @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
7247 @file{foo.c.p}, etc.@refill
7249 The motivation for this constraint is that nonterminal match-anything
7250 rules are used for making files containing specific types of data (such as
7251 executable files) and a file name with a recognized suffix indicates some
7252 other specific type of data (such as a C source file).
7254 Special built-in dummy pattern rules are provided solely to recognize
7255 certain file names so that nonterminal match-anything rules will not be
7256 considered. These dummy rules have no dependencies and no commands, and
7257 they are ignored for all other purposes. For example, the built-in
7265 exists to make sure that Pascal source files such as @file{foo.p} match a
7266 specific target pattern and thereby prevent time from being wasted looking
7267 for @file{foo.p.o} or @file{foo.p.c}.
7269 Dummy pattern rules such as the one for @samp{%.p} are made for every
7270 suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
7272 @node Canceling Rules, , Match-Anything Rules, Pattern Rules
7273 @subsection Canceling Implicit Rules
7275 You can override a built-in implicit rule (or one you have defined
7276 yourself) by defining a new pattern rule with the same target and
7277 dependencies, but different commands. When the new rule is defined, the
7278 built-in one is replaced. The new rule's position in the sequence of
7279 implicit rules is determined by where you write the new rule.
7281 You can cancel a built-in implicit rule by defining a pattern rule with the
7282 same target and dependencies, but no commands. For example, the following
7283 would cancel the rule that runs the assembler:
7289 @node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
7290 @section Defining Last-Resort Default Rules
7291 @cindex last-resort default rules
7292 @cindex default rules, last-resort
7294 You can define a last-resort implicit rule by writing a terminal
7295 match-anything pattern rule with no dependencies (@pxref{Match-Anything
7296 Rules}). This is just like any other pattern rule; the only thing
7297 special about it is that it will match any target. So such a rule's
7298 commands are used for all targets and dependencies that have no commands
7299 of their own and for which no other implicit rule applies.
7301 For example, when testing a makefile, you might not care if the source
7302 files contain real data, only that they exist. Then you might do this:
7310 to cause all the source files needed (as dependencies) to be created
7314 You can instead define commands to be used for targets for which there
7315 are no rules at all, even ones which don't specify commands. You do
7316 this by writing a rule for the target @code{.DEFAULT}. Such a rule's
7317 commands are used for all dependencies which do not appear as targets in
7318 any explicit rule, and for which no implicit rule applies. Naturally,
7319 there is no @code{.DEFAULT} rule unless you write one.
7321 If you use @code{.DEFAULT} with no commands or dependencies:
7328 the commands previously stored for @code{.DEFAULT} are cleared.
7329 Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
7331 If you do not want a target to get the commands from a match-anything
7332 pattern rule or @code{.DEFAULT}, but you also do not want any commands
7333 to be run for the target, you can give it empty commands (@pxref{Empty
7334 Commands, ,Defining Empty Commands}).@refill
7336 You can use a last-resort rule to override part of another makefile.
7337 @xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
7339 @node Suffix Rules, Search Algorithm, Last Resort, Implicit Rules
7340 @section Old-Fashioned Suffix Rules
7341 @cindex old-fashioned suffix rules
7344 @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
7345 @code{make}. Suffix rules are obsolete because pattern rules are more
7346 general and clearer. They are supported in GNU @code{make} for
7347 compatibility with old makefiles. They come in two kinds:
7348 @dfn{double-suffix} and @dfn{single-suffix}.@refill
7350 A double-suffix rule is defined by a pair of suffixes: the target suffix
7351 and the source suffix. It matches any file whose name ends with the
7352 target suffix. The corresponding implicit dependency is made by
7353 replacing the target suffix with the source suffix in the file name. A
7354 two-suffix rule whose target and source suffixes are @samp{.o} and
7355 @samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
7357 A single-suffix rule is defined by a single suffix, which is the source
7358 suffix. It matches any file name, and the corresponding implicit
7359 dependency name is made by appending the source suffix. A single-suffix
7360 rule whose source suffix is @samp{.c} is equivalent to the pattern rule
7363 Suffix rule definitions are recognized by comparing each rule's target
7364 against a defined list of known suffixes. When @code{make} sees a rule
7365 whose target is a known suffix, this rule is considered a single-suffix
7366 rule. When @code{make} sees a rule whose target is two known suffixes
7367 concatenated, this rule is taken as a double-suffix rule.
7369 For example, @samp{.c} and @samp{.o} are both on the default list of
7370 known suffixes. Therefore, if you define a rule whose target is
7371 @samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
7372 suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned
7373 way to define the rule for compiling a C source file:@refill
7377 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7380 Suffix rules cannot have any dependencies of their own. If they have any,
7381 they are treated as normal files with funny names, not as suffix rules.
7386 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7390 tells how to make the file @file{.c.o} from the dependency file
7391 @file{foo.h}, and is not at all like the pattern rule:
7395 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
7399 which tells how to make @samp{.o} files from @samp{.c} files, and makes all
7400 @samp{.o} files using this pattern rule also depend on @file{foo.h}.
7402 Suffix rules with no commands are also meaningless. They do not remove
7403 previous rules as do pattern rules with no commands (@pxref{Canceling
7404 Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as
7405 a target in the data base.@refill
7408 The known suffixes are simply the names of the dependencies of the special
7409 target @code{.SUFFIXES}. You can add your own suffixes by writing a rule
7410 for @code{.SUFFIXES} that adds more dependencies, as in:
7413 .SUFFIXES: .hack .win
7417 which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
7419 If you wish to eliminate the default known suffixes instead of just adding
7420 to them, write a rule for @code{.SUFFIXES} with no dependencies. By
7421 special dispensation, this eliminates all existing dependencies of
7422 @code{.SUFFIXES}. You can then write another rule to add the suffixes you
7427 .SUFFIXES: # @r{Delete the default suffixes}
7428 .SUFFIXES: .c .o .h # @r{Define our suffix list}
7432 The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
7433 list of suffixes to be empty.
7436 The variable @code{SUFFIXES} is defined to the default list of suffixes
7437 before @code{make} reads any makefiles. You can change the list of suffixes
7438 with a rule for the special target @code{.SUFFIXES}, but that does not alter
7441 @node Search Algorithm, , Suffix Rules, Implicit Rules
7442 @section Implicit Rule Search Algorithm
7443 @cindex implicit rule, search algorithm
7444 @cindex search algorithm, implicit rule
7446 Here is the procedure @code{make} uses for searching for an implicit rule
7447 for a target @var{t}. This procedure is followed for each double-colon
7448 rule with no commands, for each target of ordinary rules none of which have
7449 commands, and for each dependency that is not the target of any rule. It
7450 is also followed recursively for dependencies that come from implicit
7451 rules, in the search for a chain of rules.
7453 Suffix rules are not mentioned in this algorithm because suffix rules are
7454 converted to equivalent pattern rules once the makefiles have been read in.
7456 For an archive member target of the form
7457 @samp{@var{archive}(@var{member})}, the following algorithm is run twice,
7458 first using @samp{(@var{member})} as the target @var{t}, and second using
7459 the entire target if the first run found no rule.@refill
7463 Split @var{t} into a directory part, called @var{d}, and the rest,
7464 called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then
7465 @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
7468 Make a list of all the pattern rules one of whose targets matches
7469 @var{t} or @var{n}. If the target pattern contains a slash, it is
7470 matched against @var{t}; otherwise, against @var{n}.
7473 If any rule in that list is @emph{not} a match-anything rule, then
7474 remove all nonterminal match-anything rules from the list.
7477 Remove from the list all rules with no commands.
7480 For each pattern rule in the list:
7484 Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
7485 matched by the @samp{%} in the target pattern.@refill
7488 Compute the dependency names by substituting @var{s} for @samp{%}; if
7489 the target pattern does not contain a slash, append @var{d} to
7490 the front of each dependency name.@refill
7493 Test whether all the dependencies exist or ought to exist. (If a
7494 file name is mentioned in the makefile as a target or as an explicit
7495 dependency, then we say it ought to exist.)
7497 If all dependencies exist or ought to exist, or there are no dependencies,
7498 then this rule applies.
7502 If no pattern rule has been found so far, try harder.
7503 For each pattern rule in the list:
7507 If the rule is terminal, ignore it and go on to the next rule.
7510 Compute the dependency names as before.
7513 Test whether all the dependencies exist or ought to exist.
7516 For each dependency that does not exist, follow this algorithm
7517 recursively to see if the dependency can be made by an implicit
7521 If all dependencies exist, ought to exist, or can be
7522 made by implicit rules, then this rule applies.
7526 If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
7527 applies. In that case, give @var{t} the same commands that
7528 @code{.DEFAULT} has. Otherwise, there are no commands for @var{t}.
7531 Once a rule that applies has been found, for each target pattern of the
7532 rule other than the one that matched @var{t} or @var{n}, the @samp{%} in
7533 the pattern is replaced with @var{s} and the resultant file name is stored
7534 until the commands to remake the target file @var{t} are executed. After
7535 these commands are executed, each of these stored file names are entered
7536 into the data base and marked as having been updated and having the same
7537 update status as the file @var{t}.
7539 When the commands of a pattern rule are executed for @var{t}, the automatic
7540 variables are set corresponding to the target and dependencies.
7541 @xref{Automatic, ,Automatic Variables}.
7543 @node Archives, Features, Implicit Rules, Top
7544 @chapter Using @code{make} to Update Archive Files
7547 @dfn{Archive files} are files containing named subfiles called
7548 @dfn{members}; they are maintained with the program @code{ar} and their
7549 main use is as subroutine libraries for linking.
7552 * Archive Members:: Archive members as targets.
7553 * Archive Update:: The implicit rule for archive member targets.
7554 * Archive Suffix Rules:: You can write a special kind of suffix rule
7555 for updating archives.
7558 @node Archive Members, Archive Update, , Archives
7559 @section Archive Members as Targets
7560 @cindex archive member targets
7562 An individual member of an archive file can be used as a target or
7563 dependency in @code{make}. The archive file must already exist, but the
7564 member need not exist. You specify the member named @var{member} in
7565 archive file @var{archive} as follows:
7568 @var{archive}(@var{member})
7572 This construct is available only in targets and dependencies, not in
7573 commands! Most programs that you might use in commands do not support this
7574 syntax and cannot act directly on archive members. Only @code{ar} and
7575 other programs specifically designed to operate on archives can do so.
7576 Therefore, valid commands to update an archive member target probably must
7577 use @code{ar}. For example, this rule says to create a member
7578 @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
7581 foolib(hack.o) : hack.o
7585 In fact, nearly all archive member targets are updated in just this way
7586 and there is an implicit rule to do it for you.
7588 To specify several members in the same archive, you can write all the
7589 member names together between the parentheses. For example:
7592 foolib(hack.o kludge.o)
7599 foolib(hack.o) foolib(kludge.o)
7602 @cindex wildcard, in archive member
7603 You can also use shell-style wildcards in an archive member reference.
7604 @xref{Wildcards, ,Using Wildcard Characters in File Names}. For
7605 example, @w{@samp{foolib(*.o)}} expands to all existing members of the
7606 @file{foolib} archive whose names end in @samp{.o}; perhaps
7607 @samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
7609 @node Archive Update, Archive Suffix Rules, Archive Members, Archives
7610 @section Implicit Rule for Archive Member Targets
7612 Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
7613 member named @var{m} in the archive file @var{a}.
7615 When @code{make} looks for an implicit rule for such a target, as a special
7616 feature it considers implicit rules that match @file{(@var{m})}, as well as
7617 those that match the actual target @file{@var{a}(@var{m})}.
7619 This causes one special rule whose target is @file{(%)} to match. This
7620 rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
7621 into the archive. For example, it will update the archive member target
7622 @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
7623 archive @file{foo.a} as a @emph{member} named @file{bar.o}.
7625 When this rule is chained with others, the result is very powerful.
7626 Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
7627 @samp{(} and @samp{)} from being interpreted specially by the shell) in
7628 the presence of a file @file{bar.c} is enough to cause the following
7629 commands to be run, even without a makefile:
7632 cc -c bar.c -o bar.o
7638 Here @code{make} has envisioned the file @file{bar.o} as an intermediate
7639 file. @xref{Chained Rules, ,Chains of Implicit Rules}.
7641 Implicit rules such as this one are written using the automatic variable
7642 @samp{$%}. @xref{Automatic, ,Automatic Variables}.
7644 An archive member name in an archive cannot contain a directory name, but
7645 it may be useful in a makefile to pretend that it does. If you write an
7646 archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
7647 automatic updating with this command:
7650 ar r foo.a dir/file.o
7654 which has the effect of copying the file @file{dir/foo.o} into a member
7655 named @file{foo.o}. In connection with such usage, the automatic variables
7656 @code{%D} and @code{%F} may be useful.
7659 * Archive Symbols:: How to update archive symbol directories.
7662 @node Archive Symbols, , , Archive Update
7663 @subsection Updating Archive Symbol Directories
7664 @cindex @code{__.SYMDEF}
7665 @cindex updating archive symbol directories
7666 @cindex archive symbol directory updating
7667 @cindex symbol directories, updating archive
7668 @cindex directories, updating archive symbol
7670 An archive file that is used as a library usually contains a special member
7671 named @file{__.SYMDEF} that contains a directory of the external symbol
7672 names defined by all the other members. After you update any other
7673 members, you need to update @file{__.SYMDEF} so that it will summarize the
7674 other members properly. This is done by running the @code{ranlib} program:
7677 ranlib @var{archivefile}
7680 Normally you would put this command in the rule for the archive file,
7681 and make all the members of the archive file dependencies of that rule.
7685 libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
7690 The effect of this is to update archive members @file{x.o}, @file{y.o},
7691 etc., and then update the symbol directory member @file{__.SYMDEF} by
7692 running @code{ranlib}. The rules for updating the members are not shown
7693 here; most likely you can omit them and use the implicit rule which copies
7694 files into the archive, as described in the preceding section.
7696 This is not necessary when using the GNU @code{ar} program, which
7697 updates the @file{__.SYMDEF} member automatically.
7699 @node Archive Suffix Rules, , Archive Update, Archives
7700 @section Suffix Rules for Archive Files
7701 @cindex suffix rule, for archive
7702 @cindex archive, suffix rule for
7703 @cindex library archive, suffix rule for
7704 @cindex @code{.a} (archives)
7706 You can write a special kind of suffix rule for dealing with archive
7707 files. @xref{Suffix Rules}, for a full explanation of suffix rules.
7708 Archive suffix rules are obsolete in GNU @code{make}, because pattern
7709 rules for archives are a more general mechanism (@pxref{Archive
7710 Update}). But they are retained for compatibility with other
7713 To write a suffix rule for archives, you simply write a suffix rule
7714 using the target suffix @samp{.a} (the usual suffix for archive files).
7715 For example, here is the old-fashioned suffix rule to update a library
7716 archive from C source files:
7721 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7728 This works just as if you had written the pattern rule:
7733 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
7739 In fact, this is just what @code{make} does when it sees a suffix rule
7740 with @samp{.a} as the target suffix. Any double-suffix rule
7741 @w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
7742 pattern @samp{(%.o)} and a dependency pattern of @samp{%.@var{x}}.
7744 Since you might want to use @samp{.a} as the suffix for some other kind
7745 of file, @code{make} also converts archive suffix rules to pattern rules
7746 in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule
7747 @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
7748 @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
7750 @node Features, Missing, Archives, Top
7751 @chapter Features of GNU @code{make}
7752 @cindex features of GNU @code{make}
7754 @cindex compatibility
7756 Here is a summary of the features of GNU @code{make}, for comparison
7757 with and credit to other versions of @code{make}. We consider the
7758 features of @code{make} in 4.2 BSD systems as a baseline. If you are
7759 concerned with writing portable makefiles, you should use only the
7760 features of @code{make} @emph{not} listed here or in @ref{Missing}.
7762 Many features come from the version of @code{make} in System V.
7766 The @code{VPATH} variable and its special meaning.
7767 @xref{Directory Search, , Searching Directories for Dependencies}.
7768 This feature exists in System V @code{make}, but is undocumented.
7769 It is documented in 4.3 BSD @code{make} (which says it mimics System V's
7770 @code{VPATH} feature).@refill
7773 Included makefiles. @xref{Include, ,Including Other Makefiles}.
7774 Allowing multiple files to be included with a single directive is a GNU
7778 Variables are read from and communicated via the environment.
7779 @xref{Environment, ,Variables from the Environment}.
7782 Options passed through the variable @code{MAKEFLAGS} to recursive
7783 invocations of @code{make}.
7784 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
7787 The automatic variable @code{$%} is set to the member name
7788 in an archive reference. @xref{Automatic, ,Automatic Variables}.
7791 The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
7792 and @code{$?} have corresponding forms like @code{$(@@F)} and
7793 @code{$(@@D)}. We have generalized this to @code{$^} as an obvious
7794 extension. @xref{Automatic, ,Automatic Variables}.@refill
7797 Substitution variable references.
7798 @xref{Reference, ,Basics of Variable References}.
7801 The command-line options @samp{-b} and @samp{-m}, accepted and
7802 ignored. In System V @code{make}, these options actually do something.
7805 Execution of recursive commands to run @code{make} via the variable
7806 @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
7807 @xref{Recursion, ,Recursive Use of @code{make}}.
7810 Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix
7811 Rules}. This feature is obsolete in GNU @code{make}, because the
7812 general feature of rule chaining (@pxref{Chained Rules, ,Chains of
7813 Implicit Rules}) allows one pattern rule for installing members in an
7814 archive (@pxref{Archive Update}) to be sufficient.
7817 The arrangement of lines and backslash-newline combinations in
7818 commands is retained when the commands are printed, so they appear as
7819 they do in the makefile, except for the stripping of initial
7823 The following features were inspired by various other versions of
7824 @code{make}. In some cases it is unclear exactly which versions inspired
7829 Pattern rules using @samp{%}.
7830 This has been implemented in several versions of @code{make}.
7831 We're not sure who invented it first, but it's been spread around a bit.
7832 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
7835 Rule chaining and implicit intermediate files.
7836 This was implemented by Stu Feldman in his version of @code{make}
7837 for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
7838 AT&T Bell Labs in his @code{mk} program (where he terms it
7839 ``transitive closure''). We do not really know if
7840 we got this from either of them or thought it up ourselves at the
7841 same time. @xref{Chained Rules, ,Chains of Implicit Rules}.
7844 The automatic variable @code{$^} containing a list of all dependencies
7845 of the current target. We did not invent this, but we have no idea who did.
7846 @xref{Automatic, ,Automatic Variables}.
7849 The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
7850 invented by Andrew Hume in @code{mk}.
7851 @xref{Instead of Execution, ,Instead of Executing the Commands}.
7854 The concept of doing several things at once (parallelism) exists in
7855 many incarnations of @code{make} and similar programs, though not in the
7856 System V or BSD implementations. @xref{Execution, ,Command Execution}.
7859 Modified variable references using pattern substitution come from
7860 SunOS 4. @xref{Reference, ,Basics of Variable References}.
7861 This functionality was provided in GNU @code{make} by the
7862 @code{patsubst} function before the alternate syntax was implemented
7863 for compatibility with SunOS 4. It is not altogether clear who
7864 inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
7865 4 was released.@refill
7868 The special significance of @samp{+} characters preceding command lines
7869 (@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
7871 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
7874 The @samp{+=} syntax to append to the value of a variable comes from SunOS
7875 4 @code{make}. @xref{Appending, , Appending More Text to Variables}.
7878 The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
7879 multiple members in a single archive file comes from SunOS 4 @code{make}.
7880 @xref{Archive Members}.
7883 The @code{-include} directive to include makefiles with no error for a
7884 nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4
7885 @code{make} does not allow multiple makefiles to be specified in one
7886 @code{-include} directive.)
7889 The remaining features are inventions new in GNU @code{make}:
7893 Use the @samp{-v} or @samp{--version} option to print version and
7894 copyright information.
7897 Use the @samp{-h} or @samp{--help} option to summarize the options to
7901 Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}.
7904 Pass command-line variable assignments automatically through the
7905 variable @code{MAKE} to recursive @code{make} invocations.
7906 @xref{Recursion, ,Recursive Use of @code{make}}.
7909 Use the @samp{-C} or @samp{--directory} command option to change
7910 directory. @xref{Options Summary, ,Summary of Options}.
7913 Make verbatim variable definitions with @code{define}.
7914 @xref{Defining, ,Defining Variables Verbatim}.
7917 Declare phony targets with the special target @code{.PHONY}.
7919 Andrew Hume of AT&T Bell Labs implemented a similar feature with a
7920 different syntax in his @code{mk} program. This seems to be a case of
7921 parallel discovery. @xref{Phony Targets, ,Phony Targets}.
7924 Manipulate text by calling functions.
7925 @xref{Functions, ,Functions for Transforming Text}.
7928 Use the @samp{-o} or @samp{--old-file}
7929 option to pretend a file's modification-time is old.
7930 @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
7933 Conditional execution.
7935 This feature has been implemented numerous times in various versions
7936 of @code{make}; it seems a natural extension derived from the features
7937 of the C preprocessor and similar macro languages and is not a
7938 revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}.
7941 Specify a search path for included makefiles.
7942 @xref{Include, ,Including Other Makefiles}.
7945 Specify extra makefiles to read with an environment variable.
7946 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
7949 Strip leading sequences of @samp{./} from file names, so that
7950 @file{./@var{file}} and @file{@var{file}} are considered to be the
7954 Use a special search method for library dependencies written in the
7955 form @samp{-l@var{name}}.
7956 @xref{Libraries/Search, ,Directory Search for Link Libraries}.
7959 Allow suffixes for suffix rules
7960 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
7961 characters. In other versions of @code{make}, they must begin with
7962 @samp{.} and not contain any @samp{/} characters.
7965 Keep track of the current level of @code{make} recursion using the
7966 variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}.
7969 Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}.
7972 Provide selective @code{vpath} search.
7973 @xref{Directory Search, ,Searching Directories for Dependencies}.
7976 Provide computed variable references.
7977 @xref{Reference, ,Basics of Variable References}.
7980 Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
7981 System V @code{make} has a very, very limited form of this
7982 functionality in that it will check out SCCS files for makefiles.
7985 Various new built-in implicit rules.
7986 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules}.
7989 @node Missing, Makefile Conventions, Features, Top
7990 @chapter Incompatibilities and Missing Features
7991 @cindex incompatibilities
7992 @cindex missing features
7993 @cindex features, missing
7995 The @code{make} programs in various other systems support a few features
7996 that are not implemented in GNU @code{make}. The POSIX.2 standard
7997 (@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
7998 require any of these features.@refill
8002 A target of the form @samp{@var{file}((@var{entry}))} stands for a member
8003 of archive file @var{file}. The member is chosen, not by name, but by
8004 being an object file which defines the linker symbol @var{entry}.@refill
8006 This feature was not put into GNU @code{make} because of the
8007 nonmodularity of putting knowledge into @code{make} of the internal
8008 format of archive file symbol tables.
8009 @xref{Archive Symbols, ,Updating Archive Symbol Directories}.
8012 Suffixes (used in suffix rules) that end with the character @samp{~}
8013 have a special meaning to System V @code{make};
8014 they refer to the SCCS file that corresponds
8015 to the file one would get without the @samp{~}. For example, the
8016 suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
8017 the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole
8018 series of such suffix rules is required.
8019 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
8021 In GNU @code{make}, this entire series of cases is handled by two
8022 pattern rules for extraction from SCCS, in combination with the
8023 general feature of rule chaining.
8024 @xref{Chained Rules, ,Chains of Implicit Rules}.
8027 In System V @code{make}, the string @samp{$$@@} has the strange meaning
8028 that, in the dependencies of a rule with multiple targets, it stands
8029 for the particular target that is being processed.
8031 This is not defined in GNU @code{make} because @samp{$$} should always
8032 stand for an ordinary @samp{$}.
8034 It is possible to get this functionality through the use of static pattern
8035 rules (@pxref{Static Pattern, ,Static Pattern Rules}).
8036 The System V @code{make} rule:
8039 $(targets): $$@@.o lib.a
8043 can be replaced with the GNU @code{make} static pattern rule:
8046 $(targets): %: %.o lib.a
8050 In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
8051 (@pxref{Directory Search, ,Searching Directories for Dependencies}) have their names changed inside command
8052 strings. We feel it is much cleaner to always use automatic variables
8053 and thus make this feature obsolete.@refill
8056 In some Unix @code{make}s, implicit rule search
8057 (@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for
8058 @emph{all} targets, not just those without commands. This means you can
8069 and Unix @code{make} will intuit that @file{foo.o} depends on
8070 @file{foo.c}.@refill
8072 We feel that such usage is broken. The dependency properties of
8073 @code{make} are well-defined (for GNU @code{make}, at least),
8074 and doing such a thing simply does not fit the model.@refill
8077 GNU @code{make} does not include any built-in implicit rules for
8078 compiling or preprocessing EFL programs. If we hear of anyone who is
8079 using EFL, we will gladly add them.
8082 It appears that in SVR4 @code{make}, a suffix rule can be specified with
8083 no commands, and it is treated as if it had empty commands
8084 (@pxref{Empty Commands}). For example:
8091 will override the built-in @file{.c.a} suffix rule.
8093 We feel that it is cleaner for a rule without commands to always simply
8094 add to the dependency list for the target. The above example can be
8095 easily rewritten to get the desired behavior in GNU @code{make}:
8102 Some versions of @code{make} invoke the shell with the @samp{-e} flag,
8103 except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
8104 Program}). The @samp{-e} flag tells the shell to exit as soon as any
8105 program it runs returns a nonzero status. We feel it is cleaner to
8106 write each shell command line to stand on its own and not require this
8110 @comment The makefile standards are in a separate file that is also
8111 @comment included by standards.texi.
8112 @include make-stds.texi
8114 @node Quick Reference, Complex Makefile, Makefile Conventions, Top
8115 @appendix Quick Reference
8117 This appendix summarizes the directives, text manipulation functions,
8118 and special variables which GNU @code{make} understands.
8119 @xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
8120 and @ref{Options Summary, ,Summary of Options},
8121 for other summaries.
8123 Here is a summary of the directives GNU @code{make} recognizes:
8126 @item define @var{variable}
8129 Define a multi-line, recursively-expanded variable.@*
8132 @item ifdef @var{variable}
8133 @itemx ifndef @var{variable}
8134 @itemx ifeq (@var{a},@var{b})
8135 @itemx ifeq "@var{a}" "@var{b}"
8136 @itemx ifeq '@var{a}' '@var{b}'
8137 @itemx ifneq (@var{a},@var{b})
8138 @itemx ifneq "@var{a}" "@var{b}"
8139 @itemx ifneq '@var{a}' '@var{b}'
8143 Conditionally evaluate part of the makefile.@*
8144 @xref{Conditionals}.
8146 @item include @var{file}
8148 Include another makefile.@*
8149 @xref{Include, ,Including Other Makefiles}.
8151 @item override @var{variable} = @var{value}
8152 @itemx override @var{variable} := @var{value}
8153 @itemx override @var{variable} += @var{value}
8154 @itemx override define @var{variable}
8157 Define a variable, overriding any previous definition, even one from
8159 @xref{Override Directive, ,The @code{override} Directive}.
8163 Tell @code{make} to export all variables to child processes by default.@*
8164 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8166 @item export @var{variable}
8167 @itemx export @var{variable} = @var{value}
8168 @itemx export @var{variable} := @var{value}
8169 @itemx export @var{variable} += @var{value}
8170 @itemx unexport @var{variable}
8171 Tell @code{make} whether or not to export a particular variable to child
8173 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
8175 @item vpath @var{pattern} @var{path}
8176 Specify a search path for files matching a @samp{%} pattern.@*
8177 @xref{Selective Search, , The @code{vpath} Directive}.
8179 @item vpath @var{pattern}
8180 Remove all search paths previously specified for @var{pattern}.
8183 Remove all search paths previously specified in any @code{vpath}
8187 Here is a summary of the text manipulation functions (@pxref{Functions}):
8190 @item $(subst @var{from},@var{to},@var{text})
8191 Replace @var{from} with @var{to} in @var{text}.@*
8192 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8194 @item $(patsubst @var{pattern},@var{replacement},@var{text})
8195 Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
8196 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8198 @item $(strip @var{string})
8199 Remove excess whitespace characters from @var{string}.@*
8200 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8202 @item $(findstring @var{find},@var{text})
8203 Locate @var{find} in @var{text}.@*
8204 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8206 @item $(filter @var{pattern}@dots{},@var{text})
8207 Select words in @var{text} that match one of the @var{pattern} words.@*
8208 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8210 @item $(filter-out @var{pattern}@dots{},@var{text})
8211 Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
8212 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8214 @item $(sort @var{list})
8215 Sort the words in @var{list} lexicographically, removing duplicates.@*
8216 @xref{Text Functions, , Functions for String Substitution and Analysis}.
8218 @item $(dir @var{names}@dots{})
8219 Extract the directory part of each file name.@*
8220 @xref{Filename Functions, ,Functions for File Names}.
8222 @item $(notdir @var{names}@dots{})
8223 Extract the non-directory part of each file name.@*
8224 @xref{Filename Functions, ,Functions for File Names}.
8226 @item $(suffix @var{names}@dots{})
8227 Extract the suffix (the last @samp{.} and following characters) of each file name.@*
8228 @xref{Filename Functions, ,Functions for File Names}.
8230 @item $(basename @var{names}@dots{})
8231 Extract the base name (name without suffix) of each file name.@*
8232 @xref{Filename Functions, ,Functions for File Names}.
8234 @item $(addsuffix @var{suffix},@var{names}@dots{})
8235 Append @var{suffix} to each word in @var{names}.@*
8236 @xref{Filename Functions, ,Functions for File Names}.
8238 @item $(addprefix @var{prefix},@var{names}@dots{})
8239 Prepend @var{prefix} to each word in @var{names}.@*
8240 @xref{Filename Functions, ,Functions for File Names}.
8242 @item $(join @var{list1},@var{list2})
8243 Join two parallel lists of words.@*
8244 @xref{Filename Functions, ,Functions for File Names}.
8246 @item $(word @var{n},@var{text})
8247 Extract the @var{n}th word (one-origin) of @var{text}.@*
8248 @xref{Filename Functions, ,Functions for File Names}.
8250 @item $(words @var{text})
8251 Count the number of words in @var{text}.@*
8252 @xref{Filename Functions, ,Functions for File Names}.
8254 @item $(firstword @var{names}@dots{})
8255 Extract the first word of @var{names}.@*
8256 @xref{Filename Functions, ,Functions for File Names}.
8258 @item $(wildcard @var{pattern}@dots{})
8259 Find file names matching a shell file name pattern (@emph{not} a
8260 @samp{%} pattern).@*
8261 @xref{Wildcard Function, ,The Function @code{wildcard}}.
8263 @item $(shell @var{command})
8265 Execute a shell command and return its output.@*
8266 @xref{Shell Function, , The @code{shell} Function}.
8268 @item $(origin @var{variable})
8270 Return a string describing how the @code{make} variable @var{variable} was
8272 @xref{Origin Function, , The @code{origin} Function}.
8274 @item $(foreach @var{var},@var{words},@var{text})
8276 Evaluate @var{text} with @var{var} bound to each word in @var{words},
8277 and concatenate the results.@*
8278 @xref{Foreach Function, ,The @code{foreach} Function}.
8281 Here is a summary of the automatic variables.
8282 @xref{Automatic, ,Automatic Variables},
8283 for full information.
8287 The file name of the target.
8290 The target member name, when the target is an archive member.
8293 The name of the first dependency.
8296 The names of all the dependencies that are
8297 newer than the target, with spaces between them.
8298 For dependencies which are archive members, only
8299 the member named is used (@pxref{Archives}).
8302 The names of all the dependencies, with spaces between them. For
8303 dependencies which are archive members, only the member named is used
8307 The stem with which an implicit rule matches
8308 (@pxref{Pattern Match, ,How Patterns Match}).
8312 The directory part and the file-within-directory part of @code{$@@}.
8316 The directory part and the file-within-directory part of @code{$*}.
8320 The directory part and the file-within-directory part of @code{$%}.
8324 The directory part and the file-within-directory part of @code{$<}.
8328 The directory part and the file-within-directory part of @code{$^}.
8332 The directory part and the file-within-directory part of @code{$?}.
8335 These variables are used specially by GNU @code{make}:
8340 Makefiles to be read on every invocation of @code{make}.@*
8341 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
8345 Directory search path for files not found in the current directory.@*
8346 @xref{General Search, , @code{VPATH} Search Path for All Dependencies}.
8350 The name of the system default command interpreter, usually @file{/bin/sh}.
8351 You can set @code{SHELL} in the makefile to change the shell used to run
8352 commands. @xref{Execution, ,Command Execution}.
8356 The name with which @code{make} was invoked.
8357 Using this variable in commands has special meaning.
8358 @xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.
8362 The number of levels of recursion (sub-@code{make}s).@*
8363 @xref{Variables/Recursion}.
8368 The flags given to @code{make}. You can set this in the environment or
8369 a makefile to set flags.@*
8370 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
8374 The default list of suffixes before @code{make} reads any makefiles.
8377 @node Complex Makefile, Concept Index, Quick Reference, Top
8378 @appendix Complex Makefile Example
8380 Here is the makefile for the GNU @code{tar} program. This is a
8381 moderately complex makefile.
8383 Because it is the first target, the default goal is @samp{all}. An
8384 interesting feature of this makefile is that @file{testpad.h} is a
8385 source file automatically created by the @code{testpad} program,
8386 itself compiled from @file{testpad.c}.
8388 If you type @samp{make} or @samp{make all}, then @code{make} creates
8389 the @file{tar} executable, the @file{rmt} daemon that provides
8390 remote tape access, and the @file{tar.info} Info file.
8392 If you type @samp{make install}, then @code{make} not only creates
8393 @file{tar}, @file{rmt}, and @file{tar.info}, but also installs
8396 If you type @samp{make clean}, then @code{make} removes the @samp{.o}
8397 files, and the @file{tar}, @file{rmt}, @file{testpad},
8398 @file{testpad.h}, and @file{core} files.
8400 If you type @samp{make distclean}, then @code{make} not only removes
8401 the same files as does @samp{make clean} but also the
8402 @file{TAGS}, @file{Makefile}, and @file{config.status} files.
8403 (Although it is not evident, this makefile (and
8404 @file{config.status}) is generated by the user with the
8405 @code{configure} program, which is provided in the @code{tar}
8406 distribution, but is not shown here.)
8408 If you type @samp{make realclean}, then @code{make} removes the same
8409 files as does @samp{make distclean} and also removes the Info files
8410 generated from @file{tar.texinfo}.
8412 In addition, there are targets @code{shar} and @code{dist} that create
8417 # Generated automatically from Makefile.in by configure.
8418 # Un*x Makefile for GNU tar program.
8419 # Copyright (C) 1991 Free Software Foundation, Inc.
8423 # This program is free software; you can redistribute
8424 # it and/or modify it under the terms of the GNU
8425 # General Public License @dots{}
8432 #### Start of system configuration section. ####
8437 # If you use gcc, you should either run the
8438 # fixincludes script that comes with it or else use
8439 # gcc with the -traditional option. Otherwise ioctl
8440 # calls will be compiled incorrectly on some systems.
8443 INSTALL = /usr/local/bin/install -c
8444 INSTALLDATA = /usr/local/bin/install -c -m 644
8447 # Things you might add to DEFS:
8448 # -DSTDC_HEADERS If you have ANSI C headers and
8450 # -DPOSIX If you have POSIX.1 headers and
8452 # -DBSD42 If you have sys/dir.h (unless
8453 # you use -DPOSIX), sys/file.h,
8454 # and st_blocks in `struct stat'.
8455 # -DUSG If you have System V/ANSI C
8456 # string and memory functions
8457 # and headers, sys/sysmacros.h,
8458 # fcntl.h, getcwd, no valloc,
8459 # and ndir.h (unless
8460 # you use -DDIRENT).
8461 # -DNO_MEMORY_H If USG or STDC_HEADERS but do not
8463 # -DDIRENT If USG and you have dirent.h
8464 # instead of ndir.h.
8465 # -DSIGTYPE=int If your signal handlers
8466 # return int, not void.
8467 # -DNO_MTIO If you lack sys/mtio.h
8469 # -DNO_REMOTE If you do not have a remote shell
8471 # -DUSE_REXEC To use rexec for remote tape
8472 # operations instead of
8473 # forking rsh or remsh.
8474 # -DVPRINTF_MISSING If you lack vprintf function
8475 # (but have _doprnt).
8476 # -DDOPRNT_MISSING If you lack _doprnt function.
8477 # Also need to define
8478 # -DVPRINTF_MISSING.
8479 # -DFTIME_MISSING If you lack ftime system call.
8480 # -DSTRSTR_MISSING If you lack strstr function.
8481 # -DVALLOC_MISSING If you lack valloc function.
8482 # -DMKDIR_MISSING If you lack mkdir and
8483 # rmdir system calls.
8484 # -DRENAME_MISSING If you lack rename system call.
8485 # -DFTRUNCATE_MISSING If you lack ftruncate
8487 # -DV7 On Version 7 Unix (not
8488 # tested in a long time).
8489 # -DEMUL_OPEN3 If you lack a 3-argument version
8490 # of open, and want to emulate it
8491 # with system calls you do have.
8492 # -DNO_OPEN3 If you lack the 3-argument open
8493 # and want to disable the tar -k
8494 # option instead of emulating open.
8495 # -DXENIX If you have sys/inode.h
8496 # and need it 94 to be included.
8498 DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
8499 -DVPRINTF_MISSING -DBSD42
8500 # Set this to rtapelib.o unless you defined NO_REMOTE,
8501 # in which case make it empty.
8502 RTAPELIB = rtapelib.o
8504 DEF_AR_FILE = /dev/rmt8
8509 CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
8510 -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
8511 -DDEFBLOCKING=$(DEFBLOCKING)
8517 # Prefix for each installed program,
8518 # normally empty or `g'.
8521 # The directory to install tar in.
8522 bindir = $(prefix)/bin
8524 # The directory to install the info files in.
8525 infodir = $(prefix)/info
8528 #### End of system configuration section. ####
8530 SRC1 = tar.c create.c extract.c buffer.c \
8531 getoldopt.c update.c gnu.c mangle.c
8532 SRC2 = version.c list.c names.c diffarch.c \
8533 port.c wildmat.c getopt.c
8534 SRC3 = getopt1.c regex.c getdate.y
8535 SRCS = $(SRC1) $(SRC2) $(SRC3)
8536 OBJ1 = tar.o create.o extract.o buffer.o \
8537 getoldopt.o update.o gnu.o mangle.o
8538 OBJ2 = version.o list.o names.o diffarch.o \
8539 port.o wildmat.o getopt.o
8540 OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB)
8541 OBJS = $(OBJ1) $(OBJ2) $(OBJ3)
8543 AUX = README COPYING ChangeLog Makefile.in \
8544 makefile.pc configure configure.in \
8545 tar.texinfo tar.info* texinfo.tex \
8546 tar.h port.h open3.h getopt.h regex.h \
8547 rmt.h rmt.c rtapelib.c alloca.c \
8548 msd_dir.h msd_dir.c tcexparg.c \
8549 level-0 level-1 backup-specs testpad.c
8552 all: tar rmt tar.info
8556 $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
8561 $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
8565 tar.info: tar.texinfo
8566 makeinfo tar.texinfo
8571 $(INSTALL) tar $(bindir)/$(binprefix)tar
8572 -test ! -f rmt || $(INSTALL) rmt /etc/rmt
8573 $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
8577 $(OBJS): tar.h port.h testpad.h
8578 regex.o buffer.o tar.o: regex.h
8579 # getdate.y has 8 shift/reduce conflicts.
8589 $(CC) -o $@@ testpad.o
8599 rm -f *.o tar rmt testpad testpad.h core
8604 rm -f TAGS Makefile config.status
8608 realclean: distclean
8613 shar: $(SRCS) $(AUX)
8614 shar $(SRCS) $(AUX) | compress \
8615 > tar-`sed -e '/version_string/!d' \
8616 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8622 dist: $(SRCS) $(AUX)
8624 -e '/version_string/!d' \
8625 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
8628 -rm -rf `cat .fname`
8630 ln $(SRCS) $(AUX) `cat .fname`
8631 -rm -rf `cat .fname` .fname
8632 tar chZf `cat .fname`.tar.Z `cat .fname`
8636 tar.zoo: $(SRCS) $(AUX)
8640 for X in $(SRCS) $(AUX) ; do \
8642 sed 's/$$/^M/' $$X \
8643 > tmp.dir/$$X ; done
8644 cd tmp.dir ; zoo aM ../tar.zoo *
8649 @node Concept Index, Name Index, Complex Makefile, Top
8650 @unnumbered Index of Concepts
8654 @node Name Index, , Concept Index, Top
8655 @unnumbered Index of Functions, Variables, & Directives