1This is Info file make.info, produced by Makeinfo-1.54 from the input 2file ./make.texinfo. 3 4 This file documents the GNU Make utility, which determines 5automatically which pieces of a large program need to be recompiled, 6and issues the commands to recompile them. 7 8 This is Edition 0.45, last updated 11 May 1994, of `The GNU Make 9Manual', for `make', Version 3.71 Beta. 10 11 Copyright (C) 1988, '89, '90, '91, '92, '93, '94 Free Software 12Foundation, Inc. 13 14 Permission is granted to make and distribute verbatim copies of this 15manual provided the copyright notice and this permission notice are 16preserved on all copies. 17 18 Permission is granted to copy and distribute modified versions of 19this manual under the conditions for verbatim copying, provided that 20the entire resulting derived work is distributed under the terms of a 21permission notice identical to this one. 22 23 Permission is granted to copy and distribute translations of this 24manual into another language, under the above conditions for modified 25versions, except that this permission notice may be stated in a 26translation approved by the Free Software Foundation. 27 28 29File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Commands 30 31Errors in Commands 32================== 33 34 After each shell command returns, `make' looks at its exit status. 35If the command completed successfully, the next command line is executed 36in a new shell; after the last command line is finished, the rule is 37finished. 38 39 If there is an error (the exit status is nonzero), `make' gives up on 40the current rule, and perhaps on all rules. 41 42 Sometimes the failure of a certain command does not indicate a 43problem. For example, you may use the `mkdir' command to ensure that a 44directory exists. If the directory already exists, `mkdir' will report 45an error, but you probably want `make' to continue regardless. 46 47 To ignore errors in a command line, write a `-' at the beginning of 48the line's text (after the initial tab). The `-' is discarded before 49the command is passed to the shell for execution. 50 51 For example, 52 53 clean: 54 -rm -f *.o 55 56This causes `rm' to continue even if it is unable to remove a file. 57 58 When you run `make' with the `-i' or `--ignore-errors' flag, errors 59are ignored in all commands of all rules. A rule in the makefile for 60the special target `.IGNORE' has the same effect. These ways of 61ignoring errors are obsolete because `-' is more flexible. 62 63 When errors are to be ignored, because of either a `-' or the `-i' 64flag, `make' treats an error return just like success, except that it 65prints out a message that tells you the status code the command exited 66with, and says that the error has been ignored. 67 68 When an error happens that `make' has not been told to ignore, it 69implies that the current target cannot be correctly remade, and neither 70can any other that depends on it either directly or indirectly. No 71further commands will be executed for these targets, since their 72preconditions have not been achieved. 73 74 Normally `make' gives up immediately in this circumstance, returning 75a nonzero status. However, if the `-k' or `--keep-going' flag is 76specified, `make' continues to consider the other dependencies of the 77pending targets, remaking them if necessary, before it gives up and 78returns nonzero status. For example, after an error in compiling one 79object file, `make -k' will continue compiling other object files even 80though it already knows that linking them will be impossible. *Note 81Summary of Options: Options Summary. 82 83 The usual behavior assumes that your purpose is to get the specified 84targets up to date; once `make' learns that this is impossible, it 85might as well report the failure immediately. The `-k' option says 86that the real purpose is to test as many of the changes made in the 87program as possible, perhaps to find several independent problems so 88that you can correct them all before the next attempt to compile. This 89is why Emacs' `compile' command passes the `-k' flag by default. 90 91 92File: make.info, Node: Interrupts, Next: Recursion, Prev: Errors, Up: Commands 93 94Interrupting or Killing `make' 95============================== 96 97 If `make' gets a fatal signal while a command is executing, it may 98delete the target file that the command was supposed to update. This is 99done if the target file's last-modification time has changed since 100`make' first checked it. 101 102 The purpose of deleting the target is to make sure that it is remade 103from scratch when `make' is next run. Why is this? Suppose you type 104`Ctrl-c' while a compiler is running, and it has begun to write an 105object file `foo.o'. The `Ctrl-c' kills the compiler, resulting in an 106incomplete file whose last-modification time is newer than the source 107file `foo.c'. But `make' also receives the `Ctrl-c' signal and deletes 108this incomplete file. If `make' did not do this, the next invocation 109of `make' would think that `foo.o' did not require updating--resulting 110in a strange error message from the linker when it tries to link an 111object file half of which is missing. 112 113 You can prevent the deletion of a target file in this way by making 114the special target `.PRECIOUS' depend on it. Before remaking a target, 115`make' checks to see whether it appears on the dependencies of 116`.PRECIOUS', and thereby decides whether the target should be deleted 117if a signal happens. Some reasons why you might do this are that the 118target is updated in some atomic fashion, or exists only to record a 119modification-time (its contents do not matter), or must exist at all 120times to prevent other sorts of trouble. 121 122 123File: make.info, Node: Recursion, Next: Sequences, Prev: Interrupts, Up: Commands 124 125Recursive Use of `make' 126======================= 127 128 Recursive use of `make' means using `make' as a command in a 129makefile. This technique is useful when you want separate makefiles for 130various subsystems that compose a larger system. For example, suppose 131you have a subdirectory `subdir' which has its own makefile, and you 132would like the containing directory's makefile to run `make' on the 133subdirectory. You can do it by writing this: 134 135 subsystem: 136 cd subdir; $(MAKE) 137 138or, equivalently, this (*note Summary of Options: Options Summary.): 139 140 subsystem: 141 $(MAKE) -C subdir 142 143 You can write recursive `make' commands just by copying this example, 144but there are many things to know about how they work and why, and about 145how the sub-`make' relates to the top-level `make'. 146 147* Menu: 148 149* MAKE Variable:: The special effects of using `$(MAKE)'. 150* Variables/Recursion:: How to communicate variables to a sub-`make'. 151* Options/Recursion:: How to communicate options to a sub-`make'. 152* -w Option:: How the `-w' or `--print-directory' option 153 helps debug use of recursive `make' commands. 154 155 156File: make.info, Node: MAKE Variable, Next: Variables/Recursion, Up: Recursion 157 158How the `MAKE' Variable Works 159----------------------------- 160 161 Recursive `make' commands should always use the variable `MAKE', not 162the explicit command name `make', as shown here: 163 164 subsystem: 165 cd subdir; $(MAKE) 166 167 The value of this variable is the file name with which `make' was 168invoked. If this file name was `/bin/make', then the command executed 169is `cd subdir; /bin/make'. If you use a special version of `make' to 170run the top-level makefile, the same special version will be executed 171for recursive invocations. 172 173 Also, any arguments that define variable values are added to `MAKE', 174so the sub-`make' gets them too. Thus, if you do `make CFLAGS=-O', so 175that all C compilations will be optimized, the sub-`make' is run with 176`cd subdir; /bin/make CFLAGS=-O'. 177 178 The `MAKE' variable actually just refers to two other variables 179which contain these special values. In fact, `MAKE' is always defined 180as `$(MAKE_COMMAND) $(MAKEOVERRIDES)'. The variable `MAKE_COMMAND' is 181the file name with which `make' was invoked (such as `/bin/make', 182above). The variable `MAKEOVERRIDES' contains definitions for the 183variables defined on the command line; in the above example, its value 184is `CFLAGS=-O'. If you *do not* want these variable definitions done 185in all recursive `make' invocations, you can redefine the 186`MAKEOVERRIDES' variable to remove them. You do this in any of the 187normal ways for defining variables: in a makefile (*note Setting 188Variables: Setting.); on the command line with an argument like 189`MAKEOVERRIDES=' (*note Overriding Variables: Overriding.); or with an 190environment variable (*note Variables from the Environment: 191Environment.). 192 193 As a special feature, using the variable `MAKE' in the commands of a 194rule alters the effects of the `-t' (`--touch'), `-n' (`--just-print'), 195or `-q' (`--question') option. Using the `MAKE' variable has the same 196effect as using a `+' character at the beginning of the command line. 197*Note Instead of Executing the Commands: Instead of Execution. 198 199 Consider the command `make -t' in the above example. (The `-t' 200option marks targets as up to date without actually running any 201commands; see *Note Instead of Execution::.) Following the usual 202definition of `-t', a `make -t' command in the example would create a 203file named `subsystem' and do nothing else. What you really want it to 204do is run `cd subdir; make -t'; but that would require executing the 205command, and `-t' says not to execute commands. 206 207 The special feature makes this do what you want: whenever a command 208line of a rule contains the variable `MAKE', the flags `-t', `-n' and 209`-q' do not apply to that line. Command lines containing `MAKE' are 210executed normally despite the presence of a flag that causes most 211commands not to be run. The usual `MAKEFLAGS' mechanism passes the 212flags to the sub-`make' (*note Communicating Options to a Sub-`make': 213Options/Recursion.), so your request to touch the files, or print the 214commands, is propagated to the subsystem. 215 216 217File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MAKE Variable, Up: Recursion 218 219Communicating Variables to a Sub-`make' 220--------------------------------------- 221 222 Variable values of the top-level `make' can be passed to the 223sub-`make' through the environment by explicit request. These 224variables are defined in the sub-`make' as defaults, but do not 225override what is specified in the sub-`make''s makefile unless you use 226the `-e' switch (*note Summary of Options: Options Summary.). 227 228 To pass down, or "export", a variable, `make' adds the variable and 229its value to the environment for running each command. The sub-`make', 230in turn, uses the environment to initialize its table of variable 231values. *Note Variables from the Environment: Environment. 232 233 Except by explicit request, `make' exports a variable only if it is 234either defined in the environment initially or set on the command line, 235and if its name consists only of letters, numbers, and underscores. 236Some shells cannot cope with environment variable names consisting of 237characters other than letters, numbers, and underscores. 238 239 The special variables `SHELL' and `MAKEFLAGS' are always exported 240(unless you unexport them). `MAKEFILES' is exported if you set it to 241anything. 242 243 Variables are *not* normally passed down if they were created by 244default by `make' (*note Variables Used by Implicit Rules: Implicit 245Variables.). The sub-`make' will define these for itself. 246 247 If you want to export specific variables to a sub-`make', use the 248`export' directive, like this: 249 250 export VARIABLE ... 251 252If you want to *prevent* a variable from being exported, use the 253`unexport' directive, like this: 254 255 unexport VARIABLE ... 256 257As a convenience, you can define a variable and export it at the same 258time by doing: 259 260 export VARIABLE = value 261 262has the same result as: 263 264 VARIABLE = value 265 export VARIABLE 266 267and 268 269 export VARIABLE := value 270 271has the same result as: 272 273 VARIABLE := value 274 export VARIABLE 275 276 Likewise, 277 278 export VARIABLE += value 279 280is just like: 281 282 VARIABLE += value 283 export VARIABLE 284 285*Note Appending More Text to Variables: Appending. 286 287 You may notice that the `export' and `unexport' directives work in 288`make' in the same way they work in the shell, `sh'. 289 290 If you want all variables to be exported by default, you can use 291`export' by itself: 292 293 export 294 295This tells `make' that variables which are not explicitly mentioned in 296an `export' or `unexport' directive should be exported. Any variable 297given in an `unexport' directive will still *not* be exported. If you 298use `export' by itself to export variables by default, variables whose 299names contain characters other than alphanumerics and underscores will 300not be exported unless specifically mentioned in an `export' directive. 301 302 The behavior elicited by an `export' directive by itself was the 303default in older versions of GNU `make'. If your makefiles depend on 304this behavior and you want to be compatible with old versions of 305`make', you can write a rule for the special target 306`.EXPORT_ALL_VARIABLES' instead of using the `export' directive. This 307will be ignored by old `make's, while the `export' directive will cause 308a syntax error. 309 310 Likewise, you can use `unexport' by itself to tell `make' *not* to 311export variables by default. Since this is the default behavior, you 312would only need to do this if `export' had been used by itself earlier 313(in an included makefile, perhaps). You *cannot* use `export' and 314`unexport' by themselves to have variables exported for some commands 315and not for others. The last `export' or `unexport' directive that 316appears by itself determines the behavior for the entire run of `make'. 317 318 As a special feature, the variable `MAKELEVEL' is changed when it is 319passed down from level to level. This variable's value is a string 320which is the depth of the level as a decimal number. The value is `0' 321for the top-level `make'; `1' for a sub-`make', `2' for a 322sub-sub-`make', and so on. The incrementation happens when `make' sets 323up the environment for a command. 324 325 The main use of `MAKELEVEL' is to test it in a conditional directive 326(*note Conditional Parts of Makefiles: Conditionals.); this way you can 327write a makefile that behaves one way if run recursively and another 328way if run directly by you. 329 330 You can use the variable `MAKEFILES' to cause all sub-`make' 331commands to use additional makefiles. The value of `MAKEFILES' is a 332whitespace-separated list of file names. This variable, if defined in 333the outer-level makefile, is passed down through the environment; then 334it serves as a list of extra makefiles for the sub-`make' to read 335before the usual or specified ones. *Note The Variable `MAKEFILES': 336MAKEFILES Variable. 337 338 339File: make.info, Node: Options/Recursion, Next: -w Option, Prev: Variables/Recursion, Up: Recursion 340 341Communicating Options to a Sub-`make' 342------------------------------------- 343 344 Flags such as `-s' and `-k' are passed automatically to the 345sub-`make' through the variable `MAKEFLAGS'. This variable is set up 346automatically by `make' to contain the flag letters that `make' 347received. Thus, if you do `make -ks' then `MAKEFLAGS' gets the value 348`ks'. 349 350 As a consequence, every sub-`make' gets a value for `MAKEFLAGS' in 351its environment. In response, it takes the flags from that value and 352processes them as if they had been given as arguments. *Note Summary 353of Options: Options Summary. 354 355 The options `-C', `-f', `-I', `-o', and `-W' are not put into 356`MAKEFLAGS'; these options are not passed down. 357 358 The `-j' option is a special case (*note Parallel Execution: 359Parallel.). If you set it to some numeric value, `-j 1' is always put 360into `MAKEFLAGS' instead of the value you specified. This is because if 361the `-j' option were passed down to sub-`make's, you would get many 362more jobs running in parallel than you asked for. If you give `-j' 363with no numeric argument, meaning to run as many jobs as possible in 364parallel, this is passed down, since multiple infinities are no more 365than one. 366 367 If you do not want to pass the other flags down, you must change the 368value of `MAKEFLAGS', like this: 369 370 MAKEFLAGS= 371 subsystem: 372 cd subdir; $(MAKE) 373 374 or like this: 375 376 subsystem: 377 cd subdir; $(MAKE) MAKEFLAGS= 378 379 A similar variable `MFLAGS' exists also, for historical 380compatibility. It has the same value as `MAKEFLAGS' except that it 381always begins with a hyphen unless it is empty (`MAKEFLAGS' begins with 382a hyphen only when it begins with an option that has no single-letter 383version, such as `--warn-undefined-variables'). `MFLAGS' was 384traditionally used explicitly in the recursive `make' command, like 385this: 386 387 subsystem: 388 cd subdir; $(MAKE) $(MFLAGS) 389 390but now `MAKEFLAGS' makes this usage redundant. If you want your 391makefiles to be compatible with old `make' programs, use this 392technique; it will work fine with more modern `make' versions too. 393 394 The `MAKEFLAGS' variable can also be useful if you want to have 395certain options, such as `-k' (*note Summary of Options: Options 396Summary.), set each time you run `make'. You simply put a value for 397`MAKEFLAGS' in your environment. You can also set `MAKEFLAGS' in a 398makefile, to specify additional flags that should also be in effect for 399that makefile. (Note that you cannot use `MFLAGS' this way. That 400variable is set only for compatibility; `make' does not interpret a 401value you set for it in any way.) 402 403 When `make' interprets the value of `MAKEFLAGS' (either from the 404environment or from a makefile), it first prepends a hyphen if the value 405does not already begin with one. Then it chops the value into words 406separated by blanks, and parses these words as if they were options 407given on the command line (except that `-C', `-f', `-h', `-o', `-W', 408and their long-named versions are ignored; and there is no error for an 409invalid option). 410 411 If you do put `MAKEFLAGS' in your environment, you should be sure not 412to include any options that will drastically affect the actions of 413`make' and undermine the purpose of makefiles and of `make' itself. 414For instance, the `-t', `-n', and `-q' options, if put in one of these 415variables, could have disastrous consequences and would certainly have 416at least surprising and probably annoying effects. 417 418 419File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion 420 421The `--print-directory' Option 422------------------------------ 423 424 If you use several levels of recursive `make' invocations, the `-w' 425or `--print-directory' option can make the output a lot easier to 426understand by showing each directory as `make' starts processing it and 427as `make' finishes processing it. For example, if `make -w' is run in 428the directory `/u/gnu/make', `make' will print a line of the form: 429 430 make: Entering directory `/u/gnu/make'. 431 432before doing anything else, and a line of the form: 433 434 make: Leaving directory `/u/gnu/make'. 435 436when processing is completed. 437 438 Normally, you do not need to specify this option because `make' does 439it for you: `-w' is turned on automatically when you use the `-C' 440option, and in sub-`make's. `make' will not automatically turn on `-w' 441if you also use `-s', which says to be silent, or if you use 442`--no-print-directory' to explicitly disable it. 443 444 445File: make.info, Node: Sequences, Next: Empty Commands, Prev: Recursion, Up: Commands 446 447Defining Canned Command Sequences 448================================= 449 450 When the same sequence of commands is useful in making various 451targets, you can define it as a canned sequence with the `define' 452directive, and refer to the canned sequence from the rules for those 453targets. The canned sequence is actually a variable, so the name must 454not conflict with other variable names. 455 456 Here is an example of defining a canned sequence of commands: 457 458 define run-yacc 459 yacc $(firstword $^) 460 mv y.tab.c $@ 461 endef 462 463Here `run-yacc' is the name of the variable being defined; `endef' 464marks the end of the definition; the lines in between are the commands. 465The `define' directive does not expand variable references and 466function calls in the canned sequence; the `$' characters, parentheses, 467variable names, and so on, all become part of the value of the variable 468you are defining. *Note Defining Variables Verbatim: Defining, for a 469complete explanation of `define'. 470 471 The first command in this example runs Yacc on the first dependency 472of whichever rule uses the canned sequence. The output file from Yacc 473is always named `y.tab.c'. The second command moves the output to the 474rule's target file name. 475 476 To use the canned sequence, substitute the variable into the 477commands of a rule. You can substitute it like any other variable 478(*note Basics of Variable References: Reference.). Because variables 479defined by `define' are recursively expanded variables, all the 480variable references you wrote inside the `define' are expanded now. 481For example: 482 483 foo.c : foo.y 484 $(run-yacc) 485 486`foo.y' will be substituted for the variable `$^' when it occurs in 487`run-yacc''s value, and `foo.c' for `$@'. 488 489 This is a realistic example, but this particular one is not needed in 490practice because `make' has an implicit rule to figure out these 491commands based on the file names involved (*note Using Implicit Rules: 492Implicit Rules.). 493 494 In command execution, each line of a canned sequence is treated just 495as if the line appeared on its own in the rule, preceded by a tab. In 496particular, `make' invokes a separate subshell for each line. You can 497use the special prefix characters that affect command lines (`@', `-', 498and `+') on each line of a canned sequence. *Note Writing the Commands 499in Rules: Commands. For example, using this canned sequence: 500 501 define frobnicate 502 @echo "frobnicating target $@" 503 frob-step-1 $< -o $@-step-1 504 frob-step-2 $@-step-1 -o $@ 505 endef 506 507`make' will not echo the first line, the `echo' command. But it *will* 508echo the following two command lines. 509 510 On the other hand, prefix characters on the command line that refers 511to a canned sequence apply to every line in the sequence. So the rule: 512 513 frob.out: frob.in 514 @$(frobnicate) 515 516does not echo *any* commands. (*Note Command Echoing: Echoing, for a 517full explanation of `@'.) 518 519 520File: make.info, Node: Empty Commands, Prev: Sequences, Up: Commands 521 522Using Empty Commands 523==================== 524 525 It is sometimes useful to define commands which do nothing. This is 526done simply by giving a command that consists of nothing but 527whitespace. For example: 528 529 target: ; 530 531defines an empty command string for `target'. You could also use a 532line beginning with a tab character to define an empty command string, 533but this would be confusing because such a line looks empty. 534 535 You may be wondering why you would want to define a command string 536that does nothing. The only reason this is useful is to prevent a 537target from getting implicit commands (from implicit rules or the 538`.DEFAULT' special target; *note Implicit Rules::. and *note Defining 539Last-Resort Default Rules: Last Resort.). 540 541 You may be inclined to define empty command strings for targets that 542are not actual files, but only exist so that their dependencies can be 543remade. However, this is not the best way to do that, because the 544dependencies may not be remade properly if the target file actually 545does exist. *Note Phony Targets: Phony Targets, for a better way to do 546this. 547 548 549File: make.info, Node: Using Variables, Next: Conditionals, Prev: Commands, Up: Top 550 551How to Use Variables 552******************** 553 554 A "variable" is a name defined in a makefile to represent a string 555of text, called the variable's "value". These values are substituted 556by explicit request into targets, dependencies, commands, and other 557parts of the makefile. (In some other versions of `make', variables 558are called "macros".) 559 560 Variables and functions in all parts of a makefile are expanded when 561read, except for the shell commands in rules, the right-hand sides of 562variable definitions using `=', and the bodies of variable definitions 563using the `define' directive. 564 565 Variables can represent lists of file names, options to pass to 566compilers, programs to run, directories to look in for source files, 567directories to write output in, or anything else you can imagine. 568 569 A variable name may be any sequence of characters not containing `:', 570`#', `=', or leading or trailing whitespace. However, variable names 571containing characters other than letters, numbers, and underscores 572should be avoided, as they may be given special meanings in the future, 573and with some shells they cannot be passed through the environment to a 574sub-`make' (*note Communicating Variables to a Sub-`make': 575Variables/Recursion.). 576 577 Variable names are case-sensitive. The names `foo', `FOO', and 578`Foo' all refer to different variables. 579 580 It is traditional to use upper case letters in variable names, but we 581recommend using lower case letters for variable names that serve 582internal purposes in the makefile, and reserving upper case for 583parameters that control implicit rules or for parameters that the user 584should override with command options (*note Overriding Variables: 585Overriding.). 586 587 A few variables have names that are a single punctuation character or 588just a few characters. These are the "automatic variables", and they 589have particular specialized uses. *Note Automatic Variables: Automatic. 590 591* Menu: 592 593* Reference:: How to use the value of a variable. 594* Flavors:: Variables come in two flavors. 595* Advanced:: Advanced features for referencing a variable. 596* Values:: All the ways variables get their values. 597* Setting:: How to set a variable in the makefile. 598* Appending:: How to append more text to the old value 599 of a variable. 600* Override Directive:: How to set a variable in the makefile even if 601 the user has set it with a command argument. 602* Defining:: An alternate way to set a variable 603 to a verbatim string. 604* Environment:: Variable values can come from the environment. 605* Automatic:: Some special variables have predefined 606 meanings for use with implicit rules. 607 608 609File: make.info, Node: Reference, Next: Flavors, Up: Using Variables 610 611Basics of Variable References 612============================= 613 614 To substitute a variable's value, write a dollar sign followed by 615the name of the variable in parentheses or braces: either `$(foo)' or 616`${foo}' is a valid reference to the variable `foo'. This special 617significance of `$' is why you must write `$$' to have the effect of a 618single dollar sign in a file name or command. 619 620 Variable references can be used in any context: targets, 621dependencies, commands, most directives, and new variable values. Here 622is an example of a common case, where a variable holds the names of all 623the object files in a program: 624 625 objects = program.o foo.o utils.o 626 program : $(objects) 627 cc -o program $(objects) 628 629 $(objects) : defs.h 630 631 Variable references work by strict textual substitution. Thus, the 632rule 633 634 foo = c 635 prog.o : prog.$(foo) 636 $(foo)$(foo) -$(foo) prog.$(foo) 637 638could be used to compile a C program `prog.c'. Since spaces before the 639variable value are ignored in variable assignments, the value of `foo' 640is precisely `c'. (Don't actually write your makefiles this way!) 641 642 A dollar sign followed by a character other than a dollar sign, 643open-parenthesis or open-brace treats that single character as the 644variable name. Thus, you could reference the variable `x' with `$x'. 645However, this practice is strongly discouraged, except in the case of 646the automatic variables (*note Automatic Variables: Automatic.). 647 648 649File: make.info, Node: Flavors, Next: Advanced, Prev: Reference, Up: Using Variables 650 651The Two Flavors of Variables 652============================ 653 654 There are two ways that a variable in GNU `make' can have a value; 655we call them the two "flavors" of variables. The two flavors are 656distinguished in how they are defined and in what they do when expanded. 657 658 The first flavor of variable is a "recursively expanded" variable. 659Variables of this sort are defined by lines using `=' (*note Setting 660Variables: Setting.) or by the `define' directive (*note Defining 661Variables Verbatim: Defining.). The value you specify is installed 662verbatim; if it contains references to other variables, these 663references are expanded whenever this variable is substituted (in the 664course of expanding some other string). When this happens, it is 665called "recursive expansion". 666 667 For example, 668 669 foo = $(bar) 670 bar = $(ugh) 671 ugh = Huh? 672 673 all:;echo $(foo) 674 675will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to 676`$(ugh)' which finally expands to `Huh?'. 677 678 This flavor of variable is the only sort supported by other versions 679of `make'. It has its advantages and its disadvantages. An advantage 680(most would say) is that: 681 682 CFLAGS = $(include_dirs) -O 683 include_dirs = -Ifoo -Ibar 684 685will do what was intended: when `CFLAGS' is expanded in a command, it 686will expand to `-Ifoo -Ibar -O'. A major disadvantage is that you 687cannot append something on the end of a variable, as in 688 689 CFLAGS = $(CFLAGS) -O 690 691because it will cause an infinite loop in the variable expansion. 692(Actually `make' detects the infinite loop and reports an error.) 693 694 Another disadvantage is that any functions (*note Functions for 695Transforming Text: Functions.) referenced in the definition will be 696executed every time the variable is expanded. This makes `make' run 697slower; worse, it causes the `wildcard' and `shell' functions to give 698unpredictable results because you cannot easily control when they are 699called, or even how many times. 700 701 To avoid all the problems and inconveniences of recursively expanded 702variables, there is another flavor: simply expanded variables. 703 704 "Simply expanded variables" are defined by lines using `:=' (*note 705Setting Variables: Setting.). The value of a simply expanded variable 706is scanned once and for all, expanding any references to other 707variables and functions, when the variable is defined. The actual 708value of the simply expanded variable is the result of expanding the 709text that you write. It does not contain any references to other 710variables; it contains their values *as of the time this variable was 711defined*. Therefore, 712 713 x := foo 714 y := $(x) bar 715 x := later 716 717is equivalent to 718 719 y := foo bar 720 x := later 721 722 When a simply expanded variable is referenced, its value is 723substituted verbatim. 724 725 Here is a somewhat more complicated example, illustrating the use of 726`:=' in conjunction with the `shell' function. (*Note The `shell' 727Function: Shell Function.) This example also shows use of the variable 728`MAKELEVEL', which is changed when it is passed down from level to 729level. (*Note Communicating Variables to a Sub-`make': 730Variables/Recursion, for information about `MAKELEVEL'.) 731 732 ifeq (0,${MAKELEVEL}) 733 cur-dir := $(shell pwd) 734 whoami := $(shell whoami) 735 host-type := $(shell arch) 736 MAKE := ${MAKE} host-type=${host-type} whoami=${whoami} 737 endif 738 739An advantage of this use of `:=' is that a typical `descend into a 740directory' command then looks like this: 741 742 ${subdirs}: 743 ${MAKE} cur-dir=${cur-dir}/$@ -C $@ all 744 745 Simply expanded variables generally make complicated makefile 746programming more predictable because they work like variables in most 747programming languages. They allow you to redefine a variable using its 748own value (or its value processed in some way by one of the expansion 749functions) and to use the expansion functions much more efficiently 750(*note Functions for Transforming Text: Functions.). 751 752 You can also use them to introduce controlled leading whitespace into 753variable values. Leading whitespace characters are discarded from your 754input before substitution of variable references and function calls; 755this means you can include leading spaces in a variable value by 756protecting them with variable references, like this: 757 758 nullstring := 759 space := $(nullstring) # end of the line 760 761Here the value of the variable `space' is precisely one space. The 762comment `# end of the line' is included here just for clarity. Since 763trailing space characters are *not* stripped from variable values, just 764a space at the end of the line would have the same effect (but be 765rather hard to read). If you put whitespace at the end of a variable 766value, it is a good idea to put a comment like that at the end of the 767line to make your intent clear. Conversely, if you do *not* want any 768whitespace characters at the end of your variable value, you must 769remember not to put a random comment on the end of the line after some 770whitespace, such as this: 771 772 dir := /foo/bar # directory to put the frobs in 773 774Here the value of the variable `dir' is `/foo/bar ' (with four 775trailing spaces), which was probably not the intention. (Imagine 776something like `$(dir)/file' with this definition!) 777 778 779File: make.info, Node: Advanced, Next: Values, Prev: Flavors, Up: Using Variables 780 781Advanced Features for Reference to Variables 782============================================ 783 784 This section describes some advanced features you can use to 785reference variables in more flexible ways. 786 787* Menu: 788 789* Substitution Refs:: Referencing a variable with 790 substitutions on the value. 791* Computed Names:: Computing the name of the variable to refer to. 792 793 794File: make.info, Node: Substitution Refs, Next: Computed Names, Up: Advanced 795 796Substitution References 797----------------------- 798 799 A "substitution reference" substitutes the value of a variable with 800alterations that you specify. It has the form `$(VAR:A=B)' (or 801`${VAR:A=B}') and its meaning is to take the value of the variable VAR, 802replace every A at the end of a word with B in that value, and 803substitute the resulting string. 804 805 When we say "at the end of a word", we mean that A must appear 806either followed by whitespace or at the end of the value in order to be 807replaced; other occurrences of A in the value are unaltered. For 808example: 809 810 foo := a.o b.o c.o 811 bar := $(foo:.o=.c) 812 813sets `bar' to `a.c b.c c.c'. *Note Setting Variables: Setting. 814 815 A substitution reference is actually an abbreviation for use of the 816`patsubst' expansion function (*note Functions for String Substitution 817and Analysis: Text Functions.). We provide substitution references as 818well as `patsubst' for compatibility with other implementations of 819`make'. 820 821 Another type of substitution reference lets you use the full power of 822the `patsubst' function. It has the same form `$(VAR:A=B)' described 823above, except that now A must contain a single `%' character. This 824case is equivalent to `$(patsubst A,B,$(VAR))'. *Note Functions for 825String Substitution and Analysis: Text Functions, for a description of 826the `patsubst' function. 827 828For example: 829 830 foo := a.o b.o c.o 831 bar := $(foo:%.o=%.c) 832 833sets `bar' to `a.c b.c c.c'. 834 835 836File: make.info, Node: Computed Names, Prev: Substitution Refs, Up: Advanced 837 838Computed Variable Names 839----------------------- 840 841 Computed variable names are a complicated concept needed only for 842sophisticated makefile programming. For most purposes you need not 843consider them, except to know that making a variable with a dollar sign 844in its name might have strange results. However, if you are the type 845that wants to understand everything, or you are actually interested in 846what they do, read on. 847 848 Variables may be referenced inside the name of a variable. This is 849called a "computed variable name" or a "nested variable reference". 850For example, 851 852 x = y 853 y = z 854 a := $($(x)) 855 856defines `a' as `z': the `$(x)' inside `$($(x))' expands to `y', so 857`$($(x))' expands to `$(y)' which in turn expands to `z'. Here the 858name of the variable to reference is not stated explicitly; it is 859computed by expansion of `$(x)'. The reference `$(x)' here is nested 860within the outer variable reference. 861 862 The previous example shows two levels of nesting, but any number of 863levels is possible. For example, here are three levels: 864 865 x = y 866 y = z 867 z = u 868 a := $($($(x))) 869 870Here the innermost `$(x)' expands to `y', so `$($(x))' expands to 871`$(y)' which in turn expands to `z'; now we have `$(z)', which becomes 872`u'. 873 874 References to recursively-expanded variables within a variable name 875are reexpanded in the usual fashion. For example: 876 877 x = $(y) 878 y = z 879 z = Hello 880 a := $($(x)) 881 882defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes 883`$(z)' which becomes `Hello'. 884 885 Nested variable references can also contain modified references and 886function invocations (*note Functions for Transforming Text: 887Functions.), just like any other reference. For example, using the 888`subst' function (*note Functions for String Substitution and Analysis: 889Text Functions.): 890 891 x = variable1 892 variable2 := Hello 893 y = $(subst 1,2,$(x)) 894 z = y 895 a := $($($(z))) 896 897eventually defines `a' as `Hello'. It is doubtful that anyone would 898ever want to write a nested reference as convoluted as this one, but it 899works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst 9001,2,$(x)))'. This gets the value `variable1' from `x' and changes it 901by substitution to `variable2', so that the entire string becomes 902`$(variable2)', a simple variable reference whose value is `Hello'. 903 904 A computed variable name need not consist entirely of a single 905variable reference. It can contain several variable references, as 906well as some invariant text. For example, 907 908 a_dirs := dira dirb 909 1_dirs := dir1 dir2 910 911 a_files := filea fileb 912 1_files := file1 file2 913 914 ifeq "$(use_a)" "yes" 915 a1 := a 916 else 917 a1 := 1 918 endif 919 920 ifeq "$(use_dirs)" "yes" 921 df := dirs 922 else 923 df := files 924 endif 925 926 dirs := $($(a1)_$(df)) 927 928will give `dirs' the same value as `a_dirs', `1_dirs', `a_files' or 929`1_files' depending on the settings of `use_a' and `use_dirs'. 930 931 Computed variable names can also be used in substitution references: 932 933 a_objects := a.o b.o c.o 934 1_objects := 1.o 2.o 3.o 935 936 sources := $($(a1)_objects:.o=.c) 937 938defines `sources' as either `a.c b.c c.c' or `1.c 2.c 3.c', depending 939on the value of `a1'. 940 941 The only restriction on this sort of use of nested variable 942references is that they cannot specify part of the name of a function 943to be called. This is because the test for a recognized function name 944is done before the expansion of nested references. For example, 945 946 ifdef do_sort 947 func := sort 948 else 949 func := strip 950 endif 951 952 bar := a d b g q c 953 954 foo := $($(func) $(bar)) 955 956attempts to give `foo' the value of the variable `sort a d b g q c' or 957`strip a d b g q c', rather than giving `a d b g q c' as the argument 958to either the `sort' or the `strip' function. This restriction could 959be removed in the future if that change is shown to be a good idea. 960 961 You can also use computed variable names in the left-hand side of a 962variable assignment, or in a `define' directive, as in: 963 964 dir = foo 965 $(dir)_sources := $(wildcard $(dir)/*.c) 966 define $(dir)_print 967 lpr $($(dir)_sources) 968 endef 969 970This example defines the variables `dir', `foo_sources', and 971`foo_print'. 972 973 Note that "nested variable references" are quite different from 974"recursively expanded variables" (*note The Two Flavors of Variables: 975Flavors.), though both are used together in complex ways when doing 976makefile programming. 977 978 979File: make.info, Node: Values, Next: Setting, Prev: Advanced, Up: Using Variables 980 981How Variables Get Their Values 982============================== 983 984 Variables can get values in several different ways: 985 986 * You can specify an overriding value when you run `make'. *Note 987 Overriding Variables: Overriding. 988 989 * You can specify a value in the makefile, either with an assignment 990 (*note Setting Variables: Setting.) or with a verbatim definition 991 (*note Defining Variables Verbatim: Defining.). 992 993 * Variables in the environment become `make' variables. *Note 994 Variables from the Environment: Environment. 995 996 * Several "automatic" variables are given new values for each rule. 997 Each of these has a single conventional use. *Note Automatic 998 Variables: Automatic. 999 1000 * Several variables have constant initial values. *Note Variables 1001 Used by Implicit Rules: Implicit Variables. 1002 1003 1004File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Variables 1005 1006Setting Variables 1007================= 1008 1009 To set a variable from the makefile, write a line starting with the 1010variable name followed by `=' or `:='. Whatever follows the `=' or 1011`:=' on the line becomes the value. For example, 1012 1013 objects = main.o foo.o bar.o utils.o 1014 1015defines a variable named `objects'. Whitespace around the variable 1016name and immediately after the `=' is ignored. 1017 1018 Variables defined with `=' are "recursively expanded" variables. 1019Variables defined with `:=' are "simply expanded" variables; these 1020definitions can contain variable references which will be expanded 1021before the definition is made. *Note The Two Flavors of Variables: 1022Flavors. 1023 1024 The variable name may contain function and variable references, which 1025are expanded when the line is read to find the actual variable name to 1026use. 1027 1028 There is no limit on the length of the value of a variable except the 1029amount of swapping space on the computer. When a variable definition is 1030long, it is a good idea to break it into several lines by inserting 1031backslash-newline at convenient places in the definition. This will not 1032affect the functioning of `make', but it will make the makefile easier 1033to read. 1034 1035 Most variable names are considered to have the empty string as a 1036value if you have never set them. Several variables have built-in 1037initial values that are not empty, but you can set them in the usual 1038ways (*note Variables Used by Implicit Rules: Implicit Variables.). 1039Several special variables are set automatically to a new value for each 1040rule; these are called the "automatic" variables (*note Automatic 1041Variables: Automatic.). 1042 1043 1044File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables 1045 1046Appending More Text to Variables 1047================================ 1048 1049 Often it is useful to add more text to the value of a variable 1050already defined. You do this with a line containing `+=', like this: 1051 1052 objects += another.o 1053 1054This takes the value of the variable `objects', and adds the text 1055`another.o' to it (preceded by a single space). Thus: 1056 1057 objects = main.o foo.o bar.o utils.o 1058 objects += another.o 1059 1060sets `objects' to `main.o foo.o bar.o utils.o another.o'. 1061 1062 Using `+=' is similar to: 1063 1064 objects = main.o foo.o bar.o utils.o 1065 objects := $(objects) another.o 1066 1067but differs in ways that become important when you use more complex 1068values. 1069 1070 When the variable in question has not been defined before, `+=' acts 1071just like normal `=': it defines a recursively-expanded variable. 1072However, when there *is* a previous definition, exactly what `+=' does 1073depends on what flavor of variable you defined originally. *Note The 1074Two Flavors of Variables: Flavors, for an explanation of the two 1075flavors of variables. 1076 1077 When you add to a variable's value with `+=', `make' acts 1078essentially as if you had included the extra text in the initial 1079definition of the variable. If you defined it first with `:=', making 1080it a simply-expanded variable, `+=' adds to that simply-expanded 1081definition, and expands the new text before appending it to the old 1082value just as `:=' does (*note Setting Variables: Setting., for a full 1083explanation of `:='). In fact, 1084 1085 variable := value 1086 variable += more 1087 1088is exactly equivalent to: 1089 1090 variable := value 1091 variable := $(variable) more 1092 1093 On the other hand, when you use `+=' with a variable that you defined 1094first to be recursively-expanded using plain `=', `make' does something 1095a bit different. Recall that when you define a recursively-expanded 1096variable, `make' does not expand the value you set for variable and 1097function references immediately. Instead it stores the text verbatim, 1098and saves these variable and function references to be expanded later, 1099when you refer to the new variable (*note The Two Flavors of Variables: 1100Flavors.). When you use `+=' on a recursively-expanded variable, it is 1101this unexpanded text to which `make' appends the new text you specify. 1102 1103 variable = value 1104 variable += more 1105 1106is roughly equivalent to: 1107 1108 temp = value 1109 variable = $(temp) more 1110 1111except that of course it never defines a variable called `temp'. The 1112importance of this comes when the variable's old value contains 1113variable references. Take this common example: 1114 1115 CFLAGS = $(includes) -O 1116 ... 1117 CFLAGS += -pg # enable profiling 1118 1119The first line defines the `CFLAGS' variable with a reference to another 1120variable, `includes'. (`CFLAGS' is used by the rules for C 1121compilation; *note Catalogue of Implicit Rules: Catalogue of Rules..) 1122Using `=' for the definition makes `CFLAGS' a recursively-expanded 1123variable, meaning `$(includes) -O' is *not* expanded when `make' 1124processes the definition of `CFLAGS'. Thus, `includes' need not be 1125defined yet for its value to take effect. It only has to be defined 1126before any reference to `CFLAGS'. If we tried to append to the value 1127of `CFLAGS' without using `+=', we might do it like this: 1128 1129 CFLAGS := $(CFLAGS) -pg # enable profiling 1130 1131This is pretty close, but not quite what we want. Using `:=' redefines 1132`CFLAGS' as a simply-expanded variable; this means `make' expands the 1133text `$(CFLAGS) -pg' before setting the variable. If `includes' is not 1134yet defined, we get ` -O -pg', and a later definition of `includes' 1135will have no effect. Conversely, by using `+=' we set `CFLAGS' to the 1136*unexpanded* value `$(includes) -O -pg'. Thus we preserve the 1137reference to `includes', so if that variable gets defined at any later 1138point, a reference like `$(CFLAGS)' still uses its value. 1139 1140 1141File: make.info, Node: Override Directive, Next: Defining, Prev: Appending, Up: Using Variables 1142 1143The `override' Directive 1144======================== 1145 1146 If a variable has been set with a command argument (*note Overriding 1147Variables: Overriding.), then ordinary assignments in the makefile are 1148ignored. If you want to set the variable in the makefile even though 1149it was set with a command argument, you can use an `override' 1150directive, which is a line that looks like this: 1151 1152 override VARIABLE = VALUE 1153 1154or 1155 1156 override VARIABLE := VALUE 1157 1158 To append more text to a variable defined on the command line, use: 1159 1160 override VARIABLE += MORE TEXT 1161 1162*Note Appending More Text to Variables: Appending. 1163 1164 The `override' directive was not invented for escalation in the war 1165between makefiles and command arguments. It was invented so you can 1166alter and add to values that the user specifies with command arguments. 1167 1168 For example, suppose you always want the `-g' switch when you run the 1169C compiler, but you would like to allow the user to specify the other 1170switches with a command argument just as usual. You could use this 1171`override' directive: 1172 1173 override CFLAGS += -g 1174 1175 You can also use `override' directives with `define' directives. 1176This is done as you might expect: 1177 1178 override define foo 1179 bar 1180 endef 1181 1182*Note Defining Variables Verbatim: Defining. 1183 1184 1185File: make.info, Node: Defining, Next: Environment, Prev: Override Directive, Up: Using Variables 1186 1187Defining Variables Verbatim 1188=========================== 1189 1190Another way to set the value of a variable is to use the `define' 1191directive. This directive has an unusual syntax which allows newline 1192characters to be included in the value, which is convenient for defining 1193canned sequences of commands (*note Defining Canned Command Sequences: 1194Sequences.). 1195 1196 The `define' directive is followed on the same line by the name of 1197the variable and nothing more. The value to give the variable appears 1198on the following lines. The end of the value is marked by a line 1199containing just the word `endef'. Aside from this difference in 1200syntax, `define' works just like `=': it creates a recursively-expanded 1201variable (*note The Two Flavors of Variables: Flavors.). The variable 1202name may contain function and variable references, which are expanded 1203when the directive is read to find the actual variable name to use. 1204 1205 define two-lines 1206 echo foo 1207 echo $(bar) 1208 endef 1209 1210 The value in an ordinary assignment cannot contain a newline; but the 1211newlines that separate the lines of the value in a `define' become part 1212of the variable's value (except for the final newline which precedes 1213the `endef' and is not considered part of the value). 1214 1215 The previous example is functionally equivalent to this: 1216 1217 two-lines = echo foo; echo $(bar) 1218 1219since two commands separated by semicolon behave much like two separate 1220shell commands. However, note that using two separate lines means 1221`make' will invoke the shell twice, running an independent subshell for 1222each line. *Note Command Execution: Execution. 1223 1224 If you want variable definitions made with `define' to take 1225precedence over command-line variable definitions, you can use the 1226`override' directive together with `define': 1227 1228 override define two-lines 1229 foo 1230 $(bar) 1231 endef 1232 1233*Note The `override' Directive: Override Directive. 1234 1235