| 1 | This is make.info, produced by makeinfo version 4.8 from make.texi.
|
|---|
| 2 |
|
|---|
| 3 | This file documents the GNU `make' utility, which determines
|
|---|
| 4 | automatically which pieces of a large program need to be recompiled,
|
|---|
| 5 | and issues the commands to recompile them.
|
|---|
| 6 |
|
|---|
| 7 | This is Edition 0.70, last updated 1 April 2006, of `The GNU Make
|
|---|
| 8 | Manual', for GNU `make' version 3.81.
|
|---|
| 9 |
|
|---|
| 10 | Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
|---|
| 11 | 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
|
|---|
| 12 | Foundation, Inc.
|
|---|
| 13 |
|
|---|
| 14 | Permission is granted to copy, distribute and/or modify this
|
|---|
| 15 | document under the terms of the GNU Free Documentation License,
|
|---|
| 16 | Version 1.2 or any later version published by the Free Software
|
|---|
| 17 | Foundation; with no Invariant Sections, with the Front-Cover Texts
|
|---|
| 18 | being "A GNU Manual," and with the Back-Cover Texts as in (a)
|
|---|
| 19 | below. A copy of the license is included in the section entitled
|
|---|
| 20 | "GNU Free Documentation License."
|
|---|
| 21 |
|
|---|
| 22 | (a) The FSF's Back-Cover Text is: "You have freedom to copy and
|
|---|
| 23 | modify this GNU Manual, like GNU software. Copies published by
|
|---|
| 24 | the Free Software Foundation raise funds for GNU development."
|
|---|
| 25 |
|
|---|
| 26 | INFO-DIR-SECTION GNU Packages
|
|---|
| 27 | START-INFO-DIR-ENTRY
|
|---|
| 28 | * Make: (make). Remake files automatically.
|
|---|
| 29 | END-INFO-DIR-ENTRY
|
|---|
| 30 |
|
|---|
| 31 |
|
|---|
| 32 | File: make.info, Node: Top, Next: Overview, Prev: (dir), Up: (dir)
|
|---|
| 33 |
|
|---|
| 34 | GNU `make'
|
|---|
| 35 | **********
|
|---|
| 36 |
|
|---|
| 37 | This file documents the GNU `make' utility, which determines
|
|---|
| 38 | automatically which pieces of a large program need to be recompiled,
|
|---|
| 39 | and issues the commands to recompile them.
|
|---|
| 40 |
|
|---|
| 41 | This is Edition 0.70, last updated 1 April 2006, of `The GNU Make
|
|---|
| 42 | Manual', for GNU `make' version 3.81.
|
|---|
| 43 |
|
|---|
| 44 | Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
|
|---|
| 45 | 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006 Free Software
|
|---|
| 46 | Foundation, Inc.
|
|---|
| 47 |
|
|---|
| 48 | Permission is granted to copy, distribute and/or modify this
|
|---|
| 49 | document under the terms of the GNU Free Documentation License,
|
|---|
| 50 | Version 1.2 or any later version published by the Free Software
|
|---|
| 51 | Foundation; with no Invariant Sections, with the Front-Cover Texts
|
|---|
| 52 | being "A GNU Manual," and with the Back-Cover Texts as in (a)
|
|---|
| 53 | below. A copy of the license is included in the section entitled
|
|---|
| 54 | "GNU Free Documentation License."
|
|---|
| 55 |
|
|---|
| 56 | (a) The FSF's Back-Cover Text is: "You have freedom to copy and
|
|---|
| 57 | modify this GNU Manual, like GNU software. Copies published by
|
|---|
| 58 | the Free Software Foundation raise funds for GNU development."
|
|---|
| 59 |
|
|---|
| 60 | * Menu:
|
|---|
| 61 |
|
|---|
| 62 | * Overview:: Overview of `make'.
|
|---|
| 63 | * Introduction:: An introduction to `make'.
|
|---|
| 64 | * Makefiles:: Makefiles tell `make' what to do.
|
|---|
| 65 | * Rules:: Rules describe when a file must be remade.
|
|---|
| 66 | * Commands:: Commands say how to remake a file.
|
|---|
| 67 | * Using Variables:: You can use variables to avoid repetition.
|
|---|
| 68 | * Conditionals:: Use or ignore parts of the makefile based
|
|---|
| 69 | on the values of variables.
|
|---|
| 70 | * Functions:: Many powerful ways to manipulate text.
|
|---|
| 71 | * Invoking make: Running. How to invoke `make' on the command line.
|
|---|
| 72 | * Implicit Rules:: Use implicit rules to treat many files alike,
|
|---|
| 73 | based on their file names.
|
|---|
| 74 | * Archives:: How `make' can update library archives.
|
|---|
| 75 | * Features:: Features GNU `make' has over other `make's.
|
|---|
| 76 | * Missing:: What GNU `make' lacks from other `make's.
|
|---|
| 77 | * Makefile Conventions:: Conventions for writing makefiles for
|
|---|
| 78 | GNU programs.
|
|---|
| 79 | * Quick Reference:: A quick reference for experienced users.
|
|---|
| 80 | * Error Messages:: A list of common errors generated by `make'.
|
|---|
| 81 | * Complex Makefile:: A real example of a straightforward,
|
|---|
| 82 | but nontrivial, makefile.
|
|---|
| 83 |
|
|---|
| 84 | * GNU Free Documentation License:: License for copying this manual
|
|---|
| 85 | * Concept Index:: Index of Concepts
|
|---|
| 86 | * Name Index:: Index of Functions, Variables, & Directives
|
|---|
| 87 |
|
|---|
| 88 | --- The Detailed Node Listing ---
|
|---|
| 89 |
|
|---|
| 90 | Overview of `make'
|
|---|
| 91 |
|
|---|
| 92 | * Preparing:: Preparing and Running Make
|
|---|
| 93 | * Reading:: On Reading this Text
|
|---|
| 94 | * Bugs:: Problems and Bugs
|
|---|
| 95 |
|
|---|
| 96 | An Introduction to Makefiles
|
|---|
| 97 |
|
|---|
| 98 | * Rule Introduction:: What a rule looks like.
|
|---|
| 99 | * Simple Makefile:: A Simple Makefile
|
|---|
| 100 | * How Make Works:: How `make' Processes This Makefile
|
|---|
| 101 | * Variables Simplify:: Variables Make Makefiles Simpler
|
|---|
| 102 | * make Deduces:: Letting `make' Deduce the Commands
|
|---|
| 103 | * Combine By Prerequisite:: Another Style of Makefile
|
|---|
| 104 | * Cleanup:: Rules for Cleaning the Directory
|
|---|
| 105 |
|
|---|
| 106 | Writing Makefiles
|
|---|
| 107 |
|
|---|
| 108 | * Makefile Contents:: What makefiles contain.
|
|---|
| 109 | * Makefile Names:: How to name your makefile.
|
|---|
| 110 | * Include:: How one makefile can use another makefile.
|
|---|
| 111 | * MAKEFILES Variable:: The environment can specify extra makefiles.
|
|---|
| 112 | * MAKEFILE_LIST Variable:: Discover which makefiles have been read.
|
|---|
| 113 | * Special Variables:: Other special variables.
|
|---|
| 114 | * Remaking Makefiles:: How makefiles get remade.
|
|---|
| 115 | * Overriding Makefiles:: How to override part of one makefile
|
|---|
| 116 | with another makefile.
|
|---|
| 117 | * Reading Makefiles:: How makefiles are parsed.
|
|---|
| 118 | * Secondary Expansion:: How and when secondary expansion is performed.
|
|---|
| 119 |
|
|---|
| 120 | Writing Rules
|
|---|
| 121 |
|
|---|
| 122 | * Rule Example:: An example explained.
|
|---|
| 123 | * Rule Syntax:: General syntax explained.
|
|---|
| 124 | * Prerequisite Types:: There are two types of prerequisites.
|
|---|
| 125 | * Wildcards:: Using wildcard characters such as `*'.
|
|---|
| 126 | * Directory Search:: Searching other directories for source files.
|
|---|
| 127 | * Phony Targets:: Using a target that is not a real file's name.
|
|---|
| 128 | * Force Targets:: You can use a target without commands
|
|---|
| 129 | or prerequisites to mark other targets
|
|---|
| 130 | as phony.
|
|---|
| 131 | * Empty Targets:: When only the date matters and the
|
|---|
| 132 | files are empty.
|
|---|
| 133 | * Special Targets:: Targets with special built-in meanings.
|
|---|
| 134 | * Multiple Targets:: When to make use of several targets in a rule.
|
|---|
| 135 | * Multiple Rules:: How to use several rules with the same target.
|
|---|
| 136 | * Static Pattern:: Static pattern rules apply to multiple targets
|
|---|
| 137 | and can vary the prerequisites according to
|
|---|
| 138 | the target name.
|
|---|
| 139 | * Double-Colon:: How to use a special kind of rule to allow
|
|---|
| 140 | several independent rules for one target.
|
|---|
| 141 | * Automatic Prerequisites:: How to automatically generate rules giving
|
|---|
| 142 | prerequisites from source files themselves.
|
|---|
| 143 |
|
|---|
| 144 | Using Wildcard Characters in File Names
|
|---|
| 145 |
|
|---|
| 146 | * Wildcard Examples:: Several examples
|
|---|
| 147 | * Wildcard Pitfall:: Problems to avoid.
|
|---|
| 148 | * Wildcard Function:: How to cause wildcard expansion where
|
|---|
| 149 | it does not normally take place.
|
|---|
| 150 |
|
|---|
| 151 | Searching Directories for Prerequisites
|
|---|
| 152 |
|
|---|
| 153 | * General Search:: Specifying a search path that applies
|
|---|
| 154 | to every prerequisite.
|
|---|
| 155 | * Selective Search:: Specifying a search path
|
|---|
| 156 | for a specified class of names.
|
|---|
| 157 | * Search Algorithm:: When and how search paths are applied.
|
|---|
| 158 | * Commands/Search:: How to write shell commands that work together
|
|---|
| 159 | with search paths.
|
|---|
| 160 | * Implicit/Search:: How search paths affect implicit rules.
|
|---|
| 161 | * Libraries/Search:: Directory search for link libraries.
|
|---|
| 162 |
|
|---|
| 163 | Static Pattern Rules
|
|---|
| 164 |
|
|---|
| 165 | * Static Usage:: The syntax of static pattern rules.
|
|---|
| 166 | * Static versus Implicit:: When are they better than implicit rules?
|
|---|
| 167 |
|
|---|
| 168 | Writing the Commands in Rules
|
|---|
| 169 |
|
|---|
| 170 | * Command Syntax:: Command syntax features and pitfalls.
|
|---|
| 171 | * Echoing:: How to control when commands are echoed.
|
|---|
| 172 | * Execution:: How commands are executed.
|
|---|
| 173 | * Parallel:: How commands can be executed in parallel.
|
|---|
| 174 | * Errors:: What happens after a command execution error.
|
|---|
| 175 | * Interrupts:: What happens when a command is interrupted.
|
|---|
| 176 | * Recursion:: Invoking `make' from makefiles.
|
|---|
| 177 | * Sequences:: Defining canned sequences of commands.
|
|---|
| 178 | * Empty Commands:: Defining useful, do-nothing commands.
|
|---|
| 179 |
|
|---|
| 180 | Command Syntax
|
|---|
| 181 |
|
|---|
| 182 | * Splitting Lines:: Breaking long command lines for readability.
|
|---|
| 183 | * Variables in Commands:: Using `make' variables in commands.
|
|---|
| 184 |
|
|---|
| 185 | Command Execution
|
|---|
| 186 |
|
|---|
| 187 | * Choosing the Shell:: How `make' chooses the shell used
|
|---|
| 188 | to run commands.
|
|---|
| 189 |
|
|---|
| 190 | Recursive Use of `make'
|
|---|
| 191 |
|
|---|
| 192 | * MAKE Variable:: The special effects of using `$(MAKE)'.
|
|---|
| 193 | * Variables/Recursion:: How to communicate variables to a sub-`make'.
|
|---|
| 194 | * Options/Recursion:: How to communicate options to a sub-`make'.
|
|---|
| 195 | * -w Option:: How the `-w' or `--print-directory' option
|
|---|
| 196 | helps debug use of recursive `make' commands.
|
|---|
| 197 |
|
|---|
| 198 | How to Use Variables
|
|---|
| 199 |
|
|---|
| 200 | * Reference:: How to use the value of a variable.
|
|---|
| 201 | * Flavors:: Variables come in two flavors.
|
|---|
| 202 | * Advanced:: Advanced features for referencing a variable.
|
|---|
| 203 | * Values:: All the ways variables get their values.
|
|---|
| 204 | * Setting:: How to set a variable in the makefile.
|
|---|
| 205 | * Appending:: How to append more text to the old value
|
|---|
| 206 | of a variable.
|
|---|
| 207 | * Override Directive:: How to set a variable in the makefile even if
|
|---|
| 208 | the user has set it with a command argument.
|
|---|
| 209 | * Defining:: An alternate way to set a variable
|
|---|
| 210 | to a verbatim string.
|
|---|
| 211 | * Environment:: Variable values can come from the environment.
|
|---|
| 212 | * Target-specific:: Variable values can be defined on a per-target
|
|---|
| 213 | basis.
|
|---|
| 214 | * Pattern-specific:: Target-specific variable values can be applied
|
|---|
| 215 | to a group of targets that match a pattern.
|
|---|
| 216 |
|
|---|
| 217 | Advanced Features for Reference to Variables
|
|---|
| 218 |
|
|---|
| 219 | * Substitution Refs:: Referencing a variable with
|
|---|
| 220 | substitutions on the value.
|
|---|
| 221 | * Computed Names:: Computing the name of the variable to refer to.
|
|---|
| 222 |
|
|---|
| 223 | Conditional Parts of Makefiles
|
|---|
| 224 |
|
|---|
| 225 | * Conditional Example:: Example of a conditional
|
|---|
| 226 | * Conditional Syntax:: The syntax of conditionals.
|
|---|
| 227 | * Testing Flags:: Conditionals that test flags.
|
|---|
| 228 |
|
|---|
| 229 | Functions for Transforming Text
|
|---|
| 230 |
|
|---|
| 231 | * Syntax of Functions:: How to write a function call.
|
|---|
| 232 | * Text Functions:: General-purpose text manipulation functions.
|
|---|
| 233 | * File Name Functions:: Functions for manipulating file names.
|
|---|
| 234 | * Conditional Functions:: Functions that implement conditions.
|
|---|
| 235 | * Foreach Function:: Repeat some text with controlled variation.
|
|---|
| 236 | * Call Function:: Expand a user-defined function.
|
|---|
| 237 | * Value Function:: Return the un-expanded value of a variable.
|
|---|
| 238 | * Eval Function:: Evaluate the arguments as makefile syntax.
|
|---|
| 239 | * Origin Function:: Find where a variable got its value.
|
|---|
| 240 | * Flavor Function:: Find out the flavor of a variable.
|
|---|
| 241 | * Shell Function:: Substitute the output of a shell command.
|
|---|
| 242 | * Make Control Functions:: Functions that control how make runs.
|
|---|
| 243 |
|
|---|
| 244 | How to Run `make'
|
|---|
| 245 |
|
|---|
| 246 | * Makefile Arguments:: How to specify which makefile to use.
|
|---|
| 247 | * Goals:: How to use goal arguments to specify which
|
|---|
| 248 | parts of the makefile to use.
|
|---|
| 249 | * Instead of Execution:: How to use mode flags to specify what
|
|---|
| 250 | kind of thing to do with the commands
|
|---|
| 251 | in the makefile other than simply
|
|---|
| 252 | execute them.
|
|---|
| 253 | * Avoiding Compilation:: How to avoid recompiling certain files.
|
|---|
| 254 | * Overriding:: How to override a variable to specify
|
|---|
| 255 | an alternate compiler and other things.
|
|---|
| 256 | * Testing:: How to proceed past some errors, to
|
|---|
| 257 | test compilation.
|
|---|
| 258 | * Options Summary:: Summary of Options
|
|---|
| 259 |
|
|---|
| 260 | Using Implicit Rules
|
|---|
| 261 |
|
|---|
| 262 | * Using Implicit:: How to use an existing implicit rule
|
|---|
| 263 | to get the commands for updating a file.
|
|---|
| 264 | * Catalogue of Rules:: A list of built-in implicit rules.
|
|---|
| 265 | * Implicit Variables:: How to change what predefined rules do.
|
|---|
| 266 | * Chained Rules:: How to use a chain of implicit rules.
|
|---|
| 267 | * Pattern Rules:: How to define new implicit rules.
|
|---|
| 268 | * Last Resort:: How to define commands for rules which
|
|---|
| 269 | cannot find any.
|
|---|
| 270 | * Suffix Rules:: The old-fashioned style of implicit rule.
|
|---|
| 271 | * Implicit Rule Search:: The precise algorithm for applying
|
|---|
| 272 | implicit rules.
|
|---|
| 273 |
|
|---|
| 274 | Defining and Redefining Pattern Rules
|
|---|
| 275 |
|
|---|
| 276 | * Pattern Intro:: An introduction to pattern rules.
|
|---|
| 277 | * Pattern Examples:: Examples of pattern rules.
|
|---|
| 278 | * Automatic Variables:: How to use automatic variables in the
|
|---|
| 279 | commands of implicit rules.
|
|---|
| 280 | * Pattern Match:: How patterns match.
|
|---|
| 281 | * Match-Anything Rules:: Precautions you should take prior to
|
|---|
| 282 | defining rules that can match any
|
|---|
| 283 | target file whatever.
|
|---|
| 284 | * Canceling Rules:: How to override or cancel built-in rules.
|
|---|
| 285 |
|
|---|
| 286 | Using `make' to Update Archive Files
|
|---|
| 287 |
|
|---|
| 288 | * Archive Members:: Archive members as targets.
|
|---|
| 289 | * Archive Update:: The implicit rule for archive member targets.
|
|---|
| 290 | * Archive Pitfalls:: Dangers to watch out for when using archives.
|
|---|
| 291 | * Archive Suffix Rules:: You can write a special kind of suffix rule
|
|---|
| 292 | for updating archives.
|
|---|
| 293 |
|
|---|
| 294 | Implicit Rule for Archive Member Targets
|
|---|
| 295 |
|
|---|
| 296 | * Archive Symbols:: How to update archive symbol directories.
|
|---|
| 297 |
|
|---|
| 298 |
|
|---|
| 299 | File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top
|
|---|
| 300 |
|
|---|
| 301 | 1 Overview of `make'
|
|---|
| 302 | ********************
|
|---|
| 303 |
|
|---|
| 304 | The `make' utility automatically determines which pieces of a large
|
|---|
| 305 | program need to be recompiled, and issues commands to recompile them.
|
|---|
| 306 | This manual describes GNU `make', which was implemented by Richard
|
|---|
| 307 | Stallman and Roland McGrath. Development since Version 3.76 has been
|
|---|
| 308 | handled by Paul D. Smith.
|
|---|
| 309 |
|
|---|
| 310 | GNU `make' conforms to section 6.2 of `IEEE Standard 1003.2-1992'
|
|---|
| 311 | (POSIX.2).
|
|---|
| 312 |
|
|---|
| 313 | Our examples show C programs, since they are most common, but you
|
|---|
| 314 | can use `make' with any programming language whose compiler can be run
|
|---|
| 315 | with a shell command. Indeed, `make' is not limited to programs. You
|
|---|
| 316 | can use it to describe any task where some files must be updated
|
|---|
| 317 | automatically from others whenever the others change.
|
|---|
| 318 |
|
|---|
| 319 | * Menu:
|
|---|
| 320 |
|
|---|
| 321 | * Preparing:: Preparing and Running Make
|
|---|
| 322 | * Reading:: On Reading this Text
|
|---|
| 323 | * Bugs:: Problems and Bugs
|
|---|
| 324 |
|
|---|
| 325 |
|
|---|
| 326 | File: make.info, Node: Preparing, Next: Reading, Prev: Overview, Up: Overview
|
|---|
| 327 |
|
|---|
| 328 | Preparing and Running Make
|
|---|
| 329 | ==========================
|
|---|
| 330 |
|
|---|
| 331 | To prepare to use `make', you must write a file called the
|
|---|
| 332 | "makefile" that describes the relationships among files in your program
|
|---|
| 333 | and provides commands for updating each file. In a program, typically,
|
|---|
| 334 | the executable file is updated from object files, which are in turn
|
|---|
| 335 | made by compiling source files.
|
|---|
| 336 |
|
|---|
| 337 | Once a suitable makefile exists, each time you change some source
|
|---|
| 338 | files, this simple shell command:
|
|---|
| 339 |
|
|---|
| 340 | make
|
|---|
| 341 |
|
|---|
| 342 | suffices to perform all necessary recompilations. The `make' program
|
|---|
| 343 | uses the makefile data base and the last-modification times of the
|
|---|
| 344 | files to decide which of the files need to be updated. For each of
|
|---|
| 345 | those files, it issues the commands recorded in the data base.
|
|---|
| 346 |
|
|---|
| 347 | You can provide command line arguments to `make' to control which
|
|---|
| 348 | files should be recompiled, or how. *Note How to Run `make': Running.
|
|---|
| 349 |
|
|---|
| 350 |
|
|---|
| 351 | File: make.info, Node: Reading, Next: Bugs, Prev: Preparing, Up: Overview
|
|---|
| 352 |
|
|---|
| 353 | 1.1 How to Read This Manual
|
|---|
| 354 | ===========================
|
|---|
| 355 |
|
|---|
| 356 | If you are new to `make', or are looking for a general introduction,
|
|---|
| 357 | read the first few sections of each chapter, skipping the later
|
|---|
| 358 | sections. In each chapter, the first few sections contain introductory
|
|---|
| 359 | or general information and the later sections contain specialized or
|
|---|
| 360 | technical information. The exception is the second chapter, *Note An
|
|---|
| 361 | Introduction to Makefiles: Introduction, all of which is introductory.
|
|---|
| 362 |
|
|---|
| 363 | If you are familiar with other `make' programs, see *Note Features
|
|---|
| 364 | of GNU `make': Features, which lists the enhancements GNU `make' has,
|
|---|
| 365 | and *Note Incompatibilities and Missing Features: Missing, which
|
|---|
| 366 | explains the few things GNU `make' lacks that others have.
|
|---|
| 367 |
|
|---|
| 368 | For a quick summary, see *Note Options Summary::, *Note Quick
|
|---|
| 369 | Reference::, and *Note Special Targets::.
|
|---|
| 370 |
|
|---|
| 371 |
|
|---|
| 372 | File: make.info, Node: Bugs, Prev: Reading, Up: Overview
|
|---|
| 373 |
|
|---|
| 374 | 1.2 Problems and Bugs
|
|---|
| 375 | =====================
|
|---|
| 376 |
|
|---|
| 377 | If you have problems with GNU `make' or think you've found a bug,
|
|---|
| 378 | please report it to the developers; we cannot promise to do anything but
|
|---|
| 379 | we might well want to fix it.
|
|---|
| 380 |
|
|---|
| 381 | Before reporting a bug, make sure you've actually found a real bug.
|
|---|
| 382 | Carefully reread the documentation and see if it really says you can do
|
|---|
| 383 | what you're trying to do. If it's not clear whether you should be able
|
|---|
| 384 | to do something or not, report that too; it's a bug in the
|
|---|
| 385 | documentation!
|
|---|
| 386 |
|
|---|
| 387 | Before reporting a bug or trying to fix it yourself, try to isolate
|
|---|
| 388 | it to the smallest possible makefile that reproduces the problem. Then
|
|---|
| 389 | send us the makefile and the exact results `make' gave you, including
|
|---|
| 390 | any error or warning messages. Please don't paraphrase these messages:
|
|---|
| 391 | it's best to cut and paste them into your report. When generating this
|
|---|
| 392 | small makefile, be sure to not use any non-free or unusual tools in
|
|---|
| 393 | your commands: you can almost always emulate what such a tool would do
|
|---|
| 394 | with simple shell commands. Finally, be sure to explain what you
|
|---|
| 395 | expected to occur; this will help us decide whether the problem was
|
|---|
| 396 | really in the documentation.
|
|---|
| 397 |
|
|---|
| 398 | Once you have a precise problem you can report it in one of two ways.
|
|---|
| 399 | Either send electronic mail to:
|
|---|
| 400 |
|
|---|
| 401 | bug-make@gnu.org
|
|---|
| 402 |
|
|---|
| 403 | or use our Web-based project management tool, at:
|
|---|
| 404 |
|
|---|
| 405 | http://savannah.gnu.org/projects/make/
|
|---|
| 406 |
|
|---|
| 407 | In addition to the information above, please be careful to include the
|
|---|
| 408 | version number of `make' you are using. You can get this information
|
|---|
| 409 | with the command `make --version'. Be sure also to include the type of
|
|---|
| 410 | machine and operating system you are using. One way to obtain this
|
|---|
| 411 | information is by looking at the final lines of output from the command
|
|---|
| 412 | `make --help'.
|
|---|
| 413 |
|
|---|
| 414 |
|
|---|
| 415 | File: make.info, Node: Introduction, Next: Makefiles, Prev: Overview, Up: Top
|
|---|
| 416 |
|
|---|
| 417 | 2 An Introduction to Makefiles
|
|---|
| 418 | ******************************
|
|---|
| 419 |
|
|---|
| 420 | You need a file called a "makefile" to tell `make' what to do. Most
|
|---|
| 421 | often, the makefile tells `make' how to compile and link a program.
|
|---|
| 422 |
|
|---|
| 423 | In this chapter, we will discuss a simple makefile that describes
|
|---|
| 424 | how to compile and link a text editor which consists of eight C source
|
|---|
| 425 | files and three header files. The makefile can also tell `make' how to
|
|---|
| 426 | run miscellaneous commands when explicitly asked (for example, to remove
|
|---|
| 427 | certain files as a clean-up operation). To see a more complex example
|
|---|
| 428 | of a makefile, see *Note Complex Makefile::.
|
|---|
| 429 |
|
|---|
| 430 | When `make' recompiles the editor, each changed C source file must
|
|---|
| 431 | be recompiled. If a header file has changed, each C source file that
|
|---|
| 432 | includes the header file must be recompiled to be safe. Each
|
|---|
| 433 | compilation produces an object file corresponding to the source file.
|
|---|
| 434 | Finally, if any source file has been recompiled, all the object files,
|
|---|
| 435 | whether newly made or saved from previous compilations, must be linked
|
|---|
| 436 | together to produce the new executable editor.
|
|---|
| 437 |
|
|---|
| 438 | * Menu:
|
|---|
| 439 |
|
|---|
| 440 | * Rule Introduction:: What a rule looks like.
|
|---|
| 441 | * Simple Makefile:: A Simple Makefile
|
|---|
| 442 | * How Make Works:: How `make' Processes This Makefile
|
|---|
| 443 | * Variables Simplify:: Variables Make Makefiles Simpler
|
|---|
| 444 | * make Deduces:: Letting `make' Deduce the Commands
|
|---|
| 445 | * Combine By Prerequisite:: Another Style of Makefile
|
|---|
| 446 | * Cleanup:: Rules for Cleaning the Directory
|
|---|
| 447 |
|
|---|
| 448 |
|
|---|
| 449 | File: make.info, Node: Rule Introduction, Next: Simple Makefile, Prev: Introduction, Up: Introduction
|
|---|
| 450 |
|
|---|
| 451 | 2.1 What a Rule Looks Like
|
|---|
| 452 | ==========================
|
|---|
| 453 |
|
|---|
| 454 | A simple makefile consists of "rules" with the following shape:
|
|---|
| 455 |
|
|---|
| 456 | TARGET ... : PREREQUISITES ...
|
|---|
| 457 | COMMAND
|
|---|
| 458 | ...
|
|---|
| 459 | ...
|
|---|
| 460 |
|
|---|
| 461 | A "target" is usually the name of a file that is generated by a
|
|---|
| 462 | program; examples of targets are executable or object files. A target
|
|---|
| 463 | can also be the name of an action to carry out, such as `clean' (*note
|
|---|
| 464 | Phony Targets::).
|
|---|
| 465 |
|
|---|
| 466 | A "prerequisite" is a file that is used as input to create the
|
|---|
| 467 | target. A target often depends on several files.
|
|---|
| 468 |
|
|---|
| 469 | A "command" is an action that `make' carries out. A rule may have
|
|---|
| 470 | more than one command, each on its own line. *Please note:* you need
|
|---|
| 471 | to put a tab character at the beginning of every command line! This is
|
|---|
| 472 | an obscurity that catches the unwary.
|
|---|
| 473 |
|
|---|
| 474 | Usually a command is in a rule with prerequisites and serves to
|
|---|
| 475 | create a target file if any of the prerequisites change. However, the
|
|---|
| 476 | rule that specifies commands for the target need not have
|
|---|
| 477 | prerequisites. For example, the rule containing the delete command
|
|---|
| 478 | associated with the target `clean' does not have prerequisites.
|
|---|
| 479 |
|
|---|
| 480 | A "rule", then, explains how and when to remake certain files which
|
|---|
| 481 | are the targets of the particular rule. `make' carries out the
|
|---|
| 482 | commands on the prerequisites to create or update the target. A rule
|
|---|
| 483 | can also explain how and when to carry out an action. *Note Writing
|
|---|
| 484 | Rules: Rules.
|
|---|
| 485 |
|
|---|
| 486 | A makefile may contain other text besides rules, but a simple
|
|---|
| 487 | makefile need only contain rules. Rules may look somewhat more
|
|---|
| 488 | complicated than shown in this template, but all fit the pattern more
|
|---|
| 489 | or less.
|
|---|
| 490 |
|
|---|
| 491 |
|
|---|
| 492 | File: make.info, Node: Simple Makefile, Next: How Make Works, Prev: Rule Introduction, Up: Introduction
|
|---|
| 493 |
|
|---|
| 494 | 2.2 A Simple Makefile
|
|---|
| 495 | =====================
|
|---|
| 496 |
|
|---|
| 497 | Here is a straightforward makefile that describes the way an executable
|
|---|
| 498 | file called `edit' depends on eight object files which, in turn, depend
|
|---|
| 499 | on eight C source and three header files.
|
|---|
| 500 |
|
|---|
| 501 | In this example, all the C files include `defs.h', but only those
|
|---|
| 502 | defining editing commands include `command.h', and only low level files
|
|---|
| 503 | that change the editor buffer include `buffer.h'.
|
|---|
| 504 |
|
|---|
| 505 | edit : main.o kbd.o command.o display.o \
|
|---|
| 506 | insert.o search.o files.o utils.o
|
|---|
| 507 | cc -o edit main.o kbd.o command.o display.o \
|
|---|
| 508 | insert.o search.o files.o utils.o
|
|---|
| 509 |
|
|---|
| 510 | main.o : main.c defs.h
|
|---|
| 511 | cc -c main.c
|
|---|
| 512 | kbd.o : kbd.c defs.h command.h
|
|---|
| 513 | cc -c kbd.c
|
|---|
| 514 | command.o : command.c defs.h command.h
|
|---|
| 515 | cc -c command.c
|
|---|
| 516 | display.o : display.c defs.h buffer.h
|
|---|
| 517 | cc -c display.c
|
|---|
| 518 | insert.o : insert.c defs.h buffer.h
|
|---|
| 519 | cc -c insert.c
|
|---|
| 520 | search.o : search.c defs.h buffer.h
|
|---|
| 521 | cc -c search.c
|
|---|
| 522 | files.o : files.c defs.h buffer.h command.h
|
|---|
| 523 | cc -c files.c
|
|---|
| 524 | utils.o : utils.c defs.h
|
|---|
| 525 | cc -c utils.c
|
|---|
| 526 | clean :
|
|---|
| 527 | rm edit main.o kbd.o command.o display.o \
|
|---|
| 528 | insert.o search.o files.o utils.o
|
|---|
| 529 |
|
|---|
| 530 | We split each long line into two lines using backslash-newline; this is
|
|---|
| 531 | like using one long line, but is easier to read.
|
|---|
| 532 |
|
|---|
| 533 | To use this makefile to create the executable file called `edit',
|
|---|
| 534 | type:
|
|---|
| 535 |
|
|---|
| 536 | make
|
|---|
| 537 |
|
|---|
| 538 | To use this makefile to delete the executable file and all the object
|
|---|
| 539 | files from the directory, type:
|
|---|
| 540 |
|
|---|
| 541 | make clean
|
|---|
| 542 |
|
|---|
| 543 | In the example makefile, the targets include the executable file
|
|---|
| 544 | `edit', and the object files `main.o' and `kbd.o'. The prerequisites
|
|---|
| 545 | are files such as `main.c' and `defs.h'. In fact, each `.o' file is
|
|---|
| 546 | both a target and a prerequisite. Commands include `cc -c main.c' and
|
|---|
| 547 | `cc -c kbd.c'.
|
|---|
| 548 |
|
|---|
| 549 | When a target is a file, it needs to be recompiled or relinked if any
|
|---|
| 550 | of its prerequisites change. In addition, any prerequisites that are
|
|---|
| 551 | themselves automatically generated should be updated first. In this
|
|---|
| 552 | example, `edit' depends on each of the eight object files; the object
|
|---|
| 553 | file `main.o' depends on the source file `main.c' and on the header
|
|---|
| 554 | file `defs.h'.
|
|---|
| 555 |
|
|---|
| 556 | A shell command follows each line that contains a target and
|
|---|
| 557 | prerequisites. These shell commands say how to update the target file.
|
|---|
| 558 | A tab character must come at the beginning of every command line to
|
|---|
| 559 | distinguish command lines from other lines in the makefile. (Bear in
|
|---|
| 560 | mind that `make' does not know anything about how the commands work.
|
|---|
| 561 | It is up to you to supply commands that will update the target file
|
|---|
| 562 | properly. All `make' does is execute the commands in the rule you have
|
|---|
| 563 | specified when the target file needs to be updated.)
|
|---|
| 564 |
|
|---|
| 565 | The target `clean' is not a file, but merely the name of an action.
|
|---|
| 566 | Since you normally do not want to carry out the actions in this rule,
|
|---|
| 567 | `clean' is not a prerequisite of any other rule. Consequently, `make'
|
|---|
| 568 | never does anything with it unless you tell it specifically. Note that
|
|---|
| 569 | this rule not only is not a prerequisite, it also does not have any
|
|---|
| 570 | prerequisites, so the only purpose of the rule is to run the specified
|
|---|
| 571 | commands. Targets that do not refer to files but are just actions are
|
|---|
| 572 | called "phony targets". *Note Phony Targets::, for information about
|
|---|
| 573 | this kind of target. *Note Errors in Commands: Errors, to see how to
|
|---|
| 574 | cause `make' to ignore errors from `rm' or any other command.
|
|---|
| 575 |
|
|---|
| 576 |
|
|---|
| 577 | File: make.info, Node: How Make Works, Next: Variables Simplify, Prev: Simple Makefile, Up: Introduction
|
|---|
| 578 |
|
|---|
| 579 | 2.3 How `make' Processes a Makefile
|
|---|
| 580 | ===================================
|
|---|
| 581 |
|
|---|
| 582 | By default, `make' starts with the first target (not targets whose
|
|---|
| 583 | names start with `.'). This is called the "default goal". ("Goals"
|
|---|
| 584 | are the targets that `make' strives ultimately to update. You can
|
|---|
| 585 | override this behavior using the command line (*note Arguments to
|
|---|
| 586 | Specify the Goals: Goals.) or with the `.DEFAULT_GOAL' special variable
|
|---|
| 587 | (*note Other Special Variables: Special Variables.).
|
|---|
| 588 |
|
|---|
| 589 | In the simple example of the previous section, the default goal is to
|
|---|
| 590 | update the executable program `edit'; therefore, we put that rule first.
|
|---|
| 591 |
|
|---|
| 592 | Thus, when you give the command:
|
|---|
| 593 |
|
|---|
| 594 | make
|
|---|
| 595 |
|
|---|
| 596 | `make' reads the makefile in the current directory and begins by
|
|---|
| 597 | processing the first rule. In the example, this rule is for relinking
|
|---|
| 598 | `edit'; but before `make' can fully process this rule, it must process
|
|---|
| 599 | the rules for the files that `edit' depends on, which in this case are
|
|---|
| 600 | the object files. Each of these files is processed according to its
|
|---|
| 601 | own rule. These rules say to update each `.o' file by compiling its
|
|---|
| 602 | source file. The recompilation must be done if the source file, or any
|
|---|
| 603 | of the header files named as prerequisites, is more recent than the
|
|---|
| 604 | object file, or if the object file does not exist.
|
|---|
| 605 |
|
|---|
| 606 | The other rules are processed because their targets appear as
|
|---|
| 607 | prerequisites of the goal. If some other rule is not depended on by the
|
|---|
| 608 | goal (or anything it depends on, etc.), that rule is not processed,
|
|---|
| 609 | unless you tell `make' to do so (with a command such as `make clean').
|
|---|
| 610 |
|
|---|
| 611 | Before recompiling an object file, `make' considers updating its
|
|---|
| 612 | prerequisites, the source file and header files. This makefile does not
|
|---|
| 613 | specify anything to be done for them--the `.c' and `.h' files are not
|
|---|
| 614 | the targets of any rules--so `make' does nothing for these files. But
|
|---|
| 615 | `make' would update automatically generated C programs, such as those
|
|---|
| 616 | made by Bison or Yacc, by their own rules at this time.
|
|---|
| 617 |
|
|---|
| 618 | After recompiling whichever object files need it, `make' decides
|
|---|
| 619 | whether to relink `edit'. This must be done if the file `edit' does
|
|---|
| 620 | not exist, or if any of the object files are newer than it. If an
|
|---|
| 621 | object file was just recompiled, it is now newer than `edit', so `edit'
|
|---|
| 622 | is relinked.
|
|---|
| 623 |
|
|---|
| 624 | Thus, if we change the file `insert.c' and run `make', `make' will
|
|---|
| 625 | compile that file to update `insert.o', and then link `edit'. If we
|
|---|
| 626 | change the file `command.h' and run `make', `make' will recompile the
|
|---|
| 627 | object files `kbd.o', `command.o' and `files.o' and then link the file
|
|---|
| 628 | `edit'.
|
|---|
| 629 |
|
|---|
| 630 |
|
|---|
| 631 | File: make.info, Node: Variables Simplify, Next: make Deduces, Prev: How Make Works, Up: Introduction
|
|---|
| 632 |
|
|---|
| 633 | 2.4 Variables Make Makefiles Simpler
|
|---|
| 634 | ====================================
|
|---|
| 635 |
|
|---|
| 636 | In our example, we had to list all the object files twice in the rule
|
|---|
| 637 | for `edit' (repeated here):
|
|---|
| 638 |
|
|---|
| 639 | edit : main.o kbd.o command.o display.o \
|
|---|
| 640 | insert.o search.o files.o utils.o
|
|---|
| 641 | cc -o edit main.o kbd.o command.o display.o \
|
|---|
| 642 | insert.o search.o files.o utils.o
|
|---|
| 643 |
|
|---|
| 644 | Such duplication is error-prone; if a new object file is added to the
|
|---|
| 645 | system, we might add it to one list and forget the other. We can
|
|---|
| 646 | eliminate the risk and simplify the makefile by using a variable.
|
|---|
| 647 | "Variables" allow a text string to be defined once and substituted in
|
|---|
| 648 | multiple places later (*note How to Use Variables: Using Variables.).
|
|---|
| 649 |
|
|---|
| 650 | It is standard practice for every makefile to have a variable named
|
|---|
| 651 | `objects', `OBJECTS', `objs', `OBJS', `obj', or `OBJ' which is a list
|
|---|
| 652 | of all object file names. We would define such a variable `objects'
|
|---|
| 653 | with a line like this in the makefile:
|
|---|
| 654 |
|
|---|
| 655 | objects = main.o kbd.o command.o display.o \
|
|---|
| 656 | insert.o search.o files.o utils.o
|
|---|
| 657 |
|
|---|
| 658 | Then, each place we want to put a list of the object file names, we can
|
|---|
| 659 | substitute the variable's value by writing `$(objects)' (*note How to
|
|---|
| 660 | Use Variables: Using Variables.).
|
|---|
| 661 |
|
|---|
| 662 | Here is how the complete simple makefile looks when you use a
|
|---|
| 663 | variable for the object files:
|
|---|
| 664 |
|
|---|
| 665 | objects = main.o kbd.o command.o display.o \
|
|---|
| 666 | insert.o search.o files.o utils.o
|
|---|
| 667 |
|
|---|
| 668 | edit : $(objects)
|
|---|
| 669 | cc -o edit $(objects)
|
|---|
| 670 | main.o : main.c defs.h
|
|---|
| 671 | cc -c main.c
|
|---|
| 672 | kbd.o : kbd.c defs.h command.h
|
|---|
| 673 | cc -c kbd.c
|
|---|
| 674 | command.o : command.c defs.h command.h
|
|---|
| 675 | cc -c command.c
|
|---|
| 676 | display.o : display.c defs.h buffer.h
|
|---|
| 677 | cc -c display.c
|
|---|
| 678 | insert.o : insert.c defs.h buffer.h
|
|---|
| 679 | cc -c insert.c
|
|---|
| 680 | search.o : search.c defs.h buffer.h
|
|---|
| 681 | cc -c search.c
|
|---|
| 682 | files.o : files.c defs.h buffer.h command.h
|
|---|
| 683 | cc -c files.c
|
|---|
| 684 | utils.o : utils.c defs.h
|
|---|
| 685 | cc -c utils.c
|
|---|
| 686 | clean :
|
|---|
| 687 | rm edit $(objects)
|
|---|
| 688 |
|
|---|
| 689 |
|
|---|
| 690 | File: make.info, Node: make Deduces, Next: Combine By Prerequisite, Prev: Variables Simplify, Up: Introduction
|
|---|
| 691 |
|
|---|
| 692 | 2.5 Letting `make' Deduce the Commands
|
|---|
| 693 | ======================================
|
|---|
| 694 |
|
|---|
| 695 | It is not necessary to spell out the commands for compiling the
|
|---|
| 696 | individual C source files, because `make' can figure them out: it has an
|
|---|
| 697 | "implicit rule" for updating a `.o' file from a correspondingly named
|
|---|
| 698 | `.c' file using a `cc -c' command. For example, it will use the
|
|---|
| 699 | command `cc -c main.c -o main.o' to compile `main.c' into `main.o'. We
|
|---|
| 700 | can therefore omit the commands from the rules for the object files.
|
|---|
| 701 | *Note Using Implicit Rules: Implicit Rules.
|
|---|
| 702 |
|
|---|
| 703 | When a `.c' file is used automatically in this way, it is also
|
|---|
| 704 | automatically added to the list of prerequisites. We can therefore omit
|
|---|
| 705 | the `.c' files from the prerequisites, provided we omit the commands.
|
|---|
| 706 |
|
|---|
| 707 | Here is the entire example, with both of these changes, and a
|
|---|
| 708 | variable `objects' as suggested above:
|
|---|
| 709 |
|
|---|
| 710 | objects = main.o kbd.o command.o display.o \
|
|---|
| 711 | insert.o search.o files.o utils.o
|
|---|
| 712 |
|
|---|
| 713 | edit : $(objects)
|
|---|
| 714 | cc -o edit $(objects)
|
|---|
| 715 |
|
|---|
| 716 | main.o : defs.h
|
|---|
| 717 | kbd.o : defs.h command.h
|
|---|
| 718 | command.o : defs.h command.h
|
|---|
| 719 | display.o : defs.h buffer.h
|
|---|
| 720 | insert.o : defs.h buffer.h
|
|---|
| 721 | search.o : defs.h buffer.h
|
|---|
| 722 | files.o : defs.h buffer.h command.h
|
|---|
| 723 | utils.o : defs.h
|
|---|
| 724 |
|
|---|
| 725 | .PHONY : clean
|
|---|
| 726 | clean :
|
|---|
| 727 | rm edit $(objects)
|
|---|
| 728 |
|
|---|
| 729 | This is how we would write the makefile in actual practice. (The
|
|---|
| 730 | complications associated with `clean' are described elsewhere. See
|
|---|
| 731 | *Note Phony Targets::, and *Note Errors in Commands: Errors.)
|
|---|
| 732 |
|
|---|
| 733 | Because implicit rules are so convenient, they are important. You
|
|---|
| 734 | will see them used frequently.
|
|---|
| 735 |
|
|---|
| 736 |
|
|---|
| 737 | File: make.info, Node: Combine By Prerequisite, Next: Cleanup, Prev: make Deduces, Up: Introduction
|
|---|
| 738 |
|
|---|
| 739 | 2.6 Another Style of Makefile
|
|---|
| 740 | =============================
|
|---|
| 741 |
|
|---|
| 742 | When the objects of a makefile are created only by implicit rules, an
|
|---|
| 743 | alternative style of makefile is possible. In this style of makefile,
|
|---|
| 744 | you group entries by their prerequisites instead of by their targets.
|
|---|
| 745 | Here is what one looks like:
|
|---|
| 746 |
|
|---|
| 747 | objects = main.o kbd.o command.o display.o \
|
|---|
| 748 | insert.o search.o files.o utils.o
|
|---|
| 749 |
|
|---|
| 750 | edit : $(objects)
|
|---|
| 751 | cc -o edit $(objects)
|
|---|
| 752 |
|
|---|
| 753 | $(objects) : defs.h
|
|---|
| 754 | kbd.o command.o files.o : command.h
|
|---|
| 755 | display.o insert.o search.o files.o : buffer.h
|
|---|
| 756 |
|
|---|
| 757 | Here `defs.h' is given as a prerequisite of all the object files;
|
|---|
| 758 | `command.h' and `buffer.h' are prerequisites of the specific object
|
|---|
| 759 | files listed for them.
|
|---|
| 760 |
|
|---|
| 761 | Whether this is better is a matter of taste: it is more compact, but
|
|---|
| 762 | some people dislike it because they find it clearer to put all the
|
|---|
| 763 | information about each target in one place.
|
|---|
| 764 |
|
|---|
| 765 |
|
|---|
| 766 | File: make.info, Node: Cleanup, Prev: Combine By Prerequisite, Up: Introduction
|
|---|
| 767 |
|
|---|
| 768 | 2.7 Rules for Cleaning the Directory
|
|---|
| 769 | ====================================
|
|---|
| 770 |
|
|---|
| 771 | Compiling a program is not the only thing you might want to write rules
|
|---|
| 772 | for. Makefiles commonly tell how to do a few other things besides
|
|---|
| 773 | compiling a program: for example, how to delete all the object files
|
|---|
| 774 | and executables so that the directory is `clean'.
|
|---|
| 775 |
|
|---|
| 776 | Here is how we could write a `make' rule for cleaning our example
|
|---|
| 777 | editor:
|
|---|
| 778 |
|
|---|
| 779 | clean:
|
|---|
| 780 | rm edit $(objects)
|
|---|
| 781 |
|
|---|
| 782 | In practice, we might want to write the rule in a somewhat more
|
|---|
| 783 | complicated manner to handle unanticipated situations. We would do
|
|---|
| 784 | this:
|
|---|
| 785 |
|
|---|
| 786 | .PHONY : clean
|
|---|
| 787 | clean :
|
|---|
| 788 | -rm edit $(objects)
|
|---|
| 789 |
|
|---|
| 790 | This prevents `make' from getting confused by an actual file called
|
|---|
| 791 | `clean' and causes it to continue in spite of errors from `rm'. (See
|
|---|
| 792 | *Note Phony Targets::, and *Note Errors in Commands: Errors.)
|
|---|
| 793 |
|
|---|
| 794 | A rule such as this should not be placed at the beginning of the
|
|---|
| 795 | makefile, because we do not want it to run by default! Thus, in the
|
|---|
| 796 | example makefile, we want the rule for `edit', which recompiles the
|
|---|
| 797 | editor, to remain the default goal.
|
|---|
| 798 |
|
|---|
| 799 | Since `clean' is not a prerequisite of `edit', this rule will not
|
|---|
| 800 | run at all if we give the command `make' with no arguments. In order
|
|---|
| 801 | to make the rule run, we have to type `make clean'. *Note How to Run
|
|---|
| 802 | `make': Running.
|
|---|
| 803 |
|
|---|
| 804 |
|
|---|
| 805 | File: make.info, Node: Makefiles, Next: Rules, Prev: Introduction, Up: Top
|
|---|
| 806 |
|
|---|
| 807 | 3 Writing Makefiles
|
|---|
| 808 | *******************
|
|---|
| 809 |
|
|---|
| 810 | The information that tells `make' how to recompile a system comes from
|
|---|
| 811 | reading a data base called the "makefile".
|
|---|
| 812 |
|
|---|
| 813 | * Menu:
|
|---|
| 814 |
|
|---|
| 815 | * Makefile Contents:: What makefiles contain.
|
|---|
| 816 | * Makefile Names:: How to name your makefile.
|
|---|
| 817 | * Include:: How one makefile can use another makefile.
|
|---|
| 818 | * MAKEFILES Variable:: The environment can specify extra makefiles.
|
|---|
| 819 | * MAKEFILE_LIST Variable:: Discover which makefiles have been read.
|
|---|
| 820 | * Special Variables:: Other special variables.
|
|---|
| 821 | * Remaking Makefiles:: How makefiles get remade.
|
|---|
| 822 | * Overriding Makefiles:: How to override part of one makefile
|
|---|
| 823 | with another makefile.
|
|---|
| 824 | * Reading Makefiles:: How makefiles are parsed.
|
|---|
| 825 | * Secondary Expansion:: How and when secondary expansion is performed.
|
|---|
| 826 |
|
|---|
| 827 |
|
|---|
| 828 | File: make.info, Node: Makefile Contents, Next: Makefile Names, Prev: Makefiles, Up: Makefiles
|
|---|
| 829 |
|
|---|
| 830 | 3.1 What Makefiles Contain
|
|---|
| 831 | ==========================
|
|---|
| 832 |
|
|---|
| 833 | Makefiles contain five kinds of things: "explicit rules", "implicit
|
|---|
| 834 | rules", "variable definitions", "directives", and "comments". Rules,
|
|---|
| 835 | variables, and directives are described at length in later chapters.
|
|---|
| 836 |
|
|---|
| 837 | * An "explicit rule" says when and how to remake one or more files,
|
|---|
| 838 | called the rule's "targets". It lists the other files that the
|
|---|
| 839 | targets depend on, called the "prerequisites" of the target, and
|
|---|
| 840 | may also give commands to use to create or update the targets.
|
|---|
| 841 | *Note Writing Rules: Rules.
|
|---|
| 842 |
|
|---|
| 843 | * An "implicit rule" says when and how to remake a class of files
|
|---|
| 844 | based on their names. It describes how a target may depend on a
|
|---|
| 845 | file with a name similar to the target and gives commands to
|
|---|
| 846 | create or update such a target. *Note Using Implicit Rules:
|
|---|
| 847 | Implicit Rules.
|
|---|
| 848 |
|
|---|
| 849 | * A "variable definition" is a line that specifies a text string
|
|---|
| 850 | value for a variable that can be substituted into the text later.
|
|---|
| 851 | The simple makefile example shows a variable definition for
|
|---|
| 852 | `objects' as a list of all object files (*note Variables Make
|
|---|
| 853 | Makefiles Simpler: Variables Simplify.).
|
|---|
| 854 |
|
|---|
| 855 | * A "directive" is a command for `make' to do something special while
|
|---|
| 856 | reading the makefile. These include:
|
|---|
| 857 |
|
|---|
| 858 | * Reading another makefile (*note Including Other Makefiles:
|
|---|
| 859 | Include.).
|
|---|
| 860 |
|
|---|
| 861 | * Deciding (based on the values of variables) whether to use or
|
|---|
| 862 | ignore a part of the makefile (*note Conditional Parts of
|
|---|
| 863 | Makefiles: Conditionals.).
|
|---|
| 864 |
|
|---|
| 865 | * Defining a variable from a verbatim string containing
|
|---|
| 866 | multiple lines (*note Defining Variables Verbatim: Defining.).
|
|---|
| 867 |
|
|---|
| 868 | * `#' in a line of a makefile starts a "comment". It and the rest
|
|---|
| 869 | of the line are ignored, except that a trailing backslash not
|
|---|
| 870 | escaped by another backslash will continue the comment across
|
|---|
| 871 | multiple lines. A line containing just a comment (with perhaps
|
|---|
| 872 | spaces before it) is effectively blank, and is ignored. If you
|
|---|
| 873 | want a literal `#', escape it with a backslash (e.g., `\#').
|
|---|
| 874 | Comments may appear on any line in the makefile, although they are
|
|---|
| 875 | treated specially in certain situations.
|
|---|
| 876 |
|
|---|
| 877 | Within a command script (if the line begins with a TAB character)
|
|---|
| 878 | the entire line is passed to the shell, just as with any other
|
|---|
| 879 | line that begins with a TAB. The shell decides how to interpret
|
|---|
| 880 | the text: whether or not this is a comment is up to the shell.
|
|---|
| 881 |
|
|---|
| 882 | Within a `define' directive, comments are not ignored during the
|
|---|
| 883 | definition of the variable, but rather kept intact in the value of
|
|---|
| 884 | the variable. When the variable is expanded they will either be
|
|---|
| 885 | treated as `make' comments or as command script text, depending on
|
|---|
| 886 | the context in which the variable is evaluated.
|
|---|
| 887 |
|
|---|
| 888 |
|
|---|
| 889 | File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles
|
|---|
| 890 |
|
|---|
| 891 | 3.2 What Name to Give Your Makefile
|
|---|
| 892 | ===================================
|
|---|
| 893 |
|
|---|
| 894 | By default, when `make' looks for the makefile, it tries the following
|
|---|
| 895 | names, in order: `GNUmakefile', `makefile' and `Makefile'.
|
|---|
| 896 |
|
|---|
| 897 | Normally you should call your makefile either `makefile' or
|
|---|
| 898 | `Makefile'. (We recommend `Makefile' because it appears prominently
|
|---|
| 899 | near the beginning of a directory listing, right near other important
|
|---|
| 900 | files such as `README'.) The first name checked, `GNUmakefile', is not
|
|---|
| 901 | recommended for most makefiles. You should use this name if you have a
|
|---|
| 902 | makefile that is specific to GNU `make', and will not be understood by
|
|---|
| 903 | other versions of `make'. Other `make' programs look for `makefile' and
|
|---|
| 904 | `Makefile', but not `GNUmakefile'.
|
|---|
| 905 |
|
|---|
| 906 | If `make' finds none of these names, it does not use any makefile.
|
|---|
| 907 | Then you must specify a goal with a command argument, and `make' will
|
|---|
| 908 | attempt to figure out how to remake it using only its built-in implicit
|
|---|
| 909 | rules. *Note Using Implicit Rules: Implicit Rules.
|
|---|
| 910 |
|
|---|
| 911 | If you want to use a nonstandard name for your makefile, you can
|
|---|
| 912 | specify the makefile name with the `-f' or `--file' option. The
|
|---|
| 913 | arguments `-f NAME' or `--file=NAME' tell `make' to read the file NAME
|
|---|
| 914 | as the makefile. If you use more than one `-f' or `--file' option, you
|
|---|
| 915 | can specify several makefiles. All the makefiles are effectively
|
|---|
| 916 | concatenated in the order specified. The default makefile names
|
|---|
| 917 | `GNUmakefile', `makefile' and `Makefile' are not checked automatically
|
|---|
| 918 | if you specify `-f' or `--file'.
|
|---|
| 919 |
|
|---|
| 920 |
|
|---|
| 921 | File: make.info, Node: Include, Next: MAKEFILES Variable, Prev: Makefile Names, Up: Makefiles
|
|---|
| 922 |
|
|---|
| 923 | 3.3 Including Other Makefiles
|
|---|
| 924 | =============================
|
|---|
| 925 |
|
|---|
| 926 | The `include' directive tells `make' to suspend reading the current
|
|---|
| 927 | makefile and read one or more other makefiles before continuing. The
|
|---|
| 928 | directive is a line in the makefile that looks like this:
|
|---|
| 929 |
|
|---|
| 930 | include FILENAMES...
|
|---|
| 931 |
|
|---|
| 932 | FILENAMES can contain shell file name patterns. If FILENAMES is empty,
|
|---|
| 933 | nothing is included and no error is printed.
|
|---|
| 934 |
|
|---|
| 935 | Extra spaces are allowed and ignored at the beginning of the line,
|
|---|
| 936 | but a tab is not allowed. (If the line begins with a tab, it will be
|
|---|
| 937 | considered a command line.) Whitespace is required between `include'
|
|---|
| 938 | and the file names, and between file names; extra whitespace is ignored
|
|---|
| 939 | there and at the end of the directive. A comment starting with `#' is
|
|---|
| 940 | allowed at the end of the line. If the file names contain any variable
|
|---|
| 941 | or function references, they are expanded. *Note How to Use Variables:
|
|---|
| 942 | Using Variables.
|
|---|
| 943 |
|
|---|
| 944 | For example, if you have three `.mk' files, `a.mk', `b.mk', and
|
|---|
| 945 | `c.mk', and `$(bar)' expands to `bish bash', then the following
|
|---|
| 946 | expression
|
|---|
| 947 |
|
|---|
| 948 | include foo *.mk $(bar)
|
|---|
| 949 |
|
|---|
| 950 | is equivalent to
|
|---|
| 951 |
|
|---|
| 952 | include foo a.mk b.mk c.mk bish bash
|
|---|
| 953 |
|
|---|
| 954 | When `make' processes an `include' directive, it suspends reading of
|
|---|
| 955 | the containing makefile and reads from each listed file in turn. When
|
|---|
| 956 | that is finished, `make' resumes reading the makefile in which the
|
|---|
| 957 | directive appears.
|
|---|
| 958 |
|
|---|
| 959 | One occasion for using `include' directives is when several programs,
|
|---|
| 960 | handled by individual makefiles in various directories, need to use a
|
|---|
| 961 | common set of variable definitions (*note Setting Variables: Setting.)
|
|---|
| 962 | or pattern rules (*note Defining and Redefining Pattern Rules: Pattern
|
|---|
| 963 | Rules.).
|
|---|
| 964 |
|
|---|
| 965 | Another such occasion is when you want to generate prerequisites from
|
|---|
| 966 | source files automatically; the prerequisites can be put in a file that
|
|---|
| 967 | is included by the main makefile. This practice is generally cleaner
|
|---|
| 968 | than that of somehow appending the prerequisites to the end of the main
|
|---|
| 969 | makefile as has been traditionally done with other versions of `make'.
|
|---|
| 970 | *Note Automatic Prerequisites::.
|
|---|
| 971 |
|
|---|
| 972 | If the specified name does not start with a slash, and the file is
|
|---|
| 973 | not found in the current directory, several other directories are
|
|---|
| 974 | searched. First, any directories you have specified with the `-I' or
|
|---|
| 975 | `--include-dir' option are searched (*note Summary of Options: Options
|
|---|
| 976 | Summary.). Then the following directories (if they exist) are
|
|---|
| 977 | searched, in this order: `PREFIX/include' (normally `/usr/local/include'
|
|---|
| 978 | (1)) `/usr/gnu/include', `/usr/local/include', `/usr/include'.
|
|---|
| 979 |
|
|---|
| 980 | If an included makefile cannot be found in any of these directories,
|
|---|
| 981 | a warning message is generated, but it is not an immediately fatal
|
|---|
| 982 | error; processing of the makefile containing the `include' continues.
|
|---|
| 983 | Once it has finished reading makefiles, `make' will try to remake any
|
|---|
| 984 | that are out of date or don't exist. *Note How Makefiles Are Remade:
|
|---|
| 985 | Remaking Makefiles. Only after it has tried to find a way to remake a
|
|---|
| 986 | makefile and failed, will `make' diagnose the missing makefile as a
|
|---|
| 987 | fatal error.
|
|---|
| 988 |
|
|---|
| 989 | If you want `make' to simply ignore a makefile which does not exist
|
|---|
| 990 | and cannot be remade, with no error message, use the `-include'
|
|---|
| 991 | directive instead of `include', like this:
|
|---|
| 992 |
|
|---|
| 993 | -include FILENAMES...
|
|---|
| 994 |
|
|---|
| 995 | This acts like `include' in every way except that there is no error
|
|---|
| 996 | (not even a warning) if any of the FILENAMES do not exist. For
|
|---|
| 997 | compatibility with some other `make' implementations, `sinclude' is
|
|---|
| 998 | another name for `-include'.
|
|---|
| 999 |
|
|---|
| 1000 | ---------- Footnotes ----------
|
|---|
| 1001 |
|
|---|
| 1002 | (1) GNU Make compiled for MS-DOS and MS-Windows behaves as if PREFIX
|
|---|
| 1003 | has been defined to be the root of the DJGPP tree hierarchy.
|
|---|
| 1004 |
|
|---|
| 1005 |
|
|---|
| 1006 | File: make.info, Node: MAKEFILES Variable, Next: MAKEFILE_LIST Variable, Prev: Include, Up: Makefiles
|
|---|
| 1007 |
|
|---|
| 1008 | 3.4 The Variable `MAKEFILES'
|
|---|
| 1009 | ============================
|
|---|
| 1010 |
|
|---|
| 1011 | If the environment variable `MAKEFILES' is defined, `make' considers
|
|---|
| 1012 | its value as a list of names (separated by whitespace) of additional
|
|---|
| 1013 | makefiles to be read before the others. This works much like the
|
|---|
| 1014 | `include' directive: various directories are searched for those files
|
|---|
| 1015 | (*note Including Other Makefiles: Include.). In addition, the default
|
|---|
| 1016 | goal is never taken from one of these makefiles and it is not an error
|
|---|
| 1017 | if the files listed in `MAKEFILES' are not found.
|
|---|
| 1018 |
|
|---|
| 1019 | The main use of `MAKEFILES' is in communication between recursive
|
|---|
| 1020 | invocations of `make' (*note Recursive Use of `make': Recursion.). It
|
|---|
| 1021 | usually is not desirable to set the environment variable before a
|
|---|
| 1022 | top-level invocation of `make', because it is usually better not to
|
|---|
| 1023 | mess with a makefile from outside. However, if you are running `make'
|
|---|
| 1024 | without a specific makefile, a makefile in `MAKEFILES' can do useful
|
|---|
| 1025 | things to help the built-in implicit rules work better, such as
|
|---|
| 1026 | defining search paths (*note Directory Search::).
|
|---|
| 1027 |
|
|---|
| 1028 | Some users are tempted to set `MAKEFILES' in the environment
|
|---|
| 1029 | automatically on login, and program makefiles to expect this to be done.
|
|---|
| 1030 | This is a very bad idea, because such makefiles will fail to work if
|
|---|
| 1031 | run by anyone else. It is much better to write explicit `include'
|
|---|
| 1032 | directives in the makefiles. *Note Including Other Makefiles: Include.
|
|---|
| 1033 |
|
|---|
| 1034 |
|
|---|
| 1035 | File: make.info, Node: MAKEFILE_LIST Variable, Next: Special Variables, Prev: MAKEFILES Variable, Up: Makefiles
|
|---|
| 1036 |
|
|---|
| 1037 | 3.5 The Variable `MAKEFILE_LIST'
|
|---|
| 1038 | ================================
|
|---|
| 1039 |
|
|---|
| 1040 | As `make' reads various makefiles, including any obtained from the
|
|---|
| 1041 | `MAKEFILES' variable, the command line, the default files, or from
|
|---|
| 1042 | `include' directives, their names will be automatically appended to the
|
|---|
| 1043 | `MAKEFILE_LIST' variable. They are added right before `make' begins to
|
|---|
| 1044 | parse them.
|
|---|
| 1045 |
|
|---|
| 1046 | This means that if the first thing a makefile does is examine the
|
|---|
| 1047 | last word in this variable, it will be the name of the current makefile.
|
|---|
| 1048 | Once the current makefile has used `include', however, the last word
|
|---|
| 1049 | will be the just-included makefile.
|
|---|
| 1050 |
|
|---|
| 1051 | If a makefile named `Makefile' has this content:
|
|---|
| 1052 |
|
|---|
| 1053 | name1 := $(lastword $(MAKEFILE_LIST))
|
|---|
| 1054 |
|
|---|
| 1055 | include inc.mk
|
|---|
| 1056 |
|
|---|
| 1057 | name2 := $(lastword $(MAKEFILE_LIST))
|
|---|
| 1058 |
|
|---|
| 1059 | all:
|
|---|
| 1060 | @echo name1 = $(name1)
|
|---|
| 1061 | @echo name2 = $(name2)
|
|---|
| 1062 |
|
|---|
| 1063 | then you would expect to see this output:
|
|---|
| 1064 |
|
|---|
| 1065 | name1 = Makefile
|
|---|
| 1066 | name2 = inc.mk
|
|---|
| 1067 |
|
|---|
| 1068 | *Note Text Functions::, for more information on the `word' and
|
|---|
| 1069 | `words' functions used above. *Note The Two Flavors of Variables:
|
|---|
| 1070 | Flavors, for more information on simply-expanded (`:=') variable
|
|---|
| 1071 | definitions.
|
|---|
| 1072 |
|
|---|
| 1073 |
|
|---|
| 1074 | File: make.info, Node: Special Variables, Next: Remaking Makefiles, Prev: MAKEFILE_LIST Variable, Up: Makefiles
|
|---|
| 1075 |
|
|---|
| 1076 | 3.6 Other Special Variables
|
|---|
| 1077 | ===========================
|
|---|
| 1078 |
|
|---|
| 1079 | GNU `make' also supports other special variables. Unless otherwise
|
|---|
| 1080 | documented here, these values lose their special properties if they are
|
|---|
| 1081 | set by a makefile or on the command line.
|
|---|
| 1082 |
|
|---|
| 1083 | `.DEFAULT_GOAL'
|
|---|
| 1084 | Sets the default goal to be used if no targets were specified on
|
|---|
| 1085 | the command line (*note Arguments to Specify the Goals: Goals.).
|
|---|
| 1086 | The `.DEFAULT_GOAL' variable allows you to discover the current
|
|---|
| 1087 | default goal, restart the default goal selection algorithm by
|
|---|
| 1088 | clearing its value, or to explicitly set the default goal. The
|
|---|
| 1089 | following example illustrates these cases:
|
|---|
| 1090 |
|
|---|
| 1091 | # Query the default goal.
|
|---|
| 1092 | ifeq ($(.DEFAULT_GOAL),)
|
|---|
| 1093 | $(warning no default goal is set)
|
|---|
| 1094 | endif
|
|---|
| 1095 |
|
|---|
| 1096 | .PHONY: foo
|
|---|
| 1097 | foo: ; @echo $@
|
|---|
| 1098 |
|
|---|
| 1099 | $(warning default goal is $(.DEFAULT_GOAL))
|
|---|
| 1100 |
|
|---|
| 1101 | # Reset the default goal.
|
|---|
| 1102 | .DEFAULT_GOAL :=
|
|---|
| 1103 |
|
|---|
| 1104 | .PHONY: bar
|
|---|
| 1105 | bar: ; @echo $@
|
|---|
| 1106 |
|
|---|
| 1107 | $(warning default goal is $(.DEFAULT_GOAL))
|
|---|
| 1108 |
|
|---|
| 1109 | # Set our own.
|
|---|
| 1110 | .DEFAULT_GOAL := foo
|
|---|
| 1111 |
|
|---|
| 1112 | This makefile prints:
|
|---|
| 1113 |
|
|---|
| 1114 | no default goal is set
|
|---|
| 1115 | default goal is foo
|
|---|
| 1116 | default goal is bar
|
|---|
| 1117 | foo
|
|---|
| 1118 |
|
|---|
| 1119 | Note that assigning more than one target name to `.DEFAULT_GOAL' is
|
|---|
| 1120 | illegal and will result in an error.
|
|---|
| 1121 |
|
|---|
| 1122 | `MAKE_RESTARTS'
|
|---|
| 1123 | This variable is set only if this instance of `make' has restarted
|
|---|
| 1124 | (*note How Makefiles Are Remade: Remaking Makefiles.): it will
|
|---|
| 1125 | contain the number of times this instance has restarted. Note
|
|---|
| 1126 | this is not the same as recursion (counted by the `MAKELEVEL'
|
|---|
| 1127 | variable). You should not set, modify, or export this variable.
|
|---|
| 1128 |
|
|---|
| 1129 | `.VARIABLES'
|
|---|
| 1130 | Expands to a list of the _names_ of all global variables defined
|
|---|
| 1131 | so far. This includes variables which have empty values, as well
|
|---|
| 1132 | as built-in variables (*note Variables Used by Implicit Rules:
|
|---|
| 1133 | Implicit Variables.), but does not include any variables which are
|
|---|
| 1134 | only defined in a target-specific context. Note that any value
|
|---|
| 1135 | you assign to this variable will be ignored; it will always return
|
|---|
| 1136 | its special value.
|
|---|
| 1137 |
|
|---|
| 1138 | `.FEATURES'
|
|---|
| 1139 | Expands to a list of special features supported by this version of
|
|---|
| 1140 | `make'. Possible values include:
|
|---|
| 1141 |
|
|---|
| 1142 | `archives'
|
|---|
| 1143 | Supports `ar' (archive) files using special filename syntax.
|
|---|
| 1144 | *Note Using `make' to Update Archive Files: Archives.
|
|---|
| 1145 |
|
|---|
| 1146 | `check-symlink'
|
|---|
| 1147 | Supports the `-L' (`--check-symlink-times') flag. *Note
|
|---|
| 1148 | Summary of Options: Options Summary.
|
|---|
| 1149 |
|
|---|
| 1150 | `else-if'
|
|---|
| 1151 | Supports "else if" non-nested conditionals. *Note Syntax of
|
|---|
| 1152 | Conditionals: Conditional Syntax.
|
|---|
| 1153 |
|
|---|
| 1154 | `jobserver'
|
|---|
| 1155 | Supports "job server" enhanced parallel builds. *Note
|
|---|
| 1156 | Parallel Execution: Parallel.
|
|---|
| 1157 |
|
|---|
| 1158 | `second-expansion'
|
|---|
| 1159 | Supports secondary expansion of prerequisite lists.
|
|---|
| 1160 |
|
|---|
| 1161 | `order-only'
|
|---|
| 1162 | Supports order-only prerequisites. *Note Types of
|
|---|
| 1163 | Prerequisites: Prerequisite Types.
|
|---|
| 1164 |
|
|---|
| 1165 | `target-specific'
|
|---|
| 1166 | Supports target-specific and pattern-specific variable
|
|---|
| 1167 | assignments. *Note Target-specific Variable Values:
|
|---|
| 1168 | Target-specific.
|
|---|
| 1169 |
|
|---|
| 1170 |
|
|---|
| 1171 | `.INCLUDE_DIRS'
|
|---|
| 1172 | Expands to a list of directories that `make' searches for included
|
|---|
| 1173 | makefiles (*note Including Other Makefiles: Include.).
|
|---|
| 1174 |
|
|---|
| 1175 |
|
|---|
| 1176 |
|
|---|
| 1177 | File: make.info, Node: Remaking Makefiles, Next: Overriding Makefiles, Prev: Special Variables, Up: Makefiles
|
|---|
| 1178 |
|
|---|
| 1179 | 3.7 How Makefiles Are Remade
|
|---|
| 1180 | ============================
|
|---|
| 1181 |
|
|---|
| 1182 | Sometimes makefiles can be remade from other files, such as RCS or SCCS
|
|---|
| 1183 | files. If a makefile can be remade from other files, you probably want
|
|---|
| 1184 | `make' to get an up-to-date version of the makefile to read in.
|
|---|
| 1185 |
|
|---|
| 1186 | To this end, after reading in all makefiles, `make' will consider
|
|---|
| 1187 | each as a goal target and attempt to update it. If a makefile has a
|
|---|
| 1188 | rule which says how to update it (found either in that very makefile or
|
|---|
| 1189 | in another one) or if an implicit rule applies to it (*note Using
|
|---|
| 1190 | Implicit Rules: Implicit Rules.), it will be updated if necessary.
|
|---|
| 1191 | After all makefiles have been checked, if any have actually been
|
|---|
| 1192 | changed, `make' starts with a clean slate and reads all the makefiles
|
|---|
| 1193 | over again. (It will also attempt to update each of them over again,
|
|---|
| 1194 | but normally this will not change them again, since they are already up
|
|---|
| 1195 | to date.)
|
|---|
| 1196 |
|
|---|
| 1197 | If you know that one or more of your makefiles cannot be remade and
|
|---|
| 1198 | you want to keep `make' from performing an implicit rule search on
|
|---|
| 1199 | them, perhaps for efficiency reasons, you can use any normal method of
|
|---|
| 1200 | preventing implicit rule lookup to do so. For example, you can write an
|
|---|
| 1201 | explicit rule with the makefile as the target, and an empty command
|
|---|
| 1202 | string (*note Using Empty Commands: Empty Commands.).
|
|---|
| 1203 |
|
|---|
| 1204 | If the makefiles specify a double-colon rule to remake a file with
|
|---|
| 1205 | commands but no prerequisites, that file will always be remade (*note
|
|---|
| 1206 | Double-Colon::). In the case of makefiles, a makefile that has a
|
|---|
| 1207 | double-colon rule with commands but no prerequisites will be remade
|
|---|
| 1208 | every time `make' is run, and then again after `make' starts over and
|
|---|
| 1209 | reads the makefiles in again. This would cause an infinite loop:
|
|---|
| 1210 | `make' would constantly remake the makefile, and never do anything
|
|---|
| 1211 | else. So, to avoid this, `make' will *not* attempt to remake makefiles
|
|---|
| 1212 | which are specified as targets of a double-colon rule with commands but
|
|---|
| 1213 | no prerequisites.
|
|---|
| 1214 |
|
|---|
| 1215 | If you do not specify any makefiles to be read with `-f' or `--file'
|
|---|
| 1216 | options, `make' will try the default makefile names; *note What Name to
|
|---|
| 1217 | Give Your Makefile: Makefile Names. Unlike makefiles explicitly
|
|---|
| 1218 | requested with `-f' or `--file' options, `make' is not certain that
|
|---|
| 1219 | these makefiles should exist. However, if a default makefile does not
|
|---|
| 1220 | exist but can be created by running `make' rules, you probably want the
|
|---|
| 1221 | rules to be run so that the makefile can be used.
|
|---|
| 1222 |
|
|---|
| 1223 | Therefore, if none of the default makefiles exists, `make' will try
|
|---|
| 1224 | to make each of them in the same order in which they are searched for
|
|---|
| 1225 | (*note What Name to Give Your Makefile: Makefile Names.) until it
|
|---|
| 1226 | succeeds in making one, or it runs out of names to try. Note that it
|
|---|
| 1227 | is not an error if `make' cannot find or make any makefile; a makefile
|
|---|
| 1228 | is not always necessary.
|
|---|
| 1229 |
|
|---|
| 1230 | When you use the `-t' or `--touch' option (*note Instead of
|
|---|
| 1231 | Executing the Commands: Instead of Execution.), you would not want to
|
|---|
| 1232 | use an out-of-date makefile to decide which targets to touch. So the
|
|---|
| 1233 | `-t' option has no effect on updating makefiles; they are really
|
|---|
| 1234 | updated even if `-t' is specified. Likewise, `-q' (or `--question')
|
|---|
| 1235 | and `-n' (or `--just-print') do not prevent updating of makefiles,
|
|---|
| 1236 | because an out-of-date makefile would result in the wrong output for
|
|---|
| 1237 | other targets. Thus, `make -f mfile -n foo' will update `mfile', read
|
|---|
| 1238 | it in, and then print the commands to update `foo' and its prerequisites
|
|---|
| 1239 | without running them. The commands printed for `foo' will be those
|
|---|
| 1240 | specified in the updated contents of `mfile'.
|
|---|
| 1241 |
|
|---|
| 1242 | However, on occasion you might actually wish to prevent updating of
|
|---|
| 1243 | even the makefiles. You can do this by specifying the makefiles as
|
|---|
| 1244 | goals in the command line as well as specifying them as makefiles.
|
|---|
| 1245 | When the makefile name is specified explicitly as a goal, the options
|
|---|
| 1246 | `-t' and so on do apply to them.
|
|---|
| 1247 |
|
|---|
| 1248 | Thus, `make -f mfile -n mfile foo' would read the makefile `mfile',
|
|---|
| 1249 | print the commands needed to update it without actually running them,
|
|---|
| 1250 | and then print the commands needed to update `foo' without running
|
|---|
| 1251 | them. The commands for `foo' will be those specified by the existing
|
|---|
| 1252 | contents of `mfile'.
|
|---|
| 1253 |
|
|---|
| 1254 |
|
|---|
| 1255 | File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: Remaking Makefiles, Up: Makefiles
|
|---|
| 1256 |
|
|---|
| 1257 | 3.8 Overriding Part of Another Makefile
|
|---|
| 1258 | =======================================
|
|---|
| 1259 |
|
|---|
| 1260 | Sometimes it is useful to have a makefile that is mostly just like
|
|---|
| 1261 | another makefile. You can often use the `include' directive to include
|
|---|
| 1262 | one in the other, and add more targets or variable definitions.
|
|---|
| 1263 | However, if the two makefiles give different commands for the same
|
|---|
| 1264 | target, `make' will not let you just do this. But there is another way.
|
|---|
| 1265 |
|
|---|
| 1266 | In the containing makefile (the one that wants to include the other),
|
|---|
| 1267 | you can use a match-anything pattern rule to say that to remake any
|
|---|
| 1268 | target that cannot be made from the information in the containing
|
|---|
| 1269 | makefile, `make' should look in another makefile. *Note Pattern
|
|---|
| 1270 | Rules::, for more information on pattern rules.
|
|---|
| 1271 |
|
|---|
| 1272 | For example, if you have a makefile called `Makefile' that says how
|
|---|
| 1273 | to make the target `foo' (and other targets), you can write a makefile
|
|---|
| 1274 | called `GNUmakefile' that contains:
|
|---|
| 1275 |
|
|---|
| 1276 | foo:
|
|---|
| 1277 | frobnicate > foo
|
|---|
| 1278 |
|
|---|
| 1279 | %: force
|
|---|
| 1280 | @$(MAKE) -f Makefile $@
|
|---|
| 1281 | force: ;
|
|---|
| 1282 |
|
|---|
| 1283 | If you say `make foo', `make' will find `GNUmakefile', read it, and
|
|---|
| 1284 | see that to make `foo', it needs to run the command `frobnicate > foo'.
|
|---|
| 1285 | If you say `make bar', `make' will find no way to make `bar' in
|
|---|
| 1286 | `GNUmakefile', so it will use the commands from the pattern rule: `make
|
|---|
| 1287 | -f Makefile bar'. If `Makefile' provides a rule for updating `bar',
|
|---|
| 1288 | `make' will apply the rule. And likewise for any other target that
|
|---|
| 1289 | `GNUmakefile' does not say how to make.
|
|---|
| 1290 |
|
|---|
| 1291 | The way this works is that the pattern rule has a pattern of just
|
|---|
| 1292 | `%', so it matches any target whatever. The rule specifies a
|
|---|
| 1293 | prerequisite `force', to guarantee that the commands will be run even
|
|---|
| 1294 | if the target file already exists. We give `force' target empty
|
|---|
| 1295 | commands to prevent `make' from searching for an implicit rule to build
|
|---|
| 1296 | it--otherwise it would apply the same match-anything rule to `force'
|
|---|
| 1297 | itself and create a prerequisite loop!
|
|---|
| 1298 |
|
|---|
| 1299 |
|
|---|
| 1300 | File: make.info, Node: Reading Makefiles, Next: Secondary Expansion, Prev: Overriding Makefiles, Up: Makefiles
|
|---|
| 1301 |
|
|---|
| 1302 | 3.9 How `make' Reads a Makefile
|
|---|
| 1303 | ===============================
|
|---|
| 1304 |
|
|---|
| 1305 | GNU `make' does its work in two distinct phases. During the first
|
|---|
| 1306 | phase it reads all the makefiles, included makefiles, etc. and
|
|---|
| 1307 | internalizes all the variables and their values, implicit and explicit
|
|---|
| 1308 | rules, and constructs a dependency graph of all the targets and their
|
|---|
| 1309 | prerequisites. During the second phase, `make' uses these internal
|
|---|
| 1310 | structures to determine what targets will need to be rebuilt and to
|
|---|
| 1311 | invoke the rules necessary to do so.
|
|---|
| 1312 |
|
|---|
| 1313 | It's important to understand this two-phase approach because it has a
|
|---|
| 1314 | direct impact on how variable and function expansion happens; this is
|
|---|
| 1315 | often a source of some confusion when writing makefiles. Here we will
|
|---|
| 1316 | present a summary of the phases in which expansion happens for different
|
|---|
| 1317 | constructs within the makefile. We say that expansion is "immediate"
|
|---|
| 1318 | if it happens during the first phase: in this case `make' will expand
|
|---|
| 1319 | any variables or functions in that section of a construct as the
|
|---|
| 1320 | makefile is parsed. We say that expansion is "deferred" if expansion
|
|---|
| 1321 | is not performed immediately. Expansion of deferred construct is not
|
|---|
| 1322 | performed until either the construct appears later in an immediate
|
|---|
| 1323 | context, or until the second phase.
|
|---|
| 1324 |
|
|---|
| 1325 | You may not be familiar with some of these constructs yet. You can
|
|---|
| 1326 | reference this section as you become familiar with them, in later
|
|---|
| 1327 | chapters.
|
|---|
| 1328 |
|
|---|
| 1329 | Variable Assignment
|
|---|
| 1330 | -------------------
|
|---|
| 1331 |
|
|---|
| 1332 | Variable definitions are parsed as follows:
|
|---|
| 1333 |
|
|---|
| 1334 | IMMEDIATE = DEFERRED
|
|---|
| 1335 | IMMEDIATE ?= DEFERRED
|
|---|
| 1336 | IMMEDIATE := IMMEDIATE
|
|---|
| 1337 | IMMEDIATE += DEFERRED or IMMEDIATE
|
|---|
| 1338 |
|
|---|
| 1339 | define IMMEDIATE
|
|---|
| 1340 | DEFERRED
|
|---|
| 1341 | endef
|
|---|
| 1342 |
|
|---|
| 1343 | For the append operator, `+=', the right-hand side is considered
|
|---|
| 1344 | immediate if the variable was previously set as a simple variable
|
|---|
| 1345 | (`:='), and deferred otherwise.
|
|---|
| 1346 |
|
|---|
| 1347 | Conditional Statements
|
|---|
| 1348 | ----------------------
|
|---|
| 1349 |
|
|---|
| 1350 | All instances of conditional syntax are parsed immediately, in their
|
|---|
| 1351 | entirety; this includes the `ifdef', `ifeq', `ifndef', and `ifneq'
|
|---|
| 1352 | forms. Of course this means that automatic variables cannot be used in
|
|---|
| 1353 | conditional statements, as automatic variables are not set until the
|
|---|
| 1354 | command script for that rule is invoked. If you need to use automatic
|
|---|
| 1355 | variables in a conditional you _must_ use shell conditional syntax, in
|
|---|
| 1356 | your command script proper, for these tests, not `make' conditionals.
|
|---|
| 1357 |
|
|---|
| 1358 | Rule Definition
|
|---|
| 1359 | ---------------
|
|---|
| 1360 |
|
|---|
| 1361 | A rule is always expanded the same way, regardless of the form:
|
|---|
| 1362 |
|
|---|
| 1363 | IMMEDIATE : IMMEDIATE ; DEFERRED
|
|---|
| 1364 | DEFERRED
|
|---|
| 1365 |
|
|---|
| 1366 | That is, the target and prerequisite sections are expanded
|
|---|
| 1367 | immediately, and the commands used to construct the target are always
|
|---|
| 1368 | deferred. This general rule is true for explicit rules, pattern rules,
|
|---|
| 1369 | suffix rules, static pattern rules, and simple prerequisite definitions.
|
|---|
| 1370 |
|
|---|
| 1371 |
|
|---|
| 1372 | File: make.info, Node: Secondary Expansion, Prev: Reading Makefiles, Up: Makefiles
|
|---|
| 1373 |
|
|---|
| 1374 | 3.10 Secondary Expansion
|
|---|
| 1375 | ========================
|
|---|
| 1376 |
|
|---|
| 1377 | In the previous section we learned that GNU `make' works in two
|
|---|
| 1378 | distinct phases: a read-in phase and a target-update phase (*note How
|
|---|
| 1379 | `make' Reads a Makefile: Reading Makefiles.). GNU make also has the
|
|---|
| 1380 | ability to enable a _second expansion_ of the prerequisites (only) for
|
|---|
| 1381 | some or all targets defined in the makefile. In order for this second
|
|---|
| 1382 | expansion to occur, the special target `.SECONDEXPANSION' must be
|
|---|
| 1383 | defined before the first prerequisite list that makes use of this
|
|---|
| 1384 | feature.
|
|---|
| 1385 |
|
|---|
| 1386 | If that special target is defined then in between the two phases
|
|---|
| 1387 | mentioned above, right at the end of the read-in phase, all the
|
|---|
| 1388 | prerequisites of the targets defined after the special target are
|
|---|
| 1389 | expanded a _second time_. In most circumstances this secondary
|
|---|
| 1390 | expansion will have no effect, since all variable and function
|
|---|
| 1391 | references will have been expanded during the initial parsing of the
|
|---|
| 1392 | makefiles. In order to take advantage of the secondary expansion phase
|
|---|
| 1393 | of the parser, then, it's necessary to _escape_ the variable or
|
|---|
| 1394 | function reference in the makefile. In this case the first expansion
|
|---|
| 1395 | merely un-escapes the reference but doesn't expand it, and expansion is
|
|---|
| 1396 | left to the secondary expansion phase. For example, consider this
|
|---|
| 1397 | makefile:
|
|---|
| 1398 |
|
|---|
| 1399 | .SECONDEXPANSION:
|
|---|
| 1400 | ONEVAR = onefile
|
|---|
| 1401 | TWOVAR = twofile
|
|---|
| 1402 | myfile: $(ONEVAR) $$(TWOVAR)
|
|---|
| 1403 |
|
|---|
| 1404 | After the first expansion phase the prerequisites list of the
|
|---|
| 1405 | `myfile' target will be `onefile' and `$(TWOVAR)'; the first
|
|---|
| 1406 | (unescaped) variable reference to ONEVAR is expanded, while the second
|
|---|
| 1407 | (escaped) variable reference is simply unescaped, without being
|
|---|
| 1408 | recognized as a variable reference. Now during the secondary expansion
|
|---|
| 1409 | the first word is expanded again but since it contains no variable or
|
|---|
| 1410 | function references it remains the static value `onefile', while the
|
|---|
| 1411 | second word is now a normal reference to the variable TWOVAR, which is
|
|---|
| 1412 | expanded to the value `twofile'. The final result is that there are
|
|---|
| 1413 | two prerequisites, `onefile' and `twofile'.
|
|---|
| 1414 |
|
|---|
| 1415 | Obviously, this is not a very interesting case since the same result
|
|---|
| 1416 | could more easily have been achieved simply by having both variables
|
|---|
| 1417 | appear, unescaped, in the prerequisites list. One difference becomes
|
|---|
| 1418 | apparent if the variables are reset; consider this example:
|
|---|
| 1419 |
|
|---|
| 1420 | .SECONDEXPANSION:
|
|---|
| 1421 | AVAR = top
|
|---|
| 1422 | onefile: $(AVAR)
|
|---|
| 1423 | twofile: $$(AVAR)
|
|---|
| 1424 | AVAR = bottom
|
|---|
| 1425 |
|
|---|
| 1426 | Here the prerequisite of `onefile' will be expanded immediately, and
|
|---|
| 1427 | resolve to the value `top', while the prerequisite of `twofile' will
|
|---|
| 1428 | not be full expanded until the secondary expansion and yield a value of
|
|---|
| 1429 | `bottom'.
|
|---|
| 1430 |
|
|---|
| 1431 | This is marginally more exciting, but the true power of this feature
|
|---|
| 1432 | only becomes apparent when you discover that secondary expansions
|
|---|
| 1433 | always take place within the scope of the automatic variables for that
|
|---|
| 1434 | target. This means that you can use variables such as `$@', `$*', etc.
|
|---|
| 1435 | during the second expansion and they will have their expected values,
|
|---|
| 1436 | just as in the command script. All you have to do is defer the
|
|---|
| 1437 | expansion by escaping the `$'. Also, secondary expansion occurs for
|
|---|
| 1438 | both explicit and implicit (pattern) rules. Knowing this, the possible
|
|---|
| 1439 | uses for this feature increase dramatically. For example:
|
|---|
| 1440 |
|
|---|
| 1441 | .SECONDEXPANSION:
|
|---|
| 1442 | main_OBJS := main.o try.o test.o
|
|---|
| 1443 | lib_OBJS := lib.o api.o
|
|---|
| 1444 |
|
|---|
| 1445 | main lib: $$($$@_OBJS)
|
|---|
| 1446 |
|
|---|
| 1447 | Here, after the initial expansion the prerequisites of both the
|
|---|
| 1448 | `main' and `lib' targets will be `$($@_OBJS)'. During the secondary
|
|---|
| 1449 | expansion, the `$@' variable is set to the name of the target and so
|
|---|
| 1450 | the expansion for the `main' target will yield `$(main_OBJS)', or
|
|---|
| 1451 | `main.o try.o test.o', while the secondary expansion for the `lib'
|
|---|
| 1452 | target will yield `$(lib_OBJS)', or `lib.o api.o'.
|
|---|
| 1453 |
|
|---|
| 1454 | You can also mix functions here, as long as they are properly
|
|---|
| 1455 | escaped:
|
|---|
| 1456 |
|
|---|
| 1457 | main_SRCS := main.c try.c test.c
|
|---|
| 1458 | lib_SRCS := lib.c api.c
|
|---|
| 1459 |
|
|---|
| 1460 | .SECONDEXPANSION:
|
|---|
| 1461 | main lib: $$(patsubst %.c,%.o,$$($$@_SRCS))
|
|---|
| 1462 |
|
|---|
| 1463 | This version allows users to specify source files rather than object
|
|---|
| 1464 | files, but gives the same resulting prerequisites list as the previous
|
|---|
| 1465 | example.
|
|---|
| 1466 |
|
|---|
| 1467 | Evaluation of automatic variables during the secondary expansion
|
|---|
| 1468 | phase, especially of the target name variable `$$@', behaves similarly
|
|---|
| 1469 | to evaluation within command scripts. However, there are some subtle
|
|---|
| 1470 | differences and "corner cases" which come into play for the different
|
|---|
| 1471 | types of rule definitions that `make' understands. The subtleties of
|
|---|
| 1472 | using the different automatic variables are described below.
|
|---|
| 1473 |
|
|---|
| 1474 | Secondary Expansion of Explicit Rules
|
|---|
| 1475 | -------------------------------------
|
|---|
| 1476 |
|
|---|
| 1477 | During the secondary expansion of explicit rules, `$$@' and `$$%'
|
|---|
| 1478 | evaluate, respectively, to the file name of the target and, when the
|
|---|
| 1479 | target is an archive member, the target member name. The `$$<'
|
|---|
| 1480 | variable evaluates to the first prerequisite in the first rule for this
|
|---|
| 1481 | target. `$$^' and `$$+' evaluate to the list of all prerequisites of
|
|---|
| 1482 | rules _that have already appeared_ for the same target (`$$+' with
|
|---|
| 1483 | repetitions and `$$^' without). The following example will help
|
|---|
| 1484 | illustrate these behaviors:
|
|---|
| 1485 |
|
|---|
| 1486 | .SECONDEXPANSION:
|
|---|
| 1487 |
|
|---|
| 1488 | foo: foo.1 bar.1 $$< $$^ $$+ # line #1
|
|---|
| 1489 |
|
|---|
| 1490 | foo: foo.2 bar.2 $$< $$^ $$+ # line #2
|
|---|
| 1491 |
|
|---|
| 1492 | foo: foo.3 bar.3 $$< $$^ $$+ # line #3
|
|---|
| 1493 |
|
|---|
| 1494 | In the first prerequisite list, all three variables (`$$<', `$$^',
|
|---|
| 1495 | and `$$+') expand to the empty string. In the second, they will have
|
|---|
| 1496 | values `foo.1', `foo.1 bar.1', and `foo.1 bar.1' respectively. In the
|
|---|
| 1497 | third they will have values `foo.1', `foo.1 bar.1 foo.2 bar.2', and
|
|---|
| 1498 | `foo.1 bar.1 foo.2 bar.2' respectively.
|
|---|
| 1499 |
|
|---|
| 1500 | Rules undergo secondary expansion in makefile order, except that the
|
|---|
| 1501 | rule with the command script is always evaluated last.
|
|---|
| 1502 |
|
|---|
| 1503 | The variables `$$?' and `$$*' are not available and expand to the
|
|---|
| 1504 | empty string.
|
|---|
| 1505 |
|
|---|
| 1506 | Secondary Expansion of Static Pattern Rules
|
|---|
| 1507 | -------------------------------------------
|
|---|
| 1508 |
|
|---|
| 1509 | Rules for secondary expansion of static pattern rules are identical to
|
|---|
| 1510 | those for explicit rules, above, with one exception: for static pattern
|
|---|
| 1511 | rules the `$$*' variable is set to the pattern stem. As with explicit
|
|---|
| 1512 | rules, `$$?' is not available and expands to the empty string.
|
|---|
| 1513 |
|
|---|
| 1514 | Secondary Expansion of Implicit Rules
|
|---|
| 1515 | -------------------------------------
|
|---|
| 1516 |
|
|---|
| 1517 | As `make' searches for an implicit rule, it substitutes the stem and
|
|---|
| 1518 | then performs secondary expansion for every rule with a matching target
|
|---|
| 1519 | pattern. The value of the automatic variables is derived in the same
|
|---|
| 1520 | fashion as for static pattern rules. As an example:
|
|---|
| 1521 |
|
|---|
| 1522 | .SECONDEXPANSION:
|
|---|
| 1523 |
|
|---|
| 1524 | foo: bar
|
|---|
| 1525 |
|
|---|
| 1526 | foo foz: fo%: bo%
|
|---|
| 1527 |
|
|---|
| 1528 | %oo: $$< $$^ $$+ $$*
|
|---|
| 1529 |
|
|---|
| 1530 | When the implicit rule is tried for target `foo', `$$<' expands to
|
|---|
| 1531 | `bar', `$$^' expands to `bar boo', `$$+' also expands to `bar boo', and
|
|---|
| 1532 | `$$*' expands to `f'.
|
|---|
| 1533 |
|
|---|
| 1534 | Note that the directory prefix (D), as described in *Note Implicit
|
|---|
| 1535 | Rule Search Algorithm: Implicit Rule Search, is appended (after
|
|---|
| 1536 | expansion) to all the patterns in the prerequisites list. As an
|
|---|
| 1537 | example:
|
|---|
| 1538 |
|
|---|
| 1539 | .SECONDEXPANSION:
|
|---|
| 1540 |
|
|---|
| 1541 | /tmp/foo.o:
|
|---|
| 1542 |
|
|---|
| 1543 | %.o: $$(addsuffix /%.c,foo bar) foo.h
|
|---|
| 1544 |
|
|---|
| 1545 | The prerequisite list after the secondary expansion and directory
|
|---|
| 1546 | prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c
|
|---|
| 1547 | foo.h'. If you are not interested in this reconstruction, you can use
|
|---|
| 1548 | `$$*' instead of `%' in the prerequisites list.
|
|---|
| 1549 |
|
|---|
| 1550 |
|
|---|
| 1551 | File: make.info, Node: Rules, Next: Commands, Prev: Makefiles, Up: Top
|
|---|
| 1552 |
|
|---|
| 1553 | 4 Writing Rules
|
|---|
| 1554 | ***************
|
|---|
| 1555 |
|
|---|
| 1556 | A "rule" appears in the makefile and says when and how to remake
|
|---|
| 1557 | certain files, called the rule's "targets" (most often only one per
|
|---|
| 1558 | rule). It lists the other files that are the "prerequisites" of the
|
|---|
| 1559 | target, and "commands" to use to create or update the target.
|
|---|
| 1560 |
|
|---|
| 1561 | The order of rules is not significant, except for determining the
|
|---|
| 1562 | "default goal": the target for `make' to consider, if you do not
|
|---|
| 1563 | otherwise specify one. The default goal is the target of the first
|
|---|
| 1564 | rule in the first makefile. If the first rule has multiple targets,
|
|---|
| 1565 | only the first target is taken as the default. There are two
|
|---|
| 1566 | exceptions: a target starting with a period is not a default unless it
|
|---|
| 1567 | contains one or more slashes, `/', as well; and, a target that defines
|
|---|
| 1568 | a pattern rule has no effect on the default goal. (*Note Defining and
|
|---|
| 1569 | Redefining Pattern Rules: Pattern Rules.)
|
|---|
| 1570 |
|
|---|
| 1571 | Therefore, we usually write the makefile so that the first rule is
|
|---|
| 1572 | the one for compiling the entire program or all the programs described
|
|---|
| 1573 | by the makefile (often with a target called `all'). *Note Arguments to
|
|---|
| 1574 | Specify the Goals: Goals.
|
|---|
| 1575 |
|
|---|
| 1576 | * Menu:
|
|---|
| 1577 |
|
|---|
| 1578 | * Rule Example:: An example explained.
|
|---|
| 1579 | * Rule Syntax:: General syntax explained.
|
|---|
| 1580 | * Prerequisite Types:: There are two types of prerequisites.
|
|---|
| 1581 | * Wildcards:: Using wildcard characters such as `*'.
|
|---|
| 1582 | * Directory Search:: Searching other directories for source files.
|
|---|
| 1583 | * Phony Targets:: Using a target that is not a real file's name.
|
|---|
| 1584 | * Force Targets:: You can use a target without commands
|
|---|
| 1585 | or prerequisites to mark other targets
|
|---|
| 1586 | as phony.
|
|---|
| 1587 | * Empty Targets:: When only the date matters and the
|
|---|
| 1588 | files are empty.
|
|---|
| 1589 | * Special Targets:: Targets with special built-in meanings.
|
|---|
| 1590 | * Multiple Targets:: When to make use of several targets in a rule.
|
|---|
| 1591 | * Multiple Rules:: How to use several rules with the same target.
|
|---|
| 1592 | * Static Pattern:: Static pattern rules apply to multiple targets
|
|---|
| 1593 | and can vary the prerequisites according to
|
|---|
| 1594 | the target name.
|
|---|
| 1595 | * Double-Colon:: How to use a special kind of rule to allow
|
|---|
| 1596 | several independent rules for one target.
|
|---|
| 1597 | * Automatic Prerequisites:: How to automatically generate rules giving
|
|---|
| 1598 | prerequisites from source files themselves.
|
|---|
| 1599 |
|
|---|
| 1600 |
|
|---|
| 1601 | File: make.info, Node: Rule Example, Next: Rule Syntax, Prev: Rules, Up: Rules
|
|---|
| 1602 |
|
|---|
| 1603 | 4.1 Rule Example
|
|---|
| 1604 | ================
|
|---|
| 1605 |
|
|---|
| 1606 | Here is an example of a rule:
|
|---|
| 1607 |
|
|---|
| 1608 | foo.o : foo.c defs.h # module for twiddling the frobs
|
|---|
| 1609 | cc -c -g foo.c
|
|---|
| 1610 |
|
|---|
| 1611 | Its target is `foo.o' and its prerequisites are `foo.c' and
|
|---|
| 1612 | `defs.h'. It has one command, which is `cc -c -g foo.c'. The command
|
|---|
| 1613 | line starts with a tab to identify it as a command.
|
|---|
| 1614 |
|
|---|
| 1615 | This rule says two things:
|
|---|
| 1616 |
|
|---|
| 1617 | * How to decide whether `foo.o' is out of date: it is out of date if
|
|---|
| 1618 | it does not exist, or if either `foo.c' or `defs.h' is more recent
|
|---|
| 1619 | than it.
|
|---|
| 1620 |
|
|---|
| 1621 | * How to update the file `foo.o': by running `cc' as stated. The
|
|---|
| 1622 | command does not explicitly mention `defs.h', but we presume that
|
|---|
| 1623 | `foo.c' includes it, and that that is why `defs.h' was added to
|
|---|
| 1624 | the prerequisites.
|
|---|
| 1625 |
|
|---|
| 1626 |
|
|---|
| 1627 | File: make.info, Node: Rule Syntax, Next: Prerequisite Types, Prev: Rule Example, Up: Rules
|
|---|
| 1628 |
|
|---|
| 1629 | 4.2 Rule Syntax
|
|---|
| 1630 | ===============
|
|---|
| 1631 |
|
|---|
| 1632 | In general, a rule looks like this:
|
|---|
| 1633 |
|
|---|
| 1634 | TARGETS : PREREQUISITES
|
|---|
| 1635 | COMMAND
|
|---|
| 1636 | ...
|
|---|
| 1637 |
|
|---|
| 1638 | or like this:
|
|---|
| 1639 |
|
|---|
| 1640 | TARGETS : PREREQUISITES ; COMMAND
|
|---|
| 1641 | COMMAND
|
|---|
| 1642 | ...
|
|---|
| 1643 |
|
|---|
| 1644 | The TARGETS are file names, separated by spaces. Wildcard
|
|---|
| 1645 | characters may be used (*note Using Wildcard Characters in File Names:
|
|---|
| 1646 | Wildcards.) and a name of the form `A(M)' represents member M in
|
|---|
| 1647 | archive file A (*note Archive Members as Targets: Archive Members.).
|
|---|
| 1648 | Usually there is only one target per rule, but occasionally there is a
|
|---|
| 1649 | reason to have more (*note Multiple Targets in a Rule: Multiple
|
|---|
| 1650 | Targets.).
|
|---|
| 1651 |
|
|---|
| 1652 | The COMMAND lines start with a tab character. The first command may
|
|---|
| 1653 | appear on the line after the prerequisites, with a tab character, or may
|
|---|
| 1654 | appear on the same line, with a semicolon. Either way, the effect is
|
|---|
| 1655 | the same. There are other differences in the syntax of command lines.
|
|---|
| 1656 | *Note Writing the Commands in Rules: Commands.
|
|---|
| 1657 |
|
|---|
| 1658 | Because dollar signs are used to start `make' variable references,
|
|---|
| 1659 | if you really want a dollar sign in a target or prerequisite you must
|
|---|
| 1660 | write two of them, `$$' (*note How to Use Variables: Using Variables.).
|
|---|
| 1661 | If you have enabled secondary expansion (*note Secondary Expansion::)
|
|---|
| 1662 | and you want a literal dollar sign in the prerequisites lise, you must
|
|---|
| 1663 | actually write _four_ dollar signs (`$$$$').
|
|---|
| 1664 |
|
|---|
| 1665 | You may split a long line by inserting a backslash followed by a
|
|---|
| 1666 | newline, but this is not required, as `make' places no limit on the
|
|---|
| 1667 | length of a line in a makefile.
|
|---|
| 1668 |
|
|---|
| 1669 | A rule tells `make' two things: when the targets are out of date,
|
|---|
| 1670 | and how to update them when necessary.
|
|---|
| 1671 |
|
|---|
| 1672 | The criterion for being out of date is specified in terms of the
|
|---|
| 1673 | PREREQUISITES, which consist of file names separated by spaces.
|
|---|
| 1674 | (Wildcards and archive members (*note Archives::) are allowed here too.)
|
|---|
| 1675 | A target is out of date if it does not exist or if it is older than any
|
|---|
| 1676 | of the prerequisites (by comparison of last-modification times). The
|
|---|
| 1677 | idea is that the contents of the target file are computed based on
|
|---|
| 1678 | information in the prerequisites, so if any of the prerequisites
|
|---|
| 1679 | changes, the contents of the existing target file are no longer
|
|---|
| 1680 | necessarily valid.
|
|---|
| 1681 |
|
|---|
| 1682 | How to update is specified by COMMANDS. These are lines to be
|
|---|
| 1683 | executed by the shell (normally `sh'), but with some extra features
|
|---|
| 1684 | (*note Writing the Commands in Rules: Commands.).
|
|---|
| 1685 |
|
|---|
| 1686 |
|
|---|
| 1687 | File: make.info, Node: Prerequisite Types, Next: Wildcards, Prev: Rule Syntax, Up: Rules
|
|---|
| 1688 |
|
|---|
| 1689 | 4.3 Types of Prerequisites
|
|---|
| 1690 | ==========================
|
|---|
| 1691 |
|
|---|
| 1692 | There are actually two different types of prerequisites understood by
|
|---|
| 1693 | GNU `make': normal prerequisites such as described in the previous
|
|---|
| 1694 | section, and "order-only" prerequisites. A normal prerequisite makes
|
|---|
| 1695 | two statements: first, it imposes an order of execution of build
|
|---|
| 1696 | commands: any commands necessary to build any of a target's
|
|---|
| 1697 | prerequisites will be fully executed before any commands necessary to
|
|---|
| 1698 | build the target. Second, it imposes a dependency relationship: if any
|
|---|
| 1699 | prerequisite is newer than the target, then the target is considered
|
|---|
| 1700 | out-of-date and must be rebuilt.
|
|---|
| 1701 |
|
|---|
| 1702 | Normally, this is exactly what you want: if a target's prerequisite
|
|---|
| 1703 | is updated, then the target should also be updated.
|
|---|
| 1704 |
|
|---|
| 1705 | Occasionally, however, you have a situation where you want to impose
|
|---|
| 1706 | a specific ordering on the rules to be invoked _without_ forcing the
|
|---|
| 1707 | target to be updated if one of those rules is executed. In that case,
|
|---|
| 1708 | you want to define "order-only" prerequisites. Order-only
|
|---|
| 1709 | prerequisites can be specified by placing a pipe symbol (`|') in the
|
|---|
| 1710 | prerequisites list: any prerequisites to the left of the pipe symbol
|
|---|
| 1711 | are normal; any prerequisites to the right are order-only:
|
|---|
| 1712 |
|
|---|
| 1713 | TARGETS : NORMAL-PREREQUISITES | ORDER-ONLY-PREREQUISITES
|
|---|
| 1714 |
|
|---|
| 1715 | The normal prerequisites section may of course be empty. Also, you
|
|---|
| 1716 | may still declare multiple lines of prerequisites for the same target:
|
|---|
| 1717 | they are appended appropriately. Note that if you declare the same
|
|---|
| 1718 | file to be both a normal and an order-only prerequisite, the normal
|
|---|
| 1719 | prerequisite takes precedence (since they are a strict superset of the
|
|---|
| 1720 | behavior of an order-only prerequisite).
|
|---|
| 1721 |
|
|---|
| 1722 |
|
|---|
| 1723 | File: make.info, Node: Wildcards, Next: Directory Search, Prev: Prerequisite Types, Up: Rules
|
|---|
| 1724 |
|
|---|
| 1725 | 4.4 Using Wildcard Characters in File Names
|
|---|
| 1726 | ===========================================
|
|---|
| 1727 |
|
|---|
| 1728 | A single file name can specify many files using "wildcard characters".
|
|---|
| 1729 | The wildcard characters in `make' are `*', `?' and `[...]', the same as
|
|---|
| 1730 | in the Bourne shell. For example, `*.c' specifies a list of all the
|
|---|
| 1731 | files (in the working directory) whose names end in `.c'.
|
|---|
| 1732 |
|
|---|
| 1733 | The character `~' at the beginning of a file name also has special
|
|---|
| 1734 | significance. If alone, or followed by a slash, it represents your home
|
|---|
| 1735 | directory. For example `~/bin' expands to `/home/you/bin'. If the `~'
|
|---|
| 1736 | is followed by a word, the string represents the home directory of the
|
|---|
| 1737 | user named by that word. For example `~john/bin' expands to
|
|---|
| 1738 | `/home/john/bin'. On systems which don't have a home directory for
|
|---|
| 1739 | each user (such as MS-DOS or MS-Windows), this functionality can be
|
|---|
| 1740 | simulated by setting the environment variable HOME.
|
|---|
| 1741 |
|
|---|
| 1742 | Wildcard expansion is performed by `make' automatically in targets
|
|---|
| 1743 | and in prerequisites. In commands the shell is responsible for
|
|---|
| 1744 | wildcard expansion. In other contexts, wildcard expansion happens only
|
|---|
| 1745 | if you request it explicitly with the `wildcard' function.
|
|---|
| 1746 |
|
|---|
| 1747 | The special significance of a wildcard character can be turned off by
|
|---|
| 1748 | preceding it with a backslash. Thus, `foo\*bar' would refer to a
|
|---|
| 1749 | specific file whose name consists of `foo', an asterisk, and `bar'.
|
|---|
| 1750 |
|
|---|
| 1751 | * Menu:
|
|---|
| 1752 |
|
|---|
| 1753 | * Wildcard Examples:: Several examples
|
|---|
| 1754 | * Wildcard Pitfall:: Problems to avoid.
|
|---|
| 1755 | * Wildcard Function:: How to cause wildcard expansion where
|
|---|
| 1756 | it does not normally take place.
|
|---|
| 1757 |
|
|---|
| 1758 |
|
|---|
| 1759 | File: make.info, Node: Wildcard Examples, Next: Wildcard Pitfall, Prev: Wildcards, Up: Wildcards
|
|---|
| 1760 |
|
|---|
| 1761 | 4.4.1 Wildcard Examples
|
|---|
| 1762 | -----------------------
|
|---|
| 1763 |
|
|---|
| 1764 | Wildcards can be used in the commands of a rule, where they are expanded
|
|---|
| 1765 | by the shell. For example, here is a rule to delete all the object
|
|---|
| 1766 | files:
|
|---|
| 1767 |
|
|---|
| 1768 | clean:
|
|---|
| 1769 | rm -f *.o
|
|---|
| 1770 |
|
|---|
| 1771 | Wildcards are also useful in the prerequisites of a rule. With the
|
|---|
| 1772 | following rule in the makefile, `make print' will print all the `.c'
|
|---|
| 1773 | files that have changed since the last time you printed them:
|
|---|
| 1774 |
|
|---|
| 1775 | print: *.c
|
|---|
| 1776 | lpr -p $?
|
|---|
| 1777 | touch print
|
|---|
| 1778 |
|
|---|
| 1779 | This rule uses `print' as an empty target file; see *Note Empty Target
|
|---|
| 1780 | Files to Record Events: Empty Targets. (The automatic variable `$?' is
|
|---|
| 1781 | used to print only those files that have changed; see *Note Automatic
|
|---|
| 1782 | Variables::.)
|
|---|
| 1783 |
|
|---|
| 1784 | Wildcard expansion does not happen when you define a variable.
|
|---|
| 1785 | Thus, if you write this:
|
|---|
| 1786 |
|
|---|
| 1787 | objects = *.o
|
|---|
| 1788 |
|
|---|
| 1789 | then the value of the variable `objects' is the actual string `*.o'.
|
|---|
| 1790 | However, if you use the value of `objects' in a target, prerequisite or
|
|---|
| 1791 | command, wildcard expansion will take place at that time. To set
|
|---|
| 1792 | `objects' to the expansion, instead use:
|
|---|
| 1793 |
|
|---|
| 1794 | objects := $(wildcard *.o)
|
|---|
| 1795 |
|
|---|
| 1796 | *Note Wildcard Function::.
|
|---|
| 1797 |
|
|---|
| 1798 |
|
|---|
| 1799 | File: make.info, Node: Wildcard Pitfall, Next: Wildcard Function, Prev: Wildcard Examples, Up: Wildcards
|
|---|
| 1800 |
|
|---|
| 1801 | 4.4.2 Pitfalls of Using Wildcards
|
|---|
| 1802 | ---------------------------------
|
|---|
| 1803 |
|
|---|
| 1804 | Now here is an example of a naive way of using wildcard expansion, that
|
|---|
| 1805 | does not do what you would intend. Suppose you would like to say that
|
|---|
| 1806 | the executable file `foo' is made from all the object files in the
|
|---|
| 1807 | directory, and you write this:
|
|---|
| 1808 |
|
|---|
| 1809 | objects = *.o
|
|---|
| 1810 |
|
|---|
| 1811 | foo : $(objects)
|
|---|
| 1812 | cc -o foo $(CFLAGS) $(objects)
|
|---|
| 1813 |
|
|---|
| 1814 | The value of `objects' is the actual string `*.o'. Wildcard expansion
|
|---|
| 1815 | happens in the rule for `foo', so that each _existing_ `.o' file
|
|---|
| 1816 | becomes a prerequisite of `foo' and will be recompiled if necessary.
|
|---|
| 1817 |
|
|---|
| 1818 | But what if you delete all the `.o' files? When a wildcard matches
|
|---|
| 1819 | no files, it is left as it is, so then `foo' will depend on the
|
|---|
| 1820 | oddly-named file `*.o'. Since no such file is likely to exist, `make'
|
|---|
| 1821 | will give you an error saying it cannot figure out how to make `*.o'.
|
|---|
| 1822 | This is not what you want!
|
|---|
| 1823 |
|
|---|
| 1824 | Actually it is possible to obtain the desired result with wildcard
|
|---|
| 1825 | expansion, but you need more sophisticated techniques, including the
|
|---|
| 1826 | `wildcard' function and string substitution. *Note The Function
|
|---|
| 1827 | `wildcard': Wildcard Function.
|
|---|
| 1828 |
|
|---|
| 1829 | Microsoft operating systems (MS-DOS and MS-Windows) use backslashes
|
|---|
| 1830 | to separate directories in pathnames, like so:
|
|---|
| 1831 |
|
|---|
| 1832 | c:\foo\bar\baz.c
|
|---|
| 1833 |
|
|---|
| 1834 | This is equivalent to the Unix-style `c:/foo/bar/baz.c' (the `c:'
|
|---|
| 1835 | part is the so-called drive letter). When `make' runs on these
|
|---|
| 1836 | systems, it supports backslashes as well as the Unix-style forward
|
|---|
| 1837 | slashes in pathnames. However, this support does _not_ include the
|
|---|
| 1838 | wildcard expansion, where backslash is a quote character. Therefore,
|
|---|
| 1839 | you _must_ use Unix-style slashes in these cases.
|
|---|
| 1840 |
|
|---|
| 1841 |
|
|---|
| 1842 | File: make.info, Node: Wildcard Function, Prev: Wildcard Pitfall, Up: Wildcards
|
|---|
| 1843 |
|
|---|
| 1844 | 4.4.3 The Function `wildcard'
|
|---|
| 1845 | -----------------------------
|
|---|
| 1846 |
|
|---|
| 1847 | Wildcard expansion happens automatically in rules. But wildcard
|
|---|
| 1848 | expansion does not normally take place when a variable is set, or
|
|---|
| 1849 | inside the arguments of a function. If you want to do wildcard
|
|---|
| 1850 | expansion in such places, you need to use the `wildcard' function, like
|
|---|
| 1851 | this:
|
|---|
| 1852 |
|
|---|
| 1853 | $(wildcard PATTERN...)
|
|---|
| 1854 |
|
|---|
| 1855 | This string, used anywhere in a makefile, is replaced by a
|
|---|
| 1856 | space-separated list of names of existing files that match one of the
|
|---|
| 1857 | given file name patterns. If no existing file name matches a pattern,
|
|---|
| 1858 | then that pattern is omitted from the output of the `wildcard'
|
|---|
| 1859 | function. Note that this is different from how unmatched wildcards
|
|---|
| 1860 | behave in rules, where they are used verbatim rather than ignored
|
|---|
| 1861 | (*note Wildcard Pitfall::).
|
|---|
| 1862 |
|
|---|
| 1863 | One use of the `wildcard' function is to get a list of all the C
|
|---|
| 1864 | source files in a directory, like this:
|
|---|
| 1865 |
|
|---|
| 1866 | $(wildcard *.c)
|
|---|
| 1867 |
|
|---|
| 1868 | We can change the list of C source files into a list of object files
|
|---|
| 1869 | by replacing the `.c' suffix with `.o' in the result, like this:
|
|---|
| 1870 |
|
|---|
| 1871 | $(patsubst %.c,%.o,$(wildcard *.c))
|
|---|
| 1872 |
|
|---|
| 1873 | (Here we have used another function, `patsubst'. *Note Functions for
|
|---|
| 1874 | String Substitution and Analysis: Text Functions.)
|
|---|
| 1875 |
|
|---|
| 1876 | Thus, a makefile to compile all C source files in the directory and
|
|---|
| 1877 | then link them together could be written as follows:
|
|---|
| 1878 |
|
|---|
| 1879 | objects := $(patsubst %.c,%.o,$(wildcard *.c))
|
|---|
| 1880 |
|
|---|
| 1881 | foo : $(objects)
|
|---|
| 1882 | cc -o foo $(objects)
|
|---|
| 1883 |
|
|---|
| 1884 | (This takes advantage of the implicit rule for compiling C programs, so
|
|---|
| 1885 | there is no need to write explicit rules for compiling the files.
|
|---|
| 1886 | *Note The Two Flavors of Variables: Flavors, for an explanation of
|
|---|
| 1887 | `:=', which is a variant of `='.)
|
|---|
| 1888 |
|
|---|
| 1889 |
|
|---|
| 1890 | File: make.info, Node: Directory Search, Next: Phony Targets, Prev: Wildcards, Up: Rules
|
|---|
| 1891 |
|
|---|
| 1892 | 4.5 Searching Directories for Prerequisites
|
|---|
| 1893 | ===========================================
|
|---|
| 1894 |
|
|---|
| 1895 | For large systems, it is often desirable to put sources in a separate
|
|---|
| 1896 | directory from the binaries. The "directory search" features of `make'
|
|---|
| 1897 | facilitate this by searching several directories automatically to find
|
|---|
| 1898 | a prerequisite. When you redistribute the files among directories, you
|
|---|
| 1899 | do not need to change the individual rules, just the search paths.
|
|---|
| 1900 |
|
|---|
| 1901 | * Menu:
|
|---|
| 1902 |
|
|---|
| 1903 | * General Search:: Specifying a search path that applies
|
|---|
| 1904 | to every prerequisite.
|
|---|
| 1905 | * Selective Search:: Specifying a search path
|
|---|
| 1906 | for a specified class of names.
|
|---|
| 1907 | * Search Algorithm:: When and how search paths are applied.
|
|---|
| 1908 | * Commands/Search:: How to write shell commands that work together
|
|---|
| 1909 | with search paths.
|
|---|
| 1910 | * Implicit/Search:: How search paths affect implicit rules.
|
|---|
| 1911 | * Libraries/Search:: Directory search for link libraries.
|
|---|
| 1912 |
|
|---|
| 1913 |
|
|---|
| 1914 | File: make.info, Node: General Search, Next: Selective Search, Prev: Directory Search, Up: Directory Search
|
|---|
| 1915 |
|
|---|
| 1916 | 4.5.1 `VPATH': Search Path for All Prerequisites
|
|---|
| 1917 | ------------------------------------------------
|
|---|
| 1918 |
|
|---|
| 1919 | The value of the `make' variable `VPATH' specifies a list of
|
|---|
| 1920 | directories that `make' should search. Most often, the directories are
|
|---|
| 1921 | expected to contain prerequisite files that are not in the current
|
|---|
| 1922 | directory; however, `make' uses `VPATH' as a search list for both
|
|---|
| 1923 | prerequisites and targets of rules.
|
|---|
| 1924 |
|
|---|
| 1925 | Thus, if a file that is listed as a target or prerequisite does not
|
|---|
| 1926 | exist in the current directory, `make' searches the directories listed
|
|---|
| 1927 | in `VPATH' for a file with that name. If a file is found in one of
|
|---|
| 1928 | them, that file may become the prerequisite (see below). Rules may then
|
|---|
| 1929 | specify the names of files in the prerequisite list as if they all
|
|---|
| 1930 | existed in the current directory. *Note Writing Shell Commands with
|
|---|
| 1931 | Directory Search: Commands/Search.
|
|---|
| 1932 |
|
|---|
| 1933 | In the `VPATH' variable, directory names are separated by colons or
|
|---|
| 1934 | blanks. The order in which directories are listed is the order followed
|
|---|
| 1935 | by `make' in its search. (On MS-DOS and MS-Windows, semi-colons are
|
|---|
| 1936 | used as separators of directory names in `VPATH', since the colon can
|
|---|
| 1937 | be used in the pathname itself, after the drive letter.)
|
|---|
| 1938 |
|
|---|
| 1939 | For example,
|
|---|
| 1940 |
|
|---|
| 1941 | VPATH = src:../headers
|
|---|
| 1942 |
|
|---|
| 1943 | specifies a path containing two directories, `src' and `../headers',
|
|---|
| 1944 | which `make' searches in that order.
|
|---|
| 1945 |
|
|---|
| 1946 | With this value of `VPATH', the following rule,
|
|---|
| 1947 |
|
|---|
| 1948 | foo.o : foo.c
|
|---|
| 1949 |
|
|---|
| 1950 | is interpreted as if it were written like this:
|
|---|
| 1951 |
|
|---|
| 1952 | foo.o : src/foo.c
|
|---|
| 1953 |
|
|---|
| 1954 | assuming the file `foo.c' does not exist in the current directory but
|
|---|
| 1955 | is found in the directory `src'.
|
|---|
| 1956 |
|
|---|
| 1957 |
|
|---|
| 1958 | File: make.info, Node: Selective Search, Next: Search Algorithm, Prev: General Search, Up: Directory Search
|
|---|
| 1959 |
|
|---|
| 1960 | 4.5.2 The `vpath' Directive
|
|---|
| 1961 | ---------------------------
|
|---|
| 1962 |
|
|---|
| 1963 | Similar to the `VPATH' variable, but more selective, is the `vpath'
|
|---|
| 1964 | directive (note lower case), which allows you to specify a search path
|
|---|
| 1965 | for a particular class of file names: those that match a particular
|
|---|
| 1966 | pattern. Thus you can supply certain search directories for one class
|
|---|
| 1967 | of file names and other directories (or none) for other file names.
|
|---|
| 1968 |
|
|---|
| 1969 | There are three forms of the `vpath' directive:
|
|---|
| 1970 |
|
|---|
| 1971 | `vpath PATTERN DIRECTORIES'
|
|---|
| 1972 | Specify the search path DIRECTORIES for file names that match
|
|---|
| 1973 | PATTERN.
|
|---|
| 1974 |
|
|---|
| 1975 | The search path, DIRECTORIES, is a list of directories to be
|
|---|
| 1976 | searched, separated by colons (semi-colons on MS-DOS and
|
|---|
| 1977 | MS-Windows) or blanks, just like the search path used in the
|
|---|
| 1978 | `VPATH' variable.
|
|---|
| 1979 |
|
|---|
| 1980 | `vpath PATTERN'
|
|---|
| 1981 | Clear out the search path associated with PATTERN.
|
|---|
| 1982 |
|
|---|
| 1983 | `vpath'
|
|---|
| 1984 | Clear all search paths previously specified with `vpath'
|
|---|
| 1985 | directives.
|
|---|
| 1986 |
|
|---|
| 1987 | A `vpath' pattern is a string containing a `%' character. The
|
|---|
| 1988 | string must match the file name of a prerequisite that is being searched
|
|---|
| 1989 | for, the `%' character matching any sequence of zero or more characters
|
|---|
| 1990 | (as in pattern rules; *note Defining and Redefining Pattern Rules:
|
|---|
| 1991 | Pattern Rules.). For example, `%.h' matches files that end in `.h'.
|
|---|
| 1992 | (If there is no `%', the pattern must match the prerequisite exactly,
|
|---|
| 1993 | which is not useful very often.)
|
|---|
| 1994 |
|
|---|
| 1995 | `%' characters in a `vpath' directive's pattern can be quoted with
|
|---|
| 1996 | preceding backslashes (`\'). Backslashes that would otherwise quote
|
|---|
| 1997 | `%' characters can be quoted with more backslashes. Backslashes that
|
|---|
| 1998 | quote `%' characters or other backslashes are removed from the pattern
|
|---|
| 1999 | before it is compared to file names. Backslashes that are not in
|
|---|
| 2000 | danger of quoting `%' characters go unmolested.
|
|---|
| 2001 |
|
|---|
| 2002 | When a prerequisite fails to exist in the current directory, if the
|
|---|
| 2003 | PATTERN in a `vpath' directive matches the name of the prerequisite
|
|---|
| 2004 | file, then the DIRECTORIES in that directive are searched just like
|
|---|
| 2005 | (and before) the directories in the `VPATH' variable.
|
|---|
| 2006 |
|
|---|
| 2007 | For example,
|
|---|
| 2008 |
|
|---|
| 2009 | vpath %.h ../headers
|
|---|
| 2010 |
|
|---|
| 2011 | tells `make' to look for any prerequisite whose name ends in `.h' in
|
|---|
| 2012 | the directory `../headers' if the file is not found in the current
|
|---|
| 2013 | directory.
|
|---|
| 2014 |
|
|---|
| 2015 | If several `vpath' patterns match the prerequisite file's name, then
|
|---|
| 2016 | `make' processes each matching `vpath' directive one by one, searching
|
|---|
| 2017 | all the directories mentioned in each directive. `make' handles
|
|---|
| 2018 | multiple `vpath' directives in the order in which they appear in the
|
|---|
| 2019 | makefile; multiple directives with the same pattern are independent of
|
|---|
| 2020 | each other.
|
|---|
| 2021 |
|
|---|
| 2022 | Thus,
|
|---|
| 2023 |
|
|---|
| 2024 | vpath %.c foo
|
|---|
| 2025 | vpath % blish
|
|---|
| 2026 | vpath %.c bar
|
|---|
| 2027 |
|
|---|
| 2028 | will look for a file ending in `.c' in `foo', then `blish', then `bar',
|
|---|
| 2029 | while
|
|---|
| 2030 |
|
|---|
| 2031 | vpath %.c foo:bar
|
|---|
| 2032 | vpath % blish
|
|---|
| 2033 |
|
|---|
| 2034 | will look for a file ending in `.c' in `foo', then `bar', then `blish'.
|
|---|
| 2035 |
|
|---|
| 2036 |
|
|---|
| 2037 | File: make.info, Node: Search Algorithm, Next: Commands/Search, Prev: Selective Search, Up: Directory Search
|
|---|
| 2038 |
|
|---|
| 2039 | 4.5.3 How Directory Searches are Performed
|
|---|
| 2040 | ------------------------------------------
|
|---|
| 2041 |
|
|---|
| 2042 | When a prerequisite is found through directory search, regardless of
|
|---|
| 2043 | type (general or selective), the pathname located may not be the one
|
|---|
| 2044 | that `make' actually provides you in the prerequisite list. Sometimes
|
|---|
| 2045 | the path discovered through directory search is thrown away.
|
|---|
| 2046 |
|
|---|
| 2047 | The algorithm `make' uses to decide whether to keep or abandon a
|
|---|
| 2048 | path found via directory search is as follows:
|
|---|
| 2049 |
|
|---|
| 2050 | 1. If a target file does not exist at the path specified in the
|
|---|
| 2051 | makefile, directory search is performed.
|
|---|
| 2052 |
|
|---|
| 2053 | 2. If the directory search is successful, that path is kept and this
|
|---|
| 2054 | file is tentatively stored as the target.
|
|---|
| 2055 |
|
|---|
| 2056 | 3. All prerequisites of this target are examined using this same
|
|---|
| 2057 | method.
|
|---|
| 2058 |
|
|---|
| 2059 | 4. After processing the prerequisites, the target may or may not need
|
|---|
| 2060 | to be rebuilt:
|
|---|
| 2061 |
|
|---|
| 2062 | a. If the target does _not_ need to be rebuilt, the path to the
|
|---|
| 2063 | file found during directory search is used for any
|
|---|
| 2064 | prerequisite lists which contain this target. In short, if
|
|---|
| 2065 | `make' doesn't need to rebuild the target then you use the
|
|---|
| 2066 | path found via directory search.
|
|---|
| 2067 |
|
|---|
| 2068 | b. If the target _does_ need to be rebuilt (is out-of-date), the
|
|---|
| 2069 | pathname found during directory search is _thrown away_, and
|
|---|
| 2070 | the target is rebuilt using the file name specified in the
|
|---|
| 2071 | makefile. In short, if `make' must rebuild, then the target
|
|---|
| 2072 | is rebuilt locally, not in the directory found via directory
|
|---|
| 2073 | search.
|
|---|
| 2074 |
|
|---|
| 2075 | This algorithm may seem complex, but in practice it is quite often
|
|---|
| 2076 | exactly what you want.
|
|---|
| 2077 |
|
|---|
| 2078 | Other versions of `make' use a simpler algorithm: if the file does
|
|---|
| 2079 | not exist, and it is found via directory search, then that pathname is
|
|---|
| 2080 | always used whether or not the target needs to be built. Thus, if the
|
|---|
| 2081 | target is rebuilt it is created at the pathname discovered during
|
|---|
| 2082 | directory search.
|
|---|
| 2083 |
|
|---|
| 2084 | If, in fact, this is the behavior you want for some or all of your
|
|---|
| 2085 | directories, you can use the `GPATH' variable to indicate this to
|
|---|
| 2086 | `make'.
|
|---|
| 2087 |
|
|---|
| 2088 | `GPATH' has the same syntax and format as `VPATH' (that is, a space-
|
|---|
| 2089 | or colon-delimited list of pathnames). If an out-of-date target is
|
|---|
| 2090 | found by directory search in a directory that also appears in `GPATH',
|
|---|
| 2091 | then that pathname is not thrown away. The target is rebuilt using the
|
|---|
| 2092 | expanded path.
|
|---|
| 2093 |
|
|---|
| 2094 |
|
|---|
| 2095 | File: make.info, Node: Commands/Search, Next: Implicit/Search, Prev: Search Algorithm, Up: Directory Search
|
|---|
| 2096 |
|
|---|
| 2097 | 4.5.4 Writing Shell Commands with Directory Search
|
|---|
| 2098 | --------------------------------------------------
|
|---|
| 2099 |
|
|---|
| 2100 | When a prerequisite is found in another directory through directory
|
|---|
| 2101 | search, this cannot change the commands of the rule; they will execute
|
|---|
| 2102 | as written. Therefore, you must write the commands with care so that
|
|---|
| 2103 | they will look for the prerequisite in the directory where `make' finds
|
|---|
| 2104 | it.
|
|---|
| 2105 |
|
|---|
| 2106 | This is done with the "automatic variables" such as `$^' (*note
|
|---|
| 2107 | Automatic Variables::). For instance, the value of `$^' is a list of
|
|---|
| 2108 | all the prerequisites of the rule, including the names of the
|
|---|
| 2109 | directories in which they were found, and the value of `$@' is the
|
|---|
| 2110 | target. Thus:
|
|---|
| 2111 |
|
|---|
| 2112 | foo.o : foo.c
|
|---|
| 2113 | cc -c $(CFLAGS) $^ -o $@
|
|---|
| 2114 |
|
|---|
| 2115 | (The variable `CFLAGS' exists so you can specify flags for C
|
|---|
| 2116 | compilation by implicit rules; we use it here for consistency so it will
|
|---|
| 2117 | affect all C compilations uniformly; *note Variables Used by Implicit
|
|---|
| 2118 | Rules: Implicit Variables.)
|
|---|
| 2119 |
|
|---|
| 2120 | Often the prerequisites include header files as well, which you do
|
|---|
| 2121 | not want to mention in the commands. The automatic variable `$<' is
|
|---|
| 2122 | just the first prerequisite:
|
|---|
| 2123 |
|
|---|
| 2124 | VPATH = src:../headers
|
|---|
| 2125 | foo.o : foo.c defs.h hack.h
|
|---|
| 2126 | cc -c $(CFLAGS) $< -o $@
|
|---|
| 2127 |
|
|---|
| 2128 |
|
|---|
| 2129 | File: make.info, Node: Implicit/Search, Next: Libraries/Search, Prev: Commands/Search, Up: Directory Search
|
|---|
| 2130 |
|
|---|
| 2131 | 4.5.5 Directory Search and Implicit Rules
|
|---|
| 2132 | -----------------------------------------
|
|---|
| 2133 |
|
|---|
| 2134 | The search through the directories specified in `VPATH' or with `vpath'
|
|---|
| 2135 | also happens during consideration of implicit rules (*note Using
|
|---|
| 2136 | Implicit Rules: Implicit Rules.).
|
|---|
| 2137 |
|
|---|
| 2138 | For example, when a file `foo.o' has no explicit rule, `make'
|
|---|
| 2139 | considers implicit rules, such as the built-in rule to compile `foo.c'
|
|---|
| 2140 | if that file exists. If such a file is lacking in the current
|
|---|
| 2141 | directory, the appropriate directories are searched for it. If `foo.c'
|
|---|
| 2142 | exists (or is mentioned in the makefile) in any of the directories, the
|
|---|
| 2143 | implicit rule for C compilation is applied.
|
|---|
| 2144 |
|
|---|
| 2145 | The commands of implicit rules normally use automatic variables as a
|
|---|
| 2146 | matter of necessity; consequently they will use the file names found by
|
|---|
| 2147 | directory search with no extra effort.
|
|---|
| 2148 |
|
|---|
| 2149 |
|
|---|
| 2150 | File: make.info, Node: Libraries/Search, Prev: Implicit/Search, Up: Directory Search
|
|---|
| 2151 |
|
|---|
| 2152 | 4.5.6 Directory Search for Link Libraries
|
|---|
| 2153 | -----------------------------------------
|
|---|
| 2154 |
|
|---|
| 2155 | Directory search applies in a special way to libraries used with the
|
|---|
| 2156 | linker. This special feature comes into play when you write a
|
|---|
| 2157 | prerequisite whose name is of the form `-lNAME'. (You can tell
|
|---|
| 2158 | something strange is going on here because the prerequisite is normally
|
|---|
| 2159 | the name of a file, and the _file name_ of a library generally looks
|
|---|
| 2160 | like `libNAME.a', not like `-lNAME'.)
|
|---|
| 2161 |
|
|---|
| 2162 | When a prerequisite's name has the form `-lNAME', `make' handles it
|
|---|
| 2163 | specially by searching for the file `libNAME.so' in the current
|
|---|
| 2164 | directory, in directories specified by matching `vpath' search paths
|
|---|
| 2165 | and the `VPATH' search path, and then in the directories `/lib',
|
|---|
| 2166 | `/usr/lib', and `PREFIX/lib' (normally `/usr/local/lib', but
|
|---|
| 2167 | MS-DOS/MS-Windows versions of `make' behave as if PREFIX is defined to
|
|---|
| 2168 | be the root of the DJGPP installation tree).
|
|---|
| 2169 |
|
|---|
| 2170 | If that file is not found, then the file `libNAME.a' is searched
|
|---|
| 2171 | for, in the same directories as above.
|
|---|
| 2172 |
|
|---|
| 2173 | For example, if there is a `/usr/lib/libcurses.a' library on your
|
|---|
| 2174 | system (and no `/usr/lib/libcurses.so' file), then
|
|---|
| 2175 |
|
|---|
| 2176 | foo : foo.c -lcurses
|
|---|
| 2177 | cc $^ -o $@
|
|---|
| 2178 |
|
|---|
| 2179 | would cause the command `cc foo.c /usr/lib/libcurses.a -o foo' to be
|
|---|
| 2180 | executed when `foo' is older than `foo.c' or than
|
|---|
| 2181 | `/usr/lib/libcurses.a'.
|
|---|
| 2182 |
|
|---|
| 2183 | Although the default set of files to be searched for is `libNAME.so'
|
|---|
| 2184 | and `libNAME.a', this is customizable via the `.LIBPATTERNS' variable.
|
|---|
| 2185 | Each word in the value of this variable is a pattern string. When a
|
|---|
| 2186 | prerequisite like `-lNAME' is seen, `make' will replace the percent in
|
|---|
| 2187 | each pattern in the list with NAME and perform the above directory
|
|---|
| 2188 | searches using that library filename. If no library is found, the next
|
|---|
| 2189 | word in the list will be used.
|
|---|
| 2190 |
|
|---|
| 2191 | The default value for `.LIBPATTERNS' is `lib%.so lib%.a', which
|
|---|
| 2192 | provides the default behavior described above.
|
|---|
| 2193 |
|
|---|
| 2194 | You can turn off link library expansion completely by setting this
|
|---|
| 2195 | variable to an empty value.
|
|---|
| 2196 |
|
|---|
| 2197 |
|
|---|
| 2198 | File: make.info, Node: Phony Targets, Next: Force Targets, Prev: Directory Search, Up: Rules
|
|---|
| 2199 |
|
|---|
| 2200 | 4.6 Phony Targets
|
|---|
| 2201 | =================
|
|---|
| 2202 |
|
|---|
| 2203 | A phony target is one that is not really the name of a file. It is
|
|---|
| 2204 | just a name for some commands to be executed when you make an explicit
|
|---|
| 2205 | request. There are two reasons to use a phony target: to avoid a
|
|---|
| 2206 | conflict with a file of the same name, and to improve performance.
|
|---|
| 2207 |
|
|---|
| 2208 | If you write a rule whose commands will not create the target file,
|
|---|
| 2209 | the commands will be executed every time the target comes up for
|
|---|
| 2210 | remaking. Here is an example:
|
|---|
| 2211 |
|
|---|
| 2212 | clean:
|
|---|
| 2213 | rm *.o temp
|
|---|
| 2214 |
|
|---|
| 2215 | Because the `rm' command does not create a file named `clean', probably
|
|---|
| 2216 | no such file will ever exist. Therefore, the `rm' command will be
|
|---|
| 2217 | executed every time you say `make clean'.
|
|---|
| 2218 |
|
|---|
| 2219 | The phony target will cease to work if anything ever does create a
|
|---|
| 2220 | file named `clean' in this directory. Since it has no prerequisites,
|
|---|
| 2221 | the file `clean' would inevitably be considered up to date, and its
|
|---|
| 2222 | commands would not be executed. To avoid this problem, you can
|
|---|
| 2223 | explicitly declare the target to be phony, using the special target
|
|---|
| 2224 | `.PHONY' (*note Special Built-in Target Names: Special Targets.) as
|
|---|
| 2225 | follows:
|
|---|
| 2226 |
|
|---|
| 2227 | .PHONY : clean
|
|---|
| 2228 |
|
|---|
| 2229 | Once this is done, `make clean' will run the commands regardless of
|
|---|
| 2230 | whether there is a file named `clean'.
|
|---|
| 2231 |
|
|---|
| 2232 | Since it knows that phony targets do not name actual files that
|
|---|
| 2233 | could be remade from other files, `make' skips the implicit rule search
|
|---|
| 2234 | for phony targets (*note Implicit Rules::). This is why declaring a
|
|---|
| 2235 | target phony is good for performance, even if you are not worried about
|
|---|
| 2236 | the actual file existing.
|
|---|
| 2237 |
|
|---|
| 2238 | Thus, you first write the line that states that `clean' is a phony
|
|---|
| 2239 | target, then you write the rule, like this:
|
|---|
| 2240 |
|
|---|
| 2241 | .PHONY: clean
|
|---|
| 2242 | clean:
|
|---|
| 2243 | rm *.o temp
|
|---|
| 2244 |
|
|---|
| 2245 | Another example of the usefulness of phony targets is in conjunction
|
|---|
| 2246 | with recursive invocations of `make' (for more information, see *Note
|
|---|
| 2247 | Recursive Use of `make': Recursion.). In this case the makefile will
|
|---|
| 2248 | often contain a variable which lists a number of subdirectories to be
|
|---|
| 2249 | built. One way to handle this is with one rule whose command is a
|
|---|
| 2250 | shell loop over the subdirectories, like this:
|
|---|
| 2251 |
|
|---|
| 2252 | SUBDIRS = foo bar baz
|
|---|
| 2253 |
|
|---|
| 2254 | subdirs:
|
|---|
| 2255 | for dir in $(SUBDIRS); do \
|
|---|
| 2256 | $(MAKE) -C $$dir; \
|
|---|
| 2257 | done
|
|---|
| 2258 |
|
|---|
| 2259 | There are a few problems with this method, however. First, any error
|
|---|
| 2260 | detected in a submake is not noted by this rule, so it will continue to
|
|---|
| 2261 | build the rest of the directories even when one fails. This can be
|
|---|
| 2262 | overcome by adding shell commands to note the error and exit, but then
|
|---|
| 2263 | it will do so even if `make' is invoked with the `-k' option, which is
|
|---|
| 2264 | unfortunate. Second, and perhaps more importantly, you cannot take
|
|---|
| 2265 | advantage of `make''s ability to build targets in parallel (*note
|
|---|
| 2266 | Parallel Execution: Parallel.), since there is only one rule.
|
|---|
| 2267 |
|
|---|
| 2268 | By declaring the subdirectories as phony targets (you must do this as
|
|---|
| 2269 | the subdirectory obviously always exists; otherwise it won't be built)
|
|---|
| 2270 | you can remove these problems:
|
|---|
| 2271 |
|
|---|
| 2272 | SUBDIRS = foo bar baz
|
|---|
| 2273 |
|
|---|
| 2274 | .PHONY: subdirs $(SUBDIRS)
|
|---|
| 2275 |
|
|---|
| 2276 | subdirs: $(SUBDIRS)
|
|---|
| 2277 |
|
|---|
| 2278 | $(SUBDIRS):
|
|---|
| 2279 | $(MAKE) -C $@
|
|---|
| 2280 |
|
|---|
| 2281 | foo: baz
|
|---|
| 2282 |
|
|---|
| 2283 | Here we've also declared that the `foo' subdirectory cannot be built
|
|---|
| 2284 | until after the `baz' subdirectory is complete; this kind of
|
|---|
| 2285 | relationship declaration is particularly important when attempting
|
|---|
| 2286 | parallel builds.
|
|---|
| 2287 |
|
|---|
| 2288 | A phony target should not be a prerequisite of a real target file;
|
|---|
| 2289 | if it is, its commands are run every time `make' goes to update that
|
|---|
| 2290 | file. As long as a phony target is never a prerequisite of a real
|
|---|
| 2291 | target, the phony target commands will be executed only when the phony
|
|---|
| 2292 | target is a specified goal (*note Arguments to Specify the Goals:
|
|---|
| 2293 | Goals.).
|
|---|
| 2294 |
|
|---|
| 2295 | Phony targets can have prerequisites. When one directory contains
|
|---|
| 2296 | multiple programs, it is most convenient to describe all of the
|
|---|
| 2297 | programs in one makefile `./Makefile'. Since the target remade by
|
|---|
| 2298 | default will be the first one in the makefile, it is common to make
|
|---|
| 2299 | this a phony target named `all' and give it, as prerequisites, all the
|
|---|
| 2300 | individual programs. For example:
|
|---|
| 2301 |
|
|---|
| 2302 | all : prog1 prog2 prog3
|
|---|
| 2303 | .PHONY : all
|
|---|
| 2304 |
|
|---|
| 2305 | prog1 : prog1.o utils.o
|
|---|
| 2306 | cc -o prog1 prog1.o utils.o
|
|---|
| 2307 |
|
|---|
| 2308 | prog2 : prog2.o
|
|---|
| 2309 | cc -o prog2 prog2.o
|
|---|
| 2310 |
|
|---|
| 2311 | prog3 : prog3.o sort.o utils.o
|
|---|
| 2312 | cc -o prog3 prog3.o sort.o utils.o
|
|---|
| 2313 |
|
|---|
| 2314 | Now you can say just `make' to remake all three programs, or specify as
|
|---|
| 2315 | arguments the ones to remake (as in `make prog1 prog3'). Phoniness is
|
|---|
| 2316 | not inherited: the prerequisites of a phony target are not themselves
|
|---|
| 2317 | phony, unless explicitly declared to be so.
|
|---|
| 2318 |
|
|---|
| 2319 | When one phony target is a prerequisite of another, it serves as a
|
|---|
| 2320 | subroutine of the other. For example, here `make cleanall' will delete
|
|---|
| 2321 | the object files, the difference files, and the file `program':
|
|---|
| 2322 |
|
|---|
| 2323 | .PHONY: cleanall cleanobj cleandiff
|
|---|
| 2324 |
|
|---|
| 2325 | cleanall : cleanobj cleandiff
|
|---|
| 2326 | rm program
|
|---|
| 2327 |
|
|---|
| 2328 | cleanobj :
|
|---|
| 2329 | rm *.o
|
|---|
| 2330 |
|
|---|
| 2331 | cleandiff :
|
|---|
| 2332 | rm *.diff
|
|---|
| 2333 |
|
|---|
| 2334 |
|
|---|
| 2335 | File: make.info, Node: Force Targets, Next: Empty Targets, Prev: Phony Targets, Up: Rules
|
|---|
| 2336 |
|
|---|
| 2337 | 4.7 Rules without Commands or Prerequisites
|
|---|
| 2338 | ===========================================
|
|---|
| 2339 |
|
|---|
| 2340 | If a rule has no prerequisites or commands, and the target of the rule
|
|---|
| 2341 | is a nonexistent file, then `make' imagines this target to have been
|
|---|
| 2342 | updated whenever its rule is run. This implies that all targets
|
|---|
| 2343 | depending on this one will always have their commands run.
|
|---|
| 2344 |
|
|---|
| 2345 | An example will illustrate this:
|
|---|
| 2346 |
|
|---|
| 2347 | clean: FORCE
|
|---|
| 2348 | rm $(objects)
|
|---|
| 2349 | FORCE:
|
|---|
| 2350 |
|
|---|
| 2351 | Here the target `FORCE' satisfies the special conditions, so the
|
|---|
| 2352 | target `clean' that depends on it is forced to run its commands. There
|
|---|
| 2353 | is nothing special about the name `FORCE', but that is one name
|
|---|
| 2354 | commonly used this way.
|
|---|
| 2355 |
|
|---|
| 2356 | As you can see, using `FORCE' this way has the same results as using
|
|---|
| 2357 | `.PHONY: clean'.
|
|---|
| 2358 |
|
|---|
| 2359 | Using `.PHONY' is more explicit and more efficient. However, other
|
|---|
| 2360 | versions of `make' do not support `.PHONY'; thus `FORCE' appears in
|
|---|
| 2361 | many makefiles. *Note Phony Targets::.
|
|---|
| 2362 |
|
|---|
| 2363 |
|
|---|
| 2364 | File: make.info, Node: Empty Targets, Next: Special Targets, Prev: Force Targets, Up: Rules
|
|---|
| 2365 |
|
|---|
| 2366 | 4.8 Empty Target Files to Record Events
|
|---|
| 2367 | =======================================
|
|---|
| 2368 |
|
|---|
| 2369 | The "empty target" is a variant of the phony target; it is used to hold
|
|---|
| 2370 | commands for an action that you request explicitly from time to time.
|
|---|
| 2371 | Unlike a phony target, this target file can really exist; but the file's
|
|---|
| 2372 | contents do not matter, and usually are empty.
|
|---|
| 2373 |
|
|---|
| 2374 | The purpose of the empty target file is to record, with its
|
|---|
| 2375 | last-modification time, when the rule's commands were last executed. It
|
|---|
| 2376 | does so because one of the commands is a `touch' command to update the
|
|---|
| 2377 | target file.
|
|---|
| 2378 |
|
|---|
| 2379 | The empty target file should have some prerequisites (otherwise it
|
|---|
| 2380 | doesn't make sense). When you ask to remake the empty target, the
|
|---|
| 2381 | commands are executed if any prerequisite is more recent than the
|
|---|
| 2382 | target; in other words, if a prerequisite has changed since the last
|
|---|
| 2383 | time you remade the target. Here is an example:
|
|---|
| 2384 |
|
|---|
| 2385 | print: foo.c bar.c
|
|---|
| 2386 | lpr -p $?
|
|---|
| 2387 | touch print
|
|---|
| 2388 |
|
|---|
| 2389 | With this rule, `make print' will execute the `lpr' command if either
|
|---|
| 2390 | source file has changed since the last `make print'. The automatic
|
|---|
| 2391 | variable `$?' is used to print only those files that have changed
|
|---|
| 2392 | (*note Automatic Variables::).
|
|---|
| 2393 |
|
|---|
| 2394 |
|
|---|
| 2395 | File: make.info, Node: Special Targets, Next: Multiple Targets, Prev: Empty Targets, Up: Rules
|
|---|
| 2396 |
|
|---|
| 2397 | 4.9 Special Built-in Target Names
|
|---|
| 2398 | =================================
|
|---|
| 2399 |
|
|---|
| 2400 | Certain names have special meanings if they appear as targets.
|
|---|
| 2401 |
|
|---|
| 2402 | `.PHONY'
|
|---|
| 2403 | The prerequisites of the special target `.PHONY' are considered to
|
|---|
| 2404 | be phony targets. When it is time to consider such a target,
|
|---|
| 2405 | `make' will run its commands unconditionally, regardless of
|
|---|
| 2406 | whether a file with that name exists or what its last-modification
|
|---|
| 2407 | time is. *Note Phony Targets: Phony Targets.
|
|---|
| 2408 |
|
|---|
| 2409 | `.SUFFIXES'
|
|---|
| 2410 | The prerequisites of the special target `.SUFFIXES' are the list
|
|---|
| 2411 | of suffixes to be used in checking for suffix rules. *Note
|
|---|
| 2412 | Old-Fashioned Suffix Rules: Suffix Rules.
|
|---|
| 2413 |
|
|---|
| 2414 | `.DEFAULT'
|
|---|
| 2415 | The commands specified for `.DEFAULT' are used for any target for
|
|---|
| 2416 | which no rules are found (either explicit rules or implicit rules).
|
|---|
| 2417 | *Note Last Resort::. If `.DEFAULT' commands are specified, every
|
|---|
| 2418 | file mentioned as a prerequisite, but not as a target in a rule,
|
|---|
| 2419 | will have these commands executed on its behalf. *Note Implicit
|
|---|
| 2420 | Rule Search Algorithm: Implicit Rule Search.
|
|---|
| 2421 |
|
|---|
| 2422 | `.PRECIOUS'
|
|---|
| 2423 | The targets which `.PRECIOUS' depends on are given the following
|
|---|
| 2424 | special treatment: if `make' is killed or interrupted during the
|
|---|
| 2425 | execution of their commands, the target is not deleted. *Note
|
|---|
| 2426 | Interrupting or Killing `make': Interrupts. Also, if the target
|
|---|
| 2427 | is an intermediate file, it will not be deleted after it is no
|
|---|
| 2428 | longer needed, as is normally done. *Note Chains of Implicit
|
|---|
| 2429 | Rules: Chained Rules. In this latter respect it overlaps with the
|
|---|
| 2430 | `.SECONDARY' special target.
|
|---|
| 2431 |
|
|---|
| 2432 | You can also list the target pattern of an implicit rule (such as
|
|---|
| 2433 | `%.o') as a prerequisite file of the special target `.PRECIOUS' to
|
|---|
| 2434 | preserve intermediate files created by rules whose target patterns
|
|---|
| 2435 | match that file's name.
|
|---|
| 2436 |
|
|---|
| 2437 | `.INTERMEDIATE'
|
|---|
| 2438 | The targets which `.INTERMEDIATE' depends on are treated as
|
|---|
| 2439 | intermediate files. *Note Chains of Implicit Rules: Chained Rules.
|
|---|
| 2440 | `.INTERMEDIATE' with no prerequisites has no effect.
|
|---|
| 2441 |
|
|---|
| 2442 | `.SECONDARY'
|
|---|
| 2443 | The targets which `.SECONDARY' depends on are treated as
|
|---|
| 2444 | intermediate files, except that they are never automatically
|
|---|
| 2445 | deleted. *Note Chains of Implicit Rules: Chained Rules.
|
|---|
| 2446 |
|
|---|
| 2447 | `.SECONDARY' with no prerequisites causes all targets to be treated
|
|---|
| 2448 | as secondary (i.e., no target is removed because it is considered
|
|---|
| 2449 | intermediate).
|
|---|
| 2450 |
|
|---|
| 2451 | `.SECONDEXPANSION'
|
|---|
| 2452 | If `.SECONDEXPANSION' is mentioned as a target anywhere in the
|
|---|
| 2453 | makefile, then all prerequisite lists defined _after_ it appears
|
|---|
| 2454 | will be expanded a second time after all makefiles have been read
|
|---|
| 2455 | in. *Note Secondary Expansion: Secondary Expansion.
|
|---|
| 2456 |
|
|---|
| 2457 | The prerequisites of the special target `.SUFFIXES' are the list
|
|---|
| 2458 | of suffixes to be used in checking for suffix rules. *Note
|
|---|
| 2459 | Old-Fashioned Suffix Rules: Suffix Rules.
|
|---|
| 2460 |
|
|---|
| 2461 | `.DELETE_ON_ERROR'
|
|---|
| 2462 | If `.DELETE_ON_ERROR' is mentioned as a target anywhere in the
|
|---|
| 2463 | makefile, then `make' will delete the target of a rule if it has
|
|---|
| 2464 | changed and its commands exit with a nonzero exit status, just as
|
|---|
| 2465 | it does when it receives a signal. *Note Errors in Commands:
|
|---|
| 2466 | Errors.
|
|---|
| 2467 |
|
|---|
| 2468 | `.IGNORE'
|
|---|
| 2469 | If you specify prerequisites for `.IGNORE', then `make' will
|
|---|
| 2470 | ignore errors in execution of the commands run for those particular
|
|---|
| 2471 | files. The commands for `.IGNORE' are not meaningful.
|
|---|
| 2472 |
|
|---|
| 2473 | If mentioned as a target with no prerequisites, `.IGNORE' says to
|
|---|
| 2474 | ignore errors in execution of commands for all files. This usage
|
|---|
| 2475 | of `.IGNORE' is supported only for historical compatibility. Since
|
|---|
| 2476 | this affects every command in the makefile, it is not very useful;
|
|---|
| 2477 | we recommend you use the more selective ways to ignore errors in
|
|---|
| 2478 | specific commands. *Note Errors in Commands: Errors.
|
|---|
| 2479 |
|
|---|
| 2480 | `.LOW_RESOLUTION_TIME'
|
|---|
| 2481 | If you specify prerequisites for `.LOW_RESOLUTION_TIME', `make'
|
|---|
| 2482 | assumes that these files are created by commands that generate low
|
|---|
| 2483 | resolution time stamps. The commands for `.LOW_RESOLUTION_TIME'
|
|---|
| 2484 | are not meaningful.
|
|---|
| 2485 |
|
|---|
| 2486 | The high resolution file time stamps of many modern hosts lessen
|
|---|
| 2487 | the chance of `make' incorrectly concluding that a file is up to
|
|---|
| 2488 | date. Unfortunately, these hosts provide no way to set a high
|
|---|
| 2489 | resolution file time stamp, so commands like `cp -p' that
|
|---|
| 2490 | explicitly set a file's time stamp must discard its subsecond
|
|---|
| 2491 | part. If a file is created by such a command, you should list it
|
|---|
| 2492 | as a prerequisite of `.LOW_RESOLUTION_TIME' so that `make' does
|
|---|
| 2493 | not mistakenly conclude that the file is out of date. For example:
|
|---|
| 2494 |
|
|---|
| 2495 | .LOW_RESOLUTION_TIME: dst
|
|---|
| 2496 | dst: src
|
|---|
| 2497 | cp -p src dst
|
|---|
| 2498 |
|
|---|
| 2499 | Since `cp -p' discards the subsecond part of `src''s time stamp,
|
|---|
| 2500 | `dst' is typically slightly older than `src' even when it is up to
|
|---|
| 2501 | date. The `.LOW_RESOLUTION_TIME' line causes `make' to consider
|
|---|
| 2502 | `dst' to be up to date if its time stamp is at the start of the
|
|---|
| 2503 | same second that `src''s time stamp is in.
|
|---|
| 2504 |
|
|---|
| 2505 | Due to a limitation of the archive format, archive member time
|
|---|
| 2506 | stamps are always low resolution. You need not list archive
|
|---|
| 2507 | members as prerequisites of `.LOW_RESOLUTION_TIME', as `make' does
|
|---|
| 2508 | this automatically.
|
|---|
| 2509 |
|
|---|
| 2510 | `.SILENT'
|
|---|
| 2511 | If you specify prerequisites for `.SILENT', then `make' will not
|
|---|
| 2512 | print the commands to remake those particular files before
|
|---|
| 2513 | executing them. The commands for `.SILENT' are not meaningful.
|
|---|
| 2514 |
|
|---|
| 2515 | If mentioned as a target with no prerequisites, `.SILENT' says not
|
|---|
| 2516 | to print any commands before executing them. This usage of
|
|---|
| 2517 | `.SILENT' is supported only for historical compatibility. We
|
|---|
| 2518 | recommend you use the more selective ways to silence specific
|
|---|
| 2519 | commands. *Note Command Echoing: Echoing. If you want to silence
|
|---|
| 2520 | all commands for a particular run of `make', use the `-s' or
|
|---|
| 2521 | `--silent' option (*note Options Summary::).
|
|---|
| 2522 |
|
|---|
| 2523 | `.EXPORT_ALL_VARIABLES'
|
|---|
| 2524 | Simply by being mentioned as a target, this tells `make' to export
|
|---|
| 2525 | all variables to child processes by default. *Note Communicating
|
|---|
| 2526 | Variables to a Sub-`make': Variables/Recursion.
|
|---|
| 2527 |
|
|---|
| 2528 | `.NOTPARALLEL'
|
|---|
| 2529 | If `.NOTPARALLEL' is mentioned as a target, then this invocation of
|
|---|
| 2530 | `make' will be run serially, even if the `-j' option is given.
|
|---|
| 2531 | Any recursively invoked `make' command will still be run in
|
|---|
| 2532 | parallel (unless its makefile contains this target). Any
|
|---|
| 2533 | prerequisites on this target are ignored.
|
|---|
| 2534 |
|
|---|
| 2535 | Any defined implicit rule suffix also counts as a special target if
|
|---|
| 2536 | it appears as a target, and so does the concatenation of two suffixes,
|
|---|
| 2537 | such as `.c.o'. These targets are suffix rules, an obsolete way of
|
|---|
| 2538 | defining implicit rules (but a way still widely used). In principle,
|
|---|
| 2539 | any target name could be special in this way if you break it in two and
|
|---|
| 2540 | add both pieces to the suffix list. In practice, suffixes normally
|
|---|
| 2541 | begin with `.', so these special target names also begin with `.'.
|
|---|
| 2542 | *Note Old-Fashioned Suffix Rules: Suffix Rules.
|
|---|
| 2543 |
|
|---|
| 2544 |
|
|---|
| 2545 | File: make.info, Node: Multiple Targets, Next: Multiple Rules, Prev: Special Targets, Up: Rules
|
|---|
| 2546 |
|
|---|
| 2547 | 4.10 Multiple Targets in a Rule
|
|---|
| 2548 | ===============================
|
|---|
| 2549 |
|
|---|
| 2550 | A rule with multiple targets is equivalent to writing many rules, each
|
|---|
| 2551 | with one target, and all identical aside from that. The same commands
|
|---|
| 2552 | apply to all the targets, but their effects may vary because you can
|
|---|
| 2553 | substitute the actual target name into the command using `$@'. The
|
|---|
| 2554 | rule contributes the same prerequisites to all the targets also.
|
|---|
| 2555 |
|
|---|
| 2556 | This is useful in two cases.
|
|---|
| 2557 |
|
|---|
| 2558 | * You want just prerequisites, no commands. For example:
|
|---|
| 2559 |
|
|---|
| 2560 | kbd.o command.o files.o: command.h
|
|---|
| 2561 |
|
|---|
| 2562 | gives an additional prerequisite to each of the three object files
|
|---|
| 2563 | mentioned.
|
|---|
| 2564 |
|
|---|
| 2565 | * Similar commands work for all the targets. The commands do not
|
|---|
| 2566 | need to be absolutely identical, since the automatic variable `$@'
|
|---|
| 2567 | can be used to substitute the particular target to be remade into
|
|---|
| 2568 | the commands (*note Automatic Variables::). For example:
|
|---|
| 2569 |
|
|---|
| 2570 | bigoutput littleoutput : text.g
|
|---|
| 2571 | generate text.g -$(subst output,,$@) > $@
|
|---|
| 2572 |
|
|---|
| 2573 | is equivalent to
|
|---|
| 2574 |
|
|---|
| 2575 | bigoutput : text.g
|
|---|
| 2576 | generate text.g -big > bigoutput
|
|---|
| 2577 | littleoutput : text.g
|
|---|
| 2578 | generate text.g -little > littleoutput
|
|---|
| 2579 |
|
|---|
| 2580 | Here we assume the hypothetical program `generate' makes two types
|
|---|
| 2581 | of output, one if given `-big' and one if given `-little'. *Note
|
|---|
| 2582 | Functions for String Substitution and Analysis: Text Functions,
|
|---|
| 2583 | for an explanation of the `subst' function.
|
|---|
| 2584 |
|
|---|
| 2585 | Suppose you would like to vary the prerequisites according to the
|
|---|
| 2586 | target, much as the variable `$@' allows you to vary the commands. You
|
|---|
| 2587 | cannot do this with multiple targets in an ordinary rule, but you can
|
|---|
| 2588 | do it with a "static pattern rule". *Note Static Pattern Rules: Static
|
|---|
| 2589 | Pattern.
|
|---|
| 2590 |
|
|---|
| 2591 |
|
|---|
| 2592 | File: make.info, Node: Multiple Rules, Next: Static Pattern, Prev: Multiple Targets, Up: Rules
|
|---|
| 2593 |
|
|---|
| 2594 | 4.11 Multiple Rules for One Target
|
|---|
| 2595 | ==================================
|
|---|
| 2596 |
|
|---|
| 2597 | One file can be the target of several rules. All the prerequisites
|
|---|
| 2598 | mentioned in all the rules are merged into one list of prerequisites for
|
|---|
| 2599 | the target. If the target is older than any prerequisite from any rule,
|
|---|
| 2600 | the commands are executed.
|
|---|
| 2601 |
|
|---|
| 2602 | There can only be one set of commands to be executed for a file. If
|
|---|
| 2603 | more than one rule gives commands for the same file, `make' uses the
|
|---|
| 2604 | last set given and prints an error message. (As a special case, if the
|
|---|
| 2605 | file's name begins with a dot, no error message is printed. This odd
|
|---|
| 2606 | behavior is only for compatibility with other implementations of
|
|---|
| 2607 | `make'... you should avoid using it). Occasionally it is useful to
|
|---|
| 2608 | have the same target invoke multiple commands which are defined in
|
|---|
| 2609 | different parts of your makefile; you can use "double-colon rules"
|
|---|
| 2610 | (*note Double-Colon::) for this.
|
|---|
| 2611 |
|
|---|
| 2612 | An extra rule with just prerequisites can be used to give a few extra
|
|---|
| 2613 | prerequisites to many files at once. For example, makefiles often have
|
|---|
| 2614 | a variable, such as `objects', containing a list of all the compiler
|
|---|
| 2615 | output files in the system being made. An easy way to say that all of
|
|---|
| 2616 | them must be recompiled if `config.h' changes is to write the following:
|
|---|
| 2617 |
|
|---|
| 2618 | objects = foo.o bar.o
|
|---|
| 2619 | foo.o : defs.h
|
|---|
| 2620 | bar.o : defs.h test.h
|
|---|
| 2621 | $(objects) : config.h
|
|---|
| 2622 |
|
|---|
| 2623 | This could be inserted or taken out without changing the rules that
|
|---|
| 2624 | really specify how to make the object files, making it a convenient
|
|---|
| 2625 | form to use if you wish to add the additional prerequisite
|
|---|
| 2626 | intermittently.
|
|---|
| 2627 |
|
|---|
| 2628 | Another wrinkle is that the additional prerequisites could be
|
|---|
| 2629 | specified with a variable that you set with a command argument to `make'
|
|---|
| 2630 | (*note Overriding Variables: Overriding.). For example,
|
|---|
| 2631 |
|
|---|
| 2632 | extradeps=
|
|---|
| 2633 | $(objects) : $(extradeps)
|
|---|
| 2634 |
|
|---|
| 2635 | means that the command `make extradeps=foo.h' will consider `foo.h' as
|
|---|
| 2636 | a prerequisite of each object file, but plain `make' will not.
|
|---|
| 2637 |
|
|---|
| 2638 | If none of the explicit rules for a target has commands, then `make'
|
|---|
| 2639 | searches for an applicable implicit rule to find some commands *note
|
|---|
| 2640 | Using Implicit Rules: Implicit Rules.).
|
|---|
| 2641 |
|
|---|
| 2642 |
|
|---|
| 2643 | File: make.info, Node: Static Pattern, Next: Double-Colon, Prev: Multiple Rules, Up: Rules
|
|---|
| 2644 |
|
|---|
| 2645 | 4.12 Static Pattern Rules
|
|---|
| 2646 | =========================
|
|---|
| 2647 |
|
|---|
| 2648 | "Static pattern rules" are rules which specify multiple targets and
|
|---|
| 2649 | construct the prerequisite names for each target based on the target
|
|---|
| 2650 | name. They are more general than ordinary rules with multiple targets
|
|---|
| 2651 | because the targets do not have to have identical prerequisites. Their
|
|---|
| 2652 | prerequisites must be _analogous_, but not necessarily _identical_.
|
|---|
| 2653 |
|
|---|
| 2654 | * Menu:
|
|---|
| 2655 |
|
|---|
| 2656 | * Static Usage:: The syntax of static pattern rules.
|
|---|
| 2657 | * Static versus Implicit:: When are they better than implicit rules?
|
|---|
| 2658 |
|
|---|
| 2659 |
|
|---|
| 2660 | File: make.info, Node: Static Usage, Next: Static versus Implicit, Prev: Static Pattern, Up: Static Pattern
|
|---|
| 2661 |
|
|---|
| 2662 | 4.12.1 Syntax of Static Pattern Rules
|
|---|
| 2663 | -------------------------------------
|
|---|
| 2664 |
|
|---|
| 2665 | Here is the syntax of a static pattern rule:
|
|---|
| 2666 |
|
|---|
| 2667 | TARGETS ...: TARGET-PATTERN: PREREQ-PATTERNS ...
|
|---|
| 2668 | COMMANDS
|
|---|
| 2669 | ...
|
|---|
| 2670 |
|
|---|
| 2671 | The TARGETS list specifies the targets that the rule applies to. The
|
|---|
| 2672 | targets can contain wildcard characters, just like the targets of
|
|---|
| 2673 | ordinary rules (*note Using Wildcard Characters in File Names:
|
|---|
| 2674 | Wildcards.).
|
|---|
| 2675 |
|
|---|
| 2676 | The TARGET-PATTERN and PREREQ-PATTERNS say how to compute the
|
|---|
| 2677 | prerequisites of each target. Each target is matched against the
|
|---|
| 2678 | TARGET-PATTERN to extract a part of the target name, called the "stem".
|
|---|
| 2679 | This stem is substituted into each of the PREREQ-PATTERNS to make the
|
|---|
| 2680 | prerequisite names (one from each PREREQ-PATTERN).
|
|---|
| 2681 |
|
|---|
| 2682 | Each pattern normally contains the character `%' just once. When the
|
|---|
| 2683 | TARGET-PATTERN matches a target, the `%' can match any part of the
|
|---|
| 2684 | target name; this part is called the "stem". The rest of the pattern
|
|---|
| 2685 | must match exactly. For example, the target `foo.o' matches the
|
|---|
| 2686 | pattern `%.o', with `foo' as the stem. The targets `foo.c' and
|
|---|
| 2687 | `foo.out' do not match that pattern.
|
|---|
| 2688 |
|
|---|
| 2689 | The prerequisite names for each target are made by substituting the
|
|---|
| 2690 | stem for the `%' in each prerequisite pattern. For example, if one
|
|---|
| 2691 | prerequisite pattern is `%.c', then substitution of the stem `foo'
|
|---|
| 2692 | gives the prerequisite name `foo.c'. It is legitimate to write a
|
|---|
| 2693 | prerequisite pattern that does not contain `%'; then this prerequisite
|
|---|
| 2694 | is the same for all targets.
|
|---|
| 2695 |
|
|---|
| 2696 | `%' characters in pattern rules can be quoted with preceding
|
|---|
| 2697 | backslashes (`\'). Backslashes that would otherwise quote `%'
|
|---|
| 2698 | characters can be quoted with more backslashes. Backslashes that quote
|
|---|
| 2699 | `%' characters or other backslashes are removed from the pattern before
|
|---|
| 2700 | it is compared to file names or has a stem substituted into it.
|
|---|
| 2701 | Backslashes that are not in danger of quoting `%' characters go
|
|---|
| 2702 | unmolested. For example, the pattern `the\%weird\\%pattern\\' has
|
|---|
| 2703 | `the%weird\' preceding the operative `%' character, and `pattern\\'
|
|---|
| 2704 | following it. The final two backslashes are left alone because they
|
|---|
| 2705 | cannot affect any `%' character.
|
|---|
| 2706 |
|
|---|
| 2707 | Here is an example, which compiles each of `foo.o' and `bar.o' from
|
|---|
| 2708 | the corresponding `.c' file:
|
|---|
| 2709 |
|
|---|
| 2710 | objects = foo.o bar.o
|
|---|
| 2711 |
|
|---|
| 2712 | all: $(objects)
|
|---|
| 2713 |
|
|---|
| 2714 | $(objects): %.o: %.c
|
|---|
| 2715 | $(CC) -c $(CFLAGS) $< -o $@
|
|---|
| 2716 |
|
|---|
| 2717 | Here `$<' is the automatic variable that holds the name of the
|
|---|
| 2718 | prerequisite and `$@' is the automatic variable that holds the name of
|
|---|
| 2719 | the target; see *Note Automatic Variables::.
|
|---|
| 2720 |
|
|---|
| 2721 | Each target specified must match the target pattern; a warning is
|
|---|
| 2722 | issued for each target that does not. If you have a list of files,
|
|---|
| 2723 | only some of which will match the pattern, you can use the `filter'
|
|---|
| 2724 | function to remove nonmatching file names (*note Functions for String
|
|---|
| 2725 | Substitution and Analysis: Text Functions.):
|
|---|
| 2726 |
|
|---|
| 2727 | files = foo.elc bar.o lose.o
|
|---|
| 2728 |
|
|---|
| 2729 | $(filter %.o,$(files)): %.o: %.c
|
|---|
| 2730 | $(CC) -c $(CFLAGS) $< -o $@
|
|---|
| 2731 | $(filter %.elc,$(files)): %.elc: %.el
|
|---|
| 2732 | emacs -f batch-byte-compile $<
|
|---|
| 2733 |
|
|---|
| 2734 | In this example the result of `$(filter %.o,$(files))' is `bar.o
|
|---|
| 2735 | lose.o', and the first static pattern rule causes each of these object
|
|---|
| 2736 | files to be updated by compiling the corresponding C source file. The
|
|---|
| 2737 | result of `$(filter %.elc,$(files))' is `foo.elc', so that file is made
|
|---|
| 2738 | from `foo.el'.
|
|---|
| 2739 |
|
|---|
| 2740 | Another example shows how to use `$*' in static pattern rules:
|
|---|
| 2741 |
|
|---|
| 2742 | bigoutput littleoutput : %output : text.g
|
|---|
| 2743 | generate text.g -$* > $@
|
|---|
| 2744 |
|
|---|
| 2745 | When the `generate' command is run, `$*' will expand to the stem,
|
|---|
| 2746 | either `big' or `little'.
|
|---|
| 2747 |
|
|---|
| 2748 |
|
|---|
| 2749 | File: make.info, Node: Static versus Implicit, Prev: Static Usage, Up: Static Pattern
|
|---|
| 2750 |
|
|---|
| 2751 | 4.12.2 Static Pattern Rules versus Implicit Rules
|
|---|
| 2752 | -------------------------------------------------
|
|---|
| 2753 |
|
|---|
| 2754 | A static pattern rule has much in common with an implicit rule defined
|
|---|
| 2755 | as a pattern rule (*note Defining and Redefining Pattern Rules: Pattern
|
|---|
| 2756 | Rules.). Both have a pattern for the target and patterns for
|
|---|
| 2757 | constructing the names of prerequisites. The difference is in how
|
|---|
| 2758 | `make' decides _when_ the rule applies.
|
|---|
| 2759 |
|
|---|
| 2760 | An implicit rule _can_ apply to any target that matches its pattern,
|
|---|
| 2761 | but it _does_ apply only when the target has no commands otherwise
|
|---|
| 2762 | specified, and only when the prerequisites can be found. If more than
|
|---|
| 2763 | one implicit rule appears applicable, only one applies; the choice
|
|---|
| 2764 | depends on the order of rules.
|
|---|
| 2765 |
|
|---|
| 2766 | By contrast, a static pattern rule applies to the precise list of
|
|---|
| 2767 | targets that you specify in the rule. It cannot apply to any other
|
|---|
| 2768 | target and it invariably does apply to each of the targets specified.
|
|---|
| 2769 | If two conflicting rules apply, and both have commands, that's an error.
|
|---|
| 2770 |
|
|---|
| 2771 | The static pattern rule can be better than an implicit rule for these
|
|---|
| 2772 | reasons:
|
|---|
| 2773 |
|
|---|
| 2774 | * You may wish to override the usual implicit rule for a few files
|
|---|
| 2775 | whose names cannot be categorized syntactically but can be given
|
|---|
| 2776 | in an explicit list.
|
|---|
| 2777 |
|
|---|
| 2778 | * If you cannot be sure of the precise contents of the directories
|
|---|
| 2779 | you are using, you may not be sure which other irrelevant files
|
|---|
| 2780 | might lead `make' to use the wrong implicit rule. The choice
|
|---|
| 2781 | might depend on the order in which the implicit rule search is
|
|---|
| 2782 | done. With static pattern rules, there is no uncertainty: each
|
|---|
| 2783 | rule applies to precisely the targets specified.
|
|---|
| 2784 |
|
|---|
| 2785 |
|
|---|
| 2786 | File: make.info, Node: Double-Colon, Next: Automatic Prerequisites, Prev: Static Pattern, Up: Rules
|
|---|
| 2787 |
|
|---|
| 2788 | 4.13 Double-Colon Rules
|
|---|
| 2789 | =======================
|
|---|
| 2790 |
|
|---|
| 2791 | "Double-colon" rules are rules written with `::' instead of `:' after
|
|---|
| 2792 | the target names. They are handled differently from ordinary rules
|
|---|
| 2793 | when the same target appears in more than one rule.
|
|---|
| 2794 |
|
|---|
| 2795 | When a target appears in multiple rules, all the rules must be the
|
|---|
| 2796 | same type: all ordinary, or all double-colon. If they are
|
|---|
| 2797 | double-colon, each of them is independent of the others. Each
|
|---|
| 2798 | double-colon rule's commands are executed if the target is older than
|
|---|
| 2799 | any prerequisites of that rule. If there are no prerequisites for that
|
|---|
| 2800 | rule, its commands are always executed (even if the target already
|
|---|
| 2801 | exists). This can result in executing none, any, or all of the
|
|---|
| 2802 | double-colon rules.
|
|---|
| 2803 |
|
|---|
| 2804 | Double-colon rules with the same target are in fact completely
|
|---|
| 2805 | separate from one another. Each double-colon rule is processed
|
|---|
| 2806 | individually, just as rules with different targets are processed.
|
|---|
| 2807 |
|
|---|
| 2808 | The double-colon rules for a target are executed in the order they
|
|---|
| 2809 | appear in the makefile. However, the cases where double-colon rules
|
|---|
| 2810 | really make sense are those where the order of executing the commands
|
|---|
| 2811 | would not matter.
|
|---|
| 2812 |
|
|---|
| 2813 | Double-colon rules are somewhat obscure and not often very useful;
|
|---|
| 2814 | they provide a mechanism for cases in which the method used to update a
|
|---|
| 2815 | target differs depending on which prerequisite files caused the update,
|
|---|
| 2816 | and such cases are rare.
|
|---|
| 2817 |
|
|---|
| 2818 | Each double-colon rule should specify commands; if it does not, an
|
|---|
| 2819 | implicit rule will be used if one applies. *Note Using Implicit Rules:
|
|---|
| 2820 | Implicit Rules.
|
|---|
| 2821 |
|
|---|
| 2822 |
|
|---|
| 2823 | File: make.info, Node: Automatic Prerequisites, Prev: Double-Colon, Up: Rules
|
|---|
| 2824 |
|
|---|
| 2825 | 4.14 Generating Prerequisites Automatically
|
|---|
| 2826 | ===========================================
|
|---|
| 2827 |
|
|---|
| 2828 | In the makefile for a program, many of the rules you need to write often
|
|---|
| 2829 | say only that some object file depends on some header file. For
|
|---|
| 2830 | example, if `main.c' uses `defs.h' via an `#include', you would write:
|
|---|
| 2831 |
|
|---|
| 2832 | main.o: defs.h
|
|---|
| 2833 |
|
|---|
| 2834 | You need this rule so that `make' knows that it must remake `main.o'
|
|---|
| 2835 | whenever `defs.h' changes. You can see that for a large program you
|
|---|
| 2836 | would have to write dozens of such rules in your makefile. And, you
|
|---|
| 2837 | must always be very careful to update the makefile every time you add
|
|---|
| 2838 | or remove an `#include'.
|
|---|
| 2839 |
|
|---|
| 2840 | To avoid this hassle, most modern C compilers can write these rules
|
|---|
| 2841 | for you, by looking at the `#include' lines in the source files.
|
|---|
| 2842 | Usually this is done with the `-M' option to the compiler. For
|
|---|
| 2843 | example, the command:
|
|---|
| 2844 |
|
|---|
| 2845 | cc -M main.c
|
|---|
| 2846 |
|
|---|
| 2847 | generates the output:
|
|---|
| 2848 |
|
|---|
| 2849 | main.o : main.c defs.h
|
|---|
| 2850 |
|
|---|
| 2851 | Thus you no longer have to write all those rules yourself. The
|
|---|
| 2852 | compiler will do it for you.
|
|---|
| 2853 |
|
|---|
| 2854 | Note that such a prerequisite constitutes mentioning `main.o' in a
|
|---|
| 2855 | makefile, so it can never be considered an intermediate file by implicit
|
|---|
| 2856 | rule search. This means that `make' won't ever remove the file after
|
|---|
| 2857 | using it; *note Chains of Implicit Rules: Chained Rules.
|
|---|
| 2858 |
|
|---|
| 2859 | With old `make' programs, it was traditional practice to use this
|
|---|
| 2860 | compiler feature to generate prerequisites on demand with a command like
|
|---|
| 2861 | `make depend'. That command would create a file `depend' containing
|
|---|
| 2862 | all the automatically-generated prerequisites; then the makefile could
|
|---|
| 2863 | use `include' to read them in (*note Include::).
|
|---|
| 2864 |
|
|---|
| 2865 | In GNU `make', the feature of remaking makefiles makes this practice
|
|---|
| 2866 | obsolete--you need never tell `make' explicitly to regenerate the
|
|---|
| 2867 | prerequisites, because it always regenerates any makefile that is out
|
|---|
| 2868 | of date. *Note Remaking Makefiles::.
|
|---|
| 2869 |
|
|---|
| 2870 | The practice we recommend for automatic prerequisite generation is
|
|---|
| 2871 | to have one makefile corresponding to each source file. For each
|
|---|
| 2872 | source file `NAME.c' there is a makefile `NAME.d' which lists what
|
|---|
| 2873 | files the object file `NAME.o' depends on. That way only the source
|
|---|
| 2874 | files that have changed need to be rescanned to produce the new
|
|---|
| 2875 | prerequisites.
|
|---|
| 2876 |
|
|---|
| 2877 | Here is the pattern rule to generate a file of prerequisites (i.e.,
|
|---|
| 2878 | a makefile) called `NAME.d' from a C source file called `NAME.c':
|
|---|
| 2879 |
|
|---|
| 2880 | %.d: %.c
|
|---|
| 2881 | @set -e; rm -f $@; \
|
|---|
| 2882 | $(CC) -M $(CPPFLAGS) $< > $@.$$$$; \
|
|---|
| 2883 | sed 's,\($*\)\.o[ :]*,\1.o $@ : ,g' < $@.$$$$ > $@; \
|
|---|
| 2884 | rm -f $@.$$$$
|
|---|
| 2885 |
|
|---|
| 2886 | *Note Pattern Rules::, for information on defining pattern rules. The
|
|---|
| 2887 | `-e' flag to the shell causes it to exit immediately if the `$(CC)'
|
|---|
| 2888 | command (or any other command) fails (exits with a nonzero status).
|
|---|
| 2889 |
|
|---|
| 2890 | With the GNU C compiler, you may wish to use the `-MM' flag instead
|
|---|
| 2891 | of `-M'. This omits prerequisites on system header files. *Note
|
|---|
| 2892 | Options Controlling the Preprocessor: (gcc.info)Preprocessor Options,
|
|---|
| 2893 | for details.
|
|---|
| 2894 |
|
|---|
| 2895 | The purpose of the `sed' command is to translate (for example):
|
|---|
| 2896 |
|
|---|
| 2897 | main.o : main.c defs.h
|
|---|
| 2898 |
|
|---|
| 2899 | into:
|
|---|
| 2900 |
|
|---|
| 2901 | main.o main.d : main.c defs.h
|
|---|
| 2902 |
|
|---|
| 2903 | This makes each `.d' file depend on all the source and header files
|
|---|
| 2904 | that the corresponding `.o' file depends on. `make' then knows it must
|
|---|
| 2905 | regenerate the prerequisites whenever any of the source or header files
|
|---|
| 2906 | changes.
|
|---|
| 2907 |
|
|---|
| 2908 | Once you've defined the rule to remake the `.d' files, you then use
|
|---|
| 2909 | the `include' directive to read them all in. *Note Include::. For
|
|---|
| 2910 | example:
|
|---|
| 2911 |
|
|---|
| 2912 | sources = foo.c bar.c
|
|---|
| 2913 |
|
|---|
| 2914 | include $(sources:.c=.d)
|
|---|
| 2915 |
|
|---|
| 2916 | (This example uses a substitution variable reference to translate the
|
|---|
| 2917 | list of source files `foo.c bar.c' into a list of prerequisite
|
|---|
| 2918 | makefiles, `foo.d bar.d'. *Note Substitution Refs::, for full
|
|---|
| 2919 | information on substitution references.) Since the `.d' files are
|
|---|
| 2920 | makefiles like any others, `make' will remake them as necessary with no
|
|---|
| 2921 | further work from you. *Note Remaking Makefiles::.
|
|---|
| 2922 |
|
|---|
| 2923 | Note that the `.d' files contain target definitions; you should be
|
|---|
| 2924 | sure to place the `include' directive _after_ the first, default goal
|
|---|
| 2925 | in your makefiles or run the risk of having a random object file become
|
|---|
| 2926 | the default goal. *Note How Make Works::.
|
|---|
| 2927 |
|
|---|
| 2928 |
|
|---|
| 2929 | File: make.info, Node: Commands, Next: Using Variables, Prev: Rules, Up: Top
|
|---|
| 2930 |
|
|---|
| 2931 | 5 Writing the Commands in Rules
|
|---|
| 2932 | *******************************
|
|---|
| 2933 |
|
|---|
| 2934 | The commands of a rule consist of one or more shell command lines to be
|
|---|
| 2935 | executed, one at a time, in the order they appear. Typically, the
|
|---|
| 2936 | result of executing these commands is that the target of the rule is
|
|---|
| 2937 | brought up to date.
|
|---|
| 2938 |
|
|---|
| 2939 | Users use many different shell programs, but commands in makefiles
|
|---|
| 2940 | are always interpreted by `/bin/sh' unless the makefile specifies
|
|---|
| 2941 | otherwise. *Note Command Execution: Execution.
|
|---|
| 2942 |
|
|---|
| 2943 | * Menu:
|
|---|
| 2944 |
|
|---|
| 2945 | * Command Syntax:: Command syntax features and pitfalls.
|
|---|
| 2946 | * Echoing:: How to control when commands are echoed.
|
|---|
| 2947 | * Execution:: How commands are executed.
|
|---|
| 2948 | * Parallel:: How commands can be executed in parallel.
|
|---|
| 2949 | * Errors:: What happens after a command execution error.
|
|---|
| 2950 | * Interrupts:: What happens when a command is interrupted.
|
|---|
| 2951 | * Recursion:: Invoking `make' from makefiles.
|
|---|
| 2952 | * Sequences:: Defining canned sequences of commands.
|
|---|
| 2953 | * Empty Commands:: Defining useful, do-nothing commands.
|
|---|
| 2954 |
|
|---|
| 2955 |
|
|---|
| 2956 | File: make.info, Node: Command Syntax, Next: Echoing, Prev: Commands, Up: Commands
|
|---|
| 2957 |
|
|---|
| 2958 | 5.1 Command Syntax
|
|---|
| 2959 | ==================
|
|---|
| 2960 |
|
|---|
| 2961 | Makefiles have the unusual property that there are really two distinct
|
|---|
| 2962 | syntaxes in one file. Most of the makefile uses `make' syntax (*note
|
|---|
| 2963 | Writing Makefiles: Makefiles.). However, commands are meant to be
|
|---|
| 2964 | interpreted by the shell and so they are written using shell syntax.
|
|---|
| 2965 | The `make' program does not try to understand shell syntax: it performs
|
|---|
| 2966 | only a very few specific translations on the content of the command
|
|---|
| 2967 | before handing it to the shell.
|
|---|
| 2968 |
|
|---|
| 2969 | Each command line must start with a tab, except that the first
|
|---|
| 2970 | command line may be attached to the target-and-prerequisites line with a
|
|---|
| 2971 | semicolon in between. _Any_ line in the makefile that begins with a
|
|---|
| 2972 | tab and appears in a "rule context" (that is, after a rule has been
|
|---|
| 2973 | started until another rule or variable definition) will be considered a
|
|---|
| 2974 | command line for that rule. Blank lines and lines of just comments may
|
|---|
| 2975 | appear among the command lines; they are ignored.
|
|---|
| 2976 |
|
|---|
| 2977 | Some consequences of these rules include:
|
|---|
| 2978 |
|
|---|
| 2979 | * A blank line that begins with a tab is not blank: it's an empty
|
|---|
| 2980 | command (*note Empty Commands::).
|
|---|
| 2981 |
|
|---|
| 2982 | * A comment in a command line is not a `make' comment; it will be
|
|---|
| 2983 | passed to the shell as-is. Whether the shell treats it as a
|
|---|
| 2984 | comment or not depends on your shell.
|
|---|
| 2985 |
|
|---|
| 2986 | * A variable definition in a "rule context" which is indented by a
|
|---|
| 2987 | tab as the first character on the line, will be considered a
|
|---|
| 2988 | command line, not a `make' variable definition, and passed to the
|
|---|
| 2989 | shell.
|
|---|
| 2990 |
|
|---|
| 2991 | * A conditional expression (`ifdef', `ifeq', etc. *note Syntax of
|
|---|
| 2992 | Conditionals: Conditional Syntax.) in a "rule context" which is
|
|---|
| 2993 | indented by a tab as the first character on the line, will be
|
|---|
| 2994 | considered a command line and be passed to the shell.
|
|---|
| 2995 |
|
|---|
| 2996 |
|
|---|
| 2997 | * Menu:
|
|---|
| 2998 |
|
|---|
| 2999 | * Splitting Lines:: Breaking long command lines for readability.
|
|---|
| 3000 | * Variables in Commands:: Using `make' variables in commands.
|
|---|
| 3001 |
|
|---|
| 3002 |
|
|---|
| 3003 | File: make.info, Node: Splitting Lines, Next: Variables in Commands, Prev: Command Syntax, Up: Command Syntax
|
|---|
| 3004 |
|
|---|
| 3005 | 5.1.1 Splitting Command Lines
|
|---|
| 3006 | -----------------------------
|
|---|
| 3007 |
|
|---|
| 3008 | One of the few ways in which `make' does interpret command lines is
|
|---|
| 3009 | checking for a backslash just before the newline. As in normal
|
|---|
| 3010 | makefile syntax, a single command can be split into multiple lines in
|
|---|
| 3011 | the makefile by placing a backslash before each newline. A sequence of
|
|---|
| 3012 | lines like this is considered a single command, and one instance of the
|
|---|
| 3013 | shell will be invoked to run it.
|
|---|
| 3014 |
|
|---|
| 3015 | However, in contrast to how they are treated in other places in a
|
|---|
| 3016 | makefile, backslash-newline pairs are _not_ removed from the command.
|
|---|
| 3017 | Both the backslash and the newline characters are preserved and passed
|
|---|
| 3018 | to the shell. How the backslash-newline is interpreted depends on your
|
|---|
| 3019 | shell. If the first character of the next line after the
|
|---|
| 3020 | backslash-newline is a tab, then that tab (and only that tab) is
|
|---|
| 3021 | removed. Whitespace is never added to the command.
|
|---|
| 3022 |
|
|---|
| 3023 | For example, this makefile:
|
|---|
| 3024 |
|
|---|
| 3025 | all :
|
|---|
| 3026 | @echo no\
|
|---|
| 3027 | space
|
|---|
| 3028 | @echo no\
|
|---|
| 3029 | space
|
|---|
| 3030 | @echo one \
|
|---|
| 3031 | space
|
|---|
| 3032 | @echo one\
|
|---|
| 3033 | space
|
|---|
| 3034 |
|
|---|
| 3035 | consists of four separate shell commands where the output is:
|
|---|
| 3036 |
|
|---|
| 3037 | nospace
|
|---|
| 3038 | nospace
|
|---|
| 3039 | one space
|
|---|
| 3040 | one space
|
|---|
| 3041 |
|
|---|
| 3042 | As a more complex example, this makefile:
|
|---|
| 3043 |
|
|---|
| 3044 | all : ; @echo 'hello \
|
|---|
| 3045 | world' ; echo "hello \
|
|---|
| 3046 | world"
|
|---|
| 3047 |
|
|---|
| 3048 | will run one shell with a command script of:
|
|---|
| 3049 |
|
|---|
| 3050 | echo 'hello \
|
|---|
| 3051 | world' ; echo "hello \
|
|---|
| 3052 | world"
|
|---|
| 3053 |
|
|---|
| 3054 | which, according to shell quoting rules, will yield the following
|
|---|
| 3055 | output:
|
|---|
| 3056 |
|
|---|
| 3057 | hello \
|
|---|
| 3058 | world
|
|---|
| 3059 | hello world
|
|---|
| 3060 |
|
|---|
| 3061 | Notice how the backslash/newline pair was removed inside the string
|
|---|
| 3062 | quoted with double quotes (`"..."'), but not from the string quoted
|
|---|
| 3063 | with single quotes (`'...''). This is the way the default shell
|
|---|
| 3064 | (`/bin/sh') handles backslash/newline pairs. If you specify a
|
|---|
| 3065 | different shell in your makefiles it may treat them differently.
|
|---|
| 3066 |
|
|---|
| 3067 | Sometimes you want to split a long line inside of single quotes, but
|
|---|
| 3068 | you don't want the backslash-newline to appear in the quoted content.
|
|---|
| 3069 | This is often the case when passing scripts to languages such as Perl,
|
|---|
| 3070 | where extraneous backslashes inside the script can change its meaning
|
|---|
| 3071 | or even be a syntax error. One simple way of handling this is to place
|
|---|
| 3072 | the quoted string, or even the entire command, into a `make' variable
|
|---|
| 3073 | then use the variable in the command. In this situation the newline
|
|---|
| 3074 | quoting rules for makefiles will be used, and the backslash-newline
|
|---|
| 3075 | will be removed. If we rewrite our example above using this method:
|
|---|
| 3076 |
|
|---|
| 3077 | HELLO = 'hello \
|
|---|
| 3078 | world'
|
|---|
| 3079 |
|
|---|
| 3080 | all : ; @echo $(HELLO)
|
|---|
| 3081 |
|
|---|
| 3082 | we will get output like this:
|
|---|
| 3083 |
|
|---|
| 3084 | hello world
|
|---|
| 3085 |
|
|---|
| 3086 | If you like, you can also use target-specific variables (*note
|
|---|
| 3087 | Target-specific Variable Values: Target-specific.) to obtain a tighter
|
|---|
| 3088 | correspondence between the variable and the command that uses it.
|
|---|
| 3089 |
|
|---|
| 3090 |
|
|---|
| 3091 | File: make.info, Node: Variables in Commands, Prev: Splitting Lines, Up: Command Syntax
|
|---|
| 3092 |
|
|---|
| 3093 | 5.1.2 Using Variables in Commands
|
|---|
| 3094 | ---------------------------------
|
|---|
| 3095 |
|
|---|
| 3096 | The other way in which `make' processes commands is by expanding any
|
|---|
| 3097 | variable references in them (*note Basics of Variable References:
|
|---|
| 3098 | Reference.). This occurs after make has finished reading all the
|
|---|
| 3099 | makefiles and the target is determined to be out of date; so, the
|
|---|
| 3100 | commands for targets which are not rebuilt are never expanded.
|
|---|
| 3101 |
|
|---|
| 3102 | Variable and function references in commands have identical syntax
|
|---|
| 3103 | and semantics to references elsewhere in the makefile. They also have
|
|---|
| 3104 | the same quoting rules: if you want a dollar sign to appear in your
|
|---|
| 3105 | command, you must double it (`$$'). For shells like the default shell,
|
|---|
| 3106 | that use dollar signs to introduce variables, it's important to keep
|
|---|
| 3107 | clear in your mind whether the variable you want to reference is a
|
|---|
| 3108 | `make' variable (use a single dollar sign) or a shell variable (use two
|
|---|
| 3109 | dollar signs). For example:
|
|---|
| 3110 |
|
|---|
| 3111 | LIST = one two three
|
|---|
| 3112 | all:
|
|---|
| 3113 | for i in $(LIST); do \
|
|---|
| 3114 | echo $$i; \
|
|---|
| 3115 | done
|
|---|
| 3116 |
|
|---|
| 3117 | results in the following command being passed to the shell:
|
|---|
| 3118 |
|
|---|
| 3119 | for i in one two three; do \
|
|---|
| 3120 | echo $i; \
|
|---|
| 3121 | done
|
|---|
| 3122 |
|
|---|
| 3123 | which generates the expected result:
|
|---|
| 3124 |
|
|---|
| 3125 | one
|
|---|
| 3126 | two
|
|---|
| 3127 | three
|
|---|
| 3128 |
|
|---|
| 3129 |
|
|---|
| 3130 | File: make.info, Node: Echoing, Next: Execution, Prev: Command Syntax, Up: Commands
|
|---|
| 3131 |
|
|---|
| 3132 | 5.2 Command Echoing
|
|---|
| 3133 | ===================
|
|---|
| 3134 |
|
|---|
| 3135 | Normally `make' prints each command line before it is executed. We
|
|---|
| 3136 | call this "echoing" because it gives the appearance that you are typing
|
|---|
| 3137 | the commands yourself.
|
|---|
| 3138 |
|
|---|
| 3139 | When a line starts with `@', the echoing of that line is suppressed.
|
|---|
| 3140 | The `@' is discarded before the command is passed to the shell.
|
|---|
| 3141 | Typically you would use this for a command whose only effect is to print
|
|---|
| 3142 | something, such as an `echo' command to indicate progress through the
|
|---|
| 3143 | makefile:
|
|---|
| 3144 |
|
|---|
| 3145 | @echo About to make distribution files
|
|---|
| 3146 |
|
|---|
| 3147 | When `make' is given the flag `-n' or `--just-print' it only echoes
|
|---|
| 3148 | commands, it won't execute them. *Note Summary of Options: Options
|
|---|
| 3149 | Summary. In this case and only this case, even the commands starting
|
|---|
| 3150 | with `@' are printed. This flag is useful for finding out which
|
|---|
| 3151 | commands `make' thinks are necessary without actually doing them.
|
|---|
| 3152 |
|
|---|
| 3153 | The `-s' or `--silent' flag to `make' prevents all echoing, as if
|
|---|
| 3154 | all commands started with `@'. A rule in the makefile for the special
|
|---|
| 3155 | target `.SILENT' without prerequisites has the same effect (*note
|
|---|
| 3156 | Special Built-in Target Names: Special Targets.). `.SILENT' is
|
|---|
| 3157 | essentially obsolete since `@' is more flexible.
|
|---|
| 3158 |
|
|---|
| 3159 |
|
|---|
| 3160 | File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Commands
|
|---|
| 3161 |
|
|---|
| 3162 | 5.3 Command Execution
|
|---|
| 3163 | =====================
|
|---|
| 3164 |
|
|---|
| 3165 | When it is time to execute commands to update a target, they are
|
|---|
| 3166 | executed by invoking a new subshell for each command line. (In
|
|---|
| 3167 | practice, `make' may take shortcuts that do not affect the results.)
|
|---|
| 3168 |
|
|---|
| 3169 | *Please note:* this implies that setting shell variables and
|
|---|
| 3170 | invoking shell commands such as `cd' that set a context local to each
|
|---|
| 3171 | process will not affect the following command lines.(1) If you want to
|
|---|
| 3172 | use `cd' to affect the next statement, put both statements in a single
|
|---|
| 3173 | command line. Then `make' will invoke one shell to run the entire
|
|---|
| 3174 | line, and the shell will execute the statements in sequence. For
|
|---|
| 3175 | example:
|
|---|
| 3176 |
|
|---|
| 3177 | foo : bar/lose
|
|---|
| 3178 | cd $(@D) && gobble $(@F) > ../$@
|
|---|
| 3179 |
|
|---|
| 3180 | Here we use the shell AND operator (`&&') so that if the `cd' command
|
|---|
| 3181 | fails, the script will fail without trying to invoke the `gobble'
|
|---|
| 3182 | command in the wrong directory, which could cause problems (in this
|
|---|
| 3183 | case it would certainly cause `../foo' to be truncated, at least).
|
|---|
| 3184 |
|
|---|
| 3185 | * Menu:
|
|---|
| 3186 |
|
|---|
| 3187 | * Choosing the Shell:: How `make' chooses the shell used
|
|---|
| 3188 | to run commands.
|
|---|
| 3189 |
|
|---|
| 3190 | ---------- Footnotes ----------
|
|---|
| 3191 |
|
|---|
| 3192 | (1) On MS-DOS, the value of current working directory is *global*, so
|
|---|
| 3193 | changing it _will_ affect the following command lines on those systems.
|
|---|
| 3194 |
|
|---|
| 3195 |
|
|---|
| 3196 | File: make.info, Node: Choosing the Shell, Prev: Execution, Up: Execution
|
|---|
| 3197 |
|
|---|
| 3198 | 5.3.1 Choosing the Shell
|
|---|
| 3199 | ------------------------
|
|---|
| 3200 |
|
|---|
| 3201 | The program used as the shell is taken from the variable `SHELL'. If
|
|---|
| 3202 | this variable is not set in your makefile, the program `/bin/sh' is
|
|---|
| 3203 | used as the shell.
|
|---|
| 3204 |
|
|---|
| 3205 | Unlike most variables, the variable `SHELL' is never set from the
|
|---|
| 3206 | environment. This is because the `SHELL' environment variable is used
|
|---|
| 3207 | to specify your personal choice of shell program for interactive use.
|
|---|
| 3208 | It would be very bad for personal choices like this to affect the
|
|---|
| 3209 | functioning of makefiles. *Note Variables from the Environment:
|
|---|
| 3210 | Environment.
|
|---|
| 3211 |
|
|---|
| 3212 | Furthermore, when you do set `SHELL' in your makefile that value is
|
|---|
| 3213 | _not_ exported in the environment to commands that `make' invokes.
|
|---|
| 3214 | Instead, the value inherited from the user's environment, if any, is
|
|---|
| 3215 | exported. You can override this behavior by explicitly exporting
|
|---|
| 3216 | `SHELL' (*note Communicating Variables to a Sub-`make':
|
|---|
| 3217 | Variables/Recursion.), forcing it to be passed in the environment to
|
|---|
| 3218 | commands.
|
|---|
| 3219 |
|
|---|
| 3220 | However, on MS-DOS and MS-Windows the value of `SHELL' in the
|
|---|
| 3221 | environment *is* used, since on those systems most users do not set
|
|---|
| 3222 | this variable, and therefore it is most likely set specifically to be
|
|---|
| 3223 | used by `make'. On MS-DOS, if the setting of `SHELL' is not suitable
|
|---|
| 3224 | for `make', you can set the variable `MAKESHELL' to the shell that
|
|---|
| 3225 | `make' should use; if set it will be used as the shell instead of the
|
|---|
| 3226 | value of `SHELL'.
|
|---|
| 3227 |
|
|---|
| 3228 | Choosing a Shell in DOS and Windows
|
|---|
| 3229 | ...................................
|
|---|
| 3230 |
|
|---|
| 3231 | Choosing a shell in MS-DOS and MS-Windows is much more complex than on
|
|---|
| 3232 | other systems.
|
|---|
| 3233 |
|
|---|
| 3234 | On MS-DOS, if `SHELL' is not set, the value of the variable
|
|---|
| 3235 | `COMSPEC' (which is always set) is used instead.
|
|---|
| 3236 |
|
|---|
| 3237 | The processing of lines that set the variable `SHELL' in Makefiles
|
|---|
| 3238 | is different on MS-DOS. The stock shell, `command.com', is
|
|---|
| 3239 | ridiculously limited in its functionality and many users of `make' tend
|
|---|
| 3240 | to install a replacement shell. Therefore, on MS-DOS, `make' examines
|
|---|
| 3241 | the value of `SHELL', and changes its behavior based on whether it
|
|---|
| 3242 | points to a Unix-style or DOS-style shell. This allows reasonable
|
|---|
| 3243 | functionality even if `SHELL' points to `command.com'.
|
|---|
| 3244 |
|
|---|
| 3245 | If `SHELL' points to a Unix-style shell, `make' on MS-DOS
|
|---|
| 3246 | additionally checks whether that shell can indeed be found; if not, it
|
|---|
| 3247 | ignores the line that sets `SHELL'. In MS-DOS, GNU `make' searches for
|
|---|
| 3248 | the shell in the following places:
|
|---|
| 3249 |
|
|---|
| 3250 | 1. In the precise place pointed to by the value of `SHELL'. For
|
|---|
| 3251 | example, if the makefile specifies `SHELL = /bin/sh', `make' will
|
|---|
| 3252 | look in the directory `/bin' on the current drive.
|
|---|
| 3253 |
|
|---|
| 3254 | 2. In the current directory.
|
|---|
| 3255 |
|
|---|
| 3256 | 3. In each of the directories in the `PATH' variable, in order.
|
|---|
| 3257 |
|
|---|
| 3258 |
|
|---|
| 3259 | In every directory it examines, `make' will first look for the
|
|---|
| 3260 | specific file (`sh' in the example above). If this is not found, it
|
|---|
| 3261 | will also look in that directory for that file with one of the known
|
|---|
| 3262 | extensions which identify executable files. For example `.exe',
|
|---|
| 3263 | `.com', `.bat', `.btm', `.sh', and some others.
|
|---|
| 3264 |
|
|---|
| 3265 | If any of these attempts is successful, the value of `SHELL' will be
|
|---|
| 3266 | set to the full pathname of the shell as found. However, if none of
|
|---|
| 3267 | these is found, the value of `SHELL' will not be changed, and thus the
|
|---|
| 3268 | line that sets it will be effectively ignored. This is so `make' will
|
|---|
| 3269 | only support features specific to a Unix-style shell if such a shell is
|
|---|
| 3270 | actually installed on the system where `make' runs.
|
|---|
| 3271 |
|
|---|
| 3272 | Note that this extended search for the shell is limited to the cases
|
|---|
| 3273 | where `SHELL' is set from the Makefile; if it is set in the environment
|
|---|
| 3274 | or command line, you are expected to set it to the full pathname of the
|
|---|
| 3275 | shell, exactly as things are on Unix.
|
|---|
| 3276 |
|
|---|
| 3277 | The effect of the above DOS-specific processing is that a Makefile
|
|---|
| 3278 | that contains `SHELL = /bin/sh' (as many Unix makefiles do), will work
|
|---|
| 3279 | on MS-DOS unaltered if you have e.g. `sh.exe' installed in some
|
|---|
| 3280 | directory along your `PATH'.
|
|---|
| 3281 |
|
|---|
| 3282 |
|
|---|
| 3283 | File: make.info, Node: Parallel, Next: Errors, Prev: Execution, Up: Commands
|
|---|
| 3284 |
|
|---|
| 3285 | 5.4 Parallel Execution
|
|---|
| 3286 | ======================
|
|---|
| 3287 |
|
|---|
| 3288 | GNU `make' knows how to execute several commands at once. Normally,
|
|---|
| 3289 | `make' will execute only one command at a time, waiting for it to
|
|---|
| 3290 | finish before executing the next. However, the `-j' or `--jobs' option
|
|---|
| 3291 | tells `make' to execute many commands simultaneously.
|
|---|
| 3292 |
|
|---|
| 3293 | On MS-DOS, the `-j' option has no effect, since that system doesn't
|
|---|
| 3294 | support multi-processing.
|
|---|
| 3295 |
|
|---|
| 3296 | If the `-j' option is followed by an integer, this is the number of
|
|---|
| 3297 | commands to execute at once; this is called the number of "job slots".
|
|---|
| 3298 | If there is nothing looking like an integer after the `-j' option,
|
|---|
| 3299 | there is no limit on the number of job slots. The default number of job
|
|---|
| 3300 | slots is one, which means serial execution (one thing at a time).
|
|---|
| 3301 |
|
|---|
| 3302 | One unpleasant consequence of running several commands
|
|---|
| 3303 | simultaneously is that output generated by the commands appears
|
|---|
| 3304 | whenever each command sends it, so messages from different commands may
|
|---|
| 3305 | be interspersed.
|
|---|
| 3306 |
|
|---|
| 3307 | Another problem is that two processes cannot both take input from the
|
|---|
| 3308 | same device; so to make sure that only one command tries to take input
|
|---|
| 3309 | from the terminal at once, `make' will invalidate the standard input
|
|---|
| 3310 | streams of all but one running command. This means that attempting to
|
|---|
| 3311 | read from standard input will usually be a fatal error (a `Broken pipe'
|
|---|
| 3312 | signal) for most child processes if there are several.
|
|---|
| 3313 |
|
|---|
| 3314 | It is unpredictable which command will have a valid standard input
|
|---|
| 3315 | stream (which will come from the terminal, or wherever you redirect the
|
|---|
| 3316 | standard input of `make'). The first command run will always get it
|
|---|
| 3317 | first, and the first command started after that one finishes will get
|
|---|
| 3318 | it next, and so on.
|
|---|
| 3319 |
|
|---|
| 3320 | We will change how this aspect of `make' works if we find a better
|
|---|
| 3321 | alternative. In the mean time, you should not rely on any command using
|
|---|
| 3322 | standard input at all if you are using the parallel execution feature;
|
|---|
| 3323 | but if you are not using this feature, then standard input works
|
|---|
| 3324 | normally in all commands.
|
|---|
| 3325 |
|
|---|
| 3326 | Finally, handling recursive `make' invocations raises issues. For
|
|---|
| 3327 | more information on this, see *Note Communicating Options to a
|
|---|
| 3328 | Sub-`make': Options/Recursion.
|
|---|
| 3329 |
|
|---|
| 3330 | If a command fails (is killed by a signal or exits with a nonzero
|
|---|
| 3331 | status), and errors are not ignored for that command (*note Errors in
|
|---|
| 3332 | Commands: Errors.), the remaining command lines to remake the same
|
|---|
| 3333 | target will not be run. If a command fails and the `-k' or
|
|---|
| 3334 | `--keep-going' option was not given (*note Summary of Options: Options
|
|---|
| 3335 | Summary.), `make' aborts execution. If make terminates for any reason
|
|---|
| 3336 | (including a signal) with child processes running, it waits for them to
|
|---|
| 3337 | finish before actually exiting.
|
|---|
| 3338 |
|
|---|
| 3339 | When the system is heavily loaded, you will probably want to run
|
|---|
| 3340 | fewer jobs than when it is lightly loaded. You can use the `-l' option
|
|---|
| 3341 | to tell `make' to limit the number of jobs to run at once, based on the
|
|---|
| 3342 | load average. The `-l' or `--max-load' option is followed by a
|
|---|
| 3343 | floating-point number. For example,
|
|---|
| 3344 |
|
|---|
| 3345 | -l 2.5
|
|---|
| 3346 |
|
|---|
| 3347 | will not let `make' start more than one job if the load average is
|
|---|
| 3348 | above 2.5. The `-l' option with no following number removes the load
|
|---|
| 3349 | limit, if one was given with a previous `-l' option.
|
|---|
| 3350 |
|
|---|
| 3351 | More precisely, when `make' goes to start up a job, and it already
|
|---|
| 3352 | has at least one job running, it checks the current load average; if it
|
|---|
| 3353 | is not lower than the limit given with `-l', `make' waits until the load
|
|---|
| 3354 | average goes below that limit, or until all the other jobs finish.
|
|---|
| 3355 |
|
|---|
| 3356 | By default, there is no load limit.
|
|---|
| 3357 |
|
|---|
| 3358 |
|
|---|
| 3359 | File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Commands
|
|---|
| 3360 |
|
|---|
| 3361 | 5.5 Errors in Commands
|
|---|
| 3362 | ======================
|
|---|
| 3363 |
|
|---|
| 3364 | After each shell command returns, `make' looks at its exit status. If
|
|---|
| 3365 | the command completed successfully, the next command line is executed
|
|---|
| 3366 | in a new shell; after the last command line is finished, the rule is
|
|---|
| 3367 | finished.
|
|---|
| 3368 |
|
|---|
| 3369 | If there is an error (the exit status is nonzero), `make' gives up on
|
|---|
| 3370 | the current rule, and perhaps on all rules.
|
|---|
| 3371 |
|
|---|
| 3372 | Sometimes the failure of a certain command does not indicate a
|
|---|
| 3373 | problem. For example, you may use the `mkdir' command to ensure that a
|
|---|
| 3374 | directory exists. If the directory already exists, `mkdir' will report
|
|---|
| 3375 | an error, but you probably want `make' to continue regardless.
|
|---|
| 3376 |
|
|---|
| 3377 | To ignore errors in a command line, write a `-' at the beginning of
|
|---|
| 3378 | the line's text (after the initial tab). The `-' is discarded before
|
|---|
| 3379 | the command is passed to the shell for execution.
|
|---|
| 3380 |
|
|---|
| 3381 | For example,
|
|---|
| 3382 |
|
|---|
| 3383 | clean:
|
|---|
| 3384 | -rm -f *.o
|
|---|
| 3385 |
|
|---|
| 3386 | This causes `rm' to continue even if it is unable to remove a file.
|
|---|
| 3387 |
|
|---|
| 3388 | When you run `make' with the `-i' or `--ignore-errors' flag, errors
|
|---|
| 3389 | are ignored in all commands of all rules. A rule in the makefile for
|
|---|
| 3390 | the special target `.IGNORE' has the same effect, if there are no
|
|---|
| 3391 | prerequisites. These ways of ignoring errors are obsolete because `-'
|
|---|
| 3392 | is more flexible.
|
|---|
| 3393 |
|
|---|
| 3394 | When errors are to be ignored, because of either a `-' or the `-i'
|
|---|
| 3395 | flag, `make' treats an error return just like success, except that it
|
|---|
| 3396 | prints out a message that tells you the status code the command exited
|
|---|
| 3397 | with, and says that the error has been ignored.
|
|---|
| 3398 |
|
|---|
| 3399 | When an error happens that `make' has not been told to ignore, it
|
|---|
| 3400 | implies that the current target cannot be correctly remade, and neither
|
|---|
| 3401 | can any other that depends on it either directly or indirectly. No
|
|---|
| 3402 | further commands will be executed for these targets, since their
|
|---|
| 3403 | preconditions have not been achieved.
|
|---|
| 3404 |
|
|---|
| 3405 | Normally `make' gives up immediately in this circumstance, returning
|
|---|
| 3406 | a nonzero status. However, if the `-k' or `--keep-going' flag is
|
|---|
| 3407 | specified, `make' continues to consider the other prerequisites of the
|
|---|
| 3408 | pending targets, remaking them if necessary, before it gives up and
|
|---|
| 3409 | returns nonzero status. For example, after an error in compiling one
|
|---|
| 3410 | object file, `make -k' will continue compiling other object files even
|
|---|
| 3411 | though it already knows that linking them will be impossible. *Note
|
|---|
| 3412 | Summary of Options: Options Summary.
|
|---|
| 3413 |
|
|---|
| 3414 | The usual behavior assumes that your purpose is to get the specified
|
|---|
| 3415 | targets up to date; once `make' learns that this is impossible, it
|
|---|
| 3416 | might as well report the failure immediately. The `-k' option says
|
|---|
| 3417 | that the real purpose is to test as many of the changes made in the
|
|---|
| 3418 | program as possible, perhaps to find several independent problems so
|
|---|
| 3419 | that you can correct them all before the next attempt to compile. This
|
|---|
| 3420 | is why Emacs' `compile' command passes the `-k' flag by default.
|
|---|
| 3421 |
|
|---|
| 3422 | Usually when a command fails, if it has changed the target file at
|
|---|
| 3423 | all, the file is corrupted and cannot be used--or at least it is not
|
|---|
| 3424 | completely updated. Yet the file's time stamp says that it is now up to
|
|---|
| 3425 | date, so the next time `make' runs, it will not try to update that
|
|---|
| 3426 | file. The situation is just the same as when the command is killed by a
|
|---|
| 3427 | signal; *note Interrupts::. So generally the right thing to do is to
|
|---|
| 3428 | delete the target file if the command fails after beginning to change
|
|---|
| 3429 | the file. `make' will do this if `.DELETE_ON_ERROR' appears as a
|
|---|
| 3430 | target. This is almost always what you want `make' to do, but it is
|
|---|
| 3431 | not historical practice; so for compatibility, you must explicitly
|
|---|
| 3432 | request it.
|
|---|
| 3433 |
|
|---|
| 3434 |
|
|---|
| 3435 | File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Commands
|
|---|
| 3436 |
|
|---|
| 3437 | 5.6 Interrupting or Killing `make'
|
|---|
| 3438 | ==================================
|
|---|
| 3439 |
|
|---|
| 3440 | If `make' gets a fatal signal while a command is executing, it may
|
|---|
| 3441 | delete the target file that the command was supposed to update. This is
|
|---|
| 3442 | done if the target file's last-modification time has changed since
|
|---|
| 3443 | `make' first checked it.
|
|---|
| 3444 |
|
|---|
| 3445 | The purpose of deleting the target is to make sure that it is remade
|
|---|
| 3446 | from scratch when `make' is next run. Why is this? Suppose you type
|
|---|
| 3447 | `Ctrl-c' while a compiler is running, and it has begun to write an
|
|---|
| 3448 | object file `foo.o'. The `Ctrl-c' kills the compiler, resulting in an
|
|---|
| 3449 | incomplete file whose last-modification time is newer than the source
|
|---|
| 3450 | file `foo.c'. But `make' also receives the `Ctrl-c' signal and deletes
|
|---|
| 3451 | this incomplete file. If `make' did not do this, the next invocation
|
|---|
| 3452 | of `make' would think that `foo.o' did not require updating--resulting
|
|---|
| 3453 | in a strange error message from the linker when it tries to link an
|
|---|
| 3454 | object file half of which is missing.
|
|---|
| 3455 |
|
|---|
| 3456 | You can prevent the deletion of a target file in this way by making
|
|---|
| 3457 | the special target `.PRECIOUS' depend on it. Before remaking a target,
|
|---|
| 3458 | `make' checks to see whether it appears on the prerequisites of
|
|---|
| 3459 | `.PRECIOUS', and thereby decides whether the target should be deleted
|
|---|
| 3460 | if a signal happens. Some reasons why you might do this are that the
|
|---|
| 3461 | target is updated in some atomic fashion, or exists only to record a
|
|---|
| 3462 | modification-time (its contents do not matter), or must exist at all
|
|---|
| 3463 | times to prevent other sorts of trouble.
|
|---|
| 3464 |
|
|---|
| 3465 |
|
|---|
| 3466 | File: make.info, Node: Recursion, Next: Sequences, Prev: Interrupts, Up: Commands
|
|---|
| 3467 |
|
|---|
| 3468 | 5.7 Recursive Use of `make'
|
|---|
| 3469 | ===========================
|
|---|
| 3470 |
|
|---|
| 3471 | Recursive use of `make' means using `make' as a command in a makefile.
|
|---|
| 3472 | This technique is useful when you want separate makefiles for various
|
|---|
| 3473 | subsystems that compose a larger system. For example, suppose you have
|
|---|
| 3474 | a subdirectory `subdir' which has its own makefile, and you would like
|
|---|
| 3475 | the containing directory's makefile to run `make' on the subdirectory.
|
|---|
| 3476 | You can do it by writing this:
|
|---|
| 3477 |
|
|---|
| 3478 | subsystem:
|
|---|
| 3479 | cd subdir && $(MAKE)
|
|---|
| 3480 |
|
|---|
| 3481 | or, equivalently, this (*note Summary of Options: Options Summary.):
|
|---|
| 3482 |
|
|---|
| 3483 | subsystem:
|
|---|
| 3484 | $(MAKE) -C subdir
|
|---|
| 3485 |
|
|---|
| 3486 | You can write recursive `make' commands just by copying this example,
|
|---|
| 3487 | but there are many things to know about how they work and why, and about
|
|---|
| 3488 | how the sub-`make' relates to the top-level `make'. You may also find
|
|---|
| 3489 | it useful to declare targets that invoke recursive `make' commands as
|
|---|
| 3490 | `.PHONY' (for more discussion on when this is useful, see *Note Phony
|
|---|
| 3491 | Targets::).
|
|---|
| 3492 |
|
|---|
| 3493 | For your convenience, when GNU `make' starts (after it has processed
|
|---|
| 3494 | any `-C' options) it sets the variable `CURDIR' to the pathname of the
|
|---|
| 3495 | current working directory. This value is never touched by `make'
|
|---|
| 3496 | again: in particular note that if you include files from other
|
|---|
| 3497 | directories the value of `CURDIR' does not change. The value has the
|
|---|
| 3498 | same precedence it would have if it were set in the makefile (by
|
|---|
| 3499 | default, an environment variable `CURDIR' will not override this
|
|---|
| 3500 | value). Note that setting this variable has no impact on the operation
|
|---|
| 3501 | of `make' (it does not cause `make' to change its working directory,
|
|---|
| 3502 | for example).
|
|---|
| 3503 |
|
|---|
| 3504 | * Menu:
|
|---|
| 3505 |
|
|---|
| 3506 | * MAKE Variable:: The special effects of using `$(MAKE)'.
|
|---|
| 3507 | * Variables/Recursion:: How to communicate variables to a sub-`make'.
|
|---|
| 3508 | * Options/Recursion:: How to communicate options to a sub-`make'.
|
|---|
| 3509 | * -w Option:: How the `-w' or `--print-directory' option
|
|---|
| 3510 | helps debug use of recursive `make' commands.
|
|---|
| 3511 |
|
|---|
| 3512 |
|
|---|
| 3513 | File: make.info, Node: MAKE Variable, Next: Variables/Recursion, Prev: Recursion, Up: Recursion
|
|---|
| 3514 |
|
|---|
| 3515 | 5.7.1 How the `MAKE' Variable Works
|
|---|
| 3516 | -----------------------------------
|
|---|
| 3517 |
|
|---|
| 3518 | Recursive `make' commands should always use the variable `MAKE', not
|
|---|
| 3519 | the explicit command name `make', as shown here:
|
|---|
| 3520 |
|
|---|
| 3521 | subsystem:
|
|---|
| 3522 | cd subdir && $(MAKE)
|
|---|
| 3523 |
|
|---|
| 3524 | The value of this variable is the file name with which `make' was
|
|---|
| 3525 | invoked. If this file name was `/bin/make', then the command executed
|
|---|
| 3526 | is `cd subdir && /bin/make'. If you use a special version of `make' to
|
|---|
| 3527 | run the top-level makefile, the same special version will be executed
|
|---|
| 3528 | for recursive invocations.
|
|---|
| 3529 |
|
|---|
| 3530 | As a special feature, using the variable `MAKE' in the commands of a
|
|---|
| 3531 | rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'),
|
|---|
| 3532 | or `-q' (`--question') option. Using the `MAKE' variable has the same
|
|---|
| 3533 | effect as using a `+' character at the beginning of the command line.
|
|---|
| 3534 | *Note Instead of Executing the Commands: Instead of Execution. This
|
|---|
| 3535 | special feature is only enabled if the `MAKE' variable appears directly
|
|---|
| 3536 | in the command script: it does not apply if the `MAKE' variable is
|
|---|
| 3537 | referenced through expansion of another variable. In the latter case
|
|---|
| 3538 | you must use the `+' token to get these special effects.
|
|---|
| 3539 |
|
|---|
| 3540 | Consider the command `make -t' in the above example. (The `-t'
|
|---|
| 3541 | option marks targets as up to date without actually running any
|
|---|
| 3542 | commands; see *Note Instead of Execution::.) Following the usual
|
|---|
| 3543 | definition of `-t', a `make -t' command in the example would create a
|
|---|
| 3544 | file named `subsystem' and do nothing else. What you really want it to
|
|---|
| 3545 | do is run `cd subdir && make -t'; but that would require executing the
|
|---|
| 3546 | command, and `-t' says not to execute commands.
|
|---|
| 3547 |
|
|---|
| 3548 | The special feature makes this do what you want: whenever a command
|
|---|
| 3549 | line of a rule contains the variable `MAKE', the flags `-t', `-n' and
|
|---|
| 3550 | `-q' do not apply to that line. Command lines containing `MAKE' are
|
|---|
| 3551 | executed normally despite the presence of a flag that causes most
|
|---|
| 3552 | commands not to be run. The usual `MAKEFLAGS' mechanism passes the
|
|---|
| 3553 | flags to the sub-`make' (*note Communicating Options to a Sub-`make':
|
|---|
| 3554 | Options/Recursion.), so your request to touch the files, or print the
|
|---|
| 3555 | commands, is propagated to the subsystem.
|
|---|
| 3556 |
|
|---|
| 3557 |
|
|---|
| 3558 | File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MAKE Variable, Up: Recursion
|
|---|
| 3559 |
|
|---|
| 3560 | 5.7.2 Communicating Variables to a Sub-`make'
|
|---|
| 3561 | ---------------------------------------------
|
|---|
| 3562 |
|
|---|
| 3563 | Variable values of the top-level `make' can be passed to the sub-`make'
|
|---|
| 3564 | through the environment by explicit request. These variables are
|
|---|
| 3565 | defined in the sub-`make' as defaults, but do not override what is
|
|---|
| 3566 | specified in the makefile used by the sub-`make' makefile unless you
|
|---|
| 3567 | use the `-e' switch (*note Summary of Options: Options Summary.).
|
|---|
| 3568 |
|
|---|
| 3569 | To pass down, or "export", a variable, `make' adds the variable and
|
|---|
| 3570 | its value to the environment for running each command. The sub-`make',
|
|---|
| 3571 | in turn, uses the environment to initialize its table of variable
|
|---|
| 3572 | values. *Note Variables from the Environment: Environment.
|
|---|
| 3573 |
|
|---|
| 3574 | Except by explicit request, `make' exports a variable only if it is
|
|---|
| 3575 | either defined in the environment initially or set on the command line,
|
|---|
| 3576 | and if its name consists only of letters, numbers, and underscores.
|
|---|
| 3577 | Some shells cannot cope with environment variable names consisting of
|
|---|
| 3578 | characters other than letters, numbers, and underscores.
|
|---|
| 3579 |
|
|---|
| 3580 | The value of the `make' variable `SHELL' is not exported. Instead,
|
|---|
| 3581 | the value of the `SHELL' variable from the invoking environment is
|
|---|
| 3582 | passed to the sub-`make'. You can force `make' to export its value for
|
|---|
| 3583 | `SHELL' by using the `export' directive, described below. *Note
|
|---|
| 3584 | Choosing the Shell::.
|
|---|
| 3585 |
|
|---|
| 3586 | The special variable `MAKEFLAGS' is always exported (unless you
|
|---|
| 3587 | unexport it). `MAKEFILES' is exported if you set it to anything.
|
|---|
| 3588 |
|
|---|
| 3589 | `make' automatically passes down variable values that were defined
|
|---|
| 3590 | on the command line, by putting them in the `MAKEFLAGS' variable.
|
|---|
| 3591 | *Note Options/Recursion::.
|
|---|
| 3592 |
|
|---|
| 3593 | Variables are _not_ normally passed down if they were created by
|
|---|
| 3594 | default by `make' (*note Variables Used by Implicit Rules: Implicit
|
|---|
| 3595 | Variables.). The sub-`make' will define these for itself.
|
|---|
| 3596 |
|
|---|
| 3597 | If you want to export specific variables to a sub-`make', use the
|
|---|
| 3598 | `export' directive, like this:
|
|---|
| 3599 |
|
|---|
| 3600 | export VARIABLE ...
|
|---|
| 3601 |
|
|---|
| 3602 | If you want to _prevent_ a variable from being exported, use the
|
|---|
| 3603 | `unexport' directive, like this:
|
|---|
| 3604 |
|
|---|
| 3605 | unexport VARIABLE ...
|
|---|
| 3606 |
|
|---|
| 3607 | In both of these forms, the arguments to `export' and `unexport' are
|
|---|
| 3608 | expanded, and so could be variables or functions which expand to a
|
|---|
| 3609 | (list of) variable names to be (un)exported.
|
|---|
| 3610 |
|
|---|
| 3611 | As a convenience, you can define a variable and export it at the same
|
|---|
| 3612 | time by doing:
|
|---|
| 3613 |
|
|---|
| 3614 | export VARIABLE = value
|
|---|
| 3615 |
|
|---|
| 3616 | has the same result as:
|
|---|
| 3617 |
|
|---|
| 3618 | VARIABLE = value
|
|---|
| 3619 | export VARIABLE
|
|---|
| 3620 |
|
|---|
| 3621 | and
|
|---|
| 3622 |
|
|---|
| 3623 | export VARIABLE := value
|
|---|
| 3624 |
|
|---|
| 3625 | has the same result as:
|
|---|
| 3626 |
|
|---|
| 3627 | VARIABLE := value
|
|---|
| 3628 | export VARIABLE
|
|---|
| 3629 |
|
|---|
| 3630 | Likewise,
|
|---|
| 3631 |
|
|---|
| 3632 | export VARIABLE += value
|
|---|
| 3633 |
|
|---|
| 3634 | is just like:
|
|---|
| 3635 |
|
|---|
| 3636 | VARIABLE += value
|
|---|
| 3637 | export VARIABLE
|
|---|
| 3638 |
|
|---|
| 3639 | *Note Appending More Text to Variables: Appending.
|
|---|
| 3640 |
|
|---|
| 3641 | You may notice that the `export' and `unexport' directives work in
|
|---|
| 3642 | `make' in the same way they work in the shell, `sh'.
|
|---|
| 3643 |
|
|---|
| 3644 | If you want all variables to be exported by default, you can use
|
|---|
| 3645 | `export' by itself:
|
|---|
| 3646 |
|
|---|
| 3647 | export
|
|---|
| 3648 |
|
|---|
| 3649 | This tells `make' that variables which are not explicitly mentioned in
|
|---|
| 3650 | an `export' or `unexport' directive should be exported. Any variable
|
|---|
| 3651 | given in an `unexport' directive will still _not_ be exported. If you
|
|---|
| 3652 | use `export' by itself to export variables by default, variables whose
|
|---|
| 3653 | names contain characters other than alphanumerics and underscores will
|
|---|
| 3654 | not be exported unless specifically mentioned in an `export' directive.
|
|---|
| 3655 |
|
|---|
| 3656 | The behavior elicited by an `export' directive by itself was the
|
|---|
| 3657 | default in older versions of GNU `make'. If your makefiles depend on
|
|---|
| 3658 | this behavior and you want to be compatible with old versions of
|
|---|
| 3659 | `make', you can write a rule for the special target
|
|---|
| 3660 | `.EXPORT_ALL_VARIABLES' instead of using the `export' directive. This
|
|---|
| 3661 | will be ignored by old `make's, while the `export' directive will cause
|
|---|
| 3662 | a syntax error.
|
|---|
| 3663 |
|
|---|
| 3664 | Likewise, you can use `unexport' by itself to tell `make' _not_ to
|
|---|
| 3665 | export variables by default. Since this is the default behavior, you
|
|---|
| 3666 | would only need to do this if `export' had been used by itself earlier
|
|---|
| 3667 | (in an included makefile, perhaps). You *cannot* use `export' and
|
|---|
| 3668 | `unexport' by themselves to have variables exported for some commands
|
|---|
| 3669 | and not for others. The last `export' or `unexport' directive that
|
|---|
| 3670 | appears by itself determines the behavior for the entire run of `make'.
|
|---|
| 3671 |
|
|---|
| 3672 | As a special feature, the variable `MAKELEVEL' is changed when it is
|
|---|
| 3673 | passed down from level to level. This variable's value is a string
|
|---|
| 3674 | which is the depth of the level as a decimal number. The value is `0'
|
|---|
| 3675 | for the top-level `make'; `1' for a sub-`make', `2' for a
|
|---|
| 3676 | sub-sub-`make', and so on. The incrementation happens when `make' sets
|
|---|
| 3677 | up the environment for a command.
|
|---|
| 3678 |
|
|---|
| 3679 | The main use of `MAKELEVEL' is to test it in a conditional directive
|
|---|
| 3680 | (*note Conditional Parts of Makefiles: Conditionals.); this way you can
|
|---|
| 3681 | write a makefile that behaves one way if run recursively and another
|
|---|
| 3682 | way if run directly by you.
|
|---|
| 3683 |
|
|---|
| 3684 | You can use the variable `MAKEFILES' to cause all sub-`make'
|
|---|
| 3685 | commands to use additional makefiles. The value of `MAKEFILES' is a
|
|---|
| 3686 | whitespace-separated list of file names. This variable, if defined in
|
|---|
| 3687 | the outer-level makefile, is passed down through the environment; then
|
|---|
| 3688 | it serves as a list of extra makefiles for the sub-`make' to read
|
|---|
| 3689 | before the usual or specified ones. *Note The Variable `MAKEFILES':
|
|---|
| 3690 | MAKEFILES Variable.
|
|---|
| 3691 |
|
|---|
| 3692 |
|
|---|
| 3693 | File: make.info, Node: Options/Recursion, Next: -w Option, Prev: Variables/Recursion, Up: Recursion
|
|---|
| 3694 |
|
|---|
| 3695 | 5.7.3 Communicating Options to a Sub-`make'
|
|---|
| 3696 | -------------------------------------------
|
|---|
| 3697 |
|
|---|
| 3698 | Flags such as `-s' and `-k' are passed automatically to the sub-`make'
|
|---|
| 3699 | through the variable `MAKEFLAGS'. This variable is set up
|
|---|
| 3700 | automatically by `make' to contain the flag letters that `make'
|
|---|
| 3701 | received. Thus, if you do `make -ks' then `MAKEFLAGS' gets the value
|
|---|
| 3702 | `ks'.
|
|---|
| 3703 |
|
|---|
| 3704 | As a consequence, every sub-`make' gets a value for `MAKEFLAGS' in
|
|---|
| 3705 | its environment. In response, it takes the flags from that value and
|
|---|
| 3706 | processes them as if they had been given as arguments. *Note Summary
|
|---|
| 3707 | of Options: Options Summary.
|
|---|
| 3708 |
|
|---|
| 3709 | Likewise variables defined on the command line are passed to the
|
|---|
| 3710 | sub-`make' through `MAKEFLAGS'. Words in the value of `MAKEFLAGS' that
|
|---|
| 3711 | contain `=', `make' treats as variable definitions just as if they
|
|---|
| 3712 | appeared on the command line. *Note Overriding Variables: Overriding.
|
|---|
| 3713 |
|
|---|
| 3714 | The options `-C', `-f', `-o', and `-W' are not put into `MAKEFLAGS';
|
|---|
| 3715 | these options are not passed down.
|
|---|
| 3716 |
|
|---|
| 3717 | The `-j' option is a special case (*note Parallel Execution:
|
|---|
| 3718 | Parallel.). If you set it to some numeric value `N' and your operating
|
|---|
| 3719 | system supports it (most any UNIX system will; others typically won't),
|
|---|
| 3720 | the parent `make' and all the sub-`make's will communicate to ensure
|
|---|
| 3721 | that there are only `N' jobs running at the same time between them all.
|
|---|
| 3722 | Note that any job that is marked recursive (*note Instead of Executing
|
|---|
| 3723 | the Commands: Instead of Execution.) doesn't count against the total
|
|---|
| 3724 | jobs (otherwise we could get `N' sub-`make's running and have no slots
|
|---|
| 3725 | left over for any real work!)
|
|---|
| 3726 |
|
|---|
| 3727 | If your operating system doesn't support the above communication,
|
|---|
| 3728 | then `-j 1' is always put into `MAKEFLAGS' instead of the value you
|
|---|
| 3729 | specified. This is because if the `-j' option were passed down to
|
|---|
| 3730 | sub-`make's, you would get many more jobs running in parallel than you
|
|---|
| 3731 | asked for. If you give `-j' with no numeric argument, meaning to run
|
|---|
| 3732 | as many jobs as possible in parallel, this is passed down, since
|
|---|
| 3733 | multiple infinities are no more than one.
|
|---|
| 3734 |
|
|---|
| 3735 | If you do not want to pass the other flags down, you must change the
|
|---|
| 3736 | value of `MAKEFLAGS', like this:
|
|---|
| 3737 |
|
|---|
| 3738 | subsystem:
|
|---|
| 3739 | cd subdir && $(MAKE) MAKEFLAGS=
|
|---|
| 3740 |
|
|---|
| 3741 | The command line variable definitions really appear in the variable
|
|---|
| 3742 | `MAKEOVERRIDES', and `MAKEFLAGS' contains a reference to this variable.
|
|---|
| 3743 | If you do want to pass flags down normally, but don't want to pass
|
|---|
| 3744 | down the command line variable definitions, you can reset
|
|---|
| 3745 | `MAKEOVERRIDES' to empty, like this:
|
|---|
| 3746 |
|
|---|
| 3747 | MAKEOVERRIDES =
|
|---|
| 3748 |
|
|---|
| 3749 | This is not usually useful to do. However, some systems have a small
|
|---|
| 3750 | fixed limit on the size of the environment, and putting so much
|
|---|
| 3751 | information into the value of `MAKEFLAGS' can exceed it. If you see
|
|---|
| 3752 | the error message `Arg list too long', this may be the problem. (For
|
|---|
| 3753 | strict compliance with POSIX.2, changing `MAKEOVERRIDES' does not
|
|---|
| 3754 | affect `MAKEFLAGS' if the special target `.POSIX' appears in the
|
|---|
| 3755 | makefile. You probably do not care about this.)
|
|---|
| 3756 |
|
|---|
| 3757 | A similar variable `MFLAGS' exists also, for historical
|
|---|
| 3758 | compatibility. It has the same value as `MAKEFLAGS' except that it
|
|---|
| 3759 | does not contain the command line variable definitions, and it always
|
|---|
| 3760 | begins with a hyphen unless it is empty (`MAKEFLAGS' begins with a
|
|---|
| 3761 | hyphen only when it begins with an option that has no single-letter
|
|---|
| 3762 | version, such as `--warn-undefined-variables'). `MFLAGS' was
|
|---|
| 3763 | traditionally used explicitly in the recursive `make' command, like
|
|---|
| 3764 | this:
|
|---|
| 3765 |
|
|---|
| 3766 | subsystem:
|
|---|
| 3767 | cd subdir && $(MAKE) $(MFLAGS)
|
|---|
| 3768 |
|
|---|
| 3769 | but now `MAKEFLAGS' makes this usage redundant. If you want your
|
|---|
| 3770 | makefiles to be compatible with old `make' programs, use this
|
|---|
| 3771 | technique; it will work fine with more modern `make' versions too.
|
|---|
| 3772 |
|
|---|
| 3773 | The `MAKEFLAGS' variable can also be useful if you want to have
|
|---|
| 3774 | certain options, such as `-k' (*note Summary of Options: Options
|
|---|
| 3775 | Summary.), set each time you run `make'. You simply put a value for
|
|---|
| 3776 | `MAKEFLAGS' in your environment. You can also set `MAKEFLAGS' in a
|
|---|
| 3777 | makefile, to specify additional flags that should also be in effect for
|
|---|
| 3778 | that makefile. (Note that you cannot use `MFLAGS' this way. That
|
|---|
| 3779 | variable is set only for compatibility; `make' does not interpret a
|
|---|
| 3780 | value you set for it in any way.)
|
|---|
| 3781 |
|
|---|
| 3782 | When `make' interprets the value of `MAKEFLAGS' (either from the
|
|---|
| 3783 | environment or from a makefile), it first prepends a hyphen if the value
|
|---|
| 3784 | does not already begin with one. Then it chops the value into words
|
|---|
| 3785 | separated by blanks, and parses these words as if they were options
|
|---|
| 3786 | given on the command line (except that `-C', `-f', `-h', `-o', `-W',
|
|---|
| 3787 | and their long-named versions are ignored; and there is no error for an
|
|---|
| 3788 | invalid option).
|
|---|
| 3789 |
|
|---|
| 3790 | If you do put `MAKEFLAGS' in your environment, you should be sure not
|
|---|
| 3791 | to include any options that will drastically affect the actions of
|
|---|
| 3792 | `make' and undermine the purpose of makefiles and of `make' itself.
|
|---|
| 3793 | For instance, the `-t', `-n', and `-q' options, if put in one of these
|
|---|
| 3794 | variables, could have disastrous consequences and would certainly have
|
|---|
| 3795 | at least surprising and probably annoying effects.
|
|---|
| 3796 |
|
|---|
| 3797 |
|
|---|
| 3798 | File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion
|
|---|
| 3799 |
|
|---|
| 3800 | 5.7.4 The `--print-directory' Option
|
|---|
| 3801 | ------------------------------------
|
|---|
| 3802 |
|
|---|
| 3803 | If you use several levels of recursive `make' invocations, the `-w' or
|
|---|
| 3804 | `--print-directory' option can make the output a lot easier to
|
|---|
| 3805 | understand by showing each directory as `make' starts processing it and
|
|---|
| 3806 | as `make' finishes processing it. For example, if `make -w' is run in
|
|---|
| 3807 | the directory `/u/gnu/make', `make' will print a line of the form:
|
|---|
| 3808 |
|
|---|
| 3809 | make: Entering directory `/u/gnu/make'.
|
|---|
| 3810 |
|
|---|
| 3811 | before doing anything else, and a line of the form:
|
|---|
| 3812 |
|
|---|
| 3813 | make: Leaving directory `/u/gnu/make'.
|
|---|
| 3814 |
|
|---|
| 3815 | when processing is completed.
|
|---|
| 3816 |
|
|---|
| 3817 | Normally, you do not need to specify this option because `make' does
|
|---|
| 3818 | it for you: `-w' is turned on automatically when you use the `-C'
|
|---|
| 3819 | option, and in sub-`make's. `make' will not automatically turn on `-w'
|
|---|
| 3820 | if you also use `-s', which says to be silent, or if you use
|
|---|
| 3821 | `--no-print-directory' to explicitly disable it.
|
|---|
| 3822 |
|
|---|
| 3823 |
|
|---|
| 3824 | File: make.info, Node: Sequences, Next: Empty Commands, Prev: Recursion, Up: Commands
|
|---|
| 3825 |
|
|---|
| 3826 | 5.8 Defining Canned Command Sequences
|
|---|
| 3827 | =====================================
|
|---|
| 3828 |
|
|---|
| 3829 | When the same sequence of commands is useful in making various targets,
|
|---|
| 3830 | you can define it as a canned sequence with the `define' directive, and
|
|---|
| 3831 | refer to the canned sequence from the rules for those targets. The
|
|---|
| 3832 | canned sequence is actually a variable, so the name must not conflict
|
|---|
| 3833 | with other variable names.
|
|---|
| 3834 |
|
|---|
| 3835 | Here is an example of defining a canned sequence of commands:
|
|---|
| 3836 |
|
|---|
| 3837 | define run-yacc
|
|---|
| 3838 | yacc $(firstword $^)
|
|---|
| 3839 | mv y.tab.c $@
|
|---|
| 3840 | endef
|
|---|
| 3841 |
|
|---|
| 3842 | Here `run-yacc' is the name of the variable being defined; `endef'
|
|---|
| 3843 | marks the end of the definition; the lines in between are the commands.
|
|---|
| 3844 | The `define' directive does not expand variable references and
|
|---|
| 3845 | function calls in the canned sequence; the `$' characters, parentheses,
|
|---|
| 3846 | variable names, and so on, all become part of the value of the variable
|
|---|
| 3847 | you are defining. *Note Defining Variables Verbatim: Defining, for a
|
|---|
| 3848 | complete explanation of `define'.
|
|---|
| 3849 |
|
|---|
| 3850 | The first command in this example runs Yacc on the first
|
|---|
| 3851 | prerequisite of whichever rule uses the canned sequence. The output
|
|---|
| 3852 | file from Yacc is always named `y.tab.c'. The second command moves the
|
|---|
| 3853 | output to the rule's target file name.
|
|---|
| 3854 |
|
|---|
| 3855 | To use the canned sequence, substitute the variable into the
|
|---|
| 3856 | commands of a rule. You can substitute it like any other variable
|
|---|
| 3857 | (*note Basics of Variable References: Reference.). Because variables
|
|---|
| 3858 | defined by `define' are recursively expanded variables, all the
|
|---|
| 3859 | variable references you wrote inside the `define' are expanded now.
|
|---|
| 3860 | For example:
|
|---|
| 3861 |
|
|---|
| 3862 | foo.c : foo.y
|
|---|
| 3863 | $(run-yacc)
|
|---|
| 3864 |
|
|---|
| 3865 | `foo.y' will be substituted for the variable `$^' when it occurs in
|
|---|
| 3866 | `run-yacc''s value, and `foo.c' for `$@'.
|
|---|
| 3867 |
|
|---|
| 3868 | This is a realistic example, but this particular one is not needed in
|
|---|
| 3869 | practice because `make' has an implicit rule to figure out these
|
|---|
| 3870 | commands based on the file names involved (*note Using Implicit Rules:
|
|---|
| 3871 | Implicit Rules.).
|
|---|
| 3872 |
|
|---|
| 3873 | In command execution, each line of a canned sequence is treated just
|
|---|
| 3874 | as if the line appeared on its own in the rule, preceded by a tab. In
|
|---|
| 3875 | particular, `make' invokes a separate subshell for each line. You can
|
|---|
| 3876 | use the special prefix characters that affect command lines (`@', `-',
|
|---|
| 3877 | and `+') on each line of a canned sequence. *Note Writing the Commands
|
|---|
| 3878 | in Rules: Commands. For example, using this canned sequence:
|
|---|
| 3879 |
|
|---|
| 3880 | define frobnicate
|
|---|
| 3881 | @echo "frobnicating target $@"
|
|---|
| 3882 | frob-step-1 $< -o $@-step-1
|
|---|
| 3883 | frob-step-2 $@-step-1 -o $@
|
|---|
| 3884 | endef
|
|---|
| 3885 |
|
|---|
| 3886 | `make' will not echo the first line, the `echo' command. But it _will_
|
|---|
| 3887 | echo the following two command lines.
|
|---|
| 3888 |
|
|---|
| 3889 | On the other hand, prefix characters on the command line that refers
|
|---|
| 3890 | to a canned sequence apply to every line in the sequence. So the rule:
|
|---|
| 3891 |
|
|---|
| 3892 | frob.out: frob.in
|
|---|
| 3893 | @$(frobnicate)
|
|---|
| 3894 |
|
|---|
| 3895 | does not echo _any_ commands. (*Note Command Echoing: Echoing, for a
|
|---|
| 3896 | full explanation of `@'.)
|
|---|
| 3897 |
|
|---|
| 3898 |
|
|---|
| 3899 | File: make.info, Node: Empty Commands, Prev: Sequences, Up: Commands
|
|---|
| 3900 |
|
|---|
| 3901 | 5.9 Using Empty Commands
|
|---|
| 3902 | ========================
|
|---|
| 3903 |
|
|---|
| 3904 | It is sometimes useful to define commands which do nothing. This is
|
|---|
| 3905 | done simply by giving a command that consists of nothing but
|
|---|
| 3906 | whitespace. For example:
|
|---|
| 3907 |
|
|---|
| 3908 | target: ;
|
|---|
| 3909 |
|
|---|
| 3910 | defines an empty command string for `target'. You could also use a
|
|---|
| 3911 | line beginning with a tab character to define an empty command string,
|
|---|
| 3912 | but this would be confusing because such a line looks empty.
|
|---|
| 3913 |
|
|---|
| 3914 | You may be wondering why you would want to define a command string
|
|---|
| 3915 | that does nothing. The only reason this is useful is to prevent a
|
|---|
| 3916 | target from getting implicit commands (from implicit rules or the
|
|---|
| 3917 | `.DEFAULT' special target; *note Implicit Rules:: and *note Defining
|
|---|
| 3918 | Last-Resort Default Rules: Last Resort.).
|
|---|
| 3919 |
|
|---|
| 3920 | You may be inclined to define empty command strings for targets that
|
|---|
| 3921 | are not actual files, but only exist so that their prerequisites can be
|
|---|
| 3922 | remade. However, this is not the best way to do that, because the
|
|---|
| 3923 | prerequisites may not be remade properly if the target file actually
|
|---|
| 3924 | does exist. *Note Phony Targets: Phony Targets, for a better way to do
|
|---|
| 3925 | this.
|
|---|
| 3926 |
|
|---|
| 3927 |
|
|---|
| 3928 | File: make.info, Node: Using Variables, Next: Conditionals, Prev: Commands, Up: Top
|
|---|
| 3929 |
|
|---|
| 3930 | 6 How to Use Variables
|
|---|
| 3931 | **********************
|
|---|
| 3932 |
|
|---|
| 3933 | A "variable" is a name defined in a makefile to represent a string of
|
|---|
| 3934 | text, called the variable's "value". These values are substituted by
|
|---|
| 3935 | explicit request into targets, prerequisites, commands, and other parts
|
|---|
| 3936 | of the makefile. (In some other versions of `make', variables are
|
|---|
| 3937 | called "macros".)
|
|---|
| 3938 |
|
|---|
| 3939 | Variables and functions in all parts of a makefile are expanded when
|
|---|
| 3940 | read, except for the shell commands in rules, the right-hand sides of
|
|---|
| 3941 | variable definitions using `=', and the bodies of variable definitions
|
|---|
| 3942 | using the `define' directive.
|
|---|
| 3943 |
|
|---|
| 3944 | Variables can represent lists of file names, options to pass to
|
|---|
| 3945 | compilers, programs to run, directories to look in for source files,
|
|---|
| 3946 | directories to write output in, or anything else you can imagine.
|
|---|
| 3947 |
|
|---|
| 3948 | A variable name may be any sequence of characters not containing `:',
|
|---|
| 3949 | `#', `=', or leading or trailing whitespace. However, variable names
|
|---|
| 3950 | containing characters other than letters, numbers, and underscores
|
|---|
| 3951 | should be avoided, as they may be given special meanings in the future,
|
|---|
| 3952 | and with some shells they cannot be passed through the environment to a
|
|---|
| 3953 | sub-`make' (*note Communicating Variables to a Sub-`make':
|
|---|
| 3954 | Variables/Recursion.).
|
|---|
| 3955 |
|
|---|
| 3956 | Variable names are case-sensitive. The names `foo', `FOO', and
|
|---|
| 3957 | `Foo' all refer to different variables.
|
|---|
| 3958 |
|
|---|
| 3959 | It is traditional to use upper case letters in variable names, but we
|
|---|
| 3960 | recommend using lower case letters for variable names that serve
|
|---|
| 3961 | internal purposes in the makefile, and reserving upper case for
|
|---|
| 3962 | parameters that control implicit rules or for parameters that the user
|
|---|
| 3963 | should override with command options (*note Overriding Variables:
|
|---|
| 3964 | Overriding.).
|
|---|
| 3965 |
|
|---|
| 3966 | A few variables have names that are a single punctuation character or
|
|---|
| 3967 | just a few characters. These are the "automatic variables", and they
|
|---|
| 3968 | have particular specialized uses. *Note Automatic Variables::.
|
|---|
| 3969 |
|
|---|
| 3970 | * Menu:
|
|---|
| 3971 |
|
|---|
| 3972 | * Reference:: How to use the value of a variable.
|
|---|
| 3973 | * Flavors:: Variables come in two flavors.
|
|---|
| 3974 | * Advanced:: Advanced features for referencing a variable.
|
|---|
| 3975 | * Values:: All the ways variables get their values.
|
|---|
| 3976 | * Setting:: How to set a variable in the makefile.
|
|---|
| 3977 | * Appending:: How to append more text to the old value
|
|---|
| 3978 | of a variable.
|
|---|
| 3979 | * Override Directive:: How to set a variable in the makefile even if
|
|---|
| 3980 | the user has set it with a command argument.
|
|---|
| 3981 | * Defining:: An alternate way to set a variable
|
|---|
| 3982 | to a verbatim string.
|
|---|
| 3983 | * Environment:: Variable values can come from the environment.
|
|---|
| 3984 | * Target-specific:: Variable values can be defined on a per-target
|
|---|
| 3985 | basis.
|
|---|
| 3986 | * Pattern-specific:: Target-specific variable values can be applied
|
|---|
| 3987 | to a group of targets that match a pattern.
|
|---|
| 3988 |
|
|---|
| 3989 |
|
|---|
| 3990 | File: make.info, Node: Reference, Next: Flavors, Prev: Using Variables, Up: Using Variables
|
|---|
| 3991 |
|
|---|
| 3992 | 6.1 Basics of Variable References
|
|---|
| 3993 | =================================
|
|---|
| 3994 |
|
|---|
| 3995 | To substitute a variable's value, write a dollar sign followed by the
|
|---|
| 3996 | name of the variable in parentheses or braces: either `$(foo)' or
|
|---|
| 3997 | `${foo}' is a valid reference to the variable `foo'. This special
|
|---|
| 3998 | significance of `$' is why you must write `$$' to have the effect of a
|
|---|
| 3999 | single dollar sign in a file name or command.
|
|---|
| 4000 |
|
|---|
| 4001 | Variable references can be used in any context: targets,
|
|---|
| 4002 | prerequisites, commands, most directives, and new variable values.
|
|---|
| 4003 | Here is an example of a common case, where a variable holds the names
|
|---|
| 4004 | of all the object files in a program:
|
|---|
| 4005 |
|
|---|
| 4006 | objects = program.o foo.o utils.o
|
|---|
| 4007 | program : $(objects)
|
|---|
| 4008 | cc -o program $(objects)
|
|---|
| 4009 |
|
|---|
| 4010 | $(objects) : defs.h
|
|---|
| 4011 |
|
|---|
| 4012 | Variable references work by strict textual substitution. Thus, the
|
|---|
| 4013 | rule
|
|---|
| 4014 |
|
|---|
| 4015 | foo = c
|
|---|
| 4016 | prog.o : prog.$(foo)
|
|---|
| 4017 | $(foo)$(foo) -$(foo) prog.$(foo)
|
|---|
| 4018 |
|
|---|
| 4019 | could be used to compile a C program `prog.c'. Since spaces before the
|
|---|
| 4020 | variable value are ignored in variable assignments, the value of `foo'
|
|---|
| 4021 | is precisely `c'. (Don't actually write your makefiles this way!)
|
|---|
| 4022 |
|
|---|
| 4023 | A dollar sign followed by a character other than a dollar sign,
|
|---|
| 4024 | open-parenthesis or open-brace treats that single character as the
|
|---|
| 4025 | variable name. Thus, you could reference the variable `x' with `$x'.
|
|---|
| 4026 | However, this practice is strongly discouraged, except in the case of
|
|---|
| 4027 | the automatic variables (*note Automatic Variables::).
|
|---|
| 4028 |
|
|---|
| 4029 |
|
|---|
| 4030 | File: make.info, Node: Flavors, Next: Advanced, Prev: Reference, Up: Using Variables
|
|---|
| 4031 |
|
|---|
| 4032 | 6.2 The Two Flavors of Variables
|
|---|
| 4033 | ================================
|
|---|
| 4034 |
|
|---|
| 4035 | There are two ways that a variable in GNU `make' can have a value; we
|
|---|
| 4036 | call them the two "flavors" of variables. The two flavors are
|
|---|
| 4037 | distinguished in how they are defined and in what they do when expanded.
|
|---|
| 4038 |
|
|---|
| 4039 | The first flavor of variable is a "recursively expanded" variable.
|
|---|
| 4040 | Variables of this sort are defined by lines using `=' (*note Setting
|
|---|
| 4041 | Variables: Setting.) or by the `define' directive (*note Defining
|
|---|
| 4042 | Variables Verbatim: Defining.). The value you specify is installed
|
|---|
| 4043 | verbatim; if it contains references to other variables, these
|
|---|
| 4044 | references are expanded whenever this variable is substituted (in the
|
|---|
| 4045 | course of expanding some other string). When this happens, it is
|
|---|
| 4046 | called "recursive expansion".
|
|---|
| 4047 |
|
|---|
| 4048 | For example,
|
|---|
| 4049 |
|
|---|
| 4050 | foo = $(bar)
|
|---|
| 4051 | bar = $(ugh)
|
|---|
| 4052 | ugh = Huh?
|
|---|
| 4053 |
|
|---|
| 4054 | all:;echo $(foo)
|
|---|
| 4055 |
|
|---|
| 4056 | will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to
|
|---|
| 4057 | `$(ugh)' which finally expands to `Huh?'.
|
|---|
| 4058 |
|
|---|
| 4059 | This flavor of variable is the only sort supported by other versions
|
|---|
| 4060 | of `make'. It has its advantages and its disadvantages. An advantage
|
|---|
| 4061 | (most would say) is that:
|
|---|
| 4062 |
|
|---|
| 4063 | CFLAGS = $(include_dirs) -O
|
|---|
| 4064 | include_dirs = -Ifoo -Ibar
|
|---|
| 4065 |
|
|---|
| 4066 | will do what was intended: when `CFLAGS' is expanded in a command, it
|
|---|
| 4067 | will expand to `-Ifoo -Ibar -O'. A major disadvantage is that you
|
|---|
| 4068 | cannot append something on the end of a variable, as in
|
|---|
| 4069 |
|
|---|
| 4070 | CFLAGS = $(CFLAGS) -O
|
|---|
| 4071 |
|
|---|
| 4072 | because it will cause an infinite loop in the variable expansion.
|
|---|
| 4073 | (Actually `make' detects the infinite loop and reports an error.)
|
|---|
| 4074 |
|
|---|
| 4075 | Another disadvantage is that any functions (*note Functions for
|
|---|
| 4076 | Transforming Text: Functions.) referenced in the definition will be
|
|---|
| 4077 | executed every time the variable is expanded. This makes `make' run
|
|---|
| 4078 | slower; worse, it causes the `wildcard' and `shell' functions to give
|
|---|
| 4079 | unpredictable results because you cannot easily control when they are
|
|---|
| 4080 | called, or even how many times.
|
|---|
| 4081 |
|
|---|
| 4082 | To avoid all the problems and inconveniences of recursively expanded
|
|---|
| 4083 | variables, there is another flavor: simply expanded variables.
|
|---|
| 4084 |
|
|---|
| 4085 | "Simply expanded variables" are defined by lines using `:=' (*note
|
|---|
| 4086 | Setting Variables: Setting.). The value of a simply expanded variable
|
|---|
| 4087 | is scanned once and for all, expanding any references to other
|
|---|
| 4088 | variables and functions, when the variable is defined. The actual
|
|---|
| 4089 | value of the simply expanded variable is the result of expanding the
|
|---|
| 4090 | text that you write. It does not contain any references to other
|
|---|
| 4091 | variables; it contains their values _as of the time this variable was
|
|---|
| 4092 | defined_. Therefore,
|
|---|
| 4093 |
|
|---|
| 4094 | x := foo
|
|---|
| 4095 | y := $(x) bar
|
|---|
| 4096 | x := later
|
|---|
| 4097 |
|
|---|
| 4098 | is equivalent to
|
|---|
| 4099 |
|
|---|
| 4100 | y := foo bar
|
|---|
| 4101 | x := later
|
|---|
| 4102 |
|
|---|
| 4103 | When a simply expanded variable is referenced, its value is
|
|---|
| 4104 | substituted verbatim.
|
|---|
| 4105 |
|
|---|
| 4106 | Here is a somewhat more complicated example, illustrating the use of
|
|---|
| 4107 | `:=' in conjunction with the `shell' function. (*Note The `shell'
|
|---|
| 4108 | Function: Shell Function.) This example also shows use of the variable
|
|---|
| 4109 | `MAKELEVEL', which is changed when it is passed down from level to
|
|---|
| 4110 | level. (*Note Communicating Variables to a Sub-`make':
|
|---|
| 4111 | Variables/Recursion, for information about `MAKELEVEL'.)
|
|---|
| 4112 |
|
|---|
| 4113 | ifeq (0,${MAKELEVEL})
|
|---|
| 4114 | whoami := $(shell whoami)
|
|---|
| 4115 | host-type := $(shell arch)
|
|---|
| 4116 | MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
|
|---|
| 4117 | endif
|
|---|
| 4118 |
|
|---|
| 4119 | An advantage of this use of `:=' is that a typical `descend into a
|
|---|
| 4120 | directory' command then looks like this:
|
|---|
| 4121 |
|
|---|
| 4122 | ${subdirs}:
|
|---|
| 4123 | ${MAKE} -C $@ all
|
|---|
| 4124 |
|
|---|
| 4125 | Simply expanded variables generally make complicated makefile
|
|---|
| 4126 | programming more predictable because they work like variables in most
|
|---|
| 4127 | programming languages. They allow you to redefine a variable using its
|
|---|
| 4128 | own value (or its value processed in some way by one of the expansion
|
|---|
| 4129 | functions) and to use the expansion functions much more efficiently
|
|---|
| 4130 | (*note Functions for Transforming Text: Functions.).
|
|---|
| 4131 |
|
|---|
| 4132 | You can also use them to introduce controlled leading whitespace into
|
|---|
| 4133 | variable values. Leading whitespace characters are discarded from your
|
|---|
| 4134 | input before substitution of variable references and function calls;
|
|---|
| 4135 | this means you can include leading spaces in a variable value by
|
|---|
| 4136 | protecting them with variable references, like this:
|
|---|
| 4137 |
|
|---|
| 4138 | nullstring :=
|
|---|
| 4139 | space := $(nullstring) # end of the line
|
|---|
| 4140 |
|
|---|
| 4141 | Here the value of the variable `space' is precisely one space. The
|
|---|
| 4142 | comment `# end of the line' is included here just for clarity. Since
|
|---|
| 4143 | trailing space characters are _not_ stripped from variable values, just
|
|---|
| 4144 | a space at the end of the line would have the same effect (but be
|
|---|
| 4145 | rather hard to read). If you put whitespace at the end of a variable
|
|---|
| 4146 | value, it is a good idea to put a comment like that at the end of the
|
|---|
| 4147 | line to make your intent clear. Conversely, if you do _not_ want any
|
|---|
| 4148 | whitespace characters at the end of your variable value, you must
|
|---|
| 4149 | remember not to put a random comment on the end of the line after some
|
|---|
| 4150 | whitespace, such as this:
|
|---|
| 4151 |
|
|---|
| 4152 | dir := /foo/bar # directory to put the frobs in
|
|---|
| 4153 |
|
|---|
| 4154 | Here the value of the variable `dir' is `/foo/bar ' (with four
|
|---|
| 4155 | trailing spaces), which was probably not the intention. (Imagine
|
|---|
| 4156 | something like `$(dir)/file' with this definition!)
|
|---|
| 4157 |
|
|---|
| 4158 | There is another assignment operator for variables, `?='. This is
|
|---|
| 4159 | called a conditional variable assignment operator, because it only has
|
|---|
| 4160 | an effect if the variable is not yet defined. This statement:
|
|---|
| 4161 |
|
|---|
| 4162 | FOO ?= bar
|
|---|
| 4163 |
|
|---|
| 4164 | is exactly equivalent to this (*note The `origin' Function: Origin
|
|---|
| 4165 | Function.):
|
|---|
| 4166 |
|
|---|
| 4167 | ifeq ($(origin FOO), undefined)
|
|---|
| 4168 | FOO = bar
|
|---|
| 4169 | endif
|
|---|
| 4170 |
|
|---|
| 4171 | Note that a variable set to an empty value is still defined, so `?='
|
|---|
| 4172 | will not set that variable.
|
|---|
| 4173 |
|
|---|
| 4174 |
|
|---|
| 4175 | File: make.info, Node: Advanced, Next: Values, Prev: Flavors, Up: Using Variables
|
|---|
| 4176 |
|
|---|
| 4177 | 6.3 Advanced Features for Reference to Variables
|
|---|
| 4178 | ================================================
|
|---|
| 4179 |
|
|---|
| 4180 | This section describes some advanced features you can use to reference
|
|---|
| 4181 | variables in more flexible ways.
|
|---|
| 4182 |
|
|---|
| 4183 | * Menu:
|
|---|
| 4184 |
|
|---|
| 4185 | * Substitution Refs:: Referencing a variable with
|
|---|
| 4186 | substitutions on the value.
|
|---|
| 4187 | * Computed Names:: Computing the name of the variable to refer to.
|
|---|
| 4188 |
|
|---|
| 4189 |
|
|---|
| 4190 | File: make.info, Node: Substitution Refs, Next: Computed Names, Prev: Advanced, Up: Advanced
|
|---|
| 4191 |
|
|---|
| 4192 | 6.3.1 Substitution References
|
|---|
| 4193 | -----------------------------
|
|---|
| 4194 |
|
|---|
| 4195 | A "substitution reference" substitutes the value of a variable with
|
|---|
| 4196 | alterations that you specify. It has the form `$(VAR:A=B)' (or
|
|---|
| 4197 | `${VAR:A=B}') and its meaning is to take the value of the variable VAR,
|
|---|
| 4198 | replace every A at the end of a word with B in that value, and
|
|---|
| 4199 | substitute the resulting string.
|
|---|
| 4200 |
|
|---|
| 4201 | When we say "at the end of a word", we mean that A must appear
|
|---|
| 4202 | either followed by whitespace or at the end of the value in order to be
|
|---|
| 4203 | replaced; other occurrences of A in the value are unaltered. For
|
|---|
| 4204 | example:
|
|---|
| 4205 |
|
|---|
| 4206 | foo := a.o b.o c.o
|
|---|
| 4207 | bar := $(foo:.o=.c)
|
|---|
| 4208 |
|
|---|
| 4209 | sets `bar' to `a.c b.c c.c'. *Note Setting Variables: Setting.
|
|---|
| 4210 |
|
|---|
| 4211 | A substitution reference is actually an abbreviation for use of the
|
|---|
| 4212 | `patsubst' expansion function (*note Functions for String Substitution
|
|---|
| 4213 | and Analysis: Text Functions.). We provide substitution references as
|
|---|
| 4214 | well as `patsubst' for compatibility with other implementations of
|
|---|
| 4215 | `make'.
|
|---|
| 4216 |
|
|---|
| 4217 | Another type of substitution reference lets you use the full power of
|
|---|
| 4218 | the `patsubst' function. It has the same form `$(VAR:A=B)' described
|
|---|
| 4219 | above, except that now A must contain a single `%' character. This
|
|---|
| 4220 | case is equivalent to `$(patsubst A,B,$(VAR))'. *Note Functions for
|
|---|
| 4221 | String Substitution and Analysis: Text Functions, for a description of
|
|---|
| 4222 | the `patsubst' function.
|
|---|
| 4223 |
|
|---|
| 4224 | For example:
|
|---|
| 4225 |
|
|---|
| 4226 | foo := a.o b.o c.o
|
|---|
| 4227 | bar := $(foo:%.o=%.c)
|
|---|
| 4228 |
|
|---|
| 4229 | sets `bar' to `a.c b.c c.c'.
|
|---|
| 4230 |
|
|---|
| 4231 |
|
|---|
| 4232 | File: make.info, Node: Computed Names, Prev: Substitution Refs, Up: Advanced
|
|---|
| 4233 |
|
|---|
| 4234 | 6.3.2 Computed Variable Names
|
|---|
| 4235 | -----------------------------
|
|---|
| 4236 |
|
|---|
| 4237 | Computed variable names are a complicated concept needed only for
|
|---|
| 4238 | sophisticated makefile programming. For most purposes you need not
|
|---|
| 4239 | consider them, except to know that making a variable with a dollar sign
|
|---|
| 4240 | in its name might have strange results. However, if you are the type
|
|---|
| 4241 | that wants to understand everything, or you are actually interested in
|
|---|
| 4242 | what they do, read on.
|
|---|
| 4243 |
|
|---|
| 4244 | Variables may be referenced inside the name of a variable. This is
|
|---|
| 4245 | called a "computed variable name" or a "nested variable reference".
|
|---|
| 4246 | For example,
|
|---|
| 4247 |
|
|---|
| 4248 | x = y
|
|---|
| 4249 | y = z
|
|---|
| 4250 | a := $($(x))
|
|---|
| 4251 |
|
|---|
| 4252 | defines `a' as `z': the `$(x)' inside `$($(x))' expands to `y', so
|
|---|
| 4253 | `$($(x))' expands to `$(y)' which in turn expands to `z'. Here the
|
|---|
| 4254 | name of the variable to reference is not stated explicitly; it is
|
|---|
| 4255 | computed by expansion of `$(x)'. The reference `$(x)' here is nested
|
|---|
| 4256 | within the outer variable reference.
|
|---|
| 4257 |
|
|---|
| 4258 | The previous example shows two levels of nesting, but any number of
|
|---|
| 4259 | levels is possible. For example, here are three levels:
|
|---|
| 4260 |
|
|---|
| 4261 | x = y
|
|---|
| 4262 | y = z
|
|---|
| 4263 | z = u
|
|---|
| 4264 | a := $($($(x)))
|
|---|
| 4265 |
|
|---|
| 4266 | Here the innermost `$(x)' expands to `y', so `$($(x))' expands to
|
|---|
| 4267 | `$(y)' which in turn expands to `z'; now we have `$(z)', which becomes
|
|---|
| 4268 | `u'.
|
|---|
| 4269 |
|
|---|
| 4270 | References to recursively-expanded variables within a variable name
|
|---|
| 4271 | are reexpanded in the usual fashion. For example:
|
|---|
| 4272 |
|
|---|
| 4273 | x = $(y)
|
|---|
| 4274 | y = z
|
|---|
| 4275 | z = Hello
|
|---|
| 4276 | a := $($(x))
|
|---|
| 4277 |
|
|---|
| 4278 | defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes
|
|---|
| 4279 | `$(z)' which becomes `Hello'.
|
|---|
| 4280 |
|
|---|
| 4281 | Nested variable references can also contain modified references and
|
|---|
| 4282 | function invocations (*note Functions for Transforming Text:
|
|---|
| 4283 | Functions.), just like any other reference. For example, using the
|
|---|
| 4284 | `subst' function (*note Functions for String Substitution and Analysis:
|
|---|
| 4285 | Text Functions.):
|
|---|
| 4286 |
|
|---|
| 4287 | x = variable1
|
|---|
| 4288 | variable2 := Hello
|
|---|
| 4289 | y = $(subst 1,2,$(x))
|
|---|
| 4290 | z = y
|
|---|
| 4291 | a := $($($(z)))
|
|---|
| 4292 |
|
|---|
| 4293 | eventually defines `a' as `Hello'. It is doubtful that anyone would
|
|---|
| 4294 | ever want to write a nested reference as convoluted as this one, but it
|
|---|
| 4295 | works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst
|
|---|
| 4296 | 1,2,$(x)))'. This gets the value `variable1' from `x' and changes it
|
|---|
| 4297 | by substitution to `variable2', so that the entire string becomes
|
|---|
| 4298 | `$(variable2)', a simple variable reference whose value is `Hello'.
|
|---|
| 4299 |
|
|---|
| 4300 | A computed variable name need not consist entirely of a single
|
|---|
| 4301 | variable reference. It can contain several variable references, as
|
|---|
| 4302 | well as some invariant text. For example,
|
|---|
| 4303 |
|
|---|
| 4304 | a_dirs := dira dirb
|
|---|
| 4305 | 1_dirs := dir1 dir2
|
|---|
| 4306 |
|
|---|
| 4307 | a_files := filea fileb
|
|---|
| 4308 | 1_files := file1 file2
|
|---|
| 4309 |
|
|---|
| 4310 | ifeq "$(use_a)" "yes"
|
|---|
| 4311 | a1 := a
|
|---|
| 4312 | else
|
|---|
| 4313 | a1 := 1
|
|---|
| 4314 | endif
|
|---|
| 4315 |
|
|---|
| 4316 | ifeq "$(use_dirs)" "yes"
|
|---|
| 4317 | df := dirs
|
|---|
| 4318 | else
|
|---|
| 4319 | df := files
|
|---|
| 4320 | endif
|
|---|
| 4321 |
|
|---|
| 4322 | dirs := $($(a1)_$(df))
|
|---|
| 4323 |
|
|---|
| 4324 | will give `dirs' the same value as `a_dirs', `1_dirs', `a_files' or
|
|---|
| 4325 | `1_files' depending on the settings of `use_a' and `use_dirs'.
|
|---|
| 4326 |
|
|---|
| 4327 | Computed variable names can also be used in substitution references:
|
|---|
| 4328 |
|
|---|
| 4329 | a_objects := a.o b.o c.o
|
|---|
| 4330 | 1_objects := 1.o 2.o 3.o
|
|---|
| 4331 |
|
|---|
| 4332 | sources := $($(a1)_objects:.o=.c)
|
|---|
| 4333 |
|
|---|
| 4334 | defines `sources' as either `a.c b.c c.c' or `1.c 2.c 3.c', depending
|
|---|
| 4335 | on the value of `a1'.
|
|---|
| 4336 |
|
|---|
| 4337 | The only restriction on this sort of use of nested variable
|
|---|
| 4338 | references is that they cannot specify part of the name of a function
|
|---|
| 4339 | to be called. This is because the test for a recognized function name
|
|---|
| 4340 | is done before the expansion of nested references. For example,
|
|---|
| 4341 |
|
|---|
| 4342 | ifdef do_sort
|
|---|
| 4343 | func := sort
|
|---|
| 4344 | else
|
|---|
| 4345 | func := strip
|
|---|
| 4346 | endif
|
|---|
| 4347 |
|
|---|
| 4348 | bar := a d b g q c
|
|---|
| 4349 |
|
|---|
| 4350 | foo := $($(func) $(bar))
|
|---|
| 4351 |
|
|---|
| 4352 | attempts to give `foo' the value of the variable `sort a d b g q c' or
|
|---|
| 4353 | `strip a d b g q c', rather than giving `a d b g q c' as the argument
|
|---|
| 4354 | to either the `sort' or the `strip' function. This restriction could
|
|---|
| 4355 | be removed in the future if that change is shown to be a good idea.
|
|---|
| 4356 |
|
|---|
| 4357 | You can also use computed variable names in the left-hand side of a
|
|---|
| 4358 | variable assignment, or in a `define' directive, as in:
|
|---|
| 4359 |
|
|---|
| 4360 | dir = foo
|
|---|
| 4361 | $(dir)_sources := $(wildcard $(dir)/*.c)
|
|---|
| 4362 | define $(dir)_print
|
|---|
| 4363 | lpr $($(dir)_sources)
|
|---|
| 4364 | endef
|
|---|
| 4365 |
|
|---|
| 4366 | This example defines the variables `dir', `foo_sources', and
|
|---|
| 4367 | `foo_print'.
|
|---|
| 4368 |
|
|---|
| 4369 | Note that "nested variable references" are quite different from
|
|---|
| 4370 | "recursively expanded variables" (*note The Two Flavors of Variables:
|
|---|
| 4371 | Flavors.), though both are used together in complex ways when doing
|
|---|
| 4372 | makefile programming.
|
|---|
| 4373 |
|
|---|
| 4374 |
|
|---|
| 4375 | File: make.info, Node: Values, Next: Setting, Prev: Advanced, Up: Using Variables
|
|---|
| 4376 |
|
|---|
| 4377 | 6.4 How Variables Get Their Values
|
|---|
| 4378 | ==================================
|
|---|
| 4379 |
|
|---|
| 4380 | Variables can get values in several different ways:
|
|---|
| 4381 |
|
|---|
| 4382 | * You can specify an overriding value when you run `make'. *Note
|
|---|
| 4383 | Overriding Variables: Overriding.
|
|---|
| 4384 |
|
|---|
| 4385 | * You can specify a value in the makefile, either with an assignment
|
|---|
| 4386 | (*note Setting Variables: Setting.) or with a verbatim definition
|
|---|
| 4387 | (*note Defining Variables Verbatim: Defining.).
|
|---|
| 4388 |
|
|---|
| 4389 | * Variables in the environment become `make' variables. *Note
|
|---|
| 4390 | Variables from the Environment: Environment.
|
|---|
| 4391 |
|
|---|
| 4392 | * Several "automatic" variables are given new values for each rule.
|
|---|
| 4393 | Each of these has a single conventional use. *Note Automatic
|
|---|
| 4394 | Variables::.
|
|---|
| 4395 |
|
|---|
| 4396 | * Several variables have constant initial values. *Note Variables
|
|---|
| 4397 | Used by Implicit Rules: Implicit Variables.
|
|---|
| 4398 |
|
|---|
| 4399 |
|
|---|
| 4400 | File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Variables
|
|---|
| 4401 |
|
|---|
| 4402 | 6.5 Setting Variables
|
|---|
| 4403 | =====================
|
|---|
| 4404 |
|
|---|
| 4405 | To set a variable from the makefile, write a line starting with the
|
|---|
| 4406 | variable name followed by `=' or `:='. Whatever follows the `=' or
|
|---|
| 4407 | `:=' on the line becomes the value. For example,
|
|---|
| 4408 |
|
|---|
| 4409 | objects = main.o foo.o bar.o utils.o
|
|---|
| 4410 |
|
|---|
| 4411 | defines a variable named `objects'. Whitespace around the variable
|
|---|
| 4412 | name and immediately after the `=' is ignored.
|
|---|
| 4413 |
|
|---|
| 4414 | Variables defined with `=' are "recursively expanded" variables.
|
|---|
| 4415 | Variables defined with `:=' are "simply expanded" variables; these
|
|---|
| 4416 | definitions can contain variable references which will be expanded
|
|---|
| 4417 | before the definition is made. *Note The Two Flavors of Variables:
|
|---|
| 4418 | Flavors.
|
|---|
| 4419 |
|
|---|
| 4420 | The variable name may contain function and variable references, which
|
|---|
| 4421 | are expanded when the line is read to find the actual variable name to
|
|---|
| 4422 | use.
|
|---|
| 4423 |
|
|---|
| 4424 | There is no limit on the length of the value of a variable except the
|
|---|
| 4425 | amount of swapping space on the computer. When a variable definition is
|
|---|
| 4426 | long, it is a good idea to break it into several lines by inserting
|
|---|
| 4427 | backslash-newline at convenient places in the definition. This will not
|
|---|
| 4428 | affect the functioning of `make', but it will make the makefile easier
|
|---|
| 4429 | to read.
|
|---|
| 4430 |
|
|---|
| 4431 | Most variable names are considered to have the empty string as a
|
|---|
| 4432 | value if you have never set them. Several variables have built-in
|
|---|
| 4433 | initial values that are not empty, but you can set them in the usual
|
|---|
| 4434 | ways (*note Variables Used by Implicit Rules: Implicit Variables.).
|
|---|
| 4435 | Several special variables are set automatically to a new value for each
|
|---|
| 4436 | rule; these are called the "automatic" variables (*note Automatic
|
|---|
| 4437 | Variables::).
|
|---|
| 4438 |
|
|---|
| 4439 | If you'd like a variable to be set to a value only if it's not
|
|---|
| 4440 | already set, then you can use the shorthand operator `?=' instead of
|
|---|
| 4441 | `='. These two settings of the variable `FOO' are identical (*note The
|
|---|
| 4442 | `origin' Function: Origin Function.):
|
|---|
| 4443 |
|
|---|
| 4444 | FOO ?= bar
|
|---|
| 4445 |
|
|---|
| 4446 | and
|
|---|
| 4447 |
|
|---|
| 4448 | ifeq ($(origin FOO), undefined)
|
|---|
| 4449 | FOO = bar
|
|---|
| 4450 | endif
|
|---|
| 4451 |
|
|---|
| 4452 |
|
|---|
| 4453 | File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables
|
|---|
| 4454 |
|
|---|
| 4455 | 6.6 Appending More Text to Variables
|
|---|
| 4456 | ====================================
|
|---|
| 4457 |
|
|---|
| 4458 | Often it is useful to add more text to the value of a variable already
|
|---|
| 4459 | defined. You do this with a line containing `+=', like this:
|
|---|
| 4460 |
|
|---|
| 4461 | objects += another.o
|
|---|
| 4462 |
|
|---|
| 4463 | This takes the value of the variable `objects', and adds the text
|
|---|
| 4464 | `another.o' to it (preceded by a single space). Thus:
|
|---|
| 4465 |
|
|---|
| 4466 | objects = main.o foo.o bar.o utils.o
|
|---|
| 4467 | objects += another.o
|
|---|
| 4468 |
|
|---|
| 4469 | sets `objects' to `main.o foo.o bar.o utils.o another.o'.
|
|---|
| 4470 |
|
|---|
| 4471 | Using `+=' is similar to:
|
|---|
| 4472 |
|
|---|
| 4473 | objects = main.o foo.o bar.o utils.o
|
|---|
| 4474 | objects := $(objects) another.o
|
|---|
| 4475 |
|
|---|
| 4476 | but differs in ways that become important when you use more complex
|
|---|
| 4477 | values.
|
|---|
| 4478 |
|
|---|
| 4479 | When the variable in question has not been defined before, `+=' acts
|
|---|
| 4480 | just like normal `=': it defines a recursively-expanded variable.
|
|---|
| 4481 | However, when there _is_ a previous definition, exactly what `+=' does
|
|---|
| 4482 | depends on what flavor of variable you defined originally. *Note The
|
|---|
| 4483 | Two Flavors of Variables: Flavors, for an explanation of the two
|
|---|
| 4484 | flavors of variables.
|
|---|
| 4485 |
|
|---|
| 4486 | When you add to a variable's value with `+=', `make' acts
|
|---|
| 4487 | essentially as if you had included the extra text in the initial
|
|---|
| 4488 | definition of the variable. If you defined it first with `:=', making
|
|---|
| 4489 | it a simply-expanded variable, `+=' adds to that simply-expanded
|
|---|
| 4490 | definition, and expands the new text before appending it to the old
|
|---|
| 4491 | value just as `:=' does (see *Note Setting Variables: Setting, for a
|
|---|
| 4492 | full explanation of `:='). In fact,
|
|---|
| 4493 |
|
|---|
| 4494 | variable := value
|
|---|
| 4495 | variable += more
|
|---|
| 4496 |
|
|---|
| 4497 | is exactly equivalent to:
|
|---|
| 4498 |
|
|---|
| 4499 |
|
|---|
| 4500 | variable := value
|
|---|
| 4501 | variable := $(variable) more
|
|---|
| 4502 |
|
|---|
| 4503 | On the other hand, when you use `+=' with a variable that you defined
|
|---|
| 4504 | first to be recursively-expanded using plain `=', `make' does something
|
|---|
| 4505 | a bit different. Recall that when you define a recursively-expanded
|
|---|
| 4506 | variable, `make' does not expand the value you set for variable and
|
|---|
| 4507 | function references immediately. Instead it stores the text verbatim,
|
|---|
| 4508 | and saves these variable and function references to be expanded later,
|
|---|
| 4509 | when you refer to the new variable (*note The Two Flavors of Variables:
|
|---|
| 4510 | Flavors.). When you use `+=' on a recursively-expanded variable, it is
|
|---|
| 4511 | this unexpanded text to which `make' appends the new text you specify.
|
|---|
| 4512 |
|
|---|
| 4513 | variable = value
|
|---|
| 4514 | variable += more
|
|---|
| 4515 |
|
|---|
| 4516 | is roughly equivalent to:
|
|---|
| 4517 |
|
|---|
| 4518 | temp = value
|
|---|
| 4519 | variable = $(temp) more
|
|---|
| 4520 |
|
|---|
| 4521 | except that of course it never defines a variable called `temp'. The
|
|---|
| 4522 | importance of this comes when the variable's old value contains
|
|---|
| 4523 | variable references. Take this common example:
|
|---|
| 4524 |
|
|---|
| 4525 | CFLAGS = $(includes) -O
|
|---|
| 4526 | ...
|
|---|
| 4527 | CFLAGS += -pg # enable profiling
|
|---|
| 4528 |
|
|---|
| 4529 | The first line defines the `CFLAGS' variable with a reference to another
|
|---|
| 4530 | variable, `includes'. (`CFLAGS' is used by the rules for C
|
|---|
| 4531 | compilation; *note Catalogue of Implicit Rules: Catalogue of Rules.)
|
|---|
| 4532 | Using `=' for the definition makes `CFLAGS' a recursively-expanded
|
|---|
| 4533 | variable, meaning `$(includes) -O' is _not_ expanded when `make'
|
|---|
| 4534 | processes the definition of `CFLAGS'. Thus, `includes' need not be
|
|---|
| 4535 | defined yet for its value to take effect. It only has to be defined
|
|---|
| 4536 | before any reference to `CFLAGS'. If we tried to append to the value
|
|---|
| 4537 | of `CFLAGS' without using `+=', we might do it like this:
|
|---|
| 4538 |
|
|---|
| 4539 | CFLAGS := $(CFLAGS) -pg # enable profiling
|
|---|
| 4540 |
|
|---|
| 4541 | This is pretty close, but not quite what we want. Using `:=' redefines
|
|---|
| 4542 | `CFLAGS' as a simply-expanded variable; this means `make' expands the
|
|---|
| 4543 | text `$(CFLAGS) -pg' before setting the variable. If `includes' is not
|
|---|
| 4544 | yet defined, we get ` -O -pg', and a later definition of `includes'
|
|---|
| 4545 | will have no effect. Conversely, by using `+=' we set `CFLAGS' to the
|
|---|
| 4546 | _unexpanded_ value `$(includes) -O -pg'. Thus we preserve the
|
|---|
| 4547 | reference to `includes', so if that variable gets defined at any later
|
|---|
| 4548 | point, a reference like `$(CFLAGS)' still uses its value.
|
|---|
| 4549 |
|
|---|
| 4550 |
|
|---|
| 4551 | File: make.info, Node: Override Directive, Next: Defining, Prev: Appending, Up: Using Variables
|
|---|
| 4552 |
|
|---|
| 4553 | 6.7 The `override' Directive
|
|---|
| 4554 | ============================
|
|---|
| 4555 |
|
|---|
| 4556 | If a variable has been set with a command argument (*note Overriding
|
|---|
| 4557 | Variables: Overriding.), then ordinary assignments in the makefile are
|
|---|
| 4558 | ignored. If you want to set the variable in the makefile even though
|
|---|
| 4559 | it was set with a command argument, you can use an `override'
|
|---|
| 4560 | directive, which is a line that looks like this:
|
|---|
| 4561 |
|
|---|
| 4562 | override VARIABLE = VALUE
|
|---|
| 4563 |
|
|---|
| 4564 | or
|
|---|
| 4565 |
|
|---|
| 4566 | override VARIABLE := VALUE
|
|---|
| 4567 |
|
|---|
| 4568 | To append more text to a variable defined on the command line, use:
|
|---|
| 4569 |
|
|---|
| 4570 | override VARIABLE += MORE TEXT
|
|---|
| 4571 |
|
|---|
| 4572 | *Note Appending More Text to Variables: Appending.
|
|---|
| 4573 |
|
|---|
| 4574 | The `override' directive was not invented for escalation in the war
|
|---|
| 4575 | between makefiles and command arguments. It was invented so you can
|
|---|
| 4576 | alter and add to values that the user specifies with command arguments.
|
|---|
| 4577 |
|
|---|
| 4578 | For example, suppose you always want the `-g' switch when you run the
|
|---|
| 4579 | C compiler, but you would like to allow the user to specify the other
|
|---|
| 4580 | switches with a command argument just as usual. You could use this
|
|---|
| 4581 | `override' directive:
|
|---|
| 4582 |
|
|---|
| 4583 | override CFLAGS += -g
|
|---|
| 4584 |
|
|---|
| 4585 | You can also use `override' directives with `define' directives.
|
|---|
| 4586 | This is done as you might expect:
|
|---|
| 4587 |
|
|---|
| 4588 | override define foo
|
|---|
| 4589 | bar
|
|---|
| 4590 | endef
|
|---|
| 4591 |
|
|---|
| 4592 | *Note Defining Variables Verbatim: Defining.
|
|---|
| 4593 |
|
|---|
| 4594 |
|
|---|
| 4595 | File: make.info, Node: Defining, Next: Environment, Prev: Override Directive, Up: Using Variables
|
|---|
| 4596 |
|
|---|
| 4597 | 6.8 Defining Variables Verbatim
|
|---|
| 4598 | ===============================
|
|---|
| 4599 |
|
|---|
| 4600 | Another way to set the value of a variable is to use the `define'
|
|---|
| 4601 | directive. This directive has an unusual syntax which allows newline
|
|---|
| 4602 | characters to be included in the value, which is convenient for defining
|
|---|
| 4603 | both canned sequences of commands (*note Defining Canned Command
|
|---|
| 4604 | Sequences: Sequences.), and also sections of makefile syntax to use
|
|---|
| 4605 | with `eval' (*note Eval Function::).
|
|---|
| 4606 |
|
|---|
| 4607 | The `define' directive is followed on the same line by the name of
|
|---|
| 4608 | the variable and nothing more. The value to give the variable appears
|
|---|
| 4609 | on the following lines. The end of the value is marked by a line
|
|---|
| 4610 | containing just the word `endef'. Aside from this difference in
|
|---|
| 4611 | syntax, `define' works just like `=': it creates a recursively-expanded
|
|---|
| 4612 | variable (*note The Two Flavors of Variables: Flavors.). The variable
|
|---|
| 4613 | name may contain function and variable references, which are expanded
|
|---|
| 4614 | when the directive is read to find the actual variable name to use.
|
|---|
| 4615 |
|
|---|
| 4616 | You may nest `define' directives: `make' will keep track of nested
|
|---|
| 4617 | directives and report an error if they are not all properly closed with
|
|---|
| 4618 | `endef'. Note that lines beginning with tab characters are considered
|
|---|
| 4619 | part of a command script, so any `define' or `endef' strings appearing
|
|---|
| 4620 | on such a line will not be considered `make' operators.
|
|---|
| 4621 |
|
|---|
| 4622 | define two-lines
|
|---|
| 4623 | echo foo
|
|---|
| 4624 | echo $(bar)
|
|---|
| 4625 | endef
|
|---|
| 4626 |
|
|---|
| 4627 | The value in an ordinary assignment cannot contain a newline; but the
|
|---|
| 4628 | newlines that separate the lines of the value in a `define' become part
|
|---|
| 4629 | of the variable's value (except for the final newline which precedes
|
|---|
| 4630 | the `endef' and is not considered part of the value).
|
|---|
| 4631 |
|
|---|
| 4632 | When used in a command script, the previous example is functionally
|
|---|
| 4633 | equivalent to this:
|
|---|
| 4634 |
|
|---|
| 4635 | two-lines = echo foo; echo $(bar)
|
|---|
| 4636 |
|
|---|
| 4637 | since two commands separated by semicolon behave much like two separate
|
|---|
| 4638 | shell commands. However, note that using two separate lines means
|
|---|
| 4639 | `make' will invoke the shell twice, running an independent subshell for
|
|---|
| 4640 | each line. *Note Command Execution: Execution.
|
|---|
| 4641 |
|
|---|
| 4642 | If you want variable definitions made with `define' to take
|
|---|
| 4643 | precedence over command-line variable definitions, you can use the
|
|---|
| 4644 | `override' directive together with `define':
|
|---|
| 4645 |
|
|---|
| 4646 | override define two-lines
|
|---|
| 4647 | foo
|
|---|
| 4648 | $(bar)
|
|---|
| 4649 | endef
|
|---|
| 4650 |
|
|---|
| 4651 | *Note The `override' Directive: Override Directive.
|
|---|
| 4652 |
|
|---|
| 4653 |
|
|---|
| 4654 | File: make.info, Node: Environment, Next: Target-specific, Prev: Defining, Up: Using Variables
|
|---|
| 4655 |
|
|---|
| 4656 | 6.9 Variables from the Environment
|
|---|
| 4657 | ==================================
|
|---|
| 4658 |
|
|---|
| 4659 | Variables in `make' can come from the environment in which `make' is
|
|---|
| 4660 | run. Every environment variable that `make' sees when it starts up is
|
|---|
| 4661 | transformed into a `make' variable with the same name and value.
|
|---|
| 4662 | However, an explicit assignment in the makefile, or with a command
|
|---|
| 4663 | argument, overrides the environment. (If the `-e' flag is specified,
|
|---|
| 4664 | then values from the environment override assignments in the makefile.
|
|---|
| 4665 | *Note Summary of Options: Options Summary. But this is not recommended
|
|---|
| 4666 | practice.)
|
|---|
| 4667 |
|
|---|
| 4668 | Thus, by setting the variable `CFLAGS' in your environment, you can
|
|---|
| 4669 | cause all C compilations in most makefiles to use the compiler switches
|
|---|
| 4670 | you prefer. This is safe for variables with standard or conventional
|
|---|
| 4671 | meanings because you know that no makefile will use them for other
|
|---|
| 4672 | things. (Note this is not totally reliable; some makefiles set
|
|---|
| 4673 | `CFLAGS' explicitly and therefore are not affected by the value in the
|
|---|
| 4674 | environment.)
|
|---|
| 4675 |
|
|---|
| 4676 | When `make' runs a command script, variables defined in the makefile
|
|---|
| 4677 | are placed into the environment of that command. This allows you to
|
|---|
| 4678 | pass values to sub-`make' invocations (*note Recursive Use of `make':
|
|---|
| 4679 | Recursion.). By default, only variables that came from the environment
|
|---|
| 4680 | or the command line are passed to recursive invocations. You can use
|
|---|
| 4681 | the `export' directive to pass other variables. *Note Communicating
|
|---|
| 4682 | Variables to a Sub-`make': Variables/Recursion, for full details.
|
|---|
| 4683 |
|
|---|
| 4684 | Other use of variables from the environment is not recommended. It
|
|---|
| 4685 | is not wise for makefiles to depend for their functioning on
|
|---|
| 4686 | environment variables set up outside their control, since this would
|
|---|
| 4687 | cause different users to get different results from the same makefile.
|
|---|
| 4688 | This is against the whole purpose of most makefiles.
|
|---|
| 4689 |
|
|---|
| 4690 | Such problems would be especially likely with the variable `SHELL',
|
|---|
| 4691 | which is normally present in the environment to specify the user's
|
|---|
| 4692 | choice of interactive shell. It would be very undesirable for this
|
|---|
| 4693 | choice to affect `make'; so, `make' handles the `SHELL' environment
|
|---|
| 4694 | variable in a special way; see *Note Choosing the Shell::.
|
|---|
| 4695 |
|
|---|
| 4696 |
|
|---|
| 4697 | File: make.info, Node: Target-specific, Next: Pattern-specific, Prev: Environment, Up: Using Variables
|
|---|
| 4698 |
|
|---|
| 4699 | 6.10 Target-specific Variable Values
|
|---|
| 4700 | ====================================
|
|---|
| 4701 |
|
|---|
| 4702 | Variable values in `make' are usually global; that is, they are the
|
|---|
| 4703 | same regardless of where they are evaluated (unless they're reset, of
|
|---|
| 4704 | course). One exception to that is automatic variables (*note Automatic
|
|---|
| 4705 | Variables::).
|
|---|
| 4706 |
|
|---|
| 4707 | The other exception is "target-specific variable values". This
|
|---|
| 4708 | feature allows you to define different values for the same variable,
|
|---|
| 4709 | based on the target that `make' is currently building. As with
|
|---|
| 4710 | automatic variables, these values are only available within the context
|
|---|
| 4711 | of a target's command script (and in other target-specific assignments).
|
|---|
| 4712 |
|
|---|
| 4713 | Set a target-specific variable value like this:
|
|---|
| 4714 |
|
|---|
| 4715 | TARGET ... : VARIABLE-ASSIGNMENT
|
|---|
| 4716 |
|
|---|
| 4717 | or like this:
|
|---|
| 4718 |
|
|---|
| 4719 | TARGET ... : override VARIABLE-ASSIGNMENT
|
|---|
| 4720 |
|
|---|
| 4721 | or like this:
|
|---|
| 4722 |
|
|---|
| 4723 | TARGET ... : export VARIABLE-ASSIGNMENT
|
|---|
| 4724 |
|
|---|
| 4725 | Multiple TARGET values create a target-specific variable value for
|
|---|
| 4726 | each member of the target list individually.
|
|---|
| 4727 |
|
|---|
| 4728 | The VARIABLE-ASSIGNMENT can be any valid form of assignment;
|
|---|
| 4729 | recursive (`='), static (`:='), appending (`+='), or conditional
|
|---|
| 4730 | (`?='). All variables that appear within the VARIABLE-ASSIGNMENT are
|
|---|
| 4731 | evaluated within the context of the target: thus, any
|
|---|
| 4732 | previously-defined target-specific variable values will be in effect.
|
|---|
| 4733 | Note that this variable is actually distinct from any "global" value:
|
|---|
| 4734 | the two variables do not have to have the same flavor (recursive vs.
|
|---|
| 4735 | static).
|
|---|
| 4736 |
|
|---|
| 4737 | Target-specific variables have the same priority as any other
|
|---|
| 4738 | makefile variable. Variables provided on the command-line (and in the
|
|---|
| 4739 | environment if the `-e' option is in force) will take precedence.
|
|---|
| 4740 | Specifying the `override' directive will allow the target-specific
|
|---|
| 4741 | variable value to be preferred.
|
|---|
| 4742 |
|
|---|
| 4743 | There is one more special feature of target-specific variables: when
|
|---|
| 4744 | you define a target-specific variable that variable value is also in
|
|---|
| 4745 | effect for all prerequisites of this target, and all their
|
|---|
| 4746 | prerequisites, etc. (unless those prerequisites override that variable
|
|---|
| 4747 | with their own target-specific variable value). So, for example, a
|
|---|
| 4748 | statement like this:
|
|---|
| 4749 |
|
|---|
| 4750 | prog : CFLAGS = -g
|
|---|
| 4751 | prog : prog.o foo.o bar.o
|
|---|
| 4752 |
|
|---|
| 4753 | will set `CFLAGS' to `-g' in the command script for `prog', but it will
|
|---|
| 4754 | also set `CFLAGS' to `-g' in the command scripts that create `prog.o',
|
|---|
| 4755 | `foo.o', and `bar.o', and any command scripts which create their
|
|---|
| 4756 | prerequisites.
|
|---|
| 4757 |
|
|---|
| 4758 | Be aware that a given prerequisite will only be built once per
|
|---|
| 4759 | invocation of make, at most. If the same file is a prerequisite of
|
|---|
| 4760 | multiple targets, and each of those targets has a different value for
|
|---|
| 4761 | the same target-specific variable, then the first target to be built
|
|---|
| 4762 | will cause that prerequisite to be built and the prerequisite will
|
|---|
| 4763 | inherit the target-specific value from the first target. It will
|
|---|
| 4764 | ignore the target-specific values from any other targets.
|
|---|
| 4765 |
|
|---|
| 4766 |
|
|---|
| 4767 | File: make.info, Node: Pattern-specific, Prev: Target-specific, Up: Using Variables
|
|---|
| 4768 |
|
|---|
| 4769 | 6.11 Pattern-specific Variable Values
|
|---|
| 4770 | =====================================
|
|---|
| 4771 |
|
|---|
| 4772 | In addition to target-specific variable values (*note Target-specific
|
|---|
| 4773 | Variable Values: Target-specific.), GNU `make' supports
|
|---|
| 4774 | pattern-specific variable values. In this form, the variable is
|
|---|
| 4775 | defined for any target that matches the pattern specified. If a target
|
|---|
| 4776 | matches more than one pattern, all the matching pattern-specific
|
|---|
| 4777 | variables are interpreted in the order in which they were defined in
|
|---|
| 4778 | the makefile, and collected together into one set. Variables defined
|
|---|
| 4779 | in this way are searched after any target-specific variables defined
|
|---|
| 4780 | explicitly for that target, and before target-specific variables
|
|---|
| 4781 | defined for the parent target.
|
|---|
| 4782 |
|
|---|
| 4783 | Set a pattern-specific variable value like this:
|
|---|
| 4784 |
|
|---|
| 4785 | PATTERN ... : VARIABLE-ASSIGNMENT
|
|---|
| 4786 |
|
|---|
| 4787 | or like this:
|
|---|
| 4788 |
|
|---|
| 4789 | PATTERN ... : override VARIABLE-ASSIGNMENT
|
|---|
| 4790 |
|
|---|
| 4791 | where PATTERN is a %-pattern. As with target-specific variable values,
|
|---|
| 4792 | multiple PATTERN values create a pattern-specific variable value for
|
|---|
| 4793 | each pattern individually. The VARIABLE-ASSIGNMENT can be any valid
|
|---|
| 4794 | form of assignment. Any command-line variable setting will take
|
|---|
| 4795 | precedence, unless `override' is specified.
|
|---|
| 4796 |
|
|---|
| 4797 | For example:
|
|---|
| 4798 |
|
|---|
| 4799 | %.o : CFLAGS = -O
|
|---|
| 4800 |
|
|---|
| 4801 | will assign `CFLAGS' the value of `-O' for all targets matching the
|
|---|
| 4802 | pattern `%.o'.
|
|---|
| 4803 |
|
|---|
| 4804 |
|
|---|
| 4805 | File: make.info, Node: Conditionals, Next: Functions, Prev: Using Variables, Up: Top
|
|---|
| 4806 |
|
|---|
| 4807 | 7 Conditional Parts of Makefiles
|
|---|
| 4808 | ********************************
|
|---|
| 4809 |
|
|---|
| 4810 | A "conditional" causes part of a makefile to be obeyed or ignored
|
|---|
| 4811 | depending on the values of variables. Conditionals can compare the
|
|---|
| 4812 | value of one variable to another, or the value of a variable to a
|
|---|
| 4813 | constant string. Conditionals control what `make' actually "sees" in
|
|---|
| 4814 | the makefile, so they _cannot_ be used to control shell commands at the
|
|---|
| 4815 | time of execution.
|
|---|
| 4816 |
|
|---|
| 4817 | * Menu:
|
|---|
| 4818 |
|
|---|
| 4819 | * Conditional Example:: Example of a conditional
|
|---|
| 4820 | * Conditional Syntax:: The syntax of conditionals.
|
|---|
| 4821 | * Testing Flags:: Conditionals that test flags.
|
|---|
| 4822 |
|
|---|
| 4823 |
|
|---|
| 4824 | File: make.info, Node: Conditional Example, Next: Conditional Syntax, Prev: Conditionals, Up: Conditionals
|
|---|
| 4825 |
|
|---|
| 4826 | 7.1 Example of a Conditional
|
|---|
| 4827 | ============================
|
|---|
| 4828 |
|
|---|
| 4829 | The following example of a conditional tells `make' to use one set of
|
|---|
| 4830 | libraries if the `CC' variable is `gcc', and a different set of
|
|---|
| 4831 | libraries otherwise. It works by controlling which of two command
|
|---|
| 4832 | lines will be used as the command for a rule. The result is that
|
|---|
| 4833 | `CC=gcc' as an argument to `make' changes not only which compiler is
|
|---|
| 4834 | used but also which libraries are linked.
|
|---|
| 4835 |
|
|---|
| 4836 | libs_for_gcc = -lgnu
|
|---|
| 4837 | normal_libs =
|
|---|
| 4838 |
|
|---|
| 4839 | foo: $(objects)
|
|---|
| 4840 | ifeq ($(CC),gcc)
|
|---|
| 4841 | $(CC) -o foo $(objects) $(libs_for_gcc)
|
|---|
| 4842 | else
|
|---|
| 4843 | $(CC) -o foo $(objects) $(normal_libs)
|
|---|
| 4844 | endif
|
|---|
| 4845 |
|
|---|
| 4846 | This conditional uses three directives: one `ifeq', one `else' and
|
|---|
| 4847 | one `endif'.
|
|---|
| 4848 |
|
|---|
| 4849 | The `ifeq' directive begins the conditional, and specifies the
|
|---|
| 4850 | condition. It contains two arguments, separated by a comma and
|
|---|
| 4851 | surrounded by parentheses. Variable substitution is performed on both
|
|---|
| 4852 | arguments and then they are compared. The lines of the makefile
|
|---|
| 4853 | following the `ifeq' are obeyed if the two arguments match; otherwise
|
|---|
| 4854 | they are ignored.
|
|---|
| 4855 |
|
|---|
| 4856 | The `else' directive causes the following lines to be obeyed if the
|
|---|
| 4857 | previous conditional failed. In the example above, this means that the
|
|---|
| 4858 | second alternative linking command is used whenever the first
|
|---|
| 4859 | alternative is not used. It is optional to have an `else' in a
|
|---|
| 4860 | conditional.
|
|---|
| 4861 |
|
|---|
| 4862 | The `endif' directive ends the conditional. Every conditional must
|
|---|
| 4863 | end with an `endif'. Unconditional makefile text follows.
|
|---|
| 4864 |
|
|---|
| 4865 | As this example illustrates, conditionals work at the textual level:
|
|---|
| 4866 | the lines of the conditional are treated as part of the makefile, or
|
|---|
| 4867 | ignored, according to the condition. This is why the larger syntactic
|
|---|
| 4868 | units of the makefile, such as rules, may cross the beginning or the
|
|---|
| 4869 | end of the conditional.
|
|---|
| 4870 |
|
|---|
| 4871 | When the variable `CC' has the value `gcc', the above example has
|
|---|
| 4872 | this effect:
|
|---|
| 4873 |
|
|---|
| 4874 | foo: $(objects)
|
|---|
| 4875 | $(CC) -o foo $(objects) $(libs_for_gcc)
|
|---|
| 4876 |
|
|---|
| 4877 | When the variable `CC' has any other value, the effect is this:
|
|---|
| 4878 |
|
|---|
| 4879 | foo: $(objects)
|
|---|
| 4880 | $(CC) -o foo $(objects) $(normal_libs)
|
|---|
| 4881 |
|
|---|
| 4882 | Equivalent results can be obtained in another way by
|
|---|
| 4883 | conditionalizing a variable assignment and then using the variable
|
|---|
| 4884 | unconditionally:
|
|---|
| 4885 |
|
|---|
| 4886 | libs_for_gcc = -lgnu
|
|---|
| 4887 | normal_libs =
|
|---|
| 4888 |
|
|---|
| 4889 | ifeq ($(CC),gcc)
|
|---|
| 4890 | libs=$(libs_for_gcc)
|
|---|
| 4891 | else
|
|---|
| 4892 | libs=$(normal_libs)
|
|---|
| 4893 | endif
|
|---|
| 4894 |
|
|---|
| 4895 | foo: $(objects)
|
|---|
| 4896 | $(CC) -o foo $(objects) $(libs)
|
|---|
| 4897 |
|
|---|
| 4898 |
|
|---|
| 4899 | File: make.info, Node: Conditional Syntax, Next: Testing Flags, Prev: Conditional Example, Up: Conditionals
|
|---|
| 4900 |
|
|---|
| 4901 | 7.2 Syntax of Conditionals
|
|---|
| 4902 | ==========================
|
|---|
| 4903 |
|
|---|
| 4904 | The syntax of a simple conditional with no `else' is as follows:
|
|---|
| 4905 |
|
|---|
| 4906 | CONDITIONAL-DIRECTIVE
|
|---|
| 4907 | TEXT-IF-TRUE
|
|---|
| 4908 | endif
|
|---|
| 4909 |
|
|---|
| 4910 | The TEXT-IF-TRUE may be any lines of text, to be considered as part of
|
|---|
| 4911 | the makefile if the condition is true. If the condition is false, no
|
|---|
| 4912 | text is used instead.
|
|---|
| 4913 |
|
|---|
| 4914 | The syntax of a complex conditional is as follows:
|
|---|
| 4915 |
|
|---|
| 4916 | CONDITIONAL-DIRECTIVE
|
|---|
| 4917 | TEXT-IF-TRUE
|
|---|
| 4918 | else
|
|---|
| 4919 | TEXT-IF-FALSE
|
|---|
| 4920 | endif
|
|---|
| 4921 |
|
|---|
| 4922 | or:
|
|---|
| 4923 |
|
|---|
| 4924 | CONDITIONAL-DIRECTIVE
|
|---|
| 4925 | TEXT-IF-ONE-IS-TRUE
|
|---|
| 4926 | else CONDITIONAL-DIRECTIVE
|
|---|
| 4927 | TEXT-IF-TRUE
|
|---|
| 4928 | else
|
|---|
| 4929 | TEXT-IF-FALSE
|
|---|
| 4930 | endif
|
|---|
| 4931 |
|
|---|
| 4932 | There can be as many "`else' CONDITIONAL-DIRECTIVE" clauses as
|
|---|
| 4933 | necessary. Once a given condition is true, TEXT-IF-TRUE is used and no
|
|---|
| 4934 | other clause is used; if no condition is true then TEXT-IF-FALSE is
|
|---|
| 4935 | used. The TEXT-IF-TRUE and TEXT-IF-FALSE can be any number of lines of
|
|---|
| 4936 | text.
|
|---|
| 4937 |
|
|---|
| 4938 | The syntax of the CONDITIONAL-DIRECTIVE is the same whether the
|
|---|
| 4939 | conditional is simple or complex; after an `else' or not. There are
|
|---|
| 4940 | four different directives that test different conditions. Here is a
|
|---|
| 4941 | table of them:
|
|---|
| 4942 |
|
|---|
| 4943 | `ifeq (ARG1, ARG2)'
|
|---|
| 4944 | `ifeq 'ARG1' 'ARG2''
|
|---|
| 4945 | `ifeq "ARG1" "ARG2"'
|
|---|
| 4946 | `ifeq "ARG1" 'ARG2''
|
|---|
| 4947 | `ifeq 'ARG1' "ARG2"'
|
|---|
| 4948 | Expand all variable references in ARG1 and ARG2 and compare them.
|
|---|
| 4949 | If they are identical, the TEXT-IF-TRUE is effective; otherwise,
|
|---|
| 4950 | the TEXT-IF-FALSE, if any, is effective.
|
|---|
| 4951 |
|
|---|
| 4952 | Often you want to test if a variable has a non-empty value. When
|
|---|
| 4953 | the value results from complex expansions of variables and
|
|---|
| 4954 | functions, expansions you would consider empty may actually
|
|---|
| 4955 | contain whitespace characters and thus are not seen as empty.
|
|---|
| 4956 | However, you can use the `strip' function (*note Text Functions::)
|
|---|
| 4957 | to avoid interpreting whitespace as a non-empty value. For
|
|---|
| 4958 | example:
|
|---|
| 4959 |
|
|---|
| 4960 | ifeq ($(strip $(foo)),)
|
|---|
| 4961 | TEXT-IF-EMPTY
|
|---|
| 4962 | endif
|
|---|
| 4963 |
|
|---|
| 4964 | will evaluate TEXT-IF-EMPTY even if the expansion of `$(foo)'
|
|---|
| 4965 | contains whitespace characters.
|
|---|
| 4966 |
|
|---|
| 4967 | `ifneq (ARG1, ARG2)'
|
|---|
| 4968 | `ifneq 'ARG1' 'ARG2''
|
|---|
| 4969 | `ifneq "ARG1" "ARG2"'
|
|---|
| 4970 | `ifneq "ARG1" 'ARG2''
|
|---|
| 4971 | `ifneq 'ARG1' "ARG2"'
|
|---|
| 4972 | Expand all variable references in ARG1 and ARG2 and compare them.
|
|---|
| 4973 | If they are different, the TEXT-IF-TRUE is effective; otherwise,
|
|---|
| 4974 | the TEXT-IF-FALSE, if any, is effective.
|
|---|
| 4975 |
|
|---|
| 4976 | `ifdef VARIABLE-NAME'
|
|---|
| 4977 | The `ifdef' form takes the _name_ of a variable as its argument,
|
|---|
| 4978 | not a reference to a variable. The value of that variable has a
|
|---|
| 4979 | non-empty value, the TEXT-IF-TRUE is effective; otherwise, the
|
|---|
| 4980 | TEXT-IF-FALSE, if any, is effective. Variables that have never
|
|---|
| 4981 | been defined have an empty value. The text VARIABLE-NAME is
|
|---|
| 4982 | expanded, so it could be a variable or function that expands to
|
|---|
| 4983 | the name of a variable. For example:
|
|---|
| 4984 |
|
|---|
| 4985 | bar = true
|
|---|
| 4986 | foo = bar
|
|---|
| 4987 | ifdef $(foo)
|
|---|
| 4988 | frobozz = yes
|
|---|
| 4989 | endif
|
|---|
| 4990 |
|
|---|
| 4991 | The variable reference `$(foo)' is expanded, yielding `bar', which
|
|---|
| 4992 | is considered to be the name of a variable. The variable `bar' is
|
|---|
| 4993 | not expanded, but its value is examined to determine if it is
|
|---|
| 4994 | non-empty.
|
|---|
| 4995 |
|
|---|
| 4996 | Note that `ifdef' only tests whether a variable has a value. It
|
|---|
| 4997 | does not expand the variable to see if that value is nonempty.
|
|---|
| 4998 | Consequently, tests using `ifdef' return true for all definitions
|
|---|
| 4999 | except those like `foo ='. To test for an empty value, use
|
|---|
| 5000 | `ifeq ($(foo),)'. For example,
|
|---|
| 5001 |
|
|---|
| 5002 | bar =
|
|---|
| 5003 | foo = $(bar)
|
|---|
| 5004 | ifdef foo
|
|---|
| 5005 | frobozz = yes
|
|---|
| 5006 | else
|
|---|
| 5007 | frobozz = no
|
|---|
| 5008 | endif
|
|---|
| 5009 |
|
|---|
| 5010 | sets `frobozz' to `yes', while:
|
|---|
| 5011 |
|
|---|
| 5012 | foo =
|
|---|
| 5013 | ifdef foo
|
|---|
| 5014 | frobozz = yes
|
|---|
| 5015 | else
|
|---|
| 5016 | frobozz = no
|
|---|
| 5017 | endif
|
|---|
| 5018 |
|
|---|
| 5019 | sets `frobozz' to `no'.
|
|---|
| 5020 |
|
|---|
| 5021 | `ifndef VARIABLE-NAME'
|
|---|
| 5022 | If the variable VARIABLE-NAME has an empty value, the TEXT-IF-TRUE
|
|---|
| 5023 | is effective; otherwise, the TEXT-IF-FALSE, if any, is effective.
|
|---|
| 5024 | The rules for expansion and testing of VARIABLE-NAME are identical
|
|---|
| 5025 | to the `ifdef' directive.
|
|---|
| 5026 |
|
|---|
| 5027 | Extra spaces are allowed and ignored at the beginning of the
|
|---|
| 5028 | conditional directive line, but a tab is not allowed. (If the line
|
|---|
| 5029 | begins with a tab, it will be considered a command for a rule.) Aside
|
|---|
| 5030 | from this, extra spaces or tabs may be inserted with no effect anywhere
|
|---|
| 5031 | except within the directive name or within an argument. A comment
|
|---|
| 5032 | starting with `#' may appear at the end of the line.
|
|---|
| 5033 |
|
|---|
| 5034 | The other two directives that play a part in a conditional are `else'
|
|---|
| 5035 | and `endif'. Each of these directives is written as one word, with no
|
|---|
| 5036 | arguments. Extra spaces are allowed and ignored at the beginning of the
|
|---|
| 5037 | line, and spaces or tabs at the end. A comment starting with `#' may
|
|---|
| 5038 | appear at the end of the line.
|
|---|
| 5039 |
|
|---|
| 5040 | Conditionals affect which lines of the makefile `make' uses. If the
|
|---|
| 5041 | condition is true, `make' reads the lines of the TEXT-IF-TRUE as part
|
|---|
| 5042 | of the makefile; if the condition is false, `make' ignores those lines
|
|---|
| 5043 | completely. It follows that syntactic units of the makefile, such as
|
|---|
| 5044 | rules, may safely be split across the beginning or the end of the
|
|---|
| 5045 | conditional.
|
|---|
| 5046 |
|
|---|
| 5047 | `make' evaluates conditionals when it reads a makefile.
|
|---|
| 5048 | Consequently, you cannot use automatic variables in the tests of
|
|---|
| 5049 | conditionals because they are not defined until commands are run (*note
|
|---|
| 5050 | Automatic Variables::).
|
|---|
| 5051 |
|
|---|
| 5052 | To prevent intolerable confusion, it is not permitted to start a
|
|---|
| 5053 | conditional in one makefile and end it in another. However, you may
|
|---|
| 5054 | write an `include' directive within a conditional, provided you do not
|
|---|
| 5055 | attempt to terminate the conditional inside the included file.
|
|---|
| 5056 |
|
|---|
| 5057 |
|
|---|
| 5058 | File: make.info, Node: Testing Flags, Prev: Conditional Syntax, Up: Conditionals
|
|---|
| 5059 |
|
|---|
| 5060 | 7.3 Conditionals that Test Flags
|
|---|
| 5061 | ================================
|
|---|
| 5062 |
|
|---|
| 5063 | You can write a conditional that tests `make' command flags such as
|
|---|
| 5064 | `-t' by using the variable `MAKEFLAGS' together with the `findstring'
|
|---|
| 5065 | function (*note Functions for String Substitution and Analysis: Text
|
|---|
| 5066 | Functions.). This is useful when `touch' is not enough to make a file
|
|---|
| 5067 | appear up to date.
|
|---|
| 5068 |
|
|---|
| 5069 | The `findstring' function determines whether one string appears as a
|
|---|
| 5070 | substring of another. If you want to test for the `-t' flag, use `t'
|
|---|
| 5071 | as the first string and the value of `MAKEFLAGS' as the other.
|
|---|
| 5072 |
|
|---|
| 5073 | For example, here is how to arrange to use `ranlib -t' to finish
|
|---|
| 5074 | marking an archive file up to date:
|
|---|
| 5075 |
|
|---|
| 5076 | archive.a: ...
|
|---|
| 5077 | ifneq (,$(findstring t,$(MAKEFLAGS)))
|
|---|
| 5078 | +touch archive.a
|
|---|
| 5079 | +ranlib -t archive.a
|
|---|
| 5080 | else
|
|---|
| 5081 | ranlib archive.a
|
|---|
| 5082 | endif
|
|---|
| 5083 |
|
|---|
| 5084 | The `+' prefix marks those command lines as "recursive" so that they
|
|---|
| 5085 | will be executed despite use of the `-t' flag. *Note Recursive Use of
|
|---|
| 5086 | `make': Recursion.
|
|---|
| 5087 |
|
|---|
| 5088 |
|
|---|
| 5089 | File: make.info, Node: Functions, Next: Running, Prev: Conditionals, Up: Top
|
|---|
| 5090 |
|
|---|
| 5091 | 8 Functions for Transforming Text
|
|---|
| 5092 | *********************************
|
|---|
| 5093 |
|
|---|
| 5094 | "Functions" allow you to do text processing in the makefile to compute
|
|---|
| 5095 | the files to operate on or the commands to use. You use a function in a
|
|---|
| 5096 | "function call", where you give the name of the function and some text
|
|---|
| 5097 | (the "arguments") for the function to operate on. The result of the
|
|---|
| 5098 | function's processing is substituted into the makefile at the point of
|
|---|
| 5099 | the call, just as a variable might be substituted.
|
|---|
| 5100 |
|
|---|
| 5101 | * Menu:
|
|---|
| 5102 |
|
|---|
| 5103 | * Syntax of Functions:: How to write a function call.
|
|---|
| 5104 | * Text Functions:: General-purpose text manipulation functions.
|
|---|
| 5105 | * File Name Functions:: Functions for manipulating file names.
|
|---|
| 5106 | * Conditional Functions:: Functions that implement conditions.
|
|---|
| 5107 | * Foreach Function:: Repeat some text with controlled variation.
|
|---|
| 5108 | * Call Function:: Expand a user-defined function.
|
|---|
| 5109 | * Value Function:: Return the un-expanded value of a variable.
|
|---|
| 5110 | * Eval Function:: Evaluate the arguments as makefile syntax.
|
|---|
| 5111 | * Origin Function:: Find where a variable got its value.
|
|---|
| 5112 | * Flavor Function:: Find out the flavor of a variable.
|
|---|
| 5113 | * Shell Function:: Substitute the output of a shell command.
|
|---|
| 5114 | * Make Control Functions:: Functions that control how make runs.
|
|---|
| 5115 |
|
|---|
| 5116 |
|
|---|
| 5117 | File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Functions, Up: Functions
|
|---|
| 5118 |
|
|---|
| 5119 | 8.1 Function Call Syntax
|
|---|
| 5120 | ========================
|
|---|
| 5121 |
|
|---|
| 5122 | A function call resembles a variable reference. It looks like this:
|
|---|
| 5123 |
|
|---|
| 5124 | $(FUNCTION ARGUMENTS)
|
|---|
| 5125 |
|
|---|
| 5126 | or like this:
|
|---|
| 5127 |
|
|---|
| 5128 | ${FUNCTION ARGUMENTS}
|
|---|
| 5129 |
|
|---|
| 5130 | Here FUNCTION is a function name; one of a short list of names that
|
|---|
| 5131 | are part of `make'. You can also essentially create your own functions
|
|---|
| 5132 | by using the `call' builtin function.
|
|---|
| 5133 |
|
|---|
| 5134 | The ARGUMENTS are the arguments of the function. They are separated
|
|---|
| 5135 | from the function name by one or more spaces or tabs, and if there is
|
|---|
| 5136 | more than one argument, then they are separated by commas. Such
|
|---|
| 5137 | whitespace and commas are not part of an argument's value. The
|
|---|
| 5138 | delimiters which you use to surround the function call, whether
|
|---|
| 5139 | parentheses or braces, can appear in an argument only in matching pairs;
|
|---|
| 5140 | the other kind of delimiters may appear singly. If the arguments
|
|---|
| 5141 | themselves contain other function calls or variable references, it is
|
|---|
| 5142 | wisest to use the same kind of delimiters for all the references; write
|
|---|
| 5143 | `$(subst a,b,$(x))', not `$(subst a,b,${x})'. This is because it is
|
|---|
| 5144 | clearer, and because only one type of delimiter is matched to find the
|
|---|
| 5145 | end of the reference.
|
|---|
| 5146 |
|
|---|
| 5147 | The text written for each argument is processed by substitution of
|
|---|
| 5148 | variables and function calls to produce the argument value, which is
|
|---|
| 5149 | the text on which the function acts. The substitution is done in the
|
|---|
| 5150 | order in which the arguments appear.
|
|---|
| 5151 |
|
|---|
| 5152 | Commas and unmatched parentheses or braces cannot appear in the text
|
|---|
| 5153 | of an argument as written; leading spaces cannot appear in the text of
|
|---|
| 5154 | the first argument as written. These characters can be put into the
|
|---|
| 5155 | argument value by variable substitution. First define variables
|
|---|
| 5156 | `comma' and `space' whose values are isolated comma and space
|
|---|
| 5157 | characters, then substitute these variables where such characters are
|
|---|
| 5158 | wanted, like this:
|
|---|
| 5159 |
|
|---|
| 5160 | comma:= ,
|
|---|
| 5161 | empty:=
|
|---|
| 5162 | space:= $(empty) $(empty)
|
|---|
| 5163 | foo:= a b c
|
|---|
| 5164 | bar:= $(subst $(space),$(comma),$(foo))
|
|---|
| 5165 | # bar is now `a,b,c'.
|
|---|
| 5166 |
|
|---|
| 5167 | Here the `subst' function replaces each space with a comma, through the
|
|---|
| 5168 | value of `foo', and substitutes the result.
|
|---|
| 5169 |
|
|---|
| 5170 |
|
|---|
| 5171 | File: make.info, Node: Text Functions, Next: File Name Functions, Prev: Syntax of Functions, Up: Functions
|
|---|
| 5172 |
|
|---|
| 5173 | 8.2 Functions for String Substitution and Analysis
|
|---|
| 5174 | ==================================================
|
|---|
| 5175 |
|
|---|
| 5176 | Here are some functions that operate on strings:
|
|---|
| 5177 |
|
|---|
| 5178 | `$(subst FROM,TO,TEXT)'
|
|---|
| 5179 | Performs a textual replacement on the text TEXT: each occurrence
|
|---|
| 5180 | of FROM is replaced by TO. The result is substituted for the
|
|---|
| 5181 | function call. For example,
|
|---|
| 5182 |
|
|---|
| 5183 | $(subst ee,EE,feet on the street)
|
|---|
| 5184 |
|
|---|
| 5185 | substitutes the string `fEEt on the strEEt'.
|
|---|
| 5186 |
|
|---|
| 5187 | `$(patsubst PATTERN,REPLACEMENT,TEXT)'
|
|---|
| 5188 | Finds whitespace-separated words in TEXT that match PATTERN and
|
|---|
| 5189 | replaces them with REPLACEMENT. Here PATTERN may contain a `%'
|
|---|
| 5190 | which acts as a wildcard, matching any number of any characters
|
|---|
| 5191 | within a word. If REPLACEMENT also contains a `%', the `%' is
|
|---|
| 5192 | replaced by the text that matched the `%' in PATTERN. Only the
|
|---|
| 5193 | first `%' in the PATTERN and REPLACEMENT is treated this way; any
|
|---|
| 5194 | subsequent `%' is unchanged.
|
|---|
| 5195 |
|
|---|
| 5196 | `%' characters in `patsubst' function invocations can be quoted
|
|---|
| 5197 | with preceding backslashes (`\'). Backslashes that would
|
|---|
| 5198 | otherwise quote `%' characters can be quoted with more backslashes.
|
|---|
| 5199 | Backslashes that quote `%' characters or other backslashes are
|
|---|
| 5200 | removed from the pattern before it is compared file names or has a
|
|---|
| 5201 | stem substituted into it. Backslashes that are not in danger of
|
|---|
| 5202 | quoting `%' characters go unmolested. For example, the pattern
|
|---|
| 5203 | `the\%weird\\%pattern\\' has `the%weird\' preceding the operative
|
|---|
| 5204 | `%' character, and `pattern\\' following it. The final two
|
|---|
| 5205 | backslashes are left alone because they cannot affect any `%'
|
|---|
| 5206 | character.
|
|---|
| 5207 |
|
|---|
| 5208 | Whitespace between words is folded into single space characters;
|
|---|
| 5209 | leading and trailing whitespace is discarded.
|
|---|
| 5210 |
|
|---|
| 5211 | For example,
|
|---|
| 5212 |
|
|---|
| 5213 | $(patsubst %.c,%.o,x.c.c bar.c)
|
|---|
| 5214 |
|
|---|
| 5215 | produces the value `x.c.o bar.o'.
|
|---|
| 5216 |
|
|---|
| 5217 | Substitution references (*note Substitution References:
|
|---|
| 5218 | Substitution Refs.) are a simpler way to get the effect of the
|
|---|
| 5219 | `patsubst' function:
|
|---|
| 5220 |
|
|---|
| 5221 | $(VAR:PATTERN=REPLACEMENT)
|
|---|
| 5222 |
|
|---|
| 5223 | is equivalent to
|
|---|
| 5224 |
|
|---|
| 5225 | $(patsubst PATTERN,REPLACEMENT,$(VAR))
|
|---|
| 5226 |
|
|---|
| 5227 | The second shorthand simplifies one of the most common uses of
|
|---|
| 5228 | `patsubst': replacing the suffix at the end of file names.
|
|---|
| 5229 |
|
|---|
| 5230 | $(VAR:SUFFIX=REPLACEMENT)
|
|---|
| 5231 |
|
|---|
| 5232 | is equivalent to
|
|---|
| 5233 |
|
|---|
| 5234 | $(patsubst %SUFFIX,%REPLACEMENT,$(VAR))
|
|---|
| 5235 |
|
|---|
| 5236 | For example, you might have a list of object files:
|
|---|
| 5237 |
|
|---|
| 5238 | objects = foo.o bar.o baz.o
|
|---|
| 5239 |
|
|---|
| 5240 | To get the list of corresponding source files, you could simply
|
|---|
| 5241 | write:
|
|---|
| 5242 |
|
|---|
| 5243 | $(objects:.o=.c)
|
|---|
| 5244 |
|
|---|
| 5245 | instead of using the general form:
|
|---|
| 5246 |
|
|---|
| 5247 | $(patsubst %.o,%.c,$(objects))
|
|---|
| 5248 |
|
|---|
| 5249 | `$(strip STRING)'
|
|---|
| 5250 | Removes leading and trailing whitespace from STRING and replaces
|
|---|
| 5251 | each internal sequence of one or more whitespace characters with a
|
|---|
| 5252 | single space. Thus, `$(strip a b c )' results in `a b c'.
|
|---|
| 5253 |
|
|---|
| 5254 | The function `strip' can be very useful when used in conjunction
|
|---|
| 5255 | with conditionals. When comparing something with the empty string
|
|---|
| 5256 | `' using `ifeq' or `ifneq', you usually want a string of just
|
|---|
| 5257 | whitespace to match the empty string (*note Conditionals::).
|
|---|
| 5258 |
|
|---|
| 5259 | Thus, the following may fail to have the desired results:
|
|---|
| 5260 |
|
|---|
| 5261 | .PHONY: all
|
|---|
| 5262 | ifneq "$(needs_made)" ""
|
|---|
| 5263 | all: $(needs_made)
|
|---|
| 5264 | else
|
|---|
| 5265 | all:;@echo 'Nothing to make!'
|
|---|
| 5266 | endif
|
|---|
| 5267 |
|
|---|
| 5268 | Replacing the variable reference `$(needs_made)' with the function
|
|---|
| 5269 | call `$(strip $(needs_made))' in the `ifneq' directive would make
|
|---|
| 5270 | it more robust.
|
|---|
| 5271 |
|
|---|
| 5272 | `$(findstring FIND,IN)'
|
|---|
| 5273 | Searches IN for an occurrence of FIND. If it occurs, the value is
|
|---|
| 5274 | FIND; otherwise, the value is empty. You can use this function in
|
|---|
| 5275 | a conditional to test for the presence of a specific substring in
|
|---|
| 5276 | a given string. Thus, the two examples,
|
|---|
| 5277 |
|
|---|
| 5278 | $(findstring a,a b c)
|
|---|
| 5279 | $(findstring a,b c)
|
|---|
| 5280 |
|
|---|
| 5281 | produce the values `a' and `' (the empty string), respectively.
|
|---|
| 5282 | *Note Testing Flags::, for a practical application of `findstring'.
|
|---|
| 5283 |
|
|---|
| 5284 | `$(filter PATTERN...,TEXT)'
|
|---|
| 5285 | Returns all whitespace-separated words in TEXT that _do_ match any
|
|---|
| 5286 | of the PATTERN words, removing any words that _do not_ match. The
|
|---|
| 5287 | patterns are written using `%', just like the patterns used in the
|
|---|
| 5288 | `patsubst' function above.
|
|---|
| 5289 |
|
|---|
| 5290 | The `filter' function can be used to separate out different types
|
|---|
| 5291 | of strings (such as file names) in a variable. For example:
|
|---|
| 5292 |
|
|---|
| 5293 | sources := foo.c bar.c baz.s ugh.h
|
|---|
| 5294 | foo: $(sources)
|
|---|
| 5295 | cc $(filter %.c %.s,$(sources)) -o foo
|
|---|
| 5296 |
|
|---|
| 5297 | says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h'
|
|---|
| 5298 | but only `foo.c', `bar.c' and `baz.s' should be specified in the
|
|---|
| 5299 | command to the compiler.
|
|---|
| 5300 |
|
|---|
| 5301 | `$(filter-out PATTERN...,TEXT)'
|
|---|
| 5302 | Returns all whitespace-separated words in TEXT that _do not_ match
|
|---|
| 5303 | any of the PATTERN words, removing the words that _do_ match one
|
|---|
| 5304 | or more. This is the exact opposite of the `filter' function.
|
|---|
| 5305 |
|
|---|
| 5306 | For example, given:
|
|---|
| 5307 |
|
|---|
| 5308 | objects=main1.o foo.o main2.o bar.o
|
|---|
| 5309 | mains=main1.o main2.o
|
|---|
| 5310 |
|
|---|
| 5311 | the following generates a list which contains all the object files
|
|---|
| 5312 | not in `mains':
|
|---|
| 5313 |
|
|---|
| 5314 | $(filter-out $(mains),$(objects))
|
|---|
| 5315 |
|
|---|
| 5316 | `$(sort LIST)'
|
|---|
| 5317 | Sorts the words of LIST in lexical order, removing duplicate
|
|---|
| 5318 | words. The output is a list of words separated by single spaces.
|
|---|
| 5319 | Thus,
|
|---|
| 5320 |
|
|---|
| 5321 | $(sort foo bar lose)
|
|---|
| 5322 |
|
|---|
| 5323 | returns the value `bar foo lose'.
|
|---|
| 5324 |
|
|---|
| 5325 | Incidentally, since `sort' removes duplicate words, you can use it
|
|---|
| 5326 | for this purpose even if you don't care about the sort order.
|
|---|
| 5327 |
|
|---|
| 5328 | `$(word N,TEXT)'
|
|---|
| 5329 | Returns the Nth word of TEXT. The legitimate values of N start
|
|---|
| 5330 | from 1. If N is bigger than the number of words in TEXT, the
|
|---|
| 5331 | value is empty. For example,
|
|---|
| 5332 |
|
|---|
| 5333 | $(word 2, foo bar baz)
|
|---|
| 5334 |
|
|---|
| 5335 | returns `bar'.
|
|---|
| 5336 |
|
|---|
| 5337 | `$(wordlist S,E,TEXT)'
|
|---|
| 5338 | Returns the list of words in TEXT starting with word S and ending
|
|---|
| 5339 | with word E (inclusive). The legitimate values of S start from 1;
|
|---|
| 5340 | E may start from 0. If S is bigger than the number of words in
|
|---|
| 5341 | TEXT, the value is empty. If E is bigger than the number of words
|
|---|
| 5342 | in TEXT, words up to the end of TEXT are returned. If S is
|
|---|
| 5343 | greater than E, nothing is returned. For example,
|
|---|
| 5344 |
|
|---|
| 5345 | $(wordlist 2, 3, foo bar baz)
|
|---|
| 5346 |
|
|---|
| 5347 | returns `bar baz'.
|
|---|
| 5348 |
|
|---|
| 5349 | `$(words TEXT)'
|
|---|
| 5350 | Returns the number of words in TEXT. Thus, the last word of TEXT
|
|---|
| 5351 | is `$(word $(words TEXT),TEXT)'.
|
|---|
| 5352 |
|
|---|
| 5353 | `$(firstword NAMES...)'
|
|---|
| 5354 | The argument NAMES is regarded as a series of names, separated by
|
|---|
| 5355 | whitespace. The value is the first name in the series. The rest
|
|---|
| 5356 | of the names are ignored.
|
|---|
| 5357 |
|
|---|
| 5358 | For example,
|
|---|
| 5359 |
|
|---|
| 5360 | $(firstword foo bar)
|
|---|
| 5361 |
|
|---|
| 5362 | produces the result `foo'. Although `$(firstword TEXT)' is the
|
|---|
| 5363 | same as `$(word 1,TEXT)', the `firstword' function is retained for
|
|---|
| 5364 | its simplicity.
|
|---|
| 5365 |
|
|---|
| 5366 | `$(lastword NAMES...)'
|
|---|
| 5367 | The argument NAMES is regarded as a series of names, separated by
|
|---|
| 5368 | whitespace. The value is the last name in the series.
|
|---|
| 5369 |
|
|---|
| 5370 | For example,
|
|---|
| 5371 |
|
|---|
| 5372 | $(lastword foo bar)
|
|---|
| 5373 |
|
|---|
| 5374 | produces the result `bar'. Although `$(lastword TEXT)' is the
|
|---|
| 5375 | same as `$(word $(words TEXT),TEXT)', the `lastword' function was
|
|---|
| 5376 | added for its simplicity and better performance.
|
|---|
| 5377 |
|
|---|
| 5378 | Here is a realistic example of the use of `subst' and `patsubst'.
|
|---|
| 5379 | Suppose that a makefile uses the `VPATH' variable to specify a list of
|
|---|
| 5380 | directories that `make' should search for prerequisite files (*note
|
|---|
| 5381 | `VPATH' Search Path for All Prerequisites: General Search.). This
|
|---|
| 5382 | example shows how to tell the C compiler to search for header files in
|
|---|
| 5383 | the same list of directories.
|
|---|
| 5384 |
|
|---|
| 5385 | The value of `VPATH' is a list of directories separated by colons,
|
|---|
| 5386 | such as `src:../headers'. First, the `subst' function is used to
|
|---|
| 5387 | change the colons to spaces:
|
|---|
| 5388 |
|
|---|
| 5389 | $(subst :, ,$(VPATH))
|
|---|
| 5390 |
|
|---|
| 5391 | This produces `src ../headers'. Then `patsubst' is used to turn each
|
|---|
| 5392 | directory name into a `-I' flag. These can be added to the value of
|
|---|
| 5393 | the variable `CFLAGS', which is passed automatically to the C compiler,
|
|---|
| 5394 | like this:
|
|---|
| 5395 |
|
|---|
| 5396 | override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
|
|---|
| 5397 |
|
|---|
| 5398 | The effect is to append the text `-Isrc -I../headers' to the previously
|
|---|
| 5399 | given value of `CFLAGS'. The `override' directive is used so that the
|
|---|
| 5400 | new value is assigned even if the previous value of `CFLAGS' was
|
|---|
| 5401 | specified with a command argument (*note The `override' Directive:
|
|---|
| 5402 | Override Directive.).
|
|---|
| 5403 |
|
|---|
| 5404 |
|
|---|
| 5405 | File: make.info, Node: File Name Functions, Next: Conditional Functions, Prev: Text Functions, Up: Functions
|
|---|
| 5406 |
|
|---|
| 5407 | 8.3 Functions for File Names
|
|---|
| 5408 | ============================
|
|---|
| 5409 |
|
|---|
| 5410 | Several of the built-in expansion functions relate specifically to
|
|---|
| 5411 | taking apart file names or lists of file names.
|
|---|
| 5412 |
|
|---|
| 5413 | Each of the following functions performs a specific transformation
|
|---|
| 5414 | on a file name. The argument of the function is regarded as a series
|
|---|
| 5415 | of file names, separated by whitespace. (Leading and trailing
|
|---|
| 5416 | whitespace is ignored.) Each file name in the series is transformed in
|
|---|
| 5417 | the same way and the results are concatenated with single spaces
|
|---|
| 5418 | between them.
|
|---|
| 5419 |
|
|---|
| 5420 | `$(dir NAMES...)'
|
|---|
| 5421 | Extracts the directory-part of each file name in NAMES. The
|
|---|
| 5422 | directory-part of the file name is everything up through (and
|
|---|
| 5423 | including) the last slash in it. If the file name contains no
|
|---|
| 5424 | slash, the directory part is the string `./'. For example,
|
|---|
| 5425 |
|
|---|
| 5426 | $(dir src/foo.c hacks)
|
|---|
| 5427 |
|
|---|
| 5428 | produces the result `src/ ./'.
|
|---|
| 5429 |
|
|---|
| 5430 | `$(notdir NAMES...)'
|
|---|
| 5431 | Extracts all but the directory-part of each file name in NAMES.
|
|---|
| 5432 | If the file name contains no slash, it is left unchanged.
|
|---|
| 5433 | Otherwise, everything through the last slash is removed from it.
|
|---|
| 5434 |
|
|---|
| 5435 | A file name that ends with a slash becomes an empty string. This
|
|---|
| 5436 | is unfortunate, because it means that the result does not always
|
|---|
| 5437 | have the same number of whitespace-separated file names as the
|
|---|
| 5438 | argument had; but we do not see any other valid alternative.
|
|---|
| 5439 |
|
|---|
| 5440 | For example,
|
|---|
| 5441 |
|
|---|
| 5442 | $(notdir src/foo.c hacks)
|
|---|
| 5443 |
|
|---|
| 5444 | produces the result `foo.c hacks'.
|
|---|
| 5445 |
|
|---|
| 5446 | `$(suffix NAMES...)'
|
|---|
| 5447 | Extracts the suffix of each file name in NAMES. If the file name
|
|---|
| 5448 | contains a period, the suffix is everything starting with the last
|
|---|
| 5449 | period. Otherwise, the suffix is the empty string. This
|
|---|
| 5450 | frequently means that the result will be empty when NAMES is not,
|
|---|
| 5451 | and if NAMES contains multiple file names, the result may contain
|
|---|
| 5452 | fewer file names.
|
|---|
| 5453 |
|
|---|
| 5454 | For example,
|
|---|
| 5455 |
|
|---|
| 5456 | $(suffix src/foo.c src-1.0/bar.c hacks)
|
|---|
| 5457 |
|
|---|
| 5458 | produces the result `.c .c'.
|
|---|
| 5459 |
|
|---|
| 5460 | `$(basename NAMES...)'
|
|---|
| 5461 | Extracts all but the suffix of each file name in NAMES. If the
|
|---|
| 5462 | file name contains a period, the basename is everything starting
|
|---|
| 5463 | up to (and not including) the last period. Periods in the
|
|---|
| 5464 | directory part are ignored. If there is no period, the basename
|
|---|
| 5465 | is the entire file name. For example,
|
|---|
| 5466 |
|
|---|
| 5467 | $(basename src/foo.c src-1.0/bar hacks)
|
|---|
| 5468 |
|
|---|
| 5469 | produces the result `src/foo src-1.0/bar hacks'.
|
|---|
| 5470 |
|
|---|
| 5471 | `$(addsuffix SUFFIX,NAMES...)'
|
|---|
| 5472 | The argument NAMES is regarded as a series of names, separated by
|
|---|
| 5473 | whitespace; SUFFIX is used as a unit. The value of SUFFIX is
|
|---|
| 5474 | appended to the end of each individual name and the resulting
|
|---|
| 5475 | larger names are concatenated with single spaces between them.
|
|---|
| 5476 | For example,
|
|---|
| 5477 |
|
|---|
| 5478 | $(addsuffix .c,foo bar)
|
|---|
| 5479 |
|
|---|
| 5480 | produces the result `foo.c bar.c'.
|
|---|
| 5481 |
|
|---|
| 5482 | `$(addprefix PREFIX,NAMES...)'
|
|---|
| 5483 | The argument NAMES is regarded as a series of names, separated by
|
|---|
| 5484 | whitespace; PREFIX is used as a unit. The value of PREFIX is
|
|---|
| 5485 | prepended to the front of each individual name and the resulting
|
|---|
| 5486 | larger names are concatenated with single spaces between them.
|
|---|
| 5487 | For example,
|
|---|
| 5488 |
|
|---|
| 5489 | $(addprefix src/,foo bar)
|
|---|
| 5490 |
|
|---|
| 5491 | produces the result `src/foo src/bar'.
|
|---|
| 5492 |
|
|---|
| 5493 | `$(join LIST1,LIST2)'
|
|---|
| 5494 | Concatenates the two arguments word by word: the two first words
|
|---|
| 5495 | (one from each argument) concatenated form the first word of the
|
|---|
| 5496 | result, the two second words form the second word of the result,
|
|---|
| 5497 | and so on. So the Nth word of the result comes from the Nth word
|
|---|
| 5498 | of each argument. If one argument has more words that the other,
|
|---|
| 5499 | the extra words are copied unchanged into the result.
|
|---|
| 5500 |
|
|---|
| 5501 | For example, `$(join a b,.c .o)' produces `a.c b.o'.
|
|---|
| 5502 |
|
|---|
| 5503 | Whitespace between the words in the lists is not preserved; it is
|
|---|
| 5504 | replaced with a single space.
|
|---|
| 5505 |
|
|---|
| 5506 | This function can merge the results of the `dir' and `notdir'
|
|---|
| 5507 | functions, to produce the original list of files which was given
|
|---|
| 5508 | to those two functions.
|
|---|
| 5509 |
|
|---|
| 5510 | `$(wildcard PATTERN)'
|
|---|
| 5511 | The argument PATTERN is a file name pattern, typically containing
|
|---|
| 5512 | wildcard characters (as in shell file name patterns). The result
|
|---|
| 5513 | of `wildcard' is a space-separated list of the names of existing
|
|---|
| 5514 | files that match the pattern. *Note Using Wildcard Characters in
|
|---|
| 5515 | File Names: Wildcards.
|
|---|
| 5516 |
|
|---|
| 5517 | `$(realpath NAMES...)'
|
|---|
| 5518 | For each file name in NAMES return the canonical absolute name. A
|
|---|
| 5519 | canonical name does not contain any `.' or `..' components, nor
|
|---|
| 5520 | any repeated path separators (`/') or symlinks. In case of a
|
|---|
| 5521 | failure the empty string is returned. Consult the `realpath(3)'
|
|---|
| 5522 | documentation for a list of possible failure causes.
|
|---|
| 5523 |
|
|---|
| 5524 | `$(abspath NAMES...)'
|
|---|
| 5525 | For each file name in NAMES return an absolute name that does not
|
|---|
| 5526 | contain any `.' or `..' components, nor any repeated path
|
|---|
| 5527 | separators (`/'). Note that, in contrast to `realpath' function,
|
|---|
| 5528 | `abspath' does not resolve symlinks and does not require the file
|
|---|
| 5529 | names to refer to an existing file or directory. Use the
|
|---|
| 5530 | `wildcard' function to test for existence.
|
|---|
| 5531 |
|
|---|
| 5532 |
|
|---|
| 5533 | File: make.info, Node: Conditional Functions, Next: Foreach Function, Prev: File Name Functions, Up: Functions
|
|---|
| 5534 |
|
|---|
| 5535 | 8.4 Functions for Conditionals
|
|---|
| 5536 | ==============================
|
|---|
| 5537 |
|
|---|
| 5538 | There are three functions that provide conditional expansion. A key
|
|---|
| 5539 | aspect of these functions is that not all of the arguments are expanded
|
|---|
| 5540 | initially. Only those arguments which need to be expanded, will be
|
|---|
| 5541 | expanded.
|
|---|
| 5542 |
|
|---|
| 5543 | `$(if CONDITION,THEN-PART[,ELSE-PART])'
|
|---|
| 5544 | The `if' function provides support for conditional expansion in a
|
|---|
| 5545 | functional context (as opposed to the GNU `make' makefile
|
|---|
| 5546 | conditionals such as `ifeq' (*note Syntax of Conditionals:
|
|---|
| 5547 | Conditional Syntax.).
|
|---|
| 5548 |
|
|---|
| 5549 | The first argument, CONDITION, first has all preceding and
|
|---|
| 5550 | trailing whitespace stripped, then is expanded. If it expands to
|
|---|
| 5551 | any non-empty string, then the condition is considered to be true.
|
|---|
| 5552 | If it expands to an empty string, the condition is considered to
|
|---|
| 5553 | be false.
|
|---|
| 5554 |
|
|---|
| 5555 | If the condition is true then the second argument, THEN-PART, is
|
|---|
| 5556 | evaluated and this is used as the result of the evaluation of the
|
|---|
| 5557 | entire `if' function.
|
|---|
| 5558 |
|
|---|
| 5559 | If the condition is false then the third argument, ELSE-PART, is
|
|---|
| 5560 | evaluated and this is the result of the `if' function. If there is
|
|---|
| 5561 | no third argument, the `if' function evaluates to nothing (the
|
|---|
| 5562 | empty string).
|
|---|
| 5563 |
|
|---|
| 5564 | Note that only one of the THEN-PART or the ELSE-PART will be
|
|---|
| 5565 | evaluated, never both. Thus, either can contain side-effects
|
|---|
| 5566 | (such as `shell' function calls, etc.)
|
|---|
| 5567 |
|
|---|
| 5568 | `$(or CONDITION1[,CONDITION2[,CONDITION3...]])'
|
|---|
| 5569 | The `or' function provides a "short-circuiting" OR operation.
|
|---|
| 5570 | Each argument is expanded, in order. If an argument expands to a
|
|---|
| 5571 | non-empty string the processing stops and the result of the
|
|---|
| 5572 | expansion is that string. If, after all arguments are expanded,
|
|---|
| 5573 | all of them are false (empty), then the result of the expansion is
|
|---|
| 5574 | the empty string.
|
|---|
| 5575 |
|
|---|
| 5576 | `$(and CONDITION1[,CONDITION2[,CONDITION3...]])'
|
|---|
| 5577 | The `and' function provides a "short-circuiting" AND operation.
|
|---|
| 5578 | Each argument is expanded, in order. If an argument expands to an
|
|---|
| 5579 | empty string the processing stops and the result of the expansion
|
|---|
| 5580 | is the empty string. If all arguments expand to a non-empty
|
|---|
| 5581 | string then the result of the expansion is the expansion of the
|
|---|
| 5582 | last argument.
|
|---|
| 5583 |
|
|---|
| 5584 |
|
|---|
| 5585 |
|
|---|
| 5586 | File: make.info, Node: Foreach Function, Next: Call Function, Prev: Conditional Functions, Up: Functions
|
|---|
| 5587 |
|
|---|
| 5588 | 8.5 The `foreach' Function
|
|---|
| 5589 | ==========================
|
|---|
| 5590 |
|
|---|
| 5591 | The `foreach' function is very different from other functions. It
|
|---|
| 5592 | causes one piece of text to be used repeatedly, each time with a
|
|---|
| 5593 | different substitution performed on it. It resembles the `for' command
|
|---|
| 5594 | in the shell `sh' and the `foreach' command in the C-shell `csh'.
|
|---|
| 5595 |
|
|---|
| 5596 | The syntax of the `foreach' function is:
|
|---|
| 5597 |
|
|---|
| 5598 | $(foreach VAR,LIST,TEXT)
|
|---|
| 5599 |
|
|---|
| 5600 | The first two arguments, VAR and LIST, are expanded before anything
|
|---|
| 5601 | else is done; note that the last argument, TEXT, is *not* expanded at
|
|---|
| 5602 | the same time. Then for each word of the expanded value of LIST, the
|
|---|
| 5603 | variable named by the expanded value of VAR is set to that word, and
|
|---|
| 5604 | TEXT is expanded. Presumably TEXT contains references to that
|
|---|
| 5605 | variable, so its expansion will be different each time.
|
|---|
| 5606 |
|
|---|
| 5607 | The result is that TEXT is expanded as many times as there are
|
|---|
| 5608 | whitespace-separated words in LIST. The multiple expansions of TEXT
|
|---|
| 5609 | are concatenated, with spaces between them, to make the result of
|
|---|
| 5610 | `foreach'.
|
|---|
| 5611 |
|
|---|
| 5612 | This simple example sets the variable `files' to the list of all
|
|---|
| 5613 | files in the directories in the list `dirs':
|
|---|
| 5614 |
|
|---|
| 5615 | dirs := a b c d
|
|---|
| 5616 | files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
|
|---|
| 5617 |
|
|---|
| 5618 | Here TEXT is `$(wildcard $(dir)/*)'. The first repetition finds the
|
|---|
| 5619 | value `a' for `dir', so it produces the same result as `$(wildcard
|
|---|
| 5620 | a/*)'; the second repetition produces the result of `$(wildcard b/*)';
|
|---|
| 5621 | and the third, that of `$(wildcard c/*)'.
|
|---|
| 5622 |
|
|---|
| 5623 | This example has the same result (except for setting `dirs') as the
|
|---|
| 5624 | following example:
|
|---|
| 5625 |
|
|---|
| 5626 | files := $(wildcard a/* b/* c/* d/*)
|
|---|
| 5627 |
|
|---|
| 5628 | When TEXT is complicated, you can improve readability by giving it a
|
|---|
| 5629 | name, with an additional variable:
|
|---|
| 5630 |
|
|---|
| 5631 | find_files = $(wildcard $(dir)/*)
|
|---|
| 5632 | dirs := a b c d
|
|---|
| 5633 | files := $(foreach dir,$(dirs),$(find_files))
|
|---|
| 5634 |
|
|---|
| 5635 | Here we use the variable `find_files' this way. We use plain `=' to
|
|---|
| 5636 | define a recursively-expanding variable, so that its value contains an
|
|---|
| 5637 | actual function call to be reexpanded under the control of `foreach'; a
|
|---|
| 5638 | simply-expanded variable would not do, since `wildcard' would be called
|
|---|
| 5639 | only once at the time of defining `find_files'.
|
|---|
| 5640 |
|
|---|
| 5641 | The `foreach' function has no permanent effect on the variable VAR;
|
|---|
| 5642 | its value and flavor after the `foreach' function call are the same as
|
|---|
| 5643 | they were beforehand. The other values which are taken from LIST are
|
|---|
| 5644 | in effect only temporarily, during the execution of `foreach'. The
|
|---|
| 5645 | variable VAR is a simply-expanded variable during the execution of
|
|---|
| 5646 | `foreach'. If VAR was undefined before the `foreach' function call, it
|
|---|
| 5647 | is undefined after the call. *Note The Two Flavors of Variables:
|
|---|
| 5648 | Flavors.
|
|---|
| 5649 |
|
|---|
| 5650 | You must take care when using complex variable expressions that
|
|---|
| 5651 | result in variable names because many strange things are valid variable
|
|---|
| 5652 | names, but are probably not what you intended. For example,
|
|---|
| 5653 |
|
|---|
| 5654 | files := $(foreach Esta escrito en espanol!,b c ch,$(find_files))
|
|---|
| 5655 |
|
|---|
| 5656 | might be useful if the value of `find_files' references the variable
|
|---|
| 5657 | whose name is `Esta escrito en espanol!' (es un nombre bastante largo,
|
|---|
| 5658 | no?), but it is more likely to be a mistake.
|
|---|
| 5659 |
|
|---|
| 5660 |
|
|---|
| 5661 | File: make.info, Node: Call Function, Next: Value Function, Prev: Foreach Function, Up: Functions
|
|---|
| 5662 |
|
|---|
| 5663 | 8.6 The `call' Function
|
|---|
| 5664 | =======================
|
|---|
| 5665 |
|
|---|
| 5666 | The `call' function is unique in that it can be used to create new
|
|---|
| 5667 | parameterized functions. You can write a complex expression as the
|
|---|
| 5668 | value of a variable, then use `call' to expand it with different values.
|
|---|
| 5669 |
|
|---|
| 5670 | The syntax of the `call' function is:
|
|---|
| 5671 |
|
|---|
| 5672 | $(call VARIABLE,PARAM,PARAM,...)
|
|---|
| 5673 |
|
|---|
| 5674 | When `make' expands this function, it assigns each PARAM to
|
|---|
| 5675 | temporary variables `$(1)', `$(2)', etc. The variable `$(0)' will
|
|---|
| 5676 | contain VARIABLE. There is no maximum number of parameter arguments.
|
|---|
| 5677 | There is no minimum, either, but it doesn't make sense to use `call'
|
|---|
| 5678 | with no parameters.
|
|---|
| 5679 |
|
|---|
| 5680 | Then VARIABLE is expanded as a `make' variable in the context of
|
|---|
| 5681 | these temporary assignments. Thus, any reference to `$(1)' in the
|
|---|
| 5682 | value of VARIABLE will resolve to the first PARAM in the invocation of
|
|---|
| 5683 | `call'.
|
|---|
| 5684 |
|
|---|
| 5685 | Note that VARIABLE is the _name_ of a variable, not a _reference_ to
|
|---|
| 5686 | that variable. Therefore you would not normally use a `$' or
|
|---|
| 5687 | parentheses when writing it. (You can, however, use a variable
|
|---|
| 5688 | reference in the name if you want the name not to be a constant.)
|
|---|
| 5689 |
|
|---|
| 5690 | If VARIABLE is the name of a builtin function, the builtin function
|
|---|
| 5691 | is always invoked (even if a `make' variable by that name also exists).
|
|---|
| 5692 |
|
|---|
| 5693 | The `call' function expands the PARAM arguments before assigning
|
|---|
| 5694 | them to temporary variables. This means that VARIABLE values
|
|---|
| 5695 | containing references to builtin functions that have special expansion
|
|---|
| 5696 | rules, like `foreach' or `if', may not work as you expect.
|
|---|
| 5697 |
|
|---|
| 5698 | Some examples may make this clearer.
|
|---|
| 5699 |
|
|---|
| 5700 | This macro simply reverses its arguments:
|
|---|
| 5701 |
|
|---|
| 5702 | reverse = $(2) $(1)
|
|---|
| 5703 |
|
|---|
| 5704 | foo = $(call reverse,a,b)
|
|---|
| 5705 |
|
|---|
| 5706 | Here FOO will contain `b a'.
|
|---|
| 5707 |
|
|---|
| 5708 | This one is slightly more interesting: it defines a macro to search
|
|---|
| 5709 | for the first instance of a program in `PATH':
|
|---|
| 5710 |
|
|---|
| 5711 | pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
|
|---|
| 5712 |
|
|---|
| 5713 | LS := $(call pathsearch,ls)
|
|---|
| 5714 |
|
|---|
| 5715 | Now the variable LS contains `/bin/ls' or similar.
|
|---|
| 5716 |
|
|---|
| 5717 | The `call' function can be nested. Each recursive invocation gets
|
|---|
| 5718 | its own local values for `$(1)', etc. that mask the values of
|
|---|
| 5719 | higher-level `call'. For example, here is an implementation of a "map"
|
|---|
| 5720 | function:
|
|---|
| 5721 |
|
|---|
| 5722 | map = $(foreach a,$(2),$(call $(1),$(a)))
|
|---|
| 5723 |
|
|---|
| 5724 | Now you can MAP a function that normally takes only one argument,
|
|---|
| 5725 | such as `origin', to multiple values in one step:
|
|---|
| 5726 |
|
|---|
| 5727 | o = $(call map,origin,o map MAKE)
|
|---|
| 5728 |
|
|---|
| 5729 | and end up with O containing something like `file file default'.
|
|---|
| 5730 |
|
|---|
| 5731 | A final caution: be careful when adding whitespace to the arguments
|
|---|
| 5732 | to `call'. As with other functions, any whitespace contained in the
|
|---|
| 5733 | second and subsequent arguments is kept; this can cause strange
|
|---|
| 5734 | effects. It's generally safest to remove all extraneous whitespace when
|
|---|
| 5735 | providing parameters to `call'.
|
|---|
| 5736 |
|
|---|
| 5737 |
|
|---|
| 5738 | File: make.info, Node: Value Function, Next: Eval Function, Prev: Call Function, Up: Functions
|
|---|
| 5739 |
|
|---|
| 5740 | 8.7 The `value' Function
|
|---|
| 5741 | ========================
|
|---|
| 5742 |
|
|---|
| 5743 | The `value' function provides a way for you to use the value of a
|
|---|
| 5744 | variable _without_ having it expanded. Please note that this does not
|
|---|
| 5745 | undo expansions which have already occurred; for example if you create
|
|---|
| 5746 | a simply expanded variable its value is expanded during the definition;
|
|---|
| 5747 | in that case the `value' function will return the same result as using
|
|---|
| 5748 | the variable directly.
|
|---|
| 5749 |
|
|---|
| 5750 | The syntax of the `value' function is:
|
|---|
| 5751 |
|
|---|
| 5752 | $(value VARIABLE)
|
|---|
| 5753 |
|
|---|
| 5754 | Note that VARIABLE is the _name_ of a variable; not a _reference_ to
|
|---|
| 5755 | that variable. Therefore you would not normally use a `$' or
|
|---|
| 5756 | parentheses when writing it. (You can, however, use a variable
|
|---|
| 5757 | reference in the name if you want the name not to be a constant.)
|
|---|
| 5758 |
|
|---|
| 5759 | The result of this function is a string containing the value of
|
|---|
| 5760 | VARIABLE, without any expansion occurring. For example, in this
|
|---|
| 5761 | makefile:
|
|---|
| 5762 |
|
|---|
| 5763 | FOO = $PATH
|
|---|
| 5764 |
|
|---|
| 5765 | all:
|
|---|
| 5766 | @echo $(FOO)
|
|---|
| 5767 | @echo $(value FOO)
|
|---|
| 5768 |
|
|---|
| 5769 | The first output line would be `ATH', since the "$P" would be expanded
|
|---|
| 5770 | as a `make' variable, while the second output line would be the current
|
|---|
| 5771 | value of your `$PATH' environment variable, since the `value' function
|
|---|
| 5772 | avoided the expansion.
|
|---|
| 5773 |
|
|---|
| 5774 | The `value' function is most often used in conjunction with the
|
|---|
| 5775 | `eval' function (*note Eval Function::).
|
|---|
| 5776 |
|
|---|
| 5777 |
|
|---|
| 5778 | File: make.info, Node: Eval Function, Next: Origin Function, Prev: Value Function, Up: Functions
|
|---|
| 5779 |
|
|---|
| 5780 | 8.8 The `eval' Function
|
|---|
| 5781 | =======================
|
|---|
| 5782 |
|
|---|
| 5783 | The `eval' function is very special: it allows you to define new
|
|---|
| 5784 | makefile constructs that are not constant; which are the result of
|
|---|
| 5785 | evaluating other variables and functions. The argument to the `eval'
|
|---|
| 5786 | function is expanded, then the results of that expansion are parsed as
|
|---|
| 5787 | makefile syntax. The expanded results can define new `make' variables,
|
|---|
| 5788 | targets, implicit or explicit rules, etc.
|
|---|
| 5789 |
|
|---|
| 5790 | The result of the `eval' function is always the empty string; thus,
|
|---|
| 5791 | it can be placed virtually anywhere in a makefile without causing
|
|---|
| 5792 | syntax errors.
|
|---|
| 5793 |
|
|---|
| 5794 | It's important to realize that the `eval' argument is expanded
|
|---|
| 5795 | _twice_; first by the `eval' function, then the results of that
|
|---|
| 5796 | expansion are expanded again when they are parsed as makefile syntax.
|
|---|
| 5797 | This means you may need to provide extra levels of escaping for "$"
|
|---|
| 5798 | characters when using `eval'. The `value' function (*note Value
|
|---|
| 5799 | Function::) can sometimes be useful in these situations, to circumvent
|
|---|
| 5800 | unwanted expansions.
|
|---|
| 5801 |
|
|---|
| 5802 | Here is an example of how `eval' can be used; this example combines
|
|---|
| 5803 | a number of concepts and other functions. Although it might seem
|
|---|
| 5804 | overly complex to use `eval' in this example, rather than just writing
|
|---|
| 5805 | out the rules, consider two things: first, the template definition (in
|
|---|
| 5806 | `PROGRAM_template') could need to be much more complex than it is here;
|
|---|
| 5807 | and second, you might put the complex, "generic" part of this example
|
|---|
| 5808 | into another makefile, then include it in all the individual makefiles.
|
|---|
| 5809 | Now your individual makefiles are quite straightforward.
|
|---|
| 5810 |
|
|---|
| 5811 | PROGRAMS = server client
|
|---|
| 5812 |
|
|---|
| 5813 | server_OBJS = server.o server_priv.o server_access.o
|
|---|
| 5814 | server_LIBS = priv protocol
|
|---|
| 5815 |
|
|---|
| 5816 | client_OBJS = client.o client_api.o client_mem.o
|
|---|
| 5817 | client_LIBS = protocol
|
|---|
| 5818 |
|
|---|
| 5819 | # Everything after this is generic
|
|---|
| 5820 |
|
|---|
| 5821 | .PHONY: all
|
|---|
| 5822 | all: $(PROGRAMS)
|
|---|
| 5823 |
|
|---|
| 5824 | define PROGRAM_template
|
|---|
| 5825 | $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
|
|---|
| 5826 | ALL_OBJS += $$($(1)_OBJS)
|
|---|
| 5827 | endef
|
|---|
| 5828 |
|
|---|
| 5829 | $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
|
|---|
| 5830 |
|
|---|
| 5831 | $(PROGRAMS):
|
|---|
| 5832 | $(LINK.o) $^ $(LDLIBS) -o $@
|
|---|
| 5833 |
|
|---|
| 5834 | clean:
|
|---|
| 5835 | rm -f $(ALL_OBJS) $(PROGRAMS)
|
|---|
| 5836 |
|
|---|
| 5837 |
|
|---|
| 5838 | File: make.info, Node: Origin Function, Next: Flavor Function, Prev: Eval Function, Up: Functions
|
|---|
| 5839 |
|
|---|
| 5840 | 8.9 The `origin' Function
|
|---|
| 5841 | =========================
|
|---|
| 5842 |
|
|---|
| 5843 | The `origin' function is unlike most other functions in that it does
|
|---|
| 5844 | not operate on the values of variables; it tells you something _about_
|
|---|
| 5845 | a variable. Specifically, it tells you where it came from.
|
|---|
| 5846 |
|
|---|
| 5847 | The syntax of the `origin' function is:
|
|---|
| 5848 |
|
|---|
| 5849 | $(origin VARIABLE)
|
|---|
| 5850 |
|
|---|
| 5851 | Note that VARIABLE is the _name_ of a variable to inquire about; not
|
|---|
| 5852 | a _reference_ to that variable. Therefore you would not normally use a
|
|---|
| 5853 | `$' or parentheses when writing it. (You can, however, use a variable
|
|---|
| 5854 | reference in the name if you want the name not to be a constant.)
|
|---|
| 5855 |
|
|---|
| 5856 | The result of this function is a string telling you how the variable
|
|---|
| 5857 | VARIABLE was defined:
|
|---|
| 5858 |
|
|---|
| 5859 | `undefined'
|
|---|
| 5860 | if VARIABLE was never defined.
|
|---|
| 5861 |
|
|---|
| 5862 | `default'
|
|---|
| 5863 | if VARIABLE has a default definition, as is usual with `CC' and so
|
|---|
| 5864 | on. *Note Variables Used by Implicit Rules: Implicit Variables.
|
|---|
| 5865 | Note that if you have redefined a default variable, the `origin'
|
|---|
| 5866 | function will return the origin of the later definition.
|
|---|
| 5867 |
|
|---|
| 5868 | `environment'
|
|---|
| 5869 | if VARIABLE was defined as an environment variable and the `-e'
|
|---|
| 5870 | option is _not_ turned on (*note Summary of Options: Options
|
|---|
| 5871 | Summary.).
|
|---|
| 5872 |
|
|---|
| 5873 | `environment override'
|
|---|
| 5874 | if VARIABLE was defined as an environment variable and the `-e'
|
|---|
| 5875 | option _is_ turned on (*note Summary of Options: Options Summary.).
|
|---|
| 5876 |
|
|---|
| 5877 | `file'
|
|---|
| 5878 | if VARIABLE was defined in a makefile.
|
|---|
| 5879 |
|
|---|
| 5880 | `command line'
|
|---|
| 5881 | if VARIABLE was defined on the command line.
|
|---|
| 5882 |
|
|---|
| 5883 | `override'
|
|---|
| 5884 | if VARIABLE was defined with an `override' directive in a makefile
|
|---|
| 5885 | (*note The `override' Directive: Override Directive.).
|
|---|
| 5886 |
|
|---|
| 5887 | `automatic'
|
|---|
| 5888 | if VARIABLE is an automatic variable defined for the execution of
|
|---|
| 5889 | the commands for each rule (*note Automatic Variables::).
|
|---|
| 5890 |
|
|---|
| 5891 | This information is primarily useful (other than for your curiosity)
|
|---|
| 5892 | to determine if you want to believe the value of a variable. For
|
|---|
| 5893 | example, suppose you have a makefile `foo' that includes another
|
|---|
| 5894 | makefile `bar'. You want a variable `bletch' to be defined in `bar' if
|
|---|
| 5895 | you run the command `make -f bar', even if the environment contains a
|
|---|
| 5896 | definition of `bletch'. However, if `foo' defined `bletch' before
|
|---|
| 5897 | including `bar', you do not want to override that definition. This
|
|---|
| 5898 | could be done by using an `override' directive in `foo', giving that
|
|---|
| 5899 | definition precedence over the later definition in `bar';
|
|---|
| 5900 | unfortunately, the `override' directive would also override any command
|
|---|
| 5901 | line definitions. So, `bar' could include:
|
|---|
| 5902 |
|
|---|
| 5903 | ifdef bletch
|
|---|
| 5904 | ifeq "$(origin bletch)" "environment"
|
|---|
| 5905 | bletch = barf, gag, etc.
|
|---|
| 5906 | endif
|
|---|
| 5907 | endif
|
|---|
| 5908 |
|
|---|
| 5909 | If `bletch' has been defined from the environment, this will redefine
|
|---|
| 5910 | it.
|
|---|
| 5911 |
|
|---|
| 5912 | If you want to override a previous definition of `bletch' if it came
|
|---|
| 5913 | from the environment, even under `-e', you could instead write:
|
|---|
| 5914 |
|
|---|
| 5915 | ifneq "$(findstring environment,$(origin bletch))" ""
|
|---|
| 5916 | bletch = barf, gag, etc.
|
|---|
| 5917 | endif
|
|---|
| 5918 |
|
|---|
| 5919 | Here the redefinition takes place if `$(origin bletch)' returns
|
|---|
| 5920 | either `environment' or `environment override'. *Note Functions for
|
|---|
| 5921 | String Substitution and Analysis: Text Functions.
|
|---|
| 5922 |
|
|---|
| 5923 |
|
|---|
| 5924 | File: make.info, Node: Flavor Function, Next: Shell Function, Prev: Origin Function, Up: Functions
|
|---|
| 5925 |
|
|---|
| 5926 | 8.10 The `flavor' Function
|
|---|
| 5927 | ==========================
|
|---|
| 5928 |
|
|---|
| 5929 | The `flavor' function is unlike most other functions (and like `origin'
|
|---|
| 5930 | function) in that it does not operate on the values of variables; it
|
|---|
| 5931 | tells you something _about_ a variable. Specifically, it tells you the
|
|---|
| 5932 | flavor of a variable (*note The Two Flavors of Variables: Flavors.).
|
|---|
| 5933 |
|
|---|
| 5934 | The syntax of the `flavor' function is:
|
|---|
| 5935 |
|
|---|
| 5936 | $(flavor VARIABLE)
|
|---|
| 5937 |
|
|---|
| 5938 | Note that VARIABLE is the _name_ of a variable to inquire about; not
|
|---|
| 5939 | a _reference_ to that variable. Therefore you would not normally use a
|
|---|
| 5940 | `$' or parentheses when writing it. (You can, however, use a variable
|
|---|
| 5941 | reference in the name if you want the name not to be a constant.)
|
|---|
| 5942 |
|
|---|
| 5943 | The result of this function is a string that identifies the flavor
|
|---|
| 5944 | of the variable VARIABLE:
|
|---|
| 5945 |
|
|---|
| 5946 | `undefined'
|
|---|
| 5947 | if VARIABLE was never defined.
|
|---|
| 5948 |
|
|---|
| 5949 | `recursive'
|
|---|
| 5950 | if VARIABLE is a recursively expanded variable.
|
|---|
| 5951 |
|
|---|
| 5952 | `simple'
|
|---|
| 5953 | if VARIABLE is a simply expanded variable.
|
|---|
| 5954 |
|
|---|
| 5955 |
|
|---|
| 5956 |
|
|---|
| 5957 | File: make.info, Node: Shell Function, Next: Make Control Functions, Prev: Flavor Function, Up: Functions
|
|---|
| 5958 |
|
|---|
| 5959 | 8.11 The `shell' Function
|
|---|
| 5960 | =========================
|
|---|
| 5961 |
|
|---|
| 5962 | The `shell' function is unlike any other function other than the
|
|---|
| 5963 | `wildcard' function (*note The Function `wildcard': Wildcard Function.)
|
|---|
| 5964 | in that it communicates with the world outside of `make'.
|
|---|
| 5965 |
|
|---|
| 5966 | The `shell' function performs the same function that backquotes
|
|---|
| 5967 | (``') perform in most shells: it does "command expansion". This means
|
|---|
| 5968 | that it takes as an argument a shell command and evaluates to the
|
|---|
| 5969 | output of the command. The only processing `make' does on the result
|
|---|
| 5970 | is to convert each newline (or carriage-return / newline pair) to a
|
|---|
| 5971 | single space. If there is a trailing (carriage-return and) newline it
|
|---|
| 5972 | will simply be removed.
|
|---|
| 5973 |
|
|---|
| 5974 | The commands run by calls to the `shell' function are run when the
|
|---|
| 5975 | function calls are expanded (*note How `make' Reads a Makefile: Reading
|
|---|
| 5976 | Makefiles.). Because this function involves spawning a new shell, you
|
|---|
| 5977 | should carefully consider the performance implications of using the
|
|---|
| 5978 | `shell' function within recursively expanded variables vs. simply
|
|---|
| 5979 | expanded variables (*note The Two Flavors of Variables: Flavors.).
|
|---|
| 5980 |
|
|---|
| 5981 | Here are some examples of the use of the `shell' function:
|
|---|
| 5982 |
|
|---|
| 5983 | contents := $(shell cat foo)
|
|---|
| 5984 |
|
|---|
| 5985 | sets `contents' to the contents of the file `foo', with a space (rather
|
|---|
| 5986 | than a newline) separating each line.
|
|---|
| 5987 |
|
|---|
| 5988 | files := $(shell echo *.c)
|
|---|
| 5989 |
|
|---|
| 5990 | sets `files' to the expansion of `*.c'. Unless `make' is using a very
|
|---|
| 5991 | strange shell, this has the same result as `$(wildcard *.c)' (as long
|
|---|
| 5992 | as at least one `.c' file exists).
|
|---|
| 5993 |
|
|---|
| 5994 |
|
|---|
| 5995 | File: make.info, Node: Make Control Functions, Prev: Shell Function, Up: Functions
|
|---|
| 5996 |
|
|---|
| 5997 | 8.12 Functions That Control Make
|
|---|
| 5998 | ================================
|
|---|
| 5999 |
|
|---|
| 6000 | These functions control the way make runs. Generally, they are used to
|
|---|
| 6001 | provide information to the user of the makefile or to cause make to stop
|
|---|
| 6002 | if some sort of environmental error is detected.
|
|---|
| 6003 |
|
|---|
| 6004 | `$(error TEXT...)'
|
|---|
| 6005 | Generates a fatal error where the message is TEXT. Note that the
|
|---|
| 6006 | error is generated whenever this function is evaluated. So, if
|
|---|
| 6007 | you put it inside a command script or on the right side of a
|
|---|
| 6008 | recursive variable assignment, it won't be evaluated until later.
|
|---|
| 6009 | The TEXT will be expanded before the error is generated.
|
|---|
| 6010 |
|
|---|
| 6011 | For example,
|
|---|
| 6012 |
|
|---|
| 6013 | ifdef ERROR1
|
|---|
| 6014 | $(error error is $(ERROR1))
|
|---|
| 6015 | endif
|
|---|
| 6016 |
|
|---|
| 6017 | will generate a fatal error during the read of the makefile if the
|
|---|
| 6018 | `make' variable `ERROR1' is defined. Or,
|
|---|
| 6019 |
|
|---|
| 6020 | ERR = $(error found an error!)
|
|---|
| 6021 |
|
|---|
| 6022 | .PHONY: err
|
|---|
| 6023 | err: ; $(ERR)
|
|---|
| 6024 |
|
|---|
| 6025 | will generate a fatal error while `make' is running, if the `err'
|
|---|
| 6026 | target is invoked.
|
|---|
| 6027 |
|
|---|
| 6028 | `$(warning TEXT...)'
|
|---|
| 6029 | This function works similarly to the `error' function, above,
|
|---|
| 6030 | except that `make' doesn't exit. Instead, TEXT is expanded and
|
|---|
| 6031 | the resulting message is displayed, but processing of the makefile
|
|---|
| 6032 | continues.
|
|---|
| 6033 |
|
|---|
| 6034 | The result of the expansion of this function is the empty string.
|
|---|
| 6035 |
|
|---|
| 6036 | `$(info TEXT...)'
|
|---|
| 6037 | This function does nothing more than print its (expanded)
|
|---|
| 6038 | argument(s) to standard output. No makefile name or line number
|
|---|
| 6039 | is added. The result of the expansion of this function is the
|
|---|
| 6040 | empty string.
|
|---|
| 6041 |
|
|---|
| 6042 |
|
|---|
| 6043 | File: make.info, Node: Running, Next: Implicit Rules, Prev: Functions, Up: Top
|
|---|
| 6044 |
|
|---|
| 6045 | 9 How to Run `make'
|
|---|
| 6046 | *******************
|
|---|
| 6047 |
|
|---|
| 6048 | A makefile that says how to recompile a program can be used in more
|
|---|
| 6049 | than one way. The simplest use is to recompile every file that is out
|
|---|
| 6050 | of date. Usually, makefiles are written so that if you run `make' with
|
|---|
| 6051 | no arguments, it does just that.
|
|---|
| 6052 |
|
|---|
| 6053 | But you might want to update only some of the files; you might want
|
|---|
| 6054 | to use a different compiler or different compiler options; you might
|
|---|
| 6055 | want just to find out which files are out of date without changing them.
|
|---|
| 6056 |
|
|---|
| 6057 | By giving arguments when you run `make', you can do any of these
|
|---|
| 6058 | things and many others.
|
|---|
| 6059 |
|
|---|
| 6060 | The exit status of `make' is always one of three values:
|
|---|
| 6061 | `0'
|
|---|
| 6062 | The exit status is zero if `make' is successful.
|
|---|
| 6063 |
|
|---|
| 6064 | `2'
|
|---|
| 6065 | The exit status is two if `make' encounters any errors. It will
|
|---|
| 6066 | print messages describing the particular errors.
|
|---|
| 6067 |
|
|---|
| 6068 | `1'
|
|---|
| 6069 | The exit status is one if you use the `-q' flag and `make'
|
|---|
| 6070 | determines that some target is not already up to date. *Note
|
|---|
| 6071 | Instead of Executing the Commands: Instead of Execution.
|
|---|
| 6072 |
|
|---|
| 6073 | * Menu:
|
|---|
| 6074 |
|
|---|
| 6075 | * Makefile Arguments:: How to specify which makefile to use.
|
|---|
| 6076 | * Goals:: How to use goal arguments to specify which
|
|---|
| 6077 | parts of the makefile to use.
|
|---|
| 6078 | * Instead of Execution:: How to use mode flags to specify what
|
|---|
| 6079 | kind of thing to do with the commands
|
|---|
| 6080 | in the makefile other than simply
|
|---|
| 6081 | execute them.
|
|---|
| 6082 | * Avoiding Compilation:: How to avoid recompiling certain files.
|
|---|
| 6083 | * Overriding:: How to override a variable to specify
|
|---|
| 6084 | an alternate compiler and other things.
|
|---|
| 6085 | * Testing:: How to proceed past some errors, to
|
|---|
| 6086 | test compilation.
|
|---|
| 6087 | * Options Summary:: Summary of Options
|
|---|
| 6088 |
|
|---|
| 6089 |
|
|---|
| 6090 | File: make.info, Node: Makefile Arguments, Next: Goals, Prev: Running, Up: Running
|
|---|
| 6091 |
|
|---|
| 6092 | 9.1 Arguments to Specify the Makefile
|
|---|
| 6093 | =====================================
|
|---|
| 6094 |
|
|---|
| 6095 | The way to specify the name of the makefile is with the `-f' or
|
|---|
| 6096 | `--file' option (`--makefile' also works). For example, `-f altmake'
|
|---|
| 6097 | says to use the file `altmake' as the makefile.
|
|---|
| 6098 |
|
|---|
| 6099 | If you use the `-f' flag several times and follow each `-f' with an
|
|---|
| 6100 | argument, all the specified files are used jointly as makefiles.
|
|---|
| 6101 |
|
|---|
| 6102 | If you do not use the `-f' or `--file' flag, the default is to try
|
|---|
| 6103 | `GNUmakefile', `makefile', and `Makefile', in that order, and use the
|
|---|
| 6104 | first of these three which exists or can be made (*note Writing
|
|---|
| 6105 | Makefiles: Makefiles.).
|
|---|
| 6106 |
|
|---|
| 6107 |
|
|---|
| 6108 | File: make.info, Node: Goals, Next: Instead of Execution, Prev: Makefile Arguments, Up: Running
|
|---|
| 6109 |
|
|---|
| 6110 | 9.2 Arguments to Specify the Goals
|
|---|
| 6111 | ==================================
|
|---|
| 6112 |
|
|---|
| 6113 | The "goals" are the targets that `make' should strive ultimately to
|
|---|
| 6114 | update. Other targets are updated as well if they appear as
|
|---|
| 6115 | prerequisites of goals, or prerequisites of prerequisites of goals, etc.
|
|---|
| 6116 |
|
|---|
| 6117 | By default, the goal is the first target in the makefile (not
|
|---|
| 6118 | counting targets that start with a period). Therefore, makefiles are
|
|---|
| 6119 | usually written so that the first target is for compiling the entire
|
|---|
| 6120 | program or programs they describe. If the first rule in the makefile
|
|---|
| 6121 | has several targets, only the first target in the rule becomes the
|
|---|
| 6122 | default goal, not the whole list. You can manage the selection of the
|
|---|
| 6123 | default goal from within your makefile using the `.DEFAULT_GOAL'
|
|---|
| 6124 | variable (*note Other Special Variables: Special Variables.).
|
|---|
| 6125 |
|
|---|
| 6126 | You can also specify a different goal or goals with command-line
|
|---|
| 6127 | arguments to `make'. Use the name of the goal as an argument. If you
|
|---|
| 6128 | specify several goals, `make' processes each of them in turn, in the
|
|---|
| 6129 | order you name them.
|
|---|
| 6130 |
|
|---|
| 6131 | Any target in the makefile may be specified as a goal (unless it
|
|---|
| 6132 | starts with `-' or contains an `=', in which case it will be parsed as
|
|---|
| 6133 | a switch or variable definition, respectively). Even targets not in
|
|---|
| 6134 | the makefile may be specified, if `make' can find implicit rules that
|
|---|
| 6135 | say how to make them.
|
|---|
| 6136 |
|
|---|
| 6137 | `Make' will set the special variable `MAKECMDGOALS' to the list of
|
|---|
| 6138 | goals you specified on the command line. If no goals were given on the
|
|---|
| 6139 | command line, this variable is empty. Note that this variable should
|
|---|
| 6140 | be used only in special circumstances.
|
|---|
| 6141 |
|
|---|
| 6142 | An example of appropriate use is to avoid including `.d' files
|
|---|
| 6143 | during `clean' rules (*note Automatic Prerequisites::), so `make' won't
|
|---|
| 6144 | create them only to immediately remove them again:
|
|---|
| 6145 |
|
|---|
| 6146 | sources = foo.c bar.c
|
|---|
| 6147 |
|
|---|
| 6148 | ifneq ($(MAKECMDGOALS),clean)
|
|---|
| 6149 | include $(sources:.c=.d)
|
|---|
| 6150 | endif
|
|---|
| 6151 |
|
|---|
| 6152 | One use of specifying a goal is if you want to compile only a part of
|
|---|
| 6153 | the program, or only one of several programs. Specify as a goal each
|
|---|
| 6154 | file that you wish to remake. For example, consider a directory
|
|---|
| 6155 | containing several programs, with a makefile that starts like this:
|
|---|
| 6156 |
|
|---|
| 6157 | .PHONY: all
|
|---|
| 6158 | all: size nm ld ar as
|
|---|
| 6159 |
|
|---|
| 6160 | If you are working on the program `size', you might want to say
|
|---|
| 6161 | `make size' so that only the files of that program are recompiled.
|
|---|
| 6162 |
|
|---|
| 6163 | Another use of specifying a goal is to make files that are not
|
|---|
| 6164 | normally made. For example, there may be a file of debugging output,
|
|---|
| 6165 | or a version of the program that is compiled specially for testing,
|
|---|
| 6166 | which has a rule in the makefile but is not a prerequisite of the
|
|---|
| 6167 | default goal.
|
|---|
| 6168 |
|
|---|
| 6169 | Another use of specifying a goal is to run the commands associated
|
|---|
| 6170 | with a phony target (*note Phony Targets::) or empty target (*note
|
|---|
| 6171 | Empty Target Files to Record Events: Empty Targets.). Many makefiles
|
|---|
| 6172 | contain a phony target named `clean' which deletes everything except
|
|---|
| 6173 | source files. Naturally, this is done only if you request it
|
|---|
| 6174 | explicitly with `make clean'. Following is a list of typical phony and
|
|---|
| 6175 | empty target names. *Note Standard Targets::, for a detailed list of
|
|---|
| 6176 | all the standard target names which GNU software packages use.
|
|---|
| 6177 |
|
|---|
| 6178 | `all'
|
|---|
| 6179 | Make all the top-level targets the makefile knows about.
|
|---|
| 6180 |
|
|---|
| 6181 | `clean'
|
|---|
| 6182 | Delete all files that are normally created by running `make'.
|
|---|
| 6183 |
|
|---|
| 6184 | `mostlyclean'
|
|---|
| 6185 | Like `clean', but may refrain from deleting a few files that people
|
|---|
| 6186 | normally don't want to recompile. For example, the `mostlyclean'
|
|---|
| 6187 | target for GCC does not delete `libgcc.a', because recompiling it
|
|---|
| 6188 | is rarely necessary and takes a lot of time.
|
|---|
| 6189 |
|
|---|
| 6190 | `distclean'
|
|---|
| 6191 | `realclean'
|
|---|
| 6192 | `clobber'
|
|---|
| 6193 | Any of these targets might be defined to delete _more_ files than
|
|---|
| 6194 | `clean' does. For example, this would delete configuration files
|
|---|
| 6195 | or links that you would normally create as preparation for
|
|---|
| 6196 | compilation, even if the makefile itself cannot create these files.
|
|---|
| 6197 |
|
|---|
| 6198 | `install'
|
|---|
| 6199 | Copy the executable file into a directory that users typically
|
|---|
| 6200 | search for commands; copy any auxiliary files that the executable
|
|---|
| 6201 | uses into the directories where it will look for them.
|
|---|
| 6202 |
|
|---|
| 6203 | `print'
|
|---|
| 6204 | Print listings of the source files that have changed.
|
|---|
| 6205 |
|
|---|
| 6206 | `tar'
|
|---|
| 6207 | Create a tar file of the source files.
|
|---|
| 6208 |
|
|---|
| 6209 | `shar'
|
|---|
| 6210 | Create a shell archive (shar file) of the source files.
|
|---|
| 6211 |
|
|---|
| 6212 | `dist'
|
|---|
| 6213 | Create a distribution file of the source files. This might be a
|
|---|
| 6214 | tar file, or a shar file, or a compressed version of one of the
|
|---|
| 6215 | above, or even more than one of the above.
|
|---|
| 6216 |
|
|---|
| 6217 | `TAGS'
|
|---|
| 6218 | Update a tags table for this program.
|
|---|
| 6219 |
|
|---|
| 6220 | `check'
|
|---|
| 6221 | `test'
|
|---|
| 6222 | Perform self tests on the program this makefile builds.
|
|---|
| 6223 |
|
|---|
| 6224 |
|
|---|
| 6225 | File: make.info, Node: Instead of Execution, Next: Avoiding Compilation, Prev: Goals, Up: Running
|
|---|
| 6226 |
|
|---|
| 6227 | 9.3 Instead of Executing the Commands
|
|---|
| 6228 | =====================================
|
|---|
| 6229 |
|
|---|
| 6230 | The makefile tells `make' how to tell whether a target is up to date,
|
|---|
| 6231 | and how to update each target. But updating the targets is not always
|
|---|
| 6232 | what you want. Certain options specify other activities for `make'.
|
|---|
| 6233 |
|
|---|
| 6234 | `-n'
|
|---|
| 6235 | `--just-print'
|
|---|
| 6236 | `--dry-run'
|
|---|
| 6237 | `--recon'
|
|---|
| 6238 | "No-op". The activity is to print what commands would be used to
|
|---|
| 6239 | make the targets up to date, but not actually execute them.
|
|---|
| 6240 |
|
|---|
| 6241 | `-t'
|
|---|
| 6242 | `--touch'
|
|---|
| 6243 | "Touch". The activity is to mark the targets as up to date without
|
|---|
| 6244 | actually changing them. In other words, `make' pretends to compile
|
|---|
| 6245 | the targets but does not really change their contents.
|
|---|
| 6246 |
|
|---|
| 6247 | `-q'
|
|---|
| 6248 | `--question'
|
|---|
| 6249 | "Question". The activity is to find out silently whether the
|
|---|
| 6250 | targets are up to date already; but execute no commands in either
|
|---|
| 6251 | case. In other words, neither compilation nor output will occur.
|
|---|
| 6252 |
|
|---|
| 6253 | `-W FILE'
|
|---|
| 6254 | `--what-if=FILE'
|
|---|
| 6255 | `--assume-new=FILE'
|
|---|
| 6256 | `--new-file=FILE'
|
|---|
| 6257 | "What if". Each `-W' flag is followed by a file name. The given
|
|---|
| 6258 | files' modification times are recorded by `make' as being the
|
|---|
| 6259 | present time, although the actual modification times remain the
|
|---|
| 6260 | same. You can use the `-W' flag in conjunction with the `-n' flag
|
|---|
| 6261 | to see what would happen if you were to modify specific files.
|
|---|
| 6262 |
|
|---|
| 6263 | With the `-n' flag, `make' prints the commands that it would
|
|---|
| 6264 | normally execute but does not execute them.
|
|---|
| 6265 |
|
|---|
| 6266 | With the `-t' flag, `make' ignores the commands in the rules and
|
|---|
| 6267 | uses (in effect) the command `touch' for each target that needs to be
|
|---|
| 6268 | remade. The `touch' command is also printed, unless `-s' or `.SILENT'
|
|---|
| 6269 | is used. For speed, `make' does not actually invoke the program
|
|---|
| 6270 | `touch'. It does the work directly.
|
|---|
| 6271 |
|
|---|
| 6272 | With the `-q' flag, `make' prints nothing and executes no commands,
|
|---|
| 6273 | but the exit status code it returns is zero if and only if the targets
|
|---|
| 6274 | to be considered are already up to date. If the exit status is one,
|
|---|
| 6275 | then some updating needs to be done. If `make' encounters an error,
|
|---|
| 6276 | the exit status is two, so you can distinguish an error from a target
|
|---|
| 6277 | that is not up to date.
|
|---|
| 6278 |
|
|---|
| 6279 | It is an error to use more than one of these three flags in the same
|
|---|
| 6280 | invocation of `make'.
|
|---|
| 6281 |
|
|---|
| 6282 | The `-n', `-t', and `-q' options do not affect command lines that
|
|---|
| 6283 | begin with `+' characters or contain the strings `$(MAKE)' or
|
|---|
| 6284 | `${MAKE}'. Note that only the line containing the `+' character or the
|
|---|
| 6285 | strings `$(MAKE)' or `${MAKE}' is run regardless of these options.
|
|---|
| 6286 | Other lines in the same rule are not run unless they too begin with `+'
|
|---|
| 6287 | or contain `$(MAKE)' or `${MAKE}' (*Note How the `MAKE' Variable Works:
|
|---|
| 6288 | MAKE Variable.)
|
|---|
| 6289 |
|
|---|
| 6290 | The `-W' flag provides two features:
|
|---|
| 6291 |
|
|---|
| 6292 | * If you also use the `-n' or `-q' flag, you can see what `make'
|
|---|
| 6293 | would do if you were to modify some files.
|
|---|
| 6294 |
|
|---|
| 6295 | * Without the `-n' or `-q' flag, when `make' is actually executing
|
|---|
| 6296 | commands, the `-W' flag can direct `make' to act as if some files
|
|---|
| 6297 | had been modified, without actually modifying the files.
|
|---|
| 6298 |
|
|---|
| 6299 | Note that the options `-p' and `-v' allow you to obtain other
|
|---|
| 6300 | information about `make' or about the makefiles in use (*note Summary
|
|---|
| 6301 | of Options: Options Summary.).
|
|---|
| 6302 |
|
|---|
| 6303 |
|
|---|
| 6304 | File: make.info, Node: Avoiding Compilation, Next: Overriding, Prev: Instead of Execution, Up: Running
|
|---|
| 6305 |
|
|---|
| 6306 | 9.4 Avoiding Recompilation of Some Files
|
|---|
| 6307 | ========================================
|
|---|
| 6308 |
|
|---|
| 6309 | Sometimes you may have changed a source file but you do not want to
|
|---|
| 6310 | recompile all the files that depend on it. For example, suppose you add
|
|---|
| 6311 | a macro or a declaration to a header file that many other files depend
|
|---|
| 6312 | on. Being conservative, `make' assumes that any change in the header
|
|---|
| 6313 | file requires recompilation of all dependent files, but you know that
|
|---|
| 6314 | they do not need to be recompiled and you would rather not waste the
|
|---|
| 6315 | time waiting for them to compile.
|
|---|
| 6316 |
|
|---|
| 6317 | If you anticipate the problem before changing the header file, you
|
|---|
| 6318 | can use the `-t' flag. This flag tells `make' not to run the commands
|
|---|
| 6319 | in the rules, but rather to mark the target up to date by changing its
|
|---|
| 6320 | last-modification date. You would follow this procedure:
|
|---|
| 6321 |
|
|---|
| 6322 | 1. Use the command `make' to recompile the source files that really
|
|---|
| 6323 | need recompilation, ensuring that the object files are up-to-date
|
|---|
| 6324 | before you begin.
|
|---|
| 6325 |
|
|---|
| 6326 | 2. Make the changes in the header files.
|
|---|
| 6327 |
|
|---|
| 6328 | 3. Use the command `make -t' to mark all the object files as up to
|
|---|
| 6329 | date. The next time you run `make', the changes in the header
|
|---|
| 6330 | files will not cause any recompilation.
|
|---|
| 6331 |
|
|---|
| 6332 | If you have already changed the header file at a time when some files
|
|---|
| 6333 | do need recompilation, it is too late to do this. Instead, you can use
|
|---|
| 6334 | the `-o FILE' flag, which marks a specified file as "old" (*note
|
|---|
| 6335 | Summary of Options: Options Summary.). This means that the file itself
|
|---|
| 6336 | will not be remade, and nothing else will be remade on its account.
|
|---|
| 6337 | Follow this procedure:
|
|---|
| 6338 |
|
|---|
| 6339 | 1. Recompile the source files that need compilation for reasons
|
|---|
| 6340 | independent of the particular header file, with `make -o
|
|---|
| 6341 | HEADERFILE'. If several header files are involved, use a separate
|
|---|
| 6342 | `-o' option for each header file.
|
|---|
| 6343 |
|
|---|
| 6344 | 2. Touch all the object files with `make -t'.
|
|---|
| 6345 |
|
|---|
| 6346 |
|
|---|
| 6347 | File: make.info, Node: Overriding, Next: Testing, Prev: Avoiding Compilation, Up: Running
|
|---|
| 6348 |
|
|---|
| 6349 | 9.5 Overriding Variables
|
|---|
| 6350 | ========================
|
|---|
| 6351 |
|
|---|
| 6352 | An argument that contains `=' specifies the value of a variable: `V=X'
|
|---|
| 6353 | sets the value of the variable V to X. If you specify a value in this
|
|---|
| 6354 | way, all ordinary assignments of the same variable in the makefile are
|
|---|
| 6355 | ignored; we say they have been "overridden" by the command line
|
|---|
| 6356 | argument.
|
|---|
| 6357 |
|
|---|
| 6358 | The most common way to use this facility is to pass extra flags to
|
|---|
| 6359 | compilers. For example, in a properly written makefile, the variable
|
|---|
| 6360 | `CFLAGS' is included in each command that runs the C compiler, so a
|
|---|
| 6361 | file `foo.c' would be compiled something like this:
|
|---|
| 6362 |
|
|---|
| 6363 | cc -c $(CFLAGS) foo.c
|
|---|
| 6364 |
|
|---|
| 6365 | Thus, whatever value you set for `CFLAGS' affects each compilation
|
|---|
| 6366 | that occurs. The makefile probably specifies the usual value for
|
|---|
| 6367 | `CFLAGS', like this:
|
|---|
| 6368 |
|
|---|
| 6369 | CFLAGS=-g
|
|---|
| 6370 |
|
|---|
| 6371 | Each time you run `make', you can override this value if you wish.
|
|---|
| 6372 | For example, if you say `make CFLAGS='-g -O'', each C compilation will
|
|---|
| 6373 | be done with `cc -c -g -O'. (This also illustrates how you can use
|
|---|
| 6374 | quoting in the shell to enclose spaces and other special characters in
|
|---|
| 6375 | the value of a variable when you override it.)
|
|---|
| 6376 |
|
|---|
| 6377 | The variable `CFLAGS' is only one of many standard variables that
|
|---|
| 6378 | exist just so that you can change them this way. *Note Variables Used
|
|---|
| 6379 | by Implicit Rules: Implicit Variables, for a complete list.
|
|---|
| 6380 |
|
|---|
| 6381 | You can also program the makefile to look at additional variables of
|
|---|
| 6382 | your own, giving the user the ability to control other aspects of how
|
|---|
| 6383 | the makefile works by changing the variables.
|
|---|
| 6384 |
|
|---|
| 6385 | When you override a variable with a command argument, you can define
|
|---|
| 6386 | either a recursively-expanded variable or a simply-expanded variable.
|
|---|
| 6387 | The examples shown above make a recursively-expanded variable; to make a
|
|---|
| 6388 | simply-expanded variable, write `:=' instead of `='. But, unless you
|
|---|
| 6389 | want to include a variable reference or function call in the _value_
|
|---|
| 6390 | that you specify, it makes no difference which kind of variable you
|
|---|
| 6391 | create.
|
|---|
| 6392 |
|
|---|
| 6393 | There is one way that the makefile can change a variable that you
|
|---|
| 6394 | have overridden. This is to use the `override' directive, which is a
|
|---|
| 6395 | line that looks like this: `override VARIABLE = VALUE' (*note The
|
|---|
| 6396 | `override' Directive: Override Directive.).
|
|---|
| 6397 |
|
|---|
| 6398 |
|
|---|
| 6399 | File: make.info, Node: Testing, Next: Options Summary, Prev: Overriding, Up: Running
|
|---|
| 6400 |
|
|---|
| 6401 | 9.6 Testing the Compilation of a Program
|
|---|
| 6402 | ========================================
|
|---|
| 6403 |
|
|---|
| 6404 | Normally, when an error happens in executing a shell command, `make'
|
|---|
| 6405 | gives up immediately, returning a nonzero status. No further commands
|
|---|
| 6406 | are executed for any target. The error implies that the goal cannot be
|
|---|
| 6407 | correctly remade, and `make' reports this as soon as it knows.
|
|---|
| 6408 |
|
|---|
| 6409 | When you are compiling a program that you have just changed, this is
|
|---|
| 6410 | not what you want. Instead, you would rather that `make' try compiling
|
|---|
| 6411 | every file that can be tried, to show you as many compilation errors as
|
|---|
| 6412 | possible.
|
|---|
| 6413 |
|
|---|
| 6414 | On these occasions, you should use the `-k' or `--keep-going' flag.
|
|---|
| 6415 | This tells `make' to continue to consider the other prerequisites of
|
|---|
| 6416 | the pending targets, remaking them if necessary, before it gives up and
|
|---|
| 6417 | returns nonzero status. For example, after an error in compiling one
|
|---|
| 6418 | object file, `make -k' will continue compiling other object files even
|
|---|
| 6419 | though it already knows that linking them will be impossible. In
|
|---|
| 6420 | addition to continuing after failed shell commands, `make -k' will
|
|---|
| 6421 | continue as much as possible after discovering that it does not know
|
|---|
| 6422 | how to make a target or prerequisite file. This will always cause an
|
|---|
| 6423 | error message, but without `-k', it is a fatal error (*note Summary of
|
|---|
| 6424 | Options: Options Summary.).
|
|---|
| 6425 |
|
|---|
| 6426 | The usual behavior of `make' assumes that your purpose is to get the
|
|---|
| 6427 | goals up to date; once `make' learns that this is impossible, it might
|
|---|
| 6428 | as well report the failure immediately. The `-k' flag says that the
|
|---|
| 6429 | real purpose is to test as much as possible of the changes made in the
|
|---|
| 6430 | program, perhaps to find several independent problems so that you can
|
|---|
| 6431 | correct them all before the next attempt to compile. This is why Emacs'
|
|---|
| 6432 | `M-x compile' command passes the `-k' flag by default.
|
|---|
| 6433 |
|
|---|
| 6434 |
|
|---|
| 6435 | File: make.info, Node: Options Summary, Prev: Testing, Up: Running
|
|---|
| 6436 |
|
|---|
| 6437 | 9.7 Summary of Options
|
|---|
| 6438 | ======================
|
|---|
| 6439 |
|
|---|
| 6440 | Here is a table of all the options `make' understands:
|
|---|
| 6441 |
|
|---|
| 6442 | `-b'
|
|---|
| 6443 | `-m'
|
|---|
| 6444 | These options are ignored for compatibility with other versions of
|
|---|
| 6445 | `make'.
|
|---|
| 6446 |
|
|---|
| 6447 | `-B'
|
|---|
| 6448 | `--always-make'
|
|---|
| 6449 | Consider all targets out-of-date. GNU `make' proceeds to consider
|
|---|
| 6450 | targets and their prerequisites using the normal algorithms;
|
|---|
| 6451 | however, all targets so considered are always remade regardless of
|
|---|
| 6452 | the status of their prerequisites. To avoid infinite recursion, if
|
|---|
| 6453 | `MAKE_RESTARTS' (*note Other Special Variables: Special
|
|---|
| 6454 | Variables.) is set to a number greater than 0 this option is
|
|---|
| 6455 | disabled when considering whether to remake makefiles (*note How
|
|---|
| 6456 | Makefiles Are Remade: Remaking Makefiles.).
|
|---|
| 6457 |
|
|---|
| 6458 | `-C DIR'
|
|---|
| 6459 | `--directory=DIR'
|
|---|
| 6460 | Change to directory DIR before reading the makefiles. If multiple
|
|---|
| 6461 | `-C' options are specified, each is interpreted relative to the
|
|---|
| 6462 | previous one: `-C / -C etc' is equivalent to `-C /etc'. This is
|
|---|
| 6463 | typically used with recursive invocations of `make' (*note
|
|---|
| 6464 | Recursive Use of `make': Recursion.).
|
|---|
| 6465 |
|
|---|
| 6466 | `-d'
|
|---|
| 6467 | Print debugging information in addition to normal processing. The
|
|---|
| 6468 | debugging information says which files are being considered for
|
|---|
| 6469 | remaking, which file-times are being compared and with what
|
|---|
| 6470 | results, which files actually need to be remade, which implicit
|
|---|
| 6471 | rules are considered and which are applied--everything interesting
|
|---|
| 6472 | about how `make' decides what to do. The `-d' option is
|
|---|
| 6473 | equivalent to `--debug=a' (see below).
|
|---|
| 6474 |
|
|---|
| 6475 | `--debug[=OPTIONS]'
|
|---|
| 6476 | Print debugging information in addition to normal processing.
|
|---|
| 6477 | Various levels and types of output can be chosen. With no
|
|---|
| 6478 | arguments, print the "basic" level of debugging. Possible
|
|---|
| 6479 | arguments are below; only the first character is considered, and
|
|---|
| 6480 | values must be comma- or space-separated.
|
|---|
| 6481 |
|
|---|
| 6482 | `a (all)'
|
|---|
| 6483 | All types of debugging output are enabled. This is
|
|---|
| 6484 | equivalent to using `-d'.
|
|---|
| 6485 |
|
|---|
| 6486 | `b (basic)'
|
|---|
| 6487 | Basic debugging prints each target that was found to be
|
|---|
| 6488 | out-of-date, and whether the build was successful or not.
|
|---|
| 6489 |
|
|---|
| 6490 | `v (verbose)'
|
|---|
| 6491 | A level above `basic'; includes messages about which
|
|---|
| 6492 | makefiles were parsed, prerequisites that did not need to be
|
|---|
| 6493 | rebuilt, etc. This option also enables `basic' messages.
|
|---|
| 6494 |
|
|---|
| 6495 | `i (implicit)'
|
|---|
| 6496 | Prints messages describing the implicit rule searches for
|
|---|
| 6497 | each target. This option also enables `basic' messages.
|
|---|
| 6498 |
|
|---|
| 6499 | `j (jobs)'
|
|---|
| 6500 | Prints messages giving details on the invocation of specific
|
|---|
| 6501 | subcommands.
|
|---|
| 6502 |
|
|---|
| 6503 | `m (makefile)'
|
|---|
| 6504 | By default, the above messages are not enabled while trying
|
|---|
| 6505 | to remake the makefiles. This option enables messages while
|
|---|
| 6506 | rebuilding makefiles, too. Note that the `all' option does
|
|---|
| 6507 | enable this option. This option also enables `basic'
|
|---|
| 6508 | messages.
|
|---|
| 6509 |
|
|---|
| 6510 | `-e'
|
|---|
| 6511 | `--environment-overrides'
|
|---|
| 6512 | Give variables taken from the environment precedence over
|
|---|
| 6513 | variables from makefiles. *Note Variables from the Environment:
|
|---|
| 6514 | Environment.
|
|---|
| 6515 |
|
|---|
| 6516 | `-f FILE'
|
|---|
| 6517 | `--file=FILE'
|
|---|
| 6518 | `--makefile=FILE'
|
|---|
| 6519 | Read the file named FILE as a makefile. *Note Writing Makefiles:
|
|---|
| 6520 | Makefiles.
|
|---|
| 6521 |
|
|---|
| 6522 | `-h'
|
|---|
| 6523 | `--help'
|
|---|
| 6524 | Remind you of the options that `make' understands and then exit.
|
|---|
| 6525 |
|
|---|
| 6526 | `-i'
|
|---|
| 6527 | `--ignore-errors'
|
|---|
| 6528 | Ignore all errors in commands executed to remake files. *Note
|
|---|
| 6529 | Errors in Commands: Errors.
|
|---|
| 6530 |
|
|---|
| 6531 | `-I DIR'
|
|---|
| 6532 | `--include-dir=DIR'
|
|---|
| 6533 | Specifies a directory DIR to search for included makefiles. *Note
|
|---|
| 6534 | Including Other Makefiles: Include. If several `-I' options are
|
|---|
| 6535 | used to specify several directories, the directories are searched
|
|---|
| 6536 | in the order specified.
|
|---|
| 6537 |
|
|---|
| 6538 | `-j [JOBS]'
|
|---|
| 6539 | `--jobs[=JOBS]'
|
|---|
| 6540 | Specifies the number of jobs (commands) to run simultaneously.
|
|---|
| 6541 | With no argument, `make' runs as many jobs simultaneously as
|
|---|
| 6542 | possible. If there is more than one `-j' option, the last one is
|
|---|
| 6543 | effective. *Note Parallel Execution: Parallel, for more
|
|---|
| 6544 | information on how commands are run. Note that this option is
|
|---|
| 6545 | ignored on MS-DOS.
|
|---|
| 6546 |
|
|---|
| 6547 | `-k'
|
|---|
| 6548 | `--keep-going'
|
|---|
| 6549 | Continue as much as possible after an error. While the target that
|
|---|
| 6550 | failed, and those that depend on it, cannot be remade, the other
|
|---|
| 6551 | prerequisites of these targets can be processed all the same.
|
|---|
| 6552 | *Note Testing the Compilation of a Program: Testing.
|
|---|
| 6553 |
|
|---|
| 6554 | `-l [LOAD]'
|
|---|
| 6555 | `--load-average[=LOAD]'
|
|---|
| 6556 | `--max-load[=LOAD]'
|
|---|
| 6557 | Specifies that no new jobs (commands) should be started if there
|
|---|
| 6558 | are other jobs running and the load average is at least LOAD (a
|
|---|
| 6559 | floating-point number). With no argument, removes a previous load
|
|---|
| 6560 | limit. *Note Parallel Execution: Parallel.
|
|---|
| 6561 |
|
|---|
| 6562 | `-L'
|
|---|
| 6563 | `--check-symlink-times'
|
|---|
| 6564 | On systems that support symbolic links, this option causes `make'
|
|---|
| 6565 | to consider the timestamps on any symbolic links in addition to the
|
|---|
| 6566 | timestamp on the file referenced by those links. When this option
|
|---|
| 6567 | is provided, the most recent timestamp among the file and the
|
|---|
| 6568 | symbolic links is taken as the modification time for this target
|
|---|
| 6569 | file.
|
|---|
| 6570 |
|
|---|
| 6571 | `-n'
|
|---|
| 6572 | `--just-print'
|
|---|
| 6573 | `--dry-run'
|
|---|
| 6574 | `--recon'
|
|---|
| 6575 | Print the commands that would be executed, but do not execute them.
|
|---|
| 6576 | *Note Instead of Executing the Commands: Instead of Execution.
|
|---|
| 6577 |
|
|---|
| 6578 | `-o FILE'
|
|---|
| 6579 | `--old-file=FILE'
|
|---|
| 6580 | `--assume-old=FILE'
|
|---|
| 6581 | Do not remake the file FILE even if it is older than its
|
|---|
| 6582 | prerequisites, and do not remake anything on account of changes in
|
|---|
| 6583 | FILE. Essentially the file is treated as very old and its rules
|
|---|
| 6584 | are ignored. *Note Avoiding Recompilation of Some Files: Avoiding
|
|---|
| 6585 | Compilation.
|
|---|
| 6586 |
|
|---|
| 6587 | `-p'
|
|---|
| 6588 | `--print-data-base'
|
|---|
| 6589 | Print the data base (rules and variable values) that results from
|
|---|
| 6590 | reading the makefiles; then execute as usual or as otherwise
|
|---|
| 6591 | specified. This also prints the version information given by the
|
|---|
| 6592 | `-v' switch (see below). To print the data base without trying to
|
|---|
| 6593 | remake any files, use `make -qp'. To print the data base of
|
|---|
| 6594 | predefined rules and variables, use `make -p -f /dev/null'. The
|
|---|
| 6595 | data base output contains filename and linenumber information for
|
|---|
| 6596 | command and variable definitions, so it can be a useful debugging
|
|---|
| 6597 | tool in complex environments.
|
|---|
| 6598 |
|
|---|
| 6599 | `-q'
|
|---|
| 6600 | `--question'
|
|---|
| 6601 | "Question mode". Do not run any commands, or print anything; just
|
|---|
| 6602 | return an exit status that is zero if the specified targets are
|
|---|
| 6603 | already up to date, one if any remaking is required, or two if an
|
|---|
| 6604 | error is encountered. *Note Instead of Executing the Commands:
|
|---|
| 6605 | Instead of Execution.
|
|---|
| 6606 |
|
|---|
| 6607 | `-r'
|
|---|
| 6608 | `--no-builtin-rules'
|
|---|
| 6609 | Eliminate use of the built-in implicit rules (*note Using Implicit
|
|---|
| 6610 | Rules: Implicit Rules.). You can still define your own by writing
|
|---|
| 6611 | pattern rules (*note Defining and Redefining Pattern Rules:
|
|---|
| 6612 | Pattern Rules.). The `-r' option also clears out the default list
|
|---|
| 6613 | of suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
|
|---|
| 6614 | Suffix Rules.). But you can still define your own suffixes with a
|
|---|
| 6615 | rule for `.SUFFIXES', and then define your own suffix rules. Note
|
|---|
| 6616 | that only _rules_ are affected by the `-r' option; default
|
|---|
| 6617 | variables remain in effect (*note Variables Used by Implicit
|
|---|
| 6618 | Rules: Implicit Variables.); see the `-R' option below.
|
|---|
| 6619 |
|
|---|
| 6620 | `-R'
|
|---|
| 6621 | `--no-builtin-variables'
|
|---|
| 6622 | Eliminate use of the built-in rule-specific variables (*note
|
|---|
| 6623 | Variables Used by Implicit Rules: Implicit Variables.). You can
|
|---|
| 6624 | still define your own, of course. The `-R' option also
|
|---|
| 6625 | automatically enables the `-r' option (see above), since it
|
|---|
| 6626 | doesn't make sense to have implicit rules without any definitions
|
|---|
| 6627 | for the variables that they use.
|
|---|
| 6628 |
|
|---|
| 6629 | `-s'
|
|---|
| 6630 | `--silent'
|
|---|
| 6631 | `--quiet'
|
|---|
| 6632 | Silent operation; do not print the commands as they are executed.
|
|---|
| 6633 | *Note Command Echoing: Echoing.
|
|---|
| 6634 |
|
|---|
| 6635 | `-S'
|
|---|
| 6636 | `--no-keep-going'
|
|---|
| 6637 | `--stop'
|
|---|
| 6638 | Cancel the effect of the `-k' option. This is never necessary
|
|---|
| 6639 | except in a recursive `make' where `-k' might be inherited from
|
|---|
| 6640 | the top-level `make' via `MAKEFLAGS' (*note Recursive Use of
|
|---|
| 6641 | `make': Recursion.) or if you set `-k' in `MAKEFLAGS' in your
|
|---|
| 6642 | environment.
|
|---|
| 6643 |
|
|---|
| 6644 | `-t'
|
|---|
| 6645 | `--touch'
|
|---|
| 6646 | Touch files (mark them up to date without really changing them)
|
|---|
| 6647 | instead of running their commands. This is used to pretend that
|
|---|
| 6648 | the commands were done, in order to fool future invocations of
|
|---|
| 6649 | `make'. *Note Instead of Executing the Commands: Instead of
|
|---|
| 6650 | Execution.
|
|---|
| 6651 |
|
|---|
| 6652 | `-v'
|
|---|
| 6653 | `--version'
|
|---|
| 6654 | Print the version of the `make' program plus a copyright, a list
|
|---|
| 6655 | of authors, and a notice that there is no warranty; then exit.
|
|---|
| 6656 |
|
|---|
| 6657 | `-w'
|
|---|
| 6658 | `--print-directory'
|
|---|
| 6659 | Print a message containing the working directory both before and
|
|---|
| 6660 | after executing the makefile. This may be useful for tracking
|
|---|
| 6661 | down errors from complicated nests of recursive `make' commands.
|
|---|
| 6662 | *Note Recursive Use of `make': Recursion. (In practice, you
|
|---|
| 6663 | rarely need to specify this option since `make' does it for you;
|
|---|
| 6664 | see *Note The `--print-directory' Option: -w Option.)
|
|---|
| 6665 |
|
|---|
| 6666 | `--no-print-directory'
|
|---|
| 6667 | Disable printing of the working directory under `-w'. This option
|
|---|
| 6668 | is useful when `-w' is turned on automatically, but you do not
|
|---|
| 6669 | want to see the extra messages. *Note The `--print-directory'
|
|---|
| 6670 | Option: -w Option.
|
|---|
| 6671 |
|
|---|
| 6672 | `-W FILE'
|
|---|
| 6673 | `--what-if=FILE'
|
|---|
| 6674 | `--new-file=FILE'
|
|---|
| 6675 | `--assume-new=FILE'
|
|---|
| 6676 | Pretend that the target FILE has just been modified. When used
|
|---|
| 6677 | with the `-n' flag, this shows you what would happen if you were
|
|---|
| 6678 | to modify that file. Without `-n', it is almost the same as
|
|---|
| 6679 | running a `touch' command on the given file before running `make',
|
|---|
| 6680 | except that the modification time is changed only in the
|
|---|
| 6681 | imagination of `make'. *Note Instead of Executing the Commands:
|
|---|
| 6682 | Instead of Execution.
|
|---|
| 6683 |
|
|---|
| 6684 | `--warn-undefined-variables'
|
|---|
| 6685 | Issue a warning message whenever `make' sees a reference to an
|
|---|
| 6686 | undefined variable. This can be helpful when you are trying to
|
|---|
| 6687 | debug makefiles which use variables in complex ways.
|
|---|
| 6688 |
|
|---|
| 6689 |
|
|---|
| 6690 | File: make.info, Node: Implicit Rules, Next: Archives, Prev: Running, Up: Top
|
|---|
| 6691 |
|
|---|
| 6692 | 10 Using Implicit Rules
|
|---|
| 6693 | ***********************
|
|---|
| 6694 |
|
|---|
| 6695 | Certain standard ways of remaking target files are used very often. For
|
|---|
| 6696 | example, one customary way to make an object file is from a C source
|
|---|
| 6697 | file using the C compiler, `cc'.
|
|---|
| 6698 |
|
|---|
| 6699 | "Implicit rules" tell `make' how to use customary techniques so that
|
|---|
| 6700 | you do not have to specify them in detail when you want to use them.
|
|---|
| 6701 | For example, there is an implicit rule for C compilation. File names
|
|---|
| 6702 | determine which implicit rules are run. For example, C compilation
|
|---|
| 6703 | typically takes a `.c' file and makes a `.o' file. So `make' applies
|
|---|
| 6704 | the implicit rule for C compilation when it sees this combination of
|
|---|
| 6705 | file name endings.
|
|---|
| 6706 |
|
|---|
| 6707 | A chain of implicit rules can apply in sequence; for example, `make'
|
|---|
| 6708 | will remake a `.o' file from a `.y' file by way of a `.c' file.
|
|---|
| 6709 |
|
|---|
| 6710 | The built-in implicit rules use several variables in their commands
|
|---|
| 6711 | so that, by changing the values of the variables, you can change the
|
|---|
| 6712 | way the implicit rule works. For example, the variable `CFLAGS'
|
|---|
| 6713 | controls the flags given to the C compiler by the implicit rule for C
|
|---|
| 6714 | compilation.
|
|---|
| 6715 |
|
|---|
| 6716 | You can define your own implicit rules by writing "pattern rules".
|
|---|
| 6717 |
|
|---|
| 6718 | "Suffix rules" are a more limited way to define implicit rules.
|
|---|
| 6719 | Pattern rules are more general and clearer, but suffix rules are
|
|---|
| 6720 | retained for compatibility.
|
|---|
| 6721 |
|
|---|
| 6722 | * Menu:
|
|---|
| 6723 |
|
|---|
| 6724 | * Using Implicit:: How to use an existing implicit rule
|
|---|
| 6725 | to get the commands for updating a file.
|
|---|
| 6726 | * Catalogue of Rules:: A list of built-in implicit rules.
|
|---|
| 6727 | * Implicit Variables:: How to change what predefined rules do.
|
|---|
| 6728 | * Chained Rules:: How to use a chain of implicit rules.
|
|---|
| 6729 | * Pattern Rules:: How to define new implicit rules.
|
|---|
| 6730 | * Last Resort:: How to define commands for rules which
|
|---|
| 6731 | cannot find any.
|
|---|
| 6732 | * Suffix Rules:: The old-fashioned style of implicit rule.
|
|---|
| 6733 | * Implicit Rule Search:: The precise algorithm for applying
|
|---|
| 6734 | implicit rules.
|
|---|
| 6735 |
|
|---|
| 6736 |
|
|---|
| 6737 | File: make.info, Node: Using Implicit, Next: Catalogue of Rules, Prev: Implicit Rules, Up: Implicit Rules
|
|---|
| 6738 |
|
|---|
| 6739 | 10.1 Using Implicit Rules
|
|---|
| 6740 | =========================
|
|---|
| 6741 |
|
|---|
| 6742 | To allow `make' to find a customary method for updating a target file,
|
|---|
| 6743 | all you have to do is refrain from specifying commands yourself. Either
|
|---|
| 6744 | write a rule with no command lines, or don't write a rule at all. Then
|
|---|
| 6745 | `make' will figure out which implicit rule to use based on which kind
|
|---|
| 6746 | of source file exists or can be made.
|
|---|
| 6747 |
|
|---|
| 6748 | For example, suppose the makefile looks like this:
|
|---|
| 6749 |
|
|---|
| 6750 | foo : foo.o bar.o
|
|---|
| 6751 | cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
|
|---|
| 6752 |
|
|---|
| 6753 | Because you mention `foo.o' but do not give a rule for it, `make' will
|
|---|
| 6754 | automatically look for an implicit rule that tells how to update it.
|
|---|
| 6755 | This happens whether or not the file `foo.o' currently exists.
|
|---|
| 6756 |
|
|---|
| 6757 | If an implicit rule is found, it can supply both commands and one or
|
|---|
| 6758 | more prerequisites (the source files). You would want to write a rule
|
|---|
| 6759 | for `foo.o' with no command lines if you need to specify additional
|
|---|
| 6760 | prerequisites, such as header files, that the implicit rule cannot
|
|---|
| 6761 | supply.
|
|---|
| 6762 |
|
|---|
| 6763 | Each implicit rule has a target pattern and prerequisite patterns.
|
|---|
| 6764 | There may be many implicit rules with the same target pattern. For
|
|---|
| 6765 | example, numerous rules make `.o' files: one, from a `.c' file with the
|
|---|
| 6766 | C compiler; another, from a `.p' file with the Pascal compiler; and so
|
|---|
| 6767 | on. The rule that actually applies is the one whose prerequisites
|
|---|
| 6768 | exist or can be made. So, if you have a file `foo.c', `make' will run
|
|---|
| 6769 | the C compiler; otherwise, if you have a file `foo.p', `make' will run
|
|---|
| 6770 | the Pascal compiler; and so on.
|
|---|
| 6771 |
|
|---|
| 6772 | Of course, when you write the makefile, you know which implicit rule
|
|---|
| 6773 | you want `make' to use, and you know it will choose that one because you
|
|---|
| 6774 | know which possible prerequisite files are supposed to exist. *Note
|
|---|
| 6775 | Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all
|
|---|
| 6776 | the predefined implicit rules.
|
|---|
| 6777 |
|
|---|
| 6778 | Above, we said an implicit rule applies if the required
|
|---|
| 6779 | prerequisites "exist or can be made". A file "can be made" if it is
|
|---|
| 6780 | mentioned explicitly in the makefile as a target or a prerequisite, or
|
|---|
| 6781 | if an implicit rule can be recursively found for how to make it. When
|
|---|
| 6782 | an implicit prerequisite is the result of another implicit rule, we say
|
|---|
| 6783 | that "chaining" is occurring. *Note Chains of Implicit Rules: Chained
|
|---|
| 6784 | Rules.
|
|---|
| 6785 |
|
|---|
| 6786 | In general, `make' searches for an implicit rule for each target, and
|
|---|
| 6787 | for each double-colon rule, that has no commands. A file that is
|
|---|
| 6788 | mentioned only as a prerequisite is considered a target whose rule
|
|---|
| 6789 | specifies nothing, so implicit rule search happens for it. *Note
|
|---|
| 6790 | Implicit Rule Search Algorithm: Implicit Rule Search, for the details
|
|---|
| 6791 | of how the search is done.
|
|---|
| 6792 |
|
|---|
| 6793 | Note that explicit prerequisites do not influence implicit rule
|
|---|
| 6794 | search. For example, consider this explicit rule:
|
|---|
| 6795 |
|
|---|
| 6796 | foo.o: foo.p
|
|---|
| 6797 |
|
|---|
| 6798 | The prerequisite on `foo.p' does not necessarily mean that `make' will
|
|---|
| 6799 | remake `foo.o' according to the implicit rule to make an object file, a
|
|---|
| 6800 | `.o' file, from a Pascal source file, a `.p' file. For example, if
|
|---|
| 6801 | `foo.c' also exists, the implicit rule to make an object file from a C
|
|---|
| 6802 | source file is used instead, because it appears before the Pascal rule
|
|---|
| 6803 | in the list of predefined implicit rules (*note Catalogue of Implicit
|
|---|
| 6804 | Rules: Catalogue of Rules.).
|
|---|
| 6805 |
|
|---|
| 6806 | If you do not want an implicit rule to be used for a target that has
|
|---|
| 6807 | no commands, you can give that target empty commands by writing a
|
|---|
| 6808 | semicolon (*note Defining Empty Commands: Empty Commands.).
|
|---|
| 6809 |
|
|---|
| 6810 |
|
|---|
| 6811 | File: make.info, Node: Catalogue of Rules, Next: Implicit Variables, Prev: Using Implicit, Up: Implicit Rules
|
|---|
| 6812 |
|
|---|
| 6813 | 10.2 Catalogue of Implicit Rules
|
|---|
| 6814 | ================================
|
|---|
| 6815 |
|
|---|
| 6816 | Here is a catalogue of predefined implicit rules which are always
|
|---|
| 6817 | available unless the makefile explicitly overrides or cancels them.
|
|---|
| 6818 | *Note Canceling Implicit Rules: Canceling Rules, for information on
|
|---|
| 6819 | canceling or overriding an implicit rule. The `-r' or
|
|---|
| 6820 | `--no-builtin-rules' option cancels all predefined rules.
|
|---|
| 6821 |
|
|---|
| 6822 | This manual only documents the default rules available on POSIX-based
|
|---|
| 6823 | operating systems. Other operating systems, such as VMS, Windows,
|
|---|
| 6824 | OS/2, etc. may have different sets of default rules. To see the full
|
|---|
| 6825 | list of default rules and variables available in your version of GNU
|
|---|
| 6826 | `make', run `make -p' in a directory with no makefile.
|
|---|
| 6827 |
|
|---|
| 6828 | Not all of these rules will always be defined, even when the `-r'
|
|---|
| 6829 | option is not given. Many of the predefined implicit rules are
|
|---|
| 6830 | implemented in `make' as suffix rules, so which ones will be defined
|
|---|
| 6831 | depends on the "suffix list" (the list of prerequisites of the special
|
|---|
| 6832 | target `.SUFFIXES'). The default suffix list is: `.out', `.a', `.ln',
|
|---|
| 6833 | `.o', `.c', `.cc', `.C', `.cpp', `.p', `.f', `.F', `.r', `.y', `.l',
|
|---|
| 6834 | `.s', `.S', `.mod', `.sym', `.def', `.h', `.info', `.dvi', `.tex',
|
|---|
| 6835 | `.texinfo', `.texi', `.txinfo', `.w', `.ch' `.web', `.sh', `.elc',
|
|---|
| 6836 | `.el'. All of the implicit rules described below whose prerequisites
|
|---|
| 6837 | have one of these suffixes are actually suffix rules. If you modify
|
|---|
| 6838 | the suffix list, the only predefined suffix rules in effect will be
|
|---|
| 6839 | those named by one or two of the suffixes that are on the list you
|
|---|
| 6840 | specify; rules whose suffixes fail to be on the list are disabled.
|
|---|
| 6841 | *Note Old-Fashioned Suffix Rules: Suffix Rules, for full details on
|
|---|
| 6842 | suffix rules.
|
|---|
| 6843 |
|
|---|
| 6844 | Compiling C programs
|
|---|
| 6845 | `N.o' is made automatically from `N.c' with a command of the form
|
|---|
| 6846 | `$(CC) -c $(CPPFLAGS) $(CFLAGS)'.
|
|---|
| 6847 |
|
|---|
| 6848 | Compiling C++ programs
|
|---|
| 6849 | `N.o' is made automatically from `N.cc', `N.cpp', or `N.C' with a
|
|---|
| 6850 | command of the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'. We
|
|---|
| 6851 | encourage you to use the suffix `.cc' for C++ source files instead
|
|---|
| 6852 | of `.C'.
|
|---|
| 6853 |
|
|---|
| 6854 | Compiling Pascal programs
|
|---|
| 6855 | `N.o' is made automatically from `N.p' with the command `$(PC) -c
|
|---|
| 6856 | $(PFLAGS)'.
|
|---|
| 6857 |
|
|---|
| 6858 | Compiling Fortran and Ratfor programs
|
|---|
| 6859 | `N.o' is made automatically from `N.r', `N.F' or `N.f' by running
|
|---|
| 6860 | the Fortran compiler. The precise command used is as follows:
|
|---|
| 6861 |
|
|---|
| 6862 | `.f'
|
|---|
| 6863 | `$(FC) -c $(FFLAGS)'.
|
|---|
| 6864 |
|
|---|
| 6865 | `.F'
|
|---|
| 6866 | `$(FC) -c $(FFLAGS) $(CPPFLAGS)'.
|
|---|
| 6867 |
|
|---|
| 6868 | `.r'
|
|---|
| 6869 | `$(FC) -c $(FFLAGS) $(RFLAGS)'.
|
|---|
| 6870 |
|
|---|
| 6871 | Preprocessing Fortran and Ratfor programs
|
|---|
| 6872 | `N.f' is made automatically from `N.r' or `N.F'. This rule runs
|
|---|
| 6873 | just the preprocessor to convert a Ratfor or preprocessable
|
|---|
| 6874 | Fortran program into a strict Fortran program. The precise
|
|---|
| 6875 | command used is as follows:
|
|---|
| 6876 |
|
|---|
| 6877 | `.F'
|
|---|
| 6878 | `$(FC) -F $(CPPFLAGS) $(FFLAGS)'.
|
|---|
| 6879 |
|
|---|
| 6880 | `.r'
|
|---|
| 6881 | `$(FC) -F $(FFLAGS) $(RFLAGS)'.
|
|---|
| 6882 |
|
|---|
| 6883 | Compiling Modula-2 programs
|
|---|
| 6884 | `N.sym' is made from `N.def' with a command of the form `$(M2C)
|
|---|
| 6885 | $(M2FLAGS) $(DEFFLAGS)'. `N.o' is made from `N.mod'; the form is:
|
|---|
| 6886 | `$(M2C) $(M2FLAGS) $(MODFLAGS)'.
|
|---|
| 6887 |
|
|---|
| 6888 | Assembling and preprocessing assembler programs
|
|---|
| 6889 | `N.o' is made automatically from `N.s' by running the assembler,
|
|---|
| 6890 | `as'. The precise command is `$(AS) $(ASFLAGS)'.
|
|---|
| 6891 |
|
|---|
| 6892 | `N.s' is made automatically from `N.S' by running the C
|
|---|
| 6893 | preprocessor, `cpp'. The precise command is `$(CPP) $(CPPFLAGS)'.
|
|---|
| 6894 |
|
|---|
| 6895 | Linking a single object file
|
|---|
| 6896 | `N' is made automatically from `N.o' by running the linker
|
|---|
| 6897 | (usually called `ld') via the C compiler. The precise command
|
|---|
| 6898 | used is `$(CC) $(LDFLAGS) N.o $(LOADLIBES) $(LDLIBS)'.
|
|---|
| 6899 |
|
|---|
| 6900 | This rule does the right thing for a simple program with only one
|
|---|
| 6901 | source file. It will also do the right thing if there are multiple
|
|---|
| 6902 | object files (presumably coming from various other source files),
|
|---|
| 6903 | one of which has a name matching that of the executable file.
|
|---|
| 6904 | Thus,
|
|---|
| 6905 |
|
|---|
| 6906 | x: y.o z.o
|
|---|
| 6907 |
|
|---|
| 6908 | when `x.c', `y.c' and `z.c' all exist will execute:
|
|---|
| 6909 |
|
|---|
| 6910 | cc -c x.c -o x.o
|
|---|
| 6911 | cc -c y.c -o y.o
|
|---|
| 6912 | cc -c z.c -o z.o
|
|---|
| 6913 | cc x.o y.o z.o -o x
|
|---|
| 6914 | rm -f x.o
|
|---|
| 6915 | rm -f y.o
|
|---|
| 6916 | rm -f z.o
|
|---|
| 6917 |
|
|---|
| 6918 | In more complicated cases, such as when there is no object file
|
|---|
| 6919 | whose name derives from the executable file name, you must write
|
|---|
| 6920 | an explicit command for linking.
|
|---|
| 6921 |
|
|---|
| 6922 | Each kind of file automatically made into `.o' object files will
|
|---|
| 6923 | be automatically linked by using the compiler (`$(CC)', `$(FC)' or
|
|---|
| 6924 | `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files)
|
|---|
| 6925 | without the `-c' option. This could be done by using the `.o'
|
|---|
| 6926 | object files as intermediates, but it is faster to do the
|
|---|
| 6927 | compiling and linking in one step, so that's how it's done.
|
|---|
| 6928 |
|
|---|
| 6929 | Yacc for C programs
|
|---|
| 6930 | `N.c' is made automatically from `N.y' by running Yacc with the
|
|---|
| 6931 | command `$(YACC) $(YFLAGS)'.
|
|---|
| 6932 |
|
|---|
| 6933 | Lex for C programs
|
|---|
| 6934 | `N.c' is made automatically from `N.l' by running Lex. The actual
|
|---|
| 6935 | command is `$(LEX) $(LFLAGS)'.
|
|---|
| 6936 |
|
|---|
| 6937 | Lex for Ratfor programs
|
|---|
| 6938 | `N.r' is made automatically from `N.l' by running Lex. The actual
|
|---|
| 6939 | command is `$(LEX) $(LFLAGS)'.
|
|---|
| 6940 |
|
|---|
| 6941 | The convention of using the same suffix `.l' for all Lex files
|
|---|
| 6942 | regardless of whether they produce C code or Ratfor code makes it
|
|---|
| 6943 | impossible for `make' to determine automatically which of the two
|
|---|
| 6944 | languages you are using in any particular case. If `make' is
|
|---|
| 6945 | called upon to remake an object file from a `.l' file, it must
|
|---|
| 6946 | guess which compiler to use. It will guess the C compiler, because
|
|---|
| 6947 | that is more common. If you are using Ratfor, make sure `make'
|
|---|
| 6948 | knows this by mentioning `N.r' in the makefile. Or, if you are
|
|---|
| 6949 | using Ratfor exclusively, with no C files, remove `.c' from the
|
|---|
| 6950 | list of implicit rule suffixes with:
|
|---|
| 6951 |
|
|---|
| 6952 | .SUFFIXES:
|
|---|
| 6953 | .SUFFIXES: .o .r .f .l ...
|
|---|
| 6954 |
|
|---|
| 6955 | Making Lint Libraries from C, Yacc, or Lex programs
|
|---|
| 6956 | `N.ln' is made from `N.c' by running `lint'. The precise command
|
|---|
| 6957 | is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'. The same command is
|
|---|
| 6958 | used on the C code produced from `N.y' or `N.l'.
|
|---|
| 6959 |
|
|---|
| 6960 | TeX and Web
|
|---|
| 6961 | `N.dvi' is made from `N.tex' with the command `$(TEX)'. `N.tex'
|
|---|
| 6962 | is made from `N.web' with `$(WEAVE)', or from `N.w' (and from
|
|---|
| 6963 | `N.ch' if it exists or can be made) with `$(CWEAVE)'. `N.p' is
|
|---|
| 6964 | made from `N.web' with `$(TANGLE)' and `N.c' is made from `N.w'
|
|---|
| 6965 | (and from `N.ch' if it exists or can be made) with `$(CTANGLE)'.
|
|---|
| 6966 |
|
|---|
| 6967 | Texinfo and Info
|
|---|
| 6968 | `N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with
|
|---|
| 6969 | the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'. `N.info' is made from
|
|---|
| 6970 | `N.texinfo', `N.texi', or `N.txinfo', with the command
|
|---|
| 6971 | `$(MAKEINFO) $(MAKEINFO_FLAGS)'.
|
|---|
| 6972 |
|
|---|
| 6973 | RCS
|
|---|
| 6974 | Any file `N' is extracted if necessary from an RCS file named
|
|---|
| 6975 | either `N,v' or `RCS/N,v'. The precise command used is
|
|---|
| 6976 | `$(CO) $(COFLAGS)'. `N' will not be extracted from RCS if it
|
|---|
| 6977 | already exists, even if the RCS file is newer. The rules for RCS
|
|---|
| 6978 | are terminal (*note Match-Anything Pattern Rules: Match-Anything
|
|---|
| 6979 | Rules.), so RCS files cannot be generated from another source;
|
|---|
| 6980 | they must actually exist.
|
|---|
| 6981 |
|
|---|
| 6982 | SCCS
|
|---|
| 6983 | Any file `N' is extracted if necessary from an SCCS file named
|
|---|
| 6984 | either `s.N' or `SCCS/s.N'. The precise command used is
|
|---|
| 6985 | `$(GET) $(GFLAGS)'. The rules for SCCS are terminal (*note
|
|---|
| 6986 | Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS
|
|---|
| 6987 | files cannot be generated from another source; they must actually
|
|---|
| 6988 | exist.
|
|---|
| 6989 |
|
|---|
| 6990 | For the benefit of SCCS, a file `N' is copied from `N.sh' and made
|
|---|
| 6991 | executable (by everyone). This is for shell scripts that are
|
|---|
| 6992 | checked into SCCS. Since RCS preserves the execution permission
|
|---|
| 6993 | of a file, you do not need to use this feature with RCS.
|
|---|
| 6994 |
|
|---|
| 6995 | We recommend that you avoid using of SCCS. RCS is widely held to
|
|---|
| 6996 | be superior, and is also free. By choosing free software in place
|
|---|
| 6997 | of comparable (or inferior) proprietary software, you support the
|
|---|
| 6998 | free software movement.
|
|---|
| 6999 |
|
|---|
| 7000 | Usually, you want to change only the variables listed in the table
|
|---|
| 7001 | above, which are documented in the following section.
|
|---|
| 7002 |
|
|---|
| 7003 | However, the commands in built-in implicit rules actually use
|
|---|
| 7004 | variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose
|
|---|
| 7005 | values contain the commands listed above.
|
|---|
| 7006 |
|
|---|
| 7007 | `make' follows the convention that the rule to compile a `.X' source
|
|---|
| 7008 | file uses the variable `COMPILE.X'. Similarly, the rule to produce an
|
|---|
| 7009 | executable from a `.X' file uses `LINK.X'; and the rule to preprocess a
|
|---|
| 7010 | `.X' file uses `PREPROCESS.X'.
|
|---|
| 7011 |
|
|---|
| 7012 | Every rule that produces an object file uses the variable
|
|---|
| 7013 | `OUTPUT_OPTION'. `make' defines this variable either to contain `-o
|
|---|
| 7014 | $@', or to be empty, depending on a compile-time option. You need the
|
|---|
| 7015 | `-o' option to ensure that the output goes into the right file when the
|
|---|
| 7016 | source file is in a different directory, as when using `VPATH' (*note
|
|---|
| 7017 | Directory Search::). However, compilers on some systems do not accept
|
|---|
| 7018 | a `-o' switch for object files. If you use such a system, and use
|
|---|
| 7019 | `VPATH', some compilations will put their output in the wrong place. A
|
|---|
| 7020 | possible workaround for this problem is to give `OUTPUT_OPTION' the
|
|---|
| 7021 | value `; mv $*.o $@'.
|
|---|
| 7022 |
|
|---|
| 7023 |
|
|---|
| 7024 | File: make.info, Node: Implicit Variables, Next: Chained Rules, Prev: Catalogue of Rules, Up: Implicit Rules
|
|---|
| 7025 |
|
|---|
| 7026 | 10.3 Variables Used by Implicit Rules
|
|---|
| 7027 | =====================================
|
|---|
| 7028 |
|
|---|
| 7029 | The commands in built-in implicit rules make liberal use of certain
|
|---|
| 7030 | predefined variables. You can alter the values of these variables in
|
|---|
| 7031 | the makefile, with arguments to `make', or in the environment to alter
|
|---|
| 7032 | how the implicit rules work without redefining the rules themselves.
|
|---|
| 7033 | You can cancel all variables used by implicit rules with the `-R' or
|
|---|
| 7034 | `--no-builtin-variables' option.
|
|---|
| 7035 |
|
|---|
| 7036 | For example, the command used to compile a C source file actually
|
|---|
| 7037 | says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'. The default values of the
|
|---|
| 7038 | variables used are `cc' and nothing, resulting in the command `cc -c'.
|
|---|
| 7039 | By redefining `CC' to `ncc', you could cause `ncc' to be used for all C
|
|---|
| 7040 | compilations performed by the implicit rule. By redefining `CFLAGS' to
|
|---|
| 7041 | be `-g', you could pass the `-g' option to each compilation. _All_
|
|---|
| 7042 | implicit rules that do C compilation use `$(CC)' to get the program
|
|---|
| 7043 | name for the compiler and _all_ include `$(CFLAGS)' among the arguments
|
|---|
| 7044 | given to the compiler.
|
|---|
| 7045 |
|
|---|
| 7046 | The variables used in implicit rules fall into two classes: those
|
|---|
| 7047 | that are names of programs (like `CC') and those that contain arguments
|
|---|
| 7048 | for the programs (like `CFLAGS'). (The "name of a program" may also
|
|---|
| 7049 | contain some command arguments, but it must start with an actual
|
|---|
| 7050 | executable program name.) If a variable value contains more than one
|
|---|
| 7051 | argument, separate them with spaces.
|
|---|
| 7052 |
|
|---|
| 7053 | The following tables describe of some of the more commonly-used
|
|---|
| 7054 | predefined variables. This list is not exhaustive, and the default
|
|---|
| 7055 | values shown here may not be what are selected by `make' for your
|
|---|
| 7056 | environment. To see the complete list of predefined variables for your
|
|---|
| 7057 | instance of GNU `make' you can run `make -p' in a directory with no
|
|---|
| 7058 | makefiles.
|
|---|
| 7059 |
|
|---|
| 7060 | Here is a table of some of the more common variables used as names of
|
|---|
| 7061 | programs in built-in rules: makefiles.
|
|---|
| 7062 |
|
|---|
| 7063 | `AR'
|
|---|
| 7064 | Archive-maintaining program; default `ar'.
|
|---|
| 7065 |
|
|---|
| 7066 | `AS'
|
|---|
| 7067 | Program for compiling assembly files; default `as'.
|
|---|
| 7068 |
|
|---|
| 7069 | `CC'
|
|---|
| 7070 | Program for compiling C programs; default `cc'.
|
|---|
| 7071 |
|
|---|
| 7072 | `CO'
|
|---|
| 7073 | Program for checking out files from RCS; default `co'.
|
|---|
| 7074 |
|
|---|
| 7075 | `CXX'
|
|---|
| 7076 | Program for compiling C++ programs; default `g++'.
|
|---|
| 7077 |
|
|---|
| 7078 | `CO'
|
|---|
| 7079 | Program for extracting a file from RCS; default `co'.
|
|---|
| 7080 |
|
|---|
| 7081 | `CPP'
|
|---|
| 7082 | Program for running the C preprocessor, with results to standard
|
|---|
| 7083 | output; default `$(CC) -E'.
|
|---|
| 7084 |
|
|---|
| 7085 | `FC'
|
|---|
| 7086 | Program for compiling or preprocessing Fortran and Ratfor programs;
|
|---|
| 7087 | default `f77'.
|
|---|
| 7088 |
|
|---|
| 7089 | `GET'
|
|---|
| 7090 | Program for extracting a file from SCCS; default `get'.
|
|---|
| 7091 |
|
|---|
| 7092 | `LEX'
|
|---|
| 7093 | Program to use to turn Lex grammars into source code; default
|
|---|
| 7094 | `lex'.
|
|---|
| 7095 |
|
|---|
| 7096 | `YACC'
|
|---|
| 7097 | Program to use to turn Yacc grammars into source code; default
|
|---|
| 7098 | `yacc'.
|
|---|
| 7099 |
|
|---|
| 7100 | `LINT'
|
|---|
| 7101 | Program to use to run lint on source code; default `lint'.
|
|---|
| 7102 |
|
|---|
| 7103 | `M2C'
|
|---|
| 7104 | Program to use to compile Modula-2 source code; default `m2c'.
|
|---|
| 7105 |
|
|---|
| 7106 | `PC'
|
|---|
| 7107 | Program for compiling Pascal programs; default `pc'.
|
|---|
| 7108 |
|
|---|
| 7109 | `MAKEINFO'
|
|---|
| 7110 | Program to convert a Texinfo source file into an Info file; default
|
|---|
| 7111 | `makeinfo'.
|
|---|
| 7112 |
|
|---|
| 7113 | `TEX'
|
|---|
| 7114 | Program to make TeX DVI files from TeX source; default `tex'.
|
|---|
| 7115 |
|
|---|
| 7116 | `TEXI2DVI'
|
|---|
| 7117 | Program to make TeX DVI files from Texinfo source; default
|
|---|
| 7118 | `texi2dvi'.
|
|---|
| 7119 |
|
|---|
| 7120 | `WEAVE'
|
|---|
| 7121 | Program to translate Web into TeX; default `weave'.
|
|---|
| 7122 |
|
|---|
| 7123 | `CWEAVE'
|
|---|
| 7124 | Program to translate C Web into TeX; default `cweave'.
|
|---|
| 7125 |
|
|---|
| 7126 | `TANGLE'
|
|---|
| 7127 | Program to translate Web into Pascal; default `tangle'.
|
|---|
| 7128 |
|
|---|
| 7129 | `CTANGLE'
|
|---|
| 7130 | Program to translate C Web into C; default `ctangle'.
|
|---|
| 7131 |
|
|---|
| 7132 | `RM'
|
|---|
| 7133 | Command to remove a file; default `rm -f'.
|
|---|
| 7134 |
|
|---|
| 7135 | Here is a table of variables whose values are additional arguments
|
|---|
| 7136 | for the programs above. The default values for all of these is the
|
|---|
| 7137 | empty string, unless otherwise noted.
|
|---|
| 7138 |
|
|---|
| 7139 | `ARFLAGS'
|
|---|
| 7140 | Flags to give the archive-maintaining program; default `rv'.
|
|---|
| 7141 |
|
|---|
| 7142 | `ASFLAGS'
|
|---|
| 7143 | Extra flags to give to the assembler (when explicitly invoked on a
|
|---|
| 7144 | `.s' or `.S' file).
|
|---|
| 7145 |
|
|---|
| 7146 | `CFLAGS'
|
|---|
| 7147 | Extra flags to give to the C compiler.
|
|---|
| 7148 |
|
|---|
| 7149 | `CXXFLAGS'
|
|---|
| 7150 | Extra flags to give to the C++ compiler.
|
|---|
| 7151 |
|
|---|
| 7152 | `COFLAGS'
|
|---|
| 7153 | Extra flags to give to the RCS `co' program.
|
|---|
| 7154 |
|
|---|
| 7155 | `CPPFLAGS'
|
|---|
| 7156 | Extra flags to give to the C preprocessor and programs that use it
|
|---|
| 7157 | (the C and Fortran compilers).
|
|---|
| 7158 |
|
|---|
| 7159 | `FFLAGS'
|
|---|
| 7160 | Extra flags to give to the Fortran compiler.
|
|---|
| 7161 |
|
|---|
| 7162 | `GFLAGS'
|
|---|
| 7163 | Extra flags to give to the SCCS `get' program.
|
|---|
| 7164 |
|
|---|
| 7165 | `LDFLAGS'
|
|---|
| 7166 | Extra flags to give to compilers when they are supposed to invoke
|
|---|
| 7167 | the linker, `ld'.
|
|---|
| 7168 |
|
|---|
| 7169 | `LFLAGS'
|
|---|
| 7170 | Extra flags to give to Lex.
|
|---|
| 7171 |
|
|---|
| 7172 | `YFLAGS'
|
|---|
| 7173 | Extra flags to give to Yacc.
|
|---|
| 7174 |
|
|---|
| 7175 | `PFLAGS'
|
|---|
| 7176 | Extra flags to give to the Pascal compiler.
|
|---|
| 7177 |
|
|---|
| 7178 | `RFLAGS'
|
|---|
| 7179 | Extra flags to give to the Fortran compiler for Ratfor programs.
|
|---|
| 7180 |
|
|---|
| 7181 | `LINTFLAGS'
|
|---|
| 7182 | Extra flags to give to lint.
|
|---|
| 7183 |
|
|---|
| 7184 |
|
|---|
| 7185 | File: make.info, Node: Chained Rules, Next: Pattern Rules, Prev: Implicit Variables, Up: Implicit Rules
|
|---|
| 7186 |
|
|---|
| 7187 | 10.4 Chains of Implicit Rules
|
|---|
| 7188 | =============================
|
|---|
| 7189 |
|
|---|
| 7190 | Sometimes a file can be made by a sequence of implicit rules. For
|
|---|
| 7191 | example, a file `N.o' could be made from `N.y' by running first Yacc
|
|---|
| 7192 | and then `cc'. Such a sequence is called a "chain".
|
|---|
| 7193 |
|
|---|
| 7194 | If the file `N.c' exists, or is mentioned in the makefile, no
|
|---|
| 7195 | special searching is required: `make' finds that the object file can be
|
|---|
| 7196 | made by C compilation from `N.c'; later on, when considering how to
|
|---|
| 7197 | make `N.c', the rule for running Yacc is used. Ultimately both `N.c'
|
|---|
| 7198 | and `N.o' are updated.
|
|---|
| 7199 |
|
|---|
| 7200 | However, even if `N.c' does not exist and is not mentioned, `make'
|
|---|
| 7201 | knows how to envision it as the missing link between `N.o' and `N.y'!
|
|---|
| 7202 | In this case, `N.c' is called an "intermediate file". Once `make' has
|
|---|
| 7203 | decided to use the intermediate file, it is entered in the data base as
|
|---|
| 7204 | if it had been mentioned in the makefile, along with the implicit rule
|
|---|
| 7205 | that says how to create it.
|
|---|
| 7206 |
|
|---|
| 7207 | Intermediate files are remade using their rules just like all other
|
|---|
| 7208 | files. But intermediate files are treated differently in two ways.
|
|---|
| 7209 |
|
|---|
| 7210 | The first difference is what happens if the intermediate file does
|
|---|
| 7211 | not exist. If an ordinary file B does not exist, and `make' considers
|
|---|
| 7212 | a target that depends on B, it invariably creates B and then updates
|
|---|
| 7213 | the target from B. But if B is an intermediate file, then `make' can
|
|---|
| 7214 | leave well enough alone. It won't bother updating B, or the ultimate
|
|---|
| 7215 | target, unless some prerequisite of B is newer than that target or
|
|---|
| 7216 | there is some other reason to update that target.
|
|---|
| 7217 |
|
|---|
| 7218 | The second difference is that if `make' _does_ create B in order to
|
|---|
| 7219 | update something else, it deletes B later on after it is no longer
|
|---|
| 7220 | needed. Therefore, an intermediate file which did not exist before
|
|---|
| 7221 | `make' also does not exist after `make'. `make' reports the deletion
|
|---|
| 7222 | to you by printing a `rm -f' command showing which file it is deleting.
|
|---|
| 7223 |
|
|---|
| 7224 | Ordinarily, a file cannot be intermediate if it is mentioned in the
|
|---|
| 7225 | makefile as a target or prerequisite. However, you can explicitly mark
|
|---|
| 7226 | a file as intermediate by listing it as a prerequisite of the special
|
|---|
| 7227 | target `.INTERMEDIATE'. This takes effect even if the file is mentioned
|
|---|
| 7228 | explicitly in some other way.
|
|---|
| 7229 |
|
|---|
| 7230 | You can prevent automatic deletion of an intermediate file by
|
|---|
| 7231 | marking it as a "secondary" file. To do this, list it as a
|
|---|
| 7232 | prerequisite of the special target `.SECONDARY'. When a file is
|
|---|
| 7233 | secondary, `make' will not create the file merely because it does not
|
|---|
| 7234 | already exist, but `make' does not automatically delete the file.
|
|---|
| 7235 | Marking a file as secondary also marks it as intermediate.
|
|---|
| 7236 |
|
|---|
| 7237 | You can list the target pattern of an implicit rule (such as `%.o')
|
|---|
| 7238 | as a prerequisite of the special target `.PRECIOUS' to preserve
|
|---|
| 7239 | intermediate files made by implicit rules whose target patterns match
|
|---|
| 7240 | that file's name; see *Note Interrupts::.
|
|---|
| 7241 |
|
|---|
| 7242 | A chain can involve more than two implicit rules. For example, it is
|
|---|
| 7243 | possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc
|
|---|
| 7244 | and `cc'. Then both `foo.y' and `foo.c' are intermediate files that
|
|---|
| 7245 | are deleted at the end.
|
|---|
| 7246 |
|
|---|
| 7247 | No single implicit rule can appear more than once in a chain. This
|
|---|
| 7248 | means that `make' will not even consider such a ridiculous thing as
|
|---|
| 7249 | making `foo' from `foo.o.o' by running the linker twice. This
|
|---|
| 7250 | constraint has the added benefit of preventing any infinite loop in the
|
|---|
| 7251 | search for an implicit rule chain.
|
|---|
| 7252 |
|
|---|
| 7253 | There are some special implicit rules to optimize certain cases that
|
|---|
| 7254 | would otherwise be handled by rule chains. For example, making `foo'
|
|---|
| 7255 | from `foo.c' could be handled by compiling and linking with separate
|
|---|
| 7256 | chained rules, using `foo.o' as an intermediate file. But what
|
|---|
| 7257 | actually happens is that a special rule for this case does the
|
|---|
| 7258 | compilation and linking with a single `cc' command. The optimized rule
|
|---|
| 7259 | is used in preference to the step-by-step chain because it comes
|
|---|
| 7260 | earlier in the ordering of rules.
|
|---|
| 7261 |
|
|---|