diff options
| -rw-r--r-- | ChangeLog | 49 | ||||
| -rw-r--r-- | NEWS | 200 | ||||
| -rw-r--r-- | commands.c | 9 | ||||
| -rw-r--r-- | doc/make.texi | 1859 | ||||
| -rw-r--r-- | file.c | 14 | ||||
| -rw-r--r-- | job.c | 30 | ||||
| -rw-r--r-- | main.c | 9 | ||||
| -rw-r--r-- | make.h | 3 | ||||
| -rw-r--r-- | read.c | 41 | ||||
| -rw-r--r-- | remake.c | 6 | ||||
| -rw-r--r-- | tests/ChangeLog | 13 | ||||
| -rw-r--r-- | tests/scripts/functions/eval | 2 | ||||
| -rw-r--r-- | tests/scripts/misc/close_stdout | 2 | ||||
| -rw-r--r-- | tests/scripts/variables/special | 63 | ||||
| -rw-r--r-- | tests/test_driver.pl | 16 | ||||
| -rw-r--r-- | variable.c | 22 |
16 files changed, 1252 insertions, 1086 deletions
@@ -1,3 +1,11 @@ +2007-11-04 Paul Smith <psmith@gnu.org> + + * doc/make.texi: Convert references to "commands", "command + lines", and "command script" to "recipe". + * NEWS: Ditto. + * commands.c, file.c, job.c, remake.c, read.c, variable.c, main.c: + Ditto. + 2007-10-12 Eli Zaretskii <eliz@gnu.org> * variable.c (do_variable_definition): Allow $(SHELL) to expand to @@ -21,6 +29,47 @@ * w32/pathstuff.c (convert_Path_to_windows32): Handle quoted directories in Path. +2007-09-12 Paul Smith <psmith@gnu.org> + + * doc/make.texi: Applied wording cleanups from Savannah patch #6195. + Provided by Diego Biurrun <diego@biurrun.de> + (Complex Makefile): Remove .PHONY setting for tar: patch #6196. + Provided by Diego Biurrun <diego@biurrun.de> + +2007-09-11 Paul Smith <psmith@gnu.org> + + * doc/make.texi (Special Variables): Moved this into the "How to + Use Variables" chapter. Added a table entry for .RECIPEPREFIX. + (MAKEFILE_LIST) No longer a section; this was added into the + "Special Variables" section. + (Rule Introduction): Reference .RECIPEPREFIX. + (Simple Makefile): Ditto. + (Rule Syntax): Ditto. + (Command Syntax): Ditto. + (Error Messages): Ditto. + +2007-09-10 Paul Smith <psmith@gnu.org> + + * commands.c (print_commands): Don't print an extra line in the + command scripts. Prefix the command scripts with cmd_prefix, not \t. + + * read.c (construct_include_path): Add the full string to the cache; we + were chopping the last char. + + * NEWS: Announce the .RECIPEPREFIX special variable. + * variable.c (lookup_special_var): Rename from handle_special_var(). + (lookup_variable): Call the new name. + (set_special_var): New function: handle setting of special variables. + When setting .RECIPEPREFIX, reset the cmd_prefix global variable. + (do_variable_definition): Call it. + * make.h (RECIPEPREFIX_DEFAULT): Define the default command prefix char. + (RECIPEPREFIX_NAME): Define the command prefix special variable name. + * main.c (main): Create the .RECIPEPREFIX special variable. + * read.c (eval): Remove the cmd_prefix characters from the command + scripts here, so they're not stored in the commands array at all, + rather than waiting and stripping them out during command construction. + * job.c (construct_command_argv_internal): Don't skip cmd_prefix here. + 2007-08-15 Paul Smith <psmith@gnu.org> * doc/make.texi (GNU Free Documentation License): The fdl.texi @@ -14,6 +14,13 @@ Version 3.81.90 * Compiling GNU make now requires a conforming ISO C 1989 compiler and standard runtime library. +* New special variable: .RECIPEPREFIX allows you to reset the recipe + introduction character from the default (TAB) to something else. The + first character of this variable value is the new recipe introduction + character. If the variable is set to the empty string, TAB is used + again. It can be set and reset at will; rules will be parsed + according to the current value. + Version 3.81 @@ -50,13 +57,14 @@ Version 3.81 of this SysV feature you will need to update them. * WARNING: Backward-incompatibility! + In order to comply with POSIX, the way in which GNU make processes - backslash-newline sequences in command strings has changed. If your - makefiles use backslash-newline sequences inside of single-quoted - strings in command scripts you will be impacted by this change. See - the GNU make manual subsection "Splitting Command Lines" (node - "Splitting Lines"), in section "Command Syntax", chapter "Writing the - Commands in Rules", for details. + backslash-newline sequences in recipes has changed. If your makefiles + use backslash-newline sequences inside of single-quoted strings in + recipes you will be impacted by this change. See the GNU make manual + subsection "Splitting Recipe Lines" (node "Splitting Lines"), in + section "Recipe Syntax", chapter "Writing Recipe in Rules", for + details. * WARNING: Backward-incompatibility! Some previous versions of GNU make had a bug where "#" in a function @@ -65,7 +73,7 @@ Version 3.81 fixed: if your makefile uses "\#" in a function invocation the backslash is now preserved, so you'll need to remove it. -* New command-line option: -L (--check-symlink-times). On systems that +* New command line option: -L (--check-symlink-times). On systems that support symbolic links, if this option is given then GNU make will use the most recent modification time of any symbolic links that are used to resolve target files. The default behavior remains as it @@ -126,7 +134,7 @@ Version 3.81 argument if all arguments are true. * Changes made for POSIX compatibility: - - Only touch targets (under -t) if they have at least one command. + - Only touch targets (under -t) if they have a recipe. - Setting the SHELL make variable does NOT change the value of the SHELL environment variable given to programs invoked by make. As an enhancement to POSIX, if you export the make variable SHELL then @@ -199,7 +207,7 @@ Version 3.80 expanded it returns a complete list of variable names defined by all makefiles at that moment. -* A new command-line option is defined, -B or --always-make. If +* A new command line option is defined, -B or --always-make. If specified GNU make will consider all targets out-of-date even if they would otherwise not be. @@ -480,7 +488,7 @@ Version 3.72 * The `MAKEFLAGS' variable (in the environment or in a makefile) can now contain variable definitions itself; these are treated just like - command-line variable definitions. Make will automatically insert any + command line variable definitions. Make will automatically insert any variable definitions from the environment value of `MAKEFLAGS' or from the command line, into the `MAKEFLAGS' value exported to children. The `MAKEOVERRIDES' variable previously included in the value of `$(MAKE)' @@ -489,8 +497,8 @@ Version 3.72 in the environment when its size is limited. * If `.DELETE_ON_ERROR' appears as a target, Make will delete the target of - a rule if it has changed when its commands exit with a nonzero status, - just as when the commands get a signal. + a rule if it has changed when its recipe exits with a nonzero status, + just as when the recipe gets a signal. * The automatic variable `$+' is new. It lists all the dependencies like `$^', but preserves duplicates listed in the makefile. This is useful @@ -500,9 +508,9 @@ Version 3.72 * You can now specify the `.IGNORE' and `.SILENT' special targets with dependencies to limit their effects to those files. If a file appears as a dependency of `.IGNORE', then errors will be ignored while running the - commands to update that file. Likewise if a file appears as a dependency - of `.SILENT', then the commands to update that file will not be printed - before they are run. (This change was made to conform to POSIX.2.) + recipe to update that file. Likewise if a file appears as a dependency + of `.SILENT', then the recipe to update that file will not be printed + before it is run. (This change was made to conform to POSIX.2.) Version 3.71 @@ -550,22 +558,22 @@ Version 3.69 Make, and a string describing the remote job support compiled in (if any). Thus the value (in this release) is something like `3.69' or `3.69-Customs'. -* Commands in an invocation of the `shell' function are no longer run with - a modified environment like target commands are. As in versions before +* Commands in an invocation of the `shell' function are no longer run + with a modified environment like recipes are. As in versions before 3.68, they now run with the environment that `make' started with. We have reversed the change made in version 3.68 because it turned out to cause a paradoxical situation in cases like: export variable = $(shell echo value) - When Make attempted to put this variable in the environment for a target - command, it would try expand the value by running the shell command + When Make attempted to put this variable in the environment for a + recipe, it would try expand the value by running the shell command `echo value'. In version 3.68, because it constructed an environment for that shell command in the same way, Make would begin to go into an infinite loop and then get a fatal error when it detected the loop. -* The commands given for `.DEFAULT' are now used for phony targets with no - commands. +* The recipe given for `.DEFAULT' is now used for phony targets with no + recipe. Version 3.68 @@ -589,8 +597,8 @@ Version 3.68 no error (not even a warning) for a nonexistent makefile. * Commands in an invocation of the `shell' function are now run with a - modified environment like target commands are, so you can use `export' et - al to set up variables for them. They used to run with the environment + modified environment like recipes are, so you can use `export' et al + to set up variables for them. They used to run with the environment that `make' started with. Version 3.66 @@ -634,8 +642,8 @@ Version 3.63 change directory, and recursive use of Make, now set `-w' automatically. * Multiple double-colon rules for the same target will no longer have their - commands run simultaneously under -j, as this could result in the two - commands trying to change the file at the same time and interfering with + recipes run simultaneously under -j, as this could result in the two + recipes trying to change the file at the same time and interfering with one another. * The `SHELL' variable is now never taken from the environment. @@ -647,7 +655,7 @@ Version 3.63 that tells you what all the options are and what they do. Try `make --help'. * There are two new directives: `export' and `unexport'. All variables are - no longer automatically put into the environments of the commands that + no longer automatically put into the environments of the recipe lines that Make runs. Instead, only variables specified on the command line or in the environment are exported by default. To export others, use: export VARIABLE @@ -662,8 +670,8 @@ Version 3.63 to get the old behavior. See the node `Variables/Recursion' in the manual for a full description. -* The commands from the `.DEFAULT' special target are only applied to - targets which have no rules at all, not all targets with no commands. +* The recipe from the `.DEFAULT' special target is only applied to + targets which have no rules at all, not all targets with no recipe. This change was made for compatibility with Unix make. * All fatal error messages now contain `***', so they are easy to find in @@ -715,8 +723,8 @@ Version 3.61 * Built-in rules for C++ source files with the `.C' suffix. We still recommend that you use `.cc' instead. -* If commands are given too many times for a single target, - the last set given is used, and a warning message is printed. +* If a recipe is given too many times for a single target, the last one + given is used, and a warning message is printed. * Error messages about makefiles are in standard GNU error format, so C-x ` in Emacs works on them. @@ -733,7 +741,7 @@ Version 3.60 * Archives on AIX now supposedly work. -* When the commands specified for .DEFAULT are used to update a target, +* When the recipes specified for .DEFAULT are used to update a target, the $< automatic variable is given the same value as $@ for that target. This is how Unix make behaves, and this behavior is mandated by POSIX.2. @@ -758,18 +766,18 @@ Version 3.57 Version 3.55 -* There is now a Unix man page for GNU Make. It is certainly not a replacement -for the Texinfo manual, but it documents the basic functionality and the -switches. For full documentation, you should still read the Texinfo manual. -Thanks to Dennis Morse of Stanford University for contributing the initial -version of this. +* There is now a Unix man page for GNU Make. It is certainly not a + replacement for the Texinfo manual, but it documents the basic + functionality and the switches. For full documentation, you should + still read the Texinfo manual. Thanks to Dennis Morse of Stanford + University for contributing the initial version of this. -* Variables which are defined by default (e.g., `CC') will no longer be put -into the environment for child processes. (If these variables are reset by the -environment, makefiles, or the command line, they will still go into the -environment.) +* Variables which are defined by default (e.g., `CC') will no longer be + put into the environment for child processes. (If these variables are + reset by the environment, makefiles, or the command line, they will + still go into the environment.) -* Makefiles which have commands but no dependencies (and thus are always +* Makefiles which have recipes but no dependencies (and thus are always considered out of date and in need of remaking), will not be remade (if they were being remade only because they were makefiles). This means that GNU Make will no longer go into an infinite loop when fed the makefiles that @@ -781,45 +789,45 @@ pathname (instead of a `%' pattern). Version 3.51 * When removing intermediate files, only one `rm' command line is printed, -listing all file names. + listing all file names. * There are now automatic variables `$(^D)', `$(^F)', `$(?D)', and `$(?F)'. -These are the directory-only and file-only versions of `$^' and `$?'. + These are the directory-only and file-only versions of `$^' and `$?'. * Library dependencies given as `-lNAME' will use "libNAME.a" in the current -directory if it exists. + directory if it exists. * The automatic variable `$($/)' is no longer defined. -* Leading `+' characters on a command line make that line be executed even -under -n, -t, or -q (as if the line contained `$(MAKE)'). +* Leading `+' characters on a recipe line make that line be executed even + under -n, -t, or -q (as if the line contained `$(MAKE)'). -* For command lines containing `$(MAKE)', `${MAKE}', or leading `+' characters, -only those lines are executed, not their entire rules. -(This is how Unix make behaves for lines containing `$(MAKE)' or `${MAKE}'.) +* For recipe lines containing `$(MAKE)', `${MAKE}', or leading `+' characters, + only those lines are executed, not the entire recipe. + (This is how Unix make behaves for lines containing `$(MAKE)' or `${MAKE}'.) Version 3.50 * Filenames in rules will now have ~ and ~USER expanded. * The `-p' output has been changed so it can be used as a makefile. -(All information that isn't specified by makefiles is prefaced with comment -characters.) + (All information that isn't specified by makefiles is prefaced with comment + characters.) Version 3.49 * The % character can be quoted with backslash in implicit pattern rules, -static pattern rules, `vpath' directives, and `patsubst', `filter', and -`filter-out' functions. A warning is issued if a `vpath' directive's -pattern contains no %. + static pattern rules, `vpath' directives, and `patsubst', `filter', and + `filter-out' functions. A warning is issued if a `vpath' directive's + pattern contains no %. * The `wildcard' variable expansion function now expands ~ and ~USER. -* Messages indicating failed commands now contain the target name: +* Messages indicating failed recipe lines now contain the target name: make: *** [target] Error 1 * The `-p' output format has been changed somewhat to look more like -makefile rules and to give all information that Make has about files. + makefile rules and to give all information that Make has about files. Version 3.48 @@ -828,49 +836,49 @@ Version 3.47 * The `-l' switch with no argument removes any previous load-average limit. * When the `-w' switch is in effect, and Make has updated makefiles, -it will write a `Leaving directory' messagfe before re-executing itself. -This makes the `directory change tracking' changes to Emacs's compilation -commands work properly. + it will write a `Leaving directory' message before re-executing itself. + This makes the `directory change tracking' changes to Emacs's compilation + commands work properly. Version 3.46 * The automatic variable `$*' is now defined for explicit rules, -as it is in Unix make. + as it is in Unix make. Version 3.45 * The `-j' switch is now put in the MAKEFLAGS and MFLAGS variables when -specified without an argument (indicating infinite jobs). -The `-l' switch is not always put in the MAKEFLAGS and MFLAGS variables. + specified without an argument (indicating infinite jobs). + The `-l' switch is not always put in the MAKEFLAGS and MFLAGS variables. -* Make no longer checks hashed directories after running commands. -The behavior implemented in 3.41 caused too much slowdown. +* Make no longer checks hashed directories after running recipes. + The behavior implemented in 3.41 caused too much slowdown. Version 3.44 * A dependency is NOT considered newer than its dependent if -they have the same modification time. The behavior implemented -in 3.43 conflicts with RCS. + they have the same modification time. The behavior implemented + in 3.43 conflicts with RCS. Version 3.43 * Dependency loops are no longer fatal errors. * A dependency is considered newer than its dependent if -they have the same modification time. + they have the same modification time. Version 3.42 * The variables F77 and F77FLAGS are now set by default to $(FC) and -$(FFLAGS). Makefiles designed for System V make may use these variables in -explicit rules and expect them to be set. Unfortunately, there is no way to -make setting these affect the Fortran implicit rules unless FC and FFLAGS -are not used (and these are used by BSD make). + $(FFLAGS). Makefiles designed for System V make may use these variables in + explicit rules and expect them to be set. Unfortunately, there is no way to + make setting these affect the Fortran implicit rules unless FC and FFLAGS + are not used (and these are used by BSD make). Version 3.41 -* Make now checks to see if its hashed directories are changed by commands. -Other makes that hash directories (Sun, 4.3 BSD) don't do this. +* Make now checks to see if its hashed directories are changed by recipes. + Other makes that hash directories (Sun, 4.3 BSD) don't do this. Version 3.39 @@ -879,7 +887,7 @@ Version 3.39 Version 3.32 * A file beginning with a dot can be the default target if it also contains -a slash (e.g., `../bin/foo'). (Unix make allows this as well.) + a slash (e.g., `../bin/foo'). (Unix make allows this as well.) Version 3.31 @@ -888,8 +896,8 @@ Version 3.31 * Yet more USG stuff. * Minimal support for Microport System V (a 16-bit machine and a -brain-damaged compiler). This has even lower priority than other USG -support, so if it gets beyond trivial, I will take it out completely. + brain-damaged compiler). This has even lower priority than other USG + support, so if it gets beyond trivial, I will take it out completely. * Revamped default implicit rules (not much visible change). @@ -900,13 +908,13 @@ Version 3.30 * Improved support for USG and HPUX (hopefully). * A variable reference like `$(foo:a=b)', if `a' contains a `%', is -equivalent to `$(patsubst a,b,$(foo))'. + equivalent to `$(patsubst a,b,$(foo))'. -* Defining .DEFAULT with no deps or commands clears its commands. +* Defining .DEFAULT with no deps or recipe clears its recipe. -* New default implicit rules for .S (cpp, then as), and .sh (copy and make -executable). All default implicit rules that use cpp (even indirectly), use -$(CPPFLAGS). +* New default implicit rules for .S (cpp, then as), and .sh (copy and + make executable). All default implicit rules that use cpp (even + indirectly), use $(CPPFLAGS). Version 3.29 @@ -915,21 +923,21 @@ Version 3.29 Version 3.28 * New option: "-l LOAD" says not to start any new jobs while others are -running if the load average is not below LOAD (a floating-point number). + running if the load average is not below LOAD (a floating-point number). * There is support in place for implementations of remote command execution -in Make. See the file remote.c. + in Make. See the file remote.c. Version 3.26 * No more than 10 directories will be kept open at once. -(This number can be changed by redefining MAX_OPEN_DIRECTORIES in dir.c.) + (This number can be changed by redefining MAX_OPEN_DIRECTORIES in dir.c.) Version 3.25 * Archive files will have their modification times recorded before doing -anything that might change their modification times by updating an archive -member. + anything that might change their modification times by updating an archive + member. Version 3.20 @@ -938,25 +946,25 @@ Version 3.20 Version 3.19 * The recursion level indications in error messages are much shorter than -they were in version 3.14. + they were in version 3.14. Version 3.18 * Leading spaces before directives are ignored (as documented). * Included makefiles can determine the default goal target. -(System V Make does it this way, so we are being compatible). + (System V Make does it this way, so we are being compatible). Version 3.14. * Variables that are defaults built into Make will not be put in the -environment for children. This just saves some environment space and, -except under -e, will be transparent to sub-makes. + environment for children. This just saves some environment space and, + except under -e, will be transparent to sub-makes. * Error messages from sub-makes will indicate the level of recursion. * Hopefully some speed-up for large directories due to a change in the -directory hashing scheme. + directory hashing scheme. * One child will always get a standard input that is usable. @@ -965,7 +973,7 @@ directory hashing scheme. Version 3.13. * Count parentheses inside expansion function calls so you can -have nested calls: `$(sort $(foreach x,a b,$(x)))'. + have nested calls: `$(sort $(foreach x,a b,$(x)))'. Version 3.12. @@ -981,15 +989,15 @@ Version 3.12. * Makefiles will be updated and re-read if necessary. -* Can now run several commands at once (parallelism), -j option. +* Can now run several recipes at once (parallelism), -j option. * Error messages will contain the level of Make recursion, if any. * The `MAKEFLAGS' and `MFLAGS' variables will be scanned for options after -makefiles are read. + makefiles are read. -* A double-colon rule with no dependencies will always have its commands run. -(This is how both the BSD and System V versions of Make do it.) +* A double-colon rule with no dependencies will always have its recipe run. + (This is how both the BSD and System V versions of Make do it.) Version 3.05 @@ -596,7 +596,7 @@ print_commands (const struct commands *cmds) { const char *s; - fputs (_("# commands to execute"), stdout); + fputs (_("# recipe to execute"), stdout); if (cmds->fileinfo.filenm == 0) puts (_(" (built-in):")); @@ -609,15 +609,12 @@ print_commands (const struct commands *cmds) { const char *end; - while (isspace ((unsigned char)*s)) - ++s; - end = strchr (s, '\n'); if (end == 0) end = s + strlen (s); - printf ("\t%.*s\n", (int) (end - s), s); + printf ("%c%.*s\n", cmd_prefix, (int) (end - s), s); - s = end; + s = end + (end[0] == '\n'); } } diff --git a/doc/make.texi b/doc/make.texi index c30e794..f18a254 100644 --- a/doc/make.texi +++ b/doc/make.texi @@ -91,7 +91,7 @@ Cover art by Etienne Suvasa. * Introduction:: An introduction to @code{make}. * Makefiles:: Makefiles tell @code{make} what to do. * Rules:: Rules describe when a file must be remade. -* Commands:: Commands say how to remake a file. +* Recipes:: Recipes say how to remake a file. * Using Variables:: You can use variables to avoid repetition. * Conditionals:: Use or ignore parts of the makefile based on the values of variables. @@ -118,19 +118,19 @@ Cover art by Etienne Suvasa. Overview of @code{make} -* Preparing:: Preparing and Running Make -* Reading:: On Reading this Text -* Bugs:: Problems and Bugs +* Preparing:: Preparing and running make +* Reading:: On reading this text +* Bugs:: Problems and bugs An Introduction to Makefiles * Rule Introduction:: What a rule looks like. -* Simple Makefile:: A Simple Makefile -* How Make Works:: How @code{make} Processes This Makefile -* Variables Simplify:: Variables Make Makefiles Simpler -* make Deduces:: Letting @code{make} Deduce the Commands -* Combine By Prerequisite:: Another Style of Makefile -* Cleanup:: Rules for Cleaning the Directory +* Simple Makefile:: A simple makefile +* How Make Works:: How @code{make} processes this makefile +* Variables Simplify:: Variables make makefiles simpler +* make Deduces:: Letting @code{make} deduce the recipe +* Combine By Prerequisite:: Another style of makefile +* Cleanup:: Rules for cleaning the directory Writing Makefiles @@ -138,8 +138,6 @@ Writing Makefiles * Makefile Names:: How to name your makefile. * Include:: How one makefile can use another makefile. * MAKEFILES Variable:: The environment can specify extra makefiles. -* MAKEFILE_LIST Variable:: Discover which makefiles have been read. -* Special Variables:: Other special variables. * Remaking Makefiles:: How makefiles get remade. * Overriding Makefiles:: How to override part of one makefile with another makefile. @@ -154,7 +152,7 @@ Writing Rules * Wildcards:: Using wildcard characters such as `*'. * Directory Search:: Searching other directories for source files. * Phony Targets:: Using a target that is not a real file's name. -* Force Targets:: You can use a target without commands +* Force Targets:: You can use a target without a recipe or prerequisites to mark other targets as phony. * Empty Targets:: When only the date matters and the @@ -184,7 +182,7 @@ Searching Directories for Prerequisites * Selective Search:: Specifying a search path for a specified class of names. * Search Algorithm:: When and how search paths are applied. -* Commands/Search:: How to write shell commands that work together +* Recipes/Search:: How to write recipes that work together with search paths. * Implicit/Search:: How search paths affect implicit rules. * Libraries/Search:: Directory search for link libraries. @@ -194,27 +192,27 @@ Static Pattern Rules * Static Usage:: The syntax of static pattern rules. * Static versus Implicit:: When are they better than implicit rules? -Writing the Commands in Rules +Writing Recipes in Rules -* Command Syntax:: Command syntax features and pitfalls. -* Echoing:: How to control when commands are echoed. -* Execution:: How commands are executed. -* Parallel:: How commands can be executed in parallel. -* Errors:: What happens after a command execution error. -* Interrupts:: What happens when a command is interrupted. +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. * Recursion:: Invoking @code{make} from makefiles. -* Sequences:: Defining canned sequences of commands. -* Empty Commands:: Defining useful, do-nothing commands. +* Sequences:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. -Command Syntax +Recipe Syntax -* Splitting Lines:: Breaking long command lines for readability. -* Variables in Commands:: Using @code{make} variables in commands. +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using @code{make} variables in recipes. -Command Execution +Recipe Execution * Choosing the Shell:: How @code{make} chooses the shell used - to run commands. + to run recipes. Recursive Use of @code{make} @@ -242,6 +240,7 @@ How to Use Variables basis. * Pattern-specific:: Target-specific variable values can be applied to a group of targets that match a pattern. +* Special Variables:: Variables with special meaning or behavior. Advanced Features for Reference to Variables @@ -276,7 +275,7 @@ How to Run @code{make} * Goals:: How to use goal arguments to specify which parts of the makefile to use. * Instead of Execution:: How to use mode flags to specify what - kind of thing to do with the commands + kind of thing to do with the recipes in the makefile other than simply execute them. * Avoiding Compilation:: How to avoid recompiling certain files. @@ -289,12 +288,12 @@ How to Run @code{make} Using Implicit Rules * Using Implicit:: How to use an existing implicit rule - to get the commands for updating a file. + to get the recipe for updating a file. * Catalogue of Rules:: A list of built-in implicit rules. * Implicit Variables:: How to change what predefined rules do. * Chained Rules:: How to use a chain of implicit rules. * Pattern Rules:: How to define new implicit rules. -* Last Resort:: How to define commands for rules which +* Last Resort:: How to define a recipe for rules which cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. * Implicit Rule Search:: The precise algorithm for applying @@ -305,7 +304,7 @@ Defining and Redefining Pattern Rules * Pattern Intro:: An introduction to pattern rules. * Pattern Examples:: Examples of pattern rules. * Automatic Variables:: How to use automatic variables in the - commands of implicit rules. + recipe of implicit rules. * Pattern Match:: How patterns match. * Match-Anything Rules:: Precautions you should take prior to defining rules that can match any @@ -377,7 +376,7 @@ make suffices to perform all necessary recompilations. The @code{make} program uses the makefile data base and the last-modification times of the files to decide which of the files need to be updated. For each of those files, it -issues the commands recorded in the data base. +issues the recipes recorded in the data base. You can provide command line arguments to @code{make} to control which files should be recompiled, or how. @xref{Running, ,How to Run @@ -431,7 +430,7 @@ send us the makefile and the exact results @code{make} gave you, including any error or warning messages. Please don't paraphrase these messages: it's best to cut and paste them into your report. When generating this small makefile, be sure to not use any non-free -or unusual tools in your commands: you can almost always emulate what +or unusual tools in your recipes: you can almost always emulate what such a tool would do with simple shell commands. Finally, be sure to explain what you expected to occur; this will help us decide whether the problem was really in the documentation. @@ -489,7 +488,7 @@ together to produce the new executable editor. * Simple Makefile:: A Simple Makefile * How Make Works:: How @code{make} Processes This Makefile * Variables Simplify:: Variables Make Makefiles Simpler -* make Deduces:: Letting @code{make} Deduce the Commands +* make Deduces:: Letting @code{make} Deduce the Recipes * Combine By Prerequisite:: Another Style of Makefile * Cleanup:: Rules for Cleaning the Directory @end menu @@ -505,11 +504,11 @@ A simple makefile consists of ``rules'' with the following shape: @cindex targets, introduction to @cindex prerequisites, introduction to -@cindex commands, introduction to +@cindex recipes, introduction to @example @group @var{target} @dots{} : @var{prerequisites} @dots{} - @var{command} + @var{recipe} @dots{} @dots{} @end group @@ -524,20 +523,23 @@ A @dfn{prerequisite} is a file that is used as input to create the target. A target often depends on several files. @cindex tabs in rules -A @dfn{command} is an action that @code{make} carries out. -A rule may have more than one command, each on its own line. +A @dfn{recipe} is an action that @code{make} carries out. +A recipe may have more than one command, each on its own line. @strong{Please note:} you need to put a tab character at the beginning of -every command line! This is an obscurity that catches the unwary. +every command line! This is an obscurity that catches the unwary. If +you prefer to prefix your recipes with a character other than tab, +you can set the @code{.CMDPREFIX} variable to an alternate character +(@pxref{Special Variables}). -Usually a command is in a rule with prerequisites and serves to create a +Usually a recipe is in a rule with prerequisites and serves to create a target file if any of the prerequisites change. However, the rule that -specifies commands for the target need not have prerequisites. For +specifies a recipe for the target need not have prerequisites. For example, the rule containing the delete command associated with the target @samp{clean} does not have prerequisites. A @dfn{rule}, then, explains how and when to remake certain files which are the targets of the particular rule. @code{make} carries out -the commands on the prerequisites to create or update the target. A +the recipe on the prerequisites to create or update the target. A rule can also explain how and when to carry out an action. @xref{Rules, , Writing Rules}. @@ -614,7 +616,7 @@ In the example makefile, the targets include the executable file @samp{edit}, and the object files @samp{main.o} and @samp{kbd.o}. The prerequisites are files such as @samp{main.c} and @samp{defs.h}. In fact, each @samp{.o} file is both a target and a prerequisite. -Commands include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. +Recipes include @w{@samp{cc -c main.c}} and @w{@samp{cc -c kbd.c}}. When a target is a file, it needs to be recompiled or relinked if any of its prerequisites change. In addition, any prerequisites that are @@ -623,28 +625,29 @@ example, @file{edit} depends on each of the eight object files; the object file @file{main.o} depends on the source file @file{main.c} and on the header file @file{defs.h}. -A shell command follows each line that contains a target and -prerequisites. These shell commands say how to update the target file. -A tab character must come at the beginning of every command line to -distinguish command lines from other lines in the makefile. (Bear in -mind that @code{make} does not know anything about how the commands -work. It is up to you to supply commands that will update the target -file properly. All @code{make} does is execute the commands in the rule -you have specified when the target file needs to be updated.) -@cindex shell command +A recipe may follow each line that contains a target and +prerequisites. These recipes say how to update the target file. A +tab character (or whatever character is specified by the +@code{.CMDPREFIX} variable; @pxref{Special Variables}) must come at +the beginning of every line in the recipe to distinguish recipes from +other lines in the makefile. (Bear in mind that @code{make} does not +know anything about how the recipes work. It is up to you to supply +recipes that will update the target file properly. All @code{make} +does is execute the commands in the recipe you have specified when the +target file needs to be updated.)@refill +@cindex recipe The target @samp{clean} is not a file, but merely the name of an -action. Since you -normally -do not want to carry out the actions in this rule, @samp{clean} is not a prerequisite of any other rule. +action. Since you normally do not want to carry out the actions in +this rule, @samp{clean} is not a prerequisite of any other rule. Consequently, @code{make} never does anything with it unless you tell -it specifically. Note that this rule not only is not a prerequisite, it -also does not have any prerequisites, so the only purpose of the rule -is to run the specified commands. Targets that do not refer to files -but are just actions are called @dfn{phony targets}. @xref{Phony -Targets}, for information about this kind of target. @xref{Errors, , -Errors in Commands}, to see how to cause @code{make} to ignore errors -from @code{rm} or any other command. +it specifically. Note that this rule not only is not a prerequisite, +it also does not have any prerequisites, so the only purpose of the +rule is to run the specified recipe. Targets that do not refer to +files but are just actions are called @dfn{phony targets}. +@xref{Phony Targets}, for information about this kind of target. +@xref{Errors, , Errors in Recipes}, to see how to cause @code{make} +to ignore errors from @code{rm} or any other command. @cindex @code{clean} target @cindex @code{rm} (shell command) @@ -792,22 +795,22 @@ clean : @end example @node make Deduces, Combine By Prerequisite, Variables Simplify, Introduction -@section Letting @code{make} Deduce the Commands -@cindex deducing commands (implicit rules) +@section Letting @code{make} Deduce the Recipes +@cindex deducing recipes (implicit rules) @cindex implicit rule, introduction to @cindex rule, implicit, introduction to -It is not necessary to spell out the commands for compiling the individual +It is not necessary to spell out the recipes for compiling the individual C source files, because @code{make} can figure them out: it has an @dfn{implicit rule} for updating a @samp{.o} file from a correspondingly named @samp{.c} file using a @samp{cc -c} command. For example, it will -use the command @samp{cc -c main.c -o main.o} to compile @file{main.c} into -@file{main.o}. We can therefore omit the commands from the rules for the +use the recipe @samp{cc -c main.c -o main.o} to compile @file{main.c} into +@file{main.o}. We can therefore omit the recipes from the rules for the object files. @xref{Implicit Rules, ,Using Implicit Rules}.@refill When a @samp{.c} file is used automatically in this way, it is also automatically added to the list of prerequisites. We can therefore omit -the @samp{.c} files from the prerequisites, provided we omit the commands. +the @samp{.c} files from the prerequisites, provided we omit the recipe. Here is the entire example, with both of these changes, and a variable @code{objects} as suggested above: @@ -838,7 +841,7 @@ clean : @noindent This is how we would write the makefile in actual practice. (The complications associated with @samp{clean} are described elsewhere. -See @ref{Phony Targets}, and @ref{Errors, ,Errors in Commands}.) +See @ref{Phony Targets}, and @ref{Errors, ,Errors in Recipes}.) Because implicit rules are so convenient, they are important. You will see them used frequently.@refill @@ -911,7 +914,7 @@ clean : This prevents @code{make} from getting confused by an actual file called @file{clean} and causes it to continue in spite of errors from @code{rm}. (See @ref{Phony Targets}, and @ref{Errors, ,Errors in -Commands}.) +Recipes}.) @noindent A rule such as this should not be placed at the beginning of the @@ -936,8 +939,6 @@ reading a data base called the @dfn{makefile}. * Makefile Names:: How to name your makefile. * Include:: How one makefile can use another makefile. * MAKEFILES Variable:: The environment can specify extra makefiles. -* MAKEFILE_LIST Variable:: Discover which makefiles have been read. -* Special Variables:: Other special variables. * Remaking Makefiles:: How makefiles get remade. * Overriding Makefiles:: How to override part of one makefile with another makefile. @@ -960,7 +961,7 @@ length in later chapters.@refill An @dfn{explicit rule} says when and how to remake one or more files, called the rule's @dfn{targets}. It lists the other files that the targets depend on, called the @dfn{prerequisites} of the target, and -may also give commands to use to create or update the targets. +may also give a recipe to use to create or update the targets. @xref{Rules, ,Writing Rules}. @cindex rule, implicit, definition of @@ -968,7 +969,7 @@ may also give commands to use to create or update the targets. @item An @dfn{implicit rule} says when and how to remake a class of files based on their names. It describes how a target may depend on a file -with a name similar to the target and gives commands to create or +with a name similar to the target and gives a recipe to create or update such a target. @xref{Implicit Rules, ,Using Implicit Rules}. @cindex variable definition @@ -981,8 +982,8 @@ Make Makefiles Simpler}). @cindex directive @item -A @dfn{directive} is a command for @code{make} to do something special while -reading the makefile. These include: +A @dfn{directive} is an instruction for @code{make} to do something +special while reading the makefile. These include: @itemize @bullet @item @@ -1013,16 +1014,15 @@ You cannot use comments within variable references or function calls: any instance of @code{#} will be treated literally (rather than as the start of a comment) inside a variable reference or function call. -Within a command script (if the line begins with a TAB character) the -entire line is passed to the shell, just as with any other line that -begins with a TAB. The shell decides how to interpret the text: -whether or not this is a comment is up to the shell. +Comments within a recipe are passed to the shell, just as with any +other recipe text. The shell decides how to interpret it: whether or +not this is a comment is up to the shell. Within a @code{define} directive, comments are not ignored during the definition of the variable, but rather kept intact in the value of the variable. When the variable is expanded they will either be treated -as @code{make} comments or as command script text, depending on the -context in which the variable is evaluated. +as @code{make} comments or as recipe text, depending on the context in +which the variable is evaluated. @end itemize @node Makefile Names, Include, Makefile Contents, Makefiles @@ -1095,8 +1095,9 @@ include @var{filenames}@dots{} @cindex wildcard, in @code{include} Extra spaces are allowed and ignored at the beginning of the line, but -a tab is not allowed. (If the line begins with a tab, it will be -considered a command line.) Whitespace is required between +the first character must not be a tab (or the value of +@code{.CMDPREFIX})---if the line begins with a tab, it will be +considered a recipe line. Whitespace is required between @code{include} and the file names, and between file names; extra whitespace is ignored there and at the end of the directive. A comment starting with @samp{#} is allowed at the end of the line. If @@ -1181,7 +1182,7 @@ error (not even a warning) if any of the @var{filenames} do not exist. For compatibility with some other @code{make} implementations, @code{sinclude} is another name for @w{@code{-include}}. -@node MAKEFILES Variable, MAKEFILE_LIST Variable, Include, Makefiles +@node MAKEFILES Variable, Remaking Makefiles, Include, Makefiles @section The Variable @code{MAKEFILES} @cindex makefile, and @code{MAKEFILES} variable @cindex including (@code{MAKEFILES} variable) @@ -1211,187 +1212,7 @@ This is a very bad idea, because such makefiles will fail to work if run by anyone else. It is much better to write explicit @code{include} directives in the makefiles. @xref{Include, , Including Other Makefiles}. -@node MAKEFILE_LIST Variable, Special Variables, MAKEFILES Variable, Makefiles -@comment node-name, next, previous, up -@section The Variable @code{MAKEFILE_LIST} -@cindex makefiles, and @code{MAKEFILE_LIST} variable -@cindex including (@code{MAKEFILE_LIST} variable) -@vindex MAKEFILE_LIST - -As @code{make} reads various makefiles, including any obtained from the -@code{MAKEFILES} variable, the command line, the default files, or -from @code{include} directives, their names will be automatically -appended to the @code{MAKEFILE_LIST} variable. They are added right -before @code{make} begins to parse them. - -This means that if the first thing a makefile does is examine the last -word in this variable, it will be the name of the current makefile. -Once the current makefile has used @code{include}, however, the last -word will be the just-included makefile. - -If a makefile named @code{Makefile} has this content: - -@example -@group -name1 := $(lastword $(MAKEFILE_LIST)) - -include inc.mk - -name2 := $(lastword $(MAKEFILE_LIST)) - -all: - @@echo name1 = $(name1) - @@echo name2 = $(name2) -@end group -@end example - -@noindent -then you would expect to see this output: - -@example -@group -name1 = Makefile -name2 = inc.mk -@end group -@end example - -@xref{Text Functions}, for more information on the @code{lastword} -function used above. @xref{Flavors, The Two Flavors of Variables}, -for more information on simply-expanded (@code{:=}) variable -definitions. - -@node Special Variables, Remaking Makefiles, MAKEFILE_LIST Variable, Makefiles -@comment node-name, next, previous, up -@section Other Special Variables -@cindex makefiles, and special variables -@cindex special variables - -GNU @code{make} also supports other special variables. Unless -otherwise documented here, these values lose their special properties -if they are set by a makefile or on the command line. - -@table @code - -@vindex .DEFAULT_GOAL @r{(define default goal)} -@item .DEFAULT_GOAL -Sets the default goal to be used if no targets were specified on the -command line (@pxref{Goals, , Arguments to Specify the Goals}). The -@code{.DEFAULT_GOAL} variable allows you to discover the current -default goal, restart the default goal selection algorithm by clearing -its value, or to explicitly set the default goal. The following -example illustrates these cases: - -@example -@group -# Query the default goal. -ifeq ($(.DEFAULT_GOAL),) - $(warning no default goal is set) -endif - -.PHONY: foo -foo: ; @@echo $@@ - -$(warning default goal is $(.DEFAULT_GOAL)) - -# Reset the default goal. -.DEFAULT_GOAL := - -.PHONY: bar -bar: ; @@echo $@@ - -$(warning default goal is $(.DEFAULT_GOAL)) - -# Set our own. -.DEFAULT_GOAL := foo -@end group -@end example - -This makefile prints: - -@example -@group -no default goal is set -default goal is foo -default goal is bar -foo -@end group -@end example - -Note that assigning more than one target name to @code{.DEFAULT_GOAL} is -illegal and will result in an error. - -@vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)} -@item MAKE_RESTARTS -This variable is set only if this instance of @code{make} has -restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it -will contain the number of times this instance has restarted. Note -this is not the same as recursion (counted by the @code{MAKELEVEL} -variable). You should not set, modify, or export this variable. - -@vindex .VARIABLES @r{(list of variables)} -@item .VARIABLES -Expands to a list of the @emph{names} of all global variables defined -so far. This includes variables which have empty values, as well as -built-in variables (@pxref{Implicit Variables, , Variables Used by -Implicit Rules}), but does not include any variables which are only -defined in a target-specific context. Note that any value you assign -to this variable will be ignored; it will always return its special -value. - -@c @vindex .TARGETS @r{(list of targets)} -@c @item .TARGETS -@c The second special variable is @code{.TARGETS}. When expanded, the -@c value consists of a list of all targets defined in all makefiles read -@c up until that point. Note it's not enough for a file to be simply -@c mentioned in the makefile to be listed in this variable, even if it -@c would match an implicit rule and become an ``implicit target''. The -@c file must appear as a target, on the left-hand side of a ``:'', to be -@c considered a target for the purposes of this variable. - -@vindex .FEATURES @r{(list of supported features)} -@item .FEATURES -Expands to a list of special features supported by this version of -@code{make}. Possible values include: - -@table @samp - -@item archives -Supports @code{ar} (archive) files using special filename syntax. -@xref{Archives, ,Using @code{make} to Update Archive Files}. - -@item check-symlink -Supports the @code{-L} (@code{--check-symlink-times}) flag. -@xref{Options Summary, ,Summary of Options}. - -@item else-if -Supports ``else if'' non-nested conditionals. @xref{Conditional -Syntax, ,Syntax of Conditionals}. - -@item jobserver -Supports ``job server'' enhanced parallel builds. @xref{Parallel, -,Parallel Execution}. - -@item second-expansion -Supports secondary expansion of prerequisite lists. - -@item order-only -Supports order-only prerequisites. @xref{Prerequisite Types, ,Types -of Prerequisites}. - -@item target-specific -Supports target-specific and pattern-specific variable assignments. -@xref{Target-specific, ,Target-specific Variable Values}. - -@end table - -@vindex .INCLUDE_DIRS @r{(list of include directories)} -@item .INCLUDE_DIRS -Expands to a list of directories that @code{make} searches for -included makefiles (@pxref{Include, , Including Other Makefiles}). - -@end table - -@node Remaking Makefiles, Overriding Makefiles, Special Variables, Makefiles +@node Remaking Makefiles, Overriding Makefiles, MAKEFILES Variable, Makefiles @section How Makefiles Are Remade @cindex updating makefiles @@ -1412,23 +1233,23 @@ again. (It will also attempt to update each of them over again, but normally this will not change them again, since they are already up to date.)@refill -If you know that one or more of your makefiles cannot be remade and you -want to keep @code{make} from performing an implicit rule search on -them, perhaps for efficiency reasons, you can use any normal method of -preventing implicit rule lookup to do so. For example, you can write an -explicit rule with the makefile as the target, and an empty command -string (@pxref{Empty Commands, ,Using Empty Commands}). +If you know that one or more of your makefiles cannot be remade and +you want to keep @code{make} from performing an implicit rule search +on them, perhaps for efficiency reasons, you can use any normal method +of preventing implicit rule lookup to do so. For example, you can +write an explicit rule with the makefile as the target, and an empty +recipe (@pxref{Empty Recipes, ,Using Empty Recipes}). If the makefiles specify a double-colon rule to remake a file with -commands but no prerequisites, that file will always be remade +a recipe but no prerequisites, that file will always be remade (@pxref{Double-Colon}). In the case of makefiles, a makefile that has a -double-colon rule with commands but no prerequisites will be remade every +double-colon rule with a recipe but no prerequisites will be remade every time @code{make} is run, and then again after @code{make} starts over and reads the makefiles in again. This would cause an infinite loop: @code{make} would constantly remake the makefile, and never do anything else. So, to avoid this, @code{make} will @strong{not} attempt to remake makefiles which are specified as targets of a double-colon rule -with commands but no prerequisites.@refill +with a recipe but no prerequisites.@refill If you do not specify any makefiles to be read with @samp{-f} or @samp{--file} options, @code{make} will try the default makefile names; @@ -1447,7 +1268,7 @@ that it is not an error if @code{make} cannot find or make any makefile; a makefile is not always necessary.@refill When you use the @samp{-t} or @samp{--touch} option -(@pxref{Instead of Execution, ,Instead of Executing the Commands}), +(@pxref{Instead of Execution, ,Instead of Executing the Recipe}), you would not want to use an out-of-date makefile to decide which targets to touch. So the @samp{-t} option has no effect on updating makefiles; they are really updated even if @samp{-t} is specified. @@ -1455,8 +1276,8 @@ Likewise, @samp{-q} (or @samp{--question}) and @samp{-n} (or @samp{--just-print}) do not prevent updating of makefiles, because an out-of-date makefile would result in the wrong output for other targets. Thus, @samp{make -f mfile -n foo} will update @file{mfile}, read it in, -and then print the commands to update @file{foo} and its prerequisites -without running them. The commands printed for @file{foo} will be those +and then print the recipe to update @file{foo} and its prerequisites +without running it. The recipe printed for @file{foo} will be the one specified in the updated contents of @file{mfile}. However, on occasion you might actually wish to prevent updating of even @@ -1466,9 +1287,9 @@ makefile name is specified explicitly as a goal, the options @samp{-t} and so on do apply to them. Thus, @samp{make -f mfile -n mfile foo} would read the makefile -@file{mfile}, print the commands needed to update it without actually -running them, and then print the commands needed to update @file{foo} -without running them. The commands for @file{foo} will be those +@file{mfile}, print the recipe needed to update it without actually +running it, and then print the recipe needed to update @file{foo} +without running that. The recipe for @file{foo} will be the one specified by the existing contents of @file{mfile}. @node Overriding Makefiles, Reading Makefiles, Remaking Makefiles, Makefiles @@ -1479,8 +1300,8 @@ specified by the existing contents of @file{mfile}. Sometimes it is useful to have a makefile that is mostly just like another makefile. You can often use the @samp{include} directive to include one in the other, and add more targets or variable definitions. -However, if the two makefiles give different commands for the same -target, @code{make} will not let you just do this. But there is another way. +However, it is illegal for two makefiles to give different recipes for +the same target. But there is another way. @cindex match-anything rule, used to override In the containing makefile (the one that wants to include the other), @@ -1503,19 +1324,19 @@ force: ; @end example If you say @samp{make foo}, @code{make} will find @file{GNUmakefile}, -read it, and see that to make @file{foo}, it needs to run the command +read it, and see that to make @file{foo}, it needs to run the recipe @samp{frobnicate > foo}. If you say @samp{make bar}, @code{make} will find no way to make @file{bar} in @file{GNUmakefile}, so it will use the -commands from the pattern rule: @samp{make -f Makefile bar}. If +recipe from the pattern rule: @samp{make -f Makefile bar}. If @file{Makefile} provides a rule for updating @file{bar}, @code{make} will apply the rule. And likewise for any other target that @file{GNUmakefile} does not say how to make. The way this works is that the pattern rule has a pattern of just @samp{%}, so it matches any target whatever. The rule specifies a -prerequisite @file{force}, to guarantee that the commands will be run even -if the target file already exists. We give @file{force} target empty -commands to prevent @code{make} from searching for an implicit rule to +prerequisite @file{force}, to guarantee that the recipe will be run even +if the target file already exists. We give the @file{force} target an +empty recipe to prevent @code{make} from searching for an implicit rule to build it---otherwise it would apply the same match-anything rule to @file{force} itself and create a prerequisite loop! @@ -1572,20 +1393,18 @@ For the append operator, @samp{+=}, the right-hand side is considered immediate if the variable was previously set as a simple variable (@samp{:=}), and deferred otherwise. -@subheading Conditional Statements +@subheading Conditional Directives @cindex ifdef, expansion @cindex ifeq, expansion @cindex ifndef, expansion @cindex ifneq, expansion -All instances of conditional syntax are parsed immediately, in their -entirety; this includes the @code{ifdef}, @code{ifeq}, @code{ifndef}, -and @code{ifneq} forms. Of course this means that automatic variables -cannot be used in conditional statements, as automatic variables are -not set until the command script for that rule is invoked. If you -need to use automatic variables in a conditional you @emph{must} use -shell conditional syntax, in your command script proper, for these -tests, not @code{make} conditionals. +Conditional directives are parsed immediately. This means, for +example, that automatic variables cannot be used in conditional +directives, as automatic variables are not set until the recipe for +that rule is invoked. If you need to use automatic variables in a +conditional directive you @emph{must} move the condition into the +recipe and use shell conditional syntax instead. @subheading Rule Definition @cindex target, expansion @@ -1602,7 +1421,7 @@ A rule is always expanded the same way, regardless of the form: @end example That is, the target and prerequisite sections are expanded immediately, -and the commands used to construct the target are always deferred. This +and the recipe used to construct the target is always deferred. This general rule is true for explicit rules, pattern rules, suffix rules, static pattern rules, and simple prerequisite definitions. @@ -1676,11 +1495,11 @@ only becomes apparent when you discover that secondary expansions always take place within the scope of the automatic variables for that target. This means that you can use variables such as @code{$@@}, @code{$*}, etc. during the second expansion and they will have their -expected values, just as in the command script. All you have to do is -defer the expansion by escaping the @code{$}. Also, secondary -expansion occurs for both explicit and implicit (pattern) rules. -Knowing this, the possible uses for this feature increase -dramatically. For example: +expected values, just as in the recipe. All you have to do is defer +the expansion by escaping the @code{$}. Also, secondary expansion +occurs for both explicit and implicit (pattern) rules. Knowing this, +the possible uses for this feature increase dramatically. For +example: @example .SECONDEXPANSION: @@ -1698,7 +1517,7 @@ the target and so the expansion for the @file{main} target will yield secondary expansion for the @file{lib} target will yield @code{$(lib_OBJS)}, or @code{lib.o api.o}. -You can also mix functions here, as long as they are properly escaped: +You can also mix in functions here, as long as they are properly escaped: @example main_SRCS := main.c try.c test.c @@ -1714,11 +1533,11 @@ example. Evaluation of automatic variables during the secondary expansion phase, especially of the target name variable @code{$$@@}, behaves -similarly to evaluation within command scripts. However, there are -some subtle differences and ``corner cases'' which come into play for -the different types of rule definitions that @code{make} understands. -The subtleties of using the different automatic variables are -described below. +similarly to evaluation within recipes. However, there are some +subtle differences and ``corner cases'' which come into play for the +different types of rule definitions that @code{make} understands. The +subtleties of using the different automatic variables are described +below. @subheading Secondary Expansion of Explicit Rules @cindex secondary expansion and explicit rules @@ -1751,7 +1570,7 @@ second, they will have values @code{foo.1}, @code{foo.1 bar.1}, and foo.2 bar.2 foo.1 foo.1 bar.1 foo.1 bar.1} respectively. Rules undergo secondary expansion in makefile order, except that -the rule with the command script is always evaluated last. +the rule with the recipe is always evaluated last. The variables @code{$$?} and @code{$$*} are not available and expand to the empty string. @@ -1808,7 +1627,7 @@ prefix reconstruction will be @file{/tmp/foo/foo.c /tmp/var/bar/foo.c foo.h}. If you are not interested in this reconstruction, you can use @code{$$*} instead of @code{%} in the prerequisites list. -@node Rules, Commands, Makefiles, Top +@node Rules, Recipes, Makefiles, Top @chapter Writing Rules @cindex writing rules @cindex rule, how to write @@ -1818,7 +1637,7 @@ foo.h}. If you are not interested in this reconstruction, you can use A @dfn{rule} appears in the makefile and says when and how to remake certain files, called the rule's @dfn{targets} (most often only one per rule). It lists the other files that are the @dfn{prerequisites} of the target, and -@dfn{commands} to use to create or update the target. +the @dfn{recipe} to use to create or update the target. @cindex default goal @cindex goal, default @@ -1844,7 +1663,7 @@ the makefile (often with a target called @samp{all}). * Wildcards:: Using wildcard characters such as `*'. * Directory Search:: Searching other directories for source files. * Phony Targets:: Using a target that is not a real file's name. -* Force Targets:: You can use a target without commands +* Force Targets:: You can use a target without recipes or prerequisites to mark other targets as phony. * Empty Targets:: When only the date matters and the @@ -1873,8 +1692,8 @@ foo.o : foo.c defs.h # module for twiddling the frobs @end example Its target is @file{foo.o} and its prerequisites are @file{foo.c} and -@file{defs.h}. It has one command, which is @samp{cc -c -g foo.c}. -The command line starts with a tab to identify it as a command. +@file{defs.h}. It has one command in the recipe: @samp{cc -c -g foo.c}. +The recipe starts with a tab to identify it as a recipe. This rule says two things: @@ -1886,7 +1705,7 @@ more recent than it. @item How to update the file @file{foo.o}: by running @code{cc} as stated. -The command does not explicitly mention @file{defs.h}, but we presume +The recipe does not explicitly mention @file{defs.h}, but we presume that @file{foo.c} includes it, and that that is why @file{defs.h} was added to the prerequisites. @end itemize @@ -1901,7 +1720,7 @@ In general, a rule looks like this: @example @var{targets} : @var{prerequisites} - @var{command} + @var{recipe} @dots{} @end example @@ -1909,8 +1728,8 @@ In general, a rule looks like this: or like this: @example -@var{targets} : @var{prerequisites} ; @var{command} - @var{command} +@var{targets} : @var{prerequisites} ; @var{recipe} + @var{recipe} @dots{} @end example @@ -1925,13 +1744,15 @@ Usually there is only one target per rule, but occasionally there is a reason to have more (@pxref{Multiple Targets, , Multiple Targets in a Rule}).@refill -@cindex commands +@cindex recipes @cindex tab character (in commands) -The @var{command} lines start with a tab character. The first command may -appear on the line after the prerequisites, with a tab character, or may -appear on the same line, with a semicolon. Either way, the effect is the -same. There are other differences in the syntax of command lines. -@xref{Commands, ,Writing the Commands in Rules}. +The @var{recipe} lines start with a tab character (or the first +character in the value of the @code{.CMDPREFIX} variable; +@pxref{Special Variables}). The first recipe line may appear on the line +after the prerequisites, with a tab character, or may appear on the +same line, with a semicolon. Either way, the effect is the same. +There are other differences in the syntax of recipes. +@xref{Recipes, ,Writing Recipes in Rules}. @cindex dollar sign (@code{$}), in rules @cindex @code{$}, in rules @@ -1963,9 +1784,9 @@ information in the prerequisites, so if any of the prerequisites changes, the contents of the existing target file are no longer necessarily valid. -How to update is specified by @var{commands}. These are lines to be -executed by the shell (normally @samp{sh}), but with some extra features -(@pxref{Commands, ,Writing the Commands in Rules}). +How to update is specified by a @var{recipe}. This is one or more +lines to be executed by the shell (normally @samp{sh}), but with some +extra features (@pxref{Recipes, ,Writing Recipes in Rules}). @node Prerequisite Types, Wildcards, Rule Syntax, Rules @comment node-name, next, previous, up @@ -1981,8 +1802,8 @@ There are actually two different types of prerequisites understood by GNU @code{make}: normal prerequisites such as described in the previous section, and @dfn{order-only} prerequisites. A normal prerequisite makes two statements: first, it imposes an order of -execution of build commands: any commands necessary to build any of a -target's prerequisites will be fully executed before any commands +execution of recipes: any recipes necessary to build any of a +target's prerequisites will be fully executed before any recipe necessary to build the target. Second, it imposes a dependency relationship: if any prerequisite is newer than the target, then the target is considered out-of-date and must be rebuilt. @@ -2069,7 +1890,7 @@ functionality can be simulated by setting the environment variable @var{HOME}.@refill Wildcard expansion is performed by @code{make} automatically in -targets and in prerequisites. In commands the shell is responsible +targets and in prerequisites. In recipes, the shell is responsible for wildcard expansion. In other contexts, wildcard expansion happens only if you request it explicitly with the @code{wildcard} function. @@ -2088,7 +1909,7 @@ specific file whose name consists of @samp{foo}, an asterisk, and @node Wildcard Examples, Wildcard Pitfall, Wildcards, Wildcards @subsection Wildcard Examples -Wildcards can be used in the commands of a rule, where they are expanded +Wildcards can be used in the recipe of a rule, where they are expanded by the shell. For example, here is a rule to delete all the object files: @example @@ -2128,7 +1949,7 @@ objects = *.o @noindent then the value of the variable @code{objects} is the actual string @samp{*.o}. However, if you use the value of @code{objects} in a target, -prerequisite or command, wildcard expansion will take place at that time. +prerequisite, or recipe, wildcard expansion will take place at that time. To set @code{objects} to the expansion, instead use: @example @@ -2275,7 +2096,7 @@ just the search paths. * Selective Search:: Specifying a search path for a specified class of names. * Search Algorithm:: When and how search paths are applied. -* Commands/Search:: How to write shell commands that work together +* Recipes/Search:: How to write recipes that work together with search paths. * Implicit/Search:: How search paths affect implicit rules. * Libraries/Search:: Directory search for link libraries. @@ -2296,8 +2117,7 @@ in the current directory, @code{make} searches the directories listed in @code{VPATH} for a file with that name. If a file is found in one of them, that file may become the prerequisite (see below). Rules may then specify the names of files in the prerequisite list as if they all -existed in the current directory. @xref{Commands/Search, ,Writing Shell -Commands with Directory Search}. +existed in the current directory. @xref{Recipes/Search, ,Writing Recipes with Directory Search}. In the @code{VPATH} variable, directory names are separated by colons or blanks. The order in which directories are listed is the order followed @@ -2432,7 +2252,7 @@ vpath % blish will look for a file ending in @samp{.c} in @file{foo}, then @file{bar}, then @file{blish}. -@node Search Algorithm, Commands/Search, Selective Search, Directory Search +@node Search Algorithm, Recipes/Search, Selective Search, Directory Search @subsection How Directory Searches are Performed @cindex algorithm for directory search @cindex directory search algorithm @@ -2499,14 +2319,14 @@ is found by directory search in a directory that also appears in @code{GPATH}, then that pathname is not thrown away. The target is rebuilt using the expanded path. -@node Commands/Search, Implicit/Search, Search Algorithm, Directory Search -@subsection Writing Shell Commands with Directory Search -@cindex shell command, and directory search -@cindex directory search (@code{VPATH}), and shell commands +@node Recipes/Search, Implicit/Search, Search Algorithm, Directory Search +@subsection Writing Recipes with Directory Search +@cindex recipes, and directory search +@cindex directory search (@code{VPATH}), and recipes When a prerequisite is found in another directory through directory search, -this cannot change the commands of the rule; they will execute as written. -Therefore, you must write the commands with care so that they will look for +this cannot change the recipe of the rule; they will execute as written. +Therefore, you must write the recipe with care so that it will look for the prerequisite in the directory where @code{make} finds it. This is done with the @dfn{automatic variables} such as @samp{$^} @@ -2528,7 +2348,7 @@ affect all C compilations uniformly; @pxref{Implicit Variables, ,Variables Used by Implicit Rules}.) Often the prerequisites include header files as well, which you do not -want to mention in the commands. The automatic variable @samp{$<} is +want to mention in the recipe. The automatic variable @samp{$<} is just the first prerequisite: @example @@ -2537,7 +2357,7 @@ foo.o : foo.c defs.h hack.h cc -c $(CFLAGS) $< -o $@@ @end example -@node Implicit/Search, Libraries/Search, Commands/Search, Directory Search +@node Implicit/Search, Libraries/Search, Recipes/Search, Directory Search @subsection Directory Search and Implicit Rules @cindex @code{VPATH}, and implicit rules @cindex directory search (@code{VPATH}), and implicit rules @@ -2558,7 +2378,7 @@ current directory, the appropriate directories are searched for it. If @file{foo.c} exists (or is mentioned in the makefile) in any of the directories, the implicit rule for C compilation is applied. -The commands of implicit rules normally use automatic variables as a +The recipes of implicit rules normally use automatic variables as a matter of necessity; consequently they will use the file names found by directory search with no extra effort. @@ -2629,13 +2449,13 @@ variable to an empty value. @cindex targets, phony @cindex targets without a file -A phony target is one that is not really the name of a file. It is just a -name for some commands to be executed when you make an explicit request. -There are two reasons to use a phony target: to avoid a conflict with -a file of the same name, and to improve performance. +A phony target is one that is not really the name of a file; rather it +is just a name for a recipe to be executed when you make an explicit +request. There are two reasons to use a phony target: to avoid a +conflict with a file of the same name, and to improve performance. -If you write a rule whose commands will not create the target file, the -commands will be executed every time the target comes up for remaking. +If you write a rule whose recipe will not create the target file, the +recipe will be executed every time the target comes up for remaking. Here is an example: @example @@ -2655,7 +2475,7 @@ will be executed every time you say @samp{make clean}. The phony target will cease to work if anything ever does create a file named @file{clean} in this directory. Since it has no prerequisites, the file @file{clean} would inevitably be considered up to date, and its -commands would not be executed. To avoid this problem, you can explicitly +recipe would not be executed. To avoid this problem, you can explicitly declare the target to be phony, using the special target @code{.PHONY} (@pxref{Special Targets, ,Special Built-in Target Names}) as follows: @@ -2664,7 +2484,7 @@ declare the target to be phony, using the special target @code{.PHONY} @end example @noindent -Once this is done, @samp{make clean} will run the commands regardless of +Once this is done, @samp{make clean} will run the recipe regardless of whether there is a file named @file{clean}. Since it knows that phony targets do not name actual files that could be @@ -2689,7 +2509,7 @@ with recursive invocations of @code{make} (for more information, see @ref{Recursion, ,Recursive Use of @code{make}}). In this case the makefile will often contain a variable which lists a number of subdirectories to be built. One way to handle this is with one rule -whose command is a shell loop over the subdirectories, like this: +whose recipe is a shell loop over the subdirectories, like this: @example @group @@ -2702,14 +2522,15 @@ subdirs: @end group @end example -There are a few problems with this method, however. First, any error -detected in a submake is not noted by this rule, so it will continue to -build the rest of the directories even when one fails. This can be +There are problems with this method, however. First, any error +detected in a submake is ignored by this rule, so it will continue +to build the rest of the directories even when one fails. This can be overcome by adding shell commands to note the error and exit, but then -it will do so even if @code{make} is invoked with the @code{-k} option, -which is unfortunate. Second, and perhaps more importantly, you cannot -take advantage of @code{make}'s ability to build targets in parallel -(@pxref{Parallel, ,Parallel Execution}), since there is only one rule. +it will do so even if @code{make} is invoked with the @code{-k} +option, which is unfortunate. Second, and perhaps more importantly, +you cannot take advantage of @code{make}'s ability to build targets in +parallel (@pxref{Parallel, ,Parallel Execution}), since there is only +one rule. By declaring the subdirectories as phony targets (you must do this as the subdirectory obviously always exists; otherwise it won't be built) @@ -2736,9 +2557,9 @@ relationship declaration is particularly important when attempting parallel builds. A phony target should not be a prerequisite of a real target file; if it -is, its commands are run every time @code{make} goes to update that +is, its recipe will be run every time @code{make} goes to update that file. As long as a phony target is never a prerequisite of a real -target, the phony target commands will be executed only when the phony +target, the phony target recipe will be executed only when the phony target is a specified goal (@pxref{Goals, ,Arguments to Specify the Goals}). @@ -2787,16 +2608,16 @@ cleandiff : @end example @node Force Targets, Empty Targets, Phony Targets, Rules -@section Rules without Commands or Prerequisites +@section Rules without Recipes or Prerequisites @cindex force targets @cindex targets, force @cindex @code{FORCE} -@cindex rule, no commands or prerequisites +@cindex rule, no recipe or prerequisites -If a rule has no prerequisites or commands, and the target of the rule +If a rule has no prerequisites or recipe, and the target of the rule is a nonexistent file, then @code{make} imagines this target to have been updated whenever its rule is run. This implies that all targets -depending on this one will always have their commands run. +depending on this one will always have their recipe run. An example will illustrate this: @@ -2809,9 +2630,9 @@ FORCE: @end example Here the target @samp{FORCE} satisfies the special conditions, so the -target @file{clean} that depends on it is forced to run its commands. -There is nothing special about the name @samp{FORCE}, but that is one name -commonly used this way. +target @file{clean} that depends on it is forced to run its recipe. +There is nothing special about the name @samp{FORCE}, but that is one +name commonly used this way. As you can see, using @samp{FORCE} this way has the same results as using @samp{.PHONY: clean}. @@ -2827,18 +2648,18 @@ other versions of @code{make} do not support @samp{.PHONY}; thus @cindex recording events with empty targets The @dfn{empty target} is a variant of the phony target; it is used to hold -commands for an action that you request explicitly from time to time. +recipes for an action that you request explicitly from time to time. Unlike a phony target, this target file can really exist; but the file's contents do not matter, and usually are empty. The purpose of the empty target file is to record, with its -last-modification time, when the rule's commands were last executed. It -does so because one of the commands is a @code{touch} command to update the -target file. +last-modification time, when the rule's recipe was last executed. It +does so because one of the commands in the recipeis a @code{touch} +command to update the target file. The empty target file should have some prerequisites (otherwise it doesn't make sense). When you ask to remake the empty target, the -commands are executed if any prerequisite is more recent than the target; +recipe is executed if any prerequisite is more recent than the target; in other words, if a prerequisite has changed since the last time you remade the target. Here is an example: @@ -2871,7 +2692,7 @@ Certain names have special meanings if they appear as targets. The prerequisites of the special target @code{.PHONY} are considered to be phony targets. When it is time to consider such a target, -@code{make} will run its commands unconditionally, regardless of +@code{make} will run its recipe unconditionally, regardless of whether a file with that name exists or what its last-modification time is. @xref{Phony Targets, ,Phony Targets}. @@ -2885,11 +2706,11 @@ of suffixes to be used in checking for suffix rules. @findex .DEFAULT @item .DEFAULT -The commands specified for @code{.DEFAULT} are used for any target for +The recipe specified for @code{.DEFAULT} is used for any target for which no rules are found (either explicit rules or implicit rules). -@xref{Last Resort}. If @code{.DEFAULT} commands are specified, every +@xref{Last Resort}. If a @code{.DEFAULT} recipe is specified, every file mentioned as a prerequisite, but not as a target in a rule, will have -these commands executed on its behalf. @xref{Implicit Rule Search, +that recipe executed on its behalf. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}. @findex .PRECIOUS @@ -2899,7 +2720,7 @@ these commands executed on its behalf. @xref{Implicit Rule Search, The targets which @code{.PRECIOUS} depends on are given the following special treatment: if @code{make} is killed or interrupted during the -execution of their commands, the target is not deleted. +execution of their recipes, the target is not deleted. @xref{Interrupts, ,Interrupting or Killing @code{make}}. Also, if the target is an intermediate file, it will not be deleted after it is no longer needed, as is normally done. @xref{Chained Rules, ,Chains of @@ -2946,39 +2767,40 @@ will be expanded a second time after all makefiles have been read in. If @code{.DELETE_ON_ERROR} is mentioned as a target anywhere in the makefile, then @code{make} will delete the target of a rule if it has -changed and its commands exit with a nonzero exit status, just as it -does when it receives a signal. @xref{Errors, ,Errors in Commands}. +changed and its recipe exits with a nonzero exit status, just as it +does when it receives a signal. @xref{Errors, ,Errors in Recipes}. @findex .IGNORE @item .IGNORE If you specify prerequisites for @code{.IGNORE}, then @code{make} will -ignore errors in execution of the commands run for those particular -files. The commands for @code{.IGNORE} are not meaningful. +ignore errors in execution of the recipe for those particular files. +The recipe for @code{.IGNORE} (if any) is ignored. If mentioned as a target with no prerequisites, @code{.IGNORE} says to -ignore errors in execution of commands for all files. This usage of +ignore errors in execution of recipes for all files. This usage of @samp{.IGNORE} is supported only for historical compatibility. Since -this affects every command in the makefile, it is not very useful; we +this affects every recipe in the makefile, it is not very useful; we recommend you use the more selective ways to ignore errors in specific -commands. @xref{Errors, ,Errors in Commands}. +recipes. @xref{Errors, ,Errors in Recipes}. @findex .LOW_RESOLUTION_TIME @item .LOW_RESOLUTION_TIME If you specify prerequisites for @code{.LOW_RESOLUTION_TIME}, @command{make} assumes that these files are created by commands that -generate low resolution time stamps. The commands for -@code{.LOW_RESOLUTION_TIME} are not meaningful. - -The high resolution file time stamps of many modern hosts lessen the -chance of @command{make} incorrectly concluding that a file is up to -date. Unfortunately, these hosts provide no way to set a high -resolution file time stamp, so commands like @samp{cp -p} that -explicitly set a file's time stamp must discard its subsecond part. If -a file is created by such a command, you should list it as a -prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} does -not mistakenly conclude that the file is out of date. For example: +generate low resolution time stamps. The recipe for the +@code{.LOW_RESOLUTION_TIME} target are ignored. + +The high resolution file time stamps of many modern file systems +lessen the chance of @command{make} incorrectly concluding that a file +is up to date. Unfortunately, some hosts do not provide a way to set a +high resolution file time stamp, so commands like @samp{cp -p} that +explicitly set a file's time stamp must discard its subsecond part. +If a file is created by such a command, you should list it as a +prerequisite of @code{.LOW_RESOLUTION_TIME} so that @command{make} +does not mistakenly conclude that the file is out of date. For +example: @example @group @@ -3003,14 +2825,14 @@ automatically. @item .SILENT If you specify prerequisites for @code{.SILENT}, then @code{make} will -not print the commands to remake those particular files before executing -them. The commands for @code{.SILENT} are not meaningful. +not print the recipe used to remake those particular files before +executing them. The recipe for @code{.SILENT} is ignored. If mentioned as a target with no prerequisites, @code{.SILENT} says not -to print any commands before executing them. This usage of +to print any recipes before executing them. This usage of @samp{.SILENT} is supported only for historical compatibility. We -recommend you use the more selective ways to silence specific commands. -@xref{Echoing, ,Command Echoing}. If you want to silence all commands +recommend you use the more selective ways to silence specific recipes. +@xref{Echoing, ,Recipe Echoing}. If you want to silence all recipes for a particular run of @code{make}, use the @samp{-s} or @w{@samp{--silent}} option (@pxref{Options Summary}). @@ -3029,7 +2851,7 @@ Sub-@code{make}}. If @code{.NOTPARALLEL} is mentioned as a target, then this invocation of @code{make} will be run serially, even if the @samp{-j} option is given. Any recursively invoked @code{make} command will still run -commands in parallel (unless its makefile also contains this target). +recipes in parallel (unless its makefile also contains this target). Any prerequisites on this target are ignored. @end table @@ -3050,16 +2872,16 @@ both pieces to the suffix list. In practice, suffixes normally begin with @cindex rule, with multiple targets A rule with multiple targets is equivalent to writing many rules, each with -one target, and all identical aside from that. The same commands apply to -all the targets, but their effects may vary because you can substitute the -actual target name into the command using @samp{$@@}. The rule contributes +one target, and all identical aside from that. The same recipe applies to +all the targets, but its effect may vary because you can substitute the +actual target name into the recipe using @samp{$@@}. The rule contributes the same prerequisites to all the targets also. This is useful in two cases. @itemize @bullet @item -You want just prerequisites, no commands. For example: +You want just prerequisites, no recipe. For example: @example kbd.o command.o files.o: command.h @@ -3070,7 +2892,7 @@ gives an additional prerequisite to each of the three object files mentioned. @item -Similar commands work for all the targets. The commands do not need +Similar recipes work for all the targets. The recipes do not need to be absolutely identical, since the automatic variable @samp{$@@} can be used to substitute the particular target to be remade into the commands (@pxref{Automatic Variables}). For example: @@ -3101,11 +2923,11 @@ types of output, one if given @samp{-big} and one if given for an explanation of the @code{subst} function. @end itemize -Suppose you would like to vary the prerequisites according to the target, -much as the variable @samp{$@@} allows you to vary the commands. -You cannot do this with multiple targets in an ordinary rule, but you can -do it with a @dfn{static pattern rule}. -@xref{Static Pattern, ,Static Pattern Rules}. +Suppose you would like to vary the prerequisites according to the +target, much as the variable @samp{$@@} allows you to vary the recipe. +You cannot do this with multiple targets in an ordinary rule, but you +can do it with a @dfn{static pattern rule}. @xref{Static Pattern, +,Static Pattern Rules}. @node Multiple Rules, Static Pattern, Multiple Targets, Rules @section Multiple Rules for One Target @@ -3117,15 +2939,15 @@ do it with a @dfn{static pattern rule}. One file can be the target of several rules. All the prerequisites mentioned in all the rules are merged into one list of prerequisites for the target. If the target is older than any prerequisite from any rule, -the commands are executed. - -There can only be one set of commands to be executed for a file. If -more than one rule gives commands for the same file, @code{make} uses -the last set given and prints an error message. (As a special case, -if the file's name begins with a dot, no error message is printed. -This odd behavior is only for compatibility with other implementations -of @code{make}@dots{} you should avoid using it). Occasionally it is -useful to have the same target invoke multiple commands which are +the recipe is executed. + +There can only be one recipe to be executed for a file. If more than +one rule gives a recipe for the same file, @code{make} uses the last +one given and prints an error message. (As a special case, if the +file's name begins with a dot, no error message is printed. This odd +behavior is only for compatibility with other implementations of +@code{make}@dots{} you should avoid using it). Occasionally it is +useful to have the same target invoke multiple recipes which are defined in different parts of your makefile; you can use @dfn{double-colon rules} (@pxref{Double-Colon}) for this. @@ -3147,9 +2969,9 @@ This could be inserted or taken out without changing the rules that really specify how to make the object files, making it a convenient form to use if you wish to add the additional prerequisite intermittently. -Another wrinkle is that the additional prerequisites could be specified with -a variable that you set with a command argument to @code{make} -(@pxref{Overriding, ,Overriding Variables}). For example, +Another wrinkle is that the additional prerequisites could be +specified with a variable that you set with a command line argument to +@code{make} (@pxref{Overriding, ,Overriding Variables}). For example, @example @group @@ -3163,8 +2985,8 @@ means that the command @samp{make extradeps=foo.h} will consider @file{foo.h} as a prerequisite of each object file, but plain @samp{make} will not. -If none of the explicit rules for a target has commands, then @code{make} -searches for an applicable implicit rule to find some commands +If none of the explicit rules for a target has a recipe, then @code{make} +searches for an applicable implicit rule to find one @pxref{Implicit Rules, ,Using Implicit Rules}). @node Static Pattern, Double-Colon, Multiple Rules, Rules @@ -3195,7 +3017,7 @@ Here is the syntax of a static pattern rule: @example @var{targets} @dots{}: @var{target-pattern}: @var{prereq-patterns} @dots{} - @var{commands} + @var{recipe} @dots{} @end example @@ -3310,7 +3132,7 @@ names of prerequisites. The difference is in how @code{make} decides @emph{when} the rule applies. An implicit rule @emph{can} apply to any target that matches its pattern, -but it @emph{does} apply only when the target has no commands otherwise +but it @emph{does} apply only when the target has no recipe otherwise specified, and only when the prerequisites can be found. If more than one implicit rule appears applicable, only one applies; the choice depends on the order of rules. @@ -3318,7 +3140,7 @@ the order of rules. By contrast, a static pattern rule applies to the precise list of targets that you specify in the rule. It cannot apply to any other target and it invariably does apply to each of the targets specified. If two conflicting -rules apply, and both have commands, that's an error. +rules apply, and both have recipes, that's an error. The static pattern rule can be better than an implicit rule for these reasons: @@ -3351,9 +3173,9 @@ ordinary rules when the same target appears in more than one rule. When a target appears in multiple rules, all the rules must be the same type: all ordinary, or all double-colon. If they are double-colon, each -of them is independent of the others. Each double-colon rule's commands -are executed if the target is older than any prerequisites of that rule. -If there are no prerequisites for that rule, its commands are always +of them is independent of the others. Each double-colon rule's recipe +is executed if the target is older than any prerequisites of that rule. +If there are no prerequisites for that rule, its recipe is always executed (even if the target already exists). This can result in executing none, any, or all of the double-colon rules. @@ -3363,14 +3185,14 @@ as rules with different targets are processed. The double-colon rules for a target are executed in the order they appear in the makefile. However, the cases where double-colon rules really make -sense are those where the order of executing the commands would not matter. +sense are those where the order of executing the recipes would not matter. Double-colon rules are somewhat obscure and not often very useful; they provide a mechanism for cases in which the method used to update a target differs depending on which prerequisite files caused the update, and such cases are rare. -Each double-colon rule should specify commands; if it does not, an +Each double-colon rule should specify a recipe; if it does not, an implicit rule will be used if one applies. @xref{Implicit Rules, ,Using Implicit Rules}. @@ -3515,114 +3337,118 @@ default goal in your makefiles or run the risk of having a random object file become the default goal. @xref{How Make Works}. -@node Commands, Using Variables, Rules, Top -@chapter Writing the Commands in Rules -@cindex commands, how to write -@cindex rule commands -@cindex writing rule commands +@node Recipes, Using Variables, Rules, Top +@chapter Writing Recipes in Rules +@cindex recipes +@cindex recipes, how to write +@cindex writing recipes -The commands of a rule consist of one or more shell command lines to +The recipe of a rule consists of one or more shell command lines to be executed, one at a time, in the order they appear. Typically, the result of executing these commands is that the target of the rule is brought up to date. -Users use many different shell programs, but commands in makefiles are +Users use many different shell programs, but recipes in makefiles are always interpreted by @file{/bin/sh} unless the makefile specifies otherwise. @xref{Execution, ,Command Execution}. @menu -* Command Syntax:: Command syntax features and pitfalls. -* Echoing:: How to control when commands are echoed. -* Execution:: How commands are executed. -* Parallel:: How commands can be executed in parallel. -* Errors:: What happens after a command execution error. -* Interrupts:: What happens when a command is interrupted. +* Recipe Syntax:: Recipe syntax features and pitfalls. +* Echoing:: How to control when recipes are echoed. +* Execution:: How recipes are executed. +* Parallel:: How recipes can be executed in parallel. +* Errors:: What happens after a recipe execution error. +* Interrupts:: What happens when a recipe is interrupted. * Recursion:: Invoking @code{make} from makefiles. -* Sequences:: Defining canned sequences of commands. -* Empty Commands:: Defining useful, do-nothing commands. +* Sequences:: Defining canned recipes. +* Empty Recipes:: Defining useful, do-nothing recipes. @end menu -@node Command Syntax, Echoing, Commands, Commands -@section Command Syntax -@cindex command syntax -@cindex syntax of commands +@node Recipe Syntax, Echoing, Recipes, Recipes +@section Recipe Syntax +@cindex recipe syntax +@cindex syntax of recipe Makefiles have the unusual property that there are really two distinct syntaxes in one file. Most of the makefile uses @code{make} syntax -(@pxref{Makefiles, ,Writing Makefiles}). However, commands are meant to be -interpreted by the shell and so they are written using shell syntax. -The @code{make} program does not try to understand shell syntax: it -performs only a very few specific translations on the content of the -command before handing it to the shell. - -Each command line must start with a tab, except that the first command -line may be attached to the target-and-prerequisites line with a -semicolon in between. @emph{Any} line in the makefile that begins -with a tab and appears in a ``rule context'' (that is, after a rule -has been started until another rule or variable definition) will be -considered a command line for that rule. Blank lines and lines of -just comments may appear among the command lines; they are ignored. +(@pxref{Makefiles, ,Writing Makefiles}). However, recipes are meant +to be interpreted by the shell and so they are written using shell +syntax. The @code{make} program does not try to understand shell +syntax: it performs only a very few specific translations on the +content of the recipe before handing it to the shell. + +Each line in the recipe must start with a tab (or the first character +in the value of the @code{.CMDPREFIX} variable; @pxref{Special +Variables}), except that the first recipe line may be attached to the +target-and-prerequisites line with a semicolon in between. @emph{Any} +line in the makefile that begins with a tab and appears in a ``rule +context'' (that is, after a rule has been started until another rule +or variable definition) will be considered part of a recipe for that +rule. Blank lines and lines of just comments may appear among the +recipe lines; they are ignored. Some consequences of these rules include: @itemize @bullet @item A blank line that begins with a tab is not blank: it's an empty -command (@pxref{Empty Commands}). +recipe (@pxref{Empty Recipes}). -@cindex comments, in commands -@cindex commands, comments in -@cindex @code{#} (comments), in commands +@cindex comments, in recipes +@cindex recipes, comments in +@cindex @code{#} (comments), in recipes @item -A comment in a command line is not a @code{make} comment; it will be +A comment in a recipe is not a @code{make} comment; it will be passed to the shell as-is. Whether the shell treats it as a comment or not depends on your shell. @item A variable definition in a ``rule context'' which is indented by a tab -as the first character on the line, will be considered a command line, -not a @code{make} variable definition, and passed to the shell. +as the first character on the line, will be considered part of a +recipe, not a @code{make} variable definition, and passed to the +shell. @item A conditional expression (@code{ifdef}, @code{ifeq}, etc. @pxref{Conditional Syntax, ,Syntax of Conditionals}) in a ``rule context'' which is indented by a tab as the first character on the -line, will be considered a command line and be passed to the shell. +line, will be considered part of a recipe and be passed to the shell. @end itemize @menu -* Splitting Lines:: Breaking long command lines for readability. -* Variables in Commands:: Using @code{make} variables in commands. +* Splitting Lines:: Breaking long recipe lines for readability. +* Variables in Recipes:: Using @code{make} variables in recipes. @end menu -@node Splitting Lines, Variables in Commands, Command Syntax, Command Syntax -@subsection Splitting Command Lines -@cindex commands, splitting -@cindex splitting commands -@cindex commands, backslash (@code{\}) in -@cindex commands, quoting newlines in -@cindex backslash (@code{\}), in commands -@cindex @code{\} (backslash), in commands -@cindex quoting newline, in commands -@cindex newline, quoting, in commands - -One of the few ways in which @code{make} does interpret command lines -is checking for a backslash just before the newline. As in normal -makefile syntax, a single command can be split into multiple lines in -the makefile by placing a backslash before each newline. A sequence -of lines like this is considered a single command, and one instance of -the shell will be invoked to run it. +@node Splitting Lines, Variables in Recipes, Recipe Syntax, Recipe Syntax +@subsection Splitting Recipe Lines +@cindex recipes, splitting +@cindex splitting recipes +@cindex recipes, backslash (@code{\}) in +@cindex recipes, quoting newlines in +@cindex backslash (@code{\}), in recipes +@cindex @code{\} (backslash), in recipes +@cindex quoting newline, in recipes +@cindex newline, quoting, in recipes + +One of the few ways in which @code{make} does interpret recipes is +checking for a backslash just before the newline. As in normal +makefile syntax, a single logical recipe line can be split into +multiple physical lines in the makefile by placing a backslash before +each newline. A sequence of lines like this is considered a single +recipe line, and one instance of the shell will be invoked to run it. However, in contrast to how they are treated in other places in a makefile, backslash-newline pairs are @emph{not} removed from the -command. Both the backslash and the newline characters are preserved +recipe. Both the backslash and the newline characters are preserved and passed to the shell. How the backslash-newline is interpreted -depends on your shell. If the first character of the next line -after the backslash-newline is a tab, then that tab (and only that -tab) is removed. Whitespace is never added to the command. +depends on your shell. If the first character of the next line after +the backslash-newline is the recipe prefix character (a tab by +default; @pxref{Special Variables}), then that character (and only +that character) is removed. Whitespace is never added to the recipe. -For example, this makefile: +For example, the recipe for the all target in this makefile: @example @group @@ -3661,7 +3487,7 @@ all : ; @@echo 'hello \ @end example @noindent -will run one shell with a command script of: +will invoke one shell with a command of: @example @group @@ -3696,7 +3522,7 @@ This is often the case when passing scripts to languages such as Perl, where extraneous backslashes inside the script can change its meaning or even be a syntax error. One simple way of handling this is to place the quoted string, or even the entire command, into a -@code{make} variable then use the variable in the command. In this +@code{make} variable then use the variable in the recipe. In this situation the newline quoting rules for makefiles will be used, and the backslash-newline will be removed. If we rewrite our example above using this method: @@ -3721,24 +3547,24 @@ hello world If you like, you can also use target-specific variables (@pxref{Target-specific, ,Target-specific Variable Values}) to obtain -a tighter correspondence between the variable and the command that +a tighter correspondence between the variable and the recipe that uses it. -@node Variables in Commands, , Splitting Lines, Command Syntax -@subsection Using Variables in Commands -@cindex variable references in commands -@cindex commands, using variables in +@node Variables in Recipes, , Splitting Lines, Recipe Syntax +@subsection Using Variables in Recipes +@cindex variable references in recipes +@cindex recipes, using variables in -The other way in which @code{make} processes commands is by expanding +The other way in which @code{make} processes recipes is by expanding any variable references in them (@pxref{Reference,Basics of Variable References}). This occurs after make has finished reading all the makefiles and the target is determined to be out of date; so, the -commands for targets which are not rebuilt are never expanded. +recipes for targets which are not rebuilt are never expanded. -Variable and function references in commands have identical syntax and +Variable and function references in recipes have identical syntax and semantics to references elsewhere in the makefile. They also have the same quoting rules: if you want a dollar sign to appear in your -command, you must double it (@samp{$$}). For shells like the default +recipe, you must double it (@samp{$$}). For shells like the default shell, that use dollar signs to introduce variables, it's important to keep clear in your mind whether the variable you want to reference is a @code{make} variable (use a single dollar sign) or a shell variable @@ -3776,20 +3602,20 @@ three @end group @end example -@node Echoing, Execution, Command Syntax, Commands -@section Command Echoing -@cindex echoing of commands +@node Echoing, Execution, Recipe Syntax, Recipes +@section Recipe Echoing +@cindex echoing of recipes @cindex silent operation -@cindex @code{@@} (in commands) -@cindex commands, echoing -@cindex printing of commands +@cindex @code{@@} (in recipes) +@cindex recipes, echoing +@cindex printing of recipes -Normally @code{make} prints each command line before it is executed. -We call this @dfn{echoing} because it gives the appearance that you -are typing the commands yourself. +Normally @code{make} prints each line of the recipe before it is +executed. We call this @dfn{echoing} because it gives the appearance +that you are typing the lines yourself. When a line starts with @samp{@@}, the echoing of that line is suppressed. -The @samp{@@} is discarded before the command is passed to the shell. +The @samp{@@} is discarded before the line is passed to the shell. Typically you would use this for a command whose only effect is to print something, such as an @code{echo} command to indicate progress through the makefile: @@ -3803,10 +3629,10 @@ the makefile: @cindex @code{--dry-run} @cindex @code{--recon} When @code{make} is given the flag @samp{-n} or @samp{--just-print} -it only echoes commands, it won't execute them. @xref{Options Summary, +it only echoes recipes, it won't execute them. @xref{Options Summary, ,Summary of Options}. In this case and only this case, even the -commands starting with @samp{@@} are printed. This flag is useful for -finding out which commands @code{make} thinks are necessary without +recipe lines starting with @samp{@@} are printed. This flag is useful for +finding out which recipes @code{make} thinks are necessary without actually doing them. @cindex @code{-s} @@ -3814,34 +3640,33 @@ actually doing them. @cindex @code{--quiet} @findex .SILENT The @samp{-s} or @samp{--silent} -flag to @code{make} prevents all echoing, as if all commands +flag to @code{make} prevents all echoing, as if all recipes started with @samp{@@}. A rule in the makefile for the special target @code{.SILENT} without prerequisites has the same effect (@pxref{Special Targets, ,Special Built-in Target Names}). @code{.SILENT} is essentially obsolete since @samp{@@} is more flexible.@refill -@node Execution, Parallel, Echoing, Commands -@section Command Execution -@cindex commands, execution -@cindex execution, of commands -@cindex shell command, execution -@vindex @code{SHELL} @r{(command execution)} +@node Execution, Parallel, Echoing, Recipes +@section Recipe Execution +@cindex recipe, execution +@cindex execution, of recipes +@vindex @code{SHELL} @r{(recipe execution)} -When it is time to execute commands to update a target, they are -executed by invoking a new subshell for each command line. (In +When it is time to execute recipes to update a target, they are +executed by invoking a new subshell for each line of the recipe. (In practice, @code{make} may take shortcuts that do not affect the results.) @cindex @code{cd} (shell command) -@cindex shell variables, setting in commands -@cindex commands setting shell variables +@cindex shell variables, setting in recipes +@cindex recipes setting shell variables @strong{Please note:} this implies that setting shell variables and invoking shell commands such as @code{cd} that set a context local to -each process will not affect the following command lines.@footnote{On +each process will not affect the following lines in the recipe.@footnote{On MS-DOS, the value of current working directory is @strong{global}, so -changing it @emph{will} affect the following command lines on those +changing it @emph{will} affect the following recipe lines on those systems.} If you want to use @code{cd} to affect the next statement, -put both statements in a single command line. Then @code{make} will +put both statements in a single recipe line. Then @code{make} will invoke one shell to run the entire line, and the shell will execute the statements in sequence. For example: @@ -3859,7 +3684,7 @@ truncated, at least). @menu * Choosing the Shell:: How @code{make} chooses the shell used - to run commands. + to run recipes. @end menu @node Choosing the Shell, , Execution, Execution @@ -3881,12 +3706,12 @@ functioning of makefiles. @xref{Environment, ,Variables from the Environment}. Furthermore, when you do set @code{SHELL} in your makefile that value -is @emph{not} exported in the environment to commands that @code{make} -invokes. Instead, the value inherited from the user's environment, if -any, is exported. You can override this behavior by explicitly -exporting @code{SHELL} (@pxref{Variables/Recursion, ,Communicating -Variables to a Sub-@code{make}}), forcing it to be passed in the -environment to commands. +is @emph{not} exported in the environment to recipe lines that +@code{make} invokes. Instead, the value inherited from the user's +environment, if any, is exported. You can override this behavior by +explicitly exporting @code{SHELL} (@pxref{Variables/Recursion, +,Communicating Variables to a Sub-@code{make}}), forcing it to be +passed in the environment to recipe lines. @vindex @code{MAKESHELL} @r{(MS-DOS alternative to @code{SHELL})} However, on MS-DOS and MS-Windows the value of @code{SHELL} in the @@ -3961,19 +3786,19 @@ contains @samp{SHELL = /bin/sh} (as many Unix makefiles do), will work on MS-DOS unaltered if you have e.g.@: @file{sh.exe} installed in some directory along your @code{PATH}. -@node Parallel, Errors, Execution, Commands +@node Parallel, Errors, Execution, Recipes @section Parallel Execution -@cindex commands, execution in parallel +@cindex recipes, execution in parallel @cindex parallel execution @cindex execution, in parallel @cindex job slots @cindex @code{-j} @cindex @code{--jobs} -GNU @code{make} knows how to execute several commands at once. -Normally, @code{make} will execute only one command at a time, waiting +GNU @code{make} knows how to execute several recipes at once. +Normally, @code{make} will execute only one recipe at a time, waiting for it to finish before executing the next. However, the @samp{-j} or -@samp{--jobs} option tells @code{make} to execute many commands +@samp{--jobs} option tells @code{make} to execute many recipes simultaneously. You can inhibit parallelism in a particular makefile with the @code{.NOTPARALLEL} pseudo-target (@pxref{Special Targets,Special Built-in Target Names}).@refill @@ -3982,46 +3807,46 @@ On MS-DOS, the @samp{-j} option has no effect, since that system doesn't support multi-processing. If the @samp{-j} option is followed by an integer, this is the number of -commands to execute at once; this is called the number of @dfn{job slots}. +recipes to execute at once; this is called the number of @dfn{job slots}. If there is nothing looking like an integer after the @samp{-j} option, there is no limit on the number of job slots. The default number of job slots is one, which means serial execution (one thing at a time). -One unpleasant consequence of running several commands simultaneously is -that output generated by the commands appears whenever each command -sends it, so messages from different commands may be interspersed. +One unpleasant consequence of running several recipes simultaneously is +that output generated by the recipes appears whenever each recipe +sends it, so messages from different recipes may be interspersed. Another problem is that two processes cannot both take input from the -same device; so to make sure that only one command tries to take input +same device; so to make sure that only one recipe tries to take input from the terminal at once, @code{make} will invalidate the standard -input streams of all but one running command. This means that +input streams of all but one running recipe. This means that attempting to read from standard input will usually be a fatal error (a @samp{Broken pipe} signal) for most child processes if there are several. @cindex broken pipe @cindex standard input -It is unpredictable which command will have a valid standard input stream +It is unpredictable which recipe will have a valid standard input stream (which will come from the terminal, or wherever you redirect the standard -input of @code{make}). The first command run will always get it first, and -the first command started after that one finishes will get it next, and so +input of @code{make}). The first recipe run will always get it first, and +the first recipe started after that one finishes will get it next, and so on. We will change how this aspect of @code{make} works if we find a better -alternative. In the mean time, you should not rely on any command using +alternative. In the mean time, you should not rely on any recipe using standard input at all if you are using the parallel execution feature; but if you are not using this feature, then standard input works normally in -all commands. +all recipes. Finally, handling recursive @code{make} invocations raises issues. For more information on this, see @ref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. -If a command fails (is killed by a signal or exits with a nonzero -status), and errors are not ignored for that command -(@pxref{Errors, ,Errors in Commands}), -the remaining command lines to remake the same target will not be run. -If a command fails and the @samp{-k} or @samp{--keep-going} +If a recipe fails (is killed by a signal or exits with a nonzero +status), and errors are not ignored for that recipe +(@pxref{Errors, ,Errors in Recipes}), +the remaining recipe lines to remake the same target will not be run. +If a recipe fails and the @samp{-k} or @samp{--keep-going} option was not given (@pxref{Options Summary, ,Summary of Options}), @code{make} aborts execution. If make @@ -4057,29 +3882,29 @@ average goes below that limit, or until all the other jobs finish. By default, there is no load limit. -@node Errors, Interrupts, Parallel, Commands -@section Errors in Commands -@cindex errors (in commands) -@cindex commands, errors in +@node Errors, Interrupts, Parallel, Recipes +@section Errors in Recipes +@cindex errors (in recipes) +@cindex recipes, errors in @cindex exit status (errors) -After each shell command returns, @code{make} looks at its exit status. -If the command completed successfully, the next command line is executed -in a new shell; after the last command line is finished, the rule is -finished. +After each shell invocation returns, @code{make} looks at its exit +status. If the shell completed successfully (the exit status is +zero), the next line in the recipe is executed in a new shell; after +the last line is finished, the rule is finished. If there is an error (the exit status is nonzero), @code{make} gives up on the current rule, and perhaps on all rules. -Sometimes the failure of a certain command does not indicate a problem. +Sometimes the failure of a certain recipe line does not indicate a problem. For example, you may use the @code{mkdir} command to ensure that a directory exists. If the directory already exists, @code{mkdir} will report an error, but you probably want @code{make} to continue regardless. -@cindex @code{-} (in commands) -To ignore errors in a command line, write a @samp{-} at the beginning of -the line's text (after the initial tab). The @samp{-} is discarded before -the command is passed to the shell for execution. +@cindex @code{-} (in recipes) +To ignore errors in a recipe line, write a @samp{-} at the beginning +of the line's text (after the initial tab). The @samp{-} is discarded +before the line is passed to the shell for execution. For example, @@ -4092,13 +3917,14 @@ clean: @cindex @code{rm} (shell command) @noindent -This causes @code{rm} to continue even if it is unable to remove a file. +This causes @code{make} to continue even if @code{rm} is unable to +remove a file. @cindex @code{-i} @cindex @code{--ignore-errors} @findex .IGNORE When you run @code{make} with the @samp{-i} or @samp{--ignore-errors} -flag, errors are ignored in all commands of all rules. A rule in the +flag, errors are ignored in all recipes of all rules. A rule in the makefile for the special target @code{.IGNORE} has the same effect, if there are no prerequisites. These ways of ignoring errors are obsolete because @samp{-} is more flexible. @@ -4106,12 +3932,12 @@ because @samp{-} is more flexible. When errors are to be ignored, because of either a @samp{-} or the @samp{-i} flag, @code{make} treats an error return just like success, except that it prints out a message that tells you the status code -the command exited with, and says that the error has been ignored. +the shell exited with, and says that the error has been ignored. When an error happens that @code{make} has not been told to ignore, it implies that the current target cannot be correctly remade, and neither can any other that depends on it either directly or indirectly. No further -commands will be executed for these targets, since their preconditions +recipes will be executed for these targets, since their preconditions have not been achieved. @@ -4140,19 +3966,19 @@ default. @cindex deletion of target files @cindex removal of target files @cindex target, deleting on error -Usually when a command fails, if it has changed the target file at all, +Usually when a recipe line fails, if it has changed the target file at all, the file is corrupted and cannot be used---or at least it is not completely updated. Yet the file's time stamp says that it is now up to date, so the next time @code{make} runs, it will not try to update that -file. The situation is just the same as when the command is killed by a +file. The situation is just the same as when the shell is killed by a signal; @pxref{Interrupts}. So generally the right thing to do is to -delete the target file if the command fails after beginning to change +delete the target file if the recipe fails after beginning to change the file. @code{make} will do this if @code{.DELETE_ON_ERROR} appears as a target. This is almost always what you want @code{make} to do, but it is not historical practice; so for compatibility, you must explicitly request it. -@node Interrupts, Recursion, Errors, Commands +@node Interrupts, Recursion, Errors, Recipes @section Interrupting or Killing @code{make} @cindex interrupt @cindex signal @@ -4161,8 +3987,8 @@ request it. @cindex target, deleting on interrupt @cindex killing (interruption) -If @code{make} gets a fatal signal while a command is executing, it may -delete the target file that the command was supposed to update. This is +If @code{make} gets a fatal signal while a shell is executing, it may +delete the target file that the recipe was supposed to update. This is done if the target file's last-modification time has changed since @code{make} first checked it. @@ -4187,7 +4013,7 @@ target is updated in some atomic fashion, or exists only to record a modification-time (its contents do not matter), or must exist at all times to prevent other sorts of trouble. -@node Recursion, Sequences, Interrupts, Commands +@node Recursion, Sequences, Interrupts, Recipes @section Recursive Use of @code{make} @cindex recursion @cindex subdirectories, recursion for @@ -4257,45 +4083,45 @@ subsystem: @end example The value of this variable is the file name with which @code{make} was -invoked. If this file name was @file{/bin/make}, then the command executed +invoked. If this file name was @file{/bin/make}, then the recipe executed is @samp{cd subdir && /bin/make}. If you use a special version of @code{make} to run the top-level makefile, the same special version will be executed for recursive invocations. @cindex @code{cd} (shell command) -@cindex +, and commands -As a special feature, using the variable @code{MAKE} in the commands of +@cindex +, and recipes +As a special feature, using the variable @code{MAKE} in the recipe of a rule alters the effects of the @samp{-t} (@samp{--touch}), @samp{-n} (@samp{--just-print}), or @samp{-q} (@w{@samp{--question}}) option. Using the @code{MAKE} variable has the same effect as using a @samp{+} -character at the beginning of the command line. @xref{Instead of -Execution, ,Instead of Executing the Commands}. This special feature +character at the beginning of the recipe line. @xref{Instead of +Execution, ,Instead of Executing the Recipes}. This special feature is only enabled if the @code{MAKE} variable appears directly in the -command script: it does not apply if the @code{MAKE} variable is -referenced through expansion of another variable. In the latter case -you must use the @samp{+} token to get these special effects.@refill +recipe: it does not apply if the @code{MAKE} variable is referenced +through expansion of another variable. In the latter case you must +use the @samp{+} token to get these special effects.@refill Consider the command @samp{make -t} in the above example. (The @samp{-t} option marks targets as up to date without actually running -any commands; see @ref{Instead of Execution}.) Following the usual +any recipes; see @ref{Instead of Execution}.) Following the usual definition of @samp{-t}, a @samp{make -t} command in the example would create a file named @file{subsystem} and do nothing else. What you -really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but that would -require executing the command, and @samp{-t} says not to execute -commands.@refill +really want it to do is run @samp{@w{cd subdir &&} @w{make -t}}; but +that would require executing the recipe, and @samp{-t} says not to +execute recipes.@refill @cindex @code{-t}, and recursion @cindex recursion, and @code{-t} @cindex @code{--touch}, and recursion -The special feature makes this do what you want: whenever a command +The special feature makes this do what you want: whenever a recipe line of a rule contains the variable @code{MAKE}, the flags @samp{-t}, -@samp{-n} and @samp{-q} do not apply to that line. Command lines +@samp{-n} and @samp{-q} do not apply to that line. Recipe lines containing @code{MAKE} are executed normally despite the presence of a -flag that causes most commands not to be run. The usual +flag that causes most recipes not to be run. The usual @code{MAKEFLAGS} mechanism passes the flags to the sub-@code{make} (@pxref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}), so your request to touch the files, or print the -commands, is propagated to the subsystem.@refill +recipes, is propagated to the subsystem.@refill @node Variables/Recursion, Options/Recursion, MAKE Variable, Recursion @subsection Communicating Variables to a Sub-@code{make} @@ -4314,11 +4140,11 @@ override what is specified in the makefile used by the sub-@code{make} makefile unless you use the @samp{-e} switch (@pxref{Options Summary, ,Summary of Options}).@refill -To pass down, or @dfn{export}, a variable, @code{make} adds the variable -and its value to the environment for running each command. The -sub-@code{make}, in turn, uses the environment to initialize its table -of variable values. @xref{Environment, ,Variables from the -Environment}. +To pass down, or @dfn{export}, a variable, @code{make} adds the +variable and its value to the environment for running each line of the +recipe. The sub-@code{make}, in turn, uses the environment to +initialize its table of variable values. @xref{Environment, +,Variables from the Environment}. Except by explicit request, @code{make} exports a variable only if it is either defined in the environment initially or set on the command @@ -4453,7 +4279,7 @@ Likewise, you can use @code{unexport} by itself to tell @code{make} behavior, you would only need to do this if @code{export} had been used by itself earlier (in an included makefile, perhaps). You @strong{cannot} use @code{export} and @code{unexport} by themselves to -have variables exported for some commands and not for others. The last +have variables exported for some recipes and not for others. The last @code{export} or @code{unexport} directive that appears by itself determines the behavior for the entire run of @code{make}.@refill @@ -4464,7 +4290,7 @@ is passed down from level to level. This variable's value is a string which is the depth of the level as a decimal number. The value is @samp{0} for the top-level @code{make}; @samp{1} for a sub-@code{make}, @samp{2} for a sub-sub-@code{make}, and so on. The incrementation -happens when @code{make} sets up the environment for a command.@refill +happens when @code{make} sets up the environment for a recipe.@refill The main use of @code{MAKELEVEL} is to test it in a conditional directive (@pxref{Conditionals, ,Conditional Parts of Makefiles}); this @@ -4533,7 +4359,7 @@ supports it (most any UNIX system will; others typically won't), the parent @code{make} and all the sub-@code{make}s will communicate to ensure that there are only @samp{N} jobs running at the same time between them all. Note that any job that is marked recursive -(@pxref{Instead of Execution, ,Instead of Executing the Commands}) +(@pxref{Instead of Execution, ,Instead of Executing the Recipes}) doesn't count against the total jobs (otherwise we could get @samp{N} sub-@code{make}s running and have no slots left over for any real work!) @@ -4669,18 +4495,20 @@ automatically turn on @samp{-w} if you also use @samp{-s}, which says to be silent, or if you use @samp{--no-print-directory} to explicitly disable it. -@node Sequences, Empty Commands, Recursion, Commands -@section Defining Canned Command Sequences +@node Sequences, Empty Recipes, Recursion, Recipes +@section Defining Canned Recipes +@cindex canned recipes +@cindex recipes, canned @cindex sequences of commands @cindex commands, sequences of -When the same sequence of commands is useful in making various targets, you -can define it as a canned sequence with the @code{define} directive, and -refer to the canned sequence from the rules for those targets. The canned -sequence is actually a variable, so the name must not conflict with other -variable names. +When the same sequence of commands is useful in making various +targets, you can define it as a canned sequence with the @code{define} +directive, and refer to the canned sequence from the recipes for those +targets. The canned sequence is actually a variable, so the name must +not conflict with other variable names. -Here is an example of defining a canned sequence of commands: +Here is an example of defining a canned recipes: @example define run-yacc @@ -4705,7 +4533,7 @@ whichever rule uses the canned sequence. The output file from Yacc is always named @file{y.tab.c}. The second command moves the output to the rule's target file name. -To use the canned sequence, substitute the variable into the commands of a +To use the canned sequence, substitute the variable into the recipe of a rule. You can substitute it like any other variable (@pxref{Reference, ,Basics of Variable References}). Because variables defined by @code{define} are recursively expanded @@ -4729,12 +4557,12 @@ commands based on the file names involved @cindex @@, and @code{define} @cindex -, and @code{define} @cindex +, and @code{define} -In command execution, each line of a canned sequence is treated just as +In recipe execution, each line of a canned sequence is treated just as if the line appeared on its own in the rule, preceded by a tab. In particular, @code{make} invokes a separate subshell for each line. You can use the special prefix characters that affect command lines (@samp{@@}, @samp{-}, and @samp{+}) on each line of a canned sequence. -@xref{Commands, ,Writing the Commands in Rules}. +@xref{Recipes, ,Writing Recipes in Rules}. For example, using this canned sequence: @example @@ -4747,9 +4575,9 @@ endef @noindent @code{make} will not echo the first line, the @code{echo} command. -But it @emph{will} echo the following two command lines. +But it @emph{will} echo the following two recipe lines. -On the other hand, prefix characters on the command line that refers to +On the other hand, prefix characters on the recipe line that refers to a canned sequence apply to every line in the sequence. So the rule: @example @@ -4758,16 +4586,16 @@ frob.out: frob.in @end example @noindent -does not echo @emph{any} commands. -(@xref{Echoing, ,Command Echoing}, for a full explanation of @samp{@@}.) +does not echo @emph{any} recipe lines. +(@xref{Echoing, ,Recipe Echoing}, for a full explanation of @samp{@@}.) -@node Empty Commands, , Sequences, Commands -@section Using Empty Commands -@cindex empty commands -@cindex commands, empty +@node Empty Recipes, , Sequences, Recipes +@section Using Empty Recipes +@cindex empty recipes +@cindex recipes, empty -It is sometimes useful to define commands which do nothing. This is done -simply by giving a command that consists of nothing but whitespace. For +It is sometimes useful to define recipes which do nothing. This is done +simply by giving a recipe that consists of nothing but whitespace. For example: @example @@ -4775,14 +4603,14 @@ target: ; @end example @noindent -defines an empty command string for @file{target}. You could also use a -line beginning with a tab character to define an empty command string, +defines an empty recipe for @file{target}. You could also use a line +beginning with a recipe prefix character to define an empty recipe, but this would be confusing because such a line looks empty. -@findex .DEFAULT@r{, and empty commands} -You may be wondering why you would want to define a command string that +@findex .DEFAULT@r{, and empty recipes} +You may be wondering why you would want to define a recipe that does nothing. The only reason this is useful is to prevent a target -from getting implicit commands (from implicit rules or the +from getting implicit recipes (from implicit rules or the @code{.DEFAULT} special target; @pxref{Implicit Rules} and @pxref{Last Resort, ,Defining Last-Resort Default Rules}).@refill @@ -4796,13 +4624,13 @@ stamp-foo: foo.in @end example @end ignore -You may be inclined to define empty command strings for targets that are +You may be inclined to define empty recipes for targets that are not actual files, but only exist so that their prerequisites can be remade. However, this is not the best way to do that, because the prerequisites may not be remade properly if the target file actually does exist. @xref{Phony Targets, ,Phony Targets}, for a better way to do this. -@node Using Variables, Conditionals, Commands, Top +@node Using Variables, Conditionals, Recipes, Top @chapter How to Use Variables @cindex variable @cindex value @@ -4811,15 +4639,15 @@ prerequisites may not be remade properly if the target file actually does exist. A @dfn{variable} is a name defined in a makefile to represent a string of text, called the variable's @dfn{value}. These values are -substituted by explicit request into targets, prerequisites, commands, +substituted by explicit request into targets, prerequisites, recipes, and other parts of the makefile. (In some other versions of @code{make}, variables are called @dfn{macros}.) @cindex macro Variables and functions in all parts of a makefile are expanded when -read, except for the shell commands in rules, the right-hand sides of -variable definitions using @samp{=}, and the bodies of variable -definitions using the @code{define} directive.@refill +read, except for in recipes, the right-hand sides of variable +definitions using @samp{=}, and the bodies of variable definitions +using the @code{define} directive.@refill Variables can represent lists of file names, options to pass to compilers, programs to run, directories to look in for source files, directories to @@ -4863,6 +4691,7 @@ they have particular specialized uses. @xref{Automatic Variables}. basis. * Pattern-specific:: Target-specific variable values can be applied to a group of targets that match a pattern. +* Special Variables:: Variables with special meaning or behavior. @end menu @node Reference, Flavors, Using Variables, Using Variables @@ -4876,10 +4705,10 @@ To substitute a variable's value, write a dollar sign followed by the name of the variable in parentheses or braces: either @samp{$(foo)} or @samp{$@{foo@}} is a valid reference to the variable @code{foo}. This special significance of @samp{$} is why you must write @samp{$$} to have -the effect of a single dollar sign in a file name or command. +the effect of a single dollar sign in a file name or recipe. Variable references can be used in any context: targets, prerequisites, -commands, most directives, and new variable values. Here is an +recipes, most directives, and new variable values. Here is an example of a common case, where a variable holds the names of all the object files in a program: @@ -4961,7 +4790,7 @@ include_dirs = -Ifoo -Ibar @end example @noindent -will do what was intended: when @samp{CFLAGS} is expanded in a command, +will do what was intended: when @samp{CFLAGS} is expanded in a recipe, it will expand to @samp{-Ifoo -Ibar -O}. A major disadvantage is that you cannot append something on the end of a variable, as in @@ -5037,7 +4866,7 @@ endif @noindent An advantage of this use of @samp{:=} is that a typical -`descend into a directory' command then looks like this: +`descend into a directory' recipe then looks like this: @example @group @@ -5685,10 +5514,10 @@ to use. You may nest @code{define} directives: @code{make} will keep track of nested directives and report an error if they are not all properly -closed with @code{endef}. Note that lines beginning with tab -characters are considered part of a command script, so any -@code{define} or @code{endef} strings appearing on such a line will -not be considered @code{make} operators. +closed with @code{endef}. Note that lines beginning with the recipe +prefix character are considered part of a recipe, so any @code{define} +or @code{endef} strings appearing on such a line will not be +considered @code{make} operators. @example define two-lines @@ -5703,8 +5532,8 @@ part of the variable's value (except for the final newline which precedes the @code{endef} and is not considered part of the value).@refill @need 800 -When used in a command script, the previous example is functionally -equivalent to this: +When used in a recipe, the previous example is functionally equivalent +to this: @example two-lines = echo foo; echo $(bar) @@ -5714,7 +5543,7 @@ two-lines = echo foo; echo $(bar) since two commands separated by semicolon behave much like two separate shell commands. However, note that using two separate lines means @code{make} will invoke the shell twice, running an independent subshell -for each line. @xref{Execution, ,Command Execution}. +for each line. @xref{Execution, ,Recipe Execution}. If you want variable definitions made with @code{define} to take precedence over command-line variable definitions, you can use the @@ -5751,8 +5580,8 @@ because you know that no makefile will use them for other things. (Note this is not totally reliable; some makefiles set @code{CFLAGS} explicitly and therefore are not affected by the value in the environment.) -When @code{make} runs a command script, variables defined in the -makefile are placed into the environment of that command. This allows +When @code{make} runs a recipe, variables defined in the +makefile are placed into the environment of each shell. This allows you to pass values to sub-@code{make} invocations (@pxref{Recursion, ,Recursive Use of @code{make}}). By default, only variables that came from the environment or the command line are passed to recursive @@ -5788,7 +5617,7 @@ The other exception is @dfn{target-specific variable values}. This feature allows you to define different values for the same variable, based on the target that @code{make} is currently building. As with automatic variables, these values are only available within the context -of a target's command script (and in other target-specific assignments). +of a target's recipe (and in other target-specific assignments). Set a target-specific variable value like this: @@ -5823,7 +5652,7 @@ any ``global'' value: the two variables do not have to have the same flavor (recursive vs.@: static). Target-specific variables have the same priority as any other makefile -variable. Variables provided on the command-line (and in the +variable. Variables provided on the command line (and in the environment if the @samp{-e} option is in force) will take precedence. Specifying the @code{override} directive will allow the target-specific variable value to be preferred. @@ -5841,11 +5670,10 @@ prog : prog.o foo.o bar.o @end example @noindent -will set @code{CFLAGS} to @samp{-g} in the command script for -@file{prog}, but it will also set @code{CFLAGS} to @samp{-g} in the -command scripts that create @file{prog.o}, @file{foo.o}, and -@file{bar.o}, and any command scripts which create their -prerequisites. +will set @code{CFLAGS} to @samp{-g} in the recipe for @file{prog}, but +it will also set @code{CFLAGS} to @samp{-g} in the recipes that create +@file{prog.o}, @file{foo.o}, and @file{bar.o}, and any recipes which +create their prerequisites. Be aware that a given prerequisite will only be built once per invocation of make, at most. If the same file is a prerequisite of @@ -5855,7 +5683,7 @@ will cause that prerequisite to be built and the prerequisite will inherit the target-specific value from the first target. It will ignore the target-specific values from any other targets. -@node Pattern-specific, , Target-specific, Using Variables +@node Pattern-specific, Special Variables, Target-specific, Using Variables @section Pattern-specific Variable Values @cindex pattern-specific variables @cindex variables, pattern-specific @@ -5888,7 +5716,7 @@ or like this: where @var{pattern} is a %-pattern. As with target-specific variable values, multiple @var{pattern} values create a pattern-specific variable value for each pattern individually. The @var{variable-assignment} can -be any valid form of assignment. Any command-line variable setting will +be any valid form of assignment. Any command line variable setting will take precedence, unless @code{override} is specified. For example: @@ -5901,16 +5729,201 @@ For example: will assign @code{CFLAGS} the value of @samp{-O} for all targets matching the pattern @code{%.o}. +@node Special Variables, , Pattern-specific, Using Variables +@comment node-name, next, previous, up +@section Other Special Variables +@cindex makefiles, and special variables +@cindex special variables + +GNU @code{make} supports some variables that have special properties. + +@table @code + +@vindex MAKEFILE_LIST @r{(list of parsed makefiles)} +@cindex makefiles, and @code{MAKEFILE_LIST} variable +@cindex including (@code{MAKEFILE_LIST} variable) +@item MAKEFILE_LIST +Contains the name of each makefile that is parsed by @code{make}, in +the order in which it was parsed. The name is appended just +before @code{make} begins to parse the makefile. Thus, if the first +thing a makefile does is examine the last word in this variable, it +will be the name of the current makefile. Once the current makefile +has used @code{include}, however, the last word will be the +just-included makefile. + +If a makefile named @code{Makefile} has this content: + +@example +@group +name1 := $(lastword $(MAKEFILE_LIST)) + +include inc.mk + +name2 := $(lastword $(MAKEFILE_LIST)) + +all: + @@echo name1 = $(name1) + @@echo name2 = $(name2) +@end group +@end example + +@noindent +then you would expect to see this output: + +@example +@group +name1 = Makefile +name2 = inc.mk +@end group +@end example + +@vindex .DEFAULT_GOAL @r{(define default goal)} +@item .DEFAULT_GOAL +Sets the default goal to be used if no targets were specified on the +command line (@pxref{Goals, , Arguments to Specify the Goals}). The +@code{.DEFAULT_GOAL} variable allows you to discover the current +default goal, restart the default goal selection algorithm by clearing +its value, or to explicitly set the default goal. The following +example illustrates these cases: + +@example +@group +# Query the default goal. +ifeq ($(.DEFAULT_GOAL),) + $(warning no default goal is set) +endif + +.PHONY: foo +foo: ; @@echo $@@ + +$(warning default goal is $(.DEFAULT_GOAL)) + +# Reset the default goal. +.DEFAULT_GOAL := + +.PHONY: bar +bar: ; @@echo $@@ + +$(warning default goal is $(.DEFAULT_GOAL)) + +# Set our own. +.DEFAULT_GOAL := foo +@end group +@end example + +This makefile prints: + +@example +@group +no default goal is set +default goal is foo +default goal is bar +foo +@end group +@end example + +Note that assigning more than one target name to @code{.DEFAULT_GOAL} is +illegal and will result in an error. + +@vindex MAKE_RESTARTS @r{(number of times @code{make} has restarted)} +@item MAKE_RESTARTS +This variable is set only if this instance of @code{make} has +restarted (@pxref{Remaking Makefiles, , How Makefiles Are Remade}): it +will contain the number of times this instance has restarted. Note +this is not the same as recursion (counted by the @code{MAKELEVEL} +variable). You should not set, modify, or export this variable. + +@vindex .CMDPREFIX @r{(change the recipe prefix character)} +@item .CMDPREFIX +The first character of the value of this variable is used as the +character make assumes is introducing a recipe line. If the variable +is empty (as it is by default) that character is the standard tab +character. For example, this is a valid makefile: + +@example +@group +.CMDPREFIX = > +all: +> @@echo Hello, world +@end group +@end example + +The value of @code{.CMDPREFIX} can be changed multiple times; once set +it stays in effect for all rules parsed until it is modified. + +@vindex .VARIABLES @r{(list of variables)} +@item .VARIABLES +Expands to a list of the @emph{names} of all global variables defined +so far. This includes variables which have empty values, as well as +built-in variables (@pxref{Implicit Variables, , Variables Used by +Implicit Rules}), but does not include any variables which are only +defined in a target-specific context. Note that any value you assign +to this variable will be ignored; it will always return its special +value. + +@c @vindex .TARGETS @r{(list of targets)} +@c @item .TARGETS +@c The second special variable is @code{.TARGETS}. When expanded, the +@c value consists of a list of all targets defined in all makefiles read +@c up until that point. Note it's not enough for a file to be simply +@c mentioned in the makefile to be listed in this variable, even if it +@c would match an implicit rule and become an ``implicit target''. The +@c file must appear as a target, on the left-hand side of a ``:'', to be +@c considered a target for the purposes of this variable. + +@vindex .FEATURES @r{(list of supported features)} +@item .FEATURES +Expands to a list of special features supported by this version of +@code{make}. Possible values include: + +@table @samp + +@item archives +Supports @code{ar} (archive) files using special filename syntax. +@xref{Archives, ,Using @code{make} to Update Archive Files}. + +@item check-symlink +Supports the @code{-L} (@code{--check-symlink-times}) flag. +@xref{Options Summary, ,Summary of Options}. + +@item else-if +Supports ``else if'' non-nested conditionals. @xref{Conditional +Syntax, ,Syntax of Conditionals}. + +@item jobserver +Supports ``job server'' enhanced parallel builds. @xref{Parallel, +,Parallel Execution}. + +@item second-expansion +Supports secondary expansion of prerequisite lists. + +@item order-only +Supports order-only prerequisites. @xref{Prerequisite Types, ,Types +of Prerequisites}. + +@item target-specific +Supports target-specific and pattern-specific variable assignments. +@xref{Target-specific, ,Target-specific Variable Values}. + +@end table + +@vindex .INCLUDE_DIRS @r{(list of include directories)} +@item .INCLUDE_DIRS +Expands to a list of directories that @code{make} searches for +included makefiles (@pxref{Include, , Including Other Makefiles}). + +@end table + @node Conditionals, Functions, Using Variables, Top @chapter Conditional Parts of Makefiles @cindex conditionals -A @dfn{conditional} causes part of a makefile to be obeyed or ignored -depending on the values of variables. Conditionals can compare the -value of one variable to another, or the value of a variable to -a constant string. Conditionals control what @code{make} actually -``sees'' in the makefile, so they @emph{cannot} be used to control shell -commands at the time of execution.@refill +A @dfn{conditional} directive causes part of a makefile to be obeyed +or ignored depending on the values of variables. Conditionals can +compare the value of one variable to another, or the value of a +variable to a constant string. Conditionals control what @code{make} +actually ``sees'' in the makefile, so they @emph{cannot} be used to +control recipes at the time of execution.@refill @menu * Conditional Example:: Example of a conditional @@ -5921,11 +5934,11 @@ commands at the time of execution.@refill @node Conditional Example, Conditional Syntax, Conditionals, Conditionals @section Example of a Conditional -The following example of a conditional tells @code{make} to use one set -of libraries if the @code{CC} variable is @samp{gcc}, and a different -set of libraries otherwise. It works by controlling which of two -command lines will be used as the command for a rule. The result is -that @samp{CC=gcc} as an argument to @code{make} changes not only which +The following example of a conditional tells @code{make} to use one +set of libraries if the @code{CC} variable is @samp{gcc}, and a +different set of libraries otherwise. It works by controlling which +of two recipe lines will be used for the rule. The result is that +@samp{CC=gcc} as an argument to @code{make} changes not only which compiler is used but also which libraries are linked. @example @@ -6152,12 +6165,12 @@ if any, is effective. The rules for expansion and testing of @var{variable-name} are identical to the @code{ifdef} directive. @end table -Extra spaces are allowed and ignored at the beginning of the conditional -directive line, but a tab is not allowed. (If the line begins with a tab, -it will be considered a command for a rule.) Aside from this, extra spaces -or tabs may be inserted with no effect anywhere except within the directive -name or within an argument. A comment starting with @samp{#} may appear at -the end of the line. +Extra spaces are allowed and ignored at the beginning of the +conditional directive line, but a tab is not allowed. (If the line +begins with a tab, it will be considered part of a recipe for a rule.) +Aside from this, extra spaces or tabs may be inserted with no effect +anywhere except within the directive name or within an argument. A +comment starting with @samp{#} may appear at the end of the line. The other two directives that play a part in a conditional are @code{else} and @code{endif}. Each of these directives is written as one word, with no @@ -6174,7 +6187,7 @@ beginning or the end of the conditional.@refill @code{make} evaluates conditionals when it reads a makefile. Consequently, you cannot use automatic variables in the tests of -conditionals because they are not defined until commands are run +conditionals because they are not defined until recipes are run (@pxref{Automatic Variables}). To prevent intolerable confusion, it is not permitted to start a @@ -6211,20 +6224,21 @@ endif @end example @noindent -The @samp{+} prefix marks those command lines as ``recursive'' so -that they will be executed despite use of the @samp{-t} flag. +The @samp{+} prefix marks those recipe lines as ``recursive'' so that +they will be executed despite use of the @samp{-t} flag. @xref{Recursion, ,Recursive Use of @code{make}}. @node Functions, Running, Conditionals, Top @chapter Functions for Transforming Text @cindex functions -@dfn{Functions} allow you to do text processing in the makefile to compute -the files to operate on or the commands to use. You use a function in a -@dfn{function call}, where you give the name of the function and some text -(the @dfn{arguments}) for the function to operate on. The result of the -function's processing is substituted into the makefile at the point of the -call, just as a variable might be substituted. +@dfn{Functions} allow you to do text processing in the makefile to +compute the files to operate on or the commands to use in recipes. +You use a function in a @dfn{function call}, where you give the name +of the function and some text (the @dfn{arguments}) for the function +to operate on. The result of the function's processing is substituted +into the makefile at the point of the call, just as a variable might +be substituted. @menu * Syntax of Functions:: How to write a function call. @@ -7237,9 +7251,8 @@ makefile (@pxref{Override Directive, ,The @code{override} Directive}). @item automatic -if @var{variable} is an automatic variable defined for the -execution of the commands for each rule -(@pxref{Automatic Variables}). +if @var{variable} is an automatic variable defined for the execution +of the recipe for each rule (@pxref{Automatic Variables}). @end table This information is primarily useful (other than for your curiosity) to @@ -7329,7 +7342,7 @@ if @var{variable} is a simply expanded variable. @node Shell Function, Make Control Functions, Flavor Function, Functions @section The @code{shell} Function @findex shell -@cindex commands, expansion +@cindex command expansion @cindex backquotes @cindex shell command, function for @@ -7388,11 +7401,11 @@ if some sort of environmental error is detected. @findex error @cindex error, stopping on @cindex stopping make -Generates a fatal error where the message is @var{text}. Note that the -error is generated whenever this function is evaluated. So, if you put -it inside a command script or on the right side of a recursive variable -assignment, it won't be evaluated until later. The @var{text} will be -expanded before the error is generated. +Generates a fatal error where the message is @var{text}. Note that +the error is generated whenever this function is evaluated. So, if +you put it inside a recipe or on the right side of a recursive +variable assignment, it won't be evaluated until later. The +@var{text} will be expanded before the error is generated. For example, @@ -7462,7 +7475,7 @@ It will print messages describing the particular errors. @item 1 The exit status is one if you use the @samp{-q} flag and @code{make} determines that some target is not already up to date. -@xref{Instead of Execution, ,Instead of Executing the Commands}. +@xref{Instead of Execution, ,Instead of Executing the Recipes}. @end table @menu @@ -7470,7 +7483,7 @@ determines that some target is not already up to date. * Goals:: How to use goal arguments to specify which parts of the makefile to use. * Instead of Execution:: How to use mode flags to specify what - kind of thing to do with the commands + kind of thing to do with the recipes in the makefile other than simply execute them. * Avoiding Compilation:: How to avoid recompiling certain files. @@ -7517,7 +7530,7 @@ the whole list. You can manage the selection of the default goal from within your makefile using the @code{.DEFAULT_GOAL} variable (@pxref{Special Variables, , Other Special Variables}). -You can also specify a different goal or goals with command-line +You can also specify a different goal or goals with command line arguments to @code{make}. Use the name of the goal as an argument. If you specify several goals, @code{make} processes each of them in turn, in the order you name them. @@ -7567,7 +7580,7 @@ made. For example, there may be a file of debugging output, or a version of the program that is compiled specially for testing, which has a rule in the makefile but is not a prerequisite of the default goal. -Another use of specifying a goal is to run the commands associated with +Another use of specifying a goal is to run the recipe associated with a phony target (@pxref{Phony Targets}) or empty target (@pxref{Empty Targets, ,Empty Target Files to Record Events}). Many makefiles contain a phony target named @file{clean} which deletes everything except source @@ -7639,9 +7652,9 @@ Perform self tests on the program this makefile builds. @end table @node Instead of Execution, Avoiding Compilation, Goals, Running -@section Instead of Executing the Commands +@section Instead of Executing the Recipes @cindex execution, instead of -@cindex commands, instead of executing +@cindex recipes, instead of executing The makefile tells @code{make} how to tell whether a target is up to date, and how to update each target. But updating the targets is not always @@ -7658,8 +7671,8 @@ what you want. Certain options specify other activities for @code{make}. @cindex @code{--recon} @cindex @code{-n} -``No-op''. The activity is to print what commands would be used to make -the targets up to date, but not actually execute them. +``No-op''. The activity is to print what recipe would be used to make +the targets up to date, but not actually execute it. @item -t @itemx --touch @@ -7679,7 +7692,7 @@ the targets but does not really change their contents. @cindex question mode ``Question''. The activity is to find out silently whether the targets -are up to date already; but execute no commands in either case. In other +are up to date already; but execute no recipe in either case. In other words, neither compilation nor output will occur. @item -W @var{file} @@ -7700,17 +7713,17 @@ You can use the @samp{-W} flag in conjunction with the @samp{-n} flag to see what would happen if you were to modify specific files.@refill @end table -With the @samp{-n} flag, @code{make} prints the commands that it would -normally execute but does not execute them. +With the @samp{-n} flag, @code{make} prints the recipe that it would +normally execute but does not execute it. -With the @samp{-t} flag, @code{make} ignores the commands in the rules +With the @samp{-t} flag, @code{make} ignores the recipes in the rules and uses (in effect) the command @code{touch} for each target that needs to be remade. The @code{touch} command is also printed, unless @samp{-s} or @code{.SILENT} is used. For speed, @code{make} does not actually invoke the program @code{touch}. It does the work directly. With the @samp{-q} flag, @code{make} prints nothing and executes no -commands, but the exit status code it returns is zero if and only if the +recipes, but the exit status code it returns is zero if and only if the targets to be considered are already up to date. If the exit status is one, then some updating needs to be done. If @code{make} encounters an error, the exit status is two, so you can distinguish an error from a @@ -7719,8 +7732,8 @@ target that is not up to date. It is an error to use more than one of these three flags in the same invocation of @code{make}. -@cindex +, and command execution -The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect command +@cindex +, and recipe execution +The @samp{-n}, @samp{-t}, and @samp{-q} options do not affect recipe lines that begin with @samp{+} characters or contain the strings @samp{$(MAKE)} or @samp{$@{MAKE@}}. Note that only the line containing the @samp{+} character or the strings @samp{$(MAKE)} or @samp{$@{MAKE@}} @@ -7737,9 +7750,9 @@ If you also use the @samp{-n} or @samp{-q} flag, you can see what @item Without the @samp{-n} or @samp{-q} flag, when @code{make} is actually -executing commands, the @samp{-W} flag can direct @code{make} to act -as if some files had been modified, without actually modifying the -files.@refill +executing recipes, the @samp{-W} flag can direct @code{make} to act as +if some files had been modified, without actually running the recipes +for those files.@refill @end itemize Note that the options @samp{-p} and @samp{-v} allow you to obtain other @@ -7765,7 +7778,7 @@ the time waiting for them to compile. If you anticipate the problem before changing the header file, you can use the @samp{-t} flag. This flag tells @code{make} not to run the -commands in the rules, but rather to mark the target up to date by +recipes in the rules, but rather to mark the target up to date by changing its last-modification date. You would follow this procedure: @enumerate @@ -7816,7 +7829,7 @@ variable in the makefile are ignored; we say they have been The most common way to use this facility is to pass extra flags to compilers. For example, in a properly written makefile, the variable -@code{CFLAGS} is included in each command that runs the C compiler, so a +@code{CFLAGS} is included in each recipe that runs the C compiler, so a file @file{foo.c} would be compiled something like this: @example @@ -7846,13 +7859,13 @@ You can also program the makefile to look at additional variables of your own, giving the user the ability to control other aspects of how the makefile works by changing the variables. -When you override a variable with a command argument, you can define either -a recursively-expanded variable or a simply-expanded variable. The -examples shown above make a recursively-expanded variable; to make a -simply-expanded variable, write @samp{:=} instead of @samp{=}. But, unless -you want to include a variable reference or function call in the -@emph{value} that you specify, it makes no difference which kind of -variable you create. +When you override a variable with a command line argument, you can +define either a recursively-expanded variable or a simply-expanded +variable. The examples shown above make a recursively-expanded +variable; to make a simply-expanded variable, write @samp{:=} instead +of @samp{=}. But, unless you want to include a variable reference or +function call in the @emph{value} that you specify, it makes no +difference which kind of variable you create. There is one way that the makefile can change a variable that you have overridden. This is to use the @code{override} directive, which is a line @@ -7865,7 +7878,7 @@ that looks like this: @samp{override @var{variable} = @var{value}} @cindex compilation, testing Normally, when an error happens in executing a shell command, @code{make} -gives up immediately, returning a nonzero status. No further commands are +gives up immediately, returning a nonzero status. No further recipes are executed for any target. The error implies that the goal cannot be correctly remade, and @code{make} reports this as soon as it knows. @@ -8014,8 +8027,8 @@ Remind you of the options that @code{make} understands and then exit. @cindex @code{-i} @itemx --ignore-errors @cindex @code{--ignore-errors} -Ignore all errors in commands executed to remake files. -@xref{Errors, ,Errors in Commands}. +Ignore all errors in recipes executed to remake files. +@xref{Errors, ,Errors in Recipes}. @item -I @var{dir} @cindex @code{-I} @@ -8030,12 +8043,11 @@ searched in the order specified. @cindex @code{-j} @itemx --jobs[=@var{jobs}] @cindex @code{--jobs} -Specifies the number of jobs (commands) to run simultaneously. With no -argument, @code{make} runs as many jobs simultaneously as possible. If -there is more than one @samp{-j} option, the last one is effective. -@xref{Parallel, ,Parallel Execution}, -for more information on how commands are run. -Note that this option is ignored on MS-DOS. +Specifies the number of recipes (jobs) to run simultaneously. With no +argument, @code{make} runs as many recipes simultaneously as possible. +If there is more than one @samp{-j} option, the last one is effective. +@xref{Parallel, ,Parallel Execution}, for more information on how +recipes are run. Note that this option is ignored on MS-DOS. @item -k @cindex @code{-k} @@ -8052,8 +8064,8 @@ prerequisites of these targets can be processed all the same. @cindex @code{--load-average} @itemx --max-load[=@var{load}] @cindex @code{--max-load} -Specifies that no new jobs (commands) should be started if there are -other jobs running and the load average is at least @var{load} (a +Specifies that no new recipes should be started if there are other +recipes running and the load average is at least @var{load} (a floating-point number). With no argument, removes a previous load limit. @xref{Parallel, ,Parallel Execution}. @@ -8077,8 +8089,8 @@ links is taken as the modification time for this target file. @cindex @code{--recon} @c Extra blank line here makes the table look better. -Print the commands that would be executed, but do not execute them. -@xref{Instead of Execution, ,Instead of Executing the Commands}. +Print the recipe that would be executed, but do not execute it. +@xref{Instead of Execution, ,Instead of Executing the Recipes}. @item -o @var{file} @cindex @code{-o} @@ -8099,23 +8111,24 @@ Some Files}.@refill @cindex data base of @code{make} rules @cindex predefined rules and variables, printing Print the data base (rules and variable values) that results from -reading the makefiles; then execute as usual or as otherwise specified. -This also prints the version information given by the @samp{-v} switch -(see below). To print the data base without trying to remake any files, -use @w{@samp{make -qp}}. To print the data base of predefined rules and -variables, use @w{@samp{make -p -f /dev/null}}. The data base output -contains filename and linenumber information for command and variable -definitions, so it can be a useful debugging tool in complex environments. +reading the makefiles; then execute as usual or as otherwise +specified. This also prints the version information given by the +@samp{-v} switch (see below). To print the data base without trying +to remake any files, use @w{@samp{make -qp}}. To print the data base +of predefined rules and variables, use @w{@samp{make -p -f /dev/null}}. +The data base output contains filename and linenumber information for +recipe and variable definitions, so it can be a useful debugging tool +in complex environments. @item -q @cindex @code{-q} @itemx --question @cindex @code{--question} -``Question mode''. Do not run any commands, or print anything; just +``Question mode''. Do not run any recipes, or print anything; just return an exit status that is zero if the specified targets are already up to date, one if any remaking is required, or two if an error is encountered. @xref{Instead of Execution, ,Instead of Executing the -Commands}.@refill +Recipes}.@refill @item -r @cindex @code{-r} @@ -8150,8 +8163,8 @@ implicit rules without any definitions for the variables that they use. @cindex @code{--quiet} @c Extra blank line here makes the table look better. -Silent operation; do not print the commands as they are executed. -@xref{Echoing, ,Command Echoing}. +Silent operation; do not print the recipes as they are executed. +@xref{Echoing, ,Recipe Echoing}. @item -S @cindex @code{-S} @@ -8174,9 +8187,9 @@ or if you set @samp{-k} in @code{MAKEFLAGS} in your environment.@refill @c Extra blank line here makes the table look better. Touch files (mark them up to date without really changing them) -instead of running their commands. This is used to pretend that the -commands were done, in order to fool future invocations of -@code{make}. @xref{Instead of Execution, ,Instead of Executing the Commands}. +instead of running their recipes. This is used to pretend that the +recipes were done, in order to fool future invocations of +@code{make}. @xref{Instead of Execution, ,Instead of Executing the Recipes}. @item -v @cindex @code{-v} @@ -8217,7 +8230,7 @@ to modify that file. Without @samp{-n}, it is almost the same as running a @code{touch} command on the given file before running @code{make}, except that the modification time is changed only in the imagination of @code{make}. -@xref{Instead of Execution, ,Instead of Executing the Commands}. +@xref{Instead of Execution, ,Instead of Executing the Recipes}. @item --warn-undefined-variables @cindex @code{--warn-undefined-variables} @@ -8251,7 +8264,7 @@ will remake a @file{.o} file from a @file{.y} file by way of a @file{.c} file. @xref{Chained Rules, ,Chains of Implicit Rules}. @end iftex -The built-in implicit rules use several variables in their commands so +The built-in implicit rules use several variables in their recipes so that, by changing the values of the variables, you can change the way the implicit rule works. For example, the variable @code{CFLAGS} controls the flags given to the C compiler by the implicit rule for C compilation. @@ -8273,12 +8286,12 @@ retained for compatibility. @menu * Using Implicit:: How to use an existing implicit rule - to get the commands for updating a file. + to get the recipes for updating a file. * Catalogue of Rules:: A list of built-in implicit rules. * Implicit Variables:: How to change what predefined rules do. * Chained Rules:: How to use a chain of implicit rules. * Pattern Rules:: How to define new implicit rules. -* Last Resort:: How to define commands for rules which +* Last Resort:: How to define recipes for rules which cannot find any. * Suffix Rules:: The old-fashioned style of implicit rule. * Implicit Rule Search:: The precise algorithm for applying @@ -8290,11 +8303,11 @@ retained for compatibility. @cindex implicit rule, how to use @cindex rule, implicit, how to use -To allow @code{make} to find a customary method for updating a target file, -all you have to do is refrain from specifying commands yourself. Either -write a rule with no command lines, or don't write a rule at all. Then -@code{make} will figure out which implicit rule to use based on which -kind of source file exists or can be made. +To allow @code{make} to find a customary method for updating a target +file, all you have to do is refrain from specifying recipes yourself. +Either write a rule with no recipe, or don't write a rule at all. +Then @code{make} will figure out which implicit rule to use based on +which kind of source file exists or can be made. For example, suppose the makefile looks like this: @@ -8308,9 +8321,9 @@ Because you mention @file{foo.o} but do not give a rule for it, @code{make} will automatically look for an implicit rule that tells how to update it. This happens whether or not the file @file{foo.o} currently exists. -If an implicit rule is found, it can supply both commands and one or +If an implicit rule is found, it can supply both a recipe and one or more prerequisites (the source files). You would want to write a rule -for @file{foo.o} with no command lines if you need to specify additional +for @file{foo.o} with no recipe if you need to specify additional prerequisites, such as header files, that the implicit rule cannot supply. @@ -8337,7 +8350,7 @@ result of another implicit rule, we say that @dfn{chaining} is occurring. @xref{Chained Rules, ,Chains of Implicit Rules}. In general, @code{make} searches for an implicit rule for each target, and -for each double-colon rule, that has no commands. A file that is mentioned +for each double-colon rule, that has no recipe. A file that is mentioned only as a prerequisite is considered a target whose rule specifies nothing, so implicit rule search happens for it. @xref{Implicit Rule Search, ,Implicit Rule Search Algorithm}, for the details of how the search is done. @@ -8360,8 +8373,8 @@ implicit rules (@pxref{Catalogue of Rules, , Catalogue of Implicit Rules}). If you do not want an implicit rule to be used for a target that has no -commands, you can give that target empty commands by writing a semicolon -(@pxref{Empty Commands, ,Defining Empty Commands}). +recipe, you can give that target an empty recipe by writing a semicolon +(@pxref{Empty Recipes, ,Defining Empty Recipes}). @node Catalogue of Rules, Implicit Variables, Using Implicit, Implicit Rules @section Catalogue of Implicit Rules @@ -8407,7 +8420,7 @@ for full details on suffix rules. @pindex .o @pindex .c @file{@var{n}.o} is made automatically from @file{@var{n}.c} with -a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill +a recipe of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill @item Compiling C++ programs @cindex C++, rule to compile @@ -8416,7 +8429,7 @@ a command of the form @samp{$(CC) -c $(CPPFLAGS) $(CFLAGS)}.@refill @pindex .cpp @pindex .C @file{@var{n}.o} is made automatically from @file{@var{n}.cc}, -@file{@var{n}.cpp}, or @file{@var{n}.C} with a command of the form +@file{@var{n}.cpp}, or @file{@var{n}.C} with a recipe of the form @samp{$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)}. We encourage you to use the suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill @@ -8425,7 +8438,7 @@ suffix @samp{.cc} for C++ source files instead of @samp{.C}.@refill @pindex pc @pindex .p @file{@var{n}.o} is made automatically from @file{@var{n}.p} -with the command @samp{$(PC) -c $(PFLAGS)}.@refill +with the recipe @samp{$(PC) -c $(PFLAGS)}.@refill @item Compiling Fortran and Ratfor programs @cindex Fortran, rule to compile @@ -8436,7 +8449,7 @@ with the command @samp{$(PC) -c $(PFLAGS)}.@refill @pindex .F @file{@var{n}.o} is made automatically from @file{@var{n}.r}, @file{@var{n}.F} or @file{@var{n}.f} by running the -Fortran compiler. The precise command used is as follows:@refill +Fortran compiler. The precise recipe used is as follows:@refill @table @samp @item .f @@ -8451,7 +8464,7 @@ Fortran compiler. The precise command used is as follows:@refill @file{@var{n}.f} is made automatically from @file{@var{n}.r} or @file{@var{n}.F}. This rule runs just the preprocessor to convert a Ratfor or preprocessable Fortran program into a strict Fortran -program. The precise command used is as follows:@refill +program. The precise recipe used is as follows:@refill @table @samp @item .F @@ -8466,7 +8479,7 @@ program. The precise command used is as follows:@refill @pindex .sym @pindex .def @pindex .mod -@file{@var{n}.sym} is made from @file{@var{n}.def} with a command +@file{@var{n}.sym} is made from @file{@var{n}.def} with a recipe of the form @samp{$(M2C) $(M2FLAGS) $(DEFFLAGS)}. @file{@var{n}.o} is made from @file{@var{n}.mod}; the form is: @w{@samp{$(M2C) $(M2FLAGS) $(MODFLAGS)}}.@refill @@ -8477,12 +8490,12 @@ is made from @file{@var{n}.mod}; the form is: @pindex as @pindex .s @file{@var{n}.o} is made automatically from @file{@var{n}.s} by -running the assembler, @code{as}. The precise command is +running the assembler, @code{as}. The precise recipe is @samp{$(AS) $(ASFLAGS)}.@refill @pindex .S @file{@var{n}.s} is made automatically from @file{@var{n}.S} by -running the C preprocessor, @code{cpp}. The precise command is +running the C preprocessor, @code{cpp}. The precise recipe is @w{@samp{$(CPP) $(CPPFLAGS)}}. @item Linking a single object file @@ -8491,7 +8504,7 @@ running the C preprocessor, @code{cpp}. The precise command is @pindex .o @file{@var{n}} is made automatically from @file{@var{n}.o} by running the linker (usually called @code{ld}) via the C compiler. The precise -command used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}. +recipe used is @w{@samp{$(CC) $(LDFLAGS) @var{n}.o $(LOADLIBES) $(LDLIBS)}}. This rule does the right thing for a simple program with only one source file. It will also do the right thing if there are multiple @@ -8520,7 +8533,7 @@ rm -f z.o @noindent In more complicated cases, such as when there is no object file whose name derives from the executable file name, you must write an explicit -command for linking. +recipe for linking. Each kind of file automatically made into @samp{.o} object files will be automatically linked by using the compiler (@samp{$(CC)}, @@ -8535,18 +8548,18 @@ done.@refill @cindex Yacc, rule to run @pindex .y @file{@var{n}.c} is made automatically from @file{@var{n}.y} by -running Yacc with the command @samp{$(YACC) $(YFLAGS)}. +running Yacc with the recipe @samp{$(YACC) $(YFLAGS)}. @item Lex for C programs @pindex lex @cindex Lex, rule to run @pindex .l @file{@var{n}.c} is made automatically from @file{@var{n}.l} by -running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. +running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}. @item Lex for Ratfor programs @file{@var{n}.r} is made automatically from @file{@var{n}.l} by -running Lex. The actual command is @samp{$(LEX) $(LFLAGS)}. +running Lex. The actual recipe is @samp{$(LEX) $(LFLAGS)}. The convention of using the same suffix @samp{.l} for all Lex files regardless of whether they produce C code or Ratfor code makes it @@ -8571,8 +8584,8 @@ the list of implicit rule suffixes with:@refill @cindex @code{lint}, rule to run @pindex .ln @file{@var{n}.ln} is made from @file{@var{n}.c} by running @code{lint}. -The precise command is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. -The same command is used on the C code produced from +The precise recipe is @w{@samp{$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i}}. +The same recipe is used on the C code produced from @file{@var{n}.y} or @file{@var{n}.l}.@refill @item @TeX{} and Web @@ -8588,7 +8601,7 @@ The same command is used on the C code produced from @pindex .web @pindex .w @pindex .ch -@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the command +@file{@var{n}.dvi} is made from @file{@var{n}.tex} with the recipe @samp{$(TEX)}. @file{@var{n}.tex} is made from @file{@var{n}.web} with @samp{$(WEAVE)}, or from @file{@var{n}.w} (and from @file{@var{n}.ch} if it exists or can be made) with @samp{$(CWEAVE)}. @file{@var{n}.p} is @@ -8606,10 +8619,10 @@ or can be made) with @samp{$(CTANGLE)}.@refill @pindex .texi @pindex .txinfo @file{@var{n}.dvi} is made from @file{@var{n}.texinfo}, -@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the command +@file{@var{n}.texi}, or @file{@var{n}.txinfo}, with the recipe @w{@samp{$(TEXI2DVI) $(TEXI2DVI_FLAGS)}}. @file{@var{n}.info} is made from @file{@var{n}.texinfo}, @file{@var{n}.texi}, or @file{@var{n}.txinfo}, with -the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. +the recipe @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. @item RCS @cindex RCS, rule to extract from @@ -8617,7 +8630,7 @@ the command @w{@samp{$(MAKEINFO) $(MAKEINFO_FLAGS)}}. @pindex ,v @r{(RCS file extension)} Any file @file{@var{n}} is extracted if necessary from an RCS file named either @file{@var{n},v} or @file{RCS/@var{n},v}. The precise -command used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be +recipe used is @w{@samp{$(CO) $(COFLAGS)}}. @file{@var{n}} will not be extracted from RCS if it already exists, even if the RCS file is newer. The rules for RCS are terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), @@ -8630,7 +8643,7 @@ actually exist.@refill @pindex s. @r{(SCCS file prefix)} Any file @file{@var{n}} is extracted if necessary from an SCCS file named either @file{s.@var{n}} or @file{SCCS/s.@var{n}}. The precise -command used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are +recipe used is @w{@samp{$(GET) $(GFLAGS)}}. The rules for SCCS are terminal (@pxref{Match-Anything Rules, ,Match-Anything Pattern Rules}), so SCCS files cannot be generated from another source; they must actually exist.@refill @@ -8651,9 +8664,9 @@ software movement. Usually, you want to change only the variables listed in the table above, which are documented in the following section. -However, the commands in built-in implicit rules actually use +However, the recipes in built-in implicit rules actually use variables such as @code{COMPILE.c}, @code{LINK.p}, and -@code{PREPROCESS.S}, whose values contain the commands listed above. +@code{PREPROCESS.S}, whose values contain the recipes listed above. @code{make} follows the convention that the rule to compile a @file{.@var{x}} source file uses the variable @code{COMPILE.@var{x}}. @@ -8678,14 +8691,14 @@ the value @w{@samp{; mv $*.o $@@}}. @section Variables Used by Implicit Rules @cindex flags for compilers -The commands in built-in implicit rules make liberal use of certain +The recipes in built-in implicit rules make liberal use of certain predefined variables. You can alter the values of these variables in the makefile, with arguments to @code{make}, or in the environment to alter how the implicit rules work without redefining the rules themselves. You can cancel all variables used by implicit rules with the @samp{-R} or @samp{--no-builtin-variables} option. -For example, the command used to compile a C source file actually says +For example, the recipe used to compile a C source file actually says @samp{$(CC) -c $(CFLAGS) $(CPPFLAGS)}. The default values of the variables used are @samp{cc} and nothing, resulting in the command @samp{cc -c}. By redefining @samp{CC} to @samp{ncc}, you could cause @samp{ncc} to be @@ -8704,7 +8717,7 @@ with spaces. The following tables describe of some of the more commonly-used predefined variables. This list is not exhaustive, and the default values shown here may -not be what are selected by @code{make} for your environment. To see the +not be what @code{make} selects for your environment. To see the complete list of predefined variables for your instance of GNU @code{make} you can run @samp{make -p} in a directory with no makefiles. @@ -8998,7 +9011,7 @@ Variables}, and @ref{Functions, ,Functions for Transforming Text}. * Pattern Intro:: An introduction to pattern rules. * Pattern Examples:: Examples of pattern rules. * Automatic Variables:: How to use automatic variables in the - commands of implicit rules. + recipes of implicit rules. * Pattern Match:: How patterns match. * Match-Anything Rules:: Precautions you should take prior to defining rules that can match any @@ -9035,7 +9048,7 @@ become prerequisites of the target. Thus, a rule of the form @example -%.o : %.c ; @var{command}@dots{} +%.o : %.c ; @var{recipe}@dots{} @end example @noindent @@ -9053,16 +9066,17 @@ wildcard. It provides a way to make any file that matches the target pattern. @xref{Last Resort}. @c !!! The end of of this paragraph should be rewritten. --bob -Pattern rules may have more than one target. Unlike normal rules, this -does not act as many different rules with the same prerequisites and -commands. If a pattern rule has multiple targets, @code{make} knows that -the rule's commands are responsible for making all of the targets. The -commands are executed only once to make all the targets. When searching -for a pattern rule to match a target, the target patterns of a rule other -than the one that matches the target in need of a rule are incidental: -@code{make} worries only about giving commands and prerequisites to the file -presently in question. However, when this file's commands are run, the -other targets are marked as having been updated themselves. +Pattern rules may have more than one target. Unlike normal rules, +this does not act as many different rules with the same prerequisites +and recipe. If a pattern rule has multiple targets, @code{make} knows +that the rule's recipe is responsible for making all of the targets. +The recipe is executed only once to make all the targets. When +searching for a pattern rule to match a target, the target patterns of +a rule other than the one that matches the target in need of a rule +are incidental: @code{make} worries only about giving a recipe and +prerequisites to the file presently in question. However, when this +file's recipe is run, the other targets are marked as having been +updated themselves. @cindex multiple targets, in pattern rule @cindex target, multiple in pattern rule @@ -9090,7 +9104,7 @@ files:@refill @noindent defines a rule that can make any file @file{@var{x}.o} from -@file{@var{x}.c}. The command uses the automatic variables @samp{$@@} and +@file{@var{x}.c}. The recipe uses the automatic variables @samp{$@@} and @samp{$<} to substitute the names of the target file and the source file in each case where the rule applies (@pxref{Automatic Variables}).@refill @@ -9121,11 +9135,11 @@ This pattern rule has two targets: @noindent @c The following paragraph is rewritten to avoid overfull hboxes -This tells @code{make} that the command @samp{bison -d @var{x}.y} will +This tells @code{make} that the recipe @samp{bison -d @var{x}.y} will make both @file{@var{x}.tab.c} and @file{@var{x}.tab.h}. If the file @file{foo} depends on the files @file{parse.tab.o} and @file{scan.o} and the file @file{scan.o} depends on the file @file{parse.tab.h}, -when @file{parse.y} is changed, the command @samp{bison -d parse.y} +when @file{parse.y} is changed, the recipe @samp{bison -d parse.y} will be executed only once, and the prerequisites of both @file{parse.tab.o} and @file{scan.o} will be satisfied. (Presumably the file @file{parse.tab.o} will be recompiled from @file{parse.tab.c} @@ -9141,7 +9155,7 @@ prerequisites, and it will execute happily ever after.)@refill Suppose you are writing a pattern rule to compile a @samp{.c} file into a @samp{.o} file: how do you write the @samp{cc} command so that it operates -on the right source file name? You cannot write the name in the command, +on the right source file name? You cannot write the name in the recipe, because the name is different each time the implicit rule is applied. What you do is use a special feature of @code{make}, the @dfn{automatic @@ -9154,7 +9168,7 @@ for the source file name. @cindex prerequisites, and automatic variables It's very important that you recognize the limited scope in which automatic variable values are available: they only have values within -the command script. In particular, you cannot use them anywhere +the recipe. In particular, you cannot use them anywhere within the target list of a rule; they have no value there and will expand to the empty string. Also, they cannot be accessed directly within the prerequisite list of a rule. A common mistake is @@ -9173,7 +9187,7 @@ The file name of the target of the rule. If the target is an archive member, then @samp{$@@} is the name of the archive file. In a pattern rule that has multiple targets (@pxref{Pattern Intro, ,Introduction to Pattern Rules}), @samp{$@@} is the name of whichever target caused the -rule's commands to be run. +rule's recipe to be run. @vindex $% @vindex % @r{(automatic variable)} @@ -9186,7 +9200,7 @@ empty when the target is not an archive member. @vindex $< @vindex < @r{(automatic variable)} @item $< -The name of the first prerequisite. If the target got its commands from +The name of the first prerequisite. If the target got its recipe from an implicit rule, this will be the first prerequisite added by the implicit rule (@pxref{Implicit Rules}). @@ -9195,7 +9209,7 @@ implicit rule (@pxref{Implicit Rules}). @item $? The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only -the member named is used (@pxref{Archives}). +the named member is used (@pxref{Archives}). @cindex prerequisites, list of changed @cindex list of changed prerequisites @@ -9203,7 +9217,7 @@ the member named is used (@pxref{Archives}). @vindex ^ @r{(automatic variable)} @item $^ The names of all the prerequisites, with spaces between them. For -prerequisites which are archive members, only the member named is used +prerequisites which are archive members, only the named member is used (@pxref{Archives}). A target has only one prerequisite on each other file it depends on, no matter how many times each file is listed as a prerequisite. So if you list a prerequisite more than once for a target, @@ -9452,7 +9466,7 @@ other specific type of data (such as a C source file). Special built-in dummy pattern rules are provided solely to recognize certain file names so that nonterminal match-anything rules will not be -considered. These dummy rules have no prerequisites and no commands, and +considered. These dummy rules have no prerequisites and no recipes, and they are ignored for all other purposes. For example, the built-in implicit rule @@ -9473,12 +9487,12 @@ suffix listed as valid for use in suffix rules (@pxref{Suffix Rules, ,Old-Fashio You can override a built-in implicit rule (or one you have defined yourself) by defining a new pattern rule with the same target and -prerequisites, but different commands. When the new rule is defined, the +prerequisites, but a different recipe. When the new rule is defined, the built-in one is replaced. The new rule's position in the sequence of implicit rules is determined by where you write the new rule. You can cancel a built-in implicit rule by defining a pattern rule with the -same target and prerequisites, but no commands. For example, the following +same target and prerequisites, but no recipe. For example, the following would cancel the rule that runs the assembler: @example @@ -9494,7 +9508,7 @@ You can define a last-resort implicit rule by writing a terminal match-anything pattern rule with no prerequisites (@pxref{Match-Anything Rules}). This is just like any other pattern rule; the only thing special about it is that it will match any target. So such a rule's -commands are used for all targets and prerequisites that have no commands +recipe is used for all targets and prerequisites that have no recipe of their own and for which no other implicit rule applies. For example, when testing a makefile, you might not care if the source @@ -9510,27 +9524,27 @@ to cause all the source files needed (as prerequisites) to be created automatically. @findex .DEFAULT -You can instead define commands to be used for targets for which there -are no rules at all, even ones which don't specify commands. You do +You can instead define a recipe to be used for targets for which there +are no rules at all, even ones which don't specify recipes. You do this by writing a rule for the target @code{.DEFAULT}. Such a rule's -commands are used for all prerequisites which do not appear as targets in +recipe is used for all prerequisites which do not appear as targets in any explicit rule, and for which no implicit rule applies. Naturally, there is no @code{.DEFAULT} rule unless you write one. -If you use @code{.DEFAULT} with no commands or prerequisites: +If you use @code{.DEFAULT} with no recipe or prerequisites: @example .DEFAULT: @end example @noindent -the commands previously stored for @code{.DEFAULT} are cleared. -Then @code{make} acts as if you had never defined @code{.DEFAULT} at all. +the recipe previously stored for @code{.DEFAULT} is cleared. Then +@code{make} acts as if you had never defined @code{.DEFAULT} at all. -If you do not want a target to get the commands from a match-anything -pattern rule or @code{.DEFAULT}, but you also do not want any commands -to be run for the target, you can give it empty commands (@pxref{Empty -Commands, ,Defining Empty Commands}).@refill +If you do not want a target to get the recipe from a match-anything +pattern rule or @code{.DEFAULT}, but you also do not want any recipe +to be run for the target, you can give it an empty recipe +(@pxref{Empty Recipes, ,Defining Empty Recipes}).@refill You can use a last-resort rule to override part of another makefile. @xref{Overriding Makefiles, , Overriding Part of Another Makefile}. @@ -9598,10 +9612,10 @@ tells how to make the file @file{.c.o} from the prerequisite file which tells how to make @samp{.o} files from @samp{.c} files, and makes all @samp{.o} files using this pattern rule also depend on @file{foo.h}. -Suffix rules with no commands are also meaningless. They do not remove -previous rules as do pattern rules with no commands (@pxref{Canceling -Rules, , Canceling Implicit Rules}). They simply enter the suffix or pair of suffixes concatenated as -a target in the data base.@refill +Suffix rules with no recipe are also meaningless. They do not remove +previous rules as do pattern rules with no recipe (@pxref{Canceling +Rules, , Canceling Implicit Rules}). They simply enter the suffix or +pair of suffixes concatenated as a target in the data base.@refill @findex .SUFFIXES The known suffixes are simply the names of the prerequisites of the special @@ -9644,8 +9658,8 @@ this variable. Here is the procedure @code{make} uses for searching for an implicit rule for a target @var{t}. This procedure is followed for each double-colon -rule with no commands, for each target of ordinary rules none of which have -commands, and for each prerequisite that is not the target of any rule. It +rule with no recipe, for each target of ordinary rules none of which have +a recipe, and for each prerequisite that is not the target of any rule. It is also followed recursively for prerequisites that come from implicit rules, in the search for a chain of rules. @@ -9674,7 +9688,7 @@ If any rule in that list is @emph{not} a match-anything rule, then remove all nonterminal match-anything rules from the list. @item -Remove from the list all rules with no commands. +Remove from the list all rules with no recipe. @item For each pattern rule in the list: @@ -9724,21 +9738,21 @@ made by implicit rules, then this rule applies. @item If no implicit rule applies, the rule for @code{.DEFAULT}, if any, -applies. In that case, give @var{t} the same commands that -@code{.DEFAULT} has. Otherwise, there are no commands for @var{t}. +applies. In that case, give @var{t} the same recipe that +@code{.DEFAULT} has. Otherwise, there is no recipe for @var{t}. @end enumerate -Once a rule that applies has been found, for each target pattern of the -rule other than the one that matched @var{t} or @var{n}, the @samp{%} in -the pattern is replaced with @var{s} and the resultant file name is stored -until the commands to remake the target file @var{t} are executed. After -these commands are executed, each of these stored file names are entered -into the data base and marked as having been updated and having the same -update status as the file @var{t}. +Once a rule that applies has been found, for each target pattern of +the rule other than the one that matched @var{t} or @var{n}, the +@samp{%} in the pattern is replaced with @var{s} and the resultant +file name is stored until the recipe to remake the target file @var{t} +is executed. After the recipe is executed, each of these stored file +names are entered into the data base and marked as having been updated +and having the same update status as the file @var{t}. -When the commands of a pattern rule are executed for @var{t}, the automatic -variables are set corresponding to the target and prerequisites. -@xref{Automatic Variables}. +When the recipe of a pattern rule is executed for @var{t}, the +automatic variables are set corresponding to the target and +prerequisites. @xref{Automatic Variables}. @node Archives, Features, Implicit Rules, Top @chapter Using @code{make} to Update Archive Files @@ -9770,12 +9784,13 @@ archive file @var{archive} as follows: @noindent This construct is available only in targets and prerequisites, not in -commands! Most programs that you might use in commands do not support this -syntax and cannot act directly on archive members. Only @code{ar} and -other programs specifically designed to operate on archives can do so. -Therefore, valid commands to update an archive member target probably must -use @code{ar}. For example, this rule says to create a member -@file{hack.o} in archive @file{foolib} by copying the file @file{hack.o}: +recipes! Most programs that you might use in recipes do not support +this syntax and cannot act directly on archive members. Only +@code{ar} and other programs specifically designed to operate on +archives can do so. Therefore, valid recipes to update an archive +member target probably must use @code{ar}. For example, this rule +says to create a member @file{hack.o} in archive @file{foolib} by +copying the file @file{hack.o}: @example foolib(hack.o) : hack.o @@ -9828,7 +9843,7 @@ When this rule is chained with others, the result is very powerful. Thus, @samp{make "foo.a(bar.o)"} (the quotes are needed to protect the @samp{(} and @samp{)} from being interpreted specially by the shell) in the presence of a file @file{bar.c} is enough to cause the following -commands to be run, even without a makefile: +recipe to be run, even without a makefile: @example cc -c bar.c -o bar.o @@ -9846,7 +9861,7 @@ Implicit rules such as this one are written using the automatic variable An archive member name in an archive cannot contain a directory name, but it may be useful in a makefile to pretend that it does. If you write an archive member target @file{foo.a(dir/file.o)}, @code{make} will perform -automatic updating with this command: +automatic updating with this recipe: @example ar r foo.a dir/file.o @@ -9911,7 +9926,7 @@ If multiple @code{ar} commands run at the same time on the same archive file, they will not know about each other and can corrupt the file. Possibly a future version of @code{make} will provide a mechanism to -circumvent this problem by serializing all commands that operate on the +circumvent this problem by serializing all recipes that operate on the same archive file. But for the time being, you must either write your makefiles to avoid this problem in some other way, or not use @code{-j}. @@ -10017,7 +10032,7 @@ Substitution variable references. @xref{Reference, ,Basics of Variable References}. @item -The command-line options @samp{-b} and @samp{-m}, accepted and +The command line options @samp{-b} and @samp{-m}, accepted and ignored. In System V @code{make}, these options actually do something. @item @@ -10034,7 +10049,7 @@ archive (@pxref{Archive Update}) to be sufficient. @item The arrangement of lines and backslash-newline combinations in -commands is retained when the commands are printed, so they appear as +recipes is retained when the recipes are printed, so they appear as they do in the makefile, except for the stripping of initial whitespace. @end itemize @@ -10068,12 +10083,12 @@ did. @xref{Automatic Variables}. The automatic variable @item The ``what if'' flag (@samp{-W} in GNU @code{make}) was (as far as we know) invented by Andrew Hume in @code{mk}. -@xref{Instead of Execution, ,Instead of Executing the Commands}. +@xref{Instead of Execution, ,Instead of Executing the Recipes}. @item The concept of doing several things at once (parallelism) exists in many incarnations of @code{make} and similar programs, though not in the -System V or BSD implementations. @xref{Execution, ,Command Execution}. +System V or BSD implementations. @xref{Execution, ,Recipe Execution}. @item Modified variable references using pattern substitution come from @@ -10085,10 +10100,9 @@ inspired whom, since GNU @code{make} had @code{patsubst} before SunOS 4 was released.@refill @item -The special significance of @samp{+} characters preceding command lines -(@pxref{Instead of Execution, ,Instead of Executing the Commands}) is -mandated by -@cite{IEEE Standard 1003.2-1992} (POSIX.2). +The special significance of @samp{+} characters preceding recipe lines +(@pxref{Instead of Execution, ,Instead of Executing the Recipes}) is +mandated by @cite{IEEE Standard 1003.2-1992} (POSIX.2). @item The @samp{+=} syntax to append to the value of a variable comes from SunOS @@ -10122,7 +10136,7 @@ Use the @samp{-h} or @samp{--help} option to summarize the options to Simply-expanded variables. @xref{Flavors, ,The Two Flavors of Variables}. @item -Pass command-line variable assignments automatically through the +Pass command line variable assignments automatically through the variable @code{MAKE} to recursive @code{make} invocations. @xref{Recursion, ,Recursive Use of @code{make}}. @@ -10254,10 +10268,11 @@ general feature of rule chaining. @xref{Chained Rules, ,Chains of Implicit Rules}. @item -In System V and 4.3 BSD @code{make}, files found by @code{VPATH} search -(@pxref{Directory Search, ,Searching Directories for Prerequisites}) have their names changed inside command -strings. We feel it is much cleaner to always use automatic variables -and thus make this feature obsolete.@refill +In System V and 4.3 BSD @code{make}, files found by @code{VPATH} +search (@pxref{Directory Search, ,Searching Directories for +Prerequisites}) have their names changed inside recipes. We feel it +is much cleaner to always use automatic variables and thus make this +feature obsolete.@refill @item In some Unix @code{make}s, the automatic variable @code{$*} appearing in @@ -10268,9 +10283,9 @@ this; it is utterly inconsistent with the normal definition of @code{$*}. @vindex * @r{(automatic variable), unsupported bizarre usage} @item -In some Unix @code{make}s, implicit rule search -(@pxref{Implicit Rules, ,Using Implicit Rules}) is apparently done for -@emph{all} targets, not just those without commands. This means you can +In some Unix @code{make}s, implicit rule search (@pxref{Implicit +Rules, ,Using Implicit Rules}) is apparently done for @emph{all} +targets, not just those without recipes. This means you can do:@refill @example @@ -10294,9 +10309,9 @@ compiling or preprocessing EFL programs. If we hear of anyone who is using EFL, we will gladly add them. @item -It appears that in SVR4 @code{make}, a suffix rule can be specified with -no commands, and it is treated as if it had empty commands -(@pxref{Empty Commands}). For example: +It appears that in SVR4 @code{make}, a suffix rule can be specified +with no recipe, and it is treated as if it had an empty recipe +(@pxref{Empty Recipes}). For example: @example .c.a: @@ -10305,7 +10320,7 @@ no commands, and it is treated as if it had empty commands @noindent will override the built-in @file{.c.a} suffix rule. -We feel that it is cleaner for a rule without commands to always simply +We feel that it is cleaner for a rule without a recipe to always simply add to the prerequisite list for the target. The above example can be easily rewritten to get the desired behavior in GNU @code{make}: @@ -10318,7 +10333,7 @@ Some versions of @code{make} invoke the shell with the @samp{-e} flag, except under @samp{-k} (@pxref{Testing, ,Testing the Compilation of a Program}). The @samp{-e} flag tells the shell to exit as soon as any program it runs returns a nonzero status. We feel it is cleaner to -write each shell command line to stand on its own and not require this +write each line of the recipe to stand on its own and not require this special treatment. @end itemize @@ -10570,12 +10585,12 @@ The name of the first prerequisite. The names of all the prerequisites that are newer than the target, with spaces between them. For prerequisites which are archive members, only -the member named is used (@pxref{Archives}). +the named member is used (@pxref{Archives}). @item $^ @itemx $+ The names of all the prerequisites, with spaces between them. For -prerequisites which are archive members, only the member named is used +prerequisites which are archive members, only the named member is used (@pxref{Archives}). The value of @code{$^} omits duplicate prerequisites, while @code{$+} retains them and preserves their order. @@ -10629,7 +10644,7 @@ Directory search path for files not found in the current directory.@* The name of the system default command interpreter, usually @file{/bin/sh}. You can set @code{SHELL} in the makefile to change the shell used to run -commands. @xref{Execution, ,Command Execution}. The @code{SHELL} +recipes. @xref{Execution, ,Recipe Execution}. The @code{SHELL} variable is handled specially when importing from and exporting to the environment. @xref{Choosing the Shell}. @@ -10641,9 +10656,9 @@ by @code{make}. This value takes precedence over the value of @item MAKE -The name with which @code{make} was invoked. -Using this variable in commands has special meaning. -@xref{MAKE Variable, ,How the @code{MAKE} Variable Works}. +The name with which @code{make} was invoked. Using this variable in +recipes has special meaning. @xref{MAKE Variable, ,How the +@code{MAKE} Variable Works}. @item MAKELEVEL @@ -10656,8 +10671,8 @@ The flags given to @code{make}. You can set this in the environment or a makefile to set flags.@* @xref{Options/Recursion, ,Communicating Options to a Sub-@code{make}}. -It is @emph{never} appropriate to use @code{MAKEFLAGS} directly on a -command line: its contents may not be quoted correctly for use in the +It is @emph{never} appropriate to use @code{MAKEFLAGS} directly in a +recipe line: its contents may not be quoted correctly for use in the shell. Always allow recursive @code{make}'s to obtain these values through the environment from its parent. @@ -10693,8 +10708,8 @@ Here is a list of the more common errors you might see generated by them. Sometimes @code{make} errors are not fatal, especially in the presence -of a @code{-} prefix on a command script line, or the @code{-k} command -line option. Errors that are fatal are prefixed with the string +of a @code{-} prefix on a recipe line, or the @code{-k} command line +option. Errors that are fatal are prefixed with the string @code{***}. Error messages are all either prefixed with the name of the program @@ -10708,10 +10723,10 @@ In the table below, these common prefixes are left off. @item [@var{foo}] Error @var{NN} @itemx [@var{foo}] @var{signal description} These errors are not really @code{make} errors at all. They mean that a -program that @code{make} invoked as part of a command script returned a +program that @code{make} invoked as part of a recipe returned a non-0 error code (@samp{Error @var{NN}}), which @code{make} interprets as failure, or it exited in some other abnormal fashion (with a -signal of some type). @xref{Errors, ,Errors in Commands}. +signal of some type). @xref{Errors, ,Errors in Recipes}. If no @code{***} is attached to the message, then the subprocess failed but the rule in the makefile was prefixed with the @code{-} special @@ -10719,26 +10734,27 @@ character, so @code{make} ignored the error. @item missing separator. Stop. @itemx missing separator (did you mean TAB instead of 8 spaces?). Stop. -This means that @code{make} could not understand much of anything about -the command line it just read. GNU @code{make} looks for various kinds -of separators (@code{:}, @code{=}, TAB characters, etc.) to help it -decide what kind of commandline it's seeing. This means it couldn't -find a valid one. - -One of the most common reasons for this message is that you (or perhaps -your oh-so-helpful editor, as is the case with many MS-Windows editors) -have attempted to indent your command scripts with spaces instead of a -TAB character. In this case, @code{make} will use the second form of -the error above. Remember that every line in the command script must -begin with a TAB character. Eight spaces do not count. @xref{Rule -Syntax}. - -@item commands commence before first target. Stop. -@itemx missing rule before commands. Stop. -This means the first thing in the makefile seems to be part of a command -script: it begins with a TAB character and doesn't appear to be a legal -@code{make} command (such as a variable assignment). Command scripts -must always be associated with a target. +This means that @code{make} could not understand much of anything +about the makefile line it just read. GNU @code{make} looks for +various separators (@code{:}, @code{=}, recipe prefix characters, +etc.) to indicate what kind of line it's parsing. This message means +it couldn't find a valid one. + +One of the most common reasons for this message is that you (or +perhaps your oh-so-helpful editor, as is the case with many MS-Windows +editors) have attempted to indent your recipe lines with spaces +instead of a tab character. In this case, @code{make} will use the +second form of the error above. Remember that every line in the +recipe must begin with a tab character (unless you set +@code{.CMDPREFIX}; @pxref{Special Variables}). Eight spaces do not +count. @xref{Rule Syntax}. + +@item recipe commences before first target. Stop. +@itemx missing rule before recipe. Stop. +This means the first thing in the makefile seems to be part of a +recipe: it begins with a recipe prefix character and doesn't appear to +be a legal @code{make} directive (such as a variable assignment). +Recipes must always be associated with a target. The second form is generated if the line has a semicolon as the first non-whitespace character; @code{make} interprets this to mean you left @@ -10770,13 +10786,13 @@ has nothing to do in these situations. A makefile specified on the command line (first form) or included (second form) was not found. -@item warning: overriding commands for target `@var{xxx}' -@itemx warning: ignoring old commands for target `@var{xxx}' -GNU @code{make} allows commands to be specified only once per target -(except for double-colon rules). If you give commands for a target -which already has been defined to have commands, this warning is issued -and the second set of commands will overwrite the first set. -@xref{Multiple Rules, ,Multiple Rules for One Target}. +@item warning: overriding recipe for target `@var{xxx}' +@itemx warning: ignoring old recipe for target `@var{xxx}' +GNU @code{make} allows only one recipe to be specified per target +(except for double-colon rules). If you give a recipe for a target +which already has been defined to have one, this warning is issued and +the second recipe will overwrite the first. @xref{Multiple Rules, +,Multiple Rules for One Target}. @item Circular @var{xxx} <- @var{yyy} dependency dropped. This means that @code{make} detected a loop in the dependency graph: @@ -11016,7 +11032,6 @@ AUX = README COPYING ChangeLog Makefile.in \ all: tar rmt tar.info @group -.PHONY: tar tar: $(OBJS) $(CC) $(LDFLAGS) -o $@@ $(OBJS) $(LIBS) @end group @@ -255,18 +255,18 @@ rehash_file (struct file *from_file, const char *to_hname) but give a message to let the user know what's going on. */ if (to_file->cmds->fileinfo.filenm != 0) error (&from_file->cmds->fileinfo, - _("Commands were specified for file `%s' at %s:%lu,"), + _("Recipe was specified for file `%s' at %s:%lu,"), from_file->name, to_file->cmds->fileinfo.filenm, to_file->cmds->fileinfo.lineno); else error (&from_file->cmds->fileinfo, - _("Commands for file `%s' were found by implicit rule search,"), + _("Recipe for file `%s' was found by implicit rule search,"), from_file->name); error (&from_file->cmds->fileinfo, _("but `%s' is now considered the same file as `%s'."), from_file->name, to_hname); error (&from_file->cmds->fileinfo, - _("Commands for `%s' will be ignored in favor of those for `%s'."), + _("Recipe for `%s' will be ignored in favor of the one for `%s'."), to_hname, from_file->name); } } @@ -359,7 +359,7 @@ remove_intermediates (int sig) struct file *f = *file_slot; /* Is this file eligible for automatic deletion? Yes, IFF: it's marked intermediate, it's not secondary, it wasn't - given on the command-line, and it's either a -include makefile or + given on the command line, and it's either a -include makefile or it's not precious. */ if (f->intermediate && (f->dontcare || !f->precious) && !f->secondary && !f->cmd_target) @@ -895,7 +895,7 @@ print_file (const void *item) if (f->phony) puts (_("# Phony target (prerequisite of .PHONY).")); if (f->cmd_target) - puts (_("# Command-line target.")); + puts (_("# Command line target.")); if (f->dontcare) puts (_("# A default, MAKEFILES, or -include/sinclude makefile.")); puts (f->tried_implicit @@ -929,10 +929,10 @@ print_file (const void *item) switch (f->command_state) { case cs_running: - puts (_("# Commands currently running (THIS IS A BUG).")); + puts (_("# Recipe currently running (THIS IS A BUG).")); break; case cs_deps_running: - puts (_("# Dependencies commands running (THIS IS A BUG).")); + puts (_("# Dependencies recipe running (THIS IS A BUG).")); break; case cs_not_started: case cs_finished: @@ -1724,13 +1724,13 @@ new_job (struct file *file) ++jobserver_tokens; /* The job is now primed. Start it running. - (This will notice if there are in fact no commands.) */ + (This will notice if there is in fact no recipe.) */ if (cmds->fileinfo.filenm) - DB (DB_BASIC, (_("Invoking commands from %s:%lu to update target `%s'.\n"), + DB (DB_BASIC, (_("Invoking recipe from %s:%lu to update target `%s'.\n"), cmds->fileinfo.filenm, cmds->fileinfo.lineno, c->file->name)); else - DB (DB_BASIC, (_("Invoking builtin commands to update target `%s'.\n"), + DB (DB_BASIC, (_("Invoking builtin recipe to update target `%s'.\n"), c->file->name)); @@ -2461,9 +2461,6 @@ construct_command_argv_internal (char *line, char **restp, char *shell, *(ap++) = *(p++); *(ap++) = *p; } - /* If there's a command prefix char here, skip it. */ - if (p[1] == cmd_prefix) - ++p; } else if (*p == '\n' && restp != NULL) { @@ -2511,11 +2508,6 @@ construct_command_argv_internal (char *line, char **restp, char *shell, /* Throw out the backslash and newline. */ ++p; - /* If there is a command prefix after a backslash-newline, - remove it. */ - if (p[1] == cmd_prefix) - ++p; - /* If there's nothing in this argument yet, skip any whitespace before the start of the next word. */ if (ap == new_argv[i]) @@ -2743,9 +2735,8 @@ construct_command_argv_internal (char *line, char **restp, char *shell, } else if (*p == '\\' && p[1] == '\n') { - /* POSIX says we keep the backslash-newline, but throw out - the next char if it's a TAB. If we don't have a POSIX - shell on DOS/Windows/OS2, mimic the pre-POSIX behavior + /* POSIX says we keep the backslash-newline. If we don't have a + POSIX shell on DOS/Windows/OS2, mimic the pre-POSIX behavior and remove the backslash/newline. */ #if defined (__MSDOS__) || defined (__EMX__) || defined (WINDOWS32) # define PRESERVE_BSNL unixy_shell @@ -2758,11 +2749,7 @@ construct_command_argv_internal (char *line, char **restp, char *shell, *(ap++) = '\\'; *(ap++) = '\n'; } - ++p; - if (p[1] == cmd_prefix) - ++p; - continue; } @@ -2849,12 +2836,7 @@ construct_command_argv_internal (char *line, char **restp, char *shell, while (*q != '\0') { if (q[0] == '\\' && q[1] == '\n') - { - q += 2; /* remove '\\' and '\n' */ - /* Remove any command prefix in the next line */ - if (q[0] == cmd_prefix) - q++; - } + q += 2; /* remove '\\' and '\n' */ else *p++ = *q++; } @@ -320,7 +320,7 @@ static const char *const usage[] = N_("\ -h, --help Print this message and exit.\n"), N_("\ - -i, --ignore-errors Ignore errors from commands.\n"), + -i, --ignore-errors Ignore errors from recipes.\n"), N_("\ -I DIRECTORY, --include-dir=DIRECTORY\n\ Search DIRECTORY for included makefiles.\n"), @@ -335,20 +335,20 @@ static const char *const usage[] = -L, --check-symlink-times Use the latest mtime between symlinks and target.\n"), N_("\ -n, --just-print, --dry-run, --recon\n\ - Don't actually run any commands; just print them.\n"), + Don't actually run any recipe; just print them.\n"), N_("\ -o FILE, --old-file=FILE, --assume-old=FILE\n\ Consider FILE to be very old and don't remake it.\n"), N_("\ -p, --print-data-base Print make's internal database.\n"), N_("\ - -q, --question Run no commands; exit status says if up to date.\n"), + -q, --question Run no recipe; exit status says if up to date.\n"), N_("\ -r, --no-builtin-rules Disable the built-in implicit rules.\n"), N_("\ -R, --no-builtin-variables Disable the built-in variable settings.\n"), N_("\ - -s, --silent, --quiet Don't echo commands.\n"), + -s, --silent, --quiet Don't echo recipes.\n"), N_("\ -S, --no-keep-going, --stop\n\ Turns off -k.\n"), @@ -1117,6 +1117,7 @@ main (int argc, char **argv, char **envp) /* Initialize the special variables. */ define_variable (".VARIABLES", 10, "", o_default, 0)->special = 1; /* define_variable (".TARGETS", 8, "", o_default, 0)->special = 1; */ + define_variable (".RECIPEPREFIX", 13, "", o_default, 0)->special = 1; /* Set up .FEATURES */ define_variable (".FEATURES", 9, @@ -496,6 +496,9 @@ extern int second_expansion, clock_skew_detected, rebuilding_makefiles; /* can we run commands via 'sh -c xxx' or must we use batch files? */ extern int batch_mode_shell; +/* Resetting the command script introduction prefix character. */ +#define RECIPEPREFIX_NAME ".RECIPEPREFIX" +#define RECIPEPREFIX_DEFAULT '\t' extern char cmd_prefix; extern unsigned int job_slots; @@ -536,18 +536,31 @@ eval (struct ebuffer *ebuf, int set_default) /* Yep, this is a shell command, and we don't care. */ continue; - /* Append this command line to the line being accumulated. */ + /* Append this command line to the line being accumulated. + Strip command prefix chars that appear after newlines. */ if (commands_idx == 0) cmds_started = ebuf->floc.lineno; - if (linelen + 1 + commands_idx > commands_len) + if (linelen + commands_idx > commands_len) { - commands_len = (linelen + 1 + commands_idx) * 2; + commands_len = (linelen + commands_idx) * 2; commands = xrealloc (commands, commands_len); } - memcpy (&commands[commands_idx], line, linelen); - commands_idx += linelen; - commands[commands_idx++] = '\n'; + p = &commands[commands_idx]; + p2 = line + 1; + while (--linelen) + { + ++commands_idx; + *(p++) = *p2; + if (p2[0] == '\n' && p2[1] == cmd_prefix) + { + ++p2; + --linelen; + } + ++p2; + } + *p = '\n'; + ++commands_idx; continue; } @@ -844,7 +857,7 @@ eval (struct ebuffer *ebuf, int set_default) was no preceding target, and the line might have been usable as a variable definition. But now we know it is definitely lossage. */ if (line[0] == cmd_prefix) - fatal(fstart, _("commands commence before first target")); + fatal(fstart, _("recipe commences before first target")); /* This line describes some target files. This is complicated by the existence of target-specific variables, because we can't @@ -895,7 +908,7 @@ eval (struct ebuffer *ebuf, int set_default) { case w_eol: if (cmdleft != 0) - fatal(fstart, _("missing rule before commands")); + fatal(fstart, _("missing rule before recipe")); /* This line contained something but turned out to be nothing but whitespace (a comment?). */ continue; @@ -983,8 +996,8 @@ eval (struct ebuffer *ebuf, int set_default) /* There's no need to be ivory-tower about this: check for one of the most common bugs found in makefiles... */ fatal (fstart, _("missing separator%s"), - !strneq(line, " ", 8) ? "" - : _(" (did you mean TAB instead of 8 spaces?)")); + (cmd_prefix == '\t' && !strneq(line, " ", 8)) + ? "" : _(" (did you mean TAB instead of 8 spaces?)")); continue; } @@ -1871,7 +1884,7 @@ record_files (struct nameseq *filenames, const char *pattern, at this time, since they won't get snapped and we'll get core dumps. See Savannah bug # 12124. */ if (snapped_deps) - fatal (flocp, _("prerequisites cannot be defined in command scripts")); + fatal (flocp, _("prerequisites cannot be defined in recipes")); if (commands_idx > 0) { @@ -1971,10 +1984,10 @@ record_files (struct nameseq *filenames, const char *pattern, else if (cmds != 0 && f->cmds != 0 && f->is_target) { error (&cmds->fileinfo, - _("warning: overriding commands for target `%s'"), + _("warning: overriding recipe for target `%s'"), f->name); error (&f->cmds->fileinfo, - _("warning: ignoring old commands for target `%s'"), + _("warning: ignoring old recipe for target `%s'"), f->name); } @@ -2962,7 +2975,7 @@ construct_include_path (const char **arg_dirs) --len; if (len > max_incl_len) max_incl_len = len; - dirs[idx++] = strcache_add_len (*cpp, len - 1); + dirs[idx++] = strcache_add_len (*cpp, len); } } @@ -460,7 +460,7 @@ update_file_1 (struct file *file, unsigned int depth) if (file->cmds == 0 && !file->is_target && default_file != 0 && default_file->cmds != 0) { - DBF (DB_IMPLICIT, _("Using default commands for `%s'.\n")); + DBF (DB_IMPLICIT, _("Using default recipe for `%s'.\n")); file->cmds = default_file->cmds; } @@ -711,7 +711,7 @@ update_file_1 (struct file *file, unsigned int depth) { must_make = 0; DBF (DB_VERBOSE, - _("No commands for `%s' and no prerequisites actually changed.\n")); + _("No recipe for `%s' and no prerequisites actually changed.\n")); } else if (!must_make && file->cmds != 0 && always_make_flag) { @@ -761,7 +761,7 @@ update_file_1 (struct file *file, unsigned int depth) if (file->command_state != cs_finished) { - DBF (DB_VERBOSE, _("Commands of `%s' are being run.\n")); + DBF (DB_VERBOSE, _("Recipe of `%s' is being run.\n")); return 0; } diff --git a/tests/ChangeLog b/tests/ChangeLog index 9a515a3..d9a0488 100644 --- a/tests/ChangeLog +++ b/tests/ChangeLog @@ -1,3 +1,16 @@ +2007-11-04 Paul Smith <psmith@gnu.org> + + * scripts/functions/eval: Update error message for command -> recipe. + + * test_driver.pl (compare_output): Allow the answer to be a regex, + if surrounded by '/'. + * scripts/misc/close_stdout: Use a regex for the answer, since + sometimes the error will have a description and sometimes it won't. + +2007-09-10 Paul Smith <psmith@gnu.org> + + * scripts/variables/special: Add tests for .RECIPEPREFIX variable. + 2007-08-15 Paul Smith <psmith@gnu.org> These test cases were contributed by diff --git a/tests/scripts/functions/eval b/tests/scripts/functions/eval index 6f02a7a..90513bd 100644 --- a/tests/scripts/functions/eval +++ b/tests/scripts/functions/eval @@ -163,7 +163,7 @@ world'); # See Savannah bug # 12124. run_make_test('deps: ; $(eval deps: foo)', '', - '#MAKEFILE#:1: *** prerequisites cannot be defined in command scripts. Stop.', + '#MAKEFILE#:1: *** prerequisites cannot be defined in recipes. Stop.', 512); 1; diff --git a/tests/scripts/misc/close_stdout b/tests/scripts/misc/close_stdout index 688942e..18606c3 100644 --- a/tests/scripts/misc/close_stdout +++ b/tests/scripts/misc/close_stdout @@ -3,7 +3,7 @@ $description = "Make sure make exits with an error if stdout is full."; if (-e '/dev/full') { - run_make_test('', '-v > /dev/full', '#MAKE#: write error', 256); + run_make_test('', '-v > /dev/full', '/^#MAKE#: write error/', 256); } 1; diff --git a/tests/scripts/variables/special b/tests/scripts/variables/special index 77b355c..a1e15c2 100644 --- a/tests/scripts/variables/special +++ b/tests/scripts/variables/special @@ -50,5 +50,68 @@ all: # $answer = "X1 =\nX2 = all\nLAST = all foo\n"; # &compare_output($answer, &get_logfile(1)); +# Test the .RECIPEPREFIX variable +&run_make_test(' +define foo +: foo-one \ +foo-two +: foo-three + : foo-four +endef + +orig: ; : orig-one + : orig-two \ +orig-three \ + orig-four \ + orig-five \\\\ + : orig-six + $(foo) + +.RECIPEPREFIX = > +test: ; : test-one +>: test-two \ +test-three \ +>test-four \ +> test-five \\\\ +>: test-six +>$(foo) + +.RECIPEPREFIX = +reset: ; : reset-one + : reset-two \ +reset-three \ + reset-four \ + reset-five \\\\ + : reset-six + $(foo) +', + 'orig test reset', + ': orig-one +: orig-two \ +orig-three \ +orig-four \ + orig-five \\\\ +: orig-six +: foo-one foo-two +: foo-three +: foo-four +: test-one +: test-two \ +test-three \ +test-four \ + test-five \\\\ +: test-six +: foo-one foo-two +: foo-three +: foo-four +: reset-one +: reset-two \ +reset-three \ +reset-four \ + reset-five \\\\ +: reset-six +: foo-one foo-two +: foo-three +: foo-four'); 1; diff --git a/tests/test_driver.pl b/tests/test_driver.pl index bea9816..dd30320 100644 --- a/tests/test_driver.pl +++ b/tests/test_driver.pl @@ -661,15 +661,23 @@ sub compare_output $answer_matched = 1; } else { # See if it is a slash or CRLF problem - local ($answer_mod) = $answer; + local ($answer_mod, $slurp_mod) = ($answer, $slurp); $answer_mod =~ tr,\\,/,; $answer_mod =~ s,\r\n,\n,gs; - $slurp =~ tr,\\,/,; - $slurp =~ s,\r\n,\n,gs; + $slurp_mod =~ tr,\\,/,; + $slurp_mod =~ s,\r\n,\n,gs; - $answer_matched = ($slurp eq $answer_mod); + $answer_matched = ($slurp_mod eq $answer_mod); + + # If it still doesn't match, see if the answer might be a regex. + if (!$answer_matched && $answer =~ m,^/(.+)/$,) { + $answer_matched = ($slurp =~ /$1/); + if (!$answer_matched && $answer_mod =~ m,^/(.+)/$,) { + $answer_matched = ($slurp_mod =~ /$1/); + } + } } if ($answer_matched && $test_passed) @@ -252,7 +252,7 @@ define_variable_in_set (const char *name, unsigned int length, #define EXPANSION_INCREMENT(_l) ((((_l) / 500) + 1) * 500) static struct variable * -handle_special_var (struct variable *var) +lookup_special_var (struct variable *var) { static unsigned long last_var_count = 0; @@ -352,7 +352,7 @@ lookup_variable (const char *name, unsigned int length) v = (struct variable *) hash_find_item ((struct hash_table *) &set->table, &var_key); if (v) - return v->special ? handle_special_var (v) : v; + return v->special ? lookup_special_var (v) : v; } #ifdef VMS @@ -985,6 +985,20 @@ target_environment (struct file *file) return result_0; } +static struct variable * +set_special_var (struct variable *var) +{ + if (streq (var->name, RECIPEPREFIX_NAME)) + { + /* The user is resetting the command introduction prefix. This has to + happen immediately, so that subsequent rules are interpreted + properly. */ + cmd_prefix = var->value[0]=='\0' ? RECIPEPREFIX_DEFAULT : var->value[0]; + } + + return var; +} + /* Given a variable, a value, and a flavor, define the variable. See the try_variable_definition() function for details on the parameters. */ @@ -1019,7 +1033,7 @@ do_variable_definition (const struct floc *flocp, const char *varname, The value is set IFF the variable is not defined yet. */ v = lookup_variable (varname, strlen (varname)); if (v) - return v; + return v->special ? set_special_var (v) : v; conditional = 1; flavor = f_recursive; @@ -1227,7 +1241,7 @@ do_variable_definition (const struct floc *flocp, const char *varname, if (alloc_value) free (alloc_value); - return v; + return v->special ? set_special_var (v) : v; } /* Try to interpret LINE (a null-terminated string) as a variable definition. |