1 This is make.info, produced by makeinfo version 6.7 from make.texi.
3 This file documents the GNU 'make' utility, which determines
4 automatically which pieces of a large program need to be recompiled, and
5 issues the commands to recompile them.
7 This is Edition 0.76, last updated 31 October 2022, of 'The GNU Make
8 Manual', for GNU 'make' version 4.4.
10 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
11 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
12 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021,
13 2022 Free Software Foundation, Inc.
15 Permission is granted to copy, distribute and/or modify this
16 document under the terms of the GNU Free Documentation License,
17 Version 1.3 or any later version published by the Free Software
18 Foundation; with no Invariant Sections, with the Front-Cover Texts
19 being "A GNU Manual," and with the Back-Cover Texts as in (a)
20 below. A copy of the license is included in the section entitled
21 "GNU Free Documentation License."
23 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
24 modify this GNU manual. Buying copies from the FSF supports it in
25 developing GNU and promoting software freedom."
26 INFO-DIR-SECTION Software development
28 * Make: (make). Remake files automatically.
32 File: make.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
37 This file documents the GNU 'make' utility, which determines
38 automatically which pieces of a large program need to be recompiled, and
39 issues the commands to recompile them.
41 This is Edition 0.76, last updated 31 October 2022, of 'The GNU Make
42 Manual', for GNU 'make' version 4.4.
44 Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
45 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009,
46 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021,
47 2022 Free Software Foundation, Inc.
49 Permission is granted to copy, distribute and/or modify this
50 document under the terms of the GNU Free Documentation License,
51 Version 1.3 or any later version published by the Free Software
52 Foundation; with no Invariant Sections, with the Front-Cover Texts
53 being "A GNU Manual," and with the Back-Cover Texts as in (a)
54 below. A copy of the license is included in the section entitled
55 "GNU Free Documentation License."
57 (a) The FSF's Back-Cover Text is: "You have the freedom to copy and
58 modify this GNU manual. Buying copies from the FSF supports it in
59 developing GNU and promoting software freedom."
63 * Overview:: Overview of 'make'.
64 * Introduction:: An introduction to 'make'.
65 * Makefiles:: Makefiles tell 'make' what to do.
66 * Rules:: Rules describe when a file must be remade.
67 * Recipes:: Recipes say how to remake a file.
68 * Using Variables:: You can use variables to avoid repetition.
69 * Conditionals:: Use or ignore parts of the makefile based
70 on the values of variables.
71 * Functions:: Many powerful ways to manipulate text.
72 * Invoking make: Running. How to invoke 'make' on the command line.
73 * Implicit Rules:: Use implicit rules to treat many files alike,
74 based on their file names.
75 * Archives:: How 'make' can update library archives.
76 * Extending make:: Using extensions to 'make'.
77 * Integrating make:: Integrating 'make' with other tools.
78 * Features:: Features GNU 'make' has over other 'make's.
79 * Missing:: What GNU 'make' lacks from other 'make's.
80 * Makefile Conventions:: Conventions for writing makefiles for
82 * Quick Reference:: A quick reference for experienced users.
83 * Error Messages:: A list of common errors generated by 'make'.
84 * Complex Makefile:: A real example of a straightforward,
85 but nontrivial, makefile.
87 * GNU Free Documentation License:: License for copying this manual.
88 * Concept Index:: Index of Concepts.
89 * Name Index:: Index of Functions, Variables, & Directives.
91 -- The Detailed Node Listing --
95 * Preparing:: Preparing and running 'make'.
96 * Reading:: On reading this text.
97 * Bugs:: Problems and bugs.
99 An Introduction to Makefiles
101 * Rule Introduction:: What a rule looks like.
102 * Simple Makefile:: A simple makefile.
103 * How Make Works:: How 'make' processes this makefile.
104 * Variables Simplify:: Variables make makefiles simpler.
105 * make Deduces:: Letting 'make' deduce the recipes.
106 * Combine By Prerequisite:: Another style of makefile.
107 * Cleanup:: Rules for cleaning the directory.
111 * Makefile Contents:: What makefiles contain.
112 * Makefile Names:: How to name your makefile.
113 * Include:: How one makefile can use another makefile.
114 * MAKEFILES Variable:: The environment can specify extra makefiles.
115 * Remaking Makefiles:: How makefiles get remade.
116 * Overriding Makefiles:: How to override part of one makefile
117 with another makefile.
118 * Reading Makefiles:: How makefiles are read in.
119 * Parsing Makefiles:: How makefiles are parsed.
120 * Secondary Expansion:: How and when secondary expansion is performed.
122 What Makefiles Contain
124 * Splitting Lines:: Splitting long lines in makefiles
128 * Rule Example:: An example explained.
129 * Rule Syntax:: General syntax explained.
130 * Prerequisite Types:: There are two types of prerequisites.
131 * Wildcards:: Using wildcard characters such as '*'.
132 * Directory Search:: Searching other directories for source files.
133 * Phony Targets:: Using a target that is not a real file's name.
134 * Force Targets:: You can use a target without a recipe
135 or prerequisites to mark other targets
137 * Empty Targets:: When only the date matters and the
139 * Special Targets:: Targets with special built-in meanings.
140 * Multiple Targets:: When to make use of several targets in a rule.
141 * Multiple Rules:: How to use several rules with the same target.
142 * Static Pattern:: Static pattern rules apply to multiple targets
143 and can vary the prerequisites according to
145 * Double-Colon:: How to use a special kind of rule to allow
146 several independent rules for one target.
147 * Automatic Prerequisites:: How to automatically generate rules giving
148 prerequisites from source files themselves.
150 Using Wildcard Characters in File Names
152 * Wildcard Examples:: Several examples.
153 * Wildcard Pitfall:: Problems to avoid.
154 * Wildcard Function:: How to cause wildcard expansion where
155 it does not normally take place.
157 Searching Directories for Prerequisites
159 * General Search:: Specifying a search path that applies
160 to every prerequisite.
161 * Selective Search:: Specifying a search path
162 for a specified class of names.
163 * Search Algorithm:: When and how search paths are applied.
164 * Recipes/Search:: How to write recipes that work together
166 * Implicit/Search:: How search paths affect implicit rules.
167 * Libraries/Search:: Directory search for link libraries.
171 * Static Usage:: The syntax of static pattern rules.
172 * Static versus Implicit:: When are they better than implicit rules?
174 Writing Recipes in Rules
176 * Recipe Syntax:: Recipe syntax features and pitfalls.
177 * Echoing:: How to control when recipes are echoed.
178 * Execution:: How recipes are executed.
179 * Parallel:: How recipes can be executed in parallel.
180 * Errors:: What happens after a recipe execution error.
181 * Interrupts:: What happens when a recipe is interrupted.
182 * Recursion:: Invoking 'make' from makefiles.
183 * Canned Recipes:: Defining canned recipes.
184 * Empty Recipes:: Defining useful, do-nothing recipes.
188 * Splitting Recipe Lines:: Breaking long recipe lines for readability.
189 * Variables in Recipes:: Using 'make' variables in recipes.
193 * One Shell:: One shell for all lines in a recipe.
194 * Choosing the Shell:: How 'make' chooses the shell used
199 * Parallel Disable:: Disabling parallel execution
200 * Parallel Output:: Handling output during parallel execution
201 * Parallel Input:: Handling input during parallel execution
203 Recursive Use of 'make'
205 * MAKE Variable:: The special effects of using '$(MAKE)'.
206 * Variables/Recursion:: How to communicate variables to a sub-'make'.
207 * Options/Recursion:: How to communicate options to a sub-'make'.
208 * -w Option:: How the '-w' or '--print-directory' option
209 helps debug use of recursive 'make' commands.
213 * Reference:: How to use the value of a variable.
214 * Flavors:: Variables come in two flavors.
215 * Advanced:: Advanced features for referencing a variable.
216 * Values:: All the ways variables get their values.
217 * Setting:: How to set a variable in the makefile.
218 * Appending:: How to append more text to the old value
220 * Override Directive:: How to set a variable in the makefile even if
221 the user has set it with a command argument.
222 * Multi-Line:: An alternate way to set a variable
223 to a multi-line string.
224 * Undefine Directive:: How to undefine a variable so that it appears
225 as if it was never set.
226 * Environment:: Variable values can come from the environment.
227 * Target-specific:: Variable values can be defined on a per-target
229 * Pattern-specific:: Target-specific variable values can be applied
230 to a group of targets that match a pattern.
231 * Suppressing Inheritance:: Suppress inheritance of variables.
232 * Special Variables:: Variables with special meaning or behavior.
234 The Two Flavors of Variables
236 * Recursive Assignment:: Setting recursively expanded variables.
237 * Simple Assignment:: Setting simply expanded variables.
238 * Immediate Assignment:: Setting immediately expanded variables.
239 * Conditional Assignment:: Assigning variable values conditionally.
241 Advanced Features for Reference to Variables
243 * Substitution Refs:: Referencing a variable with
244 substitutions on the value.
245 * Computed Names:: Computing the name of the variable to refer to.
247 Conditional Parts of Makefiles
249 * Conditional Example:: Example of a conditional
250 * Conditional Syntax:: The syntax of conditionals.
251 * Testing Flags:: Conditionals that test flags.
253 Functions for Transforming Text
255 * Syntax of Functions:: How to write a function call.
256 * Text Functions:: General-purpose text manipulation functions.
257 * File Name Functions:: Functions for manipulating file names.
258 * Conditional Functions:: Functions that implement conditions.
259 * Let Function:: Local variables.
260 * Foreach Function:: Repeat some text with controlled variation.
261 * File Function:: Write text to a file.
262 * Call Function:: Expand a user-defined function.
263 * Value Function:: Return the un-expanded value of a variable.
264 * Eval Function:: Evaluate the arguments as makefile syntax.
265 * Origin Function:: Find where a variable got its value.
266 * Flavor Function:: Find out the flavor of a variable.
267 * Make Control Functions:: Functions that control how make runs.
268 * Shell Function:: Substitute the output of a shell command.
269 * Guile Function:: Use GNU Guile embedded scripting language.
273 * Makefile Arguments:: How to specify which makefile to use.
274 * Goals:: How to use goal arguments to specify which
275 parts of the makefile to use.
276 * Instead of Execution:: How to use mode flags to specify what
277 kind of thing to do with the recipes
278 in the makefile other than simply
280 * Avoiding Compilation:: How to avoid recompiling certain files.
281 * Overriding:: How to override a variable to specify
282 an alternate compiler and other things.
283 * Testing:: How to proceed past some errors, to
285 * Temporary Files:: Where 'make' keeps its temporary files.
286 * Options Summary:: Summary of Options
290 * Using Implicit:: How to use an existing implicit rule
291 to get the recipes for updating a file.
292 * Catalogue of Rules:: A list of built-in rules.
293 * Implicit Variables:: How to change what predefined rules do.
294 * Chained Rules:: How to use a chain of implicit rules.
295 * Pattern Rules:: How to define new implicit rules.
296 * Last Resort:: How to define a recipe for rules which
298 * Suffix Rules:: The old-fashioned style of implicit rule.
299 * Implicit Rule Search:: The precise algorithm for applying
302 Defining and Redefining Pattern Rules
304 * Pattern Intro:: An introduction to pattern rules.
305 * Pattern Examples:: Examples of pattern rules.
306 * Automatic Variables:: How to use automatic variables in the
307 recipe of implicit rules.
308 * Pattern Match:: How patterns match.
309 * Match-Anything Rules:: Precautions you should take prior to
310 defining rules that can match any
311 target file whatever.
312 * Canceling Rules:: How to override or cancel built-in rules.
314 Using 'make' to Update Archive Files
316 * Archive Members:: Archive members as targets.
317 * Archive Update:: The implicit rule for archive member targets.
318 * Archive Pitfalls:: Dangers to watch out for when using archives.
319 * Archive Suffix Rules:: You can write a special kind of suffix rule
320 for updating archives.
322 Implicit Rule for Archive Member Targets
324 * Archive Symbols:: How to update archive symbol directories.
328 * Guile Integration:: Using Guile as an embedded scripting language.
329 * Loading Objects:: Loading dynamic objects as extensions.
331 GNU Guile Integration
333 * Guile Types:: Converting Guile types to 'make' strings.
334 * Guile Interface:: Invoking 'make' functions from Guile.
335 * Guile Example:: Example using Guile in 'make'.
337 Loading Dynamic Objects
339 * load Directive:: Loading dynamic objects as extensions.
340 * Remaking Loaded Objects:: How loaded objects get remade.
341 * Loaded Object API:: Programmatic interface for loaded objects.
342 * Loaded Object Example:: Example of a loaded object
344 Integrating GNU 'make'
346 * Job Slots:: Share job slots with GNU 'make'.
347 * Terminal Output:: Control output to terminals.
349 Sharing Job Slots with GNU 'make'
351 * POSIX Jobserver:: Using the jobserver on POSIX systems.
352 * Windows Jobserver:: Using the jobserver on Windows systems.
356 File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top
361 The 'make' utility automatically determines which pieces of a large
362 program need to be recompiled, and issues commands to recompile them.
363 This manual describes GNU 'make', which was implemented by Richard
364 Stallman and Roland McGrath. Development since Version 3.76 has been
365 handled by Paul D. Smith.
367 GNU 'make' conforms to section 6.2 of 'IEEE Standard 1003.2-1992'
370 Our examples show C programs, since they are most common, but you can
371 use 'make' with any programming language whose compiler can be run with
372 a shell command. Indeed, 'make' is not limited to programs. You can
373 use it to describe any task where some files must be updated
374 automatically from others whenever the others change.
378 * Preparing:: Preparing and running 'make'.
379 * Reading:: On reading this text.
380 * Bugs:: Problems and bugs.
383 File: make.info, Node: Preparing, Next: Reading, Prev: Overview, Up: Overview
385 Preparing and Running Make
386 ==========================
388 To prepare to use 'make', you must write a file called the "makefile"
389 that describes the relationships among files in your program and
390 provides commands for updating each file. In a program, typically, the
391 executable file is updated from object files, which are in turn made by
392 compiling source files.
394 Once a suitable makefile exists, each time you change some source
395 files, this simple shell command:
399 suffices to perform all necessary recompilations. The 'make' program
400 uses the makefile data base and the last-modification times of the files
401 to decide which of the files need to be updated. For each of those
402 files, it issues the recipes recorded in the data base.
404 You can provide command line arguments to 'make' to control which
405 files should be recompiled, or how. *Note How to Run 'make': Running.
408 File: make.info, Node: Reading, Next: Bugs, Prev: Preparing, Up: Overview
410 1.1 How to Read This Manual
411 ===========================
413 If you are new to 'make', or are looking for a general introduction,
414 read the first few sections of each chapter, skipping the later
415 sections. In each chapter, the first few sections contain introductory
416 or general information and the later sections contain specialized or
417 technical information. The exception is the second chapter, *note An
418 Introduction to Makefiles: Introduction, all of which is introductory.
420 If you are familiar with other 'make' programs, see *note Features of
421 GNU 'make': Features, which lists the enhancements GNU 'make' has, and
422 *note Incompatibilities and Missing Features: Missing, which explains
423 the few things GNU 'make' lacks that others have.
425 For a quick summary, see *note Options Summary::, *note Quick
426 Reference::, and *note Special Targets::.
429 File: make.info, Node: Bugs, Prev: Reading, Up: Overview
431 1.2 Problems and Bugs
432 =====================
434 If you have problems with GNU 'make' or think you've found a bug, please
435 report it to the developers; we cannot promise to do anything but we
436 might well want to fix it.
438 Before reporting a bug, make sure you've actually found a real bug.
439 Carefully reread the documentation and see if it really says you can do
440 what you're trying to do. If it's not clear whether you should be able
441 to do something or not, report that too; it's a bug in the
444 Before reporting a bug or trying to fix it yourself, try to isolate
445 it to the smallest possible makefile that reproduces the problem. Then
446 send us the makefile and the exact results 'make' gave you, including
447 any error or warning messages. Please don't paraphrase these messages:
448 it's best to cut and paste them into your report. When generating this
449 small makefile, be sure to not use any non-free or unusual tools in your
450 recipes: you can almost always emulate what such a tool would do with
451 simple shell commands. Finally, be sure to explain what you expected to
452 occur; this will help us decide whether the problem was really in the
455 Once you have a precise problem you can report it in one of two ways.
456 Either send electronic mail to:
460 or use our Web-based project management tool, at:
462 https://savannah.gnu.org/projects/make/
464 In addition to the information above, please be careful to include the
465 version number of 'make' you are using. You can get this information
466 with the command 'make --version'. Be sure also to include the type of
467 machine and operating system you are using. One way to obtain this
468 information is by looking at the final lines of output from the command
471 If you have a code change you'd like to submit, see the 'README' file
472 section "Submitting Patches" for information.
475 File: make.info, Node: Introduction, Next: Makefiles, Prev: Overview, Up: Top
477 2 An Introduction to Makefiles
478 ******************************
480 You need a file called a "makefile" to tell 'make' what to do. Most
481 often, the makefile tells 'make' how to compile and link a program.
483 In this chapter, we will discuss a simple makefile that describes how
484 to compile and link a text editor which consists of eight C source files
485 and three header files. The makefile can also tell 'make' how to run
486 miscellaneous commands when explicitly asked (for example, to remove
487 certain files as a clean-up operation). To see a more complex example
488 of a makefile, see *note Complex Makefile::.
490 When 'make' recompiles the editor, each changed C source file must be
491 recompiled. If a header file has changed, each C source file that
492 includes the header file must be recompiled to be safe. Each
493 compilation produces an object file corresponding to the source file.
494 Finally, if any source file has been recompiled, all the object files,
495 whether newly made or saved from previous compilations, must be linked
496 together to produce the new executable editor.
500 * Rule Introduction:: What a rule looks like.
501 * Simple Makefile:: A simple makefile.
502 * How Make Works:: How 'make' processes this makefile.
503 * Variables Simplify:: Variables make makefiles simpler.
504 * make Deduces:: Letting 'make' deduce the recipes.
505 * Combine By Prerequisite:: Another style of makefile.
506 * Cleanup:: Rules for cleaning the directory.
509 File: make.info, Node: Rule Introduction, Next: Simple Makefile, Prev: Introduction, Up: Introduction
511 2.1 What a Rule Looks Like
512 ==========================
514 A simple makefile consists of "rules" with the following shape:
516 TARGET ... : PREREQUISITES ...
521 A "target" is usually the name of a file that is generated by a
522 program; examples of targets are executable or object files. A target
523 can also be the name of an action to carry out, such as 'clean' (*note
526 A "prerequisite" is a file that is used as input to create the
527 target. A target often depends on several files.
529 A "recipe" is an action that 'make' carries out. A recipe may have
530 more than one command, either on the same line or each on its own line.
531 *Please note:* you need to put a tab character at the beginning of every
532 recipe line! This is an obscurity that catches the unwary. If you
533 prefer to prefix your recipes with a character other than tab, you can
534 set the '.RECIPEPREFIX' variable to an alternate character (*note
535 Special Variables::).
537 Usually a recipe is in a rule with prerequisites and serves to create
538 a target file if any of the prerequisites change. However, the rule
539 that specifies a recipe for the target need not have prerequisites. For
540 example, the rule containing the delete command associated with the
541 target 'clean' does not have prerequisites.
543 A "rule", then, explains how and when to remake certain files which
544 are the targets of the particular rule. 'make' carries out the recipe
545 on the prerequisites to create or update the target. A rule can also
546 explain how and when to carry out an action. *Note Writing Rules:
549 A makefile may contain other text besides rules, but a simple
550 makefile need only contain rules. Rules may look somewhat more
551 complicated than shown in this template, but all fit the pattern more or
555 File: make.info, Node: Simple Makefile, Next: How Make Works, Prev: Rule Introduction, Up: Introduction
557 2.2 A Simple Makefile
558 =====================
560 Here is a straightforward makefile that describes the way an executable
561 file called 'edit' depends on eight object files which, in turn, depend
562 on eight C source and three header files.
564 In this example, all the C files include 'defs.h', but only those
565 defining editing commands include 'command.h', and only low level files
566 that change the editor buffer include 'buffer.h'.
568 edit : main.o kbd.o command.o display.o \
569 insert.o search.o files.o utils.o
570 cc -o edit main.o kbd.o command.o display.o \
571 insert.o search.o files.o utils.o
573 main.o : main.c defs.h
575 kbd.o : kbd.c defs.h command.h
577 command.o : command.c defs.h command.h
579 display.o : display.c defs.h buffer.h
581 insert.o : insert.c defs.h buffer.h
583 search.o : search.c defs.h buffer.h
585 files.o : files.c defs.h buffer.h command.h
587 utils.o : utils.c defs.h
590 rm edit main.o kbd.o command.o display.o \
591 insert.o search.o files.o utils.o
593 We split each long line into two lines using backslash/newline; this is
594 like using one long line, but is easier to read. *Note Splitting Long
595 Lines: Splitting Lines.
597 To use this makefile to create the executable file called 'edit',
602 To use this makefile to delete the executable file and all the object
603 files from the directory, type:
607 In the example makefile, the targets include the executable file
608 'edit', and the object files 'main.o' and 'kbd.o'. The prerequisites
609 are files such as 'main.c' and 'defs.h'. In fact, each '.o' file is
610 both a target and a prerequisite. Recipes include 'cc -c main.c' and
613 When a target is a file, it needs to be recompiled or relinked if any
614 of its prerequisites change. In addition, any prerequisites that are
615 themselves automatically generated should be updated first. In this
616 example, 'edit' depends on each of the eight object files; the object
617 file 'main.o' depends on the source file 'main.c' and on the header file
620 A recipe may follow each line that contains a target and
621 prerequisites. These recipes say how to update the target file. A tab
622 character (or whatever character is specified by the '.RECIPEPREFIX'
623 variable; *note Special Variables::) must come at the beginning of every
624 line in the recipe to distinguish recipes from other lines in the
625 makefile. (Bear in mind that 'make' does not know anything about how
626 the recipes work. It is up to you to supply recipes that will update
627 the target file properly. All 'make' does is execute the recipe you
628 have specified when the target file needs to be updated.)
630 The target 'clean' is not a file, but merely the name of an action.
631 Since you normally do not want to carry out the actions in this rule,
632 'clean' is not a prerequisite of any other rule. Consequently, 'make'
633 never does anything with it unless you tell it specifically. Note that
634 this rule not only is not a prerequisite, it also does not have any
635 prerequisites, so the only purpose of the rule is to run the specified
636 recipe. Targets that do not refer to files but are just actions are
637 called "phony targets". *Note Phony Targets::, for information about
638 this kind of target. *Note Errors in Recipes: Errors, to see how to
639 cause 'make' to ignore errors from 'rm' or any other command.
642 File: make.info, Node: How Make Works, Next: Variables Simplify, Prev: Simple Makefile, Up: Introduction
644 2.3 How 'make' Processes a Makefile
645 ===================================
647 By default, 'make' starts with the first target (not targets whose names
648 start with '.' unless they also contain one or more '/'). This is
649 called the "default goal". ("Goals" are the targets that 'make' strives
650 ultimately to update. You can override this behavior using the command
651 line (*note Arguments to Specify the Goals: Goals.) or with the
652 '.DEFAULT_GOAL' special variable (*note Other Special Variables: Special
655 In the simple example of the previous section, the default goal is to
656 update the executable program 'edit'; therefore, we put that rule first.
658 Thus, when you give the command:
662 'make' reads the makefile in the current directory and begins by
663 processing the first rule. In the example, this rule is for relinking
664 'edit'; but before 'make' can fully process this rule, it must process
665 the rules for the files that 'edit' depends on, which in this case are
666 the object files. Each of these files is processed according to its own
667 rule. These rules say to update each '.o' file by compiling its source
668 file. The recompilation must be done if the source file, or any of the
669 header files named as prerequisites, is more recent than the object
670 file, or if the object file does not exist.
672 The other rules are processed because their targets appear as
673 prerequisites of the goal. If some other rule is not depended on by the
674 goal (or anything it depends on, etc.), that rule is not processed,
675 unless you tell 'make' to do so (with a command such as 'make clean').
677 Before recompiling an object file, 'make' considers updating its
678 prerequisites, the source file and header files. This makefile does not
679 specify anything to be done for them--the '.c' and '.h' files are not
680 the targets of any rules--so 'make' does nothing for these files. But
681 'make' would update automatically generated C programs, such as those
682 made by Bison or Yacc, by their own rules at this time.
684 After recompiling whichever object files need it, 'make' decides
685 whether to relink 'edit'. This must be done if the file 'edit' does not
686 exist, or if any of the object files are newer than it. If an object
687 file was just recompiled, it is now newer than 'edit', so 'edit' is
690 Thus, if we change the file 'insert.c' and run 'make', 'make' will
691 compile that file to update 'insert.o', and then link 'edit'. If we
692 change the file 'command.h' and run 'make', 'make' will recompile the
693 object files 'kbd.o', 'command.o' and 'files.o' and then link the file
697 File: make.info, Node: Variables Simplify, Next: make Deduces, Prev: How Make Works, Up: Introduction
699 2.4 Variables Make Makefiles Simpler
700 ====================================
702 In our example, we had to list all the object files twice in the rule
703 for 'edit' (repeated here):
705 edit : main.o kbd.o command.o display.o \
706 insert.o search.o files.o utils.o
707 cc -o edit main.o kbd.o command.o display.o \
708 insert.o search.o files.o utils.o
710 Such duplication is error-prone; if a new object file is added to the
711 system, we might add it to one list and forget the other. We can
712 eliminate the risk and simplify the makefile by using a variable.
713 "Variables" allow a text string to be defined once and substituted in
714 multiple places later (*note How to Use Variables: Using Variables.).
716 It is standard practice for every makefile to have a variable named
717 'objects', 'OBJECTS', 'objs', 'OBJS', 'obj', or 'OBJ' which is a list of
718 all object file names. We would define such a variable 'objects' with a
719 line like this in the makefile:
721 objects = main.o kbd.o command.o display.o \
722 insert.o search.o files.o utils.o
724 Then, each place we want to put a list of the object file names, we can
725 substitute the variable's value by writing '$(objects)' (*note How to
726 Use Variables: Using Variables.).
728 Here is how the complete simple makefile looks when you use a
729 variable for the object files:
731 objects = main.o kbd.o command.o display.o \
732 insert.o search.o files.o utils.o
735 cc -o edit $(objects)
736 main.o : main.c defs.h
738 kbd.o : kbd.c defs.h command.h
740 command.o : command.c defs.h command.h
742 display.o : display.c defs.h buffer.h
744 insert.o : insert.c defs.h buffer.h
746 search.o : search.c defs.h buffer.h
748 files.o : files.c defs.h buffer.h command.h
750 utils.o : utils.c defs.h
756 File: make.info, Node: make Deduces, Next: Combine By Prerequisite, Prev: Variables Simplify, Up: Introduction
758 2.5 Letting 'make' Deduce the Recipes
759 =====================================
761 It is not necessary to spell out the recipes for compiling the
762 individual C source files, because 'make' can figure them out: it has an
763 "implicit rule" for updating a '.o' file from a correspondingly named
764 '.c' file using a 'cc -c' command. For example, it will use the recipe
765 'cc -c main.c -o main.o' to compile 'main.c' into 'main.o'. We can
766 therefore omit the recipes from the rules for the object files. *Note
767 Using Implicit Rules: Implicit Rules.
769 When a '.c' file is used automatically in this way, it is also
770 automatically added to the list of prerequisites. We can therefore omit
771 the '.c' files from the prerequisites, provided we omit the recipe.
773 Here is the entire example, with both of these changes, and a
774 variable 'objects' as suggested above:
776 objects = main.o kbd.o command.o display.o \
777 insert.o search.o files.o utils.o
780 cc -o edit $(objects)
783 kbd.o : defs.h command.h
784 command.o : defs.h command.h
785 display.o : defs.h buffer.h
786 insert.o : defs.h buffer.h
787 search.o : defs.h buffer.h
788 files.o : defs.h buffer.h command.h
795 This is how we would write the makefile in actual practice. (The
796 complications associated with 'clean' are described elsewhere. See
797 *note Phony Targets::, and *note Errors in Recipes: Errors.)
799 Because implicit rules are so convenient, they are important. You
800 will see them used frequently.
803 File: make.info, Node: Combine By Prerequisite, Next: Cleanup, Prev: make Deduces, Up: Introduction
805 2.6 Another Style of Makefile
806 =============================
808 When the objects of a makefile are created only by implicit rules, an
809 alternative style of makefile is possible. In this style of makefile,
810 you group entries by their prerequisites instead of by their targets.
811 Here is what one looks like:
813 objects = main.o kbd.o command.o display.o \
814 insert.o search.o files.o utils.o
817 cc -o edit $(objects)
820 kbd.o command.o files.o : command.h
821 display.o insert.o search.o files.o : buffer.h
823 Here 'defs.h' is given as a prerequisite of all the object files;
824 'command.h' and 'buffer.h' are prerequisites of the specific object
825 files listed for them.
827 Whether this is better is a matter of taste: it is more compact, but
828 some people dislike it because they find it clearer to put all the
829 information about each target in one place.
832 File: make.info, Node: Cleanup, Prev: Combine By Prerequisite, Up: Introduction
834 2.7 Rules for Cleaning the Directory
835 ====================================
837 Compiling a program is not the only thing you might want to write rules
838 for. Makefiles commonly tell how to do a few other things besides
839 compiling a program: for example, how to delete all the object files and
840 executables so that the directory is 'clean'.
842 Here is how we could write a 'make' rule for cleaning our example
848 In practice, we might want to write the rule in a somewhat more
849 complicated manner to handle unanticipated situations. We would do
856 This prevents 'make' from getting confused by an actual file called
857 'clean' and causes it to continue in spite of errors from 'rm'. (See
858 *note Phony Targets::, and *note Errors in Recipes: Errors.)
860 A rule such as this should not be placed at the beginning of the
861 makefile, because we do not want it to run by default! Thus, in the
862 example makefile, we want the rule for 'edit', which recompiles the
863 editor, to remain the default goal.
865 Since 'clean' is not a prerequisite of 'edit', this rule will not run
866 at all if we give the command 'make' with no arguments. In order to
867 make the rule run, we have to type 'make clean'. *Note How to Run
871 File: make.info, Node: Makefiles, Next: Rules, Prev: Introduction, Up: Top
876 The information that tells 'make' how to recompile a system comes from
877 reading a data base called the "makefile".
881 * Makefile Contents:: What makefiles contain.
882 * Makefile Names:: How to name your makefile.
883 * Include:: How one makefile can use another makefile.
884 * MAKEFILES Variable:: The environment can specify extra makefiles.
885 * Remaking Makefiles:: How makefiles get remade.
886 * Overriding Makefiles:: How to override part of one makefile
887 with another makefile.
888 * Reading Makefiles:: How makefiles are read in.
889 * Parsing Makefiles:: How makefiles are parsed.
890 * Secondary Expansion:: How and when secondary expansion is performed.
893 File: make.info, Node: Makefile Contents, Next: Makefile Names, Prev: Makefiles, Up: Makefiles
895 3.1 What Makefiles Contain
896 ==========================
898 Makefiles contain five kinds of things: "explicit rules", "implicit
899 rules", "variable definitions", "directives", and "comments". Rules,
900 variables, and directives are described at length in later chapters.
902 * An "explicit rule" says when and how to remake one or more files,
903 called the rule's "targets". It lists the other files that the
904 targets depend on, called the "prerequisites" of the target, and
905 may also give a recipe to use to create or update the targets.
906 *Note Writing Rules: Rules.
908 * An "implicit rule" says when and how to remake a class of files
909 based on their names. It describes how a target may depend on a
910 file with a name similar to the target and gives a recipe to create
911 or update such a target. *Note Using Implicit Rules: Implicit
914 * A "variable definition" is a line that specifies a text string
915 value for a variable that can be substituted into the text later.
916 The simple makefile example shows a variable definition for
917 'objects' as a list of all object files (*note Variables Make
918 Makefiles Simpler: Variables Simplify.).
920 * A "directive" is an instruction for 'make' to do something special
921 while reading the makefile. These include:
923 * Reading another makefile (*note Including Other Makefiles:
926 * Deciding (based on the values of variables) whether to use or
927 ignore a part of the makefile (*note Conditional Parts of
928 Makefiles: Conditionals.).
930 * Defining a variable from a verbatim string containing multiple
931 lines (*note Defining Multi-Line Variables: Multi-Line.).
933 * '#' in a line of a makefile starts a "comment". It and the rest of
934 the line are ignored, except that a trailing backslash not escaped
935 by another backslash will continue the comment across multiple
936 lines. A line containing just a comment (with perhaps spaces
937 before it) is effectively blank, and is ignored. If you want a
938 literal '#', escape it with a backslash (e.g., '\#'). Comments may
939 appear on any line in the makefile, although they are treated
940 specially in certain situations.
942 You cannot use comments within variable references or function
943 calls: any instance of '#' will be treated literally (rather than
944 as the start of a comment) inside a variable reference or function
947 Comments within a recipe are passed to the shell, just as with any
948 other recipe text. The shell decides how to interpret it: whether
949 or not this is a comment is up to the shell.
951 Within a 'define' directive, comments are not ignored during the
952 definition of the variable, but rather kept intact in the value of
953 the variable. When the variable is expanded they will either be
954 treated as 'make' comments or as recipe text, depending on the
955 context in which the variable is evaluated.
959 * Splitting Lines:: Splitting long lines in makefiles
962 File: make.info, Node: Splitting Lines, Prev: Makefile Contents, Up: Makefile Contents
964 3.1.1 Splitting Long Lines
965 --------------------------
967 Makefiles use a "line-based" syntax in which the newline character is
968 special and marks the end of a statement. GNU 'make' has no limit on
969 the length of a statement line, up to the amount of memory in your
972 However, it is difficult to read lines which are too long to display
973 without wrapping or scrolling. So, you can format your makefiles for
974 readability by adding newlines into the middle of a statement: you do
975 this by escaping the internal newlines with a backslash ('\') character.
976 Where we need to make a distinction we will refer to "physical lines" as
977 a single line ending with a newline (regardless of whether it is
978 escaped) and a "logical line" being a complete statement including all
979 escaped newlines up to the first non-escaped newline.
981 The way in which backslash/newline combinations are handled depends
982 on whether the statement is a recipe line or a non-recipe line.
983 Handling of backslash/newline in a recipe line is discussed later (*note
984 Splitting Recipe Lines::).
986 Outside of recipe lines, backslash/newlines are converted into a
987 single space character. Once that is done, all whitespace around the
988 backslash/newline is condensed into a single space: this includes all
989 whitespace preceding the backslash, all whitespace at the beginning of
990 the line after the backslash/newline, and any consecutive
991 backslash/newline combinations.
993 If the '.POSIX' special target is defined then backslash/newline
994 handling is modified slightly to conform to POSIX.2: first, whitespace
995 preceding a backslash is not removed and second, consecutive
996 backslash/newlines are not condensed.
998 Splitting Without Adding Whitespace
999 ...................................
1001 If you need to split a line but do _not_ want any whitespace added, you
1002 can utilize a subtle trick: replace your backslash/newline pairs with
1003 the three characters dollar sign, backslash, and newline:
1008 After 'make' removes the backslash/newline and condenses the
1009 following line into a single space, this is equivalent to:
1013 Then 'make' will perform variable expansion. The variable reference
1014 '$ ' refers to a variable with the one-character name " " (space) which
1015 does not exist, and so expands to the empty string, giving a final
1016 assignment which is the equivalent of:
1021 File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles
1023 3.2 What Name to Give Your Makefile
1024 ===================================
1026 By default, when 'make' looks for the makefile, it tries the following
1027 names, in order: 'GNUmakefile', 'makefile' and 'Makefile'.
1029 Normally you should call your makefile either 'makefile' or
1030 'Makefile'. (We recommend 'Makefile' because it appears prominently
1031 near the beginning of a directory listing, right near other important
1032 files such as 'README'.) The first name checked, 'GNUmakefile', is not
1033 recommended for most makefiles. You should use this name if you have a
1034 makefile that is specific to GNU 'make', and will not be understood by
1035 other versions of 'make'. Other 'make' programs look for 'makefile' and
1036 'Makefile', but not 'GNUmakefile'.
1038 If 'make' finds none of these names, it does not use any makefile.
1039 Then you must specify a goal with a command argument, and 'make' will
1040 attempt to figure out how to remake it using only its built-in implicit
1041 rules. *Note Using Implicit Rules: Implicit Rules.
1043 If you want to use a nonstandard name for your makefile, you can
1044 specify the makefile name with the '-f' or '--file' option. The
1045 arguments '-f NAME' or '--file=NAME' tell 'make' to read the file NAME
1046 as the makefile. If you use more than one '-f' or '--file' option, you
1047 can specify several makefiles. All the makefiles are effectively
1048 concatenated in the order specified. The default makefile names
1049 'GNUmakefile', 'makefile' and 'Makefile' are not checked automatically
1050 if you specify '-f' or '--file'.
1053 File: make.info, Node: Include, Next: MAKEFILES Variable, Prev: Makefile Names, Up: Makefiles
1055 3.3 Including Other Makefiles
1056 =============================
1058 The 'include' directive tells 'make' to suspend reading the current
1059 makefile and read one or more other makefiles before continuing. The
1060 directive is a line in the makefile that looks like this:
1062 include FILENAMES...
1064 FILENAMES can contain shell file name patterns. If FILENAMES is empty,
1065 nothing is included and no error is printed.
1067 Extra spaces are allowed and ignored at the beginning of the line,
1068 but the first character must not be a tab (or the value of
1069 '.RECIPEPREFIX')--if the line begins with a tab, it will be considered a
1070 recipe line. Whitespace is required between 'include' and the file
1071 names, and between file names; extra whitespace is ignored there and at
1072 the end of the directive. A comment starting with '#' is allowed at the
1073 end of the line. If the file names contain any variable or function
1074 references, they are expanded. *Note How to Use Variables: Using
1077 For example, if you have three '.mk' files, 'a.mk', 'b.mk', and
1078 'c.mk', and '$(bar)' expands to 'bish bash', then the following
1081 include foo *.mk $(bar)
1085 include foo a.mk b.mk c.mk bish bash
1087 When 'make' processes an 'include' directive, it suspends reading of
1088 the containing makefile and reads from each listed file in turn. When
1089 that is finished, 'make' resumes reading the makefile in which the
1092 One occasion for using 'include' directives is when several programs,
1093 handled by individual makefiles in various directories, need to use a
1094 common set of variable definitions (*note Setting Variables: Setting.)
1095 or pattern rules (*note Defining and Redefining Pattern Rules: Pattern
1098 Another such occasion is when you want to generate prerequisites from
1099 source files automatically; the prerequisites can be put in a file that
1100 is included by the main makefile. This practice is generally cleaner
1101 than that of somehow appending the prerequisites to the end of the main
1102 makefile as has been traditionally done with other versions of 'make'.
1103 *Note Automatic Prerequisites::.
1105 If the specified name does not start with a slash, and the file is
1106 not found in the current directory, several other directories are
1107 searched. First, any directories you have specified with the '-I' or
1108 '--include-dir' options are searched (*note Summary of Options: Options
1109 Summary.). Then the following directories (if they exist) are searched,
1110 in this order: 'PREFIX/include' (normally '/usr/local/include' (1))
1111 '/usr/gnu/include', '/usr/local/include', '/usr/include'.
1113 The '.INCLUDE_DIRS' variable will contain the current list of
1114 directories that make will search for included files. *Note Other
1115 Special Variables: Special Variables.
1117 You can avoid searching in these default directories by adding the
1118 command line option '-I' with the special value '-' (e.g., '-I-') to the
1119 command line. This will cause 'make' to forget any already-set include
1120 directories, including the default directories.
1122 If an included makefile cannot be found in any of these directories
1123 it is not an immediately fatal error; processing of the makefile
1124 containing the 'include' continues. Once it has finished reading
1125 makefiles, 'make' will try to remake any that are out of date or don't
1126 exist. *Note How Makefiles Are Remade: Remaking Makefiles. Only after
1127 it has failed to find a rule to remake the makefile, or it found a rule
1128 but the recipe failed, will 'make' diagnose the missing makefile as a
1131 If you want 'make' to simply ignore a makefile which does not exist
1132 or cannot be remade, with no error message, use the '-include' directive
1133 instead of 'include', like this:
1135 -include FILENAMES...
1137 This acts like 'include' in every way except that there is no error
1138 (not even a warning) if any of the FILENAMES (or any prerequisites of
1139 any of the FILENAMES) do not exist or cannot be remade.
1141 For compatibility with some other 'make' implementations, 'sinclude'
1142 is another name for '-include'.
1144 ---------- Footnotes ----------
1146 (1) GNU Make compiled for MS-DOS and MS-Windows behaves as if PREFIX
1147 has been defined to be the root of the DJGPP tree hierarchy.
1150 File: make.info, Node: MAKEFILES Variable, Next: Remaking Makefiles, Prev: Include, Up: Makefiles
1152 3.4 The Variable 'MAKEFILES'
1153 ============================
1155 If the environment variable 'MAKEFILES' is defined, 'make' considers its
1156 value as a list of names (separated by whitespace) of additional
1157 makefiles to be read before the others. This works much like the
1158 'include' directive: various directories are searched for those files
1159 (*note Including Other Makefiles: Include.). In addition, the default
1160 goal is never taken from one of these makefiles (or any makefile
1161 included by them) and it is not an error if the files listed in
1162 'MAKEFILES' are not found.
1164 The main use of 'MAKEFILES' is in communication between recursive
1165 invocations of 'make' (*note Recursive Use of 'make': Recursion.). It
1166 usually is not desirable to set the environment variable before a
1167 top-level invocation of 'make', because it is usually better not to mess
1168 with a makefile from outside. However, if you are running 'make'
1169 without a specific makefile, a makefile in 'MAKEFILES' can do useful
1170 things to help the built-in implicit rules work better, such as defining
1171 search paths (*note Directory Search::).
1173 Some users are tempted to set 'MAKEFILES' in the environment
1174 automatically on login, and program makefiles to expect this to be done.
1175 This is a very bad idea, because such makefiles will fail to work if run
1176 by anyone else. It is much better to write explicit 'include'
1177 directives in the makefiles. *Note Including Other Makefiles: Include.
1180 File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: MAKEFILES Variable, Up: Makefiles
1182 3.5 How Makefiles Are Remade
1183 ============================
1185 Sometimes makefiles can be remade from other files, such as RCS or SCCS
1186 files. If a makefile can be remade from other files, you probably want
1187 'make' to get an up-to-date version of the makefile to read in.
1189 To this end, after reading in all makefiles 'make' will consider each
1190 as a goal target, in the order in which they were processed, and attempt
1191 to update it. If parallel builds (*note Parallel Execution: Parallel.)
1192 are enabled then makefiles will be rebuilt in parallel as well.
1194 If a makefile has a rule which says how to update it (found either in
1195 that very makefile or in another one) or if an implicit rule applies to
1196 it (*note Using Implicit Rules: Implicit Rules.), it will be updated if
1197 necessary. After all makefiles have been checked, if any have actually
1198 been changed, 'make' starts with a clean slate and reads all the
1199 makefiles over again. (It will also attempt to update each of them over
1200 again, but normally this will not change them again, since they are
1201 already up to date.) Each restart will cause the special variable
1202 'MAKE_RESTARTS' to be updated (*note Special Variables::).
1204 If you know that one or more of your makefiles cannot be remade and
1205 you want to keep 'make' from performing an implicit rule search on them,
1206 perhaps for efficiency reasons, you can use any normal method of
1207 preventing implicit rule look-up to do so. For example, you can write
1208 an explicit rule with the makefile as the target, and an empty recipe
1209 (*note Using Empty Recipes: Empty Recipes.).
1211 If the makefiles specify a double-colon rule to remake a file with a
1212 recipe but no prerequisites, that file will always be remade (*note
1213 Double-Colon::). In the case of makefiles, a makefile that has a
1214 double-colon rule with a recipe but no prerequisites will be remade
1215 every time 'make' is run, and then again after 'make' starts over and
1216 reads the makefiles in again. This would cause an infinite loop: 'make'
1217 would constantly remake the makefile and restart, and never do anything
1218 else. So, to avoid this, 'make' will *not* attempt to remake makefiles
1219 which are specified as targets of a double-colon rule with a recipe but
1222 Phony targets (*note Phony Targets::) have the same effect: they are
1223 never considered up-to-date and so an included file marked as phony
1224 would cause 'make' to restart continuously. To avoid this 'make' will
1225 not attempt to remake makefiles which are marked phony.
1227 You can take advantage of this to optimize startup time: if you know
1228 you don't need your 'Makefile' to be remade you can prevent make from
1229 trying to remake it by adding either:
1237 If you do not specify any makefiles to be read with '-f' or '--file'
1238 options, 'make' will try the default makefile names; *note What Name to
1239 Give Your Makefile: Makefile Names. Unlike makefiles explicitly
1240 requested with '-f' or '--file' options, 'make' is not certain that
1241 these makefiles should exist. However, if a default makefile does not
1242 exist but can be created by running 'make' rules, you probably want the
1243 rules to be run so that the makefile can be used.
1245 Therefore, if none of the default makefiles exists, 'make' will try
1246 to make each of them until it succeeds in making one, or it runs out of
1247 names to try. Note that it is not an error if 'make' cannot find or
1248 make any makefile; a makefile is not always necessary.
1250 When you use the '-t' or '--touch' option (*note Instead of Executing
1251 Recipes: Instead of Execution.), you would not want to use an
1252 out-of-date makefile to decide which targets to touch. So the '-t'
1253 option has no effect on updating makefiles; they are really updated even
1254 if '-t' is specified. Likewise, '-q' (or '--question') and '-n' (or
1255 '--just-print') do not prevent updating of makefiles, because an
1256 out-of-date makefile would result in the wrong output for other targets.
1257 Thus, 'make -f mfile -n foo' will update 'mfile', read it in, and then
1258 print the recipe to update 'foo' and its prerequisites without running
1259 it. The recipe printed for 'foo' will be the one specified in the
1260 updated contents of 'mfile'.
1262 However, on occasion you might actually wish to prevent updating of
1263 even the makefiles. You can do this by specifying the makefiles as
1264 goals in the command line as well as specifying them as makefiles. When
1265 the makefile name is specified explicitly as a goal, the options '-t'
1266 and so on do apply to them.
1268 Thus, 'make -f mfile -n mfile foo' would read the makefile 'mfile',
1269 print the recipe needed to update it without actually running it, and
1270 then print the recipe needed to update 'foo' without running that. The
1271 recipe for 'foo' will be the one specified by the existing contents of
1275 File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: Remaking Makefiles, Up: Makefiles
1277 3.6 Overriding Part of Another Makefile
1278 =======================================
1280 Sometimes it is useful to have a makefile that is mostly just like
1281 another makefile. You can often use the 'include' directive to include
1282 one in the other, and add more targets or variable definitions.
1283 However, it is invalid for two makefiles to give different recipes for
1284 the same target. But there is another way.
1286 In the containing makefile (the one that wants to include the other),
1287 you can use a match-anything pattern rule to say that to remake any
1288 target that cannot be made from the information in the containing
1289 makefile, 'make' should look in another makefile. *Note Pattern
1290 Rules::, for more information on pattern rules.
1292 For example, if you have a makefile called 'Makefile' that says how
1293 to make the target 'foo' (and other targets), you can write a makefile
1294 called 'GNUmakefile' that contains:
1300 @$(MAKE) -f Makefile $@
1303 If you say 'make foo', 'make' will find 'GNUmakefile', read it, and
1304 see that to make 'foo', it needs to run the recipe 'frobnicate > foo'.
1305 If you say 'make bar', 'make' will find no way to make 'bar' in
1306 'GNUmakefile', so it will use the recipe from the pattern rule: 'make -f
1307 Makefile bar'. If 'Makefile' provides a rule for updating 'bar', 'make'
1308 will apply the rule. And likewise for any other target that
1309 'GNUmakefile' does not say how to make.
1311 The way this works is that the pattern rule has a pattern of just
1312 '%', so it matches any target whatever. The rule specifies a
1313 prerequisite 'force', to guarantee that the recipe will be run even if
1314 the target file already exists. We give the 'force' target an empty
1315 recipe to prevent 'make' from searching for an implicit rule to build
1316 it--otherwise it would apply the same match-anything rule to 'force'
1317 itself and create a prerequisite loop!
1320 File: make.info, Node: Reading Makefiles, Next: Parsing Makefiles, Prev: Overriding Makefiles, Up: Makefiles
1322 3.7 How 'make' Reads a Makefile
1323 ===============================
1325 GNU 'make' does its work in two distinct phases. During the first phase
1326 it reads all the makefiles, included makefiles, etc. and internalizes
1327 all the variables and their values and implicit and explicit rules, and
1328 builds a dependency graph of all the targets and their prerequisites.
1329 During the second phase, 'make' uses this internalized data to determine
1330 which targets need to be updated and run the recipes necessary to update
1333 It's important to understand this two-phase approach because it has a
1334 direct impact on how variable and function expansion happens; this is
1335 often a source of some confusion when writing makefiles. Below is a
1336 summary of the different constructs that can be found in a makefile, and
1337 the phase in which expansion happens for each part of the construct.
1339 We say that expansion is "immediate" if it happens during the first
1340 phase: 'make' will expand that part of the construct as the makefile is
1341 parsed. We say that expansion is "deferred" if it is not immediate.
1342 Expansion of a deferred construct part is delayed until the expansion is
1343 used: either when it is referenced in an immediate context, or when it
1344 is needed during the second phase.
1346 You may not be familiar with some of these constructs yet. You can
1347 reference this section as you become familiar with them, in later
1353 Variable definitions are parsed as follows:
1355 IMMEDIATE = DEFERRED
1356 IMMEDIATE ?= DEFERRED
1357 IMMEDIATE := IMMEDIATE
1358 IMMEDIATE ::= IMMEDIATE
1359 IMMEDIATE :::= IMMEDIATE-WITH-ESCAPE
1360 IMMEDIATE += DEFERRED or IMMEDIATE
1361 IMMEDIATE != IMMEDIATE
1379 define IMMEDIATE ::=
1383 define IMMEDIATE :::=
1384 IMMEDIATE-WITH-ESCAPE
1388 DEFERRED or IMMEDIATE
1395 For the append operator '+=', the right-hand side is considered
1396 immediate if the variable was previously set as a simple variable (':='
1397 or '::='), and deferred otherwise.
1399 For the IMMEDIATE-WITH-ESCAPE operator ':::=', the value on the
1400 right-hand side is immediately expanded but then escaped (that is, all
1401 instances of '$' in the result of the expansion are replaced with '$$').
1403 For the shell assignment operator '!=', the right-hand side is
1404 evaluated immediately and handed to the shell. The result is stored in
1405 the variable named on the left, and that variable is considered a
1406 recursively expanded variable (and will thus be re-evaluated on each
1409 Conditional Directives
1410 ----------------------
1412 Conditional directives are parsed immediately. This means, for example,
1413 that automatic variables cannot be used in conditional directives, as
1414 automatic variables are not set until the recipe for that rule is
1415 invoked. If you need to use automatic variables in a conditional
1416 directive you _must_ move the condition into the recipe and use shell
1417 conditional syntax instead.
1422 A rule is always expanded the same way, regardless of the form:
1424 IMMEDIATE : IMMEDIATE ; DEFERRED
1427 That is, the target and prerequisite sections are expanded
1428 immediately, and the recipe used to build the target is always deferred.
1429 This is true for explicit rules, pattern rules, suffix rules, static
1430 pattern rules, and simple prerequisite definitions.
1433 File: make.info, Node: Parsing Makefiles, Next: Secondary Expansion, Prev: Reading Makefiles, Up: Makefiles
1435 3.8 How Makefiles Are Parsed
1436 ============================
1438 GNU 'make' parses makefiles line-by-line. Parsing proceeds using the
1441 1. Read in a full logical line, including backslash-escaped lines
1442 (*note Splitting Long Lines: Splitting Lines.).
1444 2. Remove comments (*note What Makefiles Contain: Makefile Contents.).
1446 3. If the line begins with the recipe prefix character and we are in a
1447 rule context, add the line to the current recipe and read the next
1448 line (*note Recipe Syntax::).
1450 4. Expand elements of the line which appear in an _immediate_
1451 expansion context (*note How 'make' Reads a Makefile: Reading
1454 5. Scan the line for a separator character, such as ':' or '=', to
1455 determine whether the line is a macro assignment or a rule (*note
1458 6. Internalize the resulting operation and read the next line.
1460 An important consequence of this is that a macro can expand to an
1461 entire rule, _if it is one line long_. This will work:
1463 myrule = target : ; echo built
1467 However, this will not work because 'make' does not re-split lines
1468 after it has expanded them:
1477 The above makefile results in the definition of a target 'target'
1478 with prerequisites 'echo' and 'built', as if the makefile contained
1479 'target: echo built', rather than a rule with a recipe. Newlines still
1480 present in a line after expansion is complete are ignored as normal
1483 In order to properly expand a multi-line macro you must use the
1484 'eval' function: this causes the 'make' parser to be run on the results
1485 of the expanded macro (*note Eval Function::).
1488 File: make.info, Node: Secondary Expansion, Prev: Parsing Makefiles, Up: Makefiles
1490 3.9 Secondary Expansion
1491 =======================
1493 Previously we learned that GNU 'make' works in two distinct phases: a
1494 read-in phase and a target-update phase (*note How 'make' Reads a
1495 Makefile: Reading Makefiles.). GNU make also has the ability to enable
1496 a _second expansion_ of the prerequisites (only) for some or all targets
1497 defined in the makefile. In order for this second expansion to occur,
1498 the special target '.SECONDEXPANSION' must be defined before the first
1499 prerequisite list that makes use of this feature.
1501 If '.SECONDEXPANSION' is defined then when GNU 'make' needs to check
1502 the prerequisites of a target, the prerequisites are expanded a _second
1503 time_. In most circumstances this secondary expansion will have no
1504 effect, since all variable and function references will have been
1505 expanded during the initial parsing of the makefiles. In order to take
1506 advantage of the secondary expansion phase of the parser, then, it's
1507 necessary to _escape_ the variable or function reference in the
1508 makefile. In this case the first expansion merely un-escapes the
1509 reference but doesn't expand it, and expansion is left to the secondary
1510 expansion phase. For example, consider this makefile:
1515 myfile: $(ONEVAR) $$(TWOVAR)
1517 After the first expansion phase the prerequisites list of the
1518 'myfile' target will be 'onefile' and '$(TWOVAR)'; the first (unescaped)
1519 variable reference to ONEVAR is expanded, while the second (escaped)
1520 variable reference is simply unescaped, without being recognized as a
1521 variable reference. Now during the secondary expansion the first word
1522 is expanded again but since it contains no variable or function
1523 references it remains the value 'onefile', while the second word is now
1524 a normal reference to the variable TWOVAR, which is expanded to the
1525 value 'twofile'. The final result is that there are two prerequisites,
1526 'onefile' and 'twofile'.
1528 Obviously, this is not a very interesting case since the same result
1529 could more easily have been achieved simply by having both variables
1530 appear, unescaped, in the prerequisites list. One difference becomes
1531 apparent if the variables are reset; consider this example:
1539 Here the prerequisite of 'onefile' will be expanded immediately, and
1540 resolve to the value 'top', while the prerequisite of 'twofile' will not
1541 be full expanded until the secondary expansion and yield a value of
1544 This is marginally more exciting, but the true power of this feature
1545 only becomes apparent when you discover that secondary expansions always
1546 take place within the scope of the automatic variables for that target.
1547 This means that you can use variables such as '$@', '$*', etc. during
1548 the second expansion and they will have their expected values, just as
1549 in the recipe. All you have to do is defer the expansion by escaping
1550 the '$'. Also, secondary expansion occurs for both explicit and
1551 implicit (pattern) rules. Knowing this, the possible uses for this
1552 feature increase dramatically. For example:
1555 main_OBJS := main.o try.o test.o
1556 lib_OBJS := lib.o api.o
1558 main lib: $$($$@_OBJS)
1560 Here, after the initial expansion the prerequisites of both the
1561 'main' and 'lib' targets will be '$($@_OBJS)'. During the secondary
1562 expansion, the '$@' variable is set to the name of the target and so the
1563 expansion for the 'main' target will yield '$(main_OBJS)', or 'main.o
1564 try.o test.o', while the secondary expansion for the 'lib' target will
1565 yield '$(lib_OBJS)', or 'lib.o api.o'.
1567 You can also mix in functions here, as long as they are properly
1570 main_SRCS := main.c try.c test.c
1571 lib_SRCS := lib.c api.c
1574 main lib: $$(patsubst %.c,%.o,$$($$@_SRCS))
1576 This version allows users to specify source files rather than object
1577 files, but gives the same resulting prerequisites list as the previous
1580 Evaluation of automatic variables during the secondary expansion
1581 phase, especially of the target name variable '$$@', behaves similarly
1582 to evaluation within recipes. However, there are some subtle
1583 differences and "corner cases" which come into play for the different
1584 types of rule definitions that 'make' understands. The subtleties of
1585 using the different automatic variables are described below.
1587 Secondary Expansion of Explicit Rules
1588 -------------------------------------
1590 During the secondary expansion of explicit rules, '$$@' and '$$%'
1591 evaluate, respectively, to the file name of the target and, when the
1592 target is an archive member, the target member name. The '$$<' variable
1593 evaluates to the first prerequisite in the first rule for this target.
1594 '$$^' and '$$+' evaluate to the list of all prerequisites of rules _that
1595 have already appeared_ for the same target ('$$+' with repetitions and
1596 '$$^' without). The following example will help illustrate these
1601 foo: foo.1 bar.1 $$< $$^ $$+ # line #1
1603 foo: foo.2 bar.2 $$< $$^ $$+ # line #2
1605 foo: foo.3 bar.3 $$< $$^ $$+ # line #3
1607 In the first prerequisite list, all three variables ('$$<', '$$^',
1608 and '$$+') expand to the empty string. In the second, they will have
1609 values 'foo.1', 'foo.1 bar.1', and 'foo.1 bar.1' respectively. In the
1610 third they will have values 'foo.1', 'foo.1 bar.1 foo.2 bar.2', and
1611 'foo.1 bar.1 foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1' respectively.
1613 Rules undergo secondary expansion in makefile order, except that the
1614 rule with the recipe is always evaluated last.
1616 The variables '$$?' and '$$*' are not available and expand to the
1619 Secondary Expansion of Static Pattern Rules
1620 -------------------------------------------
1622 Rules for secondary expansion of static pattern rules are identical to
1623 those for explicit rules, above, with one exception: for static pattern
1624 rules the '$$*' variable is set to the pattern stem. As with explicit
1625 rules, '$$?' is not available and expands to the empty string.
1627 Secondary Expansion of Implicit Rules
1628 -------------------------------------
1630 As 'make' searches for an implicit rule, it substitutes the stem and
1631 then performs secondary expansion for every rule with a matching target
1632 pattern. The value of the automatic variables is derived in the same
1633 fashion as for static pattern rules. As an example:
1641 %oo: $$< $$^ $$+ $$*
1643 When the implicit rule is tried for target 'foo', '$$<' expands to
1644 'bar', '$$^' expands to 'bar boo', '$$+' also expands to 'bar boo', and
1645 '$$*' expands to 'f'.
1647 Note that the directory prefix (D), as described in *note Implicit
1648 Rule Search Algorithm: Implicit Rule Search, is appended (after
1649 expansion) to all the patterns in the prerequisites list. As an
1656 %.o: $$(addsuffix /%.c,foo bar) foo.h
1659 The prerequisite list printed, after the secondary expansion and
1660 directory prefix reconstruction, will be '/tmp/foo/foo.c /tmp/bar/foo.c
1661 foo.h'. If you are not interested in this reconstruction, you can use
1662 '$$*' instead of '%' in the prerequisites list.
1665 File: make.info, Node: Rules, Next: Recipes, Prev: Makefiles, Up: Top
1670 A "rule" appears in the makefile and says when and how to remake certain
1671 files, called the rule's "targets" (most often only one per rule). It
1672 lists the other files that are the "prerequisites" of the target, and
1673 the "recipe" to use to create or update the target.
1675 The order of rules is not significant, except for determining the
1676 "default goal": the target for 'make' to consider, if you do not
1677 otherwise specify one. The default goal is the first target of the
1678 first rule in the first makefile. There are two exceptions: a target
1679 starting with a period is not a default unless it also contains one or
1680 more slashes, '/'; and, a target that defines a pattern rule has no
1681 effect on the default goal. (*Note Defining and Redefining Pattern
1682 Rules: Pattern Rules.)
1684 Therefore, we usually write the makefile so that the first rule is
1685 the one for compiling the entire program or all the programs described
1686 by the makefile (often with a target called 'all'). *Note Arguments to
1687 Specify the Goals: Goals.
1691 * Rule Example:: An example explained.
1692 * Rule Syntax:: General syntax explained.
1693 * Prerequisite Types:: There are two types of prerequisites.
1694 * Wildcards:: Using wildcard characters such as '*'.
1695 * Directory Search:: Searching other directories for source files.
1696 * Phony Targets:: Using a target that is not a real file's name.
1697 * Force Targets:: You can use a target without a recipe
1698 or prerequisites to mark other targets
1700 * Empty Targets:: When only the date matters and the
1702 * Special Targets:: Targets with special built-in meanings.
1703 * Multiple Targets:: When to make use of several targets in a rule.
1704 * Multiple Rules:: How to use several rules with the same target.
1705 * Static Pattern:: Static pattern rules apply to multiple targets
1706 and can vary the prerequisites according to
1708 * Double-Colon:: How to use a special kind of rule to allow
1709 several independent rules for one target.
1710 * Automatic Prerequisites:: How to automatically generate rules giving
1711 prerequisites from source files themselves.
1714 File: make.info, Node: Rule Example, Next: Rule Syntax, Prev: Rules, Up: Rules
1719 Here is an example of a rule:
1721 foo.o : foo.c defs.h # module for twiddling the frobs
1724 Its target is 'foo.o' and its prerequisites are 'foo.c' and 'defs.h'.
1725 It has one command in the recipe: 'cc -c -g foo.c'. The recipe starts
1726 with a tab to identify it as a recipe.
1728 This rule says two things:
1730 * How to decide whether 'foo.o' is out of date: it is out of date if
1731 it does not exist, or if either 'foo.c' or 'defs.h' is more recent
1734 * How to update the file 'foo.o': by running 'cc' as stated. The
1735 recipe does not explicitly mention 'defs.h', but we presume that
1736 'foo.c' includes it, and that is why 'defs.h' was added to the
1740 File: make.info, Node: Rule Syntax, Next: Prerequisite Types, Prev: Rule Example, Up: Rules
1745 In general, a rule looks like this:
1747 TARGETS : PREREQUISITES
1753 TARGETS : PREREQUISITES ; RECIPE
1757 The TARGETS are file names, separated by spaces. Wildcard characters
1758 may be used (*note Using Wildcard Characters in File Names: Wildcards.)
1759 and a name of the form 'A(M)' represents member M in archive file A
1760 (*note Archive Members as Targets: Archive Members.). Usually there is
1761 only one target per rule, but occasionally there is a reason to have
1762 more (*note Multiple Targets in a Rule: Multiple Targets.).
1764 The RECIPE lines start with a tab character (or the first character
1765 in the value of the '.RECIPEPREFIX' variable; *note Special
1766 Variables::). The first recipe line may appear on the line after the
1767 prerequisites, with a tab character, or may appear on the same line,
1768 with a semicolon. Either way, the effect is the same. There are other
1769 differences in the syntax of recipes. *Note Writing Recipes in Rules:
1772 Because dollar signs are used to start 'make' variable references, if
1773 you really want a dollar sign in a target or prerequisite you must write
1774 two of them, '$$' (*note How to Use Variables: Using Variables.). If
1775 you have enabled secondary expansion (*note Secondary Expansion::) and
1776 you want a literal dollar sign in the prerequisites list, you must
1777 actually write _four_ dollar signs ('$$$$').
1779 You may split a long line by inserting a backslash followed by a
1780 newline, but this is not required, as 'make' places no limit on the
1781 length of a line in a makefile.
1783 A rule tells 'make' two things: when the targets are out of date, and
1784 how to update them when necessary.
1786 The criterion for being out of date is specified in terms of the
1787 PREREQUISITES, which consist of file names separated by spaces.
1788 (Wildcards and archive members (*note Archives::) are allowed here too.)
1789 A target is out of date if it does not exist or if it is older than any
1790 of the prerequisites (by comparison of last-modification times). The
1791 idea is that the contents of the target file are computed based on
1792 information in the prerequisites, so if any of the prerequisites
1793 changes, the contents of the existing target file are no longer
1796 How to update is specified by a RECIPE. This is one or more lines to
1797 be executed by the shell (normally 'sh'), but with some extra features
1798 (*note Writing Recipes in Rules: Recipes.).
1801 File: make.info, Node: Prerequisite Types, Next: Wildcards, Prev: Rule Syntax, Up: Rules
1803 4.3 Types of Prerequisites
1804 ==========================
1806 There are two different types of prerequisites understood by GNU 'make':
1807 normal prerequisites, described in the previous section, and
1808 "order-only" prerequisites. A normal prerequisite makes two statements:
1809 first, it imposes an order in which recipes will be invoked: the recipes
1810 for all prerequisites of a target will be completed before the recipe
1811 for the target is started. Second, it imposes a dependency
1812 relationship: if any prerequisite is newer than the target, then the
1813 target is considered out-of-date and must be rebuilt.
1815 Normally, this is exactly what you want: if a target's prerequisite
1816 is updated, then the target should also be updated.
1818 Occasionally you may want to ensure that a prerequisite is built
1819 before a target, but _without_ forcing the target to be updated if the
1820 prerequisite is updated. "Order-only" prerequisites are used to create
1821 this type of relationship. Order-only prerequisites can be specified by
1822 placing a pipe symbol ('|') in the prerequisites list: any prerequisites
1823 to the left of the pipe symbol are normal; any prerequisites to the
1824 right are order-only:
1826 TARGETS : NORMAL-PREREQUISITES | ORDER-ONLY-PREREQUISITES
1828 The normal prerequisites section may of course be empty. Also, you
1829 may still declare multiple lines of prerequisites for the same target:
1830 they are appended appropriately (normal prerequisites are appended to
1831 the list of normal prerequisites; order-only prerequisites are appended
1832 to the list of order-only prerequisites). Note that if you declare the
1833 same file to be both a normal and an order-only prerequisite, the normal
1834 prerequisite takes precedence (since they have a strict superset of the
1835 behavior of an order-only prerequisite).
1837 Order-only prerequisites are never checked when determining if the
1838 target is out of date; even order-only prerequisites marked as phony
1839 (*note Phony Targets::) will not cause the target to be rebuilt.
1841 Consider an example where your targets are to be placed in a separate
1842 directory, and that directory might not exist before 'make' is run. In
1843 this situation, you want the directory to be created before any targets
1844 are placed into it but, because the timestamps on directories change
1845 whenever a file is added, removed, or renamed, we certainly don't want
1846 to rebuild all the targets whenever the directory's timestamp changes.
1847 One way to manage this is with order-only prerequisites: make the
1848 directory an order-only prerequisite on all the targets:
1851 OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)
1854 $(COMPILE.c) $(OUTPUT_OPTION) $<
1858 $(OBJS): | $(OBJDIR)
1863 Now the rule to create the 'objdir' directory will be run, if needed,
1864 before any '.o' is built, but no '.o' will be built because the 'objdir'
1865 directory timestamp changed.
1868 File: make.info, Node: Wildcards, Next: Directory Search, Prev: Prerequisite Types, Up: Rules
1870 4.4 Using Wildcard Characters in File Names
1871 ===========================================
1873 A single file name can specify many files using "wildcard characters".
1874 The wildcard characters in 'make' are '*', '?' and '[...]', the same as
1875 in the Bourne shell. For example, '*.c' specifies a list of all the
1876 files (in the working directory) whose names end in '.c'.
1878 If an expression matches multiple files than the results will be
1879 sorted.(1) However multiple expressions will not be globally sorted.
1880 For example, '*.c *.h' will list all the files whose names end in '.c',
1881 sorted, followed by all the files whose names end in '.h', sorted.
1883 The character '~' at the beginning of a file name also has special
1884 significance. If alone, or followed by a slash, it represents your home
1885 directory. For example '~/bin' expands to '/home/you/bin'. If the '~'
1886 is followed by a word, the string represents the home directory of the
1887 user named by that word. For example '~john/bin' expands to
1888 '/home/john/bin'. On systems which don't have a home directory for each
1889 user (such as MS-DOS or MS-Windows), this functionality can be simulated
1890 by setting the environment variable HOME.
1892 Wildcard expansion is performed by 'make' automatically in targets
1893 and in prerequisites. In recipes, the shell is responsible for wildcard
1894 expansion. In other contexts, wildcard expansion happens only if you
1895 request it explicitly with the 'wildcard' function.
1897 The special significance of a wildcard character can be turned off by
1898 preceding it with a backslash. Thus, 'foo\*bar' would refer to a
1899 specific file whose name consists of 'foo', an asterisk, and 'bar'.
1903 * Wildcard Examples:: Several examples.
1904 * Wildcard Pitfall:: Problems to avoid.
1905 * Wildcard Function:: How to cause wildcard expansion where
1906 it does not normally take place.
1908 ---------- Footnotes ----------
1910 (1) Some older versions of GNU 'make' did not sort the results of
1914 File: make.info, Node: Wildcard Examples, Next: Wildcard Pitfall, Prev: Wildcards, Up: Wildcards
1916 4.4.1 Wildcard Examples
1917 -----------------------
1919 Wildcards can be used in the recipe of a rule, where they are expanded
1920 by the shell. For example, here is a rule to delete all the object
1926 Wildcards are also useful in the prerequisites of a rule. With the
1927 following rule in the makefile, 'make print' will print all the '.c'
1928 files that have changed since the last time you printed them:
1934 This rule uses 'print' as an empty target file; see *note Empty Target
1935 Files to Record Events: Empty Targets. (The automatic variable '$?' is
1936 used to print only those files that have changed; see *note Automatic
1939 Wildcard expansion does not happen when you define a variable. Thus,
1944 then the value of the variable 'objects' is the actual string '*.o'.
1945 However, if you use the value of 'objects' in a target or prerequisite,
1946 wildcard expansion will take place there. If you use the value of
1947 'objects' in a recipe, the shell may perform wildcard expansion when the
1948 recipe runs. To set 'objects' to the expansion, instead use:
1950 objects := $(wildcard *.o)
1952 *Note Wildcard Function::.
1955 File: make.info, Node: Wildcard Pitfall, Next: Wildcard Function, Prev: Wildcard Examples, Up: Wildcards
1957 4.4.2 Pitfalls of Using Wildcards
1958 ---------------------------------
1960 Now here is an example of a naive way of using wildcard expansion, that
1961 does not do what you would intend. Suppose you would like to say that
1962 the executable file 'foo' is made from all the object files in the
1963 directory, and you write this:
1968 cc -o foo $(CFLAGS) $(objects)
1970 The value of 'objects' is the actual string '*.o'. Wildcard expansion
1971 happens in the rule for 'foo', so that each _existing_ '.o' file becomes
1972 a prerequisite of 'foo' and will be recompiled if necessary.
1974 But what if you delete all the '.o' files? When a wildcard matches
1975 no files, it is left as it is, so then 'foo' will depend on the
1976 oddly-named file '*.o'. Since no such file is likely to exist, 'make'
1977 will give you an error saying it cannot figure out how to make '*.o'.
1978 This is not what you want!
1980 Actually it is possible to obtain the desired result with wildcard
1981 expansion, but you need more sophisticated techniques, including the
1982 'wildcard' function and string substitution. *Note The Function
1983 'wildcard': Wildcard Function.
1985 Microsoft operating systems (MS-DOS and MS-Windows) use backslashes
1986 to separate directories in pathnames, like so:
1990 This is equivalent to the Unix-style 'c:/foo/bar/baz.c' (the 'c:'
1991 part is the so-called drive letter). When 'make' runs on these systems,
1992 it supports backslashes as well as the Unix-style forward slashes in
1993 pathnames. However, this support does _not_ include the wildcard
1994 expansion, where backslash is a quote character. Therefore, you _must_
1995 use Unix-style slashes in these cases.
1998 File: make.info, Node: Wildcard Function, Prev: Wildcard Pitfall, Up: Wildcards
2000 4.4.3 The Function 'wildcard'
2001 -----------------------------
2003 Wildcard expansion happens automatically in rules. But wildcard
2004 expansion does not normally take place when a variable is set, or inside
2005 the arguments of a function. If you want to do wildcard expansion in
2006 such places, you need to use the 'wildcard' function, like this:
2008 $(wildcard PATTERN...)
2010 This string, used anywhere in a makefile, is replaced by a
2011 space-separated list of names of existing files that match one of the
2012 given file name patterns. If no existing file name matches a pattern,
2013 then that pattern is omitted from the output of the 'wildcard' function.
2014 Note that this is different from how unmatched wildcards behave in
2015 rules, where they are used verbatim rather than ignored (*note Wildcard
2018 As with wildcard expansion in rules, the results of the 'wildcard'
2019 function are sorted. But again, each individual expression is sorted
2020 separately, so '$(wildcard *.c *.h)' will expand to all files matching
2021 '.c', sorted, followed by all files matching '.h', sorted.
2023 One use of the 'wildcard' function is to get a list of all the C
2024 source files in a directory, like this:
2028 We can change the list of C source files into a list of object files
2029 by replacing the '.c' suffix with '.o' in the result, like this:
2031 $(patsubst %.c,%.o,$(wildcard *.c))
2033 (Here we have used another function, 'patsubst'. *Note Functions for
2034 String Substitution and Analysis: Text Functions.)
2036 Thus, a makefile to compile all C source files in the directory and
2037 then link them together could be written as follows:
2039 objects := $(patsubst %.c,%.o,$(wildcard *.c))
2042 cc -o foo $(objects)
2044 (This takes advantage of the implicit rule for compiling C programs, so
2045 there is no need to write explicit rules for compiling the files. *Note
2046 The Two Flavors of Variables: Flavors, for an explanation of ':=', which
2047 is a variant of '='.)
2050 File: make.info, Node: Directory Search, Next: Phony Targets, Prev: Wildcards, Up: Rules
2052 4.5 Searching Directories for Prerequisites
2053 ===========================================
2055 For large systems, it is often desirable to put sources in a separate
2056 directory from the binaries. The "directory search" features of 'make'
2057 facilitate this by searching several directories automatically to find a
2058 prerequisite. When you redistribute the files among directories, you do
2059 not need to change the individual rules, just the search paths.
2063 * General Search:: Specifying a search path that applies
2064 to every prerequisite.
2065 * Selective Search:: Specifying a search path
2066 for a specified class of names.
2067 * Search Algorithm:: When and how search paths are applied.
2068 * Recipes/Search:: How to write recipes that work together
2070 * Implicit/Search:: How search paths affect implicit rules.
2071 * Libraries/Search:: Directory search for link libraries.
2074 File: make.info, Node: General Search, Next: Selective Search, Prev: Directory Search, Up: Directory Search
2076 4.5.1 'VPATH': Search Path for All Prerequisites
2077 ------------------------------------------------
2079 The value of the 'make' variable 'VPATH' specifies a list of directories
2080 that 'make' should search. Most often, the directories are expected to
2081 contain prerequisite files that are not in the current directory;
2082 however, 'make' uses 'VPATH' as a search list for both prerequisites and
2085 Thus, if a file that is listed as a target or prerequisite does not
2086 exist in the current directory, 'make' searches the directories listed
2087 in 'VPATH' for a file with that name. If a file is found in one of
2088 them, that file may become the prerequisite (see below). Rules may then
2089 specify the names of files in the prerequisite list as if they all
2090 existed in the current directory. *Note Writing Recipes with Directory
2091 Search: Recipes/Search.
2093 In the 'VPATH' variable, directory names are separated by colons or
2094 blanks. The order in which directories are listed is the order followed
2095 by 'make' in its search. (On MS-DOS and MS-Windows, semi-colons are
2096 used as separators of directory names in 'VPATH', since the colon can be
2097 used in the pathname itself, after the drive letter.)
2101 VPATH = src:../headers
2103 specifies a path containing two directories, 'src' and '../headers',
2104 which 'make' searches in that order.
2106 With this value of 'VPATH', the following rule,
2110 is interpreted as if it were written like this:
2114 assuming the file 'foo.c' does not exist in the current directory but is
2115 found in the directory 'src'.
2118 File: make.info, Node: Selective Search, Next: Search Algorithm, Prev: General Search, Up: Directory Search
2120 4.5.2 The 'vpath' Directive
2121 ---------------------------
2123 Similar to the 'VPATH' variable, but more selective, is the 'vpath'
2124 directive (note lower case), which allows you to specify a search path
2125 for a particular class of file names: those that match a particular
2126 pattern. Thus you can supply certain search directories for one class
2127 of file names and other directories (or none) for other file names.
2129 There are three forms of the 'vpath' directive:
2131 'vpath PATTERN DIRECTORIES'
2132 Specify the search path DIRECTORIES for file names that match
2135 The search path, DIRECTORIES, is a list of directories to be
2136 searched, separated by colons (semi-colons on MS-DOS and
2137 MS-Windows) or blanks, just like the search path used in the
2141 Clear out the search path associated with PATTERN.
2145 Clear all search paths previously specified with 'vpath'
2148 A 'vpath' pattern is a string containing a '%' character. The string
2149 must match the file name of a prerequisite that is being searched for,
2150 the '%' character matching any sequence of zero or more characters (as
2151 in pattern rules; *note Defining and Redefining Pattern Rules: Pattern
2152 Rules.). For example, '%.h' matches files that end in '.h'. (If there
2153 is no '%', the pattern must match the prerequisite exactly, which is not
2156 '%' characters in a 'vpath' directive's pattern can be quoted with
2157 preceding backslashes ('\'). Backslashes that would otherwise quote '%'
2158 characters can be quoted with more backslashes. Backslashes that quote
2159 '%' characters or other backslashes are removed from the pattern before
2160 it is compared to file names. Backslashes that are not in danger of
2161 quoting '%' characters go unmolested.
2163 When a prerequisite fails to exist in the current directory, if the
2164 PATTERN in a 'vpath' directive matches the name of the prerequisite
2165 file, then the DIRECTORIES in that directive are searched just like (and
2166 before) the directories in the 'VPATH' variable.
2170 vpath %.h ../headers
2172 tells 'make' to look for any prerequisite whose name ends in '.h' in the
2173 directory '../headers' if the file is not found in the current
2176 If several 'vpath' patterns match the prerequisite file's name, then
2177 'make' processes each matching 'vpath' directive one by one, searching
2178 all the directories mentioned in each directive. 'make' handles
2179 multiple 'vpath' directives in the order in which they appear in the
2180 makefile; multiple directives with the same pattern are independent of
2189 will look for a file ending in '.c' in 'foo', then 'blish', then 'bar',
2195 will look for a file ending in '.c' in 'foo', then 'bar', then 'blish'.
2198 File: make.info, Node: Search Algorithm, Next: Recipes/Search, Prev: Selective Search, Up: Directory Search
2200 4.5.3 How Directory Searches are Performed
2201 ------------------------------------------
2203 When a prerequisite is found through directory search, regardless of
2204 type (general or selective), the pathname located may not be the one
2205 that 'make' actually provides you in the prerequisite list. Sometimes
2206 the path discovered through directory search is thrown away.
2208 The algorithm 'make' uses to decide whether to keep or abandon a path
2209 found via directory search is as follows:
2211 1. If a target file does not exist at the path specified in the
2212 makefile, directory search is performed.
2214 2. If the directory search is successful, that path is kept and this
2215 file is tentatively stored as the target.
2217 3. All prerequisites of this target are examined using this same
2220 4. After processing the prerequisites, the target may or may not need
2223 a. If the target does _not_ need to be rebuilt, the path to the
2224 file found during directory search is used for any
2225 prerequisite lists which contain this target. In short, if
2226 'make' doesn't need to rebuild the target then you use the
2227 path found via directory search.
2229 b. If the target _does_ need to be rebuilt (is out-of-date), the
2230 pathname found during directory search is _thrown away_, and
2231 the target is rebuilt using the file name specified in the
2232 makefile. In short, if 'make' must rebuild, then the target
2233 is rebuilt locally, not in the directory found via directory
2236 This algorithm may seem complex, but in practice it is quite often
2237 exactly what you want.
2239 Other versions of 'make' use a simpler algorithm: if the file does
2240 not exist, and it is found via directory search, then that pathname is
2241 always used whether or not the target needs to be built. Thus, if the
2242 target is rebuilt it is created at the pathname discovered during
2245 If, in fact, this is the behavior you want for some or all of your
2246 directories, you can use the 'GPATH' variable to indicate this to
2249 'GPATH' has the same syntax and format as 'VPATH' (that is, a space-
2250 or colon-delimited list of pathnames). If an out-of-date target is
2251 found by directory search in a directory that also appears in 'GPATH',
2252 then that pathname is not thrown away. The target is rebuilt using the
2256 File: make.info, Node: Recipes/Search, Next: Implicit/Search, Prev: Search Algorithm, Up: Directory Search
2258 4.5.4 Writing Recipes with Directory Search
2259 -------------------------------------------
2261 When a prerequisite is found in another directory through directory
2262 search, this cannot change the recipe of the rule; they will execute as
2263 written. Therefore, you must write the recipe with care so that it will
2264 look for the prerequisite in the directory where 'make' finds it.
2266 This is done with the "automatic variables" such as '$^' (*note
2267 Automatic Variables::). For instance, the value of '$^' is a list of
2268 all the prerequisites of the rule, including the names of the
2269 directories in which they were found, and the value of '$@' is the
2273 cc -c $(CFLAGS) $^ -o $@
2275 (The variable 'CFLAGS' exists so you can specify flags for C compilation
2276 by implicit rules; we use it here for consistency so it will affect all
2277 C compilations uniformly; *note Variables Used by Implicit Rules:
2278 Implicit Variables.)
2280 Often the prerequisites include header files as well, which you do
2281 not want to mention in the recipe. The automatic variable '$<' is just
2282 the first prerequisite:
2284 VPATH = src:../headers
2285 foo.o : foo.c defs.h hack.h
2286 cc -c $(CFLAGS) $< -o $@
2289 File: make.info, Node: Implicit/Search, Next: Libraries/Search, Prev: Recipes/Search, Up: Directory Search
2291 4.5.5 Directory Search and Implicit Rules
2292 -----------------------------------------
2294 The search through the directories specified in 'VPATH' or with 'vpath'
2295 also happens during consideration of implicit rules (*note Using
2296 Implicit Rules: Implicit Rules.).
2298 For example, when a file 'foo.o' has no explicit rule, 'make'
2299 considers implicit rules, such as the built-in rule to compile 'foo.c'
2300 if that file exists. If such a file is lacking in the current
2301 directory, the appropriate directories are searched for it. If 'foo.c'
2302 exists (or is mentioned in the makefile) in any of the directories, the
2303 implicit rule for C compilation is applied.
2305 The recipes of implicit rules normally use automatic variables as a
2306 matter of necessity; consequently they will use the file names found by
2307 directory search with no extra effort.
2310 File: make.info, Node: Libraries/Search, Prev: Implicit/Search, Up: Directory Search
2312 4.5.6 Directory Search for Link Libraries
2313 -----------------------------------------
2315 Directory search applies in a special way to libraries used with the
2316 linker. This special feature comes into play when you write a
2317 prerequisite whose name is of the form '-lNAME'. (You can tell
2318 something strange is going on here because the prerequisite is normally
2319 the name of a file, and the _file name_ of a library generally looks
2320 like 'libNAME.a', not like '-lNAME'.)
2322 When a prerequisite's name has the form '-lNAME', 'make' handles it
2323 specially by searching for the file 'libNAME.so', and, if it is not
2324 found, for the file 'libNAME.a' in the current directory, in directories
2325 specified by matching 'vpath' search paths and the 'VPATH' search path,
2326 and then in the directories '/lib', '/usr/lib', and 'PREFIX/lib'
2327 (normally '/usr/local/lib', but MS-DOS/MS-Windows versions of 'make'
2328 behave as if PREFIX is defined to be the root of the DJGPP installation
2331 For example, if there is a '/usr/lib/libcurses.a' library on your
2332 system (and no '/usr/lib/libcurses.so' file), then
2334 foo : foo.c -lcurses
2337 would cause the command 'cc foo.c /usr/lib/libcurses.a -o foo' to be
2338 executed when 'foo' is older than 'foo.c' or than
2339 '/usr/lib/libcurses.a'.
2341 Although the default set of files to be searched for is 'libNAME.so'
2342 and 'libNAME.a', this is customizable via the '.LIBPATTERNS' variable.
2343 Each word in the value of this variable is a pattern string. When a
2344 prerequisite like '-lNAME' is seen, 'make' will replace the percent in
2345 each pattern in the list with NAME and perform the above directory
2346 searches using each library file name.
2348 The default value for '.LIBPATTERNS' is 'lib%.so lib%.a', which
2349 provides the default behavior described above.
2351 You can turn off link library expansion completely by setting this
2352 variable to an empty value.
2355 File: make.info, Node: Phony Targets, Next: Force Targets, Prev: Directory Search, Up: Rules
2360 A phony target is one that is not really the name of a file; rather it
2361 is just a name for a recipe to be executed when you make an explicit
2362 request. There are two reasons to use a phony target: to avoid a
2363 conflict with a file of the same name, and to improve performance.
2365 If you write a rule whose recipe will not create the target file, the
2366 recipe will be executed every time the target comes up for remaking.
2372 Because the 'rm' command does not create a file named 'clean', probably
2373 no such file will ever exist. Therefore, the 'rm' command will be
2374 executed every time you say 'make clean'.
2376 In this example, the 'clean' target will not work properly if a file
2377 named 'clean' is ever created in this directory. Since it has no
2378 prerequisites, 'clean' would always be considered up to date and its
2379 recipe would not be executed. To avoid this problem you can explicitly
2380 declare the target to be phony by making it a prerequisite of the
2381 special target '.PHONY' (*note Special Built-in Target Names: Special
2382 Targets.) as follows:
2388 Once this is done, 'make clean' will run the recipe regardless of
2389 whether there is a file named 'clean'.
2391 Prerequisites of '.PHONY' are always interpreted as literal target
2392 names, never as patterns (even if they contain '%' characters). To
2393 always rebuild a pattern rule consider using a "force target" (*note
2394 Rules without Recipes or Prerequisites: Force Targets.).
2396 Phony targets are also useful in conjunction with recursive
2397 invocations of 'make' (*note Recursive Use of 'make': Recursion.). In
2398 this situation the makefile will often contain a variable which lists a
2399 number of sub-directories to be built. A simplistic way to handle this
2400 is to define one rule with a recipe that loops over the sub-directories,
2403 SUBDIRS = foo bar baz
2406 for dir in $(SUBDIRS); do \
2410 There are problems with this method, however. First, any error
2411 detected in a sub-make is ignored by this rule, so it will continue to
2412 build the rest of the directories even when one fails. This can be
2413 overcome by adding shell commands to note the error and exit, but then
2414 it will do so even if 'make' is invoked with the '-k' option, which is
2415 unfortunate. Second, and perhaps more importantly, you cannot take full
2416 advantage of 'make''s ability to build targets in parallel (*note
2417 Parallel Execution: Parallel.), since there is only one rule. Each
2418 individual makefile's targets will be built in parallel, but only one
2419 sub-directory will be built at a time.
2421 By declaring the sub-directories as '.PHONY' targets (you must do
2422 this as the sub-directory obviously always exists; otherwise it won't be
2423 built) you can remove these problems:
2425 SUBDIRS = foo bar baz
2427 .PHONY: subdirs $(SUBDIRS)
2436 Here we've also declared that the 'foo' sub-directory cannot be built
2437 until after the 'baz' sub-directory is complete; this kind of
2438 relationship declaration is particularly important when attempting
2441 The implicit rule search (*note Implicit Rules::) is skipped for
2442 '.PHONY' targets. This is why declaring a target as '.PHONY' is good
2443 for performance, even if you are not worried about the actual file
2446 A phony target should not be a prerequisite of a real target file; if
2447 it is, its recipe will be run every time 'make' considers that file. As
2448 long as a phony target is never a prerequisite of a real target, the
2449 phony target recipe will be executed only when the phony target is a
2450 specified goal (*note Arguments to Specify the Goals: Goals.).
2452 You should not declare an included makefile as phony. Phony targets
2453 are not intended to represent real files, and because the target is
2454 always considered out of date make will always rebuild it then
2455 re-execute itself (*note How Makefiles Are Remade: Remaking Makefiles.).
2456 To avoid this, 'make' will not re-execute itself if an included file
2457 marked as phony is re-built.
2459 Phony targets can have prerequisites. When one directory contains
2460 multiple programs, it is most convenient to describe all of the programs
2461 in one makefile './Makefile'. Since the target remade by default will
2462 be the first one in the makefile, it is common to make this a phony
2463 target named 'all' and give it, as prerequisites, all the individual
2464 programs. For example:
2466 all : prog1 prog2 prog3
2469 prog1 : prog1.o utils.o
2470 cc -o prog1 prog1.o utils.o
2475 prog3 : prog3.o sort.o utils.o
2476 cc -o prog3 prog3.o sort.o utils.o
2478 Now you can say just 'make' to remake all three programs, or specify as
2479 arguments the ones to remake (as in 'make prog1 prog3'). Phoniness is
2480 not inherited: the prerequisites of a phony target are not themselves
2481 phony, unless explicitly declared to be so.
2483 When one phony target is a prerequisite of another, it serves as a
2484 subroutine of the other. For example, here 'make cleanall' will delete
2485 the object files, the difference files, and the file 'program':
2487 .PHONY: cleanall cleanobj cleandiff
2489 cleanall : cleanobj cleandiff
2499 File: make.info, Node: Force Targets, Next: Empty Targets, Prev: Phony Targets, Up: Rules
2501 4.7 Rules without Recipes or Prerequisites
2502 ==========================================
2504 If a rule has no prerequisites or recipe, and the target of the rule is
2505 a nonexistent file, then 'make' imagines this target to have been
2506 updated whenever its rule is run. This implies that all targets
2507 depending on this one will always have their recipe run.
2509 An example will illustrate this:
2515 Here the target 'FORCE' satisfies the special conditions, so the
2516 target 'clean' that depends on it is forced to run its recipe. There is
2517 nothing special about the name 'FORCE', but that is one name commonly
2520 As you can see, using 'FORCE' this way has the same results as using
2523 Using '.PHONY' is more explicit and more efficient. However, other
2524 versions of 'make' do not support '.PHONY'; thus 'FORCE' appears in many
2525 makefiles. *Note Phony Targets::.
2528 File: make.info, Node: Empty Targets, Next: Special Targets, Prev: Force Targets, Up: Rules
2530 4.8 Empty Target Files to Record Events
2531 =======================================
2533 The "empty target" is a variant of the phony target; it is used to hold
2534 recipes for an action that you request explicitly from time to time.
2535 Unlike a phony target, this target file can really exist; but the file's
2536 contents do not matter, and usually are empty.
2538 The purpose of the empty target file is to record, with its
2539 last-modification time, when the rule's recipe was last executed. It
2540 does so because one of the commands in the recipe is a 'touch' command
2541 to update the target file.
2543 The empty target file should have some prerequisites (otherwise it
2544 doesn't make sense). When you ask to remake the empty target, the
2545 recipe is executed if any prerequisite is more recent than the target;
2546 in other words, if a prerequisite has changed since the last time you
2547 remade the target. Here is an example:
2553 With this rule, 'make print' will execute the 'lpr' command if either
2554 source file has changed since the last 'make print'. The automatic
2555 variable '$?' is used to print only those files that have changed (*note
2556 Automatic Variables::).
2559 File: make.info, Node: Special Targets, Next: Multiple Targets, Prev: Empty Targets, Up: Rules
2561 4.9 Special Built-in Target Names
2562 =================================
2564 Certain names have special meanings if they appear as targets.
2568 The prerequisites of the special target '.PHONY' are considered to
2569 be phony targets. When it is time to consider such a target,
2570 'make' will run its recipe unconditionally, regardless of whether a
2571 file with that name exists or what its last-modification time is.
2572 *Note Phony Targets: Phony Targets.
2576 The prerequisites of the special target '.SUFFIXES' are the list of
2577 suffixes to be used in checking for suffix rules. *Note
2578 Old-Fashioned Suffix Rules: Suffix Rules.
2582 The recipe specified for '.DEFAULT' is used for any target for
2583 which no rules are found (either explicit rules or implicit rules).
2584 *Note Last Resort::. If a '.DEFAULT' recipe is specified, every
2585 file mentioned as a prerequisite, but not as a target in a rule,
2586 will have that recipe executed on its behalf. *Note Implicit Rule
2587 Search Algorithm: Implicit Rule Search.
2591 The targets which '.PRECIOUS' depends on are given the following
2592 special treatment: if 'make' is killed or interrupted during the
2593 execution of their recipes, the target is not deleted. *Note
2594 Interrupting or Killing 'make': Interrupts. Also, if the target is
2595 an intermediate file, it will not be deleted after it is no longer
2596 needed, as is normally done. *Note Chains of Implicit Rules:
2597 Chained Rules. In this latter respect it overlaps with the
2598 '.SECONDARY' special target.
2600 You can also list the target pattern of an implicit rule (such as
2601 '%.o') as a prerequisite file of the special target '.PRECIOUS' to
2602 preserve intermediate files created by rules whose target patterns
2603 match that file's name.
2607 The targets which '.INTERMEDIATE' depends on are treated as
2608 intermediate files. *Note Chains of Implicit Rules: Chained Rules.
2609 '.INTERMEDIATE' with no prerequisites has no effect.
2613 Prerequisites of the special target '.NOTINTERMEDIATE' are never
2614 considered intermediate files. *Note Chains of Implicit Rules:
2615 Chained Rules. '.NOTINTERMEDIATE' with no prerequisites causes all
2616 targets to be treated as not intermediate.
2618 If the prerequisite is a target pattern then targets that are built
2619 using that pattern rule are not considered intermediate.
2623 The targets which '.SECONDARY' depends on are treated as
2624 intermediate files, except that they are never automatically
2625 deleted. *Note Chains of Implicit Rules: Chained Rules.
2627 '.SECONDARY' can be used to avoid redundant rebuilds in some
2628 unusual situations. For example:
2630 hello.bin: hello.o bye.o
2636 .SECONDARY: hello.o bye.o
2638 Suppose 'hello.bin' is up to date in regards to the source files,
2639 _but_ the object file 'hello.o' is missing. Without '.SECONDARY'
2640 make would rebuild 'hello.o' then rebuild 'hello.bin' even though
2641 the source files had not changed. By declaring 'hello.o' as
2642 '.SECONDARY' 'make' will not need to rebuild it and won't need to
2643 rebuild 'hello.bin' either. Of course, of one of the source files
2644 _were_ updated then all object files would be rebuilt so that the
2645 creation of 'hello.bin' could succeed.
2647 '.SECONDARY' with no prerequisites causes all targets to be treated
2648 as secondary (i.e., no target is removed because it is considered
2653 If '.SECONDEXPANSION' is mentioned as a target anywhere in the
2654 makefile, then all prerequisite lists defined _after_ it appears
2655 will be expanded a second time after all makefiles have been read
2656 in. *Note Secondary Expansion: Secondary Expansion.
2660 If '.DELETE_ON_ERROR' is mentioned as a target anywhere in the
2661 makefile, then 'make' will delete the target of a rule if it has
2662 changed and its recipe exits with a nonzero exit status, just as it
2663 does when it receives a signal. *Note Errors in Recipes: Errors.
2667 If you specify prerequisites for '.IGNORE', then 'make' will ignore
2668 errors in execution of the recipe for those particular files. The
2669 recipe for '.IGNORE' (if any) is ignored.
2671 If mentioned as a target with no prerequisites, '.IGNORE' says to
2672 ignore errors in execution of recipes for all files. This usage of
2673 '.IGNORE' is supported only for historical compatibility. Since
2674 this affects every recipe in the makefile, it is not very useful;
2675 we recommend you use the more selective ways to ignore errors in
2676 specific recipes. *Note Errors in Recipes: Errors.
2678 '.LOW_RESOLUTION_TIME'
2680 If you specify prerequisites for '.LOW_RESOLUTION_TIME', 'make'
2681 assumes that these files are created by commands that generate low
2682 resolution time stamps. The recipe for the '.LOW_RESOLUTION_TIME'
2685 The high resolution file time stamps of many modern file systems
2686 lessen the chance of 'make' incorrectly concluding that a file is
2687 up to date. Unfortunately, some hosts do not provide a way to set
2688 a high resolution file time stamp, so commands like 'cp -p' that
2689 explicitly set a file's time stamp must discard its sub-second
2690 part. If a file is created by such a command, you should list it
2691 as a prerequisite of '.LOW_RESOLUTION_TIME' so that 'make' does not
2692 mistakenly conclude that the file is out of date. For example:
2694 .LOW_RESOLUTION_TIME: dst
2698 Since 'cp -p' discards the sub-second part of 'src''s time stamp,
2699 'dst' is typically slightly older than 'src' even when it is up to
2700 date. The '.LOW_RESOLUTION_TIME' line causes 'make' to consider
2701 'dst' to be up to date if its time stamp is at the start of the
2702 same second that 'src''s time stamp is in.
2704 Due to a limitation of the archive format, archive member time
2705 stamps are always low resolution. You need not list archive
2706 members as prerequisites of '.LOW_RESOLUTION_TIME', as 'make' does
2711 If you specify prerequisites for '.SILENT', then 'make' will not
2712 print the recipe used to remake those particular files before
2713 executing them. The recipe for '.SILENT' is ignored.
2715 If mentioned as a target with no prerequisites, '.SILENT' says not
2716 to print any recipes before executing them. You may also use more
2717 selective ways to silence specific recipe command lines. *Note
2718 Recipe Echoing: Echoing. If you want to silence all recipes for a
2719 particular run of 'make', use the '-s' or '--silent' option (*note
2722 '.EXPORT_ALL_VARIABLES'
2724 Simply by being mentioned as a target, this tells 'make' to export
2725 all variables to child processes by default. This is an
2726 alternative to using 'export' with no arguments. *Note
2727 Communicating Variables to a Sub-'make': Variables/Recursion.
2731 If '.NOTPARALLEL' is mentioned as a target with no prerequisites,
2732 all targets in this invocation of 'make' will be run serially, even
2733 if the '-j' option is given. Any recursively invoked 'make'
2734 command will still run recipes in parallel (unless its makefile
2735 also contains this target).
2737 If '.NOTPARALLEL' has targets as prerequisites, then all the
2738 prerequisites of those targets will be run serially. This
2739 implicitly adds a '.WAIT' between each prerequisite of the listed
2740 targets. *Note Disabling Parallel Execution: Parallel Disable.
2744 If '.ONESHELL' is mentioned as a target, then when a target is
2745 built all lines of the recipe will be given to a single invocation
2746 of the shell rather than each line being invoked separately. *Note
2747 Recipe Execution: Execution.
2751 If '.POSIX' is mentioned as a target, then the makefile will be
2752 parsed and run in POSIX-conforming mode. This does _not_ mean that
2753 only POSIX-conforming makefiles will be accepted: all advanced GNU
2754 'make' features are still available. Rather, this target causes
2755 'make' to behave as required by POSIX in those areas where 'make''s
2756 default behavior differs.
2758 In particular, if this target is mentioned then recipes will be
2759 invoked as if the shell had been passed the '-e' flag: the first
2760 failing command in a recipe will cause the recipe to fail
2763 Any defined implicit rule suffix also counts as a special target if
2764 it appears as a target, and so does the concatenation of two suffixes,
2765 such as '.c.o'. These targets are suffix rules, an obsolete way of
2766 defining implicit rules (but a way still widely used). In principle,
2767 any target name could be special in this way if you break it in two and
2768 add both pieces to the suffix list. In practice, suffixes normally
2769 begin with '.', so these special target names also begin with '.'.
2770 *Note Old-Fashioned Suffix Rules: Suffix Rules.
2773 File: make.info, Node: Multiple Targets, Next: Multiple Rules, Prev: Special Targets, Up: Rules
2775 4.10 Multiple Targets in a Rule
2776 ===============================
2778 When an explicit rule has multiple targets they can be treated in one of
2779 two possible ways: as independent targets or as grouped targets. The
2780 manner in which they are treated is determined by the separator that
2781 appears after the list of targets.
2783 Rules with Independent Targets
2784 ..............................
2786 Rules that use the standard target separator, ':', define independent
2787 targets. This is equivalent to writing the same rule once for each
2788 target, with duplicated prerequisites and recipes. Typically, the
2789 recipe would use automatic variables such as '$@' to specify which
2790 target is being built.
2792 Rules with independent targets are useful in two cases:
2794 * You want just prerequisites, no recipe. For example:
2796 kbd.o command.o files.o: command.h
2798 gives an additional prerequisite to each of the three object files
2799 mentioned. It is equivalent to writing:
2802 command.o: command.h
2805 * Similar recipes work for all the targets. The automatic variable
2806 '$@' can be used to substitute the particular target to be remade
2807 into the commands (*note Automatic Variables::). For example:
2809 bigoutput littleoutput : text.g
2810 generate text.g -$(subst output,,$@) > $@
2815 generate text.g -big > bigoutput
2816 littleoutput : text.g
2817 generate text.g -little > littleoutput
2819 Here we assume the hypothetical program 'generate' makes two types
2820 of output, one if given '-big' and one if given '-little'. *Note
2821 Functions for String Substitution and Analysis: Text Functions, for
2822 an explanation of the 'subst' function.
2824 Suppose you would like to vary the prerequisites according to the
2825 target, much as the variable '$@' allows you to vary the recipe. You
2826 cannot do this with multiple targets in an ordinary rule, but you can do
2827 it with a "static pattern rule". *Note Static Pattern Rules: Static
2830 Rules with Grouped Targets
2831 ..........................
2833 If instead of independent targets you have a recipe that generates
2834 multiple files from a single invocation, you can express that
2835 relationship by declaring your rule to use _grouped targets_. A grouped
2836 target rule uses the separator '&:' (the '&' here is used to imply
2839 When 'make' builds any one of the grouped targets, it understands
2840 that all the other targets in the group are also updated as a result of
2841 the invocation of the recipe. Furthermore, if only some of the grouped
2842 targets are out of date or missing 'make' will realize that running the
2843 recipe will update all of the targets. Finally, if any of the grouped
2844 targets are out of date, all the grouped targets are considered out of
2847 As an example, this rule defines a grouped target:
2849 foo bar biz &: baz boz
2854 During the execution of a grouped target's recipe, the automatic
2855 variable '$@' is set to the name of the particular target in the group
2856 which triggered the rule. Caution must be used if relying on this
2857 variable in the recipe of a grouped target rule.
2859 Unlike independent targets, a grouped target rule _must_ include a
2860 recipe. However, targets that are members of a grouped target may also
2861 appear in independent target rule definitions that do not have recipes.
2863 Each target may have only one recipe associated with it. If a
2864 grouped target appears in either an independent target rule or in
2865 another grouped target rule with a recipe, you will get a warning and
2866 the latter recipe will replace the former recipe. Additionally the
2867 target will be removed from the previous group and appear only in the
2870 If you would like a target to appear in multiple groups, then you
2871 must use the double-colon grouped target separator, '&::' when declaring
2872 all of the groups containing that target. Grouped double-colon targets
2873 are each considered independently, and each grouped double-colon rule's
2874 recipe is executed at most once, if at least one of its multiple targets
2878 File: make.info, Node: Multiple Rules, Next: Static Pattern, Prev: Multiple Targets, Up: Rules
2880 4.11 Multiple Rules for One Target
2881 ==================================
2883 One file can be the target of several rules. All the prerequisites
2884 mentioned in all the rules are merged into one list of prerequisites for
2885 the target. If the target is older than any prerequisite from any rule,
2886 the recipe is executed.
2888 There can only be one recipe to be executed for a file. If more than
2889 one rule gives a recipe for the same file, 'make' uses the last one
2890 given and prints an error message. (As a special case, if the file's
2891 name begins with a dot, no error message is printed. This odd behavior
2892 is only for compatibility with other implementations of 'make'... you
2893 should avoid using it). Occasionally it is useful to have the same
2894 target invoke multiple recipes which are defined in different parts of
2895 your makefile; you can use "double-colon rules" (*note Double-Colon::)
2898 An extra rule with just prerequisites can be used to give a few extra
2899 prerequisites to many files at once. For example, makefiles often have
2900 a variable, such as 'objects', containing a list of all the compiler
2901 output files in the system being made. An easy way to say that all of
2902 them must be recompiled if 'config.h' changes is to write the following:
2904 objects = foo.o bar.o
2906 bar.o : defs.h test.h
2907 $(objects) : config.h
2909 This could be inserted or taken out without changing the rules that
2910 really specify how to make the object files, making it a convenient form
2911 to use if you wish to add the additional prerequisite intermittently.
2913 Another wrinkle is that the additional prerequisites could be
2914 specified with a variable that you set with a command line argument to
2915 'make' (*note Overriding Variables: Overriding.). For example,
2918 $(objects) : $(extradeps)
2920 means that the command 'make extradeps=foo.h' will consider 'foo.h' as a
2921 prerequisite of each object file, but plain 'make' will not.
2923 If none of the explicit rules for a target has a recipe, then 'make'
2924 searches for an applicable implicit rule to find one *note Using
2925 Implicit Rules: Implicit Rules.).
2928 File: make.info, Node: Static Pattern, Next: Double-Colon, Prev: Multiple Rules, Up: Rules
2930 4.12 Static Pattern Rules
2931 =========================
2933 "Static pattern rules" are rules which specify multiple targets and
2934 construct the prerequisite names for each target based on the target
2935 name. They are more general than ordinary rules with multiple targets
2936 because the targets do not have to have identical prerequisites. Their
2937 prerequisites must be _analogous_, but not necessarily _identical_.
2941 * Static Usage:: The syntax of static pattern rules.
2942 * Static versus Implicit:: When are they better than implicit rules?
2945 File: make.info, Node: Static Usage, Next: Static versus Implicit, Prev: Static Pattern, Up: Static Pattern
2947 4.12.1 Syntax of Static Pattern Rules
2948 -------------------------------------
2950 Here is the syntax of a static pattern rule:
2952 TARGETS ...: TARGET-PATTERN: PREREQ-PATTERNS ...
2956 The TARGETS list specifies the targets that the rule applies to. The
2957 targets can contain wildcard characters, just like the targets of
2958 ordinary rules (*note Using Wildcard Characters in File Names:
2961 The TARGET-PATTERN and PREREQ-PATTERNS say how to compute the
2962 prerequisites of each target. Each target is matched against the
2963 TARGET-PATTERN to extract a part of the target name, called the "stem".
2964 This stem is substituted into each of the PREREQ-PATTERNS to make the
2965 prerequisite names (one from each PREREQ-PATTERN).
2967 Each pattern normally contains the character '%' just once. When the
2968 TARGET-PATTERN matches a target, the '%' can match any part of the
2969 target name; this part is called the "stem". The rest of the pattern
2970 must match exactly. For example, the target 'foo.o' matches the pattern
2971 '%.o', with 'foo' as the stem. The targets 'foo.c' and 'foo.out' do not
2974 The prerequisite names for each target are made by substituting the
2975 stem for the '%' in each prerequisite pattern. For example, if one
2976 prerequisite pattern is '%.c', then substitution of the stem 'foo' gives
2977 the prerequisite name 'foo.c'. It is legitimate to write a prerequisite
2978 pattern that does not contain '%'; then this prerequisite is the same
2981 '%' characters in pattern rules can be quoted with preceding
2982 backslashes ('\'). Backslashes that would otherwise quote '%'
2983 characters can be quoted with more backslashes. Backslashes that quote
2984 '%' characters or other backslashes are removed from the pattern before
2985 it is compared to file names or has a stem substituted into it.
2986 Backslashes that are not in danger of quoting '%' characters go
2987 unmolested. For example, the pattern 'the\%weird\\%pattern\\' has
2988 'the%weird\' preceding the operative '%' character, and 'pattern\\'
2989 following it. The final two backslashes are left alone because they
2990 cannot affect any '%' character.
2992 Here is an example, which compiles each of 'foo.o' and 'bar.o' from
2993 the corresponding '.c' file:
2995 objects = foo.o bar.o
2999 $(objects): %.o: %.c
3000 $(CC) -c $(CFLAGS) $< -o $@
3002 Here '$<' is the automatic variable that holds the name of the
3003 prerequisite and '$@' is the automatic variable that holds the name of
3004 the target; see *note Automatic Variables::.
3006 Each target specified must match the target pattern; a warning is
3007 issued for each target that does not. If you have a list of files, only
3008 some of which will match the pattern, you can use the 'filter' function
3009 to remove non-matching file names (*note Functions for String
3010 Substitution and Analysis: Text Functions.):
3012 files = foo.elc bar.o lose.o
3014 $(filter %.o,$(files)): %.o: %.c
3015 $(CC) -c $(CFLAGS) $< -o $@
3016 $(filter %.elc,$(files)): %.elc: %.el
3017 emacs -f batch-byte-compile $<
3019 In this example the result of '$(filter %.o,$(files))' is 'bar.o
3020 lose.o', and the first static pattern rule causes each of these object
3021 files to be updated by compiling the corresponding C source file. The
3022 result of '$(filter %.elc,$(files))' is 'foo.elc', so that file is made
3025 Another example shows how to use '$*' in static pattern rules:
3027 bigoutput littleoutput : %output : text.g
3028 generate text.g -$* > $@
3030 When the 'generate' command is run, '$*' will expand to the stem, either
3034 File: make.info, Node: Static versus Implicit, Prev: Static Usage, Up: Static Pattern
3036 4.12.2 Static Pattern Rules versus Implicit Rules
3037 -------------------------------------------------
3039 A static pattern rule has much in common with an implicit rule defined
3040 as a pattern rule (*note Defining and Redefining Pattern Rules: Pattern
3041 Rules.). Both have a pattern for the target and patterns for
3042 constructing the names of prerequisites. The difference is in how
3043 'make' decides _when_ the rule applies.
3045 An implicit rule _can_ apply to any target that matches its pattern,
3046 but it _does_ apply only when the target has no recipe otherwise
3047 specified, and only when the prerequisites can be found. If more than
3048 one implicit rule appears applicable, only one applies; the choice
3049 depends on the order of rules.
3051 By contrast, a static pattern rule applies to the precise list of
3052 targets that you specify in the rule. It cannot apply to any other
3053 target and it invariably does apply to each of the targets specified.
3054 If two conflicting rules apply, and both have recipes, that's an error.
3056 The static pattern rule can be better than an implicit rule for these
3059 * You may wish to override the usual implicit rule for a few files
3060 whose names cannot be categorized syntactically but can be given in
3063 * If you cannot be sure of the precise contents of the directories
3064 you are using, you may not be sure which other irrelevant files
3065 might lead 'make' to use the wrong implicit rule. The choice might
3066 depend on the order in which the implicit rule search is done.
3067 With static pattern rules, there is no uncertainty: each rule
3068 applies to precisely the targets specified.
3071 File: make.info, Node: Double-Colon, Next: Automatic Prerequisites, Prev: Static Pattern, Up: Rules
3073 4.13 Double-Colon Rules
3074 =======================
3076 "Double-colon" rules are explicit rules written with '::' instead of ':'
3077 after the target names. They are handled differently from ordinary
3078 rules when the same target appears in more than one rule. Pattern rules
3079 with double-colons have an entirely different meaning (*note
3080 Match-Anything Rules::).
3082 When a target appears in multiple rules, all the rules must be the
3083 same type: all ordinary, or all double-colon. If they are double-colon,
3084 each of them is independent of the others. Each double-colon rule's
3085 recipe is executed if the target is older than any prerequisites of that
3086 rule. If there are no prerequisites for that rule, its recipe is always
3087 executed (even if the target already exists). This can result in
3088 executing none, any, or all of the double-colon rules.
3090 Double-colon rules with the same target are in fact completely
3091 separate from one another. Each double-colon rule is processed
3092 individually, just as rules with different targets are processed.
3094 The double-colon rules for a target are executed in the order they
3095 appear in the makefile. However, the cases where double-colon rules
3096 really make sense are those where the order of executing the recipes
3099 Double-colon rules are somewhat obscure and not often very useful;
3100 they provide a mechanism for cases in which the method used to update a
3101 target differs depending on which prerequisite files caused the update,
3102 and such cases are rare.
3104 Each double-colon rule should specify a recipe; if it does not, an
3105 implicit rule will be used if one applies. *Note Using Implicit Rules:
3109 File: make.info, Node: Automatic Prerequisites, Prev: Double-Colon, Up: Rules
3111 4.14 Generating Prerequisites Automatically
3112 ===========================================
3114 In the makefile for a program, many of the rules you need to write often
3115 say only that some object file depends on some header file. For
3116 example, if 'main.c' uses 'defs.h' via an '#include', you would write:
3120 You need this rule so that 'make' knows that it must remake 'main.o'
3121 whenever 'defs.h' changes. You can see that for a large program you
3122 would have to write dozens of such rules in your makefile. And, you
3123 must always be very careful to update the makefile every time you add or
3124 remove an '#include'.
3126 To avoid this hassle, most modern C compilers can write these rules
3127 for you, by looking at the '#include' lines in the source files.
3128 Usually this is done with the '-M' option to the compiler. For example,
3133 generates the output:
3135 main.o : main.c defs.h
3137 Thus you no longer have to write all those rules yourself. The compiler
3140 Note that such a rule constitutes mentioning 'main.o' in a makefile,
3141 so it can never be considered an intermediate file by implicit rule
3142 search. This means that 'make' won't ever remove the file after using
3143 it; *note Chains of Implicit Rules: Chained Rules.
3145 With old 'make' programs, it was traditional practice to use this
3146 compiler feature to generate prerequisites on demand with a command like
3147 'make depend'. That command would create a file 'depend' containing all
3148 the automatically-generated prerequisites; then the makefile could use
3149 'include' to read them in (*note Include::).
3151 In GNU 'make', the feature of remaking makefiles makes this practice
3152 obsolete--you need never tell 'make' explicitly to regenerate the
3153 prerequisites, because it always regenerates any makefile that is out of
3154 date. *Note Remaking Makefiles::.
3156 The practice we recommend for automatic prerequisite generation is to
3157 have one makefile corresponding to each source file. For each source
3158 file 'NAME.c' there is a makefile 'NAME.d' which lists what files the
3159 object file 'NAME.o' depends on. That way only the source files that
3160 have changed need to be rescanned to produce the new prerequisites.
3162 Here is the pattern rule to generate a file of prerequisites (i.e., a
3163 makefile) called 'NAME.d' from a C source file called 'NAME.c':
3166 @set -e; rm -f $@; \
3167 $(CC) -M $(CPPFLAGS) $< > $@.$$$$; \
3168 sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
3171 *Note Pattern Rules::, for information on defining pattern rules. The
3172 '-e' flag to the shell causes it to exit immediately if the '$(CC)'
3173 command (or any other command) fails (exits with a nonzero status).
3175 With the GNU C compiler, you may wish to use the '-MM' flag instead
3176 of '-M'. This omits prerequisites on system header files. *Note
3177 Options Controlling the Preprocessor: (gcc)Preprocessor Options, for
3180 The purpose of the 'sed' command is to translate (for example):
3182 main.o : main.c defs.h
3186 main.o main.d : main.c defs.h
3188 This makes each '.d' file depend on all the source and header files that
3189 the corresponding '.o' file depends on. 'make' then knows it must
3190 regenerate the prerequisites whenever any of the source or header files
3193 Once you've defined the rule to remake the '.d' files, you then use
3194 the 'include' directive to read them all in. *Note Include::. For
3197 sources = foo.c bar.c
3199 include $(sources:.c=.d)
3201 (This example uses a substitution variable reference to translate the
3202 list of source files 'foo.c bar.c' into a list of prerequisite
3203 makefiles, 'foo.d bar.d'. *Note Substitution Refs::, for full
3204 information on substitution references.) Since the '.d' files are
3205 makefiles like any others, 'make' will remake them as necessary with no
3206 further work from you. *Note Remaking Makefiles::.
3208 Note that the '.d' files contain target definitions; you should be
3209 sure to place the 'include' directive _after_ the first, default goal in
3210 your makefiles or run the risk of having a random object file become the
3211 default goal. *Note How Make Works::.
3214 File: make.info, Node: Recipes, Next: Using Variables, Prev: Rules, Up: Top
3216 5 Writing Recipes in Rules
3217 **************************
3219 The recipe of a rule consists of one or more shell command lines to be
3220 executed, one at a time, in the order they appear. Typically, the
3221 result of executing these commands is that the target of the rule is
3224 Users use many different shell programs, but recipes in makefiles are
3225 always interpreted by '/bin/sh' unless the makefile specifies otherwise.
3226 *Note Recipe Execution: Execution.
3230 * Recipe Syntax:: Recipe syntax features and pitfalls.
3231 * Echoing:: How to control when recipes are echoed.
3232 * Execution:: How recipes are executed.
3233 * Parallel:: How recipes can be executed in parallel.
3234 * Errors:: What happens after a recipe execution error.
3235 * Interrupts:: What happens when a recipe is interrupted.
3236 * Recursion:: Invoking 'make' from makefiles.
3237 * Canned Recipes:: Defining canned recipes.
3238 * Empty Recipes:: Defining useful, do-nothing recipes.
3241 File: make.info, Node: Recipe Syntax, Next: Echoing, Prev: Recipes, Up: Recipes
3246 Makefiles have the unusual property that there are really two distinct
3247 syntaxes in one file. Most of the makefile uses 'make' syntax (*note
3248 Writing Makefiles: Makefiles.). However, recipes are meant to be
3249 interpreted by the shell and so they are written using shell syntax.
3250 The 'make' program does not try to understand shell syntax: it performs
3251 only a very few specific translations on the content of the recipe
3252 before handing it to the shell.
3254 Each line in the recipe must start with a tab (or the first character
3255 in the value of the '.RECIPEPREFIX' variable; *note Special
3256 Variables::), except that the first recipe line may be attached to the
3257 target-and-prerequisites line with a semicolon in between. _Any_ line
3258 in the makefile that begins with a tab and appears in a "rule context"
3259 (that is, after a rule has been started until another rule or variable
3260 definition) will be considered part of a recipe for that rule. Blank
3261 lines and lines of just comments may appear among the recipe lines; they
3264 Some consequences of these rules include:
3266 * A blank line that begins with a tab is not blank: it's an empty
3267 recipe (*note Empty Recipes::).
3269 * A comment in a recipe is not a 'make' comment; it will be passed to
3270 the shell as-is. Whether the shell treats it as a comment or not
3271 depends on your shell.
3273 * A variable definition in a "rule context" which is indented by a
3274 tab as the first character on the line, will be considered part of
3275 a recipe, not a 'make' variable definition, and passed to the
3278 * A conditional expression ('ifdef', 'ifeq', etc. *note Syntax of
3279 Conditionals: Conditional Syntax.) in a "rule context" which is
3280 indented by a tab as the first character on the line, will be
3281 considered part of a recipe and be passed to the shell.
3285 * Splitting Recipe Lines:: Breaking long recipe lines for readability.
3286 * Variables in Recipes:: Using 'make' variables in recipes.
3289 File: make.info, Node: Splitting Recipe Lines, Next: Variables in Recipes, Prev: Recipe Syntax, Up: Recipe Syntax
3291 5.1.1 Splitting Recipe Lines
3292 ----------------------------
3294 One of the few ways in which 'make' does interpret recipes is checking
3295 for a backslash just before the newline. As in normal makefile syntax,
3296 a single logical recipe line can be split into multiple physical lines
3297 in the makefile by placing a backslash before each newline. A sequence
3298 of lines like this is considered a single recipe line, and one instance
3299 of the shell will be invoked to run it.
3301 However, in contrast to how they are treated in other places in a
3302 makefile (*note Splitting Long Lines: Splitting Lines.),
3303 backslash/newline pairs are _not_ removed from the recipe. Both the
3304 backslash and the newline characters are preserved and passed to the
3305 shell. How the backslash/newline is interpreted depends on your shell.
3306 If the first character of the next line after the backslash/newline is
3307 the recipe prefix character (a tab by default; *note Special
3308 Variables::), then that character (and only that character) is removed.
3309 Whitespace is never added to the recipe.
3311 For example, the recipe for the all target in this makefile:
3323 consists of four separate shell commands where the output is:
3330 As a more complex example, this makefile:
3332 all : ; @echo 'hello \
3333 world' ; echo "hello \
3336 will invoke one shell with a command of:
3339 world' ; echo "hello \
3342 which, according to shell quoting rules, will yield the following
3349 Notice how the backslash/newline pair was removed inside the string
3350 quoted with double quotes ('"..."'), but not from the string quoted with
3351 single quotes (''...''). This is the way the default shell ('/bin/sh')
3352 handles backslash/newline pairs. If you specify a different shell in
3353 your makefiles it may treat them differently.
3355 Sometimes you want to split a long line inside of single quotes, but
3356 you don't want the backslash/newline to appear in the quoted content.
3357 This is often the case when passing scripts to languages such as Perl,
3358 where extraneous backslashes inside the script can change its meaning or
3359 even be a syntax error. One simple way of handling this is to place the
3360 quoted string, or even the entire command, into a 'make' variable then
3361 use the variable in the recipe. In this situation the newline quoting
3362 rules for makefiles will be used, and the backslash/newline will be
3363 removed. If we rewrite our example above using this method:
3368 all : ; @echo $(HELLO)
3370 we will get output like this:
3374 If you like, you can also use target-specific variables (*note
3375 Target-specific Variable Values: Target-specific.) to obtain a tighter
3376 correspondence between the variable and the recipe that uses it.
3379 File: make.info, Node: Variables in Recipes, Prev: Splitting Recipe Lines, Up: Recipe Syntax
3381 5.1.2 Using Variables in Recipes
3382 --------------------------------
3384 The other way in which 'make' processes recipes is by expanding any
3385 variable references in them (*note Basics of Variable References:
3386 Reference.). This occurs after make has finished reading all the
3387 makefiles and the target is determined to be out of date; so, the
3388 recipes for targets which are not rebuilt are never expanded.
3390 Variable and function references in recipes have identical syntax and
3391 semantics to references elsewhere in the makefile. They also have the
3392 same quoting rules: if you want a dollar sign to appear in your recipe,
3393 you must double it ('$$'). For shells like the default shell, that use
3394 dollar signs to introduce variables, it's important to keep clear in
3395 your mind whether the variable you want to reference is a 'make'
3396 variable (use a single dollar sign) or a shell variable (use two dollar
3397 signs). For example:
3399 LIST = one two three
3401 for i in $(LIST); do \
3405 results in the following command being passed to the shell:
3407 for i in one two three; do \
3411 which generates the expected result:
3418 File: make.info, Node: Echoing, Next: Execution, Prev: Recipe Syntax, Up: Recipes
3423 Normally 'make' prints each line of the recipe before it is executed.
3424 We call this "echoing" because it gives the appearance that you are
3425 typing the lines yourself.
3427 When a line starts with '@', the echoing of that line is suppressed.
3428 The '@' is discarded before the line is passed to the shell. Typically
3429 you would use this for a command whose only effect is to print
3430 something, such as an 'echo' command to indicate progress through the
3433 @echo About to make distribution files
3435 When 'make' is given the flag '-n' or '--just-print' it only echoes
3436 most recipes, without executing them. *Note Summary of Options: Options
3437 Summary. In this case even the recipe lines starting with '@' are
3438 printed. This flag is useful for finding out which recipes 'make'
3439 thinks are necessary without actually doing them.
3441 The '-s' or '--silent' flag to 'make' prevents all echoing, as if all
3442 recipes started with '@'. A rule in the makefile for the special target
3443 '.SILENT' without prerequisites has the same effect (*note Special
3444 Built-in Target Names: Special Targets.).
3447 File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Recipes
3449 5.3 Recipe Execution
3450 ====================
3452 When it is time to execute recipes to update a target, they are executed
3453 by invoking a new sub-shell for each line of the recipe, unless the
3454 '.ONESHELL' special target is in effect (*note Using One Shell: One
3455 Shell.) (In practice, 'make' may take shortcuts that do not affect the
3458 *Please note:* this implies that setting shell variables and invoking
3459 shell commands such as 'cd' that set a context local to each process
3460 will not affect the following lines in the recipe.(1) If you want to
3461 use 'cd' to affect the next statement, put both statements in a single
3462 recipe line. Then 'make' will invoke one shell to run the entire line,
3463 and the shell will execute the statements in sequence. For example:
3466 cd $(<D) && gobble $(<F) > ../$@
3468 Here we use the shell AND operator ('&&') so that if the 'cd' command
3469 fails, the script will fail without trying to invoke the 'gobble'
3470 command in the wrong directory, which could cause problems (in this case
3471 it would certainly cause '../foo' to be truncated, at least).
3475 * One Shell:: One shell for all lines in a recipe.
3476 * Choosing the Shell:: How 'make' chooses the shell used
3479 ---------- Footnotes ----------
3481 (1) On MS-DOS, the value of current working directory is *global*, so
3482 changing it _will_ affect the following recipe lines on those systems.
3485 File: make.info, Node: One Shell, Next: Choosing the Shell, Prev: Execution, Up: Execution
3487 5.3.1 Using One Shell
3488 ---------------------
3490 Sometimes you would prefer that all the lines in the recipe be passed to
3491 a single invocation of the shell. There are generally two situations
3492 where this is useful: first, it can improve performance in makefiles
3493 where recipes consist of many command lines, by avoiding extra
3494 processes. Second, you might want newlines to be included in your
3495 recipe command (for example perhaps you are using a very different
3496 interpreter as your 'SHELL'). If the '.ONESHELL' special target appears
3497 anywhere in the makefile then _all_ recipe lines for each target will be
3498 provided to a single invocation of the shell. Newlines between recipe
3499 lines will be preserved. For example:
3504 gobble $(<F) > ../$@
3506 would now work as expected even though the commands are on different
3509 If '.ONESHELL' is provided, then only the first line of the recipe
3510 will be checked for the special prefix characters ('@', '-', and '+').
3511 Subsequent lines will include the special characters in the recipe line
3512 when the 'SHELL' is invoked. If you want your recipe to start with one
3513 of these special characters you'll need to arrange for them to not be
3514 the first characters on the first line, perhaps by adding a comment or
3515 similar. For example, this would be a syntax error in Perl because the
3516 first '@' is removed by make:
3519 SHELL = /usr/bin/perl
3525 However, either of these alternatives would work properly:
3528 SHELL = /usr/bin/perl
3531 # Make sure "@" is not the first character on the first line
3538 SHELL = /usr/bin/perl
3544 As a special feature, if 'SHELL' is determined to be a POSIX-style
3545 shell, the special prefix characters in "internal" recipe lines will be
3546 _removed_ before the recipe is processed. This feature is intended to
3547 allow existing makefiles to add the '.ONESHELL' special target and still
3548 run properly without extensive modifications. Since the special prefix
3549 characters are not legal at the beginning of a line in a POSIX shell
3550 script this is not a loss in functionality. For example, this works as
3556 @gobble $(@F) > ../$@
3558 Even with this special feature, however, makefiles with '.ONESHELL'
3559 will behave differently in ways that could be noticeable. For example,
3560 normally if any line in the recipe fails, that causes the rule to fail
3561 and no more recipe lines are processed. Under '.ONESHELL' a failure of
3562 any but the final recipe line will not be noticed by 'make'. You can
3563 modify '.SHELLFLAGS' to add the '-e' option to the shell which will
3564 cause any failure anywhere in the command line to cause the shell to
3565 fail, but this could itself cause your recipe to behave differently.
3566 Ultimately you may need to harden your recipe lines to allow them to
3567 work with '.ONESHELL'.
3570 File: make.info, Node: Choosing the Shell, Prev: One Shell, Up: Execution
3572 5.3.2 Choosing the Shell
3573 ------------------------
3575 The program used as the shell is taken from the variable 'SHELL'. If
3576 this variable is not set in your makefile, the program '/bin/sh' is used
3577 as the shell. The argument(s) passed to the shell are taken from the
3578 variable '.SHELLFLAGS'. The default value of '.SHELLFLAGS' is '-c'
3579 normally, or '-ec' in POSIX-conforming mode.
3581 Unlike most variables, the variable 'SHELL' is never set from the
3582 environment. This is because the 'SHELL' environment variable is used
3583 to specify your personal choice of shell program for interactive use.
3584 It would be very bad for personal choices like this to affect the
3585 functioning of makefiles. *Note Variables from the Environment:
3588 Furthermore, when you do set 'SHELL' in your makefile that value is
3589 _not_ exported in the environment to recipe lines that 'make' invokes.
3590 Instead, the value inherited from the user's environment, if any, is
3591 exported. You can override this behavior by explicitly exporting
3592 'SHELL' (*note Communicating Variables to a Sub-'make':
3593 Variables/Recursion.), forcing it to be passed in the environment to
3596 However, on MS-DOS and MS-Windows the value of 'SHELL' in the
3597 environment *is* used, since on those systems most users do not set this
3598 variable, and therefore it is most likely set specifically to be used by
3599 'make'. On MS-DOS, if the setting of 'SHELL' is not suitable for
3600 'make', you can set the variable 'MAKESHELL' to the shell that 'make'
3601 should use; if set it will be used as the shell instead of the value of
3604 Choosing a Shell in DOS and Windows
3605 ...................................
3607 Choosing a shell in MS-DOS and MS-Windows is much more complex than on
3610 On MS-DOS, if 'SHELL' is not set, the value of the variable 'COMSPEC'
3611 (which is always set) is used instead.
3613 The processing of lines that set the variable 'SHELL' in Makefiles is
3614 different on MS-DOS. The stock shell, 'command.com', is ridiculously
3615 limited in its functionality and many users of 'make' tend to install a
3616 replacement shell. Therefore, on MS-DOS, 'make' examines the value of
3617 'SHELL', and changes its behavior based on whether it points to a
3618 Unix-style or DOS-style shell. This allows reasonable functionality
3619 even if 'SHELL' points to 'command.com'.
3621 If 'SHELL' points to a Unix-style shell, 'make' on MS-DOS
3622 additionally checks whether that shell can indeed be found; if not, it
3623 ignores the line that sets 'SHELL'. In MS-DOS, GNU 'make' searches for
3624 the shell in the following places:
3626 1. In the precise place pointed to by the value of 'SHELL'. For
3627 example, if the makefile specifies 'SHELL = /bin/sh', 'make' will
3628 look in the directory '/bin' on the current drive.
3630 2. In the current directory.
3632 3. In each of the directories in the 'PATH' variable, in order.
3634 In every directory it examines, 'make' will first look for the
3635 specific file ('sh' in the example above). If this is not found, it
3636 will also look in that directory for that file with one of the known
3637 extensions which identify executable files. For example '.exe', '.com',
3638 '.bat', '.btm', '.sh', and some others.
3640 If any of these attempts is successful, the value of 'SHELL' will be
3641 set to the full pathname of the shell as found. However, if none of
3642 these is found, the value of 'SHELL' will not be changed, and thus the
3643 line that sets it will be effectively ignored. This is so 'make' will
3644 only support features specific to a Unix-style shell if such a shell is
3645 actually installed on the system where 'make' runs.
3647 Note that this extended search for the shell is limited to the cases
3648 where 'SHELL' is set from the Makefile; if it is set in the environment
3649 or command line, you are expected to set it to the full pathname of the
3650 shell, exactly as things are on Unix.
3652 The effect of the above DOS-specific processing is that a Makefile
3653 that contains 'SHELL = /bin/sh' (as many Unix makefiles do), will work
3654 on MS-DOS unaltered if you have e.g. 'sh.exe' installed in some
3655 directory along your 'PATH'.
3658 File: make.info, Node: Parallel, Next: Errors, Prev: Execution, Up: Recipes
3660 5.4 Parallel Execution
3661 ======================
3663 GNU 'make' knows how to execute several recipes at once. Normally,
3664 'make' will execute only one recipe at a time, waiting for it to finish
3665 before executing the next. However, the '-j' or '--jobs' option tells
3666 'make' to execute many recipes simultaneously. You can inhibit
3667 parallelism for some or all targets from within the makefile (*note
3668 Disabling Parallel Execution: Parallel Disable.).
3670 On MS-DOS, the '-j' option has no effect, since that system doesn't
3671 support multi-processing.
3673 If the '-j' option is followed by an integer, this is the number of
3674 recipes to execute at once; this is called the number of "job slots".
3675 If there is nothing looking like an integer after the '-j' option, there
3676 is no limit on the number of job slots. The default number of job slots
3677 is one, which means serial execution (one thing at a time).
3679 Handling recursive 'make' invocations raises issues for parallel
3680 execution. For more information on this, see *note Communicating
3681 Options to a Sub-'make': Options/Recursion.
3683 If a recipe fails (is killed by a signal or exits with a nonzero
3684 status), and errors are not ignored for that recipe (*note Errors in
3685 Recipes: Errors.), the remaining recipe lines to remake the same target
3686 will not be run. If a recipe fails and the '-k' or '--keep-going'
3687 option was not given (*note Summary of Options: Options Summary.),
3688 'make' aborts execution. If make terminates for any reason (including a
3689 signal) with child processes running, it waits for them to finish before
3692 When the system is heavily loaded, you will probably want to run
3693 fewer jobs than when it is lightly loaded. You can use the '-l' option
3694 to tell 'make' to limit the number of jobs to run at once, based on the
3695 load average. The '-l' or '--max-load' option is followed by a
3696 floating-point number. For example,
3700 will not let 'make' start more than one job if the load average is above
3701 2.5. The '-l' option with no following number removes the load limit,
3702 if one was given with a previous '-l' option.
3704 More precisely, when 'make' goes to start up a job, and it already
3705 has at least one job running, it checks the current load average; if it
3706 is not lower than the limit given with '-l', 'make' waits until the load
3707 average goes below that limit, or until all the other jobs finish.
3709 By default, there is no load limit.
3713 * Parallel Disable:: Disabling parallel execution
3714 * Parallel Output:: Handling output during parallel execution
3715 * Parallel Input:: Handling input during parallel execution
3718 File: make.info, Node: Parallel Disable, Next: Parallel Output, Prev: Parallel, Up: Parallel
3720 5.4.1 Disabling Parallel Execution
3721 ----------------------------------
3723 If a makefile completely and accurately defines the dependency
3724 relationships between all of its targets, then 'make' will correctly
3725 build the goals regardless of whether parallel execution is enabled or
3726 not. This is the ideal way to write makefiles.
3728 However, sometimes some or all of the targets in a makefile cannot be
3729 executed in parallel and it's not feasible to add the prerequisites
3730 needed to inform 'make'. In that case the makefile can use various
3731 methods to disable parallel execution.
3733 If the '.NOTPARALLEL' special target with no prerequisites is
3734 specified anywhere then the entire instance of 'make' will be run
3735 serially, regardless of the parallel setting. For example:
3738 one two three: ; @sleep 1; echo $@
3742 Regardless of how 'make' is invoked, the targets 'one', 'two', and
3743 'three' will be run serially.
3745 If the '.NOTPARALLEL' special target has prerequisites, then each of
3746 those prerequisites will be considered a target and all prerequisites of
3747 these targets will be run serially. Note that only when building this
3748 target will the prerequisites be run serially: if some other target
3749 lists the same prerequisites and is not in '.NOTPARALLEL' then these
3750 prerequisites may be run in parallel. For example:
3752 all: base notparallel
3755 notparallel: one two three
3757 one two three: ; @sleep 1; echo $@
3759 .NOTPARALLEL: notparallel
3761 Here 'make -j base' will run the targets 'one', 'two', and 'three' in
3762 parallel, while 'make -j notparallel' will run them serially. If you
3763 run 'make -j all' then they _will_ be run in parallel since 'base' lists
3764 them as prerequisites and is not serialized.
3766 The '.NOTPARALLEL' target should not have commands.
3768 Finally you can control the serialization of specific prerequisites
3769 in a fine-grained way using the '.WAIT' special target. When this
3770 target appears in a prerequisite list and parallel execution is enabled,
3771 'make' will not build any of the prerequisites to the _right_ of '.WAIT'
3772 until all prerequisites to the _left_ of '.WAIT' have completed. For
3775 all: one two .WAIT three
3776 one two three: ; @sleep 1; echo $@
3778 If parallel execution is enabled, 'make' will try to build 'one' and
3779 'two' in parallel but will not try to build 'three' until both are
3782 As with targets provided to '.NOTPARALLEL', '.WAIT' takes effect only
3783 when building the target in whose prerequisite list it appears. If the
3784 same prerequisites are present in other targets, without '.WAIT', then
3785 they may still be run in parallel. Because of this, neither
3786 '.NOTPARALLEL' with targets nor '.WAIT' are as reliable for controlling
3787 parallel execution as defining a prerequisite relationship. However
3788 they are easy to use and may be sufficient in less complex situations.
3790 The '.WAIT' prerequisite will not be present in any of the automatic
3791 variables for the rule.
3793 You can create an actual target '.WAIT' in your makefile for
3794 portability but this is not required to use this feature. If a '.WAIT'
3795 target is created it should not have prerequisites or commands.
3797 The '.WAIT' feature is also implemented in other versions of 'make'
3798 and it's specified in the POSIX standard for 'make'.
3801 File: make.info, Node: Parallel Output, Next: Parallel Input, Prev: Parallel Disable, Up: Parallel
3803 5.4.2 Output During Parallel Execution
3804 --------------------------------------
3806 When running several recipes in parallel the output from each recipe
3807 appears as soon as it is generated, with the result that messages from
3808 different recipes may be interspersed, sometimes even appearing on the
3809 same line. This can make reading the output very difficult.
3811 To avoid this you can use the '--output-sync' ('-O') option. This
3812 option instructs 'make' to save the output from the commands it invokes
3813 and print it all once the commands are completed. Additionally, if
3814 there are multiple recursive 'make' invocations running in parallel,
3815 they will communicate so that only one of them is generating output at a
3818 If working directory printing is enabled (*note The
3819 '--print-directory' Option: -w Option.), the enter/leave messages are
3820 printed around each output grouping. If you prefer not to see these
3821 messages add the '--no-print-directory' option to 'MAKEFLAGS'.
3823 There are four levels of granularity when synchronizing output,
3824 specified by giving an argument to the option (e.g., '-Oline' or
3825 '--output-sync=recurse').
3828 This is the default: all output is sent directly as it is generated
3829 and no synchronization is performed.
3832 Output from each individual line of the recipe is grouped and
3833 printed as soon as that line is complete. If a recipe consists of
3834 multiple lines, they may be interspersed with lines from other
3838 Output from the entire recipe for each target is grouped and
3839 printed once the target is complete. This is the default if the
3840 '--output-sync' or '-O' option is given with no argument.
3843 Output from each recursive invocation of 'make' is grouped and
3844 printed once the recursive invocation is complete.
3846 Regardless of the mode chosen, the total build time will be the same.
3847 The only difference is in how the output appears.
3849 The 'target' and 'recurse' modes both collect the output of the
3850 entire recipe of a target and display it uninterrupted when the recipe
3851 completes. The difference between them is in how recipes that contain
3852 recursive invocations of 'make' are treated (*note Recursive Use of
3853 'make': Recursion.). For all recipes which have no recursive lines, the
3854 'target' and 'recurse' modes behave identically.
3856 If the 'recurse' mode is chosen, recipes that contain recursive
3857 'make' invocations are treated the same as other targets: the output
3858 from the recipe, including the output from the recursive 'make', is
3859 saved and printed after the entire recipe is complete. This ensures
3860 output from all the targets built by a given recursive 'make' instance
3861 are grouped together, which may make the output easier to understand.
3862 However it also leads to long periods of time during the build where no
3863 output is seen, followed by large bursts of output. If you are not
3864 watching the build as it proceeds, but instead viewing a log of the
3865 build after the fact, this may be the best option for you.
3867 If you are watching the output, the long gaps of quiet during the
3868 build can be frustrating. The 'target' output synchronization mode
3869 detects when 'make' is going to be invoked recursively, using the
3870 standard methods, and it will not synchronize the output of those lines.
3871 The recursive 'make' will perform the synchronization for its targets
3872 and the output from each will be displayed immediately when it
3873 completes. Be aware that output from recursive lines of the recipe are
3874 not synchronized (for example if the recursive line prints a message
3875 before running 'make', that message will not be synchronized).
3877 The 'line' mode can be useful for front-ends that are watching the
3878 output of 'make' to track when recipes are started and completed.
3880 Some programs invoked by 'make' may behave differently if they
3881 determine they're writing output to a terminal versus a file (often
3882 described as "interactive" vs. "non-interactive" modes). For example,
3883 many programs that can display colorized output will not do so if they
3884 determine they are not writing to a terminal. If your makefile invokes
3885 a program like this then using the output synchronization options will
3886 cause the program to believe it's running in "non-interactive" mode even
3887 though the output will ultimately go to the terminal.
3890 File: make.info, Node: Parallel Input, Prev: Parallel Output, Up: Parallel
3892 5.4.3 Input During Parallel Execution
3893 -------------------------------------
3895 Two processes cannot both take input from the same device at the same
3896 time. To make sure that only one recipe tries to take input from the
3897 terminal at once, 'make' will invalidate the standard input streams of
3898 all but one running recipe. If another recipe attempts to read from
3899 standard input it will usually incur a fatal error (a 'Broken pipe'
3902 It is unpredictable which recipe will have a valid standard input
3903 stream (which will come from the terminal, or wherever you redirect the
3904 standard input of 'make'). The first recipe run will always get it
3905 first, and the first recipe started after that one finishes will get it
3908 We will change how this aspect of 'make' works if we find a better
3909 alternative. In the mean time, you should not rely on any recipe using
3910 standard input at all if you are using the parallel execution feature;
3911 but if you are not using this feature, then standard input works
3912 normally in all recipes.
3915 File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Recipes
3917 5.5 Errors in Recipes
3918 =====================
3920 After each shell invocation returns, 'make' looks at its exit status.
3921 If the shell completed successfully (the exit status is zero), the next
3922 line in the recipe is executed in a new shell; after the last line is
3923 finished, the rule is finished.
3925 If there is an error (the exit status is nonzero), 'make' gives up on
3926 the current rule, and perhaps on all rules.
3928 Sometimes the failure of a certain recipe line does not indicate a
3929 problem. For example, you may use the 'mkdir' command to ensure that a
3930 directory exists. If the directory already exists, 'mkdir' will report
3931 an error, but you probably want 'make' to continue regardless.
3933 To ignore errors in a recipe line, write a '-' at the beginning of
3934 the line's text (after the initial tab). The '-' is discarded before
3935 the line is passed to the shell for execution.
3942 This causes 'make' to continue even if 'rm' is unable to remove a file.
3944 When you run 'make' with the '-i' or '--ignore-errors' flag, errors
3945 are ignored in all recipes of all rules. A rule in the makefile for the
3946 special target '.IGNORE' has the same effect, if there are no
3947 prerequisites. This is less flexible but sometimes useful.
3949 When errors are to be ignored, because of either a '-' or the '-i'
3950 flag, 'make' treats an error return just like success, except that it
3951 prints out a message that tells you the status code the shell exited
3952 with, and says that the error has been ignored.
3954 When an error happens that 'make' has not been told to ignore, it
3955 implies that the current target cannot be correctly remade, and neither
3956 can any other that depends on it either directly or indirectly. No
3957 further recipes will be executed for these targets, since their
3958 preconditions have not been achieved.
3960 Normally 'make' gives up immediately in this circumstance, returning
3961 a nonzero status. However, if the '-k' or '--keep-going' flag is
3962 specified, 'make' continues to consider the other prerequisites of the
3963 pending targets, remaking them if necessary, before it gives up and
3964 returns nonzero status. For example, after an error in compiling one
3965 object file, 'make -k' will continue compiling other object files even
3966 though it already knows that linking them will be impossible. *Note
3967 Summary of Options: Options Summary.
3969 The usual behavior assumes that your purpose is to get the specified
3970 targets up to date; once 'make' learns that this is impossible, it might
3971 as well report the failure immediately. The '-k' option says that the
3972 real purpose is to test as many of the changes made in the program as
3973 possible, perhaps to find several independent problems so that you can
3974 correct them all before the next attempt to compile. This is why Emacs'
3975 'compile' command passes the '-k' flag by default.
3977 Usually when a recipe line fails, if it has changed the target file
3978 at all, the file is corrupted and cannot be used--or at least it is not
3979 completely updated. Yet the file's time stamp says that it is now up to
3980 date, so the next time 'make' runs, it will not try to update that file.
3981 The situation is just the same as when the shell is killed by a signal;
3982 *note Interrupts::. So generally the right thing to do is to delete the
3983 target file if the recipe fails after beginning to change the file.
3984 'make' will do this if '.DELETE_ON_ERROR' appears as a target. This is
3985 almost always what you want 'make' to do, but it is not historical
3986 practice; so for compatibility, you must explicitly request it.
3989 File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Recipes
3991 5.6 Interrupting or Killing 'make'
3992 ==================================
3994 If 'make' gets a fatal signal while a shell is executing, it may delete
3995 the target file that the recipe was supposed to update. This is done if
3996 the target file's last-modification time has changed since 'make' first
3999 The purpose of deleting the target is to make sure that it is remade
4000 from scratch when 'make' is next run. Why is this? Suppose you type
4001 'Ctrl-c' while a compiler is running, and it has begun to write an
4002 object file 'foo.o'. The 'Ctrl-c' kills the compiler, resulting in an
4003 incomplete file whose last-modification time is newer than the source
4004 file 'foo.c'. But 'make' also receives the 'Ctrl-c' signal and deletes
4005 this incomplete file. If 'make' did not do this, the next invocation of
4006 'make' would think that 'foo.o' did not require updating--resulting in a
4007 strange error message from the linker when it tries to link an object
4008 file half of which is missing.
4010 You can prevent the deletion of a target file in this way by making
4011 the special target '.PRECIOUS' depend on it. Before remaking a target,
4012 'make' checks to see whether it appears on the prerequisites of
4013 '.PRECIOUS', and thereby decides whether the target should be deleted if
4014 a signal happens. Some reasons why you might do this are that the
4015 target is updated in some atomic fashion, or exists only to record a
4016 modification-time (its contents do not matter), or must exist at all
4017 times to prevent other sorts of trouble.
4019 Although 'make' does its best to clean up there are certain
4020 situations in which cleanup is impossible. For example, 'make' may be
4021 killed by an uncatchable signal. Or, one of the programs make invokes
4022 may be killed or crash, leaving behind an up-to-date but corrupt target
4023 file: 'make' will not realize that this failure requires the target to
4024 be cleaned. Or 'make' itself may encounter a bug and crash.
4026 For these reasons it's best to write _defensive recipes_, which won't
4027 leave behind corrupted targets even if they fail. Most commonly these
4028 recipes create temporary files rather than updating the target directly,
4029 then rename the temporary file to the final target name. Some compilers
4030 already behave this way, so that you don't need to write a defensive
4034 File: make.info, Node: Recursion, Next: Canned Recipes, Prev: Interrupts, Up: Recipes
4036 5.7 Recursive Use of 'make'
4037 ===========================
4039 Recursive use of 'make' means using 'make' as a command in a makefile.
4040 This technique is useful when you want separate makefiles for various
4041 subsystems that compose a larger system. For example, suppose you have
4042 a sub-directory 'subdir' which has its own makefile, and you would like
4043 the containing directory's makefile to run 'make' on the sub-directory.
4044 You can do it by writing this:
4047 cd subdir && $(MAKE)
4049 or, equivalently, this (*note Summary of Options: Options Summary.):
4054 You can write recursive 'make' commands just by copying this example,
4055 but there are many things to know about how they work and why, and about
4056 how the sub-'make' relates to the top-level 'make'. You may also find
4057 it useful to declare targets that invoke recursive 'make' commands as
4058 '.PHONY' (for more discussion on when this is useful, see *note Phony
4061 For your convenience, when GNU 'make' starts (after it has processed
4062 any '-C' options) it sets the variable 'CURDIR' to the pathname of the
4063 current working directory. This value is never touched by 'make' again:
4064 in particular note that if you include files from other directories the
4065 value of 'CURDIR' does not change. The value has the same precedence it
4066 would have if it were set in the makefile (by default, an environment
4067 variable 'CURDIR' will not override this value). Note that setting this
4068 variable has no impact on the operation of 'make' (it does not cause
4069 'make' to change its working directory, for example).
4073 * MAKE Variable:: The special effects of using '$(MAKE)'.
4074 * Variables/Recursion:: How to communicate variables to a sub-'make'.
4075 * Options/Recursion:: How to communicate options to a sub-'make'.
4076 * -w Option:: How the '-w' or '--print-directory' option
4077 helps debug use of recursive 'make' commands.
4080 File: make.info, Node: MAKE Variable, Next: Variables/Recursion, Prev: Recursion, Up: Recursion
4082 5.7.1 How the 'MAKE' Variable Works
4083 -----------------------------------
4085 Recursive 'make' commands should always use the variable 'MAKE', not the
4086 explicit command name 'make', as shown here:
4089 cd subdir && $(MAKE)
4091 The value of this variable is the file name with which 'make' was
4092 invoked. If this file name was '/bin/make', then the recipe executed is
4093 'cd subdir && /bin/make'. If you use a special version of 'make' to run
4094 the top-level makefile, the same special version will be executed for
4095 recursive invocations.
4097 As a special feature, using the variable 'MAKE' in the recipe of a
4098 rule alters the effects of the '-t' ('--touch'), '-n' ('--just-print'),
4099 or '-q' ('--question') option. Using the 'MAKE' variable has the same
4100 effect as using a '+' character at the beginning of the recipe line.
4101 *Note Instead of Executing the Recipes: Instead of Execution. This
4102 special feature is only enabled if the 'MAKE' variable appears directly
4103 in the recipe: it does not apply if the 'MAKE' variable is referenced
4104 through expansion of another variable. In the latter case you must use
4105 the '+' token to get these special effects.
4107 Consider the command 'make -t' in the above example. (The '-t'
4108 option marks targets as up to date without actually running any recipes;
4109 see *note Instead of Execution::.) Following the usual definition of
4110 '-t', a 'make -t' command in the example would create a file named
4111 'subsystem' and do nothing else. What you really want it to do is run
4112 'cd subdir && make -t'; but that would require executing the recipe, and
4113 '-t' says not to execute recipes.
4115 The special feature makes this do what you want: whenever a recipe
4116 line of a rule contains the variable 'MAKE', the flags '-t', '-n' and
4117 '-q' do not apply to that line. Recipe lines containing 'MAKE' are
4118 executed normally despite the presence of a flag that causes most
4119 recipes not to be run. The usual 'MAKEFLAGS' mechanism passes the flags
4120 to the sub-'make' (*note Communicating Options to a Sub-'make':
4121 Options/Recursion.), so your request to touch the files, or print the
4122 recipes, is propagated to the subsystem.
4125 File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MAKE Variable, Up: Recursion
4127 5.7.2 Communicating Variables to a Sub-'make'
4128 ---------------------------------------------
4130 Variable values of the top-level 'make' can be passed to the sub-'make'
4131 through the environment by explicit request. These variables are
4132 defined in the sub-'make' as defaults, but they do not override
4133 variables defined in the makefile used by the sub-'make' unless you use
4134 the '-e' switch (*note Summary of Options: Options Summary.).
4136 To pass down, or "export", a variable, 'make' adds the variable and
4137 its value to the environment for running each line of the recipe. The
4138 sub-'make', in turn, uses the environment to initialize its table of
4139 variable values. *Note Variables from the Environment: Environment.
4141 Except by explicit request, 'make' exports a variable only if it is
4142 either defined in the environment initially, or if set on the command
4143 line and its name consists only of letters, numbers, and underscores.
4145 The value of the 'make' variable 'SHELL' is not exported. Instead,
4146 the value of the 'SHELL' variable from the invoking environment is
4147 passed to the sub-'make'. You can force 'make' to export its value for
4148 'SHELL' by using the 'export' directive, described below. *Note
4149 Choosing the Shell::.
4151 The special variable 'MAKEFLAGS' is always exported (unless you
4152 unexport it). 'MAKEFILES' is exported if you set it to anything.
4154 'make' automatically passes down variable values that were defined on
4155 the command line, by putting them in the 'MAKEFLAGS' variable. *Note
4156 Options/Recursion::.
4158 Variables are _not_ normally passed down if they were created by
4159 default by 'make' (*note Variables Used by Implicit Rules: Implicit
4160 Variables.). The sub-'make' will define these for itself.
4162 If you want to export specific variables to a sub-'make', use the
4163 'export' directive, like this:
4167 If you want to _prevent_ a variable from being exported, use the
4168 'unexport' directive, like this:
4170 unexport VARIABLE ...
4172 In both of these forms, the arguments to 'export' and 'unexport' are
4173 expanded, and so could be variables or functions which expand to a (list
4174 of) variable names to be (un)exported.
4176 As a convenience, you can define a variable and export it at the same
4179 export VARIABLE = value
4181 has the same result as:
4188 export VARIABLE := value
4190 has the same result as:
4197 export VARIABLE += value
4204 *Note Appending More Text to Variables: Appending.
4206 You may notice that the 'export' and 'unexport' directives work in
4207 'make' in the same way they work in the shell, 'sh'.
4209 If you want all variables to be exported by default, you can use
4214 This tells 'make' that variables which are not explicitly mentioned in
4215 an 'export' or 'unexport' directive should be exported. Any variable
4216 given in an 'unexport' directive will still _not_ be exported.
4218 The behavior elicited by an 'export' directive by itself was the
4219 default in older versions of GNU 'make'. If your makefiles depend on
4220 this behavior and you want to be compatible with old versions of 'make',
4221 you can add the special target '.EXPORT_ALL_VARIABLES' to your makefile
4222 instead of using the 'export' directive. This will be ignored by old
4223 'make's, while the 'export' directive will cause a syntax error.
4225 When using 'export' by itself or '.EXPORT_ALL_VARIABLES' to export
4226 variables by default, only variables whose names consist solely of
4227 alphanumerics and underscores will be exported. To export other
4228 variables you must specifically mention them in an 'export' directive.
4230 Adding a variable's value to the environment requires it to be
4231 expanded. If expanding a variable has side-effects (such as the 'info'
4232 or 'eval' or similar functions) then these side-effects will be seen
4233 every time a command is invoked. You can avoid this by ensuring that
4234 such variables have names which are not exportable by default. However,
4235 a better solution is to _not_ use this "export by default" facility at
4236 all, and instead explicitly 'export' the relevant variables by name.
4238 You can use 'unexport' by itself to tell 'make' _not_ to export
4239 variables by default. Since this is the default behavior, you would
4240 only need to do this if 'export' had been used by itself earlier (in an
4241 included makefile, perhaps). You *cannot* use 'export' and 'unexport'
4242 by themselves to have variables exported for some recipes and not for
4243 others. The last 'export' or 'unexport' directive that appears by
4244 itself determines the behavior for the entire run of 'make'.
4246 As a special feature, the variable 'MAKELEVEL' is changed when it is
4247 passed down from level to level. This variable's value is a string
4248 which is the depth of the level as a decimal number. The value is '0'
4249 for the top-level 'make'; '1' for a sub-'make', '2' for a
4250 sub-sub-'make', and so on. The incrementation happens when 'make' sets
4251 up the environment for a recipe.
4253 The main use of 'MAKELEVEL' is to test it in a conditional directive
4254 (*note Conditional Parts of Makefiles: Conditionals.); this way you can
4255 write a makefile that behaves one way if run recursively and another way
4256 if run directly by you.
4258 You can use the variable 'MAKEFILES' to cause all sub-'make' commands
4259 to use additional makefiles. The value of 'MAKEFILES' is a
4260 whitespace-separated list of file names. This variable, if defined in
4261 the outer-level makefile, is passed down through the environment; then
4262 it serves as a list of extra makefiles for the sub-'make' to read before
4263 the usual or specified ones. *Note The Variable 'MAKEFILES': MAKEFILES
4267 File: make.info, Node: Options/Recursion, Next: -w Option, Prev: Variables/Recursion, Up: Recursion
4269 5.7.3 Communicating Options to a Sub-'make'
4270 -------------------------------------------
4272 Flags such as '-s' and '-k' are passed automatically to the sub-'make'
4273 through the variable 'MAKEFLAGS'. This variable is set up automatically
4274 by 'make' to contain the flag letters that 'make' received. Thus, if
4275 you do 'make -ks' then 'MAKEFLAGS' gets the value 'ks'.
4277 As a consequence, every sub-'make' gets a value for 'MAKEFLAGS' in
4278 its environment. In response, it takes the flags from that value and
4279 processes them as if they had been given as arguments. *Note Summary of
4280 Options: Options Summary.
4282 The value of 'MAKEFLAGS' is a possibly empty group of characters
4283 representing single-letter options that take no argument, followed by a
4284 space and any options that take arguments or which have long option
4285 names. If an option has both single-letter and long options, the
4286 single-letter option is always preferred. If there are no single-letter
4287 options on the command line, then the value of 'MAKEFLAGS' starts with a
4290 Likewise variables defined on the command line are passed to the
4291 sub-'make' through 'MAKEFLAGS'. Words in the value of 'MAKEFLAGS' that
4292 contain '=', 'make' treats as variable definitions just as if they
4293 appeared on the command line. *Note Overriding Variables: Overriding.
4295 The options '-C', '-f', '-o', and '-W' are not put into 'MAKEFLAGS';
4296 these options are not passed down.
4298 The '-j' option is a special case (*note Parallel Execution:
4299 Parallel.). If you set it to some numeric value 'N' and your operating
4300 system supports it (most any UNIX system will; others typically won't),
4301 the parent 'make' and all the sub-'make's will communicate to ensure
4302 that there are only 'N' jobs running at the same time between them all.
4303 Note that any job that is marked recursive (*note Instead of Executing
4304 Recipes: Instead of Execution.) doesn't count against the total jobs
4305 (otherwise we could get 'N' sub-'make's running and have no slots left
4306 over for any real work!)
4308 If your operating system doesn't support the above communication,
4309 then no '-j' is added to 'MAKEFLAGS', so that sub-'make's run in
4310 non-parallel mode. If the '-j' option were passed down to sub-'make's
4311 you would get many more jobs running in parallel than you asked for. If
4312 you give '-j' with no numeric argument, meaning to run as many jobs as
4313 possible in parallel, this is passed down, since multiple infinities are
4316 If you do not want to pass the other flags down, you must change the
4317 value of 'MAKEFLAGS', for example like this:
4320 cd subdir && $(MAKE) MAKEFLAGS=
4322 The command line variable definitions really appear in the variable
4323 'MAKEOVERRIDES', and 'MAKEFLAGS' contains a reference to this variable.
4324 If you do want to pass flags down normally, but don't want to pass down
4325 the command line variable definitions, you can reset 'MAKEOVERRIDES' to
4330 This is not usually useful to do. However, some systems have a small
4331 fixed limit on the size of the environment, and putting so much
4332 information into the value of 'MAKEFLAGS' can exceed it. If you see the
4333 error message 'Arg list too long', this may be the problem. (For strict
4334 compliance with POSIX.2, changing 'MAKEOVERRIDES' does not affect
4335 'MAKEFLAGS' if the special target '.POSIX' appears in the makefile. You
4336 probably do not care about this.)
4338 A similar variable 'MFLAGS' exists also, for historical
4339 compatibility. It has the same value as 'MAKEFLAGS' except that it does
4340 not contain the command line variable definitions, and it always begins
4341 with a hyphen unless it is empty ('MAKEFLAGS' begins with a hyphen only
4342 when it begins with an option that has no single-letter version, such as
4343 '--warn-undefined-variables'). 'MFLAGS' was traditionally used
4344 explicitly in the recursive 'make' command, like this:
4347 cd subdir && $(MAKE) $(MFLAGS)
4349 but now 'MAKEFLAGS' makes this usage redundant. If you want your
4350 makefiles to be compatible with old 'make' programs, use this technique;
4351 it will work fine with more modern 'make' versions too.
4353 The 'MAKEFLAGS' variable can also be useful if you want to have
4354 certain options, such as '-k' (*note Summary of Options: Options
4355 Summary.), set each time you run 'make'. You simply put a value for
4356 'MAKEFLAGS' in your environment. You can also set 'MAKEFLAGS' in a
4357 makefile, to specify additional flags that should also be in effect for
4358 that makefile. (Note that you cannot use 'MFLAGS' this way. That
4359 variable is set only for compatibility; 'make' does not interpret a
4360 value you set for it in any way.)
4362 When 'make' interprets the value of 'MAKEFLAGS' (either from the
4363 environment or from a makefile), it first prepends a hyphen if the value
4364 does not already begin with one. Then it chops the value into words
4365 separated by blanks, and parses these words as if they were options
4366 given on the command line (except that '-C', '-f', '-h', '-o', '-W', and
4367 their long-named versions are ignored; and there is no error for an
4370 If you do put 'MAKEFLAGS' in your environment, you should be sure not
4371 to include any options that will drastically affect the actions of
4372 'make' and undermine the purpose of makefiles and of 'make' itself. For
4373 instance, the '-t', '-n', and '-q' options, if put in one of these
4374 variables, could have disastrous consequences and would certainly have
4375 at least surprising and probably annoying effects.
4377 If you'd like to run other implementations of 'make' in addition to
4378 GNU 'make', and hence do not want to add GNU 'make'-specific flags to
4379 the 'MAKEFLAGS' variable, you can add them to the 'GNUMAKEFLAGS'
4380 variable instead. This variable is parsed just before 'MAKEFLAGS', in
4381 the same way as 'MAKEFLAGS'. When 'make' constructs 'MAKEFLAGS' to pass
4382 to a recursive 'make' it will include all flags, even those taken from
4383 'GNUMAKEFLAGS'. As a result, after parsing 'GNUMAKEFLAGS' GNU 'make'
4384 sets this variable to the empty string to avoid duplicating flags during
4387 It's best to use 'GNUMAKEFLAGS' only with flags which won't
4388 materially change the behavior of your makefiles. If your makefiles
4389 require GNU make anyway then simply use 'MAKEFLAGS'. Flags such as
4390 '--no-print-directory' or '--output-sync' may be appropriate for
4394 File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion
4396 5.7.4 The '--print-directory' Option
4397 ------------------------------------
4399 If you use several levels of recursive 'make' invocations, the '-w' or
4400 '--print-directory' option can make the output a lot easier to
4401 understand by showing each directory as 'make' starts processing it and
4402 as 'make' finishes processing it. For example, if 'make -w' is run in
4403 the directory '/u/gnu/make', 'make' will print a line of the form:
4405 make: Entering directory `/u/gnu/make'.
4407 before doing anything else, and a line of the form:
4409 make: Leaving directory `/u/gnu/make'.
4411 when processing is completed.
4413 Normally, you do not need to specify this option because 'make' does
4414 it for you: '-w' is turned on automatically when you use the '-C'
4415 option, and in sub-'make's. 'make' will not automatically turn on '-w'
4416 if you also use '-s', which says to be silent, or if you use
4417 '--no-print-directory' to explicitly disable it.
4420 File: make.info, Node: Canned Recipes, Next: Empty Recipes, Prev: Recursion, Up: Recipes
4422 5.8 Defining Canned Recipes
4423 ===========================
4425 When the same sequence of commands is useful in making various targets,
4426 you can define it as a canned sequence with the 'define' directive, and
4427 refer to the canned sequence from the recipes for those targets. The
4428 canned sequence is actually a variable, so the name must not conflict
4429 with other variable names.
4431 Here is an example of defining a canned recipe:
4434 yacc $(firstword $^)
4438 Here 'run-yacc' is the name of the variable being defined; 'endef' marks
4439 the end of the definition; the lines in between are the commands. The
4440 'define' directive does not expand variable references and function
4441 calls in the canned sequence; the '$' characters, parentheses, variable
4442 names, and so on, all become part of the value of the variable you are
4443 defining. *Note Defining Multi-Line Variables: Multi-Line, for a
4444 complete explanation of 'define'.
4446 The first command in this example runs Yacc on the first prerequisite
4447 of whichever rule uses the canned sequence. The output file from Yacc
4448 is always named 'y.tab.c'. The second command moves the output to the
4449 rule's target file name.
4451 To use the canned sequence, substitute the variable into the recipe
4452 of a rule. You can substitute it like any other variable (*note Basics
4453 of Variable References: Reference.). Because variables defined by
4454 'define' are recursively expanded variables, all the variable references
4455 you wrote inside the 'define' are expanded now. For example:
4460 'foo.y' will be substituted for the variable '$^' when it occurs in
4461 'run-yacc''s value, and 'foo.c' for '$@'.
4463 This is a realistic example, but this particular one is not needed in
4464 practice because 'make' has an implicit rule to figure out these
4465 commands based on the file names involved (*note Using Implicit Rules:
4468 In recipe execution, each line of a canned sequence is treated just
4469 as if the line appeared on its own in the rule, preceded by a tab. In
4470 particular, 'make' invokes a separate sub-shell for each line. You can
4471 use the special prefix characters that affect command lines ('@', '-',
4472 and '+') on each line of a canned sequence. *Note Writing Recipes in
4473 Rules: Recipes. For example, using this canned sequence:
4476 @echo "frobnicating target $@"
4477 frob-step-1 $< -o $@-step-1
4478 frob-step-2 $@-step-1 -o $@
4481 'make' will not echo the first line, the 'echo' command. But it _will_
4482 echo the following two recipe lines.
4484 On the other hand, prefix characters on the recipe line that refers
4485 to a canned sequence apply to every line in the sequence. So the rule:
4490 does not echo _any_ recipe lines. (*Note Recipe Echoing: Echoing, for a
4491 full explanation of '@'.)
4494 File: make.info, Node: Empty Recipes, Prev: Canned Recipes, Up: Recipes
4496 5.9 Using Empty Recipes
4497 =======================
4499 It is sometimes useful to define recipes which do nothing. This is done
4500 simply by giving a recipe that consists of nothing but whitespace. For
4505 defines an empty recipe for 'target'. You could also use a line
4506 beginning with a recipe prefix character to define an empty recipe, but
4507 this would be confusing because such a line looks empty.
4509 You may be wondering why you would want to define a recipe that does
4510 nothing. One reason this is useful is to prevent a target from getting
4511 implicit recipes (from implicit rules or the '.DEFAULT' special target;
4512 *note Implicit Rules:: and *note Defining Last-Resort Default Rules:
4515 Empty recipes can also be used to avoid errors for targets that will
4516 be created as a side-effect of another recipe: if the target does not
4517 exist the empty recipe ensures that 'make' won't complain that it
4518 doesn't know how to build the target, and 'make' will assume the target
4521 You may be inclined to define empty recipes for targets that are not
4522 actual files, but only exist so that their prerequisites can be remade.
4523 However, this is not the best way to do that, because the prerequisites
4524 may not be remade properly if the target file actually does exist.
4525 *Note Phony Targets: Phony Targets, for a better way to do this.
4528 File: make.info, Node: Using Variables, Next: Conditionals, Prev: Recipes, Up: Top
4530 6 How to Use Variables
4531 **********************
4533 A "variable" is a name defined in a makefile to represent a string of
4534 text, called the variable's "value". These values are substituted by
4535 explicit request into targets, prerequisites, recipes, and other parts
4536 of the makefile. (In some other versions of 'make', variables are
4539 Variables and functions in all parts of a makefile are expanded when
4540 read, except for in recipes, the right-hand sides of variable
4541 definitions using '=', and the bodies of variable definitions using the
4542 'define' directive. The value a variable expands to is that of its most
4543 recent definition at the time of expansion. In other words, variables
4544 are dynamically scoped.
4546 Variables can represent lists of file names, options to pass to
4547 compilers, programs to run, directories to look in for source files,
4548 directories to write output in, or anything else you can imagine.
4550 A variable name may be any sequence of characters not containing ':',
4551 '#', '=', or whitespace. However, variable names containing characters
4552 other than letters, numbers, and underscores should be considered
4553 carefully, as in some shells they cannot be passed through the
4554 environment to a sub-'make' (*note Communicating Variables to a
4555 Sub-'make': Variables/Recursion.). Variable names beginning with '.'
4556 and an uppercase letter may be given special meaning in future versions
4559 Variable names are case-sensitive. The names 'foo', 'FOO', and 'Foo'
4560 all refer to different variables.
4562 It is traditional to use upper case letters in variable names, but we
4563 recommend using lower case letters for variable names that serve
4564 internal purposes in the makefile, and reserving upper case for
4565 parameters that control implicit rules or for parameters that the user
4566 should override with command options (*note Overriding Variables:
4569 A few variables have names that are a single punctuation character or
4570 just a few characters. These are the "automatic variables", and they
4571 have particular specialized uses. *Note Automatic Variables::.
4575 * Reference:: How to use the value of a variable.
4576 * Flavors:: Variables come in two flavors.
4577 * Advanced:: Advanced features for referencing a variable.
4578 * Values:: All the ways variables get their values.
4579 * Setting:: How to set a variable in the makefile.
4580 * Appending:: How to append more text to the old value
4582 * Override Directive:: How to set a variable in the makefile even if
4583 the user has set it with a command argument.
4584 * Multi-Line:: An alternate way to set a variable
4585 to a multi-line string.
4586 * Undefine Directive:: How to undefine a variable so that it appears
4587 as if it was never set.
4588 * Environment:: Variable values can come from the environment.
4589 * Target-specific:: Variable values can be defined on a per-target
4591 * Pattern-specific:: Target-specific variable values can be applied
4592 to a group of targets that match a pattern.
4593 * Suppressing Inheritance:: Suppress inheritance of variables.
4594 * Special Variables:: Variables with special meaning or behavior.
4597 File: make.info, Node: Reference, Next: Flavors, Prev: Using Variables, Up: Using Variables
4599 6.1 Basics of Variable References
4600 =================================
4602 To substitute a variable's value, write a dollar sign followed by the
4603 name of the variable in parentheses or braces: either '$(foo)' or
4604 '${foo}' is a valid reference to the variable 'foo'. This special
4605 significance of '$' is why you must write '$$' to have the effect of a
4606 single dollar sign in a file name or recipe.
4608 Variable references can be used in any context: targets,
4609 prerequisites, recipes, most directives, and new variable values. Here
4610 is an example of a common case, where a variable holds the names of all
4611 the object files in a program:
4613 objects = program.o foo.o utils.o
4614 program : $(objects)
4615 cc -o program $(objects)
4619 Variable references work by strict textual substitution. Thus, the
4623 prog.o : prog.$(foo)
4624 $(foo)$(foo) -$(foo) prog.$(foo)
4626 could be used to compile a C program 'prog.c'. Since spaces before the
4627 variable value are ignored in variable assignments, the value of 'foo'
4628 is precisely 'c'. (Don't actually write your makefiles this way!)
4630 A dollar sign followed by a character other than a dollar sign,
4631 open-parenthesis or open-brace treats that single character as the
4632 variable name. Thus, you could reference the variable 'x' with '$x'.
4633 However, this practice can lead to confusion (e.g., '$foo' refers to the
4634 variable 'f' followed by the string 'oo') so we recommend using
4635 parentheses or braces around all variables, even single-letter
4636 variables, unless omitting them gives significant readability
4637 improvements. One place where readability is often improved is
4638 automatic variables (*note Automatic Variables::).
4641 File: make.info, Node: Flavors, Next: Advanced, Prev: Reference, Up: Using Variables
4643 6.2 The Two Flavors of Variables
4644 ================================
4646 There are different ways that a variable in GNU 'make' can get a value;
4647 we call them the "flavors" of variables. The flavors are distinguished
4648 in how they handle the values they are assigned in the makefile, and in
4649 how those values are managed when the variable is later used and
4654 * Recursive Assignment:: Setting recursively expanded variables.
4655 * Simple Assignment:: Setting simply expanded variables.
4656 * Immediate Assignment:: Setting immediately expanded variables.
4657 * Conditional Assignment:: Assigning variable values conditionally.
4660 File: make.info, Node: Recursive Assignment, Next: Simple Assignment, Prev: Flavors, Up: Flavors
4662 6.2.1 Recursively Expanded Variable Assignment
4663 ----------------------------------------------
4665 The first flavor of variable is a "recursively expanded" variable.
4666 Variables of this sort are defined by lines using '=' (*note Setting
4667 Variables: Setting.) or by the 'define' directive (*note Defining
4668 Multi-Line Variables: Multi-Line.). The value you specify is installed
4669 verbatim; if it contains references to other variables, these references
4670 are expanded whenever this variable is substituted (in the course of
4671 expanding some other string). When this happens, it is called
4672 "recursive expansion".
4682 will echo 'Huh?': '$(foo)' expands to '$(bar)' which expands to '$(ugh)'
4683 which finally expands to 'Huh?'.
4685 This flavor of variable is the only sort supported by most other
4686 versions of 'make'. It has its advantages and its disadvantages. An
4687 advantage (most would say) is that:
4689 CFLAGS = $(include_dirs) -O
4690 include_dirs = -Ifoo -Ibar
4692 will do what was intended: when 'CFLAGS' is expanded in a recipe, it
4693 will expand to '-Ifoo -Ibar -O'. A major disadvantage is that you
4694 cannot append something on the end of a variable, as in
4696 CFLAGS = $(CFLAGS) -O
4698 because it will cause an infinite loop in the variable expansion.
4699 (Actually 'make' detects the infinite loop and reports an error.)
4701 Another disadvantage is that any functions (*note Functions for
4702 Transforming Text: Functions.) referenced in the definition will be
4703 executed every time the variable is expanded. This makes 'make' run
4704 slower; worse, it causes the 'wildcard' and 'shell' functions to give
4705 unpredictable results because you cannot easily control when they are
4706 called, or even how many times.
4709 File: make.info, Node: Simple Assignment, Next: Immediate Assignment, Prev: Recursive Assignment, Up: Flavors
4711 6.2.2 Simply Expanded Variable Assignment
4712 -----------------------------------------
4714 To avoid the problems and inconveniences of recursively expanded
4715 variables, there is another flavor: simply expanded variables.
4717 "Simply expanded variables" are defined by lines using ':=' or '::='
4718 (*note Setting Variables: Setting.). Both forms are equivalent in GNU
4719 'make'; however only the '::=' form is described by the POSIX standard
4720 (support for '::=' is added to the POSIX standard for POSIX Issue 8).
4722 The value of a simply expanded variable is scanned once, expanding
4723 any references to other variables and functions, when the variable is
4724 defined. Once that expansion is complete the value of the variable is
4725 never expanded again: when the variable is used the value is copied
4726 verbatim as the expansion. If the value contained variable references
4727 the result of the expansion will contain their values _as of the time
4728 this variable was defined_. Therefore,
4739 Here is a somewhat more complicated example, illustrating the use of
4740 ':=' in conjunction with the 'shell' function. (*Note The 'shell'
4741 Function: Shell Function.) This example also shows use of the variable
4742 'MAKELEVEL', which is changed when it is passed down from level to
4743 level. (*Note Communicating Variables to a Sub-'make':
4744 Variables/Recursion, for information about 'MAKELEVEL'.)
4746 ifeq (0,${MAKELEVEL})
4747 whoami := $(shell whoami)
4748 host-type := $(shell arch)
4749 MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
4752 An advantage of this use of ':=' is that a typical 'descend into a
4753 directory' recipe then looks like this:
4758 Simply expanded variables generally make complicated makefile
4759 programming more predictable because they work like variables in most
4760 programming languages. They allow you to redefine a variable using its
4761 own value (or its value processed in some way by one of the expansion
4762 functions) and to use the expansion functions much more efficiently
4763 (*note Functions for Transforming Text: Functions.).
4765 You can also use them to introduce controlled leading whitespace into
4766 variable values. Leading whitespace characters are discarded from your
4767 input before substitution of variable references and function calls;
4768 this means you can include leading spaces in a variable value by
4769 protecting them with variable references, like this:
4772 space := $(nullstring) # end of the line
4774 Here the value of the variable 'space' is precisely one space. The
4775 comment '# end of the line' is included here just for clarity. Since
4776 trailing space characters are _not_ stripped from variable values, just
4777 a space at the end of the line would have the same effect (but be rather
4778 hard to read). If you put whitespace at the end of a variable value, it
4779 is a good idea to put a comment like that at the end of the line to make
4780 your intent clear. Conversely, if you do _not_ want any whitespace
4781 characters at the end of your variable value, you must remember not to
4782 put a random comment on the end of the line after some whitespace, such
4785 dir := /foo/bar # directory to put the frobs in
4787 Here the value of the variable 'dir' is '/foo/bar ' (with four
4788 trailing spaces), which was probably not the intention. (Imagine
4789 something like '$(dir)/file' with this definition!)
4792 File: make.info, Node: Immediate Assignment, Next: Conditional Assignment, Prev: Simple Assignment, Up: Flavors
4794 6.2.3 Immediately Expanded Variable Assignment
4795 ----------------------------------------------
4797 Another form of assignment allows for immediate expansion, but unlike
4798 simple assignment the resulting variable is recursive: it will be
4799 re-expanded again on every use. In order to avoid unexpected results,
4800 after the value is immediately expanded it will automatically be quoted:
4801 all instances of '$' in the value after expansion will be converted into
4802 '$$'. This type of assignment uses the ':::=' operator. For example,
4808 results in the 'OUT' variable containing the text 'first', while here:
4814 results in the 'OUT' variable containing the text 'one$$two'. The value
4815 is expanded when the variable is assigned, so the result is the
4816 expansion of the first value of 'var', 'one$two'; then the value is
4817 re-escaped before the assignment is complete giving the final result of
4820 The variable 'OUT' is thereafter considered a recursive variable, so
4821 it will be re-expanded when it is used.
4823 This seems functionally equivalent to the ':=' / '::=' operators, but
4824 there are a few differences:
4826 First, after assignment the variable is a normal recursive variable;
4827 when you append to it with '+=' the value on the right-hand side is not
4828 expanded immediately. If you prefer the '+=' operator to expand the
4829 right-hand side immediately you should use the ':=' / '::=' assignment
4832 Second, these variables are slightly less efficient than simply
4833 expanded variables since they do need to be re-expanded when they are
4834 used, rather than merely copied. However since all variable references
4835 are escaped this expansion simply un-escapes the value, it won't expand
4836 any variables or run any functions.
4838 Here is another example:
4845 After this, the value of 'OUT' is the text 'one$$two $(var)'. When
4846 this variable is used it will be expanded and the result will be
4847 'one$two three$four'.
4849 This style of assignment is equivalent to the traditional BSD 'make'
4850 ':=' operator; as you can see it works slightly differently than the GNU
4851 'make' ':=' operator. The ':::=' operator is added to the POSIX
4852 specification in Issue 8 to provide portability.
4855 File: make.info, Node: Conditional Assignment, Prev: Immediate Assignment, Up: Flavors
4857 6.2.4 Conditional Variable Assignment
4858 -------------------------------------
4860 There is another assignment operator for variables, '?='. This is
4861 called a conditional variable assignment operator, because it only has
4862 an effect if the variable is not yet defined. This statement:
4866 is exactly equivalent to this (*note The 'origin' Function: Origin
4869 ifeq ($(origin FOO), undefined)
4873 Note that a variable set to an empty value is still defined, so '?='
4874 will not set that variable.
4877 File: make.info, Node: Advanced, Next: Values, Prev: Flavors, Up: Using Variables
4879 6.3 Advanced Features for Reference to Variables
4880 ================================================
4882 This section describes some advanced features you can use to reference
4883 variables in more flexible ways.
4887 * Substitution Refs:: Referencing a variable with
4888 substitutions on the value.
4889 * Computed Names:: Computing the name of the variable to refer to.
4892 File: make.info, Node: Substitution Refs, Next: Computed Names, Prev: Advanced, Up: Advanced
4894 6.3.1 Substitution References
4895 -----------------------------
4897 A "substitution reference" substitutes the value of a variable with
4898 alterations that you specify. It has the form '$(VAR:A=B)' (or
4899 '${VAR:A=B}') and its meaning is to take the value of the variable VAR,
4900 replace every A at the end of a word with B in that value, and
4901 substitute the resulting string.
4903 When we say "at the end of a word", we mean that A must appear either
4904 followed by whitespace or at the end of the value in order to be
4905 replaced; other occurrences of A in the value are unaltered. For
4908 foo := a.o b.o l.a c.o
4911 sets 'bar' to 'a.c b.c l.a c.c'. *Note Setting Variables: Setting.
4913 A substitution reference is shorthand for the 'patsubst' expansion
4914 function (*note Functions for String Substitution and Analysis: Text
4915 Functions.): '$(VAR:A=B)' is equivalent to '$(patsubst %A,%B,VAR)'. We
4916 provide substitution references as well as 'patsubst' for compatibility
4917 with other implementations of 'make'.
4919 Another type of substitution reference lets you use the full power of
4920 the 'patsubst' function. It has the same form '$(VAR:A=B)' described
4921 above, except that now A must contain a single '%' character. This case
4922 is equivalent to '$(patsubst A,B,$(VAR))'. *Note Functions for String
4923 Substitution and Analysis: Text Functions, for a description of the
4924 'patsubst' function. For example:
4926 foo := a.o b.o l.a c.o
4927 bar := $(foo:%.o=%.c)
4929 sets 'bar' to 'a.c b.c l.a c.c'.
4932 File: make.info, Node: Computed Names, Prev: Substitution Refs, Up: Advanced
4934 6.3.2 Computed Variable Names
4935 -----------------------------
4937 Computed variable names are an advanced concept, very useful in more
4938 sophisticated makefile programming. In simple situations you need not
4939 consider them, but they can be extremely useful.
4941 Variables may be referenced inside the name of a variable. This is
4942 called a "computed variable name" or a "nested variable reference". For
4949 defines 'a' as 'z': the '$(x)' inside '$($(x))' expands to 'y', so
4950 '$($(x))' expands to '$(y)' which in turn expands to 'z'. Here the name
4951 of the variable to reference is not stated explicitly; it is computed by
4952 expansion of '$(x)'. The reference '$(x)' here is nested within the
4953 outer variable reference.
4955 The previous example shows two levels of nesting, but any number of
4956 levels is possible. For example, here are three levels:
4963 Here the innermost '$(x)' expands to 'y', so '$($(x))' expands to '$(y)'
4964 which in turn expands to 'z'; now we have '$(z)', which becomes 'u'.
4966 References to recursively-expanded variables within a variable name
4967 are re-expanded in the usual fashion. For example:
4974 defines 'a' as 'Hello': '$($(x))' becomes '$($(y))' which becomes '$(z)'
4975 which becomes 'Hello'.
4977 Nested variable references can also contain modified references and
4978 function invocations (*note Functions for Transforming Text:
4979 Functions.), just like any other reference. For example, using the
4980 'subst' function (*note Functions for String Substitution and Analysis:
4985 y = $(subst 1,2,$(x))
4989 eventually defines 'a' as 'Hello'. It is doubtful that anyone would
4990 ever want to write a nested reference as convoluted as this one, but it
4991 works: '$($($(z)))' expands to '$($(y))' which becomes '$($(subst
4992 1,2,$(x)))'. This gets the value 'variable1' from 'x' and changes it by
4993 substitution to 'variable2', so that the entire string becomes
4994 '$(variable2)', a simple variable reference whose value is 'Hello'.
4996 A computed variable name need not consist entirely of a single
4997 variable reference. It can contain several variable references, as well
4998 as some invariant text. For example,
5003 a_files := filea fileb
5004 1_files := file1 file2
5006 ifeq "$(use_a)" "yes"
5012 ifeq "$(use_dirs)" "yes"
5018 dirs := $($(a1)_$(df))
5020 will give 'dirs' the same value as 'a_dirs', '1_dirs', 'a_files' or
5021 '1_files' depending on the settings of 'use_a' and 'use_dirs'.
5023 Computed variable names can also be used in substitution references:
5025 a_objects := a.o b.o c.o
5026 1_objects := 1.o 2.o 3.o
5028 sources := $($(a1)_objects:.o=.c)
5030 defines 'sources' as either 'a.c b.c c.c' or '1.c 2.c 3.c', depending on
5033 The only restriction on this sort of use of nested variable
5034 references is that they cannot specify part of the name of a function to
5035 be called. This is because the test for a recognized function name is
5036 done before the expansion of nested references. For example,
5046 foo := $($(func) $(bar))
5048 attempts to give 'foo' the value of the variable 'sort a d b g q c' or
5049 'strip a d b g q c', rather than giving 'a d b g q c' as the argument to
5050 either the 'sort' or the 'strip' function. This restriction could be
5051 removed in the future if that change is shown to be a good idea.
5053 You can also use computed variable names in the left-hand side of a
5054 variable assignment, or in a 'define' directive, as in:
5057 $(dir)_sources := $(wildcard $(dir)/*.c)
5058 define $(dir)_print =
5059 lpr $($(dir)_sources)
5062 This example defines the variables 'dir', 'foo_sources', and
5065 Note that "nested variable references" are quite different from
5066 "recursively expanded variables" (*note The Two Flavors of Variables:
5067 Flavors.), though both are used together in complex ways when doing
5068 makefile programming.
5071 File: make.info, Node: Values, Next: Setting, Prev: Advanced, Up: Using Variables
5073 6.4 How Variables Get Their Values
5074 ==================================
5076 Variables can get values in several different ways:
5078 * You can specify an overriding value when you run 'make'. *Note
5079 Overriding Variables: Overriding.
5081 * You can specify a value in the makefile, either with an assignment
5082 (*note Setting Variables: Setting.) or with a verbatim definition
5083 (*note Defining Multi-Line Variables: Multi-Line.).
5085 * You can specify a short-lived value with the 'let' function (*note
5086 Let Function::) or with the 'foreach' function (*note Foreach
5089 * Variables in the environment become 'make' variables. *Note
5090 Variables from the Environment: Environment.
5092 * Several "automatic" variables are given new values for each rule.
5093 Each of these has a single conventional use. *Note Automatic
5096 * Several variables have constant initial values. *Note Variables
5097 Used by Implicit Rules: Implicit Variables.
5100 File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Variables
5102 6.5 Setting Variables
5103 =====================
5105 To set a variable from the makefile, write a line starting with the
5106 variable name followed by one of the assignment operators '=', ':=',
5107 '::=', or ':::='. Whatever follows the operator and any initial
5108 whitespace on the line becomes the value. For example,
5110 objects = main.o foo.o bar.o utils.o
5112 defines a variable named 'objects' to contain the value 'main.o foo.o
5113 bar.o utils.o'. Whitespace around the variable name and immediately
5114 after the '=' is ignored.
5116 Variables defined with '=' are "recursively expanded" variables.
5117 Variables defined with ':=' or '::=' are "simply expanded" variables;
5118 these definitions can contain variable references which will be expanded
5119 before the definition is made. Variables defined with ':::=' are
5120 "immediately expanded" variables. The different assignment operators
5121 are described in *Note The Two Flavors of Variables: Flavors.
5123 The variable name may contain function and variable references, which
5124 are expanded when the line is read to find the actual variable name to
5127 There is no limit on the length of the value of a variable except the
5128 amount of memory on the computer. You can split the value of a variable
5129 into multiple physical lines for readability (*note Splitting Long
5130 Lines: Splitting Lines.).
5132 Most variable names are considered to have the empty string as a
5133 value if you have never set them. Several variables have built-in
5134 initial values that are not empty, but you can set them in the usual
5135 ways (*note Variables Used by Implicit Rules: Implicit Variables.).
5136 Several special variables are set automatically to a new value for each
5137 rule; these are called the "automatic" variables (*note Automatic
5140 If you'd like a variable to be set to a value only if it's not
5141 already set, then you can use the shorthand operator '?=' instead of
5142 '='. These two settings of the variable 'FOO' are identical (*note The
5143 'origin' Function: Origin Function.):
5149 ifeq ($(origin FOO), undefined)
5153 The shell assignment operator '!=' can be used to execute a shell
5154 script and set a variable to its output. This operator first evaluates
5155 the right-hand side, then passes that result to the shell for execution.
5156 If the result of the execution ends in a newline, that one newline is
5157 removed; all other newlines are replaced by spaces. The resulting
5158 string is then placed into the named recursively-expanded variable. For
5161 hash != printf '\043'
5162 file_list != find . -name '*.c'
5164 If the result of the execution could produce a '$', and you don't
5165 intend what follows that to be interpreted as a make variable or
5166 function reference, then you must replace every '$' with '$$' as part of
5167 the execution. Alternatively, you can set a simply expanded variable to
5168 the result of running a program using the 'shell' function call. *Note
5169 The 'shell' Function: Shell Function. For example:
5171 hash := $(shell printf '\043')
5172 var := $(shell find . -name "*.c")
5174 As with the 'shell' function, the exit status of the just-invoked
5175 shell script is stored in the '.SHELLSTATUS' variable.
5178 File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables
5180 6.6 Appending More Text to Variables
5181 ====================================
5183 Often it is useful to add more text to the value of a variable already
5184 defined. You do this with a line containing '+=', like this:
5186 objects += another.o
5188 This takes the value of the variable 'objects', and adds the text
5189 'another.o' to it (preceded by a single space, if it has a value
5192 objects = main.o foo.o bar.o utils.o
5193 objects += another.o
5195 sets 'objects' to 'main.o foo.o bar.o utils.o another.o'.
5197 Using '+=' is similar to:
5199 objects = main.o foo.o bar.o utils.o
5200 objects := $(objects) another.o
5202 but differs in ways that become important when you use more complex
5205 When the variable in question has not been defined before, '+=' acts
5206 just like normal '=': it defines a recursively-expanded variable.
5207 However, when there _is_ a previous definition, exactly what '+=' does
5208 depends on what flavor of variable you defined originally. *Note The
5209 Two Flavors of Variables: Flavors, for an explanation of the two flavors
5212 When you add to a variable's value with '+=', 'make' acts essentially
5213 as if you had included the extra text in the initial definition of the
5214 variable. If you defined it first with ':=' or '::=', making it a
5215 simply-expanded variable, '+=' adds to that simply-expanded definition,
5216 and expands the new text before appending it to the old value just as
5217 ':=' does (see *note Setting Variables: Setting, for a full explanation
5218 of ':=' or '::='). In fact,
5223 is exactly equivalent to:
5226 variable := $(variable) more
5228 On the other hand, when you use '+=' with a variable that you defined
5229 first to be recursively-expanded using plain '=' or ':::=', 'make'
5230 appends the un-expanded text to the existing value, whatever it is.
5236 is roughly equivalent to:
5239 variable = $(temp) more
5241 except that of course it never defines a variable called 'temp'. The
5242 importance of this comes when the variable's old value contains variable
5243 references. Take this common example:
5245 CFLAGS = $(includes) -O
5247 CFLAGS += -pg # enable profiling
5249 The first line defines the 'CFLAGS' variable with a reference to another
5250 variable, 'includes'. ('CFLAGS' is used by the rules for C compilation;
5251 *note Catalogue of Built-In Rules: Catalogue of Rules.) Using '=' for
5252 the definition makes 'CFLAGS' a recursively-expanded variable, meaning
5253 '$(includes) -O' is _not_ expanded when 'make' processes the definition
5254 of 'CFLAGS'. Thus, 'includes' need not be defined yet for its value to
5255 take effect. It only has to be defined before any reference to
5256 'CFLAGS'. If we tried to append to the value of 'CFLAGS' without using
5257 '+=', we might do it like this:
5259 CFLAGS := $(CFLAGS) -pg # enable profiling
5261 This is pretty close, but not quite what we want. Using ':=' redefines
5262 'CFLAGS' as a simply-expanded variable; this means 'make' expands the
5263 text '$(CFLAGS) -pg' before setting the variable. If 'includes' is not
5264 yet defined, we get ' -O -pg', and a later definition of 'includes' will
5265 have no effect. Conversely, by using '+=' we set 'CFLAGS' to the
5266 _unexpanded_ value '$(includes) -O -pg'. Thus we preserve the reference
5267 to 'includes', so if that variable gets defined at any later point, a
5268 reference like '$(CFLAGS)' still uses its value.
5271 File: make.info, Node: Override Directive, Next: Multi-Line, Prev: Appending, Up: Using Variables
5273 6.7 The 'override' Directive
5274 ============================
5276 If a variable has been set with a command argument (*note Overriding
5277 Variables: Overriding.), then ordinary assignments in the makefile are
5278 ignored. If you want to set the variable in the makefile even though it
5279 was set with a command argument, you can use an 'override' directive,
5280 which is a line that looks like this:
5282 override VARIABLE = VALUE
5286 override VARIABLE := VALUE
5288 To append more text to a variable defined on the command line, use:
5290 override VARIABLE += MORE TEXT
5292 *Note Appending More Text to Variables: Appending.
5294 Variable assignments marked with the 'override' flag have a higher
5295 priority than all other assignments, except another 'override'.
5296 Subsequent assignments or appends to this variable which are not marked
5297 'override' will be ignored.
5299 The 'override' directive was not invented for escalation in the war
5300 between makefiles and command arguments. It was invented so you can
5301 alter and add to values that the user specifies with command arguments.
5303 For example, suppose you always want the '-g' switch when you run the
5304 C compiler, but you would like to allow the user to specify the other
5305 switches with a command argument just as usual. You could use this
5306 'override' directive:
5308 override CFLAGS += -g
5310 You can also use 'override' directives with 'define' directives.
5311 This is done as you might expect:
5313 override define foo =
5317 *Note Defining Multi-Line Variables: Multi-Line.
5320 File: make.info, Node: Multi-Line, Next: Undefine Directive, Prev: Override Directive, Up: Using Variables
5322 6.8 Defining Multi-Line Variables
5323 =================================
5325 Another way to set the value of a variable is to use the 'define'
5326 directive. This directive has an unusual syntax which allows newline
5327 characters to be included in the value, which is convenient for defining
5328 both canned sequences of commands (*note Defining Canned Recipes: Canned
5329 Recipes.), and also sections of makefile syntax to use with 'eval'
5330 (*note Eval Function::).
5332 The 'define' directive is followed on the same line by the name of
5333 the variable being defined and an (optional) assignment operator, and
5334 nothing more. The value to give the variable appears on the following
5335 lines. The end of the value is marked by a line containing just the
5338 Aside from this difference in syntax, 'define' works just like any
5339 other variable definition. The variable name may contain function and
5340 variable references, which are expanded when the directive is read to
5341 find the actual variable name to use.
5343 The final newline before the 'endef' is not included in the value; if
5344 you want your value to contain a trailing newline you must include a
5345 blank line. For example in order to define a variable that contains a
5346 newline character you must use _two_ empty lines, not one:
5353 You may omit the variable assignment operator if you prefer. If
5354 omitted, 'make' assumes it to be '=' and creates a recursively-expanded
5355 variable (*note The Two Flavors of Variables: Flavors.). When using a
5356 '+=' operator, the value is appended to the previous value as with any
5357 other append operation: with a single space separating the old and new
5360 You may nest 'define' directives: 'make' will keep track of nested
5361 directives and report an error if they are not all properly closed with
5362 'endef'. Note that lines beginning with the recipe prefix character are
5363 considered part of a recipe, so any 'define' or 'endef' strings
5364 appearing on such a line will not be considered 'make' directives.
5371 When used in a recipe, the previous example is functionally
5374 two-lines = echo foo; echo $(bar)
5376 since two commands separated by semicolon behave much like two separate
5377 shell commands. However, note that using two separate lines means
5378 'make' will invoke the shell twice, running an independent sub-shell for
5379 each line. *Note Recipe Execution: Execution.
5381 If you want variable definitions made with 'define' to take
5382 precedence over command-line variable definitions, you can use the
5383 'override' directive together with 'define':
5385 override define two-lines =
5390 *Note The 'override' Directive: Override Directive.
5393 File: make.info, Node: Undefine Directive, Next: Environment, Prev: Multi-Line, Up: Using Variables
5395 6.9 Undefining Variables
5396 ========================
5398 If you want to clear a variable, setting its value to empty is usually
5399 sufficient. Expanding such a variable will yield the same result (empty
5400 string) regardless of whether it was set or not. However, if you are
5401 using the 'flavor' (*note Flavor Function::) and 'origin' (*note Origin
5402 Function::) functions, there is a difference between a variable that was
5403 never set and a variable with an empty value. In such situations you
5404 may want to use the 'undefine' directive to make a variable appear as if
5405 it was never set. For example:
5413 $(info $(origin foo))
5414 $(info $(flavor bar))
5416 This example will print "undefined" for both variables.
5418 If you want to undefine a command-line variable definition, you can
5419 use the 'override' directive together with 'undefine', similar to how
5420 this is done for variable definitions:
5422 override undefine CFLAGS
5425 File: make.info, Node: Environment, Next: Target-specific, Prev: Undefine Directive, Up: Using Variables
5427 6.10 Variables from the Environment
5428 ===================================
5430 Variables in 'make' can come from the environment in which 'make' is
5431 run. Every environment variable that 'make' sees when it starts up is
5432 transformed into a 'make' variable with the same name and value.
5433 However, an explicit assignment in the makefile, or with a command
5434 argument, overrides the environment. (If the '-e' flag is specified,
5435 then values from the environment override assignments in the makefile.
5436 *Note Summary of Options: Options Summary. But this is not recommended
5439 Thus, by setting the variable 'CFLAGS' in your environment, you can
5440 cause all C compilations in most makefiles to use the compiler switches
5441 you prefer. This is safe for variables with standard or conventional
5442 meanings because you know that no makefile will use them for other
5443 things. (Note this is not totally reliable; some makefiles set 'CFLAGS'
5444 explicitly and therefore are not affected by the value in the
5447 When 'make' runs a recipe, some variables defined in the makefile are
5448 placed into the environment of each command 'make' invokes. By default,
5449 only variables that came from the 'make''s environment or set on its
5450 command line are placed into the environment of the commands. You can
5451 use the 'export' directive to pass other variables. *Note Communicating
5452 Variables to a Sub-'make': Variables/Recursion, for full details.
5454 Other use of variables from the environment is not recommended. It
5455 is not wise for makefiles to depend for their functioning on environment
5456 variables set up outside their control, since this would cause different
5457 users to get different results from the same makefile. This is against
5458 the whole purpose of most makefiles.
5460 Such problems would be especially likely with the variable 'SHELL',
5461 which is normally present in the environment to specify the user's
5462 choice of interactive shell. It would be very undesirable for this
5463 choice to affect 'make'; so, 'make' handles the 'SHELL' environment
5464 variable in a special way; see *note Choosing the Shell::.
5467 File: make.info, Node: Target-specific, Next: Pattern-specific, Prev: Environment, Up: Using Variables
5469 6.11 Target-specific Variable Values
5470 ====================================
5472 Variable values in 'make' are usually global; that is, they are the same
5473 regardless of where they are evaluated (unless they're reset, of
5474 course). Exceptions to that are variables defined with the 'let'
5475 function (*note Let Function::) or the 'foreach' function (*note Foreach
5476 Function::, and automatic variables (*note Automatic Variables::).
5478 Another exception are "target-specific variable values". This
5479 feature allows you to define different values for the same variable,
5480 based on the target that 'make' is currently building. As with
5481 automatic variables, these values are only available within the context
5482 of a target's recipe (and in other target-specific assignments).
5484 Set a target-specific variable value like this:
5486 TARGET ... : VARIABLE-ASSIGNMENT
5488 Target-specific variable assignments can be prefixed with any or all
5489 of the special keywords 'export', 'unexport', 'override', or 'private';
5490 these apply their normal behavior to this instance of the variable only.
5492 Multiple TARGET values create a target-specific variable value for
5493 each member of the target list individually.
5495 The VARIABLE-ASSIGNMENT can be any valid form of assignment;
5496 recursive ('='), simple (':=' or '::='), immediate ('::='), appending
5497 ('+='), or conditional ('?='). All variables that appear within the
5498 VARIABLE-ASSIGNMENT are evaluated within the context of the target:
5499 thus, any previously-defined target-specific variable values will be in
5500 effect. Note that this variable is actually distinct from any "global"
5501 value: the two variables do not have to have the same flavor (recursive
5504 Target-specific variables have the same priority as any other
5505 makefile variable. Variables provided on the command line (and in the
5506 environment if the '-e' option is in force) will take precedence.
5507 Specifying the 'override' directive will allow the target-specific
5508 variable value to be preferred.
5510 There is one more special feature of target-specific variables: when
5511 you define a target-specific variable that variable value is also in
5512 effect for all prerequisites of this target, and all their
5513 prerequisites, etc. (unless those prerequisites override that variable
5514 with their own target-specific variable value). So, for example, a
5515 statement like this:
5518 prog : prog.o foo.o bar.o
5520 will set 'CFLAGS' to '-g' in the recipe for 'prog', but it will also set
5521 'CFLAGS' to '-g' in the recipes that create 'prog.o', 'foo.o', and
5522 'bar.o', and any recipes which create their prerequisites.
5524 Be aware that a given prerequisite will only be built once per
5525 invocation of make, at most. If the same file is a prerequisite of
5526 multiple targets, and each of those targets has a different value for
5527 the same target-specific variable, then the first target to be built
5528 will cause that prerequisite to be built and the prerequisite will
5529 inherit the target-specific value from the first target. It will ignore
5530 the target-specific values from any other targets.
5533 File: make.info, Node: Pattern-specific, Next: Suppressing Inheritance, Prev: Target-specific, Up: Using Variables
5535 6.12 Pattern-specific Variable Values
5536 =====================================
5538 In addition to target-specific variable values (*note Target-specific
5539 Variable Values: Target-specific.), GNU 'make' supports pattern-specific
5540 variable values. In this form, the variable is defined for any target
5541 that matches the pattern specified.
5543 Set a pattern-specific variable value like this:
5545 PATTERN ... : VARIABLE-ASSIGNMENT
5546 where PATTERN is a %-pattern. As with target-specific variable
5547 values, multiple PATTERN values create a pattern-specific variable value
5548 for each pattern individually. The VARIABLE-ASSIGNMENT can be any valid
5549 form of assignment. Any command line variable setting will take
5550 precedence, unless 'override' is specified.
5556 will assign 'CFLAGS' the value of '-O' for all targets matching the
5559 If a target matches more than one pattern, the matching
5560 pattern-specific variables with longer stems are interpreted first.
5561 This results in more specific variables taking precedence over the more
5562 generic ones, for example:
5565 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@
5567 lib/%.o: CFLAGS := -fPIC -g
5570 all: foo.o lib/bar.o
5572 In this example the first definition of the 'CFLAGS' variable will be
5573 used to update 'lib/bar.o' even though the second one also applies to
5574 this target. Pattern-specific variables which result in the same stem
5575 length are considered in the order in which they were defined in the
5578 Pattern-specific variables are searched after any target-specific
5579 variables defined explicitly for that target, and before target-specific
5580 variables defined for the parent target.
5583 File: make.info, Node: Suppressing Inheritance, Next: Special Variables, Prev: Pattern-specific, Up: Using Variables
5585 6.13 Suppressing Inheritance
5586 ============================
5588 As described in previous sections, 'make' variables are inherited by
5589 prerequisites. This capability allows you to modify the behavior of a
5590 prerequisite based on which targets caused it to be rebuilt. For
5591 example, you might set a target-specific variable on a 'debug' target,
5592 then running 'make debug' will cause that variable to be inherited by
5593 all prerequisites of 'debug', while just running 'make all' (for
5594 example) would not have that assignment.
5596 Sometimes, however, you may not want a variable to be inherited. For
5597 these situations, 'make' provides the 'private' modifier. Although this
5598 modifier can be used with any variable assignment, it makes the most
5599 sense with target- and pattern-specific variables. Any variable marked
5600 'private' will be visible to its local target but will not be inherited
5601 by prerequisites of that target. A global variable marked 'private'
5602 will be visible in the global scope but will not be inherited by any
5603 target, and hence will not be visible in any recipe.
5605 As an example, consider this makefile:
5608 prog: private EXTRA_CFLAGS = -L/usr/local/lib
5611 Due to the 'private' modifier, 'a.o' and 'b.o' will not inherit the
5612 'EXTRA_CFLAGS' variable assignment from the 'prog' target.
5615 File: make.info, Node: Special Variables, Prev: Suppressing Inheritance, Up: Using Variables
5617 6.14 Other Special Variables
5618 ============================
5620 GNU 'make' supports some variables that have special properties.
5623 Contains the name of each makefile that is parsed by 'make', in the
5624 order in which it was parsed. The name is appended just before
5625 'make' begins to parse the makefile. Thus, if the first thing a
5626 makefile does is examine the last word in this variable, it will be
5627 the name of the current makefile. Once the current makefile has
5628 used 'include', however, the last word will be the just-included
5631 If a makefile named 'Makefile' has this content:
5633 name1 := $(lastword $(MAKEFILE_LIST))
5637 name2 := $(lastword $(MAKEFILE_LIST))
5640 @echo name1 = $(name1)
5641 @echo name2 = $(name2)
5643 then you would expect to see this output:
5649 Sets the default goal to be used if no targets were specified on
5650 the command line (*note Arguments to Specify the Goals: Goals.).
5651 The '.DEFAULT_GOAL' variable allows you to discover the current
5652 default goal, restart the default goal selection algorithm by
5653 clearing its value, or to explicitly set the default goal. The
5654 following example illustrates these cases:
5656 # Query the default goal.
5657 ifeq ($(.DEFAULT_GOAL),)
5658 $(warning no default goal is set)
5664 $(warning default goal is $(.DEFAULT_GOAL))
5666 # Reset the default goal.
5672 $(warning default goal is $(.DEFAULT_GOAL))
5675 .DEFAULT_GOAL := foo
5677 This makefile prints:
5679 no default goal is set
5684 Note that assigning more than one target name to '.DEFAULT_GOAL' is
5685 invalid and will result in an error.
5688 This variable is set only if this instance of 'make' has restarted
5689 (*note How Makefiles Are Remade: Remaking Makefiles.): it will
5690 contain the number of times this instance has restarted. Note this
5691 is not the same as recursion (counted by the 'MAKELEVEL' variable).
5692 You should not set, modify, or export this variable.
5696 When 'make' starts it will check whether stdout and stderr will
5697 show their output on a terminal. If so, it will set 'MAKE_TERMOUT'
5698 and 'MAKE_TERMERR', respectively, to the name of the terminal
5699 device (or 'true' if this cannot be determined). If set these
5700 variables will be marked for export. These variables will not be
5701 changed by 'make' and they will not be modified if already set.
5703 These values can be used (particularly in combination with output
5704 synchronization (*note Output During Parallel Execution: Parallel
5705 Output.) to determine whether 'make' itself is writing to a
5706 terminal; they can be tested to decide whether to force recipe
5707 commands to generate colorized output for example.
5709 If you invoke a sub-'make' and redirect its stdout or stderr it is
5710 your responsibility to reset or unexport these variables as well,
5711 if your makefiles rely on them.
5714 The first character of the value of this variable is used as the
5715 character make assumes is introducing a recipe line. If the
5716 variable is empty (as it is by default) that character is the
5717 standard tab character. For example, this is a valid makefile:
5721 > @echo Hello, world
5723 The value of '.RECIPEPREFIX' can be changed multiple times; once
5724 set it stays in effect for all rules parsed until it is modified.
5727 Expands to a list of the _names_ of all global variables defined so
5728 far. This includes variables which have empty values, as well as
5729 built-in variables (*note Variables Used by Implicit Rules:
5730 Implicit Variables.), but does not include any variables which are
5731 only defined in a target-specific context. Note that any value you
5732 assign to this variable will be ignored; it will always return its
5736 Expands to a list of special features supported by this version of
5737 'make'. Possible values include, but are not limited to:
5740 Supports 'ar' (archive) files using special file name syntax.
5741 *Note Using 'make' to Update Archive Files: Archives.
5744 Supports the '-L' ('--check-symlink-times') flag. *Note
5745 Summary of Options: Options Summary.
5748 Supports "else if" non-nested conditionals. *Note Syntax of
5749 Conditionals: Conditional Syntax.
5752 Supports the '.EXTRA_PREREQS' special target.
5755 Supports grouped target syntax for explicit rules. *Note
5756 Multiple Targets in a Rule: Multiple Targets.
5759 Has GNU Guile available as an embedded extension language.
5760 *Note GNU Guile Integration: Guile Integration.
5763 Supports "job server" enhanced parallel builds. *Note
5764 Parallel Execution: Parallel.
5767 Supports "job server" enhanced parallel builds using named
5768 pipes. *Note Integrating GNU 'make': Integrating make.
5771 Supports dynamically loadable objects for creating custom
5772 extensions. *Note Loading Dynamic Objects: Loading Objects.
5775 Supports the '.NOTINTERMEDIATE' special target. *Note
5776 Integrating GNU 'make': Integrating make.
5779 Supports the '.ONESHELL' special target. *Note Using One
5783 Supports order-only prerequisites. *Note Types of
5784 Prerequisites: Prerequisite Types.
5787 Supports the '--output-sync' command line option. *Note
5788 Summary of Options: Options Summary.
5791 Supports secondary expansion of prerequisite lists.
5794 Supports exporting 'make' variables to 'shell' functions.
5797 Uses the "shortest stem" method of choosing which pattern, of
5798 multiple applicable options, will be used. *Note How Patterns
5799 Match: Pattern Match.
5802 Supports target-specific and pattern-specific variable
5803 assignments. *Note Target-specific Variable Values:
5807 Supports the 'undefine' directive. *Note Undefine
5811 Expands to a list of directories that 'make' searches for included
5812 makefiles (*note Including Other Makefiles: Include.). Note that
5813 modifying this variable's value does not change the list of
5814 directories which are searched.
5817 Each word in this variable is a new prerequisite which is added to
5818 targets for which it is set. These prerequisites differ from
5819 normal prerequisites in that they do not appear in any of the
5820 automatic variables (*note Automatic Variables::). This allows
5821 prerequisites to be defined which do not impact the recipe.
5823 Consider a rule to link a program:
5825 myprog: myprog.o file1.o file2.o
5826 $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LDLIBS)
5828 Now suppose you want to enhance this makefile to ensure that
5829 updates to the compiler cause the program to be re-linked. You can
5830 add the compiler as a prerequisite, but you must ensure that it's
5831 not passed as an argument to link command. You'll need something
5834 myprog: myprog.o file1.o file2.o $(CC)
5835 $(CC) $(CFLAGS) $(LDFLAGS) -o $@ \
5836 $(filter-out $(CC),$^) $(LDLIBS)
5838 Then consider having multiple extra prerequisites: they would all
5839 have to be filtered out. Using '.EXTRA_PREREQS' and
5840 target-specific variables provides a simpler solution:
5842 myprog: myprog.o file1.o file2.o
5843 $(CC) $(CFLAGS) $(LDFLAGS) -o $@ $^ $(LDLIBS)
5844 myprog: .EXTRA_PREREQS = $(CC)
5846 This feature can also be useful if you want to add prerequisites to
5847 a makefile you cannot easily modify: you can create a new file such
5850 myprog: .EXTRA_PREREQS = $(CC)
5852 then invoke 'make -f extra.mk -f Makefile'.
5854 Setting '.EXTRA_PREREQS' globally will cause those prerequisites to
5855 be added to all targets (which did not themselves override it with
5856 a target-specific value). Note 'make' is smart enough not to add a
5857 prerequisite listed in '.EXTRA_PREREQS' as a prerequisite to
5861 File: make.info, Node: Conditionals, Next: Functions, Prev: Using Variables, Up: Top
5863 7 Conditional Parts of Makefiles
5864 ********************************
5866 A "conditional" directive causes part of a makefile to be obeyed or
5867 ignored depending on the values of variables. Conditionals can compare
5868 the value of one variable to another, or the value of a variable to a
5869 constant string. Conditionals control what 'make' actually "sees" in
5870 the makefile, so they _cannot_ be used to control recipes at the time of
5875 * Conditional Example:: Example of a conditional
5876 * Conditional Syntax:: The syntax of conditionals.
5877 * Testing Flags:: Conditionals that test flags.
5880 File: make.info, Node: Conditional Example, Next: Conditional Syntax, Prev: Conditionals, Up: Conditionals
5882 7.1 Example of a Conditional
5883 ============================
5885 The following example of a conditional tells 'make' to use one set of
5886 libraries if the 'CC' variable is 'gcc', and a different set of
5887 libraries otherwise. It works by controlling which of two recipe lines
5888 will be used for the rule. The result is that 'CC=gcc' as an argument
5889 to 'make' changes not only which compiler is used but also which
5890 libraries are linked.
5892 libs_for_gcc = -lgnu
5897 $(CC) -o foo $(objects) $(libs_for_gcc)
5899 $(CC) -o foo $(objects) $(normal_libs)
5902 This conditional uses three directives: one 'ifeq', one 'else' and
5905 The 'ifeq' directive begins the conditional, and specifies the
5906 condition. It contains two arguments, separated by a comma and
5907 surrounded by parentheses. Variable substitution is performed on both
5908 arguments and then they are compared. The lines of the makefile
5909 following the 'ifeq' are obeyed if the two arguments match; otherwise
5912 The 'else' directive causes the following lines to be obeyed if the
5913 previous conditional failed. In the example above, this means that the
5914 second alternative linking command is used whenever the first
5915 alternative is not used. It is optional to have an 'else' in a
5918 The 'endif' directive ends the conditional. Every conditional must
5919 end with an 'endif'. Unconditional makefile text follows.
5921 As this example illustrates, conditionals work at the textual level:
5922 the lines of the conditional are treated as part of the makefile, or
5923 ignored, according to the condition. This is why the larger syntactic
5924 units of the makefile, such as rules, may cross the beginning or the end
5927 When the variable 'CC' has the value 'gcc', the above example has
5931 $(CC) -o foo $(objects) $(libs_for_gcc)
5933 When the variable 'CC' has any other value, the effect is this:
5936 $(CC) -o foo $(objects) $(normal_libs)
5938 Equivalent results can be obtained in another way by conditionalizing
5939 a variable assignment and then using the variable unconditionally:
5941 libs_for_gcc = -lgnu
5945 libs=$(libs_for_gcc)
5951 $(CC) -o foo $(objects) $(libs)
5954 File: make.info, Node: Conditional Syntax, Next: Testing Flags, Prev: Conditional Example, Up: Conditionals
5956 7.2 Syntax of Conditionals
5957 ==========================
5959 The syntax of a simple conditional with no 'else' is as follows:
5961 CONDITIONAL-DIRECTIVE
5965 The TEXT-IF-TRUE may be any lines of text, to be considered as part of
5966 the makefile if the condition is true. If the condition is false, no
5967 text is used instead.
5969 The syntax of a complex conditional is as follows:
5971 CONDITIONAL-DIRECTIVE
5979 CONDITIONAL-DIRECTIVE-ONE
5981 else CONDITIONAL-DIRECTIVE-TWO
5984 TEXT-IF-ONE-AND-TWO-ARE-FALSE
5987 There can be as many "'else' CONDITIONAL-DIRECTIVE" clauses as
5988 necessary. Once a given condition is true, TEXT-IF-TRUE is used and no
5989 other clause is used; if no condition is true then TEXT-IF-FALSE is
5990 used. The TEXT-IF-TRUE and TEXT-IF-FALSE can be any number of lines of
5993 The syntax of the CONDITIONAL-DIRECTIVE is the same whether the
5994 conditional is simple or complex; after an 'else' or not. There are
5995 four different directives that test different conditions. Here is a
5999 'ifeq 'ARG1' 'ARG2''
6000 'ifeq "ARG1" "ARG2"'
6001 'ifeq "ARG1" 'ARG2''
6002 'ifeq 'ARG1' "ARG2"'
6003 Expand all variable references in ARG1 and ARG2 and compare them.
6004 If they are identical, the TEXT-IF-TRUE is effective; otherwise,
6005 the TEXT-IF-FALSE, if any, is effective.
6007 Often you want to test if a variable has a non-empty value. When
6008 the value results from complex expansions of variables and
6009 functions, expansions you would consider empty may actually contain
6010 whitespace characters and thus are not seen as empty. However, you
6011 can use the 'strip' function (*note Text Functions::) to avoid
6012 interpreting whitespace as a non-empty value. For example:
6014 ifeq ($(strip $(foo)),)
6018 will evaluate TEXT-IF-EMPTY even if the expansion of '$(foo)'
6019 contains whitespace characters.
6021 'ifneq (ARG1, ARG2)'
6022 'ifneq 'ARG1' 'ARG2''
6023 'ifneq "ARG1" "ARG2"'
6024 'ifneq "ARG1" 'ARG2''
6025 'ifneq 'ARG1' "ARG2"'
6026 Expand all variable references in ARG1 and ARG2 and compare them.
6027 If they are different, the TEXT-IF-TRUE is effective; otherwise,
6028 the TEXT-IF-FALSE, if any, is effective.
6030 'ifdef VARIABLE-NAME'
6031 The 'ifdef' form takes the _name_ of a variable as its argument,
6032 not a reference to a variable. If the value of that variable has a
6033 non-empty value, the TEXT-IF-TRUE is effective; otherwise, the
6034 TEXT-IF-FALSE, if any, is effective. Variables that have never
6035 been defined have an empty value. The text VARIABLE-NAME is
6036 expanded, so it could be a variable or function that expands to the
6037 name of a variable. For example:
6045 The variable reference '$(foo)' is expanded, yielding 'bar', which
6046 is considered to be the name of a variable. The variable 'bar' is
6047 not expanded, but its value is examined to determine if it is
6050 Note that 'ifdef' only tests whether a variable has a value. It
6051 does not expand the variable to see if that value is nonempty.
6052 Consequently, tests using 'ifdef' return true for all definitions
6053 except those like 'foo ='. To test for an empty value, use
6054 'ifeq ($(foo),)'. For example,
6064 sets 'frobozz' to 'yes', while:
6073 sets 'frobozz' to 'no'.
6075 'ifndef VARIABLE-NAME'
6076 If the variable VARIABLE-NAME has an empty value, the TEXT-IF-TRUE
6077 is effective; otherwise, the TEXT-IF-FALSE, if any, is effective.
6078 The rules for expansion and testing of VARIABLE-NAME are identical
6079 to the 'ifdef' directive.
6081 Extra spaces are allowed and ignored at the beginning of the
6082 conditional directive line, but a tab is not allowed. (If the line
6083 begins with a tab, it will be considered part of a recipe for a rule.)
6084 Aside from this, extra spaces or tabs may be inserted with no effect
6085 anywhere except within the directive name or within an argument. A
6086 comment starting with '#' may appear at the end of the line.
6088 The other two directives that play a part in a conditional are 'else'
6089 and 'endif'. Each of these directives is written as one word, with no
6090 arguments. Extra spaces are allowed and ignored at the beginning of the
6091 line, and spaces or tabs at the end. A comment starting with '#' may
6092 appear at the end of the line.
6094 Conditionals affect which lines of the makefile 'make' uses. If the
6095 condition is true, 'make' reads the lines of the TEXT-IF-TRUE as part of
6096 the makefile; if the condition is false, 'make' ignores those lines
6097 completely. It follows that syntactic units of the makefile, such as
6098 rules, may safely be split across the beginning or the end of the
6101 'make' evaluates conditionals when it reads a makefile.
6102 Consequently, you cannot use automatic variables in the tests of
6103 conditionals because they are not defined until recipes are run (*note
6104 Automatic Variables::).
6106 To prevent intolerable confusion, it is not permitted to start a
6107 conditional in one makefile and end it in another. However, you may
6108 write an 'include' directive within a conditional, provided you do not
6109 attempt to terminate the conditional inside the included file.
6112 File: make.info, Node: Testing Flags, Prev: Conditional Syntax, Up: Conditionals
6114 7.3 Conditionals that Test Flags
6115 ================================
6117 You can write a conditional that tests 'make' command flags such as '-t'
6118 by using the variable 'MAKEFLAGS' together with the 'findstring'
6119 function (*note Functions for String Substitution and Analysis: Text
6120 Functions.). This is useful when 'touch' is not enough to make a file
6123 Recall that 'MAKEFLAGS' will put all single-letter options (such as
6124 '-t') into the first word, and that word will be empty if no
6125 single-letter options were given. To work with this, it's helpful to
6126 add a value at the start to ensure there's a word: for example
6129 The 'findstring' function determines whether one string appears as a
6130 substring of another. If you want to test for the '-t' flag, use 't' as
6131 the first string and the first word of 'MAKEFLAGS' as the other.
6133 For example, here is how to arrange to use 'ranlib -t' to finish
6134 marking an archive file up to date:
6137 ifneq (,$(findstring t,$(word 1,-$(MAKEFLAGS))))
6139 +ranlib -t archive.a
6144 The '+' prefix marks those recipe lines as "recursive" so that they will
6145 be executed despite use of the '-t' flag. *Note Recursive Use of
6149 File: make.info, Node: Functions, Next: Running, Prev: Conditionals, Up: Top
6151 8 Functions for Transforming Text
6152 *********************************
6154 "Functions" allow you to do text processing in the makefile to compute
6155 the files to operate on or the commands to use in recipes. You use a
6156 function in a "function call", where you give the name of the function
6157 and some text (the "arguments") for the function to operate on. The
6158 result of the function's processing is substituted into the makefile at
6159 the point of the call, just as a variable might be substituted.
6163 * Syntax of Functions:: How to write a function call.
6164 * Text Functions:: General-purpose text manipulation functions.
6165 * File Name Functions:: Functions for manipulating file names.
6166 * Conditional Functions:: Functions that implement conditions.
6167 * Let Function:: Local variables.
6168 * Foreach Function:: Repeat some text with controlled variation.
6169 * File Function:: Write text to a file.
6170 * Call Function:: Expand a user-defined function.
6171 * Value Function:: Return the un-expanded value of a variable.
6172 * Eval Function:: Evaluate the arguments as makefile syntax.
6173 * Origin Function:: Find where a variable got its value.
6174 * Flavor Function:: Find out the flavor of a variable.
6175 * Make Control Functions:: Functions that control how make runs.
6176 * Shell Function:: Substitute the output of a shell command.
6177 * Guile Function:: Use GNU Guile embedded scripting language.
6180 File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Functions, Up: Functions
6182 8.1 Function Call Syntax
6183 ========================
6185 A function call resembles a variable reference. It can appear anywhere
6186 a variable reference can appear, and it is expanded using the same rules
6187 as variable references. A function call looks like this:
6189 $(FUNCTION ARGUMENTS)
6193 ${FUNCTION ARGUMENTS}
6195 Here FUNCTION is a function name; one of a short list of names that
6196 are part of 'make'. You can also essentially create your own functions
6197 by using the 'call' built-in function.
6199 The ARGUMENTS are the arguments of the function. They are separated
6200 from the function name by one or more spaces or tabs, and if there is
6201 more than one argument, then they are separated by commas. Such
6202 whitespace and commas are not part of an argument's value. The
6203 delimiters which you use to surround the function call, whether
6204 parentheses or braces, can appear in an argument only in matching pairs;
6205 the other kind of delimiters may appear singly. If the arguments
6206 themselves contain other function calls or variable references, it is
6207 wisest to use the same kind of delimiters for all the references; write
6208 '$(subst a,b,$(x))', not '$(subst a,b,${x})'. This is because it is
6209 clearer, and because only one type of delimiter is matched to find the
6210 end of the reference.
6212 Each argument is expanded before the function is invoked, unless
6213 otherwise noted below. The substitution is done in the order in which
6214 the arguments appear.
6219 When using characters that are special to 'make' as function arguments,
6220 you may need to hide them. GNU 'make' doesn't support escaping
6221 characters with backslashes or other escape sequences; however, because
6222 arguments are split before they are expanded you can hide them by
6223 putting them into variables.
6225 Characters you may need to hide include:
6228 * Initial whitespace in the first argument
6229 * Unmatched open parenthesis or brace
6230 * An open parenthesis or brace if you don't want it to start a
6233 For example, you can define variables 'comma' and 'space' whose
6234 values are isolated comma and space characters, then substitute these
6235 variables where such characters are wanted, like this:
6239 space:= $(empty) $(empty)
6241 bar:= $(subst $(space),$(comma),$(foo))
6242 # bar is now 'a,b,c'.
6244 Here the 'subst' function replaces each space with a comma, through the
6245 value of 'foo', and substitutes the result.
6248 File: make.info, Node: Text Functions, Next: File Name Functions, Prev: Syntax of Functions, Up: Functions
6250 8.2 Functions for String Substitution and Analysis
6251 ==================================================
6253 Here are some functions that operate on strings:
6255 '$(subst FROM,TO,TEXT)'
6256 Performs a textual replacement on the text TEXT: each occurrence of
6257 FROM is replaced by TO. The result is substituted for the function
6260 $(subst ee,EE,feet on the street)
6262 produces the value 'fEEt on the strEEt'.
6264 '$(patsubst PATTERN,REPLACEMENT,TEXT)'
6265 Finds whitespace-separated words in TEXT that match PATTERN and
6266 replaces them with REPLACEMENT. Here PATTERN may contain a '%'
6267 which acts as a wildcard, matching any number of any characters
6268 within a word. If REPLACEMENT also contains a '%', the '%' is
6269 replaced by the text that matched the '%' in PATTERN. Words that
6270 do not match the pattern are kept without change in the output.
6271 Only the first '%' in the PATTERN and REPLACEMENT is treated this
6272 way; any subsequent '%' is unchanged.
6274 '%' characters in 'patsubst' function invocations can be quoted
6275 with preceding backslashes ('\'). Backslashes that would otherwise
6276 quote '%' characters can be quoted with more backslashes.
6277 Backslashes that quote '%' characters or other backslashes are
6278 removed from the pattern before it is compared file names or has a
6279 stem substituted into it. Backslashes that are not in danger of
6280 quoting '%' characters go unmolested. For example, the pattern
6281 'the\%weird\\%pattern\\' has 'the%weird\' preceding the operative
6282 '%' character, and 'pattern\\' following it. The final two
6283 backslashes are left alone because they cannot affect any '%'
6286 Whitespace between words is folded into single space characters;
6287 leading and trailing whitespace is discarded.
6291 $(patsubst %.c,%.o,x.c.c bar.c)
6293 produces the value 'x.c.o bar.o'.
6295 Substitution references (*note Substitution References:
6296 Substitution Refs.) are a simpler way to get the effect of the
6297 'patsubst' function:
6299 $(VAR:PATTERN=REPLACEMENT)
6303 $(patsubst PATTERN,REPLACEMENT,$(VAR))
6305 The second shorthand simplifies one of the most common uses of
6306 'patsubst': replacing the suffix at the end of file names.
6308 $(VAR:SUFFIX=REPLACEMENT)
6312 $(patsubst %SUFFIX,%REPLACEMENT,$(VAR))
6314 For example, you might have a list of object files:
6316 objects = foo.o bar.o baz.o
6318 To get the list of corresponding source files, you could simply
6323 instead of using the general form:
6325 $(patsubst %.o,%.c,$(objects))
6328 Removes leading and trailing whitespace from STRING and replaces
6329 each internal sequence of one or more whitespace characters with a
6330 single space. Thus, '$(strip a b c )' results in 'a b c'.
6332 The function 'strip' can be very useful when used in conjunction
6333 with conditionals. When comparing something with the empty string
6334 '' using 'ifeq' or 'ifneq', you usually want a string of just
6335 whitespace to match the empty string (*note Conditionals::).
6337 Thus, the following may fail to have the desired results:
6340 ifneq "$(needs_made)" ""
6343 all:;@echo 'Nothing to make!'
6346 Replacing the variable reference '$(needs_made)' with the function
6347 call '$(strip $(needs_made))' in the 'ifneq' directive would make
6350 '$(findstring FIND,IN)'
6351 Searches IN for an occurrence of FIND. If it occurs, the value is
6352 FIND; otherwise, the value is empty. You can use this function in
6353 a conditional to test for the presence of a specific substring in a
6354 given string. Thus, the two examples,
6356 $(findstring a,a b c)
6359 produce the values 'a' and '' (the empty string), respectively.
6360 *Note Testing Flags::, for a practical application of 'findstring'.
6362 '$(filter PATTERN...,TEXT)'
6363 Returns all whitespace-separated words in TEXT that _do_ match any
6364 of the PATTERN words, removing any words that _do not_ match. The
6365 patterns are written using '%', just like the patterns used in the
6366 'patsubst' function above.
6368 The 'filter' function can be used to separate out different types
6369 of strings (such as file names) in a variable. For example:
6371 sources := foo.c bar.c baz.s ugh.h
6373 cc $(filter %.c %.s,$(sources)) -o foo
6375 says that 'foo' depends of 'foo.c', 'bar.c', 'baz.s' and 'ugh.h'
6376 but only 'foo.c', 'bar.c' and 'baz.s' should be specified in the
6377 command to the compiler.
6379 '$(filter-out PATTERN...,TEXT)'
6380 Returns all whitespace-separated words in TEXT that _do not_ match
6381 any of the PATTERN words, removing the words that _do_ match one or
6382 more. This is the exact opposite of the 'filter' function.
6386 objects=main1.o foo.o main2.o bar.o
6387 mains=main1.o main2.o
6389 the following generates a list which contains all the object files
6392 $(filter-out $(mains),$(objects))
6395 Sorts the words of LIST in lexical order, removing duplicate words.
6396 The output is a list of words separated by single spaces. Thus,
6398 $(sort foo bar lose)
6400 returns the value 'bar foo lose'.
6402 Incidentally, since 'sort' removes duplicate words, you can use it
6403 for this purpose even if you don't care about the sort order.
6406 Returns the Nth word of TEXT. The legitimate values of N start
6407 from 1. If N is bigger than the number of words in TEXT, the value
6408 is empty. For example,
6410 $(word 2, foo bar baz)
6414 '$(wordlist S,E,TEXT)'
6415 Returns the list of words in TEXT starting with word S and ending
6416 with word E (inclusive). The legitimate values of S start from 1;
6417 E may start from 0. If S is bigger than the number of words in
6418 TEXT, the value is empty. If E is bigger than the number of words
6419 in TEXT, words up to the end of TEXT are returned. If S is greater
6420 than E, nothing is returned. For example,
6422 $(wordlist 2, 3, foo bar baz)
6427 Returns the number of words in TEXT. Thus, the last word of TEXT
6428 is '$(word $(words TEXT),TEXT)'.
6430 '$(firstword NAMES...)'
6431 The argument NAMES is regarded as a series of names, separated by
6432 whitespace. The value is the first name in the series. The rest
6433 of the names are ignored.
6437 $(firstword foo bar)
6439 produces the result 'foo'. Although '$(firstword TEXT)' is the
6440 same as '$(word 1,TEXT)', the 'firstword' function is retained for
6443 '$(lastword NAMES...)'
6444 The argument NAMES is regarded as a series of names, separated by
6445 whitespace. The value is the last name in the series.
6451 produces the result 'bar'. Although '$(lastword TEXT)' is the same
6452 as '$(word $(words TEXT),TEXT)', the 'lastword' function was added
6453 for its simplicity and better performance.
6455 Here is a realistic example of the use of 'subst' and 'patsubst'.
6456 Suppose that a makefile uses the 'VPATH' variable to specify a list of
6457 directories that 'make' should search for prerequisite files (*note
6458 'VPATH' Search Path for All Prerequisites: General Search.). This
6459 example shows how to tell the C compiler to search for header files in
6460 the same list of directories.
6462 The value of 'VPATH' is a list of directories separated by colons,
6463 such as 'src:../headers'. First, the 'subst' function is used to change
6464 the colons to spaces:
6466 $(subst :, ,$(VPATH))
6468 This produces 'src ../headers'. Then 'patsubst' is used to turn each
6469 directory name into a '-I' flag. These can be added to the value of the
6470 variable 'CFLAGS', which is passed automatically to the C compiler, like
6473 override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
6475 The effect is to append the text '-Isrc -I../headers' to the previously
6476 given value of 'CFLAGS'. The 'override' directive is used so that the
6477 new value is assigned even if the previous value of 'CFLAGS' was
6478 specified with a command argument (*note The 'override' Directive:
6479 Override Directive.).
6482 File: make.info, Node: File Name Functions, Next: Conditional Functions, Prev: Text Functions, Up: Functions
6484 8.3 Functions for File Names
6485 ============================
6487 Several of the built-in expansion functions relate specifically to
6488 taking apart file names or lists of file names.
6490 Each of the following functions performs a specific transformation on
6491 a file name. The argument of the function is regarded as a series of
6492 file names, separated by whitespace. (Leading and trailing whitespace
6493 is ignored.) Each file name in the series is transformed in the same
6494 way and the results are concatenated with single spaces between them.
6497 Extracts the directory-part of each file name in NAMES. The
6498 directory-part of the file name is everything up through (and
6499 including) the last slash in it. If the file name contains no
6500 slash, the directory part is the string './'. For example,
6502 $(dir src/foo.c hacks)
6504 produces the result 'src/ ./'.
6506 '$(notdir NAMES...)'
6507 Extracts all but the directory-part of each file name in NAMES. If
6508 the file name contains no slash, it is left unchanged. Otherwise,
6509 everything through the last slash is removed from it.
6511 A file name that ends with a slash becomes an empty string. This
6512 is unfortunate, because it means that the result does not always
6513 have the same number of whitespace-separated file names as the
6514 argument had; but we do not see any other valid alternative.
6518 $(notdir src/foo.c hacks)
6520 produces the result 'foo.c hacks'.
6522 '$(suffix NAMES...)'
6523 Extracts the suffix of each file name in NAMES. If the file name
6524 contains a period, the suffix is everything starting with the last
6525 period. Otherwise, the suffix is the empty string. This
6526 frequently means that the result will be empty when NAMES is not,
6527 and if NAMES contains multiple file names, the result may contain
6532 $(suffix src/foo.c src-1.0/bar.c hacks)
6534 produces the result '.c .c'.
6536 '$(basename NAMES...)'
6537 Extracts all but the suffix of each file name in NAMES. If the
6538 file name contains a period, the basename is everything starting up
6539 to (and not including) the last period. Periods in the directory
6540 part are ignored. If there is no period, the basename is the
6541 entire file name. For example,
6543 $(basename src/foo.c src-1.0/bar hacks)
6545 produces the result 'src/foo src-1.0/bar hacks'.
6547 '$(addsuffix SUFFIX,NAMES...)'
6548 The argument NAMES is regarded as a series of names, separated by
6549 whitespace; SUFFIX is used as a unit. The value of SUFFIX is
6550 appended to the end of each individual name and the resulting
6551 larger names are concatenated with single spaces between them. For
6554 $(addsuffix .c,foo bar)
6556 produces the result 'foo.c bar.c'.
6558 '$(addprefix PREFIX,NAMES...)'
6559 The argument NAMES is regarded as a series of names, separated by
6560 whitespace; PREFIX is used as a unit. The value of PREFIX is
6561 prepended to the front of each individual name and the resulting
6562 larger names are concatenated with single spaces between them. For
6565 $(addprefix src/,foo bar)
6567 produces the result 'src/foo src/bar'.
6569 '$(join LIST1,LIST2)'
6570 Concatenates the two arguments word by word: the two first words
6571 (one from each argument) concatenated form the first word of the
6572 result, the two second words form the second word of the result,
6573 and so on. So the Nth word of the result comes from the Nth word
6574 of each argument. If one argument has more words that the other,
6575 the extra words are copied unchanged into the result.
6577 For example, '$(join a b,.c .o)' produces 'a.c b.o'.
6579 Whitespace between the words in the lists is not preserved; it is
6580 replaced with a single space.
6582 This function can merge the results of the 'dir' and 'notdir'
6583 functions, to produce the original list of files which was given to
6584 those two functions.
6586 '$(wildcard PATTERN)'
6587 The argument PATTERN is a file name pattern, typically containing
6588 wildcard characters (as in shell file name patterns). The result
6589 of 'wildcard' is a space-separated list of the names of existing
6590 files that match the pattern. *Note Using Wildcard Characters in
6591 File Names: Wildcards.
6593 '$(realpath NAMES...)'
6594 For each file name in NAMES return the canonical absolute name. A
6595 canonical name does not contain any '.' or '..' components, nor any
6596 repeated path separators ('/') or symlinks. In case of a failure
6597 the empty string is returned. Consult the 'realpath(3)'
6598 documentation for a list of possible failure causes.
6600 '$(abspath NAMES...)'
6601 For each file name in NAMES return an absolute name that does not
6602 contain any '.' or '..' components, nor any repeated path
6603 separators ('/'). Note that, in contrast to 'realpath' function,
6604 'abspath' does not resolve symlinks and does not require the file
6605 names to refer to an existing file or directory. Use the
6606 'wildcard' function to test for existence.
6609 File: make.info, Node: Conditional Functions, Next: Let Function, Prev: File Name Functions, Up: Functions
6611 8.4 Functions for Conditionals
6612 ==============================
6614 There are four functions that provide conditional expansion. A key
6615 aspect of these functions is that not all of the arguments are expanded
6616 initially. Only those arguments which need to be expanded, will be
6619 '$(if CONDITION,THEN-PART[,ELSE-PART])'
6620 The 'if' function provides support for conditional expansion in a
6621 functional context (as opposed to the GNU 'make' makefile
6622 conditionals such as 'ifeq' (*note Syntax of Conditionals:
6623 Conditional Syntax.)).
6625 The first argument, CONDITION, first has all preceding and trailing
6626 whitespace stripped, then is expanded. If it expands to any
6627 non-empty string, then the condition is considered to be true. If
6628 it expands to an empty string, the condition is considered to be
6631 If the condition is true then the second argument, THEN-PART, is
6632 evaluated and this is used as the result of the evaluation of the
6633 entire 'if' function.
6635 If the condition is false then the third argument, ELSE-PART, is
6636 evaluated and this is the result of the 'if' function. If there is
6637 no third argument, the 'if' function evaluates to nothing (the
6640 Note that only one of the THEN-PART or the ELSE-PART will be
6641 evaluated, never both. Thus, either can contain side-effects (such
6642 as 'shell' function calls, etc.)
6644 '$(or CONDITION1[,CONDITION2[,CONDITION3...]])'
6645 The 'or' function provides a "short-circuiting" OR operation. Each
6646 argument is expanded, in order. If an argument expands to a
6647 non-empty string the processing stops and the result of the
6648 expansion is that string. If, after all arguments are expanded,
6649 all of them are false (empty), then the result of the expansion is
6652 '$(and CONDITION1[,CONDITION2[,CONDITION3...]])'
6653 The 'and' function provides a "short-circuiting" AND operation.
6654 Each argument is expanded, in order. If an argument expands to an
6655 empty string the processing stops and the result of the expansion
6656 is the empty string. If all arguments expand to a non-empty string
6657 then the result of the expansion is the expansion of the last
6660 '$(intcmp LHS,RHS[,LT-PART[,EQ-PART[,GT-PART]]])'
6661 The 'intcmp' function provides support for numerical comparison of
6662 integers. This function has no counterpart among the GNU 'make'
6663 makefile conditionals.
6665 The left-hand side, LHS, and right-hand side, RHS, are expanded and
6666 parsed as integral numbers in base 10. Expansion of the remaining
6667 arguments is controlled by how the numerical left-hand side
6668 compares to the numerical right-hand side.
6670 If there are no further arguments, then the function expands to
6671 empty if the left-hand side and right-hand side do not compare
6672 equal, or to their numerical value if they do compare equal.
6674 Else if the left-hand side is strictly less than the right-hand
6675 side, the 'intcmp' function evaluates to the expansion of the third
6676 argument, LT-PART. If both sides compare equal, then the 'intcmp'
6677 function evaluates to the expansion of the fourth argument,
6678 EQ-PART. If the left-hand side is strictly greater than the
6679 right-hand side, then the 'intcmp' function evaluates to the
6680 expansion of the fifth argument, GT-PART.
6682 If GT-PART is missing, it defaults to EQ-PART. If EQ-PART is
6683 missing, it defaults to the empty string. Thus both '$(intcmp
6684 9,7,hello)' and '$(intcmp 9,7,hello,world,)' evaluate to the empty
6685 string, while '$(intcmp 9,7,hello,world)' (notice the absence of a
6686 comma after 'world') evaluates to 'world'.
6689 File: make.info, Node: Let Function, Next: Foreach Function, Prev: Conditional Functions, Up: Functions
6691 8.5 The 'let' Function
6692 ======================
6694 The 'let' function provides a means to limit the scope of a variable.
6695 The assignment of the named variables in a 'let' expression is in effect
6696 only within the text provided by the 'let' expression, and this
6697 assignment doesn't impact that named variable in any outer scope.
6699 Additionally, the 'let' function enables list unpacking by assigning
6700 all unassigned values to the last named variable.
6702 The syntax of the 'let' function is:
6704 $(let VAR [VAR ...],[LIST],TEXT)
6706 The first two arguments, VAR and LIST, are expanded before anything else
6707 is done; note that the last argument, TEXT, is *not* expanded at the
6708 same time. Next, each word of the expanded value of LIST is bound to
6709 each of the variable names, VAR, in turn, with the final variable name
6710 being bound to the remainder of the expanded LIST. In other words, the
6711 first word of LIST is bound to the first variable VAR, the second word
6712 to the second variable VAR, and so on.
6714 If there are more variable names in VAR than there are words in LIST,
6715 the remaining VAR variable names are set to the empty string. If there
6716 are fewer VARs than words in LIST then the last VAR is set to all
6717 remaining words in LIST.
6719 The variables in VAR are assigned as simply-expanded variables during
6720 the execution of 'let'. *Note The Two Flavors of Variables: Flavors.
6722 After all variables are thus bound, TEXT is expanded to provide the
6723 result of the 'let' function.
6725 For example, this macro reverses the order of the words in the list
6726 that it is given as its first argument:
6728 reverse = $(let first rest,$1,\
6729 $(if $(rest),$(call reverse,$(rest)) )$(first))
6731 all: ; @echo $(call reverse,d c b a)
6733 will print 'a b c d'. When first called, 'let' will expand $1 to 'd c b
6734 a'. It will then assign FIRST to 'd' and assign REST to 'c b a'. It
6735 will then expand the if-statement, where '$(rest)' is not empty so we
6736 recursively invoke the REVERSE function with the value of REST which is
6737 now 'c b a'. The recursive invocation of 'let' assigns FIRST to 'c' and
6738 REST to 'b a'. The recursion continues until 'let' is called with just
6739 a single value, 'a'. Here FIRST is 'a' and REST is empty, so we do not
6740 recurse but simply expand '$(first)' to 'a' and return, which adds ' b',
6743 After the REVERSE call is complete, the FIRST and REST variables are
6744 no longer set. If variables by those names existed beforehand, they are
6745 not affected by the expansion of the 'reverse' macro.
6748 File: make.info, Node: Foreach Function, Next: File Function, Prev: Let Function, Up: Functions
6750 8.6 The 'foreach' Function
6751 ==========================
6753 The 'foreach' function is similar to the 'let' function, but very
6754 different from other functions. It causes one piece of text to be used
6755 repeatedly, each time with a different substitution performed on it.
6756 The 'foreach' function resembles the 'for' command in the shell 'sh' and
6757 the 'foreach' command in the C-shell 'csh'.
6759 The syntax of the 'foreach' function is:
6761 $(foreach VAR,LIST,TEXT)
6763 The first two arguments, VAR and LIST, are expanded before anything else
6764 is done; note that the last argument, TEXT, is *not* expanded at the
6765 same time. Then for each word of the expanded value of LIST, the
6766 variable named by the expanded value of VAR is set to that word, and
6767 TEXT is expanded. Presumably TEXT contains references to that variable,
6768 so its expansion will be different each time.
6770 The result is that TEXT is expanded as many times as there are
6771 whitespace-separated words in LIST. The multiple expansions of TEXT are
6772 concatenated, with spaces between them, to make the result of 'foreach'.
6774 This simple example sets the variable 'files' to the list of all
6775 files in the directories in the list 'dirs':
6778 files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
6780 Here TEXT is '$(wildcard $(dir)/*)'. The first repetition finds the
6781 value 'a' for 'dir', so it produces the same result as '$(wildcard
6782 a/*)'; the second repetition produces the result of '$(wildcard b/*)';
6783 and the third, that of '$(wildcard c/*)'.
6785 This example has the same result (except for setting 'dirs') as the
6788 files := $(wildcard a/* b/* c/* d/*)
6790 When TEXT is complicated, you can improve readability by giving it a
6791 name, with an additional variable:
6793 find_files = $(wildcard $(dir)/*)
6795 files := $(foreach dir,$(dirs),$(find_files))
6797 Here we use the variable 'find_files' this way. We use plain '=' to
6798 define a recursively-expanding variable, so that its value contains an
6799 actual function call to be re-expanded under the control of 'foreach'; a
6800 simply-expanded variable would not do, since 'wildcard' would be called
6801 only once at the time of defining 'find_files'.
6803 Like the 'let' function, the 'foreach' function has no permanent
6804 effect on the variable VAR; its value and flavor after the 'foreach'
6805 function call are the same as they were beforehand. The other values
6806 which are taken from LIST are in effect only temporarily, during the
6807 execution of 'foreach'. The variable VAR is a simply-expanded variable
6808 during the execution of 'foreach'. If VAR was undefined before the
6809 'foreach' function call, it is undefined after the call. *Note The Two
6810 Flavors of Variables: Flavors.
6812 You must take care when using complex variable expressions that
6813 result in variable names because many strange things are valid variable
6814 names, but are probably not what you intended. For example,
6816 files := $(foreach Esta-escrito-en-espanol!,b c ch,$(find_files))
6818 might be useful if the value of 'find_files' references the variable
6819 whose name is 'Esta-escrito-en-espanol!' (es un nombre bastante largo,
6820 no?), but it is more likely to be a mistake.
6823 File: make.info, Node: File Function, Next: Call Function, Prev: Foreach Function, Up: Functions
6825 8.7 The 'file' Function
6826 =======================
6828 The 'file' function allows the makefile to write to or read from a file.
6829 Two modes of writing are supported: overwrite, where the text is written
6830 to the beginning of the file and any existing content is lost, and
6831 append, where the text is written to the end of the file, preserving the
6832 existing content. In both cases the file is created if it does not
6833 exist. It is a fatal error if the file cannot be opened for writing, or
6834 if the write operation fails. The 'file' function expands to the empty
6835 string when writing to a file.
6837 When reading from a file, the 'file' function expands to the verbatim
6838 contents of the file, except that the final newline (if there is one)
6839 will be stripped. Attempting to read from a non-existent file expands
6840 to the empty string.
6842 The syntax of the 'file' function is:
6844 $(file OP FILENAME[,TEXT])
6846 When the 'file' function is evaluated all its arguments are expanded
6847 first, then the file indicated by FILENAME will be opened in the mode
6850 The operator OP can be '>' to indicate the file will be overwritten
6851 with new content, '>>' to indicate the current contents of the file will
6852 be appended to, or '<' to indicate the contents of the file will be read
6853 in. The FILENAME specifies the file to be written to or read from.
6854 There may optionally be whitespace between the operator and the file
6857 When reading files, it is an error to provide a TEXT value.
6859 When writing files, TEXT will be written to the file. If TEXT does
6860 not already end in a newline a final newline will be written (even if
6861 TEXT is the empty string). If the TEXT argument is not given at all,
6862 nothing will be written.
6864 For example, the 'file' function can be useful if your build system
6865 has a limited command line size and your recipe runs a command that can
6866 accept arguments from a file as well. Many commands use the convention
6867 that an argument prefixed with an '@' specifies a file containing more
6868 arguments. Then you might write your recipe in this way:
6872 $(CMD) $(CMDFLAGS) @$@.in
6875 If the command required each argument to be on a separate line of the
6876 input file, you might write your recipe like this:
6879 $(file >$@.in) $(foreach O,$^,$(file >>$@.in,$O))
6880 $(CMD) $(CMDFLAGS) @$@.in
6884 File: make.info, Node: Call Function, Next: Value Function, Prev: File Function, Up: Functions
6886 8.8 The 'call' Function
6887 =======================
6889 The 'call' function is unique in that it can be used to create new
6890 parameterized functions. You can write a complex expression as the
6891 value of a variable, then use 'call' to expand it with different values.
6893 The syntax of the 'call' function is:
6895 $(call VARIABLE,PARAM,PARAM,...)
6897 When 'make' expands this function, it assigns each PARAM to temporary
6898 variables '$(1)', '$(2)', etc. The variable '$(0)' will contain
6899 VARIABLE. There is no maximum number of parameter arguments. There is
6900 no minimum, either, but it doesn't make sense to use 'call' with no
6903 Then VARIABLE is expanded as a 'make' variable in the context of
6904 these temporary assignments. Thus, any reference to '$(1)' in the value
6905 of VARIABLE will resolve to the first PARAM in the invocation of 'call'.
6907 Note that VARIABLE is the _name_ of a variable, not a _reference_ to
6908 that variable. Therefore you would not normally use a '$' or
6909 parentheses when writing it. (You can, however, use a variable
6910 reference in the name if you want the name not to be a constant.)
6912 If VARIABLE is the name of a built-in function, the built-in function
6913 is always invoked (even if a 'make' variable by that name also exists).
6915 The 'call' function expands the PARAM arguments before assigning them
6916 to temporary variables. This means that VARIABLE values containing
6917 references to built-in functions that have special expansion rules, like
6918 'foreach' or 'if', may not work as you expect.
6920 Some examples may make this clearer.
6922 This macro simply reverses its arguments:
6926 foo = $(call reverse,a,b)
6928 Here 'foo' will contain 'b a'.
6930 This one is slightly more interesting: it defines a macro to search
6931 for the first instance of a program in 'PATH':
6933 pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
6935 LS := $(call pathsearch,ls)
6937 Now the variable 'LS' contains '/bin/ls' or similar.
6939 The 'call' function can be nested. Each recursive invocation gets
6940 its own local values for '$(1)', etc. that mask the values of
6941 higher-level 'call'. For example, here is an implementation of a "map"
6944 map = $(foreach a,$(2),$(call $(1),$(a)))
6946 Now you can 'map' a function that normally takes only one argument,
6947 such as 'origin', to multiple values in one step:
6949 o = $(call map,origin,o map MAKE)
6951 and end up with 'o' containing something like 'file file default'.
6953 A final caution: be careful when adding whitespace to the arguments
6954 to 'call'. As with other functions, any whitespace contained in the
6955 second and subsequent arguments is kept; this can cause strange effects.
6956 It's generally safest to remove all extraneous whitespace when providing
6957 parameters to 'call'.
6960 File: make.info, Node: Value Function, Next: Eval Function, Prev: Call Function, Up: Functions
6962 8.9 The 'value' Function
6963 ========================
6965 The 'value' function provides a way for you to use the value of a
6966 variable _without_ having it expanded. Please note that this does not
6967 undo expansions which have already occurred; for example if you create a
6968 simply expanded variable its value is expanded during the definition; in
6969 that case the 'value' function will return the same result as using the
6972 The syntax of the 'value' function is:
6976 Note that VARIABLE is the _name_ of a variable, not a _reference_ to
6977 that variable. Therefore you would not normally use a '$' or
6978 parentheses when writing it. (You can, however, use a variable
6979 reference in the name if you want the name not to be a constant.)
6981 The result of this function is a string containing the value of
6982 VARIABLE, without any expansion occurring. For example, in this
6991 The first output line would be 'ATH', since the "$P" would be expanded
6992 as a 'make' variable, while the second output line would be the current
6993 value of your '$PATH' environment variable, since the 'value' function
6994 avoided the expansion.
6996 The 'value' function is most often used in conjunction with the
6997 'eval' function (*note Eval Function::).
7000 File: make.info, Node: Eval Function, Next: Origin Function, Prev: Value Function, Up: Functions
7002 8.10 The 'eval' Function
7003 ========================
7005 The 'eval' function is very special: it allows you to define new
7006 makefile constructs that are not constant; which are the result of
7007 evaluating other variables and functions. The argument to the 'eval'
7008 function is expanded, then the results of that expansion are parsed as
7009 makefile syntax. The expanded results can define new 'make' variables,
7010 targets, implicit or explicit rules, etc.
7012 The result of the 'eval' function is always the empty string; thus,
7013 it can be placed virtually anywhere in a makefile without causing syntax
7016 It's important to realize that the 'eval' argument is expanded
7017 _twice_; first by the 'eval' function, then the results of that
7018 expansion are expanded again when they are parsed as makefile syntax.
7019 This means you may need to provide extra levels of escaping for "$"
7020 characters when using 'eval'. The 'value' function (*note Value
7021 Function::) can sometimes be useful in these situations, to circumvent
7022 unwanted expansions.
7024 Here is an example of how 'eval' can be used; this example combines a
7025 number of concepts and other functions. Although it might seem overly
7026 complex to use 'eval' in this example, rather than just writing out the
7027 rules, consider two things: first, the template definition (in
7028 'PROGRAM_template') could need to be much more complex than it is here;
7029 and second, you might put the complex, "generic" part of this example
7030 into another makefile, then include it in all the individual makefiles.
7031 Now your individual makefiles are quite straightforward.
7033 PROGRAMS = server client
7035 server_OBJS = server.o server_priv.o server_access.o
7036 server_LIBS = priv protocol
7038 client_OBJS = client.o client_api.o client_mem.o
7039 client_LIBS = protocol
7041 # Everything after this is generic
7046 define PROGRAM_template =
7047 $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
7048 ALL_OBJS += $$($(1)_OBJS)
7051 $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
7054 $(LINK.o) $^ $(LDLIBS) -o $@
7057 rm -f $(ALL_OBJS) $(PROGRAMS)
7060 File: make.info, Node: Origin Function, Next: Flavor Function, Prev: Eval Function, Up: Functions
7062 8.11 The 'origin' Function
7063 ==========================
7065 The 'origin' function is unlike most other functions in that it does not
7066 operate on the values of variables; it tells you something _about_ a
7067 variable. Specifically, it tells you where it came from.
7069 The syntax of the 'origin' function is:
7073 Note that VARIABLE is the _name_ of a variable to inquire about, not
7074 a _reference_ to that variable. Therefore you would not normally use a
7075 '$' or parentheses when writing it. (You can, however, use a variable
7076 reference in the name if you want the name not to be a constant.)
7078 The result of this function is a string telling you how the variable
7079 VARIABLE was defined:
7083 if VARIABLE was never defined.
7087 if VARIABLE has a default definition, as is usual with 'CC' and so
7088 on. *Note Variables Used by Implicit Rules: Implicit Variables.
7089 Note that if you have redefined a default variable, the 'origin'
7090 function will return the origin of the later definition.
7094 if VARIABLE was inherited from the environment provided to 'make'.
7096 'environment override'
7098 if VARIABLE was inherited from the environment provided to 'make',
7099 and is overriding a setting for VARIABLE in the makefile as a
7100 result of the '-e' option (*note Summary of Options: Options
7105 if VARIABLE was defined in a makefile.
7109 if VARIABLE was defined on the command line.
7113 if VARIABLE was defined with an 'override' directive in a makefile
7114 (*note The 'override' Directive: Override Directive.).
7118 if VARIABLE is an automatic variable defined for the execution of
7119 the recipe for each rule (*note Automatic Variables::).
7121 This information is primarily useful (other than for your curiosity)
7122 to determine if you want to believe the value of a variable. For
7123 example, suppose you have a makefile 'foo' that includes another
7124 makefile 'bar'. You want a variable 'bletch' to be defined in 'bar' if
7125 you run the command 'make -f bar', even if the environment contains a
7126 definition of 'bletch'. However, if 'foo' defined 'bletch' before
7127 including 'bar', you do not want to override that definition. This
7128 could be done by using an 'override' directive in 'foo', giving that
7129 definition precedence over the later definition in 'bar'; unfortunately,
7130 the 'override' directive would also override any command line
7131 definitions. So, 'bar' could include:
7134 ifeq "$(origin bletch)" "environment"
7135 bletch = barf, gag, etc.
7139 If 'bletch' has been defined from the environment, this will redefine
7142 If you want to override a previous definition of 'bletch' if it came
7143 from the environment, even under '-e', you could instead write:
7145 ifneq "$(findstring environment,$(origin bletch))" ""
7146 bletch = barf, gag, etc.
7149 Here the redefinition takes place if '$(origin bletch)' returns
7150 either 'environment' or 'environment override'. *Note Functions for
7151 String Substitution and Analysis: Text Functions.
7154 File: make.info, Node: Flavor Function, Next: Make Control Functions, Prev: Origin Function, Up: Functions
7156 8.12 The 'flavor' Function
7157 ==========================
7159 The 'flavor' function, like the 'origin' function, does not operate on
7160 the values of variables but rather it tells you something _about_ a
7161 variable. Specifically, it tells you the flavor of a variable (*note
7162 The Two Flavors of Variables: Flavors.).
7164 The syntax of the 'flavor' function is:
7168 Note that VARIABLE is the _name_ of a variable to inquire about, not
7169 a _reference_ to that variable. Therefore you would not normally use a
7170 '$' or parentheses when writing it. (You can, however, use a variable
7171 reference in the name if you want the name not to be a constant.)
7173 The result of this function is a string that identifies the flavor of
7174 the variable VARIABLE:
7178 if VARIABLE was never defined.
7182 if VARIABLE is a recursively expanded variable.
7186 if VARIABLE is a simply expanded variable.
7189 File: make.info, Node: Make Control Functions, Next: Shell Function, Prev: Flavor Function, Up: Functions
7191 8.13 Functions That Control Make
7192 ================================
7194 These functions control the way make runs. Generally, they are used to
7195 provide information to the user of the makefile or to cause make to stop
7196 if some sort of environmental error is detected.
7199 Generates a fatal error where the message is TEXT. Note that the
7200 error is generated whenever this function is evaluated. So, if you
7201 put it inside a recipe or on the right side of a recursive variable
7202 assignment, it won't be evaluated until later. The TEXT will be
7203 expanded before the error is generated.
7208 $(error error is $(ERROR1))
7211 will generate a fatal error during the read of the makefile if the
7212 'make' variable 'ERROR1' is defined. Or,
7214 ERR = $(error found an error!)
7219 will generate a fatal error while 'make' is running, if the 'err'
7222 '$(warning TEXT...)'
7223 This function works similarly to the 'error' function, above,
7224 except that 'make' doesn't exit. Instead, TEXT is expanded and the
7225 resulting message is displayed, but processing of the makefile
7228 The result of the expansion of this function is the empty string.
7231 This function does nothing more than print its (expanded)
7232 argument(s) to standard output. No makefile name or line number is
7233 added. The result of the expansion of this function is the empty
projects / platform / upstream / make.git / blob