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: Options Summary, Prev: Testing, Up: Running 30 31Summary of Options 32================== 33 34 Here is a table of all the options `make' understands: 35 36`-b' 37`-m' 38 These options are ignored for compatibility with other versions of 39 `make'. 40 41`-C DIR' 42`--directory=DIR' 43 Change to directory DIR before reading the makefiles. If multiple 44 `-C' options are specified, each is interpreted relative to the 45 previous one: `-C / -C etc' is equivalent to `-C /etc'. This is 46 typically used with recursive invocations of `make' (*note 47 Recursive Use of `make': Recursion.). 48 49`-d' 50`--debug' 51 Print debugging information in addition to normal processing. The 52 debugging information says which files are being considered for 53 remaking, which file-times are being compared and with what 54 results, which files actually need to be remade, which implicit 55 rules are considered and which are applied--everything interesting 56 about how `make' decides what to do. 57 58`-e' 59`--environment-overrides' 60 Give variables taken from the environment precedence over 61 variables from makefiles. *Note Variables from the Environment: 62 Environment. 63 64`-f FILE' 65`--file=FILE' 66`--makefile=FILE' 67 Read the file named FILE as a makefile. *Note Writing Makefiles: 68 Makefiles. 69 70`-h' 71`--help' 72 Remind you of the options that `make' understands and then exit. 73 74`-i' 75`--ignore-errors' 76 Ignore all errors in commands executed to remake files. *Note 77 Errors in Commands: Errors. 78 79`-I DIR' 80`--include-dir=DIR' 81 Specifies a directory DIR to search for included makefiles. *Note 82 Including Other Makefiles: Include. If several `-I' options are 83 used to specify several directories, the directories are searched 84 in the order specified. 85 86`-j [JOBS]' 87`--jobs=[JOBS]' 88 Specifies the number of jobs (commands) to run simultaneously. 89 With no argument, `make' runs as many jobs simultaneously as 90 possible. If there is more than one `-j' option, the last one is 91 effective. *Note Parallel Execution: Parallel, for more 92 information on how commands are run. 93 94`-k' 95`--keep-going' 96 Continue as much as possible after an error. While the target that 97 failed, and those that depend on it, cannot be remade, the other 98 dependencies of these targets can be processed all the same. 99 *Note Testing the Compilation of a Program: Testing. 100 101`-l [LOAD]' 102`--load-average[=LOAD]' 103`--max-load[=LOAD]' 104 Specifies that no new jobs (commands) should be started if there 105 are other jobs running and the load average is at least LOAD (a 106 floating-point number). With no argument, removes a previous load 107 limit. *Note Parallel Execution: Parallel. 108 109`-n' 110`--just-print' 111`--dry-run' 112`--recon' 113 Print the commands that would be executed, but do not execute them. 114 *Note Instead of Executing the Commands: Instead of Execution. 115 116`-o FILE' 117`--old-file=FILE' 118`--assume-old=FILE' 119 Do not remake the file FILE even if it is older than its 120 dependencies, and do not remake anything on account of changes in 121 FILE. Essentially the file is treated as very old and its rules 122 are ignored. *Note Avoiding Recompilation of Some Files: Avoiding 123 Compilation. 124 125`-p' 126`--print-data-base' 127 Print the data base (rules and variable values) that results from 128 reading the makefiles; then execute as usual or as otherwise 129 specified. This also prints the version information given by the 130 `-v' switch (see below). To print the data base without trying to 131 remake any files, use `make -p -f /dev/null'. 132 133`-q' 134`--question' 135 "Question mode". Do not run any commands, or print anything; just 136 return an exit status that is zero if the specified targets are 137 already up to date, one if any remaking is required, or two if an 138 error is encountered. *Note Instead of Executing the Commands: 139 Instead of Execution. 140 141`-r' 142`--no-builtin-rules' 143 Eliminate use of the built-in implicit rules (*note Using Implicit 144 Rules: Implicit Rules.). You can still define your own by writing 145 pattern rules (*note Defining and Redefining Pattern Rules: 146 Pattern Rules.). The `-r' option also clears out the default list 147 of suffixes for suffix rules (*note Old-Fashioned Suffix Rules: 148 Suffix Rules.). But you can still define your own suffixes with a 149 rule for `.SUFFIXES', and then define your own suffix rules. 150 151`-s' 152`--silent' 153`--quiet' 154 Silent operation; do not print the commands as they are executed. 155 *Note Command Echoing: Echoing. 156 157`-S' 158`--no-keep-going' 159`--stop' 160 Cancel the effect of the `-k' option. This is never necessary 161 except in a recursive `make' where `-k' might be inherited from 162 the top-level `make' via `MAKEFLAGS' (*note Recursive Use of 163 `make': Recursion.) or if you set `-k' in `MAKEFLAGS' in your 164 environment. 165 166`-t' 167`--touch' 168 Touch files (mark them up to date without really changing them) 169 instead of running their commands. This is used to pretend that 170 the commands were done, in order to fool future invocations of 171 `make'. *Note Instead of Executing the Commands: Instead of 172 Execution. 173 174`-v' 175`--version' 176 Print the version of the `make' program plus a copyright, a list 177 of authors, and a notice that there is no warranty; then exit. 178 179`-w' 180`--print-directory' 181 Print a message containing the working directory both before and 182 after executing the makefile. This may be useful for tracking 183 down errors from complicated nests of recursive `make' commands. 184 *Note Recursive Use of `make': Recursion. (In practice, you 185 rarely need to specify this option since `make' does it for you; 186 see *Note The `--print-directory' Option: -w Option.) 187 188`--no-print-directory' 189 Disable printing of the working directory under `-w'. This option 190 is useful when `-w' is turned on automatically, but you do not 191 want to see the extra messages. *Note The `--print-directory' 192 Option: -w Option. 193 194`-W FILE' 195`--what-if=FILE' 196`--new-file=FILE' 197`--assume-new=FILE' 198 Pretend that the target FILE has just been modified. When used 199 with the `-n' flag, this shows you what would happen if you were 200 to modify that file. Without `-n', it is almost the same as 201 running a `touch' command on the given file before running `make', 202 except that the modification time is changed only in the 203 imagination of `make'. *Note Instead of Executing the Commands: 204 Instead of Execution. 205 206`--warn-undefined-variables' 207 Issue a warning message whenever `make' sees a reference to an 208 undefined variable. This can be helpful when you are trying to 209 debug makefiles which use variables in complex ways. 210 211 212File: make.info, Node: Implicit Rules, Next: Archives, Prev: Running, Up: Top 213 214Using Implicit Rules 215******************** 216 217 Certain standard ways of remaking target files are used very often. 218For example, one customary way to make an object file is from a C 219source file using the C compiler, `cc'. 220 221 "Implicit rules" tell `make' how to use customary techniques so that 222you do not have to specify them in detail when you want to use them. 223For example, there is an implicit rule for C compilation. File names 224determine which implicit rules are run. For example, C compilation 225typically takes a `.c' file and makes a `.o' file. So `make' applies 226the implicit rule for C compilation when it sees this combination of 227file name endings. 228 229 A chain of implicit rules can apply in sequence; for example, `make' 230will remake a `.o' file from a `.y' file by way of a `.c' file. 231 232 The built-in implicit rules use several variables in their commands 233so that, by changing the values of the variables, you can change the 234way the implicit rule works. For example, the variable `CFLAGS' 235controls the flags given to the C compiler by the implicit rule for C 236compilation. 237 238 You can define your own implicit rules by writing "pattern rules". 239 240 "Suffix rules" are a more limited way to define implicit rules. 241Pattern rules are more general and clearer, but suffix rules are 242retained for compatibility. 243 244* Menu: 245 246* Using Implicit:: How to use an existing implicit rule 247 to get the commands for updating a file. 248* Catalogue of Rules:: A list of built-in implicit rules. 249* Implicit Variables:: How to change what predefined rules do. 250* Chained Rules:: How to use a chain of implicit rules. 251* Pattern Rules:: How to define new implicit rules. 252* Last Resort:: How to defining commands for rules 253 which cannot find any. 254* Suffix Rules:: The old-fashioned style of implicit rule. 255* Search Algorithm:: The precise algorithm for applying 256 implicit rules. 257 258 259File: make.info, Node: Using Implicit, Next: Catalogue of Rules, Up: Implicit Rules 260 261Using Implicit Rules 262==================== 263 264 To allow `make' to find a customary method for updating a target 265file, all you have to do is refrain from specifying commands yourself. 266Either write a rule with no command lines, or don't write a rule at 267all. Then `make' will figure out which implicit rule to use based on 268which kind of source file exists or can be made. 269 270 For example, suppose the makefile looks like this: 271 272 foo : foo.o bar.o 273 cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) 274 275Because you mention `foo.o' but do not give a rule for it, `make' will 276automatically look for an implicit rule that tells how to update it. 277This happens whether or not the file `foo.o' currently exists. 278 279 If an implicit rule is found, it can supply both commands and one or 280more dependencies (the source files). You would want to write a rule 281for `foo.o' with no command lines if you need to specify additional 282dependencies, such as header files, that the implicit rule cannot 283supply. 284 285 Each implicit rule has a target pattern and dependency patterns. 286There may be many implicit rules with the same target pattern. For 287example, numerous rules make `.o' files: one, from a `.c' file with the 288C compiler; another, from a `.p' file with the Pascal compiler; and so 289on. The rule that actually applies is the one whose dependencies exist 290or can be made. So, if you have a file `foo.c', `make' will run the C 291compiler; otherwise, if you have a file `foo.p', `make' will run the 292Pascal compiler; and so on. 293 294 Of course, when you write the makefile, you know which implicit rule 295you want `make' to use, and you know it will choose that one because you 296know which possible dependency files are supposed to exist. *Note 297Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all 298the predefined implicit rules. 299 300 Above, we said an implicit rule applies if the required dependencies 301"exist or can be made". A file "can be made" if it is mentioned 302explicitly in the makefile as a target or a dependency, or if an 303implicit rule can be recursively found for how to make it. When an 304implicit dependency is the result of another implicit rule, we say that 305"chaining" is occurring. *Note Chains of Implicit Rules: Chained Rules. 306 307 In general, `make' searches for an implicit rule for each target, and 308for each double-colon rule, that has no commands. A file that is 309mentioned only as a dependency is considered a target whose rule 310specifies nothing, so implicit rule search happens for it. *Note 311Implicit Rule Search Algorithm: Search Algorithm, for the details of 312how the search is done. 313 314 Note that explicit dependencies do not influence implicit rule 315search. For example, consider this explicit rule: 316 317 foo.o: foo.p 318 319The dependency on `foo.p' does not necessarily mean that `make' will 320remake `foo.o' according to the implicit rule to make an object file, a 321`.o' file, from a Pascal source file, a `.p' file. For example, if 322`foo.c' also exists, the implicit rule to make an object file from a C 323source file is used instead, because it appears before the Pascal rule 324in the list of predefined implicit rules (*note Catalogue of Implicit 325Rules: Catalogue of Rules.). 326 327 If you do not want an implicit rule to be used for a target that has 328no commands, you can give that target empty commands by writing a 329semicolon (*note Defining Empty Commands: Empty Commands.). 330 331 332File: make.info, Node: Catalogue of Rules, Next: Implicit Variables, Prev: Using Implicit, Up: Implicit Rules 333 334Catalogue of Implicit Rules 335=========================== 336 337 Here is a catalogue of predefined implicit rules which are always 338available unless the makefile explicitly overrides or cancels them. 339*Note Canceling Implicit Rules: Canceling Rules, for information on 340canceling or overriding an implicit rule. The `-r' or 341`--no-builtin-rules' option cancels all predefined rules. 342 343 Not all of these rules will always be defined, even when the `-r' 344option is not given. Many of the predefined implicit rules are 345implemented in `make' as suffix rules, so which ones will be defined 346depends on the "suffix list" (the list of dependencies of the special 347target `.SUFFIXES'). The default suffix list is: `.out', `.a', `.ln', 348`.o', `.c', `.cc', `.C', `.p', `.f', `.F', `.r', `.y', `.l', `.s', 349`.S', `.mod', `.sym', `.def', `.h', `.info', `.dvi', `.tex', `.texinfo', 350`.texi', `.txinfo', `.w', `.ch' `.web', `.sh', `.elc', `.el'. All of 351the implicit rules described below whose dependencies have one of these 352suffixes are actually suffix rules. If you modify the suffix list, the 353only predefined suffix rules in effect will be those named by one or 354two of the suffixes that are on the list you specify; rules whose 355suffixes fail to be on the list are disabled. *Note Old-Fashioned 356Suffix Rules: Suffix Rules, for full details on suffix rules. 357 358Compiling C programs 359 `N.o' is made automatically from `N.c' with a command of the form 360 `$(CC) -c $(CPPFLAGS) $(CFLAGS)'. 361 362Compiling C++ programs 363 `N.o' is made automatically from `N.cc' or `N.C' with a command of 364 the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'. We encourage you to 365 use the suffix `.cc' for C++ source files instead of `.C'. 366 367Compiling Pascal programs 368 `N.o' is made automatically from `N.p' with the command `$(PC) -c 369 $(PFLAGS)'. 370 371Compiling Fortran and Ratfor programs 372 `N.o' is made automatically from `N.r', `N.F' or `N.f' by running 373 the Fortran compiler. The precise command used is as follows: 374 375 `.f' 376 `$(FC) -c $(FFLAGS)'. 377 378 `.F' 379 `$(FC) -c $(FFLAGS) $(CPPFLAGS)'. 380 381 `.r' 382 `$(FC) -c $(FFLAGS) $(RFLAGS)'. 383 384Preprocessing Fortran and Ratfor programs 385 `N.f' is made automatically from `N.r' or `N.F'. This rule runs 386 just the preprocessor to convert a Ratfor or preprocessable 387 Fortran program into a strict Fortran program. The precise 388 command used is as follows: 389 390 `.F' 391 `$(FC) -F $(CPPFLAGS) $(FFLAGS)'. 392 393 `.r' 394 `$(FC) -F $(FFLAGS) $(RFLAGS)'. 395 396Compiling Modula-2 programs 397 `N.sym' is made from `N.def' with a command of the form `$(M2C) 398 $(M2FLAGS) $(DEFFLAGS)'. `N.o' is made from `N.mod'; the form is: 399 `$(M2C) $(M2FLAGS) $(MODFLAGS)'. 400 401Assembling and preprocessing assembler programs 402 `N.o' is made automatically from `N.s' by running the assembler, 403 `as'. The precise command is `$(AS) $(ASFLAGS)'. 404 405 `N.s' is made automatically from `N.S' by running the C 406 preprocessor, `cpp'. The precise command is `$(CPP) $(CPPFLAGS)'. 407 408Linking a single object file 409 `N' is made automatically from `N.o' by running the linker 410 (usually called `ld') via the C compiler. The precise command 411 used is `$(CC) $(LDFLAGS) N.o $(LOADLIBES)'. 412 413 This rule does the right thing for a simple program with only one 414 source file. It will also do the right thing if there are multiple 415 object files (presumably coming from various other source files), 416 one of which has a name matching that of the executable file. 417 Thus, 418 419 x: y.o z.o 420 421 when `x.c', `y.c' and `z.c' all exist will execute: 422 423 cc -c x.c -o x.o 424 cc -c y.c -o y.o 425 cc -c z.c -o z.o 426 cc x.o y.o z.o -o x 427 rm -f x.o 428 rm -f y.o 429 rm -f z.o 430 431 In more complicated cases, such as when there is no object file 432 whose name derives from the executable file name, you must write 433 an explicit command for linking. 434 435 Each kind of file automatically made into `.o' object files will 436 be automatically linked by using the compiler (`$(CC)', `$(FC)' or 437 `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files) 438 without the `-c' option. This could be done by using the `.o' 439 object files as intermediates, but it is faster to do the 440 compiling and linking in one step, so that's how it's done. 441 442Yacc for C programs 443 `N.c' is made automatically from `N.y' by running Yacc with the 444 command `$(YACC) $(YFLAGS)'. 445 446Lex for C programs 447 `N.c' is made automatically from `N.l' by by running Lex. The 448 actual command is `$(LEX) $(LFLAGS)'. 449 450Lex for Ratfor programs 451 `N.r' is made automatically from `N.l' by by running Lex. The 452 actual command is `$(LEX) $(LFLAGS)'. 453 454 The convention of using the same suffix `.l' for all Lex files 455 regardless of whether they produce C code or Ratfor code makes it 456 impossible for `make' to determine automatically which of the two 457 languages you are using in any particular case. If `make' is 458 called upon to remake an object file from a `.l' file, it must 459 guess which compiler to use. It will guess the C compiler, because 460 that is more common. If you are using Ratfor, make sure `make' 461 knows this by mentioning `N.r' in the makefile. Or, if you are 462 using Ratfor exclusively, with no C files, remove `.c' from the 463 list of implicit rule suffixes with: 464 465 .SUFFIXES: 466 .SUFFIXES: .o .r .f .l ... 467 468Making Lint Libraries from C, Yacc, or Lex programs 469 `N.ln' is made from `N.c' by running `lint'. The precise command 470 is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'. The same command is 471 used on the C code produced from `N.y' or `N.l'. 472 473TeX and Web 474 `N.dvi' is made from `N.tex' with the command `$(TEX)'. `N.tex' 475 is made from `N.web' with `$(WEAVE)', or from `N.w' (and from 476 `N.ch' if it exists or can be made) with `$(CWEAVE)'. `N.p' is 477 made from `N.web' with `$(TANGLE)' and `N.c' is made from `N.w' 478 (and from `N.ch' if it exists or can be made) with `$(CTANGLE)'. 479 480Texinfo and Info 481 `N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with 482 the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'. `N.info' is made from 483 `N.texinfo', `N.texi', or `N.txinfo', with the command 484 `$(MAKEINFO) $(MAKEINFO_FLAGS)'. 485 486RCS 487 Any file `N' is extracted if necessary from an RCS file named 488 either `N,v' or `RCS/N,v'. The precise command used is 489 `$(CO) $(COFLAGS)'. `N' will not be extracted from RCS if it 490 already exists, even if the RCS file is newer. The rules for RCS 491 are terminal (*note Match-Anything Pattern Rules: Match-Anything 492 Rules.), so RCS files cannot be generated from another source; 493 they must actually exist. 494 495SCCS 496 Any file `N' is extracted if necessary from an SCCS file named 497 either `s.N' or `SCCS/s.N'. The precise command used is 498 `$(GET) $(GFLAGS)'. The rules for SCCS are terminal (*note 499 Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS 500 files cannot be generated from another source; they must actually 501 exist. 502 503 For the benefit of SCCS, a file `N' is copied from `N.sh' and made 504 executable (by everyone). This is for shell scripts that are 505 checked into SCCS. Since RCS preserves the execution permission 506 of a file, you do not need to use this feature with RCS. 507 508 We recommend that you avoid using of SCCS. RCS is widely held to 509 be superior, and is also free. By choosing free software in place 510 of comparable (or inferior) proprietary software, you support the 511 free software movement. 512 513 Usually, you want to change only the variables listed in the table 514above, which are documented in the following section. 515 516 However, the commands in built-in implicit rules actually use 517variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose 518values contain the commands listed above. 519 520 `make' follows the convention that the rule to compile a `.X' source 521file uses the variable `COMPILE.X'. Similarly, the rule to produce an 522executable from a `.X' file uses `LINK.X'; and the rule to preprocess a 523`.X' file uses `PREPROCESS.X'. 524 525 Every rule that produces an object file uses the variable 526`OUTPUT_OPTION'. `make' defines this variable either to contain `-o 527$@', or to be empty, depending on a compile-time option. You need the 528`-o' option to ensure that the output goes into the right file when the 529source file is in a different directory, as when using `VPATH' (*note 530Directory Search::.). However, compilers on some systems do not accept 531a `-o' switch for object files. If you use such a system, and use 532`VPATH', some compilations will put their output in the wrong place. A 533possible workaround for this problem is to give `OUTPUT_OPTION' the 534value `; mv $*.o $@'. 535 536 537File: make.info, Node: Implicit Variables, Next: Chained Rules, Prev: Catalogue of Rules, Up: Implicit Rules 538 539Variables Used by Implicit Rules 540================================ 541 542 The commands in built-in implicit rules make liberal use of certain 543predefined variables. You can alter these variables in the makefile, 544with arguments to `make', or in the environment to alter how the 545implicit rules work without redefining the rules themselves. 546 547 For example, the command used to compile a C source file actually 548says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'. The default values of the 549variables used are `cc' and nothing, resulting in the command `cc -c'. 550By redefining `CC' to `ncc', you could cause `ncc' to be used for all C 551compilations performed by the implicit rule. By redefining `CFLAGS' to 552be `-g', you could pass the `-g' option to each compilation. *All* 553implicit rules that do C compilation use `$(CC)' to get the program 554name for the compiler and *all* include `$(CFLAGS)' among the arguments 555given to the compiler. 556 557 The variables used in implicit rules fall into two classes: those 558that are names of programs (like `CC') and those that contain arguments 559for the programs (like `CFLAGS'). (The "name of a program" may also 560contain some command arguments, but it must start with an actual 561executable program name.) If a variable value contains more than one 562argument, separate them with spaces. 563 564 Here is a table of variables used as names of programs in built-in 565rules: 566 567`AR' 568 Archive-maintaining program; default `ar'. 569 570`AS' 571 Program for doing assembly; default `as'. 572 573`CC' 574 Program for compiling C programs; default `cc'. 575 576`CXX' 577 Program for compiling C++ programs; default `g++'. 578 579`CO' 580 Program for extracting a file from RCS; default `co'. 581 582`CPP' 583 Program for running the C preprocessor, with results to standard 584 output; default `$(CC) -E'. 585 586`FC' 587 Program for compiling or preprocessing Fortran and Ratfor programs; 588 default `f77'. 589 590`GET' 591 Program for extracting a file from SCCS; default `get'. 592 593`LEX' 594 Program to use to turn Lex grammars into C programs or Ratfor 595 programs; default `lex'. 596 597`PC' 598 Program for compiling Pascal programs; default `pc'. 599 600`YACC' 601 Program to use to turn Yacc grammars into C programs; default 602 `yacc'. 603 604`YACCR' 605 Program to use to turn Yacc grammars into Ratfor programs; default 606 `yacc -r'. 607 608`MAKEINFO' 609 Program to convert a Texinfo source file into an Info file; default 610 `makeinfo'. 611 612`TEX' 613 Program to make TeX DVI files from TeX source; default `tex'. 614 615`TEXI2DVI' 616 Program to make TeX DVI files from Texinfo source; default 617 `texi2dvi'. 618 619`WEAVE' 620 Program to translate Web into TeX; default `weave'. 621 622`CWEAVE' 623 Program to translate C Web into TeX; default `cweave'. 624 625`TANGLE' 626 Program to translate Web into Pascal; default `tangle'. 627 628`CTANGLE' 629 Program to translate C Web into C; default `ctangle'. 630 631`RM' 632 Command to remove a file; default `rm -f'. 633 634 Here is a table of variables whose values are additional arguments 635for the programs above. The default values for all of these is the 636empty string, unless otherwise noted. 637 638`ARFLAGS' 639 Flags to give the archive-maintaining program; default `rv'. 640 641`ASFLAGS' 642 Extra flags to give to the assembler (when explicitly invoked on a 643 `.s' or `.S' file). 644 645`CFLAGS' 646 Extra flags to give to the C compiler. 647 648`CXXFLAGS' 649 Extra flags to give to the C++ compiler. 650 651`COFLAGS' 652 Extra flags to give to the RCS `co' program. 653 654`CPPFLAGS' 655 Extra flags to give to the C preprocessor and programs that use it 656 (the C and Fortran compilers). 657 658`FFLAGS' 659 Extra flags to give to the Fortran compiler. 660 661`GFLAGS' 662 Extra flags to give to the SCCS `get' program. 663 664`LDFLAGS' 665 Extra flags to give to compilers when they are supposed to invoke 666 the linker, `ld'. 667 668`LFLAGS' 669 Extra flags to give to Lex. 670 671`PFLAGS' 672 Extra flags to give to the Pascal compiler. 673 674`RFLAGS' 675 Extra flags to give to the Fortran compiler for Ratfor programs. 676 677`YFLAGS' 678 Extra flags to give to Yacc. 679 680 681File: make.info, Node: Chained Rules, Next: Pattern Rules, Prev: Implicit Variables, Up: Implicit Rules 682 683Chains of Implicit Rules 684======================== 685 686 Sometimes a file can be made by a sequence of implicit rules. For 687example, a file `N.o' could be made from `N.y' by running first Yacc 688and then `cc'. Such a sequence is called a "chain". 689 690 If the file `N.c' exists, or is mentioned in the makefile, no 691special searching is required: `make' finds that the object file can be 692made by C compilation from `N.c'; later on, when considering how to 693make `N.c', the rule for running Yacc is used. Ultimately both `N.c' 694and `N.o' are updated. 695 696 However, even if `N.c' does not exist and is not mentioned, `make' 697knows how to envision it as the missing link between `N.o' and `N.y'! 698In this case, `N.c' is called an "intermediate file". Once `make' has 699decided to use the intermediate file, it is entered in the data base as 700if it had been mentioned in the makefile, along with the implicit rule 701that says how to create it. 702 703 Intermediate files are remade using their rules just like all other 704files. The difference is that the intermediate file is deleted when 705`make' is finished. Therefore, the intermediate file which did not 706exist before `make' also does not exist after `make'. The deletion is 707reported to you by printing a `rm -f' command that shows what `make' is 708doing. (You can list the target pattern of an implicit rule (such as 709`%.o') as a dependency of the special target `.PRECIOUS' to preserve 710intermediate files made by implicit rules whose target patterns match 711that file's name; see *Note Interrupts::.) 712 713 A chain can involve more than two implicit rules. For example, it is 714possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc 715and `cc'. Then both `foo.y' and `foo.c' are intermediate files that 716are deleted at the end. 717 718 No single implicit rule can appear more than once in a chain. This 719means that `make' will not even consider such a ridiculous thing as 720making `foo' from `foo.o.o' by running the linker twice. This 721constraint has the added benefit of preventing any infinite loop in the 722search for an implicit rule chain. 723 724 There are some special implicit rules to optimize certain cases that 725would otherwise be handled by rule chains. For example, making `foo' 726from `foo.c' could be handled by compiling and linking with separate 727chained rules, using `foo.o' as an intermediate file. But what 728actually happens is that a special rule for this case does the 729compilation and linking with a single `cc' command. The optimized rule 730is used in preference to the step-by-step chain because it comes 731earlier in the ordering of rules. 732 733 734File: make.info, Node: Pattern Rules, Next: Last Resort, Prev: Chained Rules, Up: Implicit Rules 735 736Defining and Redefining Pattern Rules 737===================================== 738 739 You define an implicit rule by writing a "pattern rule". A pattern 740rule looks like an ordinary rule, except that its target contains the 741character `%' (exactly one of them). The target is considered a 742pattern for matching file names; the `%' can match any nonempty 743substring, while other characters match only themselves. The 744dependencies likewise use `%' to show how their names relate to the 745target name. 746 747 Thus, a pattern rule `%.o : %.c' says how to make any file `STEM.o' 748from another file `STEM.c'. 749 750 Note that expansion using `%' in pattern rules occurs *after* any 751variable or function expansions, which take place when the makefile is 752read. *Note How to Use Variables: Using Variables, and *Note Functions 753for Transforming Text: Functions. 754 755* Menu: 756 757* Pattern Intro:: An introduction to pattern rules. 758* Pattern Examples:: Examples of pattern rules. 759* Automatic:: How to use automatic variables in the 760 commands of implicit rules. 761* Pattern Match:: How patterns match. 762* Match-Anything Rules:: Precautions you should take prior to 763 defining rules that can match any 764 target file whatever. 765* Canceling Rules:: How to override or cancel built-in rules. 766 767 768File: make.info, Node: Pattern Intro, Next: Pattern Examples, Up: Pattern Rules 769 770Introduction to Pattern Rules 771----------------------------- 772 773 A pattern rule contains the character `%' (exactly one of them) in 774the target; otherwise, it looks exactly like an ordinary rule. The 775target is a pattern for matching file names; the `%' matches any 776nonempty substring, while other characters match only themselves. 777 778 For example, `%.c' as a pattern matches any file name that ends in 779`.c'. `s.%.c' as a pattern matches any file name that starts with 780`s.', ends in `.c' and is at least five characters long. (There must 781be at least one character to match the `%'.) The substring that the 782`%' matches is called the "stem". 783 784 `%' in a dependency of a pattern rule stands for the same stem that 785was matched by the `%' in the target. In order for the pattern rule to 786apply, its target pattern must match the file name under consideration, 787and its dependency patterns must name files that exist or can be made. 788These files become dependencies of the target. 789 790 Thus, a rule of the form 791 792 %.o : %.c ; COMMAND... 793 794specifies how to make a file `N.o', with another file `N.c' as its 795dependency, provided that `N.c' exists or can be made. 796 797 There may also be dependencies that do not use `%'; such a dependency 798attaches to every file made by this pattern rule. These unvarying 799dependencies are useful occasionally. 800 801 A pattern rule need not have any dependencies that contain `%', or 802in fact any dependencies at all. Such a rule is effectively a general 803wildcard. It provides a way to make any file that matches the target 804pattern. *Note Last Resort::. 805 806 Pattern rules may have more than one target. Unlike normal rules, 807this does not act as many different rules with the same dependencies and 808commands. If a pattern rule has multiple targets, `make' knows that 809the rule's commands are responsible for making all of the targets. The 810commands are executed only once to make all the targets. When searching 811for a pattern rule to match a target, the target patterns of a rule 812other than the one that matches the target in need of a rule are 813incidental: `make' worries only about giving commands and dependencies 814to the file presently in question. However, when this file's commands 815are run, the other targets are marked as having been updated themselves. 816 817 The order in which pattern rules appear in the makefile is important 818since this is the order in which they are considered. Of equally 819applicable rules, only the first one found is used. The rules you 820write take precedence over those that are built in. Note however, that 821a rule whose dependencies actually exist or are mentioned always takes 822priority over a rule with dependencies that must be made by chaining 823other implicit rules. 824 825 826File: make.info, Node: Pattern Examples, Next: Automatic, Prev: Pattern Intro, Up: Pattern Rules 827 828Pattern Rule Examples 829--------------------- 830 831 Here are some examples of pattern rules actually predefined in 832`make'. First, the rule that compiles `.c' files into `.o' files: 833 834 %.o : %.c 835 $(CC) -c $(CFLAGS) $(CPPFLAGS) $< -o $@ 836 837defines a rule that can make any file `X.o' from `X.c'. The command 838uses the automatic variables `$@' and `$<' to substitute the names of 839the target file and the source file in each case where the rule applies 840(*note Automatic Variables: Automatic.). 841 842 Here is a second built-in rule: 843 844 % :: RCS/%,v 845 $(CO) $(COFLAGS) $< 846 847defines a rule that can make any file `X' whatsoever from a 848corresponding file `X,v' in the subdirectory `RCS'. Since the target 849is `%', this rule will apply to any file whatever, provided the 850appropriate dependency file exists. The double colon makes the rule 851"terminal", which means that its dependency may not be an intermediate 852file (*note Match-Anything Pattern Rules: Match-Anything Rules.). 853 854 This pattern rule has two targets: 855 856 %.tab.c %.tab.h: %.y 857 bison -d $< 858 859This tells `make' that the command `bison -d X.y' will make both 860`X.tab.c' and `X.tab.h'. If the file `foo' depends on the files 861`parse.tab.o' and `scan.o' and the file `scan.o' depends on the file 862`parse.tab.h', when `parse.y' is changed, the command `bison -d parse.y' 863will be executed only once, and the dependencies of both `parse.tab.o' 864and `scan.o' will be satisfied. (Presumably the file `parse.tab.o' 865will be recompiled from `parse.tab.c' and the file `scan.o' from 866`scan.c', while `foo' is linked from `parse.tab.o', `scan.o', and its 867other dependencies, and it will execute happily ever after.) 868 869 870File: make.info, Node: Automatic, Next: Pattern Match, Prev: Pattern Examples, Up: Pattern Rules 871 872Automatic Variables 873------------------- 874 875 Suppose you are writing a pattern rule to compile a `.c' file into a 876`.o' file: how do you write the `cc' command so that it operates on the 877right source file name? You cannot write the name in the command, 878because the name is different each time the implicit rule is applied. 879 880 What you do is use a special feature of `make', the "automatic 881variables". These variables have values computed afresh for each rule 882that is executed, based on the target and dependencies of the rule. In 883this example, you would use `$@' for the object file name and `$<' for 884the source file name. 885 886 Here is a table of automatic variables: 887 888`$@' 889 The file name of the target of the rule. If the target is an 890 archive member, then `$@' is the name of the archive file. In a 891 pattern rule that has multiple targets (*note Introduction to 892 Pattern Rules: Pattern Intro.), `$@' is the name of whichever 893 target caused the rule's commands to be run. 894 895`$%' 896 The target member name, when the target is an archive member. 897 *Note Archives::. For example, if the target is `foo.a(bar.o)' 898 then `$%' is `bar.o' and `$@' is `foo.a'. `$%' is empty when the 899 target is not an archive member. 900 901`$<' 902 The name of the first dependency. If the target got its commands 903 from an implicit rule, this will be the first dependency added by 904 the implicit rule (*note Implicit Rules::.). 905 906`$?' 907 The names of all the dependencies that are newer than the target, 908 with spaces between them. For dependencies which are archive 909 members, only the member named is used (*note Archives::.). 910 911`$^' 912 The names of all the dependencies, with spaces between them. For 913 dependencies which are archive members, only the member named is 914 used (*note Archives::.). A target has only one dependency on 915 each other file it depends on, no matter how many times each file 916 is listed as a dependency. So if you list a dependency more than 917 once for a target, the value of `$^' contains just one copy of the 918 name. 919 920`$*' 921 The stem with which an implicit rule matches (*note How Patterns 922 Match: Pattern Match.). If the target is `dir/a.foo.b' and the 923 target pattern is `a.%.b' then the stem is `dir/foo'. The stem is 924 useful for constructing names of related files. 925 926 In a static pattern rule, the stem is part of the file name that 927 matched the `%' in the target pattern. 928 929 In an explicit rule, there is no stem; so `$*' cannot be determined 930 in that way. Instead, if the target name ends with a recognized 931 suffix (*note Old-Fashioned Suffix Rules: Suffix Rules.), `$*' is 932 set to the target name minus the suffix. For example, if the 933 target name is `foo.c', then `$*' is set to `foo', since `.c' is a 934 suffix. GNU `make' does this bizarre thing only for compatibility 935 with other implementations of `make'. You should generally avoid 936 using `$*' except in implicit rules or static pattern rules. 937 938 If the target name in an explicit rule does not end with a 939 recognized suffix, `$*' is set to the empty string for that rule. 940 941 `$?' is useful even in explicit rules when you wish to operate on 942only the dependencies that have changed. For example, suppose that an 943archive named `lib' is supposed to contain copies of several object 944files. This rule copies just the changed object files into the archive: 945 946 lib: foo.o bar.o lose.o win.o 947 ar r lib $? 948 949 Of the variables listed above, four have values that are single file 950names, and two have values that are lists of file names. These six have 951variants that get just the file's directory name or just the file name 952within the directory. The variant variables' names are formed by 953appending `D' or `F', respectively. These variants are semi-obsolete 954in GNU `make' since the functions `dir' and `notdir' can be used to get 955a similar effect (*note Functions for File Names: Filename Functions.). 956Note, however, that the `F' variants all omit the trailing slash which 957always appears in the output of the `dir' function. Here is a table of 958the variants: 959 960`$(@D)' 961 The directory part of the file name of the target, with the 962 trailing slash removed. If the value of `$@' is `dir/foo.o' then 963 `$(@D)' is `dir'. This value is `.' if `$@' does not contain a 964 slash. 965 966`$(@F)' 967 The file-within-directory part of the file name of the target. If 968 the value of `$@' is `dir/foo.o' then `$(@F)' is `foo.o'. `$(@F)' 969 is equivalent to `$(notdir $@)'. 970 971`$(*D)' 972`$(*F)' 973 The directory part and the file-within-directory part of the stem; 974 `dir' and `foo' in this example. 975 976`$(%D)' 977`$(%F)' 978 The directory part and the file-within-directory part of the target 979 archive member name. This makes sense only for archive member 980 targets of the form `ARCHIVE(MEMBER)' and is useful only when 981 MEMBER may contain a directory name. (*Note Archive Members as 982 Targets: Archive Members.) 983 984`$(<D)' 985`$(<F)' 986 The directory part and the file-within-directory part of the first 987 dependency. 988 989`$(^D)' 990`$(^F)' 991 Lists of the directory parts and the file-within-directory parts 992 of all dependencies. 993 994`$(?D)' 995`$(?F)' 996 Lists of the directory parts and the file-within-directory parts of 997 all dependencies that are newer than the target. 998 999 Note that we use a special stylistic convention when we talk about 1000these automatic variables; we write "the value of `$<'", rather than 1001"the variable `<'" as we would write for ordinary variables such as 1002`objects' and `CFLAGS'. We think this convention looks more natural in 1003this special case. Please do not assume it has a deep significance; 1004`$<' refers to the variable named `<' just as `$(CFLAGS)' refers to the 1005variable named `CFLAGS'. You could just as well use `$(<)' in place of 1006`$<'. 1007 1008 1009File: make.info, Node: Pattern Match, Next: Match-Anything Rules, Prev: Automatic, Up: Pattern Rules 1010 1011How Patterns Match 1012------------------ 1013 1014 A target pattern is composed of a `%' between a prefix and a suffix, 1015either or both of which may be empty. The pattern matches a file name 1016only if the file name starts with the prefix and ends with the suffix, 1017without overlap. The text between the prefix and the suffix is called 1018the "stem". Thus, when the pattern `%.o' matches the file name 1019`test.o', the stem is `test'. The pattern rule dependencies are turned 1020into actual file names by substituting the stem for the character `%'. 1021Thus, if in the same example one of the dependencies is written as 1022`%.c', it expands to `test.c'. 1023 1024 When the target pattern does not contain a slash (and it usually does 1025not), directory names in the file names are removed from the file name 1026before it is compared with the target prefix and suffix. After the 1027comparison of the file name to the target pattern, the directory names, 1028along with the slash that ends them, are added on to the dependency 1029file names generated from the pattern rule's dependency patterns and 1030the file name. The directories are ignored only for the purpose of 1031finding an implicit rule to use, not in the application of that rule. 1032Thus, `e%t' matches the file name `src/eat', with `src/a' as the stem. 1033When dependencies are turned into file names, the directories from the 1034stem are added at the front, while the rest of the stem is substituted 1035for the `%'. The stem `src/a' with a dependency pattern `c%r' gives 1036the file name `src/car'. 1037 1038 1039File: make.info, Node: Match-Anything Rules, Next: Canceling Rules, Prev: Pattern Match, Up: Pattern Rules 1040 1041Match-Anything Pattern Rules 1042---------------------------- 1043 1044 When a pattern rule's target is just `%', it matches any file name 1045whatever. We call these rules "match-anything" rules. They are very 1046useful, but it can take a lot of time for `make' to think about them, 1047because it must consider every such rule for each file name listed 1048either as a target or as a dependency. 1049 1050 Suppose the makefile mentions `foo.c'. For this target, `make' 1051would have to consider making it by linking an object file `foo.c.o', 1052or by C compilation-and-linking in one step from `foo.c.c', or by 1053Pascal compilation-and-linking from `foo.c.p', and many other 1054possibilities. 1055 1056 We know these possibilities are ridiculous since `foo.c' is a C 1057source file, not an executable. If `make' did consider these 1058possibilities, it would ultimately reject them, because files such as 1059`foo.c.o' and `foo.c.p' would not exist. But these possibilities are so 1060numerous that `make' would run very slowly if it had to consider them. 1061 1062 To gain speed, we have put various constraints on the way `make' 1063considers match-anything rules. There are two different constraints 1064that can be applied, and each time you define a match-anything rule you 1065must choose one or the other for that rule. 1066 1067 One choice is to mark the match-anything rule as "terminal" by 1068defining it with a double colon. When a rule is terminal, it does not 1069apply unless its dependencies actually exist. Dependencies that could 1070be made with other implicit rules are not good enough. In other words, 1071no further chaining is allowed beyond a terminal rule. 1072 1073 For example, the built-in implicit rules for extracting sources from 1074RCS and SCCS files are terminal; as a result, if the file `foo.c,v' does 1075not exist, `make' will not even consider trying to make it as an 1076intermediate file from `foo.c,v.o' or from `RCS/SCCS/s.foo.c,v'. RCS 1077and SCCS files are generally ultimate source files, which should not be 1078remade from any other files; therefore, `make' can save time by not 1079looking for ways to remake them. 1080 1081 If you do not mark the match-anything rule as terminal, then it is 1082nonterminal. A nonterminal match-anything rule cannot apply to a file 1083name that indicates a specific type of data. A file name indicates a 1084specific type of data if some non-match-anything implicit rule target 1085matches it. 1086 1087 For example, the file name `foo.c' matches the target for the pattern 1088rule `%.c : %.y' (the rule to run Yacc). Regardless of whether this 1089rule is actually applicable (which happens only if there is a file 1090`foo.y'), the fact that its target matches is enough to prevent 1091consideration of any nonterminal match-anything rules for the file 1092`foo.c'. Thus, `make' will not even consider trying to make `foo.c' as 1093an executable file from `foo.c.o', `foo.c.c', `foo.c.p', etc. 1094 1095 The motivation for this constraint is that nonterminal match-anything 1096rules are used for making files containing specific types of data (such 1097as executable files) and a file name with a recognized suffix indicates 1098some other specific type of data (such as a C source file). 1099 1100 Special built-in dummy pattern rules are provided solely to recognize 1101certain file names so that nonterminal match-anything rules will not be 1102considered. These dummy rules have no dependencies and no commands, and 1103they are ignored for all other purposes. For example, the built-in 1104implicit rule 1105 1106 %.p : 1107 1108exists to make sure that Pascal source files such as `foo.p' match a 1109specific target pattern and thereby prevent time from being wasted 1110looking for `foo.p.o' or `foo.p.c'. 1111 1112 Dummy pattern rules such as the one for `%.p' are made for every 1113suffix listed as valid for use in suffix rules (*note Old-Fashioned 1114Suffix Rules: Suffix Rules.). 1115 1116 1117File: make.info, Node: Canceling Rules, Prev: Match-Anything Rules, Up: Pattern Rules 1118 1119Canceling Implicit Rules 1120------------------------ 1121 1122 You can override a built-in implicit rule (or one you have defined 1123yourself) by defining a new pattern rule with the same target and 1124dependencies, but different commands. When the new rule is defined, the 1125built-in one is replaced. The new rule's position in the sequence of 1126implicit rules is determined by where you write the new rule. 1127 1128 You can cancel a built-in implicit rule by defining a pattern rule 1129with the same target and dependencies, but no commands. For example, 1130the following would cancel the rule that runs the assembler: 1131 1132 %.o : %.s 1133 1134 1135File: make.info, Node: Last Resort, Next: Suffix Rules, Prev: Pattern Rules, Up: Implicit Rules 1136 1137Defining Last-Resort Default Rules 1138================================== 1139 1140 You can define a last-resort implicit rule by writing a terminal 1141match-anything pattern rule with no dependencies (*note Match-Anything 1142Rules::.). This is just like any other pattern rule; the only thing 1143special about it is that it will match any target. So such a rule's 1144commands are used for all targets and dependencies that have no commands 1145of their own and for which no other implicit rule applies. 1146 1147 For example, when testing a makefile, you might not care if the 1148source files contain real data, only that they exist. Then you might 1149do this: 1150 1151 %:: 1152 touch $@ 1153 1154to cause all the source files needed (as dependencies) to be created 1155automatically. 1156 1157 You can instead define commands to be used for targets for which 1158there are no rules at all, even ones which don't specify commands. You 1159do this by writing a rule for the target `.DEFAULT'. Such a rule's 1160commands are used for all dependencies which do not appear as targets in 1161any explicit rule, and for which no implicit rule applies. Naturally, 1162there is no `.DEFAULT' rule unless you write one. 1163 1164 If you use `.DEFAULT' with no commands or dependencies: 1165 1166 .DEFAULT: 1167 1168the commands previously stored for `.DEFAULT' are cleared. Then `make' 1169acts as if you had never defined `.DEFAULT' at all. 1170 1171 If you do not want a target to get the commands from a match-anything 1172pattern rule or `.DEFAULT', but you also do not want any commands to be 1173run for the target, you can give it empty commands (*note Defining 1174Empty Commands: Empty Commands.). 1175 1176 You can use a last-resort rule to override part of another makefile. 1177*Note Overriding Part of Another Makefile: Overriding Makefiles. 1178 1179