| 1 | \input texinfo @c -*- Texinfo -*-
|
|---|
| 2 | @c %**start of header
|
|---|
| 3 | @setfilename make.info
|
|---|
| 4 |
|
|---|
| 5 | @include version.texi
|
|---|
| 6 | @set EDITION 0.74
|
|---|
| 7 |
|
|---|
| 8 | @settitle GNU @code{make}
|
|---|
| 9 | @setchapternewpage odd
|
|---|
| 10 | @c Combine the variable and function indices:
|
|---|
| 11 | @syncodeindex vr fn
|
|---|
| 12 | @c Combine the program and concept indices:
|
|---|
| 13 | @syncodeindex pg cp
|
|---|
| 14 | @c FSF publishers: format makebook.texi instead of using this file directly.
|
|---|
| 15 | @c ISBN confirmed by Jasimin Huang <jasimin@fsf.org> on 25 Mar 2009
|
|---|
| 16 | @set ISBN 1-882114-83-3
|
|---|
| 17 | @c %**end of header
|
|---|
| 18 |
|
|---|
| 19 | @copying
|
|---|
| 20 | This file documents the GNU @code{make} utility, which determines
|
|---|
| 21 | automatically which pieces of a large program need to be recompiled,
|
|---|
| 22 | and issues the commands to recompile them.
|
|---|
| 23 |
|
|---|
| 24 | This is Edition @value{EDITION}, last updated @value{UPDATED},
|
|---|
| 25 | of @cite{The GNU Make Manual}, for GNU @code{make} version @value{VERSION}.
|
|---|
| 26 |
|
|---|
| 27 | Copyright @copyright{} 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995,
|
|---|
| 28 | 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007,
|
|---|
| 29 | 2008, 2009, 2010, 2011, 2012, 2013, 2014, 2015, 2016 Free Software
|
|---|
| 30 | Foundation, Inc.
|
|---|
| 31 |
|
|---|
| 32 | @quotation
|
|---|
| 33 | Permission is granted to copy, distribute and/or modify this document
|
|---|
| 34 | under the terms of the GNU Free Documentation License, Version 1.3 or
|
|---|
| 35 | any later version published by the Free Software Foundation; with no
|
|---|
| 36 | Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
|
|---|
| 37 | and with the Back-Cover Texts as in (a) below. A copy of the
|
|---|
| 38 | license is included in the section entitled ``GNU Free Documentation
|
|---|
| 39 | License.''
|
|---|
| 40 |
|
|---|
| 41 | (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
|
|---|
| 42 | modify this GNU manual. Buying copies from the FSF supports it in
|
|---|
| 43 | developing GNU and promoting software freedom.''
|
|---|
| 44 | @end quotation
|
|---|
| 45 | @end copying
|
|---|
| 46 |
|
|---|
| 47 | @c finalout
|
|---|
| 48 |
|
|---|
| 49 | @c ISPELL CHECK: done, 10 June 1993 --roland
|
|---|
| 50 | @c ISPELL CHECK: done, 2000-06-25 --Martin Buchholz
|
|---|
| 51 |
|
|---|
| 52 |
|
|---|
| 53 | @dircategory Software development
|
|---|
| 54 | @direntry
|
|---|
| 55 | * Make: (make). Remake files automatically.
|
|---|
| 56 | @end direntry
|
|---|
| 57 |
|
|---|
| 58 | @iftex
|
|---|
| 59 | @shorttitlepage GNU Make
|
|---|
| 60 | @end iftex
|
|---|
| 61 | @titlepage
|
|---|
| 62 | @title GNU Make
|
|---|
| 63 | @subtitle A Program for Directing Recompilation
|
|---|
| 64 | @subtitle GNU @code{make} Version @value{VERSION}
|
|---|
| 65 | @subtitle @value{UPDATED-MONTH}
|
|---|
| 66 | @author Richard M. Stallman, Roland McGrath, Paul D. Smith
|
|---|
| 67 | @page
|
|---|
| 68 | @vskip 0pt plus 1filll
|
|---|
| 69 | @insertcopying
|
|---|
| 70 | @sp 2
|
|---|
| 71 | Published by the Free Software Foundation @*
|
|---|
| 72 | 51 Franklin St. -- Fifth Floor @*
|
|---|
| 73 | Boston, MA 02110-1301 USA @*
|
|---|
| 74 | ISBN @value{ISBN} @*
|
|---|
| 75 | @sp 2
|
|---|
| 76 | Cover art by Etienne Suvasa.
|
|---|
| 77 | @end titlepage
|
|---|
| 78 |
|
|---|
| 79 | @summarycontents
|
|---|
| 80 | @contents
|
|---|
| 81 |
|
|---|
| 82 | @ifnottex
|
|---|
| 83 | @node Top, Overview, (dir), (dir)
|
|---|
| 84 | @top GNU @code{make}
|
|---|
| 85 |
|
|---|
| 86 | @insertcopying
|
|---|
| 87 | @end ifnottex
|
|---|
| 88 |
|
|---|
| 89 | @menu
|
|---|
| 90 | * Overview:: Overview of @code{make}.
|
|---|
| 91 | * Introduction:: An introduction to @code{make}.
|
|---|
| 92 | * Makefiles:: Makefiles tell @code{make} what to do.
|
|---|
| 93 | * Rules:: Rules describe when a file must be remade.
|
|---|
| 94 | * Recipes:: Recipes say how to remake a file.
|
|---|
| 95 | * Using Variables:: You can use variables to avoid repetition.
|
|---|
| 96 | * Conditionals:: Use or ignore parts of the makefile based
|
|---|
| 97 | on the values of variables.
|
|---|
| 98 | * Functions:: Many powerful ways to manipulate text.
|
|---|
| 99 | * Invoking make: Running. How to invoke @code{make} on the command line.
|
|---|
| 100 | * Implicit Rules:: Use implicit rules to treat many files alike,
|
|---|
| 101 | based on their file names.
|
|---|
| 102 | * Archives:: How @code{make} can update library archives.
|
|---|
| 103 | * Extending make:: Using extensions to @code{make}.
|
|---|
| 104 | * Integrating make:: Integrating @code{make} with other tools.
|
|---|
| 105 | * Features:: Features GNU @code{make} has over other @code{make}s.
|
|---|
| 106 | * Missing:: What GNU @code{make} lacks from other @code{make}s.
|
|---|
| 107 | * Makefile Conventions:: Conventions for writing makefiles for
|
|---|
| 108 | GNU programs.
|
|---|
| 109 | * Quick Reference:: A quick reference for experienced users.
|
|---|
| 110 | * Error Messages:: A list of common errors generated by @code{make}.
|
|---|
| 111 | * Complex Makefile:: A real example of a straightforward,
|
|---|
| 112 | but nontrivial, makefile.
|
|---|
| 113 |
|
|---|
| 114 | * GNU Free Documentation License:: License for copying this manual.
|
|---|
| 115 | * Concept Index:: Index of Concepts.
|
|---|
| 116 | * Name Index:: Index of Functions, Variables, & Directives.
|
|---|
| 117 |
|
|---|
| 118 | @detailmenu
|
|---|
| 119 | --- The Detailed Node Listing ---
|
|---|
| 120 |
|
|---|
| 121 | Overview of @code{make}
|
|---|
| 122 |
|
|---|
| 123 | * Preparing:: Preparing and running @code{make}.
|
|---|
| 124 | * Reading:: On reading this text.
|
|---|
| 125 | * Bugs:: Problems and bugs.
|
|---|
| 126 |
|
|---|
| 127 | An Introduction to Makefiles
|
|---|
| 128 |
|
|---|
| 129 | * Rule Introduction:: What a rule looks like.
|
|---|
| 130 | * Simple Makefile:: A simple makefile.
|
|---|
| 131 | * How Make Works:: How @code{make} processes this makefile.
|
|---|
| 132 | * Variables Simplify:: Variables make makefiles simpler.
|
|---|
| 133 | * make Deduces:: Letting @code{make} deduce the recipes.
|
|---|
| 134 | * Combine By Prerequisite:: Another style of makefile.
|
|---|
| 135 | * Cleanup:: Rules for cleaning the directory.
|
|---|
| 136 |
|
|---|
| 137 | Writing Makefiles
|
|---|
| 138 |
|
|---|
| 139 | * Makefile Contents:: What makefiles contain.
|
|---|
| 140 | * Makefile Names:: How to name your makefile.
|
|---|
| 141 | * Include:: How one makefile can use another makefile.
|
|---|
| 142 | * MAKEFILES Variable:: The environment can specify extra makefiles.
|
|---|
| 143 | * Remaking Makefiles:: How makefiles get remade.
|
|---|
| 144 | * Overriding Makefiles:: How to override part of one makefile
|
|---|
| 145 | with another makefile.
|
|---|
| 146 | * Reading Makefiles:: How makefiles are parsed.
|
|---|
| 147 | * Secondary Expansion:: How and when secondary expansion is performed.
|
|---|
| 148 |
|
|---|
| 149 | What Makefiles Contain
|
|---|
| 150 |
|
|---|
| 151 | * Splitting Lines:: Splitting long lines in makefiles
|
|---|
| 152 |
|
|---|
| 153 | Writing Rules
|
|---|
| 154 |
|
|---|
| 155 | * Rule Example:: An example explained.
|
|---|
| 156 | * Rule Syntax:: General syntax explained.
|
|---|
| 157 | * Prerequisite Types:: There are two types of prerequisites.
|
|---|
| 158 | * Wildcards:: Using wildcard characters such as `*'.
|
|---|
| 159 | * Directory Search:: Searching other directories for source files.
|
|---|
| 160 | * Phony Targets:: Using a target that is not a real file's name.
|
|---|
| 161 | * Force Targets:: You can use a target without a recipe
|
|---|
| 162 | or prerequisites to mark other targets
|
|---|
| 163 | as phony.
|
|---|
| 164 | * Empty Targets:: When only the date matters and the
|
|---|
| 165 | files are empty.
|
|---|
| 166 | * Special Targets:: Targets with special built-in meanings.
|
|---|
| 167 | * Multiple Targets:: When to make use of several targets in a rule.
|
|---|
| 168 | * Multiple Rules:: How to use several rules with the same target.
|
|---|
| 169 | * Static Pattern:: Static pattern rules apply to multiple targets
|
|---|
| 170 | and can vary the prerequisites according to
|
|---|
| 171 | the target name.
|
|---|
| 172 | * Double-Colon:: How to use a special kind of rule to allow
|
|---|
| 173 | several independent rules for one target.
|
|---|
| 174 | * Automatic Prerequisites:: How to automatically generate rules giving
|
|---|
| 175 | prerequisites from source files themselves.
|
|---|
| 176 |
|
|---|
| 177 | Using Wildcard Characters in File Names
|
|---|
| 178 |
|
|---|
| 179 | * Wildcard Examples:: Several examples.
|
|---|
| 180 | * Wildcard Pitfall:: Problems to avoid.
|
|---|
| 181 | * Wildcard Function:: How to cause wildcard expansion where
|
|---|
| 182 | it does not normally take place.
|
|---|
| 183 |
|
|---|
| 184 | Searching Directories for Prerequisites
|
|---|
| 185 |
|
|---|
| 186 | * General Search:: Specifying a search path that applies
|
|---|
| 187 | to every prerequisite.
|
|---|
| 188 | * Selective Search:: Specifying a search path
|
|---|
| 189 | for a specified class of names.
|
|---|
| 190 | * Search Algorithm:: When and how search paths are applied.
|
|---|
| 191 | * Recipes/Search:: How to write recipes that work together
|
|---|
| 192 | with search paths.
|
|---|
| 193 | * Implicit/Search:: How search paths affect implicit rules.
|
|---|
| 194 | * Libraries/Search:: Directory search for link libraries.
|
|---|
| 195 |
|
|---|
| 196 | Static Pattern Rules
|
|---|
| 197 |
|
|---|
| 198 | * Static Usage:: The syntax of static pattern rules.
|
|---|
| 199 | * Static versus Implicit:: When are they better than implicit rules?
|
|---|
| 200 |
|
|---|
| 201 | Writing Recipes in Rules
|
|---|
| 202 |
|
|---|
| 203 | * Recipe Syntax:: Recipe syntax features and pitfalls.
|
|---|
| 204 | * Echoing:: How to control when recipes are echoed.
|
|---|
| 205 | * Execution:: How recipes are executed.
|
|---|
| 206 | * Parallel:: How recipes can be executed in parallel.
|
|---|
| 207 | * Errors:: What happens after a recipe execution error.
|
|---|
| 208 | * Interrupts:: What happens when a recipe is interrupted.
|
|---|
| 209 | * Recursion:: Invoking @code{make} from makefiles.
|
|---|
| 210 | * Canned Recipes:: Defining canned recipes.
|
|---|
| 211 | * Empty Recipes:: Defining useful, do-nothing recipes.
|
|---|
| 212 |
|
|---|
| 213 | Recipe Syntax
|
|---|
| 214 |
|
|---|
| 215 | * Splitting Recipe Lines:: Breaking long recipe lines for readability.
|
|---|
| 216 | * Variables in Recipes:: Using @code{make} variables in recipes.
|
|---|
| 217 |
|
|---|
| 218 | Recipe Execution
|
|---|
| 219 |
|
|---|
| 220 | * One Shell:: One shell for all lines in a recipe.
|
|---|
| 221 | * Choosing the Shell:: How @code{make} chooses the shell used
|
|---|
| 222 | to run recipes.
|
|---|
| 223 |
|
|---|
| 224 | Parallel Execution
|
|---|
| 225 |
|
|---|
| 226 | * Parallel Output:: Handling output during parallel execution
|
|---|
| 227 | * Parallel Input:: Handling input during parallel execution
|
|---|
| 228 |
|
|---|
| 229 | Recursive Use of @code{make}
|
|---|
| 230 |
|
|---|
| 231 | * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
|
|---|
| 232 | * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
|
|---|
| 233 | * Options/Recursion:: How to communicate options to a sub-@code{make}.
|
|---|
| 234 | * -w Option:: How the @samp{-w} or @samp{--print-directory} option
|
|---|
| 235 | helps debug use of recursive @code{make} commands.
|
|---|
| 236 |
|
|---|
| 237 | How to Use Variables
|
|---|
| 238 |
|
|---|
| 239 | * Reference:: How to use the value of a variable.
|
|---|
| 240 | * Flavors:: Variables come in two flavors.
|
|---|
| 241 | * Advanced:: Advanced features for referencing a variable.
|
|---|
| 242 | * Values:: All the ways variables get their values.
|
|---|
| 243 | * Setting:: How to set a variable in the makefile.
|
|---|
| 244 | * Appending:: How to append more text to the old value
|
|---|
| 245 | of a variable.
|
|---|
| 246 | * Override Directive:: How to set a variable in the makefile even if
|
|---|
| 247 | the user has set it with a command argument.
|
|---|
| 248 | * Multi-Line:: An alternate way to set a variable
|
|---|
| 249 | to a multi-line string.
|
|---|
| 250 | * Undefine Directive:: How to undefine a variable so that it appears
|
|---|
| 251 | as if it was never set.
|
|---|
| 252 | * Environment:: Variable values can come from the environment.
|
|---|
| 253 | * Target-specific:: Variable values can be defined on a per-target
|
|---|
| 254 | basis.
|
|---|
| 255 | * Pattern-specific:: Target-specific variable values can be applied
|
|---|
| 256 | to a group of targets that match a pattern.
|
|---|
| 257 | * Suppressing Inheritance:: Suppress inheritance of variables.
|
|---|
| 258 | * Special Variables:: Variables with special meaning or behavior.
|
|---|
| 259 |
|
|---|
| 260 | Advanced Features for Reference to Variables
|
|---|
| 261 |
|
|---|
| 262 | * Substitution Refs:: Referencing a variable with
|
|---|
| 263 | substitutions on the value.
|
|---|
| 264 | * Computed Names:: Computing the name of the variable to refer to.
|
|---|
| 265 |
|
|---|
| 266 | Conditional Parts of Makefiles
|
|---|
| 267 |
|
|---|
| 268 | * Conditional Example:: Example of a conditional
|
|---|
| 269 | * Conditional Syntax:: The syntax of conditionals.
|
|---|
| 270 | * Testing Flags:: Conditionals that test flags.
|
|---|
| 271 |
|
|---|
| 272 | Functions for Transforming Text
|
|---|
| 273 |
|
|---|
| 274 | * Syntax of Functions:: How to write a function call.
|
|---|
| 275 | * Text Functions:: General-purpose text manipulation functions.
|
|---|
| 276 | * File Name Functions:: Functions for manipulating file names.
|
|---|
| 277 | * Conditional Functions:: Functions that implement conditions.
|
|---|
| 278 | * Foreach Function:: Repeat some text with controlled variation.
|
|---|
| 279 | * File Function:: Write text to a file.
|
|---|
| 280 | * Call Function:: Expand a user-defined function.
|
|---|
| 281 | * Value Function:: Return the un-expanded value of a variable.
|
|---|
| 282 | * Eval Function:: Evaluate the arguments as makefile syntax.
|
|---|
| 283 | * Origin Function:: Find where a variable got its value.
|
|---|
| 284 | * Flavor Function:: Find out the flavor of a variable.
|
|---|
| 285 | * Make Control Functions:: Functions that control how make runs.
|
|---|
| 286 | * Shell Function:: Substitute the output of a shell command.
|
|---|
| 287 | * Guile Function:: Use GNU Guile embedded scripting language.
|
|---|
| 288 |
|
|---|
| 289 | How to Run @code{make}
|
|---|
| 290 |
|
|---|
| 291 | * Makefile Arguments:: How to specify which makefile to use.
|
|---|
| 292 | * Goals:: How to use goal arguments to specify which
|
|---|
| 293 | parts of the makefile to use.
|
|---|
| 294 | * Instead of Execution:: How to use mode flags to specify what
|
|---|
| 295 | kind of thing to do with the recipes
|
|---|
| 296 | in the makefile other than simply
|
|---|
| 297 | execute them.
|
|---|
| 298 | * Avoiding Compilation:: How to avoid recompiling certain files.
|
|---|
| 299 | * Overriding:: How to override a variable to specify
|
|---|
| 300 | an alternate compiler and other things.
|
|---|
| 301 | * Testing:: How to proceed past some errors, to
|
|---|
| 302 | test compilation.
|
|---|
| 303 | * Options Summary:: Summary of Options
|
|---|
| 304 |
|
|---|
| 305 | Using Implicit Rules
|
|---|
| 306 |
|
|---|
| 307 | * Using Implicit:: How to use an existing implicit rule
|
|---|
| 308 | to get the recipes for updating a file.
|
|---|
| 309 | * Catalogue of Rules:: A list of built-in rules.
|
|---|
| 310 | * Implicit Variables:: How to change what predefined rules do.
|
|---|
| 311 | * Chained Rules:: How to use a chain of implicit rules.
|
|---|
| 312 | * Pattern Rules:: How to define new implicit rules.
|
|---|
| 313 | * Last Resort:: How to define a recipe for rules which
|
|---|
| 314 | cannot find any.
|
|---|
| 315 | * Suffix Rules:: The old-fashioned style of implicit rule.
|
|---|
| 316 | * Implicit Rule Search:: The precise algorithm for applying
|
|---|
| 317 | implicit rules.
|
|---|
| 318 |
|
|---|
| 319 | Defining and Redefining Pattern Rules
|
|---|
| 320 |
|
|---|
| 321 | * Pattern Intro:: An introduction to pattern rules.
|
|---|
| 322 | * Pattern Examples:: Examples of pattern rules.
|
|---|
| 323 | * Automatic Variables:: How to use automatic variables in the
|
|---|
| 324 | recipe of implicit rules.
|
|---|
| 325 | * Pattern Match:: How patterns match.
|
|---|
| 326 | * Match-Anything Rules:: Precautions you should take prior to
|
|---|
| 327 | defining rules that can match any
|
|---|
| 328 | target file whatever.
|
|---|
| 329 | * Canceling Rules:: How to override or cancel built-in rules.
|
|---|
| 330 |
|
|---|
| 331 | Using @code{make} to Update Archive Files
|
|---|
| 332 |
|
|---|
| 333 | * Archive Members:: Archive members as targets.
|
|---|
| 334 | * Archive Update:: The implicit rule for archive member targets.
|
|---|
| 335 | * Archive Pitfalls:: Dangers to watch out for when using archives.
|
|---|
| 336 | * Archive Suffix Rules:: You can write a special kind of suffix rule
|
|---|
| 337 | for updating archives.
|
|---|
| 338 |
|
|---|
| 339 | Implicit Rule for Archive Member Targets
|
|---|
| 340 |
|
|---|
| 341 | * Archive Symbols:: How to update archive symbol directories.
|
|---|
| 342 |
|
|---|
| 343 | Extending GNU @code{make}
|
|---|
| 344 |
|
|---|
| 345 | * Guile Integration:: Using Guile as an embedded scripting language.
|
|---|
| 346 | * Loading Objects:: Loading dynamic objects as extensions.
|
|---|
| 347 |
|
|---|
| 348 | GNU Guile Integration
|
|---|
| 349 |
|
|---|
| 350 | * Guile Types:: Converting Guile types to @code{make} strings.
|
|---|
| 351 | * Guile Interface:: Invoking @code{make} functions from Guile.
|
|---|
| 352 | * Guile Example:: Example using Guile in @code{make}.
|
|---|
| 353 |
|
|---|
| 354 | Loading Dynamic Objects
|
|---|
| 355 |
|
|---|
| 356 | * load Directive:: Loading dynamic objects as extensions.
|
|---|
| 357 | * Remaking Loaded Objects:: How loaded objects get remade.
|
|---|
| 358 | * Loaded Object API:: Programmatic interface for loaded objects.
|
|---|
| 359 | * Loaded Object Example:: Example of a loaded object
|
|---|
| 360 |
|
|---|
| 361 | Integrating GNU @code{make}
|
|---|
| 362 |
|
|---|
| 363 | * Job Slots:: Share job slots with GNU @code{make}.
|
|---|
| 364 | * Terminal Output:: Control output to terminals.
|
|---|
| 365 |
|
|---|
| 366 | Sharing Job Slots with GNU @code{make}
|
|---|
| 367 |
|
|---|
| 368 | * POSIX Jobserver:: Using the jobserver on POSIX systems.
|
|---|
| 369 | * Windows Jobserver:: Using the jobserver on Windows systems.
|
|---|
| 370 |
|
|---|
| 371 | @end detailmenu
|
|---|
| 372 | @end menu
|
|---|
| 373 |
|
|---|
| 374 | @node Overview, Introduction, Top, Top
|
|---|
| 375 | @comment node-name, next, previous, up
|
|---|
| 376 | @chapter Overview of @code{make}
|
|---|
| 377 |
|
|---|
| 378 | The @code{make} utility automatically determines which pieces of a large
|
|---|
| 379 | program need to be recompiled, and issues commands to recompile them.
|
|---|
| 380 | This manual describes GNU @code{make}, which was implemented by Richard
|
|---|
| 381 | Stallman and Roland McGrath. Development since Version 3.76 has been
|
|---|
| 382 | handled by Paul D. Smith.
|
|---|
| 383 |
|
|---|
| 384 | GNU @code{make} conforms to section 6.2 of @cite{IEEE Standard
|
|---|
| 385 | 1003.2-1992} (POSIX.2).
|
|---|
| 386 | @cindex POSIX
|
|---|
| 387 | @cindex IEEE Standard 1003.2
|
|---|
| 388 | @cindex standards conformance
|
|---|
| 389 |
|
|---|
| 390 | Our examples show C programs, since they are most common, but you can use
|
|---|
| 391 | @code{make} with any programming language whose compiler can be run with a
|
|---|
| 392 | shell command. Indeed, @code{make} is not limited to programs. You can
|
|---|
| 393 | use it to describe any task where some files must be updated automatically
|
|---|
| 394 | from others whenever the others change.
|
|---|
| 395 |
|
|---|
| 396 | @menu
|
|---|
| 397 | * Preparing:: Preparing and running @code{make}.
|
|---|
| 398 | * Reading:: On reading this text.
|
|---|
| 399 | * Bugs:: Problems and bugs.
|
|---|
| 400 | @end menu
|
|---|
| 401 |
|
|---|
| 402 | @node Preparing, Reading, Overview, Overview
|
|---|
| 403 | @ifnottex
|
|---|
| 404 | @heading Preparing and Running Make
|
|---|
| 405 | @end ifnottex
|
|---|
| 406 |
|
|---|
| 407 | To prepare to use @code{make}, you must write a file called
|
|---|
| 408 | the @dfn{makefile} that describes the relationships among files
|
|---|
| 409 | in your program and provides commands for updating each file.
|
|---|
| 410 | In a program, typically, the executable file is updated from object
|
|---|
| 411 | files, which are in turn made by compiling source files.@refill
|
|---|
| 412 |
|
|---|
| 413 | Once a suitable makefile exists, each time you change some source files,
|
|---|
| 414 | this simple shell command:
|
|---|
| 415 |
|
|---|
| 416 | @example
|
|---|
| 417 | make
|
|---|
| 418 | @end example
|
|---|
| 419 |
|
|---|
| 420 | @noindent
|
|---|
| 421 | suffices to perform all necessary recompilations. The @code{make} program
|
|---|
| 422 | uses the makefile data base and the last-modification times of the files to
|
|---|
| 423 | decide which of the files need to be updated. For each of those files, it
|
|---|
| 424 | issues the recipes recorded in the data base.
|
|---|
| 425 |
|
|---|
| 426 | You can provide command line arguments to @code{make} to control which
|
|---|
| 427 | files should be recompiled, or how. @xref{Running, ,How to Run
|
|---|
| 428 | @code{make}}.
|
|---|
| 429 |
|
|---|
| 430 | @node Reading, Bugs, Preparing, Overview
|
|---|
| 431 | @section How to Read This Manual
|
|---|
| 432 |
|
|---|
| 433 | If you are new to @code{make}, or are looking for a general
|
|---|
| 434 | introduction, read the first few sections of each chapter, skipping the
|
|---|
| 435 | later sections. In each chapter, the first few sections contain
|
|---|
| 436 | introductory or general information and the later sections contain
|
|---|
| 437 | specialized or technical information.
|
|---|
| 438 | @ifnottex
|
|---|
| 439 | The exception is the second chapter, @ref{Introduction, ,An
|
|---|
| 440 | Introduction to Makefiles}, all of which is introductory.
|
|---|
| 441 | @end ifnottex
|
|---|
| 442 | @iftex
|
|---|
| 443 | The exception is @ref{Introduction, ,An Introduction to Makefiles},
|
|---|
| 444 | all of which is introductory.
|
|---|
| 445 | @end iftex
|
|---|
| 446 |
|
|---|
| 447 | If you are familiar with other @code{make} programs, see @ref{Features,
|
|---|
| 448 | ,Features of GNU @code{make}}, which lists the enhancements GNU
|
|---|
| 449 | @code{make} has, and @ref{Missing, ,Incompatibilities and Missing
|
|---|
| 450 | Features}, which explains the few things GNU @code{make} lacks that
|
|---|
| 451 | others have.
|
|---|
| 452 |
|
|---|
| 453 | For a quick summary, see @ref{Options Summary}, @ref{Quick Reference},
|
|---|
| 454 | and @ref{Special Targets}.
|
|---|
| 455 |
|
|---|
| 456 | @node Bugs, , Reading, Overview
|
|---|
| 457 | @section Problems and Bugs
|
|---|
| 458 | @cindex reporting bugs
|
|---|
| 459 | @cindex bugs, reporting
|
|---|
| 460 | @cindex problems and bugs, reporting
|
|---|
| 461 |
|
|---|
| 462 | If you have problems with GNU @code{make} or think you've found a bug,
|
|---|
| 463 | please report it to the developers; we cannot promise to do anything but
|
|---|
| 464 | we might well want to fix it.
|
|---|
| 465 |
|
|---|
| 466 | Before reporting a bug, make sure you've actually found a real bug.
|
|---|
| 467 | Carefully reread the documentation and see if it really says you can do
|
|---|
| 468 | what you're trying to do. If it's not clear whether you should be able
|
|---|
| 469 | to do something or not, report that too; it's a bug in the
|
|---|
| 470 | documentation!
|
|---|
| 471 |
|
|---|
| 472 | Before reporting a bug or trying to fix it yourself, try to isolate it
|
|---|
| 473 | to the smallest possible makefile that reproduces the problem. Then
|
|---|
| 474 | send us the makefile and the exact results @code{make} gave you,
|
|---|
| 475 | including any error or warning messages. Please don't paraphrase
|
|---|
| 476 | these messages: it's best to cut and paste them into your report.
|
|---|
| 477 | When generating this small makefile, be sure to not use any non-free
|
|---|
| 478 | or unusual tools in your recipes: you can almost always emulate what
|
|---|
| 479 | such a tool would do with simple shell commands. Finally, be sure to
|
|---|
| 480 | explain what you expected to occur; this will help us decide whether
|
|---|
| 481 | the problem was really in the documentation.
|
|---|
| 482 |
|
|---|
| 483 | Once you have a precise problem you can report it in one of two ways.
|
|---|
| 484 | Either send electronic mail to:
|
|---|
| 485 |
|
|---|
| 486 | @example
|
|---|
| 487 | bug-make@@gnu.org
|
|---|
| 488 | @end example
|
|---|
| 489 |
|
|---|
| 490 | @noindent
|
|---|
| 491 | or use our Web-based project management tool, at:
|
|---|
| 492 |
|
|---|
| 493 | @example
|
|---|
| 494 | http://savannah.gnu.org/projects/make/
|
|---|
| 495 | @end example
|
|---|
| 496 |
|
|---|
| 497 | @noindent
|
|---|
| 498 | In addition to the information above, please be careful to include the
|
|---|
| 499 | version number of @code{make} you are using. You can get this
|
|---|
| 500 | information with the command @samp{make --version}. Be sure also to
|
|---|
| 501 | include the type of machine and operating system you are using. One
|
|---|
| 502 | way to obtain this information is by looking at the final lines of
|
|---|
| 503 | output from the command @samp{make --help}.
|
|---|
| 504 |
|
|---|
| 505 | @node Introduction, Makefiles, Overview, Top
|
|---|
| 506 | @comment node-name, next, previous, up
|
|---|
| 507 | @chapter An Introduction to Makefiles
|
|---|
| 508 |
|
|---|
| 509 | You need a file called a @dfn{makefile} to tell @code{make} what to do.
|
|---|
| 510 | Most often, the makefile tells @code{make} how to compile and link a
|
|---|
| 511 | program.
|
|---|
| 512 | @cindex makefile
|
|---|
| 513 |
|
|---|
| 514 | In this chapter, we will discuss a simple makefile that describes how to
|
|---|
| 515 | compile and link a text editor which consists of eight C source files
|
|---|
| 516 | and three header files. The makefile can also tell @code{make} how to
|
|---|
| 517 | run miscellaneous commands when explicitly asked (for example, to remove
|
|---|
| 518 | certain files as a clean-up operation). To see a more complex example
|
|---|
| 519 | of a makefile, see @ref{Complex Makefile}.
|
|---|
| 520 |
|
|---|
| 521 | When @code{make} recompiles the editor, each changed C source file
|
|---|
| 522 | must be recompiled. If a header file has changed, each C source file
|
|---|
| 523 | that includes the header file must be recompiled to be safe. Each
|
|---|
| 524 | compilation produces an object file corresponding to the source file.
|
|---|
| 525 | Finally, if any source file has been recompiled, all the object files,
|
|---|
| 526 | whether newly made or saved from previous compilations, must be linked
|
|---|
| 527 | together to produce the new executable editor.
|
|---|
| 528 | @cindex recompilation
|
|---|
| 529 | @cindex editor
|
|---|
| 530 |
|
|---|
| 531 | @menu
|
|---|
| 532 | * Rule Introduction:: What a rule looks like.
|
|---|
| 533 | * Simple Makefile:: A simple makefile.
|
|---|
| 534 | * How Make Works:: How @code{make} processes this makefile.
|
|---|
| 535 | * Variables Simplify:: Variables make makefiles simpler.
|
|---|
| 536 | * make Deduces:: Letting @code{make} deduce the recipes.
|
|---|
| 537 | * Combine By Prerequisite:: Another style of makefile.
|
|---|
| 538 | * Cleanup:: Rules for cleaning the directory.
|
|---|
| 539 | @end menu
|
|---|
| 540 |
|
|---|
| 541 | @node Rule Introduction, Simple Makefile, Introduction, Introduction
|
|---|
| 542 | @comment node-name, next, previous, up
|
|---|
| 543 | @section What a Rule Looks Like
|
|---|
| 544 | @cindex rule, introduction to
|
|---|
| 545 | @cindex makefile rule parts
|
|---|
| 546 | @cindex parts of makefile rule
|
|---|
| 547 |
|
|---|
| 548 | A simple makefile consists of ``rules'' with the following shape:
|
|---|
| 549 |
|
|---|
| 550 | @cindex targets, introduction to
|
|---|
| 551 | @cindex prerequisites, introduction to
|
|---|
| 552 | @cindex recipes, introduction to
|
|---|
| 553 | @example
|
|---|
| 554 | @group
|
|---|
| 555 | @var{target} @dots{} : @var{prerequisites} @dots{}
|
|---|
| 556 | @var{recipe}
|
|---|
| 557 | @dots{}
|
|---|
| 558 | @dots{}
|
|---|
| 559 | @end group
|
|---|
| 560 | @end example
|
|---|
| 561 |
|
|---|
| 562 | A @dfn{target} is usually the name of a file that is generated by a
|
|---|
| 563 | program; examples of targets are executable or object files. A target
|
|---|
| 564 | can also be the name of an action to carry out, such as @samp{clean}
|
|---|
| 565 | (@pxref{Phony Targets}).
|
|---|
| 566 |
|
|---|
| 567 | A @dfn{prerequisite} is a file that is used as input to create the
|
|---|
| 568 | target. A target often depends on several files.
|
|---|
| 569 |
|
|---|
| 570 | @cindex tabs in rules
|
|---|
| 571 | A @dfn{recipe} is an action that @code{make} carries out. A recipe
|
|---|
| 572 | may have more than one command, either on the same line or each on its
|
|---|
| 573 | own line. @strong{Please note:} you need to put a tab character at
|
|---|
| 574 | the beginning of every recipe line! This is an obscurity that catches
|
|---|
| 575 | the unwary. If you prefer to prefix your recipes with a character
|
|---|
| 576 | other than tab, you can set the @code{.RECIPEPREFIX} variable to an
|
|---|
| 577 | alternate character (@pxref{Special Variables}).
|
|---|
| 578 |
|
|---|
| 579 | Usually a recipe is in a rule with prerequisites and serves to create a
|
|---|
| 580 | target file if any of the prerequisites change. However, the rule that
|
|---|
| 581 | specifies a recipe for the target need not have prerequisites. For
|
|---|
| 582 | example, the rule containing the delete command associated with the
|
|---|
| 583 | target @samp{clean} does not have prerequisites.
|
|---|
| 584 |
|
|---|
| 585 | A @dfn{rule}, then, explains how and when to remake certain files
|
|---|
| 586 | which are the targets of the particular rule. @code{make} carries out
|
|---|
| 587 | the recipe on the prerequisites to create or update the target. A
|
|---|
| 588 | rule can also explain how and when to carry out an action.
|
|---|
| 589 | @xref{Rules, , Writing Rules}.
|
|---|
| 590 |
|
|---|
| 591 | A makefile may contain other text besides rules, but a simple makefile
|
|---|
| 592 | need only contain rules. Rules may look somewhat more complicated
|
|---|
| 593 | than shown in this template, but all fit the pattern more or less.
|
|---|
| 594 |
|
|---|
| 595 | @node Simple Makefile, How Make Works, Rule Introduction, Introduction
|
|---|
| 596 | @section A Simple Makefile
|
|---|
| 597 | @cindex simple makefile
|
|---|
| 598 | @cindex makefile, simple
|
|---|
| 599 |
|
|---|
| 600 | Here is a straightforward makefile that describes the way an
|
|---|
| 601 | executable file called @code{edit} depends on eight object files
|
|---|
| 602 | which, in turn, depend on eight C source and three header files.
|
|---|
| 603 |
|
|---|
| 604 | In this example, all the C files include @file{defs.h}, but only those
|
|---|
| 605 | defining editing commands include @file{command.h}, and only low
|
|---|
| 606 | level files that change the editor buffer include @file{buffer.h}.
|
|---|
| 607 |
|
|---|
| 608 | @example
|
|---|
| 609 | @group
|
|---|
| 610 | edit : main.o kbd.o command.o display.o \
|
|---|
| 611 | insert.o search.o files.o utils.o
|
|---|
| 612 | cc -o edit main.o kbd.o command.o display.o \
|
|---|
| 613 | insert.o search.o files.o utils.o
|
|---|
| 614 |
|
|---|
| 615 | main.o : main.c defs.h
|
|---|
| 616 | cc -c main.c
|
|---|
| 617 | kbd.o : kbd.c defs.h command.h
|
|---|
| 618 | cc -c kbd.c
|
|---|
| 619 | command.o : command.c defs.h command.h
|
|---|
| 620 | cc -c command.c
|
|---|
| 621 | display.o : display.c defs.h buffer.h
|
|---|
| 622 | cc -c display.c
|
|---|
| 623 | insert.o : insert.c defs.h buffer.h
|
|---|
| 624 | cc -c insert.c
|
|---|
| 625 | search.o : search.c defs.h buffer.h
|
|---|
| 626 | cc -c search.c
|
|---|
| 627 | files.o : files.c defs.h buffer.h command.h
|
|---|
| 628 | cc -c files.c
|
|---|
| 629 | utils.o : utils.c defs.h
|
|---|
| 630 | cc -c utils.c
|
|---|
| 631 | clean :
|
|---|
| 632 | rm edit main.o kbd.o command.o display.o \
|
|---|
| 633 | insert.o search.o files.o utils.o
|
|---|
| 634 | @end group
|
|---|
| 635 | @end example
|
|---|
| 636 |
|
|---|
| 637 | @noindent
|
|---|
| 638 | We split each long line into two lines using backslash/newline; this is
|
|---|
| 639 | like using one long line, but is easier to read. @xref{Splitting Lines,
|
|---|
| 640 | , Splitting Long Lines}.
|
|---|
| 641 | @cindex continuation lines
|
|---|
| 642 | @cindex @code{\} (backslash), for continuation lines
|
|---|
| 643 | @cindex backslash (@code{\}), for continuation lines
|
|---|
| 644 | @cindex quoting newline, in makefile
|
|---|
| 645 | @cindex newline, quoting, in makefile
|
|---|
| 646 |
|
|---|
| 647 | To use this makefile to create the executable file called @file{edit},
|
|---|
| 648 | type:
|
|---|
| 649 |
|
|---|
| 650 | @example
|
|---|
| 651 | make
|
|---|
| 652 | @end example
|
|---|
| 653 |
|
|---|
| 654 | To use this makefile to delete the executable file and all the object
|
|---|
| 655 | files from the directory, type:
|
|---|
| 656 |
|
|---|
| 657 | @example
|
|---|
| 658 | make clean
|
|---|
| 659 | @end example
|
|---|
| 660 |
|
|---|
| 661 | In the example makefile, the targets include the executable file
|
|---|
| 662 | @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The
|
|---|
| 663 | prerequisites are files such as @samp{main.c} and @samp{defs.h}.
|
|---|
| 664 | In fact, each @samp{.o} file is both a target and a prerequisite.
|
|---|
| 665 | Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}.
|
|---|
| 666 |
|
|---|
| 667 | When a target is a file, it needs to be recompiled or relinked if any
|
|---|
| 668 | of its prerequisites change. In addition, any prerequisites that are
|
|---|
| 669 | themselves automatically generated should be updated first. In this
|
|---|
| 670 | example, @file{edit} depends on each of the eight object files; the
|
|---|
| 671 | object file @file{main.o} depends on the source file @file{main.c} and
|
|---|
| 672 | on the header file @file{defs.h}.
|
|---|
| 673 |
|
|---|
| 674 | A recipe may follow each line that contains a target and
|
|---|
| 675 | prerequisites. These recipes say how to update the target file. A
|
|---|
| 676 | tab character (or whatever character is specified by the
|
|---|
| 677 | @code{.RECIPEPREFIX} variable; @pxref{Special Variables}) must come at
|
|---|
| 678 | the beginning of every line in the recipe to distinguish recipes from
|
|---|
| 679 | other lines in the makefile. (Bear in mind that @code{make} does not
|
|---|
| 680 | know anything about how the recipes work. It is up to you to supply
|
|---|
| 681 | recipes that will update the target file properly. All @code{make}
|
|---|
| 682 | does is execute the recipe you have specified when the target file
|
|---|
| 683 | needs to be updated.)@refill
|
|---|
| 684 | @cindex recipe
|
|---|
| 685 |
|
|---|
| 686 | The target @samp{clean} is not a file, but merely the name of an
|
|---|
| 687 | action. Since you normally do not want to carry out the actions in
|
|---|
| 688 | this rule, @samp{clean} is not a prerequisite of any other rule.
|
|---|
| 689 | Consequently, @code{make} never does anything with it unless you tell
|
|---|
| 690 | it specifically. Note that this rule not only is not a prerequisite,
|
|---|
| 691 | it also does not have any prerequisites, so the only purpose of the
|
|---|
| 692 | rule is to run the specified recipe. Targets that do not refer to
|
|---|
| 693 | files but are just actions are called @dfn{phony targets}.
|
|---|
| 694 | @xref{Phony Targets}, for information about this kind of target.
|
|---|
| 695 | @xref{Errors, , Errors in Recipes}, to see how to cause @code{make}
|
|---|
| 696 | to ignore errors from @code{rm} or any other command.
|
|---|
| 697 | @cindex @code{clean} target
|
|---|
| 698 | @cindex @code{rm} (shell command)
|
|---|
| 699 |
|
|---|
| 700 | @node How Make Works, Variables Simplify, Simple Makefile, Introduction
|
|---|
| 701 | @comment node-name, next, previous, up
|
|---|
| 702 | @section How @code{make} Processes a Makefile
|
|---|
| 703 | @cindex processing a makefile
|
|---|
| 704 | @cindex makefile, how @code{make} processes
|
|---|
| 705 |
|
|---|
| 706 | By default, @code{make} starts with the first target (not targets whose
|
|---|
| 707 | names start with @samp{.}). This is called the @dfn{default goal}.
|
|---|
| 708 | (@dfn{Goals} are the targets that @code{make} strives ultimately to
|
|---|
| 709 | update. You can override this behavior using the command line
|
|---|
| 710 | (@pxref{Goals, , Arguments to Specify the Goals}) or with the
|
|---|
| 711 | @code{.DEFAULT_GOAL} special variable (@pxref{Special Variables, ,
|
|---|
| 712 | Other Special Variables}).
|
|---|
| 713 | @cindex default goal
|
|---|
| 714 | @cindex goal, default
|
|---|
| 715 | @cindex goal
|
|---|
| 716 |
|
|---|
| 717 | In the simple example of the previous section, the default goal is to
|
|---|
| 718 | update the executable program @file{edit}; therefore, we put that rule
|
|---|
| 719 | first.
|
|---|
| 720 |
|
|---|
| 721 | Thus, when you give the command:
|
|---|
| 722 |
|
|---|
| 723 | @example
|
|---|
| 724 | make
|
|---|
| 725 | @end example
|
|---|
| 726 |
|
|---|
| 727 | @noindent
|
|---|
| 728 | @code{make} reads the makefile in the current directory and begins by
|
|---|
| 729 | processing the first rule. In the example, this rule is for relinking
|
|---|
| 730 | @file{edit}; but before @code{make} can fully process this rule, it
|
|---|
| 731 | must process the rules for the files that @file{edit} depends on,
|
|---|
| 732 | which in this case are the object files. Each of these files is
|
|---|
| 733 | processed according to its own rule. These rules say to update each
|
|---|
| 734 | @samp{.o} file by compiling its source file. The recompilation must
|
|---|
| 735 | be done if the source file, or any of the header files named as
|
|---|
| 736 | prerequisites, is more recent than the object file, or if the object
|
|---|
| 737 | file does not exist.
|
|---|
| 738 |
|
|---|
| 739 | The other rules are processed because their targets appear as
|
|---|
| 740 | prerequisites of the goal. If some other rule is not depended on by the
|
|---|
| 741 | goal (or anything it depends on, etc.), that rule is not processed,
|
|---|
| 742 | unless you tell @code{make} to do so (with a command such as
|
|---|
| 743 | @w{@code{make clean}}).
|
|---|
| 744 |
|
|---|
| 745 | Before recompiling an object file, @code{make} considers updating its
|
|---|
| 746 | prerequisites, the source file and header files. This makefile does not
|
|---|
| 747 | specify anything to be done for them---the @samp{.c} and @samp{.h} files
|
|---|
| 748 | are not the targets of any rules---so @code{make} does nothing for these
|
|---|
| 749 | files. But @code{make} would update automatically generated C programs,
|
|---|
| 750 | such as those made by Bison or Yacc, by their own rules at this time.
|
|---|
| 751 |
|
|---|
| 752 | After recompiling whichever object files need it, @code{make} decides
|
|---|
| 753 | whether to relink @file{edit}. This must be done if the file
|
|---|
| 754 | @file{edit} does not exist, or if any of the object files are newer than
|
|---|
| 755 | it. If an object file was just recompiled, it is now newer than
|
|---|
| 756 | @file{edit}, so @file{edit} is relinked.
|
|---|
| 757 | @cindex relinking
|
|---|
| 758 |
|
|---|
| 759 | Thus, if we change the file @file{insert.c} and run @code{make},
|
|---|
| 760 | @code{make} will compile that file to update @file{insert.o}, and then
|
|---|
| 761 | link @file{edit}. If we change the file @file{command.h} and run
|
|---|
| 762 | @code{make}, @code{make} will recompile the object files @file{kbd.o},
|
|---|
| 763 | @file{command.o} and @file{files.o} and then link the file @file{edit}.
|
|---|
| 764 |
|
|---|
| 765 | @node Variables Simplify, make Deduces, How Make Works, Introduction
|
|---|
| 766 | @section Variables Make Makefiles Simpler
|
|---|
| 767 | @cindex variables
|
|---|
| 768 | @cindex simplifying with variables
|
|---|
| 769 |
|
|---|
| 770 | In our example, we had to list all the object files twice in the rule for
|
|---|
| 771 | @file{edit} (repeated here):
|
|---|
| 772 |
|
|---|
| 773 | @example
|
|---|
| 774 | @group
|
|---|
| 775 | edit : main.o kbd.o command.o display.o \
|
|---|
| 776 | insert.o search.o files.o utils.o
|
|---|
| 777 | cc -o edit main.o kbd.o command.o display.o \
|
|---|
| 778 | insert.o search.o files.o utils.o
|
|---|
| 779 | @end group
|
|---|
| 780 | @end example
|
|---|
| 781 |
|
|---|
| 782 | @cindex @code{objects}
|
|---|
| 783 | Such duplication is error-prone; if a new object file is added to the
|
|---|
| 784 | system, we might add it to one list and forget the other. We can eliminate
|
|---|
| 785 | the risk and simplify the makefile by using a variable. @dfn{Variables}
|
|---|
| 786 | allow a text string to be defined once and substituted in multiple places
|
|---|
| 787 | later (@pxref{Using Variables, ,How to Use Variables}).
|
|---|
| 788 |
|
|---|
| 789 | @cindex @code{OBJECTS}
|
|---|
| 790 | @cindex @code{objs}
|
|---|
| 791 | @cindex @code{OBJS}
|
|---|
| 792 | @cindex @code{obj}
|
|---|
| 793 | @cindex @code{OBJ}
|
|---|
| 794 | It is standard practice for every makefile to have a variable named
|
|---|
| 795 | @code{objects}, @code{OBJECTS}, @code{objs}, @code{OBJS}, @code{obj},
|
|---|
| 796 | or @code{OBJ} which is a list of all object file names. We would
|
|---|
| 797 | define such a variable @code{objects} with a line like this in the
|
|---|
| 798 | makefile:@refill
|
|---|
| 799 |
|
|---|
| 800 | @example
|
|---|
| 801 | @group
|
|---|
| 802 | objects = main.o kbd.o command.o display.o \
|
|---|
| 803 | insert.o search.o files.o utils.o
|
|---|
| 804 | @end group
|
|---|
| 805 | @end example
|
|---|
| 806 |
|
|---|
| 807 | @noindent
|
|---|
| 808 | Then, each place we want to put a list of the object file names, we can
|
|---|
| 809 | substitute the variable's value by writing @samp{$(objects)}
|
|---|
| 810 | (@pxref{Using Variables, ,How to Use Variables}).
|
|---|
| 811 |
|
|---|
| 812 | Here is how the complete simple makefile looks when you use a variable
|
|---|
| 813 | for the object files:
|
|---|
| 814 |
|
|---|
| 815 | @example
|
|---|
| 816 | @group
|
|---|
| 817 | objects = main.o kbd.o command.o display.o \
|
|---|
| 818 | insert.o search.o files.o utils.o
|
|---|
| 819 |
|
|---|
| 820 | edit : $(objects)
|
|---|
| 821 | cc -o edit $(objects)
|
|---|
| 822 | main.o : main.c defs.h
|
|---|
| 823 | cc -c main.c
|
|---|
| 824 | kbd.o : kbd.c defs.h command.h
|
|---|
| 825 | cc -c kbd.c
|
|---|
| 826 | command.o : command.c defs.h command.h
|
|---|
| 827 | cc -c command.c
|
|---|
| 828 | display.o : display.c defs.h buffer.h
|
|---|
| 829 | cc -c display.c
|
|---|
| 830 | insert.o : insert.c defs.h buffer.h
|
|---|
| 831 | cc -c insert.c
|
|---|
| 832 | search.o : search.c defs.h buffer.h
|
|---|
| 833 | cc -c search.c
|
|---|
| 834 | files.o : files.c defs.h buffer.h command.h
|
|---|
| 835 | cc -c files.c
|
|---|
| 836 | utils.o : utils.c defs.h
|
|---|
| 837 | cc -c utils.c
|
|---|
| 838 | clean :
|
|---|
| 839 | rm edit $(objects)
|
|---|
| 840 | @end group
|
|---|
| 841 | @end example
|
|---|
| 842 |
|
|---|
| 843 | @node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction
|
|---|
| 844 | @section Letting @code{make} Deduce the Recipes
|
|---|
| 845 | @cindex deducing recipes (implicit rules)
|
|---|
| 846 | @cindex implicit rule, introduction to
|
|---|
| 847 | @cindex rule, implicit, introduction to
|
|---|
| 848 |
|
|---|
| 849 | It is not necessary to spell out the recipes for compiling the individual
|
|---|
| 850 | C source files, because @code{make} can figure them out: it has an
|
|---|
| 851 | @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly
|
|---|
| 852 | named @samp{.c} file using a @samp{cc -c} command. For example, it will
|
|---|
| 853 | use the recipe @samp{cc -c main.c -o main.o} to compile @file{main.c} into
|
|---|
| 854 | @file{main.o}. We can therefore omit the recipes from the rules for the
|
|---|
| 855 | object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill
|
|---|
| 856 |
|
|---|
| 857 | When a @samp{.c} file is used automatically in this way, it is also
|
|---|
| 858 | automatically added to the list of prerequisites. We can therefore omit
|
|---|
| 859 | the @samp{.c} files from the prerequisites, provided we omit the recipe.
|
|---|
| 860 |
|
|---|
| 861 | Here is the entire example, with both of these changes, and a variable
|
|---|
| 862 | @code{objects} as suggested above:
|
|---|
| 863 |
|
|---|
| 864 | @example
|
|---|
| 865 | @group
|
|---|
| 866 | objects = main.o kbd.o command.o display.o \
|
|---|
| 867 | insert.o search.o files.o utils.o
|
|---|
| 868 |
|
|---|
| 869 | edit : $(objects)
|
|---|
| 870 | cc -o edit $(objects)
|
|---|
| 871 |
|
|---|
| 872 | main.o : defs.h
|
|---|
| 873 | kbd.o : defs.h command.h
|
|---|
| 874 | command.o : defs.h command.h
|
|---|
| 875 | display.o : defs.h buffer.h
|
|---|
| 876 | insert.o : defs.h buffer.h
|
|---|
| 877 | search.o : defs.h buffer.h
|
|---|
| 878 | files.o : defs.h buffer.h command.h
|
|---|
| 879 | utils.o : defs.h
|
|---|
| 880 |
|
|---|
| 881 | .PHONY : clean
|
|---|
| 882 | clean :
|
|---|
| 883 | rm edit $(objects)
|
|---|
| 884 | @end group
|
|---|
| 885 | @end example
|
|---|
| 886 |
|
|---|
| 887 | @noindent
|
|---|
| 888 | This is how we would write the makefile in actual practice. (The
|
|---|
| 889 | complications associated with @samp{clean} are described elsewhere.
|
|---|
| 890 | See @ref{Phony Targets}, and @ref{Errors, ,Errors in Recipes}.)
|
|---|
| 891 |
|
|---|
| 892 | Because implicit rules are so convenient, they are important. You
|
|---|
| 893 | will see them used frequently.@refill
|
|---|
| 894 |
|
|---|
| 895 | @node Combine By Prerequisite, Cleanup, make Deduces, Introduction
|
|---|
| 896 | @section Another Style of Makefile
|
|---|
| 897 | @cindex combining rules by prerequisite
|
|---|
| 898 |
|
|---|
| 899 | When the objects of a makefile are created only by implicit rules, an
|
|---|
| 900 | alternative style of makefile is possible. In this style of makefile,
|
|---|
| 901 | you group entries by their prerequisites instead of by their targets.
|
|---|
| 902 | Here is what one looks like:
|
|---|
| 903 |
|
|---|
| 904 | @example
|
|---|
| 905 | @group
|
|---|
| 906 | objects = main.o kbd.o command.o display.o \
|
|---|
| 907 | insert.o search.o files.o utils.o
|
|---|
| 908 |
|
|---|
| 909 | edit : $(objects)
|
|---|
| 910 | cc -o edit $(objects)
|
|---|
| 911 |
|
|---|
| 912 | $(objects) : defs.h
|
|---|
| 913 | kbd.o command.o files.o : command.h
|
|---|
| 914 | display.o insert.o search.o files.o : buffer.h
|
|---|
| 915 | @end group
|
|---|
| 916 | @end example
|
|---|
| 917 |
|
|---|
| 918 | @noindent
|
|---|
| 919 | Here @file{defs.h} is given as a prerequisite of all the object files;
|
|---|
| 920 | @file{command.h} and @file{buffer.h} are prerequisites of the specific
|
|---|
| 921 | object files listed for them.
|
|---|
| 922 |
|
|---|
| 923 | Whether this is better is a matter of taste: it is more compact, but some
|
|---|
| 924 | people dislike it because they find it clearer to put all the information
|
|---|
| 925 | about each target in one place.
|
|---|
| 926 |
|
|---|
| 927 | @node Cleanup, , Combine By Prerequisite, Introduction
|
|---|
| 928 | @section Rules for Cleaning the Directory
|
|---|
| 929 | @cindex cleaning up
|
|---|
| 930 | @cindex removing, to clean up
|
|---|
| 931 |
|
|---|
| 932 | Compiling a program is not the only thing you might want to write rules
|
|---|
| 933 | for. Makefiles commonly tell how to do a few other things besides
|
|---|
| 934 | compiling a program: for example, how to delete all the object files
|
|---|
| 935 | and executables so that the directory is @samp{clean}.
|
|---|
| 936 |
|
|---|
| 937 | @cindex @code{clean} target
|
|---|
| 938 | Here is how we
|
|---|
| 939 | could write a @code{make} rule for cleaning our example editor:
|
|---|
| 940 |
|
|---|
| 941 | @example
|
|---|
| 942 | @group
|
|---|
| 943 | clean:
|
|---|
| 944 | rm edit $(objects)
|
|---|
| 945 | @end group
|
|---|
| 946 | @end example
|
|---|
| 947 |
|
|---|
| 948 | In practice, we might want to write the rule in a somewhat more
|
|---|
| 949 | complicated manner to handle unanticipated situations. We would do this:
|
|---|
| 950 |
|
|---|
| 951 | @example
|
|---|
| 952 | @group
|
|---|
| 953 | .PHONY : clean
|
|---|
| 954 | clean :
|
|---|
| 955 | -rm edit $(objects)
|
|---|
| 956 | @end group
|
|---|
| 957 | @end example
|
|---|
| 958 |
|
|---|
| 959 | @noindent
|
|---|
| 960 | This prevents @code{make} from getting confused by an actual file
|
|---|
| 961 | called @file{clean} and causes it to continue in spite of errors from
|
|---|
| 962 | @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in
|
|---|
| 963 | Recipes}.)
|
|---|
| 964 |
|
|---|
| 965 | @noindent
|
|---|
| 966 | A rule such as this should not be placed at the beginning of the
|
|---|
| 967 | makefile, because we do not want it to run by default! Thus, in the
|
|---|
| 968 | example makefile, we want the rule for @code{edit}, which recompiles
|
|---|
| 969 | the editor, to remain the default goal.
|
|---|
| 970 |
|
|---|
| 971 | Since @code{clean} is not a prerequisite of @code{edit}, this rule will not
|
|---|
| 972 | run at all if we give the command @samp{make} with no arguments. In
|
|---|
| 973 | order to make the rule run, we have to type @samp{make clean}.
|
|---|
| 974 | @xref{Running, ,How to Run @code{make}}.
|
|---|
| 975 |
|
|---|
| 976 | @node Makefiles, Rules, Introduction, Top
|
|---|
| 977 | @chapter Writing Makefiles
|
|---|
| 978 |
|
|---|
| 979 | @cindex makefile, how to write
|
|---|
| 980 | The information that tells @code{make} how to recompile a system comes from
|
|---|
| 981 | reading a data base called the @dfn{makefile}.
|
|---|
| 982 |
|
|---|
| 983 | @menu
|
|---|
| 984 | * Makefile Contents:: What makefiles contain.
|
|---|
| 985 | * Makefile Names:: How to name your makefile.
|
|---|
| 986 | * Include:: How one makefile can use another makefile.
|
|---|
| 987 | * MAKEFILES Variable:: The environment can specify extra makefiles.
|
|---|
| 988 | * Remaking Makefiles:: How makefiles get remade.
|
|---|
| 989 | * Overriding Makefiles:: How to override part of one makefile
|
|---|
| 990 | with another makefile.
|
|---|
| 991 | * Reading Makefiles:: How makefiles are parsed.
|
|---|
| 992 | * Secondary Expansion:: How and when secondary expansion is performed.
|
|---|
| 993 | @end menu
|
|---|
| 994 |
|
|---|
| 995 | @node Makefile Contents, Makefile Names, Makefiles, Makefiles
|
|---|
| 996 | @section What Makefiles Contain
|
|---|
| 997 |
|
|---|
| 998 | Makefiles contain five kinds of things: @dfn{explicit rules},
|
|---|
| 999 | @dfn{implicit rules}, @dfn{variable definitions}, @dfn{directives},
|
|---|
| 1000 | and @dfn{comments}. Rules, variables, and directives are described at
|
|---|
| 1001 | length in later chapters.@refill
|
|---|
| 1002 |
|
|---|
| 1003 | @itemize @bullet
|
|---|
| 1004 | @cindex rule, explicit, definition of
|
|---|
| 1005 | @cindex explicit rule, definition of
|
|---|
| 1006 | @item
|
|---|
| 1007 | An @dfn{explicit rule} says when and how to remake one or more files,
|
|---|
| 1008 | called the rule's @dfn{targets}. It lists the other files that the
|
|---|
| 1009 | targets depend on, called the @dfn{prerequisites} of the target, and
|
|---|
| 1010 | may also give a recipe to use to create or update the targets.
|
|---|
| 1011 | @xref{Rules, ,Writing Rules}.
|
|---|
| 1012 |
|
|---|
| 1013 | @cindex rule, implicit, definition of
|
|---|
| 1014 | @cindex implicit rule, definition of
|
|---|
| 1015 | @item
|
|---|
| 1016 | An @dfn{implicit rule} says when and how to remake a class of files
|
|---|
| 1017 | based on their names. It describes how a target may depend on a file
|
|---|
| 1018 | with a name similar to the target and gives a recipe to create or
|
|---|
| 1019 | update such a target. @xref{Implicit Rules, ,Using Implicit Rules}.
|
|---|
| 1020 |
|
|---|
| 1021 | @cindex variable definition
|
|---|
| 1022 | @item
|
|---|
| 1023 | A @dfn{variable definition} is a line that specifies a text string
|
|---|
| 1024 | value for a variable that can be substituted into the text later. The
|
|---|
| 1025 | simple makefile example shows a variable definition for @code{objects}
|
|---|
| 1026 | as a list of all object files (@pxref{Variables Simplify, , Variables
|
|---|
| 1027 | Make Makefiles Simpler}).
|
|---|
| 1028 |
|
|---|
| 1029 | @cindex directive
|
|---|
| 1030 | @item
|
|---|
| 1031 | A @dfn{directive} is an instruction for @code{make} to do something
|
|---|
| 1032 | special while reading the makefile. These include:
|
|---|
| 1033 |
|
|---|
| 1034 | @itemize @bullet
|
|---|
| 1035 | @item
|
|---|
| 1036 | Reading another makefile (@pxref{Include, ,Including Other Makefiles}).
|
|---|
| 1037 |
|
|---|
| 1038 | @item
|
|---|
| 1039 | Deciding (based on the values of variables) whether to use or
|
|---|
| 1040 | ignore a part of the makefile (@pxref{Conditionals, ,Conditional Parts of Makefiles}).
|
|---|
| 1041 |
|
|---|
| 1042 | @item
|
|---|
| 1043 | Defining a variable from a verbatim string containing multiple lines
|
|---|
| 1044 | (@pxref{Multi-Line, ,Defining Multi-Line Variables}).
|
|---|
| 1045 | @end itemize
|
|---|
| 1046 |
|
|---|
| 1047 | @cindex comments, in makefile
|
|---|
| 1048 | @cindex @code{#} (comments), in makefile
|
|---|
| 1049 | @item
|
|---|
| 1050 | @samp{#} in a line of a makefile starts a @dfn{comment}. It and the
|
|---|
| 1051 | rest of the line are ignored, except that a trailing backslash not
|
|---|
| 1052 | escaped by another backslash will continue the comment across multiple
|
|---|
| 1053 | lines. A line containing just a comment (with perhaps spaces before
|
|---|
| 1054 | it) is effectively blank, and is ignored. If you want a literal
|
|---|
| 1055 | @code{#}, escape it with a backslash (e.g., @code{\#}). Comments may
|
|---|
| 1056 | appear on any line in the makefile, although they are treated
|
|---|
| 1057 | specially in certain situations.
|
|---|
| 1058 |
|
|---|
| 1059 | You cannot use comments within variable references or function calls:
|
|---|
| 1060 | any instance of @code{#} will be treated literally (rather than as the
|
|---|
| 1061 | start of a comment) inside a variable reference or function call.
|
|---|
| 1062 |
|
|---|
| 1063 | Comments within a recipe are passed to the shell, just as with any
|
|---|
| 1064 | other recipe text. The shell decides how to interpret it: whether or
|
|---|
| 1065 | not this is a comment is up to the shell.
|
|---|
| 1066 |
|
|---|
| 1067 | Within a @code{define} directive, comments are not ignored during the
|
|---|
| 1068 | definition of the variable, but rather kept intact in the value of the
|
|---|
| 1069 | variable. When the variable is expanded they will either be treated
|
|---|
| 1070 | as @code{make} comments or as recipe text, depending on the context in
|
|---|
| 1071 | which the variable is evaluated.
|
|---|
| 1072 | @end itemize
|
|---|
| 1073 |
|
|---|
| 1074 | @menu
|
|---|
| 1075 | * Splitting Lines:: Splitting long lines in makefiles
|
|---|
| 1076 | @end menu
|
|---|
| 1077 |
|
|---|
| 1078 | @node Splitting Lines, , Makefile Contents, Makefile Contents
|
|---|
| 1079 | @subsection Splitting Long Lines
|
|---|
| 1080 | @cindex splitting long lines
|
|---|
| 1081 | @cindex long lines, splitting
|
|---|
| 1082 | @cindex backslash (@code{\}), to quote newlines
|
|---|
| 1083 |
|
|---|
| 1084 | Makefiles use a ``line-based'' syntax in which the newline character
|
|---|
| 1085 | is special and marks the end of a statement. GNU @code{make} has no
|
|---|
| 1086 | limit on the length of a statement line, up to the amount of memory in
|
|---|
| 1087 | your computer.
|
|---|
| 1088 |
|
|---|
| 1089 | However, it is difficult to read lines which are too long to display
|
|---|
| 1090 | without wrapping or scrolling. So, you can format your makefiles for
|
|---|
| 1091 | readability by adding newlines into the middle of a statement: you do
|
|---|
| 1092 | this by escaping the internal newlines with a backslash (@code{\})
|
|---|
| 1093 | character. Where we need to make a distinction we will refer to
|
|---|
| 1094 | ``physical lines'' as a single line ending with a newline (regardless
|
|---|
| 1095 | of whether it is escaped) and a ``logical line'' being a complete
|
|---|
| 1096 | statement including all escaped newlines up to the first non-escaped
|
|---|
| 1097 | newline.
|
|---|
| 1098 |
|
|---|
| 1099 | The way in which backslash/newline combinations are handled depends on
|
|---|
| 1100 | whether the statement is a recipe line or a non-recipe line. Handling
|
|---|
| 1101 | of backslash/newline in a recipe line is discussed later
|
|---|
| 1102 | (@pxref{Splitting Recipe Lines}).
|
|---|
| 1103 |
|
|---|
| 1104 | Outside of recipe lines, backslash/newlines are converted into a
|
|---|
| 1105 | single space character. Once that is done, all whitespace around the
|
|---|
| 1106 | backslash/newline is condensed into a single space: this includes all
|
|---|
| 1107 | whitespace preceding the backslash, all whitespace at the beginning of
|
|---|
| 1108 | the line after the backslash/newline, and any consecutive
|
|---|
| 1109 | backslash/newline combinations.
|
|---|
| 1110 |
|
|---|
| 1111 | If the @code{.POSIX} special target is defined then backslash/newline
|
|---|
| 1112 | handling is modified slightly to conform to POSIX.2: first, whitespace
|
|---|
| 1113 | preceding a backslash is not removed and second, consecutive
|
|---|
| 1114 | backslash/newlines are not condensed.
|
|---|
| 1115 |
|
|---|
| 1116 | @node Makefile Names, Include, Makefile Contents, Makefiles
|
|---|
| 1117 | @section What Name to Give Your Makefile
|
|---|
| 1118 | @cindex makefile name
|
|---|
| 1119 | @cindex name of makefile
|
|---|
| 1120 | @cindex default makefile name
|
|---|
| 1121 | @cindex file name of makefile
|
|---|
| 1122 |
|
|---|
| 1123 | @c following paragraph rewritten to avoid overfull hbox
|
|---|
| 1124 | By default, when @code{make} looks for the makefile, it tries the
|
|---|
| 1125 | following names, in order: @file{GNUmakefile}, @file{makefile}
|
|---|
| 1126 | and @file{Makefile}.@refill
|
|---|
| 1127 | @findex Makefile
|
|---|
| 1128 | @findex GNUmakefile
|
|---|
| 1129 | @findex makefile
|
|---|
| 1130 |
|
|---|
| 1131 | @cindex @code{README}
|
|---|
| 1132 | Normally you should call your makefile either @file{makefile} or
|
|---|
| 1133 | @file{Makefile}. (We recommend @file{Makefile} because it appears
|
|---|
| 1134 | prominently near the beginning of a directory listing, right near other
|
|---|
| 1135 | important files such as @file{README}.) The first name checked,
|
|---|
| 1136 | @file{GNUmakefile}, is not recommended for most makefiles. You should
|
|---|
| 1137 | use this name if you have a makefile that is specific to GNU
|
|---|
| 1138 | @code{make}, and will not be understood by other versions of
|
|---|
| 1139 | @code{make}. Other @code{make} programs look for @file{makefile} and
|
|---|
| 1140 | @file{Makefile}, but not @file{GNUmakefile}.
|
|---|
| 1141 |
|
|---|
| 1142 | If @code{make} finds none of these names, it does not use any makefile.
|
|---|
| 1143 | Then you must specify a goal with a command argument, and @code{make}
|
|---|
| 1144 | will attempt to figure out how to remake it using only its built-in
|
|---|
| 1145 | implicit rules. @xref{Implicit Rules, ,Using Implicit Rules}.
|
|---|
| 1146 |
|
|---|
| 1147 | @cindex @code{-f}
|
|---|
| 1148 | @cindex @code{--file}
|
|---|
| 1149 | @cindex @code{--makefile}
|
|---|
| 1150 | If you want to use a nonstandard name for your makefile, you can specify
|
|---|
| 1151 | the makefile name with the @samp{-f} or @samp{--file} option. The
|
|---|
| 1152 | arguments @w{@samp{-f @var{name}}} or @w{@samp{--file=@var{name}}} tell
|
|---|
| 1153 | @code{make} to read the file @var{name} as the makefile. If you use
|
|---|
| 1154 | more than one @samp{-f} or @samp{--file} option, you can specify several
|
|---|
| 1155 | makefiles. All the makefiles are effectively concatenated in the order
|
|---|
| 1156 | specified. The default makefile names @file{GNUmakefile},
|
|---|
| 1157 | @file{makefile} and @file{Makefile} are not checked automatically if you
|
|---|
| 1158 | specify @samp{-f} or @samp{--file}.@refill
|
|---|
| 1159 | @cindex specifying makefile name
|
|---|
| 1160 | @cindex makefile name, how to specify
|
|---|
| 1161 | @cindex name of makefile, how to specify
|
|---|
| 1162 | @cindex file name of makefile, how to specify
|
|---|
| 1163 |
|
|---|
| 1164 | @node Include, MAKEFILES Variable, Makefile Names, Makefiles
|
|---|
| 1165 | @section Including Other Makefiles
|
|---|
| 1166 | @cindex including other makefiles
|
|---|
| 1167 | @cindex makefile, including
|
|---|
| 1168 |
|
|---|
| 1169 | @findex include
|
|---|
| 1170 | The @code{include} directive tells @code{make} to suspend reading the
|
|---|
| 1171 | current makefile and read one or more other makefiles before continuing.
|
|---|
| 1172 | The directive is a line in the makefile that looks like this:
|
|---|
| 1173 |
|
|---|
| 1174 | @example
|
|---|
| 1175 | include @var{filenames}@dots{}
|
|---|
| 1176 | @end example
|
|---|
| 1177 |
|
|---|
| 1178 | @noindent
|
|---|
| 1179 | @var{filenames} can contain shell file name patterns. If
|
|---|
| 1180 | @var{filenames} is empty, nothing is included and no error is printed.
|
|---|
| 1181 | @cindex shell file name pattern (in @code{include})
|
|---|
| 1182 | @cindex shell wildcards (in @code{include})
|
|---|
| 1183 | @cindex wildcard, in @code{include}
|
|---|
| 1184 |
|
|---|
| 1185 | Extra spaces are allowed and ignored at the beginning of the line, but
|
|---|
| 1186 | the first character must not be a tab (or the value of
|
|---|
| 1187 | @code{.RECIPEPREFIX})---if the line begins with a tab, it will be
|
|---|
| 1188 | considered a recipe line. Whitespace is required between
|
|---|
| 1189 | @code{include} and the file names, and between file names; extra
|
|---|
| 1190 | whitespace is ignored there and at the end of the directive. A
|
|---|
| 1191 | comment starting with @samp{#} is allowed at the end of the line. If
|
|---|
| 1192 | the file names contain any variable or function references, they are
|
|---|
| 1193 | expanded. @xref{Using Variables, ,How to Use Variables}.
|
|---|
| 1194 |
|
|---|
| 1195 | For example, if you have three @file{.mk} files, @file{a.mk},
|
|---|
| 1196 | @file{b.mk}, and @file{c.mk}, and @code{$(bar)} expands to
|
|---|
| 1197 | @code{bish bash}, then the following expression
|
|---|
| 1198 |
|
|---|
| 1199 | @example
|
|---|
| 1200 | include foo *.mk $(bar)
|
|---|
| 1201 | @end example
|
|---|
| 1202 |
|
|---|
| 1203 | is equivalent to
|
|---|
| 1204 |
|
|---|
| 1205 | @example
|
|---|
| 1206 | include foo a.mk b.mk c.mk bish bash
|
|---|
| 1207 | @end example
|
|---|
| 1208 |
|
|---|
| 1209 | When @code{make} processes an @code{include} directive, it suspends
|
|---|
| 1210 | reading of the containing makefile and reads from each listed file in
|
|---|
| 1211 | turn. When that is finished, @code{make} resumes reading the
|
|---|
| 1212 | makefile in which the directive appears.
|
|---|
| 1213 |
|
|---|
| 1214 | One occasion for using @code{include} directives is when several programs,
|
|---|
| 1215 | handled by individual makefiles in various directories, need to use a
|
|---|
| 1216 | common set of variable definitions
|
|---|
| 1217 | (@pxref{Setting, ,Setting Variables}) or pattern rules
|
|---|
| 1218 | (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
|
|---|
| 1219 |
|
|---|
| 1220 | Another such occasion is when you want to generate prerequisites from
|
|---|
| 1221 | source files automatically; the prerequisites can be put in a file that
|
|---|
| 1222 | is included by the main makefile. This practice is generally cleaner
|
|---|
| 1223 | than that of somehow appending the prerequisites to the end of the main
|
|---|
| 1224 | makefile as has been traditionally done with other versions of
|
|---|
| 1225 | @code{make}. @xref{Automatic Prerequisites}.
|
|---|
| 1226 | @cindex prerequisites, automatic generation
|
|---|
| 1227 | @cindex automatic generation of prerequisites
|
|---|
| 1228 | @cindex generating prerequisites automatically
|
|---|
| 1229 |
|
|---|
| 1230 | @cindex @code{-I}
|
|---|
| 1231 | @cindex @code{--include-dir}
|
|---|
| 1232 | @cindex included makefiles, default directories
|
|---|
| 1233 | @cindex default directories for included makefiles
|
|---|
| 1234 | @findex /usr/gnu/include
|
|---|
| 1235 | @findex /usr/local/include
|
|---|
| 1236 | @findex /usr/include
|
|---|
| 1237 | If the specified name does not start with a slash, and the file is not
|
|---|
| 1238 | found in the current directory, several other directories are searched.
|
|---|
| 1239 | First, any directories you have specified with the @samp{-I} or
|
|---|
| 1240 | @samp{--include-dir} option are searched
|
|---|
| 1241 | (@pxref{Options Summary, ,Summary of Options}).
|
|---|
| 1242 | Then the following directories (if they exist)
|
|---|
| 1243 | are searched, in this order:
|
|---|
| 1244 | @file{@var{prefix}/include} (normally @file{/usr/local/include}
|
|---|
| 1245 | @footnote{GNU Make compiled for MS-DOS and MS-Windows behaves as if
|
|---|
| 1246 | @var{prefix} has been defined to be the root of the DJGPP tree
|
|---|
| 1247 | hierarchy.})
|
|---|
| 1248 | @file{/usr/gnu/include},
|
|---|
| 1249 | @file{/usr/local/include}, @file{/usr/include}.
|
|---|
| 1250 |
|
|---|
| 1251 | If an included makefile cannot be found in any of these directories, a
|
|---|
| 1252 | warning message is generated, but it is not an immediately fatal error;
|
|---|
| 1253 | processing of the makefile containing the @code{include} continues.
|
|---|
| 1254 | Once it has finished reading makefiles, @code{make} will try to remake
|
|---|
| 1255 | any that are out of date or don't exist.
|
|---|
| 1256 | @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
|
|---|
| 1257 | Only after it has tried to find a way to remake a makefile and failed,
|
|---|
| 1258 | will @code{make} diagnose the missing makefile as a fatal error.
|
|---|
| 1259 |
|
|---|
| 1260 | If you want @code{make} to simply ignore a makefile which does not exist
|
|---|
| 1261 | or cannot be remade, with no error message, use the @w{@code{-include}}
|
|---|
| 1262 | directive instead of @code{include}, like this:
|
|---|
| 1263 |
|
|---|
| 1264 | @example
|
|---|
| 1265 | -include @var{filenames}@dots{}
|
|---|
| 1266 | @end example
|
|---|
| 1267 |
|
|---|
| 1268 | This acts like @code{include} in every way except that there is no
|
|---|
| 1269 | error (not even a warning) if any of the @var{filenames} (or any
|
|---|
| 1270 | prerequisites of any of the @var{filenames}) do not exist or cannot be
|
|---|
| 1271 | remade.
|
|---|
| 1272 |
|
|---|
| 1273 | For compatibility with some other @code{make} implementations,
|
|---|
| 1274 | @code{sinclude} is another name for @w{@code{-include}}.
|
|---|
| 1275 |
|
|---|
| 1276 | @node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles
|
|---|
| 1277 | @section The Variable @code{MAKEFILES}
|
|---|
| 1278 | @cindex makefile, and @code{MAKEFILES} variable
|
|---|
| 1279 | @cindex including (@code{MAKEFILES} variable)
|
|---|
| 1280 |
|
|---|
| 1281 | @vindex MAKEFILES
|
|---|
| 1282 | If the environment variable @code{MAKEFILES} is defined, @code{make}
|
|---|
| 1283 | considers its value as a list of names (separated by whitespace) of
|
|---|
| 1284 | additional makefiles to be read before the others. This works much
|
|---|
| 1285 | like the @code{include} directive: various directories are searched
|
|---|
| 1286 | for those files (@pxref{Include, ,Including Other Makefiles}). In
|
|---|
| 1287 | addition, the default goal is never taken from one of these makefiles
|
|---|
| 1288 | (or any makefile included by them) and it is not an error if the files
|
|---|
| 1289 | listed in @code{MAKEFILES} are not found.@refill
|
|---|
| 1290 |
|
|---|
| 1291 | @cindex recursion, and @code{MAKEFILES} variable
|
|---|
| 1292 | The main use of @code{MAKEFILES} is in communication between recursive
|
|---|
| 1293 | invocations of @code{make} (@pxref{Recursion, ,Recursive Use of
|
|---|
| 1294 | @code{make}}). It usually is not desirable to set the environment
|
|---|
| 1295 | variable before a top-level invocation of @code{make}, because it is
|
|---|
| 1296 | usually better not to mess with a makefile from outside. However, if
|
|---|
| 1297 | you are running @code{make} without a specific makefile, a makefile in
|
|---|
| 1298 | @code{MAKEFILES} can do useful things to help the built-in implicit
|
|---|
| 1299 | rules work better, such as defining search paths (@pxref{Directory Search}).
|
|---|
| 1300 |
|
|---|
| 1301 | Some users are tempted to set @code{MAKEFILES} in the environment
|
|---|
| 1302 | automatically on login, and program makefiles to expect this to be done.
|
|---|
| 1303 | This is a very bad idea, because such makefiles will fail to work if run by
|
|---|
| 1304 | anyone else. It is much better to write explicit @code{include} directives
|
|---|
| 1305 | in the makefiles. @xref{Include, , Including Other Makefiles}.
|
|---|
| 1306 |
|
|---|
| 1307 | @node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles
|
|---|
| 1308 | @section How Makefiles Are Remade
|
|---|
| 1309 | @cindex updating makefiles
|
|---|
| 1310 | @cindex remaking makefiles
|
|---|
| 1311 | @cindex makefile, remaking of
|
|---|
| 1312 | Sometimes makefiles can be remade from other files, such as RCS or SCCS
|
|---|
| 1313 | files. If a makefile can be remade from other files, you probably want
|
|---|
| 1314 | @code{make} to get an up-to-date version of the makefile to read in.
|
|---|
| 1315 |
|
|---|
| 1316 | To this end, after reading in all makefiles, @code{make} will consider
|
|---|
| 1317 | each as a goal target and attempt to update it. If a makefile has a
|
|---|
| 1318 | rule which says how to update it (found either in that very makefile or
|
|---|
| 1319 | in another one) or if an implicit rule applies to it (@pxref{Implicit
|
|---|
| 1320 | Rules, ,Using Implicit Rules}), it will be updated if necessary. After
|
|---|
| 1321 | all makefiles have been checked, if any have actually been changed,
|
|---|
| 1322 | @code{make} starts with a clean slate and reads all the makefiles over
|
|---|
| 1323 | again. (It will also attempt to update each of them over again, but
|
|---|
| 1324 | normally this will not change them again, since they are already up to
|
|---|
| 1325 | date.)@refill
|
|---|
| 1326 |
|
|---|
| 1327 | If you know that one or more of your makefiles cannot be remade and
|
|---|
| 1328 | you want to keep @code{make} from performing an implicit rule search
|
|---|
| 1329 | on them, perhaps for efficiency reasons, you can use any normal method
|
|---|
| 1330 | of preventing implicit rule look-up to do so. For example, you can
|
|---|
| 1331 | write an explicit rule with the makefile as the target, and an empty
|
|---|
| 1332 | recipe (@pxref{Empty Recipes, ,Using Empty Recipes}).
|
|---|
| 1333 |
|
|---|
| 1334 | If the makefiles specify a double-colon rule to remake a file with
|
|---|
| 1335 | a recipe but no prerequisites, that file will always be remade
|
|---|
| 1336 | (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a
|
|---|
| 1337 | double-colon rule with a recipe but no prerequisites will be remade every
|
|---|
| 1338 | time @code{make} is run, and then again after @code{make} starts over
|
|---|
| 1339 | and reads the makefiles in again. This would cause an infinite loop:
|
|---|
| 1340 | @code{make} would constantly remake the makefile, and never do anything
|
|---|
| 1341 | else. So, to avoid this, @code{make} will @strong{not} attempt to
|
|---|
| 1342 | remake makefiles which are specified as targets of a double-colon rule
|
|---|
| 1343 | with a recipe but no prerequisites.@refill
|
|---|
| 1344 |
|
|---|
| 1345 | If you do not specify any makefiles to be read with @samp{-f} or
|
|---|
| 1346 | @samp{--file} options, @code{make} will try the default makefile names;
|
|---|
| 1347 | @pxref{Makefile Names, ,What Name to Give Your Makefile}. Unlike
|
|---|
| 1348 | makefiles explicitly requested with @samp{-f} or @samp{--file} options,
|
|---|
| 1349 | @code{make} is not certain that these makefiles should exist. However,
|
|---|
| 1350 | if a default makefile does not exist but can be created by running
|
|---|
| 1351 | @code{make} rules, you probably want the rules to be run so that the
|
|---|
| 1352 | makefile can be used.
|
|---|
| 1353 |
|
|---|
| 1354 | Therefore, if none of the default makefiles exists, @code{make} will try
|
|---|
| 1355 | to make each of them in the same order in which they are searched for
|
|---|
| 1356 | (@pxref{Makefile Names, ,What Name to Give Your Makefile})
|
|---|
| 1357 | until it succeeds in making one, or it runs out of names to try. Note
|
|---|
| 1358 | that it is not an error if @code{make} cannot find or make any makefile;
|
|---|
| 1359 | a makefile is not always necessary.@refill
|
|---|
| 1360 |
|
|---|
| 1361 | When you use the @samp{-t} or @samp{--touch} option
|
|---|
| 1362 | (@pxref{Instead of Execution, ,Instead of Executing Recipes}),
|
|---|
| 1363 | you would not want to use an out-of-date makefile to decide which
|
|---|
| 1364 | targets to touch. So the @samp{-t} option has no effect on updating
|
|---|
| 1365 | makefiles; they are really updated even if @samp{-t} is specified.
|
|---|
| 1366 | Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or
|
|---|
| 1367 | @samp{--just-print}) do not prevent updating of makefiles, because an
|
|---|
| 1368 | out-of-date makefile would result in the wrong output for other targets.
|
|---|
| 1369 | Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in,
|
|---|
| 1370 | and then print the recipe to update @file{foo} and its prerequisites
|
|---|
| 1371 | without running it. The recipe printed for @file{foo} will be the one
|
|---|
| 1372 | specified in the updated contents of @file{mfile}.
|
|---|
| 1373 |
|
|---|
| 1374 | However, on occasion you might actually wish to prevent updating of even
|
|---|
| 1375 | the makefiles. You can do this by specifying the makefiles as goals in
|
|---|
| 1376 | the command line as well as specifying them as makefiles. When the
|
|---|
| 1377 | makefile name is specified explicitly as a goal, the options @samp{-t}
|
|---|
| 1378 | and so on do apply to them.
|
|---|
| 1379 |
|
|---|
| 1380 | Thus, @samp{make -f mfile -n mfile foo} would read the makefile
|
|---|
| 1381 | @file{mfile}, print the recipe needed to update it without actually
|
|---|
| 1382 | running it, and then print the recipe needed to update @file{foo}
|
|---|
| 1383 | without running that. The recipe for @file{foo} will be the one
|
|---|
| 1384 | specified by the existing contents of @file{mfile}.
|
|---|
| 1385 |
|
|---|
| 1386 | @node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles
|
|---|
| 1387 | @section Overriding Part of Another Makefile
|
|---|
| 1388 |
|
|---|
| 1389 | @cindex overriding makefiles
|
|---|
| 1390 | @cindex makefile, overriding
|
|---|
| 1391 | Sometimes it is useful to have a makefile that is mostly just like
|
|---|
| 1392 | another makefile. You can often use the @samp{include} directive to
|
|---|
| 1393 | include one in the other, and add more targets or variable definitions.
|
|---|
| 1394 | However, it is invalid for two makefiles to give different recipes for
|
|---|
| 1395 | the same target. But there is another way.
|
|---|
| 1396 |
|
|---|
| 1397 | @cindex match-anything rule, used to override
|
|---|
| 1398 | In the containing makefile (the one that wants to include the other),
|
|---|
| 1399 | you can use a match-anything pattern rule to say that to remake any
|
|---|
| 1400 | target that cannot be made from the information in the containing
|
|---|
| 1401 | makefile, @code{make} should look in another makefile.
|
|---|
| 1402 | @xref{Pattern Rules}, for more information on pattern rules.
|
|---|
| 1403 |
|
|---|
| 1404 | For example, if you have a makefile called @file{Makefile} that says how
|
|---|
| 1405 | to make the target @samp{foo} (and other targets), you can write a
|
|---|
| 1406 | makefile called @file{GNUmakefile} that contains:
|
|---|
| 1407 |
|
|---|
| 1408 | @example
|
|---|
| 1409 | foo:
|
|---|
| 1410 | frobnicate > foo
|
|---|
| 1411 |
|
|---|
| 1412 | %: force
|
|---|
| 1413 | @@$(MAKE) -f Makefile $@@
|
|---|
| 1414 | force: ;
|
|---|
| 1415 | @end example
|
|---|
| 1416 |
|
|---|
| 1417 | If you say @samp{make foo}, @code{make} will find @file{GNUmakefile},
|
|---|
| 1418 | read it, and see that to make @file{foo}, it needs to run the recipe
|
|---|
| 1419 | @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will
|
|---|
| 1420 | find no way to make @file{bar} in @file{GNUmakefile}, so it will use the
|
|---|
| 1421 | recipe from the pattern rule: @samp{make -f Makefile bar}. If
|
|---|
| 1422 | @file{Makefile} provides a rule for updating @file{bar}, @code{make}
|
|---|
| 1423 | will apply the rule. And likewise for any other target that
|
|---|
| 1424 | @file{GNUmakefile} does not say how to make.
|
|---|
| 1425 |
|
|---|
| 1426 | The way this works is that the pattern rule has a pattern of just
|
|---|
| 1427 | @samp{%}, so it matches any target whatever. The rule specifies a
|
|---|
| 1428 | prerequisite @file{force}, to guarantee that the recipe will be run even
|
|---|
| 1429 | if the target file already exists. We give the @file{force} target an
|
|---|
| 1430 | empty recipe to prevent @code{make} from searching for an implicit rule to
|
|---|
| 1431 | build it---otherwise it would apply the same match-anything rule to
|
|---|
| 1432 | @file{force} itself and create a prerequisite loop!
|
|---|
| 1433 |
|
|---|
| 1434 | @node Reading Makefiles, Secondary Expansion, Overriding Makefiles, Makefiles
|
|---|
| 1435 | @section How @code{make} Reads a Makefile
|
|---|
| 1436 | @cindex reading makefiles
|
|---|
| 1437 | @cindex makefile, parsing
|
|---|
| 1438 |
|
|---|
| 1439 | GNU @code{make} does its work in two distinct phases. During the first
|
|---|
| 1440 | phase it reads all the makefiles, included makefiles, etc. and
|
|---|
| 1441 | internalizes all the variables and their values, implicit and explicit
|
|---|
| 1442 | rules, and constructs a dependency graph of all the targets and their
|
|---|
| 1443 | prerequisites. During the second phase, @code{make} uses these internal
|
|---|
| 1444 | structures to determine what targets will need to be rebuilt and to
|
|---|
| 1445 | invoke the rules necessary to do so.
|
|---|
| 1446 |
|
|---|
| 1447 | It's important to understand this two-phase approach because it has a
|
|---|
| 1448 | direct impact on how variable and function expansion happens; this is
|
|---|
| 1449 | often a source of some confusion when writing makefiles. Here we will
|
|---|
| 1450 | present a summary of the phases in which expansion happens for different
|
|---|
| 1451 | constructs within the makefile. We say that expansion is
|
|---|
| 1452 | @dfn{immediate} if it happens during the first phase: in this case
|
|---|
| 1453 | @code{make} will expand any variables or functions in that section of a
|
|---|
| 1454 | construct as the makefile is parsed. We say that expansion is
|
|---|
| 1455 | @dfn{deferred} if expansion is not performed immediately. Expansion of
|
|---|
| 1456 | a deferred construct is not performed until either the construct appears
|
|---|
| 1457 | later in an immediate context, or until the second phase.
|
|---|
| 1458 |
|
|---|
| 1459 | You may not be familiar with some of these constructs yet. You can
|
|---|
| 1460 | reference this section as you become familiar with them, in later
|
|---|
| 1461 | chapters.
|
|---|
| 1462 |
|
|---|
| 1463 | @subheading Variable Assignment
|
|---|
| 1464 | @cindex +=, expansion
|
|---|
| 1465 | @cindex =, expansion
|
|---|
| 1466 | @cindex ?=, expansion
|
|---|
| 1467 | @cindex +=, expansion
|
|---|
| 1468 | @cindex !=, expansion
|
|---|
| 1469 | @cindex define, expansion
|
|---|
| 1470 |
|
|---|
| 1471 | Variable definitions are parsed as follows:
|
|---|
| 1472 |
|
|---|
| 1473 | @example
|
|---|
| 1474 | @var{immediate} = @var{deferred}
|
|---|
| 1475 | @var{immediate} ?= @var{deferred}
|
|---|
| 1476 | @var{immediate} := @var{immediate}
|
|---|
| 1477 | @var{immediate} ::= @var{immediate}
|
|---|
| 1478 | @var{immediate} += @var{deferred} or @var{immediate}
|
|---|
| 1479 | @var{immediate} != @var{immediate}
|
|---|
| 1480 |
|
|---|
| 1481 | define @var{immediate}
|
|---|
| 1482 | @var{deferred}
|
|---|
| 1483 | endef
|
|---|
| 1484 |
|
|---|
| 1485 | define @var{immediate} =
|
|---|
| 1486 | @var{deferred}
|
|---|
| 1487 | endef
|
|---|
| 1488 |
|
|---|
| 1489 | define @var{immediate} ?=
|
|---|
| 1490 | @var{deferred}
|
|---|
| 1491 | endef
|
|---|
| 1492 |
|
|---|
| 1493 | define @var{immediate} :=
|
|---|
| 1494 | @var{immediate}
|
|---|
| 1495 | endef
|
|---|
| 1496 |
|
|---|
| 1497 | define @var{immediate} ::=
|
|---|
| 1498 | @var{immediate}
|
|---|
| 1499 | endef
|
|---|
| 1500 |
|
|---|
| 1501 | define @var{immediate} +=
|
|---|
| 1502 | @var{deferred} or @var{immediate}
|
|---|
| 1503 | endef
|
|---|
| 1504 |
|
|---|
| 1505 | define @var{immediate} !=
|
|---|
| 1506 | @var{immediate}
|
|---|
| 1507 | endef
|
|---|
| 1508 | @end example
|
|---|
| 1509 |
|
|---|
| 1510 | For the append operator, @samp{+=}, the right-hand side is considered
|
|---|
| 1511 | immediate if the variable was previously set as a simple variable
|
|---|
| 1512 | (@samp{:=} or @samp{::=}), and deferred otherwise.
|
|---|
| 1513 |
|
|---|
| 1514 | For the shell assignment operator, @samp{!=}, the right-hand side is
|
|---|
| 1515 | evaluated immediately and handed to the shell. The result is stored in the
|
|---|
| 1516 | variable named on the left, and that variable becomes a simple variable
|
|---|
| 1517 | (and will thus be re-evaluated on each reference).
|
|---|
| 1518 |
|
|---|
| 1519 | @subheading Conditional Directives
|
|---|
| 1520 | @cindex ifdef, expansion
|
|---|
| 1521 | @cindex ifeq, expansion
|
|---|
| 1522 | @cindex ifndef, expansion
|
|---|
| 1523 | @cindex ifneq, expansion
|
|---|
| 1524 |
|
|---|
| 1525 | Conditional directives are parsed immediately. This means, for
|
|---|
| 1526 | example, that automatic variables cannot be used in conditional
|
|---|
| 1527 | directives, as automatic variables are not set until the recipe for
|
|---|
| 1528 | that rule is invoked. If you need to use automatic variables in a
|
|---|
| 1529 | conditional directive you @emph{must} move the condition into the
|
|---|
| 1530 | recipe and use shell conditional syntax instead.
|
|---|
| 1531 |
|
|---|
| 1532 | @subheading Rule Definition
|
|---|
| 1533 | @cindex target, expansion
|
|---|
| 1534 | @cindex prerequisite, expansion
|
|---|
| 1535 | @cindex implicit rule, expansion
|
|---|
| 1536 | @cindex pattern rule, expansion
|
|---|
| 1537 | @cindex explicit rule, expansion
|
|---|
| 1538 |
|
|---|
| 1539 | A rule is always expanded the same way, regardless of the form:
|
|---|
| 1540 |
|
|---|
| 1541 | @example
|
|---|
| 1542 | @var{immediate} : @var{immediate} ; @var{deferred}
|
|---|
| 1543 | @var{deferred}
|
|---|
| 1544 | @end example
|
|---|
| 1545 |
|
|---|
| 1546 | That is, the target and prerequisite sections are expanded immediately,
|
|---|
| 1547 | and the recipe used to construct the target is always deferred. This
|
|---|
| 1548 | general rule is true for explicit rules, pattern rules, suffix rules,
|
|---|
| 1549 | static pattern rules, and simple prerequisite definitions.
|
|---|
| 1550 |
|
|---|
| 1551 | @node Secondary Expansion, , Reading Makefiles, Makefiles
|
|---|
| 1552 | @section Secondary Expansion
|
|---|
| 1553 | @cindex secondary expansion
|
|---|
| 1554 | @cindex expansion, secondary
|
|---|
| 1555 |
|
|---|
| 1556 | @findex .SECONDEXPANSION
|
|---|
| 1557 | In the previous section we learned that GNU @code{make} works in two
|
|---|
| 1558 | distinct phases: a read-in phase and a target-update phase
|
|---|
| 1559 | (@pxref{Reading Makefiles, , How @code{make} Reads a Makefile}). GNU
|
|---|
| 1560 | make also has the ability to enable a @emph{second expansion} of the
|
|---|
| 1561 | prerequisites (only) for some or all targets defined in the makefile.
|
|---|
| 1562 | In order for this second expansion to occur, the special target
|
|---|
| 1563 | @code{.SECONDEXPANSION} must be defined before the first prerequisite
|
|---|
| 1564 | list that makes use of this feature.
|
|---|
| 1565 |
|
|---|
| 1566 | If that special target is defined then in between the two phases
|
|---|
| 1567 | mentioned above, right at the end of the read-in phase, all the
|
|---|
| 1568 | prerequisites of the targets defined after the special target are
|
|---|
| 1569 | expanded a @emph{second time}. In most circumstances this secondary
|
|---|
| 1570 | expansion will have no effect, since all variable and function
|
|---|
| 1571 | references will have been expanded during the initial parsing of the
|
|---|
| 1572 | makefiles. In order to take advantage of the secondary expansion
|
|---|
| 1573 | phase of the parser, then, it's necessary to @emph{escape} the
|
|---|
| 1574 | variable or function reference in the makefile. In this case the
|
|---|
| 1575 | first expansion merely un-escapes the reference but doesn't expand it,
|
|---|
| 1576 | and expansion is left to the secondary expansion phase. For example,
|
|---|
| 1577 | consider this makefile:
|
|---|
| 1578 |
|
|---|
| 1579 | @example
|
|---|
| 1580 | .SECONDEXPANSION:
|
|---|
| 1581 | ONEVAR = onefile
|
|---|
| 1582 | TWOVAR = twofile
|
|---|
| 1583 | myfile: $(ONEVAR) $$(TWOVAR)
|
|---|
| 1584 | @end example
|
|---|
| 1585 |
|
|---|
| 1586 | After the first expansion phase the prerequisites list of the
|
|---|
| 1587 | @file{myfile} target will be @code{onefile} and @code{$(TWOVAR)}; the
|
|---|
| 1588 | first (unescaped) variable reference to @var{ONEVAR} is expanded,
|
|---|
| 1589 | while the second (escaped) variable reference is simply unescaped,
|
|---|
| 1590 | without being recognized as a variable reference. Now during the
|
|---|
| 1591 | secondary expansion the first word is expanded again but since it
|
|---|
| 1592 | contains no variable or function references it remains the value
|
|---|
| 1593 | @file{onefile}, while the second word is now a normal reference to the
|
|---|
| 1594 | variable @var{TWOVAR}, which is expanded to the value @file{twofile}.
|
|---|
| 1595 | The final result is that there are two prerequisites, @file{onefile}
|
|---|
| 1596 | and @file{twofile}.
|
|---|
| 1597 |
|
|---|
| 1598 | Obviously, this is not a very interesting case since the same result
|
|---|
| 1599 | could more easily have been achieved simply by having both variables
|
|---|
| 1600 | appear, unescaped, in the prerequisites list. One difference becomes
|
|---|
| 1601 | apparent if the variables are reset; consider this example:
|
|---|
| 1602 |
|
|---|
| 1603 | @example
|
|---|
| 1604 | .SECONDEXPANSION:
|
|---|
| 1605 | AVAR = top
|
|---|
| 1606 | onefile: $(AVAR)
|
|---|
| 1607 | twofile: $$(AVAR)
|
|---|
| 1608 | AVAR = bottom
|
|---|
| 1609 | @end example
|
|---|
| 1610 |
|
|---|
| 1611 | Here the prerequisite of @file{onefile} will be expanded immediately,
|
|---|
| 1612 | and resolve to the value @file{top}, while the prerequisite of
|
|---|
| 1613 | @file{twofile} will not be full expanded until the secondary expansion
|
|---|
| 1614 | and yield a value of @file{bottom}.
|
|---|
| 1615 |
|
|---|
| 1616 | This is marginally more exciting, but the true power of this feature
|
|---|
| 1617 | only becomes apparent when you discover that secondary expansions
|
|---|
| 1618 | always take place within the scope of the automatic variables for that
|
|---|
| 1619 | target. This means that you can use variables such as @code{$@@},
|
|---|
| 1620 | @code{$*}, etc. during the second expansion and they will have their
|
|---|
| 1621 | expected values, just as in the recipe. All you have to do is defer
|
|---|
| 1622 | the expansion by escaping the @code{$}. Also, secondary expansion
|
|---|
| 1623 | occurs for both explicit and implicit (pattern) rules. Knowing this,
|
|---|
| 1624 | the possible uses for this feature increase dramatically. For
|
|---|
| 1625 | example:
|
|---|
| 1626 |
|
|---|
| 1627 | @example
|
|---|
| 1628 | .SECONDEXPANSION:
|
|---|
| 1629 | main_OBJS := main.o try.o test.o
|
|---|
| 1630 | lib_OBJS := lib.o api.o
|
|---|
| 1631 |
|
|---|
| 1632 | main lib: $$($$@@_OBJS)
|
|---|
| 1633 | @end example
|
|---|
| 1634 |
|
|---|
| 1635 | Here, after the initial expansion the prerequisites of both the
|
|---|
| 1636 | @file{main} and @file{lib} targets will be @code{$($@@_OBJS)}. During
|
|---|
| 1637 | the secondary expansion, the @code{$@@} variable is set to the name of
|
|---|
| 1638 | the target and so the expansion for the @file{main} target will yield
|
|---|
| 1639 | @code{$(main_OBJS)}, or @code{main.o try.o test.o}, while the
|
|---|
| 1640 | secondary expansion for the @file{lib} target will yield
|
|---|
| 1641 | @code{$(lib_OBJS)}, or @code{lib.o api.o}.
|
|---|
| 1642 |
|
|---|
| 1643 | You can also mix in functions here, as long as they are properly escaped:
|
|---|
| 1644 |
|
|---|
| 1645 | @example
|
|---|
| 1646 | main_SRCS := main.c try.c test.c
|
|---|
| 1647 | lib_SRCS := lib.c api.c
|
|---|
| 1648 |
|
|---|
| 1649 | .SECONDEXPANSION:
|
|---|
| 1650 | main lib: $$(patsubst %.c,%.o,$$($$@@_SRCS))
|
|---|
| 1651 | @end example
|
|---|
| 1652 |
|
|---|
| 1653 | This version allows users to specify source files rather than object
|
|---|
| 1654 | files, but gives the same resulting prerequisites list as the previous
|
|---|
| 1655 | example.
|
|---|
| 1656 |
|
|---|
| 1657 | Evaluation of automatic variables during the secondary expansion
|
|---|
| 1658 | phase, especially of the target name variable @code{$$@@}, behaves
|
|---|
| 1659 | similarly to evaluation within recipes. However, there are some
|
|---|
| 1660 | subtle differences and ``corner cases'' which come into play for the
|
|---|
| 1661 | different types of rule definitions that @code{make} understands. The
|
|---|
| 1662 | subtleties of using the different automatic variables are described
|
|---|
| 1663 | below.
|
|---|
| 1664 |
|
|---|
| 1665 | @subheading Secondary Expansion of Explicit Rules
|
|---|
| 1666 | @cindex secondary expansion and explicit rules
|
|---|
| 1667 | @cindex explicit rules, secondary expansion of
|
|---|
| 1668 |
|
|---|
| 1669 | During the secondary expansion of explicit rules, @code{$$@@} and
|
|---|
| 1670 | @code{$$%} evaluate, respectively, to the file name of the target and,
|
|---|
| 1671 | when the target is an archive member, the target member name. The
|
|---|
| 1672 | @code{$$<} variable evaluates to the first prerequisite in the first
|
|---|
| 1673 | rule for this target. @code{$$^} and @code{$$+} evaluate to the list
|
|---|
| 1674 | of all prerequisites of rules @emph{that have already appeared} for
|
|---|
| 1675 | the same target (@code{$$+} with repetitions and @code{$$^}
|
|---|
| 1676 | without). The following example will help illustrate these behaviors:
|
|---|
| 1677 |
|
|---|
| 1678 | @example
|
|---|
| 1679 | .SECONDEXPANSION:
|
|---|
| 1680 |
|
|---|
| 1681 | foo: foo.1 bar.1 $$< $$^ $$+ # line #1
|
|---|
| 1682 |
|
|---|
| 1683 | foo: foo.2 bar.2 $$< $$^ $$+ # line #2
|
|---|
| 1684 |
|
|---|
| 1685 | foo: foo.3 bar.3 $$< $$^ $$+ # line #3
|
|---|
| 1686 | @end example
|
|---|
| 1687 |
|
|---|
| 1688 | In the first prerequisite list, all three variables (@code{$$<},
|
|---|
| 1689 | @code{$$^}, and @code{$$+}) expand to the empty string. In the
|
|---|
| 1690 | second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and
|
|---|
| 1691 | @code{foo.1 bar.1} respectively. In the third they will have values
|
|---|
| 1692 | @code{foo.1}, @code{foo.1 bar.1 foo.2 bar.2}, and @code{foo.1 bar.1
|
|---|
| 1693 | foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively.
|
|---|
| 1694 |
|
|---|
| 1695 | Rules undergo secondary expansion in makefile order, except that
|
|---|
| 1696 | the rule with the recipe is always evaluated last.
|
|---|
| 1697 |
|
|---|
| 1698 | The variables @code{$$?} and @code{$$*} are not available and expand
|
|---|
| 1699 | to the empty string.
|
|---|
| 1700 |
|
|---|
| 1701 | @subheading Secondary Expansion of Static Pattern Rules
|
|---|
| 1702 | @cindex secondary expansion and static pattern rules
|
|---|
| 1703 | @cindex static pattern rules, secondary expansion of
|
|---|
| 1704 |
|
|---|
| 1705 | Rules for secondary expansion of static pattern rules are identical to
|
|---|
| 1706 | those for explicit rules, above, with one exception: for static
|
|---|
| 1707 | pattern rules the @code{$$*} variable is set to the pattern stem. As
|
|---|
| 1708 | with explicit rules, @code{$$?} is not available and expands to the
|
|---|
| 1709 | empty string.
|
|---|
| 1710 |
|
|---|
| 1711 | @subheading Secondary Expansion of Implicit Rules
|
|---|
| 1712 | @cindex secondary expansion and implicit rules
|
|---|
| 1713 | @cindex implicit rules, secondary expansion of
|
|---|
| 1714 |
|
|---|
| 1715 | As @code{make} searches for an implicit rule, it substitutes the stem
|
|---|
| 1716 | and then performs secondary expansion for every rule with a matching
|
|---|
| 1717 | target pattern. The value of the automatic variables is derived in
|
|---|
| 1718 | the same fashion as for static pattern rules. As an example:
|
|---|
| 1719 |
|
|---|
| 1720 | @example
|
|---|
| 1721 | .SECONDEXPANSION:
|
|---|
| 1722 |
|
|---|
| 1723 | foo: bar
|
|---|
| 1724 |
|
|---|
| 1725 | foo foz: fo%: bo%
|
|---|
| 1726 |
|
|---|
| 1727 | %oo: $$< $$^ $$+ $$*
|
|---|
| 1728 | @end example
|
|---|
| 1729 |
|
|---|
| 1730 | When the implicit rule is tried for target @file{foo}, @code{$$<}
|
|---|
| 1731 | expands to @file{bar}, @code{$$^} expands to @file{bar boo},
|
|---|
| 1732 | @code{$$+} also expands to @file{bar boo}, and @code{$$*} expands to
|
|---|
| 1733 | @file{f}.
|
|---|
| 1734 |
|
|---|
| 1735 | Note that the directory prefix (D), as described in @ref{Implicit Rule
|
|---|
| 1736 | Search, ,Implicit Rule Search Algorithm}, is appended (after
|
|---|
| 1737 | expansion) to all the patterns in the prerequisites list. As an
|
|---|
| 1738 | example:@refill
|
|---|
| 1739 |
|
|---|
| 1740 | @example
|
|---|
| 1741 | .SECONDEXPANSION:
|
|---|
| 1742 |
|
|---|
| 1743 | /tmp/foo.o:
|
|---|
| 1744 |
|
|---|
| 1745 | %.o: $$(addsuffix /%.c,foo bar) foo.h
|
|---|
| 1746 | @@echo $^
|
|---|
| 1747 | @end example
|
|---|
| 1748 |
|
|---|
| 1749 | The prerequisite list printed, after the secondary expansion and
|
|---|
| 1750 | directory prefix reconstruction, will be @file{/tmp/foo/foo.c
|
|---|
| 1751 | /tmp/bar/foo.c foo.h}. If you are not interested in this
|
|---|
| 1752 | reconstruction, you can use @code{$$*} instead of @code{%} in the
|
|---|
| 1753 | prerequisites list.
|
|---|
| 1754 |
|
|---|
| 1755 | @node Rules, Recipes, Makefiles, Top
|
|---|
| 1756 | @chapter Writing Rules
|
|---|
| 1757 | @cindex writing rules
|
|---|
| 1758 | @cindex rule, how to write
|
|---|
| 1759 | @cindex target
|
|---|
| 1760 | @cindex prerequisite
|
|---|
| 1761 |
|
|---|
| 1762 | A @dfn{rule} appears in the makefile and says when and how to remake
|
|---|
| 1763 | certain files, called the rule's @dfn{targets} (most often only one per rule).
|
|---|
| 1764 | It lists the other files that are the @dfn{prerequisites} of the target, and
|
|---|
| 1765 | the @dfn{recipe} to use to create or update the target.
|
|---|
| 1766 |
|
|---|
| 1767 | @cindex default goal
|
|---|
| 1768 | @cindex goal, default
|
|---|
| 1769 | The order of rules is not significant, except for determining the
|
|---|
| 1770 | @dfn{default goal}: the target for @code{make} to consider, if you do
|
|---|
| 1771 | not otherwise specify one. The default goal is the target of the first
|
|---|
| 1772 | rule in the first makefile. If the first rule has multiple targets,
|
|---|
| 1773 | only the first target is taken as the default. There are two
|
|---|
| 1774 | exceptions: a target starting with a period is not a default unless it
|
|---|
| 1775 | contains one or more slashes, @samp{/}, as well; and, a target that
|
|---|
| 1776 | defines a pattern rule has no effect on the default goal.
|
|---|
| 1777 | (@xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.)
|
|---|
| 1778 |
|
|---|
| 1779 | Therefore, we usually write the makefile so that the first rule is the
|
|---|
| 1780 | one for compiling the entire program or all the programs described by
|
|---|
| 1781 | the makefile (often with a target called @samp{all}).
|
|---|
| 1782 | @xref{Goals, ,Arguments to Specify the Goals}.
|
|---|
| 1783 |
|
|---|
| 1784 | @menu
|
|---|
| 1785 | * Rule Example:: An example explained.
|
|---|
| 1786 | * Rule Syntax:: General syntax explained.
|
|---|
| 1787 | * Prerequisite Types:: There are two types of prerequisites.
|
|---|
| 1788 | * Wildcards:: Using wildcard characters such as `*'.
|
|---|
| 1789 | * Directory Search:: Searching other directories for source files.
|
|---|
| 1790 | * Phony Targets:: Using a target that is not a real file's name.
|
|---|
| 1791 | * Force Targets:: You can use a target without a recipe
|
|---|
| 1792 | or prerequisites to mark other targets
|
|---|
| 1793 | as phony.
|
|---|
| 1794 | * Empty Targets:: When only the date matters and the
|
|---|
| 1795 | files are empty.
|
|---|
| 1796 | * Special Targets:: Targets with special built-in meanings.
|
|---|
| 1797 | * Multiple Targets:: When to make use of several targets in a rule.
|
|---|
| 1798 | * Multiple Rules:: How to use several rules with the same target.
|
|---|
| 1799 | * Static Pattern:: Static pattern rules apply to multiple targets
|
|---|
| 1800 | and can vary the prerequisites according to
|
|---|
| 1801 | the target name.
|
|---|
| 1802 | * Double-Colon:: How to use a special kind of rule to allow
|
|---|
| 1803 | several independent rules for one target.
|
|---|
| 1804 | * Automatic Prerequisites:: How to automatically generate rules giving
|
|---|
| 1805 | prerequisites from source files themselves.
|
|---|
| 1806 | @end menu
|
|---|
| 1807 |
|
|---|
| 1808 | @ifnottex
|
|---|
| 1809 | @node Rule Example, Rule Syntax, Rules, Rules
|
|---|
| 1810 | @section Rule Example
|
|---|
| 1811 |
|
|---|
| 1812 | Here is an example of a rule:
|
|---|
| 1813 |
|
|---|
| 1814 | @example
|
|---|
| 1815 | foo.o : foo.c defs.h # module for twiddling the frobs
|
|---|
| 1816 | cc -c -g foo.c
|
|---|
| 1817 | @end example
|
|---|
| 1818 |
|
|---|
| 1819 | Its target is @file{foo.o} and its prerequisites are @file{foo.c} and
|
|---|
| 1820 | @file{defs.h}. It has one command in the recipe: @samp{cc -c -g foo.c}.
|
|---|
| 1821 | The recipe starts with a tab to identify it as a recipe.
|
|---|
| 1822 |
|
|---|
| 1823 | This rule says two things:
|
|---|
| 1824 |
|
|---|
| 1825 | @itemize @bullet
|
|---|
| 1826 | @item
|
|---|
| 1827 | How to decide whether @file{foo.o} is out of date: it is out of date
|
|---|
| 1828 | if it does not exist, or if either @file{foo.c} or @file{defs.h} is
|
|---|
| 1829 | more recent than it.
|
|---|
| 1830 |
|
|---|
| 1831 | @item
|
|---|
| 1832 | How to update the file @file{foo.o}: by running @code{cc} as stated.
|
|---|
| 1833 | The recipe does not explicitly mention @file{defs.h}, but we presume
|
|---|
| 1834 | that @file{foo.c} includes it, and that that is why @file{defs.h} was
|
|---|
| 1835 | added to the prerequisites.
|
|---|
| 1836 | @end itemize
|
|---|
| 1837 | @end ifnottex
|
|---|
| 1838 |
|
|---|
| 1839 | @node Rule Syntax, Prerequisite Types, Rule Example, Rules
|
|---|
| 1840 | @section Rule Syntax
|
|---|
| 1841 |
|
|---|
| 1842 | @cindex rule syntax
|
|---|
| 1843 | @cindex syntax of rules
|
|---|
| 1844 | In general, a rule looks like this:
|
|---|
| 1845 |
|
|---|
| 1846 | @example
|
|---|
| 1847 | @var{targets} : @var{prerequisites}
|
|---|
| 1848 | @var{recipe}
|
|---|
| 1849 | @dots{}
|
|---|
| 1850 | @end example
|
|---|
| 1851 |
|
|---|
| 1852 | @noindent
|
|---|
| 1853 | or like this:
|
|---|
| 1854 |
|
|---|
| 1855 | @example
|
|---|
| 1856 | @var{targets} : @var{prerequisites} ; @var{recipe}
|
|---|
| 1857 | @var{recipe}
|
|---|
| 1858 | @dots{}
|
|---|
| 1859 | @end example
|
|---|
| 1860 |
|
|---|
| 1861 | @cindex targets
|
|---|
| 1862 | @cindex rule targets
|
|---|
| 1863 | The @var{targets} are file names, separated by spaces. Wildcard
|
|---|
| 1864 | characters may be used (@pxref{Wildcards, ,Using Wildcard Characters
|
|---|
| 1865 | in File Names}) and a name of the form @file{@var{a}(@var{m})}
|
|---|
| 1866 | represents member @var{m} in archive file @var{a}
|
|---|
| 1867 | (@pxref{Archive Members, ,Archive Members as Targets}).
|
|---|
| 1868 | Usually there is only one
|
|---|
| 1869 | target per rule, but occasionally there is a reason to have more
|
|---|
| 1870 | (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill
|
|---|
| 1871 |
|
|---|
| 1872 | @cindex recipes
|
|---|
| 1873 | @cindex tab character (in commands)
|
|---|
| 1874 | The @var{recipe} lines start with a tab character (or the first
|
|---|
| 1875 | character in the value of the @code{.RECIPEPREFIX} variable;
|
|---|
| 1876 | @pxref{Special Variables}). The first recipe line may appear on the line
|
|---|
| 1877 | after the prerequisites, with a tab character, or may appear on the
|
|---|
| 1878 | same line, with a semicolon. Either way, the effect is the same.
|
|---|
| 1879 | There are other differences in the syntax of recipes.
|
|---|
| 1880 | @xref{Recipes, ,Writing Recipes in Rules}.
|
|---|
| 1881 |
|
|---|
| 1882 | @cindex dollar sign (@code{$}), in rules
|
|---|
| 1883 | @cindex @code{$}, in rules
|
|---|
| 1884 | @cindex rules, and @code{$}
|
|---|
| 1885 | Because dollar signs are used to start @code{make} variable
|
|---|
| 1886 | references, if you really want a dollar sign in a target or
|
|---|
| 1887 | prerequisite you must write two of them, @samp{$$} (@pxref{Using
|
|---|
| 1888 | Variables, ,How to Use Variables}). If you have enabled secondary
|
|---|
| 1889 | expansion (@pxref{Secondary Expansion}) and you want a literal dollar
|
|---|
| 1890 | sign in the prerequisites list, you must actually write @emph{four}
|
|---|
| 1891 | dollar signs (@samp{$$$$}).
|
|---|
| 1892 |
|
|---|
| 1893 | You may split a long line by inserting a backslash followed by a
|
|---|
| 1894 | newline, but this is not required, as @code{make} places no limit on
|
|---|
| 1895 | the length of a line in a makefile.
|
|---|
| 1896 |
|
|---|
| 1897 | A rule tells @code{make} two things: when the targets are out of date,
|
|---|
| 1898 | and how to update them when necessary.
|
|---|
| 1899 |
|
|---|
| 1900 | @cindex prerequisites
|
|---|
| 1901 | @cindex rule prerequisites
|
|---|
| 1902 | The criterion for being out of date is specified in terms of the
|
|---|
| 1903 | @var{prerequisites}, which consist of file names separated by spaces.
|
|---|
| 1904 | (Wildcards and archive members (@pxref{Archives}) are allowed here too.)
|
|---|
| 1905 | A target is out of date if it does not exist or if it is older than any
|
|---|
| 1906 | of the prerequisites (by comparison of last-modification times). The
|
|---|
| 1907 | idea is that the contents of the target file are computed based on
|
|---|
| 1908 | information in the prerequisites, so if any of the prerequisites changes,
|
|---|
| 1909 | the contents of the existing target file are no longer necessarily
|
|---|
| 1910 | valid.
|
|---|
| 1911 |
|
|---|
| 1912 | How to update is specified by a @var{recipe}. This is one or more
|
|---|
| 1913 | lines to be executed by the shell (normally @samp{sh}), but with some
|
|---|
| 1914 | extra features (@pxref{Recipes, ,Writing Recipes in Rules}).
|
|---|
| 1915 |
|
|---|
| 1916 | @node Prerequisite Types, Wildcards, Rule Syntax, Rules
|
|---|
| 1917 | @comment node-name, next, previous, up
|
|---|
| 1918 | @section Types of Prerequisites
|
|---|
| 1919 | @cindex prerequisite types
|
|---|
| 1920 | @cindex types of prerequisites
|
|---|
| 1921 |
|
|---|
| 1922 | @cindex prerequisites, normal
|
|---|
| 1923 | @cindex normal prerequisites
|
|---|
| 1924 | @cindex prerequisites, order-only
|
|---|
| 1925 | @cindex order-only prerequisites
|
|---|
| 1926 | There are actually two different types of prerequisites understood by
|
|---|
| 1927 | GNU @code{make}: normal prerequisites such as described in the
|
|---|
| 1928 | previous section, and @dfn{order-only} prerequisites. A normal
|
|---|
| 1929 | prerequisite makes two statements: first, it imposes an order in which
|
|---|
| 1930 | recipes will be invoked: the recipes for all prerequisites of a target
|
|---|
| 1931 | will be completed before the recipe for the target is run. Second, it
|
|---|
| 1932 | imposes a dependency relationship: if any prerequisite is newer than
|
|---|
| 1933 | the target, then the target is considered out-of-date and must be
|
|---|
| 1934 | rebuilt.
|
|---|
| 1935 |
|
|---|
| 1936 | Normally, this is exactly what you want: if a target's prerequisite is
|
|---|
| 1937 | updated, then the target should also be updated.
|
|---|
| 1938 |
|
|---|
| 1939 | Occasionally, however, you have a situation where you want to impose a
|
|---|
| 1940 | specific ordering on the rules to be invoked @emph{without} forcing
|
|---|
| 1941 | the target to be updated if one of those rules is executed. In that
|
|---|
| 1942 | case, you want to define @dfn{order-only} prerequisites. Order-only
|
|---|
| 1943 | prerequisites can be specified by placing a pipe symbol (@code{|})
|
|---|
| 1944 | in the prerequisites list: any prerequisites to the left of the pipe
|
|---|
| 1945 | symbol are normal; any prerequisites to the right are order-only:
|
|---|
| 1946 |
|
|---|
| 1947 | @example
|
|---|
| 1948 | @var{targets} : @var{normal-prerequisites} | @var{order-only-prerequisites}
|
|---|
| 1949 | @end example
|
|---|
| 1950 |
|
|---|
| 1951 | The normal prerequisites section may of course be empty. Also, you
|
|---|
| 1952 | may still declare multiple lines of prerequisites for the same target:
|
|---|
| 1953 | they are appended appropriately (normal prerequisites are appended to
|
|---|
| 1954 | the list of normal prerequisites; order-only prerequisites are
|
|---|
| 1955 | appended to the list of order-only prerequisites). Note that if you
|
|---|
| 1956 | declare the same file to be both a normal and an order-only
|
|---|
| 1957 | prerequisite, the normal prerequisite takes precedence (since they
|
|---|
| 1958 | have a strict superset of the behavior of an order-only prerequisite).
|
|---|
| 1959 |
|
|---|
| 1960 | Consider an example where your targets are to be placed in a separate
|
|---|
| 1961 | directory, and that directory might not exist before @code{make} is
|
|---|
| 1962 | run. In this situation, you want the directory to be created before
|
|---|
| 1963 | any targets are placed into it but, because the timestamps on
|
|---|
| 1964 | directories change whenever a file is added, removed, or renamed, we
|
|---|
| 1965 | certainly don't want to rebuild all the targets whenever the
|
|---|
| 1966 | directory's timestamp changes. One way to manage this is with
|
|---|
| 1967 | order-only prerequisites: make the directory an order-only
|
|---|
| 1968 | prerequisite on all the targets:
|
|---|
| 1969 |
|
|---|
| 1970 | @example
|
|---|
| 1971 | OBJDIR := objdir
|
|---|
| 1972 | OBJS := $(addprefix $(OBJDIR)/,foo.o bar.o baz.o)
|
|---|
| 1973 |
|
|---|
| 1974 | $(OBJDIR)/%.o : %.c
|
|---|
| 1975 | $(COMPILE.c) $(OUTPUT_OPTION) $<
|
|---|
| 1976 |
|
|---|
| 1977 | all: $(OBJS)
|
|---|
| 1978 |
|
|---|
| 1979 | $(OBJS): | $(OBJDIR)
|
|---|
| 1980 |
|
|---|
| 1981 | $(OBJDIR):
|
|---|
| 1982 | mkdir $(OBJDIR)
|
|---|
| 1983 | @end example
|
|---|
| 1984 |
|
|---|
| 1985 | Now the rule to create the @file{objdir} directory will be run, if
|
|---|
| 1986 | needed, before any @samp{.o} is built, but no @samp{.o} will be built
|
|---|
| 1987 | because the @file{objdir} directory timestamp changed.
|
|---|
| 1988 |
|
|---|
| 1989 | @node Wildcards, Directory Search, Prerequisite Types, Rules
|
|---|
| 1990 | @section Using Wildcard Characters in File Names
|
|---|
| 1991 | @cindex wildcard
|
|---|
| 1992 | @cindex file name with wildcards
|
|---|
| 1993 | @cindex globbing (wildcards)
|
|---|
| 1994 |
|
|---|
| 1995 | @cindex @code{*} (wildcard character)
|
|---|
| 1996 | @cindex @code{?} (wildcard character)
|
|---|
| 1997 | @cindex @code{[@dots{}]} (wildcard characters)
|
|---|
| 1998 | A single file name can specify many files using @dfn{wildcard characters}.
|
|---|
| 1999 | The wildcard characters in @code{make} are @samp{*}, @samp{?} and
|
|---|
| 2000 | @samp{[@dots{}]}, the same as in the Bourne shell. For example, @file{*.c}
|
|---|
| 2001 | specifies a list of all the files (in the working directory) whose names
|
|---|
| 2002 | end in @samp{.c}.@refill
|
|---|
| 2003 |
|
|---|
| 2004 | @cindex @code{~} (tilde)
|
|---|
| 2005 | @cindex tilde (@code{~})
|
|---|
| 2006 | @cindex home directory
|
|---|
| 2007 | The character @samp{~} at the beginning of a file name also has special
|
|---|
| 2008 | significance. If alone, or followed by a slash, it represents your home
|
|---|
| 2009 | directory. For example @file{~/bin} expands to @file{/home/you/bin}.
|
|---|
| 2010 | If the @samp{~} is followed by a word, the string represents the home
|
|---|
| 2011 | directory of the user named by that word. For example @file{~john/bin}
|
|---|
| 2012 | expands to @file{/home/john/bin}. On systems which don't have a home
|
|---|
| 2013 | directory for each user (such as MS-DOS or MS-Windows), this
|
|---|
| 2014 | functionality can be simulated by setting the environment variable
|
|---|
| 2015 | @var{HOME}.@refill
|
|---|
| 2016 |
|
|---|
| 2017 | Wildcard expansion is performed by @code{make} automatically in
|
|---|
| 2018 | targets and in prerequisites. In recipes, the shell is responsible
|
|---|
| 2019 | for wildcard expansion. In other contexts, wildcard expansion happens
|
|---|
| 2020 | only if you request it explicitly with the @code{wildcard} function.
|
|---|
| 2021 |
|
|---|
| 2022 | The special significance of a wildcard character can be turned off by
|
|---|
| 2023 | preceding it with a backslash. Thus, @file{foo\*bar} would refer to a
|
|---|
| 2024 | specific file whose name consists of @samp{foo}, an asterisk, and
|
|---|
| 2025 | @samp{bar}.@refill
|
|---|
| 2026 |
|
|---|
| 2027 | @menu
|
|---|
| 2028 | * Wildcard Examples:: Several examples.
|
|---|
| 2029 | * Wildcard Pitfall:: Problems to avoid.
|
|---|
| 2030 | * Wildcard Function:: How to cause wildcard expansion where
|
|---|
| 2031 | it does not normally take place.
|
|---|
| 2032 | @end menu
|
|---|
| 2033 |
|
|---|
| 2034 | @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards
|
|---|
| 2035 | @subsection Wildcard Examples
|
|---|
| 2036 |
|
|---|
| 2037 | Wildcards can be used in the recipe of a rule, where they are expanded
|
|---|
| 2038 | by the shell. For example, here is a rule to delete all the object files:
|
|---|
| 2039 |
|
|---|
| 2040 | @example
|
|---|
| 2041 | @group
|
|---|
| 2042 | clean:
|
|---|
| 2043 | rm -f *.o
|
|---|
| 2044 | @end group
|
|---|
| 2045 | @end example
|
|---|
| 2046 | @cindex @code{rm} (shell command)
|
|---|
| 2047 |
|
|---|
| 2048 | Wildcards are also useful in the prerequisites of a rule. With the
|
|---|
| 2049 | following rule in the makefile, @samp{make print} will print all the
|
|---|
| 2050 | @samp{.c} files that have changed since the last time you printed them:
|
|---|
| 2051 |
|
|---|
| 2052 | @example
|
|---|
| 2053 | print: *.c
|
|---|
| 2054 | lpr -p $?
|
|---|
| 2055 | touch print
|
|---|
| 2056 | @end example
|
|---|
| 2057 |
|
|---|
| 2058 | @cindex @code{print} target
|
|---|
| 2059 | @cindex @code{lpr} (shell command)
|
|---|
| 2060 | @cindex @code{touch} (shell command)
|
|---|
| 2061 | @noindent
|
|---|
| 2062 | This rule uses @file{print} as an empty target file; see @ref{Empty
|
|---|
| 2063 | Targets, ,Empty Target Files to Record Events}. (The automatic variable
|
|---|
| 2064 | @samp{$?} is used to print only those files that have changed; see
|
|---|
| 2065 | @ref{Automatic Variables}.)@refill
|
|---|
| 2066 |
|
|---|
| 2067 | Wildcard expansion does not happen when you define a variable. Thus, if
|
|---|
| 2068 | you write this:
|
|---|
| 2069 |
|
|---|
| 2070 | @example
|
|---|
| 2071 | objects = *.o
|
|---|
| 2072 | @end example
|
|---|
| 2073 |
|
|---|
| 2074 | @noindent
|
|---|
| 2075 | then the value of the variable @code{objects} is the actual string
|
|---|
| 2076 | @samp{*.o}. However, if you use the value of @code{objects} in a
|
|---|
| 2077 | target or prerequisite, wildcard expansion will take place there. If
|
|---|
| 2078 | you use the value of @code{objects} in a recipe, the shell may perform
|
|---|
| 2079 | wildcard expansion when the recipe runs. To set @code{objects} to the
|
|---|
| 2080 | expansion, instead use:
|
|---|
| 2081 |
|
|---|
| 2082 | @example
|
|---|
| 2083 | objects := $(wildcard *.o)
|
|---|
| 2084 | @end example
|
|---|
| 2085 |
|
|---|
| 2086 | @noindent
|
|---|
| 2087 | @xref{Wildcard Function}.
|
|---|
| 2088 |
|
|---|
| 2089 | @node Wildcard Pitfall, Wildcard Function, Wildcard Examples, Wildcards
|
|---|
| 2090 | @subsection Pitfalls of Using Wildcards
|
|---|
| 2091 | @cindex wildcard pitfalls
|
|---|
| 2092 | @cindex pitfalls of wildcards
|
|---|
| 2093 | @cindex mistakes with wildcards
|
|---|
| 2094 | @cindex errors with wildcards
|
|---|
| 2095 | @cindex problems with wildcards
|
|---|
| 2096 |
|
|---|
| 2097 | Now here is an example of a naive way of using wildcard expansion, that
|
|---|
| 2098 | does not do what you would intend. Suppose you would like to say that the
|
|---|
| 2099 | executable file @file{foo} is made from all the object files in the
|
|---|
| 2100 | directory, and you write this:
|
|---|
| 2101 |
|
|---|
| 2102 | @example
|
|---|
| 2103 | objects = *.o
|
|---|
| 2104 |
|
|---|
| 2105 | foo : $(objects)
|
|---|
| 2106 | cc -o foo $(CFLAGS) $(objects)
|
|---|
| 2107 | @end example
|
|---|
| 2108 |
|
|---|
| 2109 | @noindent
|
|---|
| 2110 | The value of @code{objects} is the actual string @samp{*.o}. Wildcard
|
|---|
| 2111 | expansion happens in the rule for @file{foo}, so that each @emph{existing}
|
|---|
| 2112 | @samp{.o} file becomes a prerequisite of @file{foo} and will be recompiled if
|
|---|
| 2113 | necessary.
|
|---|
| 2114 |
|
|---|
| 2115 | But what if you delete all the @samp{.o} files? When a wildcard matches
|
|---|
| 2116 | no files, it is left as it is, so then @file{foo} will depend on the
|
|---|
| 2117 | oddly-named file @file{*.o}. Since no such file is likely to exist,
|
|---|
| 2118 | @code{make} will give you an error saying it cannot figure out how to
|
|---|
| 2119 | make @file{*.o}. This is not what you want!
|
|---|
| 2120 |
|
|---|
| 2121 | Actually it is possible to obtain the desired result with wildcard
|
|---|
| 2122 | expansion, but you need more sophisticated techniques, including the
|
|---|
| 2123 | @code{wildcard} function and string substitution.
|
|---|
| 2124 | @ifnottex
|
|---|
| 2125 | @xref{Wildcard Function, ,The Function @code{wildcard}}.
|
|---|
| 2126 | @end ifnottex
|
|---|
| 2127 | @iftex
|
|---|
| 2128 | These are described in the following section.
|
|---|
| 2129 | @end iftex
|
|---|
| 2130 |
|
|---|
| 2131 | @cindex wildcards and MS-DOS/MS-Windows backslashes
|
|---|
| 2132 | @cindex backslashes in pathnames and wildcard expansion
|
|---|
| 2133 |
|
|---|
| 2134 | Microsoft operating systems (MS-DOS and MS-Windows) use backslashes to
|
|---|
| 2135 | separate directories in pathnames, like so:
|
|---|
| 2136 |
|
|---|
| 2137 | @example
|
|---|
| 2138 | c:\foo\bar\baz.c
|
|---|
| 2139 | @end example
|
|---|
| 2140 |
|
|---|
| 2141 | This is equivalent to the Unix-style @file{c:/foo/bar/baz.c} (the
|
|---|
| 2142 | @file{c:} part is the so-called drive letter). When @code{make} runs on
|
|---|
| 2143 | these systems, it supports backslashes as well as the Unix-style forward
|
|---|
| 2144 | slashes in pathnames. However, this support does @emph{not} include the
|
|---|
| 2145 | wildcard expansion, where backslash is a quote character. Therefore,
|
|---|
| 2146 | you @emph{must} use Unix-style slashes in these cases.
|
|---|
| 2147 |
|
|---|
| 2148 |
|
|---|
| 2149 | @node Wildcard Function, , Wildcard Pitfall, Wildcards
|
|---|
| 2150 | @subsection The Function @code{wildcard}
|
|---|
| 2151 | @findex wildcard
|
|---|
| 2152 |
|
|---|
| 2153 | Wildcard expansion happens automatically in rules. But wildcard expansion
|
|---|
| 2154 | does not normally take place when a variable is set, or inside the
|
|---|
| 2155 | arguments of a function. If you want to do wildcard expansion in such
|
|---|
| 2156 | places, you need to use the @code{wildcard} function, like this:
|
|---|
| 2157 |
|
|---|
| 2158 | @example
|
|---|
| 2159 | $(wildcard @var{pattern}@dots{})
|
|---|
| 2160 | @end example
|
|---|
| 2161 |
|
|---|
| 2162 | @noindent
|
|---|
| 2163 | This string, used anywhere in a makefile, is replaced by a
|
|---|
| 2164 | space-separated list of names of existing files that match one of the
|
|---|
| 2165 | given file name patterns. If no existing file name matches a pattern,
|
|---|
| 2166 | then that pattern is omitted from the output of the @code{wildcard}
|
|---|
| 2167 | function. Note that this is different from how unmatched wildcards
|
|---|
| 2168 | behave in rules, where they are used verbatim rather than ignored
|
|---|
| 2169 | (@pxref{Wildcard Pitfall}).
|
|---|
| 2170 |
|
|---|
| 2171 | One use of the @code{wildcard} function is to get a list of all the C source
|
|---|
| 2172 | files in a directory, like this:
|
|---|
| 2173 |
|
|---|
| 2174 | @example
|
|---|
| 2175 | $(wildcard *.c)
|
|---|
| 2176 | @end example
|
|---|
| 2177 |
|
|---|
| 2178 | We can change the list of C source files into a list of object files by
|
|---|
| 2179 | replacing the @samp{.c} suffix with @samp{.o} in the result, like this:
|
|---|
| 2180 |
|
|---|
| 2181 | @example
|
|---|
| 2182 | $(patsubst %.c,%.o,$(wildcard *.c))
|
|---|
| 2183 | @end example
|
|---|
| 2184 |
|
|---|
| 2185 | @noindent
|
|---|
| 2186 | (Here we have used another function, @code{patsubst}.
|
|---|
| 2187 | @xref{Text Functions, ,Functions for String Substitution and Analysis}.)@refill
|
|---|
| 2188 |
|
|---|
| 2189 | Thus, a makefile to compile all C source files in the directory and then
|
|---|
| 2190 | link them together could be written as follows:
|
|---|
| 2191 |
|
|---|
| 2192 | @example
|
|---|
| 2193 | objects := $(patsubst %.c,%.o,$(wildcard *.c))
|
|---|
| 2194 |
|
|---|
| 2195 | foo : $(objects)
|
|---|
| 2196 | cc -o foo $(objects)
|
|---|
| 2197 | @end example
|
|---|
| 2198 |
|
|---|
| 2199 | @noindent
|
|---|
| 2200 | (This takes advantage of the implicit rule for compiling C programs, so
|
|---|
| 2201 | there is no need to write explicit rules for compiling the files.
|
|---|
| 2202 | @xref{Flavors, ,The Two Flavors of Variables}, for an explanation of
|
|---|
| 2203 | @samp{:=}, which is a variant of @samp{=}.)
|
|---|
| 2204 |
|
|---|
| 2205 | @node Directory Search, Phony Targets, Wildcards, Rules
|
|---|
| 2206 | @section Searching Directories for Prerequisites
|
|---|
| 2207 | @vindex VPATH
|
|---|
| 2208 | @findex vpath
|
|---|
| 2209 | @cindex vpath
|
|---|
| 2210 | @cindex search path for prerequisites (@code{VPATH})
|
|---|
| 2211 | @cindex directory search (@code{VPATH})
|
|---|
| 2212 |
|
|---|
| 2213 | For large systems, it is often desirable to put sources in a separate
|
|---|
| 2214 | directory from the binaries. The @dfn{directory search} features of
|
|---|
| 2215 | @code{make} facilitate this by searching several directories
|
|---|
| 2216 | automatically to find a prerequisite. When you redistribute the files
|
|---|
| 2217 | among directories, you do not need to change the individual rules,
|
|---|
| 2218 | just the search paths.
|
|---|
| 2219 |
|
|---|
| 2220 | @menu
|
|---|
| 2221 | * General Search:: Specifying a search path that applies
|
|---|
| 2222 | to every prerequisite.
|
|---|
| 2223 | * Selective Search:: Specifying a search path
|
|---|
| 2224 | for a specified class of names.
|
|---|
| 2225 | * Search Algorithm:: When and how search paths are applied.
|
|---|
| 2226 | * Recipes/Search:: How to write recipes that work together
|
|---|
| 2227 | with search paths.
|
|---|
| 2228 | * Implicit/Search:: How search paths affect implicit rules.
|
|---|
| 2229 | * Libraries/Search:: Directory search for link libraries.
|
|---|
| 2230 | @end menu
|
|---|
| 2231 |
|
|---|
| 2232 | @node General Search, Selective Search, Directory Search, Directory Search
|
|---|
| 2233 | @subsection @code{VPATH}: Search Path for All Prerequisites
|
|---|
| 2234 | @vindex VPATH
|
|---|
| 2235 |
|
|---|
| 2236 | The value of the @code{make} variable @code{VPATH} specifies a list of
|
|---|
| 2237 | directories that @code{make} should search. Most often, the
|
|---|
| 2238 | directories are expected to contain prerequisite files that are not in the
|
|---|
| 2239 | current directory; however, @code{make} uses @code{VPATH} as a search
|
|---|
| 2240 | list for both prerequisites and targets of rules.
|
|---|
| 2241 |
|
|---|
| 2242 | Thus, if a file that is listed as a target or prerequisite does not exist
|
|---|
| 2243 | in the current directory, @code{make} searches the directories listed in
|
|---|
| 2244 | @code{VPATH} for a file with that name. If a file is found in one of
|
|---|
| 2245 | them, that file may become the prerequisite (see below). Rules may then
|
|---|
| 2246 | specify the names of files in the prerequisite list as if they all
|
|---|
| 2247 | existed in the current directory. @xref{Recipes/Search, ,Writing Recipes with Directory Search}.
|
|---|
| 2248 |
|
|---|
| 2249 | In the @code{VPATH} variable, directory names are separated by colons or
|
|---|
| 2250 | blanks. The order in which directories are listed is the order followed
|
|---|
| 2251 | by @code{make} in its search. (On MS-DOS and MS-Windows, semi-colons
|
|---|
| 2252 | are used as separators of directory names in @code{VPATH}, since the
|
|---|
| 2253 | colon can be used in the pathname itself, after the drive letter.)
|
|---|
| 2254 |
|
|---|
| 2255 | For example,
|
|---|
| 2256 |
|
|---|
| 2257 | @example
|
|---|
| 2258 | VPATH = src:../headers
|
|---|
| 2259 | @end example
|
|---|
| 2260 |
|
|---|
| 2261 | @noindent
|
|---|
| 2262 | specifies a path containing two directories, @file{src} and
|
|---|
| 2263 | @file{../headers}, which @code{make} searches in that order.
|
|---|
| 2264 |
|
|---|
| 2265 | With this value of @code{VPATH}, the following rule,
|
|---|
| 2266 |
|
|---|
| 2267 | @example
|
|---|
| 2268 | foo.o : foo.c
|
|---|
| 2269 | @end example
|
|---|
| 2270 |
|
|---|
| 2271 | @noindent
|
|---|
| 2272 | is interpreted as if it were written like this:
|
|---|
| 2273 |
|
|---|
| 2274 | @example
|
|---|
| 2275 | foo.o : src/foo.c
|
|---|
| 2276 | @end example
|
|---|
| 2277 |
|
|---|
| 2278 | @noindent
|
|---|
| 2279 | assuming the file @file{foo.c} does not exist in the current directory but
|
|---|
| 2280 | is found in the directory @file{src}.
|
|---|
| 2281 |
|
|---|
| 2282 | @node Selective Search, Search Algorithm, General Search, Directory Search
|
|---|
| 2283 | @subsection The @code{vpath} Directive
|
|---|
| 2284 | @findex vpath
|
|---|
| 2285 |
|
|---|
| 2286 | Similar to the @code{VPATH} variable, but more selective, is the
|
|---|
| 2287 | @code{vpath} directive (note lower case), which allows you to specify a
|
|---|
| 2288 | search path for a particular class of file names: those that match a
|
|---|
| 2289 | particular pattern. Thus you can supply certain search directories for
|
|---|
| 2290 | one class of file names and other directories (or none) for other file
|
|---|
| 2291 | names.
|
|---|
| 2292 |
|
|---|
| 2293 | There are three forms of the @code{vpath} directive:
|
|---|
| 2294 |
|
|---|
| 2295 | @table @code
|
|---|
| 2296 | @item vpath @var{pattern} @var{directories}
|
|---|
| 2297 | Specify the search path @var{directories} for file names that match
|
|---|
| 2298 | @var{pattern}.
|
|---|
| 2299 |
|
|---|
| 2300 | The search path, @var{directories}, is a list of directories to be
|
|---|
| 2301 | searched, separated by colons (semi-colons on MS-DOS and MS-Windows) or
|
|---|
| 2302 | blanks, just like the search path used in the @code{VPATH} variable.
|
|---|
| 2303 |
|
|---|
| 2304 | @item vpath @var{pattern}
|
|---|
| 2305 | Clear out the search path associated with @var{pattern}.
|
|---|
| 2306 |
|
|---|
| 2307 | @c Extra blank line makes sure this gets two lines.
|
|---|
| 2308 | @item vpath
|
|---|
| 2309 |
|
|---|
| 2310 | Clear all search paths previously specified with @code{vpath} directives.
|
|---|
| 2311 | @end table
|
|---|
| 2312 |
|
|---|
| 2313 | A @code{vpath} pattern is a string containing a @samp{%} character. The
|
|---|
| 2314 | string must match the file name of a prerequisite that is being searched
|
|---|
| 2315 | for, the @samp{%} character matching any sequence of zero or more
|
|---|
| 2316 | characters (as in pattern rules; @pxref{Pattern Rules, ,Defining and
|
|---|
| 2317 | Redefining Pattern Rules}). For example, @code{%.h} matches files that
|
|---|
| 2318 | end in @code{.h}. (If there is no @samp{%}, the pattern must match the
|
|---|
| 2319 | prerequisite exactly, which is not useful very often.)
|
|---|
| 2320 |
|
|---|
| 2321 | @cindex @code{%}, quoting in @code{vpath}
|
|---|
| 2322 | @cindex @code{%}, quoting with @code{\} (backslash)
|
|---|
| 2323 | @cindex @code{\} (backslash), to quote @code{%}
|
|---|
| 2324 | @cindex backslash (@code{\}), to quote @code{%}
|
|---|
| 2325 | @cindex quoting @code{%}, in @code{vpath}
|
|---|
| 2326 | @samp{%} characters in a @code{vpath} directive's pattern can be quoted
|
|---|
| 2327 | with preceding backslashes (@samp{\}). Backslashes that would otherwise
|
|---|
| 2328 | quote @samp{%} characters can be quoted with more backslashes.
|
|---|
| 2329 | Backslashes that quote @samp{%} characters or other backslashes are
|
|---|
| 2330 | removed from the pattern before it is compared to file names. Backslashes
|
|---|
| 2331 | that are not in danger of quoting @samp{%} characters go unmolested.@refill
|
|---|
| 2332 |
|
|---|
| 2333 | When a prerequisite fails to exist in the current directory, if the
|
|---|
| 2334 | @var{pattern} in a @code{vpath} directive matches the name of the
|
|---|
| 2335 | prerequisite file, then the @var{directories} in that directive are searched
|
|---|
| 2336 | just like (and before) the directories in the @code{VPATH} variable.
|
|---|
| 2337 |
|
|---|
| 2338 | For example,
|
|---|
| 2339 |
|
|---|
| 2340 | @example
|
|---|
| 2341 | vpath %.h ../headers
|
|---|
| 2342 | @end example
|
|---|
| 2343 |
|
|---|
| 2344 | @noindent
|
|---|
| 2345 | tells @code{make} to look for any prerequisite whose name ends in @file{.h}
|
|---|
| 2346 | in the directory @file{../headers} if the file is not found in the current
|
|---|
| 2347 | directory.
|
|---|
| 2348 |
|
|---|
| 2349 | If several @code{vpath} patterns match the prerequisite file's name, then
|
|---|
| 2350 | @code{make} processes each matching @code{vpath} directive one by one,
|
|---|
| 2351 | searching all the directories mentioned in each directive. @code{make}
|
|---|
| 2352 | handles multiple @code{vpath} directives in the order in which they
|
|---|
| 2353 | appear in the makefile; multiple directives with the same pattern are
|
|---|
| 2354 | independent of each other.
|
|---|
| 2355 |
|
|---|
| 2356 | @need 750
|
|---|
| 2357 | Thus,
|
|---|
| 2358 |
|
|---|
| 2359 | @example
|
|---|
| 2360 | @group
|
|---|
| 2361 | vpath %.c foo
|
|---|
| 2362 | vpath % blish
|
|---|
| 2363 | vpath %.c bar
|
|---|
| 2364 | @end group
|
|---|
| 2365 | @end example
|
|---|
| 2366 |
|
|---|
| 2367 | @noindent
|
|---|
| 2368 | will look for a file ending in @samp{.c} in @file{foo}, then
|
|---|
| 2369 | @file{blish}, then @file{bar}, while
|
|---|
| 2370 |
|
|---|
| 2371 | @example
|
|---|
| 2372 | @group
|
|---|
| 2373 | vpath %.c foo:bar
|
|---|
| 2374 | vpath % blish
|
|---|
| 2375 | @end group
|
|---|
| 2376 | @end example
|
|---|
| 2377 |
|
|---|
| 2378 | @noindent
|
|---|
| 2379 | will look for a file ending in @samp{.c} in @file{foo}, then
|
|---|
| 2380 | @file{bar}, then @file{blish}.
|
|---|
| 2381 |
|
|---|
| 2382 | @node Search Algorithm, Recipes/Search, Selective Search, Directory Search
|
|---|
| 2383 | @subsection How Directory Searches are Performed
|
|---|
| 2384 | @cindex algorithm for directory search
|
|---|
| 2385 | @cindex directory search algorithm
|
|---|
| 2386 |
|
|---|
| 2387 | When a prerequisite is found through directory search, regardless of type
|
|---|
| 2388 | (general or selective), the pathname located may not be the one that
|
|---|
| 2389 | @code{make} actually provides you in the prerequisite list. Sometimes
|
|---|
| 2390 | the path discovered through directory search is thrown away.
|
|---|
| 2391 |
|
|---|
| 2392 | The algorithm @code{make} uses to decide whether to keep or abandon a
|
|---|
| 2393 | path found via directory search is as follows:
|
|---|
| 2394 |
|
|---|
| 2395 | @enumerate
|
|---|
| 2396 | @item
|
|---|
| 2397 | If a target file does not exist at the path specified in the makefile,
|
|---|
| 2398 | directory search is performed.
|
|---|
| 2399 |
|
|---|
| 2400 | @item
|
|---|
| 2401 | If the directory search is successful, that path is kept and this file
|
|---|
| 2402 | is tentatively stored as the target.
|
|---|
| 2403 |
|
|---|
| 2404 | @item
|
|---|
| 2405 | All prerequisites of this target are examined using this same method.
|
|---|
| 2406 |
|
|---|
| 2407 | @item
|
|---|
| 2408 | After processing the prerequisites, the target may or may not need to be
|
|---|
| 2409 | rebuilt:
|
|---|
| 2410 |
|
|---|
| 2411 | @enumerate a
|
|---|
| 2412 | @item
|
|---|
| 2413 | If the target does @emph{not} need to be rebuilt, the path to the file
|
|---|
| 2414 | found during directory search is used for any prerequisite lists which
|
|---|
| 2415 | contain this target. In short, if @code{make} doesn't need to rebuild
|
|---|
| 2416 | the target then you use the path found via directory search.
|
|---|
| 2417 |
|
|---|
| 2418 | @item
|
|---|
| 2419 | If the target @emph{does} need to be rebuilt (is out-of-date), the
|
|---|
| 2420 | pathname found during directory search is @emph{thrown away}, and the
|
|---|
| 2421 | target is rebuilt using the file name specified in the makefile. In
|
|---|
| 2422 | short, if @code{make} must rebuild, then the target is rebuilt locally,
|
|---|
| 2423 | not in the directory found via directory search.
|
|---|
| 2424 | @end enumerate
|
|---|
| 2425 | @end enumerate
|
|---|
| 2426 |
|
|---|
| 2427 | This algorithm may seem complex, but in practice it is quite often
|
|---|
| 2428 | exactly what you want.
|
|---|
| 2429 |
|
|---|
| 2430 | @cindex traditional directory search (GPATH)
|
|---|
| 2431 | @cindex directory search, traditional (GPATH)
|
|---|
| 2432 | Other versions of @code{make} use a simpler algorithm: if the file does
|
|---|
| 2433 | not exist, and it is found via directory search, then that pathname is
|
|---|
| 2434 | always used whether or not the target needs to be built. Thus, if the
|
|---|
| 2435 | target is rebuilt it is created at the pathname discovered during
|
|---|
| 2436 | directory search.
|
|---|
| 2437 |
|
|---|
| 2438 | @vindex GPATH
|
|---|
| 2439 | If, in fact, this is the behavior you want for some or all of your
|
|---|
| 2440 | directories, you can use the @code{GPATH} variable to indicate this to
|
|---|
| 2441 | @code{make}.
|
|---|
| 2442 |
|
|---|
| 2443 | @code{GPATH} has the same syntax and format as @code{VPATH} (that is, a
|
|---|
| 2444 | space- or colon-delimited list of pathnames). If an out-of-date target
|
|---|
| 2445 | is found by directory search in a directory that also appears in
|
|---|
| 2446 | @code{GPATH}, then that pathname is not thrown away. The target is
|
|---|
| 2447 | rebuilt using the expanded path.
|
|---|
| 2448 |
|
|---|
| 2449 | @node Recipes/Search, Implicit/Search, Search Algorithm, Directory Search
|
|---|
| 2450 | @subsection Writing Recipes with Directory Search
|
|---|
| 2451 | @cindex recipes, and directory search
|
|---|
| 2452 | @cindex directory search (@code{VPATH}), and recipes
|
|---|
| 2453 |
|
|---|
| 2454 | When a prerequisite is found in another directory through directory search,
|
|---|
| 2455 | this cannot change the recipe of the rule; they will execute as written.
|
|---|
| 2456 | Therefore, you must write the recipe with care so that it will look for
|
|---|
| 2457 | the prerequisite in the directory where @code{make} finds it.
|
|---|
| 2458 |
|
|---|
| 2459 | This is done with the @dfn{automatic variables} such as @samp{$^}
|
|---|
| 2460 | (@pxref{Automatic Variables}).
|
|---|
| 2461 | For instance, the value of @samp{$^} is a
|
|---|
| 2462 | list of all the prerequisites of the rule, including the names of
|
|---|
| 2463 | the directories in which they were found, and the value of
|
|---|
| 2464 | @samp{$@@} is the target. Thus:@refill
|
|---|
| 2465 |
|
|---|
| 2466 | @example
|
|---|
| 2467 | foo.o : foo.c
|
|---|
| 2468 | cc -c $(CFLAGS) $^ -o $@@
|
|---|
| 2469 | @end example
|
|---|
| 2470 |
|
|---|
| 2471 | @noindent
|
|---|
| 2472 | (The variable @code{CFLAGS} exists so you can specify flags for C
|
|---|
| 2473 | compilation by implicit rules; we use it here for consistency so it will
|
|---|
| 2474 | affect all C compilations uniformly;
|
|---|
| 2475 | @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.)
|
|---|
| 2476 |
|
|---|
| 2477 | Often the prerequisites include header files as well, which you do not
|
|---|
| 2478 | want to mention in the recipe. The automatic variable @samp{$<} is
|
|---|
| 2479 | just the first prerequisite:
|
|---|
| 2480 |
|
|---|
| 2481 | @example
|
|---|
| 2482 | VPATH = src:../headers
|
|---|
| 2483 | foo.o : foo.c defs.h hack.h
|
|---|
| 2484 | cc -c $(CFLAGS) $< -o $@@
|
|---|
| 2485 | @end example
|
|---|
| 2486 |
|
|---|
| 2487 | @node Implicit/Search, Libraries/Search, Recipes/Search, Directory Search
|
|---|
| 2488 | @subsection Directory Search and Implicit Rules
|
|---|
| 2489 | @cindex @code{VPATH}, and implicit rules
|
|---|
| 2490 | @cindex directory search (@code{VPATH}), and implicit rules
|
|---|
| 2491 | @cindex search path for prerequisites (@code{VPATH}), and implicit rules
|
|---|
| 2492 | @cindex implicit rule, and directory search
|
|---|
| 2493 | @cindex implicit rule, and @code{VPATH}
|
|---|
| 2494 | @cindex rule, implicit, and directory search
|
|---|
| 2495 | @cindex rule, implicit, and @code{VPATH}
|
|---|
| 2496 |
|
|---|
| 2497 | The search through the directories specified in @code{VPATH} or with
|
|---|
| 2498 | @code{vpath} also happens during consideration of implicit rules
|
|---|
| 2499 | (@pxref{Implicit Rules, ,Using Implicit Rules}).
|
|---|
| 2500 |
|
|---|
| 2501 | For example, when a file @file{foo.o} has no explicit rule, @code{make}
|
|---|
| 2502 | considers implicit rules, such as the built-in rule to compile
|
|---|
| 2503 | @file{foo.c} if that file exists. If such a file is lacking in the
|
|---|
| 2504 | current directory, the appropriate directories are searched for it. If
|
|---|
| 2505 | @file{foo.c} exists (or is mentioned in the makefile) in any of the
|
|---|
| 2506 | directories, the implicit rule for C compilation is applied.
|
|---|
| 2507 |
|
|---|
| 2508 | The recipes of implicit rules normally use automatic variables as a
|
|---|
| 2509 | matter of necessity; consequently they will use the file names found by
|
|---|
| 2510 | directory search with no extra effort.
|
|---|
| 2511 |
|
|---|
| 2512 | @node Libraries/Search, , Implicit/Search, Directory Search
|
|---|
| 2513 | @subsection Directory Search for Link Libraries
|
|---|
| 2514 | @cindex link libraries, and directory search
|
|---|
| 2515 | @cindex libraries for linking, directory search
|
|---|
| 2516 | @cindex directory search (@code{VPATH}), and link libraries
|
|---|
| 2517 | @cindex @code{VPATH}, and link libraries
|
|---|
| 2518 | @cindex search path for prerequisites (@code{VPATH}), and link libraries
|
|---|
| 2519 | @cindex @code{-l} (library search)
|
|---|
| 2520 | @cindex link libraries, patterns matching
|
|---|
| 2521 | @cindex @code{.LIBPATTERNS}, and link libraries
|
|---|
| 2522 | @vindex .LIBPATTERNS
|
|---|
| 2523 |
|
|---|
| 2524 | Directory search applies in a special way to libraries used with the
|
|---|
| 2525 | linker. This special feature comes into play when you write a prerequisite
|
|---|
| 2526 | whose name is of the form @samp{-l@var{name}}. (You can tell something
|
|---|
| 2527 | strange is going on here because the prerequisite is normally the name of a
|
|---|
| 2528 | file, and the @emph{file name} of a library generally looks like
|
|---|
| 2529 | @file{lib@var{name}.a}, not like @samp{-l@var{name}}.)@refill
|
|---|
| 2530 |
|
|---|
| 2531 | When a prerequisite's name has the form @samp{-l@var{name}}, @code{make}
|
|---|
| 2532 | handles it specially by searching for the file @file{lib@var{name}.so},
|
|---|
| 2533 | and, if it is not found, for the file @file{lib@var{name}.a} in the current
|
|---|
| 2534 | directory, in directories specified by matching @code{vpath}
|
|---|
| 2535 | search paths and the @code{VPATH} search path, and then in the
|
|---|
| 2536 | directories @file{/lib}, @file{/usr/lib}, and @file{@var{prefix}/lib}
|
|---|
| 2537 | (normally @file{/usr/local/lib}, but MS-DOS/MS-Windows versions of
|
|---|
| 2538 | @code{make} behave as if @var{prefix} is defined to be the root of the
|
|---|
| 2539 | DJGPP installation tree).
|
|---|
| 2540 |
|
|---|
| 2541 | For example, if there is a @file{/usr/lib/libcurses.a} library on your
|
|---|
| 2542 | system (and no @file{/usr/lib/libcurses.so} file), then
|
|---|
| 2543 |
|
|---|
| 2544 | @example
|
|---|
| 2545 | @group
|
|---|
| 2546 | foo : foo.c -lcurses
|
|---|
| 2547 | cc $^ -o $@@
|
|---|
| 2548 | @end group
|
|---|
| 2549 | @end example
|
|---|
| 2550 |
|
|---|
| 2551 | @noindent
|
|---|
| 2552 | would cause the command @samp{cc foo.c /usr/lib/libcurses.a -o foo} to
|
|---|
| 2553 | be executed when @file{foo} is older than @file{foo.c} or than
|
|---|
| 2554 | @file{/usr/lib/libcurses.a}.@refill
|
|---|
| 2555 |
|
|---|
| 2556 | Although the default set of files to be searched for is
|
|---|
| 2557 | @file{lib@var{name}.so} and @file{lib@var{name}.a}, this is customizable
|
|---|
| 2558 | via the @code{.LIBPATTERNS} variable. Each word in the value of this
|
|---|
| 2559 | variable is a pattern string. When a prerequisite like
|
|---|
| 2560 | @samp{-l@var{name}} is seen, @code{make} will replace the percent in
|
|---|
| 2561 | each pattern in the list with @var{name} and perform the above directory
|
|---|
| 2562 | searches using each library file name.
|
|---|
| 2563 |
|
|---|
| 2564 | The default value for @code{.LIBPATTERNS} is @samp{lib%.so lib%.a},
|
|---|
| 2565 | which provides the default behavior described above.
|
|---|
| 2566 |
|
|---|
| 2567 | You can turn off link library expansion completely by setting this
|
|---|
| 2568 | variable to an empty value.
|
|---|
| 2569 |
|
|---|
| 2570 | @node Phony Targets, Force Targets, Directory Search, Rules
|
|---|
| 2571 | @section Phony Targets
|
|---|
| 2572 | @cindex phony targets
|
|---|
| 2573 | @cindex targets, phony
|
|---|
| 2574 | @cindex targets without a file
|
|---|
| 2575 |
|
|---|
| 2576 | A phony target is one that is not really the name of a file; rather it
|
|---|
| 2577 | is just a name for a recipe to be executed when you make an explicit
|
|---|
| 2578 | request. There are two reasons to use a phony target: to avoid a
|
|---|
| 2579 | conflict with a file of the same name, and to improve performance.
|
|---|
| 2580 |
|
|---|
| 2581 | If you write a rule whose recipe will not create the target file, the
|
|---|
| 2582 | recipe will be executed every time the target comes up for remaking.
|
|---|
| 2583 | Here is an example:
|
|---|
| 2584 |
|
|---|
| 2585 | @example
|
|---|
| 2586 | @group
|
|---|
| 2587 | clean:
|
|---|
| 2588 | rm *.o temp
|
|---|
| 2589 | @end group
|
|---|
| 2590 | @end example
|
|---|
| 2591 |
|
|---|
| 2592 | @noindent
|
|---|
| 2593 | Because the @code{rm} command does not create a file named @file{clean},
|
|---|
| 2594 | probably no such file will ever exist. Therefore, the @code{rm} command
|
|---|
| 2595 | will be executed every time you say @samp{make clean}.
|
|---|
| 2596 | @cindex @code{rm} (shell command)
|
|---|
| 2597 |
|
|---|
| 2598 | @findex .PHONY
|
|---|
| 2599 | In this example, the @file{clean} target will not work properly if a
|
|---|
| 2600 | file named @file{clean} is ever created in this directory. Since it
|
|---|
| 2601 | has no prerequisites, @file{clean} would always be considered up to
|
|---|
| 2602 | date and its recipe would not be executed. To avoid this problem you
|
|---|
| 2603 | can explicitly declare the target to be phony by making it a
|
|---|
| 2604 | prerequisite of the special target @code{.PHONY}
|
|---|
| 2605 | (@pxref{Special Targets, ,Special Built-in Target Names}) as follows:
|
|---|
| 2606 |
|
|---|
| 2607 | @example
|
|---|
| 2608 | @group
|
|---|
| 2609 | .PHONY: clean
|
|---|
| 2610 | clean:
|
|---|
| 2611 | rm *.o temp
|
|---|
| 2612 | @end group
|
|---|
| 2613 | @end example
|
|---|
| 2614 |
|
|---|
| 2615 | @noindent
|
|---|
| 2616 | Once this is done, @samp{make clean} will run the recipe regardless of
|
|---|
| 2617 | whether there is a file named @file{clean}.
|
|---|
| 2618 |
|
|---|
| 2619 | Phony targets are also useful in conjunction with recursive
|
|---|
| 2620 | invocations of @code{make} (@pxref{Recursion, ,Recursive Use of @code{make}}).
|
|---|
| 2621 | In this situation the makefile will often contain a variable which
|
|---|
| 2622 | lists a number of sub-directories to be built. A simplistic way to
|
|---|
| 2623 | handle this is to define one rule with a recipe that loops over the
|
|---|
| 2624 | sub-directories, like this:
|
|---|
| 2625 |
|
|---|
| 2626 | @example
|
|---|
| 2627 | @group
|
|---|
| 2628 | SUBDIRS = foo bar baz
|
|---|
| 2629 |
|
|---|
| 2630 | subdirs:
|
|---|
| 2631 | for dir in $(SUBDIRS); do \
|
|---|
| 2632 | $(MAKE) -C $$dir; \
|
|---|
| 2633 | done
|
|---|
| 2634 | @end group
|
|---|
| 2635 | @end example
|
|---|
| 2636 |
|
|---|
| 2637 | There are problems with this method, however. First, any error
|
|---|
| 2638 | detected in a sub-make is ignored by this rule, so it will continue
|
|---|
| 2639 | to build the rest of the directories even when one fails. This can be
|
|---|
| 2640 | overcome by adding shell commands to note the error and exit, but then
|
|---|
| 2641 | it will do so even if @code{make} is invoked with the @code{-k}
|
|---|
| 2642 | option, which is unfortunate. Second, and perhaps more importantly,
|
|---|
| 2643 | you cannot take advantage of @code{make}'s ability to build targets in
|
|---|
| 2644 | parallel (@pxref{Parallel, ,Parallel Execution}), since there is only
|
|---|
| 2645 | one rule.
|
|---|
| 2646 |
|
|---|
| 2647 | By declaring the sub-directories as @code{.PHONY} targets (you must do
|
|---|
| 2648 | this as the sub-directory obviously always exists; otherwise it won't
|
|---|
| 2649 | be built) you can remove these problems:
|
|---|
| 2650 |
|
|---|
| 2651 | @example
|
|---|
| 2652 | @group
|
|---|
| 2653 | SUBDIRS = foo bar baz
|
|---|
| 2654 |
|
|---|
| 2655 | .PHONY: subdirs $(SUBDIRS)
|
|---|
| 2656 |
|
|---|
| 2657 | subdirs: $(SUBDIRS)
|
|---|
| 2658 |
|
|---|
| 2659 | $(SUBDIRS):
|
|---|
| 2660 | $(MAKE) -C $@@
|
|---|
| 2661 |
|
|---|
| 2662 | foo: baz
|
|---|
| 2663 | @end group
|
|---|
| 2664 | @end example
|
|---|
| 2665 |
|
|---|
| 2666 | Here we've also declared that the @file{foo} sub-directory cannot be
|
|---|
| 2667 | built until after the @file{baz} sub-directory is complete; this kind of
|
|---|
| 2668 | relationship declaration is particularly important when attempting
|
|---|
| 2669 | parallel builds.
|
|---|
| 2670 |
|
|---|
| 2671 | The implicit rule search (@pxref{Implicit Rules}) is skipped for
|
|---|
| 2672 | @code{.PHONY} targets. This is why declaring a target as
|
|---|
| 2673 | @code{.PHONY} is good for performance, even if you are not worried
|
|---|
| 2674 | about the actual file existing.
|
|---|
| 2675 |
|
|---|
| 2676 | A phony target should not be a prerequisite of a real target file; if it
|
|---|
| 2677 | is, its recipe will be run every time @code{make} goes to update that
|
|---|
| 2678 | file. As long as a phony target is never a prerequisite of a real
|
|---|
| 2679 | target, the phony target recipe will be executed only when the phony
|
|---|
| 2680 | target is a specified goal (@pxref{Goals, ,Arguments to Specify the
|
|---|
| 2681 | Goals}).
|
|---|
| 2682 |
|
|---|
| 2683 | Phony targets can have prerequisites. When one directory contains multiple
|
|---|
| 2684 | programs, it is most convenient to describe all of the programs in one
|
|---|
| 2685 | makefile @file{./Makefile}. Since the target remade by default will be the
|
|---|
| 2686 | first one in the makefile, it is common to make this a phony target named
|
|---|
| 2687 | @samp{all} and give it, as prerequisites, all the individual programs. For
|
|---|
| 2688 | example:
|
|---|
| 2689 |
|
|---|
| 2690 | @example
|
|---|
| 2691 | all : prog1 prog2 prog3
|
|---|
| 2692 | .PHONY : all
|
|---|
| 2693 |
|
|---|
| 2694 | prog1 : prog1.o utils.o
|
|---|
| 2695 | cc -o prog1 prog1.o utils.o
|
|---|
| 2696 |
|
|---|
| 2697 | prog2 : prog2.o
|
|---|
| 2698 | cc -o prog2 prog2.o
|
|---|
| 2699 |
|
|---|
| 2700 | prog3 : prog3.o sort.o utils.o
|
|---|
| 2701 | cc -o prog3 prog3.o sort.o utils.o
|
|---|
| 2702 | @end example
|
|---|
| 2703 |
|
|---|
| 2704 | @noindent
|
|---|
| 2705 | Now you can say just @samp{make} to remake all three programs, or
|
|---|
| 2706 | specify as arguments the ones to remake (as in @samp{make prog1
|
|---|
| 2707 | prog3}). Phoniness is not inherited: the prerequisites of a phony
|
|---|
| 2708 | target are not themselves phony, unless explicitly declared to be so.
|
|---|
| 2709 |
|
|---|
| 2710 | When one phony target is a prerequisite of another, it serves as a subroutine
|
|---|
| 2711 | of the other. For example, here @samp{make cleanall} will delete the
|
|---|
| 2712 | object files, the difference files, and the file @file{program}:
|
|---|
| 2713 |
|
|---|
| 2714 | @example
|
|---|
| 2715 | .PHONY: cleanall cleanobj cleandiff
|
|---|
| 2716 |
|
|---|
| 2717 | cleanall : cleanobj cleandiff
|
|---|
| 2718 | rm program
|
|---|
| 2719 |
|
|---|
| 2720 | cleanobj :
|
|---|
| 2721 | rm *.o
|
|---|
| 2722 |
|
|---|
| 2723 | cleandiff :
|
|---|
| 2724 | rm *.diff
|
|---|
| 2725 | @end example
|
|---|
| 2726 |
|
|---|
| 2727 | @node Force Targets, Empty Targets, Phony Targets, Rules
|
|---|
| 2728 | @section Rules without Recipes or Prerequisites
|
|---|
| 2729 | @cindex force targets
|
|---|
| 2730 | @cindex targets, force
|
|---|
| 2731 | @cindex @code{FORCE}
|
|---|
| 2732 | @cindex rule, no recipe or prerequisites
|
|---|
| 2733 |
|
|---|
| 2734 | If a rule has no prerequisites or recipe, and the target of the rule
|
|---|
| 2735 | is a nonexistent file, then @code{make} imagines this target to have
|
|---|
| 2736 | been updated whenever its rule is run. This implies that all targets
|
|---|
| 2737 | depending on this one will always have their recipe run.
|
|---|
| 2738 |
|
|---|
| 2739 | An example will illustrate this:
|
|---|
| 2740 |
|
|---|
| 2741 | @example
|
|---|
| 2742 | @group
|
|---|
| 2743 | clean: FORCE
|
|---|
| 2744 | rm $(objects)
|
|---|
| 2745 | FORCE:
|
|---|
| 2746 | @end group
|
|---|
| 2747 | @end example
|
|---|
| 2748 |
|
|---|
| 2749 | Here the target @samp{FORCE} satisfies the special conditions, so the
|
|---|
| 2750 | target @file{clean} that depends on it is forced to run its recipe.
|
|---|
| 2751 | There is nothing special about the name @samp{FORCE}, but that is one
|
|---|
| 2752 | name commonly used this way.
|
|---|
| 2753 |
|
|---|
| 2754 | As you can see, using @samp{FORCE} this way has the same results as using
|
|---|
| 2755 | @samp{.PHONY: clean}.
|
|---|
| 2756 |
|
|---|
| 2757 | Using @samp{.PHONY} is more explicit and more efficient. However,
|
|---|
| 2758 | other versions of @code{make} do not support @samp{.PHONY}; thus
|
|---|
| 2759 | @samp{FORCE} appears in many makefiles. @xref{Phony Targets}.
|
|---|
| 2760 |
|
|---|
| 2761 | @node Empty Targets, Special Targets, Force Targets, Rules
|
|---|
| 2762 | @section Empty Target Files to Record Events
|
|---|
| 2763 | @cindex empty targets
|
|---|
| 2764 | @cindex targets, empty
|
|---|
| 2765 | @cindex recording events with empty targets
|
|---|
| 2766 |
|
|---|
| 2767 | The @dfn{empty target} is a variant of the phony target; it is used to hold
|
|---|
| 2768 | recipes for an action that you request explicitly from time to time.
|
|---|
| 2769 | Unlike a phony target, this target file can really exist; but the file's
|
|---|
| 2770 | contents do not matter, and usually are empty.
|
|---|
| 2771 |
|
|---|
| 2772 | The purpose of the empty target file is to record, with its
|
|---|
| 2773 | last-modification time, when the rule's recipe was last executed. It
|
|---|
| 2774 | does so because one of the commands in the recipe is a @code{touch}
|
|---|
| 2775 | command to update the target file.
|
|---|
| 2776 |
|
|---|
| 2777 | The empty target file should have some prerequisites (otherwise it
|
|---|
| 2778 | doesn't make sense). When you ask to remake the empty target, the
|
|---|
| 2779 | recipe is executed if any prerequisite is more recent than the target;
|
|---|
| 2780 | in other words, if a prerequisite has changed since the last time you
|
|---|
| 2781 | remade the target. Here is an example:
|
|---|
| 2782 |
|
|---|
| 2783 | @example
|
|---|
| 2784 | print: foo.c bar.c
|
|---|
| 2785 | lpr -p $?
|
|---|
| 2786 | touch print
|
|---|
| 2787 | @end example
|
|---|
| 2788 | @cindex @code{print} target
|
|---|
| 2789 | @cindex @code{lpr} (shell command)
|
|---|
| 2790 | @cindex @code{touch} (shell command)
|
|---|
| 2791 |
|
|---|
| 2792 | @noindent
|
|---|
| 2793 | With this rule, @samp{make print} will execute the @code{lpr} command if
|
|---|
| 2794 | either source file has changed since the last @samp{make print}. The
|
|---|
| 2795 | automatic variable @samp{$?} is used to print only those files that have
|
|---|
| 2796 | changed (@pxref{Automatic Variables}).
|
|---|
| 2797 |
|
|---|
| 2798 | @node Special Targets, Multiple Targets, Empty Targets, Rules
|
|---|
| 2799 | @section Special Built-in Target Names
|
|---|
| 2800 | @cindex special targets
|
|---|
| 2801 | @cindex built-in special targets
|
|---|
| 2802 | @cindex targets, built-in special
|
|---|
| 2803 |
|
|---|
| 2804 | Certain names have special meanings if they appear as targets.
|
|---|
| 2805 |
|
|---|
| 2806 | @table @code
|
|---|
| 2807 | @findex .PHONY
|
|---|
| 2808 | @item .PHONY
|
|---|
| 2809 |
|
|---|
| 2810 | The prerequisites of the special target @code{.PHONY} are considered to
|
|---|
| 2811 | be phony targets. When it is time to consider such a target,
|
|---|
| 2812 | @code{make} will run its recipe unconditionally, regardless of
|
|---|
| 2813 | whether a file with that name exists or what its last-modification
|
|---|
| 2814 | time is. @xref{Phony Targets, ,Phony Targets}.
|
|---|
| 2815 |
|
|---|
| 2816 | @findex .SUFFIXES
|
|---|
| 2817 | @item .SUFFIXES
|
|---|
| 2818 |
|
|---|
| 2819 | The prerequisites of the special target @code{.SUFFIXES} are the list
|
|---|
| 2820 | of suffixes to be used in checking for suffix rules.
|
|---|
| 2821 | @xref{Suffix Rules, , Old-Fashioned Suffix Rules}.
|
|---|
| 2822 |
|
|---|
| 2823 | @findex .DEFAULT
|
|---|
| 2824 | @item .DEFAULT
|
|---|
| 2825 |
|
|---|
| 2826 | The recipe specified for @code{.DEFAULT} is used for any target for
|
|---|
| 2827 | which no rules are found (either explicit rules or implicit rules).
|
|---|
| 2828 | @xref{Last Resort}. If a @code{.DEFAULT} recipe is specified, every
|
|---|
| 2829 | file mentioned as a prerequisite, but not as a target in a rule, will have
|
|---|
| 2830 | that recipe executed on its behalf. @xref{Implicit Rule Search,
|
|---|
| 2831 | ,Implicit Rule Search Algorithm}.
|
|---|
| 2832 |
|
|---|
| 2833 | @findex .PRECIOUS
|
|---|
| 2834 | @item .PRECIOUS
|
|---|
| 2835 | @cindex precious targets
|
|---|
| 2836 | @cindex preserving with @code{.PRECIOUS}
|
|---|
| 2837 |
|
|---|
| 2838 | The targets which @code{.PRECIOUS} depends on are given the following
|
|---|
| 2839 | special treatment: if @code{make} is killed or interrupted during the
|
|---|
| 2840 | execution of their recipes, the target is not deleted.
|
|---|
| 2841 | @xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the
|
|---|
| 2842 | target is an intermediate file, it will not be deleted after it is no
|
|---|
| 2843 | longer needed, as is normally done. @xref{Chained Rules, ,Chains of
|
|---|
| 2844 | Implicit Rules}. In this latter respect it overlaps with the
|
|---|
| 2845 | @code{.SECONDARY} special target.
|
|---|
| 2846 |
|
|---|
| 2847 | You can also list the target pattern of an implicit rule (such as
|
|---|
| 2848 | @samp{%.o}) as a prerequisite file of the special target @code{.PRECIOUS}
|
|---|
| 2849 | to preserve intermediate files created by rules whose target patterns
|
|---|
| 2850 | match that file's name.
|
|---|
| 2851 |
|
|---|
| 2852 | @findex .INTERMEDIATE
|
|---|
| 2853 | @item .INTERMEDIATE
|
|---|
| 2854 | @cindex intermediate targets, explicit
|
|---|
| 2855 |
|
|---|
| 2856 | The targets which @code{.INTERMEDIATE} depends on are treated as
|
|---|
| 2857 | intermediate files. @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 2858 | @code{.INTERMEDIATE} with no prerequisites has no effect.
|
|---|
| 2859 |
|
|---|
| 2860 | @findex .SECONDARY
|
|---|
| 2861 | @item .SECONDARY
|
|---|
| 2862 | @cindex secondary targets
|
|---|
| 2863 | @cindex preserving with @code{.SECONDARY}
|
|---|
| 2864 |
|
|---|
| 2865 | The targets which @code{.SECONDARY} depends on are treated as
|
|---|
| 2866 | intermediate files, except that they are never automatically deleted.
|
|---|
| 2867 | @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 2868 |
|
|---|
| 2869 | @code{.SECONDARY} with no prerequisites causes all targets to be treated
|
|---|
| 2870 | as secondary (i.e., no target is removed because it is considered
|
|---|
| 2871 | intermediate).
|
|---|
| 2872 |
|
|---|
| 2873 | @findex .SECONDEXPANSION
|
|---|
| 2874 | @item .SECONDEXPANSION
|
|---|
| 2875 |
|
|---|
| 2876 | If @code{.SECONDEXPANSION} is mentioned as a target anywhere in the
|
|---|
| 2877 | makefile, then all prerequisite lists defined @emph{after} it appears
|
|---|
| 2878 | will be expanded a second time after all makefiles have been read in.
|
|---|
| 2879 | @xref{Secondary Expansion, ,Secondary Expansion}.
|
|---|
| 2880 |
|
|---|
| 2881 | @findex .DELETE_ON_ERROR
|
|---|
| 2882 | @item .DELETE_ON_ERROR
|
|---|
| 2883 | @cindex removing targets on failure
|
|---|
| 2884 |
|
|---|
| 2885 | If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the
|
|---|
| 2886 | makefile, then @code{make} will delete the target of a rule if it has
|
|---|
| 2887 | changed and its recipe exits with a nonzero exit status, just as it
|
|---|
| 2888 | does when it receives a signal. @xref{Errors, ,Errors in Recipes}.
|
|---|
| 2889 |
|
|---|
| 2890 | @findex .IGNORE
|
|---|
| 2891 | @item .IGNORE
|
|---|
| 2892 |
|
|---|
| 2893 | If you specify prerequisites for @code{.IGNORE}, then @code{make} will
|
|---|
| 2894 | ignore errors in execution of the recipe for those particular files.
|
|---|
| 2895 | The recipe for @code{.IGNORE} (if any) is ignored.
|
|---|
| 2896 |
|
|---|
| 2897 | If mentioned as a target with no prerequisites, @code{.IGNORE} says to
|
|---|
| 2898 | ignore errors in execution of recipes for all files. This usage of
|
|---|
| 2899 | @samp{.IGNORE} is supported only for historical compatibility. Since
|
|---|
| 2900 | this affects every recipe in the makefile, it is not very useful; we
|
|---|
| 2901 | recommend you use the more selective ways to ignore errors in specific
|
|---|
| 2902 | recipes. @xref{Errors, ,Errors in Recipes}.
|
|---|
| 2903 |
|
|---|
| 2904 | @findex .LOW_RESOLUTION_TIME
|
|---|
| 2905 | @item .LOW_RESOLUTION_TIME
|
|---|
| 2906 |
|
|---|
| 2907 | If you specify prerequisites for @code{.LOW_RESOLUTION_TIME},
|
|---|
| 2908 | @command{make} assumes that these files are created by commands that
|
|---|
| 2909 | generate low resolution time stamps. The recipe for the
|
|---|
| 2910 | @code{.LOW_RESOLUTION_TIME} target are ignored.
|
|---|
| 2911 |
|
|---|
| 2912 | The high resolution file time stamps of many modern file systems
|
|---|
| 2913 | lessen the chance of @command{make} incorrectly concluding that a file
|
|---|
| 2914 | is up to date. Unfortunately, some hosts do not provide a way to set a
|
|---|
| 2915 | high resolution file time stamp, so commands like @samp{cp -p} that
|
|---|
| 2916 | explicitly set a file's time stamp must discard its sub-second part.
|
|---|
| 2917 | If a file is created by such a command, you should list it as a
|
|---|
| 2918 | prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make}
|
|---|
| 2919 | does not mistakenly conclude that the file is out of date. For
|
|---|
| 2920 | example:
|
|---|
| 2921 |
|
|---|
| 2922 | @example
|
|---|
| 2923 | @group
|
|---|
| 2924 | .LOW_RESOLUTION_TIME: dst
|
|---|
| 2925 | dst: src
|
|---|
| 2926 | cp -p src dst
|
|---|
| 2927 | @end group
|
|---|
| 2928 | @end example
|
|---|
| 2929 |
|
|---|
| 2930 | Since @samp{cp -p} discards the sub-second part of @file{src}'s time
|
|---|
| 2931 | stamp, @file{dst} is typically slightly older than @file{src} even when
|
|---|
| 2932 | it is up to date. The @code{.LOW_RESOLUTION_TIME} line causes
|
|---|
| 2933 | @command{make} to consider @file{dst} to be up to date if its time stamp
|
|---|
| 2934 | is at the start of the same second that @file{src}'s time stamp is in.
|
|---|
| 2935 |
|
|---|
| 2936 | Due to a limitation of the archive format, archive member time stamps
|
|---|
| 2937 | are always low resolution. You need not list archive members as
|
|---|
| 2938 | prerequisites of @code{.LOW_RESOLUTION_TIME}, as @command{make} does this
|
|---|
| 2939 | automatically.
|
|---|
| 2940 |
|
|---|
| 2941 | @findex .SILENT
|
|---|
| 2942 | @item .SILENT
|
|---|
| 2943 |
|
|---|
| 2944 | If you specify prerequisites for @code{.SILENT}, then @code{make} will
|
|---|
| 2945 | not print the recipe used to remake those particular files before
|
|---|
| 2946 | executing them. The recipe for @code{.SILENT} is ignored.
|
|---|
| 2947 |
|
|---|
| 2948 | If mentioned as a target with no prerequisites, @code{.SILENT} says not
|
|---|
| 2949 | to print any recipes before executing them. This usage of
|
|---|
| 2950 | @samp{.SILENT} is supported only for historical compatibility. We
|
|---|
| 2951 | recommend you use the more selective ways to silence specific recipes.
|
|---|
| 2952 | @xref{Echoing, ,Recipe Echoing}. If you want to silence all recipes
|
|---|
| 2953 | for a particular run of @code{make}, use the @samp{-s} or
|
|---|
| 2954 | @w{@samp{--silent}} option (@pxref{Options Summary}).
|
|---|
| 2955 |
|
|---|
| 2956 | @findex .EXPORT_ALL_VARIABLES
|
|---|
| 2957 | @item .EXPORT_ALL_VARIABLES
|
|---|
| 2958 |
|
|---|
| 2959 | Simply by being mentioned as a target, this tells @code{make} to
|
|---|
| 2960 | export all variables to child processes by default.
|
|---|
| 2961 | @xref{Variables/Recursion, ,Communicating Variables to a
|
|---|
| 2962 | Sub-@code{make}}.
|
|---|
| 2963 |
|
|---|
| 2964 | @findex .NOTPARALLEL
|
|---|
| 2965 | @item .NOTPARALLEL
|
|---|
| 2966 | @cindex parallel execution, overriding
|
|---|
| 2967 |
|
|---|
| 2968 | If @code{.NOTPARALLEL} is mentioned as a target, then this invocation
|
|---|
| 2969 | of @code{make} will be run serially, even if the @samp{-j} option is
|
|---|
| 2970 | given. Any recursively invoked @code{make} command will still run
|
|---|
| 2971 | recipes in parallel (unless its makefile also contains this target).
|
|---|
| 2972 | Any prerequisites on this target are ignored.
|
|---|
| 2973 |
|
|---|
| 2974 | @findex .ONESHELL
|
|---|
| 2975 | @item .ONESHELL
|
|---|
| 2976 | @cindex recipe execution, single invocation
|
|---|
| 2977 |
|
|---|
| 2978 | If @code{.ONESHELL} is mentioned as a target, then when a target is
|
|---|
| 2979 | built all lines of the recipe will be given to a single invocation of
|
|---|
| 2980 | the shell rather than each line being invoked separately
|
|---|
| 2981 | (@pxref{Execution, ,Recipe Execution}).
|
|---|
| 2982 |
|
|---|
| 2983 | @findex .POSIX
|
|---|
| 2984 | @item .POSIX
|
|---|
| 2985 | @cindex POSIX-conforming mode, setting
|
|---|
| 2986 |
|
|---|
| 2987 | If @code{.POSIX} is mentioned as a target, then the makefile will be
|
|---|
| 2988 | parsed and run in POSIX-conforming mode. This does @emph{not} mean
|
|---|
| 2989 | that only POSIX-conforming makefiles will be accepted: all advanced
|
|---|
| 2990 | GNU @code{make} features are still available. Rather, this target
|
|---|
| 2991 | causes @code{make} to behave as required by POSIX in those areas
|
|---|
| 2992 | where @code{make}'s default behavior differs.
|
|---|
| 2993 |
|
|---|
| 2994 | In particular, if this target is mentioned then recipes will be
|
|---|
| 2995 | invoked as if the shell had been passed the @code{-e} flag: the first
|
|---|
| 2996 | failing command in a recipe will cause the recipe to fail immediately.
|
|---|
| 2997 | @end table
|
|---|
| 2998 |
|
|---|
| 2999 | Any defined implicit rule suffix also counts as a special target if it
|
|---|
| 3000 | appears as a target, and so does the concatenation of two suffixes, such
|
|---|
| 3001 | as @samp{.c.o}. These targets are suffix rules, an obsolete way of
|
|---|
| 3002 | defining implicit rules (but a way still widely used). In principle, any
|
|---|
| 3003 | target name could be special in this way if you break it in two and add
|
|---|
| 3004 | both pieces to the suffix list. In practice, suffixes normally begin with
|
|---|
| 3005 | @samp{.}, so these special target names also begin with @samp{.}.
|
|---|
| 3006 | @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
|
|---|
| 3007 |
|
|---|
| 3008 | @node Multiple Targets, Multiple Rules, Special Targets, Rules
|
|---|
| 3009 | @section Multiple Targets in a Rule
|
|---|
| 3010 | @cindex multiple targets
|
|---|
| 3011 | @cindex several targets in a rule
|
|---|
| 3012 | @cindex targets, multiple
|
|---|
| 3013 | @cindex rule, with multiple targets
|
|---|
| 3014 |
|
|---|
| 3015 | A rule with multiple targets is equivalent to writing many rules, each with
|
|---|
| 3016 | one target, and all identical aside from that. The same recipe applies to
|
|---|
| 3017 | all the targets, but its effect may vary because you can substitute the
|
|---|
| 3018 | actual target name into the recipe using @samp{$@@}. The rule contributes
|
|---|
| 3019 | the same prerequisites to all the targets also.
|
|---|
| 3020 |
|
|---|
| 3021 | This is useful in two cases.
|
|---|
| 3022 |
|
|---|
| 3023 | @itemize @bullet
|
|---|
| 3024 | @item
|
|---|
| 3025 | You want just prerequisites, no recipe. For example:
|
|---|
| 3026 |
|
|---|
| 3027 | @example
|
|---|
| 3028 | kbd.o command.o files.o: command.h
|
|---|
| 3029 | @end example
|
|---|
| 3030 |
|
|---|
| 3031 | @noindent
|
|---|
| 3032 | gives an additional prerequisite to each of the three object files
|
|---|
| 3033 | mentioned.
|
|---|
| 3034 |
|
|---|
| 3035 | @item
|
|---|
| 3036 | Similar recipes work for all the targets. The recipes do not need
|
|---|
| 3037 | to be absolutely identical, since the automatic variable @samp{$@@}
|
|---|
| 3038 | can be used to substitute the particular target to be remade into the
|
|---|
| 3039 | commands (@pxref{Automatic Variables}). For example:
|
|---|
| 3040 |
|
|---|
| 3041 | @example
|
|---|
| 3042 | @group
|
|---|
| 3043 | bigoutput littleoutput : text.g
|
|---|
| 3044 | generate text.g -$(subst output,,$@@) > $@@
|
|---|
| 3045 | @end group
|
|---|
| 3046 | @end example
|
|---|
| 3047 | @findex subst
|
|---|
| 3048 |
|
|---|
| 3049 | @noindent
|
|---|
| 3050 | is equivalent to
|
|---|
| 3051 |
|
|---|
| 3052 | @example
|
|---|
| 3053 | bigoutput : text.g
|
|---|
| 3054 | generate text.g -big > bigoutput
|
|---|
| 3055 | littleoutput : text.g
|
|---|
| 3056 | generate text.g -little > littleoutput
|
|---|
| 3057 | @end example
|
|---|
| 3058 |
|
|---|
| 3059 | @noindent
|
|---|
| 3060 | Here we assume the hypothetical program @code{generate} makes two
|
|---|
| 3061 | types of output, one if given @samp{-big} and one if given
|
|---|
| 3062 | @samp{-little}.
|
|---|
| 3063 | @xref{Text Functions, ,Functions for String Substitution and Analysis},
|
|---|
| 3064 | for an explanation of the @code{subst} function.
|
|---|
| 3065 | @end itemize
|
|---|
| 3066 |
|
|---|
| 3067 | Suppose you would like to vary the prerequisites according to the
|
|---|
| 3068 | target, much as the variable @samp{$@@} allows you to vary the recipe.
|
|---|
| 3069 | You cannot do this with multiple targets in an ordinary rule, but you
|
|---|
| 3070 | can do it with a @dfn{static pattern rule}. @xref{Static Pattern,
|
|---|
| 3071 | ,Static Pattern Rules}.
|
|---|
| 3072 |
|
|---|
| 3073 | @node Multiple Rules, Static Pattern, Multiple Targets, Rules
|
|---|
| 3074 | @section Multiple Rules for One Target
|
|---|
| 3075 | @cindex multiple rules for one target
|
|---|
| 3076 | @cindex several rules for one target
|
|---|
| 3077 | @cindex rule, multiple for one target
|
|---|
| 3078 | @cindex target, multiple rules for one
|
|---|
| 3079 |
|
|---|
| 3080 | One file can be the target of several rules. All the prerequisites
|
|---|
| 3081 | mentioned in all the rules are merged into one list of prerequisites for
|
|---|
| 3082 | the target. If the target is older than any prerequisite from any rule,
|
|---|
| 3083 | the recipe is executed.
|
|---|
| 3084 |
|
|---|
| 3085 | There can only be one recipe to be executed for a file. If more than
|
|---|
| 3086 | one rule gives a recipe for the same file, @code{make} uses the last
|
|---|
| 3087 | one given and prints an error message. (As a special case, if the
|
|---|
| 3088 | file's name begins with a dot, no error message is printed. This odd
|
|---|
| 3089 | behavior is only for compatibility with other implementations of
|
|---|
| 3090 | @code{make}@dots{} you should avoid using it). Occasionally it is
|
|---|
| 3091 | useful to have the same target invoke multiple recipes which are
|
|---|
| 3092 | defined in different parts of your makefile; you can use
|
|---|
| 3093 | @dfn{double-colon rules} (@pxref{Double-Colon}) for this.
|
|---|
| 3094 |
|
|---|
| 3095 | An extra rule with just prerequisites can be used to give a few extra
|
|---|
| 3096 | prerequisites to many files at once. For example, makefiles often
|
|---|
| 3097 | have a variable, such as @code{objects}, containing a list of all the
|
|---|
| 3098 | compiler output files in the system being made. An easy way to say
|
|---|
| 3099 | that all of them must be recompiled if @file{config.h} changes is to
|
|---|
| 3100 | write the following:
|
|---|
| 3101 |
|
|---|
| 3102 | @example
|
|---|
| 3103 | objects = foo.o bar.o
|
|---|
| 3104 | foo.o : defs.h
|
|---|
| 3105 | bar.o : defs.h test.h
|
|---|
| 3106 | $(objects) : config.h
|
|---|
| 3107 | @end example
|
|---|
| 3108 |
|
|---|
| 3109 | This could be inserted or taken out without changing the rules that really
|
|---|
| 3110 | specify how to make the object files, making it a convenient form to use if
|
|---|
| 3111 | you wish to add the additional prerequisite intermittently.
|
|---|
| 3112 |
|
|---|
| 3113 | Another wrinkle is that the additional prerequisites could be
|
|---|
| 3114 | specified with a variable that you set with a command line argument to
|
|---|
| 3115 | @code{make} (@pxref{Overriding, ,Overriding Variables}). For example,
|
|---|
| 3116 |
|
|---|
| 3117 | @example
|
|---|
| 3118 | @group
|
|---|
| 3119 | extradeps=
|
|---|
| 3120 | $(objects) : $(extradeps)
|
|---|
| 3121 | @end group
|
|---|
| 3122 | @end example
|
|---|
| 3123 |
|
|---|
| 3124 | @noindent
|
|---|
| 3125 | means that the command @samp{make extradeps=foo.h} will consider
|
|---|
| 3126 | @file{foo.h} as a prerequisite of each object file, but plain @samp{make}
|
|---|
| 3127 | will not.
|
|---|
| 3128 |
|
|---|
| 3129 | If none of the explicit rules for a target has a recipe, then @code{make}
|
|---|
| 3130 | searches for an applicable implicit rule to find one
|
|---|
| 3131 | @pxref{Implicit Rules, ,Using Implicit Rules}).
|
|---|
| 3132 |
|
|---|
| 3133 | @node Static Pattern, Double-Colon, Multiple Rules, Rules
|
|---|
| 3134 | @section Static Pattern Rules
|
|---|
| 3135 | @cindex static pattern rule
|
|---|
| 3136 | @cindex rule, static pattern
|
|---|
| 3137 | @cindex pattern rules, static (not implicit)
|
|---|
| 3138 | @cindex varying prerequisites
|
|---|
| 3139 | @cindex prerequisites, varying (static pattern)
|
|---|
| 3140 |
|
|---|
| 3141 | @dfn{Static pattern rules} are rules which specify multiple targets and
|
|---|
| 3142 | construct the prerequisite names for each target based on the target name.
|
|---|
| 3143 | They are more general than ordinary rules with multiple targets because the
|
|---|
| 3144 | targets do not have to have identical prerequisites. Their prerequisites must
|
|---|
| 3145 | be @emph{analogous}, but not necessarily @emph{identical}.
|
|---|
| 3146 |
|
|---|
| 3147 | @menu
|
|---|
| 3148 | * Static Usage:: The syntax of static pattern rules.
|
|---|
| 3149 | * Static versus Implicit:: When are they better than implicit rules?
|
|---|
| 3150 | @end menu
|
|---|
| 3151 |
|
|---|
| 3152 | @node Static Usage, Static versus Implicit, Static Pattern, Static Pattern
|
|---|
| 3153 | @subsection Syntax of Static Pattern Rules
|
|---|
| 3154 | @cindex static pattern rule, syntax of
|
|---|
| 3155 | @cindex pattern rules, static, syntax of
|
|---|
| 3156 |
|
|---|
| 3157 | Here is the syntax of a static pattern rule:
|
|---|
| 3158 |
|
|---|
| 3159 | @example
|
|---|
| 3160 | @var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{}
|
|---|
| 3161 | @var{recipe}
|
|---|
| 3162 | @dots{}
|
|---|
| 3163 | @end example
|
|---|
| 3164 |
|
|---|
| 3165 | @noindent
|
|---|
| 3166 | The @var{targets} list specifies the targets that the rule applies to.
|
|---|
| 3167 | The targets can contain wildcard characters, just like the targets of
|
|---|
| 3168 | ordinary rules (@pxref{Wildcards, ,Using Wildcard Characters in File
|
|---|
| 3169 | Names}).
|
|---|
| 3170 |
|
|---|
| 3171 | @cindex target pattern, static (not implicit)
|
|---|
| 3172 | @cindex stem
|
|---|
| 3173 | The @var{target-pattern} and @var{prereq-patterns} say how to compute the
|
|---|
| 3174 | prerequisites of each target. Each target is matched against the
|
|---|
| 3175 | @var{target-pattern} to extract a part of the target name, called the
|
|---|
| 3176 | @dfn{stem}. This stem is substituted into each of the @var{prereq-patterns}
|
|---|
| 3177 | to make the prerequisite names (one from each @var{prereq-pattern}).
|
|---|
| 3178 |
|
|---|
| 3179 | Each pattern normally contains the character @samp{%} just once. When the
|
|---|
| 3180 | @var{target-pattern} matches a target, the @samp{%} can match any part of
|
|---|
| 3181 | the target name; this part is called the @dfn{stem}. The rest of the
|
|---|
| 3182 | pattern must match exactly. For example, the target @file{foo.o} matches
|
|---|
| 3183 | the pattern @samp{%.o}, with @samp{foo} as the stem. The targets
|
|---|
| 3184 | @file{foo.c} and @file{foo.out} do not match that pattern.@refill
|
|---|
| 3185 |
|
|---|
| 3186 | @cindex prerequisite pattern, static (not implicit)
|
|---|
| 3187 | The prerequisite names for each target are made by substituting the stem
|
|---|
| 3188 | for the @samp{%} in each prerequisite pattern. For example, if one
|
|---|
| 3189 | prerequisite pattern is @file{%.c}, then substitution of the stem
|
|---|
| 3190 | @samp{foo} gives the prerequisite name @file{foo.c}. It is legitimate
|
|---|
| 3191 | to write a prerequisite pattern that does not contain @samp{%}; then this
|
|---|
| 3192 | prerequisite is the same for all targets.
|
|---|
| 3193 |
|
|---|
| 3194 | @cindex @code{%}, quoting in static pattern
|
|---|
| 3195 | @cindex @code{%}, quoting with @code{\} (backslash)
|
|---|
| 3196 | @cindex @code{\} (backslash), to quote @code{%}
|
|---|
| 3197 | @cindex backslash (@code{\}), to quote @code{%}
|
|---|
| 3198 | @cindex quoting @code{%}, in static pattern
|
|---|
| 3199 | @samp{%} characters in pattern rules can be quoted with preceding
|
|---|
| 3200 | backslashes (@samp{\}). Backslashes that would otherwise quote @samp{%}
|
|---|
| 3201 | characters can be quoted with more backslashes. Backslashes that quote
|
|---|
| 3202 | @samp{%} characters or other backslashes are removed from the pattern
|
|---|
| 3203 | before it is compared to file names or has a stem substituted into it.
|
|---|
| 3204 | Backslashes that are not in danger of quoting @samp{%} characters go
|
|---|
| 3205 | unmolested. For example, the pattern @file{the\%weird\\%pattern\\} has
|
|---|
| 3206 | @samp{the%weird\} preceding the operative @samp{%} character, and
|
|---|
| 3207 | @samp{pattern\\} following it. The final two backslashes are left alone
|
|---|
| 3208 | because they cannot affect any @samp{%} character.@refill
|
|---|
| 3209 |
|
|---|
| 3210 | Here is an example, which compiles each of @file{foo.o} and @file{bar.o}
|
|---|
| 3211 | from the corresponding @file{.c} file:
|
|---|
| 3212 |
|
|---|
| 3213 | @example
|
|---|
| 3214 | @group
|
|---|
| 3215 | objects = foo.o bar.o
|
|---|
| 3216 |
|
|---|
| 3217 | all: $(objects)
|
|---|
| 3218 |
|
|---|
| 3219 | $(objects): %.o: %.c
|
|---|
| 3220 | $(CC) -c $(CFLAGS) $< -o $@@
|
|---|
| 3221 | @end group
|
|---|
| 3222 | @end example
|
|---|
| 3223 |
|
|---|
| 3224 | @noindent
|
|---|
| 3225 | Here @samp{$<} is the automatic variable that holds the name of the
|
|---|
| 3226 | prerequisite and @samp{$@@} is the automatic variable that holds the name
|
|---|
| 3227 | of the target; see @ref{Automatic Variables}.
|
|---|
| 3228 |
|
|---|
| 3229 | Each target specified must match the target pattern; a warning is issued
|
|---|
| 3230 | for each target that does not. If you have a list of files, only some of
|
|---|
| 3231 | which will match the pattern, you can use the @code{filter} function to
|
|---|
| 3232 | remove non-matching file names (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
|
|---|
| 3233 |
|
|---|
| 3234 | @example
|
|---|
| 3235 | files = foo.elc bar.o lose.o
|
|---|
| 3236 |
|
|---|
| 3237 | $(filter %.o,$(files)): %.o: %.c
|
|---|
| 3238 | $(CC) -c $(CFLAGS) $< -o $@@
|
|---|
| 3239 | $(filter %.elc,$(files)): %.elc: %.el
|
|---|
| 3240 | emacs -f batch-byte-compile $<
|
|---|
| 3241 | @end example
|
|---|
| 3242 |
|
|---|
| 3243 | @noindent
|
|---|
| 3244 | In this example the result of @samp{$(filter %.o,$(files))} is
|
|---|
| 3245 | @file{bar.o lose.o}, and the first static pattern rule causes each of
|
|---|
| 3246 | these object files to be updated by compiling the corresponding C source
|
|---|
| 3247 | file. The result of @w{@samp{$(filter %.elc,$(files))}} is
|
|---|
| 3248 | @file{foo.elc}, so that file is made from @file{foo.el}.@refill
|
|---|
| 3249 |
|
|---|
| 3250 | Another example shows how to use @code{$*} in static pattern rules:
|
|---|
| 3251 | @vindex $*@r{, and static pattern}
|
|---|
| 3252 |
|
|---|
| 3253 | @example
|
|---|
| 3254 | @group
|
|---|
| 3255 | bigoutput littleoutput : %output : text.g
|
|---|
| 3256 | generate text.g -$* > $@@
|
|---|
| 3257 | @end group
|
|---|
| 3258 | @end example
|
|---|
| 3259 |
|
|---|
| 3260 | @noindent
|
|---|
| 3261 | When the @code{generate} command is run, @code{$*} will expand to the
|
|---|
| 3262 | stem, either @samp{big} or @samp{little}.
|
|---|
| 3263 |
|
|---|
| 3264 | @node Static versus Implicit, , Static Usage, Static Pattern
|
|---|
| 3265 | @subsection Static Pattern Rules versus Implicit Rules
|
|---|
| 3266 | @cindex rule, static pattern versus implicit
|
|---|
| 3267 | @cindex static pattern rule, versus implicit
|
|---|
| 3268 |
|
|---|
| 3269 | A static pattern rule has much in common with an implicit rule defined as a
|
|---|
| 3270 | pattern rule (@pxref{Pattern Rules, ,Defining and Redefining Pattern Rules}).
|
|---|
| 3271 | Both have a pattern for the target and patterns for constructing the
|
|---|
| 3272 | names of prerequisites. The difference is in how @code{make} decides
|
|---|
| 3273 | @emph{when} the rule applies.
|
|---|
| 3274 |
|
|---|
| 3275 | An implicit rule @emph{can} apply to any target that matches its pattern,
|
|---|
| 3276 | but it @emph{does} apply only when the target has no recipe otherwise
|
|---|
| 3277 | specified, and only when the prerequisites can be found. If more than one
|
|---|
| 3278 | implicit rule appears applicable, only one applies; the choice depends on
|
|---|
| 3279 | the order of rules.
|
|---|
| 3280 |
|
|---|
| 3281 | By contrast, a static pattern rule applies to the precise list of targets
|
|---|
| 3282 | that you specify in the rule. It cannot apply to any other target and it
|
|---|
| 3283 | invariably does apply to each of the targets specified. If two conflicting
|
|---|
| 3284 | rules apply, and both have recipes, that's an error.
|
|---|
| 3285 |
|
|---|
| 3286 | The static pattern rule can be better than an implicit rule for these
|
|---|
| 3287 | reasons:
|
|---|
| 3288 |
|
|---|
| 3289 | @itemize @bullet
|
|---|
| 3290 | @item
|
|---|
| 3291 | You may wish to override the usual implicit rule for a few
|
|---|
| 3292 | files whose names cannot be categorized syntactically but
|
|---|
| 3293 | can be given in an explicit list.
|
|---|
| 3294 |
|
|---|
| 3295 | @item
|
|---|
| 3296 | If you cannot be sure of the precise contents of the directories
|
|---|
| 3297 | you are using, you may not be sure which other irrelevant files
|
|---|
| 3298 | might lead @code{make} to use the wrong implicit rule. The choice
|
|---|
| 3299 | might depend on the order in which the implicit rule search is done.
|
|---|
| 3300 | With static pattern rules, there is no uncertainty: each rule applies
|
|---|
| 3301 | to precisely the targets specified.
|
|---|
| 3302 | @end itemize
|
|---|
| 3303 |
|
|---|
| 3304 | @node Double-Colon, Automatic Prerequisites, Static Pattern, Rules
|
|---|
| 3305 | @section Double-Colon Rules
|
|---|
| 3306 | @cindex double-colon rules
|
|---|
| 3307 | @cindex rule, double-colon (@code{::})
|
|---|
| 3308 | @cindex multiple rules for one target (@code{::})
|
|---|
| 3309 | @cindex @code{::} rules (double-colon)
|
|---|
| 3310 |
|
|---|
| 3311 | @dfn{Double-colon} rules are explicit rules written with @samp{::}
|
|---|
| 3312 | instead of @samp{:} after the target names. They are handled
|
|---|
| 3313 | differently from ordinary rules when the same target appears in more
|
|---|
| 3314 | than one rule. Pattern rules with double-colons have an entirely
|
|---|
| 3315 | different meaning (@pxref{Match-Anything Rules}).
|
|---|
| 3316 |
|
|---|
| 3317 | When a target appears in multiple rules, all the rules must be the same
|
|---|
| 3318 | type: all ordinary, or all double-colon. If they are double-colon, each
|
|---|
| 3319 | of them is independent of the others. Each double-colon rule's recipe
|
|---|
| 3320 | is executed if the target is older than any prerequisites of that rule.
|
|---|
| 3321 | If there are no prerequisites for that rule, its recipe is always
|
|---|
| 3322 | executed (even if the target already exists). This can result in
|
|---|
| 3323 | executing none, any, or all of the double-colon rules.
|
|---|
| 3324 |
|
|---|
| 3325 | Double-colon rules with the same target are in fact completely separate
|
|---|
| 3326 | from one another. Each double-colon rule is processed individually, just
|
|---|
| 3327 | as rules with different targets are processed.
|
|---|
| 3328 |
|
|---|
| 3329 | The double-colon rules for a target are executed in the order they appear
|
|---|
| 3330 | in the makefile. However, the cases where double-colon rules really make
|
|---|
| 3331 | sense are those where the order of executing the recipes would not matter.
|
|---|
| 3332 |
|
|---|
| 3333 | Double-colon rules are somewhat obscure and not often very useful; they
|
|---|
| 3334 | provide a mechanism for cases in which the method used to update a target
|
|---|
| 3335 | differs depending on which prerequisite files caused the update, and such
|
|---|
| 3336 | cases are rare.
|
|---|
| 3337 |
|
|---|
| 3338 | Each double-colon rule should specify a recipe; if it does not, an
|
|---|
| 3339 | implicit rule will be used if one applies.
|
|---|
| 3340 | @xref{Implicit Rules, ,Using Implicit Rules}.
|
|---|
| 3341 |
|
|---|
| 3342 | @node Automatic Prerequisites, , Double-Colon, Rules
|
|---|
| 3343 | @section Generating Prerequisites Automatically
|
|---|
| 3344 | @cindex prerequisites, automatic generation
|
|---|
| 3345 | @cindex automatic generation of prerequisites
|
|---|
| 3346 | @cindex generating prerequisites automatically
|
|---|
| 3347 |
|
|---|
| 3348 | In the makefile for a program, many of the rules you need to write often
|
|---|
| 3349 | say only that some object file depends on some header
|
|---|
| 3350 | file. For example, if @file{main.c} uses @file{defs.h} via an
|
|---|
| 3351 | @code{#include}, you would write:
|
|---|
| 3352 |
|
|---|
| 3353 | @example
|
|---|
| 3354 | main.o: defs.h
|
|---|
| 3355 | @end example
|
|---|
| 3356 |
|
|---|
| 3357 | @noindent
|
|---|
| 3358 | You need this rule so that @code{make} knows that it must remake
|
|---|
| 3359 | @file{main.o} whenever @file{defs.h} changes. You can see that for a
|
|---|
| 3360 | large program you would have to write dozens of such rules in your
|
|---|
| 3361 | makefile. And, you must always be very careful to update the makefile
|
|---|
| 3362 | every time you add or remove an @code{#include}.
|
|---|
| 3363 | @cindex @code{#include}
|
|---|
| 3364 |
|
|---|
| 3365 | @cindex @code{-M} (to compiler)
|
|---|
| 3366 | To avoid this hassle, most modern C compilers can write these rules for
|
|---|
| 3367 | you, by looking at the @code{#include} lines in the source files.
|
|---|
| 3368 | Usually this is done with the @samp{-M} option to the compiler.
|
|---|
| 3369 | For example, the command:
|
|---|
| 3370 |
|
|---|
| 3371 | @example
|
|---|
| 3372 | cc -M main.c
|
|---|
| 3373 | @end example
|
|---|
| 3374 |
|
|---|
| 3375 | @noindent
|
|---|
| 3376 | generates the output:
|
|---|
| 3377 |
|
|---|
| 3378 | @example
|
|---|
| 3379 | main.o : main.c defs.h
|
|---|
| 3380 | @end example
|
|---|
| 3381 |
|
|---|
| 3382 | @noindent
|
|---|
| 3383 | Thus you no longer have to write all those rules yourself.
|
|---|
| 3384 | The compiler will do it for you.
|
|---|
| 3385 |
|
|---|
| 3386 | Note that such a rule constitutes mentioning @file{main.o} in a
|
|---|
| 3387 | makefile, so it can never be considered an intermediate file by
|
|---|
| 3388 | implicit rule search. This means that @code{make} won't ever remove
|
|---|
| 3389 | the file after using it; @pxref{Chained Rules, ,Chains of Implicit
|
|---|
| 3390 | Rules}.
|
|---|
| 3391 |
|
|---|
| 3392 | @cindex @code{make depend}
|
|---|
| 3393 | With old @code{make} programs, it was traditional practice to use this
|
|---|
| 3394 | compiler feature to generate prerequisites on demand with a command like
|
|---|
| 3395 | @samp{make depend}. That command would create a file @file{depend}
|
|---|
| 3396 | containing all the automatically-generated prerequisites; then the
|
|---|
| 3397 | makefile could use @code{include} to read them in (@pxref{Include}).
|
|---|
| 3398 |
|
|---|
| 3399 | In GNU @code{make}, the feature of remaking makefiles makes this
|
|---|
| 3400 | practice obsolete---you need never tell @code{make} explicitly to
|
|---|
| 3401 | regenerate the prerequisites, because it always regenerates any makefile
|
|---|
| 3402 | that is out of date. @xref{Remaking Makefiles}.
|
|---|
| 3403 |
|
|---|
| 3404 | The practice we recommend for automatic prerequisite generation is to have
|
|---|
| 3405 | one makefile corresponding to each source file. For each source file
|
|---|
| 3406 | @file{@var{name}.c} there is a makefile @file{@var{name}.d} which lists
|
|---|
| 3407 | what files the object file @file{@var{name}.o} depends on. That way
|
|---|
| 3408 | only the source files that have changed need to be rescanned to produce
|
|---|
| 3409 | the new prerequisites.
|
|---|
| 3410 |
|
|---|
| 3411 | Here is the pattern rule to generate a file of prerequisites (i.e., a makefile)
|
|---|
| 3412 | called @file{@var{name}.d} from a C source file called @file{@var{name}.c}:
|
|---|
| 3413 |
|
|---|
| 3414 | @smallexample
|
|---|
| 3415 | @group
|
|---|
| 3416 | %.d: %.c
|
|---|
| 3417 | @@set -e; rm -f $@@; \
|
|---|
| 3418 | $(CC) -M $(CPPFLAGS) $< > $@@.$$$$; \
|
|---|
| 3419 | sed 's,\($*\)\.o[ :]*,\1.o $@@ : ,g' < $@@.$$$$ > $@@; \
|
|---|
| 3420 | rm -f $@@.$$$$
|
|---|
| 3421 | @end group
|
|---|
| 3422 | @end smallexample
|
|---|
| 3423 |
|
|---|
| 3424 | @noindent
|
|---|
| 3425 | @xref{Pattern Rules}, for information on defining pattern rules. The
|
|---|
| 3426 | @samp{-e} flag to the shell causes it to exit immediately if the
|
|---|
| 3427 | @code{$(CC)} command (or any other command) fails (exits with a
|
|---|
| 3428 | nonzero status).
|
|---|
| 3429 | @cindex @code{-e} (shell flag)
|
|---|
| 3430 |
|
|---|
| 3431 | @cindex @code{-MM} (to GNU compiler)
|
|---|
| 3432 | With the GNU C compiler, you may wish to use the @samp{-MM} flag instead
|
|---|
| 3433 | of @samp{-M}. This omits prerequisites on system header files.
|
|---|
| 3434 | @xref{Preprocessor Options, , Options Controlling the Preprocessor,
|
|---|
| 3435 | gcc, Using GNU CC}, for details.
|
|---|
| 3436 |
|
|---|
| 3437 | @cindex @code{sed} (shell command)
|
|---|
| 3438 | The purpose of the @code{sed} command is to translate (for example):
|
|---|
| 3439 |
|
|---|
| 3440 | @example
|
|---|
| 3441 | main.o : main.c defs.h
|
|---|
| 3442 | @end example
|
|---|
| 3443 |
|
|---|
| 3444 | @noindent
|
|---|
| 3445 | into:
|
|---|
| 3446 |
|
|---|
| 3447 | @example
|
|---|
| 3448 | main.o main.d : main.c defs.h
|
|---|
| 3449 | @end example
|
|---|
| 3450 |
|
|---|
| 3451 | @noindent
|
|---|
| 3452 | @cindex @code{.d}
|
|---|
| 3453 | This makes each @samp{.d} file depend on all the source and header files
|
|---|
| 3454 | that the corresponding @samp{.o} file depends on. @code{make} then
|
|---|
| 3455 | knows it must regenerate the prerequisites whenever any of the source or
|
|---|
| 3456 | header files changes.
|
|---|
| 3457 |
|
|---|
| 3458 | Once you've defined the rule to remake the @samp{.d} files,
|
|---|
| 3459 | you then use the @code{include} directive to read them all in.
|
|---|
| 3460 | @xref{Include}. For example:
|
|---|
| 3461 |
|
|---|
| 3462 | @example
|
|---|
| 3463 | @group
|
|---|
| 3464 | sources = foo.c bar.c
|
|---|
| 3465 |
|
|---|
| 3466 | include $(sources:.c=.d)
|
|---|
| 3467 | @end group
|
|---|
| 3468 | @end example
|
|---|
| 3469 |
|
|---|
| 3470 | @noindent
|
|---|
| 3471 | (This example uses a substitution variable reference to translate the
|
|---|
| 3472 | list of source files @samp{foo.c bar.c} into a list of prerequisite
|
|---|
| 3473 | makefiles, @samp{foo.d bar.d}. @xref{Substitution Refs}, for full
|
|---|
| 3474 | information on substitution references.) Since the @samp{.d} files are
|
|---|
| 3475 | makefiles like any others, @code{make} will remake them as necessary
|
|---|
| 3476 | with no further work from you. @xref{Remaking Makefiles}.
|
|---|
| 3477 |
|
|---|
| 3478 | Note that the @samp{.d} files contain target definitions; you should
|
|---|
| 3479 | be sure to place the @code{include} directive @emph{after} the first,
|
|---|
| 3480 | default goal in your makefiles or run the risk of having a random
|
|---|
| 3481 | object file become the default goal.
|
|---|
| 3482 | @xref{How Make Works}.
|
|---|
| 3483 |
|
|---|
| 3484 | @node Recipes, Using Variables, Rules, Top
|
|---|
| 3485 | @chapter Writing Recipes in Rules
|
|---|
| 3486 | @cindex recipes
|
|---|
| 3487 | @cindex recipes, how to write
|
|---|
| 3488 | @cindex writing recipes
|
|---|
| 3489 |
|
|---|
| 3490 | The recipe of a rule consists of one or more shell command lines to
|
|---|
| 3491 | be executed, one at a time, in the order they appear. Typically, the
|
|---|
| 3492 | result of executing these commands is that the target of the rule is
|
|---|
| 3493 | brought up to date.
|
|---|
| 3494 |
|
|---|
| 3495 | Users use many different shell programs, but recipes in makefiles are
|
|---|
| 3496 | always interpreted by @file{/bin/sh} unless the makefile specifies
|
|---|
| 3497 | otherwise. @xref{Execution, ,Recipe Execution}.
|
|---|
| 3498 |
|
|---|
| 3499 | @menu
|
|---|
| 3500 | * Recipe Syntax:: Recipe syntax features and pitfalls.
|
|---|
| 3501 | * Echoing:: How to control when recipes are echoed.
|
|---|
| 3502 | * Execution:: How recipes are executed.
|
|---|
| 3503 | * Parallel:: How recipes can be executed in parallel.
|
|---|
| 3504 | * Errors:: What happens after a recipe execution error.
|
|---|
| 3505 | * Interrupts:: What happens when a recipe is interrupted.
|
|---|
| 3506 | * Recursion:: Invoking @code{make} from makefiles.
|
|---|
| 3507 | * Canned Recipes:: Defining canned recipes.
|
|---|
| 3508 | * Empty Recipes:: Defining useful, do-nothing recipes.
|
|---|
| 3509 | @end menu
|
|---|
| 3510 |
|
|---|
| 3511 | @node Recipe Syntax, Echoing, Recipes, Recipes
|
|---|
| 3512 | @section Recipe Syntax
|
|---|
| 3513 | @cindex recipe syntax
|
|---|
| 3514 | @cindex syntax of recipe
|
|---|
| 3515 |
|
|---|
| 3516 | Makefiles have the unusual property that there are really two distinct
|
|---|
| 3517 | syntaxes in one file. Most of the makefile uses @code{make} syntax
|
|---|
| 3518 | (@pxref{Makefiles, ,Writing Makefiles}). However, recipes are meant
|
|---|
| 3519 | to be interpreted by the shell and so they are written using shell
|
|---|
| 3520 | syntax. The @code{make} program does not try to understand shell
|
|---|
| 3521 | syntax: it performs only a very few specific translations on the
|
|---|
| 3522 | content of the recipe before handing it to the shell.
|
|---|
| 3523 |
|
|---|
| 3524 | Each line in the recipe must start with a tab (or the first character
|
|---|
| 3525 | in the value of the @code{.RECIPEPREFIX} variable; @pxref{Special
|
|---|
| 3526 | Variables}), except that the first recipe line may be attached to the
|
|---|
| 3527 | target-and-prerequisites line with a semicolon in between. @emph{Any}
|
|---|
| 3528 | line in the makefile that begins with a tab and appears in a ``rule
|
|---|
| 3529 | context'' (that is, after a rule has been started until another rule
|
|---|
| 3530 | or variable definition) will be considered part of a recipe for that
|
|---|
| 3531 | rule. Blank lines and lines of just comments may appear among the
|
|---|
| 3532 | recipe lines; they are ignored.
|
|---|
| 3533 |
|
|---|
| 3534 | Some consequences of these rules include:
|
|---|
| 3535 |
|
|---|
| 3536 | @itemize @bullet
|
|---|
| 3537 | @item
|
|---|
| 3538 | A blank line that begins with a tab is not blank: it's an empty
|
|---|
| 3539 | recipe (@pxref{Empty Recipes}).
|
|---|
| 3540 |
|
|---|
| 3541 | @cindex comments, in recipes
|
|---|
| 3542 | @cindex recipes, comments in
|
|---|
| 3543 | @cindex @code{#} (comments), in recipes
|
|---|
| 3544 | @item
|
|---|
| 3545 | A comment in a recipe is not a @code{make} comment; it will be
|
|---|
| 3546 | passed to the shell as-is. Whether the shell treats it as a comment
|
|---|
| 3547 | or not depends on your shell.
|
|---|
| 3548 |
|
|---|
| 3549 | @item
|
|---|
| 3550 | A variable definition in a ``rule context'' which is indented by a tab
|
|---|
| 3551 | as the first character on the line, will be considered part of a
|
|---|
| 3552 | recipe, not a @code{make} variable definition, and passed to the
|
|---|
| 3553 | shell.
|
|---|
| 3554 |
|
|---|
| 3555 | @item
|
|---|
| 3556 | A conditional expression (@code{ifdef}, @code{ifeq},
|
|---|
| 3557 | etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule
|
|---|
| 3558 | context'' which is indented by a tab as the first character on the
|
|---|
| 3559 | line, will be considered part of a recipe and be passed to the shell.
|
|---|
| 3560 |
|
|---|
| 3561 | @end itemize
|
|---|
| 3562 |
|
|---|
| 3563 | @menu
|
|---|
| 3564 | * Splitting Recipe Lines:: Breaking long recipe lines for readability.
|
|---|
| 3565 | * Variables in Recipes:: Using @code{make} variables in recipes.
|
|---|
| 3566 | @end menu
|
|---|
| 3567 |
|
|---|
| 3568 | @node Splitting Recipe Lines, Variables in Recipes, Recipe Syntax, Recipe Syntax
|
|---|
| 3569 | @subsection Splitting Recipe Lines
|
|---|
| 3570 | @cindex recipes, splitting
|
|---|
| 3571 | @cindex splitting recipes
|
|---|
| 3572 | @cindex recipes, backslash (@code{\}) in
|
|---|
| 3573 | @cindex recipes, quoting newlines in
|
|---|
| 3574 | @cindex backslash (@code{\}), in recipes
|
|---|
| 3575 | @cindex @code{\} (backslash), in recipes
|
|---|
| 3576 | @cindex quoting newline, in recipes
|
|---|
| 3577 | @cindex newline, quoting, in recipes
|
|---|
| 3578 |
|
|---|
| 3579 | One of the few ways in which @code{make} does interpret recipes is
|
|---|
| 3580 | checking for a backslash just before the newline. As in normal
|
|---|
| 3581 | makefile syntax, a single logical recipe line can be split into
|
|---|
| 3582 | multiple physical lines in the makefile by placing a backslash before
|
|---|
| 3583 | each newline. A sequence of lines like this is considered a single
|
|---|
| 3584 | recipe line, and one instance of the shell will be invoked to run it.
|
|---|
| 3585 |
|
|---|
| 3586 | However, in contrast to how they are treated in other places in a
|
|---|
| 3587 | makefile (@pxref{Splitting Lines, , Splitting Long Lines}),
|
|---|
| 3588 | backslash/newline pairs are @emph{not} removed from the recipe. Both
|
|---|
| 3589 | the backslash and the newline characters are preserved and passed to
|
|---|
| 3590 | the shell. How the backslash/newline is interpreted depends on your
|
|---|
| 3591 | shell. If the first character of the next line after the
|
|---|
| 3592 | backslash/newline is the recipe prefix character (a tab by default;
|
|---|
| 3593 | @pxref{Special Variables}), then that character (and only that
|
|---|
| 3594 | character) is removed. Whitespace is never added to the recipe.
|
|---|
| 3595 |
|
|---|
| 3596 | For example, the recipe for the all target in this makefile:
|
|---|
| 3597 |
|
|---|
| 3598 | @example
|
|---|
| 3599 | @group
|
|---|
| 3600 | all :
|
|---|
| 3601 | @@echo no\
|
|---|
| 3602 | space
|
|---|
| 3603 | @@echo no\
|
|---|
| 3604 | space
|
|---|
| 3605 | @@echo one \
|
|---|
| 3606 | space
|
|---|
| 3607 | @@echo one\
|
|---|
| 3608 | space
|
|---|
| 3609 | @end group
|
|---|
| 3610 | @end example
|
|---|
| 3611 |
|
|---|
| 3612 | @noindent
|
|---|
| 3613 | consists of four separate shell commands where the output is:
|
|---|
| 3614 |
|
|---|
| 3615 | @example
|
|---|
| 3616 | @group
|
|---|
| 3617 | nospace
|
|---|
| 3618 | nospace
|
|---|
| 3619 | one space
|
|---|
| 3620 | one space
|
|---|
| 3621 | @end group
|
|---|
| 3622 | @end example
|
|---|
| 3623 |
|
|---|
| 3624 | As a more complex example, this makefile:
|
|---|
| 3625 |
|
|---|
| 3626 | @example
|
|---|
| 3627 | @group
|
|---|
| 3628 | all : ; @@echo 'hello \
|
|---|
| 3629 | world' ; echo "hello \
|
|---|
| 3630 | world"
|
|---|
| 3631 | @end group
|
|---|
| 3632 | @end example
|
|---|
| 3633 |
|
|---|
| 3634 | @noindent
|
|---|
| 3635 | will invoke one shell with a command of:
|
|---|
| 3636 |
|
|---|
| 3637 | @example
|
|---|
| 3638 | @group
|
|---|
| 3639 | echo 'hello \
|
|---|
| 3640 | world' ; echo "hello \
|
|---|
| 3641 | world"
|
|---|
| 3642 | @end group
|
|---|
| 3643 | @end example
|
|---|
| 3644 |
|
|---|
| 3645 | @noindent
|
|---|
| 3646 | which, according to shell quoting rules, will yield the following output:
|
|---|
| 3647 |
|
|---|
| 3648 | @example
|
|---|
| 3649 | @group
|
|---|
| 3650 | hello \
|
|---|
| 3651 | world
|
|---|
| 3652 | hello world
|
|---|
| 3653 | @end group
|
|---|
| 3654 | @end example
|
|---|
| 3655 |
|
|---|
| 3656 | @noindent
|
|---|
| 3657 | Notice how the backslash/newline pair was removed inside the string
|
|---|
| 3658 | quoted with double quotes (@code{"@dots{}"}), but not from the string
|
|---|
| 3659 | quoted with single quotes (@code{'@dots{}'}). This is the way the
|
|---|
| 3660 | default shell (@file{/bin/sh}) handles backslash/newline pairs. If
|
|---|
| 3661 | you specify a different shell in your makefiles it may treat them
|
|---|
| 3662 | differently.
|
|---|
| 3663 |
|
|---|
| 3664 | Sometimes you want to split a long line inside of single quotes, but
|
|---|
| 3665 | you don't want the backslash/newline to appear in the quoted content.
|
|---|
| 3666 | This is often the case when passing scripts to languages such as Perl,
|
|---|
| 3667 | where extraneous backslashes inside the script can change its meaning
|
|---|
| 3668 | or even be a syntax error. One simple way of handling this is to
|
|---|
| 3669 | place the quoted string, or even the entire command, into a
|
|---|
| 3670 | @code{make} variable then use the variable in the recipe. In this
|
|---|
| 3671 | situation the newline quoting rules for makefiles will be used, and
|
|---|
| 3672 | the backslash/newline will be removed. If we rewrite our example
|
|---|
| 3673 | above using this method:
|
|---|
| 3674 |
|
|---|
| 3675 | @example
|
|---|
| 3676 | @group
|
|---|
| 3677 | HELLO = 'hello \
|
|---|
| 3678 | world'
|
|---|
| 3679 |
|
|---|
| 3680 | all : ; @@echo $(HELLO)
|
|---|
| 3681 | @end group
|
|---|
| 3682 | @end example
|
|---|
| 3683 |
|
|---|
| 3684 | @noindent
|
|---|
| 3685 | we will get output like this:
|
|---|
| 3686 |
|
|---|
| 3687 | @example
|
|---|
| 3688 | @group
|
|---|
| 3689 | hello world
|
|---|
| 3690 | @end group
|
|---|
| 3691 | @end example
|
|---|
| 3692 |
|
|---|
| 3693 | If you like, you can also use target-specific variables
|
|---|
| 3694 | (@pxref{Target-specific, ,Target-specific Variable Values}) to obtain
|
|---|
| 3695 | a tighter correspondence between the variable and the recipe that
|
|---|
| 3696 | uses it.
|
|---|
| 3697 |
|
|---|
| 3698 | @node Variables in Recipes, , Splitting Recipe Lines, Recipe Syntax
|
|---|
| 3699 | @subsection Using Variables in Recipes
|
|---|
| 3700 | @cindex variable references in recipes
|
|---|
| 3701 | @cindex recipes, using variables in
|
|---|
| 3702 |
|
|---|
| 3703 | The other way in which @code{make} processes recipes is by expanding
|
|---|
| 3704 | any variable references in them (@pxref{Reference,Basics of Variable
|
|---|
| 3705 | References}). This occurs after make has finished reading all the
|
|---|
| 3706 | makefiles and the target is determined to be out of date; so, the
|
|---|
| 3707 | recipes for targets which are not rebuilt are never expanded.
|
|---|
| 3708 |
|
|---|
| 3709 | Variable and function references in recipes have identical syntax and
|
|---|
| 3710 | semantics to references elsewhere in the makefile. They also have the
|
|---|
| 3711 | same quoting rules: if you want a dollar sign to appear in your
|
|---|
| 3712 | recipe, you must double it (@samp{$$}). For shells like the default
|
|---|
| 3713 | shell, that use dollar signs to introduce variables, it's important to
|
|---|
| 3714 | keep clear in your mind whether the variable you want to reference is
|
|---|
| 3715 | a @code{make} variable (use a single dollar sign) or a shell variable
|
|---|
| 3716 | (use two dollar signs). For example:
|
|---|
| 3717 |
|
|---|
| 3718 | @example
|
|---|
| 3719 | @group
|
|---|
| 3720 | LIST = one two three
|
|---|
| 3721 | all:
|
|---|
| 3722 | for i in $(LIST); do \
|
|---|
| 3723 | echo $$i; \
|
|---|
| 3724 | done
|
|---|
| 3725 | @end group
|
|---|
| 3726 | @end example
|
|---|
| 3727 |
|
|---|
| 3728 | @noindent
|
|---|
| 3729 | results in the following command being passed to the shell:
|
|---|
| 3730 |
|
|---|
| 3731 | @example
|
|---|
| 3732 | @group
|
|---|
| 3733 | for i in one two three; do \
|
|---|
| 3734 | echo $i; \
|
|---|
| 3735 | done
|
|---|
| 3736 | @end group
|
|---|
| 3737 | @end example
|
|---|
| 3738 |
|
|---|
| 3739 | @noindent
|
|---|
| 3740 | which generates the expected result:
|
|---|
| 3741 |
|
|---|
| 3742 | @example
|
|---|
| 3743 | @group
|
|---|
| 3744 | one
|
|---|
| 3745 | two
|
|---|
| 3746 | three
|
|---|
| 3747 | @end group
|
|---|
| 3748 | @end example
|
|---|
| 3749 |
|
|---|
| 3750 | @node Echoing, Execution, Recipe Syntax, Recipes
|
|---|
| 3751 | @section Recipe Echoing
|
|---|
| 3752 | @cindex echoing of recipes
|
|---|
| 3753 | @cindex silent operation
|
|---|
| 3754 | @cindex @code{@@} (in recipes)
|
|---|
| 3755 | @cindex recipes, echoing
|
|---|
| 3756 | @cindex printing of recipes
|
|---|
| 3757 |
|
|---|
| 3758 | Normally @code{make} prints each line of the recipe before it is
|
|---|
| 3759 | executed. We call this @dfn{echoing} because it gives the appearance
|
|---|
| 3760 | that you are typing the lines yourself.
|
|---|
| 3761 |
|
|---|
| 3762 | When a line starts with @samp{@@}, the echoing of that line is suppressed.
|
|---|
| 3763 | The @samp{@@} is discarded before the line is passed to the shell.
|
|---|
| 3764 | Typically you would use this for a command whose only effect is to print
|
|---|
| 3765 | something, such as an @code{echo} command to indicate progress through
|
|---|
| 3766 | the makefile:
|
|---|
| 3767 |
|
|---|
| 3768 | @example
|
|---|
| 3769 | @@echo About to make distribution files
|
|---|
| 3770 | @end example
|
|---|
| 3771 |
|
|---|
| 3772 | @cindex @code{-n}
|
|---|
| 3773 | @cindex @code{--just-print}
|
|---|
| 3774 | @cindex @code{--dry-run}
|
|---|
| 3775 | @cindex @code{--recon}
|
|---|
| 3776 | When @code{make} is given the flag @samp{-n} or @samp{--just-print} it
|
|---|
| 3777 | only echoes most recipes, without executing them. @xref{Options
|
|---|
| 3778 | Summary, ,Summary of Options}. In this case even the recipe lines
|
|---|
| 3779 | starting with @samp{@@} are printed. This flag is useful for finding
|
|---|
| 3780 | out which recipes @code{make} thinks are necessary without actually
|
|---|
| 3781 | doing them.
|
|---|
| 3782 |
|
|---|
| 3783 | @cindex @code{-s}
|
|---|
| 3784 | @cindex @code{--silent}
|
|---|
| 3785 | @cindex @code{--quiet}
|
|---|
| 3786 | @findex .SILENT
|
|---|
| 3787 | The @samp{-s} or @samp{--silent}
|
|---|
| 3788 | flag to @code{make} prevents all echoing, as if all recipes
|
|---|
| 3789 | started with @samp{@@}. A rule in the makefile for the special target
|
|---|
| 3790 | @code{.SILENT} without prerequisites has the same effect
|
|---|
| 3791 | (@pxref{Special Targets, ,Special Built-in Target Names}).
|
|---|
| 3792 | @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill
|
|---|
| 3793 |
|
|---|
| 3794 | @node Execution, Parallel, Echoing, Recipes
|
|---|
| 3795 | @section Recipe Execution
|
|---|
| 3796 | @cindex recipe, execution
|
|---|
| 3797 | @cindex execution, of recipes
|
|---|
| 3798 | @vindex @code{SHELL} @r{(recipe execution)}
|
|---|
| 3799 |
|
|---|
| 3800 | When it is time to execute recipes to update a target, they are
|
|---|
| 3801 | executed by invoking a new sub-shell for each line of the recipe,
|
|---|
| 3802 | unless the @code{.ONESHELL} special target is in effect
|
|---|
| 3803 | (@pxref{One Shell, ,Using One Shell}) (In practice, @code{make} may
|
|---|
| 3804 | take shortcuts that do not affect the results.)
|
|---|
| 3805 |
|
|---|
| 3806 | @cindex @code{cd} (shell command)
|
|---|
| 3807 | @cindex shell variables, setting in recipes
|
|---|
| 3808 | @cindex recipes setting shell variables
|
|---|
| 3809 | @strong{Please note:} this implies that setting shell variables and
|
|---|
| 3810 | invoking shell commands such as @code{cd} that set a context local to
|
|---|
| 3811 | each process will not affect the following lines in the recipe.@footnote{On
|
|---|
| 3812 | MS-DOS, the value of current working directory is @strong{global}, so
|
|---|
| 3813 | changing it @emph{will} affect the following recipe lines on those
|
|---|
| 3814 | systems.} If you want to use @code{cd} to affect the next statement,
|
|---|
| 3815 | put both statements in a single recipe line. Then @code{make} will
|
|---|
| 3816 | invoke one shell to run the entire line, and the shell will execute
|
|---|
| 3817 | the statements in sequence. For example:
|
|---|
| 3818 |
|
|---|
| 3819 | @example
|
|---|
| 3820 | foo : bar/lose
|
|---|
| 3821 | cd $(@@D) && gobble $(@@F) > ../$@@
|
|---|
| 3822 | @end example
|
|---|
| 3823 |
|
|---|
| 3824 | @noindent
|
|---|
| 3825 | Here we use the shell AND operator (@code{&&}) so that if the
|
|---|
| 3826 | @code{cd} command fails, the script will fail without trying to invoke
|
|---|
| 3827 | the @code{gobble} command in the wrong directory, which could cause
|
|---|
| 3828 | problems (in this case it would certainly cause @file{../foo} to be
|
|---|
| 3829 | truncated, at least).
|
|---|
| 3830 |
|
|---|
| 3831 | @menu
|
|---|
| 3832 | * One Shell:: One shell for all lines in a recipe.
|
|---|
| 3833 | * Choosing the Shell:: How @code{make} chooses the shell used
|
|---|
| 3834 | to run recipes.
|
|---|
| 3835 | @end menu
|
|---|
| 3836 |
|
|---|
| 3837 | @node One Shell, Choosing the Shell, Execution, Execution
|
|---|
| 3838 | @subsection Using One Shell
|
|---|
| 3839 | @cindex recipe lines, single shell
|
|---|
| 3840 | @cindex @code{.ONESHELL}, use of
|
|---|
| 3841 | @findex .ONESHELL
|
|---|
| 3842 |
|
|---|
| 3843 | Sometimes you would prefer that all the lines in the recipe be passed
|
|---|
| 3844 | to a single invocation of the shell. There are generally two
|
|---|
| 3845 | situations where this is useful: first, it can improve performance in
|
|---|
| 3846 | makefiles where recipes consist of many command lines, by avoiding
|
|---|
| 3847 | extra processes. Second, you might want newlines to be included in
|
|---|
| 3848 | your recipe command (for example perhaps you are using a very
|
|---|
| 3849 | different interpreter as your @code{SHELL}). If the @code{.ONESHELL}
|
|---|
| 3850 | special target appears anywhere in the makefile then @emph{all}
|
|---|
| 3851 | recipe lines for each target will be provided to a single invocation
|
|---|
| 3852 | of the shell. Newlines between recipe lines will be preserved. For
|
|---|
| 3853 | example:
|
|---|
| 3854 |
|
|---|
| 3855 | @example
|
|---|
| 3856 | .ONESHELL:
|
|---|
| 3857 | foo : bar/lose
|
|---|
| 3858 | cd $(@@D)
|
|---|
| 3859 | gobble $(@@F) > ../$@@
|
|---|
| 3860 | @end example
|
|---|
| 3861 |
|
|---|
| 3862 | @noindent
|
|---|
| 3863 | would now work as expected even though the commands are on different
|
|---|
| 3864 | recipe lines.
|
|---|
| 3865 |
|
|---|
| 3866 | If @code{.ONESHELL} is provided, then only the first line of the
|
|---|
| 3867 | recipe will be checked for the special prefix characters (@samp{@@},
|
|---|
| 3868 | @samp{-}, and @samp{+}). Subsequent lines will include the special
|
|---|
| 3869 | characters in the recipe line when the @code{SHELL} is invoked. If
|
|---|
| 3870 | you want your recipe to start with one of these special characters
|
|---|
| 3871 | you'll need to arrange for them to not be the first characters on the
|
|---|
| 3872 | first line, perhaps by adding a comment or similar. For example, this
|
|---|
| 3873 | would be a syntax error in Perl because the first @samp{@@} is removed
|
|---|
| 3874 | by make:
|
|---|
| 3875 |
|
|---|
| 3876 | @example
|
|---|
| 3877 | .ONESHELL:
|
|---|
| 3878 | SHELL = /usr/bin/perl
|
|---|
| 3879 | .SHELLFLAGS = -e
|
|---|
| 3880 | show :
|
|---|
| 3881 | @@f = qw(a b c);
|
|---|
| 3882 | print "@@f\n";
|
|---|
| 3883 | @end example
|
|---|
| 3884 |
|
|---|
| 3885 | @noindent
|
|---|
| 3886 | However, either of these alternatives would work properly:
|
|---|
| 3887 |
|
|---|
| 3888 | @example
|
|---|
| 3889 | .ONESHELL:
|
|---|
| 3890 | SHELL = /usr/bin/perl
|
|---|
| 3891 | .SHELLFLAGS = -e
|
|---|
| 3892 | show :
|
|---|
| 3893 | # Make sure "@@" is not the first character on the first line
|
|---|
| 3894 | @@f = qw(a b c);
|
|---|
| 3895 | print "@@f\n";
|
|---|
| 3896 | @end example
|
|---|
| 3897 |
|
|---|
| 3898 | @noindent
|
|---|
| 3899 | or
|
|---|
| 3900 |
|
|---|
| 3901 | @example
|
|---|
| 3902 | .ONESHELL:
|
|---|
| 3903 | SHELL = /usr/bin/perl
|
|---|
| 3904 | .SHELLFLAGS = -e
|
|---|
| 3905 | show :
|
|---|
| 3906 | my @@f = qw(a b c);
|
|---|
| 3907 | print "@@f\n";
|
|---|
| 3908 | @end example
|
|---|
| 3909 |
|
|---|
| 3910 | As a special feature, if @code{SHELL} is determined to be a
|
|---|
| 3911 | POSIX-style shell, the special prefix characters in ``internal''
|
|---|
| 3912 | recipe lines will @emph{removed} before the recipe is processed. This
|
|---|
| 3913 | feature is intended to allow existing makefiles to add the
|
|---|
| 3914 | @code{.ONESHELL} special target and still run properly without
|
|---|
| 3915 | extensive modifications. Since the special prefix characters are not
|
|---|
| 3916 | legal at the beginning of a line in a POSIX shell script this is not a
|
|---|
| 3917 | loss in functionality. For example, this works as expected:
|
|---|
| 3918 |
|
|---|
| 3919 | @example
|
|---|
| 3920 | .ONESHELL:
|
|---|
| 3921 | foo : bar/lose
|
|---|
| 3922 | @@cd $(@@D)
|
|---|
| 3923 | @@gobble $(@@F) > ../$@@
|
|---|
| 3924 | @end example
|
|---|
| 3925 |
|
|---|
| 3926 | Even with this special feature, however, makefiles with
|
|---|
| 3927 | @code{.ONESHELL} will behave differently in ways that could be
|
|---|
| 3928 | noticeable. For example, normally if any line in the recipe fails,
|
|---|
| 3929 | that causes the rule to fail and no more recipe lines are processed.
|
|---|
| 3930 | Under @code{.ONESHELL} a failure of any but the final recipe line will
|
|---|
| 3931 | not be noticed by @code{make}. You can modify @code{.SHELLFLAGS} to
|
|---|
| 3932 | add the @code{-e} option to the shell which will cause any failure
|
|---|
| 3933 | anywhere in the command line to cause the shell to fail, but this
|
|---|
| 3934 | could itself cause your recipe to behave differently. Ultimately you
|
|---|
| 3935 | may need to harden your recipe lines to allow them to work with
|
|---|
| 3936 | @code{.ONESHELL}.
|
|---|
| 3937 |
|
|---|
| 3938 | @node Choosing the Shell, , One Shell, Execution
|
|---|
| 3939 | @subsection Choosing the Shell
|
|---|
| 3940 | @cindex shell, choosing the
|
|---|
| 3941 | @cindex @code{SHELL}, value of
|
|---|
| 3942 | @cindex @code{.SHELLFLAGS}, value of
|
|---|
| 3943 |
|
|---|
| 3944 | @vindex SHELL
|
|---|
| 3945 | @vindex .SHELLFLAGS
|
|---|
| 3946 | The program used as the shell is taken from the variable @code{SHELL}.
|
|---|
| 3947 | If this variable is not set in your makefile, the program
|
|---|
| 3948 | @file{/bin/sh} is used as the shell. The argument(s) passed to the
|
|---|
| 3949 | shell are taken from the variable @code{.SHELLFLAGS}. The default
|
|---|
| 3950 | value of @code{.SHELLFLAGS} is @code{-c} normally, or @code{-ec} in
|
|---|
| 3951 | POSIX-conforming mode.
|
|---|
| 3952 |
|
|---|
| 3953 | @cindex environment, @code{SHELL} in
|
|---|
| 3954 | Unlike most variables, the variable @code{SHELL} is never set from the
|
|---|
| 3955 | environment. This is because the @code{SHELL} environment variable is
|
|---|
| 3956 | used to specify your personal choice of shell program for interactive
|
|---|
| 3957 | use. It would be very bad for personal choices like this to affect the
|
|---|
| 3958 | functioning of makefiles. @xref{Environment, ,Variables from the
|
|---|
| 3959 | Environment}.
|
|---|
| 3960 |
|
|---|
| 3961 | Furthermore, when you do set @code{SHELL} in your makefile that value
|
|---|
| 3962 | is @emph{not} exported in the environment to recipe lines that
|
|---|
| 3963 | @code{make} invokes. Instead, the value inherited from the user's
|
|---|
| 3964 | environment, if any, is exported. You can override this behavior by
|
|---|
| 3965 | explicitly exporting @code{SHELL} (@pxref{Variables/Recursion,
|
|---|
| 3966 | ,Communicating Variables to a Sub-@code{make}}), forcing it to be
|
|---|
| 3967 | passed in the environment to recipe lines.
|
|---|
| 3968 |
|
|---|
| 3969 | @vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})}
|
|---|
| 3970 | However, on MS-DOS and MS-Windows the value of @code{SHELL} in the
|
|---|
| 3971 | environment @strong{is} used, since on those systems most users do not
|
|---|
| 3972 | set this variable, and therefore it is most likely set specifically to
|
|---|
| 3973 | be used by @code{make}. On MS-DOS, if the setting of @code{SHELL} is
|
|---|
| 3974 | not suitable for @code{make}, you can set the variable
|
|---|
| 3975 | @code{MAKESHELL} to the shell that @code{make} should use; if set it
|
|---|
| 3976 | will be used as the shell instead of the value of @code{SHELL}.
|
|---|
| 3977 |
|
|---|
| 3978 | @subsubheading Choosing a Shell in DOS and Windows
|
|---|
| 3979 | @cindex shell, in DOS and Windows
|
|---|
| 3980 | @cindex DOS, choosing a shell in
|
|---|
| 3981 | @cindex Windows, choosing a shell in
|
|---|
| 3982 |
|
|---|
| 3983 | Choosing a shell in MS-DOS and MS-Windows is much more complex than on
|
|---|
| 3984 | other systems.
|
|---|
| 3985 |
|
|---|
| 3986 | @vindex COMSPEC
|
|---|
| 3987 | On MS-DOS, if @code{SHELL} is not set, the value of the variable
|
|---|
| 3988 | @code{COMSPEC} (which is always set) is used instead.
|
|---|
| 3989 |
|
|---|
| 3990 | @cindex @code{SHELL}, MS-DOS specifics
|
|---|
| 3991 | The processing of lines that set the variable @code{SHELL} in Makefiles
|
|---|
| 3992 | is different on MS-DOS. The stock shell, @file{command.com}, is
|
|---|
| 3993 | ridiculously limited in its functionality and many users of @code{make}
|
|---|
| 3994 | tend to install a replacement shell. Therefore, on MS-DOS, @code{make}
|
|---|
| 3995 | examines the value of @code{SHELL}, and changes its behavior based on
|
|---|
| 3996 | whether it points to a Unix-style or DOS-style shell. This allows
|
|---|
| 3997 | reasonable functionality even if @code{SHELL} points to
|
|---|
| 3998 | @file{command.com}.
|
|---|
| 3999 |
|
|---|
| 4000 | If @code{SHELL} points to a Unix-style shell, @code{make} on MS-DOS
|
|---|
| 4001 | additionally checks whether that shell can indeed be found; if not, it
|
|---|
| 4002 | ignores the line that sets @code{SHELL}. In MS-DOS, GNU @code{make}
|
|---|
| 4003 | searches for the shell in the following places:
|
|---|
| 4004 |
|
|---|
| 4005 | @enumerate
|
|---|
| 4006 | @item
|
|---|
| 4007 | In the precise place pointed to by the value of @code{SHELL}. For
|
|---|
| 4008 | example, if the makefile specifies @samp{SHELL = /bin/sh}, @code{make}
|
|---|
| 4009 | will look in the directory @file{/bin} on the current drive.
|
|---|
| 4010 |
|
|---|
| 4011 | @item
|
|---|
| 4012 | In the current directory.
|
|---|
| 4013 |
|
|---|
| 4014 | @item
|
|---|
| 4015 | In each of the directories in the @code{PATH} variable, in order.
|
|---|
| 4016 |
|
|---|
| 4017 | @end enumerate
|
|---|
| 4018 |
|
|---|
| 4019 | In every directory it examines, @code{make} will first look for the
|
|---|
| 4020 | specific file (@file{sh} in the example above). If this is not found,
|
|---|
| 4021 | it will also look in that directory for that file with one of the known
|
|---|
| 4022 | extensions which identify executable files. For example @file{.exe},
|
|---|
| 4023 | @file{.com}, @file{.bat}, @file{.btm}, @file{.sh}, and some others.
|
|---|
| 4024 |
|
|---|
| 4025 | If any of these attempts is successful, the value of @code{SHELL} will
|
|---|
| 4026 | be set to the full pathname of the shell as found. However, if none of
|
|---|
| 4027 | these is found, the value of @code{SHELL} will not be changed, and thus
|
|---|
| 4028 | the line that sets it will be effectively ignored. This is so
|
|---|
| 4029 | @code{make} will only support features specific to a Unix-style shell if
|
|---|
| 4030 | such a shell is actually installed on the system where @code{make} runs.
|
|---|
| 4031 |
|
|---|
| 4032 | Note that this extended search for the shell is limited to the cases
|
|---|
| 4033 | where @code{SHELL} is set from the Makefile; if it is set in the
|
|---|
| 4034 | environment or command line, you are expected to set it to the full
|
|---|
| 4035 | pathname of the shell, exactly as things are on Unix.
|
|---|
| 4036 |
|
|---|
| 4037 | The effect of the above DOS-specific processing is that a Makefile that
|
|---|
| 4038 | contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work
|
|---|
| 4039 | on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some
|
|---|
| 4040 | directory along your @code{PATH}.
|
|---|
| 4041 |
|
|---|
| 4042 | @vindex SHELL
|
|---|
| 4043 | @vindex .SHELLFLAGS
|
|---|
| 4044 |
|
|---|
| 4045 | @node Parallel, Errors, Execution, Recipes
|
|---|
| 4046 | @section Parallel Execution
|
|---|
| 4047 | @cindex recipes, execution in parallel
|
|---|
| 4048 | @cindex parallel execution
|
|---|
| 4049 | @cindex execution, in parallel
|
|---|
| 4050 | @cindex job slots
|
|---|
| 4051 | @cindex @code{-j}
|
|---|
| 4052 | @cindex @code{--jobs}
|
|---|
| 4053 |
|
|---|
| 4054 | GNU @code{make} knows how to execute several recipes at once.
|
|---|
| 4055 | Normally, @code{make} will execute only one recipe at a time, waiting
|
|---|
| 4056 | for it to finish before executing the next. However, the @samp{-j} or
|
|---|
| 4057 | @samp{--jobs} option tells @code{make} to execute many recipes
|
|---|
| 4058 | simultaneously. You can inhibit parallelism in a particular makefile
|
|---|
| 4059 | with the @code{.NOTPARALLEL} pseudo-target (@pxref{Special
|
|---|
| 4060 | Targets,Special Built-in Target Names}).@refill
|
|---|
| 4061 |
|
|---|
| 4062 | On MS-DOS, the @samp{-j} option has no effect, since that system doesn't
|
|---|
| 4063 | support multi-processing.
|
|---|
| 4064 |
|
|---|
| 4065 | If the @samp{-j} option is followed by an integer, this is the number of
|
|---|
| 4066 | recipes to execute at once; this is called the number of @dfn{job slots}.
|
|---|
| 4067 | If there is nothing looking like an integer after the @samp{-j} option,
|
|---|
| 4068 | there is no limit on the number of job slots. The default number of job
|
|---|
| 4069 | slots is one, which means serial execution (one thing at a time).
|
|---|
| 4070 |
|
|---|
| 4071 | Handling recursive @code{make} invocations raises issues for parallel
|
|---|
| 4072 | execution. For more information on this, see @ref{Options/Recursion,
|
|---|
| 4073 | ,Communicating Options to a Sub-@code{make}}.
|
|---|
| 4074 |
|
|---|
| 4075 | If a recipe fails (is killed by a signal or exits with a nonzero
|
|---|
| 4076 | status), and errors are not ignored for that recipe (@pxref{Errors,
|
|---|
| 4077 | ,Errors in Recipes}), the remaining recipe lines to remake the same
|
|---|
| 4078 | target will not be run. If a recipe fails and the @samp{-k} or
|
|---|
| 4079 | @samp{--keep-going} option was not given (@pxref{Options Summary,
|
|---|
| 4080 | ,Summary of Options}), @code{make} aborts execution. If make
|
|---|
| 4081 | terminates for any reason (including a signal) with child processes
|
|---|
| 4082 | running, it waits for them to finish before actually exiting.@refill
|
|---|
| 4083 |
|
|---|
| 4084 | @cindex load average
|
|---|
| 4085 | @cindex limiting jobs based on load
|
|---|
| 4086 | @cindex jobs, limiting based on load
|
|---|
| 4087 | @cindex @code{-l} (load average)
|
|---|
| 4088 | @cindex @code{--max-load}
|
|---|
| 4089 | @cindex @code{--load-average}
|
|---|
| 4090 | When the system is heavily loaded, you will probably want to run fewer jobs
|
|---|
| 4091 | than when it is lightly loaded. You can use the @samp{-l} option to tell
|
|---|
| 4092 | @code{make} to limit the number of jobs to run at once, based on the load
|
|---|
| 4093 | average. The @samp{-l} or @samp{--max-load}
|
|---|
| 4094 | option is followed by a floating-point number. For
|
|---|
| 4095 | example,
|
|---|
| 4096 |
|
|---|
| 4097 | @example
|
|---|
| 4098 | -l 2.5
|
|---|
| 4099 | @end example
|
|---|
| 4100 |
|
|---|
| 4101 | @noindent
|
|---|
| 4102 | will not let @code{make} start more than one job if the load average is
|
|---|
| 4103 | above 2.5. The @samp{-l} option with no following number removes the
|
|---|
| 4104 | load limit, if one was given with a previous @samp{-l} option.@refill
|
|---|
| 4105 |
|
|---|
| 4106 | More precisely, when @code{make} goes to start up a job, and it already has
|
|---|
| 4107 | at least one job running, it checks the current load average; if it is not
|
|---|
| 4108 | lower than the limit given with @samp{-l}, @code{make} waits until the load
|
|---|
| 4109 | average goes below that limit, or until all the other jobs finish.
|
|---|
| 4110 |
|
|---|
| 4111 | By default, there is no load limit.
|
|---|
| 4112 |
|
|---|
| 4113 | @menu
|
|---|
| 4114 | * Parallel Output:: Handling output during parallel execution
|
|---|
| 4115 | * Parallel Input:: Handling input during parallel execution
|
|---|
| 4116 | @end menu
|
|---|
| 4117 |
|
|---|
| 4118 | @node Parallel Output, Parallel Input, Parallel, Parallel
|
|---|
| 4119 | @subsection Output During Parallel Execution
|
|---|
| 4120 | @cindex output during parallel execution
|
|---|
| 4121 | @cindex parallel execution, output during
|
|---|
| 4122 |
|
|---|
| 4123 | When running several recipes in parallel the output from each
|
|---|
| 4124 | recipe appears as soon as it is generated, with the result that
|
|---|
| 4125 | messages from different recipes may be interspersed, sometimes even
|
|---|
| 4126 | appearing on the same line. This can make reading the output very
|
|---|
| 4127 | difficult.
|
|---|
| 4128 |
|
|---|
| 4129 | @cindex @code{--output-sync}
|
|---|
| 4130 | @cindex @code{-O}
|
|---|
| 4131 | To avoid this you can use the @samp{--output-sync} (@samp{-O}) option.
|
|---|
| 4132 | This option instructs @code{make} to save the output from the commands
|
|---|
| 4133 | it invokes and print it all once the commands are completed.
|
|---|
| 4134 | Additionally, if there are multiple recursive @code{make} invocations
|
|---|
| 4135 | running in parallel, they will communicate so that only one of them is
|
|---|
| 4136 | generating output at a time.
|
|---|
| 4137 |
|
|---|
| 4138 | If working directory printing is enabled (@pxref{-w Option, ,The
|
|---|
| 4139 | @samp{--print-directory} Option}), the enter/leave messages are
|
|---|
| 4140 | printed around each output grouping. If you prefer not to see these
|
|---|
| 4141 | messages add the @samp{--no-print-directory} option to @code{MAKEFLAGS}.
|
|---|
| 4142 |
|
|---|
| 4143 | There are four levels of granularity when synchronizing output,
|
|---|
| 4144 | specified by giving an argument to the option (e.g., @samp{-Oline} or
|
|---|
| 4145 | @samp{--output-sync=recurse}).
|
|---|
| 4146 |
|
|---|
| 4147 | @table @code
|
|---|
| 4148 | @item none
|
|---|
| 4149 | This is the default: all output is sent directly as it is generated and
|
|---|
| 4150 | no synchronization is performed.
|
|---|
| 4151 |
|
|---|
| 4152 | @item line
|
|---|
| 4153 | Output from each individual line of the recipe is grouped and printed
|
|---|
| 4154 | as soon as that line is complete. If a recipe consists of multiple
|
|---|
| 4155 | lines, they may be interspersed with lines from other recipes.
|
|---|
| 4156 |
|
|---|
| 4157 | @item target
|
|---|
| 4158 | Output from the entire recipe for each target is grouped and printed
|
|---|
| 4159 | once the target is complete. This is the default if the
|
|---|
| 4160 | @code{--output-sync} or @code{-O} option is given with no argument.
|
|---|
| 4161 |
|
|---|
| 4162 | @item recurse
|
|---|
| 4163 | Output from each recursive invocation of @code{make} is grouped and
|
|---|
| 4164 | printed once the recursive invocation is complete.
|
|---|
| 4165 |
|
|---|
| 4166 | @end table
|
|---|
| 4167 |
|
|---|
| 4168 | Regardless of the mode chosen, the total build time will be the same.
|
|---|
| 4169 | The only difference is in how the output appears.
|
|---|
| 4170 |
|
|---|
| 4171 | The @samp{target} and @samp{recurse} modes both collect the output of
|
|---|
| 4172 | the entire recipe of a target and display it uninterrupted when the
|
|---|
| 4173 | recipe completes. The difference between them is in how recipes that
|
|---|
| 4174 | contain recursive invocations of @code{make} are treated
|
|---|
| 4175 | (@pxref{Recursion, ,Recursive Use of @code{make}}). For all recipes
|
|---|
| 4176 | which have no recursive lines, the @samp{target} and @samp{recurse}
|
|---|
| 4177 | modes behave identically.
|
|---|
| 4178 |
|
|---|
| 4179 | If the @samp{recurse} mode is chosen, recipes that contain recursive
|
|---|
| 4180 | @code{make} invocations are treated the same as other targets: the
|
|---|
| 4181 | output from the recipe, including the output from the recursive
|
|---|
| 4182 | @code{make}, is saved and printed after the entire recipe is complete.
|
|---|
| 4183 | This ensures output from all the targets built by a given recursive
|
|---|
| 4184 | @code{make} instance are grouped together, which may make the output
|
|---|
| 4185 | easier to understand. However it also leads to long periods of time
|
|---|
| 4186 | during the build where no output is seen, followed by large bursts of
|
|---|
| 4187 | output. If you are not watching the build as it proceeds, but instead
|
|---|
| 4188 | viewing a log of the build after the fact, this may be the best option
|
|---|
| 4189 | for you.
|
|---|
| 4190 |
|
|---|
| 4191 | If you are watching the output, the long gaps of quiet during the
|
|---|
| 4192 | build can be frustrating. The @samp{target} output synchronization
|
|---|
| 4193 | mode detects when @code{make} is going to be invoked recursively,
|
|---|
| 4194 | using the standard methods, and it will not synchronize the output of
|
|---|
| 4195 | those lines. The recursive @code{make} will perform the
|
|---|
| 4196 | synchronization for its targets and the output from each will be
|
|---|
| 4197 | displayed immediately when it completes. Be aware that output from
|
|---|
| 4198 | recursive lines of the recipe are not synchronized (for example if
|
|---|
| 4199 | the recursive line prints a message before running @code{make}, that
|
|---|
| 4200 | message will not be synchronized).
|
|---|
| 4201 |
|
|---|
| 4202 | The @samp{line} mode can be useful for front-ends that are watching
|
|---|
| 4203 | the output of @code{make} to track when recipes are started and
|
|---|
| 4204 | completed.
|
|---|
| 4205 |
|
|---|
| 4206 | Some programs invoked by @code{make} may behave differently if they
|
|---|
| 4207 | determine they're writing output to a terminal versus a file (often
|
|---|
| 4208 | described as ``interactive'' vs. ``non-interactive'' modes). For
|
|---|
| 4209 | example, many programs that can display colorized output will not do
|
|---|
| 4210 | so if they determine they are not writing to a terminal. If your
|
|---|
| 4211 | makefile invokes a program like this then using the output
|
|---|
| 4212 | synchronization options will cause the program to believe it's running
|
|---|
| 4213 | in ``non-interactive'' mode even though the output will ultimately go
|
|---|
| 4214 | to the terminal.
|
|---|
| 4215 |
|
|---|
| 4216 | @node Parallel Input, , Parallel Output, Parallel
|
|---|
| 4217 | @subsection Input During Parallel Execution
|
|---|
| 4218 | @cindex input during parallel execution
|
|---|
| 4219 | @cindex parallel execution, input during
|
|---|
| 4220 | @cindex standard input
|
|---|
| 4221 |
|
|---|
| 4222 | Two processes cannot both take input from the same device at the same
|
|---|
| 4223 | time. To make sure that only one recipe tries to take input from the
|
|---|
| 4224 | terminal at once, @code{make} will invalidate the standard input
|
|---|
| 4225 | streams of all but one running recipe. If another recipe attempts to
|
|---|
| 4226 | read from standard input it will usually incur a fatal error (a
|
|---|
| 4227 | @samp{Broken pipe} signal).
|
|---|
| 4228 | @cindex broken pipe
|
|---|
| 4229 |
|
|---|
| 4230 | It is unpredictable which recipe will have a valid standard input stream
|
|---|
| 4231 | (which will come from the terminal, or wherever you redirect the standard
|
|---|
| 4232 | input of @code{make}). The first recipe run will always get it first, and
|
|---|
| 4233 | the first recipe started after that one finishes will get it next, and so
|
|---|
| 4234 | on.
|
|---|
| 4235 |
|
|---|
| 4236 | We will change how this aspect of @code{make} works if we find a better
|
|---|
| 4237 | alternative. In the mean time, you should not rely on any recipe using
|
|---|
| 4238 | standard input at all if you are using the parallel execution feature; but
|
|---|
| 4239 | if you are not using this feature, then standard input works normally in
|
|---|
| 4240 | all recipes.
|
|---|
| 4241 |
|
|---|
| 4242 | @node Errors, Interrupts, Parallel, Recipes
|
|---|
| 4243 | @section Errors in Recipes
|
|---|
| 4244 | @cindex errors (in recipes)
|
|---|
| 4245 | @cindex recipes, errors in
|
|---|
| 4246 | @cindex exit status (errors)
|
|---|
| 4247 |
|
|---|
| 4248 | After each shell invocation returns, @code{make} looks at its exit
|
|---|
| 4249 | status. If the shell completed successfully (the exit status is
|
|---|
| 4250 | zero), the next line in the recipe is executed in a new shell; after
|
|---|
| 4251 | the last line is finished, the rule is finished.
|
|---|
| 4252 |
|
|---|
| 4253 | If there is an error (the exit status is nonzero), @code{make} gives up on
|
|---|
| 4254 | the current rule, and perhaps on all rules.
|
|---|
| 4255 |
|
|---|
| 4256 | Sometimes the failure of a certain recipe line does not indicate a problem.
|
|---|
| 4257 | For example, you may use the @code{mkdir} command to ensure that a
|
|---|
| 4258 | directory exists. If the directory already exists, @code{mkdir} will
|
|---|
| 4259 | report an error, but you probably want @code{make} to continue regardless.
|
|---|
| 4260 |
|
|---|
| 4261 | @cindex @code{-} (in recipes)
|
|---|
| 4262 | To ignore errors in a recipe line, write a @samp{-} at the beginning
|
|---|
| 4263 | of the line's text (after the initial tab). The @samp{-} is discarded
|
|---|
| 4264 | before the line is passed to the shell for execution.
|
|---|
| 4265 |
|
|---|
| 4266 | For example,
|
|---|
| 4267 |
|
|---|
| 4268 | @example
|
|---|
| 4269 | @group
|
|---|
| 4270 | clean:
|
|---|
| 4271 | -rm -f *.o
|
|---|
| 4272 | @end group
|
|---|
| 4273 | @end example
|
|---|
| 4274 | @cindex @code{rm} (shell command)
|
|---|
| 4275 |
|
|---|
| 4276 | @noindent
|
|---|
| 4277 | This causes @code{make} to continue even if @code{rm} is unable to
|
|---|
| 4278 | remove a file.
|
|---|
| 4279 |
|
|---|
| 4280 | @cindex @code{-i}
|
|---|
| 4281 | @cindex @code{--ignore-errors}
|
|---|
| 4282 | @findex .IGNORE
|
|---|
| 4283 | When you run @code{make} with the @samp{-i} or @samp{--ignore-errors}
|
|---|
| 4284 | flag, errors are ignored in all recipes of all rules. A rule in the
|
|---|
| 4285 | makefile for the special target @code{.IGNORE} has the same effect, if
|
|---|
| 4286 | there are no prerequisites. These ways of ignoring errors are obsolete
|
|---|
| 4287 | because @samp{-} is more flexible.
|
|---|
| 4288 |
|
|---|
| 4289 | When errors are to be ignored, because of either a @samp{-} or the
|
|---|
| 4290 | @samp{-i} flag, @code{make} treats an error return just like success,
|
|---|
| 4291 | except that it prints out a message that tells you the status code
|
|---|
| 4292 | the shell exited with, and says that the error has been ignored.
|
|---|
| 4293 |
|
|---|
| 4294 | When an error happens that @code{make} has not been told to ignore,
|
|---|
| 4295 | it implies that the current target cannot be correctly remade, and neither
|
|---|
| 4296 | can any other that depends on it either directly or indirectly. No further
|
|---|
| 4297 | recipes will be executed for these targets, since their preconditions
|
|---|
| 4298 | have not been achieved.
|
|---|
| 4299 |
|
|---|
| 4300 |
|
|---|
| 4301 | @cindex @code{-k}
|
|---|
| 4302 | @cindex @code{--keep-going}
|
|---|
| 4303 | Normally @code{make} gives up immediately in this circumstance, returning a
|
|---|
| 4304 | nonzero status. However, if the @samp{-k} or @samp{--keep-going}
|
|---|
| 4305 | flag is specified, @code{make}
|
|---|
| 4306 | continues to consider the other prerequisites of the pending targets,
|
|---|
| 4307 | remaking them if necessary, before it gives up and returns nonzero status.
|
|---|
| 4308 | For example, after an error in compiling one object file, @samp{make -k}
|
|---|
| 4309 | will continue compiling other object files even though it already knows
|
|---|
| 4310 | that linking them will be impossible. @xref{Options Summary, ,Summary of Options}.
|
|---|
| 4311 |
|
|---|
| 4312 | The usual behavior assumes that your purpose is to get the specified
|
|---|
| 4313 | targets up to date; once @code{make} learns that this is impossible, it
|
|---|
| 4314 | might as well report the failure immediately. The @samp{-k} option says
|
|---|
| 4315 | that the real purpose is to test as many of the changes made in the
|
|---|
| 4316 | program as possible, perhaps to find several independent problems so
|
|---|
| 4317 | that you can correct them all before the next attempt to compile. This
|
|---|
| 4318 | is why Emacs' @code{compile} command passes the @samp{-k} flag by
|
|---|
| 4319 | default.
|
|---|
| 4320 | @cindex Emacs (@code{M-x compile})
|
|---|
| 4321 |
|
|---|
| 4322 | @findex .DELETE_ON_ERROR
|
|---|
| 4323 | @cindex deletion of target files
|
|---|
| 4324 | @cindex removal of target files
|
|---|
| 4325 | @cindex target, deleting on error
|
|---|
| 4326 | Usually when a recipe line fails, if it has changed the target file at all,
|
|---|
| 4327 | the file is corrupted and cannot be used---or at least it is not
|
|---|
| 4328 | completely updated. Yet the file's time stamp says that it is now up to
|
|---|
| 4329 | date, so the next time @code{make} runs, it will not try to update that
|
|---|
| 4330 | file. The situation is just the same as when the shell is killed by a
|
|---|
| 4331 | signal; @pxref{Interrupts}. So generally the right thing to do is to
|
|---|
| 4332 | delete the target file if the recipe fails after beginning to change
|
|---|
| 4333 | the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears
|
|---|
| 4334 | as a target. This is almost always what you want @code{make} to do, but
|
|---|
| 4335 | it is not historical practice; so for compatibility, you must explicitly
|
|---|
| 4336 | request it.
|
|---|
| 4337 |
|
|---|
| 4338 | @node Interrupts, Recursion, Errors, Recipes
|
|---|
| 4339 | @section Interrupting or Killing @code{make}
|
|---|
| 4340 | @cindex interrupt
|
|---|
| 4341 | @cindex signal
|
|---|
| 4342 | @cindex deletion of target files
|
|---|
| 4343 | @cindex removal of target files
|
|---|
| 4344 | @cindex target, deleting on interrupt
|
|---|
| 4345 | @cindex killing (interruption)
|
|---|
| 4346 |
|
|---|
| 4347 | If @code{make} gets a fatal signal while a shell is executing, it may
|
|---|
| 4348 | delete the target file that the recipe was supposed to update. This is
|
|---|
| 4349 | done if the target file's last-modification time has changed since
|
|---|
| 4350 | @code{make} first checked it.
|
|---|
| 4351 |
|
|---|
| 4352 | The purpose of deleting the target is to make sure that it is remade from
|
|---|
| 4353 | scratch when @code{make} is next run. Why is this? Suppose you type
|
|---|
| 4354 | @kbd{Ctrl-c} while a compiler is running, and it has begun to write an
|
|---|
| 4355 | object file @file{foo.o}. The @kbd{Ctrl-c} kills the compiler, resulting
|
|---|
| 4356 | in an incomplete file whose last-modification time is newer than the source
|
|---|
| 4357 | file @file{foo.c}. But @code{make} also receives the @kbd{Ctrl-c} signal
|
|---|
| 4358 | and deletes this incomplete file. If @code{make} did not do this, the next
|
|---|
| 4359 | invocation of @code{make} would think that @file{foo.o} did not require
|
|---|
| 4360 | updating---resulting in a strange error message from the linker when it
|
|---|
| 4361 | tries to link an object file half of which is missing.
|
|---|
| 4362 |
|
|---|
| 4363 | @findex .PRECIOUS
|
|---|
| 4364 | You can prevent the deletion of a target file in this way by making the
|
|---|
| 4365 | special target @code{.PRECIOUS} depend on it. Before remaking a target,
|
|---|
| 4366 | @code{make} checks to see whether it appears on the prerequisites of
|
|---|
| 4367 | @code{.PRECIOUS}, and thereby decides whether the target should be deleted
|
|---|
| 4368 | if a signal happens. Some reasons why you might do this are that the
|
|---|
| 4369 | target is updated in some atomic fashion, or exists only to record a
|
|---|
| 4370 | modification-time (its contents do not matter), or must exist at all
|
|---|
| 4371 | times to prevent other sorts of trouble.
|
|---|
| 4372 |
|
|---|
| 4373 | @node Recursion, Canned Recipes, Interrupts, Recipes
|
|---|
| 4374 | @section Recursive Use of @code{make}
|
|---|
| 4375 | @cindex recursion
|
|---|
| 4376 | @cindex subdirectories, recursion for
|
|---|
| 4377 |
|
|---|
| 4378 | Recursive use of @code{make} means using @code{make} as a command in a
|
|---|
| 4379 | makefile. This technique is useful when you want separate makefiles for
|
|---|
| 4380 | various subsystems that compose a larger system. For example, suppose you
|
|---|
| 4381 | have a sub-directory @file{subdir} which has its own makefile, and you would
|
|---|
| 4382 | like the containing directory's makefile to run @code{make} on the
|
|---|
| 4383 | sub-directory. You can do it by writing this:
|
|---|
| 4384 |
|
|---|
| 4385 | @example
|
|---|
| 4386 | subsystem:
|
|---|
| 4387 | cd subdir && $(MAKE)
|
|---|
| 4388 | @end example
|
|---|
| 4389 |
|
|---|
| 4390 | @noindent
|
|---|
| 4391 | or, equivalently, this (@pxref{Options Summary, ,Summary of Options}):
|
|---|
| 4392 |
|
|---|
| 4393 | @example
|
|---|
| 4394 | subsystem:
|
|---|
| 4395 | $(MAKE) -C subdir
|
|---|
| 4396 | @end example
|
|---|
| 4397 | @cindex @code{-C}
|
|---|
| 4398 | @cindex @code{--directory}
|
|---|
| 4399 |
|
|---|
| 4400 | You can write recursive @code{make} commands just by copying this example,
|
|---|
| 4401 | but there are many things to know about how they work and why, and about
|
|---|
| 4402 | how the sub-@code{make} relates to the top-level @code{make}. You may
|
|---|
| 4403 | also find it useful to declare targets that invoke recursive
|
|---|
| 4404 | @code{make} commands as @samp{.PHONY} (for more discussion on when
|
|---|
| 4405 | this is useful, see @ref{Phony Targets}).
|
|---|
| 4406 |
|
|---|
| 4407 | @vindex @code{CURDIR}
|
|---|
| 4408 | For your convenience, when GNU @code{make} starts (after it has
|
|---|
| 4409 | processed any @code{-C} options) it sets the variable @code{CURDIR} to
|
|---|
| 4410 | the pathname of the current working directory. This value is never
|
|---|
| 4411 | touched by @code{make} again: in particular note that if you include
|
|---|
| 4412 | files from other directories the value of @code{CURDIR} does not
|
|---|
| 4413 | change. The value has the same precedence it would have if it were
|
|---|
| 4414 | set in the makefile (by default, an environment variable @code{CURDIR}
|
|---|
| 4415 | will not override this value). Note that setting this variable has no
|
|---|
| 4416 | impact on the operation of @code{make} (it does not cause @code{make}
|
|---|
| 4417 | to change its working directory, for example).
|
|---|
| 4418 |
|
|---|
| 4419 | @menu
|
|---|
| 4420 | * MAKE Variable:: The special effects of using @samp{$(MAKE)}.
|
|---|
| 4421 | * Variables/Recursion:: How to communicate variables to a sub-@code{make}.
|
|---|
| 4422 | * Options/Recursion:: How to communicate options to a sub-@code{make}.
|
|---|
| 4423 | * -w Option:: How the @samp{-w} or @samp{--print-directory} option
|
|---|
| 4424 | helps debug use of recursive @code{make} commands.
|
|---|
| 4425 | @end menu
|
|---|
| 4426 |
|
|---|
| 4427 | @node MAKE Variable, Variables/Recursion, Recursion, Recursion
|
|---|
| 4428 | @subsection How the @code{MAKE} Variable Works
|
|---|
| 4429 | @vindex MAKE
|
|---|
| 4430 | @cindex recursion, and @code{MAKE} variable
|
|---|
| 4431 |
|
|---|
| 4432 | Recursive @code{make} commands should always use the variable @code{MAKE},
|
|---|
| 4433 | not the explicit command name @samp{make}, as shown here:
|
|---|
| 4434 |
|
|---|
| 4435 | @example
|
|---|
| 4436 | @group
|
|---|
| 4437 | subsystem:
|
|---|
| 4438 | cd subdir && $(MAKE)
|
|---|
| 4439 | @end group
|
|---|
| 4440 | @end example
|
|---|
| 4441 |
|
|---|
| 4442 | The value of this variable is the file name with which @code{make} was
|
|---|
| 4443 | invoked. If this file name was @file{/bin/make}, then the recipe executed
|
|---|
| 4444 | is @samp{cd subdir && /bin/make}. If you use a special version of
|
|---|
| 4445 | @code{make} to run the top-level makefile, the same special version will be
|
|---|
| 4446 | executed for recursive invocations.
|
|---|
| 4447 | @cindex @code{cd} (shell command)
|
|---|
| 4448 |
|
|---|
| 4449 | @cindex +, and recipes
|
|---|
| 4450 | As a special feature, using the variable @code{MAKE} in the recipe of
|
|---|
| 4451 | a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n}
|
|---|
| 4452 | (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option.
|
|---|
| 4453 | Using the @code{MAKE} variable has the same effect as using a @samp{+}
|
|---|
| 4454 | character at the beginning of the recipe line. @xref{Instead of
|
|---|
| 4455 | Execution, ,Instead of Executing the Recipes}. This special feature
|
|---|
| 4456 | is only enabled if the @code{MAKE} variable appears directly in the
|
|---|
| 4457 | recipe: it does not apply if the @code{MAKE} variable is referenced
|
|---|
| 4458 | through expansion of another variable. In the latter case you must
|
|---|
| 4459 | use the @samp{+} token to get these special effects.@refill
|
|---|
| 4460 |
|
|---|
| 4461 | Consider the command @samp{make -t} in the above example. (The
|
|---|
| 4462 | @samp{-t} option marks targets as up to date without actually running
|
|---|
| 4463 | any recipes; see @ref{Instead of Execution}.) Following the usual
|
|---|
| 4464 | definition of @samp{-t}, a @samp{make -t} command in the example would
|
|---|
| 4465 | create a file named @file{subsystem} and do nothing else. What you
|
|---|
| 4466 | really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but
|
|---|
| 4467 | that would require executing the recipe, and @samp{-t} says not to
|
|---|
| 4468 | execute recipes.@refill
|
|---|
| 4469 | @cindex @code{-t}, and recursion
|
|---|
| 4470 | @cindex recursion, and @code{-t}
|
|---|
| 4471 | @cindex @code{--touch}, and recursion
|
|---|
| 4472 |
|
|---|
| 4473 | The special feature makes this do what you want: whenever a recipe
|
|---|
| 4474 | line of a rule contains the variable @code{MAKE}, the flags @samp{-t},
|
|---|
| 4475 | @samp{-n} and @samp{-q} do not apply to that line. Recipe lines
|
|---|
| 4476 | containing @code{MAKE} are executed normally despite the presence of a
|
|---|
| 4477 | flag that causes most recipes not to be run. The usual
|
|---|
| 4478 | @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make}
|
|---|
| 4479 | (@pxref{Options/Recursion, ,Communicating Options to a
|
|---|
| 4480 | Sub-@code{make}}), so your request to touch the files, or print the
|
|---|
| 4481 | recipes, is propagated to the subsystem.@refill
|
|---|
| 4482 |
|
|---|
| 4483 | @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion
|
|---|
| 4484 | @subsection Communicating Variables to a Sub-@code{make}
|
|---|
| 4485 | @cindex sub-@code{make}
|
|---|
| 4486 | @cindex environment, and recursion
|
|---|
| 4487 | @cindex exporting variables
|
|---|
| 4488 | @cindex variables, environment
|
|---|
| 4489 | @cindex variables, exporting
|
|---|
| 4490 | @cindex recursion, and environment
|
|---|
| 4491 | @cindex recursion, and variables
|
|---|
| 4492 |
|
|---|
| 4493 | Variable values of the top-level @code{make} can be passed to the
|
|---|
| 4494 | sub-@code{make} through the environment by explicit request. These
|
|---|
| 4495 | variables are defined in the sub-@code{make} as defaults, but they do
|
|---|
| 4496 | not override variables defined in the makefile used by
|
|---|
| 4497 | the sub-@code{make} unless you use the @samp{-e} switch (@pxref{Options
|
|---|
| 4498 | Summary, ,Summary of Options}).@refill
|
|---|
| 4499 |
|
|---|
| 4500 | To pass down, or @dfn{export}, a variable, @code{make} adds the
|
|---|
| 4501 | variable and its value to the environment for running each line of the
|
|---|
| 4502 | recipe. The sub-@code{make}, in turn, uses the environment to
|
|---|
| 4503 | initialize its table of variable values. @xref{Environment,
|
|---|
| 4504 | ,Variables from the Environment}.
|
|---|
| 4505 |
|
|---|
| 4506 | Except by explicit request, @code{make} exports a variable only if it
|
|---|
| 4507 | is either defined in the environment initially or set on the command
|
|---|
| 4508 | line, and if its name consists only of letters, numbers, and underscores.
|
|---|
| 4509 | Some shells cannot cope with environment variable names consisting of
|
|---|
| 4510 | characters other than letters, numbers, and underscores.
|
|---|
| 4511 |
|
|---|
| 4512 | @cindex SHELL, exported value
|
|---|
| 4513 | The value of the @code{make} variable @code{SHELL} is not exported.
|
|---|
| 4514 | Instead, the value of the @code{SHELL} variable from the invoking
|
|---|
| 4515 | environment is passed to the sub-@code{make}. You can force
|
|---|
| 4516 | @code{make} to export its value for @code{SHELL} by using the
|
|---|
| 4517 | @code{export} directive, described below. @xref{Choosing the Shell}.
|
|---|
| 4518 |
|
|---|
| 4519 | The special variable @code{MAKEFLAGS} is always exported (unless you
|
|---|
| 4520 | unexport it). @code{MAKEFILES} is exported if you set it to anything.
|
|---|
| 4521 |
|
|---|
| 4522 | @code{make} automatically passes down variable values that were defined
|
|---|
| 4523 | on the command line, by putting them in the @code{MAKEFLAGS} variable.
|
|---|
| 4524 | @iftex
|
|---|
| 4525 | See the next section.
|
|---|
| 4526 | @end iftex
|
|---|
| 4527 | @ifnottex
|
|---|
| 4528 | @xref{Options/Recursion}.
|
|---|
| 4529 | @end ifnottex
|
|---|
| 4530 |
|
|---|
| 4531 | Variables are @emph{not} normally passed down if they were created by
|
|---|
| 4532 | default by @code{make} (@pxref{Implicit Variables, ,Variables Used by
|
|---|
| 4533 | Implicit Rules}). The sub-@code{make} will define these for
|
|---|
| 4534 | itself.@refill
|
|---|
| 4535 |
|
|---|
| 4536 | @findex export
|
|---|
| 4537 | If you want to export specific variables to a sub-@code{make}, use the
|
|---|
| 4538 | @code{export} directive, like this:
|
|---|
| 4539 |
|
|---|
| 4540 | @example
|
|---|
| 4541 | export @var{variable} @dots{}
|
|---|
| 4542 | @end example
|
|---|
| 4543 |
|
|---|
| 4544 | @noindent
|
|---|
| 4545 | @findex unexport
|
|---|
| 4546 | If you want to @emph{prevent} a variable from being exported, use the
|
|---|
| 4547 | @code{unexport} directive, like this:
|
|---|
| 4548 |
|
|---|
| 4549 | @example
|
|---|
| 4550 | unexport @var{variable} @dots{}
|
|---|
| 4551 | @end example
|
|---|
| 4552 |
|
|---|
| 4553 | @noindent
|
|---|
| 4554 | In both of these forms, the arguments to @code{export} and
|
|---|
| 4555 | @code{unexport} are expanded, and so could be variables or functions
|
|---|
| 4556 | which expand to a (list of) variable names to be (un)exported.
|
|---|
| 4557 |
|
|---|
| 4558 | As a convenience, you can define a variable and export it at the same
|
|---|
| 4559 | time by doing:
|
|---|
| 4560 |
|
|---|
| 4561 | @example
|
|---|
| 4562 | export @var{variable} = value
|
|---|
| 4563 | @end example
|
|---|
| 4564 |
|
|---|
| 4565 | @noindent
|
|---|
| 4566 | has the same result as:
|
|---|
| 4567 |
|
|---|
| 4568 | @example
|
|---|
| 4569 | @var{variable} = value
|
|---|
| 4570 | export @var{variable}
|
|---|
| 4571 | @end example
|
|---|
| 4572 |
|
|---|
| 4573 | @noindent
|
|---|
| 4574 | and
|
|---|
| 4575 |
|
|---|
| 4576 | @example
|
|---|
| 4577 | export @var{variable} := value
|
|---|
| 4578 | @end example
|
|---|
| 4579 |
|
|---|
| 4580 | @noindent
|
|---|
| 4581 | has the same result as:
|
|---|
| 4582 |
|
|---|
| 4583 | @example
|
|---|
| 4584 | @var{variable} := value
|
|---|
| 4585 | export @var{variable}
|
|---|
| 4586 | @end example
|
|---|
| 4587 |
|
|---|
| 4588 | Likewise,
|
|---|
| 4589 |
|
|---|
| 4590 | @example
|
|---|
| 4591 | export @var{variable} += value
|
|---|
| 4592 | @end example
|
|---|
| 4593 |
|
|---|
| 4594 | @noindent
|
|---|
| 4595 | is just like:
|
|---|
| 4596 |
|
|---|
| 4597 | @example
|
|---|
| 4598 | @var{variable} += value
|
|---|
| 4599 | export @var{variable}
|
|---|
| 4600 | @end example
|
|---|
| 4601 |
|
|---|
| 4602 | @noindent
|
|---|
| 4603 | @xref{Appending, ,Appending More Text to Variables}.
|
|---|
| 4604 |
|
|---|
| 4605 | You may notice that the @code{export} and @code{unexport} directives
|
|---|
| 4606 | work in @code{make} in the same way they work in the shell, @code{sh}.
|
|---|
| 4607 |
|
|---|
| 4608 | If you want all variables to be exported by default, you can use
|
|---|
| 4609 | @code{export} by itself:
|
|---|
| 4610 |
|
|---|
| 4611 | @example
|
|---|
| 4612 | export
|
|---|
| 4613 | @end example
|
|---|
| 4614 |
|
|---|
| 4615 | @noindent
|
|---|
| 4616 | This tells @code{make} that variables which are not explicitly mentioned
|
|---|
| 4617 | in an @code{export} or @code{unexport} directive should be exported.
|
|---|
| 4618 | Any variable given in an @code{unexport} directive will still @emph{not}
|
|---|
| 4619 | be exported. If you use @code{export} by itself to export variables by
|
|---|
| 4620 | default, variables whose names contain characters other than
|
|---|
| 4621 | alphanumerics and underscores will not be exported unless specifically
|
|---|
| 4622 | mentioned in an @code{export} directive.@refill
|
|---|
| 4623 |
|
|---|
| 4624 | @findex .EXPORT_ALL_VARIABLES
|
|---|
| 4625 | The behavior elicited by an @code{export} directive by itself was the
|
|---|
| 4626 | default in older versions of GNU @code{make}. If your makefiles depend
|
|---|
| 4627 | on this behavior and you want to be compatible with old versions of
|
|---|
| 4628 | @code{make}, you can write a rule for the special target
|
|---|
| 4629 | @code{.EXPORT_ALL_VARIABLES} instead of using the @code{export} directive.
|
|---|
| 4630 | This will be ignored by old @code{make}s, while the @code{export}
|
|---|
| 4631 | directive will cause a syntax error.@refill
|
|---|
| 4632 | @cindex compatibility in exporting
|
|---|
| 4633 |
|
|---|
| 4634 | Likewise, you can use @code{unexport} by itself to tell @code{make}
|
|---|
| 4635 | @emph{not} to export variables by default. Since this is the default
|
|---|
| 4636 | behavior, you would only need to do this if @code{export} had been used
|
|---|
| 4637 | by itself earlier (in an included makefile, perhaps). You
|
|---|
| 4638 | @strong{cannot} use @code{export} and @code{unexport} by themselves to
|
|---|
| 4639 | have variables exported for some recipes and not for others. The last
|
|---|
| 4640 | @code{export} or @code{unexport} directive that appears by itself
|
|---|
| 4641 | determines the behavior for the entire run of @code{make}.@refill
|
|---|
| 4642 |
|
|---|
| 4643 | @vindex MAKELEVEL
|
|---|
| 4644 | @cindex recursion, level of
|
|---|
| 4645 | As a special feature, the variable @code{MAKELEVEL} is changed when it
|
|---|
| 4646 | is passed down from level to level. This variable's value is a string
|
|---|
| 4647 | which is the depth of the level as a decimal number. The value is
|
|---|
| 4648 | @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make},
|
|---|
| 4649 | @samp{2} for a sub-sub-@code{make}, and so on. The incrementation
|
|---|
| 4650 | happens when @code{make} sets up the environment for a recipe.@refill
|
|---|
| 4651 |
|
|---|
| 4652 | The main use of @code{MAKELEVEL} is to test it in a conditional
|
|---|
| 4653 | directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this
|
|---|
| 4654 | way you can write a makefile that behaves one way if run recursively and
|
|---|
| 4655 | another way if run directly by you.@refill
|
|---|
| 4656 |
|
|---|
| 4657 | @vindex MAKEFILES
|
|---|
| 4658 | You can use the variable @code{MAKEFILES} to cause all sub-@code{make}
|
|---|
| 4659 | commands to use additional makefiles. The value of @code{MAKEFILES} is
|
|---|
| 4660 | a whitespace-separated list of file names. This variable, if defined in
|
|---|
| 4661 | the outer-level makefile, is passed down through the environment; then
|
|---|
| 4662 | it serves as a list of extra makefiles for the sub-@code{make} to read
|
|---|
| 4663 | before the usual or specified ones. @xref{MAKEFILES Variable, ,The
|
|---|
| 4664 | Variable @code{MAKEFILES}}.@refill
|
|---|
| 4665 |
|
|---|
| 4666 | @node Options/Recursion, -w Option, Variables/Recursion, Recursion
|
|---|
| 4667 | @subsection Communicating Options to a Sub-@code{make}
|
|---|
| 4668 | @cindex options, and recursion
|
|---|
| 4669 | @cindex recursion, and options
|
|---|
| 4670 |
|
|---|
| 4671 | @vindex MAKEFLAGS
|
|---|
| 4672 | Flags such as @samp{-s} and @samp{-k} are passed automatically to the
|
|---|
| 4673 | sub-@code{make} through the variable @code{MAKEFLAGS}. This variable is
|
|---|
| 4674 | set up automatically by @code{make} to contain the flag letters that
|
|---|
| 4675 | @code{make} received. Thus, if you do @w{@samp{make -ks}} then
|
|---|
| 4676 | @code{MAKEFLAGS} gets the value @samp{ks}.@refill
|
|---|
| 4677 |
|
|---|
| 4678 | As a consequence, every sub-@code{make} gets a value for @code{MAKEFLAGS}
|
|---|
| 4679 | in its environment. In response, it takes the flags from that value and
|
|---|
| 4680 | processes them as if they had been given as arguments.
|
|---|
| 4681 | @xref{Options Summary, ,Summary of Options}.
|
|---|
| 4682 |
|
|---|
| 4683 | @cindex command line variable definitions, and recursion
|
|---|
| 4684 | @cindex variables, command line, and recursion
|
|---|
| 4685 | @cindex recursion, and command line variable definitions
|
|---|
| 4686 | Likewise variables defined on the command line are passed to the
|
|---|
| 4687 | sub-@code{make} through @code{MAKEFLAGS}. Words in the value of
|
|---|
| 4688 | @code{MAKEFLAGS} that contain @samp{=}, @code{make} treats as variable
|
|---|
| 4689 | definitions just as if they appeared on the command line.
|
|---|
| 4690 | @xref{Overriding, ,Overriding Variables}.
|
|---|
| 4691 |
|
|---|
| 4692 | @cindex @code{-C}, and recursion
|
|---|
| 4693 | @cindex @code{-f}, and recursion
|
|---|
| 4694 | @cindex @code{-o}, and recursion
|
|---|
| 4695 | @cindex @code{-W}, and recursion
|
|---|
| 4696 | @cindex @code{--directory}, and recursion
|
|---|
| 4697 | @cindex @code{--file}, and recursion
|
|---|
| 4698 | @cindex @code{--old-file}, and recursion
|
|---|
| 4699 | @cindex @code{--assume-old}, and recursion
|
|---|
| 4700 | @cindex @code{--assume-new}, and recursion
|
|---|
| 4701 | @cindex @code{--new-file}, and recursion
|
|---|
| 4702 | @cindex recursion, and @code{-C}
|
|---|
| 4703 | @cindex recursion, and @code{-f}
|
|---|
| 4704 | @cindex recursion, and @code{-o}
|
|---|
| 4705 | @cindex recursion, and @code{-W}
|
|---|
| 4706 | The options @samp{-C}, @samp{-f}, @samp{-o}, and @samp{-W} are not put
|
|---|
| 4707 | into @code{MAKEFLAGS}; these options are not passed down.@refill
|
|---|
| 4708 |
|
|---|
| 4709 | @cindex @code{-j}, and recursion
|
|---|
| 4710 | @cindex @code{--jobs}, and recursion
|
|---|
| 4711 | @cindex recursion, and @code{-j}
|
|---|
| 4712 | @cindex job slots, and recursion
|
|---|
| 4713 | The @samp{-j} option is a special case (@pxref{Parallel, ,Parallel Execution}).
|
|---|
| 4714 | If you set it to some numeric value @samp{N} and your operating system
|
|---|
| 4715 | supports it (most any UNIX system will; others typically won't), the
|
|---|
| 4716 | parent @code{make} and all the sub-@code{make}s will communicate to
|
|---|
| 4717 | ensure that there are only @samp{N} jobs running at the same time
|
|---|
| 4718 | between them all. Note that any job that is marked recursive
|
|---|
| 4719 | (@pxref{Instead of Execution, ,Instead of Executing Recipes})
|
|---|
| 4720 | doesn't count against the total jobs (otherwise we could get @samp{N}
|
|---|
| 4721 | sub-@code{make}s running and have no slots left over for any real work!)
|
|---|
| 4722 |
|
|---|
| 4723 | If your operating system doesn't support the above communication, then
|
|---|
| 4724 | no @samp{-j} is added to @code{MAKEFLAGS}, so that sub-@code{make}s
|
|---|
| 4725 | run in non-parallel mode. If the @w{@samp{-j}} option were passed down
|
|---|
| 4726 | to sub-@code{make}s you would get many more jobs running in parallel
|
|---|
| 4727 | than you asked for. If you give @samp{-j} with no numeric argument,
|
|---|
| 4728 | meaning to run as many jobs as possible in parallel, this is passed
|
|---|
| 4729 | down, since multiple infinities are no more than one.@refill
|
|---|
| 4730 |
|
|---|
| 4731 | If you do not want to pass the other flags down, you must change the
|
|---|
| 4732 | value of @code{MAKEFLAGS}, like this:
|
|---|
| 4733 |
|
|---|
| 4734 | @example
|
|---|
| 4735 | subsystem:
|
|---|
| 4736 | cd subdir && $(MAKE) MAKEFLAGS=
|
|---|
| 4737 | @end example
|
|---|
| 4738 |
|
|---|
| 4739 | @vindex MAKEOVERRIDES
|
|---|
| 4740 | The command line variable definitions really appear in the variable
|
|---|
| 4741 | @code{MAKEOVERRIDES}, and @code{MAKEFLAGS} contains a reference to this
|
|---|
| 4742 | variable. If you do want to pass flags down normally, but don't want to
|
|---|
| 4743 | pass down the command line variable definitions, you can reset
|
|---|
| 4744 | @code{MAKEOVERRIDES} to empty, like this:
|
|---|
| 4745 |
|
|---|
| 4746 | @example
|
|---|
| 4747 | MAKEOVERRIDES =
|
|---|
| 4748 | @end example
|
|---|
| 4749 |
|
|---|
| 4750 | @noindent
|
|---|
| 4751 | @cindex Arg list too long
|
|---|
| 4752 | @cindex E2BIG
|
|---|
| 4753 | This is not usually useful to do. However, some systems have a small
|
|---|
| 4754 | fixed limit on the size of the environment, and putting so much
|
|---|
| 4755 | information into the value of @code{MAKEFLAGS} can exceed it. If you
|
|---|
| 4756 | see the error message @samp{Arg list too long}, this may be the problem.
|
|---|
| 4757 | @findex .POSIX
|
|---|
| 4758 | @cindex POSIX
|
|---|
| 4759 | (For strict compliance with POSIX.2, changing @code{MAKEOVERRIDES} does
|
|---|
| 4760 | not affect @code{MAKEFLAGS} if the special target @samp{.POSIX} appears
|
|---|
| 4761 | in the makefile. You probably do not care about this.)
|
|---|
| 4762 |
|
|---|
| 4763 | @vindex MFLAGS
|
|---|
| 4764 | A similar variable @code{MFLAGS} exists also, for historical
|
|---|
| 4765 | compatibility. It has the same value as @code{MAKEFLAGS} except that it
|
|---|
| 4766 | does not contain the command line variable definitions, and it always
|
|---|
| 4767 | begins with a hyphen unless it is empty (@code{MAKEFLAGS} begins with a
|
|---|
| 4768 | hyphen only when it begins with an option that has no single-letter
|
|---|
| 4769 | version, such as @samp{--warn-undefined-variables}). @code{MFLAGS} was
|
|---|
| 4770 | traditionally used explicitly in the recursive @code{make} command, like
|
|---|
| 4771 | this:
|
|---|
| 4772 |
|
|---|
| 4773 | @example
|
|---|
| 4774 | subsystem:
|
|---|
| 4775 | cd subdir && $(MAKE) $(MFLAGS)
|
|---|
| 4776 | @end example
|
|---|
| 4777 |
|
|---|
| 4778 | @noindent
|
|---|
| 4779 | but now @code{MAKEFLAGS} makes this usage redundant. If you want your
|
|---|
| 4780 | makefiles to be compatible with old @code{make} programs, use this
|
|---|
| 4781 | technique; it will work fine with more modern @code{make} versions too.
|
|---|
| 4782 |
|
|---|
| 4783 | @cindex setting options from environment
|
|---|
| 4784 | @cindex options, setting from environment
|
|---|
| 4785 | @cindex setting options in makefiles
|
|---|
| 4786 | @cindex options, setting in makefiles
|
|---|
| 4787 | The @code{MAKEFLAGS} variable can also be useful if you want to have
|
|---|
| 4788 | certain options, such as @samp{-k} (@pxref{Options Summary, ,Summary of
|
|---|
| 4789 | Options}), set each time you run @code{make}. You simply put a value for
|
|---|
| 4790 | @code{MAKEFLAGS} in your environment. You can also set @code{MAKEFLAGS} in
|
|---|
| 4791 | a makefile, to specify additional flags that should also be in effect for
|
|---|
| 4792 | that makefile. (Note that you cannot use @code{MFLAGS} this way. That
|
|---|
| 4793 | variable is set only for compatibility; @code{make} does not interpret a
|
|---|
| 4794 | value you set for it in any way.)
|
|---|
| 4795 |
|
|---|
| 4796 | When @code{make} interprets the value of @code{MAKEFLAGS} (either from the
|
|---|
| 4797 | environment or from a makefile), it first prepends a hyphen if the value
|
|---|
| 4798 | does not already begin with one. Then it chops the value into words
|
|---|
| 4799 | separated by blanks, and parses these words as if they were options given
|
|---|
| 4800 | on the command line (except that @samp{-C}, @samp{-f}, @samp{-h},
|
|---|
| 4801 | @samp{-o}, @samp{-W}, and their long-named versions are ignored; and there
|
|---|
| 4802 | is no error for an invalid option).
|
|---|
| 4803 |
|
|---|
| 4804 | If you do put @code{MAKEFLAGS} in your environment, you should be sure not
|
|---|
| 4805 | to include any options that will drastically affect the actions of
|
|---|
| 4806 | @code{make} and undermine the purpose of makefiles and of @code{make}
|
|---|
| 4807 | itself. For instance, the @samp{-t}, @samp{-n}, and @samp{-q} options, if
|
|---|
| 4808 | put in one of these variables, could have disastrous consequences and would
|
|---|
| 4809 | certainly have at least surprising and probably annoying effects.@refill
|
|---|
| 4810 |
|
|---|
| 4811 | If you'd like to run other implementations of @code{make} in addition
|
|---|
| 4812 | to GNU @code{make}, and hence do not want to add GNU
|
|---|
| 4813 | @code{make}-specific flags to the @code{MAKEFLAGS} variable, you can
|
|---|
| 4814 | add them to the @code{GNUMAKEFLAGS} variable instead. This variable
|
|---|
| 4815 | is parsed just before @code{MAKEFLAGS}, in the same way as
|
|---|
| 4816 | @code{MAKEFLAGS}. When @code{make} constructs @code{MAKEFLAGS} to
|
|---|
| 4817 | pass to a recursive @code{make} it will include all flags, even those
|
|---|
| 4818 | taken from @code{GNUMAKEFLAGS}. As a result, after parsing
|
|---|
| 4819 | @code{GNUMAKEFLAGS} GNU @code{make} sets this variable to the empty
|
|---|
| 4820 | string to avoid duplicating flags during recursion.
|
|---|
| 4821 |
|
|---|
| 4822 | It's best to use @code{GNUMAKEFLAGS} only with flags which won't
|
|---|
| 4823 | materially change the behavior of your makefiles. If your makefiles
|
|---|
| 4824 | require GNU make anyway then simply use @code{MAKEFLAGS}. Flags such
|
|---|
| 4825 | as @samp{--no-print-directory} or @samp{--output-sync} may be
|
|---|
| 4826 | appropriate for @code{GNUMAKEFLAGS}.
|
|---|
| 4827 |
|
|---|
| 4828 | @node -w Option, , Options/Recursion, Recursion
|
|---|
| 4829 | @subsection The @samp{--print-directory} Option
|
|---|
| 4830 | @cindex directories, printing them
|
|---|
| 4831 | @cindex printing directories
|
|---|
| 4832 | @cindex recursion, and printing directories
|
|---|
| 4833 |
|
|---|
| 4834 | If you use several levels of recursive @code{make} invocations, the
|
|---|
| 4835 | @samp{-w} or @w{@samp{--print-directory}} option can make the output a
|
|---|
| 4836 | lot easier to understand by showing each directory as @code{make}
|
|---|
| 4837 | starts processing it and as @code{make} finishes processing it. For
|
|---|
| 4838 | example, if @samp{make -w} is run in the directory @file{/u/gnu/make},
|
|---|
| 4839 | @code{make} will print a line of the form:@refill
|
|---|
| 4840 |
|
|---|
| 4841 | @example
|
|---|
| 4842 | make: Entering directory `/u/gnu/make'.
|
|---|
| 4843 | @end example
|
|---|
| 4844 |
|
|---|
| 4845 | @noindent
|
|---|
| 4846 | before doing anything else, and a line of the form:
|
|---|
| 4847 |
|
|---|
| 4848 | @example
|
|---|
| 4849 | make: Leaving directory `/u/gnu/make'.
|
|---|
| 4850 | @end example
|
|---|
| 4851 |
|
|---|
| 4852 | @noindent
|
|---|
| 4853 | when processing is completed.
|
|---|
| 4854 |
|
|---|
| 4855 | @cindex @code{-C}, and @code{-w}
|
|---|
| 4856 | @cindex @code{--directory}, and @code{--print-directory}
|
|---|
| 4857 | @cindex recursion, and @code{-w}
|
|---|
| 4858 | @cindex @code{-w}, and @code{-C}
|
|---|
| 4859 | @cindex @code{-w}, and recursion
|
|---|
| 4860 | @cindex @code{--print-directory}, and @code{--directory}
|
|---|
| 4861 | @cindex @code{--print-directory}, and recursion
|
|---|
| 4862 | @cindex @code{--no-print-directory}
|
|---|
| 4863 | @cindex @code{--print-directory}, disabling
|
|---|
| 4864 | @cindex @code{-w}, disabling
|
|---|
| 4865 | Normally, you do not need to specify this option because @samp{make}
|
|---|
| 4866 | does it for you: @samp{-w} is turned on automatically when you use the
|
|---|
| 4867 | @samp{-C} option, and in sub-@code{make}s. @code{make} will not
|
|---|
| 4868 | automatically turn on @samp{-w} if you also use @samp{-s}, which says to
|
|---|
| 4869 | be silent, or if you use @samp{--no-print-directory} to explicitly
|
|---|
| 4870 | disable it.
|
|---|
| 4871 |
|
|---|
| 4872 | @node Canned Recipes, Empty Recipes, Recursion, Recipes
|
|---|
| 4873 | @section Defining Canned Recipes
|
|---|
| 4874 | @cindex canned recipes
|
|---|
| 4875 | @cindex recipes, canned
|
|---|
| 4876 | @cindex sequences of commands
|
|---|
| 4877 | @cindex commands, sequences of
|
|---|
| 4878 |
|
|---|
| 4879 | When the same sequence of commands is useful in making various
|
|---|
| 4880 | targets, you can define it as a canned sequence with the @code{define}
|
|---|
| 4881 | directive, and refer to the canned sequence from the recipes for those
|
|---|
| 4882 | targets. The canned sequence is actually a variable, so the name must
|
|---|
| 4883 | not conflict with other variable names.
|
|---|
| 4884 |
|
|---|
| 4885 | Here is an example of defining a canned recipe:
|
|---|
| 4886 |
|
|---|
| 4887 | @example
|
|---|
| 4888 | define run-yacc =
|
|---|
| 4889 | yacc $(firstword $^)
|
|---|
| 4890 | mv y.tab.c $@@
|
|---|
| 4891 | endef
|
|---|
| 4892 | @end example
|
|---|
| 4893 | @cindex @code{yacc}
|
|---|
| 4894 |
|
|---|
| 4895 | @noindent
|
|---|
| 4896 | Here @code{run-yacc} is the name of the variable being defined;
|
|---|
| 4897 | @code{endef} marks the end of the definition; the lines in between are the
|
|---|
| 4898 | commands. The @code{define} directive does not expand variable references
|
|---|
| 4899 | and function calls in the canned sequence; the @samp{$} characters,
|
|---|
| 4900 | parentheses, variable names, and so on, all become part of the value of the
|
|---|
| 4901 | variable you are defining.
|
|---|
| 4902 | @xref{Multi-Line, ,Defining Multi-Line Variables},
|
|---|
| 4903 | for a complete explanation of @code{define}.
|
|---|
| 4904 |
|
|---|
| 4905 | The first command in this example runs Yacc on the first prerequisite of
|
|---|
| 4906 | whichever rule uses the canned sequence. The output file from Yacc is
|
|---|
| 4907 | always named @file{y.tab.c}. The second command moves the output to the
|
|---|
| 4908 | rule's target file name.
|
|---|
| 4909 |
|
|---|
| 4910 | To use the canned sequence, substitute the variable into the recipe of a
|
|---|
| 4911 | rule. You can substitute it like any other variable
|
|---|
| 4912 | (@pxref{Reference, ,Basics of Variable References}).
|
|---|
| 4913 | Because variables defined by @code{define} are recursively expanded
|
|---|
| 4914 | variables, all the variable references you wrote inside the @code{define}
|
|---|
| 4915 | are expanded now. For example:
|
|---|
| 4916 |
|
|---|
| 4917 | @example
|
|---|
| 4918 | foo.c : foo.y
|
|---|
| 4919 | $(run-yacc)
|
|---|
| 4920 | @end example
|
|---|
| 4921 |
|
|---|
| 4922 | @noindent
|
|---|
| 4923 | @samp{foo.y} will be substituted for the variable @samp{$^} when it occurs in
|
|---|
| 4924 | @code{run-yacc}'s value, and @samp{foo.c} for @samp{$@@}.@refill
|
|---|
| 4925 |
|
|---|
| 4926 | This is a realistic example, but this particular one is not needed in
|
|---|
| 4927 | practice because @code{make} has an implicit rule to figure out these
|
|---|
| 4928 | commands based on the file names involved
|
|---|
| 4929 | (@pxref{Implicit Rules, ,Using Implicit Rules}).
|
|---|
| 4930 |
|
|---|
| 4931 | @cindex @@, and @code{define}
|
|---|
| 4932 | @cindex -, and @code{define}
|
|---|
| 4933 | @cindex +, and @code{define}
|
|---|
| 4934 | In recipe execution, each line of a canned sequence is treated just as
|
|---|
| 4935 | if the line appeared on its own in the rule, preceded by a tab. In
|
|---|
| 4936 | particular, @code{make} invokes a separate sub-shell for each line. You
|
|---|
| 4937 | can use the special prefix characters that affect command lines
|
|---|
| 4938 | (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence.
|
|---|
| 4939 | @xref{Recipes, ,Writing Recipes in Rules}.
|
|---|
| 4940 | For example, using this canned sequence:
|
|---|
| 4941 |
|
|---|
| 4942 | @example
|
|---|
| 4943 | define frobnicate =
|
|---|
| 4944 | @@echo "frobnicating target $@@"
|
|---|
| 4945 | frob-step-1 $< -o $@@-step-1
|
|---|
| 4946 | frob-step-2 $@@-step-1 -o $@@
|
|---|
| 4947 | endef
|
|---|
| 4948 | @end example
|
|---|
| 4949 |
|
|---|
| 4950 | @noindent
|
|---|
| 4951 | @code{make} will not echo the first line, the @code{echo} command.
|
|---|
| 4952 | But it @emph{will} echo the following two recipe lines.
|
|---|
| 4953 |
|
|---|
| 4954 | On the other hand, prefix characters on the recipe line that refers to
|
|---|
| 4955 | a canned sequence apply to every line in the sequence. So the rule:
|
|---|
| 4956 |
|
|---|
| 4957 | @example
|
|---|
| 4958 | frob.out: frob.in
|
|---|
| 4959 | @@$(frobnicate)
|
|---|
| 4960 | @end example
|
|---|
| 4961 |
|
|---|
| 4962 | @noindent
|
|---|
| 4963 | does not echo @emph{any} recipe lines.
|
|---|
| 4964 | (@xref{Echoing, ,Recipe Echoing}, for a full explanation of @samp{@@}.)
|
|---|
| 4965 |
|
|---|
| 4966 | @node Empty Recipes, , Canned Recipes, Recipes
|
|---|
| 4967 | @section Using Empty Recipes
|
|---|
| 4968 | @cindex empty recipes
|
|---|
| 4969 | @cindex recipes, empty
|
|---|
| 4970 |
|
|---|
| 4971 | It is sometimes useful to define recipes which do nothing. This is done
|
|---|
| 4972 | simply by giving a recipe that consists of nothing but whitespace. For
|
|---|
| 4973 | example:
|
|---|
| 4974 |
|
|---|
| 4975 | @example
|
|---|
| 4976 | target: ;
|
|---|
| 4977 | @end example
|
|---|
| 4978 |
|
|---|
| 4979 | @noindent
|
|---|
| 4980 | defines an empty recipe for @file{target}. You could also use a line
|
|---|
| 4981 | beginning with a recipe prefix character to define an empty recipe,
|
|---|
| 4982 | but this would be confusing because such a line looks empty.
|
|---|
| 4983 |
|
|---|
| 4984 | @findex .DEFAULT@r{, and empty recipes}
|
|---|
| 4985 | You may be wondering why you would want to define a recipe that does
|
|---|
| 4986 | nothing. One reason this is useful is to prevent a target from
|
|---|
| 4987 | getting implicit recipes (from implicit rules or the @code{.DEFAULT}
|
|---|
| 4988 | special target; @pxref{Implicit Rules} and @pxref{Last Resort,
|
|---|
| 4989 | ,Defining Last-Resort Default Rules}).@refill
|
|---|
| 4990 |
|
|---|
| 4991 | Empty recipes can also be used to avoid errors for targets that will
|
|---|
| 4992 | be created as a side-effect of another recipe: if the target does not
|
|---|
| 4993 | exist the empty recipe ensures that @code{make} won't complain that it
|
|---|
| 4994 | doesn't know how to build the target, and @code{make} will assume the
|
|---|
| 4995 | target is out of date.
|
|---|
| 4996 |
|
|---|
| 4997 | You may be inclined to define empty recipes for targets that are not
|
|---|
| 4998 | actual files, but only exist so that their prerequisites can be
|
|---|
| 4999 | remade. However, this is not the best way to do that, because the
|
|---|
| 5000 | prerequisites may not be remade properly if the target file actually
|
|---|
| 5001 | does exist. @xref{Phony Targets, ,Phony Targets}, for a better way to
|
|---|
| 5002 | do this.
|
|---|
| 5003 |
|
|---|
| 5004 | @node Using Variables, Conditionals, Recipes, Top
|
|---|
| 5005 | @chapter How to Use Variables
|
|---|
| 5006 | @cindex variable
|
|---|
| 5007 | @cindex value
|
|---|
| 5008 | @cindex recursive variable expansion
|
|---|
| 5009 | @cindex simple variable expansion
|
|---|
| 5010 |
|
|---|
| 5011 | A @dfn{variable} is a name defined in a makefile to represent a string
|
|---|
| 5012 | of text, called the variable's @dfn{value}. These values are
|
|---|
| 5013 | substituted by explicit request into targets, prerequisites, recipes,
|
|---|
| 5014 | and other parts of the makefile. (In some other versions of @code{make},
|
|---|
| 5015 | variables are called @dfn{macros}.)
|
|---|
| 5016 | @cindex macro
|
|---|
| 5017 |
|
|---|
| 5018 | Variables and functions in all parts of a makefile are expanded when
|
|---|
| 5019 | read, except for in recipes, the right-hand sides of variable
|
|---|
| 5020 | definitions using @samp{=}, and the bodies of variable definitions
|
|---|
| 5021 | using the @code{define} directive.@refill
|
|---|
| 5022 |
|
|---|
| 5023 | Variables can represent lists of file names, options to pass to compilers,
|
|---|
| 5024 | programs to run, directories to look in for source files, directories to
|
|---|
| 5025 | write output in, or anything else you can imagine.
|
|---|
| 5026 |
|
|---|
| 5027 | A variable name may be any sequence of characters not containing
|
|---|
| 5028 | @samp{:}, @samp{#}, @samp{=}, or whitespace. However, variable names
|
|---|
| 5029 | containing characters other than letters, numbers, and underscores
|
|---|
| 5030 | should be considered carefully, as in some shells they cannot be
|
|---|
| 5031 | passed through the environment to a sub-@code{make}
|
|---|
| 5032 | (@pxref{Variables/Recursion, ,Communicating Variables to a
|
|---|
| 5033 | Sub-@code{make}}). Variable names beginning with @samp{.} and an
|
|---|
| 5034 | uppercase letter may be given special meaning in future versions of
|
|---|
| 5035 | @code{make}.
|
|---|
| 5036 |
|
|---|
| 5037 | Variable names are case-sensitive. The names @samp{foo}, @samp{FOO},
|
|---|
| 5038 | and @samp{Foo} all refer to different variables.
|
|---|
| 5039 |
|
|---|
| 5040 | It is traditional to use upper case letters in variable names, but we
|
|---|
| 5041 | recommend using lower case letters for variable names that serve internal
|
|---|
| 5042 | purposes in the makefile, and reserving upper case for parameters that
|
|---|
| 5043 | control implicit rules or for parameters that the user should override with
|
|---|
| 5044 | command options (@pxref{Overriding, ,Overriding Variables}).
|
|---|
| 5045 |
|
|---|
| 5046 | A few variables have names that are a single punctuation character or
|
|---|
| 5047 | just a few characters. These are the @dfn{automatic variables}, and
|
|---|
| 5048 | they have particular specialized uses. @xref{Automatic Variables}.
|
|---|
| 5049 |
|
|---|
| 5050 | @menu
|
|---|
| 5051 | * Reference:: How to use the value of a variable.
|
|---|
| 5052 | * Flavors:: Variables come in two flavors.
|
|---|
| 5053 | * Advanced:: Advanced features for referencing a variable.
|
|---|
| 5054 | * Values:: All the ways variables get their values.
|
|---|
| 5055 | * Setting:: How to set a variable in the makefile.
|
|---|
| 5056 | * Appending:: How to append more text to the old value
|
|---|
| 5057 | of a variable.
|
|---|
| 5058 | * Override Directive:: How to set a variable in the makefile even if
|
|---|
| 5059 | the user has set it with a command argument.
|
|---|
| 5060 | * Multi-Line:: An alternate way to set a variable
|
|---|
| 5061 | to a multi-line string.
|
|---|
| 5062 | * Undefine Directive:: How to undefine a variable so that it appears
|
|---|
| 5063 | as if it was never set.
|
|---|
| 5064 | * Environment:: Variable values can come from the environment.
|
|---|
| 5065 | * Target-specific:: Variable values can be defined on a per-target
|
|---|
| 5066 | basis.
|
|---|
| 5067 | * Pattern-specific:: Target-specific variable values can be applied
|
|---|
| 5068 | to a group of targets that match a pattern.
|
|---|
| 5069 | * Suppressing Inheritance:: Suppress inheritance of variables.
|
|---|
| 5070 | * Special Variables:: Variables with special meaning or behavior.
|
|---|
| 5071 | @end menu
|
|---|
| 5072 |
|
|---|
| 5073 | @node Reference, Flavors, Using Variables, Using Variables
|
|---|
| 5074 | @section Basics of Variable References
|
|---|
| 5075 | @cindex variables, how to reference
|
|---|
| 5076 | @cindex reference to variables
|
|---|
| 5077 | @cindex @code{$}, in variable reference
|
|---|
| 5078 | @cindex dollar sign (@code{$}), in variable reference
|
|---|
| 5079 |
|
|---|
| 5080 | To substitute a variable's value, write a dollar sign followed by the name
|
|---|
| 5081 | of the variable in parentheses or braces: either @samp{$(foo)} or
|
|---|
| 5082 | @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This
|
|---|
| 5083 | special significance of @samp{$} is why you must write @samp{$$} to have
|
|---|
| 5084 | the effect of a single dollar sign in a file name or recipe.
|
|---|
| 5085 |
|
|---|
| 5086 | Variable references can be used in any context: targets, prerequisites,
|
|---|
| 5087 | recipes, most directives, and new variable values. Here is an
|
|---|
| 5088 | example of a common case, where a variable holds the names of all the
|
|---|
| 5089 | object files in a program:
|
|---|
| 5090 |
|
|---|
| 5091 | @example
|
|---|
| 5092 | @group
|
|---|
| 5093 | objects = program.o foo.o utils.o
|
|---|
| 5094 | program : $(objects)
|
|---|
| 5095 | cc -o program $(objects)
|
|---|
| 5096 |
|
|---|
| 5097 | $(objects) : defs.h
|
|---|
| 5098 | @end group
|
|---|
| 5099 | @end example
|
|---|
| 5100 |
|
|---|
| 5101 | Variable references work by strict textual substitution. Thus, the rule
|
|---|
| 5102 |
|
|---|
| 5103 | @example
|
|---|
| 5104 | @group
|
|---|
| 5105 | foo = c
|
|---|
| 5106 | prog.o : prog.$(foo)
|
|---|
| 5107 | $(foo)$(foo) -$(foo) prog.$(foo)
|
|---|
| 5108 | @end group
|
|---|
| 5109 | @end example
|
|---|
| 5110 |
|
|---|
| 5111 | @noindent
|
|---|
| 5112 | could be used to compile a C program @file{prog.c}. Since spaces before
|
|---|
| 5113 | the variable value are ignored in variable assignments, the value of
|
|---|
| 5114 | @code{foo} is precisely @samp{c}. (Don't actually write your makefiles
|
|---|
| 5115 | this way!)
|
|---|
| 5116 |
|
|---|
| 5117 | A dollar sign followed by a character other than a dollar sign,
|
|---|
| 5118 | open-parenthesis or open-brace treats that single character as the
|
|---|
| 5119 | variable name. Thus, you could reference the variable @code{x} with
|
|---|
| 5120 | @samp{$x}. However, this practice is strongly discouraged, except in
|
|---|
| 5121 | the case of the automatic variables (@pxref{Automatic Variables}).
|
|---|
| 5122 |
|
|---|
| 5123 | @node Flavors, Advanced, Reference, Using Variables
|
|---|
| 5124 | @section The Two Flavors of Variables
|
|---|
| 5125 | @cindex flavors of variables
|
|---|
| 5126 | @cindex recursive variable expansion
|
|---|
| 5127 | @cindex variables, flavors
|
|---|
| 5128 | @cindex recursively expanded variables
|
|---|
| 5129 | @cindex variables, recursively expanded
|
|---|
| 5130 |
|
|---|
| 5131 | There are two ways that a variable in GNU @code{make} can have a value;
|
|---|
| 5132 | we call them the two @dfn{flavors} of variables. The two flavors are
|
|---|
| 5133 | distinguished in how they are defined and in what they do when expanded.
|
|---|
| 5134 |
|
|---|
| 5135 | @cindex =
|
|---|
| 5136 | The first flavor of variable is a @dfn{recursively expanded} variable.
|
|---|
| 5137 | Variables of this sort are defined by lines using @samp{=}
|
|---|
| 5138 | (@pxref{Setting, ,Setting Variables}) or by the @code{define} directive
|
|---|
| 5139 | (@pxref{Multi-Line, ,Defining Multi-Line Variables}). The value you specify
|
|---|
| 5140 | is installed verbatim; if it contains references to other variables,
|
|---|
| 5141 | these references are expanded whenever this variable is substituted (in
|
|---|
| 5142 | the course of expanding some other string). When this happens, it is
|
|---|
| 5143 | called @dfn{recursive expansion}.@refill
|
|---|
| 5144 |
|
|---|
| 5145 | For example,
|
|---|
| 5146 |
|
|---|
| 5147 | @example
|
|---|
| 5148 | foo = $(bar)
|
|---|
| 5149 | bar = $(ugh)
|
|---|
| 5150 | ugh = Huh?
|
|---|
| 5151 |
|
|---|
| 5152 | all:;echo $(foo)
|
|---|
| 5153 | @end example
|
|---|
| 5154 |
|
|---|
| 5155 | @noindent
|
|---|
| 5156 | will echo @samp{Huh?}: @samp{$(foo)} expands to @samp{$(bar)} which
|
|---|
| 5157 | expands to @samp{$(ugh)} which finally expands to @samp{Huh?}.@refill
|
|---|
| 5158 |
|
|---|
| 5159 | This flavor of variable is the only sort supported by most other
|
|---|
| 5160 | versions of @code{make}. It has its advantages and its disadvantages.
|
|---|
| 5161 | An advantage (most would say) is that:
|
|---|
| 5162 |
|
|---|
| 5163 | @example
|
|---|
| 5164 | CFLAGS = $(include_dirs) -O
|
|---|
| 5165 | include_dirs = -Ifoo -Ibar
|
|---|
| 5166 | @end example
|
|---|
| 5167 |
|
|---|
| 5168 | @noindent
|
|---|
| 5169 | will do what was intended: when @samp{CFLAGS} is expanded in a recipe,
|
|---|
| 5170 | it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you
|
|---|
| 5171 | cannot append something on the end of a variable, as in
|
|---|
| 5172 |
|
|---|
| 5173 | @example
|
|---|
| 5174 | CFLAGS = $(CFLAGS) -O
|
|---|
| 5175 | @end example
|
|---|
| 5176 |
|
|---|
| 5177 | @noindent
|
|---|
| 5178 | because it will cause an infinite loop in the variable expansion.
|
|---|
| 5179 | (Actually @code{make} detects the infinite loop and reports an error.)
|
|---|
| 5180 | @cindex loops in variable expansion
|
|---|
| 5181 | @cindex variables, loops in expansion
|
|---|
| 5182 |
|
|---|
| 5183 | Another disadvantage is that any functions
|
|---|
| 5184 | (@pxref{Functions, ,Functions for Transforming Text})
|
|---|
| 5185 | referenced in the definition will be executed every time the variable is
|
|---|
| 5186 | expanded. This makes @code{make} run slower; worse, it causes the
|
|---|
| 5187 | @code{wildcard} and @code{shell} functions to give unpredictable results
|
|---|
| 5188 | because you cannot easily control when they are called, or even how many
|
|---|
| 5189 | times.
|
|---|
| 5190 |
|
|---|
| 5191 | To avoid all the problems and inconveniences of recursively expanded
|
|---|
| 5192 | variables, there is another flavor: simply expanded variables.
|
|---|
| 5193 |
|
|---|
| 5194 | @cindex simply expanded variables
|
|---|
| 5195 | @cindex variables, simply expanded
|
|---|
| 5196 | @cindex :=
|
|---|
| 5197 | @cindex ::=
|
|---|
| 5198 | @dfn{Simply expanded variables} are defined by lines using @samp{:=}
|
|---|
| 5199 | or @samp{::=} (@pxref{Setting, ,Setting Variables}). Both forms are
|
|---|
| 5200 | equivalent in GNU @code{make}; however only the @samp{::=} form is
|
|---|
| 5201 | described by the POSIX standard (support for @samp{::=} was added to
|
|---|
| 5202 | the POSIX standard in 2012, so older versions of @code{make} won't
|
|---|
| 5203 | accept this form either).
|
|---|
| 5204 |
|
|---|
| 5205 | The value of a simply expanded variable is scanned
|
|---|
| 5206 | once and for all, expanding any references to other variables and
|
|---|
| 5207 | functions, when the variable is defined. The actual value of the simply
|
|---|
| 5208 | expanded variable is the result of expanding the text that you write.
|
|---|
| 5209 | It does not contain any references to other variables; it contains their
|
|---|
| 5210 | values @emph{as of the time this variable was defined}. Therefore,
|
|---|
| 5211 |
|
|---|
| 5212 | @example
|
|---|
| 5213 | x := foo
|
|---|
| 5214 | y := $(x) bar
|
|---|
| 5215 | x := later
|
|---|
| 5216 | @end example
|
|---|
| 5217 |
|
|---|
| 5218 | @noindent
|
|---|
| 5219 | is equivalent to
|
|---|
| 5220 |
|
|---|
| 5221 | @example
|
|---|
| 5222 | y := foo bar
|
|---|
| 5223 | x := later
|
|---|
| 5224 | @end example
|
|---|
| 5225 |
|
|---|
| 5226 | When a simply expanded variable is referenced, its value is substituted
|
|---|
| 5227 | verbatim.
|
|---|
| 5228 |
|
|---|
| 5229 | Here is a somewhat more complicated example, illustrating the use of
|
|---|
| 5230 | @samp{:=} in conjunction with the @code{shell} function.
|
|---|
| 5231 | (@xref{Shell Function, , The @code{shell} Function}.) This example
|
|---|
| 5232 | also shows use of the variable @code{MAKELEVEL}, which is changed
|
|---|
| 5233 | when it is passed down from level to level.
|
|---|
| 5234 | (@xref{Variables/Recursion, , Communicating Variables to a
|
|---|
| 5235 | Sub-@code{make}}, for information about @code{MAKELEVEL}.)
|
|---|
| 5236 |
|
|---|
| 5237 | @vindex MAKELEVEL
|
|---|
| 5238 | @vindex MAKE
|
|---|
| 5239 | @example
|
|---|
| 5240 | @group
|
|---|
| 5241 | ifeq (0,$@{MAKELEVEL@})
|
|---|
| 5242 | whoami := $(shell whoami)
|
|---|
| 5243 | host-type := $(shell arch)
|
|---|
| 5244 | MAKE := $@{MAKE@} host-type=$@{host-type@} whoami=$@{whoami@}
|
|---|
| 5245 | endif
|
|---|
| 5246 | @end group
|
|---|
| 5247 | @end example
|
|---|
| 5248 |
|
|---|
| 5249 | @noindent
|
|---|
| 5250 | An advantage of this use of @samp{:=} is that a typical
|
|---|
| 5251 | `descend into a directory' recipe then looks like this:
|
|---|
| 5252 |
|
|---|
| 5253 | @example
|
|---|
| 5254 | @group
|
|---|
| 5255 | $@{subdirs@}:
|
|---|
| 5256 | $@{MAKE@} -C $@@ all
|
|---|
| 5257 | @end group
|
|---|
| 5258 | @end example
|
|---|
| 5259 |
|
|---|
| 5260 | Simply expanded variables generally make complicated makefile programming
|
|---|
| 5261 | more predictable because they work like variables in most programming
|
|---|
| 5262 | languages. They allow you to redefine a variable using its own value (or
|
|---|
| 5263 | its value processed in some way by one of the expansion functions) and to
|
|---|
| 5264 | use the expansion functions much more efficiently
|
|---|
| 5265 | (@pxref{Functions, ,Functions for Transforming Text}).
|
|---|
| 5266 |
|
|---|
| 5267 | @cindex spaces, in variable values
|
|---|
| 5268 | @cindex whitespace, in variable values
|
|---|
| 5269 | @cindex variables, spaces in values
|
|---|
| 5270 | You can also use them to introduce controlled leading whitespace into
|
|---|
| 5271 | variable values. Leading whitespace characters are discarded from your
|
|---|
| 5272 | input before substitution of variable references and function calls;
|
|---|
| 5273 | this means you can include leading spaces in a variable value by
|
|---|
| 5274 | protecting them with variable references, like this:
|
|---|
| 5275 |
|
|---|
| 5276 | @example
|
|---|
| 5277 | nullstring :=
|
|---|
| 5278 | space := $(nullstring) # end of the line
|
|---|
| 5279 | @end example
|
|---|
| 5280 |
|
|---|
| 5281 | @noindent
|
|---|
| 5282 | Here the value of the variable @code{space} is precisely one space. The
|
|---|
| 5283 | comment @w{@samp{# end of the line}} is included here just for clarity.
|
|---|
| 5284 | Since trailing space characters are @emph{not} stripped from variable
|
|---|
| 5285 | values, just a space at the end of the line would have the same effect
|
|---|
| 5286 | (but be rather hard to read). If you put whitespace at the end of a
|
|---|
| 5287 | variable value, it is a good idea to put a comment like that at the end
|
|---|
| 5288 | of the line to make your intent clear. Conversely, if you do @emph{not}
|
|---|
| 5289 | want any whitespace characters at the end of your variable value, you
|
|---|
| 5290 | must remember not to put a random comment on the end of the line after
|
|---|
| 5291 | some whitespace, such as this:
|
|---|
| 5292 |
|
|---|
| 5293 | @example
|
|---|
| 5294 | dir := /foo/bar # directory to put the frobs in
|
|---|
| 5295 | @end example
|
|---|
| 5296 |
|
|---|
| 5297 | @noindent
|
|---|
| 5298 | Here the value of the variable @code{dir} is @w{@samp{/foo/bar }}
|
|---|
| 5299 | (with four trailing spaces), which was probably not the intention.
|
|---|
| 5300 | (Imagine something like @w{@samp{$(dir)/file}} with this definition!)
|
|---|
| 5301 |
|
|---|
| 5302 | @cindex conditional variable assignment
|
|---|
| 5303 | @cindex variables, conditional assignment
|
|---|
| 5304 | @cindex ?=
|
|---|
| 5305 | There is another assignment operator for variables, @samp{?=}. This
|
|---|
| 5306 | is called a conditional variable assignment operator, because it only
|
|---|
| 5307 | has an effect if the variable is not yet defined. This statement:
|
|---|
| 5308 |
|
|---|
| 5309 | @example
|
|---|
| 5310 | FOO ?= bar
|
|---|
| 5311 | @end example
|
|---|
| 5312 |
|
|---|
| 5313 | @noindent
|
|---|
| 5314 | is exactly equivalent to this
|
|---|
| 5315 | (@pxref{Origin Function, ,The @code{origin} Function}):
|
|---|
| 5316 |
|
|---|
| 5317 | @example
|
|---|
| 5318 | ifeq ($(origin FOO), undefined)
|
|---|
| 5319 | FOO = bar
|
|---|
| 5320 | endif
|
|---|
| 5321 | @end example
|
|---|
| 5322 |
|
|---|
| 5323 | Note that a variable set to an empty value is still defined, so
|
|---|
| 5324 | @samp{?=} will not set that variable.
|
|---|
| 5325 |
|
|---|
| 5326 | @node Advanced, Values, Flavors, Using Variables
|
|---|
| 5327 | @section Advanced Features for Reference to Variables
|
|---|
| 5328 | @cindex reference to variables
|
|---|
| 5329 |
|
|---|
| 5330 | This section describes some advanced features you can use to reference
|
|---|
| 5331 | variables in more flexible ways.
|
|---|
| 5332 |
|
|---|
| 5333 | @menu
|
|---|
| 5334 | * Substitution Refs:: Referencing a variable with
|
|---|
| 5335 | substitutions on the value.
|
|---|
| 5336 | * Computed Names:: Computing the name of the variable to refer to.
|
|---|
| 5337 | @end menu
|
|---|
| 5338 |
|
|---|
| 5339 | @node Substitution Refs, Computed Names, Advanced, Advanced
|
|---|
| 5340 | @subsection Substitution References
|
|---|
| 5341 | @cindex modified variable reference
|
|---|
| 5342 | @cindex substitution variable reference
|
|---|
| 5343 | @cindex variables, modified reference
|
|---|
| 5344 | @cindex variables, substitution reference
|
|---|
| 5345 |
|
|---|
| 5346 | @cindex variables, substituting suffix in
|
|---|
| 5347 | @cindex suffix, substituting in variables
|
|---|
| 5348 | A @dfn{substitution reference} substitutes the value of a variable with
|
|---|
| 5349 | alterations that you specify. It has the form
|
|---|
| 5350 | @samp{$(@var{var}:@var{a}=@var{b})} (or
|
|---|
| 5351 | @samp{$@{@var{var}:@var{a}=@var{b}@}}) and its meaning is to take the value
|
|---|
| 5352 | of the variable @var{var}, replace every @var{a} at the end of a word with
|
|---|
| 5353 | @var{b} in that value, and substitute the resulting string.
|
|---|
| 5354 |
|
|---|
| 5355 | When we say ``at the end of a word'', we mean that @var{a} must appear
|
|---|
| 5356 | either followed by whitespace or at the end of the value in order to be
|
|---|
| 5357 | replaced; other occurrences of @var{a} in the value are unaltered. For
|
|---|
| 5358 | example:@refill
|
|---|
| 5359 |
|
|---|
| 5360 | @example
|
|---|
| 5361 | foo := a.o b.o c.o
|
|---|
| 5362 | bar := $(foo:.o=.c)
|
|---|
| 5363 | @end example
|
|---|
| 5364 |
|
|---|
| 5365 | @noindent
|
|---|
| 5366 | sets @samp{bar} to @samp{a.c b.c c.c}. @xref{Setting, ,Setting Variables}.
|
|---|
| 5367 |
|
|---|
| 5368 | A substitution reference is actually an abbreviation for use of the
|
|---|
| 5369 | @code{patsubst} expansion function (@pxref{Text Functions, ,Functions for String Substitution and Analysis}). We provide
|
|---|
| 5370 | substitution references as well as @code{patsubst} for compatibility with
|
|---|
| 5371 | other implementations of @code{make}.
|
|---|
| 5372 |
|
|---|
| 5373 | @findex patsubst
|
|---|
| 5374 | Another type of substitution reference lets you use the full power of
|
|---|
| 5375 | the @code{patsubst} function. It has the same form
|
|---|
| 5376 | @samp{$(@var{var}:@var{a}=@var{b})} described above, except that now
|
|---|
| 5377 | @var{a} must contain a single @samp{%} character. This case is
|
|---|
| 5378 | equivalent to @samp{$(patsubst @var{a},@var{b},$(@var{var}))}.
|
|---|
| 5379 | @xref{Text Functions, ,Functions for String Substitution and Analysis},
|
|---|
| 5380 | for a description of the @code{patsubst} function.@refill
|
|---|
| 5381 |
|
|---|
| 5382 | @example
|
|---|
| 5383 | @group
|
|---|
| 5384 | @exdent For example:
|
|---|
| 5385 |
|
|---|
| 5386 | foo := a.o b.o c.o
|
|---|
| 5387 | bar := $(foo:%.o=%.c)
|
|---|
| 5388 | @end group
|
|---|
| 5389 | @end example
|
|---|
| 5390 |
|
|---|
| 5391 | @noindent
|
|---|
| 5392 | sets @samp{bar} to @samp{a.c b.c c.c}.
|
|---|
| 5393 |
|
|---|
| 5394 | @node Computed Names, , Substitution Refs, Advanced
|
|---|
| 5395 | @subsection Computed Variable Names
|
|---|
| 5396 | @cindex nested variable reference
|
|---|
| 5397 | @cindex computed variable name
|
|---|
| 5398 | @cindex variables, computed names
|
|---|
| 5399 | @cindex variables, nested references
|
|---|
| 5400 | @cindex variables, @samp{$} in name
|
|---|
| 5401 | @cindex @code{$}, in variable name
|
|---|
| 5402 | @cindex dollar sign (@code{$}), in variable name
|
|---|
| 5403 |
|
|---|
| 5404 | Computed variable names are a complicated concept needed only for
|
|---|
| 5405 | sophisticated makefile programming. For most purposes you need not
|
|---|
| 5406 | consider them, except to know that making a variable with a dollar sign
|
|---|
| 5407 | in its name might have strange results. However, if you are the type
|
|---|
| 5408 | that wants to understand everything, or you are actually interested in
|
|---|
| 5409 | what they do, read on.
|
|---|
| 5410 |
|
|---|
| 5411 | Variables may be referenced inside the name of a variable. This is
|
|---|
| 5412 | called a @dfn{computed variable name} or a @dfn{nested variable
|
|---|
| 5413 | reference}. For example,
|
|---|
| 5414 |
|
|---|
| 5415 | @example
|
|---|
| 5416 | x = y
|
|---|
| 5417 | y = z
|
|---|
| 5418 | a := $($(x))
|
|---|
| 5419 | @end example
|
|---|
| 5420 |
|
|---|
| 5421 | @noindent
|
|---|
| 5422 | defines @code{a} as @samp{z}: the @samp{$(x)} inside @samp{$($(x))} expands
|
|---|
| 5423 | to @samp{y}, so @samp{$($(x))} expands to @samp{$(y)} which in turn expands
|
|---|
| 5424 | to @samp{z}. Here the name of the variable to reference is not stated
|
|---|
| 5425 | explicitly; it is computed by expansion of @samp{$(x)}. The reference
|
|---|
| 5426 | @samp{$(x)} here is nested within the outer variable reference.
|
|---|
| 5427 |
|
|---|
| 5428 | The previous example shows two levels of nesting, but any number of levels
|
|---|
| 5429 | is possible. For example, here are three levels:
|
|---|
| 5430 |
|
|---|
| 5431 | @example
|
|---|
| 5432 | x = y
|
|---|
| 5433 | y = z
|
|---|
| 5434 | z = u
|
|---|
| 5435 | a := $($($(x)))
|
|---|
| 5436 | @end example
|
|---|
| 5437 |
|
|---|
| 5438 | @noindent
|
|---|
| 5439 | Here the innermost @samp{$(x)} expands to @samp{y}, so @samp{$($(x))}
|
|---|
| 5440 | expands to @samp{$(y)} which in turn expands to @samp{z}; now we have
|
|---|
| 5441 | @samp{$(z)}, which becomes @samp{u}.
|
|---|
| 5442 |
|
|---|
| 5443 | References to recursively-expanded variables within a variable name are
|
|---|
| 5444 | re-expanded in the usual fashion. For example:
|
|---|
| 5445 |
|
|---|
| 5446 | @example
|
|---|
| 5447 | x = $(y)
|
|---|
| 5448 | y = z
|
|---|
| 5449 | z = Hello
|
|---|
| 5450 | a := $($(x))
|
|---|
| 5451 | @end example
|
|---|
| 5452 |
|
|---|
| 5453 | @noindent
|
|---|
| 5454 | defines @code{a} as @samp{Hello}: @samp{$($(x))} becomes @samp{$($(y))}
|
|---|
| 5455 | which becomes @samp{$(z)} which becomes @samp{Hello}.
|
|---|
| 5456 |
|
|---|
| 5457 | Nested variable references can also contain modified references and
|
|---|
| 5458 | function invocations (@pxref{Functions, ,Functions for Transforming Text}),
|
|---|
| 5459 | just like any other reference.
|
|---|
| 5460 | For example, using the @code{subst} function
|
|---|
| 5461 | (@pxref{Text Functions, ,Functions for String Substitution and Analysis}):
|
|---|
| 5462 |
|
|---|
| 5463 | @example
|
|---|
| 5464 | @group
|
|---|
| 5465 | x = variable1
|
|---|
| 5466 | variable2 := Hello
|
|---|
| 5467 | y = $(subst 1,2,$(x))
|
|---|
| 5468 | z = y
|
|---|
| 5469 | a := $($($(z)))
|
|---|
| 5470 | @end group
|
|---|
| 5471 | @end example
|
|---|
| 5472 |
|
|---|
| 5473 | @noindent
|
|---|
| 5474 | eventually defines @code{a} as @samp{Hello}. It is doubtful that anyone
|
|---|
| 5475 | would ever want to write a nested reference as convoluted as this one, but
|
|---|
| 5476 | it works: @samp{$($($(z)))} expands to @samp{$($(y))} which becomes
|
|---|
| 5477 | @samp{$($(subst 1,2,$(x)))}. This gets the value @samp{variable1} from
|
|---|
| 5478 | @code{x} and changes it by substitution to @samp{variable2}, so that the
|
|---|
| 5479 | entire string becomes @samp{$(variable2)}, a simple variable reference
|
|---|
| 5480 | whose value is @samp{Hello}.@refill
|
|---|
| 5481 |
|
|---|
| 5482 | A computed variable name need not consist entirely of a single variable
|
|---|
| 5483 | reference. It can contain several variable references, as well as some
|
|---|
| 5484 | invariant text. For example,
|
|---|
| 5485 |
|
|---|
| 5486 | @example
|
|---|
| 5487 | @group
|
|---|
| 5488 | a_dirs := dira dirb
|
|---|
| 5489 | 1_dirs := dir1 dir2
|
|---|
| 5490 | @end group
|
|---|
| 5491 |
|
|---|
| 5492 | @group
|
|---|
| 5493 | a_files := filea fileb
|
|---|
| 5494 | 1_files := file1 file2
|
|---|
| 5495 | @end group
|
|---|
| 5496 |
|
|---|
| 5497 | @group
|
|---|
| 5498 | ifeq "$(use_a)" "yes"
|
|---|
| 5499 | a1 := a
|
|---|
| 5500 | else
|
|---|
| 5501 | a1 := 1
|
|---|
| 5502 | endif
|
|---|
| 5503 | @end group
|
|---|
| 5504 |
|
|---|
| 5505 | @group
|
|---|
| 5506 | ifeq "$(use_dirs)" "yes"
|
|---|
| 5507 | df := dirs
|
|---|
| 5508 | else
|
|---|
| 5509 | df := files
|
|---|
| 5510 | endif
|
|---|
| 5511 |
|
|---|
| 5512 | dirs := $($(a1)_$(df))
|
|---|
| 5513 | @end group
|
|---|
| 5514 | @end example
|
|---|
| 5515 |
|
|---|
| 5516 | @noindent
|
|---|
| 5517 | will give @code{dirs} the same value as @code{a_dirs}, @code{1_dirs},
|
|---|
| 5518 | @code{a_files} or @code{1_files} depending on the settings of @code{use_a}
|
|---|
| 5519 | and @code{use_dirs}.@refill
|
|---|
| 5520 |
|
|---|
| 5521 | Computed variable names can also be used in substitution references:
|
|---|
| 5522 |
|
|---|
| 5523 | @example
|
|---|
| 5524 | @group
|
|---|
| 5525 | a_objects := a.o b.o c.o
|
|---|
| 5526 | 1_objects := 1.o 2.o 3.o
|
|---|
| 5527 |
|
|---|
| 5528 | sources := $($(a1)_objects:.o=.c)
|
|---|
| 5529 | @end group
|
|---|
| 5530 | @end example
|
|---|
| 5531 |
|
|---|
| 5532 | @noindent
|
|---|
| 5533 | defines @code{sources} as either @samp{a.c b.c c.c} or @samp{1.c 2.c 3.c},
|
|---|
| 5534 | depending on the value of @code{a1}.
|
|---|
| 5535 |
|
|---|
| 5536 | The only restriction on this sort of use of nested variable references
|
|---|
| 5537 | is that they cannot specify part of the name of a function to be called.
|
|---|
| 5538 | This is because the test for a recognized function name is done before
|
|---|
| 5539 | the expansion of nested references. For example,
|
|---|
| 5540 |
|
|---|
| 5541 | @example
|
|---|
| 5542 | @group
|
|---|
| 5543 | ifdef do_sort
|
|---|
| 5544 | func := sort
|
|---|
| 5545 | else
|
|---|
| 5546 | func := strip
|
|---|
| 5547 | endif
|
|---|
| 5548 | @end group
|
|---|
| 5549 |
|
|---|
| 5550 | @group
|
|---|
| 5551 | bar := a d b g q c
|
|---|
| 5552 | @end group
|
|---|
| 5553 |
|
|---|
| 5554 | @group
|
|---|
| 5555 | foo := $($(func) $(bar))
|
|---|
| 5556 | @end group
|
|---|
| 5557 | @end example
|
|---|
| 5558 |
|
|---|
| 5559 | @noindent
|
|---|
| 5560 | attempts to give @samp{foo} the value of the variable @samp{sort a d b g
|
|---|
| 5561 | q c} or @samp{strip a d b g q c}, rather than giving @samp{a d b g q c}
|
|---|
| 5562 | as the argument to either the @code{sort} or the @code{strip} function.
|
|---|
| 5563 | This restriction could be removed in the future if that change is shown
|
|---|
| 5564 | to be a good idea.
|
|---|
| 5565 |
|
|---|
| 5566 | You can also use computed variable names in the left-hand side of a
|
|---|
| 5567 | variable assignment, or in a @code{define} directive, as in:
|
|---|
| 5568 |
|
|---|
| 5569 | @example
|
|---|
| 5570 | dir = foo
|
|---|
| 5571 | $(dir)_sources := $(wildcard $(dir)/*.c)
|
|---|
| 5572 | define $(dir)_print =
|
|---|
| 5573 | lpr $($(dir)_sources)
|
|---|
| 5574 | endef
|
|---|
| 5575 | @end example
|
|---|
| 5576 |
|
|---|
| 5577 | @noindent
|
|---|
| 5578 | This example defines the variables @samp{dir}, @samp{foo_sources}, and
|
|---|
| 5579 | @samp{foo_print}.
|
|---|
| 5580 |
|
|---|
| 5581 | Note that @dfn{nested variable references} are quite different from
|
|---|
| 5582 | @dfn{recursively expanded variables}
|
|---|
| 5583 | (@pxref{Flavors, ,The Two Flavors of Variables}), though both are
|
|---|
| 5584 | used together in complex ways when doing makefile programming.@refill
|
|---|
| 5585 |
|
|---|
| 5586 | @node Values, Setting, Advanced, Using Variables
|
|---|
| 5587 | @section How Variables Get Their Values
|
|---|
| 5588 | @cindex variables, how they get their values
|
|---|
| 5589 | @cindex value, how a variable gets it
|
|---|
| 5590 |
|
|---|
| 5591 | Variables can get values in several different ways:
|
|---|
| 5592 |
|
|---|
| 5593 | @itemize @bullet
|
|---|
| 5594 | @item
|
|---|
| 5595 | You can specify an overriding value when you run @code{make}.
|
|---|
| 5596 | @xref{Overriding, ,Overriding Variables}.
|
|---|
| 5597 |
|
|---|
| 5598 | @item
|
|---|
| 5599 | You can specify a value in the makefile, either
|
|---|
| 5600 | with an assignment (@pxref{Setting, ,Setting Variables}) or with a
|
|---|
| 5601 | verbatim definition (@pxref{Multi-Line, ,Defining Multi-Line Variables}).@refill
|
|---|
| 5602 |
|
|---|
| 5603 | @item
|
|---|
| 5604 | Variables in the environment become @code{make} variables.
|
|---|
| 5605 | @xref{Environment, ,Variables from the Environment}.
|
|---|
| 5606 |
|
|---|
| 5607 | @item
|
|---|
| 5608 | Several @dfn{automatic} variables are given new values for each rule.
|
|---|
| 5609 | Each of these has a single conventional use.
|
|---|
| 5610 | @xref{Automatic Variables}.
|
|---|
| 5611 |
|
|---|
| 5612 | @item
|
|---|
| 5613 | Several variables have constant initial values.
|
|---|
| 5614 | @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
|
|---|
| 5615 | @end itemize
|
|---|
| 5616 |
|
|---|
| 5617 | @node Setting, Appending, Values, Using Variables
|
|---|
| 5618 | @section Setting Variables
|
|---|
| 5619 | @cindex setting variables
|
|---|
| 5620 | @cindex variables, setting
|
|---|
| 5621 | @cindex =
|
|---|
| 5622 | @cindex :=
|
|---|
| 5623 | @cindex ::=
|
|---|
| 5624 | @cindex ?=
|
|---|
| 5625 | @cindex !=
|
|---|
| 5626 |
|
|---|
| 5627 | To set a variable from the makefile, write a line starting with the
|
|---|
| 5628 | variable name followed by @samp{=}, @samp{:=}, or @samp{::=}. Whatever
|
|---|
| 5629 | follows the @samp{=}, @samp{:=}, or @samp{::=} on the line becomes the
|
|---|
| 5630 | value. For example,
|
|---|
| 5631 |
|
|---|
| 5632 | @example
|
|---|
| 5633 | objects = main.o foo.o bar.o utils.o
|
|---|
| 5634 | @end example
|
|---|
| 5635 |
|
|---|
| 5636 | @noindent
|
|---|
| 5637 | defines a variable named @code{objects}. Whitespace around the variable
|
|---|
| 5638 | name and immediately after the @samp{=} is ignored.
|
|---|
| 5639 |
|
|---|
| 5640 | Variables defined with @samp{=} are @dfn{recursively expanded}
|
|---|
| 5641 | variables. Variables defined with @samp{:=} or @samp{::=} are
|
|---|
| 5642 | @dfn{simply expanded} variables; these definitions can contain
|
|---|
| 5643 | variable references which will be expanded before the definition is
|
|---|
| 5644 | made. @xref{Flavors, ,The Two Flavors of Variables}.
|
|---|
| 5645 |
|
|---|
| 5646 | The variable name may contain function and variable references, which
|
|---|
| 5647 | are expanded when the line is read to find the actual variable name to use.
|
|---|
| 5648 |
|
|---|
| 5649 | There is no limit on the length of the value of a variable except the
|
|---|
| 5650 | amount of memory on the computer. You can split the value of a
|
|---|
| 5651 | variable into multiple physical lines for readability
|
|---|
| 5652 | (@pxref{Splitting Lines, ,Splitting Long Lines}).
|
|---|
| 5653 |
|
|---|
| 5654 | Most variable names are considered to have the empty string as a value if
|
|---|
| 5655 | you have never set them. Several variables have built-in initial values
|
|---|
| 5656 | that are not empty, but you can set them in the usual ways
|
|---|
| 5657 | (@pxref{Implicit Variables, ,Variables Used by Implicit Rules}).
|
|---|
| 5658 | Several special variables are set
|
|---|
| 5659 | automatically to a new value for each rule; these are called the
|
|---|
| 5660 | @dfn{automatic} variables (@pxref{Automatic Variables}).
|
|---|
| 5661 |
|
|---|
| 5662 | If you'd like a variable to be set to a value only if it's not already
|
|---|
| 5663 | set, then you can use the shorthand operator @samp{?=} instead of
|
|---|
| 5664 | @samp{=}. These two settings of the variable @samp{FOO} are identical
|
|---|
| 5665 | (@pxref{Origin Function, ,The @code{origin} Function}):
|
|---|
| 5666 |
|
|---|
| 5667 | @example
|
|---|
| 5668 | FOO ?= bar
|
|---|
| 5669 | @end example
|
|---|
| 5670 |
|
|---|
| 5671 | @noindent
|
|---|
| 5672 | and
|
|---|
| 5673 |
|
|---|
| 5674 | @example
|
|---|
| 5675 | ifeq ($(origin FOO), undefined)
|
|---|
| 5676 | FOO = bar
|
|---|
| 5677 | endif
|
|---|
| 5678 | @end example
|
|---|
| 5679 |
|
|---|
| 5680 | The shell assignment operator @samp{!=} can be used to execute a
|
|---|
| 5681 | shell script and set a variable to its output. This operator first
|
|---|
| 5682 | evaluates the right-hand side, then passes that result to the shell
|
|---|
| 5683 | for execution. If the result of the execution ends in a newline, that
|
|---|
| 5684 | one newline is removed; all other newlines are replaced by spaces.
|
|---|
| 5685 | The resulting string is then placed into the named
|
|---|
| 5686 | recursively-expanded variable. For example:
|
|---|
| 5687 |
|
|---|
| 5688 | @example
|
|---|
| 5689 | hash != printf '\043'
|
|---|
| 5690 | file_list != find . -name '*.c'
|
|---|
| 5691 | @end example
|
|---|
| 5692 |
|
|---|
| 5693 | If the result of the execution could produce a @code{$}, and you don't
|
|---|
| 5694 | intend what follows that to be interpreted as a make variable or
|
|---|
| 5695 | function reference, then you must replace every @code{$} with
|
|---|
| 5696 | @code{$$} as part of the execution. Alternatively, you can set a
|
|---|
| 5697 | simply expanded variable to the result of running a program using the
|
|---|
| 5698 | @code{shell} function call. @xref{Shell Function, , The @code{shell}
|
|---|
| 5699 | Function}. For example:
|
|---|
| 5700 |
|
|---|
| 5701 | @example
|
|---|
| 5702 | hash := $(shell printf '\043')
|
|---|
| 5703 | var := $(shell find . -name "*.c")
|
|---|
| 5704 | @end example
|
|---|
| 5705 |
|
|---|
| 5706 | As with the @code{shell} function, the exit status of the just-invoked
|
|---|
| 5707 | shell script is stored in the @code{.SHELLSTATUS} variable.
|
|---|
| 5708 |
|
|---|
| 5709 |
|
|---|
| 5710 | @node Appending, Override Directive, Setting, Using Variables
|
|---|
| 5711 | @section Appending More Text to Variables
|
|---|
| 5712 | @cindex +=
|
|---|
| 5713 | @cindex appending to variables
|
|---|
| 5714 | @cindex variables, appending to
|
|---|
| 5715 |
|
|---|
| 5716 | Often it is useful to add more text to the value of a variable already defined.
|
|---|
| 5717 | You do this with a line containing @samp{+=}, like this:
|
|---|
| 5718 |
|
|---|
| 5719 | @example
|
|---|
| 5720 | objects += another.o
|
|---|
| 5721 | @end example
|
|---|
| 5722 |
|
|---|
| 5723 | @noindent
|
|---|
| 5724 | This takes the value of the variable @code{objects}, and adds the text
|
|---|
| 5725 | @samp{another.o} to it (preceded by a single space). Thus:
|
|---|
| 5726 |
|
|---|
| 5727 | @example
|
|---|
| 5728 | objects = main.o foo.o bar.o utils.o
|
|---|
| 5729 | objects += another.o
|
|---|
| 5730 | @end example
|
|---|
| 5731 |
|
|---|
| 5732 | @noindent
|
|---|
| 5733 | sets @code{objects} to @samp{main.o foo.o bar.o utils.o another.o}.
|
|---|
| 5734 |
|
|---|
| 5735 | Using @samp{+=} is similar to:
|
|---|
| 5736 |
|
|---|
| 5737 | @example
|
|---|
| 5738 | objects = main.o foo.o bar.o utils.o
|
|---|
| 5739 | objects := $(objects) another.o
|
|---|
| 5740 | @end example
|
|---|
| 5741 |
|
|---|
| 5742 | @noindent
|
|---|
| 5743 | but differs in ways that become important when you use more complex values.
|
|---|
| 5744 |
|
|---|
| 5745 | When the variable in question has not been defined before, @samp{+=}
|
|---|
| 5746 | acts just like normal @samp{=}: it defines a recursively-expanded
|
|---|
| 5747 | variable. However, when there @emph{is} a previous definition, exactly
|
|---|
| 5748 | what @samp{+=} does depends on what flavor of variable you defined
|
|---|
| 5749 | originally. @xref{Flavors, ,The Two Flavors of Variables}, for an
|
|---|
| 5750 | explanation of the two flavors of variables.
|
|---|
| 5751 |
|
|---|
| 5752 | When you add to a variable's value with @samp{+=}, @code{make} acts
|
|---|
| 5753 | essentially as if you had included the extra text in the initial
|
|---|
| 5754 | definition of the variable. If you defined it first with @samp{:=} or
|
|---|
| 5755 | @samp{::=}, making it a simply-expanded variable, @samp{+=} adds to
|
|---|
| 5756 | that simply-expanded definition, and expands the new text before
|
|---|
| 5757 | appending it to the old value just as @samp{:=} does (see
|
|---|
| 5758 | @ref{Setting, ,Setting Variables}, for a full explanation of
|
|---|
| 5759 | @samp{:=} or @samp{::=}). In fact,
|
|---|
| 5760 |
|
|---|
| 5761 | @example
|
|---|
| 5762 | variable := value
|
|---|
| 5763 | variable += more
|
|---|
| 5764 | @end example
|
|---|
| 5765 |
|
|---|
| 5766 | @noindent
|
|---|
| 5767 | is exactly equivalent to:
|
|---|
| 5768 |
|
|---|
| 5769 | @noindent
|
|---|
| 5770 | @example
|
|---|
| 5771 | variable := value
|
|---|
| 5772 | variable := $(variable) more
|
|---|
| 5773 | @end example
|
|---|
| 5774 |
|
|---|
| 5775 | On the other hand, when you use @samp{+=} with a variable that you defined
|
|---|
| 5776 | first to be recursively-expanded using plain @samp{=}, @code{make} does
|
|---|
| 5777 | something a bit different. Recall that when you define a
|
|---|
| 5778 | recursively-expanded variable, @code{make} does not expand the value you set
|
|---|
| 5779 | for variable and function references immediately. Instead it stores the text
|
|---|
| 5780 | verbatim, and saves these variable and function references to be expanded
|
|---|
| 5781 | later, when you refer to the new variable (@pxref{Flavors, ,The Two Flavors
|
|---|
| 5782 | of Variables}). When you use @samp{+=} on a recursively-expanded variable,
|
|---|
| 5783 | it is this unexpanded text to which @code{make} appends the new text you
|
|---|
| 5784 | specify.
|
|---|
| 5785 |
|
|---|
| 5786 | @example
|
|---|
| 5787 | @group
|
|---|
| 5788 | variable = value
|
|---|
| 5789 | variable += more
|
|---|
| 5790 | @end group
|
|---|
| 5791 | @end example
|
|---|
| 5792 |
|
|---|
| 5793 | @noindent
|
|---|
| 5794 | is roughly equivalent to:
|
|---|
| 5795 |
|
|---|
| 5796 | @example
|
|---|
| 5797 | @group
|
|---|
| 5798 | temp = value
|
|---|
| 5799 | variable = $(temp) more
|
|---|
| 5800 | @end group
|
|---|
| 5801 | @end example
|
|---|
| 5802 |
|
|---|
| 5803 | @noindent
|
|---|
| 5804 | except that of course it never defines a variable called @code{temp}.
|
|---|
| 5805 | The importance of this comes when the variable's old value contains
|
|---|
| 5806 | variable references. Take this common example:
|
|---|
| 5807 |
|
|---|
| 5808 | @example
|
|---|
| 5809 | CFLAGS = $(includes) -O
|
|---|
| 5810 | @dots{}
|
|---|
| 5811 | CFLAGS += -pg # enable profiling
|
|---|
| 5812 | @end example
|
|---|
| 5813 |
|
|---|
| 5814 | @noindent
|
|---|
| 5815 | The first line defines the @code{CFLAGS} variable with a reference to another
|
|---|
| 5816 | variable, @code{includes}. (@code{CFLAGS} is used by the rules for C
|
|---|
| 5817 | compilation; @pxref{Catalogue of Rules, ,Catalogue of Built-In Rules}.)
|
|---|
| 5818 | Using @samp{=} for the definition makes @code{CFLAGS} a recursively-expanded
|
|---|
| 5819 | variable, meaning @w{@samp{$(includes) -O}} is @emph{not} expanded when
|
|---|
| 5820 | @code{make} processes the definition of @code{CFLAGS}. Thus, @code{includes}
|
|---|
| 5821 | need not be defined yet for its value to take effect. It only has to be
|
|---|
| 5822 | defined before any reference to @code{CFLAGS}. If we tried to append to the
|
|---|
| 5823 | value of @code{CFLAGS} without using @samp{+=}, we might do it like this:
|
|---|
| 5824 |
|
|---|
| 5825 | @example
|
|---|
| 5826 | CFLAGS := $(CFLAGS) -pg # enable profiling
|
|---|
| 5827 | @end example
|
|---|
| 5828 |
|
|---|
| 5829 | @noindent
|
|---|
| 5830 | This is pretty close, but not quite what we want. Using @samp{:=}
|
|---|
| 5831 | redefines @code{CFLAGS} as a simply-expanded variable; this means
|
|---|
| 5832 | @code{make} expands the text @w{@samp{$(CFLAGS) -pg}} before setting the
|
|---|
| 5833 | variable. If @code{includes} is not yet defined, we get @w{@samp{ -O
|
|---|
| 5834 | -pg}}, and a later definition of @code{includes} will have no effect.
|
|---|
| 5835 | Conversely, by using @samp{+=} we set @code{CFLAGS} to the
|
|---|
| 5836 | @emph{unexpanded} value @w{@samp{$(includes) -O -pg}}. Thus we preserve
|
|---|
| 5837 | the reference to @code{includes}, so if that variable gets defined at
|
|---|
| 5838 | any later point, a reference like @samp{$(CFLAGS)} still uses its
|
|---|
| 5839 | value.
|
|---|
| 5840 |
|
|---|
| 5841 | @node Override Directive, Multi-Line, Appending, Using Variables
|
|---|
| 5842 | @section The @code{override} Directive
|
|---|
| 5843 | @findex override
|
|---|
| 5844 | @cindex overriding with @code{override}
|
|---|
| 5845 | @cindex variables, overriding
|
|---|
| 5846 |
|
|---|
| 5847 | If a variable has been set with a command argument
|
|---|
| 5848 | (@pxref{Overriding, ,Overriding Variables}),
|
|---|
| 5849 | then ordinary assignments in the makefile are ignored. If you want to set
|
|---|
| 5850 | the variable in the makefile even though it was set with a command
|
|---|
| 5851 | argument, you can use an @code{override} directive, which is a line that
|
|---|
| 5852 | looks like this:@refill
|
|---|
| 5853 |
|
|---|
| 5854 | @example
|
|---|
| 5855 | override @var{variable} = @var{value}
|
|---|
| 5856 | @end example
|
|---|
| 5857 |
|
|---|
| 5858 | @noindent
|
|---|
| 5859 | or
|
|---|
| 5860 |
|
|---|
| 5861 | @example
|
|---|
| 5862 | override @var{variable} := @var{value}
|
|---|
| 5863 | @end example
|
|---|
| 5864 |
|
|---|
| 5865 | To append more text to a variable defined on the command line, use:
|
|---|
| 5866 |
|
|---|
| 5867 | @example
|
|---|
| 5868 | override @var{variable} += @var{more text}
|
|---|
| 5869 | @end example
|
|---|
| 5870 |
|
|---|
| 5871 | @noindent
|
|---|
| 5872 | @xref{Appending, ,Appending More Text to Variables}.
|
|---|
| 5873 |
|
|---|
| 5874 | Variable assignments marked with the @code{override} flag have a
|
|---|
| 5875 | higher priority than all other assignments, except another
|
|---|
| 5876 | @code{override}. Subsequent assignments or appends to this variable
|
|---|
| 5877 | which are not marked @code{override} will be ignored.
|
|---|
| 5878 |
|
|---|
| 5879 | The @code{override} directive was not invented for escalation in the war
|
|---|
| 5880 | between makefiles and command arguments. It was invented so you can alter
|
|---|
| 5881 | and add to values that the user specifies with command arguments.
|
|---|
| 5882 |
|
|---|
| 5883 | For example, suppose you always want the @samp{-g} switch when you run the
|
|---|
| 5884 | C compiler, but you would like to allow the user to specify the other
|
|---|
| 5885 | switches with a command argument just as usual. You could use this
|
|---|
| 5886 | @code{override} directive:
|
|---|
| 5887 |
|
|---|
| 5888 | @example
|
|---|
| 5889 | override CFLAGS += -g
|
|---|
| 5890 | @end example
|
|---|
| 5891 |
|
|---|
| 5892 | You can also use @code{override} directives with @code{define} directives.
|
|---|
| 5893 | This is done as you might expect:
|
|---|
| 5894 |
|
|---|
| 5895 | @example
|
|---|
| 5896 | override define foo =
|
|---|
| 5897 | bar
|
|---|
| 5898 | endef
|
|---|
| 5899 | @end example
|
|---|
| 5900 |
|
|---|
| 5901 | @noindent
|
|---|
| 5902 | @iftex
|
|---|
| 5903 | See the next section for information about @code{define}.
|
|---|
| 5904 | @end iftex
|
|---|
| 5905 | @ifnottex
|
|---|
| 5906 | @xref{Multi-Line, ,Defining Multi-Line Variables}.
|
|---|
| 5907 | @end ifnottex
|
|---|
| 5908 |
|
|---|
| 5909 | @node Multi-Line, Undefine Directive, Override Directive, Using Variables
|
|---|
| 5910 | @section Defining Multi-Line Variables
|
|---|
| 5911 | @findex define
|
|---|
| 5912 | @findex endef
|
|---|
| 5913 | @cindex multi-line variable definition
|
|---|
| 5914 | @cindex variables, multi-line
|
|---|
| 5915 | @cindex verbatim variable definition
|
|---|
| 5916 | @cindex defining variables verbatim
|
|---|
| 5917 | @cindex variables, defining verbatim
|
|---|
| 5918 |
|
|---|
| 5919 | Another way to set the value of a variable is to use the @code{define}
|
|---|
| 5920 | directive. This directive has an unusual syntax which allows newline
|
|---|
| 5921 | characters to be included in the value, which is convenient for
|
|---|
| 5922 | defining both canned sequences of commands (@pxref{Canned Recipes,
|
|---|
| 5923 | ,Defining Canned Recipes}), and also sections of makefile syntax to
|
|---|
| 5924 | use with @code{eval} (@pxref{Eval Function}).@refill
|
|---|
| 5925 |
|
|---|
| 5926 | The @code{define} directive is followed on the same line by the name
|
|---|
| 5927 | of the variable being defined and an (optional) assignment operator,
|
|---|
| 5928 | and nothing more. The value to give the variable appears on the
|
|---|
| 5929 | following lines. The end of the value is marked by a line containing
|
|---|
| 5930 | just the word @code{endef}. Aside from this difference in syntax,
|
|---|
| 5931 | @code{define} works just like any other variable definition. The
|
|---|
| 5932 | variable name may contain function and variable references, which are
|
|---|
| 5933 | expanded when the directive is read to find the actual variable name
|
|---|
| 5934 | to use.
|
|---|
| 5935 |
|
|---|
| 5936 | You may omit the variable assignment operator if you prefer. If
|
|---|
| 5937 | omitted, @code{make} assumes it to be @samp{=} and creates a
|
|---|
| 5938 | recursively-expanded variable (@pxref{Flavors, ,The Two Flavors of Variables}).
|
|---|
| 5939 | When using a @samp{+=} operator, the value is appended to the previous
|
|---|
| 5940 | value as with any other append operation: with a single space
|
|---|
| 5941 | separating the old and new values.
|
|---|
| 5942 |
|
|---|
| 5943 | You may nest @code{define} directives: @code{make} will keep track of
|
|---|
| 5944 | nested directives and report an error if they are not all properly
|
|---|
| 5945 | closed with @code{endef}. Note that lines beginning with the recipe
|
|---|
| 5946 | prefix character are considered part of a recipe, so any @code{define}
|
|---|
| 5947 | or @code{endef} strings appearing on such a line will not be
|
|---|
| 5948 | considered @code{make} directives.
|
|---|
| 5949 |
|
|---|
| 5950 | @example
|
|---|
| 5951 | define two-lines =
|
|---|
| 5952 | echo foo
|
|---|
| 5953 | echo $(bar)
|
|---|
| 5954 | endef
|
|---|
| 5955 | @end example
|
|---|
| 5956 |
|
|---|
| 5957 | The value in an ordinary assignment cannot contain a newline; but the
|
|---|
| 5958 | newlines that separate the lines of the value in a @code{define} become
|
|---|
| 5959 | part of the variable's value (except for the final newline which precedes
|
|---|
| 5960 | the @code{endef} and is not considered part of the value).@refill
|
|---|
| 5961 |
|
|---|
| 5962 | @need 800
|
|---|
| 5963 | When used in a recipe, the previous example is functionally equivalent
|
|---|
| 5964 | to this:
|
|---|
| 5965 |
|
|---|
| 5966 | @example
|
|---|
| 5967 | two-lines = echo foo; echo $(bar)
|
|---|
| 5968 | @end example
|
|---|
| 5969 |
|
|---|
| 5970 | @noindent
|
|---|
| 5971 | since two commands separated by semicolon behave much like two separate
|
|---|
| 5972 | shell commands. However, note that using two separate lines means
|
|---|
| 5973 | @code{make} will invoke the shell twice, running an independent sub-shell
|
|---|
| 5974 | for each line. @xref{Execution, ,Recipe Execution}.
|
|---|
| 5975 |
|
|---|
| 5976 | If you want variable definitions made with @code{define} to take
|
|---|
| 5977 | precedence over command-line variable definitions, you can use the
|
|---|
| 5978 | @code{override} directive together with @code{define}:
|
|---|
| 5979 |
|
|---|
| 5980 | @example
|
|---|
| 5981 | override define two-lines =
|
|---|
| 5982 | foo
|
|---|
| 5983 | $(bar)
|
|---|
| 5984 | endef
|
|---|
| 5985 | @end example
|
|---|
| 5986 |
|
|---|
| 5987 | @noindent
|
|---|
| 5988 | @xref{Override Directive, ,The @code{override} Directive}.
|
|---|
| 5989 |
|
|---|
| 5990 | @node Undefine Directive, Environment, Multi-Line, Using Variables
|
|---|
| 5991 | @section Undefining Variables
|
|---|
| 5992 | @findex undefine
|
|---|
| 5993 | @cindex undefining variable
|
|---|
| 5994 |
|
|---|
| 5995 | If you want to clear a variable, setting its value to empty is usually
|
|---|
| 5996 | sufficient. Expanding such a variable will yield the same result (empty
|
|---|
| 5997 | string) regardless of whether it was set or not. However, if you are
|
|---|
| 5998 | using the @code{flavor} (@pxref{Flavor Function}) and
|
|---|
| 5999 | @code{origin} (@pxref{Origin Function}) functions, there is a difference
|
|---|
| 6000 | between a variable that was never set and a variable with an empty value.
|
|---|
| 6001 | In such situations you may want to use the @code{undefine} directive to
|
|---|
| 6002 | make a variable appear as if it was never set. For example:
|
|---|
| 6003 |
|
|---|
| 6004 | @example
|
|---|
| 6005 | foo := foo
|
|---|
| 6006 | bar = bar
|
|---|
| 6007 |
|
|---|
| 6008 | undefine foo
|
|---|
| 6009 | undefine bar
|
|---|
| 6010 |
|
|---|
| 6011 | $(info $(origin foo))
|
|---|
| 6012 | $(info $(flavor bar))
|
|---|
| 6013 | @end example
|
|---|
| 6014 |
|
|---|
| 6015 | This example will print ``undefined'' for both variables.
|
|---|
| 6016 |
|
|---|
| 6017 | If you want to undefine a command-line variable definition, you can use
|
|---|
| 6018 | the @code{override} directive together with @code{undefine}, similar to
|
|---|
| 6019 | how this is done for variable definitions:
|
|---|
| 6020 |
|
|---|
| 6021 | @example
|
|---|
| 6022 | override undefine CFLAGS
|
|---|
| 6023 | @end example
|
|---|
| 6024 |
|
|---|
| 6025 | @node Environment, Target-specific, Undefine Directive, Using Variables
|
|---|
| 6026 | @section Variables from the Environment
|
|---|
| 6027 |
|
|---|
| 6028 | @cindex variables, environment
|
|---|
| 6029 | @cindex environment
|
|---|
| 6030 | Variables in @code{make} can come from the environment in which
|
|---|
| 6031 | @code{make} is run. Every environment variable that @code{make} sees
|
|---|
| 6032 | when it starts up is transformed into a @code{make} variable with the
|
|---|
| 6033 | same name and value. However, an explicit assignment in the makefile,
|
|---|
| 6034 | or with a command argument, overrides the environment. (If the
|
|---|
| 6035 | @samp{-e} flag is specified, then values from the environment override
|
|---|
| 6036 | assignments in the makefile. @xref{Options Summary, ,Summary of
|
|---|
| 6037 | Options}. But this is not recommended practice.)
|
|---|
| 6038 |
|
|---|
| 6039 | Thus, by setting the variable @code{CFLAGS} in your environment, you can
|
|---|
| 6040 | cause all C compilations in most makefiles to use the compiler switches you
|
|---|
| 6041 | prefer. This is safe for variables with standard or conventional meanings
|
|---|
| 6042 | because you know that no makefile will use them for other things. (Note
|
|---|
| 6043 | this is not totally reliable; some makefiles set @code{CFLAGS} explicitly
|
|---|
| 6044 | and therefore are not affected by the value in the environment.)
|
|---|
| 6045 |
|
|---|
| 6046 | When @code{make} runs a recipe, variables defined in the
|
|---|
| 6047 | makefile are placed into the environment of each shell. This allows
|
|---|
| 6048 | you to pass values to sub-@code{make} invocations (@pxref{Recursion,
|
|---|
| 6049 | ,Recursive Use of @code{make}}). By default, only variables that came
|
|---|
| 6050 | from the environment or the command line are passed to recursive
|
|---|
| 6051 | invocations. You can use the @code{export} directive to pass other
|
|---|
| 6052 | variables. @xref{Variables/Recursion, , Communicating Variables to a
|
|---|
| 6053 | Sub-@code{make}}, for full details.
|
|---|
| 6054 |
|
|---|
| 6055 | Other use of variables from the environment is not recommended. It is not
|
|---|
| 6056 | wise for makefiles to depend for their functioning on environment variables
|
|---|
| 6057 | set up outside their control, since this would cause different users to get
|
|---|
| 6058 | different results from the same makefile. This is against the whole
|
|---|
| 6059 | purpose of most makefiles.
|
|---|
| 6060 |
|
|---|
| 6061 | @cindex SHELL, import from environment
|
|---|
| 6062 | Such problems would be especially likely with the variable
|
|---|
| 6063 | @code{SHELL}, which is normally present in the environment to specify
|
|---|
| 6064 | the user's choice of interactive shell. It would be very undesirable
|
|---|
| 6065 | for this choice to affect @code{make}; so, @code{make} handles the
|
|---|
| 6066 | @code{SHELL} environment variable in a special way; see @ref{Choosing
|
|---|
| 6067 | the Shell}.@refill
|
|---|
| 6068 |
|
|---|
| 6069 | @node Target-specific, Pattern-specific, Environment, Using Variables
|
|---|
| 6070 | @section Target-specific Variable Values
|
|---|
| 6071 | @cindex target-specific variables
|
|---|
| 6072 | @cindex variables, target-specific
|
|---|
| 6073 |
|
|---|
| 6074 | Variable values in @code{make} are usually global; that is, they are the
|
|---|
| 6075 | same regardless of where they are evaluated (unless they're reset, of
|
|---|
| 6076 | course). One exception to that is automatic variables
|
|---|
| 6077 | (@pxref{Automatic Variables}).
|
|---|
| 6078 |
|
|---|
| 6079 | The other exception is @dfn{target-specific variable values}. This
|
|---|
| 6080 | feature allows you to define different values for the same variable,
|
|---|
| 6081 | based on the target that @code{make} is currently building. As with
|
|---|
| 6082 | automatic variables, these values are only available within the context
|
|---|
| 6083 | of a target's recipe (and in other target-specific assignments).
|
|---|
| 6084 |
|
|---|
| 6085 | Set a target-specific variable value like this:
|
|---|
| 6086 |
|
|---|
| 6087 | @example
|
|---|
| 6088 | @var{target} @dots{} : @var{variable-assignment}
|
|---|
| 6089 | @end example
|
|---|
| 6090 |
|
|---|
| 6091 | Target-specific variable assignments can be prefixed with any or all of the
|
|---|
| 6092 | special keywords @code{export}, @code{override}, or @code{private};
|
|---|
| 6093 | these apply their normal behavior to this instance of the variable only.
|
|---|
| 6094 |
|
|---|
| 6095 | Multiple @var{target} values create a target-specific variable value for
|
|---|
| 6096 | each member of the target list individually.
|
|---|
| 6097 |
|
|---|
| 6098 | The @var{variable-assignment} can be any valid form of assignment;
|
|---|
| 6099 | recursive (@samp{=}), simple (@samp{:=} or @samp{::=}), appending
|
|---|
| 6100 | (@samp{+=}), or conditional (@samp{?=}). All variables that appear
|
|---|
| 6101 | within the @var{variable-assignment} are evaluated within the context
|
|---|
| 6102 | of the target: thus, any previously-defined target-specific variable
|
|---|
| 6103 | values will be in effect. Note that this variable is actually
|
|---|
| 6104 | distinct from any ``global'' value: the two variables do not have to
|
|---|
| 6105 | have the same flavor (recursive vs.@: simple).
|
|---|
| 6106 |
|
|---|
| 6107 | Target-specific variables have the same priority as any other makefile
|
|---|
| 6108 | variable. Variables provided on the command line (and in the
|
|---|
| 6109 | environment if the @samp{-e} option is in force) will take precedence.
|
|---|
| 6110 | Specifying the @code{override} directive will allow the target-specific
|
|---|
| 6111 | variable value to be preferred.
|
|---|
| 6112 |
|
|---|
| 6113 | There is one more special feature of target-specific variables: when
|
|---|
| 6114 | you define a target-specific variable that variable value is also in
|
|---|
| 6115 | effect for all prerequisites of this target, and all their
|
|---|
| 6116 | prerequisites, etc.@: (unless those prerequisites override that variable
|
|---|
| 6117 | with their own target-specific variable value). So, for example, a
|
|---|
| 6118 | statement like this:
|
|---|
| 6119 |
|
|---|
| 6120 | @example
|
|---|
| 6121 | prog : CFLAGS = -g
|
|---|
| 6122 | prog : prog.o foo.o bar.o
|
|---|
| 6123 | @end example
|
|---|
| 6124 |
|
|---|
| 6125 | @noindent
|
|---|
| 6126 | will set @code{CFLAGS} to @samp{-g} in the recipe for @file{prog}, but
|
|---|
| 6127 | it will also set @code{CFLAGS} to @samp{-g} in the recipes that create
|
|---|
| 6128 | @file{prog.o}, @file{foo.o}, and @file{bar.o}, and any recipes which
|
|---|
| 6129 | create their prerequisites.
|
|---|
| 6130 |
|
|---|
| 6131 | Be aware that a given prerequisite will only be built once per
|
|---|
| 6132 | invocation of make, at most. If the same file is a prerequisite of
|
|---|
| 6133 | multiple targets, and each of those targets has a different value for
|
|---|
| 6134 | the same target-specific variable, then the first target to be built
|
|---|
| 6135 | will cause that prerequisite to be built and the prerequisite will
|
|---|
| 6136 | inherit the target-specific value from the first target. It will
|
|---|
| 6137 | ignore the target-specific values from any other targets.
|
|---|
| 6138 |
|
|---|
| 6139 | @node Pattern-specific, Suppressing Inheritance, Target-specific, Using Variables
|
|---|
| 6140 | @section Pattern-specific Variable Values
|
|---|
| 6141 | @cindex pattern-specific variables
|
|---|
| 6142 | @cindex variables, pattern-specific
|
|---|
| 6143 |
|
|---|
| 6144 | In addition to target-specific variable values
|
|---|
| 6145 | (@pxref{Target-specific, ,Target-specific Variable Values}), GNU
|
|---|
| 6146 | @code{make} supports pattern-specific variable values. In this form,
|
|---|
| 6147 | the variable is defined for any target that matches the pattern
|
|---|
| 6148 | specified.
|
|---|
| 6149 |
|
|---|
| 6150 | Set a pattern-specific variable value like this:
|
|---|
| 6151 |
|
|---|
| 6152 | @example
|
|---|
| 6153 | @var{pattern} @dots{} : @var{variable-assignment}
|
|---|
| 6154 | @end example
|
|---|
| 6155 | where @var{pattern} is a %-pattern. As with target-specific variable
|
|---|
| 6156 | values, multiple @var{pattern} values create a pattern-specific variable
|
|---|
| 6157 | value for each pattern individually. The @var{variable-assignment} can
|
|---|
| 6158 | be any valid form of assignment. Any command line variable setting will
|
|---|
| 6159 | take precedence, unless @code{override} is specified.
|
|---|
| 6160 |
|
|---|
| 6161 | For example:
|
|---|
| 6162 |
|
|---|
| 6163 | @example
|
|---|
| 6164 | %.o : CFLAGS = -O
|
|---|
| 6165 | @end example
|
|---|
| 6166 |
|
|---|
| 6167 | @noindent
|
|---|
| 6168 | will assign @code{CFLAGS} the value of @samp{-O} for all targets
|
|---|
| 6169 | matching the pattern @code{%.o}.
|
|---|
| 6170 |
|
|---|
| 6171 | If a target matches more than one pattern, the matching pattern-specific
|
|---|
| 6172 | variables with longer stems are interpreted first. This results in more
|
|---|
| 6173 | specific variables taking precedence over the more generic ones, for
|
|---|
| 6174 | example:
|
|---|
| 6175 |
|
|---|
| 6176 | @example
|
|---|
| 6177 | %.o: %.c
|
|---|
| 6178 | $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
|
|---|
| 6179 |
|
|---|
| 6180 | lib/%.o: CFLAGS := -fPIC -g
|
|---|
| 6181 | %.o: CFLAGS := -g
|
|---|
| 6182 |
|
|---|
| 6183 | all: foo.o lib/bar.o
|
|---|
| 6184 | @end example
|
|---|
| 6185 |
|
|---|
| 6186 | In this example the first definition of the @code{CFLAGS} variable
|
|---|
| 6187 | will be used to update @file{lib/bar.o} even though the second one
|
|---|
| 6188 | also applies to this target. Pattern-specific variables which result
|
|---|
| 6189 | in the same stem length are considered in the order in which they
|
|---|
| 6190 | were defined in the makefile.
|
|---|
| 6191 |
|
|---|
| 6192 | Pattern-specific variables are searched after any target-specific
|
|---|
| 6193 | variables defined explicitly for that target, and before target-specific
|
|---|
| 6194 | variables defined for the parent target.
|
|---|
| 6195 |
|
|---|
| 6196 | @node Suppressing Inheritance, Special Variables, Pattern-specific, Using Variables
|
|---|
| 6197 | @section Suppressing Inheritance
|
|---|
| 6198 | @findex private
|
|---|
| 6199 | @cindex suppressing inheritance
|
|---|
| 6200 | @cindex inheritance, suppressing
|
|---|
| 6201 |
|
|---|
| 6202 | As described in previous sections, @code{make} variables are inherited
|
|---|
| 6203 | by prerequisites. This capability allows you to modify the behavior
|
|---|
| 6204 | of a prerequisite based on which targets caused it to be rebuilt. For
|
|---|
| 6205 | example, you might set a target-specific variable on a @code{debug}
|
|---|
| 6206 | target, then running @samp{make debug} will cause that variable to be
|
|---|
| 6207 | inherited by all prerequisites of @code{debug}, while just running
|
|---|
| 6208 | @samp{make all} (for example) would not have that assignment.
|
|---|
| 6209 |
|
|---|
| 6210 | Sometimes, however, you may not want a variable to be inherited. For
|
|---|
| 6211 | these situations, @code{make} provides the @code{private} modifier.
|
|---|
| 6212 | Although this modifier can be used with any variable assignment, it
|
|---|
| 6213 | makes the most sense with target- and pattern-specific variables. Any
|
|---|
| 6214 | variable marked @code{private} will be visible to its local target but
|
|---|
| 6215 | will not be inherited by prerequisites of that target. A global
|
|---|
| 6216 | variable marked @code{private} will be visible in the global scope but
|
|---|
| 6217 | will not be inherited by any target, and hence will not be visible
|
|---|
| 6218 | in any recipe.
|
|---|
| 6219 |
|
|---|
| 6220 | As an example, consider this makefile:
|
|---|
| 6221 | @example
|
|---|
| 6222 | EXTRA_CFLAGS =
|
|---|
| 6223 |
|
|---|
| 6224 | prog: private EXTRA_CFLAGS = -L/usr/local/lib
|
|---|
| 6225 | prog: a.o b.o
|
|---|
| 6226 | @end example
|
|---|
| 6227 |
|
|---|
| 6228 | Due to the @code{private} modifier, @code{a.o} and @code{b.o} will not
|
|---|
| 6229 | inherit the @code{EXTRA_CFLAGS} variable assignment from the
|
|---|
| 6230 | @code{prog} target.
|
|---|
| 6231 |
|
|---|
| 6232 | @node Special Variables, , Suppressing Inheritance, Using Variables
|
|---|
| 6233 | @comment node-name, next, previous, up
|
|---|
| 6234 | @section Other Special Variables
|
|---|
| 6235 | @cindex makefiles, and special variables
|
|---|
| 6236 | @cindex special variables
|
|---|
| 6237 |
|
|---|
| 6238 | GNU @code{make} supports some variables that have special properties.
|
|---|
| 6239 |
|
|---|
| 6240 | @table @code
|
|---|
| 6241 |
|
|---|
| 6242 | @vindex MAKEFILE_LIST @r{(list of parsed makefiles)}
|
|---|
| 6243 | @cindex makefiles, and @code{MAKEFILE_LIST} variable
|
|---|
| 6244 | @cindex including (@code{MAKEFILE_LIST} variable)
|
|---|
| 6245 | @item MAKEFILE_LIST
|
|---|
| 6246 | Contains the name of each makefile that is parsed by @code{make}, in
|
|---|
| 6247 | the order in which it was parsed. The name is appended just
|
|---|
| 6248 | before @code{make} begins to parse the makefile. Thus, if the first
|
|---|
| 6249 | thing a makefile does is examine the last word in this variable, it
|
|---|
| 6250 | will be the name of the current makefile. Once the current makefile
|
|---|
| 6251 | has used @code{include}, however, the last word will be the
|
|---|
| 6252 | just-included makefile.
|
|---|
| 6253 |
|
|---|
| 6254 | If a makefile named @code{Makefile} has this content:
|
|---|
| 6255 |
|
|---|
| 6256 | @example
|
|---|
| 6257 | @group
|
|---|
| 6258 | name1 := $(lastword $(MAKEFILE_LIST))
|
|---|
| 6259 |
|
|---|
| 6260 | include inc.mk
|
|---|
| 6261 |
|
|---|
| 6262 | name2 := $(lastword $(MAKEFILE_LIST))
|
|---|
| 6263 |
|
|---|
| 6264 | all:
|
|---|
| 6265 | @@echo name1 = $(name1)
|
|---|
| 6266 | @@echo name2 = $(name2)
|
|---|
| 6267 | @end group
|
|---|
| 6268 | @end example
|
|---|
| 6269 |
|
|---|
| 6270 | @noindent
|
|---|
| 6271 | then you would expect to see this output:
|
|---|
| 6272 |
|
|---|
| 6273 | @example
|
|---|
| 6274 | @group
|
|---|
| 6275 | name1 = Makefile
|
|---|
| 6276 | name2 = inc.mk
|
|---|
| 6277 | @end group
|
|---|
| 6278 | @end example
|
|---|
| 6279 |
|
|---|
| 6280 | @vindex .DEFAULT_GOAL @r{(define default goal)}
|
|---|
| 6281 | @item .DEFAULT_GOAL
|
|---|
| 6282 | Sets the default goal to be used if no targets were specified on the
|
|---|
| 6283 | command line (@pxref{Goals, , Arguments to Specify the Goals}). The
|
|---|
| 6284 | @code{.DEFAULT_GOAL} variable allows you to discover the current
|
|---|
| 6285 | default goal, restart the default goal selection algorithm by clearing
|
|---|
| 6286 | its value, or to explicitly set the default goal. The following
|
|---|
| 6287 | example illustrates these cases:
|
|---|
| 6288 |
|
|---|
| 6289 | @example
|
|---|
| 6290 | @group
|
|---|
| 6291 | # Query the default goal.
|
|---|
| 6292 | ifeq ($(.DEFAULT_GOAL),)
|
|---|
| 6293 | $(warning no default goal is set)
|
|---|
| 6294 | endif
|
|---|
| 6295 |
|
|---|
| 6296 | .PHONY: foo
|
|---|
| 6297 | foo: ; @@echo $@@
|
|---|
| 6298 |
|
|---|
| 6299 | $(warning default goal is $(.DEFAULT_GOAL))
|
|---|
| 6300 |
|
|---|
| 6301 | # Reset the default goal.
|
|---|
| 6302 | .DEFAULT_GOAL :=
|
|---|
| 6303 |
|
|---|
| 6304 | .PHONY: bar
|
|---|
| 6305 | bar: ; @@echo $@@
|
|---|
| 6306 |
|
|---|
| 6307 | $(warning default goal is $(.DEFAULT_GOAL))
|
|---|
| 6308 |
|
|---|
| 6309 | # Set our own.
|
|---|
| 6310 | .DEFAULT_GOAL := foo
|
|---|
| 6311 | @end group
|
|---|
| 6312 | @end example
|
|---|
| 6313 |
|
|---|
| 6314 | This makefile prints:
|
|---|
| 6315 |
|
|---|
| 6316 | @example
|
|---|
| 6317 | @group
|
|---|
| 6318 | no default goal is set
|
|---|
| 6319 | default goal is foo
|
|---|
| 6320 | default goal is bar
|
|---|
| 6321 | foo
|
|---|
| 6322 | @end group
|
|---|
| 6323 | @end example
|
|---|
| 6324 |
|
|---|
| 6325 | Note that assigning more than one target name to @code{.DEFAULT_GOAL} is
|
|---|
| 6326 | invalid and will result in an error.
|
|---|
| 6327 |
|
|---|
| 6328 | @vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)}
|
|---|
| 6329 | @item MAKE_RESTARTS
|
|---|
| 6330 | This variable is set only if this instance of @code{make} has
|
|---|
| 6331 | restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it
|
|---|
| 6332 | will contain the number of times this instance has restarted. Note
|
|---|
| 6333 | this is not the same as recursion (counted by the @code{MAKELEVEL}
|
|---|
| 6334 | variable). You should not set, modify, or export this variable.
|
|---|
| 6335 |
|
|---|
| 6336 | @vindex MAKE_TERMOUT @r{(whether stdout is a terminal)}
|
|---|
| 6337 | @vindex MAKE_TERMERR @r{(whether stderr is a terminal)}
|
|---|
| 6338 | @item MAKE_TERMOUT
|
|---|
| 6339 | @itemx MAKE_TERMERR
|
|---|
| 6340 | When @code{make} starts it will check whether stdout and stderr will
|
|---|
| 6341 | show their output on a terminal. If so, it will set
|
|---|
| 6342 | @code{MAKE_TERMOUT} and @code{MAKE_TERMERR}, respectively, to the name
|
|---|
| 6343 | of the terminal device (or @code{true} if this cannot be determined).
|
|---|
| 6344 | If set these variables will be marked for export. These variables
|
|---|
| 6345 | will not be changed by @code{make} and they will not be modified if
|
|---|
| 6346 | already set.
|
|---|
| 6347 |
|
|---|
| 6348 | These values can be used (particularly in combination with output
|
|---|
| 6349 | synchronization (@pxref{Parallel Output, ,Output During Parallel
|
|---|
| 6350 | Execution}) to determine whether @code{make} itself is writing to a
|
|---|
| 6351 | terminal; they can be tested to decide whether to force recipe
|
|---|
| 6352 | commands to generate colorized output for example.
|
|---|
| 6353 |
|
|---|
| 6354 | If you invoke a sub-@code{make} and redirect its stdout or stderr it
|
|---|
| 6355 | is your responsibility to reset or unexport these variables as well,
|
|---|
| 6356 | if your makefiles rely on them.
|
|---|
| 6357 |
|
|---|
| 6358 | @vindex .RECIPEPREFIX @r{(change the recipe prefix character)}
|
|---|
| 6359 | @item .RECIPEPREFIX
|
|---|
| 6360 | The first character of the value of this variable is used as the
|
|---|
| 6361 | character make assumes is introducing a recipe line. If the variable
|
|---|
| 6362 | is empty (as it is by default) that character is the standard tab
|
|---|
| 6363 | character. For example, this is a valid makefile:
|
|---|
| 6364 |
|
|---|
| 6365 | @example
|
|---|
| 6366 | @group
|
|---|
| 6367 | .RECIPEPREFIX = >
|
|---|
| 6368 | all:
|
|---|
| 6369 | > @@echo Hello, world
|
|---|
| 6370 | @end group
|
|---|
| 6371 | @end example
|
|---|
| 6372 |
|
|---|
| 6373 | The value of @code{.RECIPEPREFIX} can be changed multiple times; once set
|
|---|
| 6374 | it stays in effect for all rules parsed until it is modified.
|
|---|
| 6375 |
|
|---|
| 6376 | @vindex .VARIABLES @r{(list of variables)}
|
|---|
| 6377 | @item .VARIABLES
|
|---|
| 6378 | Expands to a list of the @emph{names} of all global variables defined
|
|---|
| 6379 | so far. This includes variables which have empty values, as well as
|
|---|
| 6380 | built-in variables (@pxref{Implicit Variables, , Variables Used by
|
|---|
| 6381 | Implicit Rules}), but does not include any variables which are only
|
|---|
| 6382 | defined in a target-specific context. Note that any value you assign
|
|---|
| 6383 | to this variable will be ignored; it will always return its special
|
|---|
| 6384 | value.
|
|---|
| 6385 |
|
|---|
| 6386 | @c @vindex .TARGETS @r{(list of targets)}
|
|---|
| 6387 | @c @item .TARGETS
|
|---|
| 6388 | @c The second special variable is @code{.TARGETS}. When expanded, the
|
|---|
| 6389 | @c value consists of a list of all targets defined in all makefiles read
|
|---|
| 6390 | @c up until that point. Note it's not enough for a file to be simply
|
|---|
| 6391 | @c mentioned in the makefile to be listed in this variable, even if it
|
|---|
| 6392 | @c would match an implicit rule and become an ``implicit target''. The
|
|---|
| 6393 | @c file must appear as a target, on the left-hand side of a ``:'', to be
|
|---|
| 6394 | @c considered a target for the purposes of this variable.
|
|---|
| 6395 |
|
|---|
| 6396 | @vindex .FEATURES @r{(list of supported features)}
|
|---|
| 6397 | @item .FEATURES
|
|---|
| 6398 | Expands to a list of special features supported by this version of
|
|---|
| 6399 | @code{make}. Possible values include, but are not limited to:
|
|---|
| 6400 |
|
|---|
| 6401 | @table @samp
|
|---|
| 6402 |
|
|---|
| 6403 | @item archives
|
|---|
| 6404 | Supports @code{ar} (archive) files using special file name syntax.
|
|---|
| 6405 | @xref{Archives, ,Using @code{make} to Update Archive Files}.
|
|---|
| 6406 |
|
|---|
| 6407 | @item check-symlink
|
|---|
| 6408 | Supports the @code{-L} (@code{--check-symlink-times}) flag.
|
|---|
| 6409 | @xref{Options Summary, ,Summary of Options}.
|
|---|
| 6410 |
|
|---|
| 6411 | @item else-if
|
|---|
| 6412 | Supports ``else if'' non-nested conditionals. @xref{Conditional
|
|---|
| 6413 | Syntax, ,Syntax of Conditionals}.
|
|---|
| 6414 |
|
|---|
| 6415 | @item jobserver
|
|---|
| 6416 | Supports ``job server'' enhanced parallel builds. @xref{Parallel,
|
|---|
| 6417 | ,Parallel Execution}.
|
|---|
| 6418 |
|
|---|
| 6419 | @item oneshell
|
|---|
| 6420 | Supports the @code{.ONESHELL} special target. @xref{One Shell, ,Using
|
|---|
| 6421 | One Shell}.
|
|---|
| 6422 |
|
|---|
| 6423 | @item order-only
|
|---|
| 6424 | Supports order-only prerequisites. @xref{Prerequisite Types, ,Types
|
|---|
| 6425 | of Prerequisites}.
|
|---|
| 6426 |
|
|---|
| 6427 | @item second-expansion
|
|---|
| 6428 | Supports secondary expansion of prerequisite lists.
|
|---|
| 6429 |
|
|---|
| 6430 | @item shortest-stem
|
|---|
| 6431 | Uses the ``shortest stem'' method of choosing which pattern, of
|
|---|
| 6432 | multiple applicable options, will be used. @xref{Pattern Match, ,How
|
|---|
| 6433 | Patterns Match}.
|
|---|
| 6434 |
|
|---|
| 6435 | @item target-specific
|
|---|
| 6436 | Supports target-specific and pattern-specific variable assignments.
|
|---|
| 6437 | @xref{Target-specific, ,Target-specific Variable Values}.
|
|---|
| 6438 |
|
|---|
| 6439 | @item undefine
|
|---|
| 6440 | Supports the @code{undefine} directive. @xref{Undefine Directive}.
|
|---|
| 6441 |
|
|---|
| 6442 | @item guile
|
|---|
| 6443 | Has GNU Guile available as an embedded extension language.
|
|---|
| 6444 | @xref{Guile Integration, ,GNU Guile Integration}.
|
|---|
| 6445 |
|
|---|
| 6446 | @item load
|
|---|
| 6447 | Supports dynamically loadable objects for creating custom extensions.
|
|---|
| 6448 | @xref{Loading Objects, ,Loading Dynamic Objects}.
|
|---|
| 6449 | @end table
|
|---|
| 6450 |
|
|---|
| 6451 | @vindex .INCLUDE_DIRS @r{(list of include directories)}
|
|---|
| 6452 | @item .INCLUDE_DIRS
|
|---|
| 6453 | Expands to a list of directories that @code{make} searches for
|
|---|
| 6454 | included makefiles (@pxref{Include, , Including Other Makefiles}).
|
|---|
| 6455 |
|
|---|
| 6456 | @end table
|
|---|
| 6457 |
|
|---|
| 6458 | @node Conditionals, Functions, Using Variables, Top
|
|---|
| 6459 | @chapter Conditional Parts of Makefiles
|
|---|
| 6460 |
|
|---|
| 6461 | @cindex conditionals
|
|---|
| 6462 | A @dfn{conditional} directive causes part of a makefile to be obeyed
|
|---|
| 6463 | or ignored depending on the values of variables. Conditionals can
|
|---|
| 6464 | compare the value of one variable to another, or the value of a
|
|---|
| 6465 | variable to a constant string. Conditionals control what @code{make}
|
|---|
| 6466 | actually ``sees'' in the makefile, so they @emph{cannot} be used to
|
|---|
| 6467 | control recipes at the time of execution.@refill
|
|---|
| 6468 |
|
|---|
| 6469 | @menu
|
|---|
| 6470 | * Conditional Example:: Example of a conditional
|
|---|
| 6471 | * Conditional Syntax:: The syntax of conditionals.
|
|---|
| 6472 | * Testing Flags:: Conditionals that test flags.
|
|---|
| 6473 | @end menu
|
|---|
| 6474 |
|
|---|
| 6475 | @node Conditional Example, Conditional Syntax, Conditionals, Conditionals
|
|---|
| 6476 | @section Example of a Conditional
|
|---|
| 6477 |
|
|---|
| 6478 | The following example of a conditional tells @code{make} to use one
|
|---|
| 6479 | set of libraries if the @code{CC} variable is @samp{gcc}, and a
|
|---|
| 6480 | different set of libraries otherwise. It works by controlling which
|
|---|
| 6481 | of two recipe lines will be used for the rule. The result is that
|
|---|
| 6482 | @samp{CC=gcc} as an argument to @code{make} changes not only which
|
|---|
| 6483 | compiler is used but also which libraries are linked.
|
|---|
| 6484 |
|
|---|
| 6485 | @example
|
|---|
| 6486 | libs_for_gcc = -lgnu
|
|---|
| 6487 | normal_libs =
|
|---|
| 6488 |
|
|---|
| 6489 | foo: $(objects)
|
|---|
| 6490 | ifeq ($(CC),gcc)
|
|---|
| 6491 | $(CC) -o foo $(objects) $(libs_for_gcc)
|
|---|
| 6492 | else
|
|---|
| 6493 | $(CC) -o foo $(objects) $(normal_libs)
|
|---|
| 6494 | endif
|
|---|
| 6495 | @end example
|
|---|
| 6496 |
|
|---|
| 6497 | This conditional uses three directives: one @code{ifeq}, one @code{else}
|
|---|
| 6498 | and one @code{endif}.
|
|---|
| 6499 |
|
|---|
| 6500 | The @code{ifeq} directive begins the conditional, and specifies the
|
|---|
| 6501 | condition. It contains two arguments, separated by a comma and surrounded
|
|---|
| 6502 | by parentheses. Variable substitution is performed on both arguments and
|
|---|
| 6503 | then they are compared. The lines of the makefile following the
|
|---|
| 6504 | @code{ifeq} are obeyed if the two arguments match; otherwise they are
|
|---|
| 6505 | ignored.
|
|---|
| 6506 |
|
|---|
| 6507 | The @code{else} directive causes the following lines to be obeyed if the
|
|---|
| 6508 | previous conditional failed. In the example above, this means that the
|
|---|
| 6509 | second alternative linking command is used whenever the first alternative
|
|---|
| 6510 | is not used. It is optional to have an @code{else} in a conditional.
|
|---|
| 6511 |
|
|---|
| 6512 | The @code{endif} directive ends the conditional. Every conditional must
|
|---|
| 6513 | end with an @code{endif}. Unconditional makefile text follows.
|
|---|
| 6514 |
|
|---|
| 6515 | As this example illustrates, conditionals work at the textual level:
|
|---|
| 6516 | the lines of the conditional are treated as part of the makefile, or
|
|---|
| 6517 | ignored, according to the condition. This is why the larger syntactic
|
|---|
| 6518 | units of the makefile, such as rules, may cross the beginning or the
|
|---|
| 6519 | end of the conditional.
|
|---|
| 6520 |
|
|---|
| 6521 | When the variable @code{CC} has the value @samp{gcc}, the above example has
|
|---|
| 6522 | this effect:
|
|---|
| 6523 |
|
|---|
| 6524 | @example
|
|---|
| 6525 | foo: $(objects)
|
|---|
| 6526 | $(CC) -o foo $(objects) $(libs_for_gcc)
|
|---|
| 6527 | @end example
|
|---|
| 6528 |
|
|---|
| 6529 | @noindent
|
|---|
| 6530 | When the variable @code{CC} has any other value, the effect is this:
|
|---|
| 6531 |
|
|---|
| 6532 | @example
|
|---|
| 6533 | foo: $(objects)
|
|---|
| 6534 | $(CC) -o foo $(objects) $(normal_libs)
|
|---|
| 6535 | @end example
|
|---|
| 6536 |
|
|---|
| 6537 | Equivalent results can be obtained in another way by conditionalizing a
|
|---|
| 6538 | variable assignment and then using the variable unconditionally:
|
|---|
| 6539 |
|
|---|
| 6540 | @example
|
|---|
| 6541 | libs_for_gcc = -lgnu
|
|---|
| 6542 | normal_libs =
|
|---|
| 6543 |
|
|---|
| 6544 | ifeq ($(CC),gcc)
|
|---|
| 6545 | libs=$(libs_for_gcc)
|
|---|
| 6546 | else
|
|---|
| 6547 | libs=$(normal_libs)
|
|---|
| 6548 | endif
|
|---|
| 6549 |
|
|---|
| 6550 | foo: $(objects)
|
|---|
| 6551 | $(CC) -o foo $(objects) $(libs)
|
|---|
| 6552 | @end example
|
|---|
| 6553 |
|
|---|
| 6554 | @node Conditional Syntax, Testing Flags, Conditional Example, Conditionals
|
|---|
| 6555 | @section Syntax of Conditionals
|
|---|
| 6556 | @findex ifdef
|
|---|
| 6557 | @findex ifeq
|
|---|
| 6558 | @findex ifndef
|
|---|
| 6559 | @findex ifneq
|
|---|
| 6560 | @findex else
|
|---|
| 6561 | @findex endif
|
|---|
| 6562 |
|
|---|
| 6563 | The syntax of a simple conditional with no @code{else} is as follows:
|
|---|
| 6564 |
|
|---|
| 6565 | @example
|
|---|
| 6566 | @var{conditional-directive}
|
|---|
| 6567 | @var{text-if-true}
|
|---|
| 6568 | endif
|
|---|
| 6569 | @end example
|
|---|
| 6570 |
|
|---|
| 6571 | @noindent
|
|---|
| 6572 | The @var{text-if-true} may be any lines of text, to be considered as part
|
|---|
| 6573 | of the makefile if the condition is true. If the condition is false, no
|
|---|
| 6574 | text is used instead.
|
|---|
| 6575 |
|
|---|
| 6576 | The syntax of a complex conditional is as follows:
|
|---|
| 6577 |
|
|---|
| 6578 | @example
|
|---|
| 6579 | @var{conditional-directive}
|
|---|
| 6580 | @var{text-if-true}
|
|---|
| 6581 | else
|
|---|
| 6582 | @var{text-if-false}
|
|---|
| 6583 | endif
|
|---|
| 6584 | @end example
|
|---|
| 6585 |
|
|---|
| 6586 | or:
|
|---|
| 6587 |
|
|---|
| 6588 | @example
|
|---|
| 6589 | @var{conditional-directive-one}
|
|---|
| 6590 | @var{text-if-one-is-true}
|
|---|
| 6591 | else @var{conditional-directive-two}
|
|---|
| 6592 | @var{text-if-two-is-true}
|
|---|
| 6593 | else
|
|---|
| 6594 | @var{text-if-one-and-two-are-false}
|
|---|
| 6595 | endif
|
|---|
| 6596 | @end example
|
|---|
| 6597 |
|
|---|
| 6598 | @noindent
|
|---|
| 6599 | There can be as many ``@code{else} @var{conditional-directive}''
|
|---|
| 6600 | clauses as necessary. Once a given condition is true,
|
|---|
| 6601 | @var{text-if-true} is used and no other clause is used; if no
|
|---|
| 6602 | condition is true then @var{text-if-false} is used. The
|
|---|
| 6603 | @var{text-if-true} and @var{text-if-false} can be any number of lines
|
|---|
| 6604 | of text.
|
|---|
| 6605 |
|
|---|
| 6606 | The syntax of the @var{conditional-directive} is the same whether the
|
|---|
| 6607 | conditional is simple or complex; after an @code{else} or not. There
|
|---|
| 6608 | are four different directives that test different conditions. Here is
|
|---|
| 6609 | a table of them:
|
|---|
| 6610 |
|
|---|
| 6611 | @table @code
|
|---|
| 6612 | @item ifeq (@var{arg1}, @var{arg2})
|
|---|
| 6613 | @itemx ifeq '@var{arg1}' '@var{arg2}'
|
|---|
| 6614 | @itemx ifeq "@var{arg1}" "@var{arg2}"
|
|---|
| 6615 | @itemx ifeq "@var{arg1}" '@var{arg2}'
|
|---|
| 6616 | @itemx ifeq '@var{arg1}' "@var{arg2}"
|
|---|
| 6617 | Expand all variable references in @var{arg1} and @var{arg2} and
|
|---|
| 6618 | compare them. If they are identical, the @var{text-if-true} is
|
|---|
| 6619 | effective; otherwise, the @var{text-if-false}, if any, is effective.
|
|---|
| 6620 |
|
|---|
| 6621 | Often you want to test if a variable has a non-empty value. When the
|
|---|
| 6622 | value results from complex expansions of variables and functions,
|
|---|
| 6623 | expansions you would consider empty may actually contain whitespace
|
|---|
| 6624 | characters and thus are not seen as empty. However, you can use the
|
|---|
| 6625 | @code{strip} function (@pxref{Text Functions}) to avoid interpreting
|
|---|
| 6626 | whitespace as a non-empty value. For example:
|
|---|
| 6627 |
|
|---|
| 6628 | @example
|
|---|
| 6629 | @group
|
|---|
| 6630 | ifeq ($(strip $(foo)),)
|
|---|
| 6631 | @var{text-if-empty}
|
|---|
| 6632 | endif
|
|---|
| 6633 | @end group
|
|---|
| 6634 | @end example
|
|---|
| 6635 |
|
|---|
| 6636 | @noindent
|
|---|
| 6637 | will evaluate @var{text-if-empty} even if the expansion of
|
|---|
| 6638 | @code{$(foo)} contains whitespace characters.
|
|---|
| 6639 |
|
|---|
| 6640 | @item ifneq (@var{arg1}, @var{arg2})
|
|---|
| 6641 | @itemx ifneq '@var{arg1}' '@var{arg2}'
|
|---|
| 6642 | @itemx ifneq "@var{arg1}" "@var{arg2}"
|
|---|
| 6643 | @itemx ifneq "@var{arg1}" '@var{arg2}'
|
|---|
| 6644 | @itemx ifneq '@var{arg1}' "@var{arg2}"
|
|---|
| 6645 | Expand all variable references in @var{arg1} and @var{arg2} and
|
|---|
| 6646 | compare them. If they are different, the @var{text-if-true} is
|
|---|
| 6647 | effective; otherwise, the @var{text-if-false}, if any, is effective.
|
|---|
| 6648 |
|
|---|
| 6649 | @item ifdef @var{variable-name}
|
|---|
| 6650 | The @code{ifdef} form takes the @emph{name} of a variable as its
|
|---|
| 6651 | argument, not a reference to a variable. If the value of that
|
|---|
| 6652 | variable has a non-empty value, the @var{text-if-true} is effective;
|
|---|
| 6653 | otherwise, the @var{text-if-false}, if any, is effective. Variables
|
|---|
| 6654 | that have never been defined have an empty value. The text
|
|---|
| 6655 | @var{variable-name} is expanded, so it could be a variable or function
|
|---|
| 6656 | that expands to the name of a variable. For example:
|
|---|
| 6657 |
|
|---|
| 6658 | @example
|
|---|
| 6659 | bar = true
|
|---|
| 6660 | foo = bar
|
|---|
| 6661 | ifdef $(foo)
|
|---|
| 6662 | frobozz = yes
|
|---|
| 6663 | endif
|
|---|
| 6664 | @end example
|
|---|
| 6665 |
|
|---|
| 6666 | The variable reference @code{$(foo)} is expanded, yielding @code{bar},
|
|---|
| 6667 | which is considered to be the name of a variable. The variable
|
|---|
| 6668 | @code{bar} is not expanded, but its value is examined to determine if
|
|---|
| 6669 | it is non-empty.
|
|---|
| 6670 |
|
|---|
| 6671 | Note that @code{ifdef} only tests whether a variable has a value. It
|
|---|
| 6672 | does not expand the variable to see if that value is nonempty.
|
|---|
| 6673 | Consequently, tests using @code{ifdef} return true for all definitions
|
|---|
| 6674 | except those like @code{foo =}. To test for an empty value, use
|
|---|
| 6675 | @w{@code{ifeq ($(foo),)}}. For example,
|
|---|
| 6676 |
|
|---|
| 6677 | @example
|
|---|
| 6678 | bar =
|
|---|
| 6679 | foo = $(bar)
|
|---|
| 6680 | ifdef foo
|
|---|
| 6681 | frobozz = yes
|
|---|
| 6682 | else
|
|---|
| 6683 | frobozz = no
|
|---|
| 6684 | endif
|
|---|
| 6685 | @end example
|
|---|
| 6686 |
|
|---|
| 6687 | @noindent
|
|---|
| 6688 | sets @samp{frobozz} to @samp{yes}, while:
|
|---|
| 6689 |
|
|---|
| 6690 | @example
|
|---|
| 6691 | foo =
|
|---|
| 6692 | ifdef foo
|
|---|
| 6693 | frobozz = yes
|
|---|
| 6694 | else
|
|---|
| 6695 | frobozz = no
|
|---|
| 6696 | endif
|
|---|
| 6697 | @end example
|
|---|
| 6698 |
|
|---|
| 6699 | @noindent
|
|---|
| 6700 | sets @samp{frobozz} to @samp{no}.
|
|---|
| 6701 |
|
|---|
| 6702 | @item ifndef @var{variable-name}
|
|---|
| 6703 | If the variable @var{variable-name} has an empty value, the
|
|---|
| 6704 | @var{text-if-true} is effective; otherwise, the @var{text-if-false},
|
|---|
| 6705 | if any, is effective. The rules for expansion and testing of
|
|---|
| 6706 | @var{variable-name} are identical to the @code{ifdef} directive.
|
|---|
| 6707 | @end table
|
|---|
| 6708 |
|
|---|
| 6709 | Extra spaces are allowed and ignored at the beginning of the
|
|---|
| 6710 | conditional directive line, but a tab is not allowed. (If the line
|
|---|
| 6711 | begins with a tab, it will be considered part of a recipe for a rule.)
|
|---|
| 6712 | Aside from this, extra spaces or tabs may be inserted with no effect
|
|---|
| 6713 | anywhere except within the directive name or within an argument. A
|
|---|
| 6714 | comment starting with @samp{#} may appear at the end of the line.
|
|---|
| 6715 |
|
|---|
| 6716 | The other two directives that play a part in a conditional are @code{else}
|
|---|
| 6717 | and @code{endif}. Each of these directives is written as one word, with no
|
|---|
| 6718 | arguments. Extra spaces are allowed and ignored at the beginning of the
|
|---|
| 6719 | line, and spaces or tabs at the end. A comment starting with @samp{#} may
|
|---|
| 6720 | appear at the end of the line.
|
|---|
| 6721 |
|
|---|
| 6722 | Conditionals affect which lines of the makefile @code{make} uses. If
|
|---|
| 6723 | the condition is true, @code{make} reads the lines of the
|
|---|
| 6724 | @var{text-if-true} as part of the makefile; if the condition is false,
|
|---|
| 6725 | @code{make} ignores those lines completely. It follows that syntactic
|
|---|
| 6726 | units of the makefile, such as rules, may safely be split across the
|
|---|
| 6727 | beginning or the end of the conditional.@refill
|
|---|
| 6728 |
|
|---|
| 6729 | @code{make} evaluates conditionals when it reads a makefile.
|
|---|
| 6730 | Consequently, you cannot use automatic variables in the tests of
|
|---|
| 6731 | conditionals because they are not defined until recipes are run
|
|---|
| 6732 | (@pxref{Automatic Variables}).
|
|---|
| 6733 |
|
|---|
| 6734 | To prevent intolerable confusion, it is not permitted to start a
|
|---|
| 6735 | conditional in one makefile and end it in another. However, you may
|
|---|
| 6736 | write an @code{include} directive within a conditional, provided you do
|
|---|
| 6737 | not attempt to terminate the conditional inside the included file.
|
|---|
| 6738 |
|
|---|
| 6739 | @node Testing Flags, , Conditional Syntax, Conditionals
|
|---|
| 6740 | @section Conditionals that Test Flags
|
|---|
| 6741 |
|
|---|
| 6742 | You can write a conditional that tests @code{make} command flags such as
|
|---|
| 6743 | @samp{-t} by using the variable @code{MAKEFLAGS} together with the
|
|---|
| 6744 | @code{findstring} function
|
|---|
| 6745 | (@pxref{Text Functions, , Functions for String Substitution and Analysis}).
|
|---|
| 6746 | This is useful when @code{touch} is not enough to make a file appear up
|
|---|
| 6747 | to date.
|
|---|
| 6748 |
|
|---|
| 6749 | The @code{findstring} function determines whether one string appears as a
|
|---|
| 6750 | substring of another. If you want to test for the @samp{-t} flag,
|
|---|
| 6751 | use @samp{t} as the first string and the value of @code{MAKEFLAGS} as
|
|---|
| 6752 | the other.
|
|---|
| 6753 |
|
|---|
| 6754 | For example, here is how to arrange to use @samp{ranlib -t} to finish
|
|---|
| 6755 | marking an archive file up to date:
|
|---|
| 6756 |
|
|---|
| 6757 | @example
|
|---|
| 6758 | archive.a: @dots{}
|
|---|
| 6759 | ifneq (,$(findstring t,$(MAKEFLAGS)))
|
|---|
| 6760 | +touch archive.a
|
|---|
| 6761 | +ranlib -t archive.a
|
|---|
| 6762 | else
|
|---|
| 6763 | ranlib archive.a
|
|---|
| 6764 | endif
|
|---|
| 6765 | @end example
|
|---|
| 6766 |
|
|---|
| 6767 | @noindent
|
|---|
| 6768 | The @samp{+} prefix marks those recipe lines as ``recursive'' so that
|
|---|
| 6769 | they will be executed despite use of the @samp{-t} flag.
|
|---|
| 6770 | @xref{Recursion, ,Recursive Use of @code{make}}.
|
|---|
| 6771 |
|
|---|
| 6772 | @node Functions, Running, Conditionals, Top
|
|---|
| 6773 | @chapter Functions for Transforming Text
|
|---|
| 6774 | @cindex functions
|
|---|
| 6775 |
|
|---|
| 6776 | @dfn{Functions} allow you to do text processing in the makefile to
|
|---|
| 6777 | compute the files to operate on or the commands to use in recipes.
|
|---|
| 6778 | You use a function in a @dfn{function call}, where you give the name
|
|---|
| 6779 | of the function and some text (the @dfn{arguments}) for the function
|
|---|
| 6780 | to operate on. The result of the function's processing is substituted
|
|---|
| 6781 | into the makefile at the point of the call, just as a variable might
|
|---|
| 6782 | be substituted.
|
|---|
| 6783 |
|
|---|
| 6784 | @menu
|
|---|
| 6785 | * Syntax of Functions:: How to write a function call.
|
|---|
| 6786 | * Text Functions:: General-purpose text manipulation functions.
|
|---|
| 6787 | * File Name Functions:: Functions for manipulating file names.
|
|---|
| 6788 | * Conditional Functions:: Functions that implement conditions.
|
|---|
| 6789 | * Foreach Function:: Repeat some text with controlled variation.
|
|---|
| 6790 | * File Function:: Write text to a file.
|
|---|
| 6791 | * Call Function:: Expand a user-defined function.
|
|---|
| 6792 | * Value Function:: Return the un-expanded value of a variable.
|
|---|
| 6793 | * Eval Function:: Evaluate the arguments as makefile syntax.
|
|---|
| 6794 | * Origin Function:: Find where a variable got its value.
|
|---|
| 6795 | * Flavor Function:: Find out the flavor of a variable.
|
|---|
| 6796 | * Make Control Functions:: Functions that control how make runs.
|
|---|
| 6797 | * Shell Function:: Substitute the output of a shell command.
|
|---|
| 6798 | * Guile Function:: Use GNU Guile embedded scripting language.
|
|---|
| 6799 | @end menu
|
|---|
| 6800 |
|
|---|
| 6801 | @node Syntax of Functions, Text Functions, Functions, Functions
|
|---|
| 6802 | @section Function Call Syntax
|
|---|
| 6803 | @cindex @code{$}, in function call
|
|---|
| 6804 | @cindex dollar sign (@code{$}), in function call
|
|---|
| 6805 | @cindex arguments of functions
|
|---|
| 6806 | @cindex functions, syntax of
|
|---|
| 6807 |
|
|---|
| 6808 | A function call resembles a variable reference. It can appear
|
|---|
| 6809 | anywhere a variable reference can appear, and it is expanded using the
|
|---|
| 6810 | same rules as variable references. A function call looks like this:
|
|---|
| 6811 |
|
|---|
| 6812 | @example
|
|---|
| 6813 | $(@var{function} @var{arguments})
|
|---|
| 6814 | @end example
|
|---|
| 6815 |
|
|---|
| 6816 | @noindent
|
|---|
| 6817 | or like this:
|
|---|
| 6818 |
|
|---|
| 6819 | @example
|
|---|
| 6820 | $@{@var{function} @var{arguments}@}
|
|---|
| 6821 | @end example
|
|---|
| 6822 |
|
|---|
| 6823 | Here @var{function} is a function name; one of a short list of names
|
|---|
| 6824 | that are part of @code{make}. You can also essentially create your own
|
|---|
| 6825 | functions by using the @code{call} built-in function.
|
|---|
| 6826 |
|
|---|
| 6827 | The @var{arguments} are the arguments of the function. They are
|
|---|
| 6828 | separated from the function name by one or more spaces or tabs, and if
|
|---|
| 6829 | there is more than one argument, then they are separated by commas.
|
|---|
| 6830 | Such whitespace and commas are not part of an argument's value. The
|
|---|
| 6831 | delimiters which you use to surround the function call, whether
|
|---|
| 6832 | parentheses or braces, can appear in an argument only in matching pairs;
|
|---|
| 6833 | the other kind of delimiters may appear singly. If the arguments
|
|---|
| 6834 | themselves contain other function calls or variable references, it is
|
|---|
| 6835 | wisest to use the same kind of delimiters for all the references; write
|
|---|
| 6836 | @w{@samp{$(subst a,b,$(x))}}, not @w{@samp{$(subst a,b,$@{x@})}}. This
|
|---|
| 6837 | is because it is clearer, and because only one type of delimiter is
|
|---|
| 6838 | matched to find the end of the reference.
|
|---|
| 6839 |
|
|---|
| 6840 | The text written for each argument is processed by substitution of
|
|---|
| 6841 | variables and function calls to produce the argument value, which
|
|---|
| 6842 | is the text on which the function acts. The substitution is done in the
|
|---|
| 6843 | order in which the arguments appear.
|
|---|
| 6844 |
|
|---|
| 6845 | Commas and unmatched parentheses or braces cannot appear in the text of an
|
|---|
| 6846 | argument as written; leading spaces cannot appear in the text of the first
|
|---|
| 6847 | argument as written. These characters can be put into the argument value
|
|---|
| 6848 | by variable substitution. First define variables @code{comma} and
|
|---|
| 6849 | @code{space} whose values are isolated comma and space characters, then
|
|---|
| 6850 | substitute these variables where such characters are wanted, like this:
|
|---|
| 6851 |
|
|---|
| 6852 | @example
|
|---|
| 6853 | @group
|
|---|
| 6854 | comma:= ,
|
|---|
| 6855 | empty:=
|
|---|
| 6856 | space:= $(empty) $(empty)
|
|---|
| 6857 | foo:= a b c
|
|---|
| 6858 | bar:= $(subst $(space),$(comma),$(foo))
|
|---|
| 6859 | # @r{bar is now `a,b,c'.}
|
|---|
| 6860 | @end group
|
|---|
| 6861 | @end example
|
|---|
| 6862 |
|
|---|
| 6863 | @noindent
|
|---|
| 6864 | Here the @code{subst} function replaces each space with a comma, through
|
|---|
| 6865 | the value of @code{foo}, and substitutes the result.
|
|---|
| 6866 |
|
|---|
| 6867 | @node Text Functions, File Name Functions, Syntax of Functions, Functions
|
|---|
| 6868 | @section Functions for String Substitution and Analysis
|
|---|
| 6869 | @cindex functions, for text
|
|---|
| 6870 |
|
|---|
| 6871 | Here are some functions that operate on strings:
|
|---|
| 6872 |
|
|---|
| 6873 | @table @code
|
|---|
| 6874 | @item $(subst @var{from},@var{to},@var{text})
|
|---|
| 6875 | @findex subst
|
|---|
| 6876 | Performs a textual replacement on the text @var{text}: each occurrence
|
|---|
| 6877 | of @var{from} is replaced by @var{to}. The result is substituted for
|
|---|
| 6878 | the function call. For example,
|
|---|
| 6879 |
|
|---|
| 6880 | @example
|
|---|
| 6881 | $(subst ee,EE,feet on the street)
|
|---|
| 6882 | @end example
|
|---|
| 6883 |
|
|---|
| 6884 | substitutes the string @samp{fEEt on the strEEt}.
|
|---|
| 6885 |
|
|---|
| 6886 | @item $(patsubst @var{pattern},@var{replacement},@var{text})
|
|---|
| 6887 | @findex patsubst
|
|---|
| 6888 | Finds whitespace-separated words in @var{text} that match
|
|---|
| 6889 | @var{pattern} and replaces them with @var{replacement}. Here
|
|---|
| 6890 | @var{pattern} may contain a @samp{%} which acts as a wildcard,
|
|---|
| 6891 | matching any number of any characters within a word. If
|
|---|
| 6892 | @var{replacement} also contains a @samp{%}, the @samp{%} is replaced
|
|---|
| 6893 | by the text that matched the @samp{%} in @var{pattern}. Only the first
|
|---|
| 6894 | @samp{%} in the @var{pattern} and @var{replacement} is treated this
|
|---|
| 6895 | way; any subsequent @samp{%} is unchanged.@refill
|
|---|
| 6896 |
|
|---|
| 6897 | @cindex @code{%}, quoting in @code{patsubst}
|
|---|
| 6898 | @cindex @code{%}, quoting with @code{\} (backslash)
|
|---|
| 6899 | @cindex @code{\} (backslash), to quote @code{%}
|
|---|
| 6900 | @cindex backslash (@code{\}), to quote @code{%}
|
|---|
| 6901 | @cindex quoting @code{%}, in @code{patsubst}
|
|---|
| 6902 | @samp{%} characters in @code{patsubst} function invocations can be
|
|---|
| 6903 | quoted with preceding backslashes (@samp{\}). Backslashes that would
|
|---|
| 6904 | otherwise quote @samp{%} characters can be quoted with more backslashes.
|
|---|
| 6905 | Backslashes that quote @samp{%} characters or other backslashes are
|
|---|
| 6906 | removed from the pattern before it is compared file names or has a stem
|
|---|
| 6907 | substituted into it. Backslashes that are not in danger of quoting
|
|---|
| 6908 | @samp{%} characters go unmolested. For example, the pattern
|
|---|
| 6909 | @file{the\%weird\\%pattern\\} has @samp{the%weird\} preceding the
|
|---|
| 6910 | operative @samp{%} character, and @samp{pattern\\} following it. The
|
|---|
| 6911 | final two backslashes are left alone because they cannot affect any
|
|---|
| 6912 | @samp{%} character.@refill
|
|---|
| 6913 |
|
|---|
| 6914 | Whitespace between words is folded into single space characters;
|
|---|
| 6915 | leading and trailing whitespace is discarded.
|
|---|
| 6916 |
|
|---|
| 6917 | For example,
|
|---|
| 6918 |
|
|---|
| 6919 | @example
|
|---|
| 6920 | $(patsubst %.c,%.o,x.c.c bar.c)
|
|---|
| 6921 | @end example
|
|---|
| 6922 |
|
|---|
| 6923 | @noindent
|
|---|
| 6924 | produces the value @samp{x.c.o bar.o}.
|
|---|
| 6925 |
|
|---|
| 6926 | Substitution references (@pxref{Substitution Refs, ,Substitution
|
|---|
| 6927 | References}) are a simpler way to get the effect of the @code{patsubst}
|
|---|
| 6928 | function:
|
|---|
| 6929 |
|
|---|
| 6930 | @example
|
|---|
| 6931 | $(@var{var}:@var{pattern}=@var{replacement})
|
|---|
| 6932 | @end example
|
|---|
| 6933 |
|
|---|
| 6934 | @noindent
|
|---|
| 6935 | is equivalent to
|
|---|
| 6936 |
|
|---|
| 6937 | @example
|
|---|
| 6938 | $(patsubst @var{pattern},@var{replacement},$(@var{var}))
|
|---|
| 6939 | @end example
|
|---|
| 6940 |
|
|---|
| 6941 | The second shorthand simplifies one of the most common uses of
|
|---|
| 6942 | @code{patsubst}: replacing the suffix at the end of file names.
|
|---|
| 6943 |
|
|---|
| 6944 | @example
|
|---|
| 6945 | $(@var{var}:@var{suffix}=@var{replacement})
|
|---|
| 6946 | @end example
|
|---|
| 6947 |
|
|---|
| 6948 | @noindent
|
|---|
| 6949 | is equivalent to
|
|---|
| 6950 |
|
|---|
| 6951 | @example
|
|---|
| 6952 | $(patsubst %@var{suffix},%@var{replacement},$(@var{var}))
|
|---|
| 6953 | @end example
|
|---|
| 6954 |
|
|---|
| 6955 | @noindent
|
|---|
| 6956 | For example, you might have a list of object files:
|
|---|
| 6957 |
|
|---|
| 6958 | @example
|
|---|
| 6959 | objects = foo.o bar.o baz.o
|
|---|
| 6960 | @end example
|
|---|
| 6961 |
|
|---|
| 6962 | @noindent
|
|---|
| 6963 | To get the list of corresponding source files, you could simply write:
|
|---|
| 6964 |
|
|---|
| 6965 | @example
|
|---|
| 6966 | $(objects:.o=.c)
|
|---|
| 6967 | @end example
|
|---|
| 6968 |
|
|---|
| 6969 | @noindent
|
|---|
| 6970 | instead of using the general form:
|
|---|
| 6971 |
|
|---|
| 6972 | @example
|
|---|
| 6973 | $(patsubst %.o,%.c,$(objects))
|
|---|
| 6974 | @end example
|
|---|
| 6975 |
|
|---|
| 6976 | @item $(strip @var{string})
|
|---|
| 6977 | @cindex stripping whitespace
|
|---|
| 6978 | @cindex whitespace, stripping
|
|---|
| 6979 | @cindex spaces, stripping
|
|---|
| 6980 | @findex strip
|
|---|
| 6981 | Removes leading and trailing whitespace from @var{string} and replaces
|
|---|
| 6982 | each internal sequence of one or more whitespace characters with a
|
|---|
| 6983 | single space. Thus, @samp{$(strip a b c )} results in @w{@samp{a b c}}.
|
|---|
| 6984 |
|
|---|
| 6985 | The function @code{strip} can be very useful when used in conjunction
|
|---|
| 6986 | with conditionals. When comparing something with the empty string
|
|---|
| 6987 | @samp{} using @code{ifeq} or @code{ifneq}, you usually want a string of
|
|---|
| 6988 | just whitespace to match the empty string (@pxref{Conditionals}).
|
|---|
| 6989 |
|
|---|
| 6990 | Thus, the following may fail to have the desired results:
|
|---|
| 6991 |
|
|---|
| 6992 | @example
|
|---|
| 6993 | .PHONY: all
|
|---|
| 6994 | ifneq "$(needs_made)" ""
|
|---|
| 6995 | all: $(needs_made)
|
|---|
| 6996 | else
|
|---|
| 6997 | all:;@@echo 'Nothing to make!'
|
|---|
| 6998 | endif
|
|---|
| 6999 | @end example
|
|---|
| 7000 |
|
|---|
| 7001 | @noindent
|
|---|
| 7002 | Replacing the variable reference @w{@samp{$(needs_made)}} with the
|
|---|
| 7003 | function call @w{@samp{$(strip $(needs_made))}} in the @code{ifneq}
|
|---|
| 7004 | directive would make it more robust.@refill
|
|---|
| 7005 |
|
|---|
| 7006 | @item $(findstring @var{find},@var{in})
|
|---|
| 7007 | @findex findstring
|
|---|
| 7008 | @cindex searching for strings
|
|---|
| 7009 | @cindex finding strings
|
|---|
| 7010 | @cindex strings, searching for
|
|---|
| 7011 | Searches @var{in} for an occurrence of @var{find}. If it occurs, the
|
|---|
| 7012 | value is @var{find}; otherwise, the value is empty. You can use this
|
|---|
| 7013 | function in a conditional to test for the presence of a specific
|
|---|
| 7014 | substring in a given string. Thus, the two examples,
|
|---|
| 7015 |
|
|---|
| 7016 | @example
|
|---|
| 7017 | $(findstring a,a b c)
|
|---|
| 7018 | $(findstring a,b c)
|
|---|
| 7019 | @end example
|
|---|
| 7020 |
|
|---|
| 7021 | @noindent
|
|---|
| 7022 | produce the values @samp{a} and @samp{} (the empty string),
|
|---|
| 7023 | respectively. @xref{Testing Flags}, for a practical application of
|
|---|
| 7024 | @code{findstring}.@refill
|
|---|
| 7025 |
|
|---|
| 7026 | @need 750
|
|---|
| 7027 | @findex filter
|
|---|
| 7028 | @cindex filtering words
|
|---|
| 7029 | @cindex words, filtering
|
|---|
| 7030 | @item $(filter @var{pattern}@dots{},@var{text})
|
|---|
| 7031 | Returns all whitespace-separated words in @var{text} that @emph{do} match
|
|---|
| 7032 | any of the @var{pattern} words, removing any words that @emph{do not}
|
|---|
| 7033 | match. The patterns are written using @samp{%}, just like the patterns
|
|---|
| 7034 | used in the @code{patsubst} function above.@refill
|
|---|
| 7035 |
|
|---|
| 7036 | The @code{filter} function can be used to separate out different types
|
|---|
| 7037 | of strings (such as file names) in a variable. For example:
|
|---|
| 7038 |
|
|---|
| 7039 | @example
|
|---|
| 7040 | sources := foo.c bar.c baz.s ugh.h
|
|---|
| 7041 | foo: $(sources)
|
|---|
| 7042 | cc $(filter %.c %.s,$(sources)) -o foo
|
|---|
| 7043 | @end example
|
|---|
| 7044 |
|
|---|
| 7045 | @noindent
|
|---|
| 7046 | says that @file{foo} depends of @file{foo.c}, @file{bar.c},
|
|---|
| 7047 | @file{baz.s} and @file{ugh.h} but only @file{foo.c}, @file{bar.c} and
|
|---|
| 7048 | @file{baz.s} should be specified in the command to the
|
|---|
| 7049 | compiler.@refill
|
|---|
| 7050 |
|
|---|
| 7051 | @item $(filter-out @var{pattern}@dots{},@var{text})
|
|---|
| 7052 | @findex filter-out
|
|---|
| 7053 | @cindex filtering out words
|
|---|
| 7054 | @cindex words, filtering out
|
|---|
| 7055 | Returns all whitespace-separated words in @var{text} that @emph{do not}
|
|---|
| 7056 | match any of the @var{pattern} words, removing the words that @emph{do}
|
|---|
| 7057 | match one or more. This is the exact opposite of the @code{filter}
|
|---|
| 7058 | function.@refill
|
|---|
| 7059 |
|
|---|
| 7060 | For example, given:
|
|---|
| 7061 |
|
|---|
| 7062 | @example
|
|---|
| 7063 | @group
|
|---|
| 7064 | objects=main1.o foo.o main2.o bar.o
|
|---|
| 7065 | mains=main1.o main2.o
|
|---|
| 7066 | @end group
|
|---|
| 7067 | @end example
|
|---|
| 7068 |
|
|---|
| 7069 | @noindent
|
|---|
| 7070 | the following generates a list which contains all the object files not
|
|---|
| 7071 | in @samp{mains}:
|
|---|
| 7072 |
|
|---|
| 7073 | @example
|
|---|
| 7074 | $(filter-out $(mains),$(objects))
|
|---|
| 7075 | @end example
|
|---|
| 7076 |
|
|---|
| 7077 | @need 1500
|
|---|
| 7078 | @findex sort
|
|---|
| 7079 | @cindex sorting words
|
|---|
| 7080 | @item $(sort @var{list})
|
|---|
| 7081 | Sorts the words of @var{list} in lexical order, removing duplicate
|
|---|
| 7082 | words. The output is a list of words separated by single spaces.
|
|---|
| 7083 | Thus,
|
|---|
| 7084 |
|
|---|
| 7085 | @example
|
|---|
| 7086 | $(sort foo bar lose)
|
|---|
| 7087 | @end example
|
|---|
| 7088 |
|
|---|
| 7089 | @noindent
|
|---|
| 7090 | returns the value @samp{bar foo lose}.
|
|---|
| 7091 |
|
|---|
| 7092 | @cindex removing duplicate words
|
|---|
| 7093 | @cindex duplicate words, removing
|
|---|
| 7094 | @cindex words, removing duplicates
|
|---|
| 7095 | Incidentally, since @code{sort} removes duplicate words, you can use
|
|---|
| 7096 | it for this purpose even if you don't care about the sort order.
|
|---|
| 7097 |
|
|---|
| 7098 | @item $(word @var{n},@var{text})
|
|---|
| 7099 | @findex word
|
|---|
| 7100 | @cindex word, selecting a
|
|---|
| 7101 | @cindex selecting a word
|
|---|
| 7102 | Returns the @var{n}th word of @var{text}. The legitimate values of
|
|---|
| 7103 | @var{n} start from 1. If @var{n} is bigger than the number of words
|
|---|
| 7104 | in @var{text}, the value is empty. For example,
|
|---|
| 7105 |
|
|---|
| 7106 | @example
|
|---|
| 7107 | $(word 2, foo bar baz)
|
|---|
| 7108 | @end example
|
|---|
| 7109 |
|
|---|
| 7110 | @noindent
|
|---|
| 7111 | returns @samp{bar}.
|
|---|
| 7112 |
|
|---|
| 7113 | @item $(wordlist @var{s},@var{e},@var{text})
|
|---|
| 7114 | @findex wordlist
|
|---|
| 7115 | @cindex words, selecting lists of
|
|---|
| 7116 | @cindex selecting word lists
|
|---|
| 7117 | Returns the list of words in @var{text} starting with word @var{s} and
|
|---|
| 7118 | ending with word @var{e} (inclusive). The legitimate values of @var{s}
|
|---|
| 7119 | start from 1; @var{e} may start from 0. If @var{s} is bigger than the
|
|---|
| 7120 | number of words in @var{text}, the value is empty. If @var{e} is
|
|---|
| 7121 | bigger than the number of words in @var{text}, words up to the end of
|
|---|
| 7122 | @var{text} are returned. If @var{s} is greater than @var{e}, nothing
|
|---|
| 7123 | is returned. For example,
|
|---|
| 7124 |
|
|---|
| 7125 | @example
|
|---|
| 7126 | $(wordlist 2, 3, foo bar baz)
|
|---|
| 7127 | @end example
|
|---|
| 7128 |
|
|---|
| 7129 | @noindent
|
|---|
| 7130 | returns @samp{bar baz}.
|
|---|
| 7131 |
|
|---|
| 7132 | @c Following item phrased to prevent overfull hbox. --RJC 17 Jul 92
|
|---|
| 7133 | @item $(words @var{text})
|
|---|
| 7134 | @findex words
|
|---|
| 7135 | @cindex words, finding number
|
|---|
| 7136 | Returns the number of words in @var{text}.
|
|---|
| 7137 | Thus, the last word of @var{text} is
|
|---|
| 7138 | @w{@code{$(word $(words @var{text}),@var{text})}}.@refill
|
|---|
| 7139 |
|
|---|
| 7140 | @item $(firstword @var{names}@dots{})
|
|---|
| 7141 | @findex firstword
|
|---|
| 7142 | @cindex words, extracting first
|
|---|
| 7143 | The argument @var{names} is regarded as a series of names, separated
|
|---|
| 7144 | by whitespace. The value is the first name in the series. The rest
|
|---|
| 7145 | of the names are ignored.
|
|---|
| 7146 |
|
|---|
| 7147 | For example,
|
|---|
| 7148 |
|
|---|
| 7149 | @example
|
|---|
| 7150 | $(firstword foo bar)
|
|---|
| 7151 | @end example
|
|---|
| 7152 |
|
|---|
| 7153 | @noindent
|
|---|
| 7154 | produces the result @samp{foo}. Although @code{$(firstword
|
|---|
| 7155 | @var{text})} is the same as @code{$(word 1,@var{text})}, the
|
|---|
| 7156 | @code{firstword} function is retained for its simplicity.@refill
|
|---|
| 7157 |
|
|---|
| 7158 |
|
|---|
| 7159 | @item $(lastword @var{names}@dots{})
|
|---|
| 7160 | @findex lastword
|
|---|
| 7161 | @cindex words, extracting last
|
|---|
| 7162 | The argument @var{names} is regarded as a series of names, separated
|
|---|
| 7163 | by whitespace. The value is the last name in the series.
|
|---|
| 7164 |
|
|---|
| 7165 | For example,
|
|---|
| 7166 |
|
|---|
| 7167 | @example
|
|---|
| 7168 | $(lastword foo bar)
|
|---|
| 7169 | @end example
|
|---|
| 7170 |
|
|---|
| 7171 | @noindent
|
|---|
| 7172 | produces the result @samp{bar}. Although @code{$(lastword
|
|---|
| 7173 | @var{text})} is the same as @code{$(word $(words @var{text}),@var{text})},
|
|---|
| 7174 | the @code{lastword} function was added for its simplicity and better
|
|---|
| 7175 | performance.@refill
|
|---|
| 7176 | @end table
|
|---|
| 7177 |
|
|---|
| 7178 |
|
|---|
| 7179 | Here is a realistic example of the use of @code{subst} and
|
|---|
| 7180 | @code{patsubst}. Suppose that a makefile uses the @code{VPATH} variable
|
|---|
| 7181 | to specify a list of directories that @code{make} should search for
|
|---|
| 7182 | prerequisite files
|
|---|
| 7183 | (@pxref{General Search, , @code{VPATH} Search Path for All Prerequisites}).
|
|---|
| 7184 | This example shows how to
|
|---|
| 7185 | tell the C compiler to search for header files in the same list of
|
|---|
| 7186 | directories.@refill
|
|---|
| 7187 |
|
|---|
| 7188 | The value of @code{VPATH} is a list of directories separated by colons,
|
|---|
| 7189 | such as @samp{src:../headers}. First, the @code{subst} function is used to
|
|---|
| 7190 | change the colons to spaces:
|
|---|
| 7191 |
|
|---|
| 7192 | @example
|
|---|
| 7193 | $(subst :, ,$(VPATH))
|
|---|
| 7194 | @end example
|
|---|
| 7195 |
|
|---|
| 7196 | @noindent
|
|---|
| 7197 | This produces @samp{src ../headers}. Then @code{patsubst} is used to turn
|
|---|
| 7198 | each directory name into a @samp{-I} flag. These can be added to the
|
|---|
| 7199 | value of the variable @code{CFLAGS}, which is passed automatically to the C
|
|---|
| 7200 | compiler, like this:
|
|---|
| 7201 |
|
|---|
| 7202 | @example
|
|---|
| 7203 | override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH)))
|
|---|
| 7204 | @end example
|
|---|
| 7205 |
|
|---|
| 7206 | @noindent
|
|---|
| 7207 | The effect is to append the text @samp{-Isrc -I../headers} to the
|
|---|
| 7208 | previously given value of @code{CFLAGS}. The @code{override} directive is
|
|---|
| 7209 | used so that the new value is assigned even if the previous value of
|
|---|
| 7210 | @code{CFLAGS} was specified with a command argument (@pxref{Override
|
|---|
| 7211 | Directive, , The @code{override} Directive}).
|
|---|
| 7212 |
|
|---|
| 7213 | @node File Name Functions, Conditional Functions, Text Functions, Functions
|
|---|
| 7214 | @section Functions for File Names
|
|---|
| 7215 | @cindex functions, for file names
|
|---|
| 7216 | @cindex file name functions
|
|---|
| 7217 |
|
|---|
| 7218 | Several of the built-in expansion functions relate specifically to
|
|---|
| 7219 | taking apart file names or lists of file names.
|
|---|
| 7220 |
|
|---|
| 7221 | Each of the following functions performs a specific transformation on a
|
|---|
| 7222 | file name. The argument of the function is regarded as a series of file
|
|---|
| 7223 | names, separated by whitespace. (Leading and trailing whitespace is
|
|---|
| 7224 | ignored.) Each file name in the series is transformed in the same way and
|
|---|
| 7225 | the results are concatenated with single spaces between them.
|
|---|
| 7226 |
|
|---|
| 7227 | @table @code
|
|---|
| 7228 | @item $(dir @var{names}@dots{})
|
|---|
| 7229 | @findex dir
|
|---|
| 7230 | @cindex directory part
|
|---|
| 7231 | @cindex file name, directory part
|
|---|
| 7232 | Extracts the directory-part of each file name in @var{names}. The
|
|---|
| 7233 | directory-part of the file name is everything up through (and
|
|---|
| 7234 | including) the last slash in it. If the file name contains no slash,
|
|---|
| 7235 | the directory part is the string @samp{./}. For example,
|
|---|
| 7236 |
|
|---|
| 7237 | @example
|
|---|
| 7238 | $(dir src/foo.c hacks)
|
|---|
| 7239 | @end example
|
|---|
| 7240 |
|
|---|
| 7241 | @noindent
|
|---|
| 7242 | produces the result @samp{src/ ./}.
|
|---|
| 7243 |
|
|---|
| 7244 | @item $(notdir @var{names}@dots{})
|
|---|
| 7245 | @findex notdir
|
|---|
| 7246 | @cindex file name, nondirectory part
|
|---|
| 7247 | @cindex nondirectory part
|
|---|
| 7248 | Extracts all but the directory-part of each file name in @var{names}.
|
|---|
| 7249 | If the file name contains no slash, it is left unchanged. Otherwise,
|
|---|
| 7250 | everything through the last slash is removed from it.
|
|---|
| 7251 |
|
|---|
| 7252 | A file name that ends with a slash becomes an empty string. This is
|
|---|
| 7253 | unfortunate, because it means that the result does not always have the
|
|---|
| 7254 | same number of whitespace-separated file names as the argument had;
|
|---|
| 7255 | but we do not see any other valid alternative.
|
|---|
| 7256 |
|
|---|
| 7257 | For example,
|
|---|
| 7258 |
|
|---|
| 7259 | @example
|
|---|
| 7260 | $(notdir src/foo.c hacks)
|
|---|
| 7261 | @end example
|
|---|
| 7262 |
|
|---|
| 7263 | @noindent
|
|---|
| 7264 | produces the result @samp{foo.c hacks}.
|
|---|
| 7265 |
|
|---|
| 7266 | @item $(suffix @var{names}@dots{})
|
|---|
| 7267 | @findex suffix
|
|---|
| 7268 | @cindex suffix, function to find
|
|---|
| 7269 | @cindex file name suffix
|
|---|
| 7270 | Extracts the suffix of each file name in @var{names}. If the file name
|
|---|
| 7271 | contains a period, the suffix is everything starting with the last
|
|---|
| 7272 | period. Otherwise, the suffix is the empty string. This frequently
|
|---|
| 7273 | means that the result will be empty when @var{names} is not, and if
|
|---|
| 7274 | @var{names} contains multiple file names, the result may contain fewer
|
|---|
| 7275 | file names.
|
|---|
| 7276 |
|
|---|
| 7277 | For example,
|
|---|
| 7278 |
|
|---|
| 7279 | @example
|
|---|
| 7280 | $(suffix src/foo.c src-1.0/bar.c hacks)
|
|---|
| 7281 | @end example
|
|---|
| 7282 |
|
|---|
| 7283 | @noindent
|
|---|
| 7284 | produces the result @samp{.c .c}.
|
|---|
| 7285 |
|
|---|
| 7286 | @item $(basename @var{names}@dots{})
|
|---|
| 7287 | @findex basename
|
|---|
| 7288 | @cindex basename
|
|---|
| 7289 | @cindex file name, basename of
|
|---|
| 7290 | Extracts all but the suffix of each file name in @var{names}. If the
|
|---|
| 7291 | file name contains a period, the basename is everything starting up to
|
|---|
| 7292 | (and not including) the last period. Periods in the directory part are
|
|---|
| 7293 | ignored. If there is no period, the basename is the entire file name.
|
|---|
| 7294 | For example,
|
|---|
| 7295 |
|
|---|
| 7296 | @example
|
|---|
| 7297 | $(basename src/foo.c src-1.0/bar hacks)
|
|---|
| 7298 | @end example
|
|---|
| 7299 |
|
|---|
| 7300 | @noindent
|
|---|
| 7301 | produces the result @samp{src/foo src-1.0/bar hacks}.
|
|---|
| 7302 |
|
|---|
| 7303 | @c plural convention with dots (be consistent)
|
|---|
| 7304 | @item $(addsuffix @var{suffix},@var{names}@dots{})
|
|---|
| 7305 | @findex addsuffix
|
|---|
| 7306 | @cindex suffix, adding
|
|---|
| 7307 | @cindex file name suffix, adding
|
|---|
| 7308 | The argument @var{names} is regarded as a series of names, separated
|
|---|
| 7309 | by whitespace; @var{suffix} is used as a unit. The value of
|
|---|
| 7310 | @var{suffix} is appended to the end of each individual name and the
|
|---|
| 7311 | resulting larger names are concatenated with single spaces between
|
|---|
| 7312 | them. For example,
|
|---|
| 7313 |
|
|---|
| 7314 | @example
|
|---|
| 7315 | $(addsuffix .c,foo bar)
|
|---|
| 7316 | @end example
|
|---|
| 7317 |
|
|---|
| 7318 | @noindent
|
|---|
| 7319 | produces the result @samp{foo.c bar.c}.
|
|---|
| 7320 |
|
|---|
| 7321 | @item $(addprefix @var{prefix},@var{names}@dots{})
|
|---|
| 7322 | @findex addprefix
|
|---|
| 7323 | @cindex prefix, adding
|
|---|
| 7324 | @cindex file name prefix, adding
|
|---|
| 7325 | The argument @var{names} is regarded as a series of names, separated
|
|---|
| 7326 | by whitespace; @var{prefix} is used as a unit. The value of
|
|---|
| 7327 | @var{prefix} is prepended to the front of each individual name and the
|
|---|
| 7328 | resulting larger names are concatenated with single spaces between
|
|---|
| 7329 | them. For example,
|
|---|
| 7330 |
|
|---|
| 7331 | @example
|
|---|
| 7332 | $(addprefix src/,foo bar)
|
|---|
| 7333 | @end example
|
|---|
| 7334 |
|
|---|
| 7335 | @noindent
|
|---|
| 7336 | produces the result @samp{src/foo src/bar}.
|
|---|
| 7337 |
|
|---|
| 7338 | @item $(join @var{list1},@var{list2})
|
|---|
| 7339 | @findex join
|
|---|
| 7340 | @cindex joining lists of words
|
|---|
| 7341 | @cindex words, joining lists
|
|---|
| 7342 | Concatenates the two arguments word by word: the two first words (one
|
|---|
| 7343 | from each argument) concatenated form the first word of the result, the
|
|---|
| 7344 | two second words form the second word of the result, and so on. So the
|
|---|
| 7345 | @var{n}th word of the result comes from the @var{n}th word of each
|
|---|
| 7346 | argument. If one argument has more words that the other, the extra
|
|---|
| 7347 | words are copied unchanged into the result.
|
|---|
| 7348 |
|
|---|
| 7349 | For example, @samp{$(join a b,.c .o)} produces @samp{a.c b.o}.
|
|---|
| 7350 |
|
|---|
| 7351 | Whitespace between the words in the lists is not preserved; it is
|
|---|
| 7352 | replaced with a single space.
|
|---|
| 7353 |
|
|---|
| 7354 | This function can merge the results of the @code{dir} and
|
|---|
| 7355 | @code{notdir} functions, to produce the original list of files which
|
|---|
| 7356 | was given to those two functions.@refill
|
|---|
| 7357 |
|
|---|
| 7358 | @item $(wildcard @var{pattern})
|
|---|
| 7359 | @findex wildcard
|
|---|
| 7360 | @cindex wildcard, function
|
|---|
| 7361 | The argument @var{pattern} is a file name pattern, typically containing
|
|---|
| 7362 | wildcard characters (as in shell file name patterns). The result of
|
|---|
| 7363 | @code{wildcard} is a space-separated list of the names of existing files
|
|---|
| 7364 | that match the pattern.
|
|---|
| 7365 | @xref{Wildcards, ,Using Wildcard Characters in File Names}.
|
|---|
| 7366 |
|
|---|
| 7367 | @item $(realpath @var{names}@dots{})
|
|---|
| 7368 | @findex realpath
|
|---|
| 7369 | @cindex realpath
|
|---|
| 7370 | @cindex file name, realpath of
|
|---|
| 7371 | For each file name in @var{names} return the canonical absolute name.
|
|---|
| 7372 | A canonical name does not contain any @code{.} or @code{..} components,
|
|---|
| 7373 | nor any repeated path separators (@code{/}) or symlinks. In case of a
|
|---|
| 7374 | failure the empty string is returned. Consult the @code{realpath(3)}
|
|---|
| 7375 | documentation for a list of possible failure causes.
|
|---|
| 7376 |
|
|---|
| 7377 | @item $(abspath @var{names}@dots{})
|
|---|
| 7378 | @findex abspath
|
|---|
| 7379 | @cindex abspath
|
|---|
| 7380 | @cindex file name, abspath of
|
|---|
| 7381 | For each file name in @var{names} return an absolute name that does
|
|---|
| 7382 | not contain any @code{.} or @code{..} components, nor any repeated path
|
|---|
| 7383 | separators (@code{/}). Note that, in contrast to @code{realpath}
|
|---|
| 7384 | function, @code{abspath} does not resolve symlinks and does not require
|
|---|
| 7385 | the file names to refer to an existing file or directory. Use the
|
|---|
| 7386 | @code{wildcard} function to test for existence.
|
|---|
| 7387 | @end table
|
|---|
| 7388 |
|
|---|
| 7389 | @node Conditional Functions, Foreach Function, File Name Functions, Functions
|
|---|
| 7390 | @section Functions for Conditionals
|
|---|
| 7391 | @findex if
|
|---|
| 7392 | @cindex conditional expansion
|
|---|
| 7393 | There are three functions that provide conditional expansion. A key
|
|---|
| 7394 | aspect of these functions is that not all of the arguments are
|
|---|
| 7395 | expanded initially. Only those arguments which need to be expanded,
|
|---|
| 7396 | will be expanded.
|
|---|
| 7397 |
|
|---|
| 7398 | @table @code
|
|---|
| 7399 | @item $(if @var{condition},@var{then-part}[,@var{else-part}])
|
|---|
| 7400 | @findex if
|
|---|
| 7401 | The @code{if} function provides support for conditional expansion in a
|
|---|
| 7402 | functional context (as opposed to the GNU @code{make} makefile
|
|---|
| 7403 | conditionals such as @code{ifeq} (@pxref{Conditional Syntax, ,Syntax of
|
|---|
| 7404 | Conditionals}).
|
|---|
| 7405 |
|
|---|
| 7406 | The first argument, @var{condition}, first has all preceding and
|
|---|
| 7407 | trailing whitespace stripped, then is expanded. If it expands to any
|
|---|
| 7408 | non-empty string, then the condition is considered to be true. If it
|
|---|
| 7409 | expands to an empty string, the condition is considered to be false.
|
|---|
| 7410 |
|
|---|
| 7411 | If the condition is true then the second argument, @var{then-part}, is
|
|---|
| 7412 | evaluated and this is used as the result of the evaluation of the entire
|
|---|
| 7413 | @code{if} function.
|
|---|
| 7414 |
|
|---|
| 7415 | If the condition is false then the third argument, @var{else-part}, is
|
|---|
| 7416 | evaluated and this is the result of the @code{if} function. If there is
|
|---|
| 7417 | no third argument, the @code{if} function evaluates to nothing (the
|
|---|
| 7418 | empty string).
|
|---|
| 7419 |
|
|---|
| 7420 | Note that only one of the @var{then-part} or the @var{else-part} will be
|
|---|
| 7421 | evaluated, never both. Thus, either can contain side-effects (such as
|
|---|
| 7422 | @code{shell} function calls, etc.)
|
|---|
| 7423 |
|
|---|
| 7424 | @item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
|
|---|
| 7425 | @findex or
|
|---|
| 7426 | The @code{or} function provides a ``short-circuiting'' OR operation.
|
|---|
| 7427 | Each argument is expanded, in order. If an argument expands to a
|
|---|
| 7428 | non-empty string the processing stops and the result of the expansion
|
|---|
| 7429 | is that string. If, after all arguments are expanded, all of them are
|
|---|
| 7430 | false (empty), then the result of the expansion is the empty string.
|
|---|
| 7431 |
|
|---|
| 7432 | @item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
|
|---|
| 7433 | @findex and
|
|---|
| 7434 | The @code{and} function provides a ``short-circuiting'' AND operation.
|
|---|
| 7435 | Each argument is expanded, in order. If an argument expands to an
|
|---|
| 7436 | empty string the processing stops and the result of the expansion is
|
|---|
| 7437 | the empty string. If all arguments expand to a non-empty string then
|
|---|
| 7438 | the result of the expansion is the expansion of the last argument.
|
|---|
| 7439 |
|
|---|
| 7440 | @end table
|
|---|
| 7441 |
|
|---|
| 7442 | @node Foreach Function, File Function, Conditional Functions, Functions
|
|---|
| 7443 | @section The @code{foreach} Function
|
|---|
| 7444 | @findex foreach
|
|---|
| 7445 | @cindex words, iterating over
|
|---|
| 7446 |
|
|---|
| 7447 | The @code{foreach} function is very different from other functions. It
|
|---|
| 7448 | causes one piece of text to be used repeatedly, each time with a different
|
|---|
| 7449 | substitution performed on it. It resembles the @code{for} command in the
|
|---|
| 7450 | shell @code{sh} and the @code{foreach} command in the C-shell @code{csh}.
|
|---|
| 7451 |
|
|---|
| 7452 | The syntax of the @code{foreach} function is:
|
|---|
| 7453 |
|
|---|
| 7454 | @example
|
|---|
| 7455 | $(foreach @var{var},@var{list},@var{text})
|
|---|
| 7456 | @end example
|
|---|
| 7457 |
|
|---|
| 7458 | @noindent
|
|---|
| 7459 | The first two arguments, @var{var} and @var{list}, are expanded before
|
|---|
| 7460 | anything else is done; note that the last argument, @var{text}, is
|
|---|
| 7461 | @strong{not} expanded at the same time. Then for each word of the expanded
|
|---|
| 7462 | value of @var{list}, the variable named by the expanded value of @var{var}
|
|---|
| 7463 | is set to that word, and @var{text} is expanded. Presumably @var{text}
|
|---|
| 7464 | contains references to that variable, so its expansion will be different
|
|---|
| 7465 | each time.
|
|---|
| 7466 |
|
|---|
| 7467 | The result is that @var{text} is expanded as many times as there are
|
|---|
| 7468 | whitespace-separated words in @var{list}. The multiple expansions of
|
|---|
| 7469 | @var{text} are concatenated, with spaces between them, to make the result
|
|---|
| 7470 | of @code{foreach}.
|
|---|
| 7471 |
|
|---|
| 7472 | This simple example sets the variable @samp{files} to the list of all files
|
|---|
| 7473 | in the directories in the list @samp{dirs}:
|
|---|
| 7474 |
|
|---|
| 7475 | @example
|
|---|
| 7476 | dirs := a b c d
|
|---|
| 7477 | files := $(foreach dir,$(dirs),$(wildcard $(dir)/*))
|
|---|
| 7478 | @end example
|
|---|
| 7479 |
|
|---|
| 7480 | Here @var{text} is @samp{$(wildcard $(dir)/*)}. The first repetition
|
|---|
| 7481 | finds the value @samp{a} for @code{dir}, so it produces the same result
|
|---|
| 7482 | as @samp{$(wildcard a/*)}; the second repetition produces the result
|
|---|
| 7483 | of @samp{$(wildcard b/*)}; and the third, that of @samp{$(wildcard c/*)}.
|
|---|
| 7484 |
|
|---|
| 7485 | This example has the same result (except for setting @samp{dirs}) as
|
|---|
| 7486 | the following example:
|
|---|
| 7487 |
|
|---|
| 7488 | @example
|
|---|
| 7489 | files := $(wildcard a/* b/* c/* d/*)
|
|---|
| 7490 | @end example
|
|---|
| 7491 |
|
|---|
| 7492 | When @var{text} is complicated, you can improve readability by giving it
|
|---|
| 7493 | a name, with an additional variable:
|
|---|
| 7494 |
|
|---|
| 7495 | @example
|
|---|
| 7496 | find_files = $(wildcard $(dir)/*)
|
|---|
| 7497 | dirs := a b c d
|
|---|
| 7498 | files := $(foreach dir,$(dirs),$(find_files))
|
|---|
| 7499 | @end example
|
|---|
| 7500 |
|
|---|
| 7501 | @noindent
|
|---|
| 7502 | Here we use the variable @code{find_files} this way. We use plain @samp{=}
|
|---|
| 7503 | to define a recursively-expanding variable, so that its value contains an
|
|---|
| 7504 | actual function call to be re-expanded under the control of @code{foreach};
|
|---|
| 7505 | a simply-expanded variable would not do, since @code{wildcard} would be
|
|---|
| 7506 | called only once at the time of defining @code{find_files}.
|
|---|
| 7507 |
|
|---|
| 7508 | The @code{foreach} function has no permanent effect on the variable
|
|---|
| 7509 | @var{var}; its value and flavor after the @code{foreach} function call are
|
|---|
| 7510 | the same as they were beforehand. The other values which are taken from
|
|---|
| 7511 | @var{list} are in effect only temporarily, during the execution of
|
|---|
| 7512 | @code{foreach}. The variable @var{var} is a simply-expanded variable
|
|---|
| 7513 | during the execution of @code{foreach}. If @var{var} was undefined
|
|---|
| 7514 | before the @code{foreach} function call, it is undefined after the call.
|
|---|
| 7515 | @xref{Flavors, ,The Two Flavors of Variables}.@refill
|
|---|
| 7516 |
|
|---|
| 7517 | You must take care when using complex variable expressions that result in
|
|---|
| 7518 | variable names because many strange things are valid variable names, but
|
|---|
| 7519 | are probably not what you intended. For example,
|
|---|
| 7520 |
|
|---|
| 7521 | @smallexample
|
|---|
| 7522 | files := $(foreach Esta-escrito-en-espanol!,b c ch,$(find_files))
|
|---|
| 7523 | @end smallexample
|
|---|
| 7524 |
|
|---|
| 7525 | @noindent
|
|---|
| 7526 | might be useful if the value of @code{find_files} references the variable
|
|---|
| 7527 | whose name is @samp{Esta-escrito-en-espanol!} (es un nombre bastante largo,
|
|---|
| 7528 | no?), but it is more likely to be a mistake.
|
|---|
| 7529 |
|
|---|
| 7530 | @node File Function, Call Function, Foreach Function, Functions
|
|---|
| 7531 | @section The @code{file} Function
|
|---|
| 7532 | @findex file
|
|---|
| 7533 | @cindex writing to a file
|
|---|
| 7534 | @cindex file, writing to
|
|---|
| 7535 | @cindex reading from a file
|
|---|
| 7536 | @cindex file, reading from
|
|---|
| 7537 |
|
|---|
| 7538 | The @code{file} function allows the makefile to write to or read from
|
|---|
| 7539 | a file. Two modes of writing are supported: overwrite, where the text
|
|---|
| 7540 | is written to the beginning of the file and any existing content is
|
|---|
| 7541 | lost, and append, where the text is written to the end of the file,
|
|---|
| 7542 | preserving the existing content. In both cases the file is created if
|
|---|
| 7543 | it does not exist. It is a fatal error if the file cannot be opened
|
|---|
| 7544 | for writing, or if the write operation fails. The @code{file}
|
|---|
| 7545 | function expands to the empty string when writing to a file.
|
|---|
| 7546 |
|
|---|
| 7547 | When reading from a file, the @code{file} function expands to the
|
|---|
| 7548 | verbatim contents of the file, except that the final newline (if there
|
|---|
| 7549 | is one) will be stripped. Attempting to read from a non-existent file
|
|---|
| 7550 | expands to the empty string.
|
|---|
| 7551 |
|
|---|
| 7552 | The syntax of the @code{file} function is:
|
|---|
| 7553 |
|
|---|
| 7554 | @example
|
|---|
| 7555 | $(file @var{op} @var{filename}[,@var{text}])
|
|---|
| 7556 | @end example
|
|---|
| 7557 |
|
|---|
| 7558 | When the @code{file} function is evaluated all its arguments are
|
|---|
| 7559 | expanded first, then the file indicated by @var{filename} will be
|
|---|
| 7560 | opened in the mode described by @var{op}.
|
|---|
| 7561 |
|
|---|
| 7562 | The operator @var{op} can be @code{>} to indicate the file will be
|
|---|
| 7563 | overwritten with new content, @code{>>} to indicate the current
|
|---|
| 7564 | contents of the file will be appended to, or @code{<} to indicate the
|
|---|
| 7565 | contents of the file will be read in. The @var{filename} specifies
|
|---|
| 7566 | the file to be written to or read from. There may optionally be
|
|---|
| 7567 | whitespace between the operator and the file name.
|
|---|
| 7568 |
|
|---|
| 7569 | When reading files, it is an error to provide a @var{text} value.
|
|---|
| 7570 |
|
|---|
| 7571 | When writing files, @var{text} will be written to the file. If
|
|---|
| 7572 | @var{text} does not already end in a newline a final newline will be
|
|---|
| 7573 | written (even if @var{text} is the empty string). If the @var{text}
|
|---|
| 7574 | argument is not given at all, nothing will be written.
|
|---|
| 7575 |
|
|---|
| 7576 | For example, the @code{file} function can be useful if your build
|
|---|
| 7577 | system has a limited command line size and your recipe runs a command
|
|---|
| 7578 | that can accept arguments from a file as well. Many commands use the
|
|---|
| 7579 | convention that an argument prefixed with an @code{@@} specifies a
|
|---|
| 7580 | file containing more arguments. Then you might write your recipe in
|
|---|
| 7581 | this way:
|
|---|
| 7582 |
|
|---|
| 7583 | @example
|
|---|
| 7584 | @group
|
|---|
| 7585 | program: $(OBJECTS)
|
|---|
| 7586 | $(file >$@@.in,$^)
|
|---|
| 7587 | $(CMD) $(CMDFLAGS) @@$@@.in
|
|---|
| 7588 | @@rm $@@.in
|
|---|
| 7589 | @end group
|
|---|
| 7590 | @end example
|
|---|
| 7591 |
|
|---|
| 7592 | If the command required each argument to be on a separate line of the
|
|---|
| 7593 | input file, you might write your recipe like this:
|
|---|
| 7594 |
|
|---|
| 7595 | @example
|
|---|
| 7596 | @group
|
|---|
| 7597 | program: $(OBJECTS)
|
|---|
| 7598 | $(file >$@@.in) $(foreach O,$^,$(file >>$@@.in,$O))
|
|---|
| 7599 | $(CMD) $(CMDFLAGS) @@$@@.in
|
|---|
| 7600 | @@rm $@@.in
|
|---|
| 7601 | @end group
|
|---|
| 7602 | @end example
|
|---|
| 7603 |
|
|---|
| 7604 | @node Call Function, Value Function, File Function, Functions
|
|---|
| 7605 | @section The @code{call} Function
|
|---|
| 7606 | @findex call
|
|---|
| 7607 | @cindex functions, user defined
|
|---|
| 7608 | @cindex user defined functions
|
|---|
| 7609 |
|
|---|
| 7610 | The @code{call} function is unique in that it can be used to create new
|
|---|
| 7611 | parameterized functions. You can write a complex expression as the
|
|---|
| 7612 | value of a variable, then use @code{call} to expand it with different
|
|---|
| 7613 | values.
|
|---|
| 7614 |
|
|---|
| 7615 | The syntax of the @code{call} function is:
|
|---|
| 7616 |
|
|---|
| 7617 | @example
|
|---|
| 7618 | $(call @var{variable},@var{param},@var{param},@dots{})
|
|---|
| 7619 | @end example
|
|---|
| 7620 |
|
|---|
| 7621 | When @code{make} expands this function, it assigns each @var{param} to
|
|---|
| 7622 | temporary variables @code{$(1)}, @code{$(2)}, etc. The variable
|
|---|
| 7623 | @code{$(0)} will contain @var{variable}. There is no maximum number of
|
|---|
| 7624 | parameter arguments. There is no minimum, either, but it doesn't make
|
|---|
| 7625 | sense to use @code{call} with no parameters.
|
|---|
| 7626 |
|
|---|
| 7627 | Then @var{variable} is expanded as a @code{make} variable in the context
|
|---|
| 7628 | of these temporary assignments. Thus, any reference to @code{$(1)} in
|
|---|
| 7629 | the value of @var{variable} will resolve to the first @var{param} in the
|
|---|
| 7630 | invocation of @code{call}.
|
|---|
| 7631 |
|
|---|
| 7632 | Note that @var{variable} is the @emph{name} of a variable, not a
|
|---|
| 7633 | @emph{reference} to that variable. Therefore you would not normally use
|
|---|
| 7634 | a @samp{$} or parentheses when writing it. (You can, however, use a
|
|---|
| 7635 | variable reference in the name if you want the name not to be a
|
|---|
| 7636 | constant.)
|
|---|
| 7637 |
|
|---|
| 7638 | If @var{variable} is the name of a built-in function, the built-in function
|
|---|
| 7639 | is always invoked (even if a @code{make} variable by that name also
|
|---|
| 7640 | exists).
|
|---|
| 7641 |
|
|---|
| 7642 | The @code{call} function expands the @var{param} arguments before
|
|---|
| 7643 | assigning them to temporary variables. This means that @var{variable}
|
|---|
| 7644 | values containing references to built-in functions that have special
|
|---|
| 7645 | expansion rules, like @code{foreach} or @code{if}, may not work as you
|
|---|
| 7646 | expect.
|
|---|
| 7647 |
|
|---|
| 7648 | Some examples may make this clearer.
|
|---|
| 7649 |
|
|---|
| 7650 | This macro simply reverses its arguments:
|
|---|
| 7651 |
|
|---|
| 7652 | @smallexample
|
|---|
| 7653 | reverse = $(2) $(1)
|
|---|
| 7654 |
|
|---|
| 7655 | foo = $(call reverse,a,b)
|
|---|
| 7656 | @end smallexample
|
|---|
| 7657 |
|
|---|
| 7658 | @noindent
|
|---|
| 7659 | Here @var{foo} will contain @samp{b a}.
|
|---|
| 7660 |
|
|---|
| 7661 | This one is slightly more interesting: it defines a macro to search for
|
|---|
| 7662 | the first instance of a program in @code{PATH}:
|
|---|
| 7663 |
|
|---|
| 7664 | @smallexample
|
|---|
| 7665 | pathsearch = $(firstword $(wildcard $(addsuffix /$(1),$(subst :, ,$(PATH)))))
|
|---|
| 7666 |
|
|---|
| 7667 | LS := $(call pathsearch,ls)
|
|---|
| 7668 | @end smallexample
|
|---|
| 7669 |
|
|---|
| 7670 | @noindent
|
|---|
| 7671 | Now the variable LS contains @code{/bin/ls} or similar.
|
|---|
| 7672 |
|
|---|
| 7673 | The @code{call} function can be nested. Each recursive invocation gets
|
|---|
| 7674 | its own local values for @code{$(1)}, etc.@: that mask the values of
|
|---|
| 7675 | higher-level @code{call}. For example, here is an implementation of a
|
|---|
| 7676 | @dfn{map} function:
|
|---|
| 7677 |
|
|---|
| 7678 | @smallexample
|
|---|
| 7679 | map = $(foreach a,$(2),$(call $(1),$(a)))
|
|---|
| 7680 | @end smallexample
|
|---|
| 7681 |
|
|---|
| 7682 | Now you can @var{map} a function that normally takes only one argument,
|
|---|
| 7683 | such as @code{origin}, to multiple values in one step:
|
|---|
| 7684 |
|
|---|
| 7685 | @smallexample
|
|---|
| 7686 | o = $(call map,origin,o map MAKE)
|
|---|
| 7687 | @end smallexample
|
|---|
| 7688 |
|
|---|
| 7689 | and end up with @var{o} containing something like @samp{file file default}.
|
|---|
| 7690 |
|
|---|
| 7691 | A final caution: be careful when adding whitespace to the arguments to
|
|---|
| 7692 | @code{call}. As with other functions, any whitespace contained in the
|
|---|
| 7693 | second and subsequent arguments is kept; this can cause strange
|
|---|
| 7694 | effects. It's generally safest to remove all extraneous whitespace when
|
|---|
| 7695 | providing parameters to @code{call}.
|
|---|
| 7696 |
|
|---|
| 7697 | @node Value Function, Eval Function, Call Function, Functions
|
|---|
| 7698 | @comment node-name, next, previous, up
|
|---|
| 7699 | @section The @code{value} Function
|
|---|
| 7700 | @findex value
|
|---|
| 7701 | @cindex variables, unexpanded value
|
|---|
| 7702 |
|
|---|
| 7703 | The @code{value} function provides a way for you to use the value of a
|
|---|
| 7704 | variable @emph{without} having it expanded. Please note that this
|
|---|
| 7705 | does not undo expansions which have already occurred; for example if
|
|---|
| 7706 | you create a simply expanded variable its value is expanded during the
|
|---|
| 7707 | definition; in that case the @code{value} function will return the
|
|---|
| 7708 | same result as using the variable directly.
|
|---|
| 7709 |
|
|---|
| 7710 | The syntax of the @code{value} function is:
|
|---|
| 7711 |
|
|---|
| 7712 | @example
|
|---|
| 7713 | $(value @var{variable})
|
|---|
| 7714 | @end example
|
|---|
| 7715 |
|
|---|
| 7716 | Note that @var{variable} is the @emph{name} of a variable, not a
|
|---|
| 7717 | @emph{reference} to that variable. Therefore you would not normally
|
|---|
| 7718 | use a @samp{$} or parentheses when writing it. (You can, however, use
|
|---|
| 7719 | a variable reference in the name if you want the name not to be a
|
|---|
| 7720 | constant.)
|
|---|
| 7721 |
|
|---|
| 7722 | The result of this function is a string containing the value of
|
|---|
| 7723 | @var{variable}, without any expansion occurring. For example, in this
|
|---|
| 7724 | makefile:
|
|---|
| 7725 |
|
|---|
| 7726 | @example
|
|---|
| 7727 | @group
|
|---|
| 7728 | FOO = $PATH
|
|---|
| 7729 |
|
|---|
| 7730 | all:
|
|---|
| 7731 | @@echo $(FOO)
|
|---|
| 7732 | @@echo $(value FOO)
|
|---|
| 7733 | @end group
|
|---|
| 7734 | @end example
|
|---|
| 7735 |
|
|---|
| 7736 | @noindent
|
|---|
| 7737 | The first output line would be @code{ATH}, since the ``$P'' would be
|
|---|
| 7738 | expanded as a @code{make} variable, while the second output line would
|
|---|
| 7739 | be the current value of your @code{$PATH} environment variable, since
|
|---|
| 7740 | the @code{value} function avoided the expansion.
|
|---|
| 7741 |
|
|---|
| 7742 | The @code{value} function is most often used in conjunction with the
|
|---|
| 7743 | @code{eval} function (@pxref{Eval Function}).
|
|---|
| 7744 |
|
|---|
| 7745 | @node Eval Function, Origin Function, Value Function, Functions
|
|---|
| 7746 | @comment node-name, next, previous, up
|
|---|
| 7747 | @section The @code{eval} Function
|
|---|
| 7748 | @findex eval
|
|---|
| 7749 | @cindex evaluating makefile syntax
|
|---|
| 7750 | @cindex makefile syntax, evaluating
|
|---|
| 7751 |
|
|---|
| 7752 | The @code{eval} function is very special: it allows you to define new
|
|---|
| 7753 | makefile constructs that are not constant; which are the result of
|
|---|
| 7754 | evaluating other variables and functions. The argument to the
|
|---|
| 7755 | @code{eval} function is expanded, then the results of that expansion
|
|---|
| 7756 | are parsed as makefile syntax. The expanded results can define new
|
|---|
| 7757 | @code{make} variables, targets, implicit or explicit rules, etc.
|
|---|
| 7758 |
|
|---|
| 7759 | The result of the @code{eval} function is always the empty string;
|
|---|
| 7760 | thus, it can be placed virtually anywhere in a makefile without
|
|---|
| 7761 | causing syntax errors.
|
|---|
| 7762 |
|
|---|
| 7763 | It's important to realize that the @code{eval} argument is expanded
|
|---|
| 7764 | @emph{twice}; first by the @code{eval} function, then the results of
|
|---|
| 7765 | that expansion are expanded again when they are parsed as makefile
|
|---|
| 7766 | syntax. This means you may need to provide extra levels of escaping
|
|---|
| 7767 | for ``$'' characters when using @code{eval}. The @code{value}
|
|---|
| 7768 | function (@pxref{Value Function}) can sometimes be useful in these
|
|---|
| 7769 | situations, to circumvent unwanted expansions.
|
|---|
| 7770 |
|
|---|
| 7771 | Here is an example of how @code{eval} can be used; this example
|
|---|
| 7772 | combines a number of concepts and other functions. Although it might
|
|---|
| 7773 | seem overly complex to use @code{eval} in this example, rather than
|
|---|
| 7774 | just writing out the rules, consider two things: first, the template
|
|---|
| 7775 | definition (in @code{PROGRAM_template}) could need to be much more
|
|---|
| 7776 | complex than it is here; and second, you might put the complex,
|
|---|
| 7777 | ``generic'' part of this example into another makefile, then include
|
|---|
| 7778 | it in all the individual makefiles. Now your individual makefiles are
|
|---|
| 7779 | quite straightforward.
|
|---|
| 7780 |
|
|---|
| 7781 | @example
|
|---|
| 7782 | @group
|
|---|
| 7783 | PROGRAMS = server client
|
|---|
| 7784 |
|
|---|
| 7785 | server_OBJS = server.o server_priv.o server_access.o
|
|---|
| 7786 | server_LIBS = priv protocol
|
|---|
| 7787 |
|
|---|
| 7788 | client_OBJS = client.o client_api.o client_mem.o
|
|---|
| 7789 | client_LIBS = protocol
|
|---|
| 7790 |
|
|---|
| 7791 | # Everything after this is generic
|
|---|
| 7792 |
|
|---|
| 7793 | .PHONY: all
|
|---|
| 7794 | all: $(PROGRAMS)
|
|---|
| 7795 |
|
|---|
| 7796 | define PROGRAM_template =
|
|---|
| 7797 | $(1): $$($(1)_OBJS) $$($(1)_LIBS:%=-l%)
|
|---|
| 7798 | ALL_OBJS += $$($(1)_OBJS)
|
|---|
| 7799 | endef
|
|---|
| 7800 |
|
|---|
| 7801 | $(foreach prog,$(PROGRAMS),$(eval $(call PROGRAM_template,$(prog))))
|
|---|
| 7802 |
|
|---|
| 7803 | $(PROGRAMS):
|
|---|
| 7804 | $(LINK.o) $^ $(LDLIBS) -o $@@
|
|---|
| 7805 |
|
|---|
| 7806 | clean:
|
|---|
| 7807 | rm -f $(ALL_OBJS) $(PROGRAMS)
|
|---|
| 7808 | @end group
|
|---|
| 7809 | @end example
|
|---|
| 7810 |
|
|---|
| 7811 | @node Origin Function, Flavor Function, Eval Function, Functions
|
|---|
| 7812 | @section The @code{origin} Function
|
|---|
| 7813 | @findex origin
|
|---|
| 7814 | @cindex variables, origin of
|
|---|
| 7815 | @cindex origin of variable
|
|---|
| 7816 |
|
|---|
| 7817 | The @code{origin} function is unlike most other functions in that it does
|
|---|
| 7818 | not operate on the values of variables; it tells you something @emph{about}
|
|---|
| 7819 | a variable. Specifically, it tells you where it came from.
|
|---|
| 7820 |
|
|---|
| 7821 | The syntax of the @code{origin} function is:
|
|---|
| 7822 |
|
|---|
| 7823 | @example
|
|---|
| 7824 | $(origin @var{variable})
|
|---|
| 7825 | @end example
|
|---|
| 7826 |
|
|---|
| 7827 | Note that @var{variable} is the @emph{name} of a variable to inquire about,
|
|---|
| 7828 | not a @emph{reference} to that variable. Therefore you would not normally
|
|---|
| 7829 | use a @samp{$} or parentheses when writing it. (You can, however, use a
|
|---|
| 7830 | variable reference in the name if you want the name not to be a constant.)
|
|---|
| 7831 |
|
|---|
| 7832 | The result of this function is a string telling you how the variable
|
|---|
| 7833 | @var{variable} was defined:
|
|---|
| 7834 |
|
|---|
| 7835 | @table @samp
|
|---|
| 7836 | @item undefined
|
|---|
| 7837 |
|
|---|
| 7838 | if @var{variable} was never defined.
|
|---|
| 7839 |
|
|---|
| 7840 | @item default
|
|---|
| 7841 |
|
|---|
| 7842 | if @var{variable} has a default definition, as is usual with @code{CC}
|
|---|
| 7843 | and so on. @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
|
|---|
| 7844 | Note that if you have redefined a default variable, the @code{origin}
|
|---|
| 7845 | function will return the origin of the later definition.
|
|---|
| 7846 |
|
|---|
| 7847 | @item environment
|
|---|
| 7848 |
|
|---|
| 7849 | if @var{variable} was inherited from the environment provided to
|
|---|
| 7850 | @code{make}.
|
|---|
| 7851 |
|
|---|
| 7852 | @item environment override
|
|---|
| 7853 |
|
|---|
| 7854 | if @var{variable} was inherited from the environment provided to
|
|---|
| 7855 | @code{make}, and is overriding a setting for @var{variable} in the
|
|---|
| 7856 | makefile as a result of the @w{@samp{-e}} option (@pxref{Options
|
|---|
| 7857 | Summary, ,Summary of Options}).@refill
|
|---|
| 7858 |
|
|---|
| 7859 | @item file
|
|---|
| 7860 |
|
|---|
| 7861 | if @var{variable} was defined in a makefile.
|
|---|
| 7862 |
|
|---|
| 7863 | @item command line
|
|---|
| 7864 |
|
|---|
| 7865 | if @var{variable} was defined on the command line.
|
|---|
| 7866 |
|
|---|
| 7867 | @item override
|
|---|
| 7868 |
|
|---|
| 7869 | if @var{variable} was defined with an @code{override} directive in a
|
|---|
| 7870 | makefile (@pxref{Override Directive, ,The @code{override} Directive}).
|
|---|
| 7871 |
|
|---|
| 7872 | @item automatic
|
|---|
| 7873 |
|
|---|
| 7874 | if @var{variable} is an automatic variable defined for the execution
|
|---|
| 7875 | of the recipe for each rule (@pxref{Automatic Variables}).
|
|---|
| 7876 | @end table
|
|---|
| 7877 |
|
|---|
| 7878 | This information is primarily useful (other than for your curiosity) to
|
|---|
| 7879 | determine if you want to believe the value of a variable. For example,
|
|---|
| 7880 | suppose you have a makefile @file{foo} that includes another makefile
|
|---|
| 7881 | @file{bar}. You want a variable @code{bletch} to be defined in @file{bar}
|
|---|
| 7882 | if you run the command @w{@samp{make -f bar}}, even if the environment contains
|
|---|
| 7883 | a definition of @code{bletch}. However, if @file{foo} defined
|
|---|
| 7884 | @code{bletch} before including @file{bar}, you do not want to override that
|
|---|
| 7885 | definition. This could be done by using an @code{override} directive in
|
|---|
| 7886 | @file{foo}, giving that definition precedence over the later definition in
|
|---|
| 7887 | @file{bar}; unfortunately, the @code{override} directive would also
|
|---|
| 7888 | override any command line definitions. So, @file{bar} could
|
|---|
| 7889 | include:@refill
|
|---|
| 7890 |
|
|---|
| 7891 | @example
|
|---|
| 7892 | @group
|
|---|
| 7893 | ifdef bletch
|
|---|
| 7894 | ifeq "$(origin bletch)" "environment"
|
|---|
| 7895 | bletch = barf, gag, etc.
|
|---|
| 7896 | endif
|
|---|
| 7897 | endif
|
|---|
| 7898 | @end group
|
|---|
| 7899 | @end example
|
|---|
| 7900 |
|
|---|
| 7901 | @noindent
|
|---|
| 7902 | If @code{bletch} has been defined from the environment, this will redefine
|
|---|
| 7903 | it.
|
|---|
| 7904 |
|
|---|
| 7905 | If you want to override a previous definition of @code{bletch} if it came
|
|---|
| 7906 | from the environment, even under @samp{-e}, you could instead write:
|
|---|
| 7907 |
|
|---|
| 7908 | @example
|
|---|
| 7909 | @group
|
|---|
| 7910 | ifneq "$(findstring environment,$(origin bletch))" ""
|
|---|
| 7911 | bletch = barf, gag, etc.
|
|---|
| 7912 | endif
|
|---|
| 7913 | @end group
|
|---|
| 7914 | @end example
|
|---|
| 7915 |
|
|---|
| 7916 | Here the redefinition takes place if @samp{$(origin bletch)} returns either
|
|---|
| 7917 | @samp{environment} or @samp{environment override}.
|
|---|
| 7918 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 7919 |
|
|---|
| 7920 | @node Flavor Function, Make Control Functions, Origin Function, Functions
|
|---|
| 7921 | @section The @code{flavor} Function
|
|---|
| 7922 | @findex flavor
|
|---|
| 7923 | @cindex variables, flavor of
|
|---|
| 7924 | @cindex flavor of variable
|
|---|
| 7925 |
|
|---|
| 7926 | The @code{flavor} function, like the @code{origin} function, does not
|
|---|
| 7927 | operate on the values of variables but rather it tells you something
|
|---|
| 7928 | @emph{about} a variable. Specifically, it tells you the flavor of a
|
|---|
| 7929 | variable (@pxref{Flavors, ,The Two Flavors of Variables}).
|
|---|
| 7930 |
|
|---|
| 7931 | The syntax of the @code{flavor} function is:
|
|---|
| 7932 |
|
|---|
| 7933 | @example
|
|---|
| 7934 | $(flavor @var{variable})
|
|---|
| 7935 | @end example
|
|---|
| 7936 |
|
|---|
| 7937 | Note that @var{variable} is the @emph{name} of a variable to inquire about,
|
|---|
| 7938 | not a @emph{reference} to that variable. Therefore you would not normally
|
|---|
| 7939 | use a @samp{$} or parentheses when writing it. (You can, however, use a
|
|---|
| 7940 | variable reference in the name if you want the name not to be a constant.)
|
|---|
| 7941 |
|
|---|
| 7942 | The result of this function is a string that identifies the flavor of the
|
|---|
| 7943 | variable @var{variable}:
|
|---|
| 7944 |
|
|---|
| 7945 | @table @samp
|
|---|
| 7946 | @item undefined
|
|---|
| 7947 |
|
|---|
| 7948 | if @var{variable} was never defined.
|
|---|
| 7949 |
|
|---|
| 7950 | @item recursive
|
|---|
| 7951 |
|
|---|
| 7952 | if @var{variable} is a recursively expanded variable.
|
|---|
| 7953 |
|
|---|
| 7954 | @item simple
|
|---|
| 7955 |
|
|---|
| 7956 | if @var{variable} is a simply expanded variable.
|
|---|
| 7957 |
|
|---|
| 7958 | @end table
|
|---|
| 7959 |
|
|---|
| 7960 | @node Make Control Functions, Shell Function, Flavor Function, Functions
|
|---|
| 7961 | @section Functions That Control Make
|
|---|
| 7962 | @cindex functions, for controlling make
|
|---|
| 7963 | @cindex controlling make
|
|---|
| 7964 |
|
|---|
| 7965 | These functions control the way make runs. Generally, they are used to
|
|---|
| 7966 | provide information to the user of the makefile or to cause make to stop
|
|---|
| 7967 | if some sort of environmental error is detected.
|
|---|
| 7968 |
|
|---|
| 7969 | @table @code
|
|---|
| 7970 | @item $(error @var{text}@dots{})
|
|---|
| 7971 | @findex error
|
|---|
| 7972 | @cindex error, stopping on
|
|---|
| 7973 | @cindex stopping make
|
|---|
| 7974 | Generates a fatal error where the message is @var{text}. Note that
|
|---|
| 7975 | the error is generated whenever this function is evaluated. So, if
|
|---|
| 7976 | you put it inside a recipe or on the right side of a recursive
|
|---|
| 7977 | variable assignment, it won't be evaluated until later. The
|
|---|
| 7978 | @var{text} will be expanded before the error is generated.
|
|---|
| 7979 |
|
|---|
| 7980 | For example,
|
|---|
| 7981 |
|
|---|
| 7982 | @example
|
|---|
| 7983 | ifdef ERROR1
|
|---|
| 7984 | $(error error is $(ERROR1))
|
|---|
| 7985 | endif
|
|---|
| 7986 | @end example
|
|---|
| 7987 |
|
|---|
| 7988 | @noindent
|
|---|
| 7989 | will generate a fatal error during the read of the makefile if the
|
|---|
| 7990 | @code{make} variable @code{ERROR1} is defined. Or,
|
|---|
| 7991 |
|
|---|
| 7992 | @example
|
|---|
| 7993 | ERR = $(error found an error!)
|
|---|
| 7994 |
|
|---|
| 7995 | .PHONY: err
|
|---|
| 7996 | err: ; $(ERR)
|
|---|
| 7997 | @end example
|
|---|
| 7998 |
|
|---|
| 7999 | @noindent
|
|---|
| 8000 | will generate a fatal error while @code{make} is running, if the
|
|---|
| 8001 | @code{err} target is invoked.
|
|---|
| 8002 |
|
|---|
| 8003 | @item $(warning @var{text}@dots{})
|
|---|
| 8004 | @findex warning
|
|---|
| 8005 | @cindex warnings, printing
|
|---|
| 8006 | @cindex printing user warnings
|
|---|
| 8007 | This function works similarly to the @code{error} function, above,
|
|---|
| 8008 | except that @code{make} doesn't exit. Instead, @var{text} is expanded
|
|---|
| 8009 | and the resulting message is displayed, but processing of the makefile
|
|---|
| 8010 | continues.
|
|---|
| 8011 |
|
|---|
| 8012 | The result of the expansion of this function is the empty string.
|
|---|
| 8013 |
|
|---|
| 8014 | @item $(info @var{text}@dots{})
|
|---|
| 8015 | @findex info
|
|---|
| 8016 | @cindex printing messages
|
|---|
| 8017 | This function does nothing more than print its (expanded) argument(s)
|
|---|
| 8018 | to standard output. No makefile name or line number is added. The
|
|---|
| 8019 | result of the expansion of this function is the empty string.
|
|---|
| 8020 | @end table
|
|---|
| 8021 |
|
|---|
| 8022 | @node Shell Function, Guile Function, Make Control Functions, Functions
|
|---|
| 8023 | @section The @code{shell} Function
|
|---|
| 8024 | @findex shell
|
|---|
| 8025 | @cindex command expansion
|
|---|
| 8026 | @cindex backquotes
|
|---|
| 8027 | @cindex shell command, function for
|
|---|
| 8028 |
|
|---|
| 8029 | The @code{shell} function is unlike any other function other than the
|
|---|
| 8030 | @code{wildcard} function
|
|---|
| 8031 | (@pxref{Wildcard Function, ,The Function @code{wildcard}}) in that it
|
|---|
| 8032 | communicates with the world outside of @code{make}.
|
|---|
| 8033 |
|
|---|
| 8034 | The @code{shell} function performs the same function that backquotes
|
|---|
| 8035 | (@samp{`}) perform in most shells: it does @dfn{command expansion}.
|
|---|
| 8036 | This means that it takes as an argument a shell command and evaluates
|
|---|
| 8037 | to the output of the command. The only processing @code{make} does on
|
|---|
| 8038 | the result is to convert each newline (or carriage-return / newline
|
|---|
| 8039 | pair) to a single space. If there is a trailing (carriage-return
|
|---|
| 8040 | and) newline it will simply be removed.@refill
|
|---|
| 8041 |
|
|---|
| 8042 | The commands run by calls to the @code{shell} function are run when the
|
|---|
| 8043 | function calls are expanded (@pxref{Reading Makefiles, , How
|
|---|
| 8044 | @code{make} Reads a Makefile}). Because this function involves
|
|---|
| 8045 | spawning a new shell, you should carefully consider the performance
|
|---|
| 8046 | implications of using the @code{shell} function within recursively
|
|---|
| 8047 | expanded variables vs.@: simply expanded variables (@pxref{Flavors, ,The
|
|---|
| 8048 | Two Flavors of Variables}).
|
|---|
| 8049 |
|
|---|
| 8050 | @vindex .SHELLSTATUS
|
|---|
| 8051 | After the @code{shell} function or @samp{!=} assignment operator is
|
|---|
| 8052 | used, its exit status is placed in the @code{.SHELLSTATUS} variable.
|
|---|
| 8053 |
|
|---|
| 8054 | Here are some examples of the use of the @code{shell} function:
|
|---|
| 8055 |
|
|---|
| 8056 | @example
|
|---|
| 8057 | contents := $(shell cat foo)
|
|---|
| 8058 | @end example
|
|---|
| 8059 |
|
|---|
| 8060 | @noindent
|
|---|
| 8061 | sets @code{contents} to the contents of the file @file{foo}, with a space
|
|---|
| 8062 | (rather than a newline) separating each line.
|
|---|
| 8063 |
|
|---|
| 8064 | @example
|
|---|
| 8065 | files := $(shell echo *.c)
|
|---|
| 8066 | @end example
|
|---|
| 8067 |
|
|---|
| 8068 | @noindent
|
|---|
| 8069 | sets @code{files} to the expansion of @samp{*.c}. Unless @code{make} is
|
|---|
| 8070 | using a very strange shell, this has the same result as
|
|---|
| 8071 | @w{@samp{$(wildcard *.c)}} (as long as at least one @samp{.c} file
|
|---|
| 8072 | exists).@refill
|
|---|
| 8073 |
|
|---|
| 8074 | @node Guile Function, , Shell Function, Functions
|
|---|
| 8075 | @section The @code{guile} Function
|
|---|
| 8076 | @findex guile
|
|---|
| 8077 | @cindex Guile
|
|---|
| 8078 |
|
|---|
| 8079 | If GNU @code{make} is built with support for GNU Guile as an embedded
|
|---|
| 8080 | extension language then the @code{guile} function will be available.
|
|---|
| 8081 | The @code{guile} function takes one argument which is first expanded
|
|---|
| 8082 | by @code{make} in the normal fashion, then passed to the GNU Guile
|
|---|
| 8083 | evaluator. The result of the evaluator is converted into a string and
|
|---|
| 8084 | used as the expansion of the @code{guile} function in the makefile.
|
|---|
| 8085 | See @ref{Guile Integration, ,GNU Guile Integration} for details on
|
|---|
| 8086 | writing extensions to @code{make} in Guile.
|
|---|
| 8087 |
|
|---|
| 8088 | You can determine whether GNU Guile support is available by checking
|
|---|
| 8089 | the @code{.FEATURES} variable for the word @var{guile}.
|
|---|
| 8090 |
|
|---|
| 8091 | @node Running, Implicit Rules, Functions, Top
|
|---|
| 8092 | @chapter How to Run @code{make}
|
|---|
| 8093 |
|
|---|
| 8094 | A makefile that says how to recompile a program can be used in more
|
|---|
| 8095 | than one way. The simplest use is to recompile every file that is out
|
|---|
| 8096 | of date. Usually, makefiles are written so that if you run
|
|---|
| 8097 | @code{make} with no arguments, it does just that.
|
|---|
| 8098 |
|
|---|
| 8099 | But you might want to update only some of the files; you might want to use
|
|---|
| 8100 | a different compiler or different compiler options; you might want just to
|
|---|
| 8101 | find out which files are out of date without changing them.
|
|---|
| 8102 |
|
|---|
| 8103 | By giving arguments when you run @code{make}, you can do any of these
|
|---|
| 8104 | things and many others.
|
|---|
| 8105 |
|
|---|
| 8106 | @cindex exit status of make
|
|---|
| 8107 | The exit status of @code{make} is always one of three values:
|
|---|
| 8108 | @table @code
|
|---|
| 8109 | @item 0
|
|---|
| 8110 | The exit status is zero if @code{make} is successful.
|
|---|
| 8111 | @item 2
|
|---|
| 8112 | The exit status is two if @code{make} encounters any errors.
|
|---|
| 8113 | It will print messages describing the particular errors.
|
|---|
| 8114 | @item 1
|
|---|
| 8115 | The exit status is one if you use the @samp{-q} flag and @code{make}
|
|---|
| 8116 | determines that some target is not already up to date.
|
|---|
| 8117 | @xref{Instead of Execution, ,Instead of Executing Recipes}.
|
|---|
| 8118 | @end table
|
|---|
| 8119 |
|
|---|
| 8120 | @menu
|
|---|
| 8121 | * Makefile Arguments:: How to specify which makefile to use.
|
|---|
| 8122 | * Goals:: How to use goal arguments to specify which
|
|---|
| 8123 | parts of the makefile to use.
|
|---|
| 8124 | * Instead of Execution:: How to use mode flags to specify what
|
|---|
| 8125 | kind of thing to do with the recipes
|
|---|
| 8126 | in the makefile other than simply
|
|---|
| 8127 | execute them.
|
|---|
| 8128 | * Avoiding Compilation:: How to avoid recompiling certain files.
|
|---|
| 8129 | * Overriding:: How to override a variable to specify
|
|---|
| 8130 | an alternate compiler and other things.
|
|---|
| 8131 | * Testing:: How to proceed past some errors, to
|
|---|
| 8132 | test compilation.
|
|---|
| 8133 | * Options Summary:: Summary of Options
|
|---|
| 8134 | @end menu
|
|---|
| 8135 |
|
|---|
| 8136 | @node Makefile Arguments, Goals, Running, Running
|
|---|
| 8137 | @section Arguments to Specify the Makefile
|
|---|
| 8138 | @cindex @code{--file}
|
|---|
| 8139 | @cindex @code{--makefile}
|
|---|
| 8140 | @cindex @code{-f}
|
|---|
| 8141 |
|
|---|
| 8142 | The way to specify the name of the makefile is with the @samp{-f} or
|
|---|
| 8143 | @samp{--file} option (@samp{--makefile} also works). For example,
|
|---|
| 8144 | @samp{-f altmake} says to use the file @file{altmake} as the makefile.
|
|---|
| 8145 |
|
|---|
| 8146 | If you use the @samp{-f} flag several times and follow each @samp{-f}
|
|---|
| 8147 | with an argument, all the specified files are used jointly as
|
|---|
| 8148 | makefiles.
|
|---|
| 8149 |
|
|---|
| 8150 | If you do not use the @samp{-f} or @samp{--file} flag, the default is
|
|---|
| 8151 | to try @file{GNUmakefile}, @file{makefile}, and @file{Makefile}, in
|
|---|
| 8152 | that order, and use the first of these three which exists or can be made
|
|---|
| 8153 | (@pxref{Makefiles, ,Writing Makefiles}).@refill
|
|---|
| 8154 |
|
|---|
| 8155 | @node Goals, Instead of Execution, Makefile Arguments, Running
|
|---|
| 8156 | @section Arguments to Specify the Goals
|
|---|
| 8157 | @cindex goal, how to specify
|
|---|
| 8158 |
|
|---|
| 8159 | The @dfn{goals} are the targets that @code{make} should strive ultimately
|
|---|
| 8160 | to update. Other targets are updated as well if they appear as
|
|---|
| 8161 | prerequisites of goals, or prerequisites of prerequisites of goals, etc.
|
|---|
| 8162 |
|
|---|
| 8163 | By default, the goal is the first target in the makefile (not counting
|
|---|
| 8164 | targets that start with a period). Therefore, makefiles are usually
|
|---|
| 8165 | written so that the first target is for compiling the entire program or
|
|---|
| 8166 | programs they describe. If the first rule in the makefile has several
|
|---|
| 8167 | targets, only the first target in the rule becomes the default goal, not
|
|---|
| 8168 | the whole list. You can manage the selection of the default goal from
|
|---|
| 8169 | within your makefile using the @code{.DEFAULT_GOAL} variable
|
|---|
| 8170 | (@pxref{Special Variables, , Other Special Variables}).
|
|---|
| 8171 |
|
|---|
| 8172 | You can also specify a different goal or goals with command line
|
|---|
| 8173 | arguments to @code{make}. Use the name of the goal as an argument.
|
|---|
| 8174 | If you specify several goals, @code{make} processes each of them in
|
|---|
| 8175 | turn, in the order you name them.
|
|---|
| 8176 |
|
|---|
| 8177 | Any target in the makefile may be specified as a goal (unless it
|
|---|
| 8178 | starts with @samp{-} or contains an @samp{=}, in which case it will be
|
|---|
| 8179 | parsed as a switch or variable definition, respectively). Even
|
|---|
| 8180 | targets not in the makefile may be specified, if @code{make} can find
|
|---|
| 8181 | implicit rules that say how to make them.
|
|---|
| 8182 |
|
|---|
| 8183 | @vindex MAKECMDGOALS
|
|---|
| 8184 | @code{Make} will set the special variable @code{MAKECMDGOALS} to the
|
|---|
| 8185 | list of goals you specified on the command line. If no goals were given
|
|---|
| 8186 | on the command line, this variable is empty. Note that this variable
|
|---|
| 8187 | should be used only in special circumstances.
|
|---|
| 8188 |
|
|---|
| 8189 | An example of appropriate use is to avoid including @file{.d} files
|
|---|
| 8190 | during @code{clean} rules (@pxref{Automatic Prerequisites}), so
|
|---|
| 8191 | @code{make} won't create them only to immediately remove them
|
|---|
| 8192 | again:@refill
|
|---|
| 8193 |
|
|---|
| 8194 | @example
|
|---|
| 8195 | @group
|
|---|
| 8196 | sources = foo.c bar.c
|
|---|
| 8197 |
|
|---|
| 8198 | ifneq ($(MAKECMDGOALS),clean)
|
|---|
| 8199 | include $(sources:.c=.d)
|
|---|
| 8200 | endif
|
|---|
| 8201 | @end group
|
|---|
| 8202 | @end example
|
|---|
| 8203 |
|
|---|
| 8204 | One use of specifying a goal is if you want to compile only a part of
|
|---|
| 8205 | the program, or only one of several programs. Specify as a goal each
|
|---|
| 8206 | file that you wish to remake. For example, consider a directory containing
|
|---|
| 8207 | several programs, with a makefile that starts like this:
|
|---|
| 8208 |
|
|---|
| 8209 | @example
|
|---|
| 8210 | .PHONY: all
|
|---|
| 8211 | all: size nm ld ar as
|
|---|
| 8212 | @end example
|
|---|
| 8213 |
|
|---|
| 8214 | If you are working on the program @code{size}, you might want to say
|
|---|
| 8215 | @w{@samp{make size}} so that only the files of that program are recompiled.
|
|---|
| 8216 |
|
|---|
| 8217 | Another use of specifying a goal is to make files that are not normally
|
|---|
| 8218 | made. For example, there may be a file of debugging output, or a
|
|---|
| 8219 | version of the program that is compiled specially for testing, which has
|
|---|
| 8220 | a rule in the makefile but is not a prerequisite of the default goal.
|
|---|
| 8221 |
|
|---|
| 8222 | Another use of specifying a goal is to run the recipe associated with
|
|---|
| 8223 | a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty
|
|---|
| 8224 | Targets, ,Empty Target Files to Record Events}). Many makefiles contain
|
|---|
| 8225 | a phony target named @file{clean} which deletes everything except source
|
|---|
| 8226 | files. Naturally, this is done only if you request it explicitly with
|
|---|
| 8227 | @w{@samp{make clean}}. Following is a list of typical phony and empty
|
|---|
| 8228 | target names. @xref{Standard Targets}, for a detailed list of all the
|
|---|
| 8229 | standard target names which GNU software packages use.
|
|---|
| 8230 |
|
|---|
| 8231 | @table @file
|
|---|
| 8232 | @item all
|
|---|
| 8233 | @cindex @code{all} @r{(standard target)}
|
|---|
| 8234 | Make all the top-level targets the makefile knows about.
|
|---|
| 8235 |
|
|---|
| 8236 | @item clean
|
|---|
| 8237 | @cindex @code{clean} @r{(standard target)}
|
|---|
| 8238 | Delete all files that are normally created by running @code{make}.
|
|---|
| 8239 |
|
|---|
| 8240 | @item mostlyclean
|
|---|
| 8241 | @cindex @code{mostlyclean} @r{(standard target)}
|
|---|
| 8242 | Like @samp{clean}, but may refrain from deleting a few files that people
|
|---|
| 8243 | normally don't want to recompile. For example, the @samp{mostlyclean}
|
|---|
| 8244 | target for GCC does not delete @file{libgcc.a}, because recompiling it
|
|---|
| 8245 | is rarely necessary and takes a lot of time.
|
|---|
| 8246 |
|
|---|
| 8247 | @item distclean
|
|---|
| 8248 | @cindex @code{distclean} @r{(standard target)}
|
|---|
| 8249 | @itemx realclean
|
|---|
| 8250 | @cindex @code{realclean} @r{(standard target)}
|
|---|
| 8251 | @itemx clobber
|
|---|
| 8252 | @cindex @code{clobber} @r{(standard target)}
|
|---|
| 8253 | Any of these targets might be defined to delete @emph{more} files than
|
|---|
| 8254 | @samp{clean} does. For example, this would delete configuration files
|
|---|
| 8255 | or links that you would normally create as preparation for compilation,
|
|---|
| 8256 | even if the makefile itself cannot create these files.
|
|---|
| 8257 |
|
|---|
| 8258 | @item install
|
|---|
| 8259 | @cindex @code{install} @r{(standard target)}
|
|---|
| 8260 | Copy the executable file into a directory that users typically search
|
|---|
| 8261 | for commands; copy any auxiliary files that the executable uses into
|
|---|
| 8262 | the directories where it will look for them.
|
|---|
| 8263 |
|
|---|
| 8264 | @item print
|
|---|
| 8265 | @cindex @code{print} @r{(standard target)}
|
|---|
| 8266 | Print listings of the source files that have changed.
|
|---|
| 8267 |
|
|---|
| 8268 | @item tar
|
|---|
| 8269 | @cindex @code{tar} @r{(standard target)}
|
|---|
| 8270 | Create a tar file of the source files.
|
|---|
| 8271 |
|
|---|
| 8272 | @item shar
|
|---|
| 8273 | @cindex @code{shar} @r{(standard target)}
|
|---|
| 8274 | Create a shell archive (shar file) of the source files.
|
|---|
| 8275 |
|
|---|
| 8276 | @item dist
|
|---|
| 8277 | @cindex @code{dist} @r{(standard target)}
|
|---|
| 8278 | Create a distribution file of the source files. This might
|
|---|
| 8279 | be a tar file, or a shar file, or a compressed version of one of the
|
|---|
| 8280 | above, or even more than one of the above.
|
|---|
| 8281 |
|
|---|
| 8282 | @item TAGS
|
|---|
| 8283 | @cindex @code{TAGS} @r{(standard target)}
|
|---|
| 8284 | Update a tags table for this program.
|
|---|
| 8285 |
|
|---|
| 8286 | @item check
|
|---|
| 8287 | @cindex @code{check} @r{(standard target)}
|
|---|
| 8288 | @itemx test
|
|---|
| 8289 | @cindex @code{test} @r{(standard target)}
|
|---|
| 8290 | Perform self tests on the program this makefile builds.
|
|---|
| 8291 | @end table
|
|---|
| 8292 |
|
|---|
| 8293 | @node Instead of Execution, Avoiding Compilation, Goals, Running
|
|---|
| 8294 | @section Instead of Executing Recipes
|
|---|
| 8295 | @cindex execution, instead of
|
|---|
| 8296 | @cindex recipes, instead of executing
|
|---|
| 8297 |
|
|---|
| 8298 | The makefile tells @code{make} how to tell whether a target is up to date,
|
|---|
| 8299 | and how to update each target. But updating the targets is not always
|
|---|
| 8300 | what you want. Certain options specify other activities for @code{make}.
|
|---|
| 8301 |
|
|---|
| 8302 | @comment Extra blank lines make it print better.
|
|---|
| 8303 | @table @samp
|
|---|
| 8304 | @item -n
|
|---|
| 8305 | @itemx --just-print
|
|---|
| 8306 | @itemx --dry-run
|
|---|
| 8307 | @itemx --recon
|
|---|
| 8308 | @cindex @code{--just-print}
|
|---|
| 8309 | @cindex @code{--dry-run}
|
|---|
| 8310 | @cindex @code{--recon}
|
|---|
| 8311 | @cindex @code{-n}
|
|---|
| 8312 |
|
|---|
| 8313 | ``No-op''. Causes @code{make} to print the recipes that are needed to
|
|---|
| 8314 | make the targets up to date, but not actually execute them. Note that
|
|---|
| 8315 | some recipes are still executed, even with this flag (@pxref{MAKE
|
|---|
| 8316 | Variable, ,How the @code{MAKE} Variable Works}). Also any recipes
|
|---|
| 8317 | needed to update included makefiles are still executed
|
|---|
| 8318 | (@pxref{Remaking Makefiles, ,How Makefiles Are Remade}).
|
|---|
| 8319 |
|
|---|
| 8320 | @item -t
|
|---|
| 8321 | @itemx --touch
|
|---|
| 8322 | @cindex @code{--touch}
|
|---|
| 8323 | @cindex touching files
|
|---|
| 8324 | @cindex target, touching
|
|---|
| 8325 | @cindex @code{-t}
|
|---|
| 8326 |
|
|---|
| 8327 | ``Touch''. Marks targets as up to date without actually changing
|
|---|
| 8328 | them. In other words, @code{make} pretends to update the targets but
|
|---|
| 8329 | does not really change their contents; instead only their modified
|
|---|
| 8330 | times are updated.
|
|---|
| 8331 |
|
|---|
| 8332 | @item -q
|
|---|
| 8333 | @itemx --question
|
|---|
| 8334 | @cindex @code{--question}
|
|---|
| 8335 | @cindex @code{-q}
|
|---|
| 8336 | @cindex question mode
|
|---|
| 8337 |
|
|---|
| 8338 | ``Question''. Silently check whether the targets are up to date, but
|
|---|
| 8339 | do not execute recipes; the exit code shows whether any updates are
|
|---|
| 8340 | needed.
|
|---|
| 8341 |
|
|---|
| 8342 | @item -W @var{file}
|
|---|
| 8343 | @itemx --what-if=@var{file}
|
|---|
| 8344 | @itemx --assume-new=@var{file}
|
|---|
| 8345 | @itemx --new-file=@var{file}
|
|---|
| 8346 | @cindex @code{--what-if}
|
|---|
| 8347 | @cindex @code{-W}
|
|---|
| 8348 | @cindex @code{--assume-new}
|
|---|
| 8349 | @cindex @code{--new-file}
|
|---|
| 8350 | @cindex what if
|
|---|
| 8351 | @cindex files, assuming new
|
|---|
| 8352 |
|
|---|
| 8353 | ``What if''. Each @samp{-W} flag is followed by a file name. The given
|
|---|
| 8354 | files' modification times are recorded by @code{make} as being the present
|
|---|
| 8355 | time, although the actual modification times remain the same.
|
|---|
| 8356 | You can use the @samp{-W} flag in conjunction with the @samp{-n} flag
|
|---|
| 8357 | to see what would happen if you were to modify specific files.@refill
|
|---|
| 8358 | @end table
|
|---|
| 8359 |
|
|---|
| 8360 | With the @samp{-n} flag, @code{make} prints the recipe that it would
|
|---|
| 8361 | normally execute but usually does not execute it.
|
|---|
| 8362 |
|
|---|
| 8363 | With the @samp{-t} flag, @code{make} ignores the recipes in the rules
|
|---|
| 8364 | and uses (in effect) the command @code{touch} for each target that needs to
|
|---|
| 8365 | be remade. The @code{touch} command is also printed, unless @samp{-s} or
|
|---|
| 8366 | @code{.SILENT} is used. For speed, @code{make} does not actually invoke
|
|---|
| 8367 | the program @code{touch}. It does the work directly.
|
|---|
| 8368 |
|
|---|
| 8369 | With the @samp{-q} flag, @code{make} prints nothing and executes no
|
|---|
| 8370 | recipes, but the exit status code it returns is zero if and only if the
|
|---|
| 8371 | targets to be considered are already up to date. If the exit status is
|
|---|
| 8372 | one, then some updating needs to be done. If @code{make} encounters an
|
|---|
| 8373 | error, the exit status is two, so you can distinguish an error from a
|
|---|
| 8374 | target that is not up to date.
|
|---|
| 8375 |
|
|---|
| 8376 | It is an error to use more than one of these three flags in the same
|
|---|
| 8377 | invocation of @code{make}.
|
|---|
| 8378 |
|
|---|
| 8379 | @cindex +, and recipe execution
|
|---|
| 8380 | The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect recipe
|
|---|
| 8381 | lines that begin with @samp{+} characters or contain the strings
|
|---|
| 8382 | @samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing
|
|---|
| 8383 | the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}
|
|---|
| 8384 | is run regardless of these options. Other lines in the same rule are
|
|---|
| 8385 | not run unless they too begin with @samp{+} or contain @samp{$(MAKE)} or
|
|---|
| 8386 | @samp{$@{MAKE@}} (@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}.)
|
|---|
| 8387 |
|
|---|
| 8388 | @cindex phony targets and recipe execution
|
|---|
| 8389 | The @samp{-t} flag prevents phony targets (@pxref{Phony Targets}) from
|
|---|
| 8390 | being updated, unless there are recipe lines beginning with @samp{+}
|
|---|
| 8391 | or containing @samp{$(MAKE)} or @samp{$@{MAKE@}}.
|
|---|
| 8392 |
|
|---|
| 8393 | The @samp{-W} flag provides two features:
|
|---|
| 8394 |
|
|---|
| 8395 | @itemize @bullet
|
|---|
| 8396 | @item
|
|---|
| 8397 | If you also use the @samp{-n} or @samp{-q} flag, you can see what
|
|---|
| 8398 | @code{make} would do if you were to modify some files.
|
|---|
| 8399 |
|
|---|
| 8400 | @item
|
|---|
| 8401 | Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually
|
|---|
| 8402 | executing recipes, the @samp{-W} flag can direct @code{make} to act as
|
|---|
| 8403 | if some files had been modified, without actually running the recipes
|
|---|
| 8404 | for those files.@refill
|
|---|
| 8405 | @end itemize
|
|---|
| 8406 |
|
|---|
| 8407 | Note that the options @samp{-p} and @samp{-v} allow you to obtain other
|
|---|
| 8408 | information about @code{make} or about the makefiles in use
|
|---|
| 8409 | (@pxref{Options Summary, ,Summary of Options}).@refill
|
|---|
| 8410 |
|
|---|
| 8411 | @node Avoiding Compilation, Overriding, Instead of Execution, Running
|
|---|
| 8412 | @section Avoiding Recompilation of Some Files
|
|---|
| 8413 | @cindex @code{-o}
|
|---|
| 8414 | @cindex @code{--old-file}
|
|---|
| 8415 | @cindex @code{--assume-old}
|
|---|
| 8416 | @cindex files, assuming old
|
|---|
| 8417 | @cindex files, avoiding recompilation of
|
|---|
| 8418 | @cindex recompilation, avoiding
|
|---|
| 8419 |
|
|---|
| 8420 | Sometimes you may have changed a source file but you do not want to
|
|---|
| 8421 | recompile all the files that depend on it. For example, suppose you add
|
|---|
| 8422 | a macro or a declaration to a header file that many other files depend
|
|---|
| 8423 | on. Being conservative, @code{make} assumes that any change in the
|
|---|
| 8424 | header file requires recompilation of all dependent files, but you know
|
|---|
| 8425 | that they do not need to be recompiled and you would rather not waste
|
|---|
| 8426 | the time waiting for them to compile.
|
|---|
| 8427 |
|
|---|
| 8428 | If you anticipate the problem before changing the header file, you can
|
|---|
| 8429 | use the @samp{-t} flag. This flag tells @code{make} not to run the
|
|---|
| 8430 | recipes in the rules, but rather to mark the target up to date by
|
|---|
| 8431 | changing its last-modification date. You would follow this procedure:
|
|---|
| 8432 |
|
|---|
| 8433 | @enumerate
|
|---|
| 8434 | @item
|
|---|
| 8435 | Use the command @samp{make} to recompile the source files that really
|
|---|
| 8436 | need recompilation, ensuring that the object files are up-to-date
|
|---|
| 8437 | before you begin.
|
|---|
| 8438 |
|
|---|
| 8439 | @item
|
|---|
| 8440 | Make the changes in the header files.
|
|---|
| 8441 |
|
|---|
| 8442 | @item
|
|---|
| 8443 | Use the command @samp{make -t} to mark all the object files as
|
|---|
| 8444 | up to date. The next time you run @code{make}, the changes in the
|
|---|
| 8445 | header files will not cause any recompilation.
|
|---|
| 8446 | @end enumerate
|
|---|
| 8447 |
|
|---|
| 8448 | If you have already changed the header file at a time when some files
|
|---|
| 8449 | do need recompilation, it is too late to do this. Instead, you can
|
|---|
| 8450 | use the @w{@samp{-o @var{file}}} flag, which marks a specified file as
|
|---|
| 8451 | ``old'' (@pxref{Options Summary, ,Summary of Options}). This means
|
|---|
| 8452 | that the file itself will not be remade, and nothing else will be
|
|---|
| 8453 | remade on its account. Follow this procedure:
|
|---|
| 8454 |
|
|---|
| 8455 | @enumerate
|
|---|
| 8456 | @item
|
|---|
| 8457 | Recompile the source files that need compilation for reasons independent
|
|---|
| 8458 | of the particular header file, with @samp{make -o @var{headerfile}}.
|
|---|
| 8459 | If several header files are involved, use a separate @samp{-o} option
|
|---|
| 8460 | for each header file.
|
|---|
| 8461 |
|
|---|
| 8462 | @item
|
|---|
| 8463 | Touch all the object files with @samp{make -t}.
|
|---|
| 8464 | @end enumerate
|
|---|
| 8465 |
|
|---|
| 8466 | @node Overriding, Testing, Avoiding Compilation, Running
|
|---|
| 8467 | @section Overriding Variables
|
|---|
| 8468 | @cindex overriding variables with arguments
|
|---|
| 8469 | @cindex variables, overriding with arguments
|
|---|
| 8470 | @cindex command line variables
|
|---|
| 8471 | @cindex variables, command line
|
|---|
| 8472 |
|
|---|
| 8473 | An argument that contains @samp{=} specifies the value of a variable:
|
|---|
| 8474 | @samp{@var{v}=@var{x}} sets the value of the variable @var{v} to @var{x}.
|
|---|
| 8475 | If you specify a value in this way, all ordinary assignments of the same
|
|---|
| 8476 | variable in the makefile are ignored; we say they have been
|
|---|
| 8477 | @dfn{overridden} by the command line argument.
|
|---|
| 8478 |
|
|---|
| 8479 | The most common way to use this facility is to pass extra flags to
|
|---|
| 8480 | compilers. For example, in a properly written makefile, the variable
|
|---|
| 8481 | @code{CFLAGS} is included in each recipe that runs the C compiler, so a
|
|---|
| 8482 | file @file{foo.c} would be compiled something like this:
|
|---|
| 8483 |
|
|---|
| 8484 | @example
|
|---|
| 8485 | cc -c $(CFLAGS) foo.c
|
|---|
| 8486 | @end example
|
|---|
| 8487 |
|
|---|
| 8488 | Thus, whatever value you set for @code{CFLAGS} affects each compilation
|
|---|
| 8489 | that occurs. The makefile probably specifies the usual value for
|
|---|
| 8490 | @code{CFLAGS}, like this:
|
|---|
| 8491 |
|
|---|
| 8492 | @example
|
|---|
| 8493 | CFLAGS=-g
|
|---|
| 8494 | @end example
|
|---|
| 8495 |
|
|---|
| 8496 | Each time you run @code{make}, you can override this value if you
|
|---|
| 8497 | wish. For example, if you say @samp{make CFLAGS='-g -O'}, each C
|
|---|
| 8498 | compilation will be done with @samp{cc -c -g -O}. (This also
|
|---|
| 8499 | illustrates how you can use quoting in the shell to enclose spaces and
|
|---|
| 8500 | other special characters in the value of a variable when you override
|
|---|
| 8501 | it.)
|
|---|
| 8502 |
|
|---|
| 8503 | The variable @code{CFLAGS} is only one of many standard variables that
|
|---|
| 8504 | exist just so that you can change them this way. @xref{Implicit
|
|---|
| 8505 | Variables, , Variables Used by Implicit Rules}, for a complete list.
|
|---|
| 8506 |
|
|---|
| 8507 | You can also program the makefile to look at additional variables of your
|
|---|
| 8508 | own, giving the user the ability to control other aspects of how the
|
|---|
| 8509 | makefile works by changing the variables.
|
|---|
| 8510 |
|
|---|
| 8511 | When you override a variable with a command line argument, you can
|
|---|
| 8512 | define either a recursively-expanded variable or a simply-expanded
|
|---|
| 8513 | variable. The examples shown above make a recursively-expanded
|
|---|
| 8514 | variable; to make a simply-expanded variable, write @samp{:=} or
|
|---|
| 8515 | @samp{::=} instead of @samp{=}. But, unless you want to include a
|
|---|
| 8516 | variable reference or function call in the @emph{value} that you
|
|---|
| 8517 | specify, it makes no difference which kind of variable you create.
|
|---|
| 8518 |
|
|---|
| 8519 | There is one way that the makefile can change a variable that you have
|
|---|
| 8520 | overridden. This is to use the @code{override} directive, which is a line
|
|---|
| 8521 | that looks like this: @samp{override @var{variable} = @var{value}}
|
|---|
| 8522 | (@pxref{Override Directive, ,The @code{override} Directive}).
|
|---|
| 8523 |
|
|---|
| 8524 | @node Testing, Options Summary, Overriding, Running
|
|---|
| 8525 | @section Testing the Compilation of a Program
|
|---|
| 8526 | @cindex testing compilation
|
|---|
| 8527 | @cindex compilation, testing
|
|---|
| 8528 |
|
|---|
| 8529 | Normally, when an error happens in executing a shell command, @code{make}
|
|---|
| 8530 | gives up immediately, returning a nonzero status. No further recipes are
|
|---|
| 8531 | executed for any target. The error implies that the goal cannot be
|
|---|
| 8532 | correctly remade, and @code{make} reports this as soon as it knows.
|
|---|
| 8533 |
|
|---|
| 8534 | When you are compiling a program that you have just changed, this is not
|
|---|
| 8535 | what you want. Instead, you would rather that @code{make} try compiling
|
|---|
| 8536 | every file that can be tried, to show you as many compilation errors
|
|---|
| 8537 | as possible.
|
|---|
| 8538 |
|
|---|
| 8539 | @cindex @code{-k}
|
|---|
| 8540 | @cindex @code{--keep-going}
|
|---|
| 8541 | On these occasions, you should use the @samp{-k} or
|
|---|
| 8542 | @samp{--keep-going} flag. This tells @code{make} to continue to
|
|---|
| 8543 | consider the other prerequisites of the pending targets, remaking them
|
|---|
| 8544 | if necessary, before it gives up and returns nonzero status. For
|
|---|
| 8545 | example, after an error in compiling one object file, @samp{make -k}
|
|---|
| 8546 | will continue compiling other object files even though it already
|
|---|
| 8547 | knows that linking them will be impossible. In addition to continuing
|
|---|
| 8548 | after failed shell commands, @samp{make -k} will continue as much as
|
|---|
| 8549 | possible after discovering that it does not know how to make a target
|
|---|
| 8550 | or prerequisite file. This will always cause an error message, but
|
|---|
| 8551 | without @samp{-k}, it is a fatal error (@pxref{Options Summary,
|
|---|
| 8552 | ,Summary of Options}).@refill
|
|---|
| 8553 |
|
|---|
| 8554 | The usual behavior of @code{make} assumes that your purpose is to get the
|
|---|
| 8555 | goals up to date; once @code{make} learns that this is impossible, it might
|
|---|
| 8556 | as well report the failure immediately. The @samp{-k} flag says that the
|
|---|
| 8557 | real purpose is to test as much as possible of the changes made in the
|
|---|
| 8558 | program, perhaps to find several independent problems so that you can
|
|---|
| 8559 | correct them all before the next attempt to compile. This is why Emacs'
|
|---|
| 8560 | @kbd{M-x compile} command passes the @samp{-k} flag by default.
|
|---|
| 8561 |
|
|---|
| 8562 | @node Options Summary, , Testing, Running
|
|---|
| 8563 | @section Summary of Options
|
|---|
| 8564 | @cindex options
|
|---|
| 8565 | @cindex flags
|
|---|
| 8566 | @cindex switches
|
|---|
| 8567 |
|
|---|
| 8568 | Here is a table of all the options @code{make} understands:
|
|---|
| 8569 |
|
|---|
| 8570 | @table @samp
|
|---|
| 8571 | @item -b
|
|---|
| 8572 | @cindex @code{-b}
|
|---|
| 8573 | @itemx -m
|
|---|
| 8574 | @cindex @code{-m}
|
|---|
| 8575 | These options are ignored for compatibility with other versions of @code{make}.
|
|---|
| 8576 |
|
|---|
| 8577 | @item -B
|
|---|
| 8578 | @cindex @code{-B}
|
|---|
| 8579 | @itemx --always-make
|
|---|
| 8580 | @cindex @code{--always-make}
|
|---|
| 8581 | Consider all targets out-of-date. GNU @code{make} proceeds to
|
|---|
| 8582 | consider targets and their prerequisites using the normal algorithms;
|
|---|
| 8583 | however, all targets so considered are always remade regardless of the
|
|---|
| 8584 | status of their prerequisites. To avoid infinite recursion, if
|
|---|
| 8585 | @code{MAKE_RESTARTS} (@pxref{Special Variables, , Other Special
|
|---|
| 8586 | Variables}) is set to a number greater than 0 this option is disabled
|
|---|
| 8587 | when considering whether to remake makefiles (@pxref{Remaking
|
|---|
| 8588 | Makefiles, , How Makefiles Are Remade}).
|
|---|
| 8589 |
|
|---|
| 8590 | @item -C @var{dir}
|
|---|
| 8591 | @cindex @code{-C}
|
|---|
| 8592 | @itemx --directory=@var{dir}
|
|---|
| 8593 | @cindex @code{--directory}
|
|---|
| 8594 | Change to directory @var{dir} before reading the makefiles. If multiple
|
|---|
| 8595 | @samp{-C} options are specified, each is interpreted relative to the
|
|---|
| 8596 | previous one: @samp{-C / -C etc} is equivalent to @samp{-C /etc}.
|
|---|
| 8597 | This is typically used with recursive invocations of @code{make}
|
|---|
| 8598 | (@pxref{Recursion, ,Recursive Use of @code{make}}).
|
|---|
| 8599 |
|
|---|
| 8600 | @item -d
|
|---|
| 8601 | @cindex @code{-d}
|
|---|
| 8602 | @c Extra blank line here makes the table look better.
|
|---|
| 8603 |
|
|---|
| 8604 | Print debugging information in addition to normal processing. The
|
|---|
| 8605 | debugging information says which files are being considered for
|
|---|
| 8606 | remaking, which file-times are being compared and with what results,
|
|---|
| 8607 | which files actually need to be remade, which implicit rules are
|
|---|
| 8608 | considered and which are applied---everything interesting about how
|
|---|
| 8609 | @code{make} decides what to do. The @code{-d} option is equivalent to
|
|---|
| 8610 | @samp{--debug=a} (see below).
|
|---|
| 8611 |
|
|---|
| 8612 | @item --debug[=@var{options}]
|
|---|
| 8613 | @cindex @code{--debug}
|
|---|
| 8614 | @c Extra blank line here makes the table look better.
|
|---|
| 8615 |
|
|---|
| 8616 | Print debugging information in addition to normal processing. Various
|
|---|
| 8617 | levels and types of output can be chosen. With no arguments, print the
|
|---|
| 8618 | ``basic'' level of debugging. Possible arguments are below; only the
|
|---|
| 8619 | first character is considered, and values must be comma- or
|
|---|
| 8620 | space-separated.
|
|---|
| 8621 |
|
|---|
| 8622 | @table @code
|
|---|
| 8623 | @item a (@i{all})
|
|---|
| 8624 | All types of debugging output are enabled. This is equivalent to using
|
|---|
| 8625 | @samp{-d}.
|
|---|
| 8626 |
|
|---|
| 8627 | @item b (@i{basic})
|
|---|
| 8628 | Basic debugging prints each target that was found to be out-of-date, and
|
|---|
| 8629 | whether the build was successful or not.
|
|---|
| 8630 |
|
|---|
| 8631 | @item v (@i{verbose})
|
|---|
| 8632 | A level above @samp{basic}; includes messages about which makefiles were
|
|---|
| 8633 | parsed, prerequisites that did not need to be rebuilt, etc. This option
|
|---|
| 8634 | also enables @samp{basic} messages.
|
|---|
| 8635 |
|
|---|
| 8636 | @item i (@i{implicit})
|
|---|
| 8637 | Prints messages describing the implicit rule searches for each target.
|
|---|
| 8638 | This option also enables @samp{basic} messages.
|
|---|
| 8639 |
|
|---|
| 8640 | @item j (@i{jobs})
|
|---|
| 8641 | Prints messages giving details on the invocation of specific sub-commands.
|
|---|
| 8642 |
|
|---|
| 8643 | @item m (@i{makefile})
|
|---|
| 8644 | By default, the above messages are not enabled while trying to remake
|
|---|
| 8645 | the makefiles. This option enables messages while rebuilding makefiles,
|
|---|
| 8646 | too. Note that the @samp{all} option does enable this option. This
|
|---|
| 8647 | option also enables @samp{basic} messages.
|
|---|
| 8648 |
|
|---|
| 8649 | @item n (@i{none})
|
|---|
| 8650 | Disable all debugging currently enabled. If additional debugging
|
|---|
| 8651 | flags are encountered after this they will still take effect.
|
|---|
| 8652 | @end table
|
|---|
| 8653 |
|
|---|
| 8654 | @item -e
|
|---|
| 8655 | @cindex @code{-e}
|
|---|
| 8656 | @itemx --environment-overrides
|
|---|
| 8657 | @cindex @code{--environment-overrides}
|
|---|
| 8658 | Give variables taken from the environment precedence
|
|---|
| 8659 | over variables from makefiles.
|
|---|
| 8660 | @xref{Environment, ,Variables from the Environment}.
|
|---|
| 8661 |
|
|---|
| 8662 | @item --eval=@var{string}
|
|---|
| 8663 | @cindex @code{--eval}
|
|---|
| 8664 | @c Extra blank line here makes the table look better.
|
|---|
| 8665 |
|
|---|
| 8666 | Evaluate @var{string} as makefile syntax. This is a command-line
|
|---|
| 8667 | version of the @code{eval} function (@pxref{Eval Function}). The
|
|---|
| 8668 | evaluation is performed after the default rules and variables have
|
|---|
| 8669 | been defined, but before any makefiles are read.
|
|---|
| 8670 |
|
|---|
| 8671 | @item -f @var{file}
|
|---|
| 8672 | @cindex @code{-f}
|
|---|
| 8673 | @itemx --file=@var{file}
|
|---|
| 8674 | @cindex @code{--file}
|
|---|
| 8675 | @itemx --makefile=@var{file}
|
|---|
| 8676 | @cindex @code{--makefile}
|
|---|
| 8677 | Read the file named @var{file} as a makefile.
|
|---|
| 8678 | @xref{Makefiles, ,Writing Makefiles}.
|
|---|
| 8679 |
|
|---|
| 8680 | @item -h
|
|---|
| 8681 | @cindex @code{-h}
|
|---|
| 8682 | @itemx --help
|
|---|
| 8683 | @cindex @code{--help}
|
|---|
| 8684 | @c Extra blank line here makes the table look better.
|
|---|
| 8685 |
|
|---|
| 8686 | Remind you of the options that @code{make} understands and then exit.
|
|---|
| 8687 |
|
|---|
| 8688 | @item -i
|
|---|
| 8689 | @cindex @code{-i}
|
|---|
| 8690 | @itemx --ignore-errors
|
|---|
| 8691 | @cindex @code{--ignore-errors}
|
|---|
| 8692 | Ignore all errors in recipes executed to remake files.
|
|---|
| 8693 | @xref{Errors, ,Errors in Recipes}.
|
|---|
| 8694 |
|
|---|
| 8695 | @item -I @var{dir}
|
|---|
| 8696 | @cindex @code{-I}
|
|---|
| 8697 | @itemx --include-dir=@var{dir}
|
|---|
| 8698 | @cindex @code{--include-dir}
|
|---|
| 8699 | Specifies a directory @var{dir} to search for included makefiles.
|
|---|
| 8700 | @xref{Include, ,Including Other Makefiles}. If several @samp{-I}
|
|---|
| 8701 | options are used to specify several directories, the directories are
|
|---|
| 8702 | searched in the order specified.
|
|---|
| 8703 |
|
|---|
| 8704 | @item -j [@var{jobs}]
|
|---|
| 8705 | @cindex @code{-j}
|
|---|
| 8706 | @itemx --jobs[=@var{jobs}]
|
|---|
| 8707 | @cindex @code{--jobs}
|
|---|
| 8708 | Specifies the number of recipes (jobs) to run simultaneously. With no
|
|---|
| 8709 | argument, @code{make} runs as many recipes simultaneously as possible.
|
|---|
| 8710 | If there is more than one @samp{-j} option, the last one is effective.
|
|---|
| 8711 | @xref{Parallel, ,Parallel Execution}, for more information on how
|
|---|
| 8712 | recipes are run. Note that this option is ignored on MS-DOS.
|
|---|
| 8713 |
|
|---|
| 8714 | @item -k
|
|---|
| 8715 | @cindex @code{-k}
|
|---|
| 8716 | @itemx --keep-going
|
|---|
| 8717 | @cindex @code{--keep-going}
|
|---|
| 8718 | Continue as much as possible after an error. While the target that
|
|---|
| 8719 | failed, and those that depend on it, cannot be remade, the other
|
|---|
| 8720 | prerequisites of these targets can be processed all the same.
|
|---|
| 8721 | @xref{Testing, ,Testing the Compilation of a Program}.
|
|---|
| 8722 |
|
|---|
| 8723 | @item -l [@var{load}]
|
|---|
| 8724 | @cindex @code{-l}
|
|---|
| 8725 | @itemx --load-average[=@var{load}]
|
|---|
| 8726 | @cindex @code{--load-average}
|
|---|
| 8727 | @itemx --max-load[=@var{load}]
|
|---|
| 8728 | @cindex @code{--max-load}
|
|---|
| 8729 | Specifies that no new recipes should be started if there are other
|
|---|
| 8730 | recipes running and the load average is at least @var{load} (a
|
|---|
| 8731 | floating-point number). With no argument, removes a previous load
|
|---|
| 8732 | limit. @xref{Parallel, ,Parallel Execution}.
|
|---|
| 8733 |
|
|---|
| 8734 | @item -L
|
|---|
| 8735 | @cindex @code{-L}
|
|---|
| 8736 | @itemx --check-symlink-times
|
|---|
| 8737 | @cindex @code{--check-symlink-times}
|
|---|
| 8738 | On systems that support symbolic links, this option causes @code{make}
|
|---|
| 8739 | to consider the timestamps on any symbolic links in addition to the
|
|---|
| 8740 | timestamp on the file referenced by those links. When this option is
|
|---|
| 8741 | provided, the most recent timestamp among the file and the symbolic
|
|---|
| 8742 | links is taken as the modification time for this target file.
|
|---|
| 8743 |
|
|---|
| 8744 | @item -n
|
|---|
| 8745 | @cindex @code{-n}
|
|---|
| 8746 | @itemx --just-print
|
|---|
| 8747 | @cindex @code{--just-print}
|
|---|
| 8748 | @itemx --dry-run
|
|---|
| 8749 | @cindex @code{--dry-run}
|
|---|
| 8750 | @itemx --recon
|
|---|
| 8751 | @cindex @code{--recon}
|
|---|
| 8752 | @c Extra blank line here makes the table look better.
|
|---|
| 8753 |
|
|---|
| 8754 | Print the recipe that would be executed, but do not execute it (except
|
|---|
| 8755 | in certain circumstances).
|
|---|
| 8756 | @xref{Instead of Execution, ,Instead of Executing Recipes}.
|
|---|
| 8757 |
|
|---|
| 8758 | @item -o @var{file}
|
|---|
| 8759 | @cindex @code{-o}
|
|---|
| 8760 | @itemx --old-file=@var{file}
|
|---|
| 8761 | @cindex @code{--old-file}
|
|---|
| 8762 | @itemx --assume-old=@var{file}
|
|---|
| 8763 | @cindex @code{--assume-old}
|
|---|
| 8764 | Do not remake the file @var{file} even if it is older than its
|
|---|
| 8765 | prerequisites, and do not remake anything on account of changes in
|
|---|
| 8766 | @var{file}. Essentially the file is treated as very old and its rules
|
|---|
| 8767 | are ignored. @xref{Avoiding Compilation, ,Avoiding Recompilation of
|
|---|
| 8768 | Some Files}.@refill
|
|---|
| 8769 |
|
|---|
| 8770 | @item -O[@var{type}]
|
|---|
| 8771 | @cindex @code{-O}
|
|---|
| 8772 | @itemx --output-sync[=@var{type}]
|
|---|
| 8773 | @cindex @code{--output-sync}
|
|---|
| 8774 | @cindex output during parallel execution
|
|---|
| 8775 | @cindex parallel execution, output during
|
|---|
| 8776 | Ensure that the complete output from each recipe is printed in one
|
|---|
| 8777 | uninterrupted sequence. This option is only useful when using the
|
|---|
| 8778 | @code{--jobs} option to run multiple recipes simultaneously
|
|---|
| 8779 | (@pxref{Parallel, ,Parallel Execution}) Without this option output
|
|---|
| 8780 | will be displayed as it is generated by the recipes.@refill
|
|---|
| 8781 |
|
|---|
| 8782 | With no type or the type @samp{target}, output from the entire recipe
|
|---|
| 8783 | of each target is grouped together. With the type @samp{line}, output
|
|---|
| 8784 | from each line in the recipe is grouped together. With the type
|
|---|
| 8785 | @samp{recurse}, the output from an entire recursive make is grouped
|
|---|
| 8786 | together. With the type @samp{none}, no output synchronization is
|
|---|
| 8787 | performed. @xref{Parallel Output, ,Output During Parallel Execution}.
|
|---|
| 8788 |
|
|---|
| 8789 | @item -p
|
|---|
| 8790 | @cindex @code{-p}
|
|---|
| 8791 | @itemx --print-data-base
|
|---|
| 8792 | @cindex @code{--print-data-base}
|
|---|
| 8793 | @cindex data base of @code{make} rules
|
|---|
| 8794 | @cindex predefined rules and variables, printing
|
|---|
| 8795 | Print the data base (rules and variable values) that results from
|
|---|
| 8796 | reading the makefiles; then execute as usual or as otherwise
|
|---|
| 8797 | specified. This also prints the version information given by the
|
|---|
| 8798 | @samp{-v} switch (see below). To print the data base without trying
|
|---|
| 8799 | to remake any files, use @w{@samp{make -qp}}. To print the data base
|
|---|
| 8800 | of predefined rules and variables, use @w{@samp{make -p -f /dev/null}}.
|
|---|
| 8801 | The data base output contains file name and line number information for
|
|---|
| 8802 | recipe and variable definitions, so it can be a useful debugging tool
|
|---|
| 8803 | in complex environments.
|
|---|
| 8804 |
|
|---|
| 8805 | @item -q
|
|---|
| 8806 | @cindex @code{-q}
|
|---|
| 8807 | @itemx --question
|
|---|
| 8808 | @cindex @code{--question}
|
|---|
| 8809 | ``Question mode''. Do not run any recipes, or print anything; just
|
|---|
| 8810 | return an exit status that is zero if the specified targets are already
|
|---|
| 8811 | up to date, one if any remaking is required, or two if an error is
|
|---|
| 8812 | encountered. @xref{Instead of Execution, ,Instead of Executing
|
|---|
| 8813 | Recipes}.@refill
|
|---|
| 8814 |
|
|---|
| 8815 | @item -r
|
|---|
| 8816 | @cindex @code{-r}
|
|---|
| 8817 | @itemx --no-builtin-rules
|
|---|
| 8818 | @cindex @code{--no-builtin-rules}
|
|---|
| 8819 | Eliminate use of the built-in implicit rules (@pxref{Implicit Rules,
|
|---|
| 8820 | ,Using Implicit Rules}). You can still define your own by writing
|
|---|
| 8821 | pattern rules (@pxref{Pattern Rules, ,Defining and Redefining Pattern
|
|---|
| 8822 | Rules}). The @samp{-r} option also clears out the default list of
|
|---|
| 8823 | suffixes for suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix
|
|---|
| 8824 | Rules}). But you can still define your own suffixes with a rule for
|
|---|
| 8825 | @code{.SUFFIXES}, and then define your own suffix rules. Note that only
|
|---|
| 8826 | @emph{rules} are affected by the @code{-r} option; default variables
|
|---|
| 8827 | remain in effect (@pxref{Implicit Variables, ,Variables Used by Implicit
|
|---|
| 8828 | Rules}); see the @samp{-R} option below.
|
|---|
| 8829 |
|
|---|
| 8830 | @item -R
|
|---|
| 8831 | @cindex @code{-R}
|
|---|
| 8832 | @itemx --no-builtin-variables
|
|---|
| 8833 | @cindex @code{--no-builtin-variables}
|
|---|
| 8834 | Eliminate use of the built-in rule-specific variables (@pxref{Implicit
|
|---|
| 8835 | Variables, ,Variables Used by Implicit Rules}). You can still define
|
|---|
| 8836 | your own, of course. The @samp{-R} option also automatically enables
|
|---|
| 8837 | the @samp{-r} option (see above), since it doesn't make sense to have
|
|---|
| 8838 | implicit rules without any definitions for the variables that they use.
|
|---|
| 8839 |
|
|---|
| 8840 | @item -s
|
|---|
| 8841 | @cindex @code{-s}
|
|---|
| 8842 | @itemx --silent
|
|---|
| 8843 | @cindex @code{--silent}
|
|---|
| 8844 | @itemx --quiet
|
|---|
| 8845 | @cindex @code{--quiet}
|
|---|
| 8846 | @c Extra blank line here makes the table look better.
|
|---|
| 8847 |
|
|---|
| 8848 | Silent operation; do not print the recipes as they are executed.
|
|---|
| 8849 | @xref{Echoing, ,Recipe Echoing}.
|
|---|
| 8850 |
|
|---|
| 8851 | @item -S
|
|---|
| 8852 | @cindex @code{-S}
|
|---|
| 8853 | @itemx --no-keep-going
|
|---|
| 8854 | @cindex @code{--no-keep-going}
|
|---|
| 8855 | @itemx --stop
|
|---|
| 8856 | @cindex @code{--stop}
|
|---|
| 8857 | @c Extra blank line here makes the table look better.
|
|---|
| 8858 |
|
|---|
| 8859 | Cancel the effect of the @samp{-k} option. This is never necessary
|
|---|
| 8860 | except in a recursive @code{make} where @samp{-k} might be inherited
|
|---|
| 8861 | from the top-level @code{make} via @code{MAKEFLAGS}
|
|---|
| 8862 | (@pxref{Recursion, ,Recursive Use of @code{make}})
|
|---|
| 8863 | or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill
|
|---|
| 8864 |
|
|---|
| 8865 | @item -t
|
|---|
| 8866 | @cindex @code{-t}
|
|---|
| 8867 | @itemx --touch
|
|---|
| 8868 | @cindex @code{--touch}
|
|---|
| 8869 | @c Extra blank line here makes the table look better.
|
|---|
| 8870 |
|
|---|
| 8871 | Touch files (mark them up to date without really changing them)
|
|---|
| 8872 | instead of running their recipes. This is used to pretend that the
|
|---|
| 8873 | recipes were done, in order to fool future invocations of
|
|---|
| 8874 | @code{make}. @xref{Instead of Execution, ,Instead of Executing Recipes}.
|
|---|
| 8875 |
|
|---|
| 8876 | @item --trace
|
|---|
| 8877 | @cindex @code{--trace}
|
|---|
| 8878 | Show tracing information for @code{make} execution. Prints the entire
|
|---|
| 8879 | recipe to be executed, even for recipes that are normally silent (due
|
|---|
| 8880 | to @code{.SILENT} or @samp{@@}). Also prints the makefile name and
|
|---|
| 8881 | line number where the recipe was defined, and information on why the
|
|---|
| 8882 | target is being rebuilt.
|
|---|
| 8883 |
|
|---|
| 8884 | @item -v
|
|---|
| 8885 | @cindex @code{-v}
|
|---|
| 8886 | @itemx --version
|
|---|
| 8887 | @cindex @code{--version}
|
|---|
| 8888 | Print the version of the @code{make} program plus a copyright, a list
|
|---|
| 8889 | of authors, and a notice that there is no warranty; then exit.
|
|---|
| 8890 |
|
|---|
| 8891 | @item -w
|
|---|
| 8892 | @cindex @code{-w}
|
|---|
| 8893 | @itemx --print-directory
|
|---|
| 8894 | @cindex @code{--print-directory}
|
|---|
| 8895 | Print a message containing the working directory both before and after
|
|---|
| 8896 | executing the makefile. This may be useful for tracking down errors
|
|---|
| 8897 | from complicated nests of recursive @code{make} commands.
|
|---|
| 8898 | @xref{Recursion, ,Recursive Use of @code{make}}. (In practice, you
|
|---|
| 8899 | rarely need to specify this option since @samp{make} does it for you;
|
|---|
| 8900 | see @ref{-w Option, ,The @samp{--print-directory} Option}.)
|
|---|
| 8901 |
|
|---|
| 8902 | @item --no-print-directory
|
|---|
| 8903 | @cindex @code{--no-print-directory}
|
|---|
| 8904 | Disable printing of the working directory under @code{-w}.
|
|---|
| 8905 | This option is useful when @code{-w} is turned on automatically,
|
|---|
| 8906 | but you do not want to see the extra messages.
|
|---|
| 8907 | @xref{-w Option, ,The @samp{--print-directory} Option}.
|
|---|
| 8908 |
|
|---|
| 8909 | @item -W @var{file}
|
|---|
| 8910 | @cindex @code{-W}
|
|---|
| 8911 | @itemx --what-if=@var{file}
|
|---|
| 8912 | @cindex @code{--what-if}
|
|---|
| 8913 | @itemx --new-file=@var{file}
|
|---|
| 8914 | @cindex @code{--new-file}
|
|---|
| 8915 | @itemx --assume-new=@var{file}
|
|---|
| 8916 | @cindex @code{--assume-new}
|
|---|
| 8917 | Pretend that the target @var{file} has just been modified. When used
|
|---|
| 8918 | with the @samp{-n} flag, this shows you what would happen if you were
|
|---|
| 8919 | to modify that file. Without @samp{-n}, it is almost the same as
|
|---|
| 8920 | running a @code{touch} command on the given file before running
|
|---|
| 8921 | @code{make}, except that the modification time is changed only in the
|
|---|
| 8922 | imagination of @code{make}.
|
|---|
| 8923 | @xref{Instead of Execution, ,Instead of Executing Recipes}.
|
|---|
| 8924 |
|
|---|
| 8925 | @item --warn-undefined-variables
|
|---|
| 8926 | @cindex @code{--warn-undefined-variables}
|
|---|
| 8927 | @cindex variables, warning for undefined
|
|---|
| 8928 | @cindex undefined variables, warning message
|
|---|
| 8929 | Issue a warning message whenever @code{make} sees a reference to an
|
|---|
| 8930 | undefined variable. This can be helpful when you are trying to debug
|
|---|
| 8931 | makefiles which use variables in complex ways.
|
|---|
| 8932 | @end table
|
|---|
| 8933 |
|
|---|
| 8934 | @node Implicit Rules, Archives, Running, Top
|
|---|
| 8935 | @chapter Using Implicit Rules
|
|---|
| 8936 | @cindex implicit rule
|
|---|
| 8937 | @cindex rule, implicit
|
|---|
| 8938 |
|
|---|
| 8939 | Certain standard ways of remaking target files are used very often. For
|
|---|
| 8940 | example, one customary way to make an object file is from a C source file
|
|---|
| 8941 | using the C compiler, @code{cc}.
|
|---|
| 8942 |
|
|---|
| 8943 | @dfn{Implicit rules} tell @code{make} how to use customary techniques so
|
|---|
| 8944 | that you do not have to specify them in detail when you want to use
|
|---|
| 8945 | them. For example, there is an implicit rule for C compilation. File
|
|---|
| 8946 | names determine which implicit rules are run. For example, C
|
|---|
| 8947 | compilation typically takes a @file{.c} file and makes a @file{.o} file.
|
|---|
| 8948 | So @code{make} applies the implicit rule for C compilation when it sees
|
|---|
| 8949 | this combination of file name endings.@refill
|
|---|
| 8950 |
|
|---|
| 8951 | A chain of implicit rules can apply in sequence; for example, @code{make}
|
|---|
| 8952 | will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file.
|
|---|
| 8953 | @iftex
|
|---|
| 8954 | @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 8955 | @end iftex
|
|---|
| 8956 |
|
|---|
| 8957 | The built-in implicit rules use several variables in their recipes so
|
|---|
| 8958 | that, by changing the values of the variables, you can change the way the
|
|---|
| 8959 | implicit rule works. For example, the variable @code{CFLAGS} controls the
|
|---|
| 8960 | flags given to the C compiler by the implicit rule for C compilation.
|
|---|
| 8961 | @iftex
|
|---|
| 8962 | @xref{Implicit Variables, ,Variables Used by Implicit Rules}.
|
|---|
| 8963 | @end iftex
|
|---|
| 8964 |
|
|---|
| 8965 | You can define your own implicit rules by writing @dfn{pattern rules}.
|
|---|
| 8966 | @iftex
|
|---|
| 8967 | @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.
|
|---|
| 8968 | @end iftex
|
|---|
| 8969 |
|
|---|
| 8970 | @dfn{Suffix rules} are a more limited way to define implicit rules.
|
|---|
| 8971 | Pattern rules are more general and clearer, but suffix rules are
|
|---|
| 8972 | retained for compatibility.
|
|---|
| 8973 | @iftex
|
|---|
| 8974 | @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
|
|---|
| 8975 | @end iftex
|
|---|
| 8976 |
|
|---|
| 8977 | @menu
|
|---|
| 8978 | * Using Implicit:: How to use an existing implicit rule
|
|---|
| 8979 | to get the recipes for updating a file.
|
|---|
| 8980 | * Catalogue of Rules:: A list of built-in rules.
|
|---|
| 8981 | * Implicit Variables:: How to change what predefined rules do.
|
|---|
| 8982 | * Chained Rules:: How to use a chain of implicit rules.
|
|---|
| 8983 | * Pattern Rules:: How to define new implicit rules.
|
|---|
| 8984 | * Last Resort:: How to define a recipe for rules which
|
|---|
| 8985 | cannot find any.
|
|---|
| 8986 | * Suffix Rules:: The old-fashioned style of implicit rule.
|
|---|
| 8987 | * Implicit Rule Search:: The precise algorithm for applying
|
|---|
| 8988 | implicit rules.
|
|---|
| 8989 | @end menu
|
|---|
| 8990 |
|
|---|
| 8991 | @node Using Implicit, Catalogue of Rules, Implicit Rules, Implicit Rules
|
|---|
| 8992 | @section Using Implicit Rules
|
|---|
| 8993 | @cindex implicit rule, how to use
|
|---|
| 8994 | @cindex rule, implicit, how to use
|
|---|
| 8995 |
|
|---|
| 8996 | To allow @code{make} to find a customary method for updating a target
|
|---|
| 8997 | file, all you have to do is refrain from specifying recipes yourself.
|
|---|
| 8998 | Either write a rule with no recipe, or don't write a rule at all.
|
|---|
| 8999 | Then @code{make} will figure out which implicit rule to use based on
|
|---|
| 9000 | which kind of source file exists or can be made.
|
|---|
| 9001 |
|
|---|
| 9002 | For example, suppose the makefile looks like this:
|
|---|
| 9003 |
|
|---|
| 9004 | @example
|
|---|
| 9005 | foo : foo.o bar.o
|
|---|
| 9006 | cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)
|
|---|
| 9007 | @end example
|
|---|
| 9008 |
|
|---|
| 9009 | @noindent
|
|---|
| 9010 | Because you mention @file{foo.o} but do not give a rule for it, @code{make}
|
|---|
| 9011 | will automatically look for an implicit rule that tells how to update it.
|
|---|
| 9012 | This happens whether or not the file @file{foo.o} currently exists.
|
|---|
| 9013 |
|
|---|
| 9014 | If an implicit rule is found, it can supply both a recipe and one or
|
|---|
| 9015 | more prerequisites (the source files). You would want to write a rule
|
|---|
| 9016 | for @file{foo.o} with no recipe if you need to specify additional
|
|---|
| 9017 | prerequisites, such as header files, that the implicit rule cannot
|
|---|
| 9018 | supply.
|
|---|
| 9019 |
|
|---|
| 9020 | Each implicit rule has a target pattern and prerequisite patterns. There may
|
|---|
| 9021 | be many implicit rules with the same target pattern. For example, numerous
|
|---|
| 9022 | rules make @samp{.o} files: one, from a @samp{.c} file with the C compiler;
|
|---|
| 9023 | another, from a @samp{.p} file with the Pascal compiler; and so on. The rule
|
|---|
| 9024 | that actually applies is the one whose prerequisites exist or can be made.
|
|---|
| 9025 | So, if you have a file @file{foo.c}, @code{make} will run the C compiler;
|
|---|
| 9026 | otherwise, if you have a file @file{foo.p}, @code{make} will run the Pascal
|
|---|
| 9027 | compiler; and so on.
|
|---|
| 9028 |
|
|---|
| 9029 | Of course, when you write the makefile, you know which implicit rule you
|
|---|
| 9030 | want @code{make} to use, and you know it will choose that one because you
|
|---|
| 9031 | know which possible prerequisite files are supposed to exist.
|
|---|
| 9032 | @xref{Catalogue of Rules, ,Catalogue of Built-In Rules},
|
|---|
| 9033 | for a catalogue of all the predefined implicit rules.
|
|---|
| 9034 |
|
|---|
| 9035 | Above, we said an implicit rule applies if the required prerequisites ``exist
|
|---|
| 9036 | or can be made''. A file ``can be made'' if it is mentioned explicitly in
|
|---|
| 9037 | the makefile as a target or a prerequisite, or if an implicit rule can be
|
|---|
| 9038 | recursively found for how to make it. When an implicit prerequisite is the
|
|---|
| 9039 | result of another implicit rule, we say that @dfn{chaining} is occurring.
|
|---|
| 9040 | @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 9041 |
|
|---|
| 9042 | In general, @code{make} searches for an implicit rule for each target, and
|
|---|
| 9043 | for each double-colon rule, that has no recipe. A file that is mentioned
|
|---|
| 9044 | only as a prerequisite is considered a target whose rule specifies nothing,
|
|---|
| 9045 | so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the
|
|---|
| 9046 | details of how the search is done.
|
|---|
| 9047 |
|
|---|
| 9048 | Note that explicit prerequisites do not influence implicit rule search.
|
|---|
| 9049 | For example, consider this explicit rule:
|
|---|
| 9050 |
|
|---|
| 9051 | @example
|
|---|
| 9052 | foo.o: foo.p
|
|---|
| 9053 | @end example
|
|---|
| 9054 |
|
|---|
| 9055 | @noindent
|
|---|
| 9056 | The prerequisite on @file{foo.p} does not necessarily mean that
|
|---|
| 9057 | @code{make} will remake @file{foo.o} according to the implicit rule to
|
|---|
| 9058 | make an object file, a @file{.o} file, from a Pascal source file, a
|
|---|
| 9059 | @file{.p} file. For example, if @file{foo.c} also exists, the implicit
|
|---|
| 9060 | rule to make an object file from a C source file is used instead,
|
|---|
| 9061 | because it appears before the Pascal rule in the list of predefined
|
|---|
| 9062 | implicit rules (@pxref{Catalogue of Rules, , Catalogue of Built-In
|
|---|
| 9063 | Rules}).
|
|---|
| 9064 |
|
|---|
| 9065 | If you do not want an implicit rule to be used for a target that has no
|
|---|
| 9066 | recipe, you can give that target an empty recipe by writing a semicolon
|
|---|
| 9067 | (@pxref{Empty Recipes, ,Defining Empty Recipes}).
|
|---|
| 9068 |
|
|---|
| 9069 | @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules
|
|---|
| 9070 | @section Catalogue of Built-In Rules
|
|---|
| 9071 | @cindex implicit rule, predefined
|
|---|
| 9072 | @cindex rule, implicit, predefined
|
|---|
| 9073 |
|
|---|
| 9074 | Here is a catalogue of predefined implicit rules which are always
|
|---|
| 9075 | available unless the makefile explicitly overrides or cancels them.
|
|---|
| 9076 | @xref{Canceling Rules, ,Canceling Implicit Rules}, for information on
|
|---|
| 9077 | canceling or overriding an implicit rule. The @samp{-r} or
|
|---|
| 9078 | @samp{--no-builtin-rules} option cancels all predefined rules.
|
|---|
| 9079 |
|
|---|
| 9080 | This manual only documents the default rules available on POSIX-based
|
|---|
| 9081 | operating systems. Other operating systems, such as VMS, Windows,
|
|---|
| 9082 | OS/2, etc. may have different sets of default rules. To see the full
|
|---|
| 9083 | list of default rules and variables available in your version of GNU
|
|---|
| 9084 | @code{make}, run @samp{make -p} in a directory with no makefile.
|
|---|
| 9085 |
|
|---|
| 9086 | Not all of these rules will always be defined, even when the @samp{-r}
|
|---|
| 9087 | option is not given. Many of the predefined implicit rules are
|
|---|
| 9088 | implemented in @code{make} as suffix rules, so which ones will be
|
|---|
| 9089 | defined depends on the @dfn{suffix list} (the list of prerequisites of
|
|---|
| 9090 | the special target @code{.SUFFIXES}). The default suffix list is:
|
|---|
| 9091 | @code{.out}, @code{.a}, @code{.ln}, @code{.o}, @code{.c}, @code{.cc},
|
|---|
| 9092 | @code{.C}, @code{.cpp}, @code{.p}, @code{.f}, @code{.F}, @code{.m},
|
|---|
| 9093 | @code{.r}, @code{.y}, @code{.l}, @code{.ym}, @code{.lm}, @code{.s},
|
|---|
| 9094 | @code{.S}, @code{.mod}, @code{.sym}, @code{.def}, @code{.h},
|
|---|
| 9095 | @code{.info}, @code{.dvi}, @code{.tex}, @code{.texinfo}, @code{.texi},
|
|---|
| 9096 | @code{.txinfo}, @code{.w}, @code{.ch} @code{.web}, @code{.sh},
|
|---|
| 9097 | @code{.elc}, @code{.el}. All of the implicit rules described below
|
|---|
| 9098 | whose prerequisites have one of these suffixes are actually suffix
|
|---|
| 9099 | rules. If you modify the suffix list, the only predefined suffix
|
|---|
| 9100 | rules in effect will be those named by one or two of the suffixes that
|
|---|
| 9101 | are on the list you specify; rules whose suffixes fail to be on the
|
|---|
| 9102 | list are disabled. @xref{Suffix Rules, ,Old-Fashioned Suffix Rules},
|
|---|
| 9103 | for full details on suffix rules.
|
|---|
| 9104 |
|
|---|
| 9105 | @table @asis
|
|---|
| 9106 | @item Compiling C programs
|
|---|
| 9107 | @cindex C, rule to compile
|
|---|
| 9108 | @pindex cc
|
|---|
| 9109 | @pindex gcc
|
|---|
| 9110 | @pindex .o
|
|---|
| 9111 | @pindex .c
|
|---|
| 9112 | @file{@var{n}.o} is made automatically from @file{@var{n}.c} with
|
|---|
| 9113 | a recipe of the form @samp{$(CC) $(CPPFLAGS) $(CFLAGS) -c}.@refill
|
|---|
| 9114 |
|
|---|
| 9115 | @item Compiling C++ programs
|
|---|
| 9116 | @cindex C++, rule to compile
|
|---|
| 9117 | @pindex g++
|
|---|
| 9118 | @pindex .cc
|
|---|
| 9119 | @pindex .cpp
|
|---|
| 9120 | @pindex .C
|
|---|
| 9121 | @file{@var{n}.o} is made automatically from @file{@var{n}.cc},
|
|---|
| 9122 | @file{@var{n}.cpp}, or @file{@var{n}.C} with a recipe of the form
|
|---|
| 9123 | @samp{$(CXX) $(CPPFLAGS) $(CXXFLAGS) -c}. We encourage you to use the
|
|---|
| 9124 | suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill
|
|---|
| 9125 |
|
|---|
| 9126 | @item Compiling Pascal programs
|
|---|
| 9127 | @cindex Pascal, rule to compile
|
|---|
| 9128 | @pindex pc
|
|---|
| 9129 | @pindex .p
|
|---|
| 9130 | @file{@var{n}.o} is made automatically from @file{@var{n}.p}
|
|---|
| 9131 | with the recipe @samp{$(PC) $(PFLAGS) -c}.@refill
|
|---|
| 9132 |
|
|---|
| 9133 | @item Compiling Fortran and Ratfor programs
|
|---|
| 9134 | @cindex Fortran, rule to compile
|
|---|
| 9135 | @cindex Ratfor, rule to compile
|
|---|
| 9136 | @pindex f77
|
|---|
| 9137 | @pindex .f
|
|---|
| 9138 | @pindex .r
|
|---|
| 9139 | @pindex .F
|
|---|
| 9140 | @file{@var{n}.o} is made automatically from @file{@var{n}.r},
|
|---|
| 9141 | @file{@var{n}.F} or @file{@var{n}.f} by running the
|
|---|
| 9142 | Fortran compiler. The precise recipe used is as follows:@refill
|
|---|
| 9143 |
|
|---|
| 9144 | @table @samp
|
|---|
| 9145 | @item .f
|
|---|
| 9146 | @samp{$(FC) $(FFLAGS) -c}.
|
|---|
| 9147 | @item .F
|
|---|
| 9148 | @samp{$(FC) $(FFLAGS) $(CPPFLAGS) -c}.
|
|---|
| 9149 | @item .r
|
|---|
| 9150 | @samp{$(FC) $(FFLAGS) $(RFLAGS) -c}.
|
|---|
| 9151 | @end table
|
|---|
| 9152 |
|
|---|
| 9153 | @item Preprocessing Fortran and Ratfor programs
|
|---|
| 9154 | @file{@var{n}.f} is made automatically from @file{@var{n}.r} or
|
|---|
| 9155 | @file{@var{n}.F}. This rule runs just the preprocessor to convert a
|
|---|
| 9156 | Ratfor or preprocessable Fortran program into a strict Fortran
|
|---|
| 9157 | program. The precise recipe used is as follows:@refill
|
|---|
| 9158 |
|
|---|
| 9159 | @table @samp
|
|---|
| 9160 | @item .F
|
|---|
| 9161 | @samp{$(FC) $(CPPFLAGS) $(FFLAGS) -F}.
|
|---|
| 9162 | @item .r
|
|---|
| 9163 | @samp{$(FC) $(FFLAGS) $(RFLAGS) -F}.
|
|---|
| 9164 | @end table
|
|---|
| 9165 |
|
|---|
| 9166 | @item Compiling Modula-2 programs
|
|---|
| 9167 | @cindex Modula-2, rule to compile
|
|---|
| 9168 | @pindex m2c
|
|---|
| 9169 | @pindex .sym
|
|---|
| 9170 | @pindex .def
|
|---|
| 9171 | @pindex .mod
|
|---|
| 9172 | @file{@var{n}.sym} is made from @file{@var{n}.def} with a recipe
|
|---|
| 9173 | of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o}
|
|---|
| 9174 | is made from @file{@var{n}.mod}; the form is:
|
|---|
| 9175 | @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill
|
|---|
| 9176 |
|
|---|
| 9177 | @need 1200
|
|---|
| 9178 | @item Assembling and preprocessing assembler programs
|
|---|
| 9179 | @cindex assembly, rule to compile
|
|---|
| 9180 | @pindex as
|
|---|
| 9181 | @pindex .s
|
|---|
| 9182 | @file{@var{n}.o} is made automatically from @file{@var{n}.s} by
|
|---|
| 9183 | running the assembler, @code{as}. The precise recipe is
|
|---|
| 9184 | @samp{$(AS) $(ASFLAGS)}.@refill
|
|---|
| 9185 |
|
|---|
| 9186 | @pindex .S
|
|---|
| 9187 | @file{@var{n}.s} is made automatically from @file{@var{n}.S} by
|
|---|
| 9188 | running the C preprocessor, @code{cpp}. The precise recipe is
|
|---|
| 9189 | @w{@samp{$(CPP) $(CPPFLAGS)}}.
|
|---|
| 9190 |
|
|---|
| 9191 | @item Linking a single object file
|
|---|
| 9192 | @cindex linking, predefined rule for
|
|---|
| 9193 | @pindex ld
|
|---|
| 9194 | @pindex .o
|
|---|
| 9195 | @file{@var{n}} is made automatically from @file{@var{n}.o} by running
|
|---|
| 9196 | the linker (usually called @code{ld}) via the C compiler. The precise
|
|---|
| 9197 | recipe used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}.
|
|---|
| 9198 |
|
|---|
| 9199 | This rule does the right thing for a simple program with only one
|
|---|
| 9200 | source file. It will also do the right thing if there are multiple
|
|---|
| 9201 | object files (presumably coming from various other source files), one
|
|---|
| 9202 | of which has a name matching that of the executable file. Thus,
|
|---|
| 9203 |
|
|---|
| 9204 | @example
|
|---|
| 9205 | x: y.o z.o
|
|---|
| 9206 | @end example
|
|---|
| 9207 |
|
|---|
| 9208 | @noindent
|
|---|
| 9209 | when @file{x.c}, @file{y.c} and @file{z.c} all exist will execute:
|
|---|
| 9210 |
|
|---|
| 9211 | @example
|
|---|
| 9212 | @group
|
|---|
| 9213 | cc -c x.c -o x.o
|
|---|
| 9214 | cc -c y.c -o y.o
|
|---|
| 9215 | cc -c z.c -o z.o
|
|---|
| 9216 | cc x.o y.o z.o -o x
|
|---|
| 9217 | rm -f x.o
|
|---|
| 9218 | rm -f y.o
|
|---|
| 9219 | rm -f z.o
|
|---|
| 9220 | @end group
|
|---|
| 9221 | @end example
|
|---|
| 9222 |
|
|---|
| 9223 | @noindent
|
|---|
| 9224 | In more complicated cases, such as when there is no object file whose
|
|---|
| 9225 | name derives from the executable file name, you must write an explicit
|
|---|
| 9226 | recipe for linking.
|
|---|
| 9227 |
|
|---|
| 9228 | Each kind of file automatically made into @samp{.o} object files will
|
|---|
| 9229 | be automatically linked by using the compiler (@samp{$(CC)},
|
|---|
| 9230 | @samp{$(FC)} or @samp{$(PC)}; the C compiler @samp{$(CC)} is used to
|
|---|
| 9231 | assemble @samp{.s} files) without the @samp{-c} option. This could be
|
|---|
| 9232 | done by using the @samp{.o} object files as intermediates, but it is
|
|---|
| 9233 | faster to do the compiling and linking in one step, so that's how it's
|
|---|
| 9234 | done.@refill
|
|---|
| 9235 |
|
|---|
| 9236 | @item Yacc for C programs
|
|---|
| 9237 | @pindex yacc
|
|---|
| 9238 | @cindex Yacc, rule to run
|
|---|
| 9239 | @pindex .y
|
|---|
| 9240 | @file{@var{n}.c} is made automatically from @file{@var{n}.y} by
|
|---|
| 9241 | running Yacc with the recipe @samp{$(YACC) $(YFLAGS)}.
|
|---|
| 9242 |
|
|---|
| 9243 | @item Lex for C programs
|
|---|
| 9244 | @pindex lex
|
|---|
| 9245 | @cindex Lex, rule to run
|
|---|
| 9246 | @pindex .l
|
|---|
| 9247 | @file{@var{n}.c} is made automatically from @file{@var{n}.l} by
|
|---|
| 9248 | running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}.
|
|---|
| 9249 |
|
|---|
| 9250 | @item Lex for Ratfor programs
|
|---|
| 9251 | @file{@var{n}.r} is made automatically from @file{@var{n}.l} by
|
|---|
| 9252 | running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}.
|
|---|
| 9253 |
|
|---|
| 9254 | The convention of using the same suffix @samp{.l} for all Lex files
|
|---|
| 9255 | regardless of whether they produce C code or Ratfor code makes it
|
|---|
| 9256 | impossible for @code{make} to determine automatically which of the two
|
|---|
| 9257 | languages you are using in any particular case. If @code{make} is
|
|---|
| 9258 | called upon to remake an object file from a @samp{.l} file, it must
|
|---|
| 9259 | guess which compiler to use. It will guess the C compiler, because
|
|---|
| 9260 | that is more common. If you are using Ratfor, make sure @code{make}
|
|---|
| 9261 | knows this by mentioning @file{@var{n}.r} in the makefile. Or, if you
|
|---|
| 9262 | are using Ratfor exclusively, with no C files, remove @samp{.c} from
|
|---|
| 9263 | the list of implicit rule suffixes with:@refill
|
|---|
| 9264 |
|
|---|
| 9265 | @example
|
|---|
| 9266 | @group
|
|---|
| 9267 | .SUFFIXES:
|
|---|
| 9268 | .SUFFIXES: .o .r .f .l @dots{}
|
|---|
| 9269 | @end group
|
|---|
| 9270 | @end example
|
|---|
| 9271 |
|
|---|
| 9272 | @item Making Lint Libraries from C, Yacc, or Lex programs
|
|---|
| 9273 | @pindex lint
|
|---|
| 9274 | @cindex @code{lint}, rule to run
|
|---|
| 9275 | @pindex .ln
|
|---|
| 9276 | @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}.
|
|---|
| 9277 | The precise recipe is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}.
|
|---|
| 9278 | The same recipe is used on the C code produced from
|
|---|
| 9279 | @file{@var{n}.y} or @file{@var{n}.l}.@refill
|
|---|
| 9280 |
|
|---|
| 9281 | @item @TeX{} and Web
|
|---|
| 9282 | @cindex @TeX{}, rule to run
|
|---|
| 9283 | @cindex Web, rule to run
|
|---|
| 9284 | @pindex tex
|
|---|
| 9285 | @pindex cweave
|
|---|
| 9286 | @pindex weave
|
|---|
| 9287 | @pindex tangle
|
|---|
| 9288 | @pindex ctangle
|
|---|
| 9289 | @pindex .dvi
|
|---|
| 9290 | @pindex .tex
|
|---|
| 9291 | @pindex .web
|
|---|
| 9292 | @pindex .w
|
|---|
| 9293 | @pindex .ch
|
|---|
| 9294 | @file{@var{n}.dvi} is made from @file{@var{n}.tex} with the recipe
|
|---|
| 9295 | @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with
|
|---|
| 9296 | @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if
|
|---|
| 9297 | it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is
|
|---|
| 9298 | made from @file{@var{n}.web} with @samp{$(TANGLE)} and @file{@var{n}.c}
|
|---|
| 9299 | is made from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists
|
|---|
| 9300 | or can be made) with @samp{$(CTANGLE)}.@refill
|
|---|
| 9301 |
|
|---|
| 9302 | @item Texinfo and Info
|
|---|
| 9303 | @cindex Texinfo, rule to format
|
|---|
| 9304 | @cindex Info, rule to format
|
|---|
| 9305 | @pindex texi2dvi
|
|---|
| 9306 | @pindex makeinfo
|
|---|
| 9307 | @pindex .texinfo
|
|---|
| 9308 | @pindex .info
|
|---|
| 9309 | @pindex .texi
|
|---|
| 9310 | @pindex .txinfo
|
|---|
| 9311 | @file{@var{n}.dvi} is made from @file{@var{n}.texinfo},
|
|---|
| 9312 | @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the recipe
|
|---|
| 9313 | @w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from
|
|---|
| 9314 | @file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with
|
|---|
| 9315 | the recipe @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}.
|
|---|
| 9316 |
|
|---|
| 9317 | @item RCS
|
|---|
| 9318 | @cindex RCS, rule to extract from
|
|---|
| 9319 | @pindex co
|
|---|
| 9320 | @pindex ,v @r{(RCS file extension)}
|
|---|
| 9321 | Any file @file{@var{n}} is extracted if necessary from an RCS file
|
|---|
| 9322 | named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise
|
|---|
| 9323 | recipe used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be
|
|---|
| 9324 | extracted from RCS if it already exists, even if the RCS file is
|
|---|
| 9325 | newer. The rules for RCS are terminal
|
|---|
| 9326 | (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
|
|---|
| 9327 | so RCS files cannot be generated from another source; they must
|
|---|
| 9328 | actually exist.@refill
|
|---|
| 9329 |
|
|---|
| 9330 | @item SCCS
|
|---|
| 9331 | @cindex SCCS, rule to extract from
|
|---|
| 9332 | @pindex get
|
|---|
| 9333 | @pindex s. @r{(SCCS file prefix)}
|
|---|
| 9334 | Any file @file{@var{n}} is extracted if necessary from an SCCS file
|
|---|
| 9335 | named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise
|
|---|
| 9336 | recipe used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are
|
|---|
| 9337 | terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}),
|
|---|
| 9338 | so SCCS files cannot be generated from another source; they must
|
|---|
| 9339 | actually exist.@refill
|
|---|
| 9340 |
|
|---|
| 9341 | @pindex .sh
|
|---|
| 9342 | For the benefit of SCCS, a file @file{@var{n}} is copied from
|
|---|
| 9343 | @file{@var{n}.sh} and made executable (by everyone). This is for
|
|---|
| 9344 | shell scripts that are checked into SCCS. Since RCS preserves the
|
|---|
| 9345 | execution permission of a file, you do not need to use this feature
|
|---|
| 9346 | with RCS.@refill
|
|---|
| 9347 |
|
|---|
| 9348 | We recommend that you avoid using of SCCS. RCS is widely held to be
|
|---|
| 9349 | superior, and is also free. By choosing free software in place of
|
|---|
| 9350 | comparable (or inferior) proprietary software, you support the free
|
|---|
| 9351 | software movement.
|
|---|
| 9352 | @end table
|
|---|
| 9353 |
|
|---|
| 9354 | Usually, you want to change only the variables listed in the table
|
|---|
| 9355 | above, which are documented in the following section.
|
|---|
| 9356 |
|
|---|
| 9357 | However, the recipes in built-in implicit rules actually use
|
|---|
| 9358 | variables such as @code{COMPILE.c}, @code{LINK.p}, and
|
|---|
| 9359 | @code{PREPROCESS.S}, whose values contain the recipes listed above.
|
|---|
| 9360 |
|
|---|
| 9361 | @code{make} follows the convention that the rule to compile a
|
|---|
| 9362 | @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}.
|
|---|
| 9363 | Similarly, the rule to produce an executable from a @file{.@var{x}}
|
|---|
| 9364 | file uses @code{LINK.@var{x}}; and the rule to preprocess a
|
|---|
| 9365 | @file{.@var{x}} file uses @code{PREPROCESS.@var{x}}.
|
|---|
| 9366 |
|
|---|
| 9367 | @vindex OUTPUT_OPTION
|
|---|
| 9368 | Every rule that produces an object file uses the variable
|
|---|
| 9369 | @code{OUTPUT_OPTION}. @code{make} defines this variable either to
|
|---|
| 9370 | contain @samp{-o $@@}, or to be empty, depending on a compile-time
|
|---|
| 9371 | option. You need the @samp{-o} option to ensure that the output goes
|
|---|
| 9372 | into the right file when the source file is in a different directory,
|
|---|
| 9373 | as when using @code{VPATH} (@pxref{Directory Search}). However,
|
|---|
| 9374 | compilers on some systems do not accept a @samp{-o} switch for object
|
|---|
| 9375 | files. If you use such a system, and use @code{VPATH}, some
|
|---|
| 9376 | compilations will put their output in the wrong place.
|
|---|
| 9377 | A possible workaround for this problem is to give @code{OUTPUT_OPTION}
|
|---|
| 9378 | the value @w{@samp{; mv $*.o $@@}}.
|
|---|
| 9379 |
|
|---|
| 9380 | @node Implicit Variables, Chained Rules, Catalogue of Rules, Implicit Rules
|
|---|
| 9381 | @section Variables Used by Implicit Rules
|
|---|
| 9382 | @cindex flags for compilers
|
|---|
| 9383 |
|
|---|
| 9384 | The recipes in built-in implicit rules make liberal use of certain
|
|---|
| 9385 | predefined variables. You can alter the values of these variables in
|
|---|
| 9386 | the makefile, with arguments to @code{make}, or in the environment to
|
|---|
| 9387 | alter how the implicit rules work without redefining the rules
|
|---|
| 9388 | themselves. You can cancel all variables used by implicit rules with
|
|---|
| 9389 | the @samp{-R} or @samp{--no-builtin-variables} option.
|
|---|
| 9390 |
|
|---|
| 9391 | For example, the recipe used to compile a C source file actually says
|
|---|
| 9392 | @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables
|
|---|
| 9393 | used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By
|
|---|
| 9394 | redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be
|
|---|
| 9395 | used for all C compilations performed by the implicit rule. By redefining
|
|---|
| 9396 | @samp{CFLAGS} to be @samp{-g}, you could pass the @samp{-g} option to
|
|---|
| 9397 | each compilation. @emph{All} implicit rules that do C compilation use
|
|---|
| 9398 | @samp{$(CC)} to get the program name for the compiler and @emph{all}
|
|---|
| 9399 | include @samp{$(CFLAGS)} among the arguments given to the compiler.@refill
|
|---|
| 9400 |
|
|---|
| 9401 | The variables used in implicit rules fall into two classes: those that are
|
|---|
| 9402 | names of programs (like @code{CC}) and those that contain arguments for the
|
|---|
| 9403 | programs (like @code{CFLAGS}). (The ``name of a program'' may also contain
|
|---|
| 9404 | some command arguments, but it must start with an actual executable program
|
|---|
| 9405 | name.) If a variable value contains more than one argument, separate them
|
|---|
| 9406 | with spaces.
|
|---|
| 9407 |
|
|---|
| 9408 | The following tables describe of some of the more commonly-used predefined
|
|---|
| 9409 | variables. This list is not exhaustive, and the default values shown here may
|
|---|
| 9410 | not be what @code{make} selects for your environment. To see the
|
|---|
| 9411 | complete list of predefined variables for your instance of GNU @code{make} you
|
|---|
| 9412 | can run @samp{make -p} in a directory with no makefiles.
|
|---|
| 9413 |
|
|---|
| 9414 | Here is a table of some of the more common variables used as names of
|
|---|
| 9415 | programs in built-in rules:
|
|---|
| 9416 |
|
|---|
| 9417 | @table @code
|
|---|
| 9418 | @item AR
|
|---|
| 9419 | @vindex AR
|
|---|
| 9420 | Archive-maintaining program; default @samp{ar}.
|
|---|
| 9421 | @pindex ar
|
|---|
| 9422 |
|
|---|
| 9423 | @item AS
|
|---|
| 9424 | @vindex AS
|
|---|
| 9425 | Program for compiling assembly files; default @samp{as}.
|
|---|
| 9426 | @pindex as
|
|---|
| 9427 |
|
|---|
| 9428 | @item CC
|
|---|
| 9429 | @vindex CC
|
|---|
| 9430 | Program for compiling C programs; default @samp{cc}.
|
|---|
| 9431 | @pindex cc
|
|---|
| 9432 |
|
|---|
| 9433 | @item CXX
|
|---|
| 9434 | @vindex CXX
|
|---|
| 9435 | Program for compiling C++ programs; default @samp{g++}.
|
|---|
| 9436 | @pindex g++
|
|---|
| 9437 |
|
|---|
| 9438 | @item CPP
|
|---|
| 9439 | @vindex CPP
|
|---|
| 9440 | Program for running the C preprocessor, with results to standard output;
|
|---|
| 9441 | default @samp{$(CC) -E}.
|
|---|
| 9442 |
|
|---|
| 9443 | @item FC
|
|---|
| 9444 | @vindex FC
|
|---|
| 9445 | Program for compiling or preprocessing Fortran and Ratfor programs;
|
|---|
| 9446 | default @samp{f77}.
|
|---|
| 9447 | @pindex f77
|
|---|
| 9448 |
|
|---|
| 9449 | @item M2C
|
|---|
| 9450 | @vindex M2C
|
|---|
| 9451 | Program to use to compile Modula-2 source code; default @samp{m2c}.
|
|---|
| 9452 | @pindex m2c
|
|---|
| 9453 |
|
|---|
| 9454 | @item PC
|
|---|
| 9455 | @vindex PC
|
|---|
| 9456 | Program for compiling Pascal programs; default @samp{pc}.
|
|---|
| 9457 | @pindex pc
|
|---|
| 9458 |
|
|---|
| 9459 | @item CO
|
|---|
| 9460 | @vindex CO
|
|---|
| 9461 | Program for extracting a file from RCS; default @samp{co}.
|
|---|
| 9462 | @pindex co
|
|---|
| 9463 |
|
|---|
| 9464 | @item GET
|
|---|
| 9465 | @vindex GET
|
|---|
| 9466 | Program for extracting a file from SCCS; default @samp{get}.
|
|---|
| 9467 | @pindex get
|
|---|
| 9468 |
|
|---|
| 9469 | @item LEX
|
|---|
| 9470 | @vindex LEX
|
|---|
| 9471 | Program to use to turn Lex grammars into source code; default @samp{lex}.
|
|---|
| 9472 | @pindex lex
|
|---|
| 9473 |
|
|---|
| 9474 | @item YACC
|
|---|
| 9475 | @vindex YACC
|
|---|
| 9476 | Program to use to turn Yacc grammars into source code; default @samp{yacc}.
|
|---|
| 9477 | @pindex yacc
|
|---|
| 9478 |
|
|---|
| 9479 | @item LINT
|
|---|
| 9480 | @vindex LINT
|
|---|
| 9481 | Program to use to run lint on source code; default @samp{lint}.
|
|---|
| 9482 | @pindex lint
|
|---|
| 9483 |
|
|---|
| 9484 | @item MAKEINFO
|
|---|
| 9485 | @vindex MAKEINFO
|
|---|
| 9486 | Program to convert a Texinfo source file into an Info file; default
|
|---|
| 9487 | @samp{makeinfo}.
|
|---|
| 9488 | @pindex makeinfo
|
|---|
| 9489 |
|
|---|
| 9490 | @item TEX
|
|---|
| 9491 | @vindex TEX
|
|---|
| 9492 | Program to make @TeX{} @sc{dvi} files from @TeX{} source;
|
|---|
| 9493 | default @samp{tex}.
|
|---|
| 9494 | @pindex tex
|
|---|
| 9495 |
|
|---|
| 9496 | @item TEXI2DVI
|
|---|
| 9497 | @vindex TEXI2DVI
|
|---|
| 9498 | Program to make @TeX{} @sc{dvi} files from Texinfo source;
|
|---|
| 9499 | default @samp{texi2dvi}.
|
|---|
| 9500 | @pindex texi2dvi
|
|---|
| 9501 |
|
|---|
| 9502 | @item WEAVE
|
|---|
| 9503 | @vindex WEAVE
|
|---|
| 9504 | Program to translate Web into @TeX{}; default @samp{weave}.
|
|---|
| 9505 | @pindex weave
|
|---|
| 9506 |
|
|---|
| 9507 | @item CWEAVE
|
|---|
| 9508 | @vindex CWEAVE
|
|---|
| 9509 | Program to translate C Web into @TeX{}; default @samp{cweave}.
|
|---|
| 9510 | @pindex cweave
|
|---|
| 9511 |
|
|---|
| 9512 | @item TANGLE
|
|---|
| 9513 | @vindex TANGLE
|
|---|
| 9514 | Program to translate Web into Pascal; default @samp{tangle}.
|
|---|
| 9515 | @pindex tangle
|
|---|
| 9516 |
|
|---|
| 9517 | @item CTANGLE
|
|---|
| 9518 | @vindex CTANGLE
|
|---|
| 9519 | Program to translate C Web into C; default @samp{ctangle}.
|
|---|
| 9520 | @pindex ctangle
|
|---|
| 9521 |
|
|---|
| 9522 | @item RM
|
|---|
| 9523 | @vindex RM
|
|---|
| 9524 | Command to remove a file; default @samp{rm -f}.
|
|---|
| 9525 | @pindex rm
|
|---|
| 9526 | @end table
|
|---|
| 9527 |
|
|---|
| 9528 | Here is a table of variables whose values are additional arguments for the
|
|---|
| 9529 | programs above. The default values for all of these is the empty
|
|---|
| 9530 | string, unless otherwise noted.
|
|---|
| 9531 |
|
|---|
| 9532 | @table @code
|
|---|
| 9533 | @item ARFLAGS
|
|---|
| 9534 | @vindex ARFLAGS
|
|---|
| 9535 | Flags to give the archive-maintaining program; default @samp{rv}.
|
|---|
| 9536 |
|
|---|
| 9537 | @item ASFLAGS
|
|---|
| 9538 | @vindex ASFLAGS
|
|---|
| 9539 | Extra flags to give to the assembler (when explicitly
|
|---|
| 9540 | invoked on a @samp{.s} or @samp{.S} file).
|
|---|
| 9541 |
|
|---|
| 9542 | @item CFLAGS
|
|---|
| 9543 | @vindex CFLAGS
|
|---|
| 9544 | Extra flags to give to the C compiler.
|
|---|
| 9545 |
|
|---|
| 9546 | @item CXXFLAGS
|
|---|
| 9547 | @vindex CXXFLAGS
|
|---|
| 9548 | Extra flags to give to the C++ compiler.
|
|---|
| 9549 |
|
|---|
| 9550 | @item COFLAGS
|
|---|
| 9551 | @vindex COFLAGS
|
|---|
| 9552 | Extra flags to give to the RCS @code{co} program.
|
|---|
| 9553 |
|
|---|
| 9554 | @item CPPFLAGS
|
|---|
| 9555 | @vindex CPPFLAGS
|
|---|
| 9556 | Extra flags to give to the C preprocessor and programs
|
|---|
| 9557 | that use it (the C and Fortran compilers).
|
|---|
| 9558 |
|
|---|
| 9559 | @item FFLAGS
|
|---|
| 9560 | @vindex FFLAGS
|
|---|
| 9561 | Extra flags to give to the Fortran compiler.
|
|---|
| 9562 |
|
|---|
| 9563 | @item GFLAGS
|
|---|
| 9564 | @vindex GFLAGS
|
|---|
| 9565 | Extra flags to give to the SCCS @code{get} program.
|
|---|
| 9566 |
|
|---|
| 9567 | @item LDFLAGS
|
|---|
| 9568 | @vindex LDFLAGS
|
|---|
| 9569 | Extra flags to give to compilers when they are supposed to invoke the linker,
|
|---|
| 9570 | @samp{ld}, such as @code{-L}. Libraries (@code{-lfoo}) should be
|
|---|
| 9571 | added to the @code{LDLIBS} variable instead.
|
|---|
| 9572 |
|
|---|
| 9573 | @item LDLIBS
|
|---|
| 9574 | @vindex LDLIBS
|
|---|
| 9575 | @vindex LOADLIBES
|
|---|
| 9576 | Library flags or names given to compilers when they are supposed to
|
|---|
| 9577 | invoke the linker, @samp{ld}. @code{LOADLIBES} is a deprecated (but
|
|---|
| 9578 | still supported) alternative to @code{LDLIBS}. Non-library linker
|
|---|
| 9579 | flags, such as @code{-L}, should go in the @code{LDFLAGS} variable.
|
|---|
| 9580 |
|
|---|
| 9581 | @item LFLAGS
|
|---|
| 9582 | @vindex LFLAGS
|
|---|
| 9583 | Extra flags to give to Lex.
|
|---|
| 9584 |
|
|---|
| 9585 | @item YFLAGS
|
|---|
| 9586 | @vindex YFLAGS
|
|---|
| 9587 | Extra flags to give to Yacc.
|
|---|
| 9588 |
|
|---|
| 9589 | @item PFLAGS
|
|---|
| 9590 | @vindex PFLAGS
|
|---|
| 9591 | Extra flags to give to the Pascal compiler.
|
|---|
| 9592 |
|
|---|
| 9593 | @item RFLAGS
|
|---|
| 9594 | @vindex RFLAGS
|
|---|
| 9595 | Extra flags to give to the Fortran compiler for Ratfor programs.
|
|---|
| 9596 |
|
|---|
| 9597 | @item LINTFLAGS
|
|---|
| 9598 | @vindex LINTFLAGS
|
|---|
| 9599 | Extra flags to give to lint.
|
|---|
| 9600 | @end table
|
|---|
| 9601 |
|
|---|
| 9602 | @node Chained Rules, Pattern Rules, Implicit Variables, Implicit Rules
|
|---|
| 9603 | @section Chains of Implicit Rules
|
|---|
| 9604 |
|
|---|
| 9605 | @cindex chains of rules
|
|---|
| 9606 | @cindex rule, implicit, chains of
|
|---|
| 9607 | Sometimes a file can be made by a sequence of implicit rules. For example,
|
|---|
| 9608 | a file @file{@var{n}.o} could be made from @file{@var{n}.y} by running
|
|---|
| 9609 | first Yacc and then @code{cc}. Such a sequence is called a @dfn{chain}.
|
|---|
| 9610 |
|
|---|
| 9611 | If the file @file{@var{n}.c} exists, or is mentioned in the makefile, no
|
|---|
| 9612 | special searching is required: @code{make} finds that the object file can
|
|---|
| 9613 | be made by C compilation from @file{@var{n}.c}; later on, when considering
|
|---|
| 9614 | how to make @file{@var{n}.c}, the rule for running Yacc is
|
|---|
| 9615 | used. Ultimately both @file{@var{n}.c} and @file{@var{n}.o} are
|
|---|
| 9616 | updated.@refill
|
|---|
| 9617 |
|
|---|
| 9618 | @cindex intermediate files
|
|---|
| 9619 | @cindex files, intermediate
|
|---|
| 9620 | However, even if @file{@var{n}.c} does not exist and is not mentioned,
|
|---|
| 9621 | @code{make} knows how to envision it as the missing link between
|
|---|
| 9622 | @file{@var{n}.o} and @file{@var{n}.y}! In this case, @file{@var{n}.c} is
|
|---|
| 9623 | called an @dfn{intermediate file}. Once @code{make} has decided to use the
|
|---|
| 9624 | intermediate file, it is entered in the data base as if it had been
|
|---|
| 9625 | mentioned in the makefile, along with the implicit rule that says how to
|
|---|
| 9626 | create it.@refill
|
|---|
| 9627 |
|
|---|
| 9628 | Intermediate files are remade using their rules just like all other
|
|---|
| 9629 | files. But intermediate files are treated differently in two ways.
|
|---|
| 9630 |
|
|---|
| 9631 | The first difference is what happens if the intermediate file does not
|
|---|
| 9632 | exist. If an ordinary file @var{b} does not exist, and @code{make}
|
|---|
| 9633 | considers a target that depends on @var{b}, it invariably creates
|
|---|
| 9634 | @var{b} and then updates the target from @var{b}. But if @var{b} is an
|
|---|
| 9635 | intermediate file, then @code{make} can leave well enough alone. It
|
|---|
| 9636 | won't bother updating @var{b}, or the ultimate target, unless some
|
|---|
| 9637 | prerequisite of @var{b} is newer than that target or there is some other
|
|---|
| 9638 | reason to update that target.
|
|---|
| 9639 |
|
|---|
| 9640 | The second difference is that if @code{make} @emph{does} create @var{b}
|
|---|
| 9641 | in order to update something else, it deletes @var{b} later on after it
|
|---|
| 9642 | is no longer needed. Therefore, an intermediate file which did not
|
|---|
| 9643 | exist before @code{make} also does not exist after @code{make}.
|
|---|
| 9644 | @code{make} reports the deletion to you by printing a @samp{rm -f}
|
|---|
| 9645 | command showing which file it is deleting.
|
|---|
| 9646 |
|
|---|
| 9647 | Ordinarily, a file cannot be intermediate if it is mentioned in the
|
|---|
| 9648 | makefile as a target or prerequisite. However, you can explicitly mark a
|
|---|
| 9649 | file as intermediate by listing it as a prerequisite of the special target
|
|---|
| 9650 | @code{.INTERMEDIATE}. This takes effect even if the file is mentioned
|
|---|
| 9651 | explicitly in some other way.
|
|---|
| 9652 |
|
|---|
| 9653 | @cindex intermediate files, preserving
|
|---|
| 9654 | @cindex preserving intermediate files
|
|---|
| 9655 | @cindex secondary files
|
|---|
| 9656 | You can prevent automatic deletion of an intermediate file by marking it
|
|---|
| 9657 | as a @dfn{secondary} file. To do this, list it as a prerequisite of the
|
|---|
| 9658 | special target @code{.SECONDARY}. When a file is secondary, @code{make}
|
|---|
| 9659 | will not create the file merely because it does not already exist, but
|
|---|
| 9660 | @code{make} does not automatically delete the file. Marking a file as
|
|---|
| 9661 | secondary also marks it as intermediate.
|
|---|
| 9662 |
|
|---|
| 9663 | You can list the target pattern of an implicit rule (such as @samp{%.o})
|
|---|
| 9664 | as a prerequisite of the special target @code{.PRECIOUS} to preserve
|
|---|
| 9665 | intermediate files made by implicit rules whose target patterns match
|
|---|
| 9666 | that file's name; see @ref{Interrupts}.@refill
|
|---|
| 9667 | @cindex preserving with @code{.PRECIOUS}
|
|---|
| 9668 | @cindex @code{.PRECIOUS} intermediate files
|
|---|
| 9669 |
|
|---|
| 9670 | A chain can involve more than two implicit rules. For example, it is
|
|---|
| 9671 | possible to make a file @file{foo} from @file{RCS/foo.y,v} by running RCS,
|
|---|
| 9672 | Yacc and @code{cc}. Then both @file{foo.y} and @file{foo.c} are
|
|---|
| 9673 | intermediate files that are deleted at the end.@refill
|
|---|
| 9674 |
|
|---|
| 9675 | No single implicit rule can appear more than once in a chain. This means
|
|---|
| 9676 | that @code{make} will not even consider such a ridiculous thing as making
|
|---|
| 9677 | @file{foo} from @file{foo.o.o} by running the linker twice. This
|
|---|
| 9678 | constraint has the added benefit of preventing any infinite loop in the
|
|---|
| 9679 | search for an implicit rule chain.
|
|---|
| 9680 |
|
|---|
| 9681 | There are some special implicit rules to optimize certain cases that would
|
|---|
| 9682 | otherwise be handled by rule chains. For example, making @file{foo} from
|
|---|
| 9683 | @file{foo.c} could be handled by compiling and linking with separate
|
|---|
| 9684 | chained rules, using @file{foo.o} as an intermediate file. But what
|
|---|
| 9685 | actually happens is that a special rule for this case does the compilation
|
|---|
| 9686 | and linking with a single @code{cc} command. The optimized rule is used in
|
|---|
| 9687 | preference to the step-by-step chain because it comes earlier in the
|
|---|
| 9688 | ordering of rules.
|
|---|
| 9689 |
|
|---|
| 9690 | @node Pattern Rules, Last Resort, Chained Rules, Implicit Rules
|
|---|
| 9691 | @section Defining and Redefining Pattern Rules
|
|---|
| 9692 |
|
|---|
| 9693 | You define an implicit rule by writing a @dfn{pattern rule}. A pattern
|
|---|
| 9694 | rule looks like an ordinary rule, except that its target contains the
|
|---|
| 9695 | character @samp{%} (exactly one of them). The target is considered a
|
|---|
| 9696 | pattern for matching file names; the @samp{%} can match any nonempty
|
|---|
| 9697 | substring, while other characters match only themselves. The prerequisites
|
|---|
| 9698 | likewise use @samp{%} to show how their names relate to the target name.
|
|---|
| 9699 |
|
|---|
| 9700 | Thus, a pattern rule @samp{%.o : %.c} says how to make any file
|
|---|
| 9701 | @file{@var{stem}.o} from another file @file{@var{stem}.c}.@refill
|
|---|
| 9702 |
|
|---|
| 9703 | Note that expansion using @samp{%} in pattern rules occurs
|
|---|
| 9704 | @strong{after} any variable or function expansions, which take place
|
|---|
| 9705 | when the makefile is read. @xref{Using Variables, , How to Use
|
|---|
| 9706 | Variables}, and @ref{Functions, ,Functions for Transforming Text}.
|
|---|
| 9707 |
|
|---|
| 9708 | @menu
|
|---|
| 9709 | * Pattern Intro:: An introduction to pattern rules.
|
|---|
| 9710 | * Pattern Examples:: Examples of pattern rules.
|
|---|
| 9711 | * Automatic Variables:: How to use automatic variables in the
|
|---|
| 9712 | recipe of implicit rules.
|
|---|
| 9713 | * Pattern Match:: How patterns match.
|
|---|
| 9714 | * Match-Anything Rules:: Precautions you should take prior to
|
|---|
| 9715 | defining rules that can match any
|
|---|
| 9716 | target file whatever.
|
|---|
| 9717 | * Canceling Rules:: How to override or cancel built-in rules.
|
|---|
| 9718 | @end menu
|
|---|
| 9719 |
|
|---|
| 9720 | @node Pattern Intro, Pattern Examples, Pattern Rules, Pattern Rules
|
|---|
| 9721 | @subsection Introduction to Pattern Rules
|
|---|
| 9722 | @cindex pattern rule
|
|---|
| 9723 | @cindex rule, pattern
|
|---|
| 9724 |
|
|---|
| 9725 | A pattern rule contains the character @samp{%} (exactly one of them)
|
|---|
| 9726 | in the target; otherwise, it looks exactly like an ordinary rule. The
|
|---|
| 9727 | target is a pattern for matching file names; the @samp{%} matches any
|
|---|
| 9728 | nonempty substring, while other characters match only themselves.
|
|---|
| 9729 | @cindex target pattern, implicit
|
|---|
| 9730 | @cindex @code{%}, in pattern rules
|
|---|
| 9731 |
|
|---|
| 9732 | For example, @samp{%.c} as a pattern matches any file name that ends in
|
|---|
| 9733 | @samp{.c}. @samp{s.%.c} as a pattern matches any file name that starts
|
|---|
| 9734 | with @samp{s.}, ends in @samp{.c} and is at least five characters long.
|
|---|
| 9735 | (There must be at least one character to match the @samp{%}.) The substring
|
|---|
| 9736 | that the @samp{%} matches is called the @dfn{stem}.@refill
|
|---|
| 9737 |
|
|---|
| 9738 | @samp{%} in a prerequisite of a pattern rule stands for the same stem
|
|---|
| 9739 | that was matched by the @samp{%} in the target. In order for the
|
|---|
| 9740 | pattern rule to apply, its target pattern must match the file name
|
|---|
| 9741 | under consideration and all of its prerequisites (after pattern
|
|---|
| 9742 | substitution) must name files that exist or can be made. These files
|
|---|
| 9743 | become prerequisites of the target.
|
|---|
| 9744 | @cindex prerequisite pattern, implicit
|
|---|
| 9745 |
|
|---|
| 9746 | Thus, a rule of the form
|
|---|
| 9747 |
|
|---|
| 9748 | @example
|
|---|
| 9749 | %.o : %.c ; @var{recipe}@dots{}
|
|---|
| 9750 | @end example
|
|---|
| 9751 |
|
|---|
| 9752 | @noindent
|
|---|
| 9753 | specifies how to make a file @file{@var{n}.o}, with another file
|
|---|
| 9754 | @file{@var{n}.c} as its prerequisite, provided that @file{@var{n}.c}
|
|---|
| 9755 | exists or can be made.
|
|---|
| 9756 |
|
|---|
| 9757 | There may also be prerequisites that do not use @samp{%}; such a prerequisite
|
|---|
| 9758 | attaches to every file made by this pattern rule. These unvarying
|
|---|
| 9759 | prerequisites are useful occasionally.
|
|---|
| 9760 |
|
|---|
| 9761 | A pattern rule need not have any prerequisites that contain @samp{%}, or
|
|---|
| 9762 | in fact any prerequisites at all. Such a rule is effectively a general
|
|---|
| 9763 | wildcard. It provides a way to make any file that matches the target
|
|---|
| 9764 | pattern. @xref{Last Resort}.
|
|---|
| 9765 |
|
|---|
| 9766 | More than one pattern rule may match a target. In this case
|
|---|
| 9767 | @code{make} will choose the ``best fit'' rule. @xref{Pattern Match,
|
|---|
| 9768 | ,How Patterns Match}.
|
|---|
| 9769 |
|
|---|
| 9770 | @c !!! The end of of this paragraph should be rewritten. --bob
|
|---|
| 9771 | Pattern rules may have more than one target. Unlike normal rules,
|
|---|
| 9772 | this does not act as many different rules with the same prerequisites
|
|---|
| 9773 | and recipe. If a pattern rule has multiple targets, @code{make} knows
|
|---|
| 9774 | that the rule's recipe is responsible for making all of the targets.
|
|---|
| 9775 | The recipe is executed only once to make all the targets. When
|
|---|
| 9776 | searching for a pattern rule to match a target, the target patterns of
|
|---|
| 9777 | a rule other than the one that matches the target in need of a rule
|
|---|
| 9778 | are incidental: @code{make} worries only about giving a recipe and
|
|---|
| 9779 | prerequisites to the file presently in question. However, when this
|
|---|
| 9780 | file's recipe is run, the other targets are marked as having been
|
|---|
| 9781 | updated themselves.
|
|---|
| 9782 | @cindex multiple targets, in pattern rule
|
|---|
| 9783 | @cindex target, multiple in pattern rule
|
|---|
| 9784 |
|
|---|
| 9785 | @node Pattern Examples, Automatic Variables, Pattern Intro, Pattern Rules
|
|---|
| 9786 | @subsection Pattern Rule Examples
|
|---|
| 9787 |
|
|---|
| 9788 | Here are some examples of pattern rules actually predefined in
|
|---|
| 9789 | @code{make}. First, the rule that compiles @samp{.c} files into @samp{.o}
|
|---|
| 9790 | files:@refill
|
|---|
| 9791 |
|
|---|
| 9792 | @example
|
|---|
| 9793 | %.o : %.c
|
|---|
| 9794 | $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
|
|---|
| 9795 | @end example
|
|---|
| 9796 |
|
|---|
| 9797 | @noindent
|
|---|
| 9798 | defines a rule that can make any file @file{@var{x}.o} from
|
|---|
| 9799 | @file{@var{x}.c}. The recipe uses the automatic variables @samp{$@@} and
|
|---|
| 9800 | @samp{$<} to substitute the names of the target file and the source file
|
|---|
| 9801 | in each case where the rule applies (@pxref{Automatic Variables}).@refill
|
|---|
| 9802 |
|
|---|
| 9803 | Here is a second built-in rule:
|
|---|
| 9804 |
|
|---|
| 9805 | @example
|
|---|
| 9806 | % :: RCS/%,v
|
|---|
| 9807 | $(CO) $(COFLAGS) $<
|
|---|
| 9808 | @end example
|
|---|
| 9809 |
|
|---|
| 9810 | @noindent
|
|---|
| 9811 | defines a rule that can make any file @file{@var{x}} whatsoever from a
|
|---|
| 9812 | corresponding file @file{@var{x},v} in the sub-directory @file{RCS}. Since
|
|---|
| 9813 | the target is @samp{%}, this rule will apply to any file whatever, provided
|
|---|
| 9814 | the appropriate prerequisite file exists. The double colon makes the rule
|
|---|
| 9815 | @dfn{terminal}, which means that its prerequisite may not be an intermediate
|
|---|
| 9816 | file (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}).@refill
|
|---|
| 9817 |
|
|---|
| 9818 | @need 500
|
|---|
| 9819 | This pattern rule has two targets:
|
|---|
| 9820 |
|
|---|
| 9821 | @example
|
|---|
| 9822 | @group
|
|---|
| 9823 | %.tab.c %.tab.h: %.y
|
|---|
| 9824 | bison -d $<
|
|---|
| 9825 | @end group
|
|---|
| 9826 | @end example
|
|---|
| 9827 |
|
|---|
| 9828 | @noindent
|
|---|
| 9829 | @c The following paragraph is rewritten to avoid overfull hboxes
|
|---|
| 9830 | This tells @code{make} that the recipe @samp{bison -d @var{x}.y} will
|
|---|
| 9831 | make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file
|
|---|
| 9832 | @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o}
|
|---|
| 9833 | and the file @file{scan.o} depends on the file @file{parse.tab.h},
|
|---|
| 9834 | when @file{parse.y} is changed, the recipe @samp{bison -d parse.y}
|
|---|
| 9835 | will be executed only once, and the prerequisites of both
|
|---|
| 9836 | @file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably
|
|---|
| 9837 | the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c}
|
|---|
| 9838 | and the file @file{scan.o} from @file{scan.c}, while @file{foo} is
|
|---|
| 9839 | linked from @file{parse.tab.o}, @file{scan.o}, and its other
|
|---|
| 9840 | prerequisites, and it will execute happily ever after.)@refill
|
|---|
| 9841 |
|
|---|
| 9842 | @node Automatic Variables, Pattern Match, Pattern Examples, Pattern Rules
|
|---|
| 9843 | @subsection Automatic Variables
|
|---|
| 9844 | @cindex automatic variables
|
|---|
| 9845 | @cindex variables, automatic
|
|---|
| 9846 | @cindex variables, and implicit rule
|
|---|
| 9847 |
|
|---|
| 9848 | Suppose you are writing a pattern rule to compile a @samp{.c} file into a
|
|---|
| 9849 | @samp{.o} file: how do you write the @samp{cc} command so that it operates
|
|---|
| 9850 | on the right source file name? You cannot write the name in the recipe,
|
|---|
| 9851 | because the name is different each time the implicit rule is applied.
|
|---|
| 9852 |
|
|---|
| 9853 | What you do is use a special feature of @code{make}, the @dfn{automatic
|
|---|
| 9854 | variables}. These variables have values computed afresh for each rule that
|
|---|
| 9855 | is executed, based on the target and prerequisites of the rule. In this
|
|---|
| 9856 | example, you would use @samp{$@@} for the object file name and @samp{$<}
|
|---|
| 9857 | for the source file name.
|
|---|
| 9858 |
|
|---|
| 9859 | @cindex automatic variables in prerequisites
|
|---|
| 9860 | @cindex prerequisites, and automatic variables
|
|---|
| 9861 | It's very important that you recognize the limited scope in which
|
|---|
| 9862 | automatic variable values are available: they only have values within
|
|---|
| 9863 | the recipe. In particular, you cannot use them anywhere
|
|---|
| 9864 | within the target list of a rule; they have no value there and will
|
|---|
| 9865 | expand to the empty string. Also, they cannot be accessed directly
|
|---|
| 9866 | within the prerequisite list of a rule. A common mistake is
|
|---|
| 9867 | attempting to use @code{$@@} within the prerequisites list; this will
|
|---|
| 9868 | not work. However, there is a special feature of GNU @code{make},
|
|---|
| 9869 | secondary expansion (@pxref{Secondary Expansion}), which will allow
|
|---|
| 9870 | automatic variable values to be used in prerequisite lists.
|
|---|
| 9871 |
|
|---|
| 9872 | Here is a table of automatic variables:
|
|---|
| 9873 |
|
|---|
| 9874 | @table @code
|
|---|
| 9875 | @vindex $@@
|
|---|
| 9876 | @vindex @@ @r{(automatic variable)}
|
|---|
| 9877 | @item $@@
|
|---|
| 9878 | The file name of the target of the rule. If the target is an archive
|
|---|
| 9879 | member, then @samp{$@@} is the name of the archive file. In a pattern
|
|---|
| 9880 | rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to
|
|---|
| 9881 | Pattern Rules}), @samp{$@@} is the name of whichever target caused the
|
|---|
| 9882 | rule's recipe to be run.
|
|---|
| 9883 |
|
|---|
| 9884 | @vindex $%
|
|---|
| 9885 | @vindex % @r{(automatic variable)}
|
|---|
| 9886 | @item $%
|
|---|
| 9887 | The target member name, when the target is an archive member.
|
|---|
| 9888 | @xref{Archives}. For example, if the target is @file{foo.a(bar.o)} then
|
|---|
| 9889 | @samp{$%} is @file{bar.o} and @samp{$@@} is @file{foo.a}. @samp{$%} is
|
|---|
| 9890 | empty when the target is not an archive member.
|
|---|
| 9891 |
|
|---|
| 9892 | @vindex $<
|
|---|
| 9893 | @vindex < @r{(automatic variable)}
|
|---|
| 9894 | @item $<
|
|---|
| 9895 | The name of the first prerequisite. If the target got its recipe from
|
|---|
| 9896 | an implicit rule, this will be the first prerequisite added by the
|
|---|
| 9897 | implicit rule (@pxref{Implicit Rules}).
|
|---|
| 9898 |
|
|---|
| 9899 | @vindex $?
|
|---|
| 9900 | @vindex ? @r{(automatic variable)}
|
|---|
| 9901 | @item $?
|
|---|
| 9902 | The names of all the prerequisites that are newer than the target, with
|
|---|
| 9903 | spaces between them. For prerequisites which are archive members, only
|
|---|
| 9904 | the named member is used (@pxref{Archives}).
|
|---|
| 9905 | @cindex prerequisites, list of changed
|
|---|
| 9906 | @cindex list of changed prerequisites
|
|---|
| 9907 |
|
|---|
| 9908 | @vindex $^
|
|---|
| 9909 | @vindex ^ @r{(automatic variable)}
|
|---|
| 9910 | @item $^
|
|---|
| 9911 | The names of all the prerequisites, with spaces between them. For
|
|---|
| 9912 | prerequisites which are archive members, only the named member is used
|
|---|
| 9913 | (@pxref{Archives}). A target has only one prerequisite on each other file
|
|---|
| 9914 | it depends on, no matter how many times each file is listed as a
|
|---|
| 9915 | prerequisite. So if you list a prerequisite more than once for a target,
|
|---|
| 9916 | the value of @code{$^} contains just one copy of the name. This list
|
|---|
| 9917 | does @strong{not} contain any of the order-only prerequisites; for those
|
|---|
| 9918 | see the @samp{$|} variable, below.
|
|---|
| 9919 | @cindex prerequisites, list of all
|
|---|
| 9920 | @cindex list of all prerequisites
|
|---|
| 9921 |
|
|---|
| 9922 | @vindex $+
|
|---|
| 9923 | @vindex + @r{(automatic variable)}
|
|---|
| 9924 | @item $+
|
|---|
| 9925 | This is like @samp{$^}, but prerequisites listed more than once are
|
|---|
| 9926 | duplicated in the order they were listed in the makefile. This is
|
|---|
| 9927 | primarily useful for use in linking commands where it is meaningful to
|
|---|
| 9928 | repeat library file names in a particular order.
|
|---|
| 9929 |
|
|---|
| 9930 | @vindex $|
|
|---|
| 9931 | @vindex | @r{(automatic variable)}
|
|---|
| 9932 | @item $|
|
|---|
| 9933 | The names of all the order-only prerequisites, with spaces between
|
|---|
| 9934 | them.
|
|---|
| 9935 |
|
|---|
| 9936 | @vindex $*
|
|---|
| 9937 | @vindex * @r{(automatic variable)}
|
|---|
| 9938 | @item $*
|
|---|
| 9939 | The stem with which an implicit rule matches (@pxref{Pattern Match, ,How
|
|---|
| 9940 | Patterns Match}). If the target is @file{dir/a.foo.b} and the target
|
|---|
| 9941 | pattern is @file{a.%.b} then the stem is @file{dir/foo}. The stem is
|
|---|
| 9942 | useful for constructing names of related files.@refill
|
|---|
| 9943 | @cindex stem, variable for
|
|---|
| 9944 |
|
|---|
| 9945 | In a static pattern rule, the stem is part of the file name that matched
|
|---|
| 9946 | the @samp{%} in the target pattern.
|
|---|
| 9947 |
|
|---|
| 9948 | In an explicit rule, there is no stem; so @samp{$*} cannot be determined
|
|---|
| 9949 | in that way. Instead, if the target name ends with a recognized suffix
|
|---|
| 9950 | (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}), @samp{$*} is set to
|
|---|
| 9951 | the target name minus the suffix. For example, if the target name is
|
|---|
| 9952 | @samp{foo.c}, then @samp{$*} is set to @samp{foo}, since @samp{.c} is a
|
|---|
| 9953 | suffix. GNU @code{make} does this bizarre thing only for compatibility
|
|---|
| 9954 | with other implementations of @code{make}. You should generally avoid
|
|---|
| 9955 | using @samp{$*} except in implicit rules or static pattern rules.@refill
|
|---|
| 9956 |
|
|---|
| 9957 | If the target name in an explicit rule does not end with a recognized
|
|---|
| 9958 | suffix, @samp{$*} is set to the empty string for that rule.
|
|---|
| 9959 | @end table
|
|---|
| 9960 |
|
|---|
| 9961 | @samp{$?} is useful even in explicit rules when you wish to operate on only
|
|---|
| 9962 | the prerequisites that have changed. For example, suppose that an archive
|
|---|
| 9963 | named @file{lib} is supposed to contain copies of several object files.
|
|---|
| 9964 | This rule copies just the changed object files into the archive:
|
|---|
| 9965 |
|
|---|
| 9966 | @example
|
|---|
| 9967 | @group
|
|---|
| 9968 | lib: foo.o bar.o lose.o win.o
|
|---|
| 9969 | ar r lib $?
|
|---|
| 9970 | @end group
|
|---|
| 9971 | @end example
|
|---|
| 9972 |
|
|---|
| 9973 | Of the variables listed above, four have values that are single file
|
|---|
| 9974 | names, and three have values that are lists of file names. These seven
|
|---|
| 9975 | have variants that get just the file's directory name or just the file
|
|---|
| 9976 | name within the directory. The variant variables' names are formed by
|
|---|
| 9977 | appending @samp{D} or @samp{F}, respectively. These variants are
|
|---|
| 9978 | semi-obsolete in GNU @code{make} since the functions @code{dir} and
|
|---|
| 9979 | @code{notdir} can be used to get a similar effect (@pxref{File Name
|
|---|
| 9980 | Functions, , Functions for File Names}). Note, however, that the
|
|---|
| 9981 | @samp{D} variants all omit the trailing slash which always appears in
|
|---|
| 9982 | the output of the @code{dir} function. Here is a table of the variants:
|
|---|
| 9983 |
|
|---|
| 9984 | @table @samp
|
|---|
| 9985 | @vindex $(@@D)
|
|---|
| 9986 | @vindex @@D @r{(automatic variable)}
|
|---|
| 9987 | @item $(@@D)
|
|---|
| 9988 | The directory part of the file name of the target, with the trailing
|
|---|
| 9989 | slash removed. If the value of @samp{$@@} is @file{dir/foo.o} then
|
|---|
| 9990 | @samp{$(@@D)} is @file{dir}. This value is @file{.} if @samp{$@@} does
|
|---|
| 9991 | not contain a slash.
|
|---|
| 9992 |
|
|---|
| 9993 | @vindex $(@@F)
|
|---|
| 9994 | @vindex @@F @r{(automatic variable)}
|
|---|
| 9995 | @item $(@@F)
|
|---|
| 9996 | The file-within-directory part of the file name of the target. If the
|
|---|
| 9997 | value of @samp{$@@} is @file{dir/foo.o} then @samp{$(@@F)} is
|
|---|
| 9998 | @file{foo.o}. @samp{$(@@F)} is equivalent to @samp{$(notdir $@@)}.
|
|---|
| 9999 |
|
|---|
| 10000 | @vindex $(*D)
|
|---|
| 10001 | @vindex *D @r{(automatic variable)}
|
|---|
| 10002 | @item $(*D)
|
|---|
| 10003 | @vindex $(*F)
|
|---|
| 10004 | @vindex *F @r{(automatic variable)}
|
|---|
| 10005 | @itemx $(*F)
|
|---|
| 10006 | The directory part and the file-within-directory
|
|---|
| 10007 | part of the stem; @file{dir} and @file{foo} in this example.
|
|---|
| 10008 |
|
|---|
| 10009 | @vindex $(%D)
|
|---|
| 10010 | @vindex %D @r{(automatic variable)}
|
|---|
| 10011 | @item $(%D)
|
|---|
| 10012 | @vindex $(%F)
|
|---|
| 10013 | @vindex %F @r{(automatic variable)}
|
|---|
| 10014 | @itemx $(%F)
|
|---|
| 10015 | The directory part and the file-within-directory part of the target
|
|---|
| 10016 | archive member name. This makes sense only for archive member targets
|
|---|
| 10017 | of the form @file{@var{archive}(@var{member})} and is useful only when
|
|---|
| 10018 | @var{member} may contain a directory name. (@xref{Archive Members,
|
|---|
| 10019 | ,Archive Members as Targets}.)
|
|---|
| 10020 |
|
|---|
| 10021 | @vindex $(<D)
|
|---|
| 10022 | @vindex <D @r{(automatic variable)}
|
|---|
| 10023 | @item $(<D)
|
|---|
| 10024 | @vindex $(<F)
|
|---|
| 10025 | @vindex <F @r{(automatic variable)}
|
|---|
| 10026 | @itemx $(<F)
|
|---|
| 10027 | The directory part and the file-within-directory
|
|---|
| 10028 | part of the first prerequisite.
|
|---|
| 10029 |
|
|---|
| 10030 | @vindex $(^D)
|
|---|
| 10031 | @vindex ^D @r{(automatic variable)}
|
|---|
| 10032 | @item $(^D)
|
|---|
| 10033 | @vindex $(^F)
|
|---|
| 10034 | @vindex ^F @r{(automatic variable)}
|
|---|
| 10035 | @itemx $(^F)
|
|---|
| 10036 | Lists of the directory parts and the file-within-directory
|
|---|
| 10037 | parts of all prerequisites.
|
|---|
| 10038 |
|
|---|
| 10039 | @vindex $(+D)
|
|---|
| 10040 | @vindex +D @r{(automatic variable)}
|
|---|
| 10041 | @item $(+D)
|
|---|
| 10042 | @vindex $(+F)
|
|---|
| 10043 | @vindex +F @r{(automatic variable)}
|
|---|
| 10044 | @itemx $(+F)
|
|---|
| 10045 | Lists of the directory parts and the file-within-directory
|
|---|
| 10046 | parts of all prerequisites, including multiple instances of duplicated
|
|---|
| 10047 | prerequisites.
|
|---|
| 10048 |
|
|---|
| 10049 | @vindex $(?D)
|
|---|
| 10050 | @vindex ?D @r{(automatic variable)}
|
|---|
| 10051 | @item $(?D)
|
|---|
| 10052 | @vindex $(?F)
|
|---|
| 10053 | @vindex ?F @r{(automatic variable)}
|
|---|
| 10054 | @itemx $(?F)
|
|---|
| 10055 | Lists of the directory parts and the file-within-directory parts of
|
|---|
| 10056 | all prerequisites that are newer than the target.
|
|---|
| 10057 | @end table
|
|---|
| 10058 |
|
|---|
| 10059 | Note that we use a special stylistic convention when we talk about these
|
|---|
| 10060 | automatic variables; we write ``the value of @samp{$<}'', rather than
|
|---|
| 10061 | @w{``the variable @code{<}''} as we would write for ordinary variables
|
|---|
| 10062 | such as @code{objects} and @code{CFLAGS}. We think this convention
|
|---|
| 10063 | looks more natural in this special case. Please do not assume it has a
|
|---|
| 10064 | deep significance; @samp{$<} refers to the variable named @code{<} just
|
|---|
| 10065 | as @samp{$(CFLAGS)} refers to the variable named @code{CFLAGS}.
|
|---|
| 10066 | You could just as well use @samp{$(<)} in place of @samp{$<}.
|
|---|
| 10067 |
|
|---|
| 10068 | @node Pattern Match, Match-Anything Rules, Automatic Variables, Pattern Rules
|
|---|
| 10069 | @subsection How Patterns Match
|
|---|
| 10070 |
|
|---|
| 10071 | @cindex stem
|
|---|
| 10072 | A target pattern is composed of a @samp{%} between a prefix and a suffix,
|
|---|
| 10073 | either or both of which may be empty. The pattern matches a file name only
|
|---|
| 10074 | if the file name starts with the prefix and ends with the suffix, without
|
|---|
| 10075 | overlap. The text between the prefix and the suffix is called the
|
|---|
| 10076 | @dfn{stem}. Thus, when the pattern @samp{%.o} matches the file name
|
|---|
| 10077 | @file{test.o}, the stem is @samp{test}. The pattern rule prerequisites are
|
|---|
| 10078 | turned into actual file names by substituting the stem for the character
|
|---|
| 10079 | @samp{%}. Thus, if in the same example one of the prerequisites is written
|
|---|
| 10080 | as @samp{%.c}, it expands to @samp{test.c}.@refill
|
|---|
| 10081 |
|
|---|
| 10082 | When the target pattern does not contain a slash (and it usually does
|
|---|
| 10083 | not), directory names in the file names are removed from the file name
|
|---|
| 10084 | before it is compared with the target prefix and suffix. After the
|
|---|
| 10085 | comparison of the file name to the target pattern, the directory
|
|---|
| 10086 | names, along with the slash that ends them, are added on to the
|
|---|
| 10087 | prerequisite file names generated from the pattern rule's prerequisite
|
|---|
| 10088 | patterns and the file name. The directories are ignored only for the
|
|---|
| 10089 | purpose of finding an implicit rule to use, not in the application of
|
|---|
| 10090 | that rule. Thus, @samp{e%t} matches the file name @file{src/eat},
|
|---|
| 10091 | with @samp{src/a} as the stem. When prerequisites are turned into file
|
|---|
| 10092 | names, the directories from the stem are added at the front, while the
|
|---|
| 10093 | rest of the stem is substituted for the @samp{%}. The stem
|
|---|
| 10094 | @samp{src/a} with a prerequisite pattern @samp{c%r} gives the file name
|
|---|
| 10095 | @file{src/car}.@refill
|
|---|
| 10096 |
|
|---|
| 10097 | @cindex pattern rules, order of
|
|---|
| 10098 | @cindex order of pattern rules
|
|---|
| 10099 | A pattern rule can be used to build a given file only if there is a
|
|---|
| 10100 | target pattern that matches the file name, @emph{and} all
|
|---|
| 10101 | prerequisites in that rule either exist or can be built. The rules
|
|---|
| 10102 | you write take precedence over those that are built in. Note however,
|
|---|
| 10103 | that a rule whose prerequisites actually exist or are mentioned always
|
|---|
| 10104 | takes priority over a rule with prerequisites that must be made by
|
|---|
| 10105 | chaining other implicit rules.
|
|---|
| 10106 |
|
|---|
| 10107 | @cindex stem, shortest
|
|---|
| 10108 | It is possible that more than one pattern rule will meet these
|
|---|
| 10109 | criteria. In that case, @code{make} will choose the rule with the
|
|---|
| 10110 | shortest stem (that is, the pattern that matches most specifically).
|
|---|
| 10111 | If more than one pattern rule has the shortest stem, @code{make} will
|
|---|
| 10112 | choose the first one found in the makefile.
|
|---|
| 10113 |
|
|---|
| 10114 | This algorithm results in more specific rules being preferred over
|
|---|
| 10115 | more generic ones; for example:
|
|---|
| 10116 |
|
|---|
| 10117 | @example
|
|---|
| 10118 | %.o: %.c
|
|---|
| 10119 | $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
|
|---|
| 10120 |
|
|---|
| 10121 | %.o : %.f
|
|---|
| 10122 | $(COMPILE.F) $(OUTPUT_OPTION) $<
|
|---|
| 10123 |
|
|---|
| 10124 | lib/%.o: lib/%.c
|
|---|
| 10125 | $(CC) -fPIC -c $(CFLAGS) $(CPPFLAGS) $< -o $@@
|
|---|
| 10126 | @end example
|
|---|
| 10127 |
|
|---|
| 10128 | Given these rules and asked to build @file{bar.o} where both
|
|---|
| 10129 | @file{bar.c} and @file{bar.f} exist, @code{make} will choose the first
|
|---|
| 10130 | rule and compile @file{bar.c} into @file{bar.o}. In the same
|
|---|
| 10131 | situation where @file{bar.c} does not exist, then @code{make} will
|
|---|
| 10132 | choose the second rule and compile @file{bar.f} into @file{bar.o}.
|
|---|
| 10133 |
|
|---|
| 10134 | If @code{make} is asked to build @file{lib/bar.o} and both
|
|---|
| 10135 | @file{lib/bar.c} and @file{lib/bar.f} exist, then the third rule will
|
|---|
| 10136 | be chosen since the stem for this rule (@samp{bar}) is shorter than
|
|---|
| 10137 | the stem for the first rule (@samp{lib/bar}). If @file{lib/bar.c}
|
|---|
| 10138 | does not exist then the third rule is not eligible and the second rule
|
|---|
| 10139 | will be used, even though the stem is longer.
|
|---|
| 10140 |
|
|---|
| 10141 | @node Match-Anything Rules, Canceling Rules, Pattern Match, Pattern Rules
|
|---|
| 10142 | @subsection Match-Anything Pattern Rules
|
|---|
| 10143 |
|
|---|
| 10144 | @cindex match-anything rule
|
|---|
| 10145 | @cindex terminal rule
|
|---|
| 10146 | When a pattern rule's target is just @samp{%}, it matches any file name
|
|---|
| 10147 | whatever. We call these rules @dfn{match-anything} rules. They are very
|
|---|
| 10148 | useful, but it can take a lot of time for @code{make} to think about them,
|
|---|
| 10149 | because it must consider every such rule for each file name listed either
|
|---|
| 10150 | as a target or as a prerequisite.
|
|---|
| 10151 |
|
|---|
| 10152 | Suppose the makefile mentions @file{foo.c}. For this target, @code{make}
|
|---|
| 10153 | would have to consider making it by linking an object file @file{foo.c.o},
|
|---|
| 10154 | or by C compilation-and-linking in one step from @file{foo.c.c}, or by
|
|---|
| 10155 | Pascal compilation-and-linking from @file{foo.c.p}, and many other
|
|---|
| 10156 | possibilities.
|
|---|
| 10157 |
|
|---|
| 10158 | We know these possibilities are ridiculous since @file{foo.c} is a C source
|
|---|
| 10159 | file, not an executable. If @code{make} did consider these possibilities,
|
|---|
| 10160 | it would ultimately reject them, because files such as @file{foo.c.o} and
|
|---|
| 10161 | @file{foo.c.p} would not exist. But these possibilities are so
|
|---|
| 10162 | numerous that @code{make} would run very slowly if it had to consider
|
|---|
| 10163 | them.@refill
|
|---|
| 10164 |
|
|---|
| 10165 | To gain speed, we have put various constraints on the way @code{make}
|
|---|
| 10166 | considers match-anything rules. There are two different constraints that
|
|---|
| 10167 | can be applied, and each time you define a match-anything rule you must
|
|---|
| 10168 | choose one or the other for that rule.
|
|---|
| 10169 |
|
|---|
| 10170 | One choice is to mark the match-anything rule as @dfn{terminal} by defining
|
|---|
| 10171 | it with a double colon. When a rule is terminal, it does not apply unless
|
|---|
| 10172 | its prerequisites actually exist. Prerequisites that could be made with
|
|---|
| 10173 | other implicit rules are not good enough. In other words, no further
|
|---|
| 10174 | chaining is allowed beyond a terminal rule.
|
|---|
| 10175 |
|
|---|
| 10176 | For example, the built-in implicit rules for extracting sources from RCS
|
|---|
| 10177 | and SCCS files are terminal; as a result, if the file @file{foo.c,v} does
|
|---|
| 10178 | not exist, @code{make} will not even consider trying to make it as an
|
|---|
| 10179 | intermediate file from @file{foo.c,v.o} or from @file{RCS/SCCS/s.foo.c,v}.
|
|---|
| 10180 | RCS and SCCS files are generally ultimate source files, which should not be
|
|---|
| 10181 | remade from any other files; therefore, @code{make} can save time by not
|
|---|
| 10182 | looking for ways to remake them.@refill
|
|---|
| 10183 |
|
|---|
| 10184 | If you do not mark the match-anything rule as terminal, then it is
|
|---|
| 10185 | non-terminal. A non-terminal match-anything rule cannot apply to a file name
|
|---|
| 10186 | that indicates a specific type of data. A file name indicates a specific
|
|---|
| 10187 | type of data if some non-match-anything implicit rule target matches it.
|
|---|
| 10188 |
|
|---|
| 10189 | For example, the file name @file{foo.c} matches the target for the pattern
|
|---|
| 10190 | rule @samp{%.c : %.y} (the rule to run Yacc). Regardless of whether this
|
|---|
| 10191 | rule is actually applicable (which happens only if there is a file
|
|---|
| 10192 | @file{foo.y}), the fact that its target matches is enough to prevent
|
|---|
| 10193 | consideration of any non-terminal match-anything rules for the file
|
|---|
| 10194 | @file{foo.c}. Thus, @code{make} will not even consider trying to make
|
|---|
| 10195 | @file{foo.c} as an executable file from @file{foo.c.o}, @file{foo.c.c},
|
|---|
| 10196 | @file{foo.c.p}, etc.@refill
|
|---|
| 10197 |
|
|---|
| 10198 | The motivation for this constraint is that non-terminal match-anything
|
|---|
| 10199 | rules are used for making files containing specific types of data (such as
|
|---|
| 10200 | executable files) and a file name with a recognized suffix indicates some
|
|---|
| 10201 | other specific type of data (such as a C source file).
|
|---|
| 10202 |
|
|---|
| 10203 | Special built-in dummy pattern rules are provided solely to recognize
|
|---|
| 10204 | certain file names so that non-terminal match-anything rules will not be
|
|---|
| 10205 | considered. These dummy rules have no prerequisites and no recipes, and
|
|---|
| 10206 | they are ignored for all other purposes. For example, the built-in
|
|---|
| 10207 | implicit rule
|
|---|
| 10208 |
|
|---|
| 10209 | @example
|
|---|
| 10210 | %.p :
|
|---|
| 10211 | @end example
|
|---|
| 10212 |
|
|---|
| 10213 | @noindent
|
|---|
| 10214 | exists to make sure that Pascal source files such as @file{foo.p} match a
|
|---|
| 10215 | specific target pattern and thereby prevent time from being wasted looking
|
|---|
| 10216 | for @file{foo.p.o} or @file{foo.p.c}.
|
|---|
| 10217 |
|
|---|
| 10218 | Dummy pattern rules such as the one for @samp{%.p} are made for every
|
|---|
| 10219 | suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}).
|
|---|
| 10220 |
|
|---|
| 10221 | @node Canceling Rules, , Match-Anything Rules, Pattern Rules
|
|---|
| 10222 | @subsection Canceling Implicit Rules
|
|---|
| 10223 |
|
|---|
| 10224 | You can override a built-in implicit rule (or one you have defined
|
|---|
| 10225 | yourself) by defining a new pattern rule with the same target and
|
|---|
| 10226 | prerequisites, but a different recipe. When the new rule is defined, the
|
|---|
| 10227 | built-in one is replaced. The new rule's position in the sequence of
|
|---|
| 10228 | implicit rules is determined by where you write the new rule.
|
|---|
| 10229 |
|
|---|
| 10230 | You can cancel a built-in implicit rule by defining a pattern rule with the
|
|---|
| 10231 | same target and prerequisites, but no recipe. For example, the following
|
|---|
| 10232 | would cancel the rule that runs the assembler:
|
|---|
| 10233 |
|
|---|
| 10234 | @example
|
|---|
| 10235 | %.o : %.s
|
|---|
| 10236 | @end example
|
|---|
| 10237 |
|
|---|
| 10238 | @node Last Resort, Suffix Rules, Pattern Rules, Implicit Rules
|
|---|
| 10239 | @section Defining Last-Resort Default Rules
|
|---|
| 10240 | @cindex last-resort default rules
|
|---|
| 10241 | @cindex default rules, last-resort
|
|---|
| 10242 |
|
|---|
| 10243 | You can define a last-resort implicit rule by writing a terminal
|
|---|
| 10244 | match-anything pattern rule with no prerequisites (@pxref{Match-Anything
|
|---|
| 10245 | Rules}). This is just like any other pattern rule; the only thing
|
|---|
| 10246 | special about it is that it will match any target. So such a rule's
|
|---|
| 10247 | recipe is used for all targets and prerequisites that have no recipe
|
|---|
| 10248 | of their own and for which no other implicit rule applies.
|
|---|
| 10249 |
|
|---|
| 10250 | For example, when testing a makefile, you might not care if the source
|
|---|
| 10251 | files contain real data, only that they exist. Then you might do this:
|
|---|
| 10252 |
|
|---|
| 10253 | @example
|
|---|
| 10254 | %::
|
|---|
| 10255 | touch $@@
|
|---|
| 10256 | @end example
|
|---|
| 10257 |
|
|---|
| 10258 | @noindent
|
|---|
| 10259 | to cause all the source files needed (as prerequisites) to be created
|
|---|
| 10260 | automatically.
|
|---|
| 10261 |
|
|---|
| 10262 | @findex .DEFAULT
|
|---|
| 10263 | You can instead define a recipe to be used for targets for which there
|
|---|
| 10264 | are no rules at all, even ones which don't specify recipes. You do
|
|---|
| 10265 | this by writing a rule for the target @code{.DEFAULT}. Such a rule's
|
|---|
| 10266 | recipe is used for all prerequisites which do not appear as targets in
|
|---|
| 10267 | any explicit rule, and for which no implicit rule applies. Naturally,
|
|---|
| 10268 | there is no @code{.DEFAULT} rule unless you write one.
|
|---|
| 10269 |
|
|---|
| 10270 | If you use @code{.DEFAULT} with no recipe or prerequisites:
|
|---|
| 10271 |
|
|---|
| 10272 | @example
|
|---|
| 10273 | .DEFAULT:
|
|---|
| 10274 | @end example
|
|---|
| 10275 |
|
|---|
| 10276 | @noindent
|
|---|
| 10277 | the recipe previously stored for @code{.DEFAULT} is cleared. Then
|
|---|
| 10278 | @code{make} acts as if you had never defined @code{.DEFAULT} at all.
|
|---|
| 10279 |
|
|---|
| 10280 | If you do not want a target to get the recipe from a match-anything
|
|---|
| 10281 | pattern rule or @code{.DEFAULT}, but you also do not want any recipe
|
|---|
| 10282 | to be run for the target, you can give it an empty recipe
|
|---|
| 10283 | (@pxref{Empty Recipes, ,Defining Empty Recipes}).@refill
|
|---|
| 10284 |
|
|---|
| 10285 | You can use a last-resort rule to override part of another makefile.
|
|---|
| 10286 | @xref{Overriding Makefiles, , Overriding Part of Another Makefile}.
|
|---|
| 10287 |
|
|---|
| 10288 | @node Suffix Rules, Implicit Rule Search, Last Resort, Implicit Rules
|
|---|
| 10289 | @section Old-Fashioned Suffix Rules
|
|---|
| 10290 | @cindex old-fashioned suffix rules
|
|---|
| 10291 | @cindex suffix rule
|
|---|
| 10292 |
|
|---|
| 10293 | @dfn{Suffix rules} are the old-fashioned way of defining implicit rules for
|
|---|
| 10294 | @code{make}. Suffix rules are obsolete because pattern rules are more
|
|---|
| 10295 | general and clearer. They are supported in GNU @code{make} for
|
|---|
| 10296 | compatibility with old makefiles. They come in two kinds:
|
|---|
| 10297 | @dfn{double-suffix} and @dfn{single-suffix}.@refill
|
|---|
| 10298 |
|
|---|
| 10299 | A double-suffix rule is defined by a pair of suffixes: the target suffix
|
|---|
| 10300 | and the source suffix. It matches any file whose name ends with the
|
|---|
| 10301 | target suffix. The corresponding implicit prerequisite is made by
|
|---|
| 10302 | replacing the target suffix with the source suffix in the file name. A
|
|---|
| 10303 | two-suffix rule whose target and source suffixes are @samp{.o} and
|
|---|
| 10304 | @samp{.c} is equivalent to the pattern rule @samp{%.o : %.c}.
|
|---|
| 10305 |
|
|---|
| 10306 | A single-suffix rule is defined by a single suffix, which is the source
|
|---|
| 10307 | suffix. It matches any file name, and the corresponding implicit
|
|---|
| 10308 | prerequisite name is made by appending the source suffix. A single-suffix
|
|---|
| 10309 | rule whose source suffix is @samp{.c} is equivalent to the pattern rule
|
|---|
| 10310 | @samp{% : %.c}.
|
|---|
| 10311 |
|
|---|
| 10312 | Suffix rule definitions are recognized by comparing each rule's target
|
|---|
| 10313 | against a defined list of known suffixes. When @code{make} sees a rule
|
|---|
| 10314 | whose target is a known suffix, this rule is considered a single-suffix
|
|---|
| 10315 | rule. When @code{make} sees a rule whose target is two known suffixes
|
|---|
| 10316 | concatenated, this rule is taken as a double-suffix rule.
|
|---|
| 10317 |
|
|---|
| 10318 | For example, @samp{.c} and @samp{.o} are both on the default list of
|
|---|
| 10319 | known suffixes. Therefore, if you define a rule whose target is
|
|---|
| 10320 | @samp{.c.o}, @code{make} takes it to be a double-suffix rule with source
|
|---|
| 10321 | suffix @samp{.c} and target suffix @samp{.o}. Here is the old-fashioned
|
|---|
| 10322 | way to define the rule for compiling a C source file:@refill
|
|---|
| 10323 |
|
|---|
| 10324 | @example
|
|---|
| 10325 | .c.o:
|
|---|
| 10326 | $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
|
|---|
| 10327 | @end example
|
|---|
| 10328 |
|
|---|
| 10329 | Suffix rules cannot have any prerequisites of their own. If they have any,
|
|---|
| 10330 | they are treated as normal files with funny names, not as suffix rules.
|
|---|
| 10331 | Thus, the rule:
|
|---|
| 10332 |
|
|---|
| 10333 | @example
|
|---|
| 10334 | .c.o: foo.h
|
|---|
| 10335 | $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
|
|---|
| 10336 | @end example
|
|---|
| 10337 |
|
|---|
| 10338 | @noindent
|
|---|
| 10339 | tells how to make the file @file{.c.o} from the prerequisite file
|
|---|
| 10340 | @file{foo.h}, and is not at all like the pattern rule:
|
|---|
| 10341 |
|
|---|
| 10342 | @example
|
|---|
| 10343 | %.o: %.c foo.h
|
|---|
| 10344 | $(CC) -c $(CFLAGS) $(CPPFLAGS) -o $@@ $<
|
|---|
| 10345 | @end example
|
|---|
| 10346 |
|
|---|
| 10347 | @noindent
|
|---|
| 10348 | which tells how to make @samp{.o} files from @samp{.c} files, and makes all
|
|---|
| 10349 | @samp{.o} files using this pattern rule also depend on @file{foo.h}.
|
|---|
| 10350 |
|
|---|
| 10351 | Suffix rules with no recipe are also meaningless. They do not remove
|
|---|
| 10352 | previous rules as do pattern rules with no recipe (@pxref{Canceling
|
|---|
| 10353 | Rules, , Canceling Implicit Rules}). They simply enter the suffix or
|
|---|
| 10354 | pair of suffixes concatenated as a target in the data base.@refill
|
|---|
| 10355 |
|
|---|
| 10356 | @findex .SUFFIXES
|
|---|
| 10357 | The known suffixes are simply the names of the prerequisites of the special
|
|---|
| 10358 | target @code{.SUFFIXES}. You can add your own suffixes by writing a rule
|
|---|
| 10359 | for @code{.SUFFIXES} that adds more prerequisites, as in:
|
|---|
| 10360 |
|
|---|
| 10361 | @example
|
|---|
| 10362 | .SUFFIXES: .hack .win
|
|---|
| 10363 | @end example
|
|---|
| 10364 |
|
|---|
| 10365 | @noindent
|
|---|
| 10366 | which adds @samp{.hack} and @samp{.win} to the end of the list of suffixes.
|
|---|
| 10367 |
|
|---|
| 10368 | If you wish to eliminate the default known suffixes instead of just adding
|
|---|
| 10369 | to them, write a rule for @code{.SUFFIXES} with no prerequisites. By
|
|---|
| 10370 | special dispensation, this eliminates all existing prerequisites of
|
|---|
| 10371 | @code{.SUFFIXES}. You can then write another rule to add the suffixes you
|
|---|
| 10372 | want. For example,
|
|---|
| 10373 |
|
|---|
| 10374 | @example
|
|---|
| 10375 | @group
|
|---|
| 10376 | .SUFFIXES: # @r{Delete the default suffixes}
|
|---|
| 10377 | .SUFFIXES: .c .o .h # @r{Define our suffix list}
|
|---|
| 10378 | @end group
|
|---|
| 10379 | @end example
|
|---|
| 10380 |
|
|---|
| 10381 | The @samp{-r} or @samp{--no-builtin-rules} flag causes the default
|
|---|
| 10382 | list of suffixes to be empty.
|
|---|
| 10383 |
|
|---|
| 10384 | @vindex SUFFIXES
|
|---|
| 10385 | The variable @code{SUFFIXES} is defined to the default list of suffixes
|
|---|
| 10386 | before @code{make} reads any makefiles. You can change the list of suffixes
|
|---|
| 10387 | with a rule for the special target @code{.SUFFIXES}, but that does not alter
|
|---|
| 10388 | this variable.
|
|---|
| 10389 |
|
|---|
| 10390 | @node Implicit Rule Search, , Suffix Rules, Implicit Rules
|
|---|
| 10391 | @section Implicit Rule Search Algorithm
|
|---|
| 10392 | @cindex implicit rule, search algorithm
|
|---|
| 10393 | @cindex search algorithm, implicit rule
|
|---|
| 10394 |
|
|---|
| 10395 | Here is the procedure @code{make} uses for searching for an implicit rule
|
|---|
| 10396 | for a target @var{t}. This procedure is followed for each double-colon
|
|---|
| 10397 | rule with no recipe, for each target of ordinary rules none of which have
|
|---|
| 10398 | a recipe, and for each prerequisite that is not the target of any rule. It
|
|---|
| 10399 | is also followed recursively for prerequisites that come from implicit
|
|---|
| 10400 | rules, in the search for a chain of rules.
|
|---|
| 10401 |
|
|---|
| 10402 | Suffix rules are not mentioned in this algorithm because suffix rules are
|
|---|
| 10403 | converted to equivalent pattern rules once the makefiles have been read in.
|
|---|
| 10404 |
|
|---|
| 10405 | For an archive member target of the form
|
|---|
| 10406 | @samp{@var{archive}(@var{member})}, the following algorithm is run
|
|---|
| 10407 | twice, first using the entire target name @var{t}, and second using
|
|---|
| 10408 | @samp{(@var{member})} as the target @var{t} if the first run found no
|
|---|
| 10409 | rule.@refill
|
|---|
| 10410 |
|
|---|
| 10411 | @enumerate
|
|---|
| 10412 | @item
|
|---|
| 10413 | Split @var{t} into a directory part, called @var{d}, and the rest,
|
|---|
| 10414 | called @var{n}. For example, if @var{t} is @samp{src/foo.o}, then
|
|---|
| 10415 | @var{d} is @samp{src/} and @var{n} is @samp{foo.o}.@refill
|
|---|
| 10416 |
|
|---|
| 10417 | @item
|
|---|
| 10418 | Make a list of all the pattern rules one of whose targets matches
|
|---|
| 10419 | @var{t} or @var{n}. If the target pattern contains a slash, it is
|
|---|
| 10420 | matched against @var{t}; otherwise, against @var{n}.
|
|---|
| 10421 |
|
|---|
| 10422 | @item
|
|---|
| 10423 | If any rule in that list is @emph{not} a match-anything rule, then
|
|---|
| 10424 | remove all non-terminal match-anything rules from the list.
|
|---|
| 10425 |
|
|---|
| 10426 | @item
|
|---|
| 10427 | Remove from the list all rules with no recipe.
|
|---|
| 10428 |
|
|---|
| 10429 | @item
|
|---|
| 10430 | For each pattern rule in the list:
|
|---|
| 10431 |
|
|---|
| 10432 | @enumerate a
|
|---|
| 10433 | @item
|
|---|
| 10434 | Find the stem @var{s}, which is the nonempty part of @var{t} or @var{n}
|
|---|
| 10435 | matched by the @samp{%} in the target pattern.@refill
|
|---|
| 10436 |
|
|---|
| 10437 | @item
|
|---|
| 10438 | Compute the prerequisite names by substituting @var{s} for @samp{%}; if
|
|---|
| 10439 | the target pattern does not contain a slash, append @var{d} to
|
|---|
| 10440 | the front of each prerequisite name.@refill
|
|---|
| 10441 |
|
|---|
| 10442 | @item
|
|---|
| 10443 | Test whether all the prerequisites exist or ought to exist. (If a
|
|---|
| 10444 | file name is mentioned in the makefile as a target or as an explicit
|
|---|
| 10445 | prerequisite, then we say it ought to exist.)
|
|---|
| 10446 |
|
|---|
| 10447 | If all prerequisites exist or ought to exist, or there are no prerequisites,
|
|---|
| 10448 | then this rule applies.
|
|---|
| 10449 | @end enumerate
|
|---|
| 10450 |
|
|---|
| 10451 | @item
|
|---|
| 10452 | If no pattern rule has been found so far, try harder.
|
|---|
| 10453 | For each pattern rule in the list:
|
|---|
| 10454 |
|
|---|
| 10455 | @enumerate a
|
|---|
| 10456 | @item
|
|---|
| 10457 | If the rule is terminal, ignore it and go on to the next rule.
|
|---|
| 10458 |
|
|---|
| 10459 | @item
|
|---|
| 10460 | Compute the prerequisite names as before.
|
|---|
| 10461 |
|
|---|
| 10462 | @item
|
|---|
| 10463 | Test whether all the prerequisites exist or ought to exist.
|
|---|
| 10464 |
|
|---|
| 10465 | @item
|
|---|
| 10466 | For each prerequisite that does not exist, follow this algorithm
|
|---|
| 10467 | recursively to see if the prerequisite can be made by an implicit
|
|---|
| 10468 | rule.
|
|---|
| 10469 |
|
|---|
| 10470 | @item
|
|---|
| 10471 | If all prerequisites exist, ought to exist, or can be
|
|---|
| 10472 | made by implicit rules, then this rule applies.
|
|---|
| 10473 | @end enumerate
|
|---|
| 10474 |
|
|---|
| 10475 | @item
|
|---|
| 10476 | If no implicit rule applies, the rule for @code{.DEFAULT}, if any,
|
|---|
| 10477 | applies. In that case, give @var{t} the same recipe that
|
|---|
| 10478 | @code{.DEFAULT} has. Otherwise, there is no recipe for @var{t}.
|
|---|
| 10479 | @end enumerate
|
|---|
| 10480 |
|
|---|
| 10481 | Once a rule that applies has been found, for each target pattern of
|
|---|
| 10482 | the rule other than the one that matched @var{t} or @var{n}, the
|
|---|
| 10483 | @samp{%} in the pattern is replaced with @var{s} and the resultant
|
|---|
| 10484 | file name is stored until the recipe to remake the target file @var{t}
|
|---|
| 10485 | is executed. After the recipe is executed, each of these stored file
|
|---|
| 10486 | names are entered into the data base and marked as having been updated
|
|---|
| 10487 | and having the same update status as the file @var{t}.
|
|---|
| 10488 |
|
|---|
| 10489 | When the recipe of a pattern rule is executed for @var{t}, the
|
|---|
| 10490 | automatic variables are set corresponding to the target and
|
|---|
| 10491 | prerequisites. @xref{Automatic Variables}.
|
|---|
| 10492 |
|
|---|
| 10493 | @node Archives, Extending make, Implicit Rules, Top
|
|---|
| 10494 | @chapter Using @code{make} to Update Archive Files
|
|---|
| 10495 | @cindex archive
|
|---|
| 10496 |
|
|---|
| 10497 | @dfn{Archive files} are files containing named sub-files called
|
|---|
| 10498 | @dfn{members}; they are maintained with the program @code{ar} and their
|
|---|
| 10499 | main use is as subroutine libraries for linking.
|
|---|
| 10500 |
|
|---|
| 10501 | @menu
|
|---|
| 10502 | * Archive Members:: Archive members as targets.
|
|---|
| 10503 | * Archive Update:: The implicit rule for archive member targets.
|
|---|
| 10504 | * Archive Pitfalls:: Dangers to watch out for when using archives.
|
|---|
| 10505 | * Archive Suffix Rules:: You can write a special kind of suffix rule
|
|---|
| 10506 | for updating archives.
|
|---|
| 10507 | @end menu
|
|---|
| 10508 |
|
|---|
| 10509 | @node Archive Members, Archive Update, Archives, Archives
|
|---|
| 10510 | @section Archive Members as Targets
|
|---|
| 10511 | @cindex archive member targets
|
|---|
| 10512 |
|
|---|
| 10513 | An individual member of an archive file can be used as a target or
|
|---|
| 10514 | prerequisite in @code{make}. You specify the member named @var{member} in
|
|---|
| 10515 | archive file @var{archive} as follows:
|
|---|
| 10516 |
|
|---|
| 10517 | @example
|
|---|
| 10518 | @var{archive}(@var{member})
|
|---|
| 10519 | @end example
|
|---|
| 10520 |
|
|---|
| 10521 | @noindent
|
|---|
| 10522 | This construct is available only in targets and prerequisites, not in
|
|---|
| 10523 | recipes! Most programs that you might use in recipes do not support
|
|---|
| 10524 | this syntax and cannot act directly on archive members. Only
|
|---|
| 10525 | @code{ar} and other programs specifically designed to operate on
|
|---|
| 10526 | archives can do so. Therefore, valid recipes to update an archive
|
|---|
| 10527 | member target probably must use @code{ar}. For example, this rule
|
|---|
| 10528 | says to create a member @file{hack.o} in archive @file{foolib} by
|
|---|
| 10529 | copying the file @file{hack.o}:
|
|---|
| 10530 |
|
|---|
| 10531 | @example
|
|---|
| 10532 | foolib(hack.o) : hack.o
|
|---|
| 10533 | ar cr foolib hack.o
|
|---|
| 10534 | @end example
|
|---|
| 10535 |
|
|---|
| 10536 | In fact, nearly all archive member targets are updated in just this way
|
|---|
| 10537 | and there is an implicit rule to do it for you. @strong{Please note:} The
|
|---|
| 10538 | @samp{c} flag to @code{ar} is required if the archive file does not
|
|---|
| 10539 | already exist.
|
|---|
| 10540 |
|
|---|
| 10541 | To specify several members in the same archive, you can write all the
|
|---|
| 10542 | member names together between the parentheses. For example:
|
|---|
| 10543 |
|
|---|
| 10544 | @example
|
|---|
| 10545 | foolib(hack.o kludge.o)
|
|---|
| 10546 | @end example
|
|---|
| 10547 |
|
|---|
| 10548 | @noindent
|
|---|
| 10549 | is equivalent to:
|
|---|
| 10550 |
|
|---|
| 10551 | @example
|
|---|
| 10552 | foolib(hack.o) foolib(kludge.o)
|
|---|
| 10553 | @end example
|
|---|
| 10554 |
|
|---|
| 10555 | @cindex wildcard, in archive member
|
|---|
| 10556 | You can also use shell-style wildcards in an archive member reference.
|
|---|
| 10557 | @xref{Wildcards, ,Using Wildcard Characters in File Names}. For
|
|---|
| 10558 | example, @w{@samp{foolib(*.o)}} expands to all existing members of the
|
|---|
| 10559 | @file{foolib} archive whose names end in @samp{.o}; perhaps
|
|---|
| 10560 | @samp{@w{foolib(hack.o)} @w{foolib(kludge.o)}}.
|
|---|
| 10561 |
|
|---|
| 10562 | @node Archive Update, Archive Pitfalls, Archive Members, Archives
|
|---|
| 10563 | @section Implicit Rule for Archive Member Targets
|
|---|
| 10564 |
|
|---|
| 10565 | Recall that a target that looks like @file{@var{a}(@var{m})} stands for the
|
|---|
| 10566 | member named @var{m} in the archive file @var{a}.
|
|---|
| 10567 |
|
|---|
| 10568 | When @code{make} looks for an implicit rule for such a target, as a special
|
|---|
| 10569 | feature it considers implicit rules that match @file{(@var{m})}, as well as
|
|---|
| 10570 | those that match the actual target @file{@var{a}(@var{m})}.
|
|---|
| 10571 |
|
|---|
| 10572 | This causes one special rule whose target is @file{(%)} to match. This
|
|---|
| 10573 | rule updates the target @file{@var{a}(@var{m})} by copying the file @var{m}
|
|---|
| 10574 | into the archive. For example, it will update the archive member target
|
|---|
| 10575 | @file{foo.a(bar.o)} by copying the @emph{file} @file{bar.o} into the
|
|---|
| 10576 | archive @file{foo.a} as a @emph{member} named @file{bar.o}.
|
|---|
| 10577 |
|
|---|
| 10578 | When this rule is chained with others, the result is very powerful.
|
|---|
| 10579 | Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the
|
|---|
| 10580 | @samp{(} and @samp{)} from being interpreted specially by the shell) in
|
|---|
| 10581 | the presence of a file @file{bar.c} is enough to cause the following
|
|---|
| 10582 | recipe to be run, even without a makefile:
|
|---|
| 10583 |
|
|---|
| 10584 | @example
|
|---|
| 10585 | cc -c bar.c -o bar.o
|
|---|
| 10586 | ar r foo.a bar.o
|
|---|
| 10587 | rm -f bar.o
|
|---|
| 10588 | @end example
|
|---|
| 10589 |
|
|---|
| 10590 | @noindent
|
|---|
| 10591 | Here @code{make} has envisioned the file @file{bar.o} as an intermediate
|
|---|
| 10592 | file. @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 10593 |
|
|---|
| 10594 | Implicit rules such as this one are written using the automatic variable
|
|---|
| 10595 | @samp{$%}. @xref{Automatic Variables}.
|
|---|
| 10596 |
|
|---|
| 10597 | An archive member name in an archive cannot contain a directory name, but
|
|---|
| 10598 | it may be useful in a makefile to pretend that it does. If you write an
|
|---|
| 10599 | archive member target @file{foo.a(dir/file.o)}, @code{make} will perform
|
|---|
| 10600 | automatic updating with this recipe:
|
|---|
| 10601 |
|
|---|
| 10602 | @example
|
|---|
| 10603 | ar r foo.a dir/file.o
|
|---|
| 10604 | @end example
|
|---|
| 10605 |
|
|---|
| 10606 | @noindent
|
|---|
| 10607 | which has the effect of copying the file @file{dir/file.o} into a member
|
|---|
| 10608 | named @file{file.o}. In connection with such usage, the automatic variables
|
|---|
| 10609 | @code{%D} and @code{%F} may be useful.
|
|---|
| 10610 |
|
|---|
| 10611 | @menu
|
|---|
| 10612 | * Archive Symbols:: How to update archive symbol directories.
|
|---|
| 10613 | @end menu
|
|---|
| 10614 |
|
|---|
| 10615 | @node Archive Symbols, , Archive Update, Archive Update
|
|---|
| 10616 | @subsection Updating Archive Symbol Directories
|
|---|
| 10617 | @cindex @code{__.SYMDEF}
|
|---|
| 10618 | @cindex updating archive symbol directories
|
|---|
| 10619 | @cindex archive symbol directory updating
|
|---|
| 10620 | @cindex symbol directories, updating archive
|
|---|
| 10621 | @cindex directories, updating archive symbol
|
|---|
| 10622 |
|
|---|
| 10623 | An archive file that is used as a library usually contains a special member
|
|---|
| 10624 | named @file{__.SYMDEF} that contains a directory of the external symbol
|
|---|
| 10625 | names defined by all the other members. After you update any other
|
|---|
| 10626 | members, you need to update @file{__.SYMDEF} so that it will summarize the
|
|---|
| 10627 | other members properly. This is done by running the @code{ranlib} program:
|
|---|
| 10628 |
|
|---|
| 10629 | @example
|
|---|
| 10630 | ranlib @var{archivefile}
|
|---|
| 10631 | @end example
|
|---|
| 10632 |
|
|---|
| 10633 | Normally you would put this command in the rule for the archive file,
|
|---|
| 10634 | and make all the members of the archive file prerequisites of that rule.
|
|---|
| 10635 | For example,
|
|---|
| 10636 |
|
|---|
| 10637 | @example
|
|---|
| 10638 | libfoo.a: libfoo.a(x.o) libfoo.a(y.o) @dots{}
|
|---|
| 10639 | ranlib libfoo.a
|
|---|
| 10640 | @end example
|
|---|
| 10641 |
|
|---|
| 10642 | @noindent
|
|---|
| 10643 | The effect of this is to update archive members @file{x.o}, @file{y.o},
|
|---|
| 10644 | etc., and then update the symbol directory member @file{__.SYMDEF} by
|
|---|
| 10645 | running @code{ranlib}. The rules for updating the members are not shown
|
|---|
| 10646 | here; most likely you can omit them and use the implicit rule which copies
|
|---|
| 10647 | files into the archive, as described in the preceding section.
|
|---|
| 10648 |
|
|---|
| 10649 | This is not necessary when using the GNU @code{ar} program, which
|
|---|
| 10650 | updates the @file{__.SYMDEF} member automatically.
|
|---|
| 10651 |
|
|---|
| 10652 | @node Archive Pitfalls, Archive Suffix Rules, Archive Update, Archives
|
|---|
| 10653 | @section Dangers When Using Archives
|
|---|
| 10654 | @cindex archive, and parallel execution
|
|---|
| 10655 | @cindex parallel execution, and archive update
|
|---|
| 10656 | @cindex archive, and @code{-j}
|
|---|
| 10657 | @cindex @code{-j}, and archive update
|
|---|
| 10658 |
|
|---|
| 10659 | It is important to be careful when using parallel execution (the
|
|---|
| 10660 | @code{-j} switch; @pxref{Parallel, ,Parallel Execution}) and archives.
|
|---|
| 10661 | If multiple @code{ar} commands run at the same time on the same archive
|
|---|
| 10662 | file, they will not know about each other and can corrupt the file.
|
|---|
| 10663 |
|
|---|
| 10664 | Possibly a future version of @code{make} will provide a mechanism to
|
|---|
| 10665 | circumvent this problem by serializing all recipes that operate on the
|
|---|
| 10666 | same archive file. But for the time being, you must either write your
|
|---|
| 10667 | makefiles to avoid this problem in some other way, or not use @code{-j}.
|
|---|
| 10668 |
|
|---|
| 10669 | @node Archive Suffix Rules, , Archive Pitfalls, Archives
|
|---|
| 10670 | @section Suffix Rules for Archive Files
|
|---|
| 10671 | @cindex suffix rule, for archive
|
|---|
| 10672 | @cindex archive, suffix rule for
|
|---|
| 10673 | @cindex library archive, suffix rule for
|
|---|
| 10674 | @cindex @code{.a} (archives)
|
|---|
| 10675 |
|
|---|
| 10676 | You can write a special kind of suffix rule for dealing with archive
|
|---|
| 10677 | files. @xref{Suffix Rules}, for a full explanation of suffix rules.
|
|---|
| 10678 | Archive suffix rules are obsolete in GNU @code{make}, because pattern
|
|---|
| 10679 | rules for archives are a more general mechanism (@pxref{Archive
|
|---|
| 10680 | Update}). But they are retained for compatibility with other
|
|---|
| 10681 | @code{make}s.
|
|---|
| 10682 |
|
|---|
| 10683 | To write a suffix rule for archives, you simply write a suffix rule
|
|---|
| 10684 | using the target suffix @samp{.a} (the usual suffix for archive files).
|
|---|
| 10685 | For example, here is the old-fashioned suffix rule to update a library
|
|---|
| 10686 | archive from C source files:
|
|---|
| 10687 |
|
|---|
| 10688 | @example
|
|---|
| 10689 | @group
|
|---|
| 10690 | .c.a:
|
|---|
| 10691 | $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
|
|---|
| 10692 | $(AR) r $@@ $*.o
|
|---|
| 10693 | $(RM) $*.o
|
|---|
| 10694 | @end group
|
|---|
| 10695 | @end example
|
|---|
| 10696 |
|
|---|
| 10697 | @noindent
|
|---|
| 10698 | This works just as if you had written the pattern rule:
|
|---|
| 10699 |
|
|---|
| 10700 | @example
|
|---|
| 10701 | @group
|
|---|
| 10702 | (%.o): %.c
|
|---|
| 10703 | $(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
|
|---|
| 10704 | $(AR) r $@@ $*.o
|
|---|
| 10705 | $(RM) $*.o
|
|---|
| 10706 | @end group
|
|---|
| 10707 | @end example
|
|---|
| 10708 |
|
|---|
| 10709 | In fact, this is just what @code{make} does when it sees a suffix rule
|
|---|
| 10710 | with @samp{.a} as the target suffix. Any double-suffix rule
|
|---|
| 10711 | @w{@samp{.@var{x}.a}} is converted to a pattern rule with the target
|
|---|
| 10712 | pattern @samp{(%.o)} and a prerequisite pattern of @samp{%.@var{x}}.
|
|---|
| 10713 |
|
|---|
| 10714 | Since you might want to use @samp{.a} as the suffix for some other kind
|
|---|
| 10715 | of file, @code{make} also converts archive suffix rules to pattern rules
|
|---|
| 10716 | in the normal way (@pxref{Suffix Rules}). Thus a double-suffix rule
|
|---|
| 10717 | @w{@samp{.@var{x}.a}} produces two pattern rules: @samp{@w{(%.o):}
|
|---|
| 10718 | @w{%.@var{x}}} and @samp{@w{%.a}: @w{%.@var{x}}}.@refill
|
|---|
| 10719 |
|
|---|
| 10720 | @node Extending make, Integrating make, Archives, Top
|
|---|
| 10721 | @chapter Extending GNU @code{make}
|
|---|
| 10722 | @cindex make extensions
|
|---|
| 10723 |
|
|---|
| 10724 | GNU @code{make} provides many advanced capabilities, including many
|
|---|
| 10725 | useful functions. However, it does not contain a complete programming
|
|---|
| 10726 | language and so it has limitations. Sometimes these limitations can be
|
|---|
| 10727 | overcome through use of the @code{shell} function to invoke a separate
|
|---|
| 10728 | program, although this can be inefficient.
|
|---|
| 10729 |
|
|---|
| 10730 | In cases where the built-in capabilities of GNU @code{make} are
|
|---|
| 10731 | insufficient to your requirements there are two options for extending
|
|---|
| 10732 | @code{make}. On systems where it's provided, you can utilize GNU
|
|---|
| 10733 | Guile as an embedded scripting language (@pxref{Guile Integration,,GNU
|
|---|
| 10734 | Guile Integration}). On systems which support dynamically loadable
|
|---|
| 10735 | objects, you can write your own extension in any language (which can
|
|---|
| 10736 | be compiled into such an object) and load it to provide extended
|
|---|
| 10737 | capabilities (@pxref{load Directive, ,The @code{load} Directive}).
|
|---|
| 10738 |
|
|---|
| 10739 | @menu
|
|---|
| 10740 | * Guile Integration:: Using Guile as an embedded scripting language.
|
|---|
| 10741 | * Loading Objects:: Loading dynamic objects as extensions.
|
|---|
| 10742 | @end menu
|
|---|
| 10743 |
|
|---|
| 10744 | @node Guile Integration, Loading Objects, Extending make, Extending make
|
|---|
| 10745 | @section GNU Guile Integration
|
|---|
| 10746 | @cindex Guile
|
|---|
| 10747 | @cindex extensions, Guile
|
|---|
| 10748 |
|
|---|
| 10749 | GNU @code{make} may be built with support for GNU Guile as an embedded
|
|---|
| 10750 | extension language. Guile implements the Scheme language. A review
|
|---|
| 10751 | of GNU Guile and the Scheme language and its features is beyond the
|
|---|
| 10752 | scope of this manual: see the documentation for GNU Guile and Scheme.
|
|---|
| 10753 |
|
|---|
| 10754 | You can determine if @code{make} contains support for Guile by
|
|---|
| 10755 | examining the @code{.FEATURES} variable; it will contain the word
|
|---|
| 10756 | @var{guile} if Guile support is available.
|
|---|
| 10757 |
|
|---|
| 10758 | The Guile integration provides one new @code{make} function: @code{guile}.
|
|---|
| 10759 | The @code{guile} function takes one argument which is first expanded
|
|---|
| 10760 | by @code{make} in the normal fashion, then passed to the GNU Guile
|
|---|
| 10761 | evaluator. The result of the evaluator is converted into a string and
|
|---|
| 10762 | used as the expansion of the @code{guile} function in the makefile.
|
|---|
| 10763 |
|
|---|
| 10764 | In addition, GNU @code{make} exposes Guile procedures for use in Guile
|
|---|
| 10765 | scripts.
|
|---|
| 10766 |
|
|---|
| 10767 | @menu
|
|---|
| 10768 | * Guile Types:: Converting Guile types to @code{make} strings.
|
|---|
| 10769 | * Guile Interface:: Invoking @code{make} functions from Guile.
|
|---|
| 10770 | * Guile Example:: Example using Guile in @code{make}.
|
|---|
| 10771 | @end menu
|
|---|
| 10772 |
|
|---|
| 10773 | @node Guile Types, Guile Interface, Guile Integration, Guile Integration
|
|---|
| 10774 | @subsection Conversion of Guile Types
|
|---|
| 10775 | @cindex convert guile types
|
|---|
| 10776 | @cindex guile, conversion of types
|
|---|
| 10777 | @cindex types, conversion of
|
|---|
| 10778 |
|
|---|
| 10779 | There is only one ``data type'' in @code{make}: a string. GNU Guile,
|
|---|
| 10780 | on the other hand, provides a rich variety of different data types.
|
|---|
| 10781 | An important aspect of the interface between @code{make} and GNU Guile
|
|---|
| 10782 | is the conversion of Guile data types into @code{make} strings.
|
|---|
| 10783 |
|
|---|
| 10784 | This conversion is relevant in two places: when a makefile invokes the
|
|---|
| 10785 | @code{guile} function to evaluate a Guile expression, the result of
|
|---|
| 10786 | that evaluation must be converted into a make string so it can be
|
|---|
| 10787 | further evaluated by @code{make}. And secondly, when a Guile script
|
|---|
| 10788 | invokes one of the procedures exported by @code{make} the argument
|
|---|
| 10789 | provided to the procedure must be converted into a string.
|
|---|
| 10790 |
|
|---|
| 10791 | The conversion of Guile types into @code{make} strings is as below:
|
|---|
| 10792 |
|
|---|
| 10793 | @table @code
|
|---|
| 10794 | @item #f
|
|---|
| 10795 | False is converted into the empty string: in @code{make} conditionals
|
|---|
| 10796 | the empty string is considered false.
|
|---|
| 10797 |
|
|---|
| 10798 | @item #t
|
|---|
| 10799 | True is converted to the string @samp{#t}: in @code{make} conditionals
|
|---|
| 10800 | any non-empty string is considered true.
|
|---|
| 10801 |
|
|---|
| 10802 | @item symbol
|
|---|
| 10803 | @item number
|
|---|
| 10804 | A symbol or number is converted into the string representation of that
|
|---|
| 10805 | symbol or number.
|
|---|
| 10806 |
|
|---|
| 10807 | @item character
|
|---|
| 10808 | A printable character is converted to the same character.
|
|---|
| 10809 |
|
|---|
| 10810 | @item string
|
|---|
| 10811 | A string containing only printable characters is converted to the same
|
|---|
| 10812 | string.
|
|---|
| 10813 |
|
|---|
| 10814 | @item list
|
|---|
| 10815 | A list is converted recursively according to the above rules. This
|
|---|
| 10816 | implies that any structured list will be flattened (that is, a result
|
|---|
| 10817 | of @samp{'(a b (c d) e)} will be converted to the @code{make} string
|
|---|
| 10818 | @samp{a b c d e}).
|
|---|
| 10819 |
|
|---|
| 10820 | @item other
|
|---|
| 10821 | Any other Guile type results in an error. In future versions of
|
|---|
| 10822 | @code{make}, other Guile types may be converted.
|
|---|
| 10823 |
|
|---|
| 10824 | @end table
|
|---|
| 10825 |
|
|---|
| 10826 | The translation of @samp{#f} (to the empty string) and @samp{#t} (to
|
|---|
| 10827 | the non-empty string @samp{#t}) is designed to allow you to use Guile
|
|---|
| 10828 | boolean results directly as @code{make} boolean conditions. For
|
|---|
| 10829 | example:
|
|---|
| 10830 |
|
|---|
| 10831 | @example
|
|---|
| 10832 | $(if $(guile (access? "myfile" R_OK)),$(info myfile exists))
|
|---|
| 10833 | @end example
|
|---|
| 10834 |
|
|---|
| 10835 | As a consequence of these conversion rules you must consider the
|
|---|
| 10836 | result of your Guile script, as that result will be converted into a
|
|---|
| 10837 | string and parsed by @code{make}. If there is no natural result for
|
|---|
| 10838 | the script (that is, the script exists solely for its side-effects),
|
|---|
| 10839 | you should add @samp{#f} as the final expression in order to avoid
|
|---|
| 10840 | syntax errors in your makefile.
|
|---|
| 10841 |
|
|---|
| 10842 | @node Guile Interface, Guile Example, Guile Types, Guile Integration
|
|---|
| 10843 | @subsection Interfaces from Guile to @code{make}
|
|---|
| 10844 | @cindex make interface to guile
|
|---|
| 10845 | @cindex make procedures in guile
|
|---|
| 10846 |
|
|---|
| 10847 | In addition to the @code{guile} function available in makefiles,
|
|---|
| 10848 | @code{make} exposes some procedures for use in your Guile scripts. At
|
|---|
| 10849 | startup @code{make} creates a new Guile module, @code{gnu make}, and
|
|---|
| 10850 | exports these procedures as public interfaces from that module:
|
|---|
| 10851 |
|
|---|
| 10852 | @table @code
|
|---|
| 10853 | @item gmk-expand
|
|---|
| 10854 | @findex gmk-expand
|
|---|
| 10855 | This procedure takes a single argument which is converted into a
|
|---|
| 10856 | string. The string is expanded by @code{make} using normal
|
|---|
| 10857 | @code{make} expansion rules. The result of the expansion is converted
|
|---|
| 10858 | into a Guile string and provided as the result of the procedure.
|
|---|
| 10859 |
|
|---|
| 10860 | @item gmk-eval
|
|---|
| 10861 | @findex gmk-eval
|
|---|
| 10862 | This procedure takes a single argument which is converted into a
|
|---|
| 10863 | string. The string is evaluated by @code{make} as if it were a
|
|---|
| 10864 | makefile. This is the same capability available via the @code{eval}
|
|---|
| 10865 | function (@pxref{Eval Function}). The result of the @code{gmk-eval}
|
|---|
| 10866 | procedure is always the empty string.
|
|---|
| 10867 |
|
|---|
| 10868 | Note that @code{gmk-eval} is not quite the same as using
|
|---|
| 10869 | @code{gmk-expand} with the @code{eval} function: in the latter case
|
|---|
| 10870 | the evaluated string will be expanded @emph{twice}; first by
|
|---|
| 10871 | @code{gmk-expand}, then again by the @code{eval} function.
|
|---|
| 10872 |
|
|---|
| 10873 | @end table
|
|---|
| 10874 |
|
|---|
| 10875 | @node Guile Example, , Guile Interface, Guile Integration
|
|---|
| 10876 | @subsection Example Using Guile in @code{make}
|
|---|
| 10877 | @cindex Guile example
|
|---|
| 10878 | @cindex example using Guile
|
|---|
| 10879 |
|
|---|
| 10880 | Here is a very simple example using GNU Guile to manage writing to a
|
|---|
| 10881 | file. These Guile procedures simply open a file, allow writing to the
|
|---|
| 10882 | file (one string per line), and close the file. Note that because we
|
|---|
| 10883 | cannot store complex values such as Guile ports in @code{make}
|
|---|
| 10884 | variables, we'll keep the port as a global variable in the Guile
|
|---|
| 10885 | interpreter.
|
|---|
| 10886 |
|
|---|
| 10887 | You can create Guile functions easily using @code{define}/@code{endef}
|
|---|
| 10888 | to create a Guile script, then use the @code{guile} function to
|
|---|
| 10889 | internalize it:
|
|---|
| 10890 |
|
|---|
| 10891 | @example
|
|---|
| 10892 | @group
|
|---|
| 10893 | define GUILEIO
|
|---|
| 10894 | ;; A simple Guile IO library for GNU make
|
|---|
| 10895 |
|
|---|
| 10896 | (define MKPORT #f)
|
|---|
| 10897 |
|
|---|
| 10898 | (define (mkopen name mode)
|
|---|
| 10899 | (set! MKPORT (open-file name mode))
|
|---|
| 10900 | #f)
|
|---|
| 10901 |
|
|---|
| 10902 | (define (mkwrite s)
|
|---|
| 10903 | (display s MKPORT)
|
|---|
| 10904 | (newline MKPORT)
|
|---|
| 10905 | #f)
|
|---|
| 10906 |
|
|---|
| 10907 | (define (mkclose)
|
|---|
| 10908 | (close-port MKPORT)
|
|---|
| 10909 | #f)
|
|---|
| 10910 |
|
|---|
| 10911 | #f
|
|---|
| 10912 | endef
|
|---|
| 10913 |
|
|---|
| 10914 | # Internalize the Guile IO functions
|
|---|
| 10915 | $(guile $(GUILEIO))
|
|---|
| 10916 | @end group
|
|---|
| 10917 | @end example
|
|---|
| 10918 |
|
|---|
| 10919 | If you have a significant amount of Guile support code, you might
|
|---|
| 10920 | consider keeping it in a different file (e.g., @file{guileio.scm}) and
|
|---|
| 10921 | then loading it in your makefile using the @code{guile} function:
|
|---|
| 10922 |
|
|---|
| 10923 | @example
|
|---|
| 10924 | $(guile (load "guileio.scm"))
|
|---|
| 10925 | @end example
|
|---|
| 10926 |
|
|---|
| 10927 | An advantage to this method is that when editing @file{guileio.scm},
|
|---|
| 10928 | your editor will understand that this file contains Scheme syntax
|
|---|
| 10929 | rather than makefile syntax.
|
|---|
| 10930 |
|
|---|
| 10931 | Now you can use these Guile functions to create files. Suppose you
|
|---|
| 10932 | need to operate on a very large list, which cannot fit on the command
|
|---|
| 10933 | line, but the utility you're using accepts the list as input as well:
|
|---|
| 10934 |
|
|---|
| 10935 | @example
|
|---|
| 10936 | @group
|
|---|
| 10937 | prog: $(PREREQS)
|
|---|
| 10938 | @@$(guile (mkopen "tmp.out" "w")) \
|
|---|
| 10939 | $(foreach X,$^,$(guile (mkwrite "$(X)"))) \
|
|---|
| 10940 | $(guile (mkclose))
|
|---|
| 10941 | $(LINK) < tmp.out
|
|---|
| 10942 | @end group
|
|---|
| 10943 | @end example
|
|---|
| 10944 |
|
|---|
| 10945 | A more comprehensive suite of file manipulation procedures is possible
|
|---|
| 10946 | of course. You could, for example, maintain multiple output files at
|
|---|
| 10947 | the same time by choosing a symbol for each one and using it as the
|
|---|
| 10948 | key to a hash table, where the value is a port, then returning the
|
|---|
| 10949 | symbol to be stored in a @code{make} variable.
|
|---|
| 10950 |
|
|---|
| 10951 | @node Loading Objects, , Guile Integration, Extending make
|
|---|
| 10952 | @section Loading Dynamic Objects
|
|---|
| 10953 | @cindex loaded objects
|
|---|
| 10954 | @cindex objects, loaded
|
|---|
| 10955 | @cindex extensions, loading
|
|---|
| 10956 |
|
|---|
| 10957 | @cartouche
|
|---|
| 10958 | @quotation Warning
|
|---|
| 10959 | The @code{load} directive and extension capability is considered a
|
|---|
| 10960 | ``technology preview'' in this release of GNU make. We encourage you
|
|---|
| 10961 | to experiment with this feature and we appreciate any feedback on it.
|
|---|
| 10962 | However we cannot guarantee to maintain backward-compatibility in the
|
|---|
| 10963 | next release. Consider using GNU Guile instead for extending GNU make
|
|---|
| 10964 | (@pxref{Guile Function, ,The @code{guile} Function}).
|
|---|
| 10965 | @end quotation
|
|---|
| 10966 | @end cartouche
|
|---|
| 10967 |
|
|---|
| 10968 | Many operating systems provide a facility for dynamically loading
|
|---|
| 10969 | compiled objects. If your system provides this facility, GNU
|
|---|
| 10970 | @code{make} can make use of it to load dynamic objects at runtime,
|
|---|
| 10971 | providing new capabilities which may then be invoked by your makefile.
|
|---|
| 10972 |
|
|---|
| 10973 | The @code{load} directive is used to load a dynamic object. Once the
|
|---|
| 10974 | object is loaded, a ``setup'' function will be invoked to allow the
|
|---|
| 10975 | object to initialize itself and register new facilities with GNU
|
|---|
| 10976 | @code{make}. A dynamic object might include new @code{make} functions,
|
|---|
| 10977 | for example, and the ``setup'' function would register them with GNU
|
|---|
| 10978 | @code{make}'s function handling system.
|
|---|
| 10979 |
|
|---|
| 10980 | @menu
|
|---|
| 10981 | * load Directive:: Loading dynamic objects as extensions.
|
|---|
| 10982 | * Remaking Loaded Objects:: How loaded objects get remade.
|
|---|
| 10983 | * Loaded Object API:: Programmatic interface for loaded objects.
|
|---|
| 10984 | * Loaded Object Example:: Example of a loaded object
|
|---|
| 10985 | @end menu
|
|---|
| 10986 |
|
|---|
| 10987 | @node load Directive, Remaking Loaded Objects, Loading Objects, Loading Objects
|
|---|
| 10988 | @subsection The @code{load} Directive
|
|---|
| 10989 | @cindex load directive
|
|---|
| 10990 | @cindex extensions, load directive
|
|---|
| 10991 |
|
|---|
| 10992 | Objects are loaded into GNU @code{make} by placing the @code{load}
|
|---|
| 10993 | directive into your makefile. The syntax of the @code{load} directive
|
|---|
| 10994 | is as follows:
|
|---|
| 10995 |
|
|---|
| 10996 | @findex load
|
|---|
| 10997 | @example
|
|---|
| 10998 | load @var{object-file} @dots{}
|
|---|
| 10999 | @end example
|
|---|
| 11000 |
|
|---|
| 11001 | or:
|
|---|
| 11002 |
|
|---|
| 11003 | @example
|
|---|
| 11004 | load @var{object-file}(@var{symbol-name}) @dots{}
|
|---|
| 11005 | @end example
|
|---|
| 11006 |
|
|---|
| 11007 | The file @var{object-file} is dynamically loaded by GNU @code{make}.
|
|---|
| 11008 | If @var{object-file} does not include a directory path then it is
|
|---|
| 11009 | first looked for in the current directory. If it is not found there,
|
|---|
| 11010 | or a directory path is included, then system-specific paths will be
|
|---|
| 11011 | searched. If the load fails for any reason, @code{make} will print a
|
|---|
| 11012 | message and exit.
|
|---|
| 11013 |
|
|---|
| 11014 | If the load succeeds @code{make} will invoke an initializing function.
|
|---|
| 11015 |
|
|---|
| 11016 | If @var{symbol-name} is provided, it will be used as the name of the
|
|---|
| 11017 | initializing function.
|
|---|
| 11018 |
|
|---|
| 11019 | If no @var{symbol-name} is provided, the initializing function name is
|
|---|
| 11020 | created by taking the base file name of @var{object-file}, up to the
|
|---|
| 11021 | first character which is not a valid symbol name character
|
|---|
| 11022 | (alphanumerics and underscores are valid symbol name characters). To
|
|---|
| 11023 | this prefix will be appended the suffix @code{_gmk_setup}.
|
|---|
| 11024 |
|
|---|
| 11025 | More than one object file may be loaded with a single @code{load}
|
|---|
| 11026 | directive, and both forms of @code{load} arguments may be used in the
|
|---|
| 11027 | same directive.
|
|---|
| 11028 |
|
|---|
| 11029 | The initializing function will be provided the file name and line
|
|---|
| 11030 | number of the invocation of the @code{load} operation. It should
|
|---|
| 11031 | return a value of type @code{int}, which must be @code{0} on failure
|
|---|
| 11032 | and non-@code{0} on success. If the return value is @code{-1}, then
|
|---|
| 11033 | GNU make will @emph{not} attempt to rebuild the object file
|
|---|
| 11034 | (@pxref{Remaking Loaded Objects, ,How Loaded Objects Are Remade}).
|
|---|
| 11035 |
|
|---|
| 11036 | For example:
|
|---|
| 11037 |
|
|---|
| 11038 | @example
|
|---|
| 11039 | load ../mk_funcs.so
|
|---|
| 11040 | @end example
|
|---|
| 11041 |
|
|---|
| 11042 | will load the dynamic object @file{../mk_funcs.so}. After the object
|
|---|
| 11043 | is loaded, @code{make} will invoke the function (assumed to be defined
|
|---|
| 11044 | by the shared object) @code{mk_funcs_gmk_setup}.
|
|---|
| 11045 |
|
|---|
| 11046 | On the other hand:
|
|---|
| 11047 |
|
|---|
| 11048 | @example
|
|---|
| 11049 | load ../mk_funcs.so(init_mk_func)
|
|---|
| 11050 | @end example
|
|---|
| 11051 |
|
|---|
| 11052 | will load the dynamic object @file{../mk_funcs.so}. After the object
|
|---|
| 11053 | is loaded, @code{make} will invoke the function @code{init_mk_func}.
|
|---|
| 11054 |
|
|---|
| 11055 | Regardless of how many times an object file appears in a @code{load}
|
|---|
| 11056 | directive, it will only be loaded (and its setup function will only
|
|---|
| 11057 | be invoked) once.
|
|---|
| 11058 |
|
|---|
| 11059 | @vindex .LOADED
|
|---|
| 11060 | After an object has been successfully loaded, its file name is
|
|---|
| 11061 | appended to the @code{.LOADED} variable.
|
|---|
| 11062 |
|
|---|
| 11063 | @findex -load
|
|---|
| 11064 | If you would prefer that failure to load a dynamic object not be
|
|---|
| 11065 | reported as an error, you can use the @code{-load} directive instead
|
|---|
| 11066 | of @code{load}. GNU @code{make} will not fail and no message will be
|
|---|
| 11067 | generated if an object fails to load. The failed object is not added
|
|---|
| 11068 | to the @code{.LOADED} variable, which can then be consulted to
|
|---|
| 11069 | determine if the load was successful.
|
|---|
| 11070 |
|
|---|
| 11071 | @node Remaking Loaded Objects, Loaded Object API, load Directive, Loading Objects
|
|---|
| 11072 | @subsection How Loaded Objects Are Remade
|
|---|
| 11073 | @cindex updating loaded objects
|
|---|
| 11074 | @cindex remaking loaded objects
|
|---|
| 11075 | @cindex loaded objects, remaking of
|
|---|
| 11076 |
|
|---|
| 11077 | Loaded objects undergo the same re-make procedure as makefiles
|
|---|
| 11078 | (@pxref{Remaking Makefiles, ,How Makefiles Are Remade}). If any
|
|---|
| 11079 | loaded object is recreated, then @code{make} will start from scratch
|
|---|
| 11080 | and re-read all the makefiles, and reload the object files again. It
|
|---|
| 11081 | is not necessary for the loaded object to do anything special to
|
|---|
| 11082 | support this.@refill
|
|---|
| 11083 |
|
|---|
| 11084 | It's up to the makefile author to provide the rules needed for
|
|---|
| 11085 | rebuilding the loaded object.
|
|---|
| 11086 |
|
|---|
| 11087 | @node Loaded Object API, Loaded Object Example, Remaking Loaded Objects, Loading Objects
|
|---|
| 11088 | @subsection Loaded Object Interface
|
|---|
| 11089 | @cindex loaded object API
|
|---|
| 11090 | @cindex interface for loaded objects
|
|---|
| 11091 |
|
|---|
| 11092 | @cartouche
|
|---|
| 11093 | @quotation Warning
|
|---|
| 11094 | For this feature to be useful your extensions will need to invoke
|
|---|
| 11095 | various functions internal to GNU @code{make}. The programming
|
|---|
| 11096 | interfaces provided in this release should not be considered stable:
|
|---|
| 11097 | functions may be added, removed, or change calling signatures or
|
|---|
| 11098 | implementations in future versions of GNU @code{make}.
|
|---|
| 11099 | @end quotation
|
|---|
| 11100 | @end cartouche
|
|---|
| 11101 |
|
|---|
| 11102 | To be useful, loaded objects must be able to interact with GNU
|
|---|
| 11103 | @code{make}. This interaction includes both interfaces the loaded
|
|---|
| 11104 | object provides to makefiles and also interfaces @code{make} provides
|
|---|
| 11105 | to the loaded object to manipulate @code{make}'s operation.
|
|---|
| 11106 |
|
|---|
| 11107 | The interface between loaded objects and @code{make} is defined by the
|
|---|
| 11108 | @file{gnumake.h} C header file. All loaded objects written in C
|
|---|
| 11109 | should include this header file. Any loaded object not written in C
|
|---|
| 11110 | will need to implement the interface defined in this header file.
|
|---|
| 11111 |
|
|---|
| 11112 | Typically, a loaded object will register one or more new GNU
|
|---|
| 11113 | @code{make} functions using the @code{gmk_add_function} routine from
|
|---|
| 11114 | within its setup function. The implementations of these @code{make}
|
|---|
| 11115 | functions may make use of the @code{gmk_expand} and @code{gmk_eval}
|
|---|
| 11116 | routines to perform their tasks, then optionally return a string as
|
|---|
| 11117 | the result of the function expansion.
|
|---|
| 11118 |
|
|---|
| 11119 | @subsubheading Loaded Object Licensing
|
|---|
| 11120 | @cindex loaded object licensing
|
|---|
| 11121 | @cindex plugin_is_GPL_compatible
|
|---|
| 11122 |
|
|---|
| 11123 | Every dynamic extension should define the global symbol
|
|---|
| 11124 | @code{plugin_is_GPL_compatible} to assert that it has been licensed
|
|---|
| 11125 | under a GPL-compatible license. If this symbol does not exist,
|
|---|
| 11126 | @code{make} emits a fatal error and exits when it tries to load your
|
|---|
| 11127 | extension.
|
|---|
| 11128 |
|
|---|
| 11129 | The declared type of the symbol should be @code{int}. It does not need
|
|---|
| 11130 | to be in any allocated section, though. The code merely asserts that
|
|---|
| 11131 | the symbol exists in the global scope. Something like this is enough:
|
|---|
| 11132 |
|
|---|
| 11133 | @example
|
|---|
| 11134 | int plugin_is_GPL_compatible;
|
|---|
| 11135 | @end example
|
|---|
| 11136 |
|
|---|
| 11137 | @subsubheading Data Structures
|
|---|
| 11138 |
|
|---|
| 11139 | @table @code
|
|---|
| 11140 | @item gmk_floc
|
|---|
| 11141 | This structure represents a filename/location pair. It is provided
|
|---|
| 11142 | when defining items, so GNU @code{make} can inform the user later
|
|---|
| 11143 | where the definition occurred if necessary.
|
|---|
| 11144 | @end table
|
|---|
| 11145 |
|
|---|
| 11146 | @subsubheading Registering Functions
|
|---|
| 11147 | @findex gmk_add_function
|
|---|
| 11148 |
|
|---|
| 11149 | There is currently one way for makefiles to invoke operations provided
|
|---|
| 11150 | by the loaded object: through the @code{make} function call
|
|---|
| 11151 | interface. A loaded object can register one or more new functions
|
|---|
| 11152 | which may then be invoked from within the makefile in the same way as
|
|---|
| 11153 | any other function.
|
|---|
| 11154 |
|
|---|
| 11155 | Use @code{gmk_add_function} to create a new @code{make} function. Its
|
|---|
| 11156 | arguments are as follows:
|
|---|
| 11157 |
|
|---|
| 11158 | @table @code
|
|---|
| 11159 | @item name
|
|---|
| 11160 | The function name. This is what the makefile should use to invoke the
|
|---|
| 11161 | function. The name must be between 1 and 255 characters long and it
|
|---|
| 11162 | may only contain alphanumeric, period (@samp{.}), dash (@samp{-}), and
|
|---|
| 11163 | underscore (@samp{_}) characters. It may not begin with a period.
|
|---|
| 11164 |
|
|---|
| 11165 | @item func_ptr
|
|---|
| 11166 | A pointer to a function that @code{make} will invoke when it expands
|
|---|
| 11167 | the function in a makefile. This function must be defined by the
|
|---|
| 11168 | loaded object.
|
|---|
| 11169 |
|
|---|
| 11170 | @item min_args
|
|---|
| 11171 | The minimum number of arguments the function will accept. Must be
|
|---|
| 11172 | between 0 and 255. GNU @code{make} will check this and fail before
|
|---|
| 11173 | invoking @code{func_ptr} if the function was invoked with too few
|
|---|
| 11174 | arguments.
|
|---|
| 11175 |
|
|---|
| 11176 | @item max_args
|
|---|
| 11177 | The maximum number of arguments the function will accept. Must be
|
|---|
| 11178 | between 0 and 255. GNU @code{make} will check this and fail before
|
|---|
| 11179 | invoking @code{func_ptr} if the function was invoked with too few
|
|---|
| 11180 | arguments. If the value is 0, then any number of arguments is
|
|---|
| 11181 | accepted. If the value is greater than 0, then it must be greater
|
|---|
| 11182 | than or equal to @code{min_args}.
|
|---|
| 11183 |
|
|---|
| 11184 | @item flags
|
|---|
| 11185 | Flags that specify how this function will operate; the desired flags
|
|---|
| 11186 | should be OR'd together. If the @code{GMK_FUNC_NOEXPAND} flag is
|
|---|
| 11187 | given then the function arguments will not be expanded before the
|
|---|
| 11188 | function is called; otherwise they will be expanded first.
|
|---|
| 11189 | @end table
|
|---|
| 11190 |
|
|---|
| 11191 | @subsubheading Registered Function Interface
|
|---|
| 11192 | @findex gmk_func_ptr
|
|---|
| 11193 |
|
|---|
| 11194 | A function registered with @code{make} must match the
|
|---|
| 11195 | @code{gmk_func_ptr} type. It will be invoked with three parameters:
|
|---|
| 11196 | @code{name} (the name of the function), @code{argc} (the number of
|
|---|
| 11197 | arguments to the function), and @code{argv} (an array of pointers to
|
|---|
| 11198 | arguments to the function). The last pointer (that is,
|
|---|
| 11199 | @code{argv[argc]}) will be null (@code{0}).
|
|---|
| 11200 |
|
|---|
| 11201 | The return value of the function is the result of expanding the
|
|---|
| 11202 | function. If the function expands to nothing the return value may be
|
|---|
| 11203 | null. Otherwise, it must be a pointer to a string created with
|
|---|
| 11204 | @code{gmk_alloc}. Once the function returns, @code{make} owns this
|
|---|
| 11205 | string and will free it when appropriate; it cannot be accessed by the
|
|---|
| 11206 | loaded object.
|
|---|
| 11207 |
|
|---|
| 11208 | @subsubheading GNU @code{make} Facilities
|
|---|
| 11209 |
|
|---|
| 11210 | There are some facilities exported by GNU @code{make} for use by
|
|---|
| 11211 | loaded objects. Typically these would be run from within the
|
|---|
| 11212 | setup function and/or the functions registered via
|
|---|
| 11213 | @code{gmk_add_function}, to retrieve or modify the data @code{make}
|
|---|
| 11214 | works with.
|
|---|
| 11215 |
|
|---|
| 11216 | @table @code
|
|---|
| 11217 | @item gmk_expand
|
|---|
| 11218 | @findex gmk_expand
|
|---|
| 11219 | This function takes a string and expands it using @code{make}
|
|---|
| 11220 | expansion rules. The result of the expansion is returned in a
|
|---|
| 11221 | nil-terminated string buffer. The caller is responsible for calling
|
|---|
| 11222 | @code{gmk_free} with a pointer to the returned buffer when done.
|
|---|
| 11223 |
|
|---|
| 11224 | @item gmk_eval
|
|---|
| 11225 | @findex gmk_eval
|
|---|
| 11226 | This function takes a buffer and evaluates it as a segment of makefile
|
|---|
| 11227 | syntax. This function can be used to define new variables, new rules,
|
|---|
| 11228 | etc. It is equivalent to using the @code{eval} @code{make} function.
|
|---|
| 11229 | @end table
|
|---|
| 11230 |
|
|---|
| 11231 | Note that there is a difference between @code{gmk_eval} and calling
|
|---|
| 11232 | @code{gmk_expand} with a string using the @code{eval} function: in
|
|---|
| 11233 | the latter case the string will be expanded @emph{twice}; once by
|
|---|
| 11234 | @code{gmk_expand} and then again by the @code{eval} function. Using
|
|---|
| 11235 | @code{gmk_eval} the buffer is only expanded once, at most (as it's
|
|---|
| 11236 | read by the @code{make} parser).
|
|---|
| 11237 |
|
|---|
| 11238 | @subsubheading Memory Management
|
|---|
| 11239 |
|
|---|
| 11240 | Some systems allow for different memory management schemes. Thus you
|
|---|
| 11241 | should never pass memory that you've allocated directly to any
|
|---|
| 11242 | @code{make} function, nor should you attempt to directly free any
|
|---|
| 11243 | memory returned to you by any @code{make} function. Instead, use the
|
|---|
| 11244 | @code{gmk_alloc} and @code{gmk_free} functions.
|
|---|
| 11245 |
|
|---|
| 11246 | In particular, the string returned to @code{make} by a function
|
|---|
| 11247 | registered using @code{gmk_add_function} @emph{must} be allocated
|
|---|
| 11248 | using @code{gmk_alloc}, and the string returned from the @code{make}
|
|---|
| 11249 | @code{gmk_expand} function @emph{must} be freed (when no longer
|
|---|
| 11250 | needed) using @code{gmk_free}.
|
|---|
| 11251 |
|
|---|
| 11252 | @table @code
|
|---|
| 11253 | @item gmk_alloc
|
|---|
| 11254 | @findex gmk_alloc
|
|---|
| 11255 | Return a pointer to a newly-allocated buffer. This function will
|
|---|
| 11256 | always return a valid pointer; if not enough memory is available
|
|---|
| 11257 | @code{make} will exit.
|
|---|
| 11258 |
|
|---|
| 11259 | @item gmk_free
|
|---|
| 11260 | @findex gmk_free
|
|---|
| 11261 | Free a buffer returned to you by @code{make}. Once the
|
|---|
| 11262 | @code{gmk_free} function returns the string will no longer be valid.
|
|---|
| 11263 | @end table
|
|---|
| 11264 |
|
|---|
| 11265 | @node Loaded Object Example, , Loaded Object API, Loading Objects
|
|---|
| 11266 | @subsection Example Loaded Object
|
|---|
| 11267 | @cindex loaded object example
|
|---|
| 11268 | @cindex example of loaded objects
|
|---|
| 11269 |
|
|---|
| 11270 | Let's suppose we wanted to write a new GNU @code{make} function that
|
|---|
| 11271 | would create a temporary file and return its name. We would like our
|
|---|
| 11272 | function to take a prefix as an argument. First we can write the
|
|---|
| 11273 | function in a file @file{mk_temp.c}:
|
|---|
| 11274 |
|
|---|
| 11275 | @example
|
|---|
| 11276 | @group
|
|---|
| 11277 | #include <stdlib.h>
|
|---|
| 11278 | #include <stdlib.h>
|
|---|
| 11279 | #include <stdio.h>
|
|---|
| 11280 | #include <string.h>
|
|---|
| 11281 | #include <unistd.h>
|
|---|
| 11282 | #include <errno.h>
|
|---|
| 11283 |
|
|---|
| 11284 | #include <gnumake.h>
|
|---|
| 11285 |
|
|---|
| 11286 | int plugin_is_GPL_compatible;
|
|---|
| 11287 |
|
|---|
| 11288 | char *
|
|---|
| 11289 | gen_tmpfile(const char *nm, int argc, char **argv)
|
|---|
| 11290 | @{
|
|---|
| 11291 | int fd;
|
|---|
| 11292 |
|
|---|
| 11293 | /* Compute the size of the filename and allocate space for it. */
|
|---|
| 11294 | int len = strlen (argv[0]) + 6 + 1;
|
|---|
| 11295 | char *buf = gmk_alloc (len);
|
|---|
| 11296 |
|
|---|
| 11297 | strcpy (buf, argv[0]);
|
|---|
| 11298 | strcat (buf, "XXXXXX");
|
|---|
| 11299 |
|
|---|
| 11300 | fd = mkstemp(buf);
|
|---|
| 11301 | if (fd >= 0)
|
|---|
| 11302 | @{
|
|---|
| 11303 | /* Don't leak the file descriptor. */
|
|---|
| 11304 | close (fd);
|
|---|
| 11305 | return buf;
|
|---|
| 11306 | @}
|
|---|
| 11307 |
|
|---|
| 11308 | /* Failure. */
|
|---|
| 11309 | fprintf (stderr, "mkstemp(%s) failed: %s\n", buf, strerror (errno));
|
|---|
| 11310 | gmk_free (buf);
|
|---|
| 11311 | return NULL;
|
|---|
| 11312 | @}
|
|---|
| 11313 |
|
|---|
| 11314 | int
|
|---|
| 11315 | mk_temp_gmk_setup ()
|
|---|
| 11316 | @{
|
|---|
| 11317 | /* Register the function with make name "mk-temp". */
|
|---|
| 11318 | gmk_add_function ("mk-temp", gen_tmpfile, 1, 1, 1);
|
|---|
| 11319 | return 1;
|
|---|
| 11320 | @}
|
|---|
| 11321 | @end group
|
|---|
| 11322 | @end example
|
|---|
| 11323 |
|
|---|
| 11324 | Next, we will write a makefile that can build this shared object, load
|
|---|
| 11325 | it, and use it:
|
|---|
| 11326 |
|
|---|
| 11327 | @example
|
|---|
| 11328 | @group
|
|---|
| 11329 | all:
|
|---|
| 11330 | @@echo Temporary file: $(mk-temp tmpfile.)
|
|---|
| 11331 |
|
|---|
| 11332 | load mk_temp.so
|
|---|
| 11333 |
|
|---|
| 11334 | mk_temp.so: mk_temp.c
|
|---|
| 11335 | $(CC) -shared -fPIC -o $@ $<
|
|---|
| 11336 | @end group
|
|---|
| 11337 | @end example
|
|---|
| 11338 |
|
|---|
| 11339 | On MS-Windows, due to peculiarities of how shared objects are
|
|---|
| 11340 | produced, the compiler needs to scan the @dfn{import library} produced
|
|---|
| 11341 | when building @code{make}, typically called
|
|---|
| 11342 | @file{libgnumake-@var{version}.dll.a}, where @var{version} is the
|
|---|
| 11343 | version of the load object API. So the recipe to produce a shared
|
|---|
| 11344 | object will look on Windows like this (assuming the API version is 1):
|
|---|
| 11345 |
|
|---|
| 11346 | @example
|
|---|
| 11347 | @group
|
|---|
| 11348 | mk_temp.dll: mk_temp.c
|
|---|
| 11349 | $(CC) -shared -o $@ $< -lgnumake-1
|
|---|
| 11350 | @end group
|
|---|
| 11351 | @end example
|
|---|
| 11352 |
|
|---|
| 11353 | Now when you run @code{make} you'll see something like:
|
|---|
| 11354 |
|
|---|
| 11355 | @example
|
|---|
| 11356 | $ make
|
|---|
| 11357 | cc -shared -fPIC -o mk_temp.so mk_temp.c
|
|---|
| 11358 | Temporary filename: tmpfile.A7JEwd
|
|---|
| 11359 | @end example
|
|---|
| 11360 |
|
|---|
| 11361 | @node Integrating make, Features, Extending make, Top
|
|---|
| 11362 | @chapter Integrating GNU @code{make}
|
|---|
| 11363 | @cindex make integration
|
|---|
| 11364 |
|
|---|
| 11365 | GNU @code{make} is often one component in a larger system of tools,
|
|---|
| 11366 | including integrated development environments, compiler toolchains,
|
|---|
| 11367 | and others. The role of @code{make} is to start commands and
|
|---|
| 11368 | determine whether they succeeded or not: no special integration is
|
|---|
| 11369 | needed to accomplish that. However, sometimes it is convenient to
|
|---|
| 11370 | bind @code{make} more tightly with other parts of the system, both
|
|---|
| 11371 | higher-level (tools that invoke @code{make}) and lower-level (tools
|
|---|
| 11372 | that @code{make} invokes).
|
|---|
| 11373 |
|
|---|
| 11374 | @menu
|
|---|
| 11375 | * Job Slots:: Share job slots with GNU @code{make}.
|
|---|
| 11376 | * Terminal Output:: Control output to terminals.
|
|---|
| 11377 | @end menu
|
|---|
| 11378 |
|
|---|
| 11379 | @node Job Slots, Terminal Output, Integrating make, Integrating make
|
|---|
| 11380 | @section Sharing Job Slots with GNU @code{make}
|
|---|
| 11381 | @cindex job slots, sharing
|
|---|
| 11382 | @cindex tools, sharing job slots
|
|---|
| 11383 |
|
|---|
| 11384 | GNU @code{make} has the ability to run multiple recipes in parallel
|
|---|
| 11385 | (@pxref{Parallel, ,Parallel Execution}) and to cap the total number of
|
|---|
| 11386 | parallel jobs even across recursive invocations of @code{make}
|
|---|
| 11387 | (@pxref{Options/Recursion, ,Communicating Options to a
|
|---|
| 11388 | Sub-@code{make}}). Tools that @code{make} invokes which are also able
|
|---|
| 11389 | to run multiple operations in parallel, either using multiple threads
|
|---|
| 11390 | or multiple processes, can be enhanced to participate in GNU
|
|---|
| 11391 | @code{make}'s job management facility to ensure that the total number
|
|---|
| 11392 | of active threads/processes running on the system does not exceed the
|
|---|
| 11393 | maximum number of slots provided to GNU @code{make}. @refill
|
|---|
| 11394 |
|
|---|
| 11395 | @cindex jobserver
|
|---|
| 11396 | GNU @code{make} uses a method called the ``jobserver'' to control the
|
|---|
| 11397 | number of active jobs across recursive invocations. The actual
|
|---|
| 11398 | implementation of the jobserver varies across different operating
|
|---|
| 11399 | systems, but some fundamental aspects are always true.
|
|---|
| 11400 |
|
|---|
| 11401 | First, only command lines that @code{make} understands to be recursive
|
|---|
| 11402 | invocations of @code{make} (@pxref{MAKE Variable, ,How the @code{MAKE}
|
|---|
| 11403 | Variable Works}) will have access to the jobserver. When writing
|
|---|
| 11404 | makefiles you must be sure to mark the command as recursive (most
|
|---|
| 11405 | commonly by prefixing the command line with the @code{+} indicator
|
|---|
| 11406 | (@pxref{Recursion, ,Recursive Use of @code{make}}).
|
|---|
| 11407 |
|
|---|
| 11408 | Second, @code{make} will provide information necessary for accessing
|
|---|
| 11409 | the jobserver through the environment to its children, in the
|
|---|
| 11410 | @code{MAKEFLAGS} environment variable. Tools which want to
|
|---|
| 11411 | participate in the jobserver protocol will need to parse this
|
|---|
| 11412 | environment variable, as described in subsequent sections.
|
|---|
| 11413 |
|
|---|
| 11414 | Third, every command @code{make} starts has one implicit job slot
|
|---|
| 11415 | reserved for it before it starts. Any tool which wants to participate
|
|---|
| 11416 | in the jobserver protocol should assume it can always run one job
|
|---|
| 11417 | without having to contact the jobserver at all.
|
|---|
| 11418 |
|
|---|
| 11419 | Finally, it's critical that tools that participate in the jobserver
|
|---|
| 11420 | protocol return the exact number of slots they obtained from the
|
|---|
| 11421 | jobserver back to the jobserver before they exit, even under error
|
|---|
| 11422 | conditions. Remember that the implicit job slot should @strong{not}
|
|---|
| 11423 | be returned to the jobserver! Returning too few slots means that
|
|---|
| 11424 | those slots will be lost for the rest of the build process; returning
|
|---|
| 11425 | too many slots means that extra slots will be available. The
|
|---|
| 11426 | top-level @code{make} command will print an error message at the end
|
|---|
| 11427 | of the build if it detects an incorrect number of slots available in
|
|---|
| 11428 | the jobserver.
|
|---|
| 11429 |
|
|---|
| 11430 | As an example, suppose you are implementing a linker which provides
|
|---|
| 11431 | for multithreaded operation. You would like to enhance the linker so
|
|---|
| 11432 | that if it is invoked by GNU @code{make} it can participate in the
|
|---|
| 11433 | jobserver protocol to control how many threads are used during link.
|
|---|
| 11434 | First you will need to modify the linker to determine if the
|
|---|
| 11435 | @code{MAKEFLAGS} environment variable is set. Next you will need to
|
|---|
| 11436 | parse the value of that variable to determine if the jobserver is
|
|---|
| 11437 | available, and how to access it. If it is available then you can
|
|---|
| 11438 | access it to obtain job slots controlling how much parallelism your
|
|---|
| 11439 | tool can use. Once done your tool must return those job slots back to
|
|---|
| 11440 | the jobserver.
|
|---|
| 11441 |
|
|---|
| 11442 | @menu
|
|---|
| 11443 | * POSIX Jobserver:: Using the jobserver on POSIX systems.
|
|---|
| 11444 | * Windows Jobserver:: Using the jobserver on Windows systems.
|
|---|
| 11445 | @end menu
|
|---|
| 11446 |
|
|---|
| 11447 | @node POSIX Jobserver, Windows Jobserver, Job Slots, Job Slots
|
|---|
| 11448 | @subsection POSIX Jobserver Interaction
|
|---|
| 11449 | @cindex jobserver on POSIX
|
|---|
| 11450 |
|
|---|
| 11451 | On POSIX systems the jobserver is implemented as a simple UNIX pipe.
|
|---|
| 11452 | The pipe will be pre-loaded with one single-character token for each
|
|---|
| 11453 | available job. To obtain an extra slot you must read a single
|
|---|
| 11454 | character from the jobserver pipe; to release a slot you must write a
|
|---|
| 11455 | single character back into the jobserver pipe.
|
|---|
| 11456 |
|
|---|
| 11457 | To access the pipe you must parse the @code{MAKEFLAGS} variable and
|
|---|
| 11458 | look for the argument string @code{--jobserver-auth=R,W} where
|
|---|
| 11459 | @samp{R} and @samp{W} are non-negative integers representing file
|
|---|
| 11460 | descriptors: @samp{R} is the read file descriptor and @samp{W} is the
|
|---|
| 11461 | write file descriptor.
|
|---|
| 11462 |
|
|---|
| 11463 | It's important that when you release the job slot, you write back the
|
|---|
| 11464 | same character you read from the pipe for that slot. Don't assume
|
|---|
| 11465 | that all tokens are the same character; different characters may have
|
|---|
| 11466 | different meanings to GNU @code{make}. The order is not important,
|
|---|
| 11467 | since @code{make} has no idea in what order jobs will complete anyway.
|
|---|
| 11468 |
|
|---|
| 11469 | There are various error conditions you must consider to ensure your
|
|---|
| 11470 | implementation is robust:
|
|---|
| 11471 |
|
|---|
| 11472 | @itemize @bullet
|
|---|
| 11473 | @item
|
|---|
| 11474 | Usually you will have a command-line argument controlling the parallel
|
|---|
| 11475 | operation of your tool. Consider whether your tool should detect
|
|---|
| 11476 | situations where both the jobserver and the command-line argument are
|
|---|
| 11477 | specified, and how it should react.
|
|---|
| 11478 |
|
|---|
| 11479 | @item
|
|---|
| 11480 | If your tool determines that the @code{--jobserver-auth} option is
|
|---|
| 11481 | available in @code{MAKEFLAGS} but that the file descriptors specified
|
|---|
| 11482 | are closed, this means that the calling @code{make} process did not
|
|---|
| 11483 | think that your tool was a recursive @code{make} invocation (e.g., the
|
|---|
| 11484 | command line was not prefixed with a @code{+} character). You should
|
|---|
| 11485 | notify your users of this situation.
|
|---|
| 11486 |
|
|---|
| 11487 | @item
|
|---|
| 11488 | Your tool should also examine the first word of the @code{MAKEFLAGS}
|
|---|
| 11489 | variable and look for the character @code{n}. If this character is
|
|---|
| 11490 | present then @code{make} was invoked with the @samp{-n} option and
|
|---|
| 11491 | your tool should stop without performing any operations.
|
|---|
| 11492 |
|
|---|
| 11493 | @item
|
|---|
| 11494 | Your tool should be sure to write back the tokens it read, even under
|
|---|
| 11495 | error conditions. This includes not only errors in your tool but also
|
|---|
| 11496 | outside influences such as interrupts (@code{SIGINT}), etc. You may
|
|---|
| 11497 | want to install signal handlers to manage this write-back.
|
|---|
| 11498 | @end itemize
|
|---|
| 11499 |
|
|---|
| 11500 | @node Windows Jobserver, , POSIX Jobserver, Job Slots
|
|---|
| 11501 | @subsection Windows Jobserver Interaction
|
|---|
| 11502 | @cindex jobserver on Windows
|
|---|
| 11503 |
|
|---|
| 11504 | On Windows systems the jobserver is implemented as a named semaphore.
|
|---|
| 11505 | The semaphore will be set with an initial count equal to the number of
|
|---|
| 11506 | available slots; to obtain a slot you must wait on the semaphore (with
|
|---|
| 11507 | or without a timeout). To release a slot, release the semaphore.
|
|---|
| 11508 |
|
|---|
| 11509 | To access the semaphore you must parse the @code{MAKEFLAGS} variable and
|
|---|
| 11510 | look for the argument string @code{--jobserver-auth=NAME} where
|
|---|
| 11511 | @samp{NAME} is the name of the named semaphore. Use this name with
|
|---|
| 11512 | @code{OpenSemaphore} to create a handle to the semaphore.
|
|---|
| 11513 |
|
|---|
| 11514 | There are various error conditions you must consider to ensure your
|
|---|
| 11515 | implementation is robust:
|
|---|
| 11516 |
|
|---|
| 11517 | @itemize @bullet
|
|---|
| 11518 | @item
|
|---|
| 11519 | Usually you will have a command-line argument controlling the parallel
|
|---|
| 11520 | operation of your tool. Consider whether your tool should detect
|
|---|
| 11521 | situations where both the jobserver and the command-line argument are
|
|---|
| 11522 | specified, and how it should react.
|
|---|
| 11523 |
|
|---|
| 11524 | @item
|
|---|
| 11525 | Your tool should be sure to release the semaphore for the tokens it
|
|---|
| 11526 | read, even under error conditions. This includes not only errors in
|
|---|
| 11527 | your tool but also outside influences such as interrupts
|
|---|
| 11528 | (@code{SIGINT}), etc. You may want to install signal handlers to
|
|---|
| 11529 | manage this write-back.
|
|---|
| 11530 | @end itemize
|
|---|
| 11531 |
|
|---|
| 11532 | @node Terminal Output, , Job Slots, Integrating make
|
|---|
| 11533 | @section Synchronized Terminal Output
|
|---|
| 11534 | @cindex parallel output to terminal
|
|---|
| 11535 | @cindex terminal, output to
|
|---|
| 11536 |
|
|---|
| 11537 | Normally GNU @code{make} will invoke all commands with access to the
|
|---|
| 11538 | same standard and error outputs that @code{make} itself was started
|
|---|
| 11539 | with. A number of tools will detect whether the output is a terminal
|
|---|
| 11540 | or not-a-terminal, and use this information to change the output
|
|---|
| 11541 | style. For example if the output goes to a terminal the tool may add
|
|---|
| 11542 | control characters that set color, or even change the location of the
|
|---|
| 11543 | cursor. If the output is not going to a terminal then these special
|
|---|
| 11544 | control characters are not emitted so that they don't corrupt log
|
|---|
| 11545 | files, etc.
|
|---|
| 11546 |
|
|---|
| 11547 | The @code{--output-sync} (@pxref{Parallel Output, ,Output During
|
|---|
| 11548 | Parallel Output}) option will defeat the terminal detection. When
|
|---|
| 11549 | output synchronization is enabled GNU @code{make} arranges for all
|
|---|
| 11550 | command output to be written to a file, so that its output can be
|
|---|
| 11551 | written as a block without interference from other commands. This
|
|---|
| 11552 | means that all tools invoked by @code{make} will believe that their
|
|---|
| 11553 | output is not going to be displayed on a terminal, even when it will
|
|---|
| 11554 | be (because @code{make} will display it there after the command is
|
|---|
| 11555 | completed).
|
|---|
| 11556 |
|
|---|
| 11557 | In order to facilitate tools which would like to determine whether or
|
|---|
| 11558 | not their output will be displayed on a terminal, GNU @code{make} will
|
|---|
| 11559 | set the @code{MAKE_TERMOUT} and @code{MAKE_TERMERR} environment
|
|---|
| 11560 | variables before invoking any commands. Tools which would like to
|
|---|
| 11561 | determine whether standard or error output (respectively) will be
|
|---|
| 11562 | displayed on a terminal can check these environment variables to
|
|---|
| 11563 | determine if they exist and contain a non-empty value. If so the tool
|
|---|
| 11564 | can assume that the output will (eventually) be displayed on a
|
|---|
| 11565 | terminal. If the variables are not set or have an empty value, then
|
|---|
| 11566 | the tool should fall back to its normal methods of detecting whether
|
|---|
| 11567 | output is going to a terminal or not.
|
|---|
| 11568 |
|
|---|
| 11569 | The content of the variables can be parsed to determine the type of
|
|---|
| 11570 | terminal which will be used to display the output.
|
|---|
| 11571 |
|
|---|
| 11572 | Similarly, environments which invoke @code{make} and would like to
|
|---|
| 11573 | capture the output and eventually display it on a terminal (or some
|
|---|
| 11574 | display which can interpret terminal control characters) can set these
|
|---|
| 11575 | variables before invoking @code{make}. GNU @code{make} will not
|
|---|
| 11576 | modify these environment variables if they already exist when it
|
|---|
| 11577 | starts.
|
|---|
| 11578 |
|
|---|
| 11579 | @node Features, Missing, Integrating make, Top
|
|---|
| 11580 | @chapter Features of GNU @code{make}
|
|---|
| 11581 | @cindex features of GNU @code{make}
|
|---|
| 11582 | @cindex portability
|
|---|
| 11583 | @cindex compatibility
|
|---|
| 11584 |
|
|---|
| 11585 | Here is a summary of the features of GNU @code{make}, for comparison
|
|---|
| 11586 | with and credit to other versions of @code{make}. We consider the
|
|---|
| 11587 | features of @code{make} in 4.2 BSD systems as a baseline. If you are
|
|---|
| 11588 | concerned with writing portable makefiles, you should not use the
|
|---|
| 11589 | features of @code{make} listed here, nor the ones in @ref{Missing}.
|
|---|
| 11590 |
|
|---|
| 11591 | Many features come from the version of @code{make} in System V.
|
|---|
| 11592 |
|
|---|
| 11593 | @itemize @bullet
|
|---|
| 11594 | @item
|
|---|
| 11595 | The @code{VPATH} variable and its special meaning.
|
|---|
| 11596 | @xref{Directory Search, , Searching Directories for Prerequisites}.
|
|---|
| 11597 | This feature exists in System V @code{make}, but is undocumented.
|
|---|
| 11598 | It is documented in 4.3 BSD @code{make} (which says it mimics System V's
|
|---|
| 11599 | @code{VPATH} feature).@refill
|
|---|
| 11600 |
|
|---|
| 11601 | @item
|
|---|
| 11602 | Included makefiles. @xref{Include, ,Including Other Makefiles}.
|
|---|
| 11603 | Allowing multiple files to be included with a single directive is a GNU
|
|---|
| 11604 | extension.
|
|---|
| 11605 |
|
|---|
| 11606 | @item
|
|---|
| 11607 | Variables are read from and communicated via the environment.
|
|---|
| 11608 | @xref{Environment, ,Variables from the Environment}.
|
|---|
| 11609 |
|
|---|
| 11610 | @item
|
|---|
| 11611 | Options passed through the variable @code{MAKEFLAGS} to recursive
|
|---|
| 11612 | invocations of @code{make}.
|
|---|
| 11613 | @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
|
|---|
| 11614 |
|
|---|
| 11615 | @item
|
|---|
| 11616 | The automatic variable @code{$%} is set to the member name
|
|---|
| 11617 | in an archive reference. @xref{Automatic Variables}.
|
|---|
| 11618 |
|
|---|
| 11619 | @item
|
|---|
| 11620 | The automatic variables @code{$@@}, @code{$*}, @code{$<}, @code{$%},
|
|---|
| 11621 | and @code{$?} have corresponding forms like @code{$(@@F)} and
|
|---|
| 11622 | @code{$(@@D)}. We have generalized this to @code{$^} as an obvious
|
|---|
| 11623 | extension. @xref{Automatic Variables}.@refill
|
|---|
| 11624 |
|
|---|
| 11625 | @item
|
|---|
| 11626 | Substitution variable references.
|
|---|
| 11627 | @xref{Reference, ,Basics of Variable References}.
|
|---|
| 11628 |
|
|---|
| 11629 | @item
|
|---|
| 11630 | The command line options @samp{-b} and @samp{-m}, accepted and
|
|---|
| 11631 | ignored. In System V @code{make}, these options actually do something.
|
|---|
| 11632 |
|
|---|
| 11633 | @item
|
|---|
| 11634 | Execution of recursive commands to run @code{make} via the variable
|
|---|
| 11635 | @code{MAKE} even if @samp{-n}, @samp{-q} or @samp{-t} is specified.
|
|---|
| 11636 | @xref{Recursion, ,Recursive Use of @code{make}}.
|
|---|
| 11637 |
|
|---|
| 11638 | @item
|
|---|
| 11639 | Support for suffix @samp{.a} in suffix rules. @xref{Archive Suffix
|
|---|
| 11640 | Rules}. This feature is obsolete in GNU @code{make}, because the
|
|---|
| 11641 | general feature of rule chaining (@pxref{Chained Rules, ,Chains of
|
|---|
| 11642 | Implicit Rules}) allows one pattern rule for installing members in an
|
|---|
| 11643 | archive (@pxref{Archive Update}) to be sufficient.
|
|---|
| 11644 |
|
|---|
| 11645 | @item
|
|---|
| 11646 | The arrangement of lines and backslash/newline combinations in
|
|---|
| 11647 | recipes is retained when the recipes are printed, so they appear as
|
|---|
| 11648 | they do in the makefile, except for the stripping of initial
|
|---|
| 11649 | whitespace.
|
|---|
| 11650 | @end itemize
|
|---|
| 11651 |
|
|---|
| 11652 | The following features were inspired by various other versions of
|
|---|
| 11653 | @code{make}. In some cases it is unclear exactly which versions inspired
|
|---|
| 11654 | which others.
|
|---|
| 11655 |
|
|---|
| 11656 | @itemize @bullet
|
|---|
| 11657 | @item
|
|---|
| 11658 | Pattern rules using @samp{%}.
|
|---|
| 11659 | This has been implemented in several versions of @code{make}.
|
|---|
| 11660 | We're not sure who invented it first, but it's been spread around a bit.
|
|---|
| 11661 | @xref{Pattern Rules, ,Defining and Redefining Pattern Rules}.@refill
|
|---|
| 11662 |
|
|---|
| 11663 | @item
|
|---|
| 11664 | Rule chaining and implicit intermediate files.
|
|---|
| 11665 | This was implemented by Stu Feldman in his version of @code{make}
|
|---|
| 11666 | for AT&T Eighth Edition Research Unix, and later by Andrew Hume of
|
|---|
| 11667 | AT&T Bell Labs in his @code{mk} program (where he terms it
|
|---|
| 11668 | ``transitive closure''). We do not really know if
|
|---|
| 11669 | we got this from either of them or thought it up ourselves at the
|
|---|
| 11670 | same time. @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 11671 |
|
|---|
| 11672 | @item
|
|---|
| 11673 | The automatic variable @code{$^} containing a list of all prerequisites
|
|---|
| 11674 | of the current target. We did not invent this, but we have no idea who
|
|---|
| 11675 | did. @xref{Automatic Variables}. The automatic variable
|
|---|
| 11676 | @code{$+} is a simple extension of @code{$^}.
|
|---|
| 11677 |
|
|---|
| 11678 | @item
|
|---|
| 11679 | The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know)
|
|---|
| 11680 | invented by Andrew Hume in @code{mk}.
|
|---|
| 11681 | @xref{Instead of Execution, ,Instead of Executing Recipes}.
|
|---|
| 11682 |
|
|---|
| 11683 | @item
|
|---|
| 11684 | The concept of doing several things at once (parallelism) exists in
|
|---|
| 11685 | many incarnations of @code{make} and similar programs, though not in the
|
|---|
| 11686 | System V or BSD implementations. @xref{Execution, ,Recipe Execution}.
|
|---|
| 11687 |
|
|---|
| 11688 | @item
|
|---|
| 11689 | A number of different build tools that support parallelism also
|
|---|
| 11690 | support collecting output and displaying as a single block.
|
|---|
| 11691 | @xref{Parallel Output, ,Output During Parallel Execution}.
|
|---|
| 11692 |
|
|---|
| 11693 | @item
|
|---|
| 11694 | Modified variable references using pattern substitution come from
|
|---|
| 11695 | SunOS 4. @xref{Reference, ,Basics of Variable References}.
|
|---|
| 11696 | This functionality was provided in GNU @code{make} by the
|
|---|
| 11697 | @code{patsubst} function before the alternate syntax was implemented
|
|---|
| 11698 | for compatibility with SunOS 4. It is not altogether clear who
|
|---|
| 11699 | inspired whom, since GNU @code{make} had @code{patsubst} before SunOS
|
|---|
| 11700 | 4 was released.@refill
|
|---|
| 11701 |
|
|---|
| 11702 | @item
|
|---|
| 11703 | The special significance of @samp{+} characters preceding recipe lines
|
|---|
| 11704 | (@pxref{Instead of Execution, ,Instead of Executing Recipes}) is
|
|---|
| 11705 | mandated by @cite{IEEE Standard 1003.2-1992} (POSIX.2).
|
|---|
| 11706 |
|
|---|
| 11707 | @item
|
|---|
| 11708 | The @samp{+=} syntax to append to the value of a variable comes from SunOS
|
|---|
| 11709 | 4 @code{make}. @xref{Appending, , Appending More Text to Variables}.
|
|---|
| 11710 |
|
|---|
| 11711 | @item
|
|---|
| 11712 | The syntax @w{@samp{@var{archive}(@var{mem1} @var{mem2}@dots{})}} to list
|
|---|
| 11713 | multiple members in a single archive file comes from SunOS 4 @code{make}.
|
|---|
| 11714 | @xref{Archive Members}.
|
|---|
| 11715 |
|
|---|
| 11716 | @item
|
|---|
| 11717 | The @code{-include} directive to include makefiles with no error for a
|
|---|
| 11718 | nonexistent file comes from SunOS 4 @code{make}. (But note that SunOS 4
|
|---|
| 11719 | @code{make} does not allow multiple makefiles to be specified in one
|
|---|
| 11720 | @code{-include} directive.) The same feature appears with the name
|
|---|
| 11721 | @code{sinclude} in SGI @code{make} and perhaps others.
|
|---|
| 11722 |
|
|---|
| 11723 | @item
|
|---|
| 11724 | The @code{!=} shell assignment operator exists in many BSD of
|
|---|
| 11725 | @code{make} and is purposefully implemented here to behave identically
|
|---|
| 11726 | to those implementations.
|
|---|
| 11727 |
|
|---|
| 11728 | @item
|
|---|
| 11729 | Various build management tools are implemented using scripting
|
|---|
| 11730 | languages such as Perl or Python and thus provide a natural embedded
|
|---|
| 11731 | scripting language, similar to GNU @code{make}'s integration of GNU
|
|---|
| 11732 | Guile.
|
|---|
| 11733 | @end itemize
|
|---|
| 11734 |
|
|---|
| 11735 | The remaining features are inventions new in GNU @code{make}:
|
|---|
| 11736 |
|
|---|
| 11737 | @itemize @bullet
|
|---|
| 11738 | @item
|
|---|
| 11739 | Use the @samp{-v} or @samp{--version} option to print version and
|
|---|
| 11740 | copyright information.
|
|---|
| 11741 |
|
|---|
| 11742 | @item
|
|---|
| 11743 | Use the @samp{-h} or @samp{--help} option to summarize the options to
|
|---|
| 11744 | @code{make}.
|
|---|
| 11745 |
|
|---|
| 11746 | @item
|
|---|
| 11747 | Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}.
|
|---|
| 11748 |
|
|---|
| 11749 | @item
|
|---|
| 11750 | Pass command line variable assignments automatically through the
|
|---|
| 11751 | variable @code{MAKE} to recursive @code{make} invocations.
|
|---|
| 11752 | @xref{Recursion, ,Recursive Use of @code{make}}.
|
|---|
| 11753 |
|
|---|
| 11754 | @item
|
|---|
| 11755 | Use the @samp{-C} or @samp{--directory} command option to change
|
|---|
| 11756 | directory. @xref{Options Summary, ,Summary of Options}.
|
|---|
| 11757 |
|
|---|
| 11758 | @item
|
|---|
| 11759 | Make verbatim variable definitions with @code{define}.
|
|---|
| 11760 | @xref{Multi-Line, ,Defining Multi-Line Variables}.
|
|---|
| 11761 |
|
|---|
| 11762 | @item
|
|---|
| 11763 | Declare phony targets with the special target @code{.PHONY}.
|
|---|
| 11764 |
|
|---|
| 11765 | Andrew Hume of AT&T Bell Labs implemented a similar feature with a
|
|---|
| 11766 | different syntax in his @code{mk} program. This seems to be a case of
|
|---|
| 11767 | parallel discovery. @xref{Phony Targets, ,Phony Targets}.
|
|---|
| 11768 |
|
|---|
| 11769 | @item
|
|---|
| 11770 | Manipulate text by calling functions.
|
|---|
| 11771 | @xref{Functions, ,Functions for Transforming Text}.
|
|---|
| 11772 |
|
|---|
| 11773 | @item
|
|---|
| 11774 | Use the @samp{-o} or @samp{--old-file}
|
|---|
| 11775 | option to pretend a file's modification-time is old.
|
|---|
| 11776 | @xref{Avoiding Compilation, ,Avoiding Recompilation of Some Files}.
|
|---|
| 11777 |
|
|---|
| 11778 | @item
|
|---|
| 11779 | Conditional execution.
|
|---|
| 11780 |
|
|---|
| 11781 | This feature has been implemented numerous times in various versions
|
|---|
| 11782 | of @code{make}; it seems a natural extension derived from the features
|
|---|
| 11783 | of the C preprocessor and similar macro languages and is not a
|
|---|
| 11784 | revolutionary concept. @xref{Conditionals, ,Conditional Parts of Makefiles}.
|
|---|
| 11785 |
|
|---|
| 11786 | @item
|
|---|
| 11787 | Specify a search path for included makefiles.
|
|---|
| 11788 | @xref{Include, ,Including Other Makefiles}.
|
|---|
| 11789 |
|
|---|
| 11790 | @item
|
|---|
| 11791 | Specify extra makefiles to read with an environment variable.
|
|---|
| 11792 | @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
|
|---|
| 11793 |
|
|---|
| 11794 | @item
|
|---|
| 11795 | Strip leading sequences of @samp{./} from file names, so that
|
|---|
| 11796 | @file{./@var{file}} and @file{@var{file}} are considered to be the
|
|---|
| 11797 | same file.@refill
|
|---|
| 11798 |
|
|---|
| 11799 | @item
|
|---|
| 11800 | Use a special search method for library prerequisites written in the
|
|---|
| 11801 | form @samp{-l@var{name}}.
|
|---|
| 11802 | @xref{Libraries/Search, ,Directory Search for Link Libraries}.
|
|---|
| 11803 |
|
|---|
| 11804 | @item
|
|---|
| 11805 | Allow suffixes for suffix rules
|
|---|
| 11806 | (@pxref{Suffix Rules, ,Old-Fashioned Suffix Rules}) to contain any
|
|---|
| 11807 | characters. In other versions of @code{make}, they must begin with
|
|---|
| 11808 | @samp{.} and not contain any @samp{/} characters.
|
|---|
| 11809 |
|
|---|
| 11810 | @item
|
|---|
| 11811 | Keep track of the current level of @code{make} recursion using the
|
|---|
| 11812 | variable @code{MAKELEVEL}. @xref{Recursion, ,Recursive Use of @code{make}}.
|
|---|
| 11813 |
|
|---|
| 11814 | @item
|
|---|
| 11815 | Provide any goals given on the command line in the variable
|
|---|
| 11816 | @code{MAKECMDGOALS}. @xref{Goals, ,Arguments to Specify the Goals}.
|
|---|
| 11817 |
|
|---|
| 11818 | @item
|
|---|
| 11819 | Specify static pattern rules. @xref{Static Pattern, ,Static Pattern Rules}.
|
|---|
| 11820 |
|
|---|
| 11821 | @item
|
|---|
| 11822 | Provide selective @code{vpath} search.
|
|---|
| 11823 | @xref{Directory Search, ,Searching Directories for Prerequisites}.
|
|---|
| 11824 |
|
|---|
| 11825 | @item
|
|---|
| 11826 | Provide computed variable references.
|
|---|
| 11827 | @xref{Reference, ,Basics of Variable References}.
|
|---|
| 11828 |
|
|---|
| 11829 | @item
|
|---|
| 11830 | Update makefiles. @xref{Remaking Makefiles, ,How Makefiles Are Remade}.
|
|---|
| 11831 | System V @code{make} has a very, very limited form of this
|
|---|
| 11832 | functionality in that it will check out SCCS files for makefiles.
|
|---|
| 11833 |
|
|---|
| 11834 | @item
|
|---|
| 11835 | Various new built-in implicit rules.
|
|---|
| 11836 | @xref{Catalogue of Rules, ,Catalogue of Built-In Rules}.
|
|---|
| 11837 |
|
|---|
| 11838 | @item
|
|---|
| 11839 | Load dynamic objects which can modify the behavior of @code{make}.
|
|---|
| 11840 | @xref{Loading Objects, ,Loading Dynamic Objects}.
|
|---|
| 11841 | @end itemize
|
|---|
| 11842 |
|
|---|
| 11843 | @node Missing, Makefile Conventions, Features, Top
|
|---|
| 11844 | @chapter Incompatibilities and Missing Features
|
|---|
| 11845 | @cindex incompatibilities
|
|---|
| 11846 | @cindex missing features
|
|---|
| 11847 | @cindex features, missing
|
|---|
| 11848 |
|
|---|
| 11849 | The @code{make} programs in various other systems support a few features
|
|---|
| 11850 | that are not implemented in GNU @code{make}. The POSIX.2 standard
|
|---|
| 11851 | (@cite{IEEE Standard 1003.2-1992}) which specifies @code{make} does not
|
|---|
| 11852 | require any of these features.@refill
|
|---|
| 11853 |
|
|---|
| 11854 | @itemize @bullet
|
|---|
| 11855 | @item
|
|---|
| 11856 | A target of the form @samp{@var{file}((@var{entry}))} stands for a member
|
|---|
| 11857 | of archive file @var{file}. The member is chosen, not by name, but by
|
|---|
| 11858 | being an object file which defines the linker symbol @var{entry}.@refill
|
|---|
| 11859 |
|
|---|
| 11860 | This feature was not put into GNU @code{make} because of the
|
|---|
| 11861 | non-modularity of putting knowledge into @code{make} of the internal
|
|---|
| 11862 | format of archive file symbol tables.
|
|---|
| 11863 | @xref{Archive Symbols, ,Updating Archive Symbol Directories}.
|
|---|
| 11864 |
|
|---|
| 11865 | @item
|
|---|
| 11866 | Suffixes (used in suffix rules) that end with the character @samp{~}
|
|---|
| 11867 | have a special meaning to System V @code{make};
|
|---|
| 11868 | they refer to the SCCS file that corresponds
|
|---|
| 11869 | to the file one would get without the @samp{~}. For example, the
|
|---|
| 11870 | suffix rule @samp{.c~.o} would make the file @file{@var{n}.o} from
|
|---|
| 11871 | the SCCS file @file{s.@var{n}.c}. For complete coverage, a whole
|
|---|
| 11872 | series of such suffix rules is required.
|
|---|
| 11873 | @xref{Suffix Rules, ,Old-Fashioned Suffix Rules}.
|
|---|
| 11874 |
|
|---|
| 11875 | In GNU @code{make}, this entire series of cases is handled by two
|
|---|
| 11876 | pattern rules for extraction from SCCS, in combination with the
|
|---|
| 11877 | general feature of rule chaining.
|
|---|
| 11878 | @xref{Chained Rules, ,Chains of Implicit Rules}.
|
|---|
| 11879 |
|
|---|
| 11880 | @item
|
|---|
| 11881 | In System V and 4.3 BSD @code{make}, files found by @code{VPATH}
|
|---|
| 11882 | search (@pxref{Directory Search, ,Searching Directories for
|
|---|
| 11883 | Prerequisites}) have their names changed inside recipes. We feel it
|
|---|
| 11884 | is much cleaner to always use automatic variables and thus make this
|
|---|
| 11885 | feature obsolete.@refill
|
|---|
| 11886 |
|
|---|
| 11887 | @item
|
|---|
| 11888 | In some Unix @code{make}s, the automatic variable @code{$*} appearing in
|
|---|
| 11889 | the prerequisites of a rule has the amazingly strange ``feature'' of
|
|---|
| 11890 | expanding to the full name of the @emph{target of that rule}. We cannot
|
|---|
| 11891 | imagine what went on in the minds of Unix @code{make} developers to do
|
|---|
| 11892 | this; it is utterly inconsistent with the normal definition of @code{$*}.
|
|---|
| 11893 | @vindex * @r{(automatic variable), unsupported bizarre usage}
|
|---|
| 11894 |
|
|---|
| 11895 | @item
|
|---|
| 11896 | In some Unix @code{make}s, implicit rule search (@pxref{Implicit
|
|---|
| 11897 | Rules, ,Using Implicit Rules}) is apparently done for @emph{all}
|
|---|
| 11898 | targets, not just those without recipes. This means you can
|
|---|
| 11899 | do:@refill
|
|---|
| 11900 |
|
|---|
| 11901 | @example
|
|---|
| 11902 | @group
|
|---|
| 11903 | foo.o:
|
|---|
| 11904 | cc -c foo.c
|
|---|
| 11905 | @end group
|
|---|
| 11906 | @end example
|
|---|
| 11907 |
|
|---|
| 11908 | @noindent
|
|---|
| 11909 | and Unix @code{make} will intuit that @file{foo.o} depends on
|
|---|
| 11910 | @file{foo.c}.@refill
|
|---|
| 11911 |
|
|---|
| 11912 | We feel that such usage is broken. The prerequisite properties of
|
|---|
| 11913 | @code{make} are well-defined (for GNU @code{make}, at least),
|
|---|
| 11914 | and doing such a thing simply does not fit the model.@refill
|
|---|
| 11915 |
|
|---|
| 11916 | @item
|
|---|
| 11917 | GNU @code{make} does not include any built-in implicit rules for
|
|---|
| 11918 | compiling or preprocessing EFL programs. If we hear of anyone who is
|
|---|
| 11919 | using EFL, we will gladly add them.
|
|---|
| 11920 |
|
|---|
| 11921 | @item
|
|---|
| 11922 | It appears that in SVR4 @code{make}, a suffix rule can be specified
|
|---|
| 11923 | with no recipe, and it is treated as if it had an empty recipe
|
|---|
| 11924 | (@pxref{Empty Recipes}). For example:
|
|---|
| 11925 |
|
|---|
| 11926 | @example
|
|---|
| 11927 | .c.a:
|
|---|
| 11928 | @end example
|
|---|
| 11929 |
|
|---|
| 11930 | @noindent
|
|---|
| 11931 | will override the built-in @file{.c.a} suffix rule.
|
|---|
| 11932 |
|
|---|
| 11933 | We feel that it is cleaner for a rule without a recipe to always simply
|
|---|
| 11934 | add to the prerequisite list for the target. The above example can be
|
|---|
| 11935 | easily rewritten to get the desired behavior in GNU @code{make}:
|
|---|
| 11936 |
|
|---|
| 11937 | @example
|
|---|
| 11938 | .c.a: ;
|
|---|
| 11939 | @end example
|
|---|
| 11940 |
|
|---|
| 11941 | @item
|
|---|
| 11942 | Some versions of @code{make} invoke the shell with the @samp{-e} flag,
|
|---|
| 11943 | except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a
|
|---|
| 11944 | Program}). The @samp{-e} flag tells the shell to exit as soon as any
|
|---|
| 11945 | program it runs returns a nonzero status. We feel it is cleaner to
|
|---|
| 11946 | write each line of the recipe to stand on its own and not require this
|
|---|
| 11947 | special treatment.
|
|---|
| 11948 | @end itemize
|
|---|
| 11949 |
|
|---|
| 11950 | @comment The makefile standards are in a separate file that is also
|
|---|
| 11951 | @comment included by standards.texi.
|
|---|
| 11952 | @include make-stds.texi
|
|---|
| 11953 |
|
|---|
| 11954 | @node Quick Reference, Error Messages, Makefile Conventions, Top
|
|---|
| 11955 | @appendix Quick Reference
|
|---|
| 11956 |
|
|---|
| 11957 | This appendix summarizes the directives, text manipulation functions,
|
|---|
| 11958 | and special variables which GNU @code{make} understands.
|
|---|
| 11959 | @xref{Special Targets}, @ref{Catalogue of Rules, ,Catalogue of Built-In Rules},
|
|---|
| 11960 | and @ref{Options Summary, ,Summary of Options},
|
|---|
| 11961 | for other summaries.
|
|---|
| 11962 |
|
|---|
| 11963 | Here is a summary of the directives GNU @code{make} recognizes:
|
|---|
| 11964 |
|
|---|
| 11965 | @table @code
|
|---|
| 11966 | @item define @var{variable}
|
|---|
| 11967 | @itemx define @var{variable} =
|
|---|
| 11968 | @itemx define @var{variable} :=
|
|---|
| 11969 | @itemx define @var{variable} ::=
|
|---|
| 11970 | @itemx define @var{variable} +=
|
|---|
| 11971 | @itemx define @var{variable} ?=
|
|---|
| 11972 | @itemx endef
|
|---|
| 11973 | Define multi-line variables.@*
|
|---|
| 11974 | @xref{Multi-Line}.
|
|---|
| 11975 |
|
|---|
| 11976 | @item undefine @var{variable}
|
|---|
| 11977 | Undefining variables.@*
|
|---|
| 11978 | @xref{Undefine Directive}.
|
|---|
| 11979 |
|
|---|
| 11980 | @item ifdef @var{variable}
|
|---|
| 11981 | @itemx ifndef @var{variable}
|
|---|
| 11982 | @itemx ifeq (@var{a},@var{b})
|
|---|
| 11983 | @itemx ifeq "@var{a}" "@var{b}"
|
|---|
| 11984 | @itemx ifeq '@var{a}' '@var{b}'
|
|---|
| 11985 | @itemx ifneq (@var{a},@var{b})
|
|---|
| 11986 | @itemx ifneq "@var{a}" "@var{b}"
|
|---|
| 11987 | @itemx ifneq '@var{a}' '@var{b}'
|
|---|
| 11988 | @itemx else
|
|---|
| 11989 | @itemx endif
|
|---|
| 11990 | Conditionally evaluate part of the makefile.@*
|
|---|
| 11991 | @xref{Conditionals}.
|
|---|
| 11992 |
|
|---|
| 11993 | @item include @var{file}
|
|---|
| 11994 | @itemx -include @var{file}
|
|---|
| 11995 | @itemx sinclude @var{file}
|
|---|
| 11996 | Include another makefile.@*
|
|---|
| 11997 | @xref{Include, ,Including Other Makefiles}.
|
|---|
| 11998 |
|
|---|
| 11999 | @item override @var{variable-assignment}
|
|---|
| 12000 | Define a variable, overriding any previous definition, even one from
|
|---|
| 12001 | the command line.@*
|
|---|
| 12002 | @xref{Override Directive, ,The @code{override} Directive}.
|
|---|
| 12003 |
|
|---|
| 12004 | @item export
|
|---|
| 12005 | Tell @code{make} to export all variables to child processes by default.@*
|
|---|
| 12006 | @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
|
|---|
| 12007 |
|
|---|
| 12008 | @item export @var{variable}
|
|---|
| 12009 | @itemx export @var{variable-assignment}
|
|---|
| 12010 | @itemx unexport @var{variable}
|
|---|
| 12011 | Tell @code{make} whether or not to export a particular variable to child
|
|---|
| 12012 | processes.@*
|
|---|
| 12013 | @xref{Variables/Recursion, , Communicating Variables to a Sub-@code{make}}.
|
|---|
| 12014 |
|
|---|
| 12015 | @item private @var{variable-assignment}
|
|---|
| 12016 | Do not allow this variable assignment to be inherited by prerequisites.@*
|
|---|
| 12017 | @xref{Suppressing Inheritance}.
|
|---|
| 12018 |
|
|---|
| 12019 | @item vpath @var{pattern} @var{path}
|
|---|
| 12020 | Specify a search path for files matching a @samp{%} pattern.@*
|
|---|
| 12021 | @xref{Selective Search, , The @code{vpath} Directive}.
|
|---|
| 12022 |
|
|---|
| 12023 | @item vpath @var{pattern}
|
|---|
| 12024 | Remove all search paths previously specified for @var{pattern}.
|
|---|
| 12025 |
|
|---|
| 12026 | @item vpath
|
|---|
| 12027 | Remove all search paths previously specified in any @code{vpath}
|
|---|
| 12028 | directive.
|
|---|
| 12029 | @end table
|
|---|
| 12030 |
|
|---|
| 12031 | Here is a summary of the built-in functions (@pxref{Functions}):
|
|---|
| 12032 |
|
|---|
| 12033 | @table @code
|
|---|
| 12034 | @item $(subst @var{from},@var{to},@var{text})
|
|---|
| 12035 | Replace @var{from} with @var{to} in @var{text}.@*
|
|---|
| 12036 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12037 |
|
|---|
| 12038 | @item $(patsubst @var{pattern},@var{replacement},@var{text})
|
|---|
| 12039 | Replace words matching @var{pattern} with @var{replacement} in @var{text}.@*
|
|---|
| 12040 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12041 |
|
|---|
| 12042 | @item $(strip @var{string})
|
|---|
| 12043 | Remove excess whitespace characters from @var{string}.@*
|
|---|
| 12044 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12045 |
|
|---|
| 12046 | @item $(findstring @var{find},@var{text})
|
|---|
| 12047 | Locate @var{find} in @var{text}.@*
|
|---|
| 12048 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12049 |
|
|---|
| 12050 | @item $(filter @var{pattern}@dots{},@var{text})
|
|---|
| 12051 | Select words in @var{text} that match one of the @var{pattern} words.@*
|
|---|
| 12052 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12053 |
|
|---|
| 12054 | @item $(filter-out @var{pattern}@dots{},@var{text})
|
|---|
| 12055 | Select words in @var{text} that @emph{do not} match any of the @var{pattern} words.@*
|
|---|
| 12056 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12057 |
|
|---|
| 12058 | @item $(sort @var{list})
|
|---|
| 12059 | Sort the words in @var{list} lexicographically, removing duplicates.@*
|
|---|
| 12060 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12061 |
|
|---|
| 12062 | @item $(word @var{n},@var{text})
|
|---|
| 12063 | Extract the @var{n}th word (one-origin) of @var{text}.@*
|
|---|
| 12064 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12065 |
|
|---|
| 12066 | @item $(words @var{text})
|
|---|
| 12067 | Count the number of words in @var{text}.@*
|
|---|
| 12068 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12069 |
|
|---|
| 12070 | @item $(wordlist @var{s},@var{e},@var{text})
|
|---|
| 12071 | Returns the list of words in @var{text} from @var{s} to @var{e}.@*
|
|---|
| 12072 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12073 |
|
|---|
| 12074 | @item $(firstword @var{names}@dots{})
|
|---|
| 12075 | Extract the first word of @var{names}.@*
|
|---|
| 12076 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12077 |
|
|---|
| 12078 | @item $(lastword @var{names}@dots{})
|
|---|
| 12079 | Extract the last word of @var{names}.@*
|
|---|
| 12080 | @xref{Text Functions, , Functions for String Substitution and Analysis}.
|
|---|
| 12081 |
|
|---|
| 12082 | @item $(dir @var{names}@dots{})
|
|---|
| 12083 | Extract the directory part of each file name.@*
|
|---|
| 12084 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12085 |
|
|---|
| 12086 | @item $(notdir @var{names}@dots{})
|
|---|
| 12087 | Extract the non-directory part of each file name.@*
|
|---|
| 12088 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12089 |
|
|---|
| 12090 | @item $(suffix @var{names}@dots{})
|
|---|
| 12091 | Extract the suffix (the last @samp{.} and following characters) of each file name.@*
|
|---|
| 12092 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12093 |
|
|---|
| 12094 | @item $(basename @var{names}@dots{})
|
|---|
| 12095 | Extract the base name (name without suffix) of each file name.@*
|
|---|
| 12096 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12097 |
|
|---|
| 12098 | @item $(addsuffix @var{suffix},@var{names}@dots{})
|
|---|
| 12099 | Append @var{suffix} to each word in @var{names}.@*
|
|---|
| 12100 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12101 |
|
|---|
| 12102 | @item $(addprefix @var{prefix},@var{names}@dots{})
|
|---|
| 12103 | Prepend @var{prefix} to each word in @var{names}.@*
|
|---|
| 12104 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12105 |
|
|---|
| 12106 | @item $(join @var{list1},@var{list2})
|
|---|
| 12107 | Join two parallel lists of words.@*
|
|---|
| 12108 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12109 |
|
|---|
| 12110 | @item $(wildcard @var{pattern}@dots{})
|
|---|
| 12111 | Find file names matching a shell file name pattern (@emph{not} a
|
|---|
| 12112 | @samp{%} pattern).@*
|
|---|
| 12113 | @xref{Wildcard Function, ,The Function @code{wildcard}}.
|
|---|
| 12114 |
|
|---|
| 12115 | @item $(realpath @var{names}@dots{})
|
|---|
| 12116 | For each file name in @var{names}, expand to an absolute name that
|
|---|
| 12117 | does not contain any @code{.}, @code{..}, nor symlinks.@*
|
|---|
| 12118 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12119 |
|
|---|
| 12120 | @item $(abspath @var{names}@dots{})
|
|---|
| 12121 | For each file name in @var{names}, expand to an absolute name that
|
|---|
| 12122 | does not contain any @code{.} or @code{..} components, but preserves
|
|---|
| 12123 | symlinks.@*
|
|---|
| 12124 | @xref{File Name Functions, ,Functions for File Names}.
|
|---|
| 12125 |
|
|---|
| 12126 | @item $(error @var{text}@dots{})
|
|---|
| 12127 | When this function is evaluated, @code{make} generates a fatal error
|
|---|
| 12128 | with the message @var{text}.@*
|
|---|
| 12129 | @xref{Make Control Functions, ,Functions That Control Make}.
|
|---|
| 12130 |
|
|---|
| 12131 | @item $(warning @var{text}@dots{})
|
|---|
| 12132 | When this function is evaluated, @code{make} generates a warning with
|
|---|
| 12133 | the message @var{text}.@*
|
|---|
| 12134 | @xref{Make Control Functions, ,Functions That Control Make}.
|
|---|
| 12135 |
|
|---|
| 12136 | @item $(shell @var{command})
|
|---|
| 12137 | Execute a shell command and return its output.@*
|
|---|
| 12138 | @xref{Shell Function, , The @code{shell} Function}.
|
|---|
| 12139 |
|
|---|
| 12140 | @item $(origin @var{variable})
|
|---|
| 12141 | Return a string describing how the @code{make} variable @var{variable} was
|
|---|
| 12142 | defined.@*
|
|---|
| 12143 | @xref{Origin Function, , The @code{origin} Function}.
|
|---|
| 12144 |
|
|---|
| 12145 | @item $(flavor @var{variable})
|
|---|
| 12146 | Return a string describing the flavor of the @code{make} variable
|
|---|
| 12147 | @var{variable}.@*
|
|---|
| 12148 | @xref{Flavor Function, , The @code{flavor} Function}.
|
|---|
| 12149 |
|
|---|
| 12150 | @item $(foreach @var{var},@var{words},@var{text})
|
|---|
| 12151 | Evaluate @var{text} with @var{var} bound to each word in @var{words},
|
|---|
| 12152 | and concatenate the results.@*
|
|---|
| 12153 | @xref{Foreach Function, ,The @code{foreach} Function}.
|
|---|
| 12154 |
|
|---|
| 12155 | @item $(if @var{condition},@var{then-part}[,@var{else-part}])
|
|---|
| 12156 | Evaluate the condition @var{condition}; if it's non-empty substitute
|
|---|
| 12157 | the expansion of the @var{then-part} otherwise substitute the
|
|---|
| 12158 | expansion of the @var{else-part}.@*
|
|---|
| 12159 | @xref{Conditional Functions, ,Functions for Conditionals}.
|
|---|
| 12160 |
|
|---|
| 12161 | @item $(or @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
|
|---|
| 12162 | Evaluate each condition @var{conditionN} one at a time; substitute the
|
|---|
| 12163 | first non-empty expansion. If all expansions are empty, substitute
|
|---|
| 12164 | the empty string.@*
|
|---|
| 12165 | @xref{Conditional Functions, ,Functions for Conditionals}.
|
|---|
| 12166 |
|
|---|
| 12167 | @item $(and @var{condition1}[,@var{condition2}[,@var{condition3}@dots{}]])
|
|---|
| 12168 | Evaluate each condition @var{conditionN} one at a time; if any
|
|---|
| 12169 | expansion results in the empty string substitute the empty string. If
|
|---|
| 12170 | all expansions result in a non-empty string, substitute the expansion
|
|---|
| 12171 | of the last @var{condition}.@*
|
|---|
| 12172 | @xref{Conditional Functions, ,Functions for Conditionals}.
|
|---|
| 12173 |
|
|---|
| 12174 | @item $(call @var{var},@var{param},@dots{})
|
|---|
| 12175 | Evaluate the variable @var{var} replacing any references to @code{$(1)},
|
|---|
| 12176 | @code{$(2)} with the first, second, etc.@: @var{param} values.@*
|
|---|
| 12177 | @xref{Call Function, ,The @code{call} Function}.
|
|---|
| 12178 |
|
|---|
| 12179 | @item $(eval @var{text})
|
|---|
| 12180 | Evaluate @var{text} then read the results as makefile commands.
|
|---|
| 12181 | Expands to the empty string.@*
|
|---|
| 12182 | @xref{Eval Function, ,The @code{eval} Function}.
|
|---|
| 12183 |
|
|---|
| 12184 | @item $(file @var{op} @var{filename},@var{text})
|
|---|
| 12185 | Expand the arguments, then open the file @var{filename} using mode
|
|---|
| 12186 | @var{op} and write @var{text} to that file.@*
|
|---|
| 12187 | @xref{File Function, ,The @code{file} Function}.
|
|---|
| 12188 |
|
|---|
| 12189 | @item $(value @var{var})
|
|---|
| 12190 | Evaluates to the contents of the variable @var{var}, with no expansion
|
|---|
| 12191 | performed on it.@*
|
|---|
| 12192 | @xref{Value Function, ,The @code{value} Function}.
|
|---|
| 12193 | @end table
|
|---|
| 12194 |
|
|---|
| 12195 | Here is a summary of the automatic variables.
|
|---|
| 12196 | @xref{Automatic Variables},
|
|---|
| 12197 | for full information.
|
|---|
| 12198 |
|
|---|
| 12199 | @table @code
|
|---|
| 12200 | @item $@@
|
|---|
| 12201 | The file name of the target.
|
|---|
| 12202 |
|
|---|
| 12203 | @item $%
|
|---|
| 12204 | The target member name, when the target is an archive member.
|
|---|
| 12205 |
|
|---|
| 12206 | @item $<
|
|---|
| 12207 | The name of the first prerequisite.
|
|---|
| 12208 |
|
|---|
| 12209 | @item $?
|
|---|
| 12210 | The names of all the prerequisites that are
|
|---|
| 12211 | newer than the target, with spaces between them.
|
|---|
| 12212 | For prerequisites which are archive members, only
|
|---|
| 12213 | the named member is used (@pxref{Archives}).
|
|---|
| 12214 |
|
|---|
| 12215 | @item $^
|
|---|
| 12216 | @itemx $+
|
|---|
| 12217 | The names of all the prerequisites, with spaces between them. For
|
|---|
| 12218 | prerequisites which are archive members, only the named member is used
|
|---|
| 12219 | (@pxref{Archives}). The value of @code{$^} omits duplicate
|
|---|
| 12220 | prerequisites, while @code{$+} retains them and preserves their order.
|
|---|
| 12221 |
|
|---|
| 12222 | @item $*
|
|---|
| 12223 | The stem with which an implicit rule matches
|
|---|
| 12224 | (@pxref{Pattern Match, ,How Patterns Match}).
|
|---|
| 12225 |
|
|---|
| 12226 | @item $(@@D)
|
|---|
| 12227 | @itemx $(@@F)
|
|---|
| 12228 | The directory part and the file-within-directory part of @code{$@@}.
|
|---|
| 12229 |
|
|---|
| 12230 | @item $(*D)
|
|---|
| 12231 | @itemx $(*F)
|
|---|
| 12232 | The directory part and the file-within-directory part of @code{$*}.
|
|---|
| 12233 |
|
|---|
| 12234 | @item $(%D)
|
|---|
| 12235 | @itemx $(%F)
|
|---|
| 12236 | The directory part and the file-within-directory part of @code{$%}.
|
|---|
| 12237 |
|
|---|
| 12238 | @item $(<D)
|
|---|
| 12239 | @itemx $(<F)
|
|---|
| 12240 | The directory part and the file-within-directory part of @code{$<}.
|
|---|
| 12241 |
|
|---|
| 12242 | @item $(^D)
|
|---|
| 12243 | @itemx $(^F)
|
|---|
| 12244 | The directory part and the file-within-directory part of @code{$^}.
|
|---|
| 12245 |
|
|---|
| 12246 | @item $(+D)
|
|---|
| 12247 | @itemx $(+F)
|
|---|
| 12248 | The directory part and the file-within-directory part of @code{$+}.
|
|---|
| 12249 |
|
|---|
| 12250 | @item $(?D)
|
|---|
| 12251 | @itemx $(?F)
|
|---|
| 12252 | The directory part and the file-within-directory part of @code{$?}.
|
|---|
| 12253 | @end table
|
|---|
| 12254 |
|
|---|
| 12255 | These variables are used specially by GNU @code{make}:
|
|---|
| 12256 |
|
|---|
| 12257 | @table @code
|
|---|
| 12258 | @item MAKEFILES
|
|---|
| 12259 |
|
|---|
| 12260 | Makefiles to be read on every invocation of @code{make}.@*
|
|---|
| 12261 | @xref{MAKEFILES Variable, ,The Variable @code{MAKEFILES}}.
|
|---|
| 12262 |
|
|---|
| 12263 | @item VPATH
|
|---|
| 12264 |
|
|---|
| 12265 | Directory search path for files not found in the current directory.@*
|
|---|
| 12266 | @xref{General Search, , @code{VPATH} Search Path for All Prerequisites}.
|
|---|
| 12267 |
|
|---|
| 12268 | @item SHELL
|
|---|
| 12269 |
|
|---|
| 12270 | The name of the system default command interpreter, usually @file{/bin/sh}.
|
|---|
| 12271 | You can set @code{SHELL} in the makefile to change the shell used to run
|
|---|
| 12272 | recipes. @xref{Execution, ,Recipe Execution}. The @code{SHELL}
|
|---|
| 12273 | variable is handled specially when importing from and exporting to the
|
|---|
| 12274 | environment. @xref{Choosing the Shell}.
|
|---|
| 12275 |
|
|---|
| 12276 | @item MAKESHELL
|
|---|
| 12277 |
|
|---|
| 12278 | On MS-DOS only, the name of the command interpreter that is to be used
|
|---|
| 12279 | by @code{make}. This value takes precedence over the value of
|
|---|
| 12280 | @code{SHELL}. @xref{Execution, ,MAKESHELL variable}.
|
|---|
| 12281 |
|
|---|
| 12282 | @item MAKE
|
|---|
| 12283 |
|
|---|
| 12284 | The name with which @code{make} was invoked. Using this variable in
|
|---|
| 12285 | recipes has special meaning. @xref{MAKE Variable, ,How the
|
|---|
| 12286 | @code{MAKE} Variable Works}.
|
|---|
| 12287 |
|
|---|
| 12288 | @item MAKE_VERSION
|
|---|
| 12289 |
|
|---|
| 12290 | The built-in variable @samp{MAKE_VERSION} expands to the version
|
|---|
| 12291 | number of the GNU @code{make} program.
|
|---|
| 12292 | @vindex MAKE_VERSION
|
|---|
| 12293 |
|
|---|
| 12294 | @item MAKE_HOST
|
|---|
| 12295 |
|
|---|
| 12296 | The built-in variable @samp{MAKE_HOST} expands to a string
|
|---|
| 12297 | representing the host that GNU @code{make} was built to run on.
|
|---|
| 12298 | @vindex MAKE_HOST
|
|---|
| 12299 |
|
|---|
| 12300 | @item MAKELEVEL
|
|---|
| 12301 |
|
|---|
| 12302 | The number of levels of recursion (sub-@code{make}s).@*
|
|---|
| 12303 | @xref{Variables/Recursion}.
|
|---|
| 12304 |
|
|---|
| 12305 | @item MAKEFLAGS
|
|---|
| 12306 |
|
|---|
| 12307 | The flags given to @code{make}. You can set this in the environment or
|
|---|
| 12308 | a makefile to set flags.@*
|
|---|
| 12309 | @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
|
|---|
| 12310 |
|
|---|
| 12311 | It is @emph{never} appropriate to use @code{MAKEFLAGS} directly in a
|
|---|
| 12312 | recipe line: its contents may not be quoted correctly for use in the
|
|---|
| 12313 | shell. Always allow recursive @code{make}'s to obtain these values
|
|---|
| 12314 | through the environment from its parent.
|
|---|
| 12315 |
|
|---|
| 12316 | @item GNUMAKEFLAGS
|
|---|
| 12317 |
|
|---|
| 12318 | Other flags parsed by @code{make}. You can set this in the environment or
|
|---|
| 12319 | a makefile to set @code{make} command-line flags. GNU @code{make}
|
|---|
| 12320 | never sets this variable itself. This variable is only needed if
|
|---|
| 12321 | you'd like to set GNU @code{make}-specific flags in a POSIX-compliant
|
|---|
| 12322 | makefile. This variable will be seen by GNU @code{make} and ignored
|
|---|
| 12323 | by other @code{make} implementations. It's not needed if you only use
|
|---|
| 12324 | GNU @code{make}; just use @code{MAKEFLAGS} directly.
|
|---|
| 12325 | @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}.
|
|---|
| 12326 |
|
|---|
| 12327 | @item MAKECMDGOALS
|
|---|
| 12328 |
|
|---|
| 12329 | The targets given to @code{make} on the command line. Setting this
|
|---|
| 12330 | variable has no effect on the operation of @code{make}.@*
|
|---|
| 12331 | @xref{Goals, ,Arguments to Specify the Goals}.
|
|---|
| 12332 |
|
|---|
| 12333 | @item CURDIR
|
|---|
| 12334 |
|
|---|
| 12335 | Set to the absolute pathname of the current working directory (after
|
|---|
| 12336 | all @code{-C} options are processed, if any). Setting this variable
|
|---|
| 12337 | has no effect on the operation of @code{make}.@*
|
|---|
| 12338 | @xref{Recursion, ,Recursive Use of @code{make}}.
|
|---|
| 12339 |
|
|---|
| 12340 | @item SUFFIXES
|
|---|
| 12341 |
|
|---|
| 12342 | The default list of suffixes before @code{make} reads any makefiles.
|
|---|
| 12343 |
|
|---|
| 12344 | @item .LIBPATTERNS
|
|---|
| 12345 | Defines the naming of the libraries @code{make} searches for, and their
|
|---|
| 12346 | order.@*
|
|---|
| 12347 | @xref{Libraries/Search, ,Directory Search for Link Libraries}.
|
|---|
| 12348 | @end table
|
|---|
| 12349 |
|
|---|
| 12350 | @node Error Messages, Complex Makefile, Quick Reference, Top
|
|---|
| 12351 | @comment node-name, next, previous, up
|
|---|
| 12352 | @appendix Errors Generated by Make
|
|---|
| 12353 |
|
|---|
| 12354 | Here is a list of the more common errors you might see generated by
|
|---|
| 12355 | @code{make}, and some information about what they mean and how to fix
|
|---|
| 12356 | them.
|
|---|
| 12357 |
|
|---|
| 12358 | Sometimes @code{make} errors are not fatal, especially in the presence
|
|---|
| 12359 | of a @code{-} prefix on a recipe line, or the @code{-k} command line
|
|---|
| 12360 | option. Errors that are fatal are prefixed with the string
|
|---|
| 12361 | @code{***}.
|
|---|
| 12362 |
|
|---|
| 12363 | Error messages are all either prefixed with the name of the program
|
|---|
| 12364 | (usually @samp{make}), or, if the error is found in a makefile, the name
|
|---|
| 12365 | of the file and line number containing the problem.
|
|---|
| 12366 |
|
|---|
| 12367 | In the table below, these common prefixes are left off.
|
|---|
| 12368 |
|
|---|
| 12369 | @table @samp
|
|---|
| 12370 |
|
|---|
| 12371 | @item [@var{foo}] Error @var{NN}
|
|---|
| 12372 | @itemx [@var{foo}] @var{signal description}
|
|---|
| 12373 | These errors are not really @code{make} errors at all. They mean that a
|
|---|
| 12374 | program that @code{make} invoked as part of a recipe returned a
|
|---|
| 12375 | non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets
|
|---|
| 12376 | as failure, or it exited in some other abnormal fashion (with a
|
|---|
| 12377 | signal of some type). @xref{Errors, ,Errors in Recipes}.
|
|---|
| 12378 |
|
|---|
| 12379 | If no @code{***} is attached to the message, then the sub-process failed
|
|---|
| 12380 | but the rule in the makefile was prefixed with the @code{-} special
|
|---|
| 12381 | character, so @code{make} ignored the error.
|
|---|
| 12382 |
|
|---|
| 12383 | @item missing separator. Stop.
|
|---|
| 12384 | @itemx missing separator (did you mean TAB instead of 8 spaces?). Stop.
|
|---|
| 12385 | This means that @code{make} could not understand much of anything
|
|---|
| 12386 | about the makefile line it just read. GNU @code{make} looks for
|
|---|
| 12387 | various separators (@code{:}, @code{=}, recipe prefix characters,
|
|---|
| 12388 | etc.) to indicate what kind of line it's parsing. This message means
|
|---|
| 12389 | it couldn't find a valid one.
|
|---|
| 12390 |
|
|---|
| 12391 | One of the most common reasons for this message is that you (or
|
|---|
| 12392 | perhaps your oh-so-helpful editor, as is the case with many MS-Windows
|
|---|
| 12393 | editors) have attempted to indent your recipe lines with spaces
|
|---|
| 12394 | instead of a tab character. In this case, @code{make} will use the
|
|---|
| 12395 | second form of the error above. Remember that every line in the
|
|---|
| 12396 | recipe must begin with a tab character (unless you set
|
|---|
| 12397 | @code{.RECIPEPREFIX}; @pxref{Special Variables}). Eight spaces do not
|
|---|
| 12398 | count. @xref{Rule Syntax}.
|
|---|
| 12399 |
|
|---|
| 12400 | @item recipe commences before first target. Stop.
|
|---|
| 12401 | @itemx missing rule before recipe. Stop.
|
|---|
| 12402 | This means the first thing in the makefile seems to be part of a
|
|---|
| 12403 | recipe: it begins with a recipe prefix character and doesn't appear to
|
|---|
| 12404 | be a legal @code{make} directive (such as a variable assignment).
|
|---|
| 12405 | Recipes must always be associated with a target.
|
|---|
| 12406 |
|
|---|
| 12407 | The second form is generated if the line has a semicolon as the first
|
|---|
| 12408 | non-whitespace character; @code{make} interprets this to mean you left
|
|---|
| 12409 | out the "target: prerequisite" section of a rule. @xref{Rule Syntax}.
|
|---|
| 12410 |
|
|---|
| 12411 | @item No rule to make target `@var{xxx}'.
|
|---|
| 12412 | @itemx No rule to make target `@var{xxx}', needed by `@var{yyy}'.
|
|---|
| 12413 | This means that @code{make} decided it needed to build a target, but
|
|---|
| 12414 | then couldn't find any instructions in the makefile on how to do that,
|
|---|
| 12415 | either explicit or implicit (including in the default rules database).
|
|---|
| 12416 |
|
|---|
| 12417 | If you want that file to be built, you will need to add a rule to your
|
|---|
| 12418 | makefile describing how that target can be built. Other possible
|
|---|
| 12419 | sources of this problem are typos in the makefile (if that file name is
|
|---|
| 12420 | wrong) or a corrupted source tree (if that file is not supposed to be
|
|---|
| 12421 | built, but rather only a prerequisite).
|
|---|
| 12422 |
|
|---|
| 12423 | @item No targets specified and no makefile found. Stop.
|
|---|
| 12424 | @itemx No targets. Stop.
|
|---|
| 12425 | The former means that you didn't provide any targets to be built on the
|
|---|
| 12426 | command line, and @code{make} couldn't find any makefiles to read in.
|
|---|
| 12427 | The latter means that some makefile was found, but it didn't contain any
|
|---|
| 12428 | default goal and none was given on the command line. GNU @code{make}
|
|---|
| 12429 | has nothing to do in these situations.
|
|---|
| 12430 | @xref{Makefile Arguments, ,Arguments to Specify the Makefile}.@refill
|
|---|
| 12431 |
|
|---|
| 12432 | @item Makefile `@var{xxx}' was not found.
|
|---|
| 12433 | @itemx Included makefile `@var{xxx}' was not found.
|
|---|
| 12434 | A makefile specified on the command line (first form) or included
|
|---|
| 12435 | (second form) was not found.
|
|---|
| 12436 |
|
|---|
| 12437 | @item warning: overriding recipe for target `@var{xxx}'
|
|---|
| 12438 | @itemx warning: ignoring old recipe for target `@var{xxx}'
|
|---|
| 12439 | GNU @code{make} allows only one recipe to be specified per target
|
|---|
| 12440 | (except for double-colon rules). If you give a recipe for a target
|
|---|
| 12441 | which already has been defined to have one, this warning is issued and
|
|---|
| 12442 | the second recipe will overwrite the first. @xref{Multiple Rules,
|
|---|
| 12443 | ,Multiple Rules for One Target}.
|
|---|
| 12444 |
|
|---|
| 12445 | @item Circular @var{xxx} <- @var{yyy} dependency dropped.
|
|---|
| 12446 | This means that @code{make} detected a loop in the dependency graph:
|
|---|
| 12447 | after tracing the prerequisite @var{yyy} of target @var{xxx}, and its
|
|---|
| 12448 | prerequisites, etc., one of them depended on @var{xxx} again.
|
|---|
| 12449 |
|
|---|
| 12450 | @item Recursive variable `@var{xxx}' references itself (eventually). Stop.
|
|---|
| 12451 | This means you've defined a normal (recursive) @code{make} variable
|
|---|
| 12452 | @var{xxx} that, when it's expanded, will refer to itself (@var{xxx}).
|
|---|
| 12453 | This is not allowed; either use simply-expanded variables (@samp{:=}
|
|---|
| 12454 | or @samp{::=}) or use the append operator (@samp{+=}). @xref{Using
|
|---|
| 12455 | Variables, ,How to Use Variables}.
|
|---|
| 12456 |
|
|---|
| 12457 | @item Unterminated variable reference. Stop.
|
|---|
| 12458 | This means you forgot to provide the proper closing parenthesis
|
|---|
| 12459 | or brace in your variable or function reference.
|
|---|
| 12460 |
|
|---|
| 12461 | @item insufficient arguments to function `@var{xxx}'. Stop.
|
|---|
| 12462 | This means you haven't provided the requisite number of arguments for
|
|---|
| 12463 | this function. See the documentation of the function for a description
|
|---|
| 12464 | of its arguments. @xref{Functions, ,Functions for Transforming Text}.
|
|---|
| 12465 |
|
|---|
| 12466 | @item missing target pattern. Stop.
|
|---|
| 12467 | @itemx multiple target patterns. Stop.
|
|---|
| 12468 | @itemx target pattern contains no `%'. Stop.
|
|---|
| 12469 | @itemx mixed implicit and static pattern rules. Stop.
|
|---|
| 12470 | These are generated for malformed static pattern rules. The first
|
|---|
| 12471 | means there's no pattern in the target section of the rule; the second
|
|---|
| 12472 | means there are multiple patterns in the target section; the third
|
|---|
| 12473 | means the target doesn't contain a pattern character (@code{%}); and
|
|---|
| 12474 | the fourth means that all three parts of the static pattern rule
|
|---|
| 12475 | contain pattern characters (@code{%})--only the first two parts
|
|---|
| 12476 | should. If you see these errors and you aren't trying to create a
|
|---|
| 12477 | static pattern rule, check the value of any variables in your target
|
|---|
| 12478 | and prerequisite lists to be sure they do not contain colons.
|
|---|
| 12479 | @xref{Static Usage, ,Syntax of Static Pattern Rules}.
|
|---|
| 12480 |
|
|---|
| 12481 | @item warning: -jN forced in submake: disabling jobserver mode.
|
|---|
| 12482 | This warning and the next are generated if @code{make} detects error
|
|---|
| 12483 | conditions related to parallel processing on systems where
|
|---|
| 12484 | sub-@code{make}s can communicate (@pxref{Options/Recursion,
|
|---|
| 12485 | ,Communicating Options to a Sub-@code{make}}). This warning is
|
|---|
| 12486 | generated if a recursive invocation of a @code{make} process is forced
|
|---|
| 12487 | to have @samp{-j@var{N}} in its argument list (where @var{N} is greater
|
|---|
| 12488 | than one). This could happen, for example, if you set the @code{MAKE}
|
|---|
| 12489 | environment variable to @samp{make -j2}. In this case, the
|
|---|
| 12490 | sub-@code{make} doesn't communicate with other @code{make} processes and
|
|---|
| 12491 | will simply pretend it has two jobs of its own.
|
|---|
| 12492 |
|
|---|
| 12493 | @item warning: jobserver unavailable: using -j1. Add `+' to parent make rule.
|
|---|
| 12494 | In order for @code{make} processes to communicate, the parent will pass
|
|---|
| 12495 | information to the child. Since this could result in problems if the
|
|---|
| 12496 | child process isn't actually a @code{make}, the parent will only do this
|
|---|
| 12497 | if it thinks the child is a @code{make}. The parent uses the normal
|
|---|
| 12498 | algorithms to determine this (@pxref{MAKE Variable, ,How the @code{MAKE}
|
|---|
| 12499 | Variable Works}). If the makefile is constructed such that the parent
|
|---|
| 12500 | doesn't know the child is a @code{make} process, then the child will
|
|---|
| 12501 | receive only part of the information necessary. In this case, the child
|
|---|
| 12502 | will generate this warning message and proceed with its build in a
|
|---|
| 12503 | sequential manner.
|
|---|
| 12504 |
|
|---|
| 12505 | @end table
|
|---|
| 12506 |
|
|---|
| 12507 | @node Complex Makefile, GNU Free Documentation License, Error Messages, Top
|
|---|
| 12508 | @appendix Complex Makefile Example
|
|---|
| 12509 |
|
|---|
| 12510 | Here is the makefile for the GNU @code{tar} program. This is a
|
|---|
| 12511 | moderately complex makefile. The first line uses a @code{#!} setting
|
|---|
| 12512 | to allow the makefile to be executed directly.
|
|---|
| 12513 |
|
|---|
| 12514 | Because it is the first target, the default goal is @samp{all}. An
|
|---|
| 12515 | interesting feature of this makefile is that @file{testpad.h} is a
|
|---|
| 12516 | source file automatically created by the @code{testpad} program,
|
|---|
| 12517 | itself compiled from @file{testpad.c}.
|
|---|
| 12518 |
|
|---|
| 12519 | If you type @samp{make} or @samp{make all}, then @code{make} creates
|
|---|
| 12520 | the @file{tar} executable, the @file{rmt} daemon that provides
|
|---|
| 12521 | remote tape access, and the @file{tar.info} Info file.
|
|---|
| 12522 |
|
|---|
| 12523 | If you type @samp{make install}, then @code{make} not only creates
|
|---|
| 12524 | @file{tar}, @file{rmt}, and @file{tar.info}, but also installs
|
|---|
| 12525 | them.
|
|---|
| 12526 |
|
|---|
| 12527 | If you type @samp{make clean}, then @code{make} removes the @samp{.o}
|
|---|
| 12528 | files, and the @file{tar}, @file{rmt}, @file{testpad},
|
|---|
| 12529 | @file{testpad.h}, and @file{core} files.
|
|---|
| 12530 |
|
|---|
| 12531 | If you type @samp{make distclean}, then @code{make} not only removes
|
|---|
| 12532 | the same files as does @samp{make clean} but also the
|
|---|
| 12533 | @file{TAGS}, @file{Makefile}, and @file{config.status} files.
|
|---|
| 12534 | (Although it is not evident, this makefile (and
|
|---|
| 12535 | @file{config.status}) is generated by the user with the
|
|---|
| 12536 | @code{configure} program, which is provided in the @code{tar}
|
|---|
| 12537 | distribution, but is not shown here.)
|
|---|
| 12538 |
|
|---|
| 12539 | If you type @samp{make realclean}, then @code{make} removes the same
|
|---|
| 12540 | files as does @samp{make distclean} and also removes the Info files
|
|---|
| 12541 | generated from @file{tar.texinfo}.
|
|---|
| 12542 |
|
|---|
| 12543 | In addition, there are targets @code{shar} and @code{dist} that create
|
|---|
| 12544 | distribution kits.
|
|---|
| 12545 |
|
|---|
| 12546 | @example
|
|---|
| 12547 | @group
|
|---|
| 12548 | #!/usr/bin/make -f
|
|---|
| 12549 | # Generated automatically from Makefile.in by configure.
|
|---|
| 12550 | # Un*x Makefile for GNU tar program.
|
|---|
| 12551 | # Copyright (C) 1991 Free Software Foundation, Inc.
|
|---|
| 12552 | @end group
|
|---|
| 12553 |
|
|---|
| 12554 | @group
|
|---|
| 12555 | # This program is free software; you can redistribute
|
|---|
| 12556 | # it and/or modify it under the terms of the GNU
|
|---|
| 12557 | # General Public License @dots{}
|
|---|
| 12558 | @dots{}
|
|---|
| 12559 | @dots{}
|
|---|
| 12560 | @end group
|
|---|
| 12561 |
|
|---|
| 12562 | SHELL = /bin/sh
|
|---|
| 12563 |
|
|---|
| 12564 | #### Start of system configuration section. ####
|
|---|
| 12565 |
|
|---|
| 12566 | srcdir = .
|
|---|
| 12567 |
|
|---|
| 12568 | @group
|
|---|
| 12569 | # If you use gcc, you should either run the
|
|---|
| 12570 | # fixincludes script that comes with it or else use
|
|---|
| 12571 | # gcc with the -traditional option. Otherwise ioctl
|
|---|
| 12572 | # calls will be compiled incorrectly on some systems.
|
|---|
| 12573 | CC = gcc -O
|
|---|
| 12574 | YACC = bison -y
|
|---|
| 12575 | INSTALL = /usr/local/bin/install -c
|
|---|
| 12576 | INSTALLDATA = /usr/local/bin/install -c -m 644
|
|---|
| 12577 | @end group
|
|---|
| 12578 |
|
|---|
| 12579 | # Things you might add to DEFS:
|
|---|
| 12580 | # -DSTDC_HEADERS If you have ANSI C headers and
|
|---|
| 12581 | # libraries.
|
|---|
| 12582 | # -DPOSIX If you have POSIX.1 headers and
|
|---|
| 12583 | # libraries.
|
|---|
| 12584 | # -DBSD42 If you have sys/dir.h (unless
|
|---|
| 12585 | # you use -DPOSIX), sys/file.h,
|
|---|
| 12586 | # and st_blocks in `struct stat'.
|
|---|
| 12587 | # -DUSG If you have System V/ANSI C
|
|---|
| 12588 | # string and memory functions
|
|---|
| 12589 | # and headers, sys/sysmacros.h,
|
|---|
| 12590 | # fcntl.h, getcwd, no valloc,
|
|---|
| 12591 | # and ndir.h (unless
|
|---|
| 12592 | # you use -DDIRENT).
|
|---|
| 12593 | # -DNO_MEMORY_H If USG or STDC_HEADERS but do not
|
|---|
| 12594 | # include memory.h.
|
|---|
| 12595 | # -DDIRENT If USG and you have dirent.h
|
|---|
| 12596 | # instead of ndir.h.
|
|---|
| 12597 | # -DSIGTYPE=int If your signal handlers
|
|---|
| 12598 | # return int, not void.
|
|---|
| 12599 | # -DNO_MTIO If you lack sys/mtio.h
|
|---|
| 12600 | # (magtape ioctls).
|
|---|
| 12601 | # -DNO_REMOTE If you do not have a remote shell
|
|---|
| 12602 | # or rexec.
|
|---|
| 12603 | # -DUSE_REXEC To use rexec for remote tape
|
|---|
| 12604 | # operations instead of
|
|---|
| 12605 | # forking rsh or remsh.
|
|---|
| 12606 | # -DVPRINTF_MISSING If you lack vprintf function
|
|---|
| 12607 | # (but have _doprnt).
|
|---|
| 12608 | # -DDOPRNT_MISSING If you lack _doprnt function.
|
|---|
| 12609 | # Also need to define
|
|---|
| 12610 | # -DVPRINTF_MISSING.
|
|---|
| 12611 | # -DFTIME_MISSING If you lack ftime system call.
|
|---|
| 12612 | # -DSTRSTR_MISSING If you lack strstr function.
|
|---|
| 12613 | # -DVALLOC_MISSING If you lack valloc function.
|
|---|
| 12614 | # -DMKDIR_MISSING If you lack mkdir and
|
|---|
| 12615 | # rmdir system calls.
|
|---|
| 12616 | # -DRENAME_MISSING If you lack rename system call.
|
|---|
| 12617 | # -DFTRUNCATE_MISSING If you lack ftruncate
|
|---|
| 12618 | # system call.
|
|---|
| 12619 | # -DV7 On Version 7 Unix (not
|
|---|
| 12620 | # tested in a long time).
|
|---|
| 12621 | # -DEMUL_OPEN3 If you lack a 3-argument version
|
|---|
| 12622 | # of open, and want to emulate it
|
|---|
| 12623 | # with system calls you do have.
|
|---|
| 12624 | # -DNO_OPEN3 If you lack the 3-argument open
|
|---|
| 12625 | # and want to disable the tar -k
|
|---|
| 12626 | # option instead of emulating open.
|
|---|
| 12627 | # -DXENIX If you have sys/inode.h
|
|---|
| 12628 | # and need it 94 to be included.
|
|---|
| 12629 |
|
|---|
| 12630 | DEFS = -DSIGTYPE=int -DDIRENT -DSTRSTR_MISSING \
|
|---|
| 12631 | -DVPRINTF_MISSING -DBSD42
|
|---|
| 12632 | # Set this to rtapelib.o unless you defined NO_REMOTE,
|
|---|
| 12633 | # in which case make it empty.
|
|---|
| 12634 | RTAPELIB = rtapelib.o
|
|---|
| 12635 | LIBS =
|
|---|
| 12636 | DEF_AR_FILE = /dev/rmt8
|
|---|
| 12637 | DEFBLOCKING = 20
|
|---|
| 12638 |
|
|---|
| 12639 | @group
|
|---|
| 12640 | CDEBUG = -g
|
|---|
| 12641 | CFLAGS = $(CDEBUG) -I. -I$(srcdir) $(DEFS) \
|
|---|
| 12642 | -DDEF_AR_FILE=\"$(DEF_AR_FILE)\" \
|
|---|
| 12643 | -DDEFBLOCKING=$(DEFBLOCKING)
|
|---|
| 12644 | LDFLAGS = -g
|
|---|
| 12645 | @end group
|
|---|
| 12646 |
|
|---|
| 12647 | @group
|
|---|
| 12648 | prefix = /usr/local
|
|---|
| 12649 | # Prefix for each installed program,
|
|---|
| 12650 | # normally empty or `g'.
|
|---|
| 12651 | binprefix =
|
|---|
| 12652 |
|
|---|
| 12653 | # The directory to install tar in.
|
|---|
| 12654 | bindir = $(prefix)/bin
|
|---|
| 12655 |
|
|---|
| 12656 | # The directory to install the info files in.
|
|---|
| 12657 | infodir = $(prefix)/info
|
|---|
| 12658 | @end group
|
|---|
| 12659 |
|
|---|
| 12660 | #### End of system configuration section. ####
|
|---|
| 12661 |
|
|---|
| 12662 | @group
|
|---|
| 12663 | SRCS_C = tar.c create.c extract.c buffer.c \
|
|---|
| 12664 | getoldopt.c update.c gnu.c mangle.c \
|
|---|
| 12665 | version.c list.c names.c diffarch.c \
|
|---|
| 12666 | port.c wildmat.c getopt.c getopt1.c \
|
|---|
| 12667 | regex.c
|
|---|
| 12668 | SRCS_Y = getdate.y
|
|---|
| 12669 | SRCS = $(SRCS_C) $(SRCS_Y)
|
|---|
| 12670 | OBJS = $(SRCS_C:.c=.o) $(SRCS_Y:.y=.o) $(RTAPELIB)
|
|---|
| 12671 | @end group
|
|---|
| 12672 | @group
|
|---|
| 12673 | AUX = README COPYING ChangeLog Makefile.in \
|
|---|
| 12674 | makefile.pc configure configure.in \
|
|---|
| 12675 | tar.texinfo tar.info* texinfo.tex \
|
|---|
| 12676 | tar.h port.h open3.h getopt.h regex.h \
|
|---|
| 12677 | rmt.h rmt.c rtapelib.c alloca.c \
|
|---|
| 12678 | msd_dir.h msd_dir.c tcexparg.c \
|
|---|
| 12679 | level-0 level-1 backup-specs testpad.c
|
|---|
| 12680 | @end group
|
|---|
| 12681 |
|
|---|
| 12682 | .PHONY: all
|
|---|
| 12683 | all: tar rmt tar.info
|
|---|
| 12684 |
|
|---|
| 12685 | @group
|
|---|
| 12686 | tar: $(OBJS)
|
|---|
| 12687 | $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS)
|
|---|
| 12688 | @end group
|
|---|
| 12689 |
|
|---|
| 12690 | @group
|
|---|
| 12691 | rmt: rmt.c
|
|---|
| 12692 | $(CC) $(CFLAGS) $(LDFLAGS) -o $@@ rmt.c
|
|---|
| 12693 | @end group
|
|---|
| 12694 |
|
|---|
| 12695 | @group
|
|---|
| 12696 | tar.info: tar.texinfo
|
|---|
| 12697 | makeinfo tar.texinfo
|
|---|
| 12698 | @end group
|
|---|
| 12699 |
|
|---|
| 12700 | @group
|
|---|
| 12701 | .PHONY: install
|
|---|
| 12702 | install: all
|
|---|
| 12703 | $(INSTALL) tar $(bindir)/$(binprefix)tar
|
|---|
| 12704 | -test ! -f rmt || $(INSTALL) rmt /etc/rmt
|
|---|
| 12705 | $(INSTALLDATA) $(srcdir)/tar.info* $(infodir)
|
|---|
| 12706 | @end group
|
|---|
| 12707 |
|
|---|
| 12708 | @group
|
|---|
| 12709 | $(OBJS): tar.h port.h testpad.h
|
|---|
| 12710 | regex.o buffer.o tar.o: regex.h
|
|---|
| 12711 | # getdate.y has 8 shift/reduce conflicts.
|
|---|
| 12712 | @end group
|
|---|
| 12713 |
|
|---|
| 12714 | @group
|
|---|
| 12715 | testpad.h: testpad
|
|---|
| 12716 | ./testpad
|
|---|
| 12717 | @end group
|
|---|
| 12718 |
|
|---|
| 12719 | @group
|
|---|
| 12720 | testpad: testpad.o
|
|---|
| 12721 | $(CC) -o $@@ testpad.o
|
|---|
| 12722 | @end group
|
|---|
| 12723 |
|
|---|
| 12724 | @group
|
|---|
| 12725 | TAGS: $(SRCS)
|
|---|
| 12726 | etags $(SRCS)
|
|---|
| 12727 | @end group
|
|---|
| 12728 |
|
|---|
| 12729 | @group
|
|---|
| 12730 | .PHONY: clean
|
|---|
| 12731 | clean:
|
|---|
| 12732 | rm -f *.o tar rmt testpad testpad.h core
|
|---|
| 12733 | @end group
|
|---|
| 12734 |
|
|---|
| 12735 | @group
|
|---|
| 12736 | .PHONY: distclean
|
|---|
| 12737 | distclean: clean
|
|---|
| 12738 | rm -f TAGS Makefile config.status
|
|---|
| 12739 | @end group
|
|---|
| 12740 |
|
|---|
| 12741 | @group
|
|---|
| 12742 | .PHONY: realclean
|
|---|
| 12743 | realclean: distclean
|
|---|
| 12744 | rm -f tar.info*
|
|---|
| 12745 | @end group
|
|---|
| 12746 |
|
|---|
| 12747 | @group
|
|---|
| 12748 | .PHONY: shar
|
|---|
| 12749 | shar: $(SRCS) $(AUX)
|
|---|
| 12750 | shar $(SRCS) $(AUX) | compress \
|
|---|
| 12751 | > tar-`sed -e '/version_string/!d' \
|
|---|
| 12752 | -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
|
|---|
| 12753 | -e q
|
|---|
| 12754 | version.c`.shar.Z
|
|---|
| 12755 | @end group
|
|---|
| 12756 |
|
|---|
| 12757 | @group
|
|---|
| 12758 | .PHONY: dist
|
|---|
| 12759 | dist: $(SRCS) $(AUX)
|
|---|
| 12760 | echo tar-`sed \
|
|---|
| 12761 | -e '/version_string/!d' \
|
|---|
| 12762 | -e 's/[^0-9.]*\([0-9.]*\).*/\1/' \
|
|---|
| 12763 | -e q
|
|---|
| 12764 | version.c` > .fname
|
|---|
| 12765 | -rm -rf `cat .fname`
|
|---|
| 12766 | mkdir `cat .fname`
|
|---|
| 12767 | ln $(SRCS) $(AUX) `cat .fname`
|
|---|
| 12768 | tar chZf `cat .fname`.tar.Z `cat .fname`
|
|---|
| 12769 | -rm -rf `cat .fname` .fname
|
|---|
| 12770 | @end group
|
|---|
| 12771 |
|
|---|
| 12772 | @group
|
|---|
| 12773 | tar.zoo: $(SRCS) $(AUX)
|
|---|
| 12774 | -rm -rf tmp.dir
|
|---|
| 12775 | -mkdir tmp.dir
|
|---|
| 12776 | -rm tar.zoo
|
|---|
| 12777 | for X in $(SRCS) $(AUX) ; do \
|
|---|
| 12778 | echo $$X ; \
|
|---|
| 12779 | sed 's/$$/^M/' $$X \
|
|---|
| 12780 | > tmp.dir/$$X ; done
|
|---|
| 12781 | cd tmp.dir ; zoo aM ../tar.zoo *
|
|---|
| 12782 | -rm -rf tmp.dir
|
|---|
| 12783 | @end group
|
|---|
| 12784 | @end example
|
|---|
| 12785 |
|
|---|
| 12786 | @node GNU Free Documentation License, Concept Index, Complex Makefile, Top
|
|---|
| 12787 | @appendixsec GNU Free Documentation License
|
|---|
| 12788 | @cindex FDL, GNU Free Documentation License
|
|---|
| 12789 | @include fdl.texi
|
|---|
| 12790 |
|
|---|
| 12791 | @node Concept Index, Name Index, GNU Free Documentation License, Top
|
|---|
| 12792 | @unnumbered Index of Concepts
|
|---|
| 12793 |
|
|---|
| 12794 | @printindex cp
|
|---|
| 12795 |
|
|---|
| 12796 | @node Name Index, , Concept Index, Top
|
|---|
| 12797 | @unnumbered Index of Functions, Variables, & Directives
|
|---|
| 12798 |
|
|---|
| 12799 | @printindex fn
|
|---|
| 12800 |
|
|---|
| 12801 | @bye
|
|---|