/[make]/make/doc/make.texi
ViewVC logotype

Contents of /make/doc/make.texi

Parent Directory Parent Directory | Revision Log Revision Log


Revision 1.15 - (show annotations) (download) (as text)
Wed Oct 22 04:35:27 2003 UTC (20 years, 6 months ago) by psmith
Branch: MAIN
Changes since 1.14: +5 -5 lines
File MIME type: application/x-texinfo
Build fixes due to changes in the FSF web site.
Add new language support.
Minor configure, etc. cleanups.

1 \input texinfo @c -*- Texinfo -*-
2 @c %**start of header
3 @setfilename make.info
4 @settitle GNU @code{make}
5 @setchapternewpage odd
6 @c %**end of header
7
8 @c FSF publishers: format makebook.texi instead of using this file directly.
9
10 @set RCSID $Id: make.texi,v 1.14 2003/07/31 13:04:33 psmith Exp $
11 @set EDITION 0.61
12 @set VERSION 3.81
13 @set UPDATED 02 May 2003
14 @set UPDATE-MONTH May 2003
15 @comment The ISBN number might need to change on next publication.
16 @set ISBN 1-882114-81-7 @c From Brian Youmans <3diff@gnu.org>, 25 Apr 2000
17
18 @c finalout
19
20 @c ISPELL CHECK: done, 10 June 1993 --roland
21 @c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz
22
23 @c Combine the variable and function indices:
24 @syncodeindex vr fn
25 @c Combine the program and concept indices:
26 @syncodeindex pg cp
27
28 @dircategory GNU Packages
29 @direntry
30 * Make: (make). Remake files automatically.
31 @end direntry
32
33 @ifinfo
34 This file documents the GNU Make utility, which determines
35 automatically which pieces of a large program need to be recompiled,
36 and issues the commands to recompile them.
37
38 This is Edition @value{EDITION}, last updated @value{UPDATED},
39 of @cite{The GNU Make Manual}, for @code{make}, Version @value{VERSION}.
40
41 Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003
42 Free Software Foundation, Inc.
43
44 Permission is granted to copy, distribute and/or modify this document
45 under the terms of the GNU Free Documentation License, Version 1.1 or
46 any later version published by the Free Software Foundation; with no
47 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
48 Texts. A copy of the license is included in the section entitled
49 ``GNU Free Documentation License''.
50 @end ifinfo
51
52 @iftex
53 @shorttitlepage GNU Make
54 @end iftex
55 @titlepage
56 @title GNU Make
57 @subtitle A Program for Directing Recompilation
58 @subtitle GNU @code{make} Version @value{VERSION}
59 @subtitle @value{UPDATE-MONTH}
60 @author Richard M. Stallman, Roland McGrath, Paul Smith
61 @page
62 @vskip 0pt plus 1filll
63 Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
64 1996, 1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.
65 @sp 2
66 Published by the Free Software Foundation @*
67 59 Temple Place -- Suite 330, @*
68 Boston, MA 02111-1307 USA @*
69 ISBN @value{ISBN} @*
70
71 Permission is granted to copy, distribute and/or modify this document
72 under the terms of the GNU Free Documentation License, Version 1.1 or
73 any later version published by the Free Software Foundation; with the
74 Invariant Sections being ``GNU General Public License'', the Front-Cover
75 Texts being ``A GNU Manual'', and with the Back-Cover Texts being as in
76 (a) below. A copy of the license is included in the section entitled
77 ``GNU Free Documentation License''.
78
79 (a) The FSF's Back-Cover Text is:
80
81 @quotation
82 You have freedom to copy and modify this GNU Manual, like GNU
83 software. Copies published by the Free Software Foundation raise
84 funds for GNU development.
85 @end quotation
86 @sp 2
87 Cover art by Etienne Suvasa.
88 @end titlepage
89 @page
90
91 @ifinfo
92 @node Top, Overview, (dir), (dir)
93 @top Make
94
95 The GNU @code{make} utility automatically determines which pieces of a
96 large program need to be recompiled, and issues the commands to
97 recompile them.@refill
98
99 This edition of the @cite{GNU Make Manual},
100 last updated @value{UPDATED},
101 documents GNU @code{make} Version @value{VERSION}.@refill
102
103 This manual describes @code{make} and contains the following chapters:@refill
104 @end ifinfo
105
106 @menu
107 * Overview:: Overview of @code{make}.
108 * Introduction:: An introduction to @code{make}.
109 * Makefiles:: Makefiles tell @code{make} what to do.
110 * Rules:: Rules describe when a file must be remade.
111 * Commands:: Commands say how to remake a file.
112 * Using Variables:: You can use variables to avoid repetition.
113 * Conditionals:: Use or ignore parts of the makefile based
114 on the values of variables.
115 * Functions:: Many powerful ways to manipulate text.
116 * Invoking make: Running. How to invoke @code{make} on the command line.
117 * Implicit Rules:: Use implicit rules to treat many files alike,
118 based on their file names.
119 * Archives:: How @code{make} can update library archives.
120 * Features:: Features GNU @code{make} has over other @code{make}s.
121 * Missing:: What GNU @code{make} lacks from other @code{make}s.
122 * Makefile Conventions:: Conventions for writing makefiles for
123 GNU programs.
124 * Quick Reference:: A quick reference for experienced users.
125 * Error Messages:: A list of common errors generated by @code{make}.
126 * Complex Makefile:: A real example of a straightforward,
127 but nontrivial, makefile.
128
129 * GNU Free Documentation License:: License for copying this manual
130 * Concept Index:: Index of Concepts
131 * Name Index:: Index of Functions, Variables, & Directives
132
133 @detailmenu
134 --- The Detailed Node Listing ---
135
136 Overview of @code{make}
137
138 * Preparing:: Preparing and Running Make
139 * Reading:: On Reading this Text
140 * Bugs:: Problems and Bugs
141
142 An Introduction to Makefiles
143
144 * Rule Introduction:: What a rule looks like.
145 * Simple Makefile:: A Simple Makefile
146 * How Make Works:: How @code{make} Processes This Makefile
147 * Variables Simplify:: Variables Make Makefiles Simpler
148 * make Deduces:: Letting @code{make} Deduce the Commands
149 * Combine By Prerequisite:: Another Style of Makefile
150 * Cleanup:: Rules for Cleaning the Directory
151
152 Writing Makefiles
153
154 * Makefile Contents:: What makefiles contain.
155 * Makefile Names:: How to name your makefile.
156 * Include:: How one makefile can use another makefile.
157 * MAKEFILES Variable:: The environment can specify extra makefiles.
158 * MAKEFILE_LIST Variable:: Discover which makefiles have been read.
159 * Special Variables:: Other special variables.
160 * Remaking Makefiles:: How makefiles get remade.
161 * Overriding Makefiles:: How to override part of one makefile
162 with another makefile.
163 * Reading Makefiles:: How makefiles are parsed.
164
165 Writing Rules
166
167 * Rule Example:: An example explained.
168 * Rule Syntax:: General syntax explained.
169 * Prerequisite Types:: There are two types of prerequisites.
170 * Wildcards:: Using wildcard characters such as `*'.
171 * Directory Search:: Searching other directories for source files.
172 * Phony Targets:: Using a target that is not a real file's name.
173 * Force Targets:: You can use a target without commands
174 or prerequisites to mark other
175 targets as phony.
176 * Empty Targets:: When only the date matters and the
177 files are empty.
178 * Special Targets:: Targets with special built-in meanings.
179 * Multiple Targets:: When to make use of several targets in a rule.
180 * Multiple Rules:: How to use several rules with the same target.
181 * Static Pattern:: Static pattern rules apply to multiple targets
182 and can vary the prerequisites according to
183 the target name.
184 * Double-Colon:: How to use a special kind of rule to allow
185 several independent rules for one target.
186 * Automatic Prerequisites:: How to automatically generate rules giving
187 prerequisites from source files themselves.
188
189 Using Wildcard Characters in File Names
190
191 * Wildcard Examples:: Several examples
192 * Wildcard Pitfall:: Problems to avoid.
193 * Wildcard Function:: How to cause wildcard expansion where
194 it does not normally take place.
195
196 Searching Directories for Prerequisites
197
198 * General Search:: Specifying a search path that applies
199 to every prerequisite.
200 * Selective Search:: Specifying a search path
201 for a specified class of names.
202 * Search Algorithm:: When and how search paths are applied.
203 * Commands/Search:: How to write shell commands that work together
204 with search paths.
205 * Implicit/Search:: How search paths affect implicit rules.
206 * Libraries/Search:: Directory search for link libraries.
207
208 Static Pattern Rules
209
210 * Static Usage:: The syntax of static pattern rules.
211 * Static versus Implicit:: When are they better than implicit rules?
212
213 Writing the Commands in Rules
214
215 * Echoing:: How to control when commands are echoed.
216 * Execution:: How commands are executed.
217 * Parallel:: How commands can be executed in parallel.
218 * Errors:: What happens after a command execution error.
219 * Interrupts:: What happens when a command is interrupted.
220 * Recursion:: Invoking @code{make} from makefiles.
221 * Sequences:: Defining canned sequences of commands.
222 * Empty Commands:: Defining useful, do-nothing commands.
223
224 Recursive Use of @code{make}
225
226 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
227 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
228 * Options/Recursion:: How to communicate options to a sub-@code{make}.
229 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
230 helps debug use of recursive @code{make} commands.
231
232 How to Use Variables
233
234 * Reference:: How to use the value of a variable.
235 * Flavors:: Variables come in two flavors.
236 * Advanced:: Advanced features for referencing a variable.
237 * Values:: All the ways variables get their values.
238 * Setting:: How to set a variable in the makefile.
239 * Appending:: How to append more text to the old value
240 of a variable.
241 * Override Directive:: How to set a variable in the makefile even if
242 the user has set it with a command argument.
243 * Defining:: An alternate way to set a variable
244 to a verbatim string.
245 * Environment:: Variable values can come from the environment.
246 * Target-specific:: Variable values can be defined on a per-target
247 basis.
248 * Pattern-specific:: Target-specific variable values can be applied
249 to a group of targets that match a pattern.
250
251 Advanced Features for Reference to Variables
252
253 * Substitution Refs:: Referencing a variable with
254 substitutions on the value.
255 * Computed Names:: Computing the name of the variable to refer to.
256
257 Conditional Parts of Makefiles
258
259 * Conditional Example:: Example of a conditional
260 * Conditional Syntax:: The syntax of conditionals.
261 * Testing Flags:: Conditionals that test flags.
262
263 Functions for Transforming Text
264
265 * Syntax of Functions:: How to write a function call.
266 * Text Functions:: General-purpose text manipulation functions.
267 * File Name Functions:: Functions for manipulating file names.
268 * Foreach Function:: Repeat some text with controlled variation.
269 * If Function:: Conditionally expand a value.
270 * Call Function:: Expand a user-defined function.
271 * Value Function:: Return the un-expanded value of a variable.
272 * Eval Function:: Evaluate the arguments as makefile syntax.
273 * Origin Function:: Find where a variable got its value.
274 * Shell Function:: Substitute the output of a shell command.
275 * Make Control Functions:: Functions that control how make runs.
276
277 How to Run @code{make}
278
279 * Makefile Arguments:: How to specify which makefile to use.
280 * Goals:: How to use goal arguments to specify which
281 parts of the makefile to use.
282 * Instead of Execution:: How to use mode flags to specify what
283 kind of thing to do with the commands
284 in the makefile other than simply
285 execute them.
286 * Avoiding Compilation:: How to avoid recompiling certain files.
287 * Overriding:: How to override a variable to specify
288 an alternate compiler and other things.
289 * Testing:: How to proceed past some errors, to
290 test compilation.
291 * Options Summary:: Summary of Options
292
293 Using Implicit Rules
294
295 * Using Implicit:: How to use an existing implicit rule
296 to get the commands for updating a file.
297 * Catalogue of Rules:: A list of built-in implicit rules.
298 * Implicit Variables:: How to change what predefined rules do.
299 * Chained Rules:: How to use a chain of implicit rules.
300 * Pattern Rules:: How to define new implicit rules.
301 * Last Resort:: How to defining commands for rules
302 which cannot find any.
303 * Suffix Rules:: The old-fashioned style of implicit rule.
304 * Implicit Rule Search:: The precise algorithm for applying
305 implicit rules.
306
307 Defining and Redefining Pattern Rules
308
309 * Pattern Intro:: An introduction to pattern rules.
310 * Pattern Examples:: Examples of pattern rules.
311 * Automatic Variables:: How to use automatic variables in the
312 commands of implicit rules.
313 * Pattern Match:: How patterns match.
314 * Match-Anything Rules:: Precautions you should take prior to
315 defining rules that can match any
316 target file whatever.
317 * Canceling Rules:: How to override or cancel built-in rules.
318
319 Using @code{make} to Update Archive Files
320
321 * Archive Members:: Archive members as targets.
322 * Archive Update:: The implicit rule for archive member targets.
323 * Archive Pitfalls:: Dangers to watch out for when using archives.
324 * Archive Suffix Rules:: You can write a special kind of suffix rule
325 for updating archives.
326
327 Implicit Rule for Archive Member Targets
328
329 * Archive Symbols:: How to update archive symbol directories.
330
331 Makefile Conventions
332
333 * Makefile Basics:: General Conventions for Makefiles
334 * Utilities in Makefiles:: Utilities in Makefiles
335 * Command Variables:: Variables for Specifying Commands
336 * Directory Variables:: Variables for Installation Directories
337 * Standard Targets:: Standard Targets for Users
338 * Install Command Categories:: Three categories of commands in the `install'
339
340 Copying This Manual
341
342 @end detailmenu
343 @end menu
344
345 @node Overview, Introduction, Top, Top
346 @comment node-name, next, previous, up
347 @chapter Overview of @code{make}
348
349 The @code{make} utility automatically determines which pieces of a large
350 program need to be recompiled, and issues commands to recompile them.
351 This manual describes GNU @code{make}, which was implemented by Richard
352 Stallman and Roland McGrath. Development since Version 3.76 has been
353 handled by Paul Smith.
354
355 GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard
356 1003.2-1992} (POSIX.2).
357 @cindex POSIX
358 @cindex IEEE Standard 1003.2
359 @cindex standards conformance
360
361 Our examples show C programs, since they are most common, but you can use
362 @code{make} with any programming language whose compiler can be run with a
363 shell command. Indeed, @code{make} is not limited to programs. You can
364 use it to describe any task where some files must be updated automatically
365 from others whenever the others change.
366
367 @menu
368 * Preparing:: Preparing and Running Make
369 * Reading:: On Reading this Text
370 * Bugs:: Problems and Bugs
371 @end menu
372
373 @node Preparing, Reading, Overview, Overview
374 @ifinfo
375 @heading Preparing and Running Make
376 @end ifinfo
377
378 To prepare to use @code{make}, you must write a file called
379 the @dfn{makefile} that describes the relationships among files
380 in your program and provides commands for updating each file.
381 In a program, typically, the executable file is updated from object
382 files, which are in turn made by compiling source files.@refill
383
384 Once a suitable makefile exists, each time you change some source files,
385 this simple shell command:
386
387 @example
388 make
389 @end example
390
391 @noindent
392 suffices to perform all necessary recompilations. The @code{make} program
393 uses the makefile data base and the last-modification times of the files to
394 decide which of the files need to be updated. For each of those files, it
395 issues the commands recorded in the data base.
396
397 You can provide command line arguments to @code{make} to control which
398 files should be recompiled, or how. @xref{Running, ,How to Run
399 @code{make}}.
400
401 @node Reading, Bugs, Preparing, Overview
402 @section How to Read This Manual
403
404 If you are new to @code{make}, or are looking for a general
405 introduction, read the first few sections of each chapter, skipping the
406 later sections. In each chapter, the first few sections contain
407 introductory or general information and the later sections contain
408 specialized or technical information.
409 @ifinfo
410 The exception is the second chapter, @ref{Introduction, ,An
411 Introduction to Makefiles}, all of which is introductory.
412 @end ifinfo
413 @iftex
414 The exception is @ref{Introduction, ,An Introduction to Makefiles},
415 all of which is introductory.
416 @end iftex
417
418 If you are familiar with other @code{make} programs, see @ref{Features,
419 ,Features of GNU @code{make}}, which lists the enhancements GNU
420 @code{make} has, and @ref{Missing, ,Incompatibilities and Missing
421 Features}, which explains the few things GNU @code{make} lacks that
422 others have.
423
424 For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
425 and @ref{Special Targets}.
426
427 @node Bugs, , Reading, Overview
428 @section Problems and Bugs
429 @cindex reporting bugs
430 @cindex bugs, reporting
431 @cindex problems and bugs, reporting
432
433 If you have problems with GNU @code{make} or think you've found a bug,
434 please report it to the developers; we cannot promise to do anything but
435 we might well want to fix it.
436
437 Before reporting a bug, make sure you've actually found a real bug.
438 Carefully reread the documentation and see if it really says you can do
439 what you're trying to do. If it's not clear whether you should be able
440 to do something or not, report that too; it's a bug in the
441 documentation!
442
443 Before reporting a bug or trying to fix it yourself, try to isolate it
444 to the smallest possible makefile that reproduces the problem. Then
445 send us the makefile and the exact results @code{make} gave you,
446 including any error or warning messages. Please don't paraphrase
447 these messages: it's best to cut and paste them into your report.
448 When generating this small makefile, be sure to not use any non-free
449 or unusual tools in your commands: you can almost always emulate what
450 such a tool would do with simple shell commands. Finally, be sure to
451 explain what you expected to occur; this will help us decide whether
452 the problem was really in the documentation.
453
454 Once you have a precise problem you can report it in one of two ways.
455 Either send electronic mail to:
456
457 @example
458 bug-make@@gnu.org
459 @end example
460
461 @noindent
462 or use our Web-based project management tool, at:
463
464 @example
465 http://savannah.gnu.org/projects/make/
466 @end example
467
468 @noindent
469 In addition to the information above, please be careful to include the
470 version number of @code{make} you are using. You can get this
471 information with the command @samp{make --version}. Be sure also to
472 include the type of machine and operating system you are using. One
473 way to obtain this information is by looking at the final lines of
474 output from the command @samp{make --help}.
475
476 @node Introduction, Makefiles, Overview, Top
477 @comment node-name, next, previous, up
478 @chapter An Introduction to Makefiles
479
480 You need a file called a @dfn{makefile} to tell @code{make} what to do.
481 Most often, the makefile tells @code{make} how to compile and link a
482 program.
483 @cindex makefile
484
485 In this chapter, we will discuss a simple makefile that describes how to
486 compile and link a text editor which consists of eight C source files
487 and three header files. The makefile can also tell @code{make} how to
488 run miscellaneous commands when explicitly asked (for example, to remove
489 certain files as a clean-up operation). To see a more complex example
490 of a makefile, see @ref{Complex Makefile}.
491
492 When @code{make} recompiles the editor, each changed C source file
493 must be recompiled. If a header file has changed, each C source file
494 that includes the header file must be recompiled to be safe. Each
495 compilation produces an object file corresponding to the source file.
496 Finally, if any source file has been recompiled, all the object files,
497 whether newly made or saved from previous compilations, must be linked
498 together to produce the new executable editor.
499 @cindex recompilation
500 @cindex editor
501
502 @menu
503 * Rule Introduction:: What a rule looks like.
504 * Simple Makefile:: A Simple Makefile
505 * How Make Works:: How @code{make} Processes This Makefile
506 * Variables Simplify:: Variables Make Makefiles Simpler
507 * make Deduces:: Letting @code{make} Deduce the Commands
508 * Combine By Prerequisite:: Another Style of Makefile
509 * Cleanup:: Rules for Cleaning the Directory
510 @end menu
511
512 @node Rule Introduction, Simple Makefile, Introduction, Introduction
513 @comment node-name, next, previous, up
514 @section What a Rule Looks Like
515 @cindex rule, introduction to
516 @cindex makefile rule parts
517 @cindex parts of makefile rule
518
519 A simple makefile consists of ``rules'' with the following shape:
520
521 @cindex targets, introduction to
522 @cindex prerequisites, introduction to
523 @cindex commands, introduction to
524 @example
525 @group
526 @var{target} @dots{} : @var{prerequisites} @dots{}
527 @var{command}
528 @dots{}
529 @dots{}
530 @end group
531 @end example
532
533 A @dfn{target} is usually the name of a file that is generated by a
534 program; examples of targets are executable or object files. A target
535 can also be the name of an action to carry out, such as @samp{clean}
536 (@pxref{Phony Targets}).
537
538 A @dfn{prerequisite} is a file that is used as input to create the
539 target. A target often depends on several files.
540
541 @cindex tabs in rules
542 A @dfn{command} is an action that @code{make} carries out.
543 A rule may have more than one command, each on its own line.
544 @strong{Please note:} you need to put a tab character at the beginning of
545 every command line! This is an obscurity that catches the unwary.
546
547 Usually a command is in a rule with prerequisites and serves to create a
548 target file if any of the prerequisites change. However, the rule that
549 specifies commands for the target need not have prerequisites. For
550 example, the rule containing the delete command associated with the
551 target @samp{clean} does not have prerequisites.
552
553 A @dfn{rule}, then, explains how and when to remake certain files
554 which are the targets of the particular rule. @code{make} carries out
555 the commands on the prerequisites to create or update the target. A
556 rule can also explain how and when to carry out an action.
557 @xref{Rules, , Writing Rules}.
558
559 A makefile may contain other text besides rules, but a simple makefile
560 need only contain rules. Rules may look somewhat more complicated
561 than shown in this template, but all fit the pattern more or less.
562
563 @node Simple Makefile, How Make Works, Rule Introduction, Introduction
564 @section A Simple Makefile
565 @cindex simple makefile
566 @cindex makefile, simple
567
568 Here is a straightforward makefile that describes the way an
569 executable file called @code{edit} depends on eight object files
570 which, in turn, depend on eight C source and three header files.
571
572 In this example, all the C files include @file{defs.h}, but only those
573 defining editing commands include @file{command.h}, and only low
574 level files that change the editor buffer include @file{buffer.h}.
575
576 @example
577 @group
578 edit : main.o kbd.o command.o display.o \
579 insert.o search.o files.o utils.o
580 cc -o edit main.o kbd.o command.o display.o \
581 insert.o search.o files.o utils.o
582
583 main.o : main.c defs.h
584 cc -c main.c
585 kbd.o : kbd.c defs.h command.h
586 cc -c kbd.c
587 command.o : command.c defs.h command.h
588 cc -c command.c
589 display.o : display.c defs.h buffer.h
590 cc -c display.c
591 insert.o : insert.c defs.h buffer.h
592 cc -c insert.c
593 search.o : search.c defs.h buffer.h
594 cc -c search.c
595 files.o : files.c defs.h buffer.h command.h
596 cc -c files.c
597 utils.o : utils.c defs.h
598 cc -c utils.c
599 clean :
600 rm edit main.o kbd.o command.o display.o \
601 insert.o search.o files.o utils.o
602 @end group
603 @end example
604
605 @noindent
606 We split each long line into two lines using backslash-newline; this is
607 like using one long line, but is easier to read.
608 @cindex continuation lines
609 @cindex @code{\} (backslash), for continuation lines
610 @cindex backslash (@code{\}), for continuation lines
611 @cindex quoting newline, in makefile
612 @cindex newline, quoting, in makefile
613
614 To use this makefile to create the executable file called @file{edit},
615 type:
616
617 @example
618 make
619 @end example
620
621 To use this makefile to delete the executable file and all the object
622 files from the directory, type:
623
624 @example
625 make clean
626 @end example
627
628 In the example makefile, the targets include the executable file
629 @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
630 prerequisites are files such as @samp{main.c} and @samp{defs.h}.
631 In fact, each @samp{.o} file is both a target and a prerequisite.
632 Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
633
634 When a target is a file, it needs to be recompiled or relinked if any
635 of its prerequisites change. In addition, any prerequisites that are
636 themselves automatically generated should be updated first. In this
637 example, @file{edit} depends on each of the eight object files; the
638 object file @file{main.o} depends on the source file @file{main.c} and
639 on the header file @file{defs.h}.
640
641 A shell command follows each line that contains a target and
642 prerequisites. These shell commands say how to update the target file.
643 A tab character must come at the beginning of every command line to
644 distinguish commands lines from other lines in the makefile. (Bear in
645 mind that @code{make} does not know anything about how the commands
646 work. It is up to you to supply commands that will update the target
647 file properly. All @code{make} does is execute the commands in the rule
648 you have specified when the target file needs to be updated.)
649 @cindex shell command
650
651 The target @samp{clean} is not a file, but merely the name of an
652 action. Since you
653 normally
654 do not want to carry out the actions in this rule, @samp{clean} is not a prerequisite of any other rule.
655 Consequently, @code{make} never does anything with it unless you tell
656 it specifically. Note that this rule not only is not a prerequisite, it
657 also does not have any prerequisites, so the only purpose of the rule
658 is to run the specified commands. Targets that do not refer to files
659 but are just actions are called @dfn{phony targets}. @xref{Phony
660 Targets}, for information about this kind of target. @xref{Errors, ,
661 Errors in Commands}, to see how to cause @code{make} to ignore errors
662 from @code{rm} or any other command.
663 @cindex @code{clean} target
664 @cindex @code{rm} (shell command)
665
666 @node How Make Works, Variables Simplify, Simple Makefile, Introduction
667 @comment node-name, next, previous, up
668 @section How @code{make} Processes a Makefile
669 @cindex processing a makefile
670 @cindex makefile, how @code{make} processes
671
672 By default, @code{make} starts with the first target (not targets whose
673 names start with @samp{.}). This is called the @dfn{default goal}.
674 (@dfn{Goals} are the targets that @code{make} strives ultimately to
675 update. @xref{Goals, , Arguments to Specify the Goals}.)
676 @cindex default goal
677 @cindex goal, default
678 @cindex goal
679
680 In the simple example of the previous section, the default goal is to
681 update the executable program @file{edit}; therefore, we put that rule
682 first.
683
684 Thus, when you give the command:
685
686 @example
687 make
688 @end example
689
690 @noindent
691 @code{make} reads the makefile in the current directory and begins by
692 processing the first rule. In the example, this rule is for relinking
693 @file{edit}; but before @code{make} can fully process this rule, it
694 must process the rules for the files that @file{edit} depends on,
695 which in this case are the object files. Each of these files is
696 processed according to its own rule. These rules say to update each
697 @samp{.o} file by compiling its source file. The recompilation must
698 be done if the source file, or any of the header files named as
699 prerequisites, is more recent than the object file, or if the object
700 file does not exist.
701
702 The other rules are processed because their targets appear as
703 prerequisites of the goal. If some other rule is not depended on by the
704 goal (or anything it depends on, etc.), that rule is not processed,
705 unless you tell @code{make} to do so (with a command such as
706 @w{@code{make clean}}).
707
708 Before recompiling an object file, @code{make} considers updating its
709 prerequisites, the source file and header files. This makefile does not
710 specify anything to be done for them---the @samp{.c} and @samp{.h} files
711 are not the targets of any rules---so @code{make} does nothing for these
712 files. But @code{make} would update automatically generated C programs,
713 such as those made by Bison or Yacc, by their own rules at this time.
714
715 After recompiling whichever object files need it, @code{make} decides
716 whether to relink @file{edit}. This must be done if the file
717 @file{edit} does not exist, or if any of the object files are newer than
718 it. If an object file was just recompiled, it is now newer than
719 @file{edit}, so @file{edit} is relinked.
720 @cindex relinking
721
722 Thus, if we change the file @file{insert.c} and run @code{make},
723 @code{make} will compile that file to update @file{insert.o}, and then
724 link @file{edit}. If we change the file @file{command.h} and run
725 @code{make}, @code{make} will recompile the object files @file{kbd.o},
726 @file{command.o} and @file{files.o} and then link the file @file{edit}.
727
728 @node Variables Simplify, make Deduces, How Make Works, Introduction
729 @section Variables Make Makefiles Simpler
730 @cindex variables
731 @cindex simplifying with variables
732
733 In our example, we had to list all the object files twice in the rule for
734 @file{edit} (repeated here):
735
736 @example
737 @group
738 edit : main.o kbd.o command.o display.o \
739 insert.o search.o files.o utils.o
740 cc -o edit main.o kbd.o command.o display.o \
741 insert.o search.o files.o utils.o
742 @end group
743 @end example
744
745 @cindex @code{objects}
746 Such duplication is error-prone; if a new object file is added to the
747 system, we might add it to one list and forget the other. We can eliminate
748 the risk and simplify the makefile by using a variable. @dfn{Variables}
749 allow a text string to be defined once and substituted in multiple places
750 later (@pxref{Using Variables, ,How to Use Variables}).
751
752 @cindex @code{OBJECTS}
753 @cindex @code{objs}
754 @cindex @code{OBJS}
755 @cindex @code{obj}
756 @cindex @code{OBJ}
757 It is standard practice for every makefile to have a variable named
758 @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
759 or @code{OBJ} which is a list of all object file names. We would
760 define such a variable @code{objects} with a line like this in the
761 makefile:@refill
762
763 @example
764 @group
765 objects = main.o kbd.o command.o display.o \
766 insert.o search.o files.o utils.o
767 @end group
768 @end example
769
770 @noindent
771 Then, each place we want to put a list of the object file names, we can
772 substitute the variable's value by writing @samp{$(objects)}
773 (@pxref{Using Variables, ,How to Use Variables}).
774
775 Here is how the complete simple makefile looks when you use a variable
776 for the object files:
777
778 @example
779 @group
780 objects = main.o kbd.o command.o display.o \
781 insert.o search.o files.o utils.o
782
783 edit : $(objects)
784 cc -o edit $(objects)
785 main.o : main.c defs.h
786 cc -c main.c
787 kbd.o : kbd.c defs.h command.h
788 cc -c kbd.c
789 command.o : command.c defs.h command.h
790 cc -c command.c
791 display.o : display.c defs.h buffer.h
792 cc -c display.c
793 insert.o : insert.c defs.h buffer.h
794 cc -c insert.c
795 search.o : search.c defs.h buffer.h
796 cc -c search.c
797 files.o : files.c defs.h buffer.h command.h
798 cc -c files.c
799 utils.o : utils.c defs.h
800 cc -c utils.c
801 clean :
802 rm edit $(objects)
803 @end group
804 @end example
805
806 @node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction
807 @section Letting @code{make} Deduce the Commands
808 @cindex deducing commands (implicit rules)
809 @cindex implicit rule, introduction to
810 @cindex rule, implicit, introduction to
811
812 It is not necessary to spell out the commands for compiling the individual
813 C source files, because @code{make} can figure them out: it has an
814 @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
815 named @samp{.c} file using a @samp{cc -c} command. For example, it will
816 use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into
817 @file{main.o}. We can therefore omit the commands from the rules for the
818 object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill
819
820 When a @samp{.c} file is used automatically in this way, it is also
821 automatically added to the list of prerequisites. We can therefore omit
822 the @samp{.c} files from the prerequisites, provided we omit the commands.
823
824 Here is the entire example, with both of these changes, and a variable
825 @code{objects} as suggested above:
826
827 @example
828 @group
829 objects = main.o kbd.o command.o display.o \
830 insert.o search.o files.o utils.o
831
832 edit : $(objects)
833 cc -o edit $(objects)
834
835 main.o : defs.h
836 kbd.o : defs.h command.h
837 command.o : defs.h command.h
838 display.o : defs.h buffer.h
839 insert.o : defs.h buffer.h
840 search.o : defs.h buffer.h
841 files.o : defs.h buffer.h command.h
842 utils.o : defs.h
843
844 .PHONY : clean
845 clean :
846 rm edit $(objects)
847 @end group
848 @end example
849
850 @noindent
851 This is how we would write the makefile in actual practice. (The
852 complications associated with @samp{clean} are described elsewhere.
853 See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.)
854
855 Because implicit rules are so convenient, they are important. You
856 will see them used frequently.@refill
857
858 @node Combine By Prerequisite, Cleanup, make Deduces, Introduction
859 @section Another Style of Makefile
860 @cindex combining rules by prerequisite
861
862 When the objects of a makefile are created only by implicit rules, an
863 alternative style of makefile is possible. In this style of makefile,
864 you group entries by their prerequisites instead of by their targets.
865 Here is what one looks like:
866
867 @example
868 @group
869 objects = main.o kbd.o command.o display.o \
870 insert.o search.o files.o utils.o
871
872 edit : $(objects)
873 cc -o edit $(objects)
874
875 $(objects) : defs.h
876 kbd.o command.o files.o : command.h
877 display.o insert.o search.o files.o : buffer.h
878 @end group
879 @end example
880
881 @noindent
882 Here @file{defs.h} is given as a prerequisite of all the object files;
883 @file{command.h} and @file{buffer.h} are prerequisites of the specific
884 object files listed for them.
885
886 Whether this is better is a matter of taste: it is more compact, but some
887 people dislike it because they find it clearer to put all the information
888 about each target in one place.
889
890 @node Cleanup, , Combine By Prerequisite, Introduction
891 @section Rules for Cleaning the Directory
892 @cindex cleaning up
893 @cindex removing, to clean up
894
895 Compiling a program is not the only thing you might want to write rules
896 for. Makefiles commonly tell how to do a few other things besides
897 compiling a program: for example, how to delete all the object files
898 and executables so that the directory is @samp{clean}.
899
900 @cindex @code{clean} target
901 Here is how we
902 could write a @code{make} rule for cleaning our example editor:
903
904 @example
905 @group
906 clean:
907 rm edit $(objects)
908 @end group
909 @end example
910
911 In practice, we might want to write the rule in a somewhat more
912 complicated manner to handle unanticipated situations. We would do this:
913
914 @example
915 @group
916 .PHONY : clean
917 clean :
918 -rm edit $(objects)
919 @end group
920 @end example
921
922 @noindent
923 This prevents @code{make} from getting confused by an actual file
924 called @file{clean} and causes it to continue in spite of errors from
925 @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
926 Commands}.)
927
928 @noindent
929 A rule such as this should not be placed at the beginning of the
930 makefile, because we do not want it to run by default! Thus, in the
931 example makefile, we want the rule for @code{edit}, which recompiles
932 the editor, to remain the default goal.
933
934 Since @code{clean} is not a prerequisite of @code{edit}, this rule will not
935 run at all if we give the command @samp{make} with no arguments. In
936 order to make the rule run, we have to type @samp{make clean}.
937 @xref{Running, ,How to Run @code{make}}.
938
939 @node Makefiles, Rules, Introduction, Top
940 @chapter Writing Makefiles
941
942 @cindex makefile, how to write
943 The information that tells @code{make} how to recompile a system comes from
944 reading a data base called the @dfn{makefile}.
945
946 @menu
947 * Makefile Contents:: What makefiles contain.
948 * Makefile Names:: How to name your makefile.
949 * Include:: How one makefile can use another makefile.
950 * MAKEFILES Variable:: The environment can specify extra makefiles.
951 * MAKEFILE_LIST Variable:: Discover which makefiles have been read.
952 * Special Variables:: Other special variables.
953 * Remaking Makefiles:: How makefiles get remade.
954 * Overriding Makefiles:: How to override part of one makefile
955 with another makefile.
956 * Reading Makefiles:: How makefiles are parsed.
957 @end menu
958
959 @node Makefile Contents, Makefile Names, Makefiles, Makefiles
960 @section What Makefiles Contain
961
962 Makefiles contain five kinds of things: @dfn{explicit rules},
963 @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
964 and @dfn{comments}. Rules, variables, and directives are described at
965 length in later chapters.@refill
966
967 @itemize @bullet
968 @cindex rule, explicit, definition of
969 @cindex explicit rule, definition of
970 @item
971 An @dfn{explicit rule} says when and how to remake one or more files,
972 called the rule's @dfn{targets}. It lists the other files that the
973 targets depend on, called the @dfn{prerequisites} of the target, and
974 may also give commands to use to create or update the targets.
975 @xref{Rules, ,Writing Rules}.
976
977 @cindex rule, implicit, definition of
978 @cindex implicit rule, definition of
979 @item
980 An @dfn{implicit rule} says when and how to remake a class of files
981 based on their names. It describes how a target may depend on a file
982 with a name similar to the target and gives commands to create or
983 update such a target. @xref{Implicit Rules, ,Using Implicit Rules}.
984
985 @cindex variable definition
986 @item
987 A @dfn{variable definition} is a line that specifies a text string
988 value for a variable that can be substituted into the text later. The
989 simple makefile example shows a variable definition for @code{objects}
990 as a list of all object files (@pxref{Variables Simplify, , Variables
991 Make Makefiles Simpler}).
992
993 @cindex directive
994 @item
995 A @dfn{directive} is a command for @code{make} to do something special while
996 reading the makefile. These include:
997
998 @itemize @bullet
999 @item
1000 Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
1001
1002 @item
1003 Deciding (based on the values of variables) whether to use or
1004 ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
1005
1006 @item
1007 Defining a variable from a verbatim string containing multiple lines
1008 (@pxref{Defining, ,Defining Variables Verbatim}).
1009 @end itemize
1010
1011 @cindex comments, in makefile
1012 @cindex @code{#} (comments), in makefile
1013 @item
1014 @samp{#} in a line of a makefile starts a @dfn{comment}. It and the
1015 rest of the line are ignored, except that a trailing backslash not
1016 escaped by another backslash will continue the comment across multiple
1017 lines. A line containing just a comment (with perhaps spaces before
1018 it) is effectively blank, and is ignored. If you want a literal
1019 @code{#}, escape it with a backslash (e.g., @code{\#}). Comments may
1020 appear on any line in the makefile, although they are treated
1021 specially in certain situations.
1022
1023 Within a command script (if the line begins with a TAB character) the
1024 entire line is passed to the shell, just as with any other line that
1025 begins with a TAB. The shell decides how to interpret the text:
1026 whether or not this is a comment is up to the shell.
1027
1028 Within a @code{define} directive, comments are not ignored during the
1029 definition of the variable, but rather kept intact in the value of the
1030 variable. When the variable is expanded they will either be treated
1031 as @code{make} comments or as command script text, depending on the
1032 context in which the variable is evaluated.
1033 @end itemize
1034
1035 @node Makefile Names, Include, Makefile Contents, Makefiles
1036 @section What Name to Give Your Makefile
1037 @cindex makefile name
1038 @cindex name of makefile
1039 @cindex default makefile name
1040 @cindex file name of makefile
1041
1042 @c following paragraph rewritten to avoid overfull hbox
1043 By default, when @code{make} looks for the makefile, it tries the
1044 following names, in order: @file{GNUmakefile}, @file{makefile}
1045 and @file{Makefile}.@refill
1046 @findex Makefile
1047 @findex GNUmakefile
1048 @findex makefile
1049
1050 @cindex @code{README}
1051 Normally you should call your makefile either @file{makefile} or
1052 @file{Makefile}. (We recommend @file{Makefile} because it appears
1053 prominently near the beginning of a directory listing, right near other
1054 important files such as @file{README}.) The first name checked,
1055 @file{GNUmakefile}, is not recommended for most makefiles. You should
1056 use this name if you have a makefile that is specific to GNU
1057 @code{make}, and will not be understood by other versions of
1058 @code{make}. Other @code{make} programs look for @file{makefile} and
1059 @file{Makefile}, but not @file{GNUmakefile}.
1060
1061 If @code{make} finds none of these names, it does not use any makefile.
1062 Then you must specify a goal with a command argument, and @code{make}
1063 will attempt to figure out how to remake it using only its built-in
1064 implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}.
1065
1066 @cindex @code{-f}
1067 @cindex @code{--file}
1068 @cindex @code{--makefile}
1069 If you want to use a nonstandard name for your makefile, you can specify
1070 the makefile name with the @samp{-f} or @samp{--file} option. The
1071 arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
1072 @code{make} to read the file @var{name} as the makefile. If you use
1073 more than one @samp{-f} or @samp{--file} option, you can specify several
1074 makefiles. All the makefiles are effectively concatenated in the order
1075 specified. The default makefile names @file{GNUmakefile},
1076 @file{makefile} and @file{Makefile} are not checked automatically if you
1077 specify @samp{-f} or @samp{--file}.@refill
1078 @cindex specifying makefile name
1079 @cindex makefile name, how to specify
1080 @cindex name of makefile, how to specify
1081 @cindex file name of makefile, how to specify
1082
1083 @node Include, MAKEFILES Variable, Makefile Names, Makefiles
1084 @section Including Other Makefiles
1085 @cindex including other makefiles
1086 @cindex makefile, including
1087
1088 @findex include
1089 The @code{include} directive tells @code{make} to suspend reading the
1090 current makefile and read one or more other makefiles before continuing.
1091 The directive is a line in the makefile that looks like this:
1092
1093 @example
1094 include @var{filenames}@dots{}
1095 @end example
1096
1097 @noindent
1098 @var{filenames} can contain shell file name patterns.
1099 @cindex shell file name pattern (in @code{include})
1100 @cindex shell wildcards (in @code{include})
1101 @cindex wildcard, in @code{include}
1102
1103 Extra spaces are allowed and ignored at the beginning of the line, but
1104 a tab is not allowed. (If the line begins with a tab, it will be
1105 considered a command line.) Whitespace is required between
1106 @code{include} and the file names, and between file names; extra
1107 whitespace is ignored there and at the end of the directive. A
1108 comment starting with @samp{#} is allowed at the end of the line. If
1109 the file names contain any variable or function references, they are
1110 expanded. @xref{Using Variables, ,How to Use Variables}.
1111
1112 For example, if you have three @file{.mk} files, @file{a.mk},
1113 @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
1114 @code{bish bash}, then the following expression
1115
1116 @example
1117 include foo *.mk $(bar)
1118 @end example
1119
1120 is equivalent to
1121
1122 @example
1123 include foo a.mk b.mk c.mk bish bash
1124 @end example
1125
1126 When @code{make} processes an @code{include} directive, it suspends
1127 reading of the containing makefile and reads from each listed file in
1128 turn. When that is finished, @code{make} resumes reading the
1129 makefile in which the directive appears.
1130
1131 One occasion for using @code{include} directives is when several programs,
1132 handled by individual makefiles in various directories, need to use a
1133 common set of variable definitions
1134 (@pxref{Setting, ,Setting Variables}) or pattern rules
1135 (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
1136
1137 Another such occasion is when you want to generate prerequisites from
1138 source files automatically; the prerequisites can be put in a file that
1139 is included by the main makefile. This practice is generally cleaner
1140 than that of somehow appending the prerequisites to the end of the main
1141 makefile as has been traditionally done with other versions of
1142 @code{make}. @xref{Automatic Prerequisites}.
1143 @cindex prerequisites, automatic generation
1144 @cindex automatic generation of prerequisites
1145 @cindex generating prerequisites automatically
1146
1147 @cindex @code{-I}
1148 @cindex @code{--include-dir}
1149 @cindex included makefiles, default directories
1150 @cindex default directories for included makefiles
1151 @findex /usr/gnu/include
1152 @findex /usr/local/include
1153 @findex /usr/include
1154 If the specified name does not start with a slash, and the file is not
1155 found in the current directory, several other directories are searched.
1156 First, any directories you have specified with the @samp{-I} or
1157 @samp{--include-dir} option are searched
1158 (@pxref{Options Summary, ,Summary of Options}).
1159 Then the following directories (if they exist)
1160 are searched, in this order:
1161 @file{@var{prefix}/include} (normally @file{/usr/local/include}
1162 @footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if
1163 @var{prefix} has been defined to be the root of the DJGPP tree
1164 hierarchy.})
1165 @file{/usr/gnu/include},
1166 @file{/usr/local/include}, @file{/usr/include}.
1167
1168 If an included makefile cannot be found in any of these directories, a
1169 warning message is generated, but it is not an immediately fatal error;
1170 processing of the makefile containing the @code{include} continues.
1171 Once it has finished reading makefiles, @code{make} will try to remake
1172 any that are out of date or don't exist.
1173 @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
1174 Only after it has tried to find a way to remake a makefile and failed,
1175 will @code{make} diagnose the missing makefile as a fatal error.
1176
1177 If you want @code{make} to simply ignore a makefile which does not exist
1178 and cannot be remade, with no error message, use the @w{@code{-include}}
1179 directive instead of @code{include}, like this:
1180
1181 @example
1182 -include @var{filenames}@dots{}
1183 @end example
1184
1185 This acts like @code{include} in every way except that there is no
1186 error (not even a warning) if any of the @var{filenames} do not exist.
1187 For compatibility with some other @code{make} implementations,
1188 @code{sinclude} is another name for @w{@code{-include}}.
1189
1190 @node MAKEFILES Variable, MAKEFILE_LIST Variable, Include, Makefiles
1191 @section The Variable @code{MAKEFILES}
1192 @cindex makefile, and @code{MAKEFILES} variable
1193 @cindex including (@code{MAKEFILES} variable)
1194
1195 @vindex MAKEFILES
1196 If the environment variable @code{MAKEFILES} is defined, @code{make}
1197 considers its value as a list of names (separated by whitespace) of
1198 additional makefiles to be read before the others. This works much like
1199 the @code{include} directive: various directories are searched for those
1200 files (@pxref{Include, ,Including Other Makefiles}). In addition, the
1201 default goal is never taken from one of these makefiles and it is not an
1202 error if the files listed in @code{MAKEFILES} are not found.@refill
1203
1204 @cindex recursion, and @code{MAKEFILES} variable
1205 The main use of @code{MAKEFILES} is in communication between recursive
1206 invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
1207 @code{make}}). It usually is not desirable to set the environment
1208 variable before a top-level invocation of @code{make}, because it is
1209 usually better not to mess with a makefile from outside. However, if
1210 you are running @code{make} without a specific makefile, a makefile in
1211 @code{MAKEFILES} can do useful things to help the built-in implicit
1212 rules work better, such as defining search paths (@pxref{Directory Search}).
1213
1214 Some users are tempted to set @code{MAKEFILES} in the environment
1215 automatically on login, and program makefiles to expect this to be done.
1216 This is a very bad idea, because such makefiles will fail to work if run by
1217 anyone else. It is much better to write explicit @code{include} directives
1218 in the makefiles. @xref{Include, , Including Other Makefiles}.
1219
1220 @node MAKEFILE_LIST Variable, Special Variables, MAKEFILES Variable, Makefiles
1221 @comment node-name, next, previous, up
1222 @section The Variable @code{MAKEFILE_LIST}
1223 @cindex makefiles, and @code{MAKEFILE_LIST} variable
1224 @cindex including (@code{MAKEFILE_LIST} variable)
1225
1226 As @code{make} reads various makefiles, including any obtained from the
1227 @code{MAKEFILES} variable, the command line, the default files, or
1228 from @code{include} directives, their names will be automatically
1229 appended to the @code{MAKEFILE_LIST} variable. They are added right
1230 before @code{make} begins to parse them.
1231
1232 This means that if the first thing a makefile does is examine the last
1233 word in this variable, it will be the name of the current makefile.
1234 Once the current makefile has used @code{include}, however, the last
1235 word will be the just-included makefile.
1236
1237 If a makefile named @code{Makefile} has this content:
1238
1239 @example
1240 @group
1241 name1 := $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))
1242
1243 include inc.mk
1244
1245 name2 := $(word $(words $(MAKEFILE_LIST)),$(MAKEFILE_LIST))
1246
1247 all:
1248 @@echo name1 = $(name1)
1249 @@echo name2 = $(name2)
1250 @end group
1251 @end example
1252
1253 @noindent
1254 then you would expect to see this output:
1255
1256 @example
1257 @group
1258 name1 = Makefile
1259 name2 = inc.mk
1260 @end group
1261 @end example
1262
1263 @xref{Text Functions}, for more information on the @code{word} and
1264 @code{words} functions used above. @xref{Flavors, The Two Flavors of
1265 Variables}, for more information on simply-expanded (@code{:=})
1266 variable definitions.
1267
1268 @node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles
1269 @comment node-name, next, previous, up
1270 @section Other Special Variables
1271 @cindex makefiles, and special variables
1272 @cindex special variables
1273
1274 GNU @code{make} also supports a special variable. Note that any value
1275 you assign to this variable will be ignored; it will always return its
1276 special value.
1277
1278 @vindex $(.VARIABLES)
1279 @vindex .VARIABLES @r{(list of variables)}
1280 The first special variable is @code{.VARIABLES}. When expanded, the
1281 value consists of a list of the @emph{names} of all global variables
1282 defined in all makefiles read up until that point. This includes
1283 variables which have empty values, as well as built-in variables
1284 (@pxref{Implicit Variables, , Variables Used by Implicit Rules}), but
1285 does not include any variables which are only defined in a
1286 target-specific context.
1287
1288 @c @vindex $(.TARGETS)
1289 @c @vindex .TARGETS @r{(list of targets)}
1290 @c The second special variable is @code{.TARGETS}. When expanded, the
1291 @c value consists of a list of all targets defined in all makefiles read
1292 @c up until that point. Note it's not enough for a file to be simply
1293 @c mentioned in the makefile to be listed in this variable, even if it
1294 @c would match an implicit rule and become an ``implicit target''. The
1295 @c file must appear as a target, on the left-hand side of a ``:'', to be
1296 @c considered a target for the purposes of this variable.
1297
1298 @node Remaking Makefiles, Overriding Makefiles, Special Variables, Makefiles
1299 @section How Makefiles Are Remade
1300
1301 @cindex updating makefiles
1302 @cindex remaking makefiles
1303 @cindex makefile, remaking of
1304 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1305 files. If a makefile can be remade from other files, you probably want
1306 @code{make} to get an up-to-date version of the makefile to read in.
1307
1308 To this end, after reading in all makefiles, @code{make} will consider
1309 each as a goal target and attempt to update it. If a makefile has a
1310 rule which says how to update it (found either in that very makefile or
1311 in another one) or if an implicit rule applies to it (@pxref{Implicit
1312 Rules, ,Using Implicit Rules}), it will be updated if necessary. After
1313 all makefiles have been checked, if any have actually been changed,
1314 @code{make} starts with a clean slate and reads all the makefiles over
1315 again. (It will also attempt to update each of them over again, but
1316 normally this will not change them again, since they are already up to
1317 date.)@refill
1318
1319 If you know that one or more of your makefiles cannot be remade and you
1320 want to keep @code{make} from performing an implicit rule search on
1321 them, perhaps for efficiency reasons, you can use any normal method of
1322 preventing implicit rule lookup to do so. For example, you can write an
1323 explicit rule with the makefile as the target, and an empty command
1324 string (@pxref{Empty Commands, ,Using Empty Commands}).
1325
1326 If the makefiles specify a double-colon rule to remake a file with
1327 commands but no prerequisites, that file will always be remade
1328 (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a
1329 double-colon rule with commands but no prerequisites will be remade every
1330 time @code{make} is run, and then again after @code{make} starts over
1331 and reads the makefiles in again. This would cause an infinite loop:
1332 @code{make} would constantly remake the makefile, and never do anything
1333 else. So, to avoid this, @code{make} will @strong{not} attempt to
1334 remake makefiles which are specified as targets of a double-colon rule
1335 with commands but no prerequisites.@refill
1336
1337 If you do not specify any makefiles to be read with @samp{-f} or
1338 @samp{--file} options, @code{make} will try the default makefile names;
1339 @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike
1340 makefiles explicitly requested with @samp{-f} or @samp{--file} options,
1341 @code{make} is not certain that these makefiles should exist. However,
1342 if a default makefile does not exist but can be created by running
1343 @code{make} rules, you probably want the rules to be run so that the
1344 makefile can be used.
1345
1346 Therefore, if none of the default makefiles exists, @code{make} will try
1347 to make each of them in the same order in which they are searched for
1348 (@pxref{Makefile Names, ,What Name to Give Your Makefile})
1349 until it succeeds in making one, or it runs out of names to try. Note
1350 that it is not an error if @code{make} cannot find or make any makefile;
1351 a makefile is not always necessary.@refill
1352
1353 When you use the @samp{-t} or @samp{--touch} option
1354 (@pxref{Instead of Execution, ,Instead of Executing the Commands}),
1355 you would not want to use an out-of-date makefile to decide which
1356 targets to touch. So the @samp{-t} option has no effect on updating
1357 makefiles; they are really updated even if @samp{-t} is specified.
1358 Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
1359 @samp{--just-print}) do not prevent updating of makefiles, because an
1360 out-of-date makefile would result in the wrong output for other targets.
1361 Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
1362 and then print the commands to update @file{foo} and its prerequisites
1363 without running them. The commands printed for @file{foo} will be those
1364 specified in the updated contents of @file{mfile}.
1365
1366 However, on occasion you might actually wish to prevent updating of even
1367 the makefiles. You can do this by specifying the makefiles as goals in
1368 the command line as well as specifying them as makefiles. When the
1369 makefile name is specified explicitly as a goal, the options @samp{-t}
1370 and so on do apply to them.
1371
1372 Thus, @samp{make -f mfile -n mfile foo} would read the makefile
1373 @file{mfile}, print the commands needed to update it without actually
1374 running them, and then print the commands needed to update @file{foo}
1375 without running them. The commands for @file{foo} will be those
1376 specified by the existing contents of @file{mfile}.
1377
1378 @node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles
1379 @section Overriding Part of Another Makefile
1380
1381 @cindex overriding makefiles
1382 @cindex makefile, overriding
1383 Sometimes it is useful to have a makefile that is mostly just like
1384 another makefile. You can often use the @samp{include} directive to
1385 include one in the other, and add more targets or variable definitions.
1386 However, if the two makefiles give different commands for the same
1387 target, @code{make} will not let you just do this. But there is another way.
1388
1389 @cindex match-anything rule, used to override
1390 In the containing makefile (the one that wants to include the other),
1391 you can use a match-anything pattern rule to say that to remake any
1392 target that cannot be made from the information in the containing
1393 makefile, @code{make} should look in another makefile.
1394 @xref{Pattern Rules}, for more information on pattern rules.
1395
1396 For example, if you have a makefile called @file{Makefile} that says how
1397 to make the target @samp{foo} (and other targets), you can write a
1398 makefile called @file{GNUmakefile} that contains:
1399
1400 @example
1401 foo:
1402 frobnicate > foo
1403
1404 %: force
1405 @@$(MAKE) -f Makefile $@@
1406 force: ;
1407 @end example
1408
1409 If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
1410 read it, and see that to make @file{foo}, it needs to run the command
1411 @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will
1412 find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
1413 commands from the pattern rule: @samp{make -f Makefile bar}. If
1414 @file{Makefile} provides a rule for updating @file{bar}, @code{make}
1415 will apply the rule. And likewise for any other target that
1416 @file{GNUmakefile} does not say how to make.
1417
1418 The way this works is that the pattern rule has a pattern of just
1419 @samp{%}, so it matches any target whatever. The rule specifies a
1420 prerequisite @file{force}, to guarantee that the commands will be run even
1421 if the target file already exists. We give @file{force} target empty
1422 commands to prevent @code{make} from searching for an implicit rule to
1423 build it---otherwise it would apply the same match-anything rule to
1424 @file{force} itself and create a prerequisite loop!
1425
1426 @node Reading Makefiles, , Overriding Makefiles, Makefiles
1427 @section How @code{make} Reads a Makefile
1428 @cindex reading makefiles
1429 @cindex makefile, parsing
1430
1431 GNU @code{make} does its work in two distinct phases. During the first
1432 phase it reads all the makefiles, included makefiles, etc. and
1433 internalizes all the variables and their values, implicit and explicit
1434 rules, and constructs a dependency graph of all the targets and their
1435 prerequisites. During the second phase, @code{make} uses these internal
1436 structures to determine what targets will need to be rebuilt and to
1437 invoke the rules necessary to do so.
1438
1439 It's important to understand this two-phase approach because it has a
1440 direct impact on how variable and function expansion happens; this is
1441 often a source of some confusion when writing makefiles. Here we will
1442 present a summary of the phases in which expansion happens for different
1443 constructs within the makefile. We say that expansion is
1444 @dfn{immediate} if it happens during the first phase: in this case
1445 @code{make} will expand any variables or functions in that section of a
1446 construct as the makefile is parsed. We say that expansion is
1447 @dfn{deferred} if expansion is not performed immediately. Expansion of
1448 deferred construct is not performed until either the construct appears
1449 later in an immediate context, or until the second phase.
1450
1451 You may not be familiar with some of these constructs yet. You can
1452 reference this section as you become familiar with them, in later
1453 chapters.
1454
1455 @subheading Variable Assignment
1456 @cindex +=, expansion
1457 @cindex =, expansion
1458 @cindex ?=, expansion
1459 @cindex +=, expansion
1460 @cindex define, expansion
1461
1462 Variable definitions are parsed as follows:
1463
1464 @example
1465 @var{immediate} = @var{deferred}
1466 @var{immediate} ?= @var{deferred}
1467 @var{immediate} := @var{immediate}
1468 @var{immediate} += @var{deferred} or @var{immediate}
1469
1470 define @var{immediate}
1471 @var{deferred}
1472 endef
1473 @end example
1474
1475 For the append operator, @samp{+=}, the right-hand side is considered
1476 immediate if the variable was previously set as a simple variable
1477 (@samp{:=}), and deferred otherwise.
1478
1479 @subheading Conditional Statements
1480 @cindex ifdef, expansion
1481 @cindex ifeq, expansion
1482 @cindex ifndef, expansion
1483 @cindex ifneq, expansion
1484
1485 All instances of conditional syntax are parsed immediately, in their
1486 entirety; this includes the @code{ifdef}, @code{ifeq}, @code{ifndef},
1487 and @code{ifneq} forms.
1488
1489 @subheading Rule Definition
1490 @cindex target, expansion
1491 @cindex prerequisite, expansion
1492 @cindex implicit rule, expansion
1493 @cindex pattern rule, expansion
1494 @cindex explicit rule, expansion
1495
1496 A rule is always expanded the same way, regardless of the form:
1497
1498 @example
1499 @var{immediate} : @var{immediate} ; @var{deferred}
1500 @var{deferred}
1501 @end example
1502
1503 That is, the target and prerequisite sections are expanded immediately,
1504 and the commands used to construct the target are always deferred. This
1505 general rule is true for explicit rules, pattern rules, suffix rules,
1506 static pattern rules, and simple prerequisite definitions.
1507
1508 @node Rules, Commands, Makefiles, Top
1509 @chapter Writing Rules
1510 @cindex writing rules
1511 @cindex rule, how to write
1512 @cindex target
1513 @cindex prerequisite
1514
1515 A @dfn{rule} appears in the makefile and says when and how to remake
1516 certain files, called the rule's @dfn{targets} (most often only one per rule).
1517 It lists the other files that are the @dfn{prerequisites} of the target, and
1518 @dfn{commands} to use to create or update the target.
1519
1520 @cindex default goal
1521 @cindex goal, default
1522 The order of rules is not significant, except for determining the
1523 @dfn{default goal}: the target for @code{make} to consider, if you do
1524 not otherwise specify one. The default goal is the target of the first
1525 rule in the first makefile. If the first rule has multiple targets,
1526 only the first target is taken as the default. There are two
1527 exceptions: a target starting with a period is not a default unless it
1528 contains one or more slashes, @samp{/}, as well; and, a target that
1529 defines a pattern rule has no effect on the default goal.
1530 (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
1531
1532 Therefore, we usually write the makefile so that the first rule is the
1533 one for compiling the entire program or all the programs described by
1534 the makefile (often with a target called @samp{all}).
1535 @xref{Goals, ,Arguments to Specify the Goals}.
1536
1537 @menu
1538 * Rule Example:: An example explained.
1539 * Rule Syntax:: General syntax explained.
1540 * Prerequisite Types:: There are two types of prerequisites.
1541 * Wildcards:: Using wildcard characters such as `*'.
1542 * Directory Search:: Searching other directories for source files.
1543 * Phony Targets:: Using a target that is not a real file's name.
1544 * Force Targets:: You can use a target without commands
1545 or prerequisites to mark other
1546 targets as phony.
1547 * Empty Targets:: When only the date matters and the
1548 files are empty.
1549 * Special Targets:: Targets with special built-in meanings.
1550 * Multiple Targets:: When to make use of several targets in a rule.
1551 * Multiple Rules:: How to use several rules with the same target.
1552 * Static Pattern:: Static pattern rules apply to multiple targets
1553 and can vary the prerequisites according to
1554 the target name.
1555 * Double-Colon:: How to use a special kind of rule to allow
1556 several independent rules for one target.
1557 * Automatic Prerequisites:: How to automatically generate rules giving
1558 prerequisites from source files themselves.
1559 @end menu
1560
1561 @ifinfo
1562 @node Rule Example, Rule Syntax, Rules, Rules
1563 @section Rule Example
1564
1565 Here is an example of a rule:
1566
1567 @example
1568 foo.o : foo.c defs.h # module for twiddling the frobs
1569 cc -c -g foo.c
1570 @end example
1571
1572 Its target is @file{foo.o} and its prerequisites are @file{foo.c} and
1573 @file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}.
1574 The command line starts with a tab to identify it as a command.
1575
1576 This rule says two things:
1577
1578 @itemize @bullet
1579 @item
1580 How to decide whether @file{foo.o} is out of date: it is out of date
1581 if it does not exist, or if either @file{foo.c} or @file{defs.h} is
1582 more recent than it.
1583
1584 @item
1585 How to update the file @file{foo.o}: by running @code{cc} as stated.
1586 The command does not explicitly mention @file{defs.h}, but we presume
1587 that @file{foo.c} includes it, and that that is why @file{defs.h} was
1588 added to the prerequisites.
1589 @end itemize
1590 @end ifinfo
1591
1592 @node Rule Syntax, Prerequisite Types, Rule Example, Rules
1593 @section Rule Syntax
1594
1595 @cindex rule syntax
1596 @cindex syntax of rules
1597 In general, a rule looks like this:
1598
1599 @example
1600 @var{targets} : @var{prerequisites}
1601 @var{command}
1602 @dots{}
1603 @end example
1604
1605 @noindent
1606 or like this:
1607
1608 @example
1609 @var{targets} : @var{prerequisites} ; @var{command}
1610 @var{command}
1611 @dots{}
1612 @end example
1613
1614 @cindex targets
1615 @cindex rule targets
1616 The @var{targets} are file names, separated by spaces. Wildcard
1617 characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
1618 in File Names}) and a name of the form @file{@var{a}(@var{m})}
1619 represents member @var{m} in archive file @var{a}
1620 (@pxref{Archive Members, ,Archive Members as Targets}).
1621 Usually there is only one
1622 target per rule, but occasionally there is a reason to have more
1623 (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
1624
1625 @cindex commands
1626 @cindex tab character (in commands)
1627 The @var{command} lines start with a tab character. The first command may
1628 appear on the line after the prerequisites, with a tab character, or may
1629 appear on the same line, with a semicolon. Either way, the effect is the
1630 same. @xref{Commands, ,Writing the Commands in Rules}.
1631
1632 @cindex dollar sign (@code{$}), in rules
1633 @cindex @code{$}, in rules
1634 @cindex rule, and @code{$}
1635 Because dollar signs are used to start variable references, if you really
1636 want a dollar sign in a rule you must write two of them, @samp{$$}
1637 (@pxref{Using Variables, ,How to Use Variables}).
1638 You may split a long line by inserting a backslash
1639 followed by a newline, but this is not required, as @code{make} places no
1640 limit on the length of a line in a makefile.
1641
1642 A rule tells @code{make} two things: when the targets are out of date,
1643 and how to update them when necessary.
1644
1645 @cindex prerequisites
1646 @cindex rule prerequisites
1647 The criterion for being out of date is specified in terms of the
1648 @var{prerequisites}, which consist of file names separated by spaces.
1649 (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
1650 A target is out of date if it does not exist or if it is older than any
1651 of the prerequisites (by comparison of last-modification times). The
1652 idea is that the contents of the target file are computed based on
1653 information in the prerequisites, so if any of the prerequisites changes,
1654 the contents of the existing target file are no longer necessarily
1655 valid.
1656
1657 How to update is specified by @var{commands}. These are lines to be
1658 executed by the shell (normally @samp{sh}), but with some extra features
1659 (@pxref{Commands, ,Writing the Commands in Rules}).
1660
1661 @node Prerequisite Types, Wildcards, Rule Syntax, Rules
1662 @comment node-name, next, previous, up
1663 @section Types of Prerequisites
1664 @cindex prerequisite types
1665 @cindex types of prerequisites
1666
1667 @cindex prerequisites, normal
1668 @cindex normal prerequisites
1669 @cindex prerequisites, order-only
1670 @cindex order-only prerequisites
1671 There are actually two different types of prerequisites understood by
1672 GNU @code{make}: normal prerequisites such as described in the
1673 previous section, and @dfn{order-only} prerequisites. A normal
1674 prerequisite makes two statements: first, it imposes an order of
1675 execution of build commands: any commands necessary to build any of a
1676 target's prerequisites will be fully executed before any commands
1677 necessary to build the target. Second, it imposes a dependency
1678 relationship: if any prerequisite is newer than the target, then the
1679 target is considered out-of-date and must be rebuilt.
1680
1681 Normally, this is exactly what you want: if a target's prerequisite is
1682 updated, then the target should also be updated.
1683
1684 Occasionally, however, you have a situation where you want to impose a
1685 specific ordering on the rules to be invoked @emph{without} forcing
1686 the target to be updated if one of those rules is executed. In that
1687 case, you want to define @dfn{order-only} prerequisites. Order-only
1688 prerequisites can be specified by placing a pipe symbol (@code{|})
1689 in the prerequisites list: any prerequisites to the left of the pipe
1690 symbol are normal; any prerequisites to the right are order-only:
1691
1692 @example
1693 @var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites}
1694 @end example
1695
1696 The normal prerequisites section may of course be empty. Also, you
1697 may still declare multiple lines of prerequisites for the same target:
1698 they are appended appropriately. Note that if you declare the same
1699 file to be both a normal and an order-only prerequisite, the normal
1700 prerequisite takes precedence (since they are a strict superset of the
1701 behavior of an order-only prerequisite).
1702
1703 @node Wildcards, Directory Search, Prerequisite Types, Rules
1704 @section Using Wildcard Characters in File Names
1705 @cindex wildcard
1706 @cindex file name with wildcards
1707 @cindex globbing (wildcards)
1708
1709 @cindex @code{*} (wildcard character)
1710 @cindex @code{?} (wildcard character)
1711 @cindex @code{[@dots{}]} (wildcard characters)
1712 A single file name can specify many files using @dfn{wildcard characters}.
1713 The wildcard characters in @code{make} are @samp{*}, @samp{?} and
1714 @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
1715 specifies a list of all the files (in the working directory) whose names
1716 end in @samp{.c}.@refill
1717
1718 @cindex @code{~} (tilde)
1719 @cindex tilde (@code{~})
1720 @cindex home directory
1721 The character @samp{~} at the beginning of a file name also has special
1722 significance. If alone, or followed by a slash, it represents your home
1723 directory. For example @file{~/bin} expands to @file{/home/you/bin}.
1724 If the @samp{~} is followed by a word, the string represents the home
1725 directory of the user named by that word. For example @file{~john/bin}
1726 expands to @file{/home/john/bin}. On systems which don't have a home
1727 directory for each user (such as MS-DOS or MS-Windows), this
1728 functionality can be simulated by setting the environment variable
1729 @var{HOME}.@refill
1730
1731 Wildcard expansion happens automatically in targets, in prerequisites,
1732 and in commands (where the shell does the expansion). In other
1733 contexts, wildcard expansion happens only if you request it explicitly
1734 with the @code{wildcard} function.
1735
1736 The special significance of a wildcard character can be turned off by
1737 preceding it with a backslash. Thus, @file{foo\*bar} would refer to a
1738 specific file whose name consists of @samp{foo}, an asterisk, and
1739 @samp{bar}.@refill
1740
1741 @menu
1742 * Wildcard Examples:: Several examples
1743 * Wildcard Pitfall:: Problems to avoid.
1744 * Wildcard Function:: How to cause wildcard expansion where
1745 it does not normally take place.
1746 @end menu
1747
1748 @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards
1749 @subsection Wildcard Examples
1750
1751 Wildcards can be used in the commands of a rule, where they are expanded
1752 by the shell. For example, here is a rule to delete all the object files:
1753
1754 @example
1755 @group
1756 clean:
1757 rm -f *.o
1758 @end group
1759 @end example
1760 @cindex @code{rm} (shell command)
1761
1762 Wildcards are also useful in the prerequisites of a rule. With the
1763 following rule in the makefile, @samp{make print} will print all the
1764 @samp{.c} files that have changed since the last time you printed them:
1765
1766 @example
1767 print: *.c
1768 lpr -p $?
1769 touch print
1770 @end example
1771
1772 @cindex @code{print} target
1773 @cindex @code{lpr} (shell command)
1774 @cindex @code{touch} (shell command)
1775 @noindent
1776 This rule uses @file{print} as an empty target file; see @ref{Empty
1777 Targets, ,Empty Target Files to Record Events}. (The automatic variable
1778 @samp{$?} is used to print only those files that have changed; see
1779 @ref{Automatic Variables}.)@refill
1780
1781 Wildcard expansion does not happen when you define a variable. Thus, if
1782 you write this:
1783
1784 @example
1785 objects = *.o
1786 @end example
1787
1788 @noindent
1789 then the value of the variable @code{objects} is the actual string
1790 @samp{*.o}. However, if you use the value of @code{objects} in a target,
1791 prerequisite or command, wildcard expansion will take place at that time.
1792 To set @code{objects} to the expansion, instead use:
1793
1794 @example
1795 objects := $(wildcard *.o)
1796 @end example
1797
1798 @noindent
1799 @xref{Wildcard Function}.
1800
1801 @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
1802 @subsection Pitfalls of Using Wildcards
1803 @cindex wildcard pitfalls
1804 @cindex pitfalls of wildcards
1805 @cindex mistakes with wildcards
1806 @cindex errors with wildcards
1807 @cindex problems with wildcards
1808
1809 Now here is an example of a naive way of using wildcard expansion, that
1810 does not do what you would intend. Suppose you would like to say that the
1811 executable file @file{foo} is made from all the object files in the
1812 directory, and you write this:
1813
1814 @example
1815 objects = *.o
1816
1817 foo : $(objects)
1818 cc -o foo $(CFLAGS) $(objects)
1819 @end example
1820
1821 @noindent
1822 The value of @code{objects} is the actual string @samp{*.o}. Wildcard
1823 expansion happens in the rule for @file{foo}, so that each @emph{existing}
1824 @samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if
1825 necessary.
1826
1827 But what if you delete all the @samp{.o} files? When a wildcard matches
1828 no files, it is left as it is, so then @file{foo} will depend on the
1829 oddly-named file @file{*.o}. Since no such file is likely to exist,
1830 @code{make} will give you an error saying it cannot figure out how to
1831 make @file{*.o}. This is not what you want!
1832
1833 Actually it is possible to obtain the desired result with wildcard
1834 expansion, but you need more sophisticated techniques, including the
1835 @code{wildcard} function and string substitution.
1836 @ifinfo
1837 @xref{Wildcard Function, ,The Function @code{wildcard}}.
1838 @end ifinfo
1839 @iftex
1840 These are described in the following section.
1841 @end iftex
1842
1843 @cindex wildcards and MS-DOS/MS-Windows backslashes
1844 @cindex backslashes in pathnames and wildcard expansion
1845
1846 Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to
1847 separate directories in pathnames, like so:
1848
1849 @example
1850 c:\foo\bar\baz.c
1851 @end example
1852
1853 This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the
1854 @file{c:} part is the so-called drive letter). When @code{make} runs on
1855 these systems, it supports backslashes as well as the Unix-style forward
1856 slashes in pathnames. However, this support does @emph{not} include the
1857 wildcard expansion, where backslash is a quote character. Therefore,
1858 you @emph{must} use Unix-style slashes in these cases.
1859
1860
1861 @node Wildcard Function, , Wildcard Pitfall, Wildcards
1862 @subsection The Function @code{wildcard}
1863 @findex wildcard
1864
1865 Wildcard expansion happens automatically in rules. But wildcard expansion
1866 does not normally take place when a variable is set, or inside the
1867 arguments of a function. If you want to do wildcard expansion in such
1868 places, you need to use the @code{wildcard} function, like this:
1869
1870 @example
1871 $(wildcard @var{pattern}@dots{})
1872 @end example
1873
1874 @noindent
1875 This string, used anywhere in a makefile, is replaced by a
1876 space-separated list of names of existing files that match one of the
1877 given file name patterns. If no existing file name matches a pattern,
1878 then that pattern is omitted from the output of the @code{wildcard}
1879 function. Note that this is different from how unmatched wildcards
1880 behave in rules, where they are used verbatim rather than ignored
1881 (@pxref{Wildcard Pitfall}).
1882
1883 One use of the @code{wildcard} function is to get a list of all the C source
1884 files in a directory, like this:
1885
1886 @example
1887 $(wildcard *.c)
1888 @end example
1889
1890 We can change the list of C source files into a list of object files by
1891 replacing the @samp{.c} suffix with @samp{.o} in the result, like this:
1892
1893 @example
1894 $(patsubst %.c,%.o,$(wildcard *.c))
1895 @end example
1896
1897 @noindent
1898 (Here we have used another function, @code{patsubst}.
1899 @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
1900
1901 Thus, a makefile to compile all C source files in the directory and then
1902 link them together could be written as follows:
1903
1904 @example
1905 objects := $(patsubst %.c,%.o,$(wildcard *.c))
1906
1907 foo : $(objects)
1908 cc -o foo $(objects)
1909 @end example
1910
1911 @noindent
1912 (This takes advantage of the implicit rule for compiling C programs, so
1913 there is no need to write explicit rules for compiling the files.
1914 @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
1915 @samp{:=}, which is a variant of @samp{=}.)
1916
1917 @node Directory Search, Phony Targets, Wildcards, Rules
1918 @section Searching Directories for Prerequisites
1919 @vindex VPATH
1920 @findex vpath
1921 @cindex vpath
1922 @cindex search path for prerequisites (@code{VPATH})
1923 @cindex directory search (@code{VPATH})
1924
1925 For large systems, it is often desirable to put sources in a separate
1926 directory from the binaries. The @dfn{directory search} features of
1927 @code{make} facilitate this by searching several directories
1928 automatically to find a prerequisite. When you redistribute the files
1929 among directories, you do not need to change the individual rules,
1930 just the search paths.
1931
1932 @menu
1933 * General Search:: Specifying a search path that applies
1934 to every prerequisite.
1935 * Selective Search:: Specifying a search path
1936 for a specified class of names.
1937 * Search Algorithm:: When and how search paths are applied.
1938 * Commands/Search:: How to write shell commands that work together
1939 with search paths.
1940 * Implicit/Search:: How search paths affect implicit rules.
1941 * Libraries/Search:: Directory search for link libraries.
1942 @end menu
1943
1944 @node General Search, Selective Search, Directory Search, Directory Search
1945 @subsection @code{VPATH}: Search Path for All Prerequisites
1946 @vindex VPATH
1947
1948 The value of the @code{make} variable @code{VPATH} specifies a list of
1949 directories that @code{make} should search. Most often, the
1950 directories are expected to contain prerequisite files that are not in the
1951 current directory; however, @code{VPATH} specifies a search list that
1952 @code{make} applies for all files, including files which are targets of
1953 rules.
1954
1955 Thus, if a file that is listed as a target or prerequisite does not exist
1956 in the current directory, @code{make} searches the directories listed in
1957 @code{VPATH} for a file with that name. If a file is found in one of
1958 them, that file may become the prerequisite (see below). Rules may then
1959 specify the names of files in the prerequisite list as if they all
1960 existed in the current directory. @xref{Commands/Search, ,Writing Shell
1961 Commands with Directory Search}.
1962
1963 In the @code{VPATH} variable, directory names are separated by colons or
1964 blanks. The order in which directories are listed is the order followed
1965 by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons
1966 are used as separators of directory names in @code{VPATH}, since the
1967 colon can be used in the pathname itself, after the drive letter.)
1968
1969 For example,
1970
1971 @example
1972 VPATH = src:../headers
1973 @end example
1974
1975 @noindent
1976 specifies a path containing two directories, @file{src} and
1977 @file{../headers}, which @code{make} searches in that order.
1978
1979 With this value of @code{VPATH}, the following rule,
1980
1981 @example
1982 foo.o : foo.c
1983 @end example
1984
1985 @noindent
1986 is interpreted as if it were written like this:
1987
1988 @example
1989 foo.o : src/foo.c
1990 @end example
1991
1992 @noindent
1993 assuming the file @file{foo.c} does not exist in the current directory but
1994 is found in the directory @file{src}.
1995
1996 @node Selective Search, Search Algorithm, General Search, Directory Search
1997 @subsection The @code{vpath} Directive
1998 @findex vpath
1999
2000 Similar to the @code{VPATH} variable, but more selective, is the
2001 @code{vpath} directive (note lower case), which allows you to specify a
2002 search path for a particular class of file names: those that match a
2003 particular pattern. Thus you can supply certain search directories for
2004 one class of file names and other directories (or none) for other file
2005 names.
2006
2007 There are three forms of the @code{vpath} directive:
2008
2009 @table @code
2010 @item vpath @var{pattern} @var{directories}
2011 Specify the search path @var{directories} for file names that match
2012 @var{pattern}.
2013
2014 The search path, @var{directories}, is a list of directories to be
2015 searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or
2016 blanks, just like the search path used in the @code{VPATH} variable.
2017
2018 @item vpath @var{pattern}
2019 Clear out the search path associated with @var{pattern}.
2020
2021 @c Extra blank line makes sure this gets two lines.
2022 @item vpath
2023
2024 Clear all search paths previously specified with @code{vpath} directives.
2025 @end table
2026
2027 A @code{vpath} pattern is a string containing a @samp{%} character. The
2028 string must match the file name of a prerequisite that is being searched
2029 for, the @samp{%} character matching any sequence of zero or more
2030 characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
2031 Redefining Pattern Rules}). For example, @code{%.h} matches files that
2032 end in @code{.h}. (If there is no @samp{%}, the pattern must match the
2033 prerequisite exactly, which is not useful very often.)
2034
2035 @cindex @code{%}, quoting in @code{vpath}
2036 @cindex @code{%}, quoting with @code{\} (backslash)
2037 @cindex @code{\} (backslash), to quote @code{%}
2038 @cindex backslash (@code{\}), to quote @code{%}
2039 @cindex quoting @code{%}, in @code{vpath}
2040 @samp{%} characters in a @code{vpath} directive's pattern can be quoted
2041 with preceding backslashes (@samp{\}). Backslashes that would otherwise
2042 quote @samp{%} characters can be quoted with more backslashes.
2043 Backslashes that quote @samp{%} characters or other backslashes are
2044 removed from the pattern before it is compared to file names. Backslashes
2045 that are not in danger of quoting @samp{%} characters go unmolested.@refill
2046
2047 When a prerequisite fails to exist in the current directory, if the
2048 @var{pattern} in a @code{vpath} directive matches the name of the
2049 prerequisite file, then the @var{directories} in that directive are searched
2050 just like (and before) the directories in the @code{VPATH} variable.
2051
2052 For example,
2053
2054 @example
2055 vpath %.h ../headers
2056 @end example
2057
2058 @noindent
2059 tells @code{make} to look for any prerequisite whose name ends in @file{.h}
2060 in the directory @file{../headers} if the file is not found in the current
2061 directory.
2062
2063 If several @code{vpath} patterns match the prerequisite file's name, then
2064 @code{make} processes each matching @code{vpath} directive one by one,
2065 searching all the directories mentioned in each directive. @code{make}
2066 handles multiple @code{vpath} directives in the order in which they
2067 appear in the makefile; multiple directives with the same pattern are
2068 independent of each other.
2069
2070 @need 750
2071 Thus,
2072
2073 @example
2074 @group
2075 vpath %.c foo
2076 vpath % blish
2077 vpath %.c bar
2078 @end group
2079 @end example
2080
2081 @noindent
2082 will look for a file ending in @samp{.c} in @file{foo}, then
2083 @file{blish}, then @file{bar}, while
2084
2085 @example
2086 @group
2087 vpath %.c foo:bar
2088 vpath % blish
2089 @end group
2090 @end example
2091
2092 @noindent
2093 will look for a file ending in @samp{.c} in @file{foo}, then
2094 @file{bar}, then @file{blish}.
2095
2096 @node Search Algorithm, Commands/Search, Selective Search, Directory Search
2097 @subsection How Directory Searches are Performed
2098 @cindex algorithm for directory search
2099 @cindex directory search algorithm
2100
2101 When a prerequisite is found through directory search, regardless of type
2102 (general or selective), the pathname located may not be the one that
2103 @code{make} actually provides you in the prerequisite list. Sometimes
2104 the path discovered through directory search is thrown away.
2105
2106 The algorithm @code{make} uses to decide whether to keep or abandon a
2107 path found via directory search is as follows:
2108
2109 @enumerate
2110 @item
2111 If a target file does not exist at the path specified in the makefile,
2112 directory search is performed.
2113
2114 @item
2115 If the directory search is successful, that path is kept and this file
2116 is tentatively stored as the target.
2117
2118 @item
2119 All prerequisites of this target are examined using this same method.
2120
2121 @item
2122 After processing the prerequisites, the target may or may not need to be
2123 rebuilt:
2124
2125 @enumerate a
2126 @item
2127 If the target does @emph{not} need to be rebuilt, the path to the file
2128 found during directory search is used for any prerequisite lists which
2129 contain this target. In short, if @code{make} doesn't need to rebuild
2130 the target then you use the path found via directory search.
2131
2132 @item
2133 If the target @emph{does} need to be rebuilt (is out-of-date), the
2134 pathname found during directory search is @emph{thrown away}, and the
2135 target is rebuilt using the file name specified in the makefile. In
2136 short, if @code{make} must rebuild, then the target is rebuilt locally,
2137 not in the directory found via directory search.
2138 @end enumerate
2139 @end enumerate
2140
2141 This algorithm may seem complex, but in practice it is quite often
2142 exactly what you want.
2143
2144 @cindex traditional directory search (GPATH)
2145 @cindex directory search, traditional (GPATH)
2146 Other versions of @code{make} use a simpler algorithm: if the file does
2147 not exist, and it is found via directory search, then that pathname is
2148 always used whether or not the target needs to be built. Thus, if the
2149 target is rebuilt it is created at the pathname discovered during
2150 directory search.
2151
2152 @vindex GPATH
2153 If, in fact, this is the behavior you want for some or all of your
2154 directories, you can use the @code{GPATH} variable to indicate this to
2155 @code{make}.
2156
2157 @code{GPATH} has the same syntax and format as @code{VPATH} (that is, a
2158 space- or colon-delimited list of pathnames). If an out-of-date target
2159 is found by directory search in a directory that also appears in
2160 @code{GPATH}, then that pathname is not thrown away. The target is
2161 rebuilt using the expanded path.
2162
2163 @node Commands/Search, Implicit/Search, Search Algorithm, Directory Search
2164 @subsection Writing Shell Commands with Directory Search
2165 @cindex shell command, and directory search
2166 @cindex directory search (@code{VPATH}), and shell commands
2167
2168 When a prerequisite is found in another directory through directory search,
2169 this cannot change the commands of the rule; they will execute as written.
2170 Therefore, you must write the commands with care so that they will look for
2171 the prerequisite in the directory where @code{make} finds it.
2172
2173 This is done with the @dfn{automatic variables} such as @samp{$^}
2174 (@pxref{Automatic Variables}).
2175 For instance, the value of @samp{$^} is a
2176 list of all the prerequisites of the rule, including the names of
2177 the directories in which they were found, and the value of
2178 @samp{$@@} is the target. Thus:@refill
2179
2180 @example
2181 foo.o : foo.c
2182 cc -c $(CFLAGS) $^ -o $@@
2183 @end example
2184
2185 @noindent
2186 (The variable @code{CFLAGS} exists so you can specify flags for C
2187 compilation by implicit rules; we use it here for consistency so it will
2188 affect all C compilations uniformly;
2189 @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
2190
2191 Often the prerequisites include header files as well, which you do not
2192 want to mention in the commands. The automatic variable @samp{$<} is
2193 just the first prerequisite:
2194
2195 @example
2196 VPATH = src:../headers
2197 foo.o : foo.c defs.h hack.h
2198 cc -c $(CFLAGS) $< -o $@@
2199 @end example
2200
2201 @node Implicit/Search, Libraries/Search, Commands/Search, Directory Search
2202 @subsection Directory Search and Implicit Rules
2203 @cindex @code{VPATH}, and implicit rules
2204 @cindex directory search (@code{VPATH}), and implicit rules
2205 @cindex search path for prerequisites (@code{VPATH}), and implicit rules
2206 @cindex implicit rule, and directory search
2207 @cindex implicit rule, and @code{VPATH}
2208 @cindex rule, implicit, and directory search
2209 @cindex rule, implicit, and @code{VPATH}
2210
2211 The search through the directories specified in @code{VPATH} or with
2212 @code{vpath} also happens during consideration of implicit rules
2213 (@pxref{Implicit Rules, ,Using Implicit Rules}).
2214
2215 For example, when a file @file{foo.o} has no explicit rule, @code{make}
2216 considers implicit rules, such as the built-in rule to compile
2217 @file{foo.c} if that file exists. If such a file is lacking in the
2218 current directory, the appropriate directories are searched for it. If
2219 @file{foo.c} exists (or is mentioned in the makefile) in any of the
2220 directories, the implicit rule for C compilation is applied.
2221
2222 The commands of implicit rules normally use automatic variables as a
2223 matter of necessity; consequently they will use the file names found by
2224 directory search with no extra effort.
2225
2226 @node Libraries/Search, , Implicit/Search, Directory Search
2227 @subsection Directory Search for Link Libraries
2228 @cindex link libraries, and directory search
2229 @cindex libraries for linking, directory search
2230 @cindex directory search (@code{VPATH}), and link libraries
2231 @cindex @code{VPATH}, and link libraries
2232 @cindex search path for prerequisites (@code{VPATH}), and link libraries
2233 @cindex @code{-l} (library search)
2234 @cindex link libraries, patterns matching
2235 @cindex @code{.LIBPATTERNS}, and link libraries
2236 @vindex .LIBPATTERNS
2237
2238 Directory search applies in a special way to libraries used with the
2239 linker. This special feature comes into play when you write a prerequisite
2240 whose name is of the form @samp{-l@var{name}}. (You can tell something
2241 strange is going on here because the prerequisite is normally the name of a
2242 file, and the @emph{file name} of a library generally looks like
2243 @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
2244
2245 When a prerequisite's name has the form @samp{-l@var{name}}, @code{make}
2246 handles it specially by searching for the file @file{lib@var{name}.so} in
2247 the current directory, in directories specified by matching @code{vpath}
2248 search paths and the @code{VPATH} search path, and then in the
2249 directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
2250 (normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of
2251 @code{make} behave as if @var{prefix} is defined to be the root of the
2252 DJGPP installation tree).
2253
2254 If that file is not found, then the file @file{lib@var{name}.a} is
2255 searched for, in the same directories as above.
2256
2257 For example, if there is a @file{/usr/lib/libcurses.a} library on your
2258 system (and no @file{/usr/lib/libcurses.so} file), then
2259
2260 @example
2261 @group
2262 foo : foo.c -lcurses
2263 cc $^ -o $@@
2264 @end group
2265 @end example
2266
2267 @noindent
2268 would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
2269 be executed when @file{foo} is older than @file{foo.c} or than
2270 @file{/usr/lib/libcurses.a}.@refill
2271
2272 Although the default set of files to be searched for is
2273 @file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable
2274 via the @code{.LIBPATTERNS} variable. Each word in the value of this
2275 variable is a pattern string. When a prerequisite like
2276 @samp{-l@var{name}} is seen, @code{make} will replace the percent in
2277 each pattern in the list with @var{name} and perform the above directory
2278 searches using that library filename. If no library is found, the next
2279 word in the list will be used.
2280
2281 The default value for @code{.LIBPATTERNS} is ``@samp{lib%.so lib%.a}'',
2282 which provides the default behavior described above.
2283
2284 You can turn off link library expansion completely by setting this
2285 variable to an empty value.
2286
2287 @node Phony Targets, Force Targets, Directory Search, Rules
2288 @section Phony Targets
2289 @cindex phony targets
2290 @cindex targets, phony
2291 @cindex targets without a file
2292
2293 A phony target is one that is not really the name of a file. It is just a
2294 name for some commands to be executed when you make an explicit request.
2295 There are two reasons to use a phony target: to avoid a conflict with
2296 a file of the same name, and to improve performance.
2297
2298 If you write a rule whose commands will not create the target file, the
2299 commands will be executed every time the target comes up for remaking.
2300 Here is an example:
2301
2302 @example
2303 @group
2304 clean:
2305 rm *.o temp
2306 @end group
2307 @end example
2308
2309 @noindent
2310 Because the @code{rm} command does not create a file named @file{clean},
2311 probably no such file will ever exist. Therefore, the @code{rm} command
2312 will be executed every time you say @samp{make clean}.
2313 @cindex @code{rm} (shell command)
2314
2315 @findex .PHONY
2316 The phony target will cease to work if anything ever does create a file
2317 named @file{clean} in this directory. Since it has no prerequisites, the
2318 file @file{clean} would inevitably be considered up to date, and its
2319 commands would not be executed. To avoid this problem, you can explicitly
2320 declare the target to be phony, using the special target @code{.PHONY}
2321 (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
2322
2323 @example
2324 .PHONY : clean
2325 @end example
2326
2327 @noindent
2328 Once this is done, @samp{make clean} will run the commands regardless of
2329 whether there is a file named @file{clean}.
2330
2331 Since it knows that phony targets do not name actual files that could be
2332 remade from other files, @code{make} skips the implicit rule search for
2333 phony targets (@pxref{Implicit Rules}). This is why declaring a target
2334 phony is good for performance, even if you are not worried about the
2335 actual file existing.
2336
2337 Thus, you first write the line that states that @code{clean} is a
2338 phony target, then you write the rule, like this:
2339
2340 @example
2341 @group
2342 .PHONY: clean
2343 clean:
2344 rm *.o temp
2345 @end group
2346 @end example
2347
2348 Another example of the usefulness of phony targets is in conjunction
2349 with recursive invocations of @code{make} (for more information, see
2350 @ref{Recursion, ,Recursive Use of @code{make}}). In this case the
2351 makefile will often contain a variable which lists a number of
2352 subdirectories to be built. One way to handle this is with one rule
2353 whose command is a shell loop over the subdirectories, like this:
2354
2355 @example
2356 @group
2357 SUBDIRS = foo bar baz
2358
2359 subdirs:
2360 for dir in $(SUBDIRS); do \
2361 $(MAKE) -C $$dir; \
2362 done
2363 @end group
2364 @end example
2365
2366 There are a few problems with this method, however. First, any error
2367 detected in a submake is not noted by this rule, so it will continue to
2368 build the rest of the directories even when one fails. This can be
2369 overcome by adding shell commands to note the error and exit, but then
2370 it will do so even if @code{make} is invoked with the @code{-k} option,
2371 which is unfortunate. Second, and perhaps more importantly, you cannot
2372 take advantage of the parallel build capabilities of make using this
2373 method, since there is only one rule.
2374
2375 By declaring the subdirectories as phony targets (you must do this as
2376 the subdirectory obviously always exists; otherwise it won't be built)
2377 you can remove these problems:
2378
2379 @example
2380 @group
2381 SUBDIRS = foo bar baz
2382
2383 .PHONY: subdirs $(SUBDIRS)
2384
2385 subdirs: $(SUBDIRS)
2386
2387 $(SUBDIRS):
2388 $(MAKE) -C $@@
2389
2390 foo: baz
2391 @end group
2392 @end example
2393
2394 Here we've also declared that the @file{foo} subdirectory cannot be
2395 built until after the @file{baz} subdirectory is complete; this kind of
2396 relationship declaration is particularly important when attempting
2397 parallel builds.
2398
2399 A phony target should not be a prerequisite of a real target file; if it
2400 is, its commands are run every time @code{make} goes to update that
2401 file. As long as a phony target is never a prerequisite of a real
2402 target, the phony target commands will be executed only when the phony
2403 target is a specified goal (@pxref{Goals, ,Arguments to Specify the
2404 Goals}).
2405
2406 Phony targets can have prerequisites. When one directory contains multiple
2407 programs, it is most convenient to describe all of the programs in one
2408 makefile @file{./Makefile}. Since the target remade by default will be the
2409 first one in the makefile, it is common to make this a phony target named
2410 @samp{all} and give it, as prerequisites, all the individual programs. For
2411 example:
2412
2413 @example
2414 all : prog1 prog2 prog3
2415 .PHONY : all
2416
2417 prog1 : prog1.o utils.o
2418 cc -o prog1 prog1.o utils.o
2419
2420 prog2 : prog2.o
2421 cc -o prog2 prog2.o
2422
2423 prog3 : prog3.o sort.o utils.o
2424 cc -o prog3 prog3.o sort.o utils.o
2425 @end example
2426
2427 @noindent
2428 Now you can say just @samp{make} to remake all three programs, or specify
2429 as arguments the ones to remake (as in @samp{make prog1 prog3}).
2430
2431 When one phony target is a prerequisite of another, it serves as a subroutine
2432 of the other. For example, here @samp{make cleanall} will delete the
2433 object files, the difference files, and the file @file{program}:
2434
2435 @example
2436 .PHONY: cleanall cleanobj cleandiff
2437
2438 cleanall : cleanobj cleandiff
2439 rm program
2440
2441 cleanobj :
2442 rm *.o
2443
2444 cleandiff :
2445 rm *.diff
2446 @end example
2447
2448 @node Force Targets, Empty Targets, Phony Targets, Rules
2449 @section Rules without Commands or Prerequisites
2450 @cindex force targets
2451 @cindex targets, force
2452 @cindex @code{FORCE}
2453 @cindex rule, no commands or prerequisites
2454
2455 If a rule has no prerequisites or commands, and the target of the rule
2456 is a nonexistent file, then @code{make} imagines this target to have
2457 been updated whenever its rule is run. This implies that all targets
2458 depending on this one will always have their commands run.
2459
2460 An example will illustrate this:
2461
2462 @example
2463 @group
2464 clean: FORCE
2465 rm $(objects)
2466 FORCE:
2467 @end group
2468 @end example
2469
2470 Here the target @samp{FORCE} satisfies the special conditions, so the
2471 target @file{clean} that depends on it is forced to run its commands.
2472 There is nothing special about the name @samp{FORCE}, but that is one name
2473 commonly used this way.
2474
2475 As you can see, using @samp{FORCE} this way has the same results as using
2476 @samp{.PHONY: clean}.
2477
2478 Using @samp{.PHONY} is more explicit and more efficient. However,
2479 other versions of @code{make} do not support @samp{.PHONY}; thus
2480 @samp{FORCE} appears in many makefiles. @xref{Phony Targets}.
2481
2482 @node Empty Targets, Special Targets, Force Targets, Rules
2483 @section Empty Target Files to Record Events
2484 @cindex empty targets
2485 @cindex targets, empty
2486 @cindex recording events with empty targets
2487
2488 The @dfn{empty target} is a variant of the phony target; it is used to hold
2489 commands for an action that you request explicitly from time to time.
2490 Unlike a phony target, this target file can really exist; but the file's
2491 contents do not matter, and usually are empty.
2492
2493 The purpose of the empty target file is to record, with its
2494 last-modification time, when the rule's commands were last executed. It
2495 does so because one of the commands is a @code{touch} command to update the
2496 target file.
2497
2498 The empty target file should have some prerequisites (otherwise it
2499 doesn't make sense). When you ask to remake the empty target, the
2500 commands are executed if any prerequisite is more recent than the target;
2501 in other words, if a prerequisite has changed since the last time you
2502 remade the target. Here is an example:
2503
2504 @example
2505 print: foo.c bar.c
2506 lpr -p $?
2507 touch print
2508 @end example
2509 @cindex @code{print} target
2510 @cindex @code{lpr} (shell command)
2511 @cindex @code{touch} (shell command)
2512
2513 @noindent
2514 With this rule, @samp{make print} will execute the @code{lpr} command if
2515 either source file has changed since the last @samp{make print}. The
2516 automatic variable @samp{$?} is used to print only those files that have
2517 changed (@pxref{Automatic Variables}).
2518
2519 @node Special Targets, Multiple Targets, Empty Targets, Rules
2520 @section Special Built-in Target Names
2521 @cindex special targets
2522 @cindex built-in special targets
2523 @cindex targets, built-in special
2524
2525 Certain names have special meanings if they appear as targets.
2526
2527 @table @code
2528 @findex .PHONY
2529 @item .PHONY
2530
2531 The prerequisites of the special target @code{.PHONY} are considered to
2532 be phony targets. When it is time to consider such a target,
2533 @code{make} will run its commands unconditionally, regardless of
2534 whether a file with that name exists or what its last-modification
2535 time is. @xref{Phony Targets, ,Phony Targets}.
2536
2537 @findex .SUFFIXES
2538 @item .SUFFIXES
2539
2540 The prerequisites of the special target @code{.SUFFIXES} are the list
2541 of suffixes to be used in checking for suffix rules.
2542 @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
2543
2544 @findex .DEFAULT
2545 @item .DEFAULT
2546
2547 The commands specified for @code{.DEFAULT} are used for any target for
2548 which no rules are found (either explicit rules or implicit rules).
2549 @xref{Last Resort}. If @code{.DEFAULT} commands are specified, every
2550 file mentioned as a prerequisite, but not as a target in a rule, will have
2551 these commands executed on its behalf. @xref{Implicit Rule Search,
2552 ,Implicit Rule Search Algorithm}.
2553
2554 @findex .PRECIOUS
2555 @item .PRECIOUS
2556 @cindex precious targets
2557 @cindex preserving with @code{.PRECIOUS}
2558
2559 The targets which @code{.PRECIOUS} depends on are given the following
2560 special treatment: if @code{make} is killed or interrupted during the
2561 execution of their commands, the target is not deleted.
2562 @xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the
2563 target is an intermediate file, it will not be deleted after it is no
2564 longer needed, as is normally done. @xref{Chained Rules, ,Chains of
2565 Implicit Rules}. In this latter respect it overlaps with the
2566 @code{.SECONDARY} special target.
2567
2568 You can also list the target pattern of an implicit rule (such as
2569 @samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS}
2570 to preserve intermediate files created by rules whose target patterns
2571 match that file's name.
2572
2573 @findex .INTERMEDIATE
2574 @item .INTERMEDIATE
2575 @cindex intermediate targets, explicit
2576
2577 The targets which @code{.INTERMEDIATE} depends on are treated as
2578 intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}.
2579 @code{.INTERMEDIATE} with no prerequisites has no effect.
2580
2581 @findex .SECONDARY
2582 @item .SECONDARY
2583 @cindex secondary targets
2584 @cindex preserving with @code{.SECONDARY}
2585
2586 The targets which @code{.SECONDARY} depends on are treated as
2587 intermediate files, except that they are never automatically deleted.
2588 @xref{Chained Rules, ,Chains of Implicit Rules}.
2589
2590 @code{.SECONDARY} with no prerequisites causes all targets to be treated
2591 as secondary (i.e., no target is removed because it is considered
2592 intermediate).
2593
2594 @findex .DELETE_ON_ERROR
2595 @item .DELETE_ON_ERROR
2596 @cindex removing targets on failure
2597
2598 If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the
2599 makefile, then @code{make} will delete the target of a rule if it has
2600 changed and its commands exit with a nonzero exit status, just as it
2601 does when it receives a signal. @xref{Errors, ,Errors in Commands}.
2602
2603 @findex .IGNORE
2604 @item .IGNORE
2605
2606 If you specify prerequisites for @code{.IGNORE}, then @code{make} will
2607 ignore errors in execution of the commands run for those particular
2608 files. The commands for @code{.IGNORE} are not meaningful.
2609
2610 If mentioned as a target with no prerequisites, @code{.IGNORE} says to
2611 ignore errors in execution of commands for all files. This usage of
2612 @samp{.IGNORE} is supported only for historical compatibility. Since
2613 this affects every command in the makefile, it is not very useful; we
2614 recommend you use the more selective ways to ignore errors in specific
2615 commands. @xref{Errors, ,Errors in Commands}.
2616
2617 @findex .LOW_RESOLUTION_TIME
2618 @item .LOW_RESOLUTION_TIME
2619
2620 If you specify prerequisites for @code{.LOW_RESOLUTION_TIME},
2621 @command{make} assumes that these files are created by commands that
2622 generate low resolution time stamps. The commands for
2623 @code{.LOW_RESOLUTION_TIME} are not meaningful.
2624
2625 The high resolution file time stamps of many modern hosts lessen the
2626 chance of @command{make} incorrectly concluding that a file is up to
2627 date. Unfortunately, these hosts provide no way to set a high
2628 resolution file time stamp, so commands like @samp{cp -p} that
2629 explicitly set a file's time stamp must discard its subsecond part. If
2630 a file is created by such a command, you should list it as a
2631 prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} does
2632 not mistakenly conclude that the file is out of date. For example:
2633
2634 @example
2635 @group
2636 .LOW_RESOLUTION_TIME: dst
2637 dst: src
2638 cp -p src dst
2639 @end group
2640 @end example
2641
2642 Since @samp{cp -p} discards the subsecond part of @file{src}'s time
2643 stamp, @file{dst} is typically slightly older than @file{src} even when
2644 it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes
2645 @command{make} to consider @file{dst} to be up to date if its time stamp
2646 is at the start of the same second that @file{src}'s time stamp is in.
2647
2648 Due to a limitation of the archive format, archive member time stamps
2649 are always low resolution. You need not list archive members as
2650 prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this
2651 automatically.
2652
2653 @findex .SILENT
2654 @item .SILENT
2655
2656 If you specify prerequisites for @code{.SILENT}, then @code{make} will
2657 not print the commands to remake those particular files before executing
2658 them. The commands for @code{.SILENT} are not meaningful.
2659
2660 If mentioned as a target with no prerequisites, @code{.SILENT} says not
2661 to print any commands before executing them. This usage of
2662 @samp{.SILENT} is supported only for historical compatibility. We
2663 recommend you use the more selective ways to silence specific commands.
2664 @xref{Echoing, ,Command Echoing}. If you want to silence all commands
2665 for a particular run of @code{make}, use the @samp{-s} or
2666 @w{@samp{--silent}} option (@pxref{Options Summary}).
2667
2668 @findex .EXPORT_ALL_VARIABLES
2669 @item .EXPORT_ALL_VARIABLES
2670
2671 Simply by being mentioned as a target, this tells @code{make} to
2672 export all variables to child processes by default.
2673 @xref{Variables/Recursion, ,Communicating Variables to a
2674 Sub-@code{make}}.
2675
2676 @findex .NOTPARALLEL
2677 @item .NOTPARALLEL
2678 @cindex parallel execution, overriding
2679
2680 If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of
2681 @code{make} will be run serially, even if the @samp{-j} option is
2682 given. Any recursively invoked @code{make} command will still be run in
2683 parallel (unless its makefile contains this target). Any prerequisites
2684 on this target are ignored.
2685 @end table
2686
2687 Any defined implicit rule suffix also counts as a special target if it
2688 appears as a target, and so does the concatenation of two suffixes, such
2689 as @samp{.c.o}. These targets are suffix rules, an obsolete way of
2690 defining implicit rules (but a way still widely used). In principle, any
2691 target name could be special in this way if you break it in two and add
2692 both pieces to the suffix list. In practice, suffixes normally begin with
2693 @samp{.}, so these special target names also begin with @samp{.}.
2694 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
2695
2696 @node Multiple Targets, Multiple Rules, Special Targets, Rules
2697 @section Multiple Targets in a Rule
2698 @cindex multiple targets
2699 @cindex several targets in a rule
2700 @cindex targets, multiple
2701 @cindex rule, with multiple targets
2702
2703 A rule with multiple targets is equivalent to writing many rules, each with
2704 one target, and all identical aside from that. The same commands apply to
2705 all the targets, but their effects may vary because you can substitute the
2706 actual target name into the command using @samp{$@@}. The rule contributes
2707 the same prerequisites to all the targets also.
2708
2709 This is useful in two cases.
2710
2711 @itemize @bullet
2712 @item
2713 You want just prerequisites, no commands. For example:
2714
2715 @example
2716 kbd.o command.o files.o: command.h
2717 @end example
2718
2719 @noindent
2720 gives an additional prerequisite to each of the three object files
2721 mentioned.
2722
2723 @item
2724 Similar commands work for all the targets. The commands do not need
2725 to be absolutely identical, since the automatic variable @samp{$@@}
2726 can be used to substitute the particular target to be remade into the
2727 commands (@pxref{Automatic Variables}). For example:
2728
2729 @example
2730 @group
2731 bigoutput littleoutput : text.g
2732 generate text.g -$(subst output,,$@@) > $@@
2733 @end group
2734 @end example
2735 @findex subst
2736
2737 @noindent
2738 is equivalent to
2739
2740 @example
2741 bigoutput : text.g
2742 generate text.g -big > bigoutput
2743 littleoutput : text.g
2744 generate text.g -little > littleoutput
2745 @end example
2746
2747 @noindent
2748 Here we assume the hypothetical program @code{generate} makes two
2749 types of output, one if given @samp{-big} and one if given
2750 @samp{-little}.
2751 @xref{Text Functions, ,Functions for String Substitution and Analysis},
2752 for an explanation of the @code{subst} function.
2753 @end itemize
2754
2755 Suppose you would like to vary the prerequisites according to the target,
2756 much as the variable @samp{$@@} allows you to vary the commands.
2757 You cannot do this with multiple targets in an ordinary rule, but you can
2758 do it with a @dfn{static pattern rule}.
2759 @xref{Static Pattern, ,Static Pattern Rules}.
2760
2761 @node Multiple Rules, Static Pattern, Multiple Targets, Rules
2762 @section Multiple Rules for One Target
2763 @cindex multiple rules for one target
2764 @cindex several rules for one target
2765 @cindex rule, multiple for one target
2766 @cindex target, multiple rules for one
2767
2768 One file can be the target of several rules. All the prerequisites
2769 mentioned in all the rules are merged into one list of prerequisites for
2770 the target. If the target is older than any prerequisite from any rule,
2771 the commands are executed.
2772
2773 There can only be one set of commands to be executed for a file. If
2774 more than one rule gives commands for the same file, @code{make} uses
2775 the last set given and prints an error message. (As a special case,
2776 if the file's name begins with a dot, no error message is printed.
2777 This odd behavior is only for compatibility with other implementations
2778 of @code{make}... you should avoid using it). Occasionally it is
2779 useful to have the same target invoke multiple commands which are
2780 defined in different parts of your makefile; you can use
2781 @dfn{double-colon rules} (@pxref{Double-Colon}) for this.
2782
2783 An extra rule with just prerequisites can be used to give a few extra
2784 prerequisites to many files at once. For example, makefiles often
2785 have a variable, such as @code{objects}, containing a list of all the
2786 compiler output files in the system being made. An easy way to say
2787 that all of them must be recompiled if @file{config.h} changes is to
2788 write the following:
2789
2790 @example
2791 objects = foo.o bar.o
2792 foo.o : defs.h
2793 bar.o : defs.h test.h
2794 $(objects) : config.h
2795 @end example
2796
2797 This could be inserted or taken out without changing the rules that really
2798 specify how to make the object files, making it a convenient form to use if
2799 you wish to add the additional prerequisite intermittently.
2800
2801 Another wrinkle is that the additional prerequisites could be specified with
2802 a variable that you set with a command argument to @code{make}
2803 (@pxref{Overriding, ,Overriding Variables}). For example,
2804
2805 @example
2806 @group
2807 extradeps=
2808 $(objects) : $(extradeps)
2809 @end group
2810 @end example
2811
2812 @noindent
2813 means that the command @samp{make extradeps=foo.h} will consider
2814 @file{foo.h} as a prerequisite of each object file, but plain @samp{make}
2815 will not.
2816
2817 If none of the explicit rules for a target has commands, then @code{make}
2818 searches for an applicable implicit rule to find some commands
2819 @pxref{Implicit Rules, ,Using Implicit Rules}).
2820
2821 @node Static Pattern, Double-Colon, Multiple Rules, Rules
2822 @section Static Pattern Rules
2823 @cindex static pattern rule
2824 @cindex rule, static pattern
2825 @cindex pattern rules, static (not implicit)
2826 @cindex varying prerequisites
2827 @cindex prerequisites, varying (static pattern)
2828
2829 @dfn{Static pattern rules} are rules which specify multiple targets and
2830 construct the prerequisite names for each target based on the target name.
2831 They are more general than ordinary rules with multiple targets because the
2832 targets do not have to have identical prerequisites. Their prerequisites must
2833 be @emph{analogous}, but not necessarily @emph{identical}.
2834
2835 @menu
2836 * Static Usage:: The syntax of static pattern rules.
2837 * Static versus Implicit:: When are they better than implicit rules?
2838 @end menu
2839
2840 @node Static Usage, Static versus Implicit, Static Pattern, Static Pattern
2841 @subsection Syntax of Static Pattern Rules
2842 @cindex static pattern rule, syntax of
2843 @cindex pattern rules, static, syntax of
2844
2845 Here is the syntax of a static pattern rule:
2846
2847 @example
2848 @var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{}
2849 @var{commands}
2850 @dots{}
2851 @end example
2852
2853 @noindent
2854 The @var{targets} list specifies the targets that the rule applies to.
2855 The targets can contain wildcard characters, just like the targets of
2856 ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
2857 Names}).
2858
2859 @cindex target pattern, static (not implicit)
2860 @cindex stem
2861 The @var{target-pattern} and @var{prereq-patterns} say how to compute the
2862 prerequisites of each target. Each target is matched against the
2863 @var{target-pattern} to extract a part of the target name, called the
2864 @dfn{stem}. This stem is substituted into each of the @var{prereq-patterns}
2865 to make the prerequisite names (one from each @var{prereq-pattern}).
2866
2867 Each pattern normally contains the character @samp{%} just once. When the
2868 @var{target-pattern} matches a target, the @samp{%} can match any part of
2869 the target name; this part is called the @dfn{stem}. The rest of the
2870 pattern must match exactly. For example, the target @file{foo.o} matches
2871 the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
2872 @file{foo.c} and @file{foo.out} do not match that pattern.@refill
2873
2874 @cindex prerequisite pattern, static (not implicit)
2875 The prerequisite names for each target are made by substituting the stem
2876 for the @samp{%} in each prerequisite pattern. For example, if one
2877 prerequisite pattern is @file{%.c}, then substitution of the stem
2878 @samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate
2879 to write a prerequisite pattern that does not contain @samp{%}; then this
2880 prerequisite is the same for all targets.
2881
2882 @cindex @code{%}, quoting in static pattern
2883 @cindex @code{%}, quoting with @code{\} (backslash)
2884 @cindex @code{\} (backslash), to quote @code{%}
2885 @cindex backslash (@code{\}), to quote @code{%}
2886 @cindex quoting @code{%}, in static pattern
2887 @samp{%} characters in pattern rules can be quoted with preceding
2888 backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%}
2889 characters can be quoted with more backslashes. Backslashes that quote
2890 @samp{%} characters or other backslashes are removed from the pattern
2891 before it is compared to file names or has a stem substituted into it.
2892 Backslashes that are not in danger of quoting @samp{%} characters go
2893 unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has
2894 @samp{the%weird\} preceding the operative @samp{%} character, and
2895 @samp{pattern\\} following it. The final two backslashes are left alone
2896 because they cannot affect any @samp{%} character.@refill
2897
2898 Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
2899 from the corresponding @file{.c} file:
2900
2901 @example
2902 @group
2903 objects = foo.o bar.o
2904
2905 all: $(objects)
2906
2907 $(objects): %.o: %.c
2908 $(CC) -c $(CFLAGS) $< -o $@@
2909 @end group
2910 @end example
2911
2912 @noindent
2913 Here @samp{$<} is the automatic variable that holds the name of the
2914 prerequisite and @samp{$@@} is the automatic variable that holds the name
2915 of the target; see @ref{Automatic Variables}.
2916
2917 Each target specified must match the target pattern; a warning is issued
2918 for each target that does not. If you have a list of files, only some of
2919 which will match the pattern, you can use the @code{filter} function to
2920 remove nonmatching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
2921
2922 @example
2923 files = foo.elc bar.o lose.o
2924
2925 $(filter %.o,$(files)): %.o: %.c
2926 $(CC) -c $(CFLAGS) $< -o $@@
2927 $(filter %.elc,$(files)): %.elc: %.el
2928 emacs -f batch-byte-compile $<
2929 @end example
2930
2931 @noindent
2932 In this example the result of @samp{$(filter %.o,$(files))} is
2933 @file{bar.o lose.o}, and the first static pattern rule causes each of
2934 these object files to be updated by compiling the corresponding C source
2935 file. The result of @w{@samp{$(filter %.elc,$(files))}} is
2936 @file{foo.elc}, so that file is made from @file{foo.el}.@refill
2937
2938 Another example shows how to use @code{$*} in static pattern rules:
2939 @vindex $*@r{, and static pattern}
2940
2941 @example
2942 @group
2943 bigoutput littleoutput : %output : text.g
2944 generate text.g -$* > $@@
2945 @end group
2946 @end example
2947
2948 @noindent
2949 When the @code{generate} command is run, @code{$*} will expand to the
2950 stem, either @samp{big} or @samp{little}.
2951
2952 @node Static versus Implicit, , Static Usage, Static Pattern
2953 @subsection Static Pattern Rules versus Implicit Rules
2954 @cindex rule, static pattern versus implicit
2955 @cindex static pattern rule, versus implicit
2956
2957 A static pattern rule has much in common with an implicit rule defined as a
2958 pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
2959 Both have a pattern for the target and patterns for constructing the
2960 names of prerequisites. The difference is in how @code{make} decides
2961 @emph{when} the rule applies.
2962
2963 An implicit rule @emph{can} apply to any target that matches its pattern,
2964 but it @emph{does} apply only when the target has no commands otherwise
2965 specified, and only when the prerequisites can be found. If more than one
2966 implicit rule appears applicable, only one applies; the choice depends on
2967 the order of rules.
2968
2969 By contrast, a static pattern rule applies to the precise list of targets
2970 that you specify in the rule. It cannot apply to any other target and it
2971 invariably does apply to each of the targets specified. If two conflicting
2972 rules apply, and both have commands, that's an error.
2973
2974 The static pattern rule can be better than an implicit rule for these
2975 reasons:
2976
2977 @itemize @bullet
2978 @item
2979 You may wish to override the usual implicit rule for a few
2980 files whose names cannot be categorized syntactically but
2981 can be given in an explicit list.
2982
2983 @item
2984 If you cannot be sure of the precise contents of the directories
2985 you are using, you may not be sure which other irrelevant files
2986 might lead @code{make} to use the wrong implicit rule. The choice
2987 might depend on the order in which the implicit rule search is done.
2988 With static pattern rules, there is no uncertainty: each rule applies
2989 to precisely the targets specified.
2990 @end itemize
2991
2992 @node Double-Colon, Automatic Prerequisites, Static Pattern, Rules
2993 @section Double-Colon Rules
2994 @cindex double-colon rules
2995 @cindex rule, double-colon (@code{::})
2996 @cindex multiple rules for one target (@code{::})
2997 @cindex @code{::} rules (double-colon)
2998
2999 @dfn{Double-colon} rules are rules written with @samp{::} instead of
3000 @samp{:} after the target names. They are handled differently from
3001 ordinary rules when the same target appears in more than one rule.
3002
3003 When a target appears in multiple rules, all the rules must be the same
3004 type: all ordinary, or all double-colon. If they are double-colon, each
3005 of them is independent of the others. Each double-colon rule's commands
3006 are executed if the target is older than any prerequisites of that rule.
3007 If there are no prerequisites for that rule, its commands are always
3008 executed (even if the target already exists). This can result in
3009 executing none, any, or all of the double-colon rules.
3010
3011 Double-colon rules with the same target are in fact completely separate
3012 from one another. Each double-colon rule is processed individually, just
3013 as rules with different targets are processed.
3014
3015 The double-colon rules for a target are executed in the order they appear
3016 in the makefile. However, the cases where double-colon rules really make
3017 sense are those where the order of executing the commands would not matter.
3018
3019 Double-colon rules are somewhat obscure and not often very useful; they
3020 provide a mechanism for cases in which the method used to update a target
3021 differs depending on which prerequisite files caused the update, and such
3022 cases are rare.
3023
3024 Each double-colon rule should specify commands; if it does not, an
3025 implicit rule will be used if one applies.
3026 @xref{Implicit Rules, ,Using Implicit Rules}.
3027
3028 @node Automatic Prerequisites, , Double-Colon, Rules
3029 @section Generating Prerequisites Automatically
3030 @cindex prerequisites, automatic generation
3031 @cindex automatic generation of prerequisites
3032 @cindex generating prerequisites automatically
3033
3034 In the makefile for a program, many of the rules you need to write often
3035 say only that some object file depends on some header
3036 file. For example, if @file{main.c} uses @file{defs.h} via an
3037 @code{#include}, you would write:
3038
3039 @example
3040 main.o: defs.h
3041 @end example
3042
3043 @noindent
3044 You need this rule so that @code{make} knows that it must remake
3045 @file{main.o} whenever @file{defs.h} changes. You can see that for a
3046 large program you would have to write dozens of such rules in your
3047 makefile. And, you must always be very careful to update the makefile
3048 every time you add or remove an @code{#include}.
3049 @cindex @code{#include}
3050
3051 @cindex @code{-M} (to compiler)
3052 To avoid this hassle, most modern C compilers can write these rules for
3053 you, by looking at the @code{#include} lines in the source files.
3054 Usually this is done with the @samp{-M} option to the compiler.
3055 For example, the command:
3056
3057 @example
3058 cc -M main.c
3059 @end example
3060
3061 @noindent
3062 generates the output:
3063
3064 @example
3065 main.o : main.c defs.h
3066 @end example
3067
3068 @noindent
3069 Thus you no longer have to write all those rules yourself.
3070 The compiler will do it for you.
3071
3072 Note that such a prerequisite constitutes mentioning @file{main.o} in a
3073 makefile, so it can never be considered an intermediate file by implicit
3074 rule search. This means that @code{make} won't ever remove the file
3075 after using it; @pxref{Chained Rules, ,Chains of Implicit Rules}.
3076
3077 @cindex @code{make depend}
3078 With old @code{make} programs, it was traditional practice to use this
3079 compiler feature to generate prerequisites on demand with a command like
3080 @samp{make depend}. That command would create a file @file{depend}
3081 containing all the automatically-generated prerequisites; then the
3082 makefile could use @code{include} to read them in (@pxref{Include}).
3083
3084 In GNU @code{make}, the feature of remaking makefiles makes this
3085 practice obsolete---you need never tell @code{make} explicitly to
3086 regenerate the prerequisites, because it always regenerates any makefile
3087 that is out of date. @xref{Remaking Makefiles}.
3088
3089 The practice we recommend for automatic prerequisite generation is to have
3090 one makefile corresponding to each source file. For each source file
3091 @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
3092 what files the object file @file{@var{name}.o} depends on. That way
3093 only the source files that have changed need to be rescanned to produce
3094 the new prerequisites.
3095
3096 Here is the pattern rule to generate a file of prerequisites (i.e., a makefile)
3097 called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
3098
3099 @smallexample
3100 @group
3101 %.d: %.c
3102 @set -e; rm -f $@@; \
3103 $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \
3104 sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \
3105 rm -f $@@.$$$$
3106 @end group
3107 @end smallexample
3108
3109 @noindent
3110 @xref{Pattern Rules}, for information on defining pattern rules. The
3111 @samp{-e} flag to the shell causes it to exit immediately if the
3112 @code{$(CC)} command (or any other command) fails (exits with a
3113 nonzero status).
3114 @cindex @code{-e} (shell flag)
3115
3116 @cindex @code{-MM} (to GNU compiler)
3117 With the GNU C compiler, you may wish to use the @samp{-MM} flag instead
3118 of @samp{-M}. This omits prerequisites on system header files.
3119 @xref{Preprocessor Options, , Options Controlling the Preprocessor,
3120 gcc.info, Using GNU CC}, for details.
3121
3122 @cindex @code{sed} (shell command)
3123 The purpose of the @code{sed} command is to translate (for example):
3124
3125 @example
3126 main.o : main.c defs.h
3127 @end example
3128
3129 @noindent
3130 into:
3131
3132 @example
3133 main.o main.d : main.c defs.h
3134 @end example
3135
3136 @noindent
3137 @cindex @code{.d}
3138 This makes each @samp{.d} file depend on all the source and header files
3139 that the corresponding @samp{.o} file depends on. @code{make} then
3140 knows it must regenerate the prerequisites whenever any of the source or
3141 header files changes.
3142
3143 Once you've defined the rule to remake the @samp{.d} files,
3144 you then use the @code{include} directive to read them all in.
3145 @xref{Include}. For example:
3146
3147 @example
3148 @group
3149 sources = foo.c bar.c
3150
3151 include $(sources:.c=.d)
3152 @end group
3153 @end example
3154
3155 @noindent
3156 (This example uses a substitution variable reference to translate the
3157 list of source files @samp{foo.c bar.c} into a list of prerequisite
3158 makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full
3159 information on substitution references.) Since the @samp{.d} files are
3160 makefiles like any others, @code{make} will remake them as necessary
3161 with no further work from you. @xref{Remaking Makefiles}.
3162
3163 Note that the @samp{.d} files contain target definitions; you should
3164 be sure to place the @code{include} directive @emph{after} the first,
3165 default target in your makefiles or run the risk of having a random
3166 object file become the default target.
3167 @xref{How Make Works}.
3168
3169 @node Commands, Using Variables, Rules, Top
3170 @chapter Writing the Commands in Rules
3171 @cindex commands, how to write
3172 @cindex rule commands
3173 @cindex writing rule commands
3174
3175 The commands of a rule consist of shell command lines to be executed one
3176 by one. Each command line must start with a tab, except that the first
3177 command line may be attached to the target-and-prerequisites line with a
3178 semicolon in between. Blank lines and lines of just comments may appear
3179 among the command lines; they are ignored. (But beware, an apparently
3180 ``blank'' line that begins with a tab is @emph{not} blank! It is an
3181 empty command; @pxref{Empty Commands}.)
3182
3183 Users use many different shell programs, but commands in makefiles are
3184 always interpreted by @file{/bin/sh} unless the makefile specifies
3185 otherwise. @xref{Execution, ,Command Execution}.
3186
3187 @cindex comments, in commands
3188 @cindex commands, comments in
3189 @cindex @code{#} (comments), in commands
3190 The shell that is in use determines whether comments can be written on
3191 command lines, and what syntax they use. When the shell is
3192 @file{/bin/sh}, a @samp{#} starts a comment that extends to the end of
3193 the line. The @samp{#} does not have to be at the beginning of a line.
3194 Text on a line before a @samp{#} is not part of the comment.
3195
3196 @menu
3197 * Echoing:: How to control when commands are echoed.
3198 * Execution:: How commands are executed.
3199 * Parallel:: How commands can be executed in parallel.
3200 * Errors:: What happens after a command execution error.
3201 * Interrupts:: What happens when a command is interrupted.
3202 * Recursion:: Invoking @code{make} from makefiles.
3203 * Sequences:: Defining canned sequences of commands.
3204 * Empty Commands:: Defining useful, do-nothing commands.
3205 @end menu
3206
3207 @node Echoing, Execution, Commands, Commands
3208 @section Command Echoing
3209 @cindex echoing of commands
3210 @cindex silent operation
3211 @cindex @code{@@} (in commands)
3212 @cindex commands, echoing
3213 @cindex printing of commands
3214
3215 Normally @code{make} prints each command line before it is executed.
3216 We call this @dfn{echoing} because it gives the appearance that you
3217 are typing the commands yourself.
3218
3219 When a line starts with @samp{@@}, the echoing of that line is suppressed.
3220 The @samp{@@} is discarded before the command is passed to the shell.
3221 Typically you would use this for a command whose only effect is to print
3222 something, such as an @code{echo} command to indicate progress through
3223 the makefile:
3224
3225 @example
3226 @@echo About to make distribution files
3227 @end example
3228
3229 @cindex @code{-n}
3230 @cindex @code{--just-print}
3231 @cindex @code{--dry-run}
3232 @cindex @code{--recon}
3233 When @code{make} is given the flag @samp{-n} or @samp{--just-print}
3234 it only echoes commands, it won't execute them. @xref{Options Summary,
3235 ,Summary of Options}. In this case and only this case, even the
3236 commands starting with @samp{@@} are printed. This flag is useful for
3237 finding out which commands @code{make} thinks are necessary without
3238 actually doing them.
3239
3240 @cindex @code{-s}
3241 @cindex @code{--silent}
3242 @cindex @code{--quiet}
3243 @findex .SILENT
3244 The @samp{-s} or @samp{--silent}
3245 flag to @code{make} prevents all echoing, as if all commands
3246 started with @samp{@@}. A rule in the makefile for the special target
3247 @code{.SILENT} without prerequisites has the same effect
3248 (@pxref{Special Targets, ,Special Built-in Target Names}).
3249 @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
3250
3251 @node Execution, Parallel, Echoing, Commands
3252 @section Command Execution
3253 @cindex commands, execution
3254 @cindex execution, of commands
3255 @cindex shell command, execution
3256 @vindex SHELL @r{(command execution)}
3257
3258 When it is time to execute commands to update a target, they are executed
3259 by making a new subshell for each line. (In practice, @code{make} may
3260 take shortcuts that do not affect the results.)
3261
3262 @cindex @code{cd} (shell command)
3263 @strong{Please note:} this implies that shell commands such as @code{cd}
3264 that set variables local to each process will not affect the following
3265 command lines. @footnote{On MS-DOS, the value of current working
3266 directory is @strong{global}, so changing it @emph{will} affect the
3267 following command lines on those systems.} If you want to use @code{cd}
3268 to affect the next command, put the two on a single line with a
3269 semicolon between them. Then @code{make} will consider them a single
3270 command and pass them, together, to a shell which will execute them in
3271 sequence. For example:
3272
3273 @example
3274 foo : bar/lose
3275 cd bar; gobble lose > ../foo
3276 @end example
3277
3278 @cindex commands, backslash (@code{\}) in
3279 @cindex commands, quoting newlines in
3280 @cindex backslash (@code{\}), in commands
3281 @cindex @code{\} (backslash), in commands
3282 @cindex quoting newline, in commands
3283 @cindex newline, quoting, in commands
3284 If you would like to split a single shell command into multiple lines of
3285 text, you must use a backslash at the end of all but the last subline.
3286 Such a sequence of lines is combined into a single line, by deleting the
3287 backslash-newline sequences, before passing it to the shell. Thus, the
3288 following is equivalent to the preceding example:
3289
3290 @example
3291 @group
3292 foo : bar/lose
3293 cd bar; \
3294 gobble lose > ../foo
3295 @end group
3296 @end example
3297
3298 @vindex SHELL
3299 The program used as the shell is taken from the variable @code{SHELL}.
3300 By default, the program @file{/bin/sh} is used.
3301
3302 @vindex COMSPEC
3303 On MS-DOS, if @code{SHELL} is not set, the value of the variable
3304 @code{COMSPEC} (which is always set) is used instead.
3305
3306 @cindex @code{SHELL}, MS-DOS specifics
3307 The processing of lines that set the variable @code{SHELL} in Makefiles
3308 is different on MS-DOS. The stock shell, @file{command.com}, is
3309 ridiculously limited in its functionality and many users of @code{make}
3310 tend to install a replacement shell. Therefore, on MS-DOS, @code{make}
3311 examines the value of @code{SHELL}, and changes its behavior based on
3312 whether it points to a Unix-style or DOS-style shell. This allows
3313 reasonable functionality even if @code{SHELL} points to
3314 @file{command.com}.
3315
3316 If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS
3317 additionally checks whether that shell can indeed be found; if not, it
3318 ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make}
3319 searches for the shell in the following places:
3320
3321 @enumerate
3322 @item
3323 In the precise place pointed to by the value of @code{SHELL}. For
3324 example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make}
3325 will look in the directory @file{/bin} on the current drive.
3326
3327 @item
3328 In the current directory.
3329
3330 @item
3331 In each of the directories in the @code{PATH} variable, in order.
3332
3333 @end enumerate
3334
3335 In every directory it examines, @code{make} will first look for the
3336 specific file (@file{sh} in the example above). If this is not found,
3337 it will also look in that directory for that file with one of the known
3338 extensions which identify executable files. For example @file{.exe},
3339 @file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others.
3340
3341 If any of these attempts is successful, the value of @code{SHELL} will
3342 be set to the full pathname of the shell as found. However, if none of
3343 these is found, the value of @code{SHELL} will not be changed, and thus
3344 the line that sets it will be effectively ignored. This is so
3345 @code{make} will only support features specific to a Unix-style shell if
3346 such a shell is actually installed on the system where @code{make} runs.
3347
3348 Note that this extended search for the shell is limited to the cases
3349 where @code{SHELL} is set from the Makefile; if it is set in the
3350 environment or command line, you are expected to set it to the full
3351 pathname of the shell, exactly as things are on Unix.
3352
3353 The effect of the above DOS-specific processing is that a Makefile that
3354 says @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
3355 on MS-DOS unaltered if you have e.g. @file{sh.exe} installed in some
3356 directory along your @code{PATH}.
3357
3358 @cindex environment, @code{SHELL} in
3359 Unlike most variables, the variable @code{SHELL} is never set from the
3360 environment. This is because the @code{SHELL} environment variable is
3361 used to specify your personal choice of shell program for interactive
3362 use. It would be very bad for personal choices like this to affect the
3363 functioning of makefiles. @xref{Environment, ,Variables from the
3364 Environment}. However, on MS-DOS and MS-Windows the value of
3365 @code{SHELL} in the environment @strong{is} used, since on those systems
3366 most users do not set this variable, and therefore it is most likely set
3367 specifically to be used by @code{make}. On MS-DOS, if the setting of
3368 @code{SHELL} is not suitable for @code{make}, you can set the variable
3369 @code{MAKESHELL} to the shell that @code{make} should use; this will
3370 override the value of @code{SHELL}.
3371
3372 @node Parallel, Errors, Execution, Commands
3373 @section Parallel Execution
3374 @cindex commands, execution in parallel
3375 @cindex parallel execution
3376 @cindex execution, in parallel
3377 @cindex job slots
3378 @cindex @code{-j}
3379 @cindex @code{--jobs}
3380
3381 GNU @code{make} knows how to execute several commands at once.
3382 Normally, @code{make} will execute only one command at a time, waiting
3383 for it to finish before executing the next. However, the @samp{-j} or
3384 @samp{--jobs} option tells @code{make} to execute many commands
3385 simultaneously.@refill
3386
3387 On MS-DOS, the @samp{-j} option has no effect, since that system doesn't
3388 support multi-processing.
3389
3390 If the @samp{-j} option is followed by an integer, this is the number of
3391 commands to execute at once; this is called the number of @dfn{job slots}.
3392 If there is nothing looking like an integer after the @samp{-j} option,
3393 there is no limit on the number of job slots. The default number of job
3394 slots is one, which means serial execution (one thing at a time).
3395
3396 One unpleasant consequence of running several commands simultaneously is
3397 that output generated by the commands appears whenever each command
3398 sends it, so messages from different commands may be interspersed.
3399
3400 Another problem is that two processes cannot both take input from the
3401 same device; so to make sure that only one command tries to take input
3402 from the terminal at once, @code{make} will invalidate the standard
3403 input streams of all but one running command. This means that
3404 attempting to read from standard input will usually be a fatal error (a
3405 @samp{Broken pipe} signal) for most child processes if there are
3406 several.
3407 @cindex broken pipe
3408 @cindex standard input
3409
3410 It is unpredictable which command will have a valid standard input stream
3411 (which will come from the terminal, or wherever you redirect the standard
3412 input of @code{make}). The first command run will always get it first, and
3413 the first command started after that one finishes will get it next, and so
3414 on.
3415
3416 We will change how this aspect of @code{make} works if we find a better
3417 alternative. In the mean time, you should not rely on any command using
3418 standard input at all if you are using the parallel execution feature; but
3419 if you are not using this feature, then standard input works normally in
3420 all commands.
3421
3422 Finally, handling recursive @code{make} invocations raises issues. For
3423 more information on this, see
3424 @ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
3425
3426 If a command fails (is killed by a signal or exits with a nonzero
3427 status), and errors are not ignored for that command
3428 (@pxref{Errors, ,Errors in Commands}),
3429 the remaining command lines to remake the same target will not be run.
3430 If a command fails and the @samp{-k} or @samp{--keep-going}
3431 option was not given
3432 (@pxref{Options Summary, ,Summary of Options}),
3433 @code{make} aborts execution. If make
3434 terminates for any reason (including a signal) with child processes
3435 running, it waits for them to finish before actually exiting.@refill
3436
3437 @cindex load average
3438 @cindex limiting jobs based on load
3439 @cindex jobs, limiting based on load
3440 @cindex @code{-l} (load average)
3441 @cindex @code{--max-load}
3442 @cindex @code{--load-average}
3443 When the system is heavily loaded, you will probably want to run fewer jobs
3444 than when it is lightly loaded. You can use the @samp{-l} option to tell
3445 @code{make} to limit the number of jobs to run at once, based on the load
3446 average. The @samp{-l} or @samp{--max-load}
3447 option is followed by a floating-point number. For
3448 example,
3449
3450 @example
3451 -l 2.5
3452 @end example
3453
3454 @noindent
3455 will not let @code{make} start more than one job if the load average is
3456 above 2.5. The @samp{-l} option with no following number removes the
3457 load limit, if one was given with a previous @samp{-l} option.@refill
3458
3459 More precisely, when @code{make} goes to start up a job, and it already has
3460 at least one job running, it checks the current load average; if it is not
3461 lower than the limit given with @samp{-l}, @code{make} waits until the load
3462 average goes below that limit, or until all the other jobs finish.
3463
3464 By default, there is no load limit.
3465
3466 @node Errors, Interrupts, Parallel, Commands
3467 @section Errors in Commands
3468 @cindex errors (in commands)
3469 @cindex commands, errors in
3470 @cindex exit status (errors)
3471
3472 After each shell command returns, @code{make} looks at its exit status.
3473 If the command completed successfully, the next command line is executed
3474 in a new shell; after the last command line is finished, the rule is
3475 finished.
3476
3477 If there is an error (the exit status is nonzero), @code{make} gives up on
3478 the current rule, and perhaps on all rules.
3479
3480 Sometimes the failure of a certain command does not indicate a problem.
3481 For example, you may use the @code{mkdir} command to ensure that a
3482 directory exists. If the directory already exists, @code{mkdir} will
3483 report an error, but you probably want @code{make} to continue regardless.
3484
3485 @cindex @code{-} (in commands)
3486 To ignore errors in a command line, write a @samp{-} at the beginning of
3487 the line's text (after the initial tab). The @samp{-} is discarded before
3488 the command is passed to the shell for execution.
3489
3490 For example,
3491
3492 @example
3493 @group
3494 clean:
3495 -rm -f *.o
3496 @end group
3497 @end example
3498 @cindex @code{rm} (shell command)
3499
3500 @noindent
3501 This causes @code{rm} to continue even if it is unable to remove a file.
3502
3503 @cindex @code{-i}
3504 @cindex @code{--ignore-errors}
3505 @findex .IGNORE
3506 When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
3507 flag, errors are ignored in all commands of all rules. A rule in the
3508 makefile for the special target @code{.IGNORE} has the same effect, if
3509 there are no prerequisites. These ways of ignoring errors are obsolete
3510 because @samp{-} is more flexible.
3511
3512 When errors are to be ignored, because of either a @samp{-} or the
3513 @samp{-i} flag, @code{make} treats an error return just like success,
3514 except that it prints out a message that tells you the status code
3515 the command exited with, and says that the error has been ignored.
3516
3517 When an error happens that @code{make} has not been told to ignore,
3518 it implies that the current target cannot be correctly remade, and neither
3519 can any other that depends on it either directly or indirectly. No further
3520 commands will be executed for these targets, since their preconditions
3521 have not been achieved.
3522
3523
3524 @cindex @code{-k}
3525 @cindex @code{--keep-going}
3526 Normally @code{make} gives up immediately in this circumstance, returning a
3527 nonzero status. However, if the @samp{-k} or @samp{--keep-going}
3528 flag is specified, @code{make}
3529 continues to consider the other prerequisites of the pending targets,
3530 remaking them if necessary, before it gives up and returns nonzero status.
3531 For example, after an error in compiling one object file, @samp{make -k}
3532 will continue compiling other object files even though it already knows
3533 that linking them will be impossible. @xref{Options Summary, ,Summary of Options}.
3534
3535 The usual behavior assumes that your purpose is to get the specified
3536 targets up to date; once @code{make} learns that this is impossible, it
3537 might as well report the failure immediately. The @samp{-k} option says
3538 that the real purpose is to test as many of the changes made in the
3539 program as possible, perhaps to find several independent problems so
3540 that you can correct them all before the next attempt to compile. This
3541 is why Emacs' @code{compile} command passes the @samp{-k} flag by
3542 default.
3543 @cindex Emacs (@code{M-x compile})
3544
3545 @findex .DELETE_ON_ERROR
3546 @cindex deletion of target files
3547 @cindex removal of target files
3548 @cindex target, deleting on error
3549 Usually when a command fails, if it has changed the target file at all,
3550 the file is corrupted and cannot be used---or at least it is not
3551 completely updated. Yet the file's time stamp says that it is now up to
3552 date, so the next time @code{make} runs, it will not try to update that
3553 file. The situation is just the same as when the command is killed by a
3554 signal; @pxref{Interrupts}. So generally the right thing to do is to
3555 delete the target file if the command fails after beginning to change
3556 the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears
3557 as a target. This is almost always what you want @code{make} to do, but
3558 it is not historical practice; so for compatibility, you must explicitly
3559 request it.
3560
3561 @node Interrupts, Recursion, Errors, Commands
3562 @section Interrupting or Killing @code{make}
3563 @cindex interrupt
3564 @cindex signal
3565 @cindex deletion of target files
3566 @cindex removal of target files
3567 @cindex target, deleting on interrupt
3568 @cindex killing (interruption)
3569
3570 If @code{make} gets a fatal signal while a command is executing, it may
3571 delete the target file that the command was supposed to update. This is
3572 done if the target file's last-modification time has changed since
3573 @code{make} first checked it.
3574
3575 The purpose of deleting the target is to make sure that it is remade from
3576 scratch when @code{make} is next run. Why is this? Suppose you type
3577 @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
3578 object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting
3579 in an incomplete file whose last-modification time is newer than the source
3580 file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal
3581 and deletes this incomplete file. If @code{make} did not do this, the next
3582 invocation of @code{make} would think that @file{foo.o} did not require
3583 updating---resulting in a strange error message from the linker when it
3584 tries to link an object file half of which is missing.
3585
3586 @findex .PRECIOUS
3587 You can prevent the deletion of a target file in this way by making the
3588 special target @code{.PRECIOUS} depend on it. Before remaking a target,
3589 @code{make} checks to see whether it appears on the prerequisites of
3590 @code{.PRECIOUS}, and thereby decides whether the target should be deleted
3591 if a signal happens. Some reasons why you might do this are that the
3592 target is updated in some atomic fashion, or exists only to record a
3593 modification-time (its contents do not matter), or must exist at all
3594 times to prevent other sorts of trouble.
3595
3596 @node Recursion, Sequences, Interrupts, Commands
3597 @section Recursive Use of @code{make}
3598 @cindex recursion
3599 @cindex subdirectories, recursion for
3600
3601 Recursive use of @code{make} means using @code{make} as a command in a
3602 makefile. This technique is useful when you want separate makefiles for
3603 various subsystems that compose a larger system. For example, suppose you
3604 have a subdirectory @file{subdir} which has its own makefile, and you would
3605 like the containing directory's makefile to run @code{make} on the
3606 subdirectory. You can do it by writing this:
3607
3608 @example
3609 subsystem:
3610 cd subdir && $(MAKE)
3611 @end example
3612
3613 @noindent
3614 or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
3615
3616 @example
3617 subsystem:
3618 $(MAKE) -C subdir
3619 @end example
3620 @cindex @code{-C}
3621 @cindex @code{--directory}
3622
3623 You can write recursive @code{make} commands just by copying this example,
3624 but there are many things to know about how they work and why, and about
3625 how the sub-@code{make} relates to the top-level @code{make}. You may
3626 also find it useful to declare targets that invoke recursive
3627 @code{make} commands as @samp{.PHONY} (for more discussion on when
3628 this is useful, see @ref{Phony Targets}).
3629
3630 @vindex @code{CURDIR}
3631 For your convenience, when GNU @code{make} starts (after it has
3632 processed any @code{-C} options) it sets the variable @code{CURDIR} to
3633 the pathname of the current working directory. This value is never
3634 touched by @code{make} again: in particular note that if you include
3635 files from other directories the value of @code{CURDIR} does not
3636 change. The value has the same precedence it would have if it were
3637 set in the makefile (by default, an environment variable @code{CURDIR}
3638 will not override this value). Note that setting this variable has no
3639 impact on the operation of @code{make} (it does not cause @code{make}
3640 to change its working directory, for example).
3641
3642 @menu
3643 * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
3644 * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
3645 * Options/Recursion:: How to communicate options to a sub-@code{make}.
3646 * -w Option:: How the @samp{-w} or @samp{--print-directory} option
3647 helps debug use of recursive @code{make} commands.
3648 @end menu
3649
3650 @node MAKE Variable, Variables/Recursion, Recursion, Recursion
3651 @subsection How the @code{MAKE} Variable Works
3652 @vindex MAKE
3653 @cindex recursion, and @code{MAKE} variable
3654
3655 Recursive @code{make} commands should always use the variable @code{MAKE},
3656 not the explicit command name @samp{make}, as shown here:
3657
3658 @example
3659 @group
3660 subsystem:
3661 cd subdir && $(MAKE)
3662 @end group
3663 @end example
3664
3665 The value of this variable is the file name with which @code{make} was
3666 invoked. If this file name was @file{/bin/make}, then the command executed
3667 is @samp{cd subdir && /bin/make}. If you use a special version of
3668 @code{make} to run the top-level makefile, the same special version will be
3669 executed for recursive invocations.
3670 @cindex @code{cd} (shell command)
3671
3672 @cindex +, and commands
3673 As a special feature, using the variable @code{MAKE} in the commands of
3674 a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
3675 (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
3676 Using the @code{MAKE} variable has the same effect as using a @samp{+}
3677 character at the beginning of the command line. @xref{Instead of
3678 Execution, ,Instead of Executing the Commands}.@refill
3679
3680 Consider the command @samp{make -t} in the above example. (The
3681 @samp{-t} option marks targets as up to date without actually running
3682 any commands; see @ref{Instead of Execution}.) Following the usual
3683 definition of @samp{-t}, a @samp{make -t} command in the example would
3684 create a file named @file{subsystem} and do nothing else. What you
3685 really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would
3686 require executing the command, and @samp{-t} says not to execute
3687 commands.@refill
3688 @cindex @code{-t}, and recursion
3689 @cindex recursion, and @code{-t}
3690 @cindex @code{--touch}, and recursion
3691
3692 The special feature makes this do what you want: whenever a command
3693 line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
3694 @samp{-n} and @samp{-q} do not apply to that line. Command lines
3695 containing @code{MAKE} are executed normally despite the presence of a
3696 flag that causes most commands not to be run. The usual
3697 @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
3698 (@pxref{Options/Recursion, ,Communicating Options to a
3699 Sub-@code{make}}), so your request to touch the files, or print the
3700 commands, is propagated to the subsystem.@refill
3701
3702 @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
3703 @subsection Communicating Variables to a Sub-@code{make}
3704 @cindex sub-@code{make}
3705 @cindex environment, and recursion
3706 @cindex exporting variables
3707 @cindex variables, environment
3708 @cindex variables, exporting
3709 @cindex recursion, and environment
3710 @cindex recursion, and variables
3711
3712 Variable values of the top-level @code{make} can be passed to the
3713 sub-@code{make} through the environment by explicit request. These
3714 variables are defined in the sub-@code{make} as defaults, but do not
3715 override what is specified in the makefile used by the sub-@code{make}
3716 makefile unless you use the @samp{-e} switch (@pxref{Options Summary,
3717 ,Summary of Options}).@refill
3718
3719 To pass down, or @dfn{export}, a variable, @code{make} adds the variable
3720 and its value to the environment for running each command. The
3721 sub-@code{make}, in turn, uses the environment to initialize its table
3722 of variable values. @xref{Environment, ,Variables from the
3723 Environment}.
3724
3725 Except by explicit request, @code{make} exports a variable only if it
3726 is either defined in the environment initially or set on the command
3727 line, and if its name consists only of letters, numbers, and underscores.
3728 Some shells cannot cope with environment variable names consisting of
3729 characters other than letters, numbers, and underscores.
3730
3731 The special variables @code{SHELL} and @code{MAKEFLAGS} are always
3732 exported (unless you unexport them).
3733 @code{MAKEFILES} is exported if you set it to anything.
3734
3735 @code{make} automatically passes down variable values that were defined
3736 on the command line, by putting them in the @code{MAKEFLAGS} variable.
3737 @iftex
3738 See the next section.
3739 @end iftex
3740 @ifinfo
3741 @xref{Options/Recursion}.
3742 @end ifinfo
3743
3744 Variables are @emph{not} normally passed down if they were created by
3745 default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
3746 Implicit Rules}). The sub-@code{make} will define these for
3747 itself.@refill
3748
3749 @findex export
3750 If you want to export specific variables to a sub-@code{make}, use the
3751 @code{export} directive, like this:
3752
3753 @example
3754 export @var{variable} @dots{}
3755 @end example
3756
3757 @noindent
3758 @findex unexport
3759 If you want to @emph{prevent} a variable from being exported, use the
3760 @code{unexport} directive, like this:
3761
3762 @example
3763 unexport @var{variable} @dots{}
3764 @end example
3765
3766 @noindent
3767 In both of these forms, the arguments to @code{export} and
3768 @code{unexport} are expanded, and so could be variables or functions
3769 which expand to a (list of) variable names to be (un)exported.
3770
3771 As a convenience, you can define a variable and export it at the same
3772 time by doing:
3773
3774 @example
3775 export @var{variable} = value
3776 @end example
3777
3778 @noindent
3779 has the same result as:
3780
3781 @example
3782 @var{variable} = value
3783 export @var{variable}
3784 @end example
3785
3786 @noindent
3787 and
3788
3789 @example
3790 export @var{variable} := value
3791 @end example
3792
3793 @noindent
3794 has the same result as:
3795
3796 @example
3797 @var{variable} := value
3798 export @var{variable}
3799 @end example
3800
3801 Likewise,
3802
3803 @example
3804 export @var{variable} += value
3805 @end example
3806
3807 @noindent
3808 is just like:
3809
3810 @example
3811 @var{variable} += value
3812 export @var{variable}
3813 @end example
3814
3815 @noindent
3816 @xref{Appending, ,Appending More Text to Variables}.
3817
3818 You may notice that the @code{export} and @code{unexport} directives
3819 work in @code{make} in the same way they work in the shell, @code{sh}.
3820
3821 If you want all variables to be exported by default, you can use
3822 @code{export} by itself:
3823
3824 @example
3825 export
3826 @end example
3827
3828 @noindent
3829 This tells @code{make} that variables which are not explicitly mentioned
3830 in an @code{export} or @code{unexport} directive should be exported.
3831 Any variable given in an @code{unexport} directive will still @emph{not}
3832 be exported. If you use @code{export} by itself to export variables by
3833 default, variables whose names contain characters other than
3834 alphanumerics and underscores will not be exported unless specifically
3835 mentioned in an @code{export} directive.@refill
3836
3837 @findex .EXPORT_ALL_VARIABLES
3838 The behavior elicited by an @code{export} directive by itself was the
3839 default in older versions of GNU @code{make}. If your makefiles depend
3840 on this behavior and you want to be compatible with old versions of
3841 @code{make}, you can write a rule for the special target
3842 @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
3843 This will be ignored by old @code{make}s, while the @code{export}
3844 directive will cause a syntax error.@refill
3845 @cindex compatibility in exporting
3846
3847 Likewise, you can use @code{unexport} by itself to tell @code{make}
3848 @emph{not} to export variables by default. Since this is the default
3849 behavior, you would only need to do this if @code{export} had been used
3850 by itself earlier (in an included makefile, perhaps). You
3851 @strong{cannot} use @code{export} and @code{unexport} by themselves to
3852 have variables exported for some commands and not for others. The last
3853 @code{export} or @code{unexport} directive that appears by itself
3854 determines the behavior for the entire run of @code{make}.@refill
3855
3856 @vindex MAKELEVEL
3857 @cindex recursion, level of
3858 As a special feature, the variable @code{MAKELEVEL} is changed when it
3859 is passed down from level to level. This variable's value is a string
3860 which is the depth of the level as a decimal number. The value is
3861 @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
3862 @samp{2} for a sub-sub-@code{make}, and so on. The incrementation
3863 happens when @code{make} sets up the environment for a command.@refill
3864
3865 The main use of @code{MAKELEVEL} is to test it in a conditional
3866 directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
3867 way you can write a makefile that behaves one way if run recursively and
3868 another way if run directly by you.@refill
3869
3870 @vindex MAKEFILES
3871 You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
3872 commands to use additional makefiles. The value of @code{MAKEFILES} is
3873 a whitespace-separated list of file names. This variable, if defined in
3874 the outer-level makefile, is passed down through the environment; then
3875 it serves as a list of extra makefiles for the sub-@code{make} to read
3876 before the usual or specified ones. @xref{MAKEFILES Variable, ,The
3877 Variable @code{MAKEFILES}}.@refill
3878
3879 @node Options/Recursion, -w Option, Variables/Recursion, Recursion
3880 @subsection Communicating Options to a Sub-@code{make}
3881 @cindex options, and recursion
3882 @cindex recursion, and options
3883
3884 @vindex MAKEFLAGS
3885 Flags such as @samp{-s} and @samp{-k} are passed automatically to the
3886 sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
3887 set up automatically by @code{make} to contain the flag letters that
3888 @code{make} received. Thus, if you do @w{@samp{make -ks}} then
3889 @code{MAKEFLAGS} gets the value @samp{ks}.@refill
3890
3891 As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
3892 in its environment. In response, it takes the flags from that value and
3893 processes them as if they had been given as arguments.
3894 @xref{Options Summary, ,Summary of Options}.
3895
3896 @cindex command line variable definitions, and recursion
3897 @cindex variables, command line, and recursion
3898 @cindex recursion, and command line variable definitions
3899 Likewise variables defined on the command line are passed to the
3900 sub-@code{make} through @code{MAKEFLAGS}. Words in the value of
3901 @code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable
3902 definitions just as if they appeared on the command line.
3903 @xref{Overriding, ,Overriding Variables}.
3904
3905 @cindex @code{-C}, and recursion
3906 @cindex @code{-f}, and recursion
3907 @cindex @code{-o}, and recursion
3908 @cindex @code{-W}, and recursion
3909 @cindex @code{--directory}, and recursion
3910 @cindex @code{--file}, and recursion
3911 @cindex @code{--old-file}, and recursion
3912 @cindex @code{--assume-old}, and recursion
3913 @cindex @code{--assume-new}, and recursion
3914 @cindex @code{--new-file}, and recursion
3915 @cindex recursion, and @code{-C}
3916 @cindex recursion, and @code{-f}
3917 @cindex recursion, and @code{-o}
3918 @cindex recursion, and @code{-W}
3919 The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put
3920 into @code{MAKEFLAGS}; these options are not passed down.@refill
3921
3922 @cindex @code{-j}, and recursion
3923 @cindex @code{--jobs}, and recursion
3924 @cindex recursion, and @code{-j}
3925 @cindex job slots, and recursion
3926 The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
3927 If you set it to some numeric value @samp{N} and your operating system
3928 supports it (most any UNIX system will; others typically won't), the
3929 parent @code{make} and all the sub-@code{make}s will communicate to
3930 ensure that there are only @samp{N} jobs running at the same time
3931 between them all. Note that any job that is marked recursive
3932 (@pxref{Instead of Execution, ,Instead of Executing the Commands})
3933 doesn't count against the total jobs (otherwise we could get @samp{N}
3934 sub-@code{make}s running and have no slots left over for any real work!)
3935
3936 If your operating system doesn't support the above communication, then
3937 @samp{-j 1} is always put into @code{MAKEFLAGS} instead of the value you
3938 specified. This is because if the @w{@samp{-j}} option were passed down
3939 to sub-@code{make}s, you would get many more jobs running in parallel
3940 than you asked for. If you give @samp{-j} with no numeric argument,
3941 meaning to run as many jobs as possible in parallel, this is passed
3942 down, since multiple infinities are no more than one.@refill
3943
3944 If you do not want to pass the other flags down, you must change the
3945 value of @code{MAKEFLAGS}, like this:
3946
3947 @example
3948 subsystem:
3949 cd subdir && $(MAKE) MAKEFLAGS=
3950 @end example
3951
3952 @vindex MAKEOVERRIDES
3953 The command line variable definitions really appear in the variable
3954 @code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this
3955 variable. If you do want to pass flags down normally, but don't want to
3956 pass down the command line variable definitions, you can reset
3957 @code{MAKEOVERRIDES} to empty, like this:
3958
3959 @example
3960 MAKEOVERRIDES =
3961 @end example
3962
3963 @noindent
3964 @cindex Arg list too long
3965 @cindex E2BIG
3966 This is not usually useful to do. However, some systems have a small
3967 fixed limit on the size of the environment, and putting so much
3968 information into the value of @code{MAKEFLAGS} can exceed it. If you
3969 see the error message @samp{Arg list too long}, this may be the problem.
3970 @findex .POSIX
3971 @cindex POSIX.2
3972 (For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does
3973 not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears
3974 in the makefile. You probably do not care about this.)
3975
3976 @vindex MFLAGS
3977 A similar variable @code{MFLAGS} exists also, for historical
3978 compatibility. It has the same value as @code{MAKEFLAGS} except that it
3979 does not contain the command line variable definitions, and it always
3980 begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a
3981 hyphen only when it begins with an option that has no single-letter
3982 version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was
3983 traditionally used explicitly in the recursive @code{make} command, like
3984 this:
3985
3986 @example
3987 subsystem:
3988 cd subdir && $(MAKE) $(MFLAGS)
3989 @end example
3990
3991 @noindent
3992 but now @code{MAKEFLAGS} makes this usage redundant. If you want your
3993 makefiles to be compatible with old @code{make} programs, use this
3994 technique; it will work fine with more modern @code{make} versions too.
3995
3996 @cindex setting options from environment
3997 @cindex options, setting from environment
3998 @cindex setting options in makefiles
3999 @cindex options, setting in makefiles
4000 The @code{MAKEFLAGS} variable can also be useful if you want to have
4001 certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
4002 Options}), set each time you run @code{make}. You simply put a value for
4003 @code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in
4004 a makefile, to specify additional flags that should also be in effect for
4005 that makefile. (Note that you cannot use @code{MFLAGS} this way. That
4006 variable is set only for compatibility; @code{make} does not interpret a
4007 value you set for it in any way.)
4008
4009 When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
4010 environment or from a makefile), it first prepends a hyphen if the value
4011 does not already begin with one. Then it chops the value into words
4012 separated by blanks, and parses these words as if they were options given
4013 on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
4014 @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
4015 is no error for an invalid option).
4016
4017 If you do put @code{MAKEFLAGS} in your environment, you should be sure not
4018 to include any options that will drastically affect the actions of
4019 @code{make} and undermine the purpose of makefiles and of @code{make}
4020 itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
4021 put in one of these variables, could have disastrous consequences and would
4022 certainly have at least surprising and probably annoying effects.@refill
4023
4024 @node -w Option, , Options/Recursion, Recursion
4025 @subsection The @samp{--print-directory} Option
4026 @cindex directories, printing them
4027 @cindex printing directories
4028 @cindex recursion, and printing directories
4029
4030 If you use several levels of recursive @code{make} invocations, the
4031 @samp{-w} or @w{@samp{--print-directory}} option can make the output a
4032 lot easier to understand by showing each directory as @code{make}
4033 starts processing it and as @code{make} finishes processing it. For
4034 example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
4035 @code{make} will print a line of the form:@refill
4036
4037 @example
4038 make: Entering directory `/u/gnu/make'.
4039 @end example
4040
4041 @noindent
4042 before doing anything else, and a line of the form:
4043
4044 @example
4045 make: Leaving directory `/u/gnu/make'.
4046 @end example
4047
4048 @noindent
4049 when processing is completed.
4050
4051 @cindex @code{-C}, and @code{-w}
4052 @cindex @code{--directory}, and @code{--print-directory}
4053 @cindex recursion, and @code{-w}
4054 @cindex @code{-w}, and @code{-C}
4055 @cindex @code{-w}, and recursion
4056 @cindex @code{--print-directory}, and @code{--directory}
4057 @cindex @code{--print-directory}, and recursion
4058 @cindex @code{--no-print-directory}
4059 @cindex @code{--print-directory}, disabling
4060 @cindex @code{-w}, disabling
4061 Normally, you do not need to specify this option because @samp{make}
4062 does it for you: @samp{-w} is turned on automatically when you use the
4063 @samp{-C} option, and in sub-@code{make}s. @code{make} will not
4064 automatically turn on @samp{-w} if you also use @samp{-s}, which says to
4065 be silent, or if you use @samp{--no-print-directory} to explicitly
4066 disable it.
4067
4068 @node Sequences, Empty Commands, Recursion, Commands
4069 @section Defining Canned Command Sequences
4070 @cindex sequences of commands
4071 @cindex commands, sequences of
4072
4073 When the same sequence of commands is useful in making various targets, you
4074 can define it as a canned sequence with the @code{define} directive, and
4075 refer to the canned sequence from the rules for those targets. The canned
4076 sequence is actually a variable, so the name must not conflict with other
4077 variable names.
4078
4079 Here is an example of defining a canned sequence of commands:
4080
4081 @example
4082 define run-yacc
4083 yacc $(firstword $^)
4084 mv y.tab.c $@@
4085 endef
4086 @end example
4087 @cindex @code{yacc}
4088
4089 @noindent
4090 Here @code{run-yacc} is the name of the variable being defined;
4091 @code{endef} marks the end of the definition; the lines in between are the
4092 commands. The @code{define} directive does not expand variable references
4093 and function calls in the canned sequence; the @samp{$} characters,
4094 parentheses, variable names, and so on, all become part of the value of the
4095 variable you are defining.
4096 @xref{Defining, ,Defining Variables Verbatim},
4097 for a complete explanation of @code{define}.
4098
4099 The first command in this example runs Yacc on the first prerequisite of
4100 whichever rule uses the canned sequence. The output file from Yacc is
4101 always named @file{y.tab.c}. The second command moves the output to the
4102 rule's target file name.
4103
4104 To use the canned sequence, substitute the variable into the commands of a
4105 rule. You can substitute it like any other variable
4106 (@pxref{Reference, ,Basics of Variable References}).
4107 Because variables defined by @code{define} are recursively expanded
4108 variables, all the variable references you wrote inside the @code{define}
4109 are expanded now. For example:
4110
4111 @example
4112 foo.c : foo.y
4113 $(run-yacc)
4114 @end example
4115
4116 @noindent
4117 @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
4118 @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
4119
4120 This is a realistic example, but this particular one is not needed in
4121 practice because @code{make} has an implicit rule to figure out these
4122 commands based on the file names involved
4123 (@pxref{Implicit Rules, ,Using Implicit Rules}).
4124
4125 @cindex @@, and @code{define}
4126 @cindex -, and @code{define}
4127 @cindex +, and @code{define}
4128 In command execution, each line of a canned sequence is treated just as
4129 if the line appeared on its own in the rule, preceded by a tab. In
4130 particular, @code{make} invokes a separate subshell for each line. You
4131 can use the special prefix characters that affect command lines
4132 (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
4133 @xref{Commands, ,Writing the Commands in Rules}.
4134 For example, using this canned sequence:
4135
4136 @example
4137 define frobnicate
4138 @@echo "frobnicating target $@@"
4139 frob-step-1 $< -o $@@-step-1
4140 frob-step-2 $@@-step-1 -o $@@
4141 endef
4142 @end example
4143
4144 @noindent
4145 @code{make} will not echo the first line, the @code{echo} command.
4146 But it @emph{will} echo the following two command lines.
4147
4148 On the other hand, prefix characters on the command line that refers to
4149 a canned sequence apply to every line in the sequence. So the rule:
4150
4151 @example
4152 frob.out: frob.in
4153 @@$(frobnicate)
4154 @end example
4155
4156 @noindent
4157 does not echo @emph{any} commands.
4158 (@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.)
4159
4160 @node Empty Commands, , Sequences, Commands
4161 @section Using Empty Commands
4162 @cindex empty commands
4163 @cindex commands, empty
4164
4165 It is sometimes useful to define commands which do nothing. This is done
4166 simply by giving a command that consists of nothing but whitespace. For
4167 example:
4168
4169 @example
4170 target: ;
4171 @end example
4172
4173 @noindent
4174 defines an empty command string for @file{target}. You could also use a
4175 line beginning with a tab character to define an empty command string,
4176 but this would be confusing because such a line looks empty.
4177
4178 @findex .DEFAULT@r{, and empty commands}
4179 You may be wondering why you would want to define a command string that
4180 does nothing. The only reason this is useful is to prevent a target
4181 from getting implicit commands (from implicit rules or the
4182 @code{.DEFAULT} special target; @pxref{Implicit Rules} and
4183 @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill
4184
4185 @c !!! another reason is for canonical stamp files:
4186 @ignore
4187 @example
4188 foo: stamp-foo ;
4189 stamp-foo: foo.in
4190 create foo frm foo.in
4191 touch $@
4192 @end example
4193 @end ignore
4194
4195 You may be inclined to define empty command strings for targets that are
4196 not actual files, but only exist so that their prerequisites can be
4197 remade. However, this is not the best way to do that, because the
4198 prerequisites may not be remade properly if the target file actually does exist.
4199 @xref{Phony Targets, ,Phony Targets}, for a better way to do this.
4200
4201 @node Using Variables, Conditionals, Commands, Top
4202 @chapter How to Use Variables
4203 @cindex variable
4204 @cindex value
4205 @cindex recursive variable expansion
4206 @cindex simple variable expansion
4207
4208 A @dfn{variable} is a name defined in a makefile to represent a string
4209 of text, called the variable's @dfn{value}. These values are
4210 substituted by explicit request into targets, prerequisites, commands,
4211 and other parts of the makefile. (In some other versions of @code{make},
4212 variables are called @dfn{macros}.)
4213 @cindex macro
4214
4215 Variables and functions in all parts of a makefile are expanded when
4216 read, except for the shell commands in rules, the right-hand sides of
4217 variable definitions using @samp{=}, and the bodies of variable
4218 definitions using the @code{define} directive.@refill
4219
4220 Variables can represent lists of file names, options to pass to compilers,
4221 programs to run, directories to look in for source files, directories to
4222 write output in, or anything else you can imagine.
4223
4224 A variable name may be any sequence of characters not containing @samp{:},
4225 @samp{#}, @samp{=}, or leading or trailing whitespace. However,
4226 variable names containing characters other than letters, numbers, and
4227 underscores should be avoided, as they may be given special meanings in the
4228 future, and with some shells they cannot be passed through the environment to a
4229 sub-@code{make}
4230 (@pxref{Variables/Recursion, ,Communicating Variables to a Sub-@code{make}}).
4231
4232 Variable names are case-sensitive. The names @samp{foo}, @samp{FOO},
4233 and @samp{Foo} all refer to different variables.
4234
4235 It is traditional to use upper case letters in variable names, but we
4236 recommend using lower case letters for variable names that serve internal
4237 purposes in the makefile, and reserving upper case for parameters that
4238 control implicit rules or for parameters that the user should override with
4239 command options (@pxref{Overriding, ,Overriding Variables}).
4240
4241 A few variables have names that are a single punctuation character or
4242 just a few characters. These are the @dfn{automatic variables}, and
4243 they have particular specialized uses. @xref{Automatic Variables}.
4244
4245 @menu
4246 * Reference:: How to use the value of a variable.
4247 * Flavors:: Variables come in two flavors.
4248 * Advanced:: Advanced features for referencing a variable.
4249 * Values:: All the ways variables get their values.
4250 * Setting:: How to set a variable in the makefile.
4251 * Appending:: How to append more text to the old value
4252 of a variable.
4253 * Override Directive:: How to set a variable in the makefile even if
4254 the user has set it with a command argument.
4255 * Defining:: An alternate way to set a variable
4256 to a verbatim string.
4257 * Environment:: Variable values can come from the environment.
4258 * Target-specific:: Variable values can be defined on a per-target
4259 basis.
4260 * Pattern-specific:: Target-specific variable values can be applied
4261 to a group of targets that match a pattern.
4262 @end menu
4263
4264 @node Reference, Flavors, Using Variables, Using Variables
4265 @section Basics of Variable References
4266 @cindex variables, how to reference
4267 @cindex reference to variables
4268 @cindex @code{$}, in variable reference
4269 @cindex dollar sign (@code{$}), in variable reference
4270
4271 To substitute a variable's value, write a dollar sign followed by the name
4272 of the variable in parentheses or braces: either @samp{$(foo)} or
4273 @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This
4274 special significance of @samp{$} is why you must write @samp{$$} to have
4275 the effect of a single dollar sign in a file name or command.
4276
4277 Variable references can be used in any context: targets, prerequisites,
4278 commands, most directives, and new variable values. Here is an
4279 example of a common case, where a variable holds the names of all the
4280 object files in a program:
4281
4282 @example
4283 @group
4284 objects = program.o foo.o utils.o
4285 program : $(objects)
4286 cc -o program $(objects)
4287
4288 $(objects) : defs.h
4289 @end group
4290 @end example
4291
4292 Variable references work by strict textual substitution. Thus, the rule
4293
4294 @example
4295 @group
4296 foo = c
4297 prog.o : prog.$(foo)
4298 $(foo)$(foo) -$(foo) prog.$(foo)
4299 @end group
4300 @end example
4301
4302 @noindent
4303 could be used to compile a C program @file{prog.c}. Since spaces before
4304 the variable value are ignored in variable assignments, the value of
4305 @code{foo} is precisely @samp{c}. (Don't actually write your makefiles
4306 this way!)
4307
4308 A dollar sign followed by a character other than a dollar sign,
4309 open-parenthesis or open-brace treats that single character as the
4310 variable name. Thus, you could reference the variable @code{x} with
4311 @samp{$x}. However, this practice is strongly discouraged, except in
4312 the case of the automatic variables (@pxref{Automatic Variables}).
4313
4314 @node Flavors, Advanced, Reference, Using Variables
4315 @section The Two Flavors of Variables
4316 @cindex flavors of variables
4317 @cindex recursive variable expansion
4318 @cindex variables, flavors
4319 @cindex recursively expanded variables
4320 @cindex variables, recursively expanded
4321
4322 There are two ways that a variable in GNU @code{make} can have a value;
4323 we call them the two @dfn{flavors} of variables. The two flavors are
4324 distinguished in how they are defined and in what they do when expanded.
4325
4326 @cindex =
4327 The first flavor of variable is a @dfn{recursively expanded} variable.
4328 Variables of this sort are defined by lines using @samp{=}
4329 (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
4330 (@pxref{Defining, ,Defining Variables Verbatim}). The value you specify
4331 is installed verbatim; if it contains references to other variables,
4332 these references are expanded whenever this variable is substituted (in
4333 the course of expanding some other string). When this happens, it is
4334 called @dfn{recursive expansion}.@refill
4335
4336 For example,
4337
4338 @example
4339 foo = $(bar)
4340 bar = $(ugh)
4341 ugh = Huh?
4342
4343 all:;echo $(foo)
4344 @end example
4345
4346 @noindent
4347 will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
4348 expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
4349
4350 This flavor of variable is the only sort supported by other versions of
4351 @code{make}. It has its advantages and its disadvantages. An advantage
4352 (most would say) is that:
4353
4354 @example
4355 CFLAGS = $(include_dirs) -O
4356 include_dirs = -Ifoo -Ibar
4357 @end example
4358
4359 @noindent
4360 will do what was intended: when @samp{CFLAGS} is expanded in a command,
4361 it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you
4362 cannot append something on the end of a variable, as in
4363
4364 @example
4365 CFLAGS = $(CFLAGS) -O
4366 @end example
4367
4368 @noindent
4369 because it will cause an infinite loop in the variable expansion.
4370 (Actually @code{make} detects the infinite loop and reports an error.)
4371 @cindex loops in variable expansion
4372 @cindex variables, loops in expansion
4373
4374 Another disadvantage is that any functions
4375 (@pxref{Functions, ,Functions for Transforming Text})
4376 referenced in the definition will be executed every time the variable is
4377 expanded. This makes @code{make} run slower; worse, it causes the
4378 @code{wildcard} and @code{shell} functions to give unpredictable results
4379 because you cannot easily control when they are called, or even how many
4380 times.
4381
4382 To avoid all the problems and inconveniences of recursively expanded
4383 variables, there is another flavor: simply expanded variables.
4384
4385 @cindex simply expanded variables
4386 @cindex variables, simply expanded
4387 @cindex :=
4388 @dfn{Simply expanded variables} are defined by lines using @samp{:=}
4389 (@pxref{Setting, ,Setting Variables}).
4390 The value of a simply expanded variable is scanned
4391 once and for all, expanding any references to other variables and
4392 functions, when the variable is defined. The actual value of the simply
4393 expanded variable is the result of expanding the text that you write.
4394 It does not contain any references to other variables; it contains their
4395 values @emph{as of the time this variable was defined}. Therefore,
4396
4397 @example
4398 x := foo
4399 y := $(x) bar
4400 x := later
4401 @end example
4402
4403 @noindent
4404 is equivalent to
4405
4406 @example
4407 y := foo bar
4408 x := later
4409 @end example
4410
4411 When a simply expanded variable is referenced, its value is substituted
4412 verbatim.
4413
4414 Here is a somewhat more complicated example, illustrating the use of
4415 @samp{:=} in conjunction with the @code{shell} function.
4416 (@xref{Shell Function, , The @code{shell} Function}.) This example
4417 also shows use of the variable @code{MAKELEVEL}, which is changed
4418 when it is passed down from level to level.
4419 (@xref{Variables/Recursion, , Communicating Variables to a
4420 Sub-@code{make}}, for information about @code{MAKELEVEL}.)
4421
4422 @vindex MAKELEVEL
4423 @vindex MAKE
4424 @example
4425 @group
4426 ifeq (0,$@{MAKELEVEL@})
4427 cur-dir := $(shell pwd)
4428 whoami := $(shell whoami)
4429 host-type := $(shell arch)
4430 MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
4431 endif
4432 @end group
4433 @end example
4434
4435 @noindent
4436 An advantage of this use of @samp{:=} is that a typical
4437 `descend into a directory' command then looks like this:
4438
4439 @example
4440 @group
4441 $@{subdirs@}:
4442 $@{MAKE@} cur-dir=$@{cur-dir@}/$@@ -C $@@ all
4443 @end group
4444 @end example
4445
4446 Simply expanded variables generally make complicated makefile programming
4447 more predictable because they work like variables in most programming
4448 languages. They allow you to redefine a variable using its own value (or
4449 its value processed in some way by one of the expansion functions) and to
4450 use the expansion functions much more efficiently
4451 (@pxref{Functions, ,Functions for Transforming Text}).
4452
4453 @cindex spaces, in variable values
4454 @cindex whitespace, in variable values
4455 @cindex variables, spaces in values
4456 You can also use them to introduce controlled leading whitespace into
4457 variable values. Leading whitespace characters are discarded from your
4458 input before substitution of variable references and function calls;
4459 this means you can include leading spaces in a variable value by
4460 protecting them with variable references, like this:
4461
4462 @example
4463 nullstring :=
4464 space := $(nullstring) # end of the line
4465 @end example
4466
4467 @noindent
4468 Here the value of the variable @code{space} is precisely one space. The
4469 comment @w{@samp{# end of the line}} is included here just for clarity.
4470 Since trailing space characters are @emph{not} stripped from variable
4471 values, just a space at the end of the line would have the same effect
4472 (but be rather hard to read). If you put whitespace at the end of a
4473 variable value, it is a good idea to put a comment like that at the end
4474 of the line to make your intent clear. Conversely, if you do @emph{not}
4475 want any whitespace characters at the end of your variable value, you
4476 must remember not to put a random comment on the end of the line after
4477 some whitespace, such as this:
4478
4479 @example
4480 dir := /foo/bar # directory to put the frobs in
4481 @end example
4482
4483 @noindent
4484 Here the value of the variable @code{dir} is @w{@samp{/foo/bar }}
4485 (with four trailing spaces), which was probably not the intention.
4486 (Imagine something like @w{@samp{$(dir)/file}} with this definition!)
4487
4488 @cindex conditional variable assignment
4489 @cindex variables, conditional assignment
4490 @cindex ?=
4491 There is another assignment operator for variables, @samp{?=}. This
4492 is called a conditional variable assignment operator, because it only
4493 has an effect if the variable is not yet defined. This statement:
4494
4495 @example
4496 FOO ?= bar
4497 @end example
4498
4499 @noindent
4500 is exactly equivalent to this
4501 (@pxref{Origin Function, ,The @code{origin} Function}):
4502
4503 @example
4504 ifeq ($(origin FOO), undefined)
4505 FOO = bar
4506 endif
4507 @end example
4508
4509 Note that a variable set to an empty value is still defined, so
4510 @samp{?=} will not set that variable.
4511
4512 @node Advanced, Values, Flavors, Using Variables
4513 @section Advanced Features for Reference to Variables
4514 @cindex reference to variables
4515
4516 This section describes some advanced features you can use to reference
4517 variables in more flexible ways.
4518
4519 @menu
4520 * Substitution Refs:: Referencing a variable with
4521 substitutions on the value.
4522 * Computed Names:: Computing the name of the variable to refer to.
4523 @end menu
4524
4525 @node Substitution Refs, Computed Names, Advanced, Advanced
4526 @subsection Substitution References
4527 @cindex modified variable reference
4528 @cindex substitution variable reference
4529 @cindex variables, modified reference
4530 @cindex variables, substitution reference
4531
4532 @cindex variables, substituting suffix in
4533 @cindex suffix, substituting in variables
4534 A @dfn{substitution reference} substitutes the value of a variable with
4535 alterations that you specify. It has the form
4536 @samp{$(@var{var}:@var{a}=@var{b})} (or
4537 @samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
4538 of the variable @var{var}, replace every @var{a} at the end of a word with
4539 @var{b} in that value, and substitute the resulting string.
4540
4541 When we say ``at the end of a word'', we mean that @var{a} must appear
4542 either followed by whitespace or at the end of the value in order to be
4543 replaced; other occurrences of @var{a} in the value are unaltered. For
4544 example:@refill
4545
4546 @example
4547 foo := a.o b.o c.o
4548 bar := $(foo:.o=.c)
4549 @end example
4550
4551 @noindent
4552 sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}.
4553
4554 A substitution reference is actually an abbreviation for use of the
4555 @code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide
4556 substitution references as well as @code{patsubst} for compatibility with
4557 other implementations of @code{make}.
4558
4559 @findex patsubst
4560 Another type of substitution reference lets you use the full power of
4561 the @code{patsubst} function. It has the same form
4562 @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
4563 @var{a} must contain a single @samp{%} character. This case is
4564 equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
4565 @xref{Text Functions, ,Functions for String Substitution and Analysis},
4566 for a description of the @code{patsubst} function.@refill
4567
4568 @example
4569 @group
4570 @exdent For example:
4571
4572 foo := a.o b.o c.o
4573 bar := $(foo:%.o=%.c)
4574 @end group
4575 @end example
4576
4577 @noindent
4578 sets @samp{bar} to @samp{a.c b.c c.c}.
4579
4580 @node Computed Names, , Substitution Refs, Advanced
4581 @subsection Computed Variable Names
4582 @cindex nested variable reference
4583 @cindex computed variable name
4584 @cindex variables, computed names
4585 @cindex variables, nested references
4586 @cindex variables, @samp{$} in name
4587 @cindex @code{$}, in variable name
4588 @cindex dollar sign (@code{$}), in variable name
4589
4590 Computed variable names are a complicated concept needed only for
4591 sophisticated makefile programming. For most purposes you need not
4592 consider them, except to know that making a variable with a dollar sign
4593 in its name might have strange results. However, if you are the type
4594 that wants to understand everything, or you are actually interested in
4595 what they do, read on.
4596
4597 Variables may be referenced inside the name of a variable. This is
4598 called a @dfn{computed variable name} or a @dfn{nested variable
4599 reference}. For example,
4600
4601 @example
4602 x = y
4603 y = z
4604 a := $($(x))
4605 @end example
4606
4607 @noindent
4608 defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
4609 to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
4610 to @samp{z}. Here the name of the variable to reference is not stated
4611 explicitly; it is computed by expansion of @samp{$(x)}. The reference
4612 @samp{$(x)} here is nested within the outer variable reference.
4613
4614 The previous example shows two levels of nesting, but any number of levels
4615 is possible. For example, here are three levels:
4616
4617 @example
4618 x = y
4619 y = z
4620 z = u
4621 a := $($($(x)))
4622 @end example
4623
4624 @noindent
4625 Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
4626 expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
4627 @samp{$(z)}, which becomes @samp{u}.
4628
4629 References to recursively-expanded variables within a variable name are
4630 reexpanded in the usual fashion. For example:
4631
4632 @example
4633 x = $(y)
4634 y = z
4635 z = Hello
4636 a := $($(x))
4637 @end example
4638
4639 @noindent
4640 defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
4641 which becomes @samp{$(z)} which becomes @samp{Hello}.
4642
4643 Nested variable references can also contain modified references and
4644 function invocations (@pxref{Functions, ,Functions for Transforming Text}),
4645 just like any other reference.
4646 For example, using the @code{subst} function
4647 (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
4648
4649 @example
4650 @group
4651 x = variable1
4652 variable2 := Hello
4653 y = $(subst 1,2,$(x))
4654 z = y
4655 a := $($($(z)))
4656 @end group
4657 @end example
4658
4659 @noindent
4660 eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone
4661 would ever want to write a nested reference as convoluted as this one, but
4662 it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
4663 @samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from
4664 @code{x} and changes it by substitution to @samp{variable2}, so that the
4665 entire string becomes @samp{$(variable2)}, a simple variable reference
4666 whose value is @samp{Hello}.@refill
4667
4668 A computed variable name need not consist entirely of a single variable
4669 reference. It can contain several variable references, as well as some
4670 invariant text. For example,
4671
4672 @example
4673 @group
4674 a_dirs := dira dirb
4675 1_dirs := dir1 dir2
4676 @end group
4677
4678 @group
4679 a_files := filea fileb
4680 1_files := file1 file2
4681 @end group
4682
4683 @group
4684 ifeq "$(use_a)" "yes"
4685 a1 := a
4686 else
4687 a1 := 1
4688 endif
4689 @end group
4690
4691 @group
4692 ifeq "$(use_dirs)" "yes"
4693 df := dirs
4694 else
4695 df := files
4696 endif
4697
4698 dirs := $($(a1)_$(df))
4699 @end group
4700 @end example
4701
4702 @noindent
4703 will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
4704 @code{a_files} or @code{1_files} depending on the settings of @code{use_a}
4705 and @code{use_dirs}.@refill
4706
4707 Computed variable names can also be used in substitution references:
4708
4709 @example
4710 @group
4711 a_objects := a.o b.o c.o
4712 1_objects := 1.o 2.o 3.o
4713
4714 sources := $($(a1)_objects:.o=.c)
4715 @end group
4716 @end example
4717
4718 @noindent
4719 defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
4720 depending on the value of @code{a1}.
4721
4722 The only restriction on this sort of use of nested variable references
4723 is that they cannot specify part of the name of a function to be called.
4724 This is because the test for a recognized function name is done before
4725 the expansion of nested references. For example,
4726
4727 @example
4728 @group
4729 ifdef do_sort
4730 func := sort
4731 else
4732 func := strip
4733 endif
4734 @end group
4735
4736 @group
4737 bar := a d b g q c
4738 @end group
4739
4740 @group
4741 foo := $($(func) $(bar))
4742 @end group
4743 @end example
4744
4745 @noindent
4746 attempts to give @samp{foo} the value of the variable @samp{sort a d b g
4747 q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
4748 as the argument to either the @code{sort} or the @code{strip} function.
4749 This restriction could be removed in the future if that change is shown
4750 to be a good idea.
4751
4752 You can also use computed variable names in the left-hand side of a
4753 variable assignment, or in a @code{define} directive, as in:
4754
4755 @example
4756 dir = foo
4757 $(dir)_sources := $(wildcard $(dir)/*.c)
4758 define $(dir)_print
4759 lpr $($(dir)_sources)
4760 endef
4761 @end example
4762
4763 @noindent
4764 This example defines the variables @samp{dir}, @samp{foo_sources}, and
4765 @samp{foo_print}.
4766
4767 Note that @dfn{nested variable references} are quite different from
4768 @dfn{recursively expanded variables}
4769 (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
4770 used together in complex ways when doing makefile programming.@refill
4771
4772 @node Values, Setting, Advanced, Using Variables
4773 @section How Variables Get Their Values
4774 @cindex variables, how they get their values
4775 @cindex value, how a variable gets it
4776
4777 Variables can get values in several different ways:
4778
4779 @itemize @bullet
4780 @item
4781 You can specify an overriding value when you run @code{make}.
4782 @xref{Overriding, ,Overriding Variables}.
4783
4784 @item
4785 You can specify a value in the makefile, either
4786 with an assignment (@pxref{Setting, ,Setting Variables}) or with a
4787 verbatim definition (@pxref{Defining, ,Defining Variables Verbatim}).@refill
4788
4789 @item
4790 Variables in the environment become @code{make} variables.
4791 @xref{Environment, ,Variables from the Environment}.
4792
4793 @item
4794 Several @dfn{automatic} variables are given new values for each rule.
4795 Each of these has a single conventional use.
4796 @xref{Automatic Variables}.
4797
4798 @item
4799 Several variables have constant initial values.
4800 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
4801 @end itemize
4802
4803 @node Setting, Appending, Values, Using Variables
4804 @section Setting Variables
4805 @cindex setting variables
4806 @cindex variables, setting
4807 @cindex =
4808 @cindex :=
4809 @cindex ?=
4810
4811 To set a variable from the makefile, write a line starting with the
4812 variable name followed by @samp{=} or @samp{:=}. Whatever follows the
4813 @samp{=} or @samp{:=} on the line becomes the value. For example,
4814
4815 @example
4816 objects = main.o foo.o bar.o utils.o
4817 @end example
4818
4819 @noindent
4820 defines a variable named @code{objects}. Whitespace around the variable
4821 name and immediately after the @samp{=} is ignored.
4822
4823 Variables defined with @samp{=} are @dfn{recursively expanded} variables.
4824 Variables defined with @samp{:=} are @dfn{simply expanded} variables; these
4825 definitions can contain variable references which will be expanded before
4826 the definition is made. @xref{Flavors, ,The Two Flavors of Variables}.
4827
4828 The variable name may contain function and variable references, which
4829 are expanded when the line is read to find the actual variable name to use.
4830
4831 There is no limit on the length of the value of a variable except the
4832 amount of swapping space on the computer. When a variable definition is
4833 long, it is a good idea to break it into several lines by inserting
4834 backslash-newline at convenient places in the definition. This will not
4835 affect the functioning of @code{make}, but it will make the makefile easier
4836 to read.
4837
4838 Most variable names are considered to have the empty string as a value if
4839 you have never set them. Several variables have built-in initial values
4840 that are not empty, but you can set them in the usual ways
4841 (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
4842 Several special variables are set
4843 automatically to a new value for each rule; these are called the
4844 @dfn{automatic} variables (@pxref{Automatic Variables}).
4845
4846 If you'd like a variable to be set to a value only if it's not already
4847 set, then you can use the shorthand operator @samp{?=} instead of
4848 @samp{=}. These two settings of the variable @samp{FOO} are identical
4849 (@pxref{Origin Function, ,The @code{origin} Function}):
4850
4851 @example
4852 FOO ?= bar
4853 @end example
4854
4855 @noindent
4856 and
4857
4858 @example
4859 ifeq ($(origin FOO), undefined)
4860 FOO = bar
4861 endif
4862 @end example
4863
4864 @node Appending, Override Directive, Setting, Using Variables
4865 @section Appending More Text to Variables
4866 @cindex +=
4867 @cindex appending to variables
4868 @cindex variables, appending to
4869
4870 Often it is useful to add more text to the value of a variable already defined.
4871 You do this with a line containing @samp{+=}, like this:
4872
4873 @example
4874 objects += another.o
4875 @end example
4876
4877 @noindent
4878 This takes the value of the variable @code{objects}, and adds the text
4879 @samp{another.o} to it (preceded by a single space). Thus:
4880
4881 @example
4882 objects = main.o foo.o bar.o utils.o
4883 objects += another.o
4884 @end example
4885
4886 @noindent
4887 sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
4888
4889 Using @samp{+=} is similar to:
4890
4891 @example
4892 objects = main.o foo.o bar.o utils.o
4893 objects := $(objects) another.o
4894 @end example
4895
4896 @noindent
4897 but differs in ways that become important when you use more complex values.
4898
4899 When the variable in question has not been defined before, @samp{+=}
4900 acts just like normal @samp{=}: it defines a recursively-expanded
4901 variable. However, when there @emph{is} a previous definition, exactly
4902 what @samp{+=} does depends on what flavor of variable you defined
4903 originally. @xref{Flavors, ,The Two Flavors of Variables}, for an
4904 explanation of the two flavors of variables.
4905
4906 When you add to a variable's value with @samp{+=}, @code{make} acts
4907 essentially as if you had included the extra text in the initial
4908 definition of the variable. If you defined it first with @samp{:=},
4909 making it a simply-expanded variable, @samp{+=} adds to that
4910 simply-expanded definition, and expands the new text before appending it
4911 to the old value just as @samp{:=} does
4912 (@pxref{Setting, ,Setting Variables}, for a full explanation of @samp{:=}).
4913 In fact,
4914
4915 @example
4916 variable := value
4917 variable += more
4918 @end example
4919
4920 @noindent
4921 is exactly equivalent to:
4922
4923 @noindent
4924 @example
4925 variable := value
4926 variable := $(variable) more
4927 @end example
4928
4929 On the other hand, when you use @samp{+=} with a variable that you defined
4930 first to be recursively-expanded using plain @samp{=}, @code{make} does
4931 something a bit different. Recall that when you define a
4932 recursively-expanded variable, @code{make} does not expand the value you set
4933 for variable and function references immediately. Instead it stores the text
4934 verbatim, and saves these variable and function references to be expanded
4935 later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
4936 of Variables}). When you use @samp{+=} on a recursively-expanded variable,
4937 it is this unexpanded text to which @code{make} appends the new text you
4938 specify.
4939
4940 @example
4941 @group
4942 variable = value
4943 variable += more
4944 @end group
4945 @end example
4946
4947 @noindent
4948 is roughly equivalent to:
4949
4950 @example
4951 @group
4952 temp = value
4953 variable = $(temp) more
4954 @end group
4955 @end example
4956
4957 @noindent
4958 except that of course it never defines a variable called @code{temp}.
4959 The importance of this comes when the variable's old value contains
4960 variable references. Take this common example:
4961
4962 @example
4963 CFLAGS = $(includes) -O
4964 @dots{}
4965 CFLAGS += -pg # enable profiling
4966 @end example
4967
4968 @noindent
4969 The first line defines the @code{CFLAGS} variable with a reference to another
4970 variable, @code{includes}. (@code{CFLAGS} is used by the rules for C
4971 compilation; @pxref{Catalogue of Rules, ,Catalogue of Implicit Rules}.)
4972 Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
4973 variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
4974 @code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes}
4975 need not be defined yet for its value to take effect. It only has to be
4976 defined before any reference to @code{CFLAGS}. If we tried to append to the
4977 value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
4978
4979 @example
4980 CFLAGS := $(CFLAGS) -pg # enable profiling
4981 @end example
4982
4983 @noindent
4984 This is pretty close, but not quite what we want. Using @samp{:=}
4985 redefines @code{CFLAGS} as a simply-expanded variable; this means
4986 @code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
4987 variable. If @code{includes} is not yet defined, we get @w{@samp{ -O
4988 -pg}}, and a later definition of @code{includes} will have no effect.
4989 Conversely, by using @samp{+=} we set @code{CFLAGS} to the
4990 @emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve
4991 the reference to @code{includes}, so if that variable gets defined at
4992 any later point, a reference like @samp{$(CFLAGS)} still uses its
4993 value.
4994
4995 @node Override Directive, Defining, Appending, Using Variables
4996 @section The @code{override} Directive
4997 @findex override
4998 @cindex overriding with @code{override}
4999 @cindex variables, overriding
5000
5001 If a variable has been set with a command argument
5002 (@pxref{Overriding, ,Overriding Variables}),
5003 then ordinary assignments in the makefile are ignored. If you want to set
5004 the variable in the makefile even though it was set with a command
5005 argument, you can use an @code{override} directive, which is a line that
5006 looks like this:@refill
5007
5008 @example
5009 override @var{variable} = @var{value}
5010 @end example
5011
5012 @noindent
5013 or
5014
5015 @example
5016 override @var{variable} := @var{value}
5017 @end example
5018
5019 To append more text to a variable defined on the command line, use:
5020
5021 @example
5022 override @var{variable} += @var{more text}
5023 @end example
5024
5025 @noindent
5026 @xref{Appending, ,Appending More Text to Variables}.
5027
5028 The @code{override} directive was not invented for escalation in the war
5029 between makefiles and command arguments. It was invented so you can alter
5030 and add to values that the user specifies with command arguments.
5031
5032 For example, suppose you always want the @samp{-g} switch when you run the
5033 C compiler, but you would like to allow the user to specify the other
5034 switches with a command argument just as usual. You could use this
5035 @code{override} directive:
5036
5037 @example
5038 override CFLAGS += -g
5039 @end example
5040
5041 You can also use @code{override} directives with @code{define} directives.
5042 This is done as you might expect:
5043
5044 @example
5045 override define foo
5046 bar
5047 endef
5048 @end example
5049
5050 @noindent
5051 @iftex
5052 See the next section for information about @code{define}.
5053 @end iftex
5054 @ifinfo
5055 @xref{Defining, ,Defining Variables Verbatim}.
5056 @end ifinfo
5057
5058 @node Defining, Environment, Override Directive, Using Variables
5059 @section Defining Variables Verbatim
5060 @findex define
5061 @findex endef
5062 @cindex verbatim variable definition
5063 @cindex defining variables verbatim
5064 @cindex variables, defining verbatim
5065
5066 Another way to set the value of a variable is to use the @code{define}
5067 directive. This directive has an unusual syntax which allows newline
5068 characters to be included in the value, which is convenient for defining
5069 both canned sequences of commands
5070 (@pxref{Sequences, ,Defining Canned Command Sequences}), and also
5071 sections of makefile syntax to use with @code{eval} (@pxref{Eval Function}).
5072
5073 The @code{define} directive is followed on the same line by the name of the
5074 variable and nothing more. The value to give the variable appears on the
5075 following lines. The end of the value is marked by a line containing just
5076 the word @code{endef}. Aside from this difference in syntax, @code{define}
5077 works just like @samp{=}: it creates a recursively-expanded variable
5078 (@pxref{Flavors, ,The Two Flavors of Variables}).
5079 The variable name may contain function and variable references, which
5080 are expanded when the directive is read to find the actual variable name
5081 to use.
5082
5083 You may nest @code{define} directives: @code{make} will keep track of
5084 nested directives and report an error if they are not all properly
5085 closed with @code{endef}. Note that lines beginning with tab
5086 characters are considered part of a command script, so any
5087 @code{define} or @code{endef} strings appearing on such a line will
5088 not be considered @code{make} operators.
5089
5090 @example
5091 define two-lines
5092 echo foo
5093 echo $(bar)
5094 endef
5095 @end example
5096
5097 The value in an ordinary assignment cannot contain a newline; but the
5098 newlines that separate the lines of the value in a @code{define} become
5099 part of the variable's value (except for the final newline which precedes
5100 the @code{endef} and is not considered part of the value).@refill
5101
5102 @need 800
5103 When used in a command script, the previous example is functionally
5104 equivalent to this:
5105
5106 @example
5107 two-lines = echo foo; echo $(bar)
5108 @end example
5109
5110 @noindent
5111 since two commands separated by semicolon behave much like two separate
5112 shell commands. However, note that using two separate lines means
5113 @code{make} will invoke the shell twice, running an independent subshell
5114 for each line. @xref{Execution, ,Command Execution}.
5115
5116 If you want variable definitions made with @code{define} to take
5117 precedence over command-line variable definitions, you can use the
5118 @code{override} directive together with @code{define}:
5119
5120 @example
5121 override define two-lines
5122 foo
5123 $(bar)
5124 endef
5125 @end example
5126
5127 @noindent
5128 @xref{Override Directive, ,The @code{override} Directive}.
5129
5130 @node Environment, Target-specific, Defining, Using Variables
5131 @section Variables from the Environment
5132
5133 @cindex variables, environment
5134 @cindex environment
5135 Variables in @code{make} can come from the environment in which
5136 @code{make} is run. Every environment variable that @code{make} sees when
5137 it starts up is transformed into a @code{make} variable with the same name
5138 and value. But an explicit assignment in the makefile, or with a command
5139 argument, overrides the environment. (If the @samp{-e} flag is specified,
5140 then values from the environment override assignments in the makefile.
5141 @xref{Options Summary, ,Summary of Options}.
5142 But this is not recommended practice.)
5143
5144 Thus, by setting the variable @code{CFLAGS} in your environment, you can
5145 cause all C compilations in most makefiles to use the compiler switches you
5146 prefer. This is safe for variables with standard or conventional meanings
5147 because you know that no makefile will use them for other things. (But
5148 this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
5149 and therefore are not affected by the value in the environment.)
5150
5151 When @code{make} is invoked recursively, variables defined in the
5152 outer invocation can be passed to inner invocations through the
5153 environment (@pxref{Recursion, ,Recursive Use of @code{make}}). By
5154 default, only variables that came from the environment or the command
5155 line are passed to recursive invocations. You can use the
5156 @code{export} directive to pass other variables.
5157 @xref{Variables/Recursion, , Communicating Variables to a
5158 Sub-@code{make}}, for full details.
5159
5160 Other use of variables from the environment is not recommended. It is not
5161 wise for makefiles to depend for their functioning on environment variables
5162 set up outside their control, since this would cause different users to get
5163 different results from the same makefile. This is against the whole
5164 purpose of most makefiles.
5165
5166 Such problems would be especially likely with the variable @code{SHELL},
5167 which is normally present in the environment to specify the user's choice
5168 of interactive shell. It would be very undesirable for this choice to
5169 affect @code{make}. So @code{make} ignores the environment value of
5170 @code{SHELL} (except on MS-DOS and MS-Windows, where @code{SHELL} is
5171 usually not set. @xref{Execution, ,Special handling of SHELL on
5172 MS-DOS}.)@refill
5173
5174 @node Target-specific, Pattern-specific, Environment, Using Variables
5175 @section Target-specific Variable Values
5176 @cindex target-specific variables
5177 @cindex variables, target-specific
5178
5179 Variable values in @code{make} are usually global; that is, they are the
5180 same regardless of where they are evaluated (unless they're reset, of
5181 course). One exception to that is automatic variables
5182 (@pxref{Automatic Variables}).
5183
5184 The other exception is @dfn{target-specific variable values}. This
5185 feature allows you to define different values for the same variable,
5186 based on the target that @code{make} is currently building. As with
5187 automatic variables, these values are only available within the context
5188 of a target's command script (and in other target-specific assignments).
5189
5190 Set a target-specific variable value like this:
5191
5192 @example
5193 @var{target} @dots{} : @var{variable-assignment}
5194 @end example
5195
5196 @noindent
5197 or like this:
5198
5199 @example
5200 @var{target} @dots{} : override @var{variable-assignment}
5201 @end example
5202
5203 @noindent
5204 or like this:
5205
5206 @example
5207 @var{target} @dots{} : export @var{variable-assignment}
5208 @end example
5209
5210 Multiple @var{target} values create a target-specific variable value for
5211 each member of the target list individually.
5212
5213 The @var{variable-assignment} can be any valid form of assignment;
5214 recursive (@samp{=}), static (@samp{:=}), appending (@samp{+=}), or
5215 conditional (@samp{?=}). All variables that appear within the
5216 @var{variable-assignment} are evaluated within the context of the
5217 target: thus, any previously-defined target-specific variable values
5218 will be in effect. Note that this variable is actually distinct from
5219 any ``global'' value: the two variables do not have to have the same
5220 flavor (recursive vs. static).
5221
5222 Target-specific variables have the same priority as any other makefile
5223 variable. Variables provided on the command-line (and in the
5224 environment if the @samp{-e} option is in force) will take precedence.
5225 Specifying the @code{override} directive will allow the target-specific
5226 variable value to be preferred.
5227
5228 There is one more special feature of target-specific variables: when you
5229 define a target-specific variable, that variable value is also in effect
5230 for all prerequisites of this target (unless those prerequisites override
5231 it with their own target-specific variable value). So, for example, a
5232 statement like this:
5233
5234 @example
5235 prog : CFLAGS = -g
5236 prog : prog.o foo.o bar.o
5237 @end example
5238
5239 @noindent
5240 will set @code{CFLAGS} to @samp{-g} in the command script for
5241 @file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the
5242 command scripts that create @file{prog.o}, @file{foo.o}, and
5243 @file{bar.o}, and any command scripts which create their prerequisites.
5244
5245 @node Pattern-specific, , Target-specific, Using Variables
5246 @section Pattern-specific Variable Values
5247 @cindex pattern-specific variables
5248 @cindex variables, pattern-specific
5249
5250 In addition to target-specific variable values
5251 (@pxref{Target-specific, ,Target-specific Variable Values}), GNU
5252 @code{make} supports pattern-specific variable values. In this form,
5253 the variable is defined for any target that matches the pattern
5254 specified. If a target matches more than one pattern, all the
5255 matching pattern-specific variables are interpreted in the order in
5256 which they were defined in the makefile, and collected together into
5257 one set. Variables defined in this way are searched after any
5258 target-specific variables defined explicitly for that target, and
5259 before target-specific variables defined for the parent target.
5260
5261 Set a pattern-specific variable value like this:
5262
5263 @example
5264 @var{pattern} @dots{} : @var{variable-assignment}
5265 @end example
5266
5267 @noindent
5268 or like this:
5269
5270 @example
5271 @var{pattern} @dots{} : override @var{variable-assignment}
5272 @end example
5273
5274 @noindent
5275 where @var{pattern} is a %-pattern. As with target-specific variable
5276 values, multiple @var{pattern} values create a pattern-specific variable
5277 value for each pattern individually. The @var{variable-assignment} can
5278 be any valid form of assignment. Any command-line variable setting will
5279 take precedence, unless @code{override} is specified.
5280
5281 For example:
5282
5283 @example
5284 %.o : CFLAGS = -O
5285 @end example
5286
5287 @noindent
5288 will assign @code{CFLAGS} the value of @samp{-O} for all targets
5289 matching the pattern @code{%.o}.
5290
5291 @node Conditionals, Functions, Using Variables, Top
5292 @chapter Conditional Parts of Makefiles
5293
5294 @cindex conditionals
5295 A @dfn{conditional} causes part of a makefile to be obeyed or ignored
5296 depending on the values of variables. Conditionals can compare the
5297 value of one variable to another, or the value of a variable to
5298 a constant string. Conditionals control what @code{make} actually
5299 ``sees'' in the makefile, so they @emph{cannot} be used to control shell
5300 commands at the time of execution.@refill
5301
5302 @menu
5303 * Conditional Example:: Example of a conditional
5304 * Conditional Syntax:: The syntax of conditionals.
5305 * Testing Flags:: Conditionals that test flags.
5306 @end menu
5307
5308 @node Conditional Example, Conditional Syntax, Conditionals, Conditionals
5309 @section Example of a Conditional
5310
5311 The following example of a conditional tells @code{make} to use one set
5312 of libraries if the @code{CC} variable is @samp{gcc}, and a different
5313 set of libraries otherwise. It works by controlling which of two
5314 command lines will be used as the command for a rule. The result is
5315 that @samp{CC=gcc} as an argument to @code{make} changes not only which
5316 compiler is used but also which libraries are linked.
5317
5318 @example
5319 libs_for_gcc = -lgnu
5320 normal_libs =
5321
5322 foo: $(objects)
5323 ifeq ($(CC),gcc)
5324 $(CC) -o foo $(objects) $(libs_for_gcc)
5325 else
5326 $(CC) -o foo $(objects) $(normal_libs)
5327 endif
5328 @end example
5329
5330 This conditional uses three directives: one @code{ifeq}, one @code{else}
5331 and one @code{endif}.
5332
5333 The @code{ifeq} directive begins the conditional, and specifies the
5334 condition. It contains two arguments, separated by a comma and surrounded
5335 by parentheses. Variable substitution is performed on both arguments and
5336 then they are compared. The lines of the makefile following the
5337 @code{ifeq} are obeyed if the two arguments match; otherwise they are
5338 ignored.
5339
5340 The @code{else} directive causes the following lines to be obeyed if the
5341 previous conditional failed. In the example above, this means that the
5342 second alternative linking command is used whenever the first alternative
5343 is not used. It is optional to have an @code{else} in a conditional.
5344
5345 The @code{endif} directive ends the conditional. Every conditional must
5346 end with an @code{endif}. Unconditional makefile text follows.
5347
5348 As this example illustrates, conditionals work at the textual level:
5349 the lines of the conditional are treated as part of the makefile, or
5350 ignored, according to the condition. This is why the larger syntactic
5351 units of the makefile, such as rules, may cross the beginning or the
5352 end of the conditional.
5353
5354 When the variable @code{CC} has the value @samp{gcc}, the above example has
5355 this effect:
5356
5357 @example
5358 foo: $(objects)
5359 $(CC) -o foo $(objects) $(libs_for_gcc)
5360 @end example
5361
5362 @noindent
5363 When the variable @code{CC} has any other value, the effect is this:
5364
5365 @example
5366 foo: $(objects)
5367 $(CC) -o foo $(objects) $(normal_libs)
5368 @end example
5369
5370 Equivalent results can be obtained in another way by conditionalizing a
5371 variable assignment and then using the variable unconditionally:
5372
5373 @example
5374 libs_for_gcc = -lgnu
5375 normal_libs =
5376
5377 ifeq ($(CC),gcc)
5378 libs=$(libs_for_gcc)
5379 else
5380 libs=$(normal_libs)
5381 endif
5382
5383 foo: $(objects)
5384 $(CC) -o foo $(objects) $(libs)
5385 @end example
5386
5387 @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
5388 @section Syntax of Conditionals
5389 @findex ifdef
5390 @findex ifeq
5391 @findex ifndef
5392 @findex ifneq
5393 @findex else
5394 @findex endif
5395
5396 The syntax of a simple conditional with no @code{else} is as follows:
5397
5398 @example
5399 @var{conditional-directive}
5400 @var{text-if-true}
5401 endif
5402 @end example
5403
5404 @noindent
5405 The @var{text-if-true} may be any lines of text, to be considered as part
5406 of the makefile if the condition is true. If the condition is false, no
5407 text is used instead.
5408
5409 The syntax of a complex conditional is as follows:
5410
5411 @example
5412 @var{conditional-directive}
5413 @var{text-if-true}
5414 else
5415 @var{text-if-false}
5416 endif
5417 @end example
5418
5419 @noindent
5420 If the condition is true, @var{text-if-true} is used; otherwise,
5421 @var{text-if-false} is used instead. The @var{text-if-false} can be any
5422 number of lines of text.
5423
5424 The syntax of the @var{conditional-directive} is the same whether the
5425 conditional is simple or complex. There are four different directives that
5426 test different conditions. Here is a table of them:
5427
5428 @table @code
5429 @item ifeq (@var{arg1}, @var{arg2})
5430 @itemx ifeq '@var{arg1}' '@var{arg2}'
5431 @itemx ifeq "@var{arg1}" "@var{arg2}"
5432 @itemx ifeq "@var{arg1}" '@var{arg2}'
5433 @itemx ifeq '@var{arg1}' "@var{arg2}"
5434 Expand all variable references in @var{arg1} and @var{arg2} and
5435 compare them. If they are identical, the @var{text-if-true} is
5436 effective; otherwise, the @var{text-if-false}, if any, is effective.
5437
5438 Often you want to test if a variable has a non-empty value. When the
5439 value results from complex expansions of variables and functions,
5440 expansions you would consider empty may actually contain whitespace
5441 characters and thus are not seen as empty. However, you can use the
5442 @code{strip} function (@pxref{Text Functions}) to avoid interpreting
5443 whitespace as a non-empty value. For example:
5444
5445 @example
5446 @group
5447 ifeq ($(strip $(foo)),)
5448 @var{text-if-empty}
5449 endif
5450 @end group
5451 @end example
5452
5453 @noindent
5454 will evaluate @var{text-if-empty} even if the expansion of
5455 @code{$(foo)} contains whitespace characters.
5456
5457 @item ifneq (@var{arg1}, @var{arg2})
5458 @itemx ifneq '@var{arg1}' '@var{arg2}'
5459 @itemx ifneq "@var{arg1}" "@var{arg2}"
5460 @itemx ifneq "@var{arg1}" '@var{arg2}'
5461 @itemx ifneq '@var{arg1}' "@var{arg2}"
5462 Expand all variable references in @var{arg1} and @var{arg2} and
5463 compare them. If they are different, the @var{text-if-true} is
5464 effective; otherwise, the @var{text-if-false}, if any, is effective.
5465
5466 @item ifdef @var{variable-name}
5467 If the variable @var{variable-name} has a non-empty value, the
5468 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
5469 if any, is effective. Variables that have never been defined have an
5470 empty value. The variable @var{variable-name} is itself expanded, so
5471 it could be a variable or function that expands to the name of a
5472 variable.
5473
5474 Note that @code{ifdef} only tests whether a variable has a value. It
5475 does not expand the variable to see if that value is nonempty.
5476 Consequently, tests using @code{ifdef} return true for all definitions
5477 except those like @code{foo =}. To test for an empty value, use
5478 @w{@code{ifeq ($(foo),)}}. For example,
5479
5480 @example
5481 bar =
5482 foo = $(bar)
5483 ifdef foo
5484 frobozz = yes
5485 else
5486 frobozz = no
5487 endif
5488 @end example
5489
5490 @noindent
5491 sets @samp{frobozz} to @samp{yes}, while:
5492
5493 @example
5494 foo =
5495 ifdef foo
5496 frobozz = yes
5497 else
5498 frobozz = no
5499 endif
5500 @end example
5501
5502 @noindent
5503 sets @samp{frobozz} to @samp{no}.
5504
5505 @item ifndef @var{variable-name}
5506 If the variable @var{variable-name} has an empty value, the
5507 @var{text-if-true} is effective; otherwise, the @var{text-if-false},
5508 if any, is effective.
5509 @end table
5510
5511 Extra spaces are allowed and ignored at the beginning of the conditional
5512 directive line, but a tab is not allowed. (If the line begins with a tab,
5513 it will be considered a command for a rule.) Aside from this, extra spaces
5514 or tabs may be inserted with no effect anywhere except within the directive
5515 name or within an argument. A comment starting with @samp{#} may appear at
5516 the end of the line.
5517
5518 The other two directives that play a part in a conditional are @code{else}
5519 and @code{endif}. Each of these directives is written as one word, with no
5520 arguments. Extra spaces are allowed and ignored at the beginning of the
5521 line, and spaces or tabs at the end. A comment starting with @samp{#} may
5522 appear at the end of the line.
5523
5524 Conditionals affect which lines of the makefile @code{make} uses. If
5525 the condition is true, @code{make} reads the lines of the
5526 @var{text-if-true} as part of the makefile; if the condition is false,
5527 @code{make} ignores those lines completely. It follows that syntactic
5528 units of the makefile, such as rules, may safely be split across the
5529 beginning or the end of the conditional.@refill
5530
5531 @code{make} evaluates conditionals when it reads a makefile.
5532 Consequently, you cannot use automatic variables in the tests of
5533 conditionals because they are not defined until commands are run
5534 (@pxref{Automatic Variables}).
5535
5536 To prevent intolerable confusion, it is not permitted to start a
5537 conditional in one makefile and end it in another. However, you may
5538 write an @code{include} directive within a conditional, provided you do
5539 not attempt to terminate the conditional inside the included file.
5540
5541 @node Testing Flags, , Conditional Syntax, Conditionals
5542 @section Conditionals that Test Flags
5543
5544 You can write a conditional that tests @code{make} command flags such as
5545 @samp{-t} by using the variable @code{MAKEFLAGS} together with the
5546 @code{findstring} function
5547 (@pxref{Text Functions, , Functions for String Substitution and Analysis}).
5548 This is useful when @code{touch} is not enough to make a file appear up
5549 to date.
5550
5551 The @code{findstring} function determines whether one string appears as a
5552 substring of another. If you want to test for the @samp{-t} flag,
5553 use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
5554 the other.
5555
5556 For example, here is how to arrange to use @samp{ranlib -t} to finish
5557 marking an archive file up to date:
5558
5559 @example
5560 archive.a: @dots{}
5561 ifneq (,$(findstring t,$(MAKEFLAGS)))
5562 +touch archive.a
5563 +ranlib -t archive.a
5564 else
5565 ranlib archive.a
5566 endif
5567 @end example
5568
5569 @noindent
5570 The @samp{+} prefix marks those command lines as ``recursive'' so
5571 that they will be executed despite use of the @samp{-t} flag.
5572 @xref{Recursion, ,Recursive Use of @code{make}}.
5573
5574 @node Functions, Running, Conditionals, Top
5575 @chapter Functions for Transforming Text
5576 @cindex functions
5577
5578 @dfn{Functions} allow you to do text processing in the makefile to compute
5579 the files to operate on or the commands to use. You use a function in a
5580 @dfn{function call}, where you give the name of the function and some text
5581 (the @dfn{arguments}) for the function to operate on. The result of the
5582 function's processing is substituted into the makefile at the point of the
5583 call, just as a variable might be substituted.
5584
5585 @menu
5586 * Syntax of Functions:: How to write a function call.
5587 * Text Functions:: General-purpose text manipulation functions.
5588 * File Name Functions:: Functions for manipulating file names.
5589 * Foreach Function:: Repeat some text with controlled variation.
5590 * If Function:: Conditionally expand a value.
5591 * Call Function:: Expand a user-defined function.
5592 * Value Function:: Return the un-expanded value of a variable.
5593 * Eval Function:: Evaluate the arguments as makefile syntax.
5594 * Origin Function:: Find where a variable got its value.
5595 * Shell Function:: Substitute the output of a shell command.
5596 * Make Control Functions:: Functions that control how make runs.
5597 @end menu
5598
5599 @node Syntax of Functions, Text Functions, Functions, Functions
5600 @section Function Call Syntax
5601 @cindex @code{$}, in function call
5602 @cindex dollar sign (@code{$}), in function call
5603 @cindex arguments of functions
5604 @cindex functions, syntax of
5605
5606 A function call resembles a variable reference. It looks like this:
5607
5608 @example
5609 $(@var{function} @var{arguments})
5610 @end example
5611
5612 @noindent
5613 or like this:
5614
5615 @example
5616 $@{@var{function} @var{arguments}@}
5617 @end example
5618
5619 Here @var{function} is a function name; one of a short list of names
5620 that are part of @code{make}. You can also essentially create your own
5621 functions by using the @code{call} builtin function.
5622
5623 The @var{arguments} are the arguments of the function. They are
5624 separated from the function name by one or more spaces or tabs, and if
5625 there is more than one argument, then they are separated by commas.
5626 Such whitespace and commas are not part of an argument's value. The
5627 delimiters which you use to surround the function call, whether
5628 parentheses or braces, can appear in an argument only in matching pairs;
5629 the other kind of delimiters may appear singly. If the arguments
5630 themselves contain other function calls or variable references, it is
5631 wisest to use the same kind of delimiters for all the references; write
5632 @w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This
5633 is because it is clearer, and because only one type of delimiter is
5634 matched to find the end of the reference.
5635
5636 The text written for each argument is processed by substitution of
5637 variables and function calls to produce the argument value, which
5638 is the text on which the function acts. The substitution is done in the
5639 order in which the arguments appear.
5640
5641 Commas and unmatched parentheses or braces cannot appear in the text of an
5642 argument as written; leading spaces cannot appear in the text of the first
5643 argument as written. These characters can be put into the argument value
5644 by variable substitution. First define variables @code{comma} and
5645 @code{space} whose values are isolated comma and space characters, then
5646 substitute these variables where such characters are wanted, like this:
5647
5648 @example
5649 @group
5650 comma:= ,
5651 empty:=
5652 space:= $(empty) $(empty)
5653 foo:= a b c
5654 bar:= $(subst $(space),$(comma),$(foo))
5655 # @r{bar is now `a,b,c'.}
5656 @end group
5657 @end example
5658
5659 @noindent
5660 Here the @code{subst} function replaces each space with a comma, through
5661 the value of @code{foo}, and substitutes the result.
5662
5663 @node Text Functions, File Name Functions, Syntax of Functions, Functions
5664 @section Functions for String Substitution and Analysis
5665 @cindex functions, for text
5666
5667 Here are some functions that operate on strings:
5668
5669 @table @code
5670 @item $(subst @var{from},@var{to},@var{text})
5671 @findex subst
5672 Performs a textual replacement on the text @var{text}: each occurrence
5673 of @var{from} is replaced by @var{to}. The result is substituted for
5674 the function call. For example,
5675
5676 @example
5677 $(subst ee,EE,feet on the street)
5678 @end example
5679
5680 substitutes the string @samp{fEEt on the strEEt}.
5681
5682 @item $(patsubst @var{pattern},@var{replacement},@var{text})
5683 @findex patsubst
5684 Finds whitespace-separated words in @var{text} that match
5685 @var{pattern} and replaces them with @var{replacement}. Here
5686 @var{pattern} may contain a @samp{%} which acts as a wildcard,
5687 matching any number of any characters within a word. If
5688 @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
5689 by the text that matched the @samp{%} in @var{pattern}. Only the first
5690 @samp{%} in the @var{pattern} and @var{replacement} is treated this
5691 way; any subsequent @samp{%} is unchanged.@refill
5692
5693 @cindex @code{%}, quoting in @code{patsubst}
5694 @cindex @code{%}, quoting with @code{\} (backslash)
5695 @cindex @code{\} (backslash), to quote @code{%}
5696 @cindex backslash (@code{\}), to quote @code{%}
5697 @cindex quoting @code{%}, in @code{patsubst}
5698 @samp{%} characters in @code{patsubst} function invocations can be
5699 quoted with preceding backslashes (@samp{\}). Backslashes that would
5700 otherwise quote @samp{%} characters can be quoted with more backslashes.
5701 Backslashes that quote @samp{%} characters or other backslashes are
5702 removed from the pattern before it is compared file names or has a stem
5703 substituted into it. Backslashes that are not in danger of quoting
5704 @samp{%} characters go unmolested. For example, the pattern
5705 @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
5706 operative @samp{%} character, and @samp{pattern\\} following it. The
5707 final two backslashes are left alone because they cannot affect any
5708 @samp{%} character.@refill
5709
5710 Whitespace between words is folded into single space characters;
5711 leading and trailing whitespace is discarded.
5712
5713 For example,
5714
5715 @example
5716 $(patsubst %.c,%.o,x.c.c bar.c)
5717 @end example
5718
5719 @noindent
5720 produces the value @samp{x.c.o bar.o}.
5721
5722 Substitution references (@pxref{Substitution Refs, ,Substitution
5723 References}) are a simpler way to get the effect of the @code{patsubst}
5724 function:
5725
5726 @example
5727 $(@var{var}:@var{pattern}=@var{replacement})
5728 @end example
5729
5730 @noindent
5731 is equivalent to
5732
5733 @example
5734 $(patsubst @var{pattern},@var{replacement},$(@var{var}))
5735 @end example
5736
5737 The second shorthand simplifies one of the most common uses of
5738 @code{patsubst}: replacing the suffix at the end of file names.
5739
5740 @example
5741 $(@var{var}:@var{suffix}=@var{replacement})
5742 @end example
5743
5744 @noindent
5745 is equivalent to
5746
5747 @example
5748 $(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
5749 @end example
5750
5751 @noindent
5752 For example, you might have a list of object files:
5753
5754 @example
5755 objects = foo.o bar.o baz.o
5756 @end example
5757
5758 @noindent
5759 To get the list of corresponding source files, you could simply write:
5760
5761 @example
5762 $(objects:.o=.c)
5763 @end example
5764
5765 @noindent
5766 instead of using the general form:
5767
5768 @example
5769 $(patsubst %.o,%.c,$(objects))
5770 @end example
5771
5772 @item $(strip @var{string})
5773 @cindex stripping whitespace
5774 @cindex whitespace, stripping
5775 @cindex spaces, stripping
5776 @findex strip
5777 Removes leading and trailing whitespace from @var{string} and replaces
5778 each internal sequence of one or more whitespace characters with a
5779 single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}.
5780
5781 The function @code{strip} can be very useful when used in conjunction
5782 with conditionals. When comparing something with the empty string
5783 @samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
5784 just whitespace to match the empty string (@pxref{Conditionals}).
5785
5786 Thus, the following may fail to have the desired results:
5787
5788 @example
5789 .PHONY: all
5790 ifneq "$(needs_made)" ""
5791 all: $(needs_made)
5792 else
5793 all:;@@echo 'Nothing to make!'
5794 endif
5795 @end example
5796
5797 @noindent
5798 Replacing the variable reference @w{@samp{$(needs_made)}} with the
5799 function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
5800 directive would make it more robust.@refill
5801
5802 @item $(findstring @var{find},@var{in})
5803 @findex findstring
5804 @cindex searching for strings
5805 @cindex finding strings
5806 @cindex strings, searching for
5807 Searches @var{in} for an occurrence of @var{find}. If it occurs, the
5808 value is @var{find}; otherwise, the value is empty. You can use this
5809 function in a conditional to test for the presence of a specific
5810 substring in a given string. Thus, the two examples,
5811
5812 @example
5813 $(findstring a,a b c)
5814 $(findstring a,b c)
5815 @end example
5816
5817 @noindent
5818 produce the values @samp{a} and @samp{} (the empty string),
5819 respectively. @xref{Testing Flags}, for a practical application of
5820 @code{findstring}.@refill
5821
5822 @need 750
5823 @findex filter
5824 @cindex filtering words
5825 @cindex words, filtering
5826 @item $(filter @var{pattern}@dots{},@var{text})
5827 Returns all whitespace-separated words in @var{text} that @emph{do} match
5828 any of the @var{pattern} words, removing any words that @emph{do not}
5829 match. The patterns are written using @samp{%}, just like the patterns
5830 used in the @code{patsubst} function above.@refill
5831
5832 The @code{filter} function can be used to separate out different types
5833 of strings (such as file names) in a variable. For example:
5834
5835 @example
5836 sources := foo.c bar.c baz.s ugh.h
5837 foo: $(sources)
5838 cc $(filter %.c %.s,$(sources)) -o foo
5839 @end example
5840
5841 @noindent
5842 says that @file{foo} depends of @file{foo.c}, @file{bar.c},
5843 @file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
5844 @file{baz.s} should be specified in the command to the
5845 compiler.@refill
5846
5847 @item $(filter-out @var{pattern}@dots{},@var{text})
5848 @findex filter-out
5849 @cindex filtering out words
5850 @cindex words, filtering out
5851 Returns all whitespace-separated words in @var{text} that @emph{do not}
5852 match any of the @var{pattern} words, removing the words that @emph{do}
5853 match one or more. This is the exact opposite of the @code{filter}
5854 function.@refill
5855
5856 For example, given:
5857
5858 @example
5859 @group
5860 objects=main1.o foo.o main2.o bar.o
5861 mains=main1.o main2.o
5862 @end group
5863 @end example
5864
5865 @noindent
5866 the following generates a list which contains all the object files not
5867 in @samp{mains}:
5868
5869 @example
5870 $(filter-out $(mains),$(objects))
5871 @end example
5872
5873 @need 1500
5874 @findex sort
5875 @cindex sorting words
5876 @item $(sort @var{list})
5877 Sorts the words of @var{list} in lexical order, removing duplicate
5878 words. The output is a list of words separated by single spaces.
5879 Thus,
5880
5881 @example
5882 $(sort foo bar lose)
5883 @end example
5884
5885 @noindent
5886 returns the value @samp{bar foo lose}.
5887
5888 @cindex removing duplicate words
5889 @cindex duplicate words, removing
5890 @cindex words, removing duplicates
5891 Incidentally, since @code{sort} removes duplicate words, you can use
5892 it for this purpose even if you don't care about the sort order.
5893
5894 @item $(word @var{n},@var{text})
5895 @findex word
5896 @cindex word, selecting a
5897 @cindex selecting a word
5898 Returns the @var{n}th word of @var{text}. The legitimate values of
5899 @var{n} start from 1. If @var{n} is bigger than the number of words
5900 in @var{text}, the value is empty. For example,
5901
5902 @example
5903 $(word 2, foo bar baz)
5904 @end example
5905
5906 @noindent
5907 returns @samp{bar}.
5908
5909 @item $(wordlist @var{s},@var{e},@var{text})
5910 @findex wordlist
5911 @cindex words, selecting lists of
5912 @cindex selecting word lists
5913 Returns the list of words in @var{text} starting with word @var{s} and
5914 ending with word @var{e} (inclusive). The legitimate values of @var{s}
5915 and @var{e} start from 1. If @var{s} is bigger than the number of words
5916 in @var{text}, the value is empty. If @var{e} is bigger than the number
5917 of words in @var{text}, words up to the end of @var{text} are returned.
5918 If @var{s} is greater than @var{e}, nothing is returned. For example,
5919
5920 @example
5921 $(wordlist 2, 3, foo bar baz)
5922 @end example
5923
5924 @noindent
5925 returns @samp{bar baz}.
5926
5927 @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
5928 @item $(words @var{text})
5929 @findex words
5930 @cindex words, finding number
5931 Returns the number of words in @var{text}.
5932 Thus, the last word of @var{text} is
5933 @w{@code{$(word $(words @var{text}),@var{text})}}.@refill
5934
5935 @item $(firstword @var{names}@dots{})
5936 @findex firstword
5937 @cindex words, extracting first
5938 The argument @var{names} is regarded as a series of names, separated
5939 by whitespace. The value is the first name in the series. The rest
5940 of the names are ignored.
5941
5942 For example,
5943
5944 @example
5945 $(firstword foo bar)
5946 @end example
5947
5948 @noindent
5949 produces the result @samp{foo}. Although @code{$(firstword
5950 @var{text})} is the same as @code{$(word 1,@var{text})}, the
5951 @code{firstword} function is retained for its simplicity.@refill
5952 @end table
5953
5954 Here is a realistic example of the use of @code{subst} and
5955 @code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable
5956 to specify a list of directories that @code{make} should search for
5957 prerequisite files
5958 (@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}).
5959 This example shows how to
5960 tell the C compiler to search for header files in the same list of
5961 directories.@refill
5962
5963 The value of @code{VPATH} is a list of directories separated by colons,
5964 such as @samp{src:../headers}. First, the @code{subst} function is used to
5965 change the colons to spaces:
5966
5967 @example
5968 $(subst :, ,$(VPATH))
5969 @end example
5970
5971 @noindent
5972 This produces @samp{src ../headers}. Then @code{patsubst} is used to turn
5973 each directory name into a @samp{-I} flag. These can be added to the
5974 value of the variable @code{CFLAGS}, which is passed automatically to the C
5975 compiler, like this:
5976
5977 @example
5978 override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
5979 @end example
5980
5981 @noindent
5982 The effect is to append the text @samp{-Isrc -I../headers} to the
5983 previously given value of @code{CFLAGS}. The @code{override} directive is
5984 used so that the new value is assigned even if the previous value of
5985 @code{CFLAGS} was specified with a command argument (@pxref{Override
5986 Directive, , The @code{override} Directive}).
5987
5988 @node File Name Functions, Foreach Function, Text Functions, Functions
5989 @section Functions for File Names
5990 @cindex functions, for file names
5991 @cindex file name functions
5992
5993 Several of the built-in expansion functions relate specifically to
5994 taking apart file names or lists of file names.
5995
5996 Each of the following functions performs a specific transformation on a
5997 file name. The argument of the function is regarded as a series of file
5998 names, separated by whitespace. (Leading and trailing whitespace is
5999 ignored.) Each file name in the series is transformed in the same way and
6000 the results are concatenated with single spaces between them.
6001
6002 @table @code
6003 @item $(dir @var{names}@dots{})
6004 @findex dir
6005 @cindex directory part
6006 @cindex file name, directory part
6007 Extracts the directory-part of each file name in @var{names}. The
6008 directory-part of the file name is everything up through (and
6009 including) the last slash in it. If the file name contains no slash,
6010 the directory part is the string @samp{./}. For example,
6011
6012 @example
6013 $(dir src/foo.c hacks)
6014 @end example
6015
6016 @noindent
6017 produces the result @samp{src/ ./}.
6018
6019 @item $(notdir @var{names}@dots{})
6020 @findex notdir
6021 @cindex file name, nondirectory part
6022 @cindex nondirectory part
6023 Extracts all but the directory-part of each file name in @var{names}.
6024 If the file name contains no slash, it is left unchanged. Otherwise,
6025 everything through the last slash is removed from it.
6026
6027 A file name that ends with a slash becomes an empty string. This is
6028 unfortunate, because it means that the result does not always have the
6029 same number of whitespace-separated file names as the argument had;
6030 but we do not see any other valid alternative.
6031
6032 For example,
6033
6034 @example
6035 $(notdir src/foo.c hacks)
6036 @end example
6037
6038 @noindent
6039 produces the result @samp{foo.c hacks}.
6040
6041 @item $(suffix @var{names}@dots{})
6042 @findex suffix
6043 @cindex suffix, function to find
6044 @cindex file name suffix
6045 Extracts the suffix of each file name in @var{names}. If the file name
6046 contains a period, the suffix is everything starting with the last
6047 period. Otherwise, the suffix is the empty string. This frequently
6048 means that the result will be empty when @var{names} is not, and if
6049 @var{names} contains multiple file names, the result may contain fewer
6050 file names.
6051
6052 For example,
6053
6054 @example
6055 $(suffix src/foo.c src-1.0/bar.c hacks)
6056 @end example
6057
6058 @noindent
6059 produces the result @samp{.c .c}.
6060
6061 @item $(basename @var{names}@dots{})
6062 @findex basename
6063 @cindex basename
6064 @cindex file name, basename of
6065 Extracts all but the suffix of each file name in @var{names}. If the
6066 file name contains a period, the basename is everything starting up to
6067 (and not including) the last period. Periods in the directory part are
6068 ignored. If there is no period, the basename is the entire file name.
6069 For example,
6070
6071 @example
6072 $(basename src/foo.c src-1.0/bar hacks)
6073 @end example
6074
6075 @noindent
6076 produces the result @samp{src/foo src-1.0/bar hacks}.
6077
6078 @c plural convention with dots (be consistent)
6079 @item $(addsuffix @var{suffix},@var{names}@dots{})
6080 @findex addsuffix
6081 @cindex suffix, adding
6082 @cindex file name suffix, adding
6083 The argument @var{names} is regarded as a series of names, separated
6084 by whitespace; @var{suffix} is used as a unit. The value of
6085 @var{suffix} is appended to the end of each individual name and the
6086 resulting larger names are concatenated with single spaces between
6087 them. For example,
6088
6089 @example
6090 $(addsuffix .c,foo bar)
6091 @end example
6092
6093 @noindent
6094 produces the result @samp{foo.c bar.c}.
6095
6096 @item $(addprefix @var{prefix},@var{names}@dots{})
6097 @findex addprefix
6098 @cindex prefix, adding
6099 @cindex file name prefix, adding
6100 The argument @var{names} is regarded as a series of names, separated
6101 by whitespace; @var{prefix} is used as a unit. The value of
6102 @var{prefix} is prepended to the front of each individual name and the
6103 resulting larger names are concatenated with single spaces between
6104 them. For example,
6105
6106 @example
6107 $(addprefix src/,foo bar)
6108 @end example
6109
6110 @noindent
6111 produces the result @samp{src/foo src/bar}.
6112
6113 @item $(join @var{list1},@var{list2})
6114 @findex join
6115 @cindex joining lists of words
6116 @cindex words, joining lists
6117 Concatenates the two arguments word by word: the two first words (one
6118 from each argument) concatenated form the first word of the result, the
6119 two second words form the second word of the result, and so on. So the
6120 @var{n}th word of the result comes from the @var{n}th word of each
6121 argument. If one argument has more words that the other, the extra
6122 words are copied unchanged into the result.
6123
6124 For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
6125
6126 Whitespace between the words in the lists is not preserved; it is
6127 replaced with a single space.
6128
6129 This function can merge the results of the @code{dir} and
6130 @code{notdir} functions, to produce the original list of files which
6131 was given to those two functions.@refill
6132
6133 @item $(wildcard @var{pattern})
6134 @findex wildcard
6135 @cindex wildcard, function
6136 The argument @var{pattern} is a file name pattern, typically containing
6137 wildcard characters (as in shell file name patterns). The result of
6138 @code{wildcard} is a space-separated list of the names of existing files
6139 that match the pattern.
6140 @xref{Wildcards, ,Using Wildcard Characters in File Names}.
6141 @end table
6142
6143 @node Foreach Function, If Function, File Name Functions, Functions
6144 @section The @code{foreach} Function
6145 @findex foreach
6146 @cindex words, iterating over
6147
6148 The @code{foreach} function is very different from other functions. It
6149 causes one piece of text to be used repeatedly, each time with a different
6150 substitution performed on it. It resembles the @code{for} command in the
6151 shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
6152
6153 The syntax of the @code{foreach} function is:
6154
6155 @example
6156 $(foreach @var{var},@var{list},@var{text})
6157 @end example
6158
6159 @noindent
6160 The first two arguments, @var{var} and @var{list}, are expanded before
6161 anything else is done; note that the last argument, @var{text}, is
6162 @strong{not} expanded at the same time. Then for each word of the expanded
6163 value of @var{list}, the variable named by the expanded value of @var{var}
6164 is set to that word, and @var{text} is expanded. Presumably @var{text}
6165 contains references to that variable, so its expansion will be different
6166 each time.
6167
6168 The result is that @var{text} is expanded as many times as there are
6169 whitespace-separated words in @var{list}. The multiple expansions of
6170 @var{text} are concatenated, with spaces between them, to make the result
6171 of @code{foreach}.
6172
6173 This simple example sets the variable @samp{files} to the list of all files
6174 in the directories in the list @samp{dirs}:
6175
6176 @example
6177 dirs := a b c d
6178 files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
6179 @end example
6180
6181 Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition
6182 finds the value @samp{a} for @code{dir}, so it produces the same result
6183 as @samp{$(wildcard a/*)}; the second repetition produces the result
6184 of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
6185
6186 This example has the same result (except for setting @samp{dirs}) as
6187 the following example:
6188
6189 @example
6190 files := $(wildcard a/* b/* c/* d/*)
6191 @end example
6192
6193 When @var{text} is complicated, you can improve readability by giving it
6194 a name, with an additional variable:
6195
6196 @example
6197 find_files = $(wildcard $(dir)/*)
6198 dirs := a b c d
6199 files := $(foreach dir,$(dirs),$(find_files))
6200 @end example
6201
6202 @noindent
6203 Here we use the variable @code{find_files} this way. We use plain @samp{=}
6204 to define a recursively-expanding variable, so that its value contains an
6205 actual function call to be reexpanded under the control of @code{foreach};
6206 a simply-expanded variable would not do, since @code{wildcard} would be
6207 called only once at the time of defining @code{find_files}.
6208
6209 The @code{foreach} function has no permanent effect on the variable
6210 @var{var}; its value and flavor after the @code{foreach} function call are
6211 the same as they were beforehand. The other values which are taken from
6212 @var{list} are in effect only temporarily, during the execution of
6213 @code{foreach}. The variable @var{var} is a simply-expanded variable
6214 during the execution of @code{foreach}. If @var{var} was undefined
6215 before the @code{foreach} function call, it is undefined after the call.
6216 @xref{Flavors, ,The Two Flavors of Variables}.@refill
6217
6218 You must take care when using complex variable expressions that result in
6219 variable names because many strange things are valid variable names, but
6220 are probably not what you intended. For example,
6221
6222 @smallexample
6223 files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
6224 @end smallexample
6225
6226 @noindent
6227 might be useful if the value of @code{find_files} references the variable
6228 whose name is @samp{Esta escrito en espanol!} (es un nombre bastante largo,
6229 no?), but it is more likely to be a mistake.
6230
6231 @node If Function, Call Function, Foreach Function, Functions
6232 @section The @code{if} Function
6233 @findex if
6234 @cindex conditional expansion
6235
6236 The @code{if} function provides support for conditional expansion in a
6237 functional context (as opposed to the GNU @code{make} makefile
6238 conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of
6239 Conditionals}).
6240
6241 An @code{if} function call can contain either two or three arguments:
6242
6243 @example
6244 $(if @var{condition},@var{then-part}[,@var{else-part}])
6245 @end example
6246
6247 The first argument, @var{condition}, first has all preceding and
6248 trailing whitespace stripped, then is expanded. If it expands to any
6249 non-empty string, then the condition is considered to be true. If it
6250 expands to an empty string, the condition is considered to be false.
6251
6252 If the condition is true then the second argument, @var{then-part}, is
6253 evaluated and this is used as the result of the evaluation of the entire
6254 @code{if} function.
6255
6256 If the condition is false then the third argument, @var{else-part}, is
6257 evaluated and this is the result of the @code{if} function. If there is
6258 no third argument, the @code{if} function evaluates to nothing (the
6259 empty string).
6260
6261 Note that only one of the @var{then-part} or the @var{else-part} will be
6262 evaluated, never both. Thus, either can contain side-effects (such as
6263 @code{shell} function calls, etc.)
6264
6265 @node Call Function, Value Function, If Function, Functions
6266 @section The @code{call} Function
6267 @findex call
6268 @cindex functions, user defined
6269 @cindex user defined functions
6270
6271 The @code{call} function is unique in that it can be used to create new
6272 parameterized functions. You can write a complex expression as the
6273 value of a variable, then use @code{call} to expand it with different
6274 values.
6275
6276 The syntax of the @code{call} function is:
6277
6278 @example
6279 $(call @var{variable},@var{param},@var{param},@dots{})
6280 @end example
6281
6282 When @code{make} expands this function, it assigns each @var{param} to
6283 temporary variables @code{$(1)}, @code{$(2)}, etc. The variable
6284 @code{$(0)} will contain @var{variable}. There is no maximum number of
6285 parameter arguments. There is no minimum, either, but it doesn't make
6286 sense to use @code{call} with no parameters.
6287
6288 Then @var{variable} is expanded as a @code{make} variable in the context
6289 of these temporary assignments. Thus, any reference to @code{$(1)} in
6290 the value of @var{variable} will resolve to the first @var{param} in the
6291 invocation of @code{call}.
6292
6293 Note that @var{variable} is the @emph{name} of a variable, not a
6294 @emph{reference} to that variable. Therefore you would not normally use
6295 a @samp{$} or parentheses when writing it. (You can, however, use a
6296 variable reference in the name if you want the name not to be a
6297 constant.)
6298
6299 If @var{variable} is the name of a builtin function, the builtin function
6300 is always invoked (even if a @code{make} variable by that name also
6301 exists).
6302
6303 The @code{call} function expands the @var{param} arguments before
6304 assigning them to temporary variables. This means that @var{variable}
6305 values containing references to builtin functions that have special
6306 expansion rules, like @code{foreach} or @code{if}, may not work as you
6307 expect.
6308
6309 Some examples may make this clearer.
6310
6311 This macro simply reverses its arguments:
6312
6313 @smallexample
6314 reverse = $(2) $(1)
6315
6316 foo = $(call reverse,a,b)
6317 @end smallexample
6318
6319 @noindent
6320 Here @var{foo} will contain @samp{b a}.
6321
6322 This one is slightly more interesting: it defines a macro to search for
6323 the first instance of a program in @code{PATH}:
6324
6325 @smallexample
6326 pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
6327
6328 LS := $(call pathsearch,ls)
6329 @end smallexample
6330
6331 @noindent
6332 Now the variable LS contains @code{/bin/ls} or similar.
6333
6334 The @code{call} function can be nested. Each recursive invocation gets
6335 its own local values for @code{$(1)}, etc. that mask the values of
6336 higher-level @code{call}. For example, here is an implementation of a
6337 @dfn{map} function:
6338
6339 @smallexample
6340 map = $(foreach a,$(2),$(call $(1),$(a)))
6341 @end smallexample
6342
6343 Now you can @var{map} a function that normally takes only one argument,
6344 such as @code{origin}, to multiple values in one step:
6345
6346 @smallexample
6347 o = $(call map,origin,o map MAKE)
6348 @end smallexample
6349
6350 and end up with @var{o} containing something like @samp{file file default}.
6351
6352 A final caution: be careful when adding whitespace to the arguments to
6353 @code{call}. As with other functions, any whitespace contained in the
6354 second and subsequent arguments is kept; this can cause strange
6355 effects. It's generally safest to remove all extraneous whitespace when
6356 providing parameters to @code{call}.
6357
6358 @node Value Function, Eval Function, Call Function, Functions
6359 @comment node-name, next, previous, up
6360 @section The @code{value} Function
6361 @findex value
6362 @cindex variables, unexpanded value
6363
6364 The @code{value} function provides a way for you to use the value of a
6365 variable @emph{without} having it expanded. Please note that this
6366 does not undo expansions which have already occurred; for example if
6367 you create a simply expanded variable its value is expanded during the
6368 definition; in that case the @code{value} function will return the
6369 same result as using the variable directly.
6370
6371 The syntax of the @code{value} function is:
6372
6373 @example
6374 $(value @var{variable})
6375 @end example
6376
6377 Note that @var{variable} is the @emph{name} of a variable; not a
6378 @emph{reference} to that variable. Therefore you would not normally
6379 use a @samp{$} or parentheses when writing it. (You can, however, use
6380 a variable reference in the name if you want the name not to be a
6381 constant.)
6382
6383 The result of this function is a string containing the value of
6384 @var{variable}, without any expansion occurring. For example, in this
6385 makefile:
6386
6387 @example
6388 @group
6389 FOO = $PATH
6390
6391 all:
6392 @@echo $(FOO)
6393 @@echo $(value FOO)
6394 @end group
6395 @end example
6396
6397 @noindent
6398 The first output line would be @code{ATH}, since the ``$P'' would be
6399 expanded as a @code{make} variable, while the second output line would
6400 be the current value of your @code{$PATH} environment variable, since
6401 the @code{value} function avoided the expansion.
6402
6403 The @code{value} function is most often used in conjunction with the
6404 @code{eval} function (@pxref{Eval Function}).
6405
6406 @node Eval Function, Origin Function, Value Function, Functions
6407 @comment node-name, next, previous, up
6408 @section The @code{eval} Function
6409 @findex eval
6410 @cindex evaluating makefile syntax
6411 @cindex makefile syntax, evaluating
6412
6413 The @code{eval} function is very special: it allows you to define new
6414 makefile constructs that are not constant; which are the result of
6415 evaluating other variables and functions. The argument to the
6416 @code{eval} function is expanded, then the results of that expansion
6417 are parsed as makefile syntax. The expanded results can define new
6418 @code{make} variables, targets, implicit or explicit rules, etc.
6419
6420 The result of the @code{eval} function is always the empty string;
6421 thus, it can be placed virtually anywhere in a makefile without
6422 causing syntax errors.
6423
6424 It's important to realize that the @code{eval} argument is expanded
6425 @emph{twice}; first by the @code{eval} function, then the results of
6426 that expansion are expanded again when they are parsed as makefile
6427 syntax. This means you may need to provide extra levels of escaping
6428 for ``$'' characters when using @code{eval}. The @code{value}
6429 function (@pxref{Value Function}) can sometimes be useful in these
6430 situations, to circumvent unwanted expansions.
6431
6432 Here is an example of how @code{eval} can be used; this example
6433 combines a number of concepts and other functions. Although it might
6434 seem overly complex to use @code{eval} in this example, rather than
6435 just writing out the rules, consider two things: first, the template
6436 definition (in @code{PROGRAM_template}) could need to be much more
6437 complex than it is here; and second, you might put the complex,
6438 ``generic'' part of this example into another makefile, then include
6439 it in all the individual makefiles. Now your individual makefiles are
6440 quite straightforward.
6441
6442 @example
6443 @group
6444 PROGRAMS = server client
6445
6446 server_OBJS = server.o server_priv.o server_access.o
6447 server_LIBS = priv protocol
6448
6449 client_OBJS = client.o client_api.o client_mem.o
6450 client_LIBS = protocol
6451
6452 # Everything after this is generic
6453
6454 .PHONY: all
6455 all: $(PROGRAMS)
6456
6457 define PROGRAM_template
6458 $(1): $$($(1)_OBJ) $$($(1)_LIBS:%=-l%)
6459 ALL_OBJS += $$($(1)_OBJS)
6460 endef
6461
6462 $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
6463
6464 $(PROGRAMS):
6465 $(LINK.o) $^ $(LDLIBS) -o $@@
6466
6467 clean:
6468 rm -f $(ALL_OBJS) $(PROGRAMS)
6469 @end group
6470 @end example
6471
6472 @node Origin Function, Shell Function, Eval Function, Functions
6473 @section The @code{origin} Function
6474 @findex origin
6475 @cindex variables, origin of
6476 @cindex origin of variable
6477
6478 The @code{origin} function is unlike most other functions in that it does
6479 not operate on the values of variables; it tells you something @emph{about}
6480 a variable. Specifically, it tells you where it came from.
6481
6482 The syntax of the @code{origin} function is:
6483
6484 @example
6485 $(origin @var{variable})
6486 @end example
6487
6488 Note that @var{variable} is the @emph{name} of a variable to inquire about;
6489 not a @emph{reference} to that variable. Therefore you would not normally
6490 use a @samp{$} or parentheses when writing it. (You can, however, use a
6491 variable reference in the name if you want the name not to be a constant.)
6492
6493 The result of this function is a string telling you how the variable
6494 @var{variable} was defined:
6495
6496 @table @samp
6497 @item undefined
6498
6499 if @var{variable} was never defined.
6500
6501 @item default
6502
6503 if @var{variable} has a default definition, as is usual with @code{CC}
6504 and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
6505 Note that if you have redefined a default variable, the @code{origin}
6506 function will return the origin of the later definition.
6507
6508 @item environment
6509
6510 if @var{variable} was defined as an environment variable and the
6511 @samp{-e} option is @emph{not} turned on (@pxref{Options Summary, ,Summary of Options}).
6512
6513 @item environment override
6514
6515 if @var{variable} was defined as an environment variable and the
6516 @w{@samp{-e}} option @emph{is} turned on (@pxref{Options Summary,
6517 ,Summary of Options}).@refill
6518
6519 @item file
6520
6521 if @var{variable} was defined in a makefile.
6522
6523 @item command line
6524
6525 if @var{variable} was defined on the command line.
6526
6527 @item override
6528
6529 if @var{variable} was defined with an @code{override} directive in a
6530 makefile (@pxref{Override Directive, ,The @code{override} Directive}).
6531
6532 @item automatic
6533
6534 if @var{variable} is an automatic variable defined for the
6535 execution of the commands for each rule
6536 (@pxref{Automatic Variables}).
6537 @end table
6538
6539 This information is primarily useful (other than for your curiosity) to
6540 determine if you want to believe the value of a variable. For example,
6541 suppose you have a makefile @file{foo} that includes another makefile
6542 @file{bar}. You want a variable @code{bletch} to be defined in @file{bar}
6543 if you run the command @w{@samp{make -f bar}}, even if the environment contains
6544 a definition of @code{bletch}. However, if @file{foo} defined
6545 @code{bletch} before including @file{bar}, you do not want to override that
6546 definition. This could be done by using an @code{override} directive in
6547 @file{foo}, giving that definition precedence over the later definition in
6548 @file{bar}; unfortunately, the @code{override} directive would also
6549 override any command line definitions. So, @file{bar} could
6550 include:@refill
6551
6552 @example
6553 @group
6554 ifdef bletch
6555 ifeq "$(origin bletch)" "environment"
6556 bletch = barf, gag, etc.
6557 endif
6558 endif
6559 @end group
6560 @end example
6561
6562 @noindent
6563 If @code{bletch} has been defined from the environment, this will redefine
6564 it.
6565
6566 If you want to override a previous definition of @code{bletch} if it came
6567 from the environment, even under @samp{-e}, you could instead write:
6568
6569 @example
6570 @group
6571 ifneq "$(findstring environment,$(origin bletch))" ""
6572 bletch = barf, gag, etc.
6573 endif
6574 @end group
6575 @end example
6576
6577 Here the redefinition takes place if @samp{$(origin bletch)} returns either
6578 @samp{environment} or @samp{environment override}.
6579 @xref{Text Functions, , Functions for String Substitution and Analysis}.
6580
6581 @node Shell Function, Make Control Functions, Origin Function, Functions
6582 @section The @code{shell} Function
6583 @findex shell
6584 @cindex commands, expansion
6585 @cindex backquotes
6586 @cindex shell command, function for
6587
6588 The @code{shell} function is unlike any other function except the
6589 @code{wildcard} function
6590 (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
6591 communicates with the world outside of @code{make}.
6592
6593 The @code{shell} function performs the same function that backquotes
6594 (@samp{`}) perform in most shells: it does @dfn{command expansion}. This
6595 means that it takes an argument that is a shell command and returns the
6596 output of the command. The only processing @code{make} does on the result,
6597 before substituting it into the surrounding text, is to convert each
6598 newline or carriage-return / newline pair to a single space. It also
6599 removes the trailing (carriage-return and) newline, if it's the last
6600 thing in the result.@refill
6601
6602 The commands run by calls to the @code{shell} function are run when the
6603 function calls are expanded (@pxref{Reading Makefiles, , How
6604 @code{make} Reads a Makefile}). Because this function involves
6605 spawning a new shell, you should carefully consider the performance
6606 implications of using the @code{shell} function within recursively
6607 expanded variables vs. simply expanded variables (@pxref{Flavors, ,The
6608 Two Flavors of Variables}).
6609
6610 Here are some examples of the use of the @code{shell} function:
6611
6612 @example
6613 contents := $(shell cat foo)
6614 @end example
6615
6616 @noindent
6617 sets @code{contents} to the contents of the file @file{foo}, with a space
6618 (rather than a newline) separating each line.
6619
6620 @example
6621 files := $(shell echo *.c)
6622 @end example
6623
6624 @noindent
6625 sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is
6626 using a very strange shell, this has the same result as
6627 @w{@samp{$(wildcard *.c)}}.@refill
6628
6629 @node Make Control Functions, , Shell Function, Functions
6630 @section Functions That Control Make
6631 @cindex functions, for controlling make
6632 @cindex controlling make
6633
6634 These functions control the way make runs. Generally, they are used to
6635 provide information to the user of the makefile or to cause make to stop
6636 if some sort of environmental error is detected.
6637
6638 @table @code
6639 @item $(error @var{text}@dots{})
6640 @findex error
6641 @cindex error, stopping on
6642 @cindex stopping make
6643 Generates a fatal error where the message is @var{text}. Note that the
6644 error is generated whenever this function is evaluated. So, if you put
6645 it inside a command script or on the right side of a recursive variable
6646 assignment, it won't be evaluated until later. The @var{text} will be
6647 expanded before the error is generated.
6648
6649 For example,
6650
6651 @example
6652 ifdef ERROR1
6653 $(error error is $(ERROR1))
6654 endif
6655 @end example
6656
6657 @noindent
6658 will generate a fatal error during the read of the makefile if the
6659 @code{make} variable @code{ERROR1} is defined. Or,
6660
6661 @example
6662 ERR = $(error found an error!)
6663
6664 .PHONY: err
6665 err: ; $(ERR)
6666 @end example
6667
6668 @noindent
6669 will generate a fatal error while @code{make} is running, if the
6670 @code{err} target is invoked.
6671
6672 @item $(warning @var{text}@dots{})
6673 @findex warning
6674 @cindex warnings, printing
6675 @cindex printing user warnings
6676 This function works similarly to the @code{error} function, above,
6677 except that @code{make} doesn't exit. Instead, @var{text} is expanded
6678 and the resulting message is displayed, but processing of the makefile
6679 continues.
6680
6681 The result of the expansion of this function is the empty string.
6682 @end table
6683
6684 @node Running, Implicit Rules, Functions, Top
6685 @chapter How to Run @code{make}
6686
6687 A makefile that says how to recompile a program can be used in more
6688 than one way. The simplest use is to recompile every file that is out
6689 of date. Usually, makefiles are written so that if you run
6690 @code{make} with no arguments, it does just that.
6691
6692 But you might want to update only some of the files; you might want to use
6693 a different compiler or different compiler options; you might want just to
6694 find out which files are out of date without changing them.
6695
6696 By giving arguments when you run @code{make}, you can do any of these
6697 things and many others.
6698
6699 The exit status of @code{make} is always one of three values:
6700 @table @code
6701 @item 0
6702 The exit status is zero if @code{make} is successful.
6703 @item 2
6704 The exit status is two if @code{make} encounters any errors.
6705 It will print messages describing the particular errors.
6706 @item 1
6707 The exit status is one if you use the @samp{-q} flag and @code{make}
6708 determines that some target is not already up to date.
6709 @xref{Instead of Execution, ,Instead of Executing the Commands}.
6710 @end table
6711
6712 @menu
6713 * Makefile Arguments:: How to specify which makefile to use.
6714 * Goals:: How to use goal arguments to specify which
6715 parts of the makefile to use.
6716 * Instead of Execution:: How to use mode flags to specify what
6717 kind of thing to do with the commands
6718 in the makefile other than simply
6719 execute them.
6720 * Avoiding Compilation:: How to avoid recompiling certain files.
6721 * Overriding:: How to override a variable to specify
6722 an alternate compiler and other things.
6723 * Testing:: How to proceed past some errors, to
6724 test compilation.
6725 * Options Summary:: Summary of Options
6726 @end menu
6727
6728 @node Makefile Arguments, Goals, Running, Running
6729 @section Arguments to Specify the Makefile
6730 @cindex @code{--file}
6731 @cindex @code{--makefile}
6732 @cindex @code{-f}
6733
6734 The way to specify the name of the makefile is with the @samp{-f} or
6735 @samp{--file} option (@samp{--makefile} also works). For example,
6736 @samp{-f altmake} says to use the file @file{altmake} as the makefile.
6737
6738 If you use the @samp{-f} flag several times and follow each @samp{-f}
6739 with an argument, all the specified files are used jointly as
6740 makefiles.
6741
6742 If you do not use the @samp{-f} or @samp{--file} flag, the default is
6743 to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
6744 that order, and use the first of these three which exists or can be made
6745 (@pxref{Makefiles, ,Writing Makefiles}).@refill
6746
6747 @node Goals, Instead of Execution, Makefile Arguments, Running
6748 @section Arguments to Specify the Goals
6749 @cindex goal, how to specify
6750
6751 The @dfn{goals} are the targets that @code{make} should strive ultimately
6752 to update. Other targets are updated as well if they appear as
6753 prerequisites of goals, or prerequisites of prerequisites of goals, etc.
6754
6755 By default, the goal is the first target in the makefile (not counting
6756 targets that start with a period). Therefore, makefiles are usually
6757 written so that the first target is for compiling the entire program or
6758 programs they describe. If the first rule in the makefile has several
6759 targets, only the first target in the rule becomes the default goal, not
6760 the whole list.
6761
6762 You can specify a different goal or goals with arguments to @code{make}.
6763 Use the name of the goal as an argument. If you specify several goals,
6764 @code{make} processes each of them in turn, in the order you name them.
6765
6766 Any target in the makefile may be specified as a goal (unless it
6767 starts with @samp{-} or contains an @samp{=}, in which case it will be
6768 parsed as a switch or variable definition, respectively). Even
6769 targets not in the makefile may be specified, if @code{make} can find
6770 implicit rules that say how to make them.
6771
6772 @cindex @code{MAKECMDGOALS}
6773 @vindex MAKECMDGOALS
6774 @code{Make} will set the special variable @code{MAKECMDGOALS} to the
6775 list of goals you specified on the command line. If no goals were given
6776 on the command line, this variable is empty. Note that this variable
6777 should be used only in special circumstances.
6778
6779 An example of appropriate use is to avoid including @file{.d} files
6780 during @code{clean} rules (@pxref{Automatic Prerequisites}), so
6781 @code{make} won't create them only to immediately remove them
6782 again:@refill
6783
6784 @example
6785 @group
6786 sources = foo.c bar.c
6787
6788 ifneq ($(MAKECMDGOALS),clean)
6789 include $(sources:.c=.d)
6790 endif
6791 @end group
6792 @end example
6793
6794 One use of specifying a goal is if you want to compile only a part of
6795 the program, or only one of several programs. Specify as a goal each
6796 file that you wish to remake. For example, consider a directory containing
6797 several programs, with a makefile that starts like this:
6798
6799 @example
6800 .PHONY: all
6801 all: size nm ld ar as
6802 @end example
6803
6804 If you are working on the program @code{size}, you might want to say
6805 @w{@samp{make size}} so that only the files of that program are recompiled.
6806
6807 Another use of specifying a goal is to make files that are not normally
6808 made. For example, there may be a file of debugging output, or a
6809 version of the program that is compiled specially for testing, which has
6810 a rule in the makefile but is not a prerequisite of the default goal.
6811
6812 Another use of specifying a goal is to run the commands associated with
6813 a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
6814 Targets, ,Empty Target Files to Record Events}). Many makefiles contain
6815 a phony target named @file{clean} which deletes everything except source
6816 files. Naturally, this is done only if you request it explicitly with
6817 @w{@samp{make clean}}. Following is a list of typical phony and empty
6818 target names. @xref{Standard Targets}, for a detailed list of all the
6819 standard target names which GNU software packages use.
6820
6821 @table @file
6822 @item all
6823 @cindex @code{all} @r{(standard target)}
6824 Make all the top-level targets the makefile knows about.
6825
6826 @item clean
6827 @cindex @code{clean} @r{(standard target)}
6828 Delete all files that are normally created by running @code{make}.
6829
6830 @item mostlyclean
6831 @cindex @code{mostlyclean} @r{(standard target)}
6832 Like @samp{clean}, but may refrain from deleting a few files that people
6833 normally don't want to recompile. For example, the @samp{mostlyclean}
6834 target for GCC does not delete @file{libgcc.a}, because recompiling it
6835 is rarely necessary and takes a lot of time.
6836
6837 @item distclean
6838 @cindex @code{distclean} @r{(standard target)}
6839 @itemx realclean
6840 @cindex @code{realclean} @r{(standard target)}
6841 @itemx clobber
6842 @cindex @code{clobber} @r{(standard target)}
6843 Any of these targets might be defined to delete @emph{more} files than
6844 @samp{clean} does. For example, this would delete configuration files
6845 or links that you would normally create as preparation for compilation,
6846 even if the makefile itself cannot create these files.
6847
6848 @item install
6849 @cindex @code{install} @r{(standard target)}
6850 Copy the executable file into a directory that users typically search
6851 for commands; copy any auxiliary files that the executable uses into
6852 the directories where it will look for them.
6853
6854 @item print
6855 @cindex @code{print} @r{(standard target)}
6856 Print listings of the source files that have changed.
6857
6858 @item tar
6859 @cindex @code{tar} @r{(standard target)}
6860 Create a tar file of the source files.
6861
6862 @item shar
6863 @cindex @code{shar} @r{(standard target)}
6864 Create a shell archive (shar file) of the source files.
6865
6866 @item dist
6867 @cindex @code{dist} @r{(standard target)}
6868 Create a distribution file of the source files. This might
6869 be a tar file, or a shar file, or a compressed version of one of the
6870 above, or even more than one of the above.
6871
6872 @item TAGS
6873 @cindex @code{TAGS} @r{(standard target)}
6874 Update a tags table for this program.
6875
6876 @item check
6877 @cindex @code{check} @r{(standard target)}
6878 @itemx test
6879 @cindex @code{test} @r{(standard target)}
6880 Perform self tests on the program this makefile builds.
6881 @end table
6882
6883 @node Instead of Execution, Avoiding Compilation, Goals, Running
6884 @section Instead of Executing the Commands
6885 @cindex execution, instead of
6886 @cindex commands, instead of executing
6887
6888 The makefile tells @code{make} how to tell whether a target is up to date,
6889 and how to update each target. But updating the targets is not always
6890 what you want. Certain options specify other activities for @code{make}.
6891
6892 @comment Extra blank lines make it print better.
6893 @table @samp
6894 @item -n
6895 @itemx --just-print
6896 @itemx --dry-run
6897 @itemx --recon
6898 @cindex @code{--just-print}
6899 @cindex @code{--dry-run}
6900 @cindex @code{--recon}
6901 @cindex @code{-n}
6902
6903 ``No-op''. The activity is to print what commands would be used to make
6904 the targets up to date, but not actually execute them.
6905
6906 @item -t
6907 @itemx --touch
6908 @cindex @code{--touch}
6909 @cindex touching files
6910 @cindex target, touching
6911 @cindex @code{-t}
6912
6913 ``Touch''. The activity is to mark the targets as up to date without
6914 actually changing them. In other words, @code{make} pretends to compile
6915 the targets but does not really change their contents.
6916
6917 @item -q
6918 @itemx --question
6919 @cindex @code{--question}
6920 @cindex @code{-q}
6921 @cindex question mode
6922
6923 ``Question''. The activity is to find out silently whether the targets
6924 are up to date already; but execute no commands in either case. In other
6925 words, neither compilation nor output will occur.
6926
6927 @item -W @var{file}
6928 @itemx --what-if=@var{file}
6929 @itemx --assume-new=@var{file}
6930 @itemx --new-file=@var{file}
6931 @cindex @code{--what-if}
6932 @cindex @code{-W}
6933 @cindex @code{--assume-new}
6934 @cindex @code{--new-file}
6935 @cindex what if
6936 @cindex files, assuming new
6937
6938 ``What if''. Each @samp{-W} flag is followed by a file name. The given
6939 files' modification times are recorded by @code{make} as being the present
6940 time, although the actual modification times remain the same.
6941 You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
6942 to see what would happen if you were to modify specific files.@refill
6943 @end table
6944
6945 With the @samp{-n} flag, @code{make} prints the commands that it would
6946 normally execute but does not execute them.
6947
6948 With the @samp{-t} flag, @code{make} ignores the commands in the rules
6949 and uses (in effect) the command @code{touch} for each target that needs to
6950 be remade. The @code{touch} command is also printed, unless @samp{-s} or
6951 @code{.SILENT} is used. For speed, @code{make} does not actually invoke
6952 the program @code{touch}. It does the work directly.
6953
6954 With the @samp{-q} flag, @code{make} prints nothing and executes no
6955 commands, but the exit status code it returns is zero if and only if the
6956 targets to be considered are already up to date. If the exit status is
6957 one, then some updating needs to be done. If @code{make} encounters an
6958 error, the exit status is two, so you can distinguish an error from a
6959 target that is not up to date.
6960
6961 It is an error to use more than one of these three flags in the same
6962 invocation of @code{make}.
6963
6964 @cindex +, and command execution
6965 The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command
6966 lines that begin with @samp{+} characters or contain the strings
6967 @samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing
6968 the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
6969 is run regardless of these options. Other lines in the same rule are
6970 not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
6971 @samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
6972
6973 The @samp{-W} flag provides two features:
6974
6975 @itemize @bullet
6976 @item
6977 If you also use the @samp{-n} or @samp{-q} flag, you can see what
6978 @code{make} would do if you were to modify some files.
6979
6980 @item
6981 Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
6982 executing commands, the @samp{-W} flag can direct @code{make} to act
6983 as if some files had been modified, without actually modifying the
6984 files.@refill
6985 @end itemize
6986
6987 Note that the options @samp{-p} and @samp{-v} allow you to obtain other
6988 information about @code{make} or about the makefiles in use
6989 (@pxref{Options Summary, ,Summary of Options}).@refill
6990
6991 @node Avoiding Compilation, Overriding, Instead of Execution, Running
6992 @section Avoiding Recompilation of Some Files
6993 @cindex @code{-o}
6994 @cindex @code{--old-file}
6995 @cindex @code{--assume-old}
6996 @cindex files, assuming old
6997 @cindex files, avoiding recompilation of
6998 @cindex recompilation, avoiding
6999
7000 Sometimes you may have changed a source file but you do not want to
7001 recompile all the files that depend on it. For example, suppose you add
7002 a macro or a declaration to a header file that many other files depend
7003 on. Being conservative, @code{make} assumes that any change in the
7004 header file requires recompilation of all dependent files, but you know
7005 that they do not need to be recompiled and you would rather not waste
7006 the time waiting for them to compile.
7007
7008 If you anticipate the problem before changing the header file, you can
7009 use the @samp{-t} flag. This flag tells @code{make} not to run the
7010 commands in the rules, but rather to mark the target up to date by
7011 changing its last-modification date. You would follow this procedure:
7012
7013 @enumerate
7014 @item
7015 Use the command @samp{make} to recompile the source files that really
7016 need recompilation, ensuring that the object files are up-to-date
7017 before you begin.
7018
7019 @item
7020 Make the changes in the header files.
7021
7022 @item
7023 Use the command @samp{make -t} to mark all the object files as
7024 up to date. The next time you run @code{make}, the changes in the
7025 header files will not cause any recompilation.
7026 @end enumerate
7027
7028 If you have already changed the header file at a time when some files
7029 do need recompilation, it is too late to do this. Instead, you can
7030 use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
7031 ``old'' (@pxref{Options Summary, ,Summary of Options}). This means
7032 that the file itself will not be remade, and nothing else will be
7033 remade on its account. Follow this procedure:
7034
7035 @enumerate
7036 @item
7037 Recompile the source files that need compilation for reasons independent
7038 of the particular header file, with @samp{make -o @var{headerfile}}.
7039 If several header files are involved, use a separate @samp{-o} option
7040 for each header file.
7041
7042 @item
7043 Touch all the object files with @samp{make -t}.
7044 @end enumerate
7045
7046 @node Overriding, Testing, Avoiding Compilation, Running
7047 @section Overriding Variables
7048 @cindex overriding variables with arguments
7049 @cindex variables, overriding with arguments
7050 @cindex command line variables
7051 @cindex variables, command line
7052
7053 An argument that contains @samp{=} specifies the value of a variable:
7054 @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
7055 If you specify a value in this way, all ordinary assignments of the same
7056 variable in the makefile are ignored; we say they have been
7057 @dfn{overridden} by the command line argument.
7058
7059 The most common way to use this facility is to pass extra flags to
7060 compilers. For example, in a properly written makefile, the variable
7061 @code{CFLAGS} is included in each command that runs the C compiler, so a
7062 file @file{foo.c} would be compiled something like this:
7063
7064 @example
7065 cc -c $(CFLAGS) foo.c
7066 @end example
7067
7068 Thus, whatever value you set for @code{CFLAGS} affects each compilation
7069 that occurs. The makefile probably specifies the usual value for
7070 @code{CFLAGS}, like this:
7071
7072 @example
7073 CFLAGS=-g
7074 @end example
7075
7076 Each time you run @code{make}, you can override this value if you
7077 wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C
7078 compilation will be done with @samp{cc -c -g -O}. (This also
7079 illustrates how you can use quoting in the shell to enclose spaces and
7080 other special characters in the value of a variable when you override
7081 it.)
7082
7083 The variable @code{CFLAGS} is only one of many standard variables that
7084 exist just so that you can change them this way. @xref{Implicit
7085 Variables, , Variables Used by Implicit Rules}, for a complete list.
7086
7087 You can also program the makefile to look at additional variables of your
7088 own, giving the user the ability to control other aspects of how the
7089 makefile works by changing the variables.
7090
7091 When you override a variable with a command argument, you can define either
7092 a recursively-expanded variable or a simply-expanded variable. The
7093 examples shown above make a recursively-expanded variable; to make a
7094 simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless
7095 you want to include a variable reference or function call in the
7096 @emph{value} that you specify, it makes no difference which kind of
7097 variable you create.
7098
7099 There is one way that the makefile can change a variable that you have
7100 overridden. This is to use the @code{override} directive, which is a line
7101 that looks like this: @samp{override @var{variable} = @var{value}}
7102 (@pxref{Override Directive, ,The @code{override} Directive}).
7103
7104 @node Testing, Options Summary, Overriding, Running
7105 @section Testing the Compilation of a Program
7106 @cindex testing compilation
7107 @cindex compilation, testing
7108
7109 Normally, when an error happens in executing a shell command, @code{make}
7110 gives up immediately, returning a nonzero status. No further commands are
7111 executed for any target. The error implies that the goal cannot be
7112 correctly remade, and @code{make} reports this as soon as it knows.
7113
7114 When you are compiling a program that you have just changed, this is not
7115 what you want. Instead, you would rather that @code{make} try compiling
7116 every file that can be tried, to show you as many compilation errors
7117 as possible.
7118
7119 @cindex @code{-k}
7120 @cindex @code{--keep-going}
7121 On these occasions, you should use the @samp{-k} or
7122 @samp{--keep-going} flag. This tells @code{make} to continue to
7123 consider the other prerequisites of the pending targets, remaking them
7124 if necessary, before it gives up and returns nonzero status. For
7125 example, after an error in compiling one object file, @samp{make -k}
7126 will continue compiling other object files even though it already
7127 knows that linking them will be impossible. In addition to continuing
7128 after failed shell commands, @samp{make -k} will continue as much as
7129 possible after discovering that it does not know how to make a target
7130 or prerequisite file. This will always cause an error message, but
7131 without @samp{-k}, it is a fatal error (@pxref{Options Summary,
7132 ,Summary of Options}).@refill
7133
7134 The usual behavior of @code{make} assumes that your purpose is to get the
7135 goals up to date; once @code{make} learns that this is impossible, it might
7136 as well report the failure immediately. The @samp{-k} flag says that the
7137 real purpose is to test as much as possible of the changes made in the
7138 program, perhaps to find several independent problems so that you can
7139 correct them all before the next attempt to compile. This is why Emacs'
7140 @kbd{M-x compile} command passes the @samp{-k} flag by default.
7141
7142 @node Options Summary, , Testing, Running
7143 @section Summary of Options
7144 @cindex options
7145 @cindex flags
7146 @cindex switches
7147
7148 Here is a table of all the options @code{make} understands:
7149
7150 @table @samp
7151 @item -b
7152 @cindex @code{-b}
7153 @itemx -m
7154 @cindex @code{-m}
7155 These options are ignored for compatibility with other versions of @code{make}.
7156
7157 @item -B
7158 @cindex @code{-B}
7159 @itemx --always-make
7160 @cindex @code{--always-make}
7161 Consider all targets out-of-date. GNU @code{make} proceeds to
7162 consider targets and their prerequisites using the normal algorithms;
7163 however, all these targets are remade, regardless of the status of
7164 their prerequisites.
7165
7166 @item -C @var{dir}
7167 @cindex @code{-C}
7168 @itemx --directory=@var{dir}
7169 @cindex @code{--directory}
7170 Change to directory @var{dir} before reading the makefiles. If multiple
7171 @samp{-C} options are specified, each is interpreted relative to the
7172 previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
7173 This is typically used with recursive invocations of @code{make}
7174 (@pxref{Recursion, ,Recursive Use of @code{make}}).
7175
7176 @item -d
7177 @cindex @code{-d}
7178 @c Extra blank line here makes the table look better.
7179
7180 Print debugging information in addition to normal processing. The
7181 debugging information says which files are being considered for
7182 remaking, which file-times are being compared and with what results,
7183 which files actually need to be remade, which implicit rules are
7184 considered and which are applied---everything interesting about how
7185 @code{make} decides what to do. The @code{-d} option is equivalent to
7186 @samp{--debug=a} (see below).
7187
7188 @item --debug[=@var{options}]
7189 @cindex @code{--debug}
7190 @c Extra blank line here makes the table look better.
7191
7192 Print debugging information in addition to normal processing. Various
7193 levels and types of output can be chosen. With no arguments, print the
7194 ``basic'' level of debugging. Possible arguments are below; only the
7195 first character is considered, and values must be comma- or
7196 space-separated.
7197
7198 @table @code
7199 @item a (@i{all})
7200 All types of debugging output are enabled. This is equivalent to using
7201 @samp{-d}.
7202
7203 @item b (@i{basic})
7204 Basic debugging prints each target that was found to be out-of-date, and
7205 whether the build was successful or not.
7206
7207 @item v (@i{verbose})
7208 A level above @samp{basic}; includes messages about which makefiles were
7209 parsed, prerequisites that did not need to be rebuilt, etc. This option
7210 also enables @samp{basic} messages.
7211
7212 @item i (@i{implicit})
7213 Prints messages describing the implicit rule searches for each target.
7214 This option also enables @samp{basic} messages.
7215
7216 @item j (@i{jobs})
7217 Prints messages giving details on the invocation of specific subcommands.
7218
7219 @item m (@i{makefile})
7220 By default, the above messages are not enabled while trying to remake
7221 the makefiles. This option enables messages while rebuilding makefiles,
7222 too. Note that the @samp{all} option does enable this option. This
7223 option also enables @samp{basic} messages.
7224 @end table
7225
7226 @item -e
7227 @cindex @code{-e}
7228 @itemx --environment-overrides
7229 @cindex @code{--environment-overrides}
7230 Give variables taken from the environment precedence
7231 over variables from makefiles.
7232 @xref{Environment, ,Variables from the Environment}.
7233
7234 @item -f @var{file}
7235 @cindex @code{-f}
7236 @itemx --file=@var{file}
7237 @cindex @code{--file}
7238 @itemx --makefile=@var{file}
7239 @cindex @code{--makefile}
7240 Read the file named @var{file} as a makefile.
7241 @xref{Makefiles, ,Writing Makefiles}.
7242
7243 @item -h
7244 @cindex @code{-h}
7245 @itemx --help
7246 @cindex @code{--help}
7247 @c Extra blank line here makes the table look better.
7248
7249 Remind you of the options that @code{make} understands and then exit.
7250
7251 @item -i
7252 @cindex @code{-i}
7253 @itemx --ignore-errors
7254 @cindex @code{--ignore-errors}
7255 Ignore all errors in commands executed to remake files.
7256 @xref{Errors, ,Errors in Commands}.
7257
7258 @item -I @var{dir}
7259 @cindex @code{-I}
7260 @itemx --include-dir=@var{dir}
7261 @cindex @code{--include-dir}
7262 Specifies a directory @var{dir} to search for included makefiles.
7263 @xref{Include, ,Including Other Makefiles}. If several @samp{-I}
7264 options are used to specify several directories, the directories are
7265 searched in the order specified.
7266
7267 @item -j [@var{jobs}]
7268 @cindex @code{-j}
7269 @itemx --jobs[=@var{jobs}]
7270 @cindex @code{--jobs}
7271 Specifies the number of jobs (commands) to run simultaneously. With no
7272 argument, @code{make} runs as many jobs simultaneously as possible. If
7273 there is more than one @samp{-j} option, the last one is effective.
7274 @xref{Parallel, ,Parallel Execution},
7275 for more information on how commands are run.
7276 Note that this option is ignored on MS-DOS.
7277
7278 @item -k
7279 @cindex @code{-k}
7280 @itemx --keep-going
7281 @cindex @code{--keep-going}
7282 Continue as much as possible after an error. While the target that
7283 failed, and those that depend on it, cannot be remade, the other
7284 prerequisites of these targets can be processed all the same.
7285 @xref{Testing, ,Testing the Compilation of a Program}.
7286
7287 @item -l [@var{load}]
7288 @cindex @code{-l}
7289 @itemx --load-average[=@var{load}]
7290 @cindex @code{--load-average}
7291 @itemx --max-load[=@var{load}]
7292 @cindex @code{--max-load}
7293 Specifies that no new jobs (commands) should be started if there are
7294 other jobs running and the load average is at least @var{load} (a
7295 floating-point number). With no argument, removes a previous load
7296 limit. @xref{Parallel, ,Parallel Execution}.
7297
7298 @item -n
7299 @cindex @code{-n}
7300 @itemx --just-print
7301 @cindex @code{--just-print}
7302 @itemx --dry-run
7303 @cindex @code{--dry-run}
7304 @itemx --recon
7305 @cindex @code{--recon}
7306 @c Extra blank line here makes the table look better.
7307
7308 Print the commands that would be executed, but do not execute them.
7309 @xref{Instead of Execution, ,Instead of Executing the Commands}.
7310
7311 @item -o @var{file}
7312 @cindex @code{-o}
7313 @itemx --old-file=@var{file}
7314 @cindex @code{--old-file}
7315 @itemx --assume-old=@var{file}
7316 @cindex @code{--assume-old}
7317 Do not remake the file @var{file} even if it is older than its
7318 prerequisites, and do not remake anything on account of changes in
7319 @var{file}. Essentially the file is treated as very old and its rules
7320 are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of
7321 Some Files}.@refill
7322
7323 @item -p
7324 @cindex @code{-p}
7325 @itemx --print-data-base
7326 @cindex @code{--print-data-base}
7327 @cindex data base of @code{make} rules
7328 @cindex predefined rules and variables, printing
7329 Print the data base (rules and variable values) that results from
7330 reading the makefiles; then execute as usual or as otherwise specified.
7331 This also prints the version information given by the @samp{-v} switch
7332 (see below). To print the data base without trying to remake any files,
7333 use @w{@samp{make -qp}}. To print the data base of predefined rules and
7334 variables, use @w{@samp{make -p -f /dev/null}}. The data base output
7335 contains filename and linenumber information for command and variable
7336 definitions, so it can be a useful debugging tool in complex environments.
7337
7338 @item -q
7339 @cindex @code{-q}
7340 @itemx --question
7341 @cindex @code{--question}
7342 ``Question mode''. Do not run any commands, or print anything; just
7343 return an exit status that is zero if the specified targets are already
7344 up to date, one if any remaking is required, or two if an error is
7345 encountered. @xref{Instead of Execution, ,Instead of Executing the
7346 Commands}.@refill
7347
7348 @item -r
7349 @cindex @code{-r}
7350 @itemx --no-builtin-rules
7351 @cindex @code{--no-builtin-rules}
7352 Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
7353 ,Using Implicit Rules}). You can still define your own by writing
7354 pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
7355 Rules}). The @samp{-r} option also clears out the default list of
7356 suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
7357 Rules}). But you can still define your own suffixes with a rule for
7358 @code{.SUFFIXES}, and then define your own suffix rules. Note that only
7359 @emph{rules} are affected by the @code{-r} option; default variables
7360 remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit
7361 Rules}); see the @samp{-R} option below.
7362
7363 @item -R
7364 @cindex @code{-R}
7365 @itemx --no-builtin-variables
7366 @cindex @code{--no-builtin-variables}
7367 Eliminate use of the built-in rule-specific variables (@pxref{Implicit
7368 Variables, ,Variables Used by Implicit Rules}). You can still define
7369 your own, of course. The @samp{-R} option also automatically enables
7370 the @samp{-r} option (see above), since it doesn't make sense to have
7371 implicit rules without any definitions for the variables that they use.
7372
7373 @item -s
7374 @cindex @code{-s}
7375 @itemx --silent
7376 @cindex @code{--silent}
7377 @itemx --quiet
7378 @cindex @code{--quiet}
7379 @c Extra blank line here makes the table look better.
7380
7381 Silent operation; do not print the commands as they are executed.
7382 @xref{Echoing, ,Command Echoing}.
7383
7384 @item -S
7385 @cindex @code{-S}
7386 @itemx --no-keep-going
7387 @cindex @code{--no-keep-going}
7388 @itemx --stop
7389 @cindex @code{--stop}
7390 @c Extra blank line here makes the table look better.
7391
7392 Cancel the effect of the @samp{-k} option. This is never necessary
7393 except in a recursive @code{make} where @samp{-k} might be inherited
7394 from the top-level @code{make} via @code{MAKEFLAGS}
7395 (@pxref{Recursion, ,Recursive Use of @code{make}})
7396 or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
7397
7398 @item -t
7399 @cindex @code{-t}
7400 @itemx --touch
7401 @cindex @code{--touch}
7402 @c Extra blank line here makes the table look better.
7403
7404 Touch files (mark them up to date without really changing them)
7405 instead of running their commands. This is used to pretend that the
7406 commands were done, in order to fool future invocations of
7407 @code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}.
7408
7409 @item -v
7410 @cindex @code{-v}
7411 @itemx --version
7412 @cindex @code{--version}
7413 Print the version of the @code{make} program plus a copyright, a list
7414 of authors, and a notice that there is no warranty; then exit.
7415
7416 @item -w
7417 @cindex @code{-w}
7418 @itemx --print-directory
7419 @cindex @code{--print-directory}
7420 Print a message containing the working directory both before and after
7421 executing the makefile. This may be useful for tracking down errors
7422 from complicated nests of recursive @code{make} commands.
7423 @xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you
7424 rarely need to specify this option since @samp{make} does it for you;
7425 see @ref{-w Option, ,The @samp{--print-directory} Option}.)
7426
7427 @itemx --no-print-directory
7428 @cindex @code{--no-print-directory}
7429 Disable printing of the working directory under @code{-w}.
7430 This option is useful when @code{-w} is turned on automatically,
7431 but you do not want to see the extra messages.
7432 @xref{-w Option, ,The @samp{--print-directory} Option}.
7433
7434 @item -W @var{file}
7435 @cindex @code{-W}
7436 @itemx --what-if=@var{file}
7437 @cindex @code{--what-if}
7438 @itemx --new-file=@var{file}
7439 @cindex @code{--new-file}
7440 @itemx --assume-new=@var{file}
7441 @cindex @code{--assume-new}
7442 Pretend that the target @var{file} has just been modified. When used
7443 with the @samp{-n} flag, this shows you what would happen if you were
7444 to modify that file. Without @samp{-n}, it is almost the same as
7445 running a @code{touch} command on the given file before running
7446 @code{make}, except that the modification time is changed only in the
7447 imagination of @code{make}.
7448 @xref{Instead of Execution, ,Instead of Executing the Commands}.
7449
7450 @item --warn-undefined-variables
7451 @cindex @code{--warn-undefined-variables}
7452 @cindex variables, warning for undefined
7453 @cindex undefined variables, warning message
7454 Issue a warning message whenever @code{make} sees a reference to an
7455 undefined variable. This can be helpful when you are trying to debug
7456 makefiles which use variables in complex ways.
7457 @end table
7458
7459 @node Implicit Rules, Archives, Running, Top
7460 @chapter Using Implicit Rules
7461 @cindex implicit rule
7462 @cindex rule, implicit
7463
7464 Certain standard ways of remaking target files are used very often. For
7465 example, one customary way to make an object file is from a C source file
7466 using the C compiler, @code{cc}.
7467
7468 @dfn{Implicit rules} tell @code{make} how to use customary techniques so
7469 that you do not have to specify them in detail when you want to use
7470 them. For example, there is an implicit rule for C compilation. File
7471 names determine which implicit rules are run. For example, C
7472 compilation typically takes a @file{.c} file and makes a @file{.o} file.
7473 So @code{make} applies the implicit rule for C compilation when it sees
7474 this combination of file name endings.@refill
7475
7476 A chain of implicit rules can apply in sequence; for example, @code{make}
7477 will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
7478 @iftex
7479 @xref{Chained Rules, ,Chains of Implicit Rules}.
7480 @end iftex
7481
7482 The built-in implicit rules use several variables in their commands so
7483 that, by changing the values of the variables, you can change the way the
7484 implicit rule works. For example, the variable @code{CFLAGS} controls the
7485 flags given to the C compiler by the implicit rule for C compilation.
7486 @iftex
7487 @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
7488 @end iftex
7489
7490 You can define your own implicit rules by writing @dfn{pattern rules}.
7491 @iftex
7492 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
7493 @end iftex
7494
7495 @dfn{Suffix rules} are a more limited way to define implicit rules.
7496 Pattern rules are more general and clearer, but suffix rules are
7497 retained for compatibility.
7498 @iftex
7499 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
7500 @end iftex
7501
7502 @menu
7503 * Using Implicit:: How to use an existing implicit rule
7504 to get the commands for updating a file.
7505 * Catalogue of Rules:: A list of built-in implicit rules.
7506 * Implicit Variables:: How to change what predefined rules do.
7507 * Chained Rules:: How to use a chain of implicit rules.
7508 * Pattern Rules:: How to define new implicit rules.
7509 * Last Resort:: How to defining commands for rules
7510 which cannot find any.
7511 * Suffix Rules:: The old-fashioned style of implicit rule.
7512 * Implicit Rule Search:: The precise algorithm for applying
7513 implicit rules.
7514 @end menu
7515
7516 @node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules
7517 @section Using Implicit Rules
7518 @cindex implicit rule, how to use
7519 @cindex rule, implicit, how to use
7520
7521 To allow @code{make} to find a customary method for updating a target file,
7522 all you have to do is refrain from specifying commands yourself. Either
7523 write a rule with no command lines, or don't write a rule at all. Then
7524 @code{make} will figure out which implicit rule to use based on which
7525 kind of source file exists or can be made.
7526
7527 For example, suppose the makefile looks like this:
7528
7529 @example
7530 foo : foo.o bar.o
7531 cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
7532 @end example
7533
7534 @noindent
7535 Because you mention @file{foo.o} but do not give a rule for it, @code{make}
7536 will automatically look for an implicit rule that tells how to update it.
7537 This happens whether or not the file @file{foo.o} currently exists.
7538
7539 If an implicit rule is found, it can supply both commands and one or
7540 more prerequisites (the source files). You would want to write a rule
7541 for @file{foo.o} with no command lines if you need to specify additional
7542 prerequisites, such as header files, that the implicit rule cannot
7543 supply.
7544
7545 Each implicit rule has a target pattern and prerequisite patterns. There may
7546 be many implicit rules with the same target pattern. For example, numerous
7547 rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
7548 another, from a @samp{.p} file with the Pascal compiler; and so on. The rule
7549 that actually applies is the one whose prerequisites exist or can be made.
7550 So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
7551 otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
7552 compiler; and so on.
7553
7554 Of course, when you write the makefile, you know which implicit rule you
7555 want @code{make} to use, and you know it will choose that one because you
7556 know which possible prerequisite files are supposed to exist.
7557 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules},
7558 for a catalogue of all the predefined implicit rules.
7559
7560 Above, we said an implicit rule applies if the required prerequisites ``exist
7561 or can be made''. A file ``can be made'' if it is mentioned explicitly in
7562 the makefile as a target or a prerequisite, or if an implicit rule can be
7563 recursively found for how to make it. When an implicit prerequisite is the
7564 result of another implicit rule, we say that @dfn{chaining} is occurring.
7565 @xref{Chained Rules, ,Chains of Implicit Rules}.
7566
7567 In general, @code{make} searches for an implicit rule for each target, and
7568 for each double-colon rule, that has no commands. A file that is mentioned
7569 only as a prerequisite is considered a target whose rule specifies nothing,
7570 so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the
7571 details of how the search is done.
7572
7573 Note that explicit prerequisites do not influence implicit rule search.
7574 For example, consider this explicit rule:
7575
7576 @example
7577 foo.o: foo.p
7578 @end example
7579
7580 @noindent
7581 The prerequisite on @file{foo.p} does not necessarily mean that
7582 @code{make} will remake @file{foo.o} according to the implicit rule to
7583 make an object file, a @file{.o} file, from a Pascal source file, a
7584 @file{.p} file. For example, if @file{foo.c} also exists, the implicit
7585 rule to make an object file from a C source file is used instead,
7586 because it appears before the Pascal rule in the list of predefined
7587 implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit
7588 Rules}).
7589
7590 If you do not want an implicit rule to be used for a target that has no
7591 commands, you can give that target empty commands by writing a semicolon
7592 (@pxref{Empty Commands, ,Defining Empty Commands}).
7593
7594 @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
7595 @section Catalogue of Implicit Rules
7596 @cindex implicit rule, predefined
7597 @cindex rule, implicit, predefined
7598
7599 Here is a catalogue of predefined implicit rules which are always
7600 available unless the makefile explicitly overrides or cancels them.
7601 @xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
7602 canceling or overriding an implicit rule. The @samp{-r} or
7603 @samp{--no-builtin-rules} option cancels all predefined rules.
7604
7605 Not all of these rules will always be defined, even when the @samp{-r}
7606 option is not given. Many of the predefined implicit rules are
7607 implemented in @code{make} as suffix rules, so which ones will be
7608 defined depends on the @dfn{suffix list} (the list of prerequisites of
7609 the special target @code{.SUFFIXES}). The default suffix list is:
7610 @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
7611 @code{.C}, @code{.p}, @code{.f}, @code{.F}, @code{.r}, @code{.y},
7612 @code{.l}, @code{.s}, @code{.S}, @code{.mod}, @code{.sym}, @code{.def},
7613 @code{.h}, @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo},
7614 @code{.texi}, @code{.txinfo}, @code{.w}, @code{.ch} @code{.web},
7615 @code{.sh}, @code{.elc}, @code{.el}. All of the implicit rules
7616 described below whose prerequisites have one of these suffixes are
7617 actually suffix rules. If you modify the suffix list, the only
7618 predefined suffix rules in effect will be those named by one or two of
7619 the suffixes that are on the list you specify; rules whose suffixes fail
7620 to be on the list are disabled. @xref{Suffix Rules, ,Old-Fashioned
7621 Suffix Rules}, for full details on suffix rules.
7622
7623 @table @asis
7624 @item Compiling C programs
7625 @cindex C, rule to compile
7626 @pindex cc
7627 @pindex gcc
7628 @pindex .o
7629 @pindex .c
7630 @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
7631 a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill
7632
7633 @item Compiling C++ programs
7634 @cindex C++, rule to compile
7635 @pindex g++
7636 @pindex .C
7637 @pindex .cc
7638 @file{@var{n}.o} is made automatically from @file{@var{n}.cc} or
7639 @file{@var{n}.C} with a command of the form @samp{$(CXX) -c $(CPPFLAGS)
7640 $(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++
7641 source files instead of @samp{.C}.@refill
7642
7643 @item Compiling Pascal programs
7644 @cindex Pascal, rule to compile
7645 @pindex pc
7646 @pindex .p
7647 @file{@var{n}.o} is made automatically from @file{@var{n}.p}
7648 with the command @samp{$(PC) -c $(PFLAGS)}.@refill
7649
7650 @item Compiling Fortran and Ratfor programs
7651 @cindex Fortran, rule to compile
7652 @cindex Ratfor, rule to compile
7653 @pindex f77
7654 @pindex .f
7655 @pindex .r
7656 @pindex .F
7657 @file{@var{n}.o} is made automatically from @file{@var{n}.r},
7658 @file{@var{n}.F} or @file{@var{n}.f} by running the
7659 Fortran compiler. The precise command used is as follows:@refill
7660
7661 @table @samp
7662 @item .f
7663 @samp{$(FC) -c $(FFLAGS)}.
7664 @item .F
7665 @samp{$(FC) -c $(FFLAGS) $(CPPFLAGS)}.
7666 @item .r
7667 @samp{$(FC) -c $(FFLAGS) $(RFLAGS)}.
7668 @end table
7669
7670 @item Preprocessing Fortran and Ratfor programs
7671 @file{@var{n}.f} is made automatically from @file{@var{n}.r} or
7672 @file{@var{n}.F}. This rule runs just the preprocessor to convert a
7673 Ratfor or preprocessable Fortran program into a strict Fortran
7674 program. The precise command used is as follows:@refill
7675
7676 @table @samp
7677 @item .F
7678 @samp{$(FC) -F $(CPPFLAGS) $(FFLAGS)}.
7679 @item .r
7680 @samp{$(FC) -F $(FFLAGS) $(RFLAGS)}.
7681 @end table
7682
7683 @item Compiling Modula-2 programs
7684 @cindex Modula-2, rule to compile
7685 @pindex m2c
7686 @pindex .sym
7687 @pindex .def
7688 @pindex .mod
7689 @file{@var{n}.sym} is made from @file{@var{n}.def} with a command
7690 of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o}
7691 is made from @file{@var{n}.mod}; the form is:
7692 @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
7693
7694 @need 1200
7695 @item Assembling and preprocessing assembler programs
7696 @cindex assembly, rule to compile
7697 @pindex as
7698 @pindex .s
7699 @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
7700 running the assembler, @code{as}. The precise command is
7701 @samp{$(AS) $(ASFLAGS)}.@refill
7702
7703 @pindex .S
7704 @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
7705 running the C preprocessor, @code{cpp}. The precise command is
7706 @w{@samp{$(CPP) $(CPPFLAGS)}}.
7707
7708 @item Linking a single object file
7709 @cindex linking, predefined rule for
7710 @pindex ld
7711 @pindex .o
7712 @file{@var{n}} is made automatically from @file{@var{n}.o} by running
7713 the linker (usually called @code{ld}) via the C compiler. The precise
7714 command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}.
7715
7716 This rule does the right thing for a simple program with only one
7717 source file. It will also do the right thing if there are multiple
7718 object files (presumably coming from various other source files), one
7719 of which has a name matching that of the executable file. Thus,
7720
7721 @example
7722 x: y.o z.o
7723 @end example
7724
7725 @noindent
7726 when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
7727
7728 @example
7729 @group
7730 cc -c x.c -o x.o
7731 cc -c y.c -o y.o
7732 cc -c z.c -o z.o
7733 cc x.o y.o z.o -o x
7734 rm -f x.o
7735 rm -f y.o
7736 rm -f z.o
7737 @end group
7738 @end example
7739
7740 @noindent
7741 In more complicated cases, such as when there is no object file whose
7742 name derives from the executable file name, you must write an explicit
7743 command for linking.
7744
7745 Each kind of file automatically made into @samp{.o} object files will
7746 be automatically linked by using the compiler (@samp{$(CC)},
7747 @samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
7748 assemble @samp{.s} files) without the @samp{-c} option. This could be
7749 done by using the @samp{.o} object files as intermediates, but it is
7750 faster to do the compiling and linking in one step, so that's how it's
7751 done.@refill
7752
7753 @item Yacc for C programs
7754 @pindex yacc
7755 @cindex Yacc, rule to run
7756 @pindex .y
7757 @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
7758 running Yacc with the command @samp{$(YACC) $(YFLAGS)}.
7759
7760 @item Lex for C programs
7761 @pindex lex
7762 @cindex Lex, rule to run
7763 @pindex .l
7764 @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
7765 running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
7766
7767 @item Lex for Ratfor programs
7768 @file{@var{n}.r} is made automatically from @file{@var{n}.l} by
7769 running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}.
7770
7771 The convention of using the same suffix @samp{.l} for all Lex files
7772 regardless of whether they produce C code or Ratfor code makes it
7773 impossible for @code{make} to determine automatically which of the two
7774 languages you are using in any particular case. If @code{make} is
7775 called upon to remake an object file from a @samp{.l} file, it must
7776 guess which compiler to use. It will guess the C compiler, because
7777 that is more common. If you are using Ratfor, make sure @code{make}
7778 knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you
7779 are using Ratfor exclusively, with no C files, remove @samp{.c} from
7780 the list of implicit rule suffixes with:@refill
7781
7782 @example
7783 @group
7784 .SUFFIXES:
7785 .SUFFIXES: .o .r .f .l @dots{}
7786 @end group
7787 @end example
7788
7789 @item Making Lint Libraries from C, Yacc, or Lex programs
7790 @pindex lint
7791 @cindex @code{lint}, rule to run
7792 @pindex .ln
7793 @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
7794 The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
7795 The same command is used on the C code produced from
7796 @file{@var{n}.y} or @file{@var{n}.l}.@refill
7797
7798 @item @TeX{} and Web
7799 @cindex @TeX{}, rule to run
7800 @cindex Web, rule to run
7801 @pindex tex
7802 @pindex cweave
7803 @pindex weave
7804 @pindex tangle
7805 @pindex ctangle
7806 @pindex .dvi
7807 @pindex .tex
7808 @pindex .web
7809 @pindex .w
7810 @pindex .ch
7811 @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command
7812 @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with
7813 @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
7814 it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is
7815 made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
7816 is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
7817 or can be made) with @samp{$(CTANGLE)}.@refill
7818
7819 @item Texinfo and Info
7820 @cindex Texinfo, rule to format
7821 @cindex Info, rule to format
7822 @pindex texi2dvi
7823 @pindex makeinfo
7824 @pindex .texinfo
7825 @pindex .info
7826 @pindex .texi
7827 @pindex .txinfo
7828 @file{@var{n}.dvi} is made from @file{@var{n}.texinfo},
7829 @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command
7830 @w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from
7831 @file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with
7832 the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}.
7833
7834 @item RCS
7835 @cindex RCS, rule to extract from
7836 @pindex co
7837 @pindex ,v @r{(RCS file extension)}
7838 Any file @file{@var{n}} is extracted if necessary from an RCS file
7839 named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise
7840 command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be
7841 extracted from RCS if it already exists, even if the RCS file is
7842 newer. The rules for RCS are terminal
7843 (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
7844 so RCS files cannot be generated from another source; they must
7845 actually exist.@refill
7846
7847 @item SCCS
7848 @cindex SCCS, rule to extract from
7849 @pindex get
7850 @pindex s. @r{(SCCS file prefix)}
7851 Any file @file{@var{n}} is extracted if necessary from an SCCS file
7852 named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise
7853 command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are
7854 terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
7855 so SCCS files cannot be generated from another source; they must
7856 actually exist.@refill
7857
7858 @pindex .sh
7859 For the benefit of SCCS, a file @file{@var{n}} is copied from
7860 @file{@var{n}.sh} and made executable (by everyone). This is for
7861 shell scripts that are checked into SCCS. Since RCS preserves the
7862 execution permission of a file, you do not need to use this feature
7863 with RCS.@refill
7864
7865 We recommend that you avoid using of SCCS. RCS is widely held to be
7866 superior, and is also free. By choosing free software in place of
7867 comparable (or inferior) proprietary software, you support the free
7868 software movement.
7869 @end table
7870
7871 Usually, you want to change only the variables listed in the table
7872 above, which are documented in the following section.
7873
7874 However, the commands in built-in implicit rules actually use
7875 variables such as @code{COMPILE.c}, @code{LINK.p}, and
7876 @code{PREPROCESS.S}, whose values contain the commands listed above.
7877
7878 @code{make} follows the convention that the rule to compile a
7879 @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
7880 Similarly, the rule to produce an executable from a @file{.@var{x}}
7881 file uses @code{LINK.@var{x}}; and the rule to preprocess a
7882 @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
7883
7884 @vindex OUTPUT_OPTION
7885 Every rule that produces an object file uses the variable
7886 @code{OUTPUT_OPTION}. @code{make} defines this variable either to
7887 contain @samp{-o $@@}, or to be empty, depending on a compile-time
7888 option. You need the @samp{-o} option to ensure that the output goes
7889 into the right file when the source file is in a different directory,
7890 as when using @code{VPATH} (@pxref{Directory Search}). However,
7891 compilers on some systems do not accept a @samp{-o} switch for object
7892 files. If you use such a system, and use @code{VPATH}, some
7893 compilations will put their output in the wrong place.
7894 A possible workaround for this problem is to give @code{OUTPUT_OPTION}
7895 the value @w{@samp{; mv $*.o $@@}}.
7896
7897 @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
7898 @section Variables Used by Implicit Rules
7899 @cindex flags for compilers
7900
7901 The commands in built-in implicit rules make liberal use of certain
7902 predefined variables. You can alter these variables in the makefile,
7903 with arguments to @code{make}, or in the environment to alter how the
7904 implicit rules work without redefining the rules themselves. You can
7905 cancel all variables used by implicit rules with the @samp{-R} or
7906 @samp{--no-builtin-variables} option.
7907
7908 For example, the command used to compile a C source file actually says
7909 @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables
7910 used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By
7911 redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
7912 used for all C compilations performed by the implicit rule. By redefining
7913 @samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
7914 each compilation. @emph{All} implicit rules that do C compilation use
7915 @samp{$(CC)} to get the program name for the compiler and @emph{all}
7916 include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
7917
7918 The variables used in implicit rules fall into two classes: those that are
7919 names of programs (like @code{CC}) and those that contain arguments for the
7920 programs (like @code{CFLAGS}). (The ``name of a program'' may also contain
7921 some command arguments, but it must start with an actual executable program
7922 name.) If a variable value contains more than one argument, separate them
7923 with spaces.
7924
7925 Here is a table of variables used as names of programs in built-in rules:
7926
7927 @table @code
7928 @item AR
7929 @vindex AR
7930 Archive-maintaining program; default @samp{ar}.
7931 @pindex ar
7932
7933 @item AS
7934 @vindex AS
7935 Program for doing assembly; default @samp{as}.
7936 @pindex as
7937
7938 @item CC
7939 @vindex CC
7940 Program for compiling C programs; default @samp{cc}.
7941 @pindex cc
7942
7943 @item CXX
7944 @vindex CXX
7945 Program for compiling C++ programs; default @samp{g++}.
7946 @pindex g++
7947
7948 @item CO
7949 @vindex CO
7950 Program for extracting a file from RCS; default @samp{co}.
7951 @pindex co
7952
7953 @item CPP
7954 @vindex CPP
7955 Program for running the C preprocessor, with results to standard output;
7956 default @samp{$(CC) -E}.
7957
7958 @item FC
7959 @vindex FC
7960 Program for compiling or preprocessing Fortran and Ratfor programs;
7961 default @samp{f77}.
7962 @pindex f77
7963
7964 @item GET
7965 @vindex GET
7966 Program for extracting a file from SCCS; default @samp{get}.
7967 @pindex get
7968
7969 @item LEX
7970 @vindex LEX
7971 Program to use to turn Lex grammars into C programs or Ratfor programs;
7972 default @samp{lex}.
7973 @pindex lex
7974
7975 @item PC
7976 @vindex PC
7977 Program for compiling Pascal programs; default @samp{pc}.
7978 @pindex pc
7979
7980 @item YACC
7981 @vindex YACC
7982 Program to use to turn Yacc grammars into C programs; default @samp{yacc}.
7983 @pindex yacc
7984
7985 @item YACCR
7986 @vindex YACCR
7987 Program to use to turn Yacc grammars into Ratfor
7988 programs; default @samp{yacc -r}.
7989
7990 @item MAKEINFO
7991 @vindex MAKEINFO
7992 Program to convert a Texinfo source file into an Info file; default
7993 @samp{makeinfo}.
7994 @pindex makeinfo
7995
7996 @item TEX
7997 @vindex TEX
7998 Program to make @TeX{} @sc{dvi} files from @TeX{} source;
7999 default @samp{tex}.
8000 @pindex tex
8001
8002 @item TEXI2DVI
8003 @vindex TEXI2DVI
8004 Program to make @TeX{} @sc{dvi} files from Texinfo source;
8005 default @samp{texi2dvi}.
8006 @pindex texi2dvi
8007
8008 @item WEAVE
8009 @vindex WEAVE
8010 Program to translate Web into @TeX{}; default @samp{weave}.
8011 @pindex weave
8012
8013 @item CWEAVE
8014 @vindex CWEAVE
8015 Program to translate C Web into @TeX{}; default @samp{cweave}.
8016 @pindex cweave
8017
8018 @item TANGLE
8019 @vindex TANGLE
8020 Program to translate Web into Pascal; default @samp{tangle}.
8021 @pindex tangle
8022
8023 @item CTANGLE
8024 @vindex CTANGLE
8025 Program to translate C Web into C; default @samp{ctangle}.
8026 @pindex ctangle
8027
8028 @item RM
8029 @vindex RM
8030 Command to remove a file; default @samp{rm -f}.
8031 @pindex rm
8032 @end table
8033
8034 Here is a table of variables whose values are additional arguments for the
8035 programs above. The default values for all of these is the empty
8036 string, unless otherwise noted.
8037
8038 @table @code
8039 @item ARFLAGS
8040 @vindex ARFLAGS
8041 Flags to give the archive-maintaining program; default @samp{rv}.
8042
8043 @item ASFLAGS
8044 @vindex ASFLAGS
8045 Extra flags to give to the assembler (when explicitly
8046 invoked on a @samp{.s} or @samp{.S} file).
8047
8048 @item CFLAGS
8049 @vindex CFLAGS
8050 Extra flags to give to the C compiler.
8051
8052 @item CXXFLAGS
8053 @vindex CXXFLAGS
8054 Extra flags to give to the C++ compiler.
8055
8056 @item COFLAGS
8057 @vindex COFLAGS
8058 Extra flags to give to the RCS @code{co} program.
8059
8060 @item CPPFLAGS
8061 @vindex CPPFLAGS
8062 Extra flags to give to the C preprocessor and programs
8063 that use it (the C and Fortran compilers).
8064
8065 @item FFLAGS
8066 @vindex FFLAGS
8067 Extra flags to give to the Fortran compiler.
8068
8069 @item GFLAGS
8070 @vindex GFLAGS
8071 Extra flags to give to the SCCS @code{get} program.
8072
8073 @item LDFLAGS
8074 @vindex LDFLAGS
8075 Extra flags to give to compilers when they are
8076 supposed to invoke the linker, @samp{ld}.
8077
8078 @item LFLAGS
8079 @vindex LFLAGS
8080 Extra flags to give to Lex.
8081
8082 @item PFLAGS
8083 @vindex PFLAGS
8084 Extra flags to give to the Pascal compiler.
8085
8086 @item RFLAGS
8087 @vindex RFLAGS
8088 Extra flags to give to the Fortran compiler for Ratfor programs.
8089
8090 @item YFLAGS
8091 @vindex YFLAGS
8092 Extra flags to give to Yacc.
8093 @end table
8094
8095 @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
8096 @section Chains of Implicit Rules
8097
8098 @cindex chains of rules
8099 @cindex rule, implicit, chains of
8100 Sometimes a file can be made by a sequence of implicit rules. For example,
8101 a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
8102 first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
8103
8104 If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
8105 special searching is required: @code{make} finds that the object file can
8106 be made by C compilation from @file{@var{n}.c}; later on, when considering
8107 how to make @file{@var{n}.c}, the rule for running Yacc is
8108 used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
8109 updated.@refill
8110
8111 @cindex intermediate files
8112 @cindex files, intermediate
8113 However, even if @file{@var{n}.c} does not exist and is not mentioned,
8114 @code{make} knows how to envision it as the missing link between
8115 @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
8116 called an @dfn{intermediate file}. Once @code{make} has decided to use the
8117 intermediate file, it is entered in the data base as if it had been
8118 mentioned in the makefile, along with the implicit rule that says how to
8119 create it.@refill
8120
8121 Intermediate files are remade using their rules just like all other
8122 files. But intermediate files are treated differently in two ways.
8123
8124 The first difference is what happens if the intermediate file does not
8125 exist. If an ordinary file @var{b} does not exist, and @code{make}
8126 considers a target that depends on @var{b}, it invariably creates
8127 @var{b} and then updates the target from @var{b}. But if @var{b} is an
8128 intermediate file, then @code{make} can leave well enough alone. It
8129 won't bother updating @var{b}, or the ultimate target, unless some
8130 prerequisite of @var{b} is newer than that target or there is some other
8131 reason to update that target.
8132
8133 The second difference is that if @code{make} @emph{does} create @var{b}
8134 in order to update something else, it deletes @var{b} later on after it
8135 is no longer needed. Therefore, an intermediate file which did not
8136 exist before @code{make} also does not exist after @code{make}.
8137 @code{make} reports the deletion to you by printing a @samp{rm -f}
8138 command showing which file it is deleting.
8139
8140 Ordinarily, a file cannot be intermediate if it is mentioned in the
8141 makefile as a target or prerequisite. However, you can explicitly mark a
8142 file as intermediate by listing it as a prerequisite of the special target
8143 @code{.INTERMEDIATE}. This takes effect even if the file is mentioned
8144 explicitly in some other way.
8145
8146 @cindex intermediate files, preserving
8147 @cindex preserving intermediate files
8148 @cindex secondary files
8149 You can prevent automatic deletion of an intermediate file by marking it
8150 as a @dfn{secondary} file. To do this, list it as a prerequisite of the
8151 special target @code{.SECONDARY}. When a file is secondary, @code{make}
8152 will not create the file merely because it does not already exist, but
8153 @code{make} does not automatically delete the file. Marking a file as
8154 secondary also marks it as intermediate.
8155
8156 You can list the target pattern of an implicit rule (such as @samp{%.o})
8157 as a prerequisite of the special target @code{.PRECIOUS} to preserve
8158 intermediate files made by implicit rules whose target patterns match
8159 that file's name; see @ref{Interrupts}.@refill
8160 @cindex preserving with @code{.PRECIOUS}
8161 @cindex @code{.PRECIOUS} intermediate files
8162
8163 A chain can involve more than two implicit rules. For example, it is
8164 possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
8165 Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are
8166 intermediate files that are deleted at the end.@refill
8167
8168 No single implicit rule can appear more than once in a chain. This means
8169 that @code{make} will not even consider such a ridiculous thing as making
8170 @file{foo} from @file{foo.o.o} by running the linker twice. This
8171 constraint has the added benefit of preventing any infinite loop in the
8172 search for an implicit rule chain.
8173
8174 There are some special implicit rules to optimize certain cases that would
8175 otherwise be handled by rule chains. For example, making @file{foo} from
8176 @file{foo.c} could be handled by compiling and linking with separate
8177 chained rules, using @file{foo.o} as an intermediate file. But what
8178 actually happens is that a special rule for this case does the compilation
8179 and linking with a single @code{cc} command. The optimized rule is used in
8180 preference to the step-by-step chain because it comes earlier in the
8181 ordering of rules.
8182
8183 @node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
8184 @section Defining and Redefining Pattern Rules
8185
8186 You define an implicit rule by writing a @dfn{pattern rule}. A pattern
8187 rule looks like an ordinary rule, except that its target contains the
8188 character @samp{%} (exactly one of them). The target is considered a
8189 pattern for matching file names; the @samp{%} can match any nonempty
8190 substring, while other characters match only themselves. The prerequisites
8191 likewise use @samp{%} to show how their names relate to the target name.
8192
8193 Thus, a pattern rule @samp{%.o : %.c} says how to make any file
8194 @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
8195
8196 Note that expansion using @samp{%} in pattern rules occurs
8197 @strong{after} any variable or function expansions, which take place
8198 when the makefile is read. @xref{Using Variables, , How to Use
8199 Variables}, and @ref{Functions, ,Functions for Transforming Text}.
8200
8201 @menu
8202 * Pattern Intro:: An introduction to pattern rules.
8203 * Pattern Examples:: Examples of pattern rules.
8204 * Automatic Variables:: How to use automatic variables in the
8205 commands of implicit rules.
8206 * Pattern Match:: How patterns match.
8207 * Match-Anything Rules:: Precautions you should take prior to
8208 defining rules that can match any
8209 target file whatever.
8210 * Canceling Rules:: How to override or cancel built-in rules.
8211 @end menu
8212
8213 @node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules
8214 @subsection Introduction to Pattern Rules
8215 @cindex pattern rule
8216 @cindex rule, pattern
8217
8218 A pattern rule contains the character @samp{%} (exactly one of them)
8219 in the target; otherwise, it looks exactly like an ordinary rule. The
8220 target is a pattern for matching file names; the @samp{%} matches any
8221 nonempty substring, while other characters match only themselves.
8222 @cindex target pattern, implicit
8223 @cindex @code{%}, in pattern rules
8224
8225 For example, @samp{%.c} as a pattern matches any file name that ends in
8226 @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
8227 with @samp{s.}, ends in @samp{.c} and is at least five characters long.
8228 (There must be at least one character to match the @samp{%}.) The substring
8229 that the @samp{%} matches is called the @dfn{stem}.@refill
8230
8231 @samp{%} in a prerequisite of a pattern rule stands for the same stem
8232 that was matched by the @samp{%} in the target. In order for
8233 the pattern rule to apply, its target pattern must match the file name
8234 under consideration, and its prerequisite patterns must name files that
8235 exist or can be made. These files become prerequisites of the target.
8236 @cindex prerequisite pattern, implicit
8237
8238 Thus, a rule of the form
8239
8240 @example
8241 %.o : %.c ; @var{command}@dots{}
8242 @end example
8243
8244 @noindent
8245 specifies how to make a file @file{@var{n}.o}, with another file
8246 @file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c}
8247 exists or can be made.
8248
8249 There may also be prerequisites that do not use @samp{%}; such a prerequisite
8250 attaches to every file made by this pattern rule. These unvarying
8251 prerequisites are useful occasionally.
8252
8253 A pattern rule need not have any prerequisites that contain @samp{%}, or
8254 in fact any prerequisites at all. Such a rule is effectively a general
8255 wildcard. It provides a way to make any file that matches the target
8256 pattern. @xref{Last Resort}.
8257
8258 @c !!! The end of of this paragraph should be rewritten. --bob
8259 Pattern rules may have more than one target. Unlike normal rules, this
8260 does not act as many different rules with the same prerequisites and
8261 commands. If a pattern rule has multiple targets, @code{make} knows that
8262 the rule's commands are responsible for making all of the targets. The
8263 commands are executed only once to make all the targets. When searching
8264 for a pattern rule to match a target, the target patterns of a rule other
8265 than the one that matches the target in need of a rule are incidental:
8266 @code{make} worries only about giving commands and prerequisites to the file
8267 presently in question. However, when this file's commands are run, the
8268 other targets are marked as having been updated themselves.
8269 @cindex multiple targets, in pattern rule
8270 @cindex target, multiple in pattern rule
8271
8272 The order in which pattern rules appear in the makefile is important
8273 since this is the order in which they are considered.
8274 Of equally applicable
8275 rules, only the first one found is used. The rules you write take precedence
8276 over those that are built in. Note however, that a rule whose
8277 prerequisites actually exist or are mentioned always takes priority over a
8278 rule with prerequisites that must be made by chaining other implicit rules.
8279 @cindex pattern rules, order of
8280 @cindex order of pattern rules
8281
8282 @node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules
8283 @subsection Pattern Rule Examples
8284
8285 Here are some examples of pattern rules actually predefined in
8286 @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o}
8287 files:@refill
8288
8289 @example
8290 %.o : %.c
8291 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
8292 @end example
8293
8294 @noindent
8295 defines a rule that can make any file @file{@var{x}.o} from
8296 @file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and
8297 @samp{$<} to substitute the names of the target file and the source file
8298 in each case where the rule applies (@pxref{Automatic Variables}).@refill
8299
8300 Here is a second built-in rule:
8301
8302 @example
8303 % :: RCS/%,v
8304 $(CO) $(COFLAGS) $<
8305 @end example
8306
8307 @noindent
8308 defines a rule that can make any file @file{@var{x}} whatsoever from a
8309 corresponding file @file{@var{x},v} in the subdirectory @file{RCS}. Since
8310 the target is @samp{%}, this rule will apply to any file whatever, provided
8311 the appropriate prerequisite file exists. The double colon makes the rule
8312 @dfn{terminal}, which means that its prerequisite may not be an intermediate
8313 file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
8314
8315 @need 500
8316 This pattern rule has two targets:
8317
8318 @example
8319 @group
8320 %.tab.c %.tab.h: %.y
8321 bison -d $<
8322 @end group
8323 @end example
8324
8325 @noindent
8326 @c The following paragraph is rewritten to avoid overfull hboxes
8327 This tells @code{make} that the command @samp{bison -d @var{x}.y} will
8328 make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file
8329 @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
8330 and the file @file{scan.o} depends on the file @file{parse.tab.h},
8331 when @file{parse.y} is changed, the command @samp{bison -d parse.y}
8332 will be executed only once, and the prerequisites of both
8333 @file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably
8334 the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
8335 and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
8336 linked from @file{parse.tab.o}, @file{scan.o}, and its other
8337 prerequisites, and it will execute happily ever after.)@refill
8338
8339 @node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules
8340 @subsection Automatic Variables
8341 @cindex automatic variables
8342 @cindex variables, automatic
8343 @cindex variables, and implicit rule
8344
8345 Suppose you are writing a pattern rule to compile a @samp{.c} file into a
8346 @samp{.o} file: how do you write the @samp{cc} command so that it operates
8347 on the right source file name? You cannot write the name in the command,
8348 because the name is different each time the implicit rule is applied.
8349
8350 What you do is use a special feature of @code{make}, the @dfn{automatic
8351 variables}. These variables have values computed afresh for each rule that
8352 is executed, based on the target and prerequisites of the rule. In this
8353 example, you would use @samp{$@@} for the object file name and @samp{$<}
8354 for the source file name.
8355
8356 @cindex automatic variables in prerequisites
8357 @cindex prerequisites, and automatic variables
8358 It's very important that you recognize the limited scope in which
8359 automatic variable values are available: they only have values within
8360 the command script. In particular, you cannot use them anywhere
8361 within the target or prerequisite lists of a rule; they have no value
8362 there and will expand to the empty string. A common mistake is
8363 attempting to use @code{$@@} within the prerequisites list in a rule;
8364 this will not work. However, see below for information on the
8365 SysV-style @code{$$@@} variables.
8366
8367 Here is a table of automatic variables:
8368
8369 @table @code
8370 @vindex $@@
8371 @vindex @@ @r{(automatic variable)}
8372 @item $@@
8373 The file name of the target of the rule. If the target is an archive
8374 member, then @samp{$@@} is the name of the archive file. In a pattern
8375 rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
8376 Pattern Rules}), @samp{$@@} is the name of whichever target caused the
8377 rule's commands to be run.
8378
8379 @vindex $%
8380 @vindex % @r{(automatic variable)}
8381 @item $%
8382 The target member name, when the target is an archive member.
8383 @xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then
8384 @samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is
8385 empty when the target is not an archive member.
8386
8387 @vindex $<
8388 @vindex < @r{(automatic variable)}
8389 @item $<
8390 The name of the first prerequisite. If the target got its commands from
8391 an implicit rule, this will be the first prerequisite added by the
8392 implicit rule (@pxref{Implicit Rules}).
8393
8394 @vindex $?
8395 @vindex ? @r{(automatic variable)}
8396 @item $?
8397 The names of all the prerequisites that are newer than the target, with
8398 spaces between them. For prerequisites which are archive members, only
8399 the member named is used (@pxref{Archives}).
8400 @cindex prerequisites, list of changed
8401 @cindex list of changed prerequisites
8402
8403 @vindex $^
8404 @vindex ^ @r{(automatic variable)}
8405 @item $^
8406 The names of all the prerequisites, with spaces between them. For
8407 prerequisites which are archive members, only the member named is used
8408 (@pxref{Archives}). A target has only one prerequisite on each other file
8409 it depends on, no matter how many times each file is listed as a
8410 prerequisite. So if you list a prerequisite more than once for a target,
8411 the value of @code{$^} contains just one copy of the name.
8412 @cindex prerequisites, list of all
8413 @cindex list of all prerequisites
8414
8415 @vindex $+
8416 @vindex + @r{(automatic variable)}
8417 @item $+
8418 This is like @samp{$^}, but prerequisites listed more than once are
8419 duplicated in the order they were listed in the makefile. This is
8420 primarily useful for use in linking commands where it is meaningful to
8421 repeat library file names in a particular order.
8422
8423 @vindex $*
8424 @vindex * @r{(automatic variable)}
8425 @item $*
8426 The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
8427 Patterns Match}). If the target is @file{dir/a.foo.b} and the target
8428 pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is
8429 useful for constructing names of related files.@refill
8430 @cindex stem, variable for
8431
8432 In a static pattern rule, the stem is part of the file name that matched
8433 the @samp{%} in the target pattern.
8434
8435 In an explicit rule, there is no stem; so @samp{$*} cannot be determined
8436 in that way. Instead, if the target name ends with a recognized suffix
8437 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
8438 the target name minus the suffix. For example, if the target name is
8439 @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
8440 suffix. GNU @code{make} does this bizarre thing only for compatibility
8441 with other implementations of @code{make}. You should generally avoid
8442 using @samp{$*} except in implicit rules or static pattern rules.@refill
8443
8444 If the target name in an explicit rule does not end with a recognized
8445 suffix, @samp{$*} is set to the empty string for that rule.
8446 @end table
8447
8448 @samp{$?} is useful even in explicit rules when you wish to operate on only
8449 the prerequisites that have changed. For example, suppose that an archive
8450 named @file{lib} is supposed to contain copies of several object files.
8451 This rule copies just the changed object files into the archive:
8452
8453 @example
8454 @group
8455 lib: foo.o bar.o lose.o win.o
8456 ar r lib $?
8457 @end group
8458 @end example
8459
8460 Of the variables listed above, four have values that are single file
8461 names, and three have values that are lists of file names. These seven
8462 have variants that get just the file's directory name or just the file
8463 name within the directory. The variant variables' names are formed by
8464 appending @samp{D} or @samp{F}, respectively. These variants are
8465 semi-obsolete in GNU @code{make} since the functions @code{dir} and
8466 @code{notdir} can be used to get a similar effect (@pxref{File Name
8467 Functions, , Functions for File Names}). Note, however, that the
8468 @samp{D} variants all omit the trailing slash which always appears in
8469 the output of the @code{dir} function. Here is a table of the variants:
8470
8471 @table @samp
8472 @vindex $(@@D)
8473 @vindex @@D @r{(automatic variable)}
8474 @item $(@@D)
8475 The directory part of the file name of the target, with the trailing
8476 slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then
8477 @samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does
8478 not contain a slash.
8479
8480 @vindex $(@@F)
8481 @vindex @@F @r{(automatic variable)}
8482 @item $(@@F)
8483 The file-within-directory part of the file name of the target. If the
8484 value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
8485 @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
8486
8487 @vindex $(*D)
8488 @vindex *D @r{(automatic variable)}
8489 @item $(*D)
8490 @vindex $(*F)
8491 @vindex *F @r{(automatic variable)}
8492 @itemx $(*F)
8493 The directory part and the file-within-directory
8494 part of the stem; @file{dir} and @file{foo} in this example.
8495
8496 @vindex $(%D)
8497 @vindex %D @r{(automatic variable)}
8498 @item $(%D)
8499 @vindex $(%F)
8500 @vindex %F @r{(automatic variable)}
8501 @itemx $(%F)
8502 The directory part and the file-within-directory part of the target
8503 archive member name. This makes sense only for archive member targets
8504 of the form @file{@var{archive}(@var{member})} and is useful only when
8505 @var{member} may contain a directory name. (@xref{Archive Members,
8506 ,Archive Members as Targets}.)
8507
8508 @vindex $(<D)
8509 @vindex <D @r{(automatic variable)}
8510 @item $(<D)
8511 @vindex $(<F)
8512 @vindex <F @r{(automatic variable)}
8513 @itemx $(<F)
8514 The directory part and the file-within-directory
8515 part of the first prerequisite.
8516
8517 @vindex $(^D)
8518 @vindex ^D @r{(automatic variable)}
8519 @item $(^D)
8520 @vindex $(^F)
8521 @vindex ^F @r{(automatic variable)}
8522 @itemx $(^F)
8523 Lists of the directory parts and the file-within-directory
8524 parts of all prerequisites.
8525
8526 @vindex $(+D)
8527 @vindex +D @r{(automatic variable)}
8528 @item $(+D)
8529 @vindex $(+F)
8530 @vindex +F @r{(automatic variable)}
8531 @itemx $(+F)
8532 Lists of the directory parts and the file-within-directory
8533 parts of all prerequisites, including multiple instances of duplicated
8534 prerequisites.
8535
8536 @vindex $(?D)
8537 @vindex ?D @r{(automatic variable)}
8538 @item $(?D)
8539 @vindex $(?F)
8540 @vindex ?F @r{(automatic variable)}
8541 @itemx $(?F)
8542 Lists of the directory parts and the file-within-directory parts of
8543 all prerequisites that are newer than the target.
8544 @end table
8545
8546 Note that we use a special stylistic convention when we talk about these
8547 automatic variables; we write ``the value of @samp{$<}'', rather than
8548 @w{``the variable @code{<}''} as we would write for ordinary variables
8549 such as @code{objects} and @code{CFLAGS}. We think this convention
8550 looks more natural in this special case. Please do not assume it has a
8551 deep significance; @samp{$<} refers to the variable named @code{<} just
8552 as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
8553 You could just as well use @samp{$(<)} in place of @samp{$<}.
8554
8555 @vindex $$@@
8556 @vindex $$(@@D)
8557 @vindex $$(@@F)
8558 @cindex $$@@, support for
8559 GNU @code{make} provides support for the SysV @code{make} feature that
8560 allows special variable references @code{$$@@}, @code{$$(@@D)}, and
8561 @code{$$(@@F)} (note the required double-''$''!) to appear with the
8562 @emph{prerequisites list} (normal automatic variables are available
8563 only within a command script). When appearing in a prerequisites
8564 list, these variables are expanded to the name of the target, the
8565 directory component of the target, and the file component of the
8566 target, respectively.
8567
8568 Note that these variables are available only within explicit and
8569 static pattern (@pxref{Static Pattern, ,Static Pattern Rules}) rules;
8570 they have no special significance within implicit (suffix or pattern)
8571 rules. Also note that while SysV @code{make} actually expands its
8572 entire prerequisite list @emph{twice}, GNU @code{make} does not behave
8573 this way: instead it simply expands these special variables without
8574 re-expanding any other part of the prerequisites list.
8575
8576 This somewhat bizarre feature is included only to provide some
8577 compatibility with SysV makefiles. In a native GNU @code{make} file
8578 there are other ways to accomplish the same results. This feature is
8579 disabled if the special pseudo target @code{.POSIX} is defined.
8580
8581 @node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules
8582 @subsection How Patterns Match
8583
8584 @cindex stem
8585 A target pattern is composed of a @samp{%} between a prefix and a suffix,
8586 either or both of which may be empty. The pattern matches a file name only
8587 if the file name starts with the prefix and ends with the suffix, without
8588 overlap. The text between the prefix and the suffix is called the
8589 @dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name
8590 @file{test.o}, the stem is @samp{test}. The pattern rule prerequisites are
8591 turned into actual file names by substituting the stem for the character
8592 @samp{%}. Thus, if in the same example one of the prerequisites is written
8593 as @samp{%.c}, it expands to @samp{test.c}.@refill
8594
8595 When the target pattern does not contain a slash (and it usually does
8596 not), directory names in the file names are removed from the file name
8597 before it is compared with the target prefix and suffix. After the
8598 comparison of the file name to the target pattern, the directory
8599 names, along with the slash that ends them, are added on to the
8600 prerequisite file names generated from the pattern rule's prerequisite
8601 patterns and the file name. The directories are ignored only for the
8602 purpose of finding an implicit rule to use, not in the application of
8603 that rule. Thus, @samp{e%t} matches the file name @file{src/eat},
8604 with @samp{src/a} as the stem. When prerequisites are turned into file
8605 names, the directories from the stem are added at the front, while the
8606 rest of the stem is substituted for the @samp{%}. The stem
8607 @samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name
8608 @file{src/car}.@refill
8609
8610 @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
8611 @subsection Match-Anything Pattern Rules
8612
8613 @cindex match-anything rule
8614 @cindex terminal rule
8615 When a pattern rule's target is just @samp{%}, it matches any file name
8616 whatever. We call these rules @dfn{match-anything} rules. They are very
8617 useful, but it can take a lot of time for @code{make} to think about them,
8618 because it must consider every such rule for each file name listed either
8619 as a target or as a prerequisite.
8620
8621 Suppose the makefile mentions @file{foo.c}. For this target, @code{make}
8622 would have to consider making it by linking an object file @file{foo.c.o},
8623 or by C compilation-and-linking in one step from @file{foo.c.c}, or by
8624 Pascal compilation-and-linking from @file{foo.c.p}, and many other
8625 possibilities.
8626
8627 We know these possibilities are ridiculous since @file{foo.c} is a C source
8628 file, not an executable. If @code{make} did consider these possibilities,
8629 it would ultimately reject them, because files such as @file{foo.c.o} and
8630 @file{foo.c.p} would not exist. But these possibilities are so
8631 numerous that @code{make} would run very slowly if it had to consider
8632 them.@refill
8633
8634 To gain speed, we have put various constraints on the way @code{make}
8635 considers match-anything rules. There are two different constraints that
8636 can be applied, and each time you define a match-anything rule you must
8637 choose one or the other for that rule.
8638
8639 One choice is to mark the match-anything rule as @dfn{terminal} by defining
8640 it with a double colon. When a rule is terminal, it does not apply unless
8641 its prerequisites actually exist. Prerequisites that could be made with
8642 other implicit rules are not good enough. In other words, no further
8643 chaining is allowed beyond a terminal rule.
8644
8645 For example, the built-in implicit rules for extracting sources from RCS
8646 and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
8647 not exist, @code{make} will not even consider trying to make it as an
8648 intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
8649 RCS and SCCS files are generally ultimate source files, which should not be
8650 remade from any other files; therefore, @code{make} can save time by not
8651 looking for ways to remake them.@refill
8652
8653 If you do not mark the match-anything rule as terminal, then it is
8654 nonterminal. A nonterminal match-anything rule cannot apply to a file name
8655 that indicates a specific type of data. A file name indicates a specific
8656 type of data if some non-match-anything implicit rule target matches it.
8657
8658 For example, the file name @file{foo.c} matches the target for the pattern
8659 rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this
8660 rule is actually applicable (which happens only if there is a file
8661 @file{foo.y}), the fact that its target matches is enough to prevent
8662 consideration of any nonterminal match-anything rules for the file
8663 @file{foo.c}. Thus, @code{make} will not even consider trying to make
8664 @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
8665 @file{foo.c.p}, etc.@refill
8666
8667 The motivation for this constraint is that nonterminal match-anything
8668 rules are used for making files containing specific types of data (such as
8669 executable files) and a file name with a recognized suffix indicates some
8670 other specific type of data (such as a C source file).
8671
8672 Special built-in dummy pattern rules are provided solely to recognize
8673 certain file names so that nonterminal match-anything rules will not be
8674 considered. These dummy rules have no prerequisites and no commands, and
8675 they are ignored for all other purposes. For example, the built-in
8676 implicit rule
8677
8678 @example
8679 %.p :
8680 @end example
8681
8682 @noindent
8683 exists to make sure that Pascal source files such as @file{foo.p} match a
8684 specific target pattern and thereby prevent time from being wasted looking
8685 for @file{foo.p.o} or @file{foo.p.c}.
8686
8687 Dummy pattern rules such as the one for @samp{%.p} are made for every
8688 suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
8689
8690 @node Canceling Rules, , Match-Anything Rules, Pattern Rules
8691 @subsection Canceling Implicit Rules
8692
8693 You can override a built-in implicit rule (or one you have defined
8694 yourself) by defining a new pattern rule with the same target and
8695 prerequisites, but different commands. When the new rule is defined, the
8696 built-in one is replaced. The new rule's position in the sequence of
8697 implicit rules is determined by where you write the new rule.
8698
8699 You can cancel a built-in implicit rule by defining a pattern rule with the
8700 same target and prerequisites, but no commands. For example, the following
8701 would cancel the rule that runs the assembler:
8702
8703 @example
8704 %.o : %.s
8705 @end example
8706
8707 @node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
8708 @section Defining Last-Resort Default Rules
8709 @cindex last-resort default rules
8710 @cindex default rules, last-resort
8711
8712 You can define a last-resort implicit rule by writing a terminal
8713 match-anything pattern rule with no prerequisites (@pxref{Match-Anything
8714 Rules}). This is just like any other pattern rule; the only thing
8715 special about it is that it will match any target. So such a rule's
8716 commands are used for all targets and prerequisites that have no commands
8717 of their own and for which no other implicit rule applies.
8718
8719 For example, when testing a makefile, you might not care if the source
8720 files contain real data, only that they exist. Then you might do this:
8721
8722 @example
8723 %::
8724 touch $@@
8725 @end example
8726
8727 @noindent
8728 to cause all the source files needed (as prerequisites) to be created
8729 automatically.
8730
8731 @findex .DEFAULT
8732 You can instead define commands to be used for targets for which there
8733 are no rules at all, even ones which don't specify commands. You do
8734 this by writing a rule for the target @code{.DEFAULT}. Such a rule's
8735 commands are used for all prerequisites which do not appear as targets in
8736 any explicit rule, and for which no implicit rule applies. Naturally,
8737 there is no @code{.DEFAULT} rule unless you write one.
8738
8739 If you use @code{.DEFAULT} with no commands or prerequisites:
8740
8741 @example
8742 .DEFAULT:
8743 @end example
8744
8745 @noindent
8746 the commands previously stored for @code{.DEFAULT} are cleared.
8747 Then @code{make} acts as if you had never defined @code{.DEFAULT} at all.
8748
8749 If you do not want a target to get the commands from a match-anything
8750 pattern rule or @code{.DEFAULT}, but you also do not want any commands
8751 to be run for the target, you can give it empty commands (@pxref{Empty
8752 Commands, ,Defining Empty Commands}).@refill
8753
8754 You can use a last-resort rule to override part of another makefile.
8755 @xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
8756
8757 @node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules
8758 @section Old-Fashioned Suffix Rules
8759 @cindex old-fashioned suffix rules
8760 @cindex suffix rule
8761
8762 @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
8763 @code{make}. Suffix rules are obsolete because pattern rules are more
8764 general and clearer. They are supported in GNU @code{make} for
8765 compatibility with old makefiles. They come in two kinds:
8766 @dfn{double-suffix} and @dfn{single-suffix}.@refill
8767
8768 A double-suffix rule is defined by a pair of suffixes: the target suffix
8769 and the source suffix. It matches any file whose name ends with the
8770 target suffix. The corresponding implicit prerequisite is made by
8771 replacing the target suffix with the source suffix in the file name. A
8772 two-suffix rule whose target and source suffixes are @samp{.o} and
8773 @samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
8774
8775 A single-suffix rule is defined by a single suffix, which is the source
8776 suffix. It matches any file name, and the corresponding implicit
8777 prerequisite name is made by appending the source suffix. A single-suffix
8778 rule whose source suffix is @samp{.c} is equivalent to the pattern rule
8779 @samp{% : %.c}.
8780
8781 Suffix rule definitions are recognized by comparing each rule's target
8782 against a defined list of known suffixes. When @code{make} sees a rule
8783 whose target is a known suffix, this rule is considered a single-suffix
8784 rule. When @code{make} sees a rule whose target is two known suffixes
8785 concatenated, this rule is taken as a double-suffix rule.
8786
8787 For example, @samp{.c} and @samp{.o} are both on the default list of
8788 known suffixes. Therefore, if you define a rule whose target is
8789 @samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
8790 suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned
8791 way to define the rule for compiling a C source file:@refill
8792
8793 @example
8794 .c.o:
8795 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
8796 @end example
8797
8798 Suffix rules cannot have any prerequisites of their own. If they have any,
8799 they are treated as normal files with funny names, not as suffix rules.
8800 Thus, the rule:
8801
8802 @example
8803 .c.o: foo.h
8804 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
8805 @end example
8806
8807 @noindent
8808 tells how to make the file @file{.c.o} from the prerequisite file
8809 @file{foo.h}, and is not at all like the pattern rule:
8810
8811 @example
8812 %.o: %.c foo.h
8813 $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
8814 @end example
8815
8816 @noindent
8817 which tells how to make @samp{.o} files from @samp{.c} files, and makes all
8818 @samp{.o} files using this pattern rule also depend on @file{foo.h}.
8819
8820 Suffix rules with no commands are also meaningless. They do not remove
8821 previous rules as do pattern rules with no commands (@pxref{Canceling
8822 Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as
8823 a target in the data base.@refill
8824
8825 @findex .SUFFIXES
8826 The known suffixes are simply the names of the prerequisites of the special
8827 target @code{.SUFFIXES}. You can add your own suffixes by writing a rule
8828 for @code{.SUFFIXES} that adds more prerequisites, as in:
8829
8830 @example
8831 .SUFFIXES: .hack .win
8832 @end example
8833
8834 @noindent
8835 which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
8836
8837 If you wish to eliminate the default known suffixes instead of just adding
8838 to them, write a rule for @code{.SUFFIXES} with no prerequisites. By
8839 special dispensation, this eliminates all existing prerequisites of
8840 @code{.SUFFIXES}. You can then write another rule to add the suffixes you
8841 want. For example,
8842
8843 @example
8844 @group
8845 .SUFFIXES: # @r{Delete the default suffixes}
8846 .SUFFIXES: .c .o .h # @r{Define our suffix list}
8847 @end group
8848 @end example
8849
8850 The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
8851 list of suffixes to be empty.
8852
8853 @vindex SUFFIXES
8854 The variable @code{SUFFIXES} is defined to the default list of suffixes
8855 before @code{make} reads any makefiles. You can change the list of suffixes
8856 with a rule for the special target @code{.SUFFIXES}, but that does not alter
8857 this variable.
8858
8859 @node Implicit Rule Search, , Suffix Rules, Implicit Rules
8860 @section Implicit Rule Search Algorithm
8861 @cindex implicit rule, search algorithm
8862 @cindex search algorithm, implicit rule
8863
8864 Here is the procedure @code{make} uses for searching for an implicit rule
8865 for a target @var{t}. This procedure is followed for each double-colon
8866 rule with no commands, for each target of ordinary rules none of which have
8867 commands, and for each prerequisite that is not the target of any rule. It
8868 is also followed recursively for prerequisites that come from implicit
8869 rules, in the search for a chain of rules.
8870
8871 Suffix rules are not mentioned in this algorithm because suffix rules are
8872 converted to equivalent pattern rules once the makefiles have been read in.
8873
8874 For an archive member target of the form
8875 @samp{@var{archive}(@var{member})}, the following algorithm is run
8876 twice, first using the entire target name @var{t}, and second using
8877 @samp{(@var{member})} as the target @var{t} if the first run found no
8878 rule.@refill
8879
8880 @enumerate
8881 @item
8882 Split @var{t} into a directory part, called @var{d}, and the rest,
8883 called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then
8884 @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
8885
8886 @item
8887 Make a list of all the pattern rules one of whose targets matches
8888 @var{t} or @var{n}. If the target pattern contains a slash, it is
8889 matched against @var{t}; otherwise, against @var{n}.
8890
8891 @item
8892 If any rule in that list is @emph{not} a match-anything rule, then
8893 remove all nonterminal match-anything rules from the list.
8894
8895 @item
8896 Remove from the list all rules with no commands.
8897
8898 @item
8899 For each pattern rule in the list:
8900
8901 @enumerate a
8902 @item
8903 Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
8904 matched by the @samp{%} in the target pattern.@refill
8905
8906 @item
8907 Compute the prerequisite names by substituting @var{s} for @samp{%}; if
8908 the target pattern does not contain a slash, append @var{d} to
8909 the front of each prerequisite name.@refill
8910
8911 @item
8912 Test whether all the prerequisites exist or ought to exist. (If a
8913 file name is mentioned in the makefile as a target or as an explicit
8914 prerequisite, then we say it ought to exist.)
8915
8916 If all prerequisites exist or ought to exist, or there are no prerequisites,
8917 then this rule applies.
8918 @end enumerate
8919
8920 @item
8921 If no pattern rule has been found so far, try harder.
8922 For each pattern rule in the list:
8923
8924 @enumerate a
8925 @item
8926 If the rule is terminal, ignore it and go on to the next rule.
8927
8928 @item
8929 Compute the prerequisite names as before.
8930
8931 @item
8932 Test whether all the prerequisites exist or ought to exist.
8933
8934 @item
8935 For each prerequisite that does not exist, follow this algorithm
8936 recursively to see if the prerequisite can be made by an implicit
8937 rule.
8938
8939 @item
8940 If all prerequisites exist, ought to exist, or can be
8941 made by implicit rules, then this rule applies.
8942 @end enumerate
8943
8944 @item
8945 If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
8946 applies. In that case, give @var{t} the same commands that
8947 @code{.DEFAULT} has. Otherwise, there are no commands for @var{t}.
8948 @end enumerate
8949
8950 Once a rule that applies has been found, for each target pattern of the
8951 rule other than the one that matched @var{t} or @var{n}, the @samp{%} in
8952 the pattern is replaced with @var{s} and the resultant file name is stored
8953 until the commands to remake the target file @var{t} are executed. After
8954 these commands are executed, each of these stored file names are entered
8955 into the data base and marked as having been updated and having the same
8956 update status as the file @var{t}.
8957
8958 When the commands of a pattern rule are executed for @var{t}, the automatic
8959 variables are set corresponding to the target and prerequisites.
8960 @xref{Automatic Variables}.
8961
8962 @node Archives, Features, Implicit Rules, Top
8963 @chapter Using @code{make} to Update Archive Files
8964 @cindex archive
8965
8966 @dfn{Archive files} are files containing named subfiles called
8967 @dfn{members}; they are maintained with the program @code{ar} and their
8968 main use is as subroutine libraries for linking.
8969
8970 @menu
8971 * Archive Members:: Archive members as targets.
8972 * Archive Update:: The implicit rule for archive member targets.
8973 * Archive Pitfalls:: Dangers to watch out for when using archives.
8974 * Archive Suffix Rules:: You can write a special kind of suffix rule
8975 for updating archives.
8976 @end menu
8977
8978 @node Archive Members, Archive Update, Archives, Archives
8979 @section Archive Members as Targets
8980 @cindex archive member targets
8981
8982 An individual member of an archive file can be used as a target or
8983 prerequisite in @code{make}. You specify the member named @var{member} in
8984 archive file @var{archive} as follows:
8985
8986 @example
8987 @var{archive}(@var{member})
8988 @end example
8989
8990 @noindent
8991 This construct is available only in targets and prerequisites, not in
8992 commands! Most programs that you might use in commands do not support this
8993 syntax and cannot act directly on archive members. Only @code{ar} and
8994 other programs specifically designed to operate on archives can do so.
8995 Therefore, valid commands to update an archive member target probably must
8996 use @code{ar}. For example, this rule says to create a member
8997 @file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}:
8998
8999 @example
9000 foolib(hack.o) : hack.o
9001 ar cr foolib hack.o
9002 @end example
9003
9004 In fact, nearly all archive member targets are updated in just this way
9005 and there is an implicit rule to do it for you. @strong{Note:} The
9006 @samp{c} flag to @code{ar} is required if the archive file does not
9007 already exist.
9008
9009 To specify several members in the same archive, you can write all the
9010 member names together between the parentheses. For example:
9011
9012 @example
9013 foolib(hack.o kludge.o)
9014 @end example
9015
9016 @noindent
9017 is equivalent to:
9018
9019 @example
9020 foolib(hack.o) foolib(kludge.o)
9021 @end example
9022
9023 @cindex wildcard, in archive member
9024 You can also use shell-style wildcards in an archive member reference.
9025 @xref{Wildcards, ,Using Wildcard Characters in File Names}. For
9026 example, @w{@samp{foolib(*.o)}} expands to all existing members of the
9027 @file{foolib} archive whose names end in @samp{.o}; perhaps
9028 @samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
9029
9030 @node Archive Update, Archive Pitfalls, Archive Members, Archives
9031 @section Implicit Rule for Archive Member Targets
9032
9033 Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
9034 member named @var{m} in the archive file @var{a}.
9035
9036 When @code{make} looks for an implicit rule for such a target, as a special
9037 feature it considers implicit rules that match @file{(@var{m})}, as well as
9038 those that match the actual target @file{@var{a}(@var{m})}.
9039
9040 This causes one special rule whose target is @file{(%)} to match. This
9041 rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
9042 into the archive. For example, it will update the archive member target
9043 @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
9044 archive @file{foo.a} as a @emph{member} named @file{bar.o}.
9045
9046 When this rule is chained with others, the result is very powerful.
9047 Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
9048 @samp{(} and @samp{)} from being interpreted specially by the shell) in
9049 the presence of a file @file{bar.c} is enough to cause the following
9050 commands to be run, even without a makefile:
9051
9052 @example
9053 cc -c bar.c -o bar.o
9054 ar r foo.a bar.o
9055 rm -f bar.o
9056 @end example
9057
9058 @noindent
9059 Here @code{make} has envisioned the file @file{bar.o} as an intermediate
9060 file. @xref{Chained Rules, ,Chains of Implicit Rules}.
9061
9062 Implicit rules such as this one are written using the automatic variable
9063 @samp{$%}. @xref{Automatic Variables}.
9064
9065 An archive member name in an archive cannot contain a directory name, but
9066 it may be useful in a makefile to pretend that it does. If you write an
9067 archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
9068 automatic updating with this command:
9069
9070 @example
9071 ar r foo.a dir/file.o
9072 @end example
9073
9074 @noindent
9075 which has the effect of copying the file @file{dir/file.o} into a member
9076 named @file{file.o}. In connection with such usage, the automatic variables
9077 @code{%D} and @code{%F} may be useful.
9078
9079 @menu
9080 * Archive Symbols:: How to update archive symbol directories.
9081 @end menu
9082
9083 @node Archive Symbols, , Archive Update, Archive Update
9084 @subsection Updating Archive Symbol Directories
9085 @cindex @code{__.SYMDEF}
9086 @cindex updating archive symbol directories
9087 @cindex archive symbol directory updating
9088 @cindex symbol directories, updating archive
9089 @cindex directories, updating archive symbol
9090
9091 An archive file that is used as a library usually contains a special member
9092 named @file{__.SYMDEF} that contains a directory of the external symbol
9093 names defined by all the other members. After you update any other
9094 members, you need to update @file{__.SYMDEF} so that it will summarize the
9095 other members properly. This is done by running the @code{ranlib} program:
9096
9097 @example
9098 ranlib @var{archivefile}
9099 @end example
9100
9101 Normally you would put this command in the rule for the archive file,
9102 and make all the members of the archive file prerequisites of that rule.
9103 For example,
9104
9105 @example
9106 libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
9107 ranlib libfoo.a
9108 @end example
9109
9110 @noindent
9111 The effect of this is to update archive members @file{x.o}, @file{y.o},
9112 etc., and then update the symbol directory member @file{__.SYMDEF} by
9113 running @code{ranlib}. The rules for updating the members are not shown
9114 here; most likely you can omit them and use the implicit rule which copies
9115 files into the archive, as described in the preceding section.
9116
9117 This is not necessary when using the GNU @code{ar} program, which
9118 updates the @file{__.SYMDEF} member automatically.
9119
9120 @node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives
9121 @section Dangers When Using Archives
9122 @cindex archive, and parallel execution
9123 @cindex parallel execution, and archive update
9124 @cindex archive, and @code{-j}
9125 @cindex @code{-j}, and archive update
9126
9127 It is important to be careful when using parallel execution (the
9128 @code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives.
9129 If multiple @code{ar} commands run at the same time on the same archive
9130 file, they will not know about each other and can corrupt the file.
9131
9132 Possibly a future version of @code{make} will provide a mechanism to
9133 circumvent this problem by serializing all commands that operate on the
9134 same archive file. But for the time being, you must either write your
9135 makefiles to avoid this problem in some other way, or not use @code{-j}.
9136
9137 @node Archive Suffix Rules, , Archive Pitfalls, Archives
9138 @section Suffix Rules for Archive Files
9139 @cindex suffix rule, for archive
9140 @cindex archive, suffix rule for
9141 @cindex library archive, suffix rule for
9142 @cindex @code{.a} (archives)
9143
9144 You can write a special kind of suffix rule for dealing with archive
9145 files. @xref{Suffix Rules}, for a full explanation of suffix rules.
9146 Archive suffix rules are obsolete in GNU @code{make}, because pattern
9147 rules for archives are a more general mechanism (@pxref{Archive
9148 Update}). But they are retained for compatibility with other
9149 @code{make}s.
9150
9151 To write a suffix rule for archives, you simply write a suffix rule
9152 using the target suffix @samp{.a} (the usual suffix for archive files).
9153 For example, here is the old-fashioned suffix rule to update a library
9154 archive from C source files:
9155
9156 @example
9157 @group
9158 .c.a:
9159 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
9160 $(AR) r $@@ $*.o
9161 $(RM) $*.o
9162 @end group
9163 @end example
9164
9165 @noindent
9166 This works just as if you had written the pattern rule:
9167
9168 @example
9169 @group
9170 (%.o): %.c
9171 $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
9172 $(AR) r $@@ $*.o
9173 $(RM) $*.o
9174 @end group
9175 @end example
9176
9177 In fact, this is just what @code{make} does when it sees a suffix rule
9178 with @samp{.a} as the target suffix. Any double-suffix rule
9179 @w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
9180 pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}.
9181
9182 Since you might want to use @samp{.a} as the suffix for some other kind
9183 of file, @code{make} also converts archive suffix rules to pattern rules
9184 in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule
9185 @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
9186 @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
9187
9188 @node Features, Missing, Archives, Top
9189 @chapter Features of GNU @code{make}
9190 @cindex features of GNU @code{make}
9191 @cindex portability
9192 @cindex compatibility
9193
9194 Here is a summary of the features of GNU @code{make}, for comparison
9195 with and credit to other versions of @code{make}. We consider the
9196 features of @code{make} in 4.2 BSD systems as a baseline. If you are
9197 concerned with writing portable makefiles, you should not use the
9198 features of @code{make} listed here, nor the ones in @ref{Missing}.
9199
9200 Many features come from the version of @code{make} in System V.
9201
9202 @itemize @bullet
9203 @item
9204 The @code{VPATH} variable and its special meaning.
9205 @xref{Directory Search, , Searching Directories for Prerequisites}.
9206 This feature exists in System V @code{make}, but is undocumented.
9207 It is documented in 4.3 BSD @code{make} (which says it mimics System V's
9208 @code{VPATH} feature).@refill
9209
9210 @item
9211 Included makefiles. @xref{Include, ,Including Other Makefiles}.
9212 Allowing multiple files to be included with a single directive is a GNU
9213 extension.
9214
9215 @item
9216 Variables are read from and communicated via the environment.
9217 @xref{Environment, ,Variables from the Environment}.
9218
9219 @item
9220 Options passed through the variable @code{MAKEFLAGS} to recursive
9221 invocations of @code{make}.
9222 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
9223
9224 @item
9225 The automatic variable @code{$%} is set to the member name
9226 in an archive reference. @xref{Automatic Variables}.
9227
9228 @item
9229 The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
9230 and @code{$?} have corresponding forms like @code{$(@@F)} and
9231 @code{$(@@D)}. We have generalized this to @code{$^} as an obvious
9232 extension. @xref{Automatic Variables}.@refill
9233
9234 @item
9235 Substitution variable references.
9236 @xref{Reference, ,Basics of Variable References}.
9237
9238 @item
9239 The command-line options @samp{-b} and @samp{-m}, accepted and
9240 ignored. In System V @code{make}, these options actually do something.
9241
9242 @item
9243 Execution of recursive commands to run @code{make} via the variable
9244 @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
9245 @xref{Recursion, ,Recursive Use of @code{make}}.
9246
9247 @item
9248 Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix
9249 Rules}. This feature is obsolete in GNU @code{make}, because the
9250 general feature of rule chaining (@pxref{Chained Rules, ,Chains of
9251 Implicit Rules}) allows one pattern rule for installing members in an
9252 archive (@pxref{Archive Update}) to be sufficient.
9253
9254 @item
9255 The arrangement of lines and backslash-newline combinations in
9256 commands is retained when the commands are printed, so they appear as
9257 they do in the makefile, except for the stripping of initial
9258 whitespace.
9259 @end itemize
9260
9261 The following features were inspired by various other versions of
9262 @code{make}. In some cases it is unclear exactly which versions inspired
9263 which others.
9264
9265 @itemize @bullet
9266 @item
9267 Pattern rules using @samp{%}.
9268 This has been implemented in several versions of @code{make}.
9269 We're not sure who invented it first, but it's been spread around a bit.
9270 @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
9271
9272 @item
9273 Rule chaining and implicit intermediate files.
9274 This was implemented by Stu Feldman in his version of @code{make}
9275 for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
9276 AT&T Bell Labs in his @code{mk} program (where he terms it
9277 ``transitive closure''). We do not really know if
9278 we got this from either of them or thought it up ourselves at the
9279 same time. @xref{Chained Rules, ,Chains of Implicit Rules}.
9280
9281 @item
9282 The automatic variable @code{$^} containing a list of all prerequisites
9283 of the current target. We did not invent this, but we have no idea who
9284 did. @xref{Automatic Variables}. The automatic variable
9285 @code{$+} is a simple extension of @code{$^}.
9286
9287 @item
9288 The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
9289 invented by Andrew Hume in @code{mk}.
9290 @xref{Instead of Execution, ,Instead of Executing the Commands}.
9291
9292 @item
9293 The concept of doing several things at once (parallelism) exists in
9294 many incarnations of @code{make} and similar programs, though not in the
9295 System V or BSD implementations. @xref{Execution, ,Command Execution}.
9296
9297 @item
9298 Modified variable references using pattern substitution come from
9299 SunOS 4. @xref{Reference, ,Basics of Variable References}.
9300 This functionality was provided in GNU @code{make} by the
9301 @code{patsubst} function before the alternate syntax was implemented
9302 for compatibility with SunOS 4. It is not altogether clear who
9303 inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
9304 4 was released.@refill
9305
9306 @item
9307 The special significance of @samp{+} characters preceding command lines
9308 (@pxref{Instead of Execution, ,Instead of Executing the Commands}) is
9309 mandated by
9310 @cite{IEEE Standard 1003.2-1992} (POSIX.2).
9311
9312 @item
9313 The @samp{+=} syntax to append to the value of a variable comes from SunOS
9314 4 @code{make}. @xref{Appending, , Appending More Text to Variables}.
9315
9316 @item
9317 The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
9318 multiple members in a single archive file comes from SunOS 4 @code{make}.
9319 @xref{Archive Members}.
9320
9321 @item
9322 The @code{-include} directive to include makefiles with no error for a
9323 nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4
9324 @code{make} does not allow multiple makefiles to be specified in one
9325 @code{-include} directive.) The same feature appears with the name
9326 @code{sinclude} in SGI @code{make} and perhaps others.
9327 @end itemize
9328
9329 The remaining features are inventions new in GNU @code{make}:
9330
9331 @itemize @bullet
9332 @item
9333 Use the @samp{-v} or @samp{--version} option to print version and
9334 copyright information.
9335
9336 @item
9337 Use the @samp{-h} or @samp{--help} option to summarize the options to
9338 @code{make}.
9339
9340 @item
9341 Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}.
9342
9343 @item
9344 Pass command-line variable assignments automatically through the
9345 variable @code{MAKE} to recursive @code{make} invocations.
9346 @xref{Recursion, ,Recursive Use of @code{make}}.
9347
9348 @item
9349 Use the @samp{-C} or @samp{--directory} command option to change
9350 directory. @xref{Options Summary, ,Summary of Options}.
9351
9352 @item
9353 Make verbatim variable definitions with @code{define}.
9354 @xref{Defining, ,Defining Variables Verbatim}.
9355
9356 @item
9357 Declare phony targets with the special target @code{.PHONY}.
9358
9359 Andrew Hume of AT&T Bell Labs implemented a similar feature with a
9360 different syntax in his @code{mk} program. This seems to be a case of
9361 parallel discovery. @xref{Phony Targets, ,Phony Targets}.
9362
9363 @item
9364 Manipulate text by calling functions.
9365 @xref{Functions, ,Functions for Transforming Text}.
9366
9367 @item
9368 Use the @samp{-o} or @samp{--old-file}
9369 option to pretend a file's modification-time is old.
9370 @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
9371
9372 @item
9373 Conditional execution.
9374
9375 This feature has been implemented numerous times in various versions
9376 of @code{make}; it seems a natural extension derived from the features
9377 of the C preprocessor and similar macro languages and is not a
9378 revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}.
9379
9380 @item
9381 Specify a search path for included makefiles.
9382 @xref{Include, ,Including Other Makefiles}.
9383
9384 @item
9385 Specify extra makefiles to read with an environment variable.
9386 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
9387
9388 @item
9389 Strip leading sequences of @samp{./} from file names, so that
9390 @file{./@var{file}} and @file{@var{file}} are considered to be the
9391 same file.@refill
9392
9393 @item
9394 Use a special search method for library prerequisites written in the
9395 form @samp{-l@var{name}}.
9396 @xref{Libraries/Search, ,Directory Search for Link Libraries}.
9397
9398 @item
9399 Allow suffixes for suffix rules
9400 (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
9401 characters. In other versions of @code{make}, they must begin with
9402 @samp{.} and not contain any @samp{/} characters.
9403
9404 @item
9405 Keep track of the current level of @code{make} recursion using the
9406 variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}.
9407
9408 @item
9409 Provide any goals given on the command line in the variable
9410 @code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}.
9411
9412 @item
9413 Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}.
9414
9415 @item
9416 Provide selective @code{vpath} search.
9417 @xref{Directory Search, ,Searching Directories for Prerequisites}.
9418
9419 @item
9420 Provide computed variable references.
9421 @xref{Reference, ,Basics of Variable References}.
9422
9423 @item
9424 Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
9425 System V @code{make} has a very, very limited form of this
9426 functionality in that it will check out SCCS files for makefiles.
9427
9428 @item
9429 Various new built-in implicit rules.
9430 @xref{Catalogue of Rules, ,Catalogue of Implicit Rules}.
9431
9432 @item
9433 The built-in variable @samp{MAKE_VERSION} gives the version number of
9434 @code{make}.
9435 @end itemize
9436
9437 @node Missing, Makefile Conventions, Features, Top
9438 @chapter Incompatibilities and Missing Features
9439 @cindex incompatibilities
9440 @cindex missing features
9441 @cindex features, missing
9442
9443 The @code{make} programs in various other systems support a few features
9444 that are not implemented in GNU @code{make}. The POSIX.2 standard
9445 (@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
9446 require any of these features.@refill
9447
9448 @itemize @bullet
9449 @item
9450 A target of the form @samp{@var{file}((@var{entry}))} stands for a member
9451 of archive file @var{file}. The member is chosen, not by name, but by
9452 being an object file which defines the linker symbol @var{entry}.@refill
9453
9454 This feature was not put into GNU @code{make} because of the
9455 nonmodularity of putting knowledge into @code{make} of the internal
9456 format of archive file symbol tables.
9457 @xref{Archive Symbols, ,Updating Archive Symbol Directories}.
9458
9459 @item
9460 Suffixes (used in suffix rules) that end with the character @samp{~}
9461 have a special meaning to System V @code{make};
9462 they refer to the SCCS file that corresponds
9463 to the file one would get without the @samp{~}. For example, the
9464 suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
9465 the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole
9466 series of such suffix rules is required.
9467 @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
9468
9469 In GNU @code{make}, this entire series of cases is handled by two
9470 pattern rules for extraction from SCCS, in combination with the
9471 general feature of rule chaining.
9472 @xref{Chained Rules, ,Chains of Implicit Rules}.
9473
9474 @item
9475 In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search
9476 (@pxref{Directory Search, ,Searching Directories for Prerequisites}) have their names changed inside command
9477 strings. We feel it is much cleaner to always use automatic variables
9478 and thus make this feature obsolete.@refill
9479
9480 @item
9481 In some Unix @code{make}s, the automatic variable @code{$*} appearing in
9482 the prerequisites of a rule has the amazingly strange ``feature'' of
9483 expanding to the full name of the @emph{target of that rule}. We cannot
9484 imagine what went on in the minds of Unix @code{make} developers to do
9485 this; it is utterly inconsistent with the normal definition of @code{$*}.
9486 @vindex * @r{(automatic variable), unsupported bizarre usage}
9487
9488 @item
9489 In some Unix @code{make}s, implicit rule search
9490 (@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for
9491 @emph{all} targets, not just those without commands. This means you can
9492 do:@refill
9493
9494 @example
9495 @group
9496 foo.o:
9497 cc -c foo.c
9498 @end group
9499 @end example
9500
9501 @noindent
9502 and Unix @code{make} will intuit that @file{foo.o} depends on
9503 @file{foo.c}.@refill
9504
9505 We feel that such usage is broken. The prerequisite properties of
9506 @code{make} are well-defined (for GNU @code{make}, at least),
9507 and doing such a thing simply does not fit the model.@refill
9508
9509 @item
9510 GNU @code{make} does not include any built-in implicit rules for
9511 compiling or preprocessing EFL programs. If we hear of anyone who is
9512 using EFL, we will gladly add them.
9513
9514 @item
9515 It appears that in SVR4 @code{make}, a suffix rule can be specified with
9516 no commands, and it is treated as if it had empty commands
9517 (@pxref{Empty Commands}). For example:
9518
9519 @example
9520 .c.a:
9521 @end example
9522
9523 @noindent
9524 will override the built-in @file{.c.a} suffix rule.
9525
9526 We feel that it is cleaner for a rule without commands to always simply
9527 add to the prerequisite list for the target. The above example can be
9528 easily rewritten to get the desired behavior in GNU @code{make}:
9529
9530 @example
9531 .c.a: ;
9532 @end example
9533
9534 @item
9535 Some versions of @code{make} invoke the shell with the @samp{-e} flag,
9536 except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
9537 Program}). The @samp{-e} flag tells the shell to exit as soon as any
9538 program it runs returns a nonzero status. We feel it is cleaner to
9539 write each shell command line to stand on its own and not require this
9540 special treatment.
9541 @end itemize
9542
9543 @comment The makefile standards are in a separate file that is also
9544 @comment included by standards.texi.
9545 @include make-stds.texi
9546
9547 @node Quick Reference, Error Messages, Makefile Conventions, Top
9548 @appendix Quick Reference
9549
9550 This appendix summarizes the directives, text manipulation functions,
9551 and special variables which GNU @code{make} understands.
9552 @xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Implicit Rules},
9553 and @ref{Options Summary, ,Summary of Options},
9554 for other summaries.
9555
9556 Here is a summary of the directives GNU @code{make} recognizes:
9557
9558 @table @code
9559 @item define @var{variable}
9560 @itemx endef
9561
9562 Define a multi-line, recursively-expanded variable.@*
9563 @xref{Sequences}.
9564
9565 @item ifdef @var{variable}
9566 @itemx ifndef @var{variable}
9567 @itemx ifeq (@var{a},@var{b})
9568 @itemx ifeq "@var{a}" "@var{b}"
9569 @itemx ifeq '@var{a}' '@var{b}'
9570 @itemx ifneq (@var{a},@var{b})
9571 @itemx ifneq "@var{a}" "@var{b}"
9572 @itemx ifneq '@var{a}' '@var{b}'
9573 @itemx else
9574 @itemx endif
9575
9576 Conditionally evaluate part of the makefile.@*
9577 @xref{Conditionals}.
9578
9579 @item include @var{file}
9580 @itemx -include @var{file}
9581 @itemx sinclude @var{file}
9582
9583 Include another makefile.@*
9584 @xref{Include, ,Including Other Makefiles}.
9585
9586 @item override @var{variable} = @var{value}
9587 @itemx override @var{variable} := @var{value}
9588 @itemx override @var{variable} += @var{value}
9589 @itemx override @var{variable} ?= @var{value}
9590 @itemx override define @var{variable}
9591 @itemx endef
9592
9593 Define a variable, overriding any previous definition, even one from
9594 the command line.@*
9595 @xref{Override Directive, ,The @code{override} Directive}.
9596
9597 @item export
9598
9599 Tell @code{make} to export all variables to child processes by default.@*
9600 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
9601
9602 @item export @var{variable}
9603 @itemx export @var{variable} = @var{value}
9604 @itemx export @var{variable} := @var{value}
9605 @itemx export @var{variable} += @var{value}
9606 @itemx export @var{variable} ?= @var{value}
9607 @itemx unexport @var{variable}
9608 Tell @code{make} whether or not to export a particular variable to child
9609 processes.@*
9610 @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
9611
9612 @item vpath @var{pattern} @var{path}
9613 Specify a search path for files matching a @samp{%} pattern.@*
9614 @xref{Selective Search, , The @code{vpath} Directive}.
9615
9616 @item vpath @var{pattern}
9617 Remove all search paths previously specified for @var{pattern}.
9618
9619 @item vpath
9620 Remove all search paths previously specified in any @code{vpath}
9621 directive.
9622 @end table
9623
9624 Here is a summary of the text manipulation functions (@pxref{Functions}):
9625
9626 @table @code
9627 @item $(subst @var{from},@var{to},@var{text})
9628 Replace @var{from} with @var{to} in @var{text}.@*
9629 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9630
9631 @item $(patsubst @var{pattern},@var{replacement},@var{text})
9632 Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
9633 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9634
9635 @item $(strip @var{string})
9636 Remove excess whitespace characters from @var{string}.@*
9637 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9638
9639 @item $(findstring @var{find},@var{text})
9640 Locate @var{find} in @var{text}.@*
9641 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9642
9643 @item $(filter @var{pattern}@dots{},@var{text})
9644 Select words in @var{text} that match one of the @var{pattern} words.@*
9645 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9646
9647 @item $(filter-out @var{pattern}@dots{},@var{text})
9648 Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
9649 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9650
9651 @item $(sort @var{list})
9652 Sort the words in @var{list} lexicographically, removing duplicates.@*
9653 @xref{Text Functions, , Functions for String Substitution and Analysis}.
9654
9655 @item $(dir @var{names}@dots{})
9656 Extract the directory part of each file name.@*
9657 @xref{File Name Functions, ,Functions for File Names}.
9658
9659 @item $(notdir @var{names}@dots{})
9660 Extract the non-directory part of each file name.@*
9661 @xref{File Name Functions, ,Functions for File Names}.
9662
9663 @item $(suffix @var{names}@dots{})
9664 Extract the suffix (the last @samp{.} and following characters) of each file name.@*
9665 @xref{File Name Functions, ,Functions for File Names}.
9666
9667 @item $(basename @var{names}@dots{})
9668 Extract the base name (name without suffix) of each file name.@*
9669 @xref{File Name Functions, ,Functions for File Names}.
9670
9671 @item $(addsuffix @var{suffix},@var{names}@dots{})
9672 Append @var{suffix} to each word in @var{names}.@*
9673 @xref{File Name Functions, ,Functions for File Names}.
9674
9675 @item $(addprefix @var{prefix},@var{names}@dots{})
9676 Prepend @var{prefix} to each word in @var{names}.@*
9677 @xref{File Name Functions, ,Functions for File Names}.
9678
9679 @item $(join @var{list1},@var{list2})
9680 Join two parallel lists of words.@*
9681 @xref{File Name Functions, ,Functions for File Names}.
9682
9683 @item $(word @var{n},@var{text})
9684 Extract the @var{n}th word (one-origin) of @var{text}.@*
9685 @xref{File Name Functions, ,Functions for File Names}.
9686
9687 @item $(words @var{text})
9688 Count the number of words in @var{text}.@*
9689 @xref{File Name Functions, ,Functions for File Names}.
9690
9691 @item $(wordlist @var{s},@var{e},@var{text})
9692 Returns the list of words in @var{text} from @var{s} to @var{e}.@*
9693 @xref{File Name Functions, ,Functions for File Names}.
9694
9695 @item $(firstword @var{names}@dots{})
9696 Extract the first word of @var{names}.@*
9697 @xref{File Name Functions, ,Functions for File Names}.
9698
9699 @item $(wildcard @var{pattern}@dots{})
9700 Find file names matching a shell file name pattern (@emph{not} a
9701 @samp{%} pattern).@*
9702 @xref{Wildcard Function, ,The Function @code{wildcard}}.
9703
9704 @item $(error @var{text}@dots{})
9705
9706 When this function is evaluated, @code{make} generates a fatal error
9707 with the message @var{text}.@*
9708 @xref{Make Control Functions, ,Functions That Control Make}.
9709
9710 @item $(warning @var{text}@dots{})
9711
9712 When this function is evaluated, @code{make} generates a warning with
9713 the message @var{text}.@*
9714 @xref{Make Control Functions, ,Functions That Control Make}.
9715
9716 @item $(shell @var{command})
9717
9718 Execute a shell command and return its output.@*
9719 @xref{Shell Function, , The @code{shell} Function}.
9720
9721 @item $(origin @var{variable})
9722
9723 Return a string describing how the @code{make} variable @var{variable} was
9724 defined.@*
9725 @xref{Origin Function, , The @code{origin} Function}.
9726
9727 @item $(foreach @var{var},@var{words},@var{text})
9728
9729 Evaluate @var{text} with @var{var} bound to each word in @var{words},
9730 and concatenate the results.@*
9731 @xref{Foreach Function, ,The @code{foreach} Function}.
9732
9733 @item $(call @var{var},@var{param},@dots{})
9734
9735 Evaluate the variable @var{var} replacing any references to @code{$(1)},
9736 @code{$(2)} with the first, second, etc. @var{param} values.@*
9737 @xref{Call Function, ,The @code{call} Function}.
9738
9739 @item $(eval @var{text})
9740
9741 Evaluate @var{text} then read the results as makefile commands.
9742 Expands to the empty string.@*
9743 @xref{Eval Function, ,The @code{eval} Function}.
9744
9745 @item $(value @var{var})
9746
9747 Evaluates to the contents of the variable @var{var}, with no expansion
9748 performed on it.@*
9749 @xref{Value Function, ,The @code{value} Function}.
9750 @end table
9751
9752 Here is a summary of the automatic variables.
9753 @xref{Automatic Variables},
9754 for full information.
9755
9756 @table @code
9757 @item $@@
9758 The file name of the target.
9759
9760 @item $%
9761 The target member name, when the target is an archive member.
9762
9763 @item $<
9764 The name of the first prerequisite.
9765
9766 @item $?
9767 The names of all the prerequisites that are
9768 newer than the target, with spaces between them.
9769 For prerequisites which are archive members, only
9770 the member named is used (@pxref{Archives}).
9771
9772 @item $^
9773 @itemx $+
9774 The names of all the prerequisites, with spaces between them. For
9775 prerequisites which are archive members, only the member named is used
9776 (@pxref{Archives}). The value of @code{$^} omits duplicate
9777 prerequisites, while @code{$+} retains them and preserves their order.
9778
9779 @item $*
9780 The stem with which an implicit rule matches
9781 (@pxref{Pattern Match, ,How Patterns Match}).
9782
9783 @item $(@@D)
9784 @itemx $(@@F)
9785 The directory part and the file-within-directory part of @code{$@@}.
9786
9787 @item $(*D)
9788 @itemx $(*F)
9789 The directory part and the file-within-directory part of @code{$*}.
9790
9791 @item $(%D)
9792 @itemx $(%F)
9793 The directory part and the file-within-directory part of @code{$%}.
9794
9795 @item $(<D)
9796 @itemx $(<F)
9797 The directory part and the file-within-directory part of @code{$<}.
9798
9799 @item $(^D)
9800 @itemx $(^F)
9801 The directory part and the file-within-directory part of @code{$^}.
9802
9803 @item $(+D)
9804 @itemx $(+F)
9805 The directory part and the file-within-directory part of @code{$+}.
9806
9807 @item $(?D)
9808 @itemx $(?F)
9809 The directory part and the file-within-directory part of @code{$?}.
9810 @end table
9811
9812 These variables are used specially by GNU @code{make}:
9813
9814 @table @code
9815 @item MAKEFILES
9816
9817 Makefiles to be read on every invocation of @code{make}.@*
9818 @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
9819
9820 @item VPATH
9821
9822 Directory search path for files not found in the current directory.@*
9823 @xref{General Search, , @code{VPATH} Search Path for All Prerequisites}.
9824
9825 @item SHELL
9826
9827 The name of the system default command interpreter, usually @file{/bin/sh}.
9828 You can set @code{SHELL} in the makefile to change the shell used to run
9829 commands. @xref{Execution, ,Command Execution}.
9830
9831 @item MAKESHELL
9832
9833 On MS-DOS only, the name of the command interpreter that is to be used
9834 by @code{make}. This value takes precedence over the value of
9835 @code{SHELL}. @xref{Execution, ,MAKESHELL variable}.
9836
9837 @item MAKE
9838
9839 The name with which @code{make} was invoked.
9840 Using this variable in commands has special meaning.
9841 @xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.
9842
9843 @item MAKELEVEL
9844
9845 The number of levels of recursion (sub-@code{make}s).@*
9846 @xref{Variables/Recursion}.
9847
9848 @item MAKEFLAGS
9849
9850 The flags given to @code{make}. You can set this in the environment or
9851 a makefile to set flags.@*
9852 @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
9853
9854 It is @emph{never} appropriate to use @code{MAKEFLAGS} directly on a
9855 command line: its contents may not be quoted correctly for use in the
9856 shell. Always allow recursive @code{make}'s to obtain these values
9857 through the environment from its parent.
9858
9859 @item MAKECMDGOALS
9860
9861 The targets given to @code{make} on the command line. Setting this
9862 variable has no effect on the operation of @code{make}.@*
9863 @xref{Goals, ,Arguments to Specify the Goals}.
9864
9865 @item CURDIR
9866
9867 Set to the pathname of the current working directory (after all
9868 @code{-C} options are processed, if any). Setting this variable has no
9869 effect on the operation of @code{make}.@*
9870 @xref{Recursion, ,Recursive Use of @code{make}}.
9871
9872 @item SUFFIXES
9873
9874 The default list of suffixes before @code{make} reads any makefiles.
9875
9876 @item .LIBPATTERNS
9877 Defines the naming of the libraries @code{make} searches for, and their
9878 order.@*
9879 @xref{Libraries/Search, ,Directory Search for Link Libraries}.
9880 @end table
9881
9882 @node Error Messages, Complex Makefile, Quick Reference, Top
9883 @comment node-name, next, previous, up
9884 @appendix Errors Generated by Make
9885
9886 Here is a list of the more common errors you might see generated by
9887 @code{make}, and some information about what they mean and how to fix
9888 them.
9889
9890 Sometimes @code{make} errors are not fatal, especially in the presence
9891 of a @code{-} prefix on a command script line, or the @code{-k} command
9892 line option. Errors that are fatal are prefixed with the string
9893 @code{***}.
9894
9895 Error messages are all either prefixed with the name of the program
9896 (usually @samp{make}), or, if the error is found in a makefile, the name
9897 of the file and linenumber containing the problem.
9898
9899 In the table below, these common prefixes are left off.
9900
9901 @table @samp
9902
9903 @item [@var{foo}] Error @var{NN}
9904 @itemx [@var{foo}] @var{signal description}
9905 These errors are not really @code{make} errors at all. They mean that a
9906 program that @code{make} invoked as part of a command script returned a
9907 non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets
9908 as failure, or it exited in some other abnormal fashion (with a
9909 signal of some type). @xref{Errors, ,Errors in Commands}.
9910
9911 If no @code{***} is attached to the message, then the subprocess failed
9912 but the rule in the makefile was prefixed with the @code{-} special
9913 character, so @code{make} ignored the error.
9914
9915 @item missing separator. Stop.
9916 @itemx missing separator (did you mean TAB instead of 8 spaces?). Stop.
9917 This means that @code{make} could not understand much of anything about
9918 the command line it just read. GNU @code{make} looks for various kinds
9919 of separators (@code{:}, @code{=}, TAB characters, etc.) to help it
9920 decide what kind of commandline it's seeing. This means it couldn't
9921 find a valid one.
9922
9923 One of the most common reasons for this message is that you (or perhaps
9924 your oh-so-helpful editor, as is the case with many MS-Windows editors)
9925 have attempted to indent your command scripts with spaces instead of a
9926 TAB character. In this case, @code{make} will use the second form of
9927 the error above. Remember that every line in the command script must
9928 begin with a TAB character. Eight spaces do not count. @xref{Rule
9929 Syntax}.
9930
9931 @item commands commence before first target. Stop.
9932 @itemx missing rule before commands. Stop.
9933 This means the first thing in the makefile seems to be part of a command
9934 script: it begins with a TAB character and doesn't appear to be a legal
9935 @code{make} command (such as a variable assignment). Command scripts
9936 must always be associated with a target.
9937
9938 The second form is generated if the line has a semicolon as the first
9939 non-whitespace character; @code{make} interprets this to mean you left
9940 out the "target: prerequisite" section of a rule. @xref{Rule Syntax}.
9941
9942 @item No rule to make target `@var{xxx}'.
9943 @itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'.
9944 This means that @code{make} decided it needed to build a target, but
9945 then couldn't find any instructions in the makefile on how to do that,
9946 either explicit or implicit (including in the default rules database).
9947
9948 If you want that file to be built, you will need to add a rule to your
9949 makefile describing how that target can be built. Other possible
9950 sources of this problem are typos in the makefile (if that filename is
9951 wrong) or a corrupted source tree (if that file is not supposed to be
9952 built, but rather only a prerequisite).
9953
9954 @item No targets specified and no makefile found. Stop.
9955 @itemx No targets. Stop.
9956 The former means that you didn't provide any targets to be built on the
9957 command line, and @code{make} couldn't find any makefiles to read in.
9958 The latter means that some makefile was found, but it didn't contain any
9959 default target and none was given on the command line. GNU @code{make}
9960 has nothing to do in these situations.
9961 @xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill
9962
9963 @item Makefile `@var{xxx}' was not found.
9964 @itemx Included makefile `@var{xxx}' was not found.
9965 A makefile specified on the command line (first form) or included
9966 (second form) was not found.
9967
9968 @item warning: overriding commands for target `@var{xxx}'
9969 @itemx warning: ignoring old commands for target `@var{xxx}'
9970 GNU @code{make} allows commands to be specified only once per target
9971 (except for double-colon rules). If you give commands for a target
9972 which already has been defined to have commands, this warning is issued
9973 and the second set of commands will overwrite the first set.
9974 @xref{Multiple Rules, ,Multiple Rules for One Target}.
9975
9976 @item Circular @var{xxx} <- @var{yyy} dependency dropped.
9977 This means that @code{make} detected a loop in the dependency graph:
9978 after tracing the prerequisite @var{yyy} of target @var{xxx}, and its
9979 prerequisites, etc., one of them depended on @var{xxx} again.
9980
9981 @item Recursive variable `@var{xxx}' references itself (eventually). Stop.
9982 This means you've defined a normal (recursive) @code{make} variable
9983 @var{xxx} that, when it's expanded, will refer to itself (@var{xxx}).
9984 This is not allowed; either use simply-expanded variables (@code{:=}) or
9985 use the append operator (@code{+=}). @xref{Using Variables, ,How to Use
9986 Variables}.
9987
9988 @item Unterminated variable reference. Stop.
9989 This means you forgot to provide the proper closing parenthesis
9990 or brace in your variable or function reference.
9991
9992 @item insufficient arguments to function `@var{xxx}'. Stop.
9993 This means you haven't provided the requisite number of arguments for
9994 this function. See the documentation of the function for a description
9995 of its arguments. @xref{Functions, ,Functions for Transforming Text}.
9996
9997 @item missing target pattern. Stop.
9998 @itemx multiple target patterns. Stop.
9999 @itemx target pattern contains no `%'. Stop.
10000 @itemx mixed implicit and static pattern rules. Stop.
10001 These are generated for malformed static pattern rules. The first means
10002 there's no pattern in the target section of the rule; the second means
10003 there are multiple patterns in the target section; the third means
10004 the target doesn't contain a pattern character (@code{%}); and the
10005 fourth means that all three parts of the static pattern rule contain
10006 pattern characters (@code{%})--only the first two parts should.
10007 @xref{Static Usage, ,Syntax of Static Pattern Rules}.
10008
10009 @item warning: -jN forced in submake: disabling jobserver mode.
10010 This warning and the next are generated if @code{make} detects error
10011 conditions related to parallel processing on systems where
10012 sub-@code{make}s can communicate (@pxref{Options/Recursion,
10013 ,Communicating Options to a Sub-@code{make}}). This warning is
10014 generated if a recursive invocation of a @code{make} process is forced
10015 to have @samp{-j@var{N}} in its argument list (where @var{N} is greater
10016 than one). This could happen, for example, if you set the @code{MAKE}
10017 environment variable to @samp{make -j2}. In this case, the
10018 sub-@code{make} doesn't communicate with other @code{make} processes and
10019 will simply pretend it has two jobs of its own.
10020
10021 @item warning: jobserver unavailable: using -j1. Add `+' to parent make rule.
10022 In order for @code{make} processes to communicate, the parent will pass
10023 information to the child. Since this could result in problems if the
10024 child process isn't actually a @code{make}, the parent will only do this
10025 if it thinks the child is a @code{make}. The parent uses the normal
10026 algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE}
10027 Variable Works}). If the makefile is constructed such that the parent
10028 doesn't know the child is a @code{make} process, then the child will
10029 receive only part of the information necessary. In this case, the child
10030 will generate this warning message and proceed with its build in a
10031 sequential manner.
10032
10033 @end table
10034
10035 @node Complex Makefile, GNU Free Documentation License, Error Messages, Top
10036 @appendix Complex Makefile Example
10037
10038 Here is the makefile for the GNU @code{tar} program. This is a
10039 moderately complex makefile.
10040
10041 Because it is the first target, the default goal is @samp{all}. An
10042 interesting feature of this makefile is that @file{testpad.h} is a
10043 source file automatically created by the @code{testpad} program,
10044 itself compiled from @file{testpad.c}.
10045
10046 If you type @samp{make} or @samp{make all}, then @code{make} creates
10047 the @file{tar} executable, the @file{rmt} daemon that provides
10048 remote tape access, and the @file{tar.info} Info file.
10049
10050 If you type @samp{make install}, then @code{make} not only creates
10051 @file{tar}, @file{rmt}, and @file{tar.info}, but also installs
10052 them.
10053
10054 If you type @samp{make clean}, then @code{make} removes the @samp{.o}
10055 files, and the @file{tar}, @file{rmt}, @file{testpad},
10056 @file{testpad.h}, and @file{core} files.
10057
10058 If you type @samp{make distclean}, then @code{make} not only removes
10059 the same files as does @samp{make clean} but also the
10060 @file{TAGS}, @file{Makefile}, and @file{config.status} files.
10061 (Although it is not evident, this makefile (and
10062 @file{config.status}) is generated by the user with the
10063 @code{configure} program, which is provided in the @code{tar}
10064 distribution, but is not shown here.)
10065
10066 If you type @samp{make realclean}, then @code{make} removes the same
10067 files as does @samp{make distclean} and also removes the Info files
10068 generated from @file{tar.texinfo}.
10069
10070 In addition, there are targets @code{shar} and @code{dist} that create
10071 distribution kits.
10072
10073 @example
10074 @group
10075 # Generated automatically from Makefile.in by configure.
10076 # Un*x Makefile for GNU tar program.
10077 # Copyright (C) 1991 Free Software Foundation, Inc.
10078 @end group
10079
10080 @group
10081 # This program is free software; you can redistribute
10082 # it and/or modify it under the terms of the GNU
10083 # General Public License @dots{}
10084 @dots{}
10085 @dots{}
10086 @end group
10087
10088 SHELL = /bin/sh
10089
10090 #### Start of system configuration section. ####
10091
10092 srcdir = .
10093
10094 @group
10095 # If you use gcc, you should either run the
10096 # fixincludes script that comes with it or else use
10097 # gcc with the -traditional option. Otherwise ioctl
10098 # calls will be compiled incorrectly on some systems.
10099 CC = gcc -O
10100 YACC = bison -y
10101 INSTALL = /usr/local/bin/install -c
10102 INSTALLDATA = /usr/local/bin/install -c -m 644
10103 @end group
10104
10105 # Things you might add to DEFS:
10106 # -DSTDC_HEADERS If you have ANSI C headers and
10107 # libraries.
10108 # -DPOSIX If you have POSIX.1 headers and
10109 # libraries.
10110 # -DBSD42 If you have sys/dir.h (unless
10111 # you use -DPOSIX), sys/file.h,
10112 # and st_blocks in `struct stat'.
10113 # -DUSG If you have System V/ANSI C
10114 # string and memory functions
10115 # and headers, sys/sysmacros.h,
10116 # fcntl.h, getcwd, no valloc,
10117 # and ndir.h (unless
10118 # you use -DDIRENT).
10119 # -DNO_MEMORY_H If USG or STDC_HEADERS but do not
10120 # include memory.h.
10121 # -DDIRENT If USG and you have dirent.h
10122 # instead of ndir.h.
10123 # -DSIGTYPE=int If your signal handlers
10124 # return int, not void.
10125 # -DNO_MTIO If you lack sys/mtio.h
10126 # (magtape ioctls).
10127 # -DNO_REMOTE If you do not have a remote shell
10128 # or rexec.
10129 # -DUSE_REXEC To use rexec for remote tape
10130 # operations instead of
10131 # forking rsh or remsh.
10132 # -DVPRINTF_MISSING If you lack vprintf function
10133 # (but have _doprnt).
10134 # -DDOPRNT_MISSING If you lack _doprnt function.
10135 # Also need to define
10136 # -DVPRINTF_MISSING.
10137 # -DFTIME_MISSING If you lack ftime system call.
10138 # -DSTRSTR_MISSING If you lack strstr function.
10139 # -DVALLOC_MISSING If you lack valloc function.
10140 # -DMKDIR_MISSING If you lack mkdir and
10141 # rmdir system calls.
10142 # -DRENAME_MISSING If you lack rename system call.
10143 # -DFTRUNCATE_MISSING If you lack ftruncate
10144 # system call.
10145 # -DV7 On Version 7 Unix (not
10146 # tested in a long time).
10147 # -DEMUL_OPEN3 If you lack a 3-argument version
10148 # of open, and want to emulate it
10149 # with system calls you do have.
10150 # -DNO_OPEN3 If you lack the 3-argument open
10151 # and want to disable the tar -k
10152 # option instead of emulating open.
10153 # -DXENIX If you have sys/inode.h
10154 # and need it 94 to be included.
10155
10156 DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
10157 -DVPRINTF_MISSING -DBSD42
10158 # Set this to rtapelib.o unless you defined NO_REMOTE,
10159 # in which case make it empty.
10160 RTAPELIB = rtapelib.o
10161 LIBS =
10162 DEF_AR_FILE = /dev/rmt8
10163 DEFBLOCKING = 20
10164
10165 @group
10166 CDEBUG = -g
10167 CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
10168 -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
10169 -DDEFBLOCKING=$(DEFBLOCKING)
10170 LDFLAGS = -g
10171 @end group
10172
10173 @group
10174 prefix = /usr/local
10175 # Prefix for each installed program,
10176 # normally empty or `g'.
10177 binprefix =
10178
10179 # The directory to install tar in.
10180 bindir = $(prefix)/bin
10181
10182 # The directory to install the info files in.
10183 infodir = $(prefix)/info
10184 @end group
10185
10186 #### End of system configuration section. ####
10187
10188 SRC1 = tar.c create.c extract.c buffer.c \
10189 getoldopt.c update.c gnu.c mangle.c
10190 SRC2 = version.c list.c names.c diffarch.c \
10191 port.c wildmat.c getopt.c
10192 SRC3 = getopt1.c regex.c getdate.y
10193 SRCS = $(SRC1) $(SRC2) $(SRC3)
10194 OBJ1 = tar.o create.o extract.o buffer.o \
10195 getoldopt.o update.o gnu.o mangle.o
10196 OBJ2 = version.o list.o names.o diffarch.o \
10197 port.o wildmat.o getopt.o
10198 OBJ3 = getopt1.o regex.o getdate.o $(RTAPELIB)
10199 OBJS = $(OBJ1) $(OBJ2) $(OBJ3)
10200 @group
10201 AUX = README COPYING ChangeLog Makefile.in \
10202 makefile.pc configure configure.in \
10203 tar.texinfo tar.info* texinfo.tex \
10204 tar.h port.h open3.h getopt.h regex.h \
10205 rmt.h rmt.c rtapelib.c alloca.c \
10206 msd_dir.h msd_dir.c tcexparg.c \
10207 level-0 level-1 backup-specs testpad.c
10208 @end group
10209
10210 all: tar rmt tar.info
10211
10212 @group
10213 tar: $(OBJS)
10214 $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
10215 @end group
10216
10217 @group
10218 rmt: rmt.c
10219 $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
10220 @end group
10221
10222 @group
10223 tar.info: tar.texinfo
10224 makeinfo tar.texinfo
10225 @end group
10226
10227 @group
10228 install: all
10229 $(INSTALL) tar $(bindir)/$(binprefix)tar
10230 -test ! -f rmt || $(INSTALL) rmt /etc/rmt
10231 $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
10232 @end group
10233
10234 @group
10235 $(OBJS): tar.h port.h testpad.h
10236 regex.o buffer.o tar.o: regex.h
10237 # getdate.y has 8 shift/reduce conflicts.
10238 @end group
10239
10240 @group
10241 testpad.h: testpad
10242 ./testpad
10243 @end group
10244
10245 @group
10246 testpad: testpad.o
10247 $(CC) -o $@@ testpad.o
10248 @end group
10249
10250 @group
10251 TAGS: $(SRCS)
10252 etags $(SRCS)
10253 @end group
10254
10255 @group
10256 clean:
10257 rm -f *.o tar rmt testpad testpad.h core
10258 @end group
10259
10260 @group
10261 distclean: clean
10262 rm -f TAGS Makefile config.status
10263 @end group
10264
10265 @group
10266 realclean: distclean
10267 rm -f tar.info*
10268 @end group
10269
10270 @group
10271 shar: $(SRCS) $(AUX)
10272 shar $(SRCS) $(AUX) | compress \
10273 > tar-`sed -e '/version_string/!d' \
10274 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
10275 -e q
10276 version.c`.shar.Z
10277 @end group
10278
10279 @group
10280 dist: $(SRCS) $(AUX)
10281 echo tar-`sed \
10282 -e '/version_string/!d' \
10283 -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
10284 -e q
10285 version.c` > .fname
10286 -rm -rf `cat .fname`
10287 mkdir `cat .fname`
10288 ln $(SRCS) $(AUX) `cat .fname`
10289 tar chZf `cat .fname`.tar.Z `cat .fname`
10290 -rm -rf `cat .fname` .fname
10291 @end group
10292
10293 @group
10294 tar.zoo: $(SRCS) $(AUX)
10295 -rm -rf tmp.dir
10296 -mkdir tmp.dir
10297 -rm tar.zoo
10298 for X in $(SRCS) $(AUX) ; do \
10299 echo $$X ; \
10300 sed 's/$$/^M/' $$X \
10301 > tmp.dir/$$X ; done
10302 cd tmp.dir ; zoo aM ../tar.zoo *
10303 -rm -rf tmp.dir
10304 @end group
10305 @end example
10306
10307 @raisesections
10308 @include fdl.texi
10309 @lowersections
10310
10311 @node Concept Index, Name Index, GNU Free Documentation License, Top
10312 @unnumbered Index of Concepts
10313
10314 @printindex cp
10315
10316 @node Name Index, , Concept Index, Top
10317 @unnumbered Index of Functions, Variables, & Directives
10318
10319 @printindex fn
10320
10321 @summarycontents
10322 @contents
10323 @bye

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26