Home | History | Annotate | Download | only in doc
      1 This is
      2 /usr/local/google/digit/repo/opensource/ndk/sources/host-tools/make-3.81/doc/make.info,
      3 produced by makeinfo version 4.13 from
      4 /usr/local/google/digit/repo/opensource/ndk/sources/host-tools/make-3.81/doc/make.texi.
      5 
      6 This file documents the GNU `make' utility, which determines
      7 automatically which pieces of a large program need to be recompiled,
      8 and issues the commands to recompile them.
      9 
     10    This is Edition 0.70, last updated 13 October 2011, of `The GNU Make
     11 Manual', for GNU `make' version 3.81.
     12 
     13    Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
     14 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
     15 Foundation, Inc.
     16 
     17      Permission is granted to copy, distribute and/or modify this
     18      document under the terms of the GNU Free Documentation License,
     19      Version 1.2 or any later version published by the Free Software
     20      Foundation; with no Invariant Sections, with the Front-Cover Texts
     21      being "A GNU Manual," and with the Back-Cover Texts as in (a)
     22      below.  A copy of the license is included in the section entitled
     23      "GNU Free Documentation License."
     24 
     25      (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     26      modify this GNU Manual, like GNU software.  Copies published by
     27      the Free Software Foundation raise funds for GNU development."
     28 
     29 INFO-DIR-SECTION GNU Packages
     30 START-INFO-DIR-ENTRY
     31 * Make: (make).            Remake files automatically.
     32 END-INFO-DIR-ENTRY
     33 
     34 
     35 File: make.info,  Node: Top,  Next: Overview,  Prev: (dir),  Up: (dir)
     36 
     37 GNU `make'
     38 **********
     39 
     40 This file documents the GNU `make' utility, which determines
     41 automatically which pieces of a large program need to be recompiled,
     42 and issues the commands to recompile them.
     43 
     44    This is Edition 0.70, last updated 13 October 2011, of `The GNU Make
     45 Manual', for GNU `make' version 3.81.
     46 
     47    Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
     48 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
     49 Foundation, Inc.
     50 
     51      Permission is granted to copy, distribute and/or modify this
     52      document under the terms of the GNU Free Documentation License,
     53      Version 1.2 or any later version published by the Free Software
     54      Foundation; with no Invariant Sections, with the Front-Cover Texts
     55      being "A GNU Manual," and with the Back-Cover Texts as in (a)
     56      below.  A copy of the license is included in the section entitled
     57      "GNU Free Documentation License."
     58 
     59      (a) The FSF's Back-Cover Text is: "You have freedom to copy and
     60      modify this GNU Manual, like GNU software.  Copies published by
     61      the Free Software Foundation raise funds for GNU development."
     62 
     63 * Menu:
     64 
     65 * Overview::                    Overview of `make'.
     66 * Introduction::                An introduction to `make'.
     67 * Makefiles::                   Makefiles tell `make' what to do.
     68 * Rules::                       Rules describe when a file must be remade.
     69 * Commands::                    Commands say how to remake a file.
     70 * Using Variables::             You can use variables to avoid repetition.
     71 * Conditionals::                Use or ignore parts of the makefile based
     72                                   on the values of variables.
     73 * Functions::                   Many powerful ways to manipulate text.
     74 * Invoking make: Running.       How to invoke `make' on the command line.
     75 * Implicit Rules::              Use implicit rules to treat many files alike,
     76                                   based on their file names.
     77 * Archives::                    How `make' can update library archives.
     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
     81                                   GNU programs.
     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.
     86 
     87 * GNU Free Documentation License::  License for copying this manual
     88 * Concept Index::               Index of Concepts
     89 * Name Index::                  Index of Functions, Variables, & Directives
     90 
     91  --- The Detailed Node Listing ---
     92 
     93 Overview of `make'
     94 
     95 * Preparing::                   Preparing and Running Make
     96 * Reading::                     On Reading this Text
     97 * Bugs::                        Problems and Bugs
     98 
     99 An Introduction to Makefiles
    100 
    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 Commands
    106 * Combine By Prerequisite::     Another Style of Makefile
    107 * Cleanup::                     Rules for Cleaning the Directory
    108 
    109 Writing Makefiles
    110 
    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 * MAKEFILE_LIST Variable::      Discover which makefiles have been read.
    116 * Special Variables::           Other special variables.
    117 * Remaking Makefiles::          How makefiles get remade.
    118 * Overriding Makefiles::        How to override part of one makefile
    119                                   with another makefile.
    120 * Reading Makefiles::           How makefiles are parsed.
    121 * Secondary Expansion::         How and when secondary expansion is performed.
    122 
    123 Writing Rules
    124 
    125 * Rule Example::                An example explained.
    126 * Rule Syntax::                 General syntax explained.
    127 * Prerequisite Types::          There are two types of prerequisites.
    128 * Wildcards::                   Using wildcard characters such as `*'.
    129 * Directory Search::            Searching other directories for source files.
    130 * Phony Targets::               Using a target that is not a real file's name.
    131 * Force Targets::               You can use a target without commands
    132                                   or prerequisites to mark other targets
    133                                   as phony.
    134 * Empty Targets::               When only the date matters and the
    135                                   files are empty.
    136 * Special Targets::             Targets with special built-in meanings.
    137 * Multiple Targets::            When to make use of several targets in a rule.
    138 * Multiple Rules::              How to use several rules with the same target.
    139 * Static Pattern::              Static pattern rules apply to multiple targets
    140                                   and can vary the prerequisites according to
    141                                   the target name.
    142 * Double-Colon::                How to use a special kind of rule to allow
    143                                   several independent rules for one target.
    144 * Automatic Prerequisites::     How to automatically generate rules giving
    145                                   prerequisites from source files themselves.
    146 
    147 Using Wildcard Characters in File Names
    148 
    149 * Wildcard Examples::           Several examples
    150 * Wildcard Pitfall::            Problems to avoid.
    151 * Wildcard Function::           How to cause wildcard expansion where
    152                                   it does not normally take place.
    153 
    154 Searching Directories for Prerequisites
    155 
    156 * General Search::              Specifying a search path that applies
    157                                   to every prerequisite.
    158 * Selective Search::            Specifying a search path
    159                                   for a specified class of names.
    160 * Search Algorithm::            When and how search paths are applied.
    161 * Commands/Search::             How to write shell commands that work together
    162                                   with search paths.
    163 * Implicit/Search::             How search paths affect implicit rules.
    164 * Libraries/Search::            Directory search for link libraries.
    165 
    166 Static Pattern Rules
    167 
    168 * Static Usage::                The syntax of static pattern rules.
    169 * Static versus Implicit::      When are they better than implicit rules?
    170 
    171 Writing the Commands in Rules
    172 
    173 * Command Syntax::              Command syntax features and pitfalls.
    174 * Echoing::                     How to control when commands are echoed.
    175 * Execution::                   How commands are executed.
    176 * Parallel::                    How commands can be executed in parallel.
    177 * Errors::                      What happens after a command execution error.
    178 * Interrupts::                  What happens when a command is interrupted.
    179 * Recursion::                   Invoking `make' from makefiles.
    180 * Sequences::                   Defining canned sequences of commands.
    181 * Empty Commands::              Defining useful, do-nothing commands.
    182 
    183 Command Syntax
    184 
    185 * Splitting Lines::             Breaking long command lines for readability.
    186 * Variables in Commands::       Using `make' variables in commands.
    187 
    188 Command Execution
    189 
    190 * Choosing the Shell::          How `make' chooses the shell used
    191                                   to run commands.
    192 
    193 Recursive Use of `make'
    194 
    195 * MAKE Variable::               The special effects of using `$(MAKE)'.
    196 * Variables/Recursion::         How to communicate variables to a sub-`make'.
    197 * Options/Recursion::           How to communicate options to a sub-`make'.
    198 * -w Option::                   How the `-w' or `--print-directory' option
    199                                   helps debug use of recursive `make' commands.
    200 
    201 How to Use Variables
    202 
    203 * Reference::                   How to use the value of a variable.
    204 * Flavors::                     Variables come in two flavors.
    205 * Advanced::                    Advanced features for referencing a variable.
    206 * Values::                      All the ways variables get their values.
    207 * Setting::                     How to set a variable in the makefile.
    208 * Appending::                   How to append more text to the old value
    209                                   of a variable.
    210 * Override Directive::          How to set a variable in the makefile even if
    211                                   the user has set it with a command argument.
    212 * Defining::                    An alternate way to set a variable
    213                                   to a verbatim string.
    214 * Environment::                 Variable values can come from the environment.
    215 * Target-specific::             Variable values can be defined on a per-target
    216                                   basis.
    217 * Pattern-specific::            Target-specific variable values can be applied
    218                                   to a group of targets that match a pattern.
    219 
    220 Advanced Features for Reference to Variables
    221 
    222 * Substitution Refs::           Referencing a variable with
    223                                   substitutions on the value.
    224 * Computed Names::              Computing the name of the variable to refer to.
    225 
    226 Conditional Parts of Makefiles
    227 
    228 * Conditional Example::         Example of a conditional
    229 * Conditional Syntax::          The syntax of conditionals.
    230 * Testing Flags::               Conditionals that test flags.
    231 
    232 Functions for Transforming Text
    233 
    234 * Syntax of Functions::         How to write a function call.
    235 * Text Functions::              General-purpose text manipulation functions.
    236 * File Name Functions::         Functions for manipulating file names.
    237 * Conditional Functions::       Functions that implement conditions.
    238 * Foreach Function::            Repeat some text with controlled variation.
    239 * Call Function::               Expand a user-defined function.
    240 * Value Function::              Return the un-expanded value of a variable.
    241 * Eval Function::               Evaluate the arguments as makefile syntax.
    242 * Origin Function::             Find where a variable got its value.
    243 * Flavor Function::             Find out the flavor of a variable.
    244 * Shell Function::              Substitute the output of a shell command.
    245 * Make Control Functions::      Functions that control how make runs.
    246 
    247 How to Run `make'
    248 
    249 * Makefile Arguments::          How to specify which makefile to use.
    250 * Goals::                       How to use goal arguments to specify which
    251                                   parts of the makefile to use.
    252 * Instead of Execution::        How to use mode flags to specify what
    253                                   kind of thing to do with the commands
    254                                   in the makefile other than simply
    255                                   execute them.
    256 * Avoiding Compilation::        How to avoid recompiling certain files.
    257 * Overriding::                  How to override a variable to specify
    258                                   an alternate compiler and other things.
    259 * Testing::                     How to proceed past some errors, to
    260                                   test compilation.
    261 * Options Summary::             Summary of Options
    262 
    263 Using Implicit Rules
    264 
    265 * Using Implicit::              How to use an existing implicit rule
    266                                   to get the commands for updating a file.
    267 * Catalogue of Rules::          A list of built-in implicit rules.
    268 * Implicit Variables::          How to change what predefined rules do.
    269 * Chained Rules::               How to use a chain of implicit rules.
    270 * Pattern Rules::               How to define new implicit rules.
    271 * Last Resort::                 How to define commands for rules which
    272                                   cannot find any.
    273 * Suffix Rules::                The old-fashioned style of implicit rule.
    274 * Implicit Rule Search::        The precise algorithm for applying
    275                                   implicit rules.
    276 
    277 Defining and Redefining Pattern Rules
    278 
    279 * Pattern Intro::               An introduction to pattern rules.
    280 * Pattern Examples::            Examples of pattern rules.
    281 * Automatic Variables::         How to use automatic variables in the
    282                                   commands of implicit rules.
    283 * Pattern Match::               How patterns match.
    284 * Match-Anything Rules::        Precautions you should take prior to
    285                                   defining rules that can match any
    286                                   target file whatever.
    287 * Canceling Rules::             How to override or cancel built-in rules.
    288 
    289 Using `make' to Update Archive Files
    290 
    291 * Archive Members::             Archive members as targets.
    292 * Archive Update::              The implicit rule for archive member targets.
    293 * Archive Pitfalls::            Dangers to watch out for when using archives.
    294 * Archive Suffix Rules::        You can write a special kind of suffix rule
    295                                   for updating archives.
    296 
    297 Implicit Rule for Archive Member Targets
    298 
    299 * Archive Symbols::             How to update archive symbol directories.
    300 
    301 
    302 File: make.info,  Node: Overview,  Next: Introduction,  Prev: Top,  Up: Top
    303 
    304 1 Overview of `make'
    305 ********************
    306 
    307 The `make' utility automatically determines which pieces of a large
    308 program need to be recompiled, and issues commands to recompile them.
    309 This manual describes GNU `make', which was implemented by Richard
    310 Stallman and Roland McGrath.  Development since Version 3.76 has been
    311 handled by Paul D. Smith.
    312 
    313    GNU `make' conforms to section 6.2 of `IEEE Standard 1003.2-1992'
    314 (POSIX.2).  
    315 
    316    Our examples show C programs, since they are most common, but you
    317 can use `make' with any programming language whose compiler can be run
    318 with a shell command.  Indeed, `make' is not limited to programs.  You
    319 can use it to describe any task where some files must be updated
    320 automatically from others whenever the others change.
    321 
    322 * Menu:
    323 
    324 * Preparing::                   Preparing and Running Make
    325 * Reading::                     On Reading this Text
    326 * Bugs::                        Problems and Bugs
    327 
    328 
    329 File: make.info,  Node: Preparing,  Next: Reading,  Prev: Overview,  Up: Overview
    330 
    331 Preparing and Running Make
    332 ==========================
    333 
    334    To prepare to use `make', you must write a file called the
    335 "makefile" that describes the relationships among files in your program
    336 and provides commands for updating each file.  In a program, typically,
    337 the executable file is updated from object files, which are in turn
    338 made by compiling source files.
    339 
    340    Once a suitable makefile exists, each time you change some source
    341 files, this simple shell command:
    342 
    343      make
    344 
    345 suffices to perform all necessary recompilations.  The `make' program
    346 uses the makefile data base and the last-modification times of the
    347 files to decide which of the files need to be updated.  For each of
    348 those files, it issues the commands recorded in the data base.
    349 
    350    You can provide command line arguments to `make' to control which
    351 files should be recompiled, or how.  *Note How to Run `make': Running.
    352 
    353 
    354 File: make.info,  Node: Reading,  Next: Bugs,  Prev: Preparing,  Up: Overview
    355 
    356 1.1 How to Read This Manual
    357 ===========================
    358 
    359 If you are new to `make', or are looking for a general introduction,
    360 read the first few sections of each chapter, skipping the later
    361 sections.  In each chapter, the first few sections contain introductory
    362 or general information and the later sections contain specialized or
    363 technical information.  The exception is the second chapter, *note An
    364 Introduction to Makefiles: Introduction, all of which is introductory.
    365 
    366    If you are familiar with other `make' programs, see *note Features
    367 of GNU `make': Features, which lists the enhancements GNU `make' has,
    368 and *note Incompatibilities and Missing Features: Missing, which
    369 explains the few things GNU `make' lacks that others have.
    370 
    371    For a quick summary, see *note Options Summary::, *note Quick
    372 Reference::, and *note Special Targets::.
    373 
    374 
    375 File: make.info,  Node: Bugs,  Prev: Reading,  Up: Overview
    376 
    377 1.2 Problems and Bugs
    378 =====================
    379 
    380 If you have problems with GNU `make' or think you've found a bug,
    381 please report it to the developers; we cannot promise to do anything but
    382 we might well want to fix it.
    383 
    384    Before reporting a bug, make sure you've actually found a real bug.
    385 Carefully reread the documentation and see if it really says you can do
    386 what you're trying to do.  If it's not clear whether you should be able
    387 to do something or not, report that too; it's a bug in the
    388 documentation!
    389 
    390    Before reporting a bug or trying to fix it yourself, try to isolate
    391 it to the smallest possible makefile that reproduces the problem.  Then
    392 send us the makefile and the exact results `make' gave you, including
    393 any error or warning messages.  Please don't paraphrase these messages:
    394 it's best to cut and paste them into your report.  When generating this
    395 small makefile, be sure to not use any non-free or unusual tools in
    396 your commands: you can almost always emulate what such a tool would do
    397 with simple shell commands.  Finally, be sure to explain what you
    398 expected to occur; this will help us decide whether the problem was
    399 really in the documentation.
    400 
    401    Once you have a precise problem you can report it in one of two ways.
    402 Either send electronic mail to:
    403 
    404          bug-make (a] gnu.org
    405 
    406 or use our Web-based project management tool, at:
    407 
    408          http://savannah.gnu.org/projects/make/
    409 
    410 In addition to the information above, please be careful to include the
    411 version number of `make' you are using.  You can get this information
    412 with the command `make --version'.  Be sure also to include the type of
    413 machine and operating system you are using.  One way to obtain this
    414 information is by looking at the final lines of output from the command
    415 `make --help'.
    416 
    417 
    418 File: make.info,  Node: Introduction,  Next: Makefiles,  Prev: Overview,  Up: Top
    419 
    420 2 An Introduction to Makefiles
    421 ******************************
    422 
    423 You need a file called a "makefile" to tell `make' what to do.  Most
    424 often, the makefile tells `make' how to compile and link a program.  
    425 
    426    In this chapter, we will discuss a simple makefile that describes
    427 how to compile and link a text editor which consists of eight C source
    428 files and three header files.  The makefile can also tell `make' how to
    429 run miscellaneous commands when explicitly asked (for example, to remove
    430 certain files as a clean-up operation).  To see a more complex example
    431 of a makefile, see *note Complex Makefile::.
    432 
    433    When `make' recompiles the editor, each changed C source file must
    434 be recompiled.  If a header file has changed, each C source file that
    435 includes the header file must be recompiled to be safe.  Each
    436 compilation produces an object file corresponding to the source file.
    437 Finally, if any source file has been recompiled, all the object files,
    438 whether newly made or saved from previous compilations, must be linked
    439 together to produce the new executable editor.  
    440 
    441 * Menu:
    442 
    443 * Rule Introduction::           What a rule looks like.
    444 * Simple Makefile::             A Simple Makefile
    445 * How Make Works::              How `make' Processes This Makefile
    446 * Variables Simplify::          Variables Make Makefiles Simpler
    447 * make Deduces::                Letting `make' Deduce the Commands
    448 * Combine By Prerequisite::     Another Style of Makefile
    449 * Cleanup::                     Rules for Cleaning the Directory
    450 
    451 
    452 File: make.info,  Node: Rule Introduction,  Next: Simple Makefile,  Prev: Introduction,  Up: Introduction
    453 
    454 2.1 What a Rule Looks Like
    455 ==========================
    456 
    457 A simple makefile consists of "rules" with the following shape:
    458 
    459      TARGET ... : PREREQUISITES ...
    460              COMMAND
    461              ...
    462              ...
    463 
    464    A "target" is usually the name of a file that is generated by a
    465 program; examples of targets are executable or object files.  A target
    466 can also be the name of an action to carry out, such as `clean' (*note
    467 Phony Targets::).
    468 
    469    A "prerequisite" is a file that is used as input to create the
    470 target.  A target often depends on several files.
    471 
    472    A "command" is an action that `make' carries out.  A rule may have
    473 more than one command, each on its own line.  *Please note:* you need
    474 to put a tab character at the beginning of every command line!  This is
    475 an obscurity that catches the unwary.
    476 
    477    Usually a command is in a rule with prerequisites and serves to
    478 create a target file if any of the prerequisites change.  However, the
    479 rule that specifies commands for the target need not have
    480 prerequisites.  For example, the rule containing the delete command
    481 associated with the target `clean' does not have prerequisites.
    482 
    483    A "rule", then, explains how and when to remake certain files which
    484 are the targets of the particular rule.  `make' carries out the
    485 commands on the prerequisites to create or update the target.  A rule
    486 can also explain how and when to carry out an action.  *Note Writing
    487 Rules: Rules.
    488 
    489    A makefile may contain other text besides rules, but a simple
    490 makefile need only contain rules.  Rules may look somewhat more
    491 complicated than shown in this template, but all fit the pattern more
    492 or less.
    493 
    494 
    495 File: make.info,  Node: Simple Makefile,  Next: How Make Works,  Prev: Rule Introduction,  Up: Introduction
    496 
    497 2.2 A Simple Makefile
    498 =====================
    499 
    500 Here is a straightforward makefile that describes the way an executable
    501 file called `edit' depends on eight object files which, in turn, depend
    502 on eight C source and three header files.
    503 
    504    In this example, all the C files include `defs.h', but only those
    505 defining editing commands include `command.h', and only low level files
    506 that change the editor buffer include `buffer.h'.
    507 
    508      edit : main.o kbd.o command.o display.o \
    509             insert.o search.o files.o utils.o
    510              cc -o edit main.o kbd.o command.o display.o \
    511                         insert.o search.o files.o utils.o
    512 
    513      main.o : main.c defs.h
    514              cc -c main.c
    515      kbd.o : kbd.c defs.h command.h
    516              cc -c kbd.c
    517      command.o : command.c defs.h command.h
    518              cc -c command.c
    519      display.o : display.c defs.h buffer.h
    520              cc -c display.c
    521      insert.o : insert.c defs.h buffer.h
    522              cc -c insert.c
    523      search.o : search.c defs.h buffer.h
    524              cc -c search.c
    525      files.o : files.c defs.h buffer.h command.h
    526              cc -c files.c
    527      utils.o : utils.c defs.h
    528              cc -c utils.c
    529      clean :
    530              rm edit main.o kbd.o command.o display.o \
    531                 insert.o search.o files.o utils.o
    532 
    533 We split each long line into two lines using backslash-newline; this is
    534 like using one long line, but is easier to read.  
    535 
    536    To use this makefile to create the executable file called `edit',
    537 type:
    538 
    539      make
    540 
    541    To use this makefile to delete the executable file and all the object
    542 files from the directory, type:
    543 
    544      make clean
    545 
    546    In the example makefile, the targets include the executable file
    547 `edit', and the object files `main.o' and `kbd.o'.  The prerequisites
    548 are files such as `main.c' and `defs.h'.  In fact, each `.o' file is
    549 both a target and a prerequisite.  Commands include `cc -c main.c' and
    550 `cc -c kbd.c'.
    551 
    552    When a target is a file, it needs to be recompiled or relinked if any
    553 of its prerequisites change.  In addition, any prerequisites that are
    554 themselves automatically generated should be updated first.  In this
    555 example, `edit' depends on each of the eight object files; the object
    556 file `main.o' depends on the source file `main.c' and on the header
    557 file `defs.h'.
    558 
    559    A shell command follows each line that contains a target and
    560 prerequisites.  These shell commands say how to update the target file.
    561 A tab character must come at the beginning of every command line to
    562 distinguish command lines from other lines in the makefile.  (Bear in
    563 mind that `make' does not know anything about how the commands work.
    564 It is up to you to supply commands that will update the target file
    565 properly.  All `make' does is execute the commands in the rule you have
    566 specified when the target file needs to be updated.)  
    567 
    568    The target `clean' is not a file, but merely the name of an action.
    569 Since you normally do not want to carry out the actions in this rule,
    570 `clean' is not a prerequisite of any other rule.  Consequently, `make'
    571 never does anything with it unless you tell it specifically.  Note that
    572 this rule not only is not a prerequisite, it also does not have any
    573 prerequisites, so the only purpose of the rule is to run the specified
    574 commands.  Targets that do not refer to files but are just actions are
    575 called "phony targets".  *Note Phony Targets::, for information about
    576 this kind of target.  *Note Errors in Commands: Errors, to see how to
    577 cause `make' to ignore errors from `rm' or any other command.  
    578 
    579 
    580 File: make.info,  Node: How Make Works,  Next: Variables Simplify,  Prev: Simple Makefile,  Up: Introduction
    581 
    582 2.3 How `make' Processes a Makefile
    583 ===================================
    584 
    585 By default, `make' starts with the first target (not targets whose
    586 names start with `.').  This is called the "default goal".  ("Goals"
    587 are the targets that `make' strives ultimately to update.    You can
    588 override this behavior using the command line (*note Arguments to
    589 Specify the Goals: Goals.) or with the `.DEFAULT_GOAL' special variable
    590 (*note Other Special Variables: Special Variables.).  
    591 
    592    In the simple example of the previous section, the default goal is to
    593 update the executable program `edit'; therefore, we put that rule first.
    594 
    595    Thus, when you give the command:
    596 
    597      make
    598 
    599 `make' reads the makefile in the current directory and begins by
    600 processing the first rule.  In the example, this rule is for relinking
    601 `edit'; but before `make' can fully process this rule, it must process
    602 the rules for the files that `edit' depends on, which in this case are
    603 the object files.  Each of these files is processed according to its
    604 own rule.  These rules say to update each `.o' file by compiling its
    605 source file.  The recompilation must be done if the source file, or any
    606 of the header files named as prerequisites, is more recent than the
    607 object file, or if the object file does not exist.
    608 
    609    The other rules are processed because their targets appear as
    610 prerequisites of the goal.  If some other rule is not depended on by the
    611 goal (or anything it depends on, etc.), that rule is not processed,
    612 unless you tell `make' to do so (with a command such as `make clean').
    613 
    614    Before recompiling an object file, `make' considers updating its
    615 prerequisites, the source file and header files.  This makefile does not
    616 specify anything to be done for them--the `.c' and `.h' files are not
    617 the targets of any rules--so `make' does nothing for these files.  But
    618 `make' would update automatically generated C programs, such as those
    619 made by Bison or Yacc, by their own rules at this time.
    620 
    621    After recompiling whichever object files need it, `make' decides
    622 whether to relink `edit'.  This must be done if the file `edit' does
    623 not exist, or if any of the object files are newer than it.  If an
    624 object file was just recompiled, it is now newer than `edit', so `edit'
    625 is relinked.  
    626 
    627    Thus, if we change the file `insert.c' and run `make', `make' will
    628 compile that file to update `insert.o', and then link `edit'.  If we
    629 change the file `command.h' and run `make', `make' will recompile the
    630 object files `kbd.o', `command.o' and `files.o' and then link the file
    631 `edit'.
    632 
    633 
    634 File: make.info,  Node: Variables Simplify,  Next: make Deduces,  Prev: How Make Works,  Up: Introduction
    635 
    636 2.4 Variables Make Makefiles Simpler
    637 ====================================
    638 
    639 In our example, we had to list all the object files twice in the rule
    640 for `edit' (repeated here):
    641 
    642      edit : main.o kbd.o command.o display.o \
    643                    insert.o search.o files.o utils.o
    644              cc -o edit main.o kbd.o command.o display.o \
    645                         insert.o search.o files.o utils.o
    646 
    647    Such duplication is error-prone; if a new object file is added to the
    648 system, we might add it to one list and forget the other.  We can
    649 eliminate the risk and simplify the makefile by using a variable.
    650 "Variables" allow a text string to be defined once and substituted in
    651 multiple places later (*note How to Use Variables: Using Variables.).
    652 
    653    It is standard practice for every makefile to have a variable named
    654 `objects', `OBJECTS', `objs', `OBJS', `obj', or `OBJ' which is a list
    655 of all object file names.  We would define such a variable `objects'
    656 with a line like this in the makefile:
    657 
    658      objects = main.o kbd.o command.o display.o \
    659                insert.o search.o files.o utils.o
    660 
    661 Then, each place we want to put a list of the object file names, we can
    662 substitute the variable's value by writing `$(objects)' (*note How to
    663 Use Variables: Using Variables.).
    664 
    665    Here is how the complete simple makefile looks when you use a
    666 variable for the object files:
    667 
    668      objects = main.o kbd.o command.o display.o \
    669                insert.o search.o files.o utils.o
    670 
    671      edit : $(objects)
    672              cc -o edit $(objects)
    673      main.o : main.c defs.h
    674              cc -c main.c
    675      kbd.o : kbd.c defs.h command.h
    676              cc -c kbd.c
    677      command.o : command.c defs.h command.h
    678              cc -c command.c
    679      display.o : display.c defs.h buffer.h
    680              cc -c display.c
    681      insert.o : insert.c defs.h buffer.h
    682              cc -c insert.c
    683      search.o : search.c defs.h buffer.h
    684              cc -c search.c
    685      files.o : files.c defs.h buffer.h command.h
    686              cc -c files.c
    687      utils.o : utils.c defs.h
    688              cc -c utils.c
    689      clean :
    690              rm edit $(objects)
    691 
    692 
    693 File: make.info,  Node: make Deduces,  Next: Combine By Prerequisite,  Prev: Variables Simplify,  Up: Introduction
    694 
    695 2.5 Letting `make' Deduce the Commands
    696 ======================================
    697 
    698 It is not necessary to spell out the commands for compiling the
    699 individual C source files, because `make' can figure them out: it has an
    700 "implicit rule" for updating a `.o' file from a correspondingly named
    701 `.c' file using a `cc -c' command.  For example, it will use the
    702 command `cc -c main.c -o main.o' to compile `main.c' into `main.o'.  We
    703 can therefore omit the commands from the rules for the object files.
    704 *Note Using Implicit Rules: Implicit Rules.
    705 
    706    When a `.c' file is used automatically in this way, it is also
    707 automatically added to the list of prerequisites.  We can therefore omit
    708 the `.c' files from the prerequisites, provided we omit the commands.
    709 
    710    Here is the entire example, with both of these changes, and a
    711 variable `objects' as suggested above:
    712 
    713      objects = main.o kbd.o command.o display.o \
    714                insert.o search.o files.o utils.o
    715 
    716      edit : $(objects)
    717              cc -o edit $(objects)
    718 
    719      main.o : defs.h
    720      kbd.o : defs.h command.h
    721      command.o : defs.h command.h
    722      display.o : defs.h buffer.h
    723      insert.o : defs.h buffer.h
    724      search.o : defs.h buffer.h
    725      files.o : defs.h buffer.h command.h
    726      utils.o : defs.h
    727 
    728      .PHONY : clean
    729      clean :
    730              rm edit $(objects)
    731 
    732 This is how we would write the makefile in actual practice.  (The
    733 complications associated with `clean' are described elsewhere.  See
    734 *note Phony Targets::, and *note Errors in Commands: Errors.)
    735 
    736    Because implicit rules are so convenient, they are important.  You
    737 will see them used frequently.
    738 
    739 
    740 File: make.info,  Node: Combine By Prerequisite,  Next: Cleanup,  Prev: make Deduces,  Up: Introduction
    741 
    742 2.6 Another Style of Makefile
    743 =============================
    744 
    745 When the objects of a makefile are created only by implicit rules, an
    746 alternative style of makefile is possible.  In this style of makefile,
    747 you group entries by their prerequisites instead of by their targets.
    748 Here is what one looks like:
    749 
    750      objects = main.o kbd.o command.o display.o \
    751                insert.o search.o files.o utils.o
    752 
    753      edit : $(objects)
    754              cc -o edit $(objects)
    755 
    756      $(objects) : defs.h
    757      kbd.o command.o files.o : command.h
    758      display.o insert.o search.o files.o : buffer.h
    759 
    760 Here `defs.h' is given as a prerequisite of all the object files;
    761 `command.h' and `buffer.h' are prerequisites of the specific object
    762 files listed for them.
    763 
    764    Whether this is better is a matter of taste: it is more compact, but
    765 some people dislike it because they find it clearer to put all the
    766 information about each target in one place.
    767 
    768 
    769 File: make.info,  Node: Cleanup,  Prev: Combine By Prerequisite,  Up: Introduction
    770 
    771 2.7 Rules for Cleaning the Directory
    772 ====================================
    773 
    774 Compiling a program is not the only thing you might want to write rules
    775 for.  Makefiles commonly tell how to do a few other things besides
    776 compiling a program: for example, how to delete all the object files
    777 and executables so that the directory is `clean'.
    778 
    779    Here is how we could write a `make' rule for cleaning our example
    780 editor:
    781 
    782      clean:
    783              rm edit $(objects)
    784 
    785    In practice, we might want to write the rule in a somewhat more
    786 complicated manner to handle unanticipated situations.  We would do
    787 this:
    788 
    789      .PHONY : clean
    790      clean :
    791              -rm edit $(objects)
    792 
    793 This prevents `make' from getting confused by an actual file called
    794 `clean' and causes it to continue in spite of errors from `rm'.  (See
    795 *note Phony Targets::, and *note Errors in Commands: Errors.)
    796 
    797 A rule such as this should not be placed at the beginning of the
    798 makefile, because we do not want it to run by default!  Thus, in the
    799 example makefile, we want the rule for `edit', which recompiles the
    800 editor, to remain the default goal.
    801 
    802    Since `clean' is not a prerequisite of `edit', this rule will not
    803 run at all if we give the command `make' with no arguments.  In order
    804 to make the rule run, we have to type `make clean'.  *Note How to Run
    805 `make': Running.
    806 
    807 
    808 File: make.info,  Node: Makefiles,  Next: Rules,  Prev: Introduction,  Up: Top
    809 
    810 3 Writing Makefiles
    811 *******************
    812 
    813 The information that tells `make' how to recompile a system comes from
    814 reading a data base called the "makefile".
    815 
    816 * Menu:
    817 
    818 * Makefile Contents::           What makefiles contain.
    819 * Makefile Names::              How to name your makefile.
    820 * Include::                     How one makefile can use another makefile.
    821 * MAKEFILES Variable::          The environment can specify extra makefiles.
    822 * MAKEFILE_LIST Variable::      Discover which makefiles have been read.
    823 * Special Variables::           Other special variables.
    824 * Remaking Makefiles::          How makefiles get remade.
    825 * Overriding Makefiles::        How to override part of one makefile
    826                                   with another makefile.
    827 * Reading Makefiles::           How makefiles are parsed.
    828 * Secondary Expansion::         How and when secondary expansion is performed.
    829 
    830 
    831 File: make.info,  Node: Makefile Contents,  Next: Makefile Names,  Prev: Makefiles,  Up: Makefiles
    832 
    833 3.1 What Makefiles Contain
    834 ==========================
    835 
    836 Makefiles contain five kinds of things: "explicit rules", "implicit
    837 rules", "variable definitions", "directives", and "comments".  Rules,
    838 variables, and directives are described at length in later chapters.
    839 
    840    * An "explicit rule" says when and how to remake one or more files,
    841      called the rule's "targets".  It lists the other files that the
    842      targets depend on, called the "prerequisites" of the target, and
    843      may also give commands to use to create or update the targets.
    844      *Note Writing Rules: Rules.
    845 
    846    * An "implicit rule" says when and how to remake a class of files
    847      based on their names.  It describes how a target may depend on a
    848      file with a name similar to the target and gives commands to
    849      create or update such a target.  *Note Using Implicit Rules:
    850      Implicit Rules.
    851 
    852    * A "variable definition" is a line that specifies a text string
    853      value for a variable that can be substituted into the text later.
    854      The simple makefile example shows a variable definition for
    855      `objects' as a list of all object files (*note Variables Make
    856      Makefiles Simpler: Variables Simplify.).
    857 
    858    * A "directive" is a command for `make' to do something special while
    859      reading the makefile.  These include:
    860 
    861         * Reading another makefile (*note Including Other Makefiles:
    862           Include.).
    863 
    864         * Deciding (based on the values of variables) whether to use or
    865           ignore a part of the makefile (*note Conditional Parts of
    866           Makefiles: Conditionals.).
    867 
    868         * Defining a variable from a verbatim string containing
    869           multiple lines (*note Defining Variables Verbatim: Defining.).
    870 
    871    * `#' in a line of a makefile starts a "comment".  It and the rest
    872      of the line are ignored, except that a trailing backslash not
    873      escaped by another backslash will continue the comment across
    874      multiple lines.  A line containing just a comment (with perhaps
    875      spaces before it) is effectively blank, and is ignored.  If you
    876      want a literal `#', escape it with a backslash (e.g., `\#').
    877      Comments may appear on any line in the makefile, although they are
    878      treated specially in certain situations.
    879 
    880      Within a command script (if the line begins with a TAB character)
    881      the entire line is passed to the shell, just as with any other
    882      line that begins with a TAB.  The shell decides how to interpret
    883      the text: whether or not this is a comment is up to the shell.
    884 
    885      Within a `define' directive, comments are not ignored during the
    886      definition of the variable, but rather kept intact in the value of
    887      the variable.  When the variable is expanded they will either be
    888      treated as `make' comments or as command script text, depending on
    889      the context in which the variable is evaluated.
    890 
    891 
    892 File: make.info,  Node: Makefile Names,  Next: Include,  Prev: Makefile Contents,  Up: Makefiles
    893 
    894 3.2 What Name to Give Your Makefile
    895 ===================================
    896 
    897 By default, when `make' looks for the makefile, it tries the following
    898 names, in order: `GNUmakefile', `makefile' and `Makefile'.  
    899 
    900    Normally you should call your makefile either `makefile' or
    901 `Makefile'.  (We recommend `Makefile' because it appears prominently
    902 near the beginning of a directory listing, right near other important
    903 files such as `README'.)  The first name checked, `GNUmakefile', is not
    904 recommended for most makefiles.  You should use this name if you have a
    905 makefile that is specific to GNU `make', and will not be understood by
    906 other versions of `make'.  Other `make' programs look for `makefile' and
    907 `Makefile', but not `GNUmakefile'.
    908 
    909    If `make' finds none of these names, it does not use any makefile.
    910 Then you must specify a goal with a command argument, and `make' will
    911 attempt to figure out how to remake it using only its built-in implicit
    912 rules.  *Note Using Implicit Rules: Implicit Rules.
    913 
    914    If you want to use a nonstandard name for your makefile, you can
    915 specify the makefile name with the `-f' or `--file' option.  The
    916 arguments `-f NAME' or `--file=NAME' tell `make' to read the file NAME
    917 as the makefile.  If you use more than one `-f' or `--file' option, you
    918 can specify several makefiles.  All the makefiles are effectively
    919 concatenated in the order specified.  The default makefile names
    920 `GNUmakefile', `makefile' and `Makefile' are not checked automatically
    921 if you specify `-f' or `--file'.  
    922 
    923 
    924 File: make.info,  Node: Include,  Next: MAKEFILES Variable,  Prev: Makefile Names,  Up: Makefiles
    925 
    926 3.3 Including Other Makefiles
    927 =============================
    928 
    929 The `include' directive tells `make' to suspend reading the current
    930 makefile and read one or more other makefiles before continuing.  The
    931 directive is a line in the makefile that looks like this:
    932 
    933      include FILENAMES...
    934 
    935 FILENAMES can contain shell file name patterns.  If FILENAMES is empty,
    936 nothing is included and no error is printed.  
    937 
    938    Extra spaces are allowed and ignored at the beginning of the line,
    939 but a tab is not allowed.  (If the line begins with a tab, it will be
    940 considered a command line.)  Whitespace is required between `include'
    941 and the file names, and between file names; extra whitespace is ignored
    942 there and at the end of the directive.  A comment starting with `#' is
    943 allowed at the end of the line.  If the file names contain any variable
    944 or function references, they are expanded.  *Note How to Use Variables:
    945 Using Variables.
    946 
    947    For example, if you have three `.mk' files, `a.mk', `b.mk', and
    948 `c.mk', and `$(bar)' expands to `bish bash', then the following
    949 expression
    950 
    951      include foo *.mk $(bar)
    952 
    953    is equivalent to
    954 
    955      include foo a.mk b.mk c.mk bish bash
    956 
    957    When `make' processes an `include' directive, it suspends reading of
    958 the containing makefile and reads from each listed file in turn.  When
    959 that is finished, `make' resumes reading the makefile in which the
    960 directive appears.
    961 
    962    One occasion for using `include' directives is when several programs,
    963 handled by individual makefiles in various directories, need to use a
    964 common set of variable definitions (*note Setting Variables: Setting.)
    965 or pattern rules (*note Defining and Redefining Pattern Rules: Pattern
    966 Rules.).
    967 
    968    Another such occasion is when you want to generate prerequisites from
    969 source files automatically; the prerequisites can be put in a file that
    970 is included by the main makefile.  This practice is generally cleaner
    971 than that of somehow appending the prerequisites to the end of the main
    972 makefile as has been traditionally done with other versions of `make'.
    973 *Note Automatic Prerequisites::.  
    974 
    975    If the specified name does not start with a slash, and the file is
    976 not found in the current directory, several other directories are
    977 searched.  First, any directories you have specified with the `-I' or
    978 `--include-dir' option are searched (*note Summary of Options: Options
    979 Summary.).  Then the following directories (if they exist) are
    980 searched, in this order: `PREFIX/include' (normally `/usr/local/include'
    981 (1)) `/usr/gnu/include', `/usr/local/include', `/usr/include'.
    982 
    983    If an included makefile cannot be found in any of these directories,
    984 a warning message is generated, but it is not an immediately fatal
    985 error; processing of the makefile containing the `include' continues.
    986 Once it has finished reading makefiles, `make' will try to remake any
    987 that are out of date or don't exist.  *Note How Makefiles Are Remade:
    988 Remaking Makefiles.  Only after it has tried to find a way to remake a
    989 makefile and failed, will `make' diagnose the missing makefile as a
    990 fatal error.
    991 
    992    If you want `make' to simply ignore a makefile which does not exist
    993 and cannot be remade, with no error message, use the `-include'
    994 directive instead of `include', like this:
    995 
    996      -include FILENAMES...
    997 
    998    This acts like `include' in every way except that there is no error
    999 (not even a warning) if any of the FILENAMES do not exist.  For
   1000 compatibility with some other `make' implementations, `sinclude' is
   1001 another name for `-include'.
   1002 
   1003    ---------- Footnotes ----------
   1004 
   1005    (1) GNU Make compiled for MS-DOS and MS-Windows behaves as if PREFIX
   1006 has been defined to be the root of the DJGPP tree hierarchy.
   1007 
   1008 
   1009 File: make.info,  Node: MAKEFILES Variable,  Next: MAKEFILE_LIST Variable,  Prev: Include,  Up: Makefiles
   1010 
   1011 3.4 The Variable `MAKEFILES'
   1012 ============================
   1013 
   1014 If the environment variable `MAKEFILES' is defined, `make' considers
   1015 its value as a list of names (separated by whitespace) of additional
   1016 makefiles to be read before the others.  This works much like the
   1017 `include' directive: various directories are searched for those files
   1018 (*note Including Other Makefiles: Include.).  In addition, the default
   1019 goal is never taken from one of these makefiles and it is not an error
   1020 if the files listed in `MAKEFILES' are not found.
   1021 
   1022    The main use of `MAKEFILES' is in communication between recursive
   1023 invocations of `make' (*note Recursive Use of `make': Recursion.).  It
   1024 usually is not desirable to set the environment variable before a
   1025 top-level invocation of `make', because it is usually better not to
   1026 mess with a makefile from outside.  However, if you are running `make'
   1027 without a specific makefile, a makefile in `MAKEFILES' can do useful
   1028 things to help the built-in implicit rules work better, such as
   1029 defining search paths (*note Directory Search::).
   1030 
   1031    Some users are tempted to set `MAKEFILES' in the environment
   1032 automatically on login, and program makefiles to expect this to be done.
   1033 This is a very bad idea, because such makefiles will fail to work if
   1034 run by anyone else.  It is much better to write explicit `include'
   1035 directives in the makefiles.  *Note Including Other Makefiles: Include.
   1036 
   1037 
   1038 File: make.info,  Node: MAKEFILE_LIST Variable,  Next: Special Variables,  Prev: MAKEFILES Variable,  Up: Makefiles
   1039 
   1040 3.5 The Variable `MAKEFILE_LIST'
   1041 ================================
   1042 
   1043 As `make' reads various makefiles, including any obtained from the
   1044 `MAKEFILES' variable, the command line, the default files, or from
   1045 `include' directives, their names will be automatically appended to the
   1046 `MAKEFILE_LIST' variable.  They are added right before `make' begins to
   1047 parse them.
   1048 
   1049    This means that if the first thing a makefile does is examine the
   1050 last word in this variable, it will be the name of the current makefile.
   1051 Once the current makefile has used `include', however, the last word
   1052 will be the just-included makefile.
   1053 
   1054    If a makefile named `Makefile' has this content:
   1055 
   1056      name1 := $(lastword $(MAKEFILE_LIST))
   1057 
   1058      include inc.mk
   1059 
   1060      name2 := $(lastword $(MAKEFILE_LIST))
   1061 
   1062      all:
   1063              @echo name1 = $(name1)
   1064              @echo name2 = $(name2)
   1065 
   1066 then you would expect to see this output:
   1067 
   1068      name1 = Makefile
   1069      name2 = inc.mk
   1070 
   1071    *Note Text Functions::, for more information on the `word' and
   1072 `words' functions used above.  *Note The Two Flavors of Variables:
   1073 Flavors, for more information on simply-expanded (`:=') variable
   1074 definitions.
   1075 
   1076 
   1077 File: make.info,  Node: Special Variables,  Next: Remaking Makefiles,  Prev: MAKEFILE_LIST Variable,  Up: Makefiles
   1078 
   1079 3.6 Other Special Variables
   1080 ===========================
   1081 
   1082 GNU `make' also supports other special variables.  Unless otherwise
   1083 documented here, these values lose their special properties if they are
   1084 set by a makefile or on the command line.
   1085 
   1086 `.DEFAULT_GOAL'
   1087      Sets the default goal to be used if no targets were specified on
   1088      the command line (*note Arguments to Specify the Goals: Goals.).
   1089      The `.DEFAULT_GOAL' variable allows you to discover the current
   1090      default goal, restart the default goal selection algorithm by
   1091      clearing its value, or to explicitly set the default goal.  The
   1092      following example illustrates these cases:
   1093 
   1094           # Query the default goal.
   1095           ifeq ($(.DEFAULT_GOAL),)
   1096             $(warning no default goal is set)
   1097           endif
   1098 
   1099           .PHONY: foo
   1100           foo: ; @echo $@
   1101 
   1102           $(warning default goal is $(.DEFAULT_GOAL))
   1103 
   1104           # Reset the default goal.
   1105           .DEFAULT_GOAL :=
   1106 
   1107           .PHONY: bar
   1108           bar: ; @echo $@
   1109 
   1110           $(warning default goal is $(.DEFAULT_GOAL))
   1111 
   1112           # Set our own.
   1113           .DEFAULT_GOAL := foo
   1114 
   1115      This makefile prints:
   1116 
   1117           no default goal is set
   1118           default goal is foo
   1119           default goal is bar
   1120           foo
   1121 
   1122      Note that assigning more than one target name to `.DEFAULT_GOAL' is
   1123      illegal and will result in an error.
   1124 
   1125 `MAKE_RESTARTS'
   1126      This variable is set only if this instance of `make' has restarted
   1127      (*note How Makefiles Are Remade: Remaking Makefiles.): it will
   1128      contain the number of times this instance has restarted.  Note
   1129      this is not the same as recursion (counted by the `MAKELEVEL'
   1130      variable).  You should not set, modify, or export this variable.
   1131 
   1132 `.VARIABLES'
   1133      Expands to a list of the _names_ of all global variables defined
   1134      so far.  This includes variables which have empty values, as well
   1135      as built-in variables (*note Variables Used by Implicit Rules:
   1136      Implicit Variables.), but does not include any variables which are
   1137      only defined in a target-specific context.  Note that any value
   1138      you assign to this variable will be ignored; it will always return
   1139      its special value.
   1140 
   1141 `.FEATURES'
   1142      Expands to a list of special features supported by this version of
   1143      `make'.  Possible values include:
   1144 
   1145     `archives'
   1146           Supports `ar' (archive) files using special filename syntax.
   1147           *Note Using `make' to Update Archive Files: Archives.
   1148 
   1149     `check-symlink'
   1150           Supports the `-L' (`--check-symlink-times') flag.  *Note
   1151           Summary of Options: Options Summary.
   1152 
   1153     `else-if'
   1154           Supports "else if" non-nested conditionals.  *Note Syntax of
   1155           Conditionals: Conditional Syntax.
   1156 
   1157     `jobserver'
   1158           Supports "job server" enhanced parallel builds.  *Note
   1159           Parallel Execution: Parallel.
   1160 
   1161     `second-expansion'
   1162           Supports secondary expansion of prerequisite lists.
   1163 
   1164     `order-only'
   1165           Supports order-only prerequisites.  *Note Types of
   1166           Prerequisites: Prerequisite Types.
   1167 
   1168     `target-specific'
   1169           Supports target-specific and pattern-specific variable
   1170           assignments.  *Note Target-specific Variable Values:
   1171           Target-specific.
   1172 
   1173 
   1174 `.INCLUDE_DIRS'
   1175      Expands to a list of directories that `make' searches for included
   1176      makefiles (*note Including Other Makefiles: Include.).
   1177 
   1178 
   1179 
   1180 File: make.info,  Node: Remaking Makefiles,  Next: Overriding Makefiles,  Prev: Special Variables,  Up: Makefiles
   1181 
   1182 3.7 How Makefiles Are Remade
   1183 ============================
   1184 
   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.
   1188 
   1189    To this end, after reading in all makefiles, `make' will consider
   1190 each as a goal target and attempt to update it.  If a makefile has a
   1191 rule which says how to update it (found either in that very makefile or
   1192 in another one) or if an implicit rule applies to it (*note Using
   1193 Implicit Rules: Implicit Rules.), it will be updated if necessary.
   1194 After all makefiles have been checked, if any have actually been
   1195 changed, `make' starts with a clean slate and reads all the makefiles
   1196 over again.  (It will also attempt to update each of them over again,
   1197 but normally this will not change them again, since they are already up
   1198 to date.)
   1199 
   1200    If you know that one or more of your makefiles cannot be remade and
   1201 you want to keep `make' from performing an implicit rule search on
   1202 them, perhaps for efficiency reasons, you can use any normal method of
   1203 preventing implicit rule lookup to do so.  For example, you can write an
   1204 explicit rule with the makefile as the target, and an empty command
   1205 string (*note Using Empty Commands: Empty Commands.).
   1206 
   1207    If the makefiles specify a double-colon rule to remake a file with
   1208 commands but no prerequisites, that file will always be remade (*note
   1209 Double-Colon::).  In the case of makefiles, a makefile that has a
   1210 double-colon rule with commands but no prerequisites will be remade
   1211 every time `make' is run, and then again after `make' starts over and
   1212 reads the makefiles in again.  This would cause an infinite loop:
   1213 `make' would constantly remake the makefile, and never do anything
   1214 else.  So, to avoid this, `make' will *not* attempt to remake makefiles
   1215 which are specified as targets of a double-colon rule with commands but
   1216 no prerequisites.
   1217 
   1218    If you do not specify any makefiles to be read with `-f' or `--file'
   1219 options, `make' will try the default makefile names; *note What Name to
   1220 Give Your Makefile: Makefile Names.  Unlike makefiles explicitly
   1221 requested with `-f' or `--file' options, `make' is not certain that
   1222 these makefiles should exist.  However, if a default makefile does not
   1223 exist but can be created by running `make' rules, you probably want the
   1224 rules to be run so that the makefile can be used.
   1225 
   1226    Therefore, if none of the default makefiles exists, `make' will try
   1227 to make each of them in the same order in which they are searched for
   1228 (*note What Name to Give Your Makefile: Makefile Names.)  until it
   1229 succeeds in making one, or it runs out of names to try.  Note that it
   1230 is not an error if `make' cannot find or make any makefile; a makefile
   1231 is not always necessary.
   1232 
   1233    When you use the `-t' or `--touch' option (*note Instead of
   1234 Executing the Commands: Instead of Execution.), you would not want to
   1235 use an out-of-date makefile to decide which targets to touch.  So the
   1236 `-t' option has no effect on updating makefiles; they are really
   1237 updated even if `-t' is specified.  Likewise, `-q' (or `--question')
   1238 and `-n' (or `--just-print') do not prevent updating of makefiles,
   1239 because an out-of-date makefile would result in the wrong output for
   1240 other targets.  Thus, `make -f mfile -n foo' will update `mfile', read
   1241 it in, and then print the commands to update `foo' and its prerequisites
   1242 without running them.  The commands printed for `foo' will be those
   1243 specified in the updated contents of `mfile'.
   1244 
   1245    However, on occasion you might actually wish to prevent updating of
   1246 even the makefiles.  You can do this by specifying the makefiles as
   1247 goals in the command line as well as specifying them as makefiles.
   1248 When the makefile name is specified explicitly as a goal, the options
   1249 `-t' and so on do apply to them.
   1250 
   1251    Thus, `make -f mfile -n mfile foo' would read the makefile `mfile',
   1252 print the commands needed to update it without actually running them,
   1253 and then print the commands needed to update `foo' without running
   1254 them.  The commands for `foo' will be those specified by the existing
   1255 contents of `mfile'.
   1256 
   1257 
   1258 File: make.info,  Node: Overriding Makefiles,  Next: Reading Makefiles,  Prev: Remaking Makefiles,  Up: Makefiles
   1259 
   1260 3.8 Overriding Part of Another Makefile
   1261 =======================================
   1262 
   1263 Sometimes it is useful to have a makefile that is mostly just like
   1264 another makefile.  You can often use the `include' directive to include
   1265 one in the other, and add more targets or variable definitions.
   1266 However, if the two makefiles give different commands for the same
   1267 target, `make' will not let you just do this.  But there is another way.
   1268 
   1269    In the containing makefile (the one that wants to include the other),
   1270 you can use a match-anything pattern rule to say that to remake any
   1271 target that cannot be made from the information in the containing
   1272 makefile, `make' should look in another makefile.  *Note Pattern
   1273 Rules::, for more information on pattern rules.
   1274 
   1275    For example, if you have a makefile called `Makefile' that says how
   1276 to make the target `foo' (and other targets), you can write a makefile
   1277 called `GNUmakefile' that contains:
   1278 
   1279      foo:
   1280              frobnicate > foo
   1281 
   1282      %: force
   1283              @$(MAKE) -f Makefile $@
   1284      force: ;
   1285 
   1286    If you say `make foo', `make' will find `GNUmakefile', read it, and
   1287 see that to make `foo', it needs to run the command `frobnicate > foo'.
   1288 If you say `make bar', `make' will find no way to make `bar' in
   1289 `GNUmakefile', so it will use the commands from the pattern rule: `make
   1290 -f Makefile bar'.  If `Makefile' provides a rule for updating `bar',
   1291 `make' will apply the rule.  And likewise for any other target that
   1292 `GNUmakefile' does not say how to make.
   1293 
   1294    The way this works is that the pattern rule has a pattern of just
   1295 `%', so it matches any target whatever.  The rule specifies a
   1296 prerequisite `force', to guarantee that the commands will be run even
   1297 if the target file already exists.  We give `force' target empty
   1298 commands to prevent `make' from searching for an implicit rule to build
   1299 it--otherwise it would apply the same match-anything rule to `force'
   1300 itself and create a prerequisite loop!
   1301 
   1302 
   1303 File: make.info,  Node: Reading Makefiles,  Next: Secondary Expansion,  Prev: Overriding Makefiles,  Up: Makefiles
   1304 
   1305 3.9 How `make' Reads a Makefile
   1306 ===============================
   1307 
   1308 GNU `make' does its work in two distinct phases.  During the first
   1309 phase it reads all the makefiles, included makefiles, etc. and
   1310 internalizes all the variables and their values, implicit and explicit
   1311 rules, and constructs a dependency graph of all the targets and their
   1312 prerequisites.  During the second phase, `make' uses these internal
   1313 structures to determine what targets will need to be rebuilt and to
   1314 invoke the rules necessary to do so.
   1315 
   1316    It's important to understand this two-phase approach because it has a
   1317 direct impact on how variable and function expansion happens; this is
   1318 often a source of some confusion when writing makefiles.  Here we will
   1319 present a summary of the phases in which expansion happens for different
   1320 constructs within the makefile.  We say that expansion is "immediate"
   1321 if it happens during the first phase: in this case `make' will expand
   1322 any variables or functions in that section of a construct as the
   1323 makefile is parsed.  We say that expansion is "deferred" if expansion
   1324 is not performed immediately.  Expansion of deferred construct is not
   1325 performed until either the construct appears later in an immediate
   1326 context, or until the second phase.
   1327 
   1328    You may not be familiar with some of these constructs yet.  You can
   1329 reference this section as you become familiar with them, in later
   1330 chapters.
   1331 
   1332 Variable Assignment
   1333 -------------------
   1334 
   1335 Variable definitions are parsed as follows:
   1336 
   1337      IMMEDIATE = DEFERRED
   1338      IMMEDIATE ?= DEFERRED
   1339      IMMEDIATE := IMMEDIATE
   1340      IMMEDIATE += DEFERRED or IMMEDIATE
   1341 
   1342      define IMMEDIATE
   1343        DEFERRED
   1344      endef
   1345 
   1346    For the append operator, `+=', the right-hand side is considered
   1347 immediate if the variable was previously set as a simple variable
   1348 (`:='), and deferred otherwise.
   1349 
   1350 Conditional Statements
   1351 ----------------------
   1352 
   1353 All instances of conditional syntax are parsed immediately, in their
   1354 entirety; this includes the `ifdef', `ifeq', `ifndef', and `ifneq'
   1355 forms.  Of course this means that automatic variables cannot be used in
   1356 conditional statements, as automatic variables are not set until the
   1357 command script for that rule is invoked.  If you need to use automatic
   1358 variables in a conditional you _must_ use shell conditional syntax, in
   1359 your command script proper, for these tests, not `make' conditionals.
   1360 
   1361 Rule Definition
   1362 ---------------
   1363 
   1364 A rule is always expanded the same way, regardless of the form:
   1365 
   1366      IMMEDIATE : IMMEDIATE ; DEFERRED
   1367      	DEFERRED
   1368 
   1369    That is, the target and prerequisite sections are expanded
   1370 immediately, and the commands used to construct the target are always
   1371 deferred.  This general rule is true for explicit rules, pattern rules,
   1372 suffix rules, static pattern rules, and simple prerequisite definitions.
   1373 
   1374 
   1375 File: make.info,  Node: Secondary Expansion,  Prev: Reading Makefiles,  Up: Makefiles
   1376 
   1377 3.10 Secondary Expansion
   1378 ========================
   1379 
   1380 In the previous section we learned that GNU `make' works in two
   1381 distinct phases: a read-in phase and a target-update phase (*note How
   1382 `make' Reads a Makefile: Reading Makefiles.).  GNU make also has the
   1383 ability to enable a _second expansion_ of the prerequisites (only) for
   1384 some or all targets defined in the makefile.  In order for this second
   1385 expansion to occur, the special target `.SECONDEXPANSION' must be
   1386 defined before the first prerequisite list that makes use of this
   1387 feature.
   1388 
   1389    If that special target is defined then in between the two phases
   1390 mentioned above, right at the end of the read-in phase, all the
   1391 prerequisites of the targets defined after the special target are
   1392 expanded a _second time_.  In most circumstances this secondary
   1393 expansion will have no effect, since all variable and function
   1394 references will have been expanded during the initial parsing of the
   1395 makefiles.  In order to take advantage of the secondary expansion phase
   1396 of the parser, then, it's necessary to _escape_ the variable or
   1397 function reference in the makefile.  In this case the first expansion
   1398 merely un-escapes the reference but doesn't expand it, and expansion is
   1399 left to the secondary expansion phase.  For example, consider this
   1400 makefile:
   1401 
   1402      .SECONDEXPANSION:
   1403      ONEVAR = onefile
   1404      TWOVAR = twofile
   1405      myfile: $(ONEVAR) $$(TWOVAR)
   1406 
   1407    After the first expansion phase the prerequisites list of the
   1408 `myfile' target will be `onefile' and `$(TWOVAR)'; the first
   1409 (unescaped) variable reference to ONEVAR is expanded, while the second
   1410 (escaped) variable reference is simply unescaped, without being
   1411 recognized as a variable reference.  Now during the secondary expansion
   1412 the first word is expanded again but since it contains no variable or
   1413 function references it remains the static value `onefile', while the
   1414 second word is now a normal reference to the variable TWOVAR, which is
   1415 expanded to the value `twofile'.  The final result is that there are
   1416 two prerequisites, `onefile' and `twofile'.
   1417 
   1418    Obviously, this is not a very interesting case since the same result
   1419 could more easily have been achieved simply by having both variables
   1420 appear, unescaped, in the prerequisites list.  One difference becomes
   1421 apparent if the variables are reset; consider this example:
   1422 
   1423      .SECONDEXPANSION:
   1424      AVAR = top
   1425      onefile: $(AVAR)
   1426      twofile: $$(AVAR)
   1427      AVAR = bottom
   1428 
   1429    Here the prerequisite of `onefile' will be expanded immediately, and
   1430 resolve to the value `top', while the prerequisite of `twofile' will
   1431 not be full expanded until the secondary expansion and yield a value of
   1432 `bottom'.
   1433 
   1434    This is marginally more exciting, but the true power of this feature
   1435 only becomes apparent when you discover that secondary expansions
   1436 always take place within the scope of the automatic variables for that
   1437 target.  This means that you can use variables such as `$@', `$*', etc.
   1438 during the second expansion and they will have their expected values,
   1439 just as in the command script.  All you have to do is defer the
   1440 expansion by escaping the `$'.  Also, secondary expansion occurs for
   1441 both explicit and implicit (pattern) rules.  Knowing this, the possible
   1442 uses for this feature increase dramatically.  For example:
   1443 
   1444      .SECONDEXPANSION:
   1445      main_OBJS := main.o try.o test.o
   1446      lib_OBJS := lib.o api.o
   1447 
   1448      main lib: $$($$@_OBJS)
   1449 
   1450    Here, after the initial expansion the prerequisites of both the
   1451 `main' and `lib' targets will be `$($@_OBJS)'.  During the secondary
   1452 expansion, the `$@' variable is set to the name of the target and so
   1453 the expansion for the `main' target will yield `$(main_OBJS)', or
   1454 `main.o try.o test.o', while the secondary expansion for the `lib'
   1455 target will yield `$(lib_OBJS)', or `lib.o api.o'.
   1456 
   1457    You can also mix functions here, as long as they are properly
   1458 escaped:
   1459 
   1460      main_SRCS := main.c try.c test.c
   1461      lib_SRCS := lib.c api.c
   1462 
   1463      .SECONDEXPANSION:
   1464      main lib: $$(patsubst %.c,%.o,$$($$@_SRCS))
   1465 
   1466    This version allows users to specify source files rather than object
   1467 files, but gives the same resulting prerequisites list as the previous
   1468 example.
   1469 
   1470    Evaluation of automatic variables during the secondary expansion
   1471 phase, especially of the target name variable `$$@', behaves similarly
   1472 to evaluation within command scripts.  However, there are some subtle
   1473 differences and "corner cases" which come into play for the different
   1474 types of rule definitions that `make' understands.  The subtleties of
   1475 using the different automatic variables are described below.
   1476 
   1477 Secondary Expansion of Explicit Rules
   1478 -------------------------------------
   1479 
   1480 During the secondary expansion of explicit rules, `$$@' and `$$%'
   1481 evaluate, respectively, to the file name of the target and, when the
   1482 target is an archive member, the target member name.  The `$$<'
   1483 variable evaluates to the first prerequisite in the first rule for this
   1484 target.  `$$^' and `$$+' evaluate to the list of all prerequisites of
   1485 rules _that have already appeared_ for the same target (`$$+' with
   1486 repetitions and `$$^' without).  The following example will help
   1487 illustrate these behaviors:
   1488 
   1489      .SECONDEXPANSION:
   1490 
   1491      foo: foo.1 bar.1 $$< $$^ $$+    # line #1
   1492 
   1493      foo: foo.2 bar.2 $$< $$^ $$+    # line #2
   1494 
   1495      foo: foo.3 bar.3 $$< $$^ $$+    # line #3
   1496 
   1497    In the first prerequisite list, all three variables (`$$<', `$$^',
   1498 and `$$+') expand to the empty string.  In the second, they will have
   1499 values `foo.1', `foo.1 bar.1', and `foo.1 bar.1' respectively.  In the
   1500 third they will have values `foo.1', `foo.1 bar.1 foo.2 bar.2', and
   1501 `foo.1 bar.1 foo.2 bar.2' respectively.
   1502 
   1503    Rules undergo secondary expansion in makefile order, except that the
   1504 rule with the command script is always evaluated last.
   1505 
   1506    The variables `$$?' and `$$*' are not available and expand to the
   1507 empty string.
   1508 
   1509 Secondary Expansion of Static Pattern Rules
   1510 -------------------------------------------
   1511 
   1512 Rules for secondary expansion of static pattern rules are identical to
   1513 those for explicit rules, above, with one exception: for static pattern
   1514 rules the `$$*' variable is set to the pattern stem.  As with explicit
   1515 rules, `$$?' is not available and expands to the empty string.
   1516 
   1517 Secondary Expansion of Implicit Rules
   1518 -------------------------------------
   1519 
   1520 As `make' searches for an implicit rule, it substitutes the stem and
   1521 then performs secondary expansion for every rule with a matching target
   1522 pattern.  The value of the automatic variables is derived in the same
   1523 fashion as for static pattern rules.  As an example:
   1524 
   1525      .SECONDEXPANSION:
   1526 
   1527      foo: bar
   1528 
   1529      foo foz: fo%: bo%
   1530 
   1531      %oo: $$< $$^ $$+ $$*
   1532 
   1533    When the implicit rule is tried for target `foo', `$$<' expands to
   1534 `bar', `$$^' expands to `bar boo', `$$+' also expands to `bar boo', and
   1535 `$$*' expands to `f'.
   1536 
   1537    Note that the directory prefix (D), as described in *note Implicit
   1538 Rule Search Algorithm: Implicit Rule Search, is appended (after
   1539 expansion) to all the patterns in the prerequisites list.  As an
   1540 example:
   1541 
   1542      .SECONDEXPANSION:
   1543 
   1544      /tmp/foo.o:
   1545 
   1546      %.o: $$(addsuffix /%.c,foo bar) foo.h
   1547 
   1548    The prerequisite list after the secondary expansion and directory
   1549 prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c
   1550 foo.h'.  If you are not interested in this reconstruction, you can use
   1551 `$$*' instead of `%' in the prerequisites list.
   1552 
   1553 
   1554 File: make.info,  Node: Rules,  Next: Commands,  Prev: Makefiles,  Up: Top
   1555 
   1556 4 Writing Rules
   1557 ***************
   1558 
   1559 A "rule" appears in the makefile and says when and how to remake
   1560 certain files, called the rule's "targets" (most often only one per
   1561 rule).  It lists the other files that are the "prerequisites" of the
   1562 target, and "commands" to use to create or update the target.
   1563 
   1564    The order of rules is not significant, except for determining the
   1565 "default goal": the target for `make' to consider, if you do not
   1566 otherwise specify one.  The default goal is the target of the first
   1567 rule in the first makefile.  If the first rule has multiple targets,
   1568 only the first target is taken as the default.  There are two
   1569 exceptions: a target starting with a period is not a default unless it
   1570 contains one or more slashes, `/', as well; and, a target that defines
   1571 a pattern rule has no effect on the default goal.  (*Note Defining and
   1572 Redefining Pattern Rules: Pattern Rules.)
   1573 
   1574    Therefore, we usually write the makefile so that the first rule is
   1575 the one for compiling the entire program or all the programs described
   1576 by the makefile (often with a target called `all').  *Note Arguments to
   1577 Specify the Goals: Goals.
   1578 
   1579 * Menu:
   1580 
   1581 * Rule Example::                An example explained.
   1582 * Rule Syntax::                 General syntax explained.
   1583 * Prerequisite Types::          There are two types of prerequisites.
   1584 * Wildcards::                   Using wildcard characters such as `*'.
   1585 * Directory Search::            Searching other directories for source files.
   1586 * Phony Targets::               Using a target that is not a real file's name.
   1587 * Force Targets::               You can use a target without commands
   1588                                   or prerequisites to mark other targets
   1589                                   as phony.
   1590 * Empty Targets::               When only the date matters and the
   1591                                   files are empty.
   1592 * Special Targets::             Targets with special built-in meanings.
   1593 * Multiple Targets::            When to make use of several targets in a rule.
   1594 * Multiple Rules::              How to use several rules with the same target.
   1595 * Static Pattern::              Static pattern rules apply to multiple targets
   1596                                   and can vary the prerequisites according to
   1597                                   the target name.
   1598 * Double-Colon::                How to use a special kind of rule to allow
   1599                                   several independent rules for one target.
   1600 * Automatic Prerequisites::     How to automatically generate rules giving
   1601                                   prerequisites from source files themselves.
   1602 
   1603 
   1604 File: make.info,  Node: Rule Example,  Next: Rule Syntax,  Prev: Rules,  Up: Rules
   1605 
   1606 4.1 Rule Example
   1607 ================
   1608 
   1609 Here is an example of a rule:
   1610 
   1611      foo.o : foo.c defs.h       # module for twiddling the frobs
   1612              cc -c -g foo.c
   1613 
   1614    Its target is `foo.o' and its prerequisites are `foo.c' and
   1615 `defs.h'.  It has one command, which is `cc -c -g foo.c'.  The command
   1616 line starts with a tab to identify it as a command.
   1617 
   1618    This rule says two things:
   1619 
   1620    * How to decide whether `foo.o' is out of date: it is out of date if
   1621      it does not exist, or if either `foo.c' or `defs.h' is more recent
   1622      than it.
   1623 
   1624    * How to update the file `foo.o': by running `cc' as stated.  The
   1625      command does not explicitly mention `defs.h', but we presume that
   1626      `foo.c' includes it, and that that is why `defs.h' was added to
   1627      the prerequisites.
   1628 
   1629 
   1630 File: make.info,  Node: Rule Syntax,  Next: Prerequisite Types,  Prev: Rule Example,  Up: Rules
   1631 
   1632 4.2 Rule Syntax
   1633 ===============
   1634 
   1635 In general, a rule looks like this:
   1636 
   1637      TARGETS : PREREQUISITES
   1638              COMMAND
   1639              ...
   1640 
   1641 or like this:
   1642 
   1643      TARGETS : PREREQUISITES ; COMMAND
   1644              COMMAND
   1645              ...
   1646 
   1647    The TARGETS are file names, separated by spaces.  Wildcard
   1648 characters may be used (*note Using Wildcard Characters in File Names:
   1649 Wildcards.) and a name of the form `A(M)' represents member M in
   1650 archive file A (*note Archive Members as Targets: Archive Members.).
   1651 Usually there is only one target per rule, but occasionally there is a
   1652 reason to have more (*note Multiple Targets in a Rule: Multiple
   1653 Targets.).
   1654 
   1655    The COMMAND lines start with a tab character.  The first command may
   1656 appear on the line after the prerequisites, with a tab character, or may
   1657 appear on the same line, with a semicolon.  Either way, the effect is
   1658 the same.  There are other differences in the syntax of command lines.
   1659 *Note Writing the Commands in Rules: Commands.
   1660 
   1661    Because dollar signs are used to start `make' variable references,
   1662 if you really want a dollar sign in a target or prerequisite you must
   1663 write two of them, `$$' (*note How to Use Variables: Using Variables.).
   1664 If you have enabled secondary expansion (*note Secondary Expansion::)
   1665 and you want a literal dollar sign in the prerequisites lise, you must
   1666 actually write _four_ dollar signs (`$$$$').
   1667 
   1668    You may split a long line by inserting a backslash followed by a
   1669 newline, but this is not required, as `make' places no limit on the
   1670 length of a line in a makefile.
   1671 
   1672    A rule tells `make' two things: when the targets are out of date,
   1673 and how to update them when necessary.
   1674 
   1675    The criterion for being out of date is specified in terms of the
   1676 PREREQUISITES, which consist of file names separated by spaces.
   1677 (Wildcards and archive members (*note Archives::) are allowed here too.)
   1678 A target is out of date if it does not exist or if it is older than any
   1679 of the prerequisites (by comparison of last-modification times).  The
   1680 idea is that the contents of the target file are computed based on
   1681 information in the prerequisites, so if any of the prerequisites
   1682 changes, the contents of the existing target file are no longer
   1683 necessarily valid.
   1684 
   1685    How to update is specified by COMMANDS.  These are lines to be
   1686 executed by the shell (normally `sh'), but with some extra features
   1687 (*note Writing the Commands in Rules: Commands.).
   1688 
   1689 
   1690 File: make.info,  Node: Prerequisite Types,  Next: Wildcards,  Prev: Rule Syntax,  Up: Rules
   1691 
   1692 4.3 Types of Prerequisites
   1693 ==========================
   1694 
   1695 There are actually two different types of prerequisites understood by
   1696 GNU `make': normal prerequisites such as described in the previous
   1697 section, and "order-only" prerequisites.  A normal prerequisite makes
   1698 two statements: first, it imposes an order of execution of build
   1699 commands: any commands necessary to build any of a target's
   1700 prerequisites will be fully executed before any commands necessary to
   1701 build the target.  Second, it imposes a dependency relationship: if any
   1702 prerequisite is newer than the target, then the target is considered
   1703 out-of-date and must be rebuilt.
   1704 
   1705    Normally, this is exactly what you want: if a target's prerequisite
   1706 is updated, then the target should also be updated.
   1707 
   1708    Occasionally, however, you have a situation where you want to impose
   1709 a specific ordering on the rules to be invoked _without_ forcing the
   1710 target to be updated if one of those rules is executed.  In that case,
   1711 you want to define "order-only" prerequisites.  Order-only
   1712 prerequisites can be specified by placing a pipe symbol (`|') in the
   1713 prerequisites list: any prerequisites to the left of the pipe symbol
   1714 are normal; any prerequisites to the right are order-only:
   1715 
   1716      TARGETS : NORMAL-PREREQUISITES | ORDER-ONLY-PREREQUISITES
   1717 
   1718    The normal prerequisites section may of course be empty.  Also, you
   1719 may still declare multiple lines of prerequisites for the same target:
   1720 they are appended appropriately.  Note that if you declare the same
   1721 file to be both a normal and an order-only prerequisite, the normal
   1722 prerequisite takes precedence (since they are a strict superset of the
   1723 behavior of an order-only prerequisite).
   1724 
   1725 
   1726 File: make.info,  Node: Wildcards,  Next: Directory Search,  Prev: Prerequisite Types,  Up: Rules
   1727 
   1728 4.4 Using Wildcard Characters in File Names
   1729 ===========================================
   1730 
   1731 A single file name can specify many files using "wildcard characters".
   1732 The wildcard characters in `make' are `*', `?' and `[...]', the same as
   1733 in the Bourne shell.  For example, `*.c' specifies a list of all the
   1734 files (in the working directory) whose names end in `.c'.
   1735 
   1736    The character `~' at the beginning of a file name also has special
   1737 significance.  If alone, or followed by a slash, it represents your home
   1738 directory.  For example `~/bin' expands to `/home/you/bin'.  If the `~'
   1739 is followed by a word, the string represents the home directory of the
   1740 user named by that word.  For example `~john/bin' expands to
   1741 `/home/john/bin'.  On systems which don't have a home directory for
   1742 each user (such as MS-DOS or MS-Windows), this functionality can be
   1743 simulated by setting the environment variable HOME.
   1744 
   1745    Wildcard expansion is performed by `make' automatically in targets
   1746 and in prerequisites.  In commands the shell is responsible for
   1747 wildcard expansion.  In other contexts, wildcard expansion happens only
   1748 if you request it explicitly with the `wildcard' function.
   1749 
   1750    The special significance of a wildcard character can be turned off by
   1751 preceding it with a backslash.  Thus, `foo\*bar' would refer to a
   1752 specific file whose name consists of `foo', an asterisk, and `bar'.
   1753 
   1754 * Menu:
   1755 
   1756 * Wildcard Examples::           Several examples
   1757 * Wildcard Pitfall::            Problems to avoid.
   1758 * Wildcard Function::           How to cause wildcard expansion where
   1759                                   it does not normally take place.
   1760 
   1761 
   1762 File: make.info,  Node: Wildcard Examples,  Next: Wildcard Pitfall,  Prev: Wildcards,  Up: Wildcards
   1763 
   1764 4.4.1 Wildcard Examples
   1765 -----------------------
   1766 
   1767 Wildcards can be used in the commands of a rule, where they are expanded
   1768 by the shell.  For example, here is a rule to delete all the object
   1769 files:
   1770 
   1771      clean:
   1772              rm -f *.o
   1773 
   1774    Wildcards are also useful in the prerequisites of a rule.  With the
   1775 following rule in the makefile, `make print' will print all the `.c'
   1776 files that have changed since the last time you printed them:
   1777 
   1778      print: *.c
   1779              lpr -p $?
   1780              touch print
   1781 
   1782 This rule uses `print' as an empty target file; see *note Empty Target
   1783 Files to Record Events: Empty Targets.  (The automatic variable `$?' is
   1784 used to print only those files that have changed; see *note Automatic
   1785 Variables::.)
   1786 
   1787    Wildcard expansion does not happen when you define a variable.
   1788 Thus, if you write this:
   1789 
   1790      objects = *.o
   1791 
   1792 then the value of the variable `objects' is the actual string `*.o'.
   1793 However, if you use the value of `objects' in a target, prerequisite or
   1794 command, wildcard expansion will take place at that time.  To set
   1795 `objects' to the expansion, instead use:
   1796 
   1797      objects := $(wildcard *.o)
   1798 
   1799 *Note Wildcard Function::.
   1800 
   1801 
   1802 File: make.info,  Node: Wildcard Pitfall,  Next: Wildcard Function,  Prev: Wildcard Examples,  Up: Wildcards
   1803 
   1804 4.4.2 Pitfalls of Using Wildcards
   1805 ---------------------------------
   1806 
   1807 Now here is an example of a naive way of using wildcard expansion, that
   1808 does not do what you would intend.  Suppose you would like to say that
   1809 the executable file `foo' is made from all the object files in the
   1810 directory, and you write this:
   1811 
   1812      objects = *.o
   1813 
   1814      foo : $(objects)
   1815              cc -o foo $(CFLAGS) $(objects)
   1816 
   1817 The value of `objects' is the actual string `*.o'.  Wildcard expansion
   1818 happens in the rule for `foo', so that each _existing_ `.o' file
   1819 becomes a prerequisite of `foo' and will be recompiled if necessary.
   1820 
   1821    But what if you delete all the `.o' files?  When a wildcard matches
   1822 no files, it is left as it is, so then `foo' will depend on the
   1823 oddly-named file `*.o'.  Since no such file is likely to exist, `make'
   1824 will give you an error saying it cannot figure out how to make `*.o'.
   1825 This is not what you want!
   1826 
   1827    Actually it is possible to obtain the desired result with wildcard
   1828 expansion, but you need more sophisticated techniques, including the
   1829 `wildcard' function and string substitution.  *Note The Function
   1830 `wildcard': Wildcard Function.
   1831 
   1832    Microsoft operating systems (MS-DOS and MS-Windows) use backslashes
   1833 to separate directories in pathnames, like so:
   1834 
   1835        c:\foo\bar\baz.c
   1836 
   1837    This is equivalent to the Unix-style `c:/foo/bar/baz.c' (the `c:'
   1838 part is the so-called drive letter).  When `make' runs on these
   1839 systems, it supports backslashes as well as the Unix-style forward
   1840 slashes in pathnames.  However, this support does _not_ include the
   1841 wildcard expansion, where backslash is a quote character.  Therefore,
   1842 you _must_ use Unix-style slashes in these cases.
   1843 
   1844 
   1845 File: make.info,  Node: Wildcard Function,  Prev: Wildcard Pitfall,  Up: Wildcards
   1846 
   1847 4.4.3 The Function `wildcard'
   1848 -----------------------------
   1849 
   1850 Wildcard expansion happens automatically in rules.  But wildcard
   1851 expansion does not normally take place when a variable is set, or
   1852 inside the arguments of a function.  If you want to do wildcard
   1853 expansion in such places, you need to use the `wildcard' function, like
   1854 this:
   1855 
   1856      $(wildcard PATTERN...)
   1857 
   1858 This string, used anywhere in a makefile, is replaced by a
   1859 space-separated list of names of existing files that match one of the
   1860 given file name patterns.  If no existing file name matches a pattern,
   1861 then that pattern is omitted from the output of the `wildcard'
   1862 function.  Note that this is different from how unmatched wildcards
   1863 behave in rules, where they are used verbatim rather than ignored
   1864 (*note Wildcard Pitfall::).
   1865 
   1866    One use of the `wildcard' function is to get a list of all the C
   1867 source files in a directory, like this:
   1868 
   1869      $(wildcard *.c)
   1870 
   1871    We can change the list of C source files into a list of object files
   1872 by replacing the `.c' suffix with `.o' in the result, like this:
   1873 
   1874      $(patsubst %.c,%.o,$(wildcard *.c))
   1875 
   1876 (Here we have used another function, `patsubst'.  *Note Functions for
   1877 String Substitution and Analysis: Text Functions.)
   1878 
   1879    Thus, a makefile to compile all C source files in the directory and
   1880 then link them together could be written as follows:
   1881 
   1882      objects := $(patsubst %.c,%.o,$(wildcard *.c))
   1883 
   1884      foo : $(objects)
   1885              cc -o foo $(objects)
   1886 
   1887 (This takes advantage of the implicit rule for compiling C programs, so
   1888 there is no need to write explicit rules for compiling the files.
   1889 *Note The Two Flavors of Variables: Flavors, for an explanation of
   1890 `:=', which is a variant of `='.)
   1891 
   1892 
   1893 File: make.info,  Node: Directory Search,  Next: Phony Targets,  Prev: Wildcards,  Up: Rules
   1894 
   1895 4.5 Searching Directories for Prerequisites
   1896 ===========================================
   1897 
   1898 For large systems, it is often desirable to put sources in a separate
   1899 directory from the binaries.  The "directory search" features of `make'
   1900 facilitate this by searching several directories automatically to find
   1901 a prerequisite.  When you redistribute the files among directories, you
   1902 do not need to change the individual rules, just the search paths.
   1903 
   1904 * Menu:
   1905 
   1906 * General Search::              Specifying a search path that applies
   1907                                   to every prerequisite.
   1908 * Selective Search::            Specifying a search path
   1909                                   for a specified class of names.
   1910 * Search Algorithm::            When and how search paths are applied.
   1911 * Commands/Search::             How to write shell commands that work together
   1912                                   with search paths.
   1913 * Implicit/Search::             How search paths affect implicit rules.
   1914 * Libraries/Search::            Directory search for link libraries.
   1915 
   1916 
   1917 File: make.info,  Node: General Search,  Next: Selective Search,  Prev: Directory Search,  Up: Directory Search
   1918 
   1919 4.5.1 `VPATH': Search Path for All Prerequisites
   1920 ------------------------------------------------
   1921 
   1922 The value of the `make' variable `VPATH' specifies a list of
   1923 directories that `make' should search.  Most often, the directories are
   1924 expected to contain prerequisite files that are not in the current
   1925 directory; however, `make' uses `VPATH' as a search list for both
   1926 prerequisites and targets of rules.
   1927 
   1928    Thus, if a file that is listed as a target or prerequisite does not
   1929 exist in the current directory, `make' searches the directories listed
   1930 in `VPATH' for a file with that name.  If a file is found in one of
   1931 them, that file may become the prerequisite (see below).  Rules may then
   1932 specify the names of files in the prerequisite list as if they all
   1933 existed in the current directory.  *Note Writing Shell Commands with
   1934 Directory Search: Commands/Search.
   1935 
   1936    In the `VPATH' variable, directory names are separated by colons or
   1937 blanks.  The order in which directories are listed is the order followed
   1938 by `make' in its search.  (On MS-DOS and MS-Windows, semi-colons are
   1939 used as separators of directory names in `VPATH', since the colon can
   1940 be used in the pathname itself, after the drive letter.)
   1941 
   1942    For example,
   1943 
   1944      VPATH = src:../headers
   1945 
   1946 specifies a path containing two directories, `src' and `../headers',
   1947 which `make' searches in that order.
   1948 
   1949    With this value of `VPATH', the following rule,
   1950 
   1951      foo.o : foo.c
   1952 
   1953 is interpreted as if it were written like this:
   1954 
   1955      foo.o : src/foo.c
   1956 
   1957 assuming the file `foo.c' does not exist in the current directory but
   1958 is found in the directory `src'.
   1959 
   1960 
   1961 File: make.info,  Node: Selective Search,  Next: Search Algorithm,  Prev: General Search,  Up: Directory Search
   1962 
   1963 4.5.2 The `vpath' Directive
   1964 ---------------------------
   1965 
   1966 Similar to the `VPATH' variable, but more selective, is the `vpath'
   1967 directive (note lower case), which allows you to specify a search path
   1968 for a particular class of file names: those that match a particular
   1969 pattern.  Thus you can supply certain search directories for one class
   1970 of file names and other directories (or none) for other file names.
   1971 
   1972    There are three forms of the `vpath' directive:
   1973 
   1974 `vpath PATTERN DIRECTORIES'
   1975      Specify the search path DIRECTORIES for file names that match
   1976      PATTERN.
   1977 
   1978      The search path, DIRECTORIES, is a list of directories to be
   1979      searched, separated by colons (semi-colons on MS-DOS and
   1980      MS-Windows) or blanks, just like the search path used in the
   1981      `VPATH' variable.
   1982 
   1983 `vpath PATTERN'
   1984      Clear out the search path associated with PATTERN.
   1985 
   1986 `vpath'
   1987      Clear all search paths previously specified with `vpath'
   1988      directives.
   1989 
   1990    A `vpath' pattern is a string containing a `%' character.  The
   1991 string must match the file name of a prerequisite that is being searched
   1992 for, the `%' character matching any sequence of zero or more characters
   1993 (as in pattern rules; *note Defining and Redefining Pattern Rules:
   1994 Pattern Rules.).  For example, `%.h' matches files that end in `.h'.
   1995 (If there is no `%', the pattern must match the prerequisite exactly,
   1996 which is not useful very often.)
   1997 
   1998    `%' characters in a `vpath' directive's pattern can be quoted with
   1999 preceding backslashes (`\').  Backslashes that would otherwise quote
   2000 `%' characters can be quoted with more backslashes.  Backslashes that
   2001 quote `%' characters or other backslashes are removed from the pattern
   2002 before it is compared to file names.  Backslashes that are not in
   2003 danger of quoting `%' characters go unmolested.
   2004 
   2005    When a prerequisite fails to exist in the current directory, if the
   2006 PATTERN in a `vpath' directive matches the name of the prerequisite
   2007 file, then the DIRECTORIES in that directive are searched just like
   2008 (and before) the directories in the `VPATH' variable.
   2009 
   2010    For example,
   2011 
   2012      vpath %.h ../headers
   2013 
   2014 tells `make' to look for any prerequisite whose name ends in `.h' in
   2015 the directory `../headers' if the file is not found in the current
   2016 directory.
   2017 
   2018    If several `vpath' patterns match the prerequisite file's name, then
   2019 `make' processes each matching `vpath' directive one by one, searching
   2020 all the directories mentioned in each directive.  `make' handles
   2021 multiple `vpath' directives in the order in which they appear in the
   2022 makefile; multiple directives with the same pattern are independent of
   2023 each other.
   2024 
   2025    Thus,
   2026 
   2027      vpath %.c foo
   2028      vpath %   blish
   2029      vpath %.c bar
   2030 
   2031 will look for a file ending in `.c' in `foo', then `blish', then `bar',
   2032 while
   2033 
   2034      vpath %.c foo:bar
   2035      vpath %   blish
   2036 
   2037 will look for a file ending in `.c' in `foo', then `bar', then `blish'.
   2038 
   2039 
   2040 File: make.info,  Node: Search Algorithm,  Next: Commands/Search,  Prev: Selective Search,  Up: Directory Search
   2041 
   2042 4.5.3 How Directory Searches are Performed
   2043 ------------------------------------------
   2044 
   2045 When a prerequisite is found through directory search, regardless of
   2046 type (general or selective), the pathname located may not be the one
   2047 that `make' actually provides you in the prerequisite list.  Sometimes
   2048 the path discovered through directory search is thrown away.
   2049 
   2050    The algorithm `make' uses to decide whether to keep or abandon a
   2051 path found via directory search is as follows:
   2052 
   2053   1. If a target file does not exist at the path specified in the
   2054      makefile, directory search is performed.
   2055 
   2056   2. If the directory search is successful, that path is kept and this
   2057      file is tentatively stored as the target.
   2058 
   2059   3. All prerequisites of this target are examined using this same
   2060      method.
   2061 
   2062   4. After processing the prerequisites, the target may or may not need
   2063      to be rebuilt:
   2064 
   2065        a. If the target does _not_ need to be rebuilt, the path to the
   2066           file found during directory search is used for any
   2067           prerequisite lists which contain this target.  In short, if
   2068           `make' doesn't need to rebuild the target then you use the
   2069           path found via directory search.
   2070 
   2071        b. If the target _does_ need to be rebuilt (is out-of-date), the
   2072           pathname found during directory search is _thrown away_, and
   2073           the target is rebuilt using the file name specified in the
   2074           makefile.  In short, if `make' must rebuild, then the target
   2075           is rebuilt locally, not in the directory found via directory
   2076           search.
   2077 
   2078    This algorithm may seem complex, but in practice it is quite often
   2079 exactly what you want.
   2080 
   2081    Other versions of `make' use a simpler algorithm: if the file does
   2082 not exist, and it is found via directory search, then that pathname is
   2083 always used whether or not the target needs to be built.  Thus, if the
   2084 target is rebuilt it is created at the pathname discovered during
   2085 directory search.
   2086 
   2087    If, in fact, this is the behavior you want for some or all of your
   2088 directories, you can use the `GPATH' variable to indicate this to
   2089 `make'.
   2090 
   2091    `GPATH' has the same syntax and format as `VPATH' (that is, a space-
   2092 or colon-delimited list of pathnames).  If an out-of-date target is
   2093 found by directory search in a directory that also appears in `GPATH',
   2094 then that pathname is not thrown away.  The target is rebuilt using the
   2095 expanded path.
   2096 
   2097 
   2098 File: make.info,  Node: Commands/Search,  Next: Implicit/Search,  Prev: Search Algorithm,  Up: Directory Search
   2099 
   2100 4.5.4 Writing Shell Commands with Directory Search
   2101 --------------------------------------------------
   2102 
   2103 When a prerequisite is found in another directory through directory
   2104 search, this cannot change the commands of the rule; they will execute
   2105 as written.  Therefore, you must write the commands with care so that
   2106 they will look for the prerequisite in the directory where `make' finds
   2107 it.
   2108 
   2109    This is done with the "automatic variables" such as `$^' (*note
   2110 Automatic Variables::).  For instance, the value of `$^' is a list of
   2111 all the prerequisites of the rule, including the names of the
   2112 directories in which they were found, and the value of `$@' is the
   2113 target.  Thus:
   2114 
   2115      foo.o : foo.c
   2116              cc -c $(CFLAGS) $^ -o $@
   2117 
   2118 (The variable `CFLAGS' exists so you can specify flags for C
   2119 compilation by implicit rules; we use it here for consistency so it will
   2120 affect all C compilations uniformly; *note Variables Used by Implicit
   2121 Rules: Implicit Variables.)
   2122 
   2123    Often the prerequisites include header files as well, which you do
   2124 not want to mention in the commands.  The automatic variable `$<' is
   2125 just the first prerequisite:
   2126 
   2127      VPATH = src:../headers
   2128      foo.o : foo.c defs.h hack.h
   2129              cc -c $(CFLAGS) $< -o $@
   2130 
   2131 
   2132 File: make.info,  Node: Implicit/Search,  Next: Libraries/Search,  Prev: Commands/Search,  Up: Directory Search
   2133 
   2134 4.5.5 Directory Search and Implicit Rules
   2135 -----------------------------------------
   2136 
   2137 The search through the directories specified in `VPATH' or with `vpath'
   2138 also happens during consideration of implicit rules (*note Using
   2139 Implicit Rules: Implicit Rules.).
   2140 
   2141    For example, when a file `foo.o' has no explicit rule, `make'
   2142 considers implicit rules, such as the built-in rule to compile `foo.c'
   2143 if that file exists.  If such a file is lacking in the current
   2144 directory, the appropriate directories are searched for it.  If `foo.c'
   2145 exists (or is mentioned in the makefile) in any of the directories, the
   2146 implicit rule for C compilation is applied.
   2147 
   2148    The commands of implicit rules normally use automatic variables as a
   2149 matter of necessity; consequently they will use the file names found by
   2150 directory search with no extra effort.
   2151 
   2152 
   2153 File: make.info,  Node: Libraries/Search,  Prev: Implicit/Search,  Up: Directory Search
   2154 
   2155 4.5.6 Directory Search for Link Libraries
   2156 -----------------------------------------
   2157 
   2158 Directory search applies in a special way to libraries used with the
   2159 linker.  This special feature comes into play when you write a
   2160 prerequisite whose name is of the form `-lNAME'.  (You can tell
   2161 something strange is going on here because the prerequisite is normally
   2162 the name of a file, and the _file name_ of a library generally looks
   2163 like `libNAME.a', not like `-lNAME'.)
   2164 
   2165    When a prerequisite's name has the form `-lNAME', `make' handles it
   2166 specially by searching for the file `libNAME.so' in the current
   2167 directory, in directories specified by matching `vpath' search paths
   2168 and the `VPATH' search path, and then in the directories `/lib',
   2169 `/usr/lib', and `PREFIX/lib' (normally `/usr/local/lib', but
   2170 MS-DOS/MS-Windows versions of `make' behave as if PREFIX is defined to
   2171 be the root of the DJGPP installation tree).
   2172 
   2173    If that file is not found, then the file `libNAME.a' is searched
   2174 for, in the same directories as above.
   2175 
   2176    For example, if there is a `/usr/lib/libcurses.a' library on your
   2177 system (and no `/usr/lib/libcurses.so' file), then
   2178 
   2179      foo : foo.c -lcurses
   2180              cc $^ -o $@
   2181 
   2182 would cause the command `cc foo.c /usr/lib/libcurses.a -o foo' to be
   2183 executed when `foo' is older than `foo.c' or than
   2184 `/usr/lib/libcurses.a'.
   2185 
   2186    Although the default set of files to be searched for is `libNAME.so'
   2187 and `libNAME.a', this is customizable via the `.LIBPATTERNS' variable.
   2188 Each word in the value of this variable is a pattern string.  When a
   2189 prerequisite like `-lNAME' is seen, `make' will replace the percent in
   2190 each pattern in the list with NAME and perform the above directory
   2191 searches using that library filename.  If no library is found, the next
   2192 word in the list will be used.
   2193 
   2194    The default value for `.LIBPATTERNS' is `lib%.so lib%.a', which
   2195 provides the default behavior described above.
   2196 
   2197    You can turn off link library expansion completely by setting this
   2198 variable to an empty value.
   2199 
   2200 
   2201 File: make.info,  Node: Phony Targets,  Next: Force Targets,  Prev: Directory Search,  Up: Rules
   2202 
   2203 4.6 Phony Targets
   2204 =================
   2205 
   2206 A phony target is one that is not really the name of a file.  It is
   2207 just a name for some commands to be executed when you make an explicit
   2208 request.  There are two reasons to use a phony target: to avoid a
   2209 conflict with a file of the same name, and to improve performance.
   2210 
   2211    If you write a rule whose commands will not create the target file,
   2212 the commands will be executed every time the target comes up for
   2213 remaking.  Here is an example:
   2214 
   2215      clean:
   2216              rm *.o temp
   2217 
   2218 Because the `rm' command does not create a file named `clean', probably
   2219 no such file will ever exist.  Therefore, the `rm' command will be
   2220 executed every time you say `make clean'.  
   2221 
   2222    The phony target will cease to work if anything ever does create a
   2223 file named `clean' in this directory.  Since it has no prerequisites,
   2224 the file `clean' would inevitably be considered up to date, and its
   2225 commands would not be executed.  To avoid this problem, you can
   2226 explicitly declare the target to be phony, using the special target
   2227 `.PHONY' (*note Special Built-in Target Names: Special Targets.) as
   2228 follows:
   2229 
   2230      .PHONY : clean
   2231 
   2232 Once this is done, `make clean' will run the commands regardless of
   2233 whether there is a file named `clean'.
   2234 
   2235    Since it knows that phony targets do not name actual files that
   2236 could be remade from other files, `make' skips the implicit rule search
   2237 for phony targets (*note Implicit Rules::).  This is why declaring a
   2238 target phony is good for performance, even if you are not worried about
   2239 the actual file existing.
   2240 
   2241    Thus, you first write the line that states that `clean' is a phony
   2242 target, then you write the rule, like this:
   2243 
   2244      .PHONY: clean
   2245      clean:
   2246              rm *.o temp
   2247 
   2248    Another example of the usefulness of phony targets is in conjunction
   2249 with recursive invocations of `make' (for more information, see *note
   2250 Recursive Use of `make': Recursion.).  In this case the makefile will
   2251 often contain a variable which lists a number of subdirectories to be
   2252 built.  One way to handle this is with one rule whose command is a
   2253 shell loop over the subdirectories, like this:
   2254 
   2255      SUBDIRS = foo bar baz
   2256 
   2257      subdirs:
   2258              for dir in $(SUBDIRS); do \
   2259                $(MAKE) -C $$dir; \
   2260              done
   2261 
   2262    There are a few problems with this method, however.  First, any error
   2263 detected in a submake is not noted by this rule, so it will continue to
   2264 build the rest of the directories even when one fails.  This can be
   2265 overcome by adding shell commands to note the error and exit, but then
   2266 it will do so even if `make' is invoked with the `-k' option, which is
   2267 unfortunate.  Second, and perhaps more importantly, you cannot take
   2268 advantage of `make''s ability to build targets in parallel (*note
   2269 Parallel Execution: Parallel.), since there is only one rule.
   2270 
   2271    By declaring the subdirectories as phony targets (you must do this as
   2272 the subdirectory obviously always exists; otherwise it won't be built)
   2273 you can remove these problems:
   2274 
   2275      SUBDIRS = foo bar baz
   2276 
   2277      .PHONY: subdirs $(SUBDIRS)
   2278 
   2279      subdirs: $(SUBDIRS)
   2280 
   2281      $(SUBDIRS):
   2282              $(MAKE) -C $@
   2283 
   2284      foo: baz
   2285 
   2286    Here we've also declared that the `foo' subdirectory cannot be built
   2287 until after the `baz' subdirectory is complete; this kind of
   2288 relationship declaration is particularly important when attempting
   2289 parallel builds.
   2290 
   2291    A phony target should not be a prerequisite of a real target file;
   2292 if it is, its commands are run every time `make' goes to update that
   2293 file.  As long as a phony target is never a prerequisite of a real
   2294 target, the phony target commands will be executed only when the phony
   2295 target is a specified goal (*note Arguments to Specify the Goals:
   2296 Goals.).
   2297 
   2298    Phony targets can have prerequisites.  When one directory contains
   2299 multiple programs, it is most convenient to describe all of the
   2300 programs in one makefile `./Makefile'.  Since the target remade by
   2301 default will be the first one in the makefile, it is common to make
   2302 this a phony target named `all' and give it, as prerequisites, all the
   2303 individual programs.  For example:
   2304 
   2305      all : prog1 prog2 prog3
   2306      .PHONY : all
   2307 
   2308      prog1 : prog1.o utils.o
   2309              cc -o prog1 prog1.o utils.o
   2310 
   2311      prog2 : prog2.o
   2312              cc -o prog2 prog2.o
   2313 
   2314      prog3 : prog3.o sort.o utils.o
   2315              cc -o prog3 prog3.o sort.o utils.o
   2316 
   2317 Now you can say just `make' to remake all three programs, or specify as
   2318 arguments the ones to remake (as in `make prog1 prog3').  Phoniness is
   2319 not inherited: the prerequisites of a phony target are not themselves
   2320 phony, unless explicitly declared to be so.
   2321 
   2322    When one phony target is a prerequisite of another, it serves as a
   2323 subroutine of the other.  For example, here `make cleanall' will delete
   2324 the object files, the difference files, and the file `program':
   2325 
   2326      .PHONY: cleanall cleanobj cleandiff
   2327 
   2328      cleanall : cleanobj cleandiff
   2329              rm program
   2330 
   2331      cleanobj :
   2332              rm *.o
   2333 
   2334      cleandiff :
   2335              rm *.diff
   2336 
   2337 
   2338 File: make.info,  Node: Force Targets,  Next: Empty Targets,  Prev: Phony Targets,  Up: Rules
   2339 
   2340 4.7 Rules without Commands or Prerequisites
   2341 ===========================================
   2342 
   2343 If a rule has no prerequisites or commands, and the target of the rule
   2344 is a nonexistent file, then `make' imagines this target to have been
   2345 updated whenever its rule is run.  This implies that all targets
   2346 depending on this one will always have their commands run.
   2347 
   2348    An example will illustrate this:
   2349 
   2350      clean: FORCE
   2351              rm $(objects)
   2352      FORCE:
   2353 
   2354    Here the target `FORCE' satisfies the special conditions, so the
   2355 target `clean' that depends on it is forced to run its commands.  There
   2356 is nothing special about the name `FORCE', but that is one name
   2357 commonly used this way.
   2358 
   2359    As you can see, using `FORCE' this way has the same results as using
   2360 `.PHONY: clean'.
   2361 
   2362    Using `.PHONY' is more explicit and more efficient.  However, other
   2363 versions of `make' do not support `.PHONY'; thus `FORCE' appears in
   2364 many makefiles.  *Note Phony Targets::.
   2365 
   2366 
   2367 File: make.info,  Node: Empty Targets,  Next: Special Targets,  Prev: Force Targets,  Up: Rules
   2368 
   2369 4.8 Empty Target Files to Record Events
   2370 =======================================
   2371 
   2372 The "empty target" is a variant of the phony target; it is used to hold
   2373 commands for an action that you request explicitly from time to time.
   2374 Unlike a phony target, this target file can really exist; but the file's
   2375 contents do not matter, and usually are empty.
   2376 
   2377    The purpose of the empty target file is to record, with its
   2378 last-modification time, when the rule's commands were last executed.  It
   2379 does so because one of the commands is a `touch' command to update the
   2380 target file.
   2381 
   2382    The empty target file should have some prerequisites (otherwise it
   2383 doesn't make sense).  When you ask to remake the empty target, the
   2384 commands are executed if any prerequisite is more recent than the
   2385 target; in other words, if a prerequisite has changed since the last
   2386 time you remade the target.  Here is an example:
   2387 
   2388      print: foo.c bar.c
   2389              lpr -p $?
   2390              touch print
   2391    
   2392 With this rule, `make print' will execute the `lpr' command if either
   2393 source file has changed since the last `make print'.  The automatic
   2394 variable `$?' is used to print only those files that have changed
   2395 (*note Automatic Variables::).
   2396 
   2397 
   2398 File: make.info,  Node: Special Targets,  Next: Multiple Targets,  Prev: Empty Targets,  Up: Rules
   2399 
   2400 4.9 Special Built-in Target Names
   2401 =================================
   2402 
   2403 Certain names have special meanings if they appear as targets.
   2404 
   2405 `.PHONY'
   2406      The prerequisites of the special target `.PHONY' are considered to
   2407      be phony targets.  When it is time to consider such a target,
   2408      `make' will run its commands unconditionally, regardless of
   2409      whether a file with that name exists or what its last-modification
   2410      time is.  *Note Phony Targets: Phony Targets.
   2411 
   2412 `.SUFFIXES'
   2413      The prerequisites of the special target `.SUFFIXES' are the list
   2414      of suffixes to be used in checking for suffix rules.  *Note
   2415      Old-Fashioned Suffix Rules: Suffix Rules.
   2416 
   2417 `.DEFAULT'
   2418      The commands specified for `.DEFAULT' are used for any target for
   2419      which no rules are found (either explicit rules or implicit rules).
   2420      *Note Last Resort::.  If `.DEFAULT' commands are specified, every
   2421      file mentioned as a prerequisite, but not as a target in a rule,
   2422      will have these commands executed on its behalf.  *Note Implicit
   2423      Rule Search Algorithm: Implicit Rule Search.
   2424 
   2425 `.PRECIOUS'
   2426      The targets which `.PRECIOUS' depends on are given the following
   2427      special treatment: if `make' is killed or interrupted during the
   2428      execution of their commands, the target is not deleted.  *Note
   2429      Interrupting or Killing `make': Interrupts.  Also, if the target
   2430      is an intermediate file, it will not be deleted after it is no
   2431      longer needed, as is normally done.  *Note Chains of Implicit
   2432      Rules: Chained Rules.  In this latter respect it overlaps with the
   2433      `.SECONDARY' special target.
   2434 
   2435      You can also list the target pattern of an implicit rule (such as
   2436      `%.o') as a prerequisite file of the special target `.PRECIOUS' to
   2437      preserve intermediate files created by rules whose target patterns
   2438      match that file's name.
   2439 
   2440 `.INTERMEDIATE'
   2441      The targets which `.INTERMEDIATE' depends on are treated as
   2442      intermediate files.  *Note Chains of Implicit Rules: Chained Rules.
   2443      `.INTERMEDIATE' with no prerequisites has no effect.
   2444 
   2445 `.SECONDARY'
   2446      The targets which `.SECONDARY' depends on are treated as
   2447      intermediate files, except that they are never automatically
   2448      deleted.  *Note Chains of Implicit Rules: Chained Rules.
   2449 
   2450      `.SECONDARY' with no prerequisites causes all targets to be treated
   2451      as secondary (i.e., no target is removed because it is considered
   2452      intermediate).
   2453 
   2454 `.SECONDEXPANSION'
   2455      If `.SECONDEXPANSION' is mentioned as a target anywhere in the
   2456      makefile, then all prerequisite lists defined _after_ it appears
   2457      will be expanded a second time after all makefiles have been read
   2458      in.  *Note Secondary Expansion: Secondary Expansion.
   2459 
   2460      The prerequisites of the special target `.SUFFIXES' are the list
   2461      of suffixes to be used in checking for suffix rules.  *Note
   2462      Old-Fashioned Suffix Rules: Suffix Rules.
   2463 
   2464 `.DELETE_ON_ERROR'
   2465      If `.DELETE_ON_ERROR' is mentioned as a target anywhere in the
   2466      makefile, then `make' will delete the target of a rule if it has
   2467      changed and its commands exit with a nonzero exit status, just as
   2468      it does when it receives a signal.  *Note Errors in Commands:
   2469      Errors.
   2470 
   2471 `.IGNORE'
   2472      If you specify prerequisites for `.IGNORE', then `make' will
   2473      ignore errors in execution of the commands run for those particular
   2474      files.  The commands for `.IGNORE' are not meaningful.
   2475 
   2476      If mentioned as a target with no prerequisites, `.IGNORE' says to
   2477      ignore errors in execution of commands for all files.  This usage
   2478      of `.IGNORE' is supported only for historical compatibility.  Since
   2479      this affects every command in the makefile, it is not very useful;
   2480      we recommend you use the more selective ways to ignore errors in
   2481      specific commands.  *Note Errors in Commands: Errors.
   2482 
   2483 `.LOW_RESOLUTION_TIME'
   2484      If you specify prerequisites for `.LOW_RESOLUTION_TIME', `make'
   2485      assumes that these files are created by commands that generate low
   2486      resolution time stamps.  The commands for `.LOW_RESOLUTION_TIME'
   2487      are not meaningful.
   2488 
   2489      The high resolution file time stamps of many modern hosts lessen
   2490      the chance of `make' incorrectly concluding that a file is up to
   2491      date.  Unfortunately, these hosts provide no way to set a high
   2492      resolution file time stamp, so commands like `cp -p' that
   2493      explicitly set a file's time stamp must discard its subsecond
   2494      part.  If a file is created by such a command, you should list it
   2495      as a prerequisite of `.LOW_RESOLUTION_TIME' so that `make' does
   2496      not mistakenly conclude that the file is out of date.  For example:
   2497 
   2498           .LOW_RESOLUTION_TIME: dst
   2499           dst: src
   2500                   cp -p src dst
   2501 
   2502      Since `cp -p' discards the subsecond part of `src''s time stamp,
   2503      `dst' is typically slightly older than `src' even when it is up to
   2504      date.  The `.LOW_RESOLUTION_TIME' line causes `make' to consider
   2505      `dst' to be up to date if its time stamp is at the start of the
   2506      same second that `src''s time stamp is in.
   2507 
   2508      Due to a limitation of the archive format, archive member time
   2509      stamps are always low resolution.  You need not list archive
   2510      members as prerequisites of `.LOW_RESOLUTION_TIME', as `make' does
   2511      this automatically.
   2512 
   2513 `.SILENT'
   2514      If you specify prerequisites for `.SILENT', then `make' will not
   2515      print the commands to remake those particular files before
   2516      executing them.  The commands for `.SILENT' are not meaningful.
   2517 
   2518      If mentioned as a target with no prerequisites, `.SILENT' says not
   2519      to print any commands before executing them.  This usage of
   2520      `.SILENT' is supported only for historical compatibility.  We
   2521      recommend you use the more selective ways to silence specific
   2522      commands.  *Note Command Echoing: Echoing.  If you want to silence
   2523      all commands for a particular run of `make', use the `-s' or
   2524      `--silent' option (*note Options Summary::).
   2525 
   2526 `.EXPORT_ALL_VARIABLES'
   2527      Simply by being mentioned as a target, this tells `make' to export
   2528      all variables to child processes by default.  *Note Communicating
   2529      Variables to a Sub-`make': Variables/Recursion.
   2530 
   2531 `.NOTPARALLEL'
   2532      If `.NOTPARALLEL' is mentioned as a target, then this invocation of
   2533      `make' will be run serially, even if the `-j' option is given.
   2534      Any recursively invoked `make' command will still be run in
   2535      parallel (unless its makefile contains this target).  Any
   2536      prerequisites on this target are ignored.
   2537 
   2538    Any defined implicit rule suffix also counts as a special target if
   2539 it appears as a target, and so does the concatenation of two suffixes,
   2540 such as `.c.o'.  These targets are suffix rules, an obsolete way of
   2541 defining implicit rules (but a way still widely used).  In principle,
   2542 any target name could be special in this way if you break it in two and
   2543 add both pieces to the suffix list.  In practice, suffixes normally
   2544 begin with `.', so these special target names also begin with `.'.
   2545 *Note Old-Fashioned Suffix Rules: Suffix Rules.
   2546 
   2547 
   2548 File: make.info,  Node: Multiple Targets,  Next: Multiple Rules,  Prev: Special Targets,  Up: Rules
   2549 
   2550 4.10 Multiple Targets in a Rule
   2551 ===============================
   2552 
   2553 A rule with multiple targets is equivalent to writing many rules, each
   2554 with one target, and all identical aside from that.  The same commands
   2555 apply to all the targets, but their effects may vary because you can
   2556 substitute the actual target name into the command using `$@'.  The
   2557 rule contributes the same prerequisites to all the targets also.
   2558 
   2559    This is useful in two cases.
   2560 
   2561    * You want just prerequisites, no commands.  For example:
   2562 
   2563           kbd.o command.o files.o: command.h
   2564 
   2565      gives an additional prerequisite to each of the three object files
   2566      mentioned.
   2567 
   2568    * Similar commands work for all the targets.  The commands do not
   2569      need to be absolutely identical, since the automatic variable `$@'
   2570      can be used to substitute the particular target to be remade into
   2571      the commands (*note Automatic Variables::).  For example:
   2572 
   2573           bigoutput littleoutput : text.g
   2574                   generate text.g -$(subst output,,$@) > $@
   2575      
   2576      is equivalent to
   2577 
   2578           bigoutput : text.g
   2579                   generate text.g -big > bigoutput
   2580           littleoutput : text.g
   2581                   generate text.g -little > littleoutput
   2582 
   2583      Here we assume the hypothetical program `generate' makes two types
   2584      of output, one if given `-big' and one if given `-little'.  *Note
   2585      Functions for String Substitution and Analysis: Text Functions,
   2586      for an explanation of the `subst' function.
   2587 
   2588    Suppose you would like to vary the prerequisites according to the
   2589 target, much as the variable `$@' allows you to vary the commands.  You
   2590 cannot do this with multiple targets in an ordinary rule, but you can
   2591 do it with a "static pattern rule".  *Note Static Pattern Rules: Static
   2592 Pattern.
   2593 
   2594 
   2595 File: make.info,  Node: Multiple Rules,  Next: Static Pattern,  Prev: Multiple Targets,  Up: Rules
   2596 
   2597 4.11 Multiple Rules for One Target
   2598 ==================================
   2599 
   2600 One file can be the target of several rules.  All the prerequisites
   2601 mentioned in all the rules are merged into one list of prerequisites for
   2602 the target.  If the target is older than any prerequisite from any rule,
   2603 the commands are executed.
   2604 
   2605    There can only be one set of commands to be executed for a file.  If
   2606 more than one rule gives commands for the same file, `make' uses the
   2607 last set given and prints an error message.  (As a special case, if the
   2608 file's name begins with a dot, no error message is printed.  This odd
   2609 behavior is only for compatibility with other implementations of
   2610 `make'... you should avoid using it).  Occasionally it is useful to
   2611 have the same target invoke multiple commands which are defined in
   2612 different parts of your makefile; you can use "double-colon rules"
   2613 (*note Double-Colon::) for this.
   2614 
   2615    An extra rule with just prerequisites can be used to give a few extra
   2616 prerequisites to many files at once.  For example, makefiles often have
   2617 a variable, such as `objects', containing a list of all the compiler
   2618 output files in the system being made.  An easy way to say that all of
   2619 them must be recompiled if `config.h' changes is to write the following:
   2620 
   2621      objects = foo.o bar.o
   2622      foo.o : defs.h
   2623      bar.o : defs.h test.h
   2624      $(objects) : config.h
   2625 
   2626    This could be inserted or taken out without changing the rules that
   2627 really specify how to make the object files, making it a convenient
   2628 form to use if you wish to add the additional prerequisite
   2629 intermittently.
   2630 
   2631    Another wrinkle is that the additional prerequisites could be
   2632 specified with a variable that you set with a command argument to `make'
   2633 (*note Overriding Variables: Overriding.).  For example,
   2634 
   2635      extradeps=
   2636      $(objects) : $(extradeps)
   2637 
   2638 means that the command `make extradeps=foo.h' will consider `foo.h' as
   2639 a prerequisite of each object file, but plain `make' will not.
   2640 
   2641    If none of the explicit rules for a target has commands, then `make'
   2642 searches for an applicable implicit rule to find some commands *note
   2643 Using Implicit Rules: Implicit Rules.).
   2644 
   2645 
   2646 File: make.info,  Node: Static Pattern,  Next: Double-Colon,  Prev: Multiple Rules,  Up: Rules
   2647 
   2648 4.12 Static Pattern Rules
   2649 =========================
   2650 
   2651 "Static pattern rules" are rules which specify multiple targets and
   2652 construct the prerequisite names for each target based on the target
   2653 name.  They are more general than ordinary rules with multiple targets
   2654 because the targets do not have to have identical prerequisites.  Their
   2655 prerequisites must be _analogous_, but not necessarily _identical_.
   2656 
   2657 * Menu:
   2658 
   2659 * Static Usage::                The syntax of static pattern rules.
   2660 * Static versus Implicit::      When are they better than implicit rules?
   2661 
   2662 
   2663 File: make.info,  Node: Static Usage,  Next: Static versus Implicit,  Prev: Static Pattern,  Up: Static Pattern
   2664 
   2665 4.12.1 Syntax of Static Pattern Rules
   2666 -------------------------------------
   2667 
   2668 Here is the syntax of a static pattern rule:
   2669 
   2670      TARGETS ...: TARGET-PATTERN: PREREQ-PATTERNS ...
   2671              COMMANDS
   2672              ...
   2673 
   2674 The TARGETS list specifies the targets that the rule applies to.  The
   2675 targets can contain wildcard characters, just like the targets of
   2676 ordinary rules (*note Using Wildcard Characters in File Names:
   2677 Wildcards.).
   2678 
   2679    The TARGET-PATTERN and PREREQ-PATTERNS say how to compute the
   2680 prerequisites of each target.  Each target is matched against the
   2681 TARGET-PATTERN to extract a part of the target name, called the "stem".
   2682 This stem is substituted into each of the PREREQ-PATTERNS to make the
   2683 prerequisite names (one from each PREREQ-PATTERN).
   2684 
   2685    Each pattern normally contains the character `%' just once.  When the
   2686 TARGET-PATTERN matches a target, the `%' can match any part of the
   2687 target name; this part is called the "stem".  The rest of the pattern
   2688 must match exactly.  For example, the target `foo.o' matches the
   2689 pattern `%.o', with `foo' as the stem.  The targets `foo.c' and
   2690 `foo.out' do not match that pattern.
   2691 
   2692    The prerequisite names for each target are made by substituting the
   2693 stem for the `%' in each prerequisite pattern.  For example, if one
   2694 prerequisite pattern is `%.c', then substitution of the stem `foo'
   2695 gives the prerequisite name `foo.c'.  It is legitimate to write a
   2696 prerequisite pattern that does not contain `%'; then this prerequisite
   2697 is the same for all targets.
   2698 
   2699    `%' characters in pattern rules can be quoted with preceding
   2700 backslashes (`\').  Backslashes that would otherwise quote `%'
   2701 characters can be quoted with more backslashes.  Backslashes that quote
   2702 `%' characters or other backslashes are removed from the pattern before
   2703 it is compared to file names or has a stem substituted into it.
   2704 Backslashes that are not in danger of quoting `%' characters go
   2705 unmolested.  For example, the pattern `the\%weird\\%pattern\\' has
   2706 `the%weird\' preceding the operative `%' character, and `pattern\\'
   2707 following it.  The final two backslashes are left alone because they
   2708 cannot affect any `%' character.
   2709 
   2710    Here is an example, which compiles each of `foo.o' and `bar.o' from
   2711 the corresponding `.c' file:
   2712 
   2713      objects = foo.o bar.o
   2714 
   2715      all: $(objects)
   2716 
   2717      $(objects): %.o: %.c
   2718              $(CC) -c $(CFLAGS) $< -o $@
   2719 
   2720 Here `$<' is the automatic variable that holds the name of the
   2721 prerequisite and `$@' is the automatic variable that holds the name of
   2722 the target; see *note Automatic Variables::.
   2723 
   2724    Each target specified must match the target pattern; a warning is
   2725 issued for each target that does not.  If you have a list of files,
   2726 only some of which will match the pattern, you can use the `filter'
   2727 function to remove nonmatching file names (*note Functions for String
   2728 Substitution and Analysis: Text Functions.):
   2729 
   2730      files = foo.elc bar.o lose.o
   2731 
   2732      $(filter %.o,$(files)): %.o: %.c
   2733              $(CC) -c $(CFLAGS) $< -o $@
   2734      $(filter %.elc,$(files)): %.elc: %.el
   2735              emacs -f batch-byte-compile $<
   2736 
   2737 In this example the result of `$(filter %.o,$(files))' is `bar.o
   2738 lose.o', and the first static pattern rule causes each of these object
   2739 files to be updated by compiling the corresponding C source file.  The
   2740 result of `$(filter %.elc,$(files))' is `foo.elc', so that file is made
   2741 from `foo.el'.
   2742 
   2743    Another example shows how to use `$*' in static pattern rules: 
   2744 
   2745      bigoutput littleoutput : %output : text.g
   2746              generate text.g -$* > $@
   2747 
   2748 When the `generate' command is run, `$*' will expand to the stem,
   2749 either `big' or `little'.
   2750 
   2751 
   2752 File: make.info,  Node: Static versus Implicit,  Prev: Static Usage,  Up: Static Pattern
   2753 
   2754 4.12.2 Static Pattern Rules versus Implicit Rules
   2755 -------------------------------------------------
   2756 
   2757 A static pattern rule has much in common with an implicit rule defined
   2758 as a pattern rule (*note Defining and Redefining Pattern Rules: Pattern
   2759 Rules.).  Both have a pattern for the target and patterns for
   2760 constructing the names of prerequisites.  The difference is in how
   2761 `make' decides _when_ the rule applies.
   2762 
   2763    An implicit rule _can_ apply to any target that matches its pattern,
   2764 but it _does_ apply only when the target has no commands otherwise
   2765 specified, and only when the prerequisites can be found.  If more than
   2766 one implicit rule appears applicable, only one applies; the choice
   2767 depends on the order of rules.
   2768 
   2769    By contrast, a static pattern rule applies to the precise list of
   2770 targets that you specify in the rule.  It cannot apply to any other
   2771 target and it invariably does apply to each of the targets specified.
   2772 If two conflicting rules apply, and both have commands, that's an error.
   2773 
   2774    The static pattern rule can be better than an implicit rule for these
   2775 reasons:
   2776 
   2777    * You may wish to override the usual implicit rule for a few files
   2778      whose names cannot be categorized syntactically but can be given
   2779      in an explicit list.
   2780 
   2781    * If you cannot be sure of the precise contents of the directories
   2782      you are using, you may not be sure which other irrelevant files
   2783      might lead `make' to use the wrong implicit rule.  The choice
   2784      might depend on the order in which the implicit rule search is
   2785      done.  With static pattern rules, there is no uncertainty: each
   2786      rule applies to precisely the targets specified.
   2787 
   2788 
   2789 File: make.info,  Node: Double-Colon,  Next: Automatic Prerequisites,  Prev: Static Pattern,  Up: Rules
   2790 
   2791 4.13 Double-Colon Rules
   2792 =======================
   2793 
   2794 "Double-colon" rules are rules written with `::' instead of `:' after
   2795 the target names.  They are handled differently from ordinary rules
   2796 when the same target appears in more than one rule.
   2797 
   2798    When a target appears in multiple rules, all the rules must be the
   2799 same type: all ordinary, or all double-colon.  If they are
   2800 double-colon, each of them is independent of the others.  Each
   2801 double-colon rule's commands are executed if the target is older than
   2802 any prerequisites of that rule.  If there are no prerequisites for that
   2803 rule, its commands are always executed (even if the target already
   2804 exists).  This can result in executing none, any, or all of the
   2805 double-colon rules.
   2806 
   2807    Double-colon rules with the same target are in fact completely
   2808 separate from one another.  Each double-colon rule is processed
   2809 individually, just as rules with different targets are processed.
   2810 
   2811    The double-colon rules for a target are executed in the order they
   2812 appear in the makefile.  However, the cases where double-colon rules
   2813 really make sense are those where the order of executing the commands
   2814 would not matter.
   2815 
   2816    Double-colon rules are somewhat obscure and not often very useful;
   2817 they provide a mechanism for cases in which the method used to update a
   2818 target differs depending on which prerequisite files caused the update,
   2819 and such cases are rare.
   2820 
   2821    Each double-colon rule should specify commands; if it does not, an
   2822 implicit rule will be used if one applies.  *Note Using Implicit Rules:
   2823 Implicit Rules.
   2824 
   2825 
   2826 File: make.info,  Node: Automatic Prerequisites,  Prev: Double-Colon,  Up: Rules
   2827 
   2828 4.14 Generating Prerequisites Automatically
   2829 ===========================================
   2830 
   2831 In the makefile for a program, many of the rules you need to write often
   2832 say only that some object file depends on some header file.  For
   2833 example, if `main.c' uses `defs.h' via an `#include', you would write:
   2834 
   2835      main.o: defs.h
   2836 
   2837 You need this rule so that `make' knows that it must remake `main.o'
   2838 whenever `defs.h' changes.  You can see that for a large program you
   2839 would have to write dozens of such rules in your makefile.  And, you
   2840 must always be very careful to update the makefile every time you add
   2841 or remove an `#include'.  
   2842 
   2843    To avoid this hassle, most modern C compilers can write these rules
   2844 for you, by looking at the `#include' lines in the source files.
   2845 Usually this is done with the `-M' option to the compiler.  For
   2846 example, the command:
   2847 
   2848      cc -M main.c
   2849 
   2850 generates the output:
   2851 
   2852      main.o : main.c defs.h
   2853 
   2854 Thus you no longer have to write all those rules yourself.  The
   2855 compiler will do it for you.
   2856 
   2857    Note that such a prerequisite constitutes mentioning `main.o' in a
   2858 makefile, so it can never be considered an intermediate file by implicit
   2859 rule search.  This means that `make' won't ever remove the file after
   2860 using it; *note Chains of Implicit Rules: Chained Rules.
   2861 
   2862    With old `make' programs, it was traditional practice to use this
   2863 compiler feature to generate prerequisites on demand with a command like
   2864 `make depend'.  That command would create a file `depend' containing
   2865 all the automatically-generated prerequisites; then the makefile could
   2866 use `include' to read them in (*note Include::).
   2867 
   2868    In GNU `make', the feature of remaking makefiles makes this practice
   2869 obsolete--you need never tell `make' explicitly to regenerate the
   2870 prerequisites, because it always regenerates any makefile that is out
   2871 of date.  *Note Remaking Makefiles::.
   2872 
   2873    The practice we recommend for automatic prerequisite generation is
   2874 to have one makefile corresponding to each source file.  For each
   2875 source file `NAME.c' there is a makefile `NAME.d' which lists what
   2876 files the object file `NAME.o' depends on.  That way only the source
   2877 files that have changed need to be rescanned to produce the new
   2878 prerequisites.
   2879 
   2880    Here is the pattern rule to generate a file of prerequisites (i.e.,
   2881 a makefile) called `NAME.d' from a C source file called `NAME.c':
   2882 
   2883      %.d: %.c
   2884              @set -e; rm -f $@; \
   2885               $(CC) -M $(CPPFLAGS) $< > $@.$$$$; \
   2886               sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
   2887               rm -f $@.$$$$
   2888 
   2889 *Note Pattern Rules::, for information on defining pattern rules.  The
   2890 `-e' flag to the shell causes it to exit immediately if the `$(CC)'
   2891 command (or any other command) fails (exits with a nonzero status).  
   2892 
   2893    With the GNU C compiler, you may wish to use the `-MM' flag instead
   2894 of `-M'.  This omits prerequisites on system header files.  *Note
   2895 Options Controlling the Preprocessor: (gcc.info)Preprocessor Options,
   2896 for details.
   2897 
   2898    The purpose of the `sed' command is to translate (for example):
   2899 
   2900      main.o : main.c defs.h
   2901 
   2902 into:
   2903 
   2904      main.o main.d : main.c defs.h
   2905 
   2906 This makes each `.d' file depend on all the source and header files
   2907 that the corresponding `.o' file depends on.  `make' then knows it must
   2908 regenerate the prerequisites whenever any of the source or header files
   2909 changes.
   2910 
   2911    Once you've defined the rule to remake the `.d' files, you then use
   2912 the `include' directive to read them all in.  *Note Include::.  For
   2913 example:
   2914 
   2915      sources = foo.c bar.c
   2916 
   2917      include $(sources:.c=.d)
   2918 
   2919 (This example uses a substitution variable reference to translate the
   2920 list of source files `foo.c bar.c' into a list of prerequisite
   2921 makefiles, `foo.d bar.d'.  *Note Substitution Refs::, for full
   2922 information on substitution references.)  Since the `.d' files are
   2923 makefiles like any others, `make' will remake them as necessary with no
   2924 further work from you.  *Note Remaking Makefiles::.
   2925 
   2926    Note that the `.d' files contain target definitions; you should be
   2927 sure to place the `include' directive _after_ the first, default goal
   2928 in your makefiles or run the risk of having a random object file become
   2929 the default goal.  *Note How Make Works::.
   2930 
   2931 
   2932 File: make.info,  Node: Commands,  Next: Using Variables,  Prev: Rules,  Up: Top
   2933 
   2934 5 Writing the Commands in Rules
   2935 *******************************
   2936 
   2937 The commands of a rule consist of one or more shell command lines to be
   2938 executed, one at a time, in the order they appear.  Typically, the
   2939 result of executing these commands is that the target of the rule is
   2940 brought up to date.
   2941 
   2942    Users use many different shell programs, but commands in makefiles
   2943 are always interpreted by `/bin/sh' unless the makefile specifies
   2944 otherwise.  *Note Command Execution: Execution.
   2945 
   2946 * Menu:
   2947 
   2948 * Command Syntax::              Command syntax features and pitfalls.
   2949 * Echoing::                     How to control when commands are echoed.
   2950 * Execution::                   How commands are executed.
   2951 * Parallel::                    How commands can be executed in parallel.
   2952 * Errors::                      What happens after a command execution error.
   2953 * Interrupts::                  What happens when a command is interrupted.
   2954 * Recursion::                   Invoking `make' from makefiles.
   2955 * Sequences::                   Defining canned sequences of commands.
   2956 * Empty Commands::              Defining useful, do-nothing commands.
   2957 
   2958 
   2959 File: make.info,  Node: Command Syntax,  Next: Echoing,  Prev: Commands,  Up: Commands
   2960 
   2961 5.1 Command Syntax
   2962 ==================
   2963 
   2964 Makefiles have the unusual property that there are really two distinct
   2965 syntaxes in one file.  Most of the makefile uses `make' syntax (*note
   2966 Writing Makefiles: Makefiles.).  However, commands are meant to be
   2967 interpreted by the shell and so they are written using shell syntax.
   2968 The `make' program does not try to understand shell syntax: it performs
   2969 only a very few specific translations on the content of the command
   2970 before handing it to the shell.
   2971 
   2972    Each command line must start with a tab, except that the first
   2973 command line may be attached to the target-and-prerequisites line with a
   2974 semicolon in between.  _Any_ line in the makefile that begins with a
   2975 tab and appears in a "rule context" (that is, after a rule has been
   2976 started until another rule or variable definition) will be considered a
   2977 command line for that rule.  Blank lines and lines of just comments may
   2978 appear among the command lines; they are ignored.
   2979 
   2980    Some consequences of these rules include:
   2981 
   2982    * A blank line that begins with a tab is not blank: it's an empty
   2983      command (*note Empty Commands::).
   2984 
   2985    * A comment in a command line is not a `make' comment; it will be
   2986      passed to the shell as-is.  Whether the shell treats it as a
   2987      comment or not depends on your shell.
   2988 
   2989    * A variable definition in a "rule context" which is indented by a
   2990      tab as the first character on the line, will be considered a
   2991      command line, not a `make' variable definition, and passed to the
   2992      shell.
   2993 
   2994    * A conditional expression (`ifdef', `ifeq', etc. *note Syntax of
   2995      Conditionals: Conditional Syntax.) in a "rule context" which is
   2996      indented by a tab as the first character on the line, will be
   2997      considered a command line and be passed to the shell.
   2998 
   2999 
   3000 * Menu:
   3001 
   3002 * Splitting Lines::             Breaking long command lines for readability.
   3003 * Variables in Commands::       Using `make' variables in commands.
   3004 
   3005 
   3006 File: make.info,  Node: Splitting Lines,  Next: Variables in Commands,  Prev: Command Syntax,  Up: Command Syntax
   3007 
   3008 5.1.1 Splitting Command Lines
   3009 -----------------------------
   3010 
   3011 One of the few ways in which `make' does interpret command lines is
   3012 checking for a backslash just before the newline.  As in normal
   3013 makefile syntax, a single command can be split into multiple lines in
   3014 the makefile by placing a backslash before each newline.  A sequence of
   3015 lines like this is considered a single command, and one instance of the
   3016 shell will be invoked to run it.
   3017 
   3018    However, in contrast to how they are treated in other places in a
   3019 makefile, backslash-newline pairs are _not_ removed from the command.
   3020 Both the backslash and the newline characters are preserved and passed
   3021 to the shell.  How the backslash-newline is interpreted depends on your
   3022 shell.  If the first character of the next line after the
   3023 backslash-newline is a tab, then that tab (and only that tab) is
   3024 removed.  Whitespace is never added to the command.
   3025 
   3026    For example, this makefile:
   3027 
   3028      all :
   3029              @echo no\
   3030      space
   3031              @echo no\
   3032              space
   3033              @echo one \
   3034              space
   3035              @echo one\
   3036               space
   3037 
   3038 consists of four separate shell commands where the output is:
   3039 
   3040      nospace
   3041      nospace
   3042      one space
   3043      one space
   3044 
   3045    As a more complex example, this makefile:
   3046 
   3047      all : ; @echo 'hello \
   3048              world' ; echo "hello \
   3049          world"
   3050 
   3051 will run one shell with a command script of:
   3052 
   3053      echo 'hello \
   3054      world' ; echo "hello \
   3055          world"
   3056 
   3057 which, according to shell quoting rules, will yield the following
   3058 output:
   3059 
   3060      hello \
   3061      world
   3062      hello     world
   3063 
   3064 Notice how the backslash/newline pair was removed inside the string
   3065 quoted with double quotes (`"..."'), but not from the string quoted
   3066 with single quotes (`'...'').  This is the way the default shell
   3067 (`/bin/sh') handles backslash/newline pairs.  If you specify a
   3068 different shell in your makefiles it may treat them differently.
   3069 
   3070    Sometimes you want to split a long line inside of single quotes, but
   3071 you don't want the backslash-newline to appear in the quoted content.
   3072 This is often the case when passing scripts to languages such as Perl,
   3073 where extraneous backslashes inside the script can change its meaning
   3074 or even be a syntax error.  One simple way of handling this is to place
   3075 the quoted string, or even the entire command, into a `make' variable
   3076 then use the variable in the command.  In this situation the newline
   3077 quoting rules for makefiles will be used, and the backslash-newline
   3078 will be removed.  If we rewrite our example above using this method:
   3079 
   3080      HELLO = 'hello \
   3081      world'
   3082 
   3083      all : ; @echo $(HELLO)
   3084 
   3085 we will get output like this:
   3086 
   3087      hello world
   3088 
   3089    If you like, you can also use target-specific variables (*note
   3090 Target-specific Variable Values: Target-specific.) to obtain a tighter
   3091 correspondence between the variable and the command that uses it.
   3092 
   3093 
   3094 File: make.info,  Node: Variables in Commands,  Prev: Splitting Lines,  Up: Command Syntax
   3095 
   3096 5.1.2 Using Variables in Commands
   3097 ---------------------------------
   3098 
   3099 The other way in which `make' processes commands is by expanding any
   3100 variable references in them (*note Basics of Variable References:
   3101 Reference.).  This occurs after make has finished reading all the
   3102 makefiles and the target is determined to be out of date; so, the
   3103 commands for targets which are not rebuilt are never expanded.
   3104 
   3105    Variable and function references in commands have identical syntax
   3106 and semantics to references elsewhere in the makefile.  They also have
   3107 the same quoting rules: if you want a dollar sign to appear in your
   3108 command, you must double it (`$$').  For shells like the default shell,
   3109 that use dollar signs to introduce variables, it's important to keep
   3110 clear in your mind whether the variable you want to reference is a
   3111 `make' variable (use a single dollar sign) or a shell variable (use two
   3112 dollar signs).  For example:
   3113 
   3114      LIST = one two three
   3115      all:
   3116              for i in $(LIST); do \
   3117                  echo $$i; \
   3118              done
   3119 
   3120 results in the following command being passed to the shell:
   3121 
   3122      for i in one two three; do \
   3123          echo $i; \
   3124      done
   3125 
   3126 which generates the expected result:
   3127 
   3128      one
   3129      two
   3130      three
   3131 
   3132 
   3133 File: make.info,  Node: Echoing,  Next: Execution,  Prev: Command Syntax,  Up: Commands
   3134 
   3135 5.2 Command Echoing
   3136 ===================
   3137 
   3138 Normally `make' prints each command line before it is executed.  We
   3139 call this "echoing" because it gives the appearance that you are typing
   3140 the commands yourself.
   3141 
   3142    When a line starts with `@', the echoing of that line is suppressed.
   3143 The `@' is discarded before the command is passed to the shell.
   3144 Typically you would use this for a command whose only effect is to print
   3145 something, such as an `echo' command to indicate progress through the
   3146 makefile:
   3147 
   3148      @echo About to make distribution files
   3149 
   3150    When `make' is given the flag `-n' or `--just-print' it only echoes
   3151 commands, it won't execute them.  *Note Summary of Options: Options
   3152 Summary.  In this case and only this case, even the commands starting
   3153 with `@' are printed.  This flag is useful for finding out which
   3154 commands `make' thinks are necessary without actually doing them.
   3155 
   3156    The `-s' or `--silent' flag to `make' prevents all echoing, as if
   3157 all commands started with `@'.  A rule in the makefile for the special
   3158 target `.SILENT' without prerequisites has the same effect (*note
   3159 Special Built-in Target Names: Special Targets.).  `.SILENT' is
   3160 essentially obsolete since `@' is more flexible.
   3161 
   3162 
   3163 File: make.info,  Node: Execution,  Next: Parallel,  Prev: Echoing,  Up: Commands
   3164 
   3165 5.3 Command Execution
   3166 =====================
   3167 
   3168 When it is time to execute commands to update a target, they are
   3169 executed by invoking a new subshell for each command line.  (In
   3170 practice, `make' may take shortcuts that do not affect the results.)
   3171 
   3172    *Please note:* this implies that setting shell variables and
   3173 invoking shell commands such as `cd' that set a context local to each
   3174 process will not affect the following command lines.(1)  If you want to
   3175 use `cd' to affect the next statement, put both statements in a single
   3176 command line.  Then `make' will invoke one shell to run the entire
   3177 line, and the shell will execute the statements in sequence.  For
   3178 example:
   3179 
   3180      foo : bar/lose
   3181              cd $(@D) && gobble $(@F) > ../$@
   3182 
   3183 Here we use the shell AND operator (`&&') so that if the `cd' command
   3184 fails, the script will fail without trying to invoke the `gobble'
   3185 command in the wrong directory, which could cause problems (in this
   3186 case it would certainly cause `../foo' to be truncated, at least).
   3187 
   3188 * Menu:
   3189 
   3190 * Choosing the Shell::          How `make' chooses the shell used
   3191                                   to run commands.
   3192 
   3193    ---------- Footnotes ----------
   3194 
   3195    (1) On MS-DOS, the value of current working directory is *global*, so
   3196 changing it _will_ affect the following command lines on those systems.
   3197 
   3198 
   3199 File: make.info,  Node: Choosing the Shell,  Prev: Execution,  Up: Execution
   3200 
   3201 5.3.1 Choosing the Shell
   3202 ------------------------
   3203 
   3204 The program used as the shell is taken from the variable `SHELL'.  If
   3205 this variable is not set in your makefile, the program `/bin/sh' is
   3206 used as the shell.
   3207 
   3208    Unlike most variables, the variable `SHELL' is never set from the
   3209 environment.  This is because the `SHELL' environment variable is used
   3210 to specify your personal choice of shell program for interactive use.
   3211 It would be very bad for personal choices like this to affect the
   3212 functioning of makefiles.  *Note Variables from the Environment:
   3213 Environment.
   3214 
   3215    Furthermore, when you do set `SHELL' in your makefile that value is
   3216 _not_ exported in the environment to commands that `make' invokes.
   3217 Instead, the value inherited from the user's environment, if any, is
   3218 exported.  You can override this behavior by explicitly exporting
   3219 `SHELL' (*note Communicating Variables to a Sub-`make':
   3220 Variables/Recursion.), forcing it to be passed in the environment to
   3221 commands.
   3222 
   3223    However, on MS-DOS and MS-Windows the value of `SHELL' in the
   3224 environment *is* used, since on those systems most users do not set
   3225 this variable, and therefore it is most likely set specifically to be
   3226 used by `make'.  On MS-DOS, if the setting of `SHELL' is not suitable
   3227 for `make', you can set the variable `MAKESHELL' to the shell that
   3228 `make' should use; if set it will be used as the shell instead of the
   3229 value of `SHELL'.
   3230 
   3231 Choosing a Shell in DOS and Windows
   3232 ...................................
   3233 
   3234 Choosing a shell in MS-DOS and MS-Windows is much more complex than on
   3235 other systems.
   3236 
   3237    On MS-DOS, if `SHELL' is not set, the value of the variable
   3238 `COMSPEC' (which is always set) is used instead.
   3239 
   3240    The processing of lines that set the variable `SHELL' in Makefiles
   3241 is different on MS-DOS.  The stock shell, `command.com', is
   3242 ridiculously limited in its functionality and many users of `make' tend
   3243 to install a replacement shell.  Therefore, on MS-DOS, `make' examines
   3244 the value of `SHELL', and changes its behavior based on whether it
   3245 points to a Unix-style or DOS-style shell.  This allows reasonable
   3246 functionality even if `SHELL' points to `command.com'.
   3247 
   3248    If `SHELL' points to a Unix-style shell, `make' on MS-DOS
   3249 additionally checks whether that shell can indeed be found; if not, it
   3250 ignores the line that sets `SHELL'.  In MS-DOS, GNU `make' searches for
   3251 the shell in the following places:
   3252 
   3253   1. In the precise place pointed to by the value of `SHELL'.  For
   3254      example, if the makefile specifies `SHELL = /bin/sh', `make' will
   3255      look in the directory `/bin' on the current drive.
   3256 
   3257   2. In the current directory.
   3258 
   3259   3. In each of the directories in the `PATH' variable, in order.
   3260 
   3261 
   3262    In every directory it examines, `make' will first look for the
   3263 specific file (`sh' in the example above).  If this is not found, it
   3264 will also look in that directory for that file with one of the known
   3265 extensions which identify executable files.  For example `.exe',
   3266 `.com', `.bat', `.btm', `.sh', and some others.
   3267 
   3268    If any of these attempts is successful, the value of `SHELL' will be
   3269 set to the full pathname of the shell as found.  However, if none of
   3270 these is found, the value of `SHELL' will not be changed, and thus the
   3271 line that sets it will be effectively ignored.  This is so `make' will
   3272 only support features specific to a Unix-style shell if such a shell is
   3273 actually installed on the system where `make' runs.
   3274 
   3275    Note that this extended search for the shell is limited to the cases
   3276 where `SHELL' is set from the Makefile; if it is set in the environment
   3277 or command line, you are expected to set it to the full pathname of the
   3278 shell, exactly as things are on Unix.
   3279 
   3280    The effect of the above DOS-specific processing is that a Makefile
   3281 that contains `SHELL = /bin/sh' (as many Unix makefiles do), will work
   3282 on MS-DOS unaltered if you have e.g. `sh.exe' installed in some
   3283 directory along your `PATH'.
   3284 
   3285 
   3286 File: make.info,  Node: Parallel,  Next: Errors,  Prev: Execution,  Up: Commands
   3287 
   3288 5.4 Parallel Execution
   3289 ======================
   3290 
   3291 GNU `make' knows how to execute several commands at once.  Normally,
   3292 `make' will execute only one command at a time, waiting for it to
   3293 finish before executing the next.  However, the `-j' or `--jobs' option
   3294 tells `make' to execute many commands simultaneously.
   3295 
   3296    On MS-DOS, the `-j' option has no effect, since that system doesn't
   3297 support multi-processing.
   3298 
   3299    If the `-j' option is followed by an integer, this is the number of
   3300 commands to execute at once; this is called the number of "job slots".
   3301 If there is nothing looking like an integer after the `-j' option,
   3302 there is no limit on the number of job slots.  The default number of job
   3303 slots is one, which means serial execution (one thing at a time).
   3304 
   3305    One unpleasant consequence of running several commands
   3306 simultaneously is that output generated by the commands appears
   3307 whenever each command sends it, so messages from different commands may
   3308 be interspersed.
   3309 
   3310    Another problem is that two processes cannot both take input from the
   3311 same device; so to make sure that only one command tries to take input
   3312 from the terminal at once, `make' will invalidate the standard input
   3313 streams of all but one running command.  This means that attempting to
   3314 read from standard input will usually be a fatal error (a `Broken pipe'
   3315 signal) for most child processes if there are several.  
   3316 
   3317    It is unpredictable which command will have a valid standard input
   3318 stream (which will come from the terminal, or wherever you redirect the
   3319 standard input of `make').  The first command run will always get it
   3320 first, and the first command started after that one finishes will get
   3321 it next, and so on.
   3322 
   3323    We will change how this aspect of `make' works if we find a better
   3324 alternative.  In the mean time, you should not rely on any command using
   3325 standard input at all if you are using the parallel execution feature;
   3326 but if you are not using this feature, then standard input works
   3327 normally in all commands.
   3328 
   3329    Finally, handling recursive `make' invocations raises issues.  For
   3330 more information on this, see *note Communicating Options to a
   3331 Sub-`make': Options/Recursion.
   3332 
   3333    If a command fails (is killed by a signal or exits with a nonzero
   3334 status), and errors are not ignored for that command (*note Errors in
   3335 Commands: Errors.), the remaining command lines to remake the same
   3336 target will not be run.  If a command fails and the `-k' or
   3337 `--keep-going' option was not given (*note Summary of Options: Options
   3338 Summary.), `make' aborts execution.  If make terminates for any reason
   3339 (including a signal) with child processes running, it waits for them to
   3340 finish before actually exiting.
   3341 
   3342    When the system is heavily loaded, you will probably want to run
   3343 fewer jobs than when it is lightly loaded.  You can use the `-l' option
   3344 to tell `make' to limit the number of jobs to run at once, based on the
   3345 load average.  The `-l' or `--max-load' option is followed by a
   3346 floating-point number.  For example,
   3347 
   3348      -l 2.5
   3349 
   3350 will not let `make' start more than one job if the load average is
   3351 above 2.5.  The `-l' option with no following number removes the load
   3352 limit, if one was given with a previous `-l' option.
   3353 
   3354    More precisely, when `make' goes to start up a job, and it already
   3355 has at least one job running, it checks the current load average; if it
   3356 is not lower than the limit given with `-l', `make' waits until the load
   3357 average goes below that limit, or until all the other jobs finish.
   3358 
   3359    By default, there is no load limit.
   3360 
   3361 
   3362 File: make.info,  Node: Errors,  Next: Interrupts,  Prev: Parallel,  Up: Commands
   3363 
   3364 5.5 Errors in Commands
   3365 ======================
   3366 
   3367 After each shell command returns, `make' looks at its exit status.  If
   3368 the command completed successfully, the next command line is executed
   3369 in a new shell; after the last command line is finished, the rule is
   3370 finished.
   3371 
   3372    If there is an error (the exit status is nonzero), `make' gives up on
   3373 the current rule, and perhaps on all rules.
   3374 
   3375    Sometimes the failure of a certain command does not indicate a
   3376 problem.  For example, you may use the `mkdir' command to ensure that a
   3377 directory exists.  If the directory already exists, `mkdir' will report
   3378 an error, but you probably want `make' to continue regardless.
   3379 
   3380    To ignore errors in a command line, write a `-' at the beginning of
   3381 the line's text (after the initial tab).  The `-' is discarded before
   3382 the command is passed to the shell for execution.
   3383 
   3384    For example,
   3385 
   3386      clean:
   3387              -rm -f *.o
   3388 
   3389 This causes `rm' to continue even if it is unable to remove a file.
   3390 
   3391    When you run `make' with the `-i' or `--ignore-errors' flag, errors
   3392 are ignored in all commands of all rules.  A rule in the makefile for
   3393 the special target `.IGNORE' has the same effect, if there are no
   3394 prerequisites.  These ways of ignoring errors are obsolete because `-'
   3395 is more flexible.
   3396 
   3397    When errors are to be ignored, because of either a `-' or the `-i'
   3398 flag, `make' treats an error return just like success, except that it
   3399 prints out a message that tells you the status code the command exited
   3400 with, and says that the error has been ignored.
   3401 
   3402    When an error happens that `make' has not been told to ignore, it
   3403 implies that the current target cannot be correctly remade, and neither
   3404 can any other that depends on it either directly or indirectly.  No
   3405 further commands will be executed for these targets, since their
   3406 preconditions have not been achieved.
   3407 
   3408    Normally `make' gives up immediately in this circumstance, returning
   3409 a nonzero status.  However, if the `-k' or `--keep-going' flag is
   3410 specified, `make' continues to consider the other prerequisites of the
   3411 pending targets, remaking them if necessary, before it gives up and
   3412 returns nonzero status.  For example, after an error in compiling one
   3413 object file, `make -k' will continue compiling other object files even
   3414 though it already knows that linking them will be impossible.  *Note
   3415 Summary of Options: Options Summary.
   3416 
   3417    The usual behavior assumes that your purpose is to get the specified
   3418 targets up to date; once `make' learns that this is impossible, it
   3419 might as well report the failure immediately.  The `-k' option says
   3420 that the real purpose is to test as many of the changes made in the
   3421 program as possible, perhaps to find several independent problems so
   3422 that you can correct them all before the next attempt to compile.  This
   3423 is why Emacs' `compile' command passes the `-k' flag by default.  
   3424 
   3425    Usually when a command fails, if it has changed the target file at
   3426 all, the file is corrupted and cannot be used--or at least it is not
   3427 completely updated.  Yet the file's time stamp says that it is now up to
   3428 date, so the next time `make' runs, it will not try to update that
   3429 file.  The situation is just the same as when the command is killed by a
   3430 signal; *note Interrupts::.  So generally the right thing to do is to
   3431 delete the target file if the command fails after beginning to change
   3432 the file.  `make' will do this if `.DELETE_ON_ERROR' appears as a
   3433 target.  This is almost always what you want `make' to do, but it is
   3434 not historical practice; so for compatibility, you must explicitly
   3435 request it.
   3436 
   3437 
   3438 File: make.info,  Node: Interrupts,  Next: Recursion,  Prev: Errors,  Up: Commands
   3439 
   3440 5.6 Interrupting or Killing `make'
   3441 ==================================
   3442 
   3443 If `make' gets a fatal signal while a command is executing, it may
   3444 delete the target file that the command was supposed to update.  This is
   3445 done if the target file's last-modification time has changed since
   3446 `make' first checked it.
   3447 
   3448    The purpose of deleting the target is to make sure that it is remade
   3449 from scratch when `make' is next run.  Why is this?  Suppose you type
   3450 `Ctrl-c' while a compiler is running, and it has begun to write an
   3451 object file `foo.o'.  The `Ctrl-c' kills the compiler, resulting in an
   3452 incomplete file whose last-modification time is newer than the source
   3453 file `foo.c'.  But `make' also receives the `Ctrl-c' signal and deletes
   3454 this incomplete file.  If `make' did not do this, the next invocation
   3455 of `make' would think that `foo.o' did not require updating--resulting
   3456 in a strange error message from the linker when it tries to link an
   3457 object file half of which is missing.
   3458 
   3459    You can prevent the deletion of a target file in this way by making
   3460 the special target `.PRECIOUS' depend on it.  Before remaking a target,
   3461 `make' checks to see whether it appears on the prerequisites of
   3462 `.PRECIOUS', and thereby decides whether the target should be deleted
   3463 if a signal happens.  Some reasons why you might do this are that the
   3464 target is updated in some atomic fashion, or exists only to record a
   3465 modification-time (its contents do not matter), or must exist at all
   3466 times to prevent other sorts of trouble.
   3467 
   3468 
   3469 File: make.info,  Node: Recursion,  Next: Sequences,  Prev: Interrupts,  Up: Commands
   3470 
   3471 5.7 Recursive Use of `make'
   3472 ===========================
   3473 
   3474 Recursive use of `make' means using `make' as a command in a makefile.
   3475 This technique is useful when you want separate makefiles for various
   3476 subsystems that compose a larger system.  For example, suppose you have
   3477 a subdirectory `subdir' which has its own makefile, and you would like
   3478 the containing directory's makefile to run `make' on the subdirectory.
   3479 You can do it by writing this:
   3480 
   3481      subsystem:
   3482              cd subdir && $(MAKE)
   3483 
   3484 or, equivalently, this (*note Summary of Options: Options Summary.):
   3485 
   3486      subsystem:
   3487              $(MAKE) -C subdir
   3488    
   3489    You can write recursive `make' commands just by copying this example,
   3490 but there are many things to know about how they work and why, and about
   3491 how the sub-`make' relates to the top-level `make'.  You may also find
   3492 it useful to declare targets that invoke recursive `make' commands as
   3493 `.PHONY' (for more discussion on when this is useful, see *note Phony
   3494 Targets::).
   3495 
   3496    For your convenience, when GNU `make' starts (after it has processed
   3497 any `-C' options) it sets the variable `CURDIR' to the pathname of the
   3498 current working directory.  This value is never touched by `make'
   3499 again: in particular note that if you include files from other
   3500 directories the value of `CURDIR' does not change.  The value has the
   3501 same precedence it would have if it were set in the makefile (by
   3502 default, an environment variable `CURDIR' will not override this
   3503 value).  Note that setting this variable has no impact on the operation
   3504 of `make' (it does not cause `make' to change its working directory,
   3505 for example).
   3506 
   3507 * Menu:
   3508 
   3509 * MAKE Variable::               The special effects of using `$(MAKE)'.
   3510 * Variables/Recursion::         How to communicate variables to a sub-`make'.
   3511 * Options/Recursion::           How to communicate options to a sub-`make'.
   3512 * -w Option::                   How the `-w' or `--print-directory' option
   3513                                   helps debug use of recursive `make' commands.
   3514 
   3515 
   3516 File: make.info,  Node: MAKE Variable,  Next: Variables/Recursion,  Prev: Recursion,  Up: Recursion
   3517 
   3518 5.7.1 How the `MAKE' Variable Works
   3519 -----------------------------------
   3520 
   3521 Recursive `make' commands should always use the variable `MAKE', not
   3522 the explicit command name `make', as shown here:
   3523 
   3524      subsystem:
   3525              cd subdir && $(MAKE)
   3526 
   3527    The value of this variable is the file name with which `make' was
   3528 invoked.  If this file name was `/bin/make', then the command executed
   3529 is `cd subdir && /bin/make'.  If you use a special version of `make' to
   3530 run the top-level makefile, the same special version will be executed
   3531 for recursive invocations.  
   3532 
   3533    As a special feature, using the variable `MAKE' in the commands of a
   3534 rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'),
   3535 or `-q' (`--question') option.  Using the `MAKE' variable has the same
   3536 effect as using a `+' character at the beginning of the command line.
   3537 *Note Instead of Executing the Commands: Instead of Execution.  This
   3538 special feature is only enabled if the `MAKE' variable appears directly
   3539 in the command script: it does not apply if the `MAKE' variable is
   3540 referenced through expansion of another variable.  In the latter case
   3541 you must use the `+' token to get these special effects.
   3542 
   3543    Consider the command `make -t' in the above example.  (The `-t'
   3544 option marks targets as up to date without actually running any
   3545 commands; see *note Instead of Execution::.)  Following the usual
   3546 definition of `-t', a `make -t' command in the example would create a
   3547 file named `subsystem' and do nothing else.  What you really want it to
   3548 do is run `cd subdir && make -t'; but that would require executing the
   3549 command, and `-t' says not to execute commands.  
   3550 
   3551    The special feature makes this do what you want: whenever a command
   3552 line of a rule contains the variable `MAKE', the flags `-t', `-n' and
   3553 `-q' do not apply to that line.  Command lines containing `MAKE' are
   3554 executed normally despite the presence of a flag that causes most
   3555 commands not to be run.  The usual `MAKEFLAGS' mechanism passes the
   3556 flags to the sub-`make' (*note Communicating Options to a Sub-`make':
   3557 Options/Recursion.), so your request to touch the files, or print the
   3558 commands, is propagated to the subsystem.
   3559 
   3560 
   3561 File: make.info,  Node: Variables/Recursion,  Next: Options/Recursion,  Prev: MAKE Variable,  Up: Recursion
   3562 
   3563 5.7.2 Communicating Variables to a Sub-`make'
   3564 ---------------------------------------------
   3565 
   3566 Variable values of the top-level `make' can be passed to the sub-`make'
   3567 through the environment by explicit request.  These variables are
   3568 defined in the sub-`make' as defaults, but do not override what is
   3569 specified in the makefile used by the sub-`make' makefile unless you
   3570 use the `-e' switch (*note Summary of Options: Options Summary.).
   3571 
   3572    To pass down, or "export", a variable, `make' adds the variable and
   3573 its value to the environment for running each command.  The sub-`make',
   3574 in turn, uses the environment to initialize its table of variable
   3575 values.  *Note Variables from the Environment: Environment.
   3576 
   3577    Except by explicit request, `make' exports a variable only if it is
   3578 either defined in the environment initially or set on the command line,
   3579 and if its name consists only of letters, numbers, and underscores.
   3580 Some shells cannot cope with environment variable names consisting of
   3581 characters other than letters, numbers, and underscores.
   3582 
   3583    The value of the `make' variable `SHELL' is not exported.  Instead,
   3584 the value of the `SHELL' variable from the invoking environment is
   3585 passed to the sub-`make'.  You can force `make' to export its value for
   3586 `SHELL' by using the `export' directive, described below.  *Note
   3587 Choosing the Shell::.
   3588 
   3589    The special variable `MAKEFLAGS' is always exported (unless you
   3590 unexport it).  `MAKEFILES' is exported if you set it to anything.
   3591 
   3592    `make' automatically passes down variable values that were defined
   3593 on the command line, by putting them in the `MAKEFLAGS' variable.
   3594 *Note Options/Recursion::.
   3595 
   3596    Variables are _not_ normally passed down if they were created by
   3597 default by `make' (*note Variables Used by Implicit Rules: Implicit
   3598 Variables.).  The sub-`make' will define these for itself.
   3599 
   3600    If you want to export specific variables to a sub-`make', use the
   3601 `export' directive, like this:
   3602 
   3603      export VARIABLE ...
   3604 
   3605 If you want to _prevent_ a variable from being exported, use the
   3606 `unexport' directive, like this:
   3607 
   3608      unexport VARIABLE ...
   3609 
   3610 In both of these forms, the arguments to `export' and `unexport' are
   3611 expanded, and so could be variables or functions which expand to a
   3612 (list of) variable names to be (un)exported.
   3613 
   3614    As a convenience, you can define a variable and export it at the same
   3615 time by doing:
   3616 
   3617      export VARIABLE = value
   3618 
   3619 has the same result as:
   3620 
   3621      VARIABLE = value
   3622      export VARIABLE
   3623 
   3624 and
   3625 
   3626      export VARIABLE := value
   3627 
   3628 has the same result as:
   3629 
   3630      VARIABLE := value
   3631      export VARIABLE
   3632 
   3633    Likewise,
   3634 
   3635      export VARIABLE += value
   3636 
   3637 is just like:
   3638 
   3639      VARIABLE += value
   3640      export VARIABLE
   3641 
   3642 *Note Appending More Text to Variables: Appending.
   3643 
   3644    You may notice that the `export' and `unexport' directives work in
   3645 `make' in the same way they work in the shell, `sh'.
   3646 
   3647    If you want all variables to be exported by default, you can use
   3648 `export' by itself:
   3649 
   3650      export
   3651 
   3652 This tells `make' that variables which are not explicitly mentioned in
   3653 an `export' or `unexport' directive should be exported.  Any variable
   3654 given in an `unexport' directive will still _not_ be exported.  If you
   3655 use `export' by itself to export variables by default, variables whose
   3656 names contain characters other than alphanumerics and underscores will
   3657 not be exported unless specifically mentioned in an `export' directive.
   3658 
   3659    The behavior elicited by an `export' directive by itself was the
   3660 default in older versions of GNU `make'.  If your makefiles depend on
   3661 this behavior and you want to be compatible with old versions of
   3662 `make', you can write a rule for the special target
   3663 `.EXPORT_ALL_VARIABLES' instead of using the `export' directive.  This
   3664 will be ignored by old `make's, while the `export' directive will cause
   3665 a syntax error.  
   3666 
   3667    Likewise, you can use `unexport' by itself to tell `make' _not_ to
   3668 export variables by default.  Since this is the default behavior, you
   3669 would only need to do this if `export' had been used by itself earlier
   3670 (in an included makefile, perhaps).  You *cannot* use `export' and
   3671 `unexport' by themselves to have variables exported for some commands
   3672 and not for others.  The last `export' or `unexport' directive that
   3673 appears by itself determines the behavior for the entire run of `make'.
   3674 
   3675    As a special feature, the variable `MAKELEVEL' is changed when it is
   3676 passed down from level to level.  This variable's value is a string
   3677 which is the depth of the level as a decimal number.  The value is `0'
   3678 for the top-level `make'; `1' for a sub-`make', `2' for a
   3679 sub-sub-`make', and so on.  The incrementation happens when `make' sets
   3680 up the environment for a command.
   3681 
   3682    The main use of `MAKELEVEL' is to test it in a conditional directive
   3683 (*note Conditional Parts of Makefiles: Conditionals.); this way you can
   3684 write a makefile that behaves one way if run recursively and another
   3685 way if run directly by you.
   3686 
   3687    You can use the variable `MAKEFILES' to cause all sub-`make'
   3688 commands to use additional makefiles.  The value of `MAKEFILES' is a
   3689 whitespace-separated list of file names.  This variable, if defined in
   3690 the outer-level makefile, is passed down through the environment; then
   3691 it serves as a list of extra makefiles for the sub-`make' to read
   3692 before the usual or specified ones.  *Note The Variable `MAKEFILES':
   3693 MAKEFILES Variable.
   3694 
   3695 
   3696 File: make.info,  Node: Options/Recursion,  Next: -w Option,  Prev: Variables/Recursion,  Up: Recursion
   3697 
   3698 5.7.3 Communicating Options to a Sub-`make'
   3699 -------------------------------------------
   3700 
   3701 Flags such as `-s' and `-k' are passed automatically to the sub-`make'
   3702 through the variable `MAKEFLAGS'.  This variable is set up
   3703 automatically by `make' to contain the flag letters that `make'
   3704 received.  Thus, if you do `make -ks' then `MAKEFLAGS' gets the value
   3705 `ks'.
   3706 
   3707    As a consequence, every sub-`make' gets a value for `MAKEFLAGS' in
   3708 its environment.  In response, it takes the flags from that value and
   3709 processes them as if they had been given as arguments.  *Note Summary
   3710 of Options: Options Summary.
   3711 
   3712    Likewise variables defined on the command line are passed to the
   3713 sub-`make' through `MAKEFLAGS'.  Words in the value of `MAKEFLAGS' that
   3714 contain `=', `make' treats as variable definitions just as if they
   3715 appeared on the command line.  *Note Overriding Variables: Overriding.
   3716 
   3717    The options `-C', `-f', `-o', and `-W' are not put into `MAKEFLAGS';
   3718 these options are not passed down.
   3719 
   3720    The `-j' option is a special case (*note Parallel Execution:
   3721 Parallel.).  If you set it to some numeric value `N' and your operating
   3722 system supports it (most any UNIX system will; others typically won't),
   3723 the parent `make' and all the sub-`make's will communicate to ensure
   3724 that there are only `N' jobs running at the same time between them all.
   3725 Note that any job that is marked recursive (*note Instead of Executing
   3726 the Commands: Instead of Execution.)  doesn't count against the total
   3727 jobs (otherwise we could get `N' sub-`make's running and have no slots
   3728 left over for any real work!)
   3729 
   3730    If your operating system doesn't support the above communication,
   3731 then `-j 1' is always put into `MAKEFLAGS' instead of the value you
   3732 specified.  This is because if the `-j' option were passed down to
   3733 sub-`make's, you would get many more jobs running in parallel than you
   3734 asked for.  If you give `-j' with no numeric argument, meaning to run
   3735 as many jobs as possible in parallel, this is passed down, since
   3736 multiple infinities are no more than one.
   3737 
   3738    If you do not want to pass the other flags down, you must change the
   3739 value of `MAKEFLAGS', like this:
   3740 
   3741      subsystem:
   3742              cd subdir && $(MAKE) MAKEFLAGS=
   3743 
   3744    The command line variable definitions really appear in the variable
   3745 `MAKEOVERRIDES', and `MAKEFLAGS' contains a reference to this variable.
   3746 If you do want to pass flags down normally, but don't want to pass down
   3747 the command line variable definitions, you can reset `MAKEOVERRIDES' to
   3748 empty, like this:
   3749 
   3750      MAKEOVERRIDES =
   3751 
   3752 This is not usually useful to do.  However, some systems have a small
   3753 fixed limit on the size of the environment, and putting so much
   3754 information into the value of `MAKEFLAGS' can exceed it.  If you see
   3755 the error message `Arg list too long', this may be the problem.  (For
   3756 strict compliance with POSIX.2, changing `MAKEOVERRIDES' does not
   3757 affect `MAKEFLAGS' if the special target `.POSIX' appears in the
   3758 makefile.  You probably do not care about this.)
   3759 
   3760    A similar variable `MFLAGS' exists also, for historical
   3761 compatibility.  It has the same value as `MAKEFLAGS' except that it
   3762 does not contain the command line variable definitions, and it always
   3763 begins with a hyphen unless it is empty (`MAKEFLAGS' begins with a
   3764 hyphen only when it begins with an option that has no single-letter
   3765 version, such as `--warn-undefined-variables').  `MFLAGS' was
   3766 traditionally used explicitly in the recursive `make' command, like
   3767 this:
   3768 
   3769      subsystem:
   3770              cd subdir && $(MAKE) $(MFLAGS)
   3771 
   3772 but now `MAKEFLAGS' makes this usage redundant.  If you want your
   3773 makefiles to be compatible with old `make' programs, use this
   3774 technique; it will work fine with more modern `make' versions too.
   3775 
   3776    The `MAKEFLAGS' variable can also be useful if you want to have
   3777 certain options, such as `-k' (*note Summary of Options: Options
   3778 Summary.), set each time you run `make'.  You simply put a value for
   3779 `MAKEFLAGS' in your environment.  You can also set `MAKEFLAGS' in a
   3780 makefile, to specify additional flags that should also be in effect for
   3781 that makefile.  (Note that you cannot use `MFLAGS' this way.  That
   3782 variable is set only for compatibility; `make' does not interpret a
   3783 value you set for it in any way.)
   3784 
   3785    When `make' interprets the value of `MAKEFLAGS' (either from the
   3786 environment or from a makefile), it first prepends a hyphen if the value
   3787 does not already begin with one.  Then it chops the value into words
   3788 separated by blanks, and parses these words as if they were options
   3789 given on the command line (except that `-C', `-f', `-h', `-o', `-W',
   3790 and their long-named versions are ignored; and there is no error for an
   3791 invalid option).
   3792 
   3793    If you do put `MAKEFLAGS' in your environment, you should be sure not
   3794 to include any options that will drastically affect the actions of
   3795 `make' and undermine the purpose of makefiles and of `make' itself.
   3796 For instance, the `-t', `-n', and `-q' options, if put in one of these
   3797 variables, could have disastrous consequences and would certainly have
   3798 at least surprising and probably annoying effects.
   3799 
   3800 
   3801 File: make.info,  Node: -w Option,  Prev: Options/Recursion,  Up: Recursion
   3802 
   3803 5.7.4 The `--print-directory' Option
   3804 ------------------------------------
   3805 
   3806 If you use several levels of recursive `make' invocations, the `-w' or
   3807 `--print-directory' option can make the output a lot easier to
   3808 understand by showing each directory as `make' starts processing it and
   3809 as `make' finishes processing it.  For example, if `make -w' is run in
   3810 the directory `/u/gnu/make', `make' will print a line of the form:
   3811 
   3812      make: Entering directory `/u/gnu/make'.
   3813 
   3814 before doing anything else, and a line of the form:
   3815 
   3816      make: Leaving directory `/u/gnu/make'.
   3817 
   3818 when processing is completed.
   3819 
   3820    Normally, you do not need to specify this option because `make' does
   3821 it for you: `-w' is turned on automatically when you use the `-C'
   3822 option, and in sub-`make's.  `make' will not automatically turn on `-w'
   3823 if you also use `-s', which says to be silent, or if you use
   3824 `--no-print-directory' to explicitly disable it.
   3825 
   3826 
   3827 File: make.info,  Node: Sequences,  Next: Empty Commands,  Prev: Recursion,  Up: Commands
   3828 
   3829 5.8 Defining Canned Command Sequences
   3830 =====================================
   3831 
   3832 When the same sequence of commands is useful in making various targets,
   3833 you can define it as a canned sequence with the `define' directive, and
   3834 refer to the canned sequence from the rules for those targets.  The
   3835 canned sequence is actually a variable, so the name must not conflict
   3836 with other variable names.
   3837 
   3838    Here is an example of defining a canned sequence of commands:
   3839 
   3840      define run-yacc
   3841      yacc $(firstword $^)
   3842      mv y.tab.c $@
   3843      endef
   3844    
   3845 Here `run-yacc' is the name of the variable being defined; `endef'
   3846 marks the end of the definition; the lines in between are the commands.
   3847 The `define' directive does not expand variable references and function
   3848 calls in the canned sequence; the `$' characters, parentheses, variable
   3849 names, and so on, all become part of the value of the variable you are
   3850 defining.  *Note Defining Variables Verbatim: Defining, for a complete
   3851 explanation of `define'.
   3852 
   3853    The first command in this example runs Yacc on the first
   3854 prerequisite of whichever rule uses the canned sequence.  The output
   3855 file from Yacc is always named `y.tab.c'.  The second command moves the
   3856 output to the rule's target file name.
   3857 
   3858    To use the canned sequence, substitute the variable into the
   3859 commands of a rule.  You can substitute it like any other variable
   3860 (*note Basics of Variable References: Reference.).  Because variables
   3861 defined by `define' are recursively expanded variables, all the
   3862 variable references you wrote inside the `define' are expanded now.
   3863 For example:
   3864 
   3865      foo.c : foo.y
   3866              $(run-yacc)
   3867 
   3868 `foo.y' will be substituted for the variable `$^' when it occurs in
   3869 `run-yacc''s value, and `foo.c' for `$@'.
   3870 
   3871    This is a realistic example, but this particular one is not needed in
   3872 practice because `make' has an implicit rule to figure out these
   3873 commands based on the file names involved (*note Using Implicit Rules:
   3874 Implicit Rules.).
   3875 
   3876    In command execution, each line of a canned sequence is treated just
   3877 as if the line appeared on its own in the rule, preceded by a tab.  In
   3878 particular, `make' invokes a separate subshell for each line.  You can
   3879 use the special prefix characters that affect command lines (`@', `-',
   3880 and `+') on each line of a canned sequence.  *Note Writing the Commands
   3881 in Rules: Commands.  For example, using this canned sequence:
   3882 
   3883      define frobnicate
   3884      @echo "frobnicating target $@"
   3885      frob-step-1 $< -o $@-step-1
   3886      frob-step-2 $@-step-1 -o $@
   3887      endef
   3888 
   3889 `make' will not echo the first line, the `echo' command.  But it _will_
   3890 echo the following two command lines.
   3891 
   3892    On the other hand, prefix characters on the command line that refers
   3893 to a canned sequence apply to every line in the sequence.  So the rule:
   3894 
   3895      frob.out: frob.in
   3896              @$(frobnicate)
   3897 
   3898 does not echo _any_ commands.  (*Note Command Echoing: Echoing, for a
   3899 full explanation of `@'.)
   3900 
   3901 
   3902 File: make.info,  Node: Empty Commands,  Prev: Sequences,  Up: Commands
   3903 
   3904 5.9 Using Empty Commands
   3905 ========================
   3906 
   3907 It is sometimes useful to define commands which do nothing.  This is
   3908 done simply by giving a command that consists of nothing but
   3909 whitespace.  For example:
   3910 
   3911      target: ;
   3912 
   3913 defines an empty command string for `target'.  You could also use a
   3914 line beginning with a tab character to define an empty command string,
   3915 but this would be confusing because such a line looks empty.
   3916 
   3917    You may be wondering why you would want to define a command string
   3918 that does nothing.  The only reason this is useful is to prevent a
   3919 target from getting implicit commands (from implicit rules or the
   3920 `.DEFAULT' special target; *note Implicit Rules:: and *note Defining
   3921 Last-Resort Default Rules: Last Resort.).
   3922 
   3923    You may be inclined to define empty command strings for targets that
   3924 are not actual files, but only exist so that their prerequisites can be
   3925 remade.  However, this is not the best way to do that, because the
   3926 prerequisites may not be remade properly if the target file actually
   3927 does exist.  *Note Phony Targets: Phony Targets, for a better way to do
   3928 this.
   3929 
   3930 
   3931 File: make.info,  Node: Using Variables,  Next: Conditionals,  Prev: Commands,  Up: Top
   3932 
   3933 6 How to Use Variables
   3934 **********************
   3935 
   3936 A "variable" is a name defined in a makefile to represent a string of
   3937 text, called the variable's "value".  These values are substituted by
   3938 explicit request into targets, prerequisites, commands, and other parts
   3939 of the makefile.  (In some other versions of `make', variables are
   3940 called "macros".)  
   3941 
   3942    Variables and functions in all parts of a makefile are expanded when
   3943 read, except for the shell commands in rules, the right-hand sides of
   3944 variable definitions using `=', and the bodies of variable definitions
   3945 using the `define' directive.
   3946 
   3947    Variables can represent lists of file names, options to pass to
   3948 compilers, programs to run, directories to look in for source files,
   3949 directories to write output in, or anything else you can imagine.
   3950 
   3951    A variable name may be any sequence of characters not containing `:',
   3952 `#', `=', or leading or trailing whitespace.  However, variable names
   3953 containing characters other than letters, numbers, and underscores
   3954 should be avoided, as they may be given special meanings in the future,
   3955 and with some shells they cannot be passed through the environment to a
   3956 sub-`make' (*note Communicating Variables to a Sub-`make':
   3957 Variables/Recursion.).
   3958 
   3959    Variable names are case-sensitive.  The names `foo', `FOO', and
   3960 `Foo' all refer to different variables.
   3961 
   3962    It is traditional to use upper case letters in variable names, but we
   3963 recommend using lower case letters for variable names that serve
   3964 internal purposes in the makefile, and reserving upper case for
   3965 parameters that control implicit rules or for parameters that the user
   3966 should override with command options (*note Overriding Variables:
   3967 Overriding.).
   3968 
   3969    A few variables have names that are a single punctuation character or
   3970 just a few characters.  These are the "automatic variables", and they
   3971 have particular specialized uses.  *Note Automatic Variables::.
   3972 
   3973 * Menu:
   3974 
   3975 * Reference::                   How to use the value of a variable.
   3976 * Flavors::                     Variables come in two flavors.
   3977 * Advanced::                    Advanced features for referencing a variable.
   3978 * Values::                      All the ways variables get their values.
   3979 * Setting::                     How to set a variable in the makefile.
   3980 * Appending::                   How to append more text to the old value
   3981                                   of a variable.
   3982 * Override Directive::          How to set a variable in the makefile even if
   3983                                   the user has set it with a command argument.
   3984 * Defining::                    An alternate way to set a variable
   3985                                   to a verbatim string.
   3986 * Environment::                 Variable values can come from the environment.
   3987 * Target-specific::             Variable values can be defined on a per-target
   3988                                   basis.
   3989 * Pattern-specific::            Target-specific variable values can be applied
   3990                                   to a group of targets that match a pattern.
   3991 
   3992 
   3993 File: make.info,  Node: Reference,  Next: Flavors,  Prev: Using Variables,  Up: Using Variables
   3994 
   3995 6.1 Basics of Variable References
   3996 =================================
   3997 
   3998 To substitute a variable's value, write a dollar sign followed by the
   3999 name of the variable in parentheses or braces: either `$(foo)' or
   4000 `${foo}' is a valid reference to the variable `foo'.  This special
   4001 significance of `$' is why you must write `$$' to have the effect of a
   4002 single dollar sign in a file name or command.
   4003 
   4004    Variable references can be used in any context: targets,
   4005 prerequisites, commands, most directives, and new variable values.
   4006 Here is an example of a common case, where a variable holds the names
   4007 of all the object files in a program:
   4008 
   4009      objects = program.o foo.o utils.o
   4010      program : $(objects)
   4011              cc -o program $(objects)
   4012 
   4013      $(objects) : defs.h
   4014 
   4015    Variable references work by strict textual substitution.  Thus, the
   4016 rule
   4017 
   4018      foo = c
   4019      prog.o : prog.$(foo)
   4020              $(foo)$(foo) -$(foo) prog.$(foo)
   4021 
   4022 could be used to compile a C program `prog.c'.  Since spaces before the
   4023 variable value are ignored in variable assignments, the value of `foo'
   4024 is precisely `c'.  (Don't actually write your makefiles this way!)
   4025 
   4026    A dollar sign followed by a character other than a dollar sign,
   4027 open-parenthesis or open-brace treats that single character as the
   4028 variable name.  Thus, you could reference the variable `x' with `$x'.
   4029 However, this practice is strongly discouraged, except in the case of
   4030 the automatic variables (*note Automatic Variables::).
   4031 
   4032 
   4033 File: make.info,  Node: Flavors,  Next: Advanced,  Prev: Reference,  Up: Using Variables
   4034 
   4035 6.2 The Two Flavors of Variables
   4036 ================================
   4037 
   4038 There are two ways that a variable in GNU `make' can have a value; we
   4039 call them the two "flavors" of variables.  The two flavors are
   4040 distinguished in how they are defined and in what they do when expanded.
   4041 
   4042    The first flavor of variable is a "recursively expanded" variable.
   4043 Variables of this sort are defined by lines using `=' (*note Setting
   4044 Variables: Setting.) or by the `define' directive (*note Defining
   4045 Variables Verbatim: Defining.).  The value you specify is installed
   4046 verbatim; if it contains references to other variables, these
   4047 references are expanded whenever this variable is substituted (in the
   4048 course of expanding some other string).  When this happens, it is
   4049 called "recursive expansion".
   4050 
   4051    For example,
   4052 
   4053      foo = $(bar)
   4054      bar = $(ugh)
   4055      ugh = Huh?
   4056 
   4057      all:;echo $(foo)
   4058 
   4059 will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to
   4060 `$(ugh)' which finally expands to `Huh?'.
   4061 
   4062    This flavor of variable is the only sort supported by other versions
   4063 of `make'.  It has its advantages and its disadvantages.  An advantage
   4064 (most would say) is that:
   4065 
   4066      CFLAGS = $(include_dirs) -O
   4067      include_dirs = -Ifoo -Ibar
   4068 
   4069 will do what was intended: when `CFLAGS' is expanded in a command, it
   4070 will expand to `-Ifoo -Ibar -O'.  A major disadvantage is that you
   4071 cannot append something on the end of a variable, as in
   4072 
   4073      CFLAGS = $(CFLAGS) -O
   4074 
   4075 because it will cause an infinite loop in the variable expansion.
   4076 (Actually `make' detects the infinite loop and reports an error.)  
   4077 
   4078    Another disadvantage is that any functions (*note Functions for
   4079 Transforming Text: Functions.)  referenced in the definition will be
   4080 executed every time the variable is expanded.  This makes `make' run
   4081 slower; worse, it causes the `wildcard' and `shell' functions to give
   4082 unpredictable results because you cannot easily control when they are
   4083 called, or even how many times.
   4084 
   4085    To avoid all the problems and inconveniences of recursively expanded
   4086 variables, there is another flavor: simply expanded variables.
   4087 
   4088    "Simply expanded variables" are defined by lines using `:=' (*note
   4089 Setting Variables: Setting.).  The value of a simply expanded variable
   4090 is scanned once and for all, expanding any references to other
   4091 variables and functions, when the variable is defined.  The actual
   4092 value of the simply expanded variable is the result of expanding the
   4093 text that you write.  It does not contain any references to other
   4094 variables; it contains their values _as of the time this variable was
   4095 defined_.  Therefore,
   4096 
   4097      x := foo
   4098      y := $(x) bar
   4099      x := later
   4100 
   4101 is equivalent to
   4102 
   4103      y := foo bar
   4104      x := later
   4105 
   4106    When a simply expanded variable is referenced, its value is
   4107 substituted verbatim.
   4108 
   4109    Here is a somewhat more complicated example, illustrating the use of
   4110 `:=' in conjunction with the `shell' function.  (*Note The `shell'
   4111 Function: Shell Function.)  This example also shows use of the variable
   4112 `MAKELEVEL', which is changed when it is passed down from level to
   4113 level.  (*Note Communicating Variables to a Sub-`make':
   4114 Variables/Recursion, for information about `MAKELEVEL'.)
   4115 
   4116      ifeq (0,${MAKELEVEL})
   4117      whoami    := $(shell whoami)
   4118      host-type := $(shell arch)
   4119      MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
   4120      endif
   4121 
   4122 An advantage of this use of `:=' is that a typical `descend into a
   4123 directory' command then looks like this:
   4124 
   4125      ${subdirs}:
   4126              ${MAKE} -C $@ all
   4127 
   4128    Simply expanded variables generally make complicated makefile
   4129 programming more predictable because they work like variables in most
   4130 programming languages.  They allow you to redefine a variable using its
   4131 own value (or its value processed in some way by one of the expansion
   4132 functions) and to use the expansion functions much more efficiently
   4133 (*note Functions for Transforming Text: Functions.).
   4134 
   4135    You can also use them to introduce controlled leading whitespace into
   4136 variable values.  Leading whitespace characters are discarded from your
   4137 input before substitution of variable references and function calls;
   4138 this means you can include leading spaces in a variable value by
   4139 protecting them with variable references, like this:
   4140 
   4141      nullstring :=
   4142      space := $(nullstring) # end of the line
   4143 
   4144 Here the value of the variable `space' is precisely one space.  The
   4145 comment `# end of the line' is included here just for clarity.  Since
   4146 trailing space characters are _not_ stripped from variable values, just
   4147 a space at the end of the line would have the same effect (but be
   4148 rather hard to read).  If you put whitespace at the end of a variable
   4149 value, it is a good idea to put a comment like that at the end of the
   4150 line to make your intent clear.  Conversely, if you do _not_ want any
   4151 whitespace characters at the end of your variable value, you must
   4152 remember not to put a random comment on the end of the line after some
   4153 whitespace, such as this:
   4154 
   4155      dir := /foo/bar    # directory to put the frobs in
   4156 
   4157 Here the value of the variable `dir' is `/foo/bar    ' (with four
   4158 trailing spaces), which was probably not the intention.  (Imagine
   4159 something like `$(dir)/file' with this definition!)
   4160 
   4161    There is another assignment operator for variables, `?='.  This is
   4162 called a conditional variable assignment operator, because it only has
   4163 an effect if the variable is not yet defined.  This statement:
   4164 
   4165      FOO ?= bar
   4166 
   4167 is exactly equivalent to this (*note The `origin' Function: Origin
   4168 Function.):
   4169 
   4170      ifeq ($(origin FOO), undefined)
   4171        FOO = bar
   4172      endif
   4173 
   4174    Note that a variable set to an empty value is still defined, so `?='
   4175 will not set that variable.
   4176 
   4177 
   4178 File: make.info,  Node: Advanced,  Next: Values,  Prev: Flavors,  Up: Using Variables
   4179 
   4180 6.3 Advanced Features for Reference to Variables
   4181 ================================================
   4182 
   4183 This section describes some advanced features you can use to reference
   4184 variables in more flexible ways.
   4185 
   4186 * Menu:
   4187 
   4188 * Substitution Refs::           Referencing a variable with
   4189                                   substitutions on the value.
   4190 * Computed Names::              Computing the name of the variable to refer to.
   4191 
   4192 
   4193 File: make.info,  Node: Substitution Refs,  Next: Computed Names,  Prev: Advanced,  Up: Advanced
   4194 
   4195 6.3.1 Substitution References
   4196 -----------------------------
   4197 
   4198 A "substitution reference" substitutes the value of a variable with
   4199 alterations that you specify.  It has the form `$(VAR:A=B)' (or
   4200 `${VAR:A=B}') and its meaning is to take the value of the variable VAR,
   4201 replace every A at the end of a word with B in that value, and
   4202 substitute the resulting string.
   4203 
   4204    When we say "at the end of a word", we mean that A must appear
   4205 either followed by whitespace or at the end of the value in order to be
   4206 replaced; other occurrences of A in the value are unaltered.  For
   4207 example:
   4208 
   4209      foo := a.o b.o c.o
   4210      bar := $(foo:.o=.c)
   4211 
   4212 sets `bar' to `a.c b.c c.c'.  *Note Setting Variables: Setting.
   4213 
   4214    A substitution reference is actually an abbreviation for use of the
   4215 `patsubst' expansion function (*note Functions for String Substitution
   4216 and Analysis: Text Functions.).  We provide substitution references as
   4217 well as `patsubst' for compatibility with other implementations of
   4218 `make'.
   4219 
   4220    Another type of substitution reference lets you use the full power of
   4221 the `patsubst' function.  It has the same form `$(VAR:A=B)' described
   4222 above, except that now A must contain a single `%' character.  This
   4223 case is equivalent to `$(patsubst A,B,$(VAR))'.  *Note Functions for
   4224 String Substitution and Analysis: Text Functions, for a description of
   4225 the `patsubst' function.
   4226 
   4227 For example:
   4228 
   4229      foo := a.o b.o c.o
   4230      bar := $(foo:%.o=%.c)
   4231 
   4232 sets `bar' to `a.c b.c c.c'.
   4233 
   4234 
   4235 File: make.info,  Node: Computed Names,  Prev: Substitution Refs,  Up: Advanced
   4236 
   4237 6.3.2 Computed Variable Names
   4238 -----------------------------
   4239 
   4240 Computed variable names are a complicated concept needed only for
   4241 sophisticated makefile programming.  For most purposes you need not
   4242 consider them, except to know that making a variable with a dollar sign
   4243 in its name might have strange results.  However, if you are the type
   4244 that wants to understand everything, or you are actually interested in
   4245 what they do, read on.
   4246 
   4247    Variables may be referenced inside the name of a variable.  This is
   4248 called a "computed variable name" or a "nested variable reference".
   4249 For example,
   4250 
   4251      x = y
   4252      y = z
   4253      a := $($(x))
   4254 
   4255 defines `a' as `z': the `$(x)' inside `$($(x))' expands to `y', so
   4256 `$($(x))' expands to `$(y)' which in turn expands to `z'.  Here the
   4257 name of the variable to reference is not stated explicitly; it is
   4258 computed by expansion of `$(x)'.  The reference `$(x)' here is nested
   4259 within the outer variable reference.
   4260 
   4261    The previous example shows two levels of nesting, but any number of
   4262 levels is possible.  For example, here are three levels:
   4263 
   4264      x = y
   4265      y = z
   4266      z = u
   4267      a := $($($(x)))
   4268 
   4269 Here the innermost `$(x)' expands to `y', so `$($(x))' expands to
   4270 `$(y)' which in turn expands to `z'; now we have `$(z)', which becomes
   4271 `u'.
   4272 
   4273    References to recursively-expanded variables within a variable name
   4274 are reexpanded in the usual fashion.  For example:
   4275 
   4276      x = $(y)
   4277      y = z
   4278      z = Hello
   4279      a := $($(x))
   4280 
   4281 defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes
   4282 `$(z)' which becomes `Hello'.
   4283 
   4284    Nested variable references can also contain modified references and
   4285 function invocations (*note Functions for Transforming Text:
   4286 Functions.), just like any other reference.  For example, using the
   4287 `subst' function (*note Functions for String Substitution and Analysis:
   4288 Text Functions.):
   4289 
   4290      x = variable1
   4291      variable2 := Hello
   4292      y = $(subst 1,2,$(x))
   4293      z = y
   4294      a := $($($(z)))
   4295 
   4296 eventually defines `a' as `Hello'.  It is doubtful that anyone would
   4297 ever want to write a nested reference as convoluted as this one, but it
   4298 works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst
   4299 1,2,$(x)))'.  This gets the value `variable1' from `x' and changes it
   4300 by substitution to `variable2', so that the entire string becomes
   4301 `$(variable2)', a simple variable reference whose value is `Hello'.
   4302 
   4303    A computed variable name need not consist entirely of a single
   4304 variable reference.  It can contain several variable references, as
   4305 well as some invariant text.  For example,
   4306 
   4307      a_dirs := dira dirb
   4308      1_dirs := dir1 dir2
   4309 
   4310      a_files := filea fileb
   4311      1_files := file1 file2
   4312 
   4313      ifeq "$(use_a)" "yes"
   4314      a1 := a
   4315      else
   4316      a1 := 1
   4317      endif
   4318 
   4319      ifeq "$(use_dirs)" "yes"
   4320      df := dirs
   4321      else
   4322      df := files
   4323      endif
   4324 
   4325      dirs := $($(a1)_$(df))
   4326 
   4327 will give `dirs' the same value as `a_dirs', `1_dirs', `a_files' or
   4328 `1_files' depending on the settings of `use_a' and `use_dirs'.
   4329 
   4330    Computed variable names can also be used in substitution references:
   4331 
   4332      a_objects := a.o b.o c.o
   4333      1_objects := 1.o 2.o 3.o
   4334 
   4335      sources := $($(a1)_objects:.o=.c)
   4336 
   4337 defines `sources' as either `a.c b.c c.c' or `1.c 2.c 3.c', depending
   4338 on the value of `a1'.
   4339 
   4340    The only restriction on this sort of use of nested variable
   4341 references is that they cannot specify part of the name of a function
   4342 to be called.  This is because the test for a recognized function name
   4343 is done before the expansion of nested references.  For example,
   4344 
   4345      ifdef do_sort
   4346      func := sort
   4347      else
   4348      func := strip
   4349      endif
   4350 
   4351      bar := a d b g q c
   4352 
   4353      foo := $($(func) $(bar))
   4354 
   4355 attempts to give `foo' the value of the variable `sort a d b g q c' or
   4356 `strip a d b g q c', rather than giving `a d b g q c' as the argument
   4357 to either the `sort' or the `strip' function.  This restriction could
   4358 be removed in the future if that change is shown to be a good idea.
   4359 
   4360    You can also use computed variable names in the left-hand side of a
   4361 variable assignment, or in a `define' directive, as in:
   4362 
   4363      dir = foo
   4364      $(dir)_sources := $(wildcard $(dir)/*.c)
   4365      define $(dir)_print
   4366      lpr $($(dir)_sources)
   4367      endef
   4368 
   4369 This example defines the variables `dir', `foo_sources', and
   4370 `foo_print'.
   4371 
   4372    Note that "nested variable references" are quite different from
   4373 "recursively expanded variables" (*note The Two Flavors of Variables:
   4374 Flavors.), though both are used together in complex ways when doing
   4375 makefile programming.
   4376 
   4377 
   4378 File: make.info,  Node: Values,  Next: Setting,  Prev: Advanced,  Up: Using Variables
   4379 
   4380 6.4 How Variables Get Their Values
   4381 ==================================
   4382 
   4383 Variables can get values in several different ways:
   4384 
   4385    * You can specify an overriding value when you run `make'.  *Note
   4386      Overriding Variables: Overriding.
   4387 
   4388    * You can specify a value in the makefile, either with an assignment
   4389      (*note Setting Variables: Setting.) or with a verbatim definition
   4390      (*note Defining Variables Verbatim: Defining.).
   4391 
   4392    * Variables in the environment become `make' variables.  *Note
   4393      Variables from the Environment: Environment.
   4394 
   4395    * Several "automatic" variables are given new values for each rule.
   4396      Each of these has a single conventional use.  *Note Automatic
   4397      Variables::.
   4398 
   4399    * Several variables have constant initial values.  *Note Variables
   4400      Used by Implicit Rules: Implicit Variables.
   4401 
   4402 
   4403 File: make.info,  Node: Setting,  Next: Appending,  Prev: Values,  Up: Using Variables
   4404 
   4405 6.5 Setting Variables
   4406 =====================
   4407 
   4408 To set a variable from the makefile, write a line starting with the
   4409 variable name followed by `=' or `:='.  Whatever follows the `=' or
   4410 `:=' on the line becomes the value.  For example,
   4411 
   4412      objects = main.o foo.o bar.o utils.o
   4413 
   4414 defines a variable named `objects'.  Whitespace around the variable
   4415 name and immediately after the `=' is ignored.
   4416 
   4417    Variables defined with `=' are "recursively expanded" variables.
   4418 Variables defined with `:=' are "simply expanded" variables; these
   4419 definitions can contain variable references which will be expanded
   4420 before the definition is made.  *Note The Two Flavors of Variables:
   4421 Flavors.
   4422 
   4423    The variable name may contain function and variable references, which
   4424 are expanded when the line is read to find the actual variable name to
   4425 use.
   4426 
   4427    There is no limit on the length of the value of a variable except the
   4428 amount of swapping space on the computer.  When a variable definition is
   4429 long, it is a good idea to break it into several lines by inserting
   4430 backslash-newline at convenient places in the definition.  This will not
   4431 affect the functioning of `make', but it will make the makefile easier
   4432 to read.
   4433 
   4434    Most variable names are considered to have the empty string as a
   4435 value if you have never set them.  Several variables have built-in
   4436 initial values that are not empty, but you can set them in the usual
   4437 ways (*note Variables Used by Implicit Rules: Implicit Variables.).
   4438 Several special variables are set automatically to a new value for each
   4439 rule; these are called the "automatic" variables (*note Automatic
   4440 Variables::).
   4441 
   4442    If you'd like a variable to be set to a value only if it's not
   4443 already set, then you can use the shorthand operator `?=' instead of
   4444 `='.  These two settings of the variable `FOO' are identical (*note The
   4445 `origin' Function: Origin Function.):
   4446 
   4447      FOO ?= bar
   4448 
   4449 and
   4450 
   4451      ifeq ($(origin FOO), undefined)
   4452      FOO = bar
   4453      endif
   4454 
   4455 
   4456 File: make.info,  Node: Appending,  Next: Override Directive,  Prev: Setting,  Up: Using Variables
   4457 
   4458 6.6 Appending More Text to Variables
   4459 ====================================
   4460 
   4461 Often it is useful to add more text to the value of a variable already
   4462 defined.  You do this with a line containing `+=', like this:
   4463 
   4464      objects += another.o
   4465 
   4466 This takes the value of the variable `objects', and adds the text
   4467 `another.o' to it (preceded by a single space).  Thus:
   4468 
   4469      objects = main.o foo.o bar.o utils.o
   4470      objects += another.o
   4471 
   4472 sets `objects' to `main.o foo.o bar.o utils.o another.o'.
   4473 
   4474    Using `+=' is similar to:
   4475 
   4476      objects = main.o foo.o bar.o utils.o
   4477      objects := $(objects) another.o
   4478 
   4479 but differs in ways that become important when you use more complex
   4480 values.
   4481 
   4482    When the variable in question has not been defined before, `+=' acts
   4483 just like normal `=': it defines a recursively-expanded variable.
   4484 However, when there _is_ a previous definition, exactly what `+=' does
   4485 depends on what flavor of variable you defined originally.  *Note The
   4486 Two Flavors of Variables: Flavors, for an explanation of the two
   4487 flavors of variables.
   4488 
   4489    When you add to a variable's value with `+=', `make' acts
   4490 essentially as if you had included the extra text in the initial
   4491 definition of the variable.  If you defined it first with `:=', making
   4492 it a simply-expanded variable, `+=' adds to that simply-expanded
   4493 definition, and expands the new text before appending it to the old
   4494 value just as `:=' does (see *note Setting Variables: Setting, for a
   4495 full explanation of `:=').  In fact,
   4496 
   4497      variable := value
   4498      variable += more
   4499 
   4500 is exactly equivalent to:
   4501 
   4502 
   4503      variable := value
   4504      variable := $(variable) more
   4505 
   4506    On the other hand, when you use `+=' with a variable that you defined
   4507 first to be recursively-expanded using plain `=', `make' does something
   4508 a bit different.  Recall that when you define a recursively-expanded
   4509 variable, `make' does not expand the value you set for variable and
   4510 function references immediately.  Instead it stores the text verbatim,
   4511 and saves these variable and function references to be expanded later,
   4512 when you refer to the new variable (*note The Two Flavors of Variables:
   4513 Flavors.).  When you use `+=' on a recursively-expanded variable, it is
   4514 this unexpanded text to which `make' appends the new text you specify.
   4515 
   4516      variable = value
   4517      variable += more
   4518 
   4519 is roughly equivalent to:
   4520 
   4521      temp = value
   4522      variable = $(temp) more
   4523 
   4524 except that of course it never defines a variable called `temp'.  The
   4525 importance of this comes when the variable's old value contains
   4526 variable references.  Take this common example:
   4527 
   4528      CFLAGS = $(includes) -O
   4529      ...
   4530      CFLAGS += -pg # enable profiling
   4531 
   4532 The first line defines the `CFLAGS' variable with a reference to another
   4533 variable, `includes'.  (`CFLAGS' is used by the rules for C
   4534 compilation; *note Catalogue of Implicit Rules: Catalogue of Rules.)
   4535 Using `=' for the definition makes `CFLAGS' a recursively-expanded
   4536 variable, meaning `$(includes) -O' is _not_ expanded when `make'
   4537 processes the definition of `CFLAGS'.  Thus, `includes' need not be
   4538 defined yet for its value to take effect.  It only has to be defined
   4539 before any reference to `CFLAGS'.  If we tried to append to the value
   4540 of `CFLAGS' without using `+=', we might do it like this:
   4541 
   4542      CFLAGS := $(CFLAGS) -pg # enable profiling
   4543 
   4544 This is pretty close, but not quite what we want.  Using `:=' redefines
   4545 `CFLAGS' as a simply-expanded variable; this means `make' expands the
   4546 text `$(CFLAGS) -pg' before setting the variable.  If `includes' is not
   4547 yet defined, we get ` -O -pg', and a later definition of `includes'
   4548 will have no effect.  Conversely, by using `+=' we set `CFLAGS' to the
   4549 _unexpanded_ value `$(includes) -O -pg'.  Thus we preserve the
   4550 reference to `includes', so if that variable gets defined at any later
   4551 point, a reference like `$(CFLAGS)' still uses its value.
   4552 
   4553 
   4554 File: make.info,  Node: Override Directive,  Next: Defining,  Prev: Appending,  Up: Using Variables
   4555 
   4556 6.7 The `override' Directive
   4557 ============================
   4558 
   4559 If a variable has been set with a command argument (*note Overriding
   4560 Variables: Overriding.), then ordinary assignments in the makefile are
   4561 ignored.  If you want to set the variable in the makefile even though
   4562 it was set with a command argument, you can use an `override'
   4563 directive, which is a line that looks like this:
   4564 
   4565      override VARIABLE = VALUE
   4566 
   4567 or
   4568 
   4569      override VARIABLE := VALUE
   4570 
   4571    To append more text to a variable defined on the command line, use:
   4572 
   4573      override VARIABLE += MORE TEXT
   4574 
   4575 *Note Appending More Text to Variables: Appending.
   4576 
   4577    The `override' directive was not invented for escalation in the war
   4578 between makefiles and command arguments.  It was invented so you can
   4579 alter and add to values that the user specifies with command arguments.
   4580 
   4581    For example, suppose you always want the `-g' switch when you run the
   4582 C compiler, but you would like to allow the user to specify the other
   4583 switches with a command argument just as usual.  You could use this
   4584 `override' directive:
   4585 
   4586      override CFLAGS += -g
   4587 
   4588    You can also use `override' directives with `define' directives.
   4589 This is done as you might expect:
   4590 
   4591      override define foo
   4592      bar
   4593      endef
   4594 
   4595 *Note Defining Variables Verbatim: Defining.
   4596 
   4597 
   4598 File: make.info,  Node: Defining,  Next: Environment,  Prev: Override Directive,  Up: Using Variables
   4599 
   4600 6.8 Defining Variables Verbatim
   4601 ===============================
   4602 
   4603 Another way to set the value of a variable is to use the `define'
   4604 directive.  This directive has an unusual syntax which allows newline
   4605 characters to be included in the value, which is convenient for defining
   4606 both canned sequences of commands (*note Defining Canned Command
   4607 Sequences: Sequences.), and also sections of makefile syntax to use
   4608 with `eval' (*note Eval Function::).
   4609 
   4610    The `define' directive is followed on the same line by the name of
   4611 the variable and nothing more.  The value to give the variable appears
   4612 on the following lines.  The end of the value is marked by a line
   4613 containing just the word `endef'.  Aside from this difference in
   4614 syntax, `define' works just like `=': it creates a recursively-expanded
   4615 variable (*note The Two Flavors of Variables: Flavors.).  The variable
   4616 name may contain function and variable references, which are expanded
   4617 when the directive is read to find the actual variable name to use.
   4618 
   4619    You may nest `define' directives: `make' will keep track of nested
   4620 directives and report an error if they are not all properly closed with
   4621 `endef'.  Note that lines beginning with tab characters are considered
   4622 part of a command script, so any `define' or `endef' strings appearing
   4623 on such a line will not be considered `make' operators.
   4624 
   4625      define two-lines
   4626      echo foo
   4627      echo $(bar)
   4628      endef
   4629 
   4630    The value in an ordinary assignment cannot contain a newline; but the
   4631 newlines that separate the lines of the value in a `define' become part
   4632 of the variable's value (except for the final newline which precedes
   4633 the `endef' and is not considered part of the value).
   4634 
   4635    When used in a command script, the previous example is functionally
   4636 equivalent to this:
   4637 
   4638      two-lines = echo foo; echo $(bar)
   4639 
   4640 since two commands separated by semicolon behave much like two separate
   4641 shell commands.  However, note that using two separate lines means
   4642 `make' will invoke the shell twice, running an independent subshell for
   4643 each line.  *Note Command Execution: Execution.
   4644 
   4645    If you want variable definitions made with `define' to take
   4646 precedence over command-line variable definitions, you can use the
   4647 `override' directive together with `define':
   4648 
   4649      override define two-lines
   4650      foo
   4651      $(bar)
   4652      endef
   4653 
   4654 *Note The `override' Directive: Override Directive.
   4655 
   4656 
   4657 File: make.info,  Node: Environment,  Next: Target-specific,  Prev: Defining,  Up: Using Variables
   4658 
   4659 6.9 Variables from the Environment
   4660 ==================================
   4661 
   4662 Variables in `make' can come from the environment in which `make' is
   4663 run.  Every environment variable that `make' sees when it starts up is
   4664 transformed into a `make' variable with the same name and value.
   4665 However, an explicit assignment in the makefile, or with a command
   4666 argument, overrides the environment.  (If the `-e' flag is specified,
   4667 then values from the environment override assignments in the makefile.
   4668 *Note Summary of Options: Options Summary.  But this is not recommended
   4669 practice.)
   4670 
   4671    Thus, by setting the variable `CFLAGS' in your environment, you can
   4672 cause all C compilations in most makefiles to use the compiler switches
   4673 you prefer.  This is safe for variables with standard or conventional
   4674 meanings because you know that no makefile will use them for other
   4675 things.  (Note this is not totally reliable; some makefiles set
   4676 `CFLAGS' explicitly and therefore are not affected by the value in the
   4677 environment.)
   4678 
   4679    When `make' runs a command script, variables defined in the makefile
   4680 are placed into the environment of that command.  This allows you to
   4681 pass values to sub-`make' invocations (*note Recursive Use of `make':
   4682 Recursion.).  By default, only variables that came from the environment
   4683 or the command line are passed to recursive invocations.  You can use
   4684 the `export' directive to pass other variables.  *Note Communicating
   4685 Variables to a Sub-`make': Variables/Recursion, for full details.
   4686 
   4687    Other use of variables from the environment is not recommended.  It
   4688 is not wise for makefiles to depend for their functioning on
   4689 environment variables set up outside their control, since this would
   4690 cause different users to get different results from the same makefile.
   4691 This is against the whole purpose of most makefiles.
   4692 
   4693    Such problems would be especially likely with the variable `SHELL',
   4694 which is normally present in the environment to specify the user's
   4695 choice of interactive shell.  It would be very undesirable for this
   4696 choice to affect `make'; so, `make' handles the `SHELL' environment
   4697 variable in a special way; see *note Choosing the Shell::.
   4698 
   4699 
   4700 File: make.info,  Node: Target-specific,  Next: Pattern-specific,  Prev: Environment,  Up: Using Variables
   4701 
   4702 6.10 Target-specific Variable Values
   4703 ====================================
   4704 
   4705 Variable values in `make' are usually global; that is, they are the
   4706 same regardless of where they are evaluated (unless they're reset, of
   4707 course).  One exception to that is automatic variables (*note Automatic
   4708 Variables::).
   4709 
   4710    The other exception is "target-specific variable values".  This
   4711 feature allows you to define different values for the same variable,
   4712 based on the target that `make' is currently building.  As with
   4713 automatic variables, these values are only available within the context
   4714 of a target's command script (and in other target-specific assignments).
   4715 
   4716    Set a target-specific variable value like this:
   4717 
   4718      TARGET ... : VARIABLE-ASSIGNMENT
   4719 
   4720 or like this:
   4721 
   4722      TARGET ... : override VARIABLE-ASSIGNMENT
   4723 
   4724 or like this:
   4725 
   4726      TARGET ... : export VARIABLE-ASSIGNMENT
   4727 
   4728    Multiple TARGET values create a target-specific variable value for
   4729 each member of the target list individually.
   4730 
   4731    The VARIABLE-ASSIGNMENT can be any valid form of assignment;
   4732 recursive (`='), static (`:='), appending (`+='), or conditional
   4733 (`?=').  All variables that appear within the VARIABLE-ASSIGNMENT are
   4734 evaluated within the context of the target: thus, any
   4735 previously-defined target-specific variable values will be in effect.
   4736 Note that this variable is actually distinct from any "global" value:
   4737 the two variables do not have to have the same flavor (recursive vs.
   4738 static).
   4739 
   4740    Target-specific variables have the same priority as any other
   4741 makefile variable.  Variables provided on the command-line (and in the
   4742 environment if the `-e' option is in force) will take precedence.
   4743 Specifying the `override' directive will allow the target-specific
   4744 variable value to be preferred.
   4745 
   4746    There is one more special feature of target-specific variables: when
   4747 you define a target-specific variable that variable value is also in
   4748 effect for all prerequisites of this target, and all their
   4749 prerequisites, etc. (unless those prerequisites override that variable
   4750 with their own target-specific variable value).  So, for example, a
   4751 statement like this:
   4752 
   4753      prog : CFLAGS = -g
   4754      prog : prog.o foo.o bar.o
   4755 
   4756 will set `CFLAGS' to `-g' in the command script for `prog', but it will
   4757 also set `CFLAGS' to `-g' in the command scripts that create `prog.o',
   4758 `foo.o', and `bar.o', and any command scripts which create their
   4759 prerequisites.
   4760 
   4761    Be aware that a given prerequisite will only be built once per
   4762 invocation of make, at most.  If the same file is a prerequisite of
   4763 multiple targets, and each of those targets has a different value for
   4764 the same target-specific variable, then the first target to be built
   4765 will cause that prerequisite to be built and the prerequisite will
   4766 inherit the target-specific value from the first target.  It will
   4767 ignore the target-specific values from any other targets.
   4768 
   4769 
   4770 File: make.info,  Node: Pattern-specific,  Prev: Target-specific,  Up: Using Variables
   4771 
   4772 6.11 Pattern-specific Variable Values
   4773 =====================================
   4774 
   4775 In addition to target-specific variable values (*note Target-specific
   4776 Variable Values: Target-specific.), GNU `make' supports
   4777 pattern-specific variable values.  In this form, the variable is
   4778 defined for any target that matches the pattern specified.  If a target
   4779 matches more than one pattern, all the matching pattern-specific
   4780 variables are interpreted in the order in which they were defined in
   4781 the makefile, and collected together into one set.  Variables defined
   4782 in this way are searched after any target-specific variables defined
   4783 explicitly for that target, and before target-specific variables
   4784 defined for the parent target.
   4785 
   4786    Set a pattern-specific variable value like this:
   4787 
   4788      PATTERN ... : VARIABLE-ASSIGNMENT
   4789 
   4790 or like this:
   4791 
   4792      PATTERN ... : override VARIABLE-ASSIGNMENT
   4793 
   4794 where PATTERN is a %-pattern.  As with target-specific variable values,
   4795 multiple PATTERN values create a pattern-specific variable value for
   4796 each pattern individually.  The VARIABLE-ASSIGNMENT can be any valid
   4797 form of assignment.  Any command-line variable setting will take
   4798 precedence, unless `override' is specified.
   4799 
   4800    For example:
   4801 
   4802      %.o : CFLAGS = -O
   4803 
   4804 will assign `CFLAGS' the value of `-O' for all targets matching the
   4805 pattern `%.o'.
   4806 
   4807 
   4808 File: make.info,  Node: Conditionals,  Next: Functions,  Prev: Using Variables,  Up: Top
   4809 
   4810 7 Conditional Parts of Makefiles
   4811 ********************************
   4812 
   4813 A "conditional" causes part of a makefile to be obeyed or ignored
   4814 depending on the values of variables.  Conditionals can compare the
   4815 value of one variable to another, or the value of a variable to a
   4816 constant string.  Conditionals control what `make' actually "sees" in
   4817 the makefile, so they _cannot_ be used to control shell commands at the
   4818 time of execution.
   4819 
   4820 * Menu:
   4821 
   4822 * Conditional Example::         Example of a conditional
   4823 * Conditional Syntax::          The syntax of conditionals.
   4824 * Testing Flags::               Conditionals that test flags.
   4825 
   4826 
   4827 File: make.info,  Node: Conditional Example,  Next: Conditional Syntax,  Prev: Conditionals,  Up: Conditionals
   4828 
   4829 7.1 Example of a Conditional
   4830 ============================
   4831 
   4832 The following example of a conditional tells `make' to use one set of
   4833 libraries if the `CC' variable is `gcc', and a different set of
   4834 libraries otherwise.  It works by controlling which of two command
   4835 lines will be used as the command for a rule.  The result is that
   4836 `CC=gcc' as an argument to `make' changes not only which compiler is
   4837 used but also which libraries are linked.
   4838 
   4839      libs_for_gcc = -lgnu
   4840      normal_libs =
   4841 
   4842      foo: $(objects)
   4843      ifeq ($(CC),gcc)
   4844              $(CC) -o foo $(objects) $(libs_for_gcc)
   4845      else
   4846              $(CC) -o foo $(objects) $(normal_libs)
   4847      endif
   4848 
   4849    This conditional uses three directives: one `ifeq', one `else' and
   4850 one `endif'.
   4851 
   4852    The `ifeq' directive begins the conditional, and specifies the
   4853 condition.  It contains two arguments, separated by a comma and
   4854 surrounded by parentheses.  Variable substitution is performed on both
   4855 arguments and then they are compared.  The lines of the makefile
   4856 following the `ifeq' are obeyed if the two arguments match; otherwise
   4857 they are ignored.
   4858 
   4859    The `else' directive causes the following lines to be obeyed if the
   4860 previous conditional failed.  In the example above, this means that the
   4861 second alternative linking command is used whenever the first
   4862 alternative is not used.  It is optional to have an `else' in a
   4863 conditional.
   4864 
   4865    The `endif' directive ends the conditional.  Every conditional must
   4866 end with an `endif'.  Unconditional makefile text follows.
   4867 
   4868    As this example illustrates, conditionals work at the textual level:
   4869 the lines of the conditional are treated as part of the makefile, or
   4870 ignored, according to the condition.  This is why the larger syntactic
   4871 units of the makefile, such as rules, may cross the beginning or the
   4872 end of the conditional.
   4873 
   4874    When the variable `CC' has the value `gcc', the above example has
   4875 this effect:
   4876 
   4877      foo: $(objects)
   4878              $(CC) -o foo $(objects) $(libs_for_gcc)
   4879 
   4880 When the variable `CC' has any other value, the effect is this:
   4881 
   4882      foo: $(objects)
   4883              $(CC) -o foo $(objects) $(normal_libs)
   4884 
   4885    Equivalent results can be obtained in another way by
   4886 conditionalizing a variable assignment and then using the variable
   4887 unconditionally:
   4888 
   4889      libs_for_gcc = -lgnu
   4890      normal_libs =
   4891 
   4892      ifeq ($(CC),gcc)
   4893        libs=$(libs_for_gcc)
   4894      else
   4895        libs=$(normal_libs)
   4896      endif
   4897 
   4898      foo: $(objects)
   4899              $(CC) -o foo $(objects) $(libs)
   4900 
   4901 
   4902 File: make.info,  Node: Conditional Syntax,  Next: Testing Flags,  Prev: Conditional Example,  Up: Conditionals
   4903 
   4904 7.2 Syntax of Conditionals
   4905 ==========================
   4906 
   4907 The syntax of a simple conditional with no `else' is as follows:
   4908 
   4909      CONDITIONAL-DIRECTIVE
   4910      TEXT-IF-TRUE
   4911      endif
   4912 
   4913 The TEXT-IF-TRUE may be any lines of text, to be considered as part of
   4914 the makefile if the condition is true.  If the condition is false, no
   4915 text is used instead.
   4916 
   4917    The syntax of a complex conditional is as follows:
   4918 
   4919      CONDITIONAL-DIRECTIVE
   4920      TEXT-IF-TRUE
   4921      else
   4922      TEXT-IF-FALSE
   4923      endif
   4924 
   4925    or:
   4926 
   4927      CONDITIONAL-DIRECTIVE
   4928      TEXT-IF-ONE-IS-TRUE
   4929      else CONDITIONAL-DIRECTIVE
   4930      TEXT-IF-TRUE
   4931      else
   4932      TEXT-IF-FALSE
   4933      endif
   4934 
   4935 There can be as many "`else' CONDITIONAL-DIRECTIVE" clauses as
   4936 necessary.  Once a given condition is true, TEXT-IF-TRUE is used and no
   4937 other clause is used; if no condition is true then TEXT-IF-FALSE is
   4938 used.  The TEXT-IF-TRUE and TEXT-IF-FALSE can be any number of lines of
   4939 text.
   4940 
   4941    The syntax of the CONDITIONAL-DIRECTIVE is the same whether the
   4942 conditional is simple or complex; after an `else' or not.  There are
   4943 four different directives that test different conditions.  Here is a
   4944 table of them:
   4945 
   4946 `ifeq (ARG1, ARG2)'
   4947 `ifeq 'ARG1' 'ARG2''
   4948 `ifeq "ARG1" "ARG2"'
   4949 `ifeq "ARG1" 'ARG2''
   4950 `ifeq 'ARG1' "ARG2"'
   4951      Expand all variable references in ARG1 and ARG2 and compare them.
   4952      If they are identical, the TEXT-IF-TRUE is effective; otherwise,
   4953      the TEXT-IF-FALSE, if any, is effective.
   4954 
   4955      Often you want to test if a variable has a non-empty value.  When
   4956      the value results from complex expansions of variables and
   4957      functions, expansions you would consider empty may actually
   4958      contain whitespace characters and thus are not seen as empty.
   4959      However, you can use the `strip' function (*note Text Functions::)
   4960      to avoid interpreting whitespace as a non-empty value.  For
   4961      example:
   4962 
   4963           ifeq ($(strip $(foo)),)
   4964           TEXT-IF-EMPTY
   4965           endif
   4966 
   4967      will evaluate TEXT-IF-EMPTY even if the expansion of `$(foo)'
   4968      contains whitespace characters.
   4969 
   4970 `ifneq (ARG1, ARG2)'
   4971 `ifneq 'ARG1' 'ARG2''
   4972 `ifneq "ARG1" "ARG2"'
   4973 `ifneq "ARG1" 'ARG2''
   4974 `ifneq 'ARG1' "ARG2"'
   4975      Expand all variable references in ARG1 and ARG2 and compare them.
   4976      If they are different, the TEXT-IF-TRUE is effective; otherwise,
   4977      the TEXT-IF-FALSE, if any, is effective.
   4978 
   4979 `ifdef VARIABLE-NAME'
   4980      The `ifdef' form takes the _name_ of a variable as its argument,
   4981      not a reference to a variable.  The value of that variable has a
   4982      non-empty value, the TEXT-IF-TRUE is effective; otherwise, the
   4983      TEXT-IF-FALSE, if any, is effective.  Variables that have never
   4984      been defined have an empty value.  The text VARIABLE-NAME is
   4985      expanded, so it could be a variable or function that expands to
   4986      the name of a variable.  For example:
   4987 
   4988           bar = true
   4989           foo = bar
   4990           ifdef $(foo)
   4991           frobozz = yes
   4992           endif
   4993 
   4994      The variable reference `$(foo)' is expanded, yielding `bar', which
   4995      is considered to be the name of a variable.  The variable `bar' is
   4996      not expanded, but its value is examined to determine if it is
   4997      non-empty.
   4998 
   4999      Note that `ifdef' only tests whether a variable has a value.  It
   5000      does not expand the variable to see if that value is nonempty.
   5001      Consequently, tests using `ifdef' return true for all definitions
   5002      except those like `foo ='.  To test for an empty value, use
   5003      `ifeq ($(foo),)'.  For example,
   5004 
   5005           bar =
   5006           foo = $(bar)
   5007           ifdef foo
   5008           frobozz = yes
   5009           else
   5010           frobozz = no
   5011           endif
   5012 
   5013      sets `frobozz' to `yes', while:
   5014 
   5015           foo =
   5016           ifdef foo
   5017           frobozz = yes
   5018           else
   5019           frobozz = no
   5020           endif
   5021 
   5022      sets `frobozz' to `no'.
   5023 
   5024 `ifndef VARIABLE-NAME'
   5025      If the variable VARIABLE-NAME has an empty value, the TEXT-IF-TRUE
   5026      is effective; otherwise, the TEXT-IF-FALSE, if any, is effective.
   5027      The rules for expansion and testing of VARIABLE-NAME are identical
   5028      to the `ifdef' directive.
   5029 
   5030    Extra spaces are allowed and ignored at the beginning of the
   5031 conditional directive line, but a tab is not allowed.  (If the line
   5032 begins with a tab, it will be considered a command for a rule.)  Aside
   5033 from this, extra spaces or tabs may be inserted with no effect anywhere
   5034 except within the directive name or within an argument.  A comment
   5035 starting with `#' may appear at the end of the line.
   5036 
   5037    The other two directives that play a part in a conditional are `else'
   5038 and `endif'.  Each of these directives is written as one word, with no
   5039 arguments.  Extra spaces are allowed and ignored at the beginning of the
   5040 line, and spaces or tabs at the end.  A comment starting with `#' may
   5041 appear at the end of the line.
   5042 
   5043    Conditionals affect which lines of the makefile `make' uses.  If the
   5044 condition is true, `make' reads the lines of the TEXT-IF-TRUE as part
   5045 of the makefile; if the condition is false, `make' ignores those lines
   5046 completely.  It follows that syntactic units of the makefile, such as
   5047 rules, may safely be split across the beginning or the end of the
   5048 conditional.
   5049 
   5050    `make' evaluates conditionals when it reads a makefile.
   5051 Consequently, you cannot use automatic variables in the tests of
   5052 conditionals because they are not defined until commands are run (*note
   5053 Automatic Variables::).
   5054 
   5055    To prevent intolerable confusion, it is not permitted to start a
   5056 conditional in one makefile and end it in another.  However, you may
   5057 write an `include' directive within a conditional, provided you do not
   5058 attempt to terminate the conditional inside the included file.
   5059 
   5060 
   5061 File: make.info,  Node: Testing Flags,  Prev: Conditional Syntax,  Up: Conditionals
   5062 
   5063 7.3 Conditionals that Test Flags
   5064 ================================
   5065 
   5066 You can write a conditional that tests `make' command flags such as
   5067 `-t' by using the variable `MAKEFLAGS' together with the `findstring'
   5068 function (*note Functions for String Substitution and Analysis: Text
   5069 Functions.).  This is useful when `touch' is not enough to make a file
   5070 appear up to date.
   5071 
   5072    The `findstring' function determines whether one string appears as a
   5073 substring of another.  If you want to test for the `-t' flag, use `t'
   5074 as the first string and the value of `MAKEFLAGS' as the other.
   5075 
   5076    For example, here is how to arrange to use `ranlib -t' to finish
   5077 marking an archive file up to date:
   5078 
   5079      archive.a: ...
   5080      ifneq (,$(findstring t,$(MAKEFLAGS)))
   5081              +touch archive.a
   5082              +ranlib -t archive.a
   5083      else
   5084              ranlib archive.a
   5085      endif
   5086 
   5087 The `+' prefix marks those command lines as "recursive" so that they
   5088 will be executed despite use of the `-t' flag.  *Note Recursive Use of
   5089 `make': Recursion.
   5090 
   5091 
   5092 File: make.info,  Node: Functions,  Next: Running,  Prev: Conditionals,  Up: Top
   5093 
   5094 8 Functions for Transforming Text
   5095 *********************************
   5096 
   5097 "Functions" allow you to do text processing in the makefile to compute
   5098 the files to operate on or the commands to use.  You use a function in a
   5099 "function call", where you give the name of the function and some text
   5100 (the "arguments") for the function to operate on.  The result of the
   5101 function's processing is substituted into the makefile at the point of
   5102 the call, just as a variable might be substituted.
   5103 
   5104 * Menu:
   5105 
   5106 * Syntax of Functions::         How to write a function call.
   5107 * Text Functions::              General-purpose text manipulation functions.
   5108 * File Name Functions::         Functions for manipulating file names.
   5109 * Conditional Functions::       Functions that implement conditions.
   5110 * Foreach Function::            Repeat some text with controlled variation.
   5111 * Call Function::               Expand a user-defined function.
   5112 * Value Function::              Return the un-expanded value of a variable.
   5113 * Eval Function::               Evaluate the arguments as makefile syntax.
   5114 * Origin Function::             Find where a variable got its value.
   5115 * Flavor Function::             Find out the flavor of a variable.
   5116 * Shell Function::              Substitute the output of a shell command.
   5117 * Make Control Functions::      Functions that control how make runs.
   5118 
   5119 
   5120 File: make.info,  Node: Syntax of Functions,  Next: Text Functions,  Prev: Functions,  Up: Functions
   5121 
   5122 8.1 Function Call Syntax
   5123 ========================
   5124 
   5125 A function call resembles a variable reference.  It looks like this:
   5126 
   5127      $(FUNCTION ARGUMENTS)
   5128 
   5129 or like this:
   5130 
   5131      ${FUNCTION ARGUMENTS}
   5132 
   5133    Here FUNCTION is a function name; one of a short list of names that
   5134 are part of `make'.  You can also essentially create your own functions
   5135 by using the `call' builtin function.
   5136 
   5137    The ARGUMENTS are the arguments of the function.  They are separated
   5138 from the function name by one or more spaces or tabs, and if there is
   5139 more than one argument, then they are separated by commas.  Such
   5140 whitespace and commas are not part of an argument's value.  The
   5141 delimiters which you use to surround the function call, whether
   5142 parentheses or braces, can appear in an argument only in matching pairs;
   5143 the other kind of delimiters may appear singly.  If the arguments
   5144 themselves contain other function calls or variable references, it is
   5145 wisest to use the same kind of delimiters for all the references; write
   5146 `$(subst a,b,$(x))', not `$(subst a,b,${x})'.  This is because it is
   5147 clearer, and because only one type of delimiter is matched to find the
   5148 end of the reference.
   5149 
   5150    The text written for each argument is processed by substitution of
   5151 variables and function calls to produce the argument value, which is
   5152 the text on which the function acts.  The substitution is done in the
   5153 order in which the arguments appear.
   5154 
   5155    Commas and unmatched parentheses or braces cannot appear in the text
   5156 of an argument as written; leading spaces cannot appear in the text of
   5157 the first argument as written.  These characters can be put into the
   5158 argument value by variable substitution.  First define variables
   5159 `comma' and `space' whose values are isolated comma and space
   5160 characters, then substitute these variables where such characters are
   5161 wanted, like this:
   5162 
   5163      comma:= ,
   5164      empty:=
   5165      space:= $(empty) $(empty)
   5166      foo:= a b c
   5167      bar:= $(subst $(space),$(comma),$(foo))
   5168      # bar is now `a,b,c'.
   5169 
   5170 Here the `subst' function replaces each space with a comma, through the
   5171 value of `foo', and substitutes the result.
   5172 
   5173 
   5174 File: make.info,  Node: Text Functions,  Next: File Name Functions,  Prev: Syntax of Functions,  Up: Functions
   5175 
   5176 8.2 Functions for String Substitution and Analysis
   5177 ==================================================
   5178 
   5179 Here are some functions that operate on strings:
   5180 
   5181 `$(subst FROM,TO,TEXT)'
   5182      Performs a textual replacement on the text TEXT: each occurrence
   5183      of FROM is replaced by TO.  The result is substituted for the
   5184      function call.  For example,
   5185 
   5186           $(subst ee,EE,feet on the street)
   5187 
   5188      substitutes the string `fEEt on the strEEt'.
   5189 
   5190 `$(patsubst PATTERN,REPLACEMENT,TEXT)'
   5191      Finds whitespace-separated words in TEXT that match PATTERN and
   5192      replaces them with REPLACEMENT.  Here PATTERN may contain a `%'
   5193      which acts as a wildcard, matching any number of any characters
   5194      within a word.  If REPLACEMENT also contains a `%', the `%' is
   5195      replaced by the text that matched the `%' in PATTERN.  Only the
   5196      first `%' in the PATTERN and REPLACEMENT is treated this way; any
   5197      subsequent `%' is unchanged.
   5198 
   5199      `%' characters in `patsubst' function invocations can be quoted
   5200      with preceding backslashes (`\').  Backslashes that would
   5201      otherwise quote `%' characters can be quoted with more backslashes.
   5202      Backslashes that quote `%' characters or other backslashes are
   5203      removed from the pattern before it is compared file names or has a
   5204      stem substituted into it.  Backslashes that are not in danger of
   5205      quoting `%' characters go unmolested.  For example, the pattern
   5206      `the\%weird\\%pattern\\' has `the%weird\' preceding the operative
   5207      `%' character, and `pattern\\' following it.  The final two
   5208      backslashes are left alone because they cannot affect any `%'
   5209      character.
   5210 
   5211      Whitespace between words is folded into single space characters;
   5212      leading and trailing whitespace is discarded.
   5213 
   5214      For example,
   5215 
   5216           $(patsubst %.c,%.o,x.c.c bar.c)
   5217 
   5218      produces the value `x.c.o bar.o'.
   5219 
   5220      Substitution references (*note Substitution References:
   5221      Substitution Refs.) are a simpler way to get the effect of the
   5222      `patsubst' function:
   5223 
   5224           $(VAR:PATTERN=REPLACEMENT)
   5225 
   5226      is equivalent to
   5227 
   5228           $(patsubst PATTERN,REPLACEMENT,$(VAR))
   5229 
   5230      The second shorthand simplifies one of the most common uses of
   5231      `patsubst': replacing the suffix at the end of file names.
   5232 
   5233           $(VAR:SUFFIX=REPLACEMENT)
   5234 
   5235      is equivalent to
   5236 
   5237           $(patsubst %SUFFIX,%REPLACEMENT,$(VAR))
   5238 
   5239      For example, you might have a list of object files:
   5240 
   5241           objects = foo.o bar.o baz.o
   5242 
   5243      To get the list of corresponding source files, you could simply
   5244      write:
   5245 
   5246           $(objects:.o=.c)
   5247 
   5248      instead of using the general form:
   5249 
   5250           $(patsubst %.o,%.c,$(objects))
   5251 
   5252 `$(strip STRING)'
   5253      Removes leading and trailing whitespace from STRING and replaces
   5254      each internal sequence of one or more whitespace characters with a
   5255      single space.  Thus, `$(strip a b  c )' results in `a b c'.
   5256 
   5257      The function `strip' can be very useful when used in conjunction
   5258      with conditionals.  When comparing something with the empty string
   5259      `' using `ifeq' or `ifneq', you usually want a string of just
   5260      whitespace to match the empty string (*note Conditionals::).
   5261 
   5262      Thus, the following may fail to have the desired results:
   5263 
   5264           .PHONY: all
   5265           ifneq   "$(needs_made)" ""
   5266           all: $(needs_made)
   5267           else
   5268           all:;@echo 'Nothing to make!'
   5269           endif
   5270 
   5271      Replacing the variable reference `$(needs_made)' with the function
   5272      call `$(strip $(needs_made))' in the `ifneq' directive would make
   5273      it more robust.
   5274 
   5275 `$(findstring FIND,IN)'
   5276      Searches IN for an occurrence of FIND.  If it occurs, the value is
   5277      FIND; otherwise, the value is empty.  You can use this function in
   5278      a conditional to test for the presence of a specific substring in
   5279      a given string.  Thus, the two examples,
   5280 
   5281           $(findstring a,a b c)
   5282           $(findstring a,b c)
   5283 
   5284      produce the values `a' and `' (the empty string), respectively.
   5285      *Note Testing Flags::, for a practical application of `findstring'.
   5286 
   5287 `$(filter PATTERN...,TEXT)'
   5288      Returns all whitespace-separated words in TEXT that _do_ match any
   5289      of the PATTERN words, removing any words that _do not_ match.  The
   5290      patterns are written using `%', just like the patterns used in the
   5291      `patsubst' function above.
   5292 
   5293      The `filter' function can be used to separate out different types
   5294      of strings (such as file names) in a variable.  For example:
   5295 
   5296           sources := foo.c bar.c baz.s ugh.h
   5297           foo: $(sources)
   5298                   cc $(filter %.c %.s,$(sources)) -o foo
   5299 
   5300      says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h'
   5301      but only `foo.c', `bar.c' and `baz.s' should be specified in the
   5302      command to the compiler.
   5303 
   5304 `$(filter-out PATTERN...,TEXT)'
   5305      Returns all whitespace-separated words in TEXT that _do not_ match
   5306      any of the PATTERN words, removing the words that _do_ match one
   5307      or more.  This is the exact opposite of the `filter' function.
   5308 
   5309      For example, given:
   5310 
   5311           objects=main1.o foo.o main2.o bar.o
   5312           mains=main1.o main2.o
   5313 
   5314      the following generates a list which contains all the object files
   5315      not in `mains':
   5316 
   5317           $(filter-out $(mains),$(objects))
   5318 
   5319 `$(sort LIST)'
   5320      Sorts the words of LIST in lexical order, removing duplicate
   5321      words.  The output is a list of words separated by single spaces.
   5322      Thus,
   5323 
   5324           $(sort foo bar lose)
   5325 
   5326      returns the value `bar foo lose'.
   5327 
   5328      Incidentally, since `sort' removes duplicate words, you can use it
   5329      for this purpose even if you don't care about the sort order.
   5330 
   5331 `$(word N,TEXT)'
   5332      Returns the Nth word of TEXT.  The legitimate values of N start
   5333      from 1.  If N is bigger than the number of words in TEXT, the
   5334      value is empty.  For example,
   5335 
   5336           $(word 2, foo bar baz)
   5337 
   5338      returns `bar'.
   5339 
   5340 `$(wordlist S,E,TEXT)'
   5341      Returns the list of words in TEXT starting with word S and ending
   5342      with word E (inclusive).  The legitimate values of S start from 1;
   5343      E may start from 0.  If S is bigger than the number of words in
   5344      TEXT, the value is empty.  If E is bigger than the number of words
   5345      in TEXT, words up to the end of TEXT are returned.  If S is
   5346      greater than E, nothing is returned.  For example,
   5347 
   5348           $(wordlist 2, 3, foo bar baz)
   5349 
   5350      returns `bar baz'.
   5351 
   5352 `$(words TEXT)'
   5353      Returns the number of words in TEXT.  Thus, the last word of TEXT
   5354      is `$(word $(words TEXT),TEXT)'.
   5355 
   5356 `$(firstword NAMES...)'
   5357      The argument NAMES is regarded as a series of names, separated by
   5358      whitespace.  The value is the first name in the series.  The rest
   5359      of the names are ignored.
   5360 
   5361      For example,
   5362 
   5363           $(firstword foo bar)
   5364 
   5365      produces the result `foo'.  Although `$(firstword TEXT)' is the
   5366      same as `$(word 1,TEXT)', the `firstword' function is retained for
   5367      its simplicity.
   5368 
   5369 `$(lastword NAMES...)'
   5370      The argument NAMES is regarded as a series of names, separated by
   5371      whitespace.  The value is the last name in the series.
   5372 
   5373      For example,
   5374 
   5375           $(lastword foo bar)
   5376 
   5377      produces the result `bar'.  Although `$(lastword TEXT)' is the
   5378      same as `$(word $(words TEXT),TEXT)', the `lastword' function was
   5379      added for its simplicity and better performance.
   5380 
   5381    Here is a realistic example of the use of `subst' and `patsubst'.
   5382 Suppose that a makefile uses the `VPATH' variable to specify a list of
   5383 directories that `make' should search for prerequisite files (*note
   5384 `VPATH' Search Path for All Prerequisites: General Search.).  This
   5385 example shows how to tell the C compiler to search for header files in
   5386 the same list of directories.
   5387 
   5388    The value of `VPATH' is a list of directories separated by colons,
   5389 such as `src:../headers'.  First, the `subst' function is used to
   5390 change the colons to spaces:
   5391 
   5392      $(subst :, ,$(VPATH))
   5393 
   5394 This produces `src ../headers'.  Then `patsubst' is used to turn each
   5395 directory name into a `-I' flag.  These can be added to the value of
   5396 the variable `CFLAGS', which is passed automatically to the C compiler,
   5397 like this:
   5398 
   5399      override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
   5400 
   5401 The effect is to append the text `-Isrc -I../headers' to the previously
   5402 given value of `CFLAGS'.  The `override' directive is used so that the
   5403 new value is assigned even if the previous value of `CFLAGS' was
   5404 specified with a command argument (*note The `override' Directive:
   5405 Override Directive.).
   5406 
   5407 
   5408 File: make.info,  Node: File Name Functions,  Next: Conditional Functions,  Prev: Text Functions,  Up: Functions
   5409 
   5410 8.3 Functions for File Names
   5411 ============================
   5412 
   5413 Several of the built-in expansion functions relate specifically to
   5414 taking apart file names or lists of file names.
   5415 
   5416    Each of the following functions performs a specific transformation
   5417 on a file name.  The argument of the function is regarded as a series
   5418 of file names, separated by whitespace.  (Leading and trailing
   5419 whitespace is ignored.)  Each file name in the series is transformed in
   5420 the same way and the results are concatenated with single spaces
   5421 between them.
   5422 
   5423 `$(dir NAMES...)'
   5424      Extracts the directory-part of each file name in NAMES.  The
   5425      directory-part of the file name is everything up through (and
   5426      including) the last slash in it.  If the file name contains no
   5427      slash, the directory part is the string `./'.  For example,
   5428 
   5429           $(dir src/foo.c hacks)
   5430 
   5431      produces the result `src/ ./'.
   5432 
   5433 `$(notdir NAMES...)'
   5434      Extracts all but the directory-part of each file name in NAMES.
   5435      If the file name contains no slash, it is left unchanged.
   5436      Otherwise, everything through the last slash is removed from it.
   5437 
   5438      A file name that ends with a slash becomes an empty string.  This
   5439      is unfortunate, because it means that the result does not always
   5440      have the same number of whitespace-separated file names as the
   5441      argument had; but we do not see any other valid alternative.
   5442 
   5443      For example,
   5444 
   5445           $(notdir src/foo.c hacks)
   5446 
   5447      produces the result `foo.c hacks'.
   5448 
   5449 `$(suffix NAMES...)'
   5450      Extracts the suffix of each file name in NAMES.  If the file name
   5451      contains a period, the suffix is everything starting with the last
   5452      period.  Otherwise, the suffix is the empty string.  This
   5453      frequently means that the result will be empty when NAMES is not,
   5454      and if NAMES contains multiple file names, the result may contain
   5455      fewer file names.
   5456 
   5457      For example,
   5458 
   5459           $(suffix src/foo.c src-1.0/bar.c hacks)
   5460 
   5461      produces the result `.c .c'.
   5462 
   5463 `$(basename NAMES...)'
   5464      Extracts all but the suffix of each file name in NAMES.  If the
   5465      file name contains a period, the basename is everything starting
   5466      up to (and not including) the last period.  Periods in the
   5467      directory part are ignored.  If there is no period, the basename
   5468      is the entire file name.  For example,
   5469 
   5470           $(basename src/foo.c src-1.0/bar hacks)
   5471 
   5472      produces the result `src/foo src-1.0/bar hacks'.
   5473 
   5474 `$(addsuffix SUFFIX,NAMES...)'
   5475      The argument NAMES is regarded as a series of names, separated by
   5476      whitespace; SUFFIX is used as a unit.  The value of SUFFIX is
   5477      appended to the end of each individual name and the resulting
   5478      larger names are concatenated with single spaces between them.
   5479      For example,
   5480 
   5481           $(addsuffix .c,foo bar)
   5482 
   5483      produces the result `foo.c bar.c'.
   5484 
   5485 `$(addprefix PREFIX,NAMES...)'
   5486      The argument NAMES is regarded as a series of names, separated by
   5487      whitespace; PREFIX is used as a unit.  The value of PREFIX is
   5488      prepended to the front of each individual name and the resulting
   5489      larger names are concatenated with single spaces between them.
   5490      For example,
   5491 
   5492           $(addprefix src/,foo bar)
   5493 
   5494      produces the result `src/foo src/bar'.
   5495 
   5496 `$(join LIST1,LIST2)'
   5497      Concatenates the two arguments word by word: the two first words
   5498      (one from each argument) concatenated form the first word of the
   5499      result, the two second words form the second word of the result,
   5500      and so on.  So the Nth word of the result comes from the Nth word
   5501      of each argument.  If one argument has more words that the other,
   5502      the extra words are copied unchanged into the result.
   5503 
   5504      For example, `$(join a b,.c .o)' produces `a.c b.o'.
   5505 
   5506      Whitespace between the words in the lists is not preserved; it is
   5507      replaced with a single space.
   5508 
   5509      This function can merge the results of the `dir' and `notdir'
   5510      functions, to produce the original list of files which was given
   5511      to those two functions.
   5512 
   5513 `$(wildcard PATTERN)'
   5514      The argument PATTERN is a file name pattern, typically containing
   5515      wildcard characters (as in shell file name patterns).  The result
   5516      of `wildcard' is a space-separated list of the names of existing
   5517      files that match the pattern.  *Note Using Wildcard Characters in
   5518      File Names: Wildcards.
   5519 
   5520 `$(realpath NAMES...)'
   5521      For each file name in NAMES return the canonical absolute name.  A
   5522      canonical name does not contain any `.' or `..' components, nor
   5523      any repeated path separators (`/') or symlinks.  In case of a
   5524      failure the empty string is returned.  Consult the `realpath(3)'
   5525      documentation for a list of possible failure causes.
   5526 
   5527 `$(abspath NAMES...)'
   5528      For each file name in NAMES return an absolute name that does not
   5529      contain any `.' or `..' components, nor any repeated path
   5530      separators (`/').  Note that, in contrast to `realpath' function,
   5531      `abspath' does not resolve symlinks and does not require the file
   5532      names to refer to an existing file or directory.  Use the
   5533      `wildcard' function to test for existence.
   5534 
   5535 
   5536 File: make.info,  Node: Conditional Functions,  Next: Foreach Function,  Prev: File Name Functions,  Up: Functions
   5537 
   5538 8.4 Functions for Conditionals
   5539 ==============================
   5540 
   5541 There are three functions that provide conditional expansion.  A key
   5542 aspect of these functions is that not all of the arguments are expanded
   5543 initially.  Only those arguments which need to be expanded, will be
   5544 expanded.
   5545 
   5546 `$(if CONDITION,THEN-PART[,ELSE-PART])'
   5547      The `if' function provides support for conditional expansion in a
   5548      functional context (as opposed to the GNU `make' makefile
   5549      conditionals such as `ifeq' (*note Syntax of Conditionals:
   5550      Conditional Syntax.).
   5551 
   5552      The first argument, CONDITION, first has all preceding and
   5553      trailing whitespace stripped, then is expanded.  If it expands to
   5554      any non-empty string, then the condition is considered to be true.
   5555      If it expands to an empty string, the condition is considered to
   5556      be false.
   5557 
   5558      If the condition is true then the second argument, THEN-PART, is
   5559      evaluated and this is used as the result of the evaluation of the
   5560      entire `if' function.
   5561 
   5562      If the condition is false then the third argument, ELSE-PART, is
   5563      evaluated and this is the result of the `if' function.  If there is
   5564      no third argument, the `if' function evaluates to nothing (the
   5565      empty string).
   5566 
   5567      Note that only one of the THEN-PART or the ELSE-PART will be
   5568      evaluated, never both.  Thus, either can contain side-effects
   5569      (such as `shell' function calls, etc.)
   5570 
   5571 `$(or CONDITION1[,CONDITION2[,CONDITION3...]])'
   5572      The `or' function provides a "short-circuiting" OR operation.
   5573      Each argument is expanded, in order.  If an argument expands to a
   5574      non-empty string the processing stops and the result of the
   5575      expansion is that string.  If, after all arguments are expanded,
   5576      all of them are false (empty), then the result of the expansion is
   5577      the empty string.
   5578 
   5579 `$(and CONDITION1[,CONDITION2[,CONDITION3...]])'
   5580      The `and' function provides a "short-circuiting" AND operation.
   5581      Each argument is expanded, in order.  If an argument expands to an
   5582      empty string the processing stops and the result of the expansion
   5583      is the empty string.  If all arguments expand to a non-empty
   5584      string then the result of the expansion is the expansion of the
   5585      last argument.
   5586 
   5587 
   5588 
   5589 File: make.info,  Node: Foreach Function,  Next: Call Function,  Prev: Conditional Functions,  Up: Functions
   5590 
   5591 8.5 The `foreach' Function
   5592 ==========================
   5593 
   5594 The `foreach' function is very different from other functions.  It
   5595 causes one piece of text to be used repeatedly, each time with a
   5596 different substitution performed on it.  It resembles the `for' command
   5597 in the shell `sh' and the `foreach' command in the C-shell `csh'.
   5598 
   5599    The syntax of the `foreach' function is:
   5600 
   5601      $(foreach VAR,LIST,TEXT)
   5602 
   5603 The first two arguments, VAR and LIST, are expanded before anything
   5604 else is done; note that the last argument, TEXT, is *not* expanded at
   5605 the same time.  Then for each word of the expanded value of LIST, the
   5606 variable named by the expanded value of VAR is set to that word, and
   5607 TEXT is expanded.  Presumably TEXT contains references to that
   5608 variable, so its expansion will be different each time.
   5609 
   5610    The result is that TEXT is expanded as many times as there are
   5611 whitespace-separated words in LIST.  The multiple expansions of TEXT
   5612 are concatenated, with spaces between them, to make the result of
   5613 `foreach'.
   5614 
   5615    This simple example sets the variable `files' to the list of all
   5616 files in the directories in the list `dirs':
   5617 
   5618      dirs := a b c d
   5619      files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
   5620 
   5621    Here TEXT is `$(wildcard $(dir)/*)'.  The first repetition finds the
   5622 value `a' for `dir', so it produces the same result as `$(wildcard
   5623 a/*)'; the second repetition produces the result of `$(wildcard b/*)';
   5624 and the third, that of `$(wildcard c/*)'.
   5625 
   5626    This example has the same result (except for setting `dirs') as the
   5627 following example:
   5628 
   5629      files := $(wildcard a/* b/* c/* d/*)
   5630 
   5631    When TEXT is complicated, you can improve readability by giving it a
   5632 name, with an additional variable:
   5633 
   5634      find_files = $(wildcard $(dir)/*)
   5635      dirs := a b c d
   5636      files := $(foreach dir,$(dirs),$(find_files))
   5637 
   5638 Here we use the variable `find_files' this way.  We use plain `=' to
   5639 define a recursively-expanding variable, so that its value contains an
   5640 actual function call to be reexpanded under the control of `foreach'; a
   5641 simply-expanded variable would not do, since `wildcard' would be called
   5642 only once at the time of defining `find_files'.
   5643 
   5644    The `foreach' function has no permanent effect on the variable VAR;
   5645 its value and flavor after the `foreach' function call are the same as
   5646 they were beforehand.  The other values which are taken from LIST are
   5647 in effect only temporarily, during the execution of `foreach'.  The
   5648 variable VAR is a simply-expanded variable during the execution of
   5649 `foreach'.  If VAR was undefined before the `foreach' function call, it
   5650 is undefined after the call.  *Note The Two Flavors of Variables:
   5651 Flavors.
   5652 
   5653    You must take care when using complex variable expressions that
   5654 result in variable names because many strange things are valid variable
   5655 names, but are probably not what you intended.  For example,
   5656 
   5657      files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
   5658 
   5659 might be useful if the value of `find_files' references the variable
   5660 whose name is `Esta escrito en espanol!' (es un nombre bastante largo,
   5661 no?), but it is more likely to be a mistake.
   5662 
   5663 
   5664 File: make.info,  Node: Call Function,  Next: Value Function,  Prev: Foreach Function,  Up: Functions
   5665 
   5666 8.6 The `call' Function
   5667 =======================
   5668 
   5669 The `call' function is unique in that it can be used to create new
   5670 parameterized functions.  You can write a complex expression as the
   5671 value of a variable, then use `call' to expand it with different values.
   5672 
   5673    The syntax of the `call' function is:
   5674 
   5675      $(call VARIABLE,PARAM,PARAM,...)
   5676 
   5677    When `make' expands this function, it assigns each PARAM to
   5678 temporary variables `$(1)', `$(2)', etc.  The variable `$(0)' will
   5679 contain VARIABLE.  There is no maximum number of parameter arguments.
   5680 There is no minimum, either, but it doesn't make sense to use `call'
   5681 with no parameters.
   5682 
   5683    Then VARIABLE is expanded as a `make' variable in the context of
   5684 these temporary assignments.  Thus, any reference to `$(1)' in the
   5685 value of VARIABLE will resolve to the first PARAM in the invocation of
   5686 `call'.
   5687 
   5688    Note that VARIABLE is the _name_ of a variable, not a _reference_ to
   5689 that variable.  Therefore you would not normally use a `$' or
   5690 parentheses when writing it.  (You can, however, use a variable
   5691 reference in the name if you want the name not to be a constant.)
   5692 
   5693    If VARIABLE is the name of a builtin function, the builtin function
   5694 is always invoked (even if a `make' variable by that name also exists).
   5695 
   5696    The `call' function expands the PARAM arguments before assigning
   5697 them to temporary variables.  This means that VARIABLE values
   5698 containing references to builtin functions that have special expansion
   5699 rules, like `foreach' or `if', may not work as you expect.
   5700 
   5701    Some examples may make this clearer.
   5702 
   5703    This macro simply reverses its arguments:
   5704 
   5705      reverse = $(2) $(1)
   5706 
   5707      foo = $(call reverse,a,b)
   5708 
   5709 Here FOO will contain `b a'.
   5710 
   5711    This one is slightly more interesting: it defines a macro to search
   5712 for the first instance of a program in `PATH':
   5713 
   5714      pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
   5715 
   5716      LS := $(call pathsearch,ls)
   5717 
   5718 Now the variable LS contains `/bin/ls' or similar.
   5719 
   5720    The `call' function can be nested.  Each recursive invocation gets
   5721 its own local values for `$(1)', etc. that mask the values of
   5722 higher-level `call'.  For example, here is an implementation of a "map"
   5723 function:
   5724 
   5725      map = $(foreach a,$(2),$(call $(1),$(a)))
   5726 
   5727    Now you can MAP a function that normally takes only one argument,
   5728 such as `origin', to multiple values in one step:
   5729 
   5730      o = $(call map,origin,o map MAKE)
   5731 
   5732    and end up with O containing something like `file file default'.
   5733 
   5734    A final caution: be careful when adding whitespace to the arguments
   5735 to `call'.  As with other functions, any whitespace contained in the
   5736 second and subsequent arguments is kept; this can cause strange
   5737 effects.  It's generally safest to remove all extraneous whitespace when
   5738 providing parameters to `call'.
   5739 
   5740 
   5741 File: make.info,  Node: Value Function,  Next: Eval Function,  Prev: Call Function,  Up: Functions
   5742 
   5743 8.7 The `value' Function
   5744 ========================
   5745 
   5746 The `value' function provides a way for you to use the value of a
   5747 variable _without_ having it expanded.  Please note that this does not
   5748 undo expansions which have already occurred; for example if you create
   5749 a simply expanded variable its value is expanded during the definition;
   5750 in that case the `value' function will return the same result as using
   5751 the variable directly.
   5752 
   5753    The syntax of the `value' function is:
   5754 
   5755      $(value VARIABLE)
   5756 
   5757    Note that VARIABLE is the _name_ of a variable; not a _reference_ to
   5758 that variable.  Therefore you would not normally use a `$' or
   5759 parentheses when writing it.  (You can, however, use a variable
   5760 reference in the name if you want the name not to be a constant.)
   5761 
   5762    The result of this function is a string containing the value of
   5763 VARIABLE, without any expansion occurring.  For example, in this
   5764 makefile:
   5765 
   5766      FOO = $PATH
   5767 
   5768      all:
   5769              @echo $(FOO)
   5770              @echo $(value FOO)
   5771 
   5772 The first output line would be `ATH', since the "$P" would be expanded
   5773 as a `make' variable, while the second output line would be the current
   5774 value of your `$PATH' environment variable, since the `value' function
   5775 avoided the expansion.
   5776 
   5777    The `value' function is most often used in conjunction with the
   5778 `eval' function (*note Eval Function::).
   5779 
   5780 
   5781 File: make.info,  Node: Eval Function,  Next: Origin Function,  Prev: Value Function,  Up: Functions
   5782 
   5783 8.8 The `eval' Function
   5784 =======================
   5785 
   5786 The `eval' function is very special: it allows you to define new
   5787 makefile constructs that are not constant; which are the result of
   5788 evaluating other variables and functions.  The argument to the `eval'
   5789 function is expanded, then the results of that expansion are parsed as
   5790 makefile syntax.  The expanded results can define new `make' variables,
   5791 targets, implicit or explicit rules, etc.
   5792 
   5793    The result of the `eval' function is always the empty string; thus,
   5794 it can be placed virtually anywhere in a makefile without causing
   5795 syntax errors.
   5796 
   5797    It's important to realize that the `eval' argument is expanded
   5798 _twice_; first by the `eval' function, then the results of that
   5799 expansion are expanded again when they are parsed as makefile syntax.
   5800 This means you may need to provide extra levels of escaping for "$"
   5801 characters when using `eval'.  The `value' function (*note Value
   5802 Function::) can sometimes be useful in these situations, to circumvent
   5803 unwanted expansions.
   5804 
   5805    Here is an example of how `eval' can be used; this example combines
   5806 a number of concepts and other functions.  Although it might seem
   5807 overly complex to use `eval' in this example, rather than just writing
   5808 out the rules, consider two things: first, the template definition (in
   5809 `PROGRAM_template') could need to be much more complex than it is here;
   5810 and second, you might put the complex, "generic" part of this example
   5811 into another makefile, then include it in all the individual makefiles.
   5812 Now your individual makefiles are quite straightforward.
   5813 
   5814      PROGRAMS    = server client
   5815 
   5816      server_OBJS = server.o server_priv.o server_access.o
   5817      server_LIBS = priv protocol
   5818 
   5819      client_OBJS = client.o client_api.o client_mem.o
   5820      client_LIBS = protocol
   5821 
   5822      # Everything after this is generic
   5823 
   5824      .PHONY: all
   5825      all: $(PROGRAMS)
   5826 
   5827      define PROGRAM_template
   5828       $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
   5829       ALL_OBJS   += $$($(1)_OBJS)
   5830      endef
   5831 
   5832      $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
   5833 
   5834      $(PROGRAMS):
   5835              $(LINK.o) $^ $(LDLIBS) -o $@
   5836 
   5837      clean:
   5838              rm -f $(ALL_OBJS) $(PROGRAMS)
   5839 
   5840 
   5841 File: make.info,  Node: Origin Function,  Next: Flavor Function,  Prev: Eval Function,  Up: Functions
   5842 
   5843 8.9 The `origin' Function
   5844 =========================
   5845 
   5846 The `origin' function is unlike most other functions in that it does
   5847 not operate on the values of variables; it tells you something _about_
   5848 a variable.  Specifically, it tells you where it came from.
   5849 
   5850    The syntax of the `origin' function is:
   5851 
   5852      $(origin VARIABLE)
   5853 
   5854    Note that VARIABLE is the _name_ of a variable to inquire about; not
   5855 a _reference_ to that variable.  Therefore you would not normally use a
   5856 `$' or parentheses when writing it.  (You can, however, use a variable
   5857 reference in the name if you want the name not to be a constant.)
   5858 
   5859    The result of this function is a string telling you how the variable
   5860 VARIABLE was defined:
   5861 
   5862 `undefined'
   5863      if VARIABLE was never defined.
   5864 
   5865 `default'
   5866      if VARIABLE has a default definition, as is usual with `CC' and so
   5867      on.  *Note Variables Used by Implicit Rules: Implicit Variables.
   5868      Note that if you have redefined a default variable, the `origin'
   5869      function will return the origin of the later definition.
   5870 
   5871 `environment'
   5872      if VARIABLE was defined as an environment variable and the `-e'
   5873      option is _not_ turned on (*note Summary of Options: Options
   5874      Summary.).
   5875 
   5876 `environment override'
   5877      if VARIABLE was defined as an environment variable and the `-e'
   5878      option _is_ turned on (*note Summary of Options: Options Summary.).
   5879 
   5880 `file'
   5881      if VARIABLE was defined in a makefile.
   5882 
   5883 `command line'
   5884      if VARIABLE was defined on the command line.
   5885 
   5886 `override'
   5887      if VARIABLE was defined with an `override' directive in a makefile
   5888      (*note The `override' Directive: Override Directive.).
   5889 
   5890 `automatic'
   5891      if VARIABLE is an automatic variable defined for the execution of
   5892      the commands for each rule (*note Automatic Variables::).
   5893 
   5894    This information is primarily useful (other than for your curiosity)
   5895 to determine if you want to believe the value of a variable.  For
   5896 example, suppose you have a makefile `foo' that includes another
   5897 makefile `bar'.  You want a variable `bletch' to be defined in `bar' if
   5898 you run the command `make -f bar', even if the environment contains a
   5899 definition of `bletch'.  However, if `foo' defined `bletch' before
   5900 including `bar', you do not want to override that definition.  This
   5901 could be done by using an `override' directive in `foo', giving that
   5902 definition precedence over the later definition in `bar';
   5903 unfortunately, the `override' directive would also override any command
   5904 line definitions.  So, `bar' could include:
   5905 
   5906      ifdef bletch
   5907      ifeq "$(origin bletch)" "environment"
   5908      bletch = barf, gag, etc.
   5909      endif
   5910      endif
   5911 
   5912 If `bletch' has been defined from the environment, this will redefine
   5913 it.
   5914 
   5915    If you want to override a previous definition of `bletch' if it came
   5916 from the environment, even under `-e', you could instead write:
   5917 
   5918      ifneq "$(findstring environment,$(origin bletch))" ""
   5919      bletch = barf, gag, etc.
   5920      endif
   5921 
   5922    Here the redefinition takes place if `$(origin bletch)' returns
   5923 either `environment' or `environment override'.  *Note Functions for
   5924 String Substitution and Analysis: Text Functions.
   5925 
   5926 
   5927 File: make.info,  Node: Flavor Function,  Next: Shell Function,  Prev: Origin Function,  Up: Functions
   5928 
   5929 8.10 The `flavor' Function
   5930 ==========================
   5931 
   5932 The `flavor' function is unlike most other functions (and like `origin'
   5933 function) in that it does not operate on the values of variables; it
   5934 tells you something _about_ a variable.  Specifically, it tells you the
   5935 flavor of a variable (*note The Two Flavors of Variables: Flavors.).
   5936 
   5937    The syntax of the `flavor' function is:
   5938 
   5939      $(flavor VARIABLE)
   5940 
   5941    Note that VARIABLE is the _name_ of a variable to inquire about; not
   5942 a _reference_ to that variable.  Therefore you would not normally use a
   5943 `$' or parentheses when writing it.  (You can, however, use a variable
   5944 reference in the name if you want the name not to be a constant.)
   5945 
   5946    The result of this function is a string that identifies the flavor
   5947 of the variable VARIABLE:
   5948 
   5949 `undefined'
   5950      if VARIABLE was never defined.
   5951 
   5952 `recursive'
   5953      if VARIABLE is a recursively expanded variable.
   5954 
   5955 `simple'
   5956      if VARIABLE is a simply expanded variable.
   5957 
   5958 
   5959 
   5960 File: make.info,  Node: Shell Function,  Next: Make Control Functions,  Prev: Flavor Function,  Up: Functions
   5961 
   5962 8.11 The `shell' Function
   5963 =========================
   5964 
   5965 The `shell' function is unlike any other function other than the
   5966 `wildcard' function (*note The Function `wildcard': Wildcard Function.)
   5967 in that it communicates with the world outside of `make'.
   5968 
   5969    The `shell' function performs the same function that backquotes
   5970 (``') perform in most shells: it does "command expansion".  This means
   5971 that it takes as an argument a shell command and evaluates to the
   5972 output of the command.  The only processing `make' does on the result
   5973 is to convert each newline (or carriage-return / newline pair) to a
   5974 single space.  If there is a trailing (carriage-return and) newline it
   5975 will simply be removed.
   5976 
   5977    The commands run by calls to the `shell' function are run when the
   5978 function calls are expanded (*note How `make' Reads a Makefile: Reading
   5979 Makefiles.).  Because this function involves spawning a new shell, you
   5980 should carefully consider the performance implications of using the
   5981 `shell' function within recursively expanded variables vs. simply
   5982 expanded variables (*note The Two Flavors of Variables: Flavors.).
   5983 
   5984    Here are some examples of the use of the `shell' function:
   5985 
   5986      contents := $(shell cat foo)
   5987 
   5988 sets `contents' to the contents of the file `foo', with a space (rather
   5989 than a newline) separating each line.
   5990 
   5991      files := $(shell echo *.c)
   5992 
   5993 sets `files' to the expansion of `*.c'.  Unless `make' is using a very
   5994 strange shell, this has the same result as `$(wildcard *.c)' (as long
   5995 as at least one `.c' file exists).
   5996 
   5997 
   5998 File: make.info,  Node: Make Control Functions,  Prev: Shell Function,  Up: Functions
   5999 
   6000 8.12 Functions That Control Make
   6001 ================================
   6002 
   6003 These functions control the way make runs.  Generally, they are used to
   6004 provide information to the user of the makefile or to cause make to stop
   6005 if some sort of environmental error is detected.
   6006 
   6007 `$(error TEXT...)'
   6008      Generates a fatal error where the message is TEXT.  Note that the
   6009      error is generated whenever this function is evaluated.  So, if
   6010      you put it inside a command script or on the right side of a
   6011      recursive variable assignment, it won't be evaluated until later.
   6012      The TEXT will be expanded before the error is generated.
   6013 
   6014      For example,
   6015 
   6016           ifdef ERROR1
   6017           $(error error is $(ERROR1))
   6018           endif
   6019 
   6020      will generate a fatal error during the read of the makefile if the
   6021      `make' variable `ERROR1' is defined.  Or,
   6022 
   6023           ERR = $(error found an error!)
   6024 
   6025           .PHONY: err
   6026           err: ; $(ERR)
   6027 
   6028      will generate a fatal error while `make' is running, if the `err'
   6029      target is invoked.
   6030 
   6031 `$(warning TEXT...)'
   6032      This function works similarly to the `error' function, above,
   6033      except that `make' doesn't exit.  Instead, TEXT is expanded and
   6034      the resulting message is displayed, but processing of the makefile
   6035      continues.
   6036 
   6037      The result of the expansion of this function is the empty string.
   6038 
   6039 `$(info TEXT...)'
   6040      This function does nothing more than print its (expanded)
   6041      argument(s) to standard output.  No makefile name or line number
   6042      is added.  The result of the expansion of this function is the
   6043      empty string.
   6044 
   6045 
   6046 File: make.info,  Node: Running,  Next: Implicit Rules,  Prev: Functions,  Up: Top
   6047 
   6048 9 How to Run `make'
   6049 *******************
   6050 
   6051 A makefile that says how to recompile a program can be used in more
   6052 than one way.  The simplest use is to recompile every file that is out
   6053 of date.  Usually, makefiles are written so that if you run `make' with
   6054 no arguments, it does just that.
   6055 
   6056    But you might want to update only some of the files; you might want
   6057 to use a different compiler or different compiler options; you might
   6058 want just to find out which files are out of date without changing them.
   6059 
   6060    By giving arguments when you run `make', you can do any of these
   6061 things and many others.
   6062 
   6063    The exit status of `make' is always one of three values:
   6064 `0'
   6065      The exit status is zero if `make' is successful.
   6066 
   6067 `2'
   6068      The exit status is two if `make' encounters any errors.  It will
   6069      print messages describing the particular errors.
   6070 
   6071 `1'
   6072      The exit status is one if you use the `-q' flag and `make'
   6073      determines that some target is not already up to date.  *Note
   6074      Instead of Executing the Commands: Instead of Execution.
   6075 
   6076 * Menu:
   6077 
   6078 * Makefile Arguments::          How to specify which makefile to use.
   6079 * Goals::                       How to use goal arguments to specify which
   6080                                   parts of the makefile to use.
   6081 * Instead of Execution::        How to use mode flags to specify what
   6082                                   kind of thing to do with the commands
   6083                                   in the makefile other than simply
   6084                                   execute them.
   6085 * Avoiding Compilation::        How to avoid recompiling certain files.
   6086 * Overriding::                  How to override a variable to specify
   6087                                   an alternate compiler and other things.
   6088 * Testing::                     How to proceed past some errors, to
   6089                                   test compilation.
   6090 * Options Summary::             Summary of Options
   6091 
   6092 
   6093 File: make.info,  Node: Makefile Arguments,  Next: Goals,  Prev: Running,  Up: Running
   6094 
   6095 9.1 Arguments to Specify the Makefile
   6096 =====================================
   6097 
   6098 The way to specify the name of the makefile is with the `-f' or
   6099 `--file' option (`--makefile' also works).  For example, `-f altmake'
   6100 says to use the file `altmake' as the makefile.
   6101 
   6102    If you use the `-f' flag several times and follow each `-f' with an
   6103 argument, all the specified files are used jointly as makefiles.
   6104 
   6105    If you do not use the `-f' or `--file' flag, the default is to try
   6106 `GNUmakefile', `makefile', and `Makefile', in that order, and use the
   6107 first of these three which exists or can be made (*note Writing
   6108 Makefiles: Makefiles.).
   6109 
   6110 
   6111 File: make.info,  Node: Goals,  Next: Instead of Execution,  Prev: Makefile Arguments,  Up: Running
   6112 
   6113 9.2 Arguments to Specify the Goals
   6114 ==================================
   6115 
   6116 The "goals" are the targets that `make' should strive ultimately to
   6117 update.  Other targets are updated as well if they appear as
   6118 prerequisites of goals, or prerequisites of prerequisites of goals, etc.
   6119 
   6120    By default, the goal is the first target in the makefile (not
   6121 counting targets that start with a period).  Therefore, makefiles are
   6122 usually written so that the first target is for compiling the entire
   6123 program or programs they describe.  If the first rule in the makefile
   6124 has several targets, only the first target in the rule becomes the
   6125 default goal, not the whole list.  You can manage the selection of the
   6126 default goal from within your makefile using the `.DEFAULT_GOAL'
   6127 variable (*note Other Special Variables: Special Variables.).
   6128 
   6129    You can also specify a different goal or goals with command-line
   6130 arguments to `make'.  Use the name of the goal as an argument.  If you
   6131 specify several goals, `make' processes each of them in turn, in the
   6132 order you name them.
   6133 
   6134    Any target in the makefile may be specified as a goal (unless it
   6135 starts with `-' or contains an `=', in which case it will be parsed as
   6136 a switch or variable definition, respectively).  Even targets not in
   6137 the makefile may be specified, if `make' can find implicit rules that
   6138 say how to make them.
   6139 
   6140    `Make' will set the special variable `MAKECMDGOALS' to the list of
   6141 goals you specified on the command line.  If no goals were given on the
   6142 command line, this variable is empty.  Note that this variable should
   6143 be used only in special circumstances.
   6144 
   6145    An example of appropriate use is to avoid including `.d' files
   6146 during `clean' rules (*note Automatic Prerequisites::), so `make' won't
   6147 create them only to immediately remove them again:
   6148 
   6149      sources = foo.c bar.c
   6150 
   6151      ifneq ($(MAKECMDGOALS),clean)
   6152      include $(sources:.c=.d)
   6153      endif
   6154 
   6155    One use of specifying a goal is if you want to compile only a part of
   6156 the program, or only one of several programs.  Specify as a goal each
   6157 file that you wish to remake.  For example, consider a directory
   6158 containing several programs, with a makefile that starts like this:
   6159 
   6160      .PHONY: all
   6161      all: size nm ld ar as
   6162 
   6163    If you are working on the program `size', you might want to say
   6164 `make size' so that only the files of that program are recompiled.
   6165 
   6166    Another use of specifying a goal is to make files that are not
   6167 normally made.  For example, there may be a file of debugging output,
   6168 or a version of the program that is compiled specially for testing,
   6169 which has a rule in the makefile but is not a prerequisite of the
   6170 default goal.
   6171 
   6172    Another use of specifying a goal is to run the commands associated
   6173 with a phony target (*note Phony Targets::) or empty target (*note
   6174 Empty Target Files to Record Events: Empty Targets.).  Many makefiles
   6175 contain a phony target named `clean' which deletes everything except
   6176 source files.  Naturally, this is done only if you request it
   6177 explicitly with `make clean'.  Following is a list of typical phony and
   6178 empty target names.  *Note Standard Targets::, for a detailed list of
   6179 all the standard target names which GNU software packages use.
   6180 
   6181 `all'
   6182      Make all the top-level targets the makefile knows about.
   6183 
   6184 `clean'
   6185      Delete all files that are normally created by running `make'.
   6186 
   6187 `mostlyclean'
   6188      Like `clean', but may refrain from deleting a few files that people
   6189      normally don't want to recompile.  For example, the `mostlyclean'
   6190      target for GCC does not delete `libgcc.a', because recompiling it
   6191      is rarely necessary and takes a lot of time.
   6192 
   6193 `distclean'
   6194 `realclean'
   6195 `clobber'
   6196      Any of these targets might be defined to delete _more_ files than
   6197      `clean' does.  For example, this would delete configuration files
   6198      or links that you would normally create as preparation for
   6199      compilation, even if the makefile itself cannot create these files.
   6200 
   6201 `install'
   6202      Copy the executable file into a directory that users typically
   6203      search for commands; copy any auxiliary files that the executable
   6204      uses into the directories where it will look for them.
   6205 
   6206 `print'
   6207      Print listings of the source files that have changed.
   6208 
   6209 `tar'
   6210      Create a tar file of the source files.
   6211 
   6212 `shar'
   6213      Create a shell archive (shar file) of the source files.
   6214 
   6215 `dist'
   6216      Create a distribution file of the source files.  This might be a
   6217      tar file, or a shar file, or a compressed version of one of the
   6218      above, or even more than one of the above.
   6219 
   6220 `TAGS'
   6221      Update a tags table for this program.
   6222 
   6223 `check'
   6224 `test'
   6225      Perform self tests on the program this makefile builds.
   6226 
   6227 
   6228 File: make.info,  Node: Instead of Execution,  Next: Avoiding Compilation,  Prev: Goals,  Up: Running
   6229 
   6230 9.3 Instead of Executing the Commands
   6231 =====================================
   6232 
   6233 The makefile tells `make' how to tell whether a target is up to date,
   6234 and how to update each target.  But updating the targets is not always
   6235 what you want.  Certain options specify other activities for `make'.
   6236 
   6237 `-n'
   6238 `--just-print'
   6239 `--dry-run'
   6240 `--recon'
   6241      "No-op".  The activity is to print what commands would be used to
   6242      make the targets up to date, but not actually execute them.
   6243 
   6244 `-t'
   6245 `--touch'
   6246      "Touch".  The activity is to mark the targets as up to date without
   6247      actually changing them.  In other words, `make' pretends to compile
   6248      the targets but does not really change their contents.
   6249 
   6250 `-q'
   6251 `--question'
   6252      "Question".  The activity is to find out silently whether the
   6253      targets are up to date already; but execute no commands in either
   6254      case.  In other words, neither compilation nor output will occur.
   6255 
   6256 `-W FILE'
   6257 `--what-if=FILE'
   6258 `--assume-new=FILE'
   6259 `--new-file=FILE'
   6260      "What if".  Each `-W' flag is followed by a file name.  The given
   6261      files' modification times are recorded by `make' as being the
   6262      present time, although the actual modification times remain the
   6263      same.  You can use the `-W' flag in conjunction with the `-n' flag
   6264      to see what would happen if you were to modify specific files.
   6265 
   6266    With the `-n' flag, `make' prints the commands that it would
   6267 normally execute but does not execute them.
   6268 
   6269    With the `-t' flag, `make' ignores the commands in the rules and
   6270 uses (in effect) the command `touch' for each target that needs to be
   6271 remade.  The `touch' command is also printed, unless `-s' or `.SILENT'
   6272 is used.  For speed, `make' does not actually invoke the program
   6273 `touch'.  It does the work directly.
   6274 
   6275    With the `-q' flag, `make' prints nothing and executes no commands,
   6276 but the exit status code it returns is zero if and only if the targets
   6277 to be considered are already up to date.  If the exit status is one,
   6278 then some updating needs to be done.  If `make' encounters an error,
   6279 the exit status is two, so you can distinguish an error from a target
   6280 that is not up to date.
   6281 
   6282    It is an error to use more than one of these three flags in the same
   6283 invocation of `make'.
   6284 
   6285    The `-n', `-t', and `-q' options do not affect command lines that
   6286 begin with `+' characters or contain the strings `$(MAKE)' or
   6287 `${MAKE}'.  Note that only the line containing the `+' character or the
   6288 strings `$(MAKE)' or `${MAKE}' is run regardless of these options.
   6289 Other lines in the same rule are not run unless they too begin with `+'
   6290 or contain `$(MAKE)' or `${MAKE}' (*Note How the `MAKE' Variable Works:
   6291 MAKE Variable.)
   6292 
   6293    The `-W' flag provides two features:
   6294 
   6295    * If you also use the `-n' or `-q' flag, you can see what `make'
   6296      would do if you were to modify some files.
   6297 
   6298    * Without the `-n' or `-q' flag, when `make' is actually executing
   6299      commands, the `-W' flag can direct `make' to act as if some files
   6300      had been modified, without actually modifying the files.
   6301 
   6302    Note that the options `-p' and `-v' allow you to obtain other
   6303 information about `make' or about the makefiles in use (*note Summary
   6304 of Options: Options Summary.).
   6305 
   6306 
   6307 File: make.info,  Node: Avoiding Compilation,  Next: Overriding,  Prev: Instead of Execution,  Up: Running
   6308 
   6309 9.4 Avoiding Recompilation of Some Files
   6310 ========================================
   6311 
   6312 Sometimes you may have changed a source file but you do not want to
   6313 recompile all the files that depend on it.  For example, suppose you add
   6314 a macro or a declaration to a header file that many other files depend
   6315 on.  Being conservative, `make' assumes that any change in the header
   6316 file requires recompilation of all dependent files, but you know that
   6317 they do not need to be recompiled and you would rather not waste the
   6318 time waiting for them to compile.
   6319 
   6320    If you anticipate the problem before changing the header file, you
   6321 can use the `-t' flag.  This flag tells `make' not to run the commands
   6322 in the rules, but rather to mark the target up to date by changing its
   6323 last-modification date.  You would follow this procedure:
   6324 
   6325   1. Use the command `make' to recompile the source files that really
   6326      need recompilation, ensuring that the object files are up-to-date
   6327      before you begin.
   6328 
   6329   2. Make the changes in the header files.
   6330 
   6331   3. Use the command `make -t' to mark all the object files as up to
   6332      date.  The next time you run `make', the changes in the header
   6333      files will not cause any recompilation.
   6334 
   6335    If you have already changed the header file at a time when some files
   6336 do need recompilation, it is too late to do this.  Instead, you can use
   6337 the `-o FILE' flag, which marks a specified file as "old" (*note
   6338 Summary of Options: Options Summary.).  This means that the file itself
   6339 will not be remade, and nothing else will be remade on its account.
   6340 Follow this procedure:
   6341 
   6342   1. Recompile the source files that need compilation for reasons
   6343      independent of the particular header file, with `make -o
   6344      HEADERFILE'.  If several header files are involved, use a separate
   6345      `-o' option for each header file.
   6346 
   6347   2. Touch all the object files with `make -t'.
   6348 
   6349 
   6350 File: make.info,  Node: Overriding,  Next: Testing,  Prev: Avoiding Compilation,  Up: Running
   6351 
   6352 9.5 Overriding Variables
   6353 ========================
   6354 
   6355 An argument that contains `=' specifies the value of a variable: `V=X'
   6356 sets the value of the variable V to X.  If you specify a value in this
   6357 way, all ordinary assignments of the same variable in the makefile are
   6358 ignored; we say they have been "overridden" by the command line
   6359 argument.
   6360 
   6361    The most common way to use this facility is to pass extra flags to
   6362 compilers.  For example, in a properly written makefile, the variable
   6363 `CFLAGS' is included in each command that runs the C compiler, so a
   6364 file `foo.c' would be compiled something like this:
   6365 
   6366      cc -c $(CFLAGS) foo.c
   6367 
   6368    Thus, whatever value you set for `CFLAGS' affects each compilation
   6369 that occurs.  The makefile probably specifies the usual value for
   6370 `CFLAGS', like this:
   6371 
   6372      CFLAGS=-g
   6373 
   6374    Each time you run `make', you can override this value if you wish.
   6375 For example, if you say `make CFLAGS='-g -O'', each C compilation will
   6376 be done with `cc -c -g -O'.  (This also illustrates how you can use
   6377 quoting in the shell to enclose spaces and other special characters in
   6378 the value of a variable when you override it.)
   6379 
   6380    The variable `CFLAGS' is only one of many standard variables that
   6381 exist just so that you can change them this way.  *Note Variables Used
   6382 by Implicit Rules: Implicit Variables, for a complete list.
   6383 
   6384    You can also program the makefile to look at additional variables of
   6385 your own, giving the user the ability to control other aspects of how
   6386 the makefile works by changing the variables.
   6387 
   6388    When you override a variable with a command argument, you can define
   6389 either a recursively-expanded variable or a simply-expanded variable.
   6390 The examples shown above make a recursively-expanded variable; to make a
   6391 simply-expanded variable, write `:=' instead of `='.  But, unless you
   6392 want to include a variable reference or function call in the _value_
   6393 that you specify, it makes no difference which kind of variable you
   6394 create.
   6395 
   6396    There is one way that the makefile can change a variable that you
   6397 have overridden.  This is to use the `override' directive, which is a
   6398 line that looks like this: `override VARIABLE = VALUE' (*note The
   6399 `override' Directive: Override Directive.).
   6400 
   6401 
   6402 File: make.info,  Node: Testing,  Next: Options Summary,  Prev: Overriding,  Up: Running
   6403 
   6404 9.6 Testing the Compilation of a Program
   6405 ========================================
   6406 
   6407 Normally, when an error happens in executing a shell command, `make'
   6408 gives up immediately, returning a nonzero status.  No further commands
   6409 are executed for any target.  The error implies that the goal cannot be
   6410 correctly remade, and `make' reports this as soon as it knows.
   6411 
   6412    When you are compiling a program that you have just changed, this is
   6413 not what you want.  Instead, you would rather that `make' try compiling
   6414 every file that can be tried, to show you as many compilation errors as
   6415 possible.
   6416 
   6417    On these occasions, you should use the `-k' or `--keep-going' flag.
   6418 This tells `make' to continue to consider the other prerequisites of
   6419 the pending targets, remaking them if necessary, before it gives up and
   6420 returns nonzero status.  For example, after an error in compiling one
   6421 object file, `make -k' will continue compiling other object files even
   6422 though it already knows that linking them will be impossible.  In
   6423 addition to continuing after failed shell commands, `make -k' will
   6424 continue as much as possible after discovering that it does not know
   6425 how to make a target or prerequisite file.  This will always cause an
   6426 error message, but without `-k', it is a fatal error (*note Summary of
   6427 Options: Options Summary.).
   6428 
   6429    The usual behavior of `make' assumes that your purpose is to get the
   6430 goals up to date; once `make' learns that this is impossible, it might
   6431 as well report the failure immediately.  The `-k' flag says that the
   6432 real purpose is to test as much as possible of the changes made in the
   6433 program, perhaps to find several independent problems so that you can
   6434 correct them all before the next attempt to compile.  This is why Emacs'
   6435 `M-x compile' command passes the `-k' flag by default.
   6436 
   6437 
   6438 File: make.info,  Node: Options Summary,  Prev: Testing,  Up: Running
   6439 
   6440 9.7 Summary of Options
   6441 ======================
   6442 
   6443 Here is a table of all the options `make' understands:
   6444 
   6445 `-b'
   6446 `-m'
   6447      These options are ignored for compatibility with other versions of
   6448      `make'.
   6449 
   6450 `-B'
   6451 `--always-make'
   6452      Consider all targets out-of-date.  GNU `make' proceeds to consider
   6453      targets and their prerequisites using the normal algorithms;
   6454      however, all targets so considered are always remade regardless of
   6455      the status of their prerequisites.  To avoid infinite recursion, if
   6456      `MAKE_RESTARTS' (*note Other Special Variables: Special
   6457      Variables.) is set to a number greater than 0 this option is
   6458      disabled when considering whether to remake makefiles (*note How
   6459      Makefiles Are Remade: Remaking Makefiles.).
   6460 
   6461 `-C DIR'
   6462 `--directory=DIR'
   6463      Change to directory DIR before reading the makefiles.  If multiple
   6464      `-C' options are specified, each is interpreted relative to the
   6465      previous one: `-C / -C etc' is equivalent to `-C /etc'.  This is
   6466      typically used with recursive invocations of `make' (*note
   6467      Recursive Use of `make': Recursion.).
   6468 
   6469 `-d'
   6470      Print debugging information in addition to normal processing.  The
   6471      debugging information says which files are being considered for
   6472      remaking, which file-times are being compared and with what
   6473      results, which files actually need to be remade, which implicit
   6474      rules are considered and which are applied--everything interesting
   6475      about how `make' decides what to do.  The `-d' option is
   6476      equivalent to `--debug=a' (see below).
   6477 
   6478 `--debug[=OPTIONS]'
   6479      Print debugging information in addition to normal processing.
   6480      Various levels and types of output can be chosen.  With no
   6481      arguments, print the "basic" level of debugging.  Possible
   6482      arguments are below; only the first character is considered, and
   6483      values must be comma- or space-separated.
   6484 
   6485     `a (all)'
   6486           All types of debugging output are enabled.  This is
   6487           equivalent to using `-d'.
   6488 
   6489     `b (basic)'
   6490           Basic debugging prints each target that was found to be
   6491           out-of-date, and whether the build was successful or not.
   6492 
   6493     `v (verbose)'
   6494           A level above `basic'; includes messages about which
   6495           makefiles were parsed, prerequisites that did not need to be
   6496           rebuilt, etc.  This option also enables `basic' messages.
   6497 
   6498     `i (implicit)'
   6499           Prints messages describing the implicit rule searches for
   6500           each target.  This option also enables `basic' messages.
   6501 
   6502     `j (jobs)'
   6503           Prints messages giving details on the invocation of specific
   6504           subcommands.
   6505 
   6506     `m (makefile)'
   6507           By default, the above messages are not enabled while trying
   6508           to remake the makefiles.  This option enables messages while
   6509           rebuilding makefiles, too.  Note that the `all' option does
   6510           enable this option.  This option also enables `basic'
   6511           messages.
   6512 
   6513 `-e'
   6514 `--environment-overrides'
   6515      Give variables taken from the environment precedence over
   6516      variables from makefiles.  *Note Variables from the Environment:
   6517      Environment.
   6518 
   6519 `-f FILE'
   6520 `--file=FILE'
   6521 `--makefile=FILE'
   6522      Read the file named FILE as a makefile.  *Note Writing Makefiles:
   6523      Makefiles.
   6524 
   6525 `-h'
   6526 `--help'
   6527      Remind you of the options that `make' understands and then exit.
   6528 
   6529 `-i'
   6530 `--ignore-errors'
   6531      Ignore all errors in commands executed to remake files.  *Note
   6532      Errors in Commands: Errors.
   6533 
   6534 `-I DIR'
   6535 `--include-dir=DIR'
   6536      Specifies a directory DIR to search for included makefiles.  *Note
   6537      Including Other Makefiles: Include.  If several `-I' options are
   6538      used to specify several directories, the directories are searched
   6539      in the order specified.
   6540 
   6541 `-j [JOBS]'
   6542 `--jobs[=JOBS]'
   6543      Specifies the number of jobs (commands) to run simultaneously.
   6544      With no argument, `make' runs as many jobs simultaneously as
   6545      possible.  If there is more than one `-j' option, the last one is
   6546      effective.  *Note Parallel Execution: Parallel, for more
   6547      information on how commands are run.  Note that this option is
   6548      ignored on MS-DOS.
   6549 
   6550 `-k'
   6551 `--keep-going'
   6552      Continue as much as possible after an error.  While the target that
   6553      failed, and those that depend on it, cannot be remade, the other
   6554      prerequisites of these targets can be processed all the same.
   6555      *Note Testing the Compilation of a Program: Testing.
   6556 
   6557 `-l [LOAD]'
   6558 `--load-average[=LOAD]'
   6559 `--max-load[=LOAD]'
   6560      Specifies that no new jobs (commands) should be started if there
   6561      are other jobs running and the load average is at least LOAD (a
   6562      floating-point number).  With no argument, removes a previous load
   6563      limit.  *Note Parallel Execution: Parallel.
   6564 
   6565 `-L'
   6566 `--check-symlink-times'
   6567      On systems that support symbolic links, this option causes `make'
   6568      to consider the timestamps on any symbolic links in addition to the
   6569      timestamp on the file referenced by those links.  When this option
   6570      is provided, the most recent timestamp among the file and the
   6571      symbolic links is taken as the modification time for this target
   6572      file.
   6573 
   6574 `-n'
   6575 `--just-print'
   6576 `--dry-run'
   6577 `--recon'
   6578      Print the commands that would be executed, but do not execute them.
   6579      *Note Instead of Executing the Commands: Instead of Execution.
   6580 
   6581 `-o FILE'
   6582 `--old-file=FILE'
   6583 `--assume-old=FILE'
   6584      Do not remake the file FILE even if it is older than its
   6585      prerequisites, and do not remake anything on account of changes in
   6586      FILE.  Essentially the file is treated as very old and its rules
   6587      are ignored.  *Note Avoiding Recompilation of Some Files: Avoiding
   6588      Compilation.
   6589 
   6590 `-p'
   6591 `--print-data-base'
   6592      Print the data base (rules and variable values) that results from
   6593      reading the makefiles; then execute as usual or as otherwise
   6594      specified.  This also prints the version information given by the
   6595      `-v' switch (see below).  To print the data base without trying to
   6596      remake any files, use `make -qp'.  To print the data base of
   6597      predefined rules and variables, use `make -p -f /dev/null'.  The
   6598      data base output contains filename and linenumber information for
   6599      command and variable definitions, so it can be a useful debugging
   6600      tool in complex environments.
   6601 
   6602 `-q'
   6603 `--question'
   6604      "Question mode".  Do not run any commands, or print anything; just
   6605      return an exit status that is zero if the specified targets are
   6606      already up to date, one if any remaking is required, or two if an
   6607      error is encountered.  *Note Instead of Executing the Commands:
   6608      Instead of Execution.
   6609 
   6610 `-r'
   6611 `--no-builtin-rules'
   6612      Eliminate use of the built-in implicit rules (*note Using Implicit
   6613      Rules: Implicit Rules.).  You can still define your own by writing
   6614      pattern rules (*note Defining and Redefining Pattern Rules:
   6615      Pattern Rules.).  The `-r' option also clears out the default list
   6616      of suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
   6617      Suffix Rules.).  But you can still define your own suffixes with a
   6618      rule for `.SUFFIXES', and then define your own suffix rules.  Note
   6619      that only _rules_ are affected by the `-r' option; default
   6620      variables remain in effect (*note Variables Used by Implicit
   6621      Rules: Implicit Variables.); see the `-R' option below.
   6622 
   6623 `-R'
   6624 `--no-builtin-variables'
   6625      Eliminate use of the built-in rule-specific variables (*note
   6626      Variables Used by Implicit Rules: Implicit Variables.).  You can
   6627      still define your own, of course.  The `-R' option also
   6628      automatically enables the `-r' option (see above), since it
   6629      doesn't make sense to have implicit rules without any definitions
   6630      for the variables that they use.
   6631 
   6632 `-s'
   6633 `--silent'
   6634 `--quiet'
   6635      Silent operation; do not print the commands as they are executed.
   6636      *Note Command Echoing: Echoing.
   6637 
   6638 `-S'
   6639 `--no-keep-going'
   6640 `--stop'
   6641      Cancel the effect of the `-k' option.  This is never necessary
   6642      except in a recursive `make' where `-k' might be inherited from
   6643      the top-level `make' via `MAKEFLAGS' (*note Recursive Use of
   6644      `make': Recursion.)  or if you set `-k' in `MAKEFLAGS' in your
   6645      environment.
   6646 
   6647 `-t'
   6648 `--touch'
   6649      Touch files (mark them up to date without really changing them)
   6650      instead of running their commands.  This is used to pretend that
   6651      the commands were done, in order to fool future invocations of
   6652      `make'.  *Note Instead of Executing the Commands: Instead of
   6653      Execution.
   6654 
   6655 `-v'
   6656 `--version'
   6657      Print the version of the `make' program plus a copyright, a list
   6658      of authors, and a notice that there is no warranty; then exit.
   6659 
   6660 `-w'
   6661 `--print-directory'
   6662      Print a message containing the working directory both before and
   6663      after executing the makefile.  This may be useful for tracking
   6664      down errors from complicated nests of recursive `make' commands.
   6665      *Note Recursive Use of `make': Recursion.  (In practice, you
   6666      rarely need to specify this option since `make' does it for you;
   6667      see *note The `--print-directory' Option: -w Option.)
   6668 
   6669 `--no-print-directory'
   6670      Disable printing of the working directory under `-w'.  This option
   6671      is useful when `-w' is turned on automatically, but you do not
   6672      want to see the extra messages.  *Note The `--print-directory'
   6673      Option: -w Option.
   6674 
   6675 `-W FILE'
   6676 `--what-if=FILE'
   6677 `--new-file=FILE'
   6678 `--assume-new=FILE'
   6679      Pretend that the target FILE has just been modified.  When used
   6680      with the `-n' flag, this shows you what would happen if you were
   6681      to modify that file.  Without `-n', it is almost the same as
   6682      running a `touch' command on the given file before running `make',
   6683      except that the modification time is changed only in the
   6684      imagination of `make'.  *Note Instead of Executing the Commands:
   6685      Instead of Execution.
   6686 
   6687 `--warn-undefined-variables'
   6688      Issue a warning message whenever `make' sees a reference to an
   6689      undefined variable.  This can be helpful when you are trying to
   6690      debug makefiles which use variables in complex ways.
   6691 
   6692 
   6693 File: make.info,  Node: Implicit Rules,  Next: Archives,  Prev: Running,  Up: Top
   6694 
   6695 10 Using Implicit Rules
   6696 ***********************
   6697 
   6698 Certain standard ways of remaking target files are used very often.  For
   6699 example, one customary way to make an object file is from a C source
   6700 file using the C compiler, `cc'.
   6701 
   6702    "Implicit rules" tell `make' how to use customary techniques so that
   6703 you do not have to specify them in detail when you want to use them.
   6704 For example, there is an implicit rule for C compilation.  File names
   6705 determine which implicit rules are run.  For example, C compilation
   6706 typically takes a `.c' file and makes a `.o' file.  So `make' applies
   6707 the implicit rule for C compilation when it sees this combination of
   6708 file name endings.
   6709 
   6710    A chain of implicit rules can apply in sequence; for example, `make'
   6711 will remake a `.o' file from a `.y' file by way of a `.c' file.
   6712 
   6713    The built-in implicit rules use several variables in their commands
   6714 so that, by changing the values of the variables, you can change the
   6715 way the implicit rule works.  For example, the variable `CFLAGS'
   6716 controls the flags given to the C compiler by the implicit rule for C
   6717 compilation.
   6718 
   6719    You can define your own implicit rules by writing "pattern rules".
   6720 
   6721    "Suffix rules" are a more limited way to define implicit rules.
   6722 Pattern rules are more general and clearer, but suffix rules are
   6723 retained for compatibility.
   6724 
   6725 * Menu:
   6726 
   6727 * Using Implicit::              How to use an existing implicit rule
   6728                                   to get the commands for updating a file.
   6729 * Catalogue of Rules::          A list of built-in implicit rules.
   6730 * Implicit Variables::          How to change what predefined rules do.
   6731 * Chained Rules::               How to use a chain of implicit rules.
   6732 * Pattern Rules::               How to define new implicit rules.
   6733 * Last Resort::                 How to define commands for rules which
   6734                                   cannot find any.
   6735 * Suffix Rules::                The old-fashioned style of implicit rule.
   6736 * Implicit Rule Search::        The precise algorithm for applying
   6737                                   implicit rules.
   6738 
   6739 
   6740 File: make.info,  Node: Using Implicit,  Next: Catalogue of Rules,  Prev: Implicit Rules,  Up: Implicit Rules
   6741 
   6742 10.1 Using Implicit Rules
   6743 =========================
   6744 
   6745 To allow `make' to find a customary method for updating a target file,
   6746 all you have to do is refrain from specifying commands yourself.  Either
   6747 write a rule with no command lines, or don't write a rule at all.  Then
   6748 `make' will figure out which implicit rule to use based on which kind
   6749 of source file exists or can be made.
   6750 
   6751    For example, suppose the makefile looks like this:
   6752 
   6753      foo : foo.o bar.o
   6754              cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
   6755 
   6756 Because you mention `foo.o' but do not give a rule for it, `make' will
   6757 automatically look for an implicit rule that tells how to update it.
   6758 This happens whether or not the file `foo.o' currently exists.
   6759 
   6760    If an implicit rule is found, it can supply both commands and one or
   6761 more prerequisites (the source files).  You would want to write a rule
   6762 for `foo.o' with no command lines if you need to specify additional
   6763 prerequisites, such as header files, that the implicit rule cannot
   6764 supply.
   6765 
   6766    Each implicit rule has a target pattern and prerequisite patterns.
   6767 There may be many implicit rules with the same target pattern.  For
   6768 example, numerous rules make `.o' files: one, from a `.c' file with the
   6769 C compiler; another, from a `.p' file with the Pascal compiler; and so
   6770 on.  The rule that actually applies is the one whose prerequisites
   6771 exist or can be made.  So, if you have a file `foo.c', `make' will run
   6772 the C compiler; otherwise, if you have a file `foo.p', `make' will run
   6773 the Pascal compiler; and so on.
   6774 
   6775    Of course, when you write the makefile, you know which implicit rule
   6776 you want `make' to use, and you know it will choose that one because you
   6777 know which possible prerequisite files are supposed to exist.  *Note
   6778 Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all
   6779 the predefined implicit rules.
   6780 
   6781    Above, we said an implicit rule applies if the required
   6782 prerequisites "exist or can be made".  A file "can be made" if it is
   6783 mentioned explicitly in the makefile as a target or a prerequisite, or
   6784 if an implicit rule can be recursively found for how to make it.  When
   6785 an implicit prerequisite is the result of another implicit rule, we say
   6786 that "chaining" is occurring.  *Note Chains of Implicit Rules: Chained
   6787 Rules.
   6788 
   6789    In general, `make' searches for an implicit rule for each target, and
   6790 for each double-colon rule, that has no commands.  A file that is
   6791 mentioned only as a prerequisite is considered a target whose rule
   6792 specifies nothing, so implicit rule search happens for it.  *Note
   6793 Implicit Rule Search Algorithm: Implicit Rule Search, for the details
   6794 of how the search is done.
   6795 
   6796    Note that explicit prerequisites do not influence implicit rule
   6797 search.  For example, consider this explicit rule:
   6798 
   6799      foo.o: foo.p
   6800 
   6801 The prerequisite on `foo.p' does not necessarily mean that `make' will
   6802 remake `foo.o' according to the implicit rule to make an object file, a
   6803 `.o' file, from a Pascal source file, a `.p' file.  For example, if
   6804 `foo.c' also exists, the implicit rule to make an object file from a C
   6805 source file is used instead, because it appears before the Pascal rule
   6806 in the list of predefined implicit rules (*note Catalogue of Implicit
   6807 Rules: Catalogue of Rules.).
   6808 
   6809    If you do not want an implicit rule to be used for a target that has
   6810 no commands, you can give that target empty commands by writing a
   6811 semicolon (*note Defining Empty Commands: Empty Commands.).
   6812 
   6813 
   6814 File: make.info,  Node: Catalogue of Rules,  Next: Implicit Variables,  Prev: Using Implicit,  Up: Implicit Rules
   6815 
   6816 10.2 Catalogue of Implicit Rules
   6817 ================================
   6818 
   6819 Here is a catalogue of predefined implicit rules which are always
   6820 available unless the makefile explicitly overrides or cancels them.
   6821 *Note Canceling Implicit Rules: Canceling Rules, for information on
   6822 canceling or overriding an implicit rule.  The `-r' or
   6823 `--no-builtin-rules' option cancels all predefined rules.
   6824 
   6825    This manual only documents the default rules available on POSIX-based
   6826 operating systems.  Other operating systems, such as VMS, Windows,
   6827 OS/2, etc. may have different sets of default rules.  To see the full
   6828 list of default rules and variables available in your version of GNU
   6829 `make', run `make -p' in a directory with no makefile.
   6830 
   6831    Not all of these rules will always be defined, even when the `-r'
   6832 option is not given.  Many of the predefined implicit rules are
   6833 implemented in `make' as suffix rules, so which ones will be defined
   6834 depends on the "suffix list" (the list of prerequisites of the special
   6835 target `.SUFFIXES').  The default suffix list is: `.out', `.a', `.ln',
   6836 `.o', `.c', `.cc', `.C', `.cpp', `.p', `.f', `.F', `.r', `.y', `.l',
   6837 `.s', `.S', `.mod', `.sym', `.def', `.h', `.info', `.dvi', `.tex',
   6838 `.texinfo', `.texi', `.txinfo', `.w', `.ch' `.web', `.sh', `.elc',
   6839 `.el'.  All of the implicit rules described below whose prerequisites
   6840 have one of these suffixes are actually suffix rules.  If you modify
   6841 the suffix list, the only predefined suffix rules in effect will be
   6842 those named by one or two of the suffixes that are on the list you
   6843 specify; rules whose suffixes fail to be on the list are disabled.
   6844 *Note Old-Fashioned Suffix Rules: Suffix Rules, for full details on
   6845 suffix rules.
   6846 
   6847 Compiling C programs
   6848      `N.o' is made automatically from `N.c' with a command of the form
   6849      `$(CC) -c $(CPPFLAGS) $(CFLAGS)'.
   6850 
   6851 Compiling C++ programs
   6852      `N.o' is made automatically from `N.cc', `N.cpp', or `N.C' with a
   6853      command of the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'.  We
   6854      encourage you to use the suffix `.cc' for C++ source files instead
   6855      of `.C'.
   6856 
   6857 Compiling Pascal programs
   6858      `N.o' is made automatically from `N.p' with the command `$(PC) -c
   6859      $(PFLAGS)'.
   6860 
   6861 Compiling Fortran and Ratfor programs
   6862      `N.o' is made automatically from `N.r', `N.F' or `N.f' by running
   6863      the Fortran compiler.  The precise command used is as follows:
   6864 
   6865     `.f'
   6866           `$(FC) -c $(FFLAGS)'.
   6867 
   6868     `.F'
   6869           `$(FC) -c $(FFLAGS) $(CPPFLAGS)'.
   6870 
   6871     `.r'
   6872           `$(FC) -c $(FFLAGS) $(RFLAGS)'.
   6873 
   6874 Preprocessing Fortran and Ratfor programs
   6875      `N.f' is made automatically from `N.r' or `N.F'.  This rule runs
   6876      just the preprocessor to convert a Ratfor or preprocessable
   6877      Fortran program into a strict Fortran program.  The precise
   6878      command used is as follows:
   6879 
   6880     `.F'
   6881           `$(FC) -F $(CPPFLAGS) $(FFLAGS)'.
   6882 
   6883     `.r'
   6884           `$(FC) -F $(FFLAGS) $(RFLAGS)'.
   6885 
   6886 Compiling Modula-2 programs
   6887      `N.sym' is made from `N.def' with a command of the form `$(M2C)
   6888      $(M2FLAGS) $(DEFFLAGS)'.  `N.o' is made from `N.mod'; the form is:
   6889      `$(M2C) $(M2FLAGS) $(MODFLAGS)'.
   6890 
   6891 Assembling and preprocessing assembler programs
   6892      `N.o' is made automatically from `N.s' by running the assembler,
   6893      `as'.  The precise command is `$(AS) $(ASFLAGS)'.
   6894 
   6895      `N.s' is made automatically from `N.S' by running the C
   6896      preprocessor, `cpp'.  The precise command is `$(CPP) $(CPPFLAGS)'.
   6897 
   6898 Linking a single object file
   6899      `N' is made automatically from `N.o' by running the linker
   6900      (usually called `ld') via the C compiler.  The precise command
   6901      used is `$(CC) $(LDFLAGS) N.o $(LOADLIBES) $(LDLIBS)'.
   6902 
   6903      This rule does the right thing for a simple program with only one
   6904      source file.  It will also do the right thing if there are multiple
   6905      object files (presumably coming from various other source files),
   6906      one of which has a name matching that of the executable file.
   6907      Thus,
   6908 
   6909           x: y.o z.o
   6910 
   6911      when `x.c', `y.c' and `z.c' all exist will execute:
   6912 
   6913           cc -c x.c -o x.o
   6914           cc -c y.c -o y.o
   6915           cc -c z.c -o z.o
   6916           cc x.o y.o z.o -o x
   6917           rm -f x.o
   6918           rm -f y.o
   6919           rm -f z.o
   6920 
   6921      In more complicated cases, such as when there is no object file
   6922      whose name derives from the executable file name, you must write
   6923      an explicit command for linking.
   6924 
   6925      Each kind of file automatically made into `.o' object files will
   6926      be automatically linked by using the compiler (`$(CC)', `$(FC)' or
   6927      `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files)
   6928      without the `-c' option.  This could be done by using the `.o'
   6929      object files as intermediates, but it is faster to do the
   6930      compiling and linking in one step, so that's how it's done.
   6931 
   6932 Yacc for C programs
   6933      `N.c' is made automatically from `N.y' by running Yacc with the
   6934      command `$(YACC) $(YFLAGS)'.
   6935 
   6936 Lex for C programs
   6937      `N.c' is made automatically from `N.l' by running Lex.  The actual
   6938      command is `$(LEX) $(LFLAGS)'.
   6939 
   6940 Lex for Ratfor programs
   6941      `N.r' is made automatically from `N.l' by running Lex.  The actual
   6942      command is `$(LEX) $(LFLAGS)'.
   6943 
   6944      The convention of using the same suffix `.l' for all Lex files
   6945      regardless of whether they produce C code or Ratfor code makes it
   6946      impossible for `make' to determine automatically which of the two
   6947      languages you are using in any particular case.  If `make' is
   6948      called upon to remake an object file from a `.l' file, it must
   6949      guess which compiler to use.  It will guess the C compiler, because
   6950      that is more common.  If you are using Ratfor, make sure `make'
   6951      knows this by mentioning `N.r' in the makefile.  Or, if you are
   6952      using Ratfor exclusively, with no C files, remove `.c' from the
   6953      list of implicit rule suffixes with:
   6954 
   6955           .SUFFIXES:
   6956           .SUFFIXES: .o .r .f .l ...
   6957 
   6958 Making Lint Libraries from C, Yacc, or Lex programs
   6959      `N.ln' is made from `N.c' by running `lint'.  The precise command
   6960      is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'.  The same command is
   6961      used on the C code produced from `N.y' or `N.l'.
   6962 
   6963 TeX and Web
   6964      `N.dvi' is made from `N.tex' with the command `$(TEX)'.  `N.tex'
   6965      is made from `N.web' with `$(WEAVE)', or from `N.w' (and from
   6966      `N.ch' if it exists or can be made) with `$(CWEAVE)'.  `N.p' is
   6967      made from `N.web' with `$(TANGLE)' and `N.c' is made from `N.w'
   6968      (and from `N.ch' if it exists or can be made) with `$(CTANGLE)'.
   6969 
   6970 Texinfo and Info
   6971      `N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with
   6972      the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'.  `N.info' is made from
   6973      `N.texinfo', `N.texi', or `N.txinfo', with the command
   6974      `$(MAKEINFO) $(MAKEINFO_FLAGS)'.
   6975 
   6976 RCS
   6977      Any file `N' is extracted if necessary from an RCS file named
   6978      either `N,v' or `RCS/N,v'.  The precise command used is
   6979      `$(CO) $(COFLAGS)'.  `N' will not be extracted from RCS if it
   6980      already exists, even if the RCS file is newer.  The rules for RCS
   6981      are terminal (*note Match-Anything Pattern Rules: Match-Anything
   6982      Rules.), so RCS files cannot be generated from another source;
   6983      they must actually exist.
   6984 
   6985 SCCS
   6986      Any file `N' is extracted if necessary from an SCCS file named
   6987      either `s.N' or `SCCS/s.N'.  The precise command used is
   6988      `$(GET) $(GFLAGS)'.  The rules for SCCS are terminal (*note
   6989      Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS
   6990      files cannot be generated from another source; they must actually
   6991      exist.
   6992 
   6993      For the benefit of SCCS, a file `N' is copied from `N.sh' and made
   6994      executable (by everyone).  This is for shell scripts that are
   6995      checked into SCCS.  Since RCS preserves the execution permission
   6996      of a file, you do not need to use this feature with RCS.
   6997 
   6998      We recommend that you avoid using of SCCS.  RCS is widely held to
   6999      be superior, and is also free.  By choosing free software in place
   7000      of comparable (or inferior) proprietary software, you support the
   7001      free software movement.
   7002 
   7003    Usually, you want to change only the variables listed in the table
   7004 above, which are documented in the following section.
   7005 
   7006    However, the commands in built-in implicit rules actually use
   7007 variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose
   7008 values contain the commands listed above.
   7009 
   7010    `make' follows the convention that the rule to compile a `.X' source
   7011 file uses the variable `COMPILE.X'.  Similarly, the rule to produce an
   7012 executable from a `.X' file uses `LINK.X'; and the rule to preprocess a
   7013 `.X' file uses `PREPROCESS.X'.
   7014 
   7015    Every rule that produces an object file uses the variable
   7016 `OUTPUT_OPTION'.  `make' defines this variable either to contain `-o
   7017 $@', or to be empty, depending on a compile-time option.  You need the
   7018 `-o' option to ensure that the output goes into the right file when the
   7019 source file is in a different directory, as when using `VPATH' (*note
   7020 Directory Search::).  However, compilers on some systems do not accept
   7021 a `-o' switch for object files.  If you use such a system, and use
   7022 `VPATH', some compilations will put their output in the wrong place.  A
   7023 possible workaround for this problem is to give `OUTPUT_OPTION' the
   7024 value `; mv $*.o $@'.
   7025 
   7026 
   7027 File: make.info,  Node: Implicit Variables,  Next: Chained Rules,  Prev: Catalogue of Rules,  Up: Implicit Rules
   7028 
   7029 10.3 Variables Used by Implicit Rules
   7030 =====================================
   7031 
   7032 The commands in built-in implicit rules make liberal use of certain
   7033 predefined variables.  You can alter the values of these variables in
   7034 the makefile, with arguments to `make', or in the environment to alter
   7035 how the implicit rules work without redefining the rules themselves.
   7036 You can cancel all variables used by implicit rules with the `-R' or
   7037 `--no-builtin-variables' option.
   7038 
   7039    For example, the command used to compile a C source file actually
   7040 says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'.  The default values of the
   7041 variables used are `cc' and nothing, resulting in the command `cc -c'.
   7042 By redefining `CC' to `ncc', you could cause `ncc' to be used for all C
   7043 compilations performed by the implicit rule.  By redefining `CFLAGS' to
   7044 be `-g', you could pass the `-g' option to each compilation.  _All_
   7045 implicit rules that do C compilation use `$(CC)' to get the program
   7046 name for the compiler and _all_ include `$(CFLAGS)' among the arguments
   7047 given to the compiler.
   7048 
   7049    The variables used in implicit rules fall into two classes: those
   7050 that are names of programs (like `CC') and those that contain arguments
   7051 for the programs (like `CFLAGS').  (The "name of a program" may also
   7052 contain some command arguments, but it must start with an actual
   7053 executable program name.)  If a variable value contains more than one
   7054 argument, separate them with spaces.
   7055 
   7056    The following tables describe of some of the more commonly-used
   7057 predefined variables.  This list is not exhaustive, and the default
   7058 values shown here may not be what are selected by `make' for your
   7059 environment.  To see the complete list of predefined variables for your
   7060 instance of GNU `make' you can run `make -p' in a directory with no
   7061 makefiles.
   7062 
   7063    Here is a table of some of the more common variables used as names of
   7064 programs in built-in rules: makefiles.
   7065 
   7066 `AR'
   7067      Archive-maintaining program; default `ar'.  
   7068 
   7069 `AS'
   7070      Program for compiling assembly files; default `as'.  
   7071 
   7072 `CC'
   7073      Program for compiling C programs; default `cc'.  
   7074 
   7075 `CO'
   7076      Program for checking out files from RCS; default `co'.  
   7077 
   7078 `CXX'
   7079      Program for compiling C++ programs; default `g++'.  
   7080 
   7081 `CO'
   7082      Program for extracting a file from RCS; default `co'.  
   7083 
   7084 `CPP'
   7085      Program for running the C preprocessor, with results to standard
   7086      output; default `$(CC) -E'.
   7087 
   7088 `FC'
   7089      Program for compiling or preprocessing Fortran and Ratfor programs;
   7090      default `f77'.  
   7091 
   7092 `GET'
   7093      Program for extracting a file from SCCS; default `get'.  
   7094 
   7095 `LEX'
   7096      Program to use to turn Lex grammars into source code; default
   7097      `lex'.  
   7098 
   7099 `YACC'
   7100      Program to use to turn Yacc grammars into source code; default
   7101      `yacc'.  
   7102 
   7103 `LINT'
   7104      Program to use to run lint on source code; default `lint'.  
   7105 
   7106 `M2C'
   7107      Program to use to compile Modula-2 source code; default `m2c'.  
   7108 
   7109 `PC'
   7110      Program for compiling Pascal programs; default `pc'.  
   7111 
   7112 `MAKEINFO'
   7113      Program to convert a Texinfo source file into an Info file; default
   7114      `makeinfo'.  
   7115 
   7116 `TEX'
   7117      Program to make TeX DVI files from TeX source; default `tex'.  
   7118 
   7119 `TEXI2DVI'
   7120      Program to make TeX DVI files from Texinfo source; default
   7121      `texi2dvi'.  
   7122 
   7123 `WEAVE'
   7124      Program to translate Web into TeX; default `weave'.  
   7125 
   7126 `CWEAVE'
   7127      Program to translate C Web into TeX; default `cweave'.  
   7128 
   7129 `TANGLE'
   7130      Program to translate Web into Pascal; default `tangle'.  
   7131 
   7132 `CTANGLE'
   7133      Program to translate C Web into C; default `ctangle'.  
   7134 
   7135 `RM'
   7136      Command to remove a file; default `rm -f'.  
   7137 
   7138    Here is a table of variables whose values are additional arguments
   7139 for the programs above.  The default values for all of these is the
   7140 empty string, unless otherwise noted.
   7141 
   7142 `ARFLAGS'
   7143      Flags to give the archive-maintaining program; default `rv'.
   7144 
   7145 `ASFLAGS'
   7146      Extra flags to give to the assembler (when explicitly invoked on a
   7147      `.s' or `.S' file).
   7148 
   7149 `CFLAGS'
   7150      Extra flags to give to the C compiler.
   7151 
   7152 `CXXFLAGS'
   7153      Extra flags to give to the C++ compiler.
   7154 
   7155 `COFLAGS'
   7156      Extra flags to give to the RCS `co' program.
   7157 
   7158 `CPPFLAGS'
   7159      Extra flags to give to the C preprocessor and programs that use it
   7160      (the C and Fortran compilers).
   7161 
   7162 `FFLAGS'
   7163      Extra flags to give to the Fortran compiler.
   7164 
   7165 `GFLAGS'
   7166      Extra flags to give to the SCCS `get' program.
   7167 
   7168 `LDFLAGS'
   7169      Extra flags to give to compilers when they are supposed to invoke
   7170      the linker, `ld'.
   7171 
   7172 `LFLAGS'
   7173      Extra flags to give to Lex.
   7174 
   7175 `YFLAGS'
   7176      Extra flags to give to Yacc.
   7177 
   7178 `PFLAGS'
   7179      Extra flags to give to the Pascal compiler.
   7180 
   7181 `RFLAGS'
   7182      Extra flags to give to the Fortran compiler for Ratfor programs.
   7183 
   7184 `LINTFLAGS'
   7185      Extra flags to give to lint.
   7186 
   7187 
   7188 File: make.info,  Node: Chained Rules,  Next: Pattern Rules,  Prev: Implicit Variables,  Up: Implicit Rules
   7189 
   7190 10.4 Chains of Implicit Rules
   7191 =============================
   7192 
   7193 Sometimes a file can be made by a sequence of implicit rules.  For
   7194 example, a file `N.o' could be made from `N.y' by running first Yacc
   7195 and then `cc'.  Such a sequence is called a "chain".
   7196 
   7197    If the file `N.c' exists, or is mentioned in the makefile, no
   7198 special searching is required: `make' finds that the object file can be
   7199 made by C compilation from `N.c'; later on, when considering how to
   7200 make `N.c', the rule for running Yacc is used.  Ultimately both `N.c'
   7201 and `N.o' are updated.
   7202 
   7203    However, even if `N.c' does not exist and is not mentioned, `make'
   7204 knows how to envision it as the missing link between `N.o' and `N.y'!
   7205 In this case, `N.c' is called an "intermediate file".  Once `make' has
   7206 decided to use the intermediate file, it is entered in the data base as
   7207 if it had been mentioned in the makefile, along with the implicit rule
   7208 that says how to create it.
   7209 
   7210    Intermediate files are remade using their rules just like all other
   7211 files.  But intermediate files are treated differently in two ways.
   7212 
   7213    The first difference is what happens if the intermediate file does
   7214 not exist.  If an ordinary file B does not exist, and `make' considers
   7215 a target that depends on B, it invariably creates B and then updates
   7216 the target from B.  But if B is an intermediate file, then `make' can
   7217 leave well enough alone.  It won't bother updating B, or the ultimate
   7218 target, unless some prerequisite of B is newer than that target or
   7219 there is some other reason to update that target.
   7220 
   7221    The second difference is that if `make' _does_ create B in order to
   7222 update something else, it deletes B later on after it is no longer
   7223 needed.  Therefore, an intermediate file which did not exist before
   7224 `make' also does not exist after `make'.  `make' reports the deletion
   7225 to you by printing a `rm -f' command showing which file it is deleting.
   7226 
   7227    Ordinarily, a file cannot be intermediate if it is mentioned in the
   7228 makefile as a target or prerequisite.  However, you can explicitly mark
   7229 a file as intermediate by listing it as a prerequisite of the special
   7230 target `.INTERMEDIATE'.  This takes effect even if the file is mentioned
   7231 explicitly in some other way.
   7232 
   7233    You can prevent automatic deletion of an intermediate file by
   7234 marking it as a "secondary" file.  To do this, list it as a
   7235 prerequisite of the special target `.SECONDARY'.  When a file is
   7236 secondary, `make' will not create the file merely because it does not
   7237 already exist, but `make' does not automatically delete the file.
   7238 Marking a file as secondary also marks it as intermediate.
   7239 
   7240    You can list the target pattern of an implicit rule (such as `%.o')
   7241 as a prerequisite of the special target `.PRECIOUS' to preserve
   7242 intermediate files made by implicit rules whose target patterns match
   7243 that file's name; see *note Interrupts::.  
   7244 
   7245    A chain can involve more than two implicit rules.  For example, it is
   7246 possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc
   7247 and `cc'.  Then both `foo.y' and `foo.c' are intermediate files that
   7248 are deleted at the end.
   7249 
   7250    No single implicit rule can appear more than once in a chain.  This
   7251 means that `make' will not even consider such a ridiculous thing as
   7252 making `foo' from `foo.o.o' by running the linker twice.  This
   7253 constraint has the added benefit of preventing any infinite loop in the
   7254 search for an implicit rule chain.
   7255 
   7256    There are some special implicit rules to optimize certain cases that
   7257 would otherwise be handled by rule chains.  For example, making `foo'
   7258 from `foo.c' could be handled by compiling and linking with separate
   7259 chained rules, using `foo.o' as an intermediate file.  But what
   7260 actually happens is that a special rule for this case does the
   7261 compilation and linking with a single `cc' command.  The optimized rule
   7262 is used in preference to the step-by-step chain because it comes
   7263 earlier in the ordering of rules.
   7264 
   7265