diff options
Diffstat (limited to 'doc/make.info-1')
| -rw-r--r-- | doc/make.info-1 | 1204 |
1 files changed, 573 insertions, 631 deletions
diff --git a/doc/make.info-1 b/doc/make.info-1 index 509ce05..4025d3e 100644 --- a/doc/make.info-1 +++ b/doc/make.info-1 @@ -4,16 +4,16 @@ This file documents the GNU `make' utility, which determines automatically which pieces of a large program need to be recompiled, and issues the commands to recompile them. - This is Edition 0.71, last updated 19 July 2010, of `The GNU Make -Manual', for GNU `make' version 3.82. + This is Edition 0.72, last updated 9 October 2013, of `The GNU Make +Manual', for GNU `make' version 4.0. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010 Free Software Foundation, Inc. +2010, 2011, 2012, 2013 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, - Version 1.2 or any later version published by the Free Software + Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled @@ -38,16 +38,16 @@ This file documents the GNU `make' utility, which determines automatically which pieces of a large program need to be recompiled, and issues the commands to recompile them. - This is Edition 0.71, last updated 19 July 2010, of `The GNU Make -Manual', for GNU `make' version 3.82. + This is Edition 0.72, last updated 9 October 2013, of `The GNU Make +Manual', for GNU `make' version 4.0. Copyright (C) 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996, 1997, 1998, 1999, 2000, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, -2010 Free Software Foundation, Inc. +2010, 2011, 2012, 2013 Free Software Foundation, Inc. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, - Version 1.2 or any later version published by the Free Software + Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, with the Front-Cover Texts being "A GNU Manual," and with the Back-Cover Texts as in (a) below. A copy of the license is included in the section entitled @@ -72,6 +72,7 @@ Manual', for GNU `make' version 3.82. * Implicit Rules:: Use implicit rules to treat many files alike, based on their file names. * Archives:: How `make' can update library archives. +* Extending make:: Using extensions to `make'. * Features:: Features GNU `make' has over other `make's. * Missing:: What GNU `make' lacks from other `make's. * Makefile Conventions:: Conventions for writing makefiles for @@ -81,27 +82,27 @@ Manual', for GNU `make' version 3.82. * Complex Makefile:: A real example of a straightforward, but nontrivial, makefile. -* GNU Free Documentation License:: License for copying this manual -* Concept Index:: Index of Concepts -* Name Index:: Index of Functions, Variables, & Directives +* GNU Free Documentation License:: License for copying this manual. +* Concept Index:: Index of Concepts. +* Name Index:: Index of Functions, Variables, & Directives. --- The Detailed Node Listing --- Overview of `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 `make' processes this makefile -* Variables Simplify:: Variables make makefiles simpler -* make Deduces:: Letting `make' deduce the recipe -* Combine By Prerequisite:: Another style of makefile -* Cleanup:: Rules for cleaning the directory +* Simple Makefile:: A simple makefile. +* How Make Works:: How `make' processes this makefile. +* Variables Simplify:: Variables make makefiles simpler. +* make Deduces:: Letting `make' deduce the recipes. +* Combine By Prerequisite:: Another style of makefile. +* Cleanup:: Rules for cleaning the directory. Writing Makefiles @@ -115,6 +116,10 @@ Writing Makefiles * Reading Makefiles:: How makefiles are parsed. * Secondary Expansion:: How and when secondary expansion is performed. +What Makefiles Contain + +* Splitting Lines:: Splitting long lines in makefiles + Writing Rules * Rule Example:: An example explained. @@ -141,7 +146,7 @@ Writing Rules Using Wildcard Characters in File Names -* Wildcard Examples:: Several examples +* Wildcard Examples:: Several examples. * Wildcard Pitfall:: Problems to avoid. * Wildcard Function:: How to cause wildcard expansion where it does not normally take place. @@ -177,14 +182,20 @@ Writing Recipes in Rules Recipe Syntax -* Splitting Lines:: Breaking long recipe lines for readability. +* Splitting Recipe Lines:: Breaking long recipe lines for readability. * Variables in Recipes:: Using `make' variables in recipes. Recipe Execution +* One Shell:: One shell for all lines in a recipe. * Choosing the Shell:: How `make' chooses the shell used to run recipes. +Parallel Execution + +* Parallel Output:: Handling output during parallel execution +* Parallel Input:: Handling input during parallel execution + Recursive Use of `make' * MAKE Variable:: The special effects of using `$(MAKE)'. @@ -206,6 +217,8 @@ How to Use Variables the user has set it with a command argument. * Multi-Line:: An alternate way to set a variable to a multi-line string. +* Undefine Directive:: How to undefine a variable so that it appears + as if it was never set. * Environment:: Variable values can come from the environment. * Target-specific:: Variable values can be defined on a per-target basis. @@ -233,13 +246,15 @@ Functions for Transforming Text * File Name Functions:: Functions for manipulating file names. * Conditional Functions:: Functions that implement conditions. * Foreach Function:: Repeat some text with controlled variation. +* File Function:: Write text to a file. * Call Function:: Expand a user-defined function. * Value Function:: Return the un-expanded value of a variable. * Eval Function:: Evaluate the arguments as makefile syntax. * Origin Function:: Find where a variable got its value. * Flavor Function:: Find out the flavor of a variable. -* Shell Function:: Substitute the output of a shell command. * Make Control Functions:: Functions that control how make runs. +* Shell Function:: Substitute the output of a shell command. +* Guile Function:: Use GNU Guile embedded scripting language. How to Run `make' @@ -260,7 +275,7 @@ How to Run `make' Using Implicit Rules * Using Implicit:: How to use an existing implicit rule - to get the recipe 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. @@ -295,6 +310,24 @@ Implicit Rule for Archive Member Targets * Archive Symbols:: How to update archive symbol directories. +Extending GNU `make' + +* Guile Integration:: Using Guile as an embedded scripting language. +* Loading Objects:: Loading dynamic objects as extensions. + +GNU Guile Integration + +* Guile Types:: Converting Guile types to `make' strings. +* Guile Interface:: Invoking `make' functions from Guile. +* Guile Example:: Example using Guile in `make'. + +Loading Dynamic Objects + +* load Directive:: Loading dynamic objects as extensions. +* Remaking Loaded Objects:: How loaded objects get remade. +* Loaded Object API:: Programmatic interface for loaded objects. +* Loaded Object Example:: Example of a loaded object + File: make.info, Node: Overview, Next: Introduction, Prev: Top, Up: Top @@ -318,9 +351,9 @@ automatically from others whenever the others change. * Menu: -* 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. File: make.info, Node: Preparing, Next: Reading, Prev: Overview, Up: Overview @@ -438,12 +471,12 @@ together to produce the new executable editor. * Menu: * Rule Introduction:: What a rule looks like. -* Simple Makefile:: A Simple Makefile -* How Make Works:: How `make' Processes This Makefile -* Variables Simplify:: Variables Make Makefiles Simpler -* make Deduces:: Letting `make' Deduce the Recipes -* Combine By Prerequisite:: Another Style of Makefile -* Cleanup:: Rules for Cleaning the Directory +* Simple Makefile:: A simple makefile. +* How Make Works:: How `make' processes this makefile. +* Variables Simplify:: Variables make makefiles simpler. +* make Deduces:: Letting `make' deduce the recipes. +* Combine By Prerequisite:: Another style of makefile. +* Cleanup:: Rules for cleaning the directory. File: make.info, Node: Rule Introduction, Next: Simple Makefile, Prev: Introduction, Up: Introduction @@ -530,8 +563,9 @@ that change the editor buffer include `buffer.h'. rm edit main.o kbd.o command.o display.o \ insert.o search.o files.o utils.o -We split each long line into two lines using backslash-newline; this is -like using one long line, but is easier to read. +We split each long line into two lines using backslash/newline; this is +like using one long line, but is easier to read. *Note Splitting Long +Lines: Splitting Lines. To use this makefile to create the executable file called `edit', type: @@ -892,6 +926,47 @@ variables, and directives are described at length in later chapters. treated as `make' comments or as recipe text, depending on the context in which the variable is evaluated. +* Menu: + +* Splitting Lines:: Splitting long lines in makefiles + + +File: make.info, Node: Splitting Lines, Prev: Makefile Contents, Up: Makefile Contents + +3.1.1 Splitting Long Lines +-------------------------- + +Makefiles use a "line-based" syntax in which the newline character is +special and marks the end of a statement. GNU `make' has no limit on +the length of a statement line, up to the amount of memory in your +computer. + + However, it is difficult to read lines which are too long to display +without wrapping or scrolling. So, you can format your makefiles for +readability by adding newlines into the middle of a statement: you do +this by escaping the internal newlines with a backslash (`\') +character. Where we need to make a distinction we will refer to +"physical lines" as a single line ending with a newline (regardless of +whether it is escaped) and a "logical line" being a complete statement +including all escaped newlines up to the first non-escaped newline. + + The way in which backslash/newline combinations are handled depends +on whether the statement is a recipe line or a non-recipe line. +Handling of backslash/newline in a recipe line is discussed later +(*note Splitting Recipe Lines::). + + Outside of recipe lines, backslash/newlines are converted into a +single space character. Once that is done, all whitespace around the +backslash/newline is condensed into a single space: this includes all +whitespace preceding the backslash, all whitespace at the beginning of +the line after the backslash/newline, and any consecutive +backslash/newline combinations. + + If the `.POSIX' special target is defined then backslash/newline +handling is modified slightly to conform to POSIX.2: first, whitespace +preceding a backslash is not removed and second, consecutive +backslash/newlines are not condensed. + File: make.info, Node: Makefile Names, Next: Include, Prev: Makefile Contents, Up: Makefiles @@ -1066,7 +1141,7 @@ to date.) If you know that one or more of your makefiles cannot be remade and you want to keep `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 +preventing implicit rule look-up to do so. For example, you can write an explicit rule with the makefile as the target, and an empty recipe (*note Using Empty Recipes: Empty Recipes.). @@ -1129,7 +1204,7 @@ File: make.info, Node: Overriding Makefiles, Next: Reading Makefiles, Prev: R Sometimes it is useful to have a makefile that is mostly just like another makefile. You can often use the `include' directive to include one in the other, and add more targets or variable definitions. -However, it is illegal for two makefiles to give different recipes for +However, it is invalid for two makefiles to give different recipes for the same target. But there is another way. In the containing makefile (the one that wants to include the other), @@ -1203,7 +1278,9 @@ Variable definitions are parsed as follows: IMMEDIATE = DEFERRED IMMEDIATE ?= DEFERRED IMMEDIATE := IMMEDIATE + IMMEDIATE ::= IMMEDIATE IMMEDIATE += DEFERRED or IMMEDIATE + IMMEDIATE != IMMEDIATE define IMMEDIATE DEFERRED @@ -1221,13 +1298,26 @@ Variable definitions are parsed as follows: IMMEDIATE endef + define IMMEDIATE ::= + IMMEDIATE + endef + define IMMEDIATE += DEFERRED or IMMEDIATE endef + define IMMEDIATE != + IMMEDIATE + endef + For the append operator, `+=', the right-hand side is considered -immediate if the variable was previously set as a simple variable -(`:='), and deferred otherwise. +immediate if the variable was previously set as a simple variable (`:=' +or `::='), and deferred otherwise. + + For the shell assignment operator, `!=', the right-hand side is +evaluated immediately and handed to the shell. The result is stored in +the variable named on the left, and that variable becomes a simple +variable (and will thus be re-evaluated on each reference). Conditional Directives ---------------------- @@ -1291,8 +1381,8 @@ makefile: (escaped) variable reference is simply unescaped, without being recognized as a variable reference. Now during the secondary expansion the first word is expanded again but since it contains no variable or -function references it remains the static value `onefile', while the -second word is now a normal reference to the variable TWOVAR, which is +function references it remains the value `onefile', while the second +word is now a normal reference to the variable TWOVAR, which is expanded to the value `twofile'. The final result is that there are two prerequisites, `onefile' and `twofile'. @@ -1425,9 +1515,10 @@ example: /tmp/foo.o: %.o: $$(addsuffix /%.c,foo bar) foo.h + @echo $^ - The prerequisite list after the secondary expansion and directory -prefix reconstruction will be `/tmp/foo/foo.c /tmp/var/bar/foo.c + The prerequisite list printed, after the secondary expansion and +directory prefix reconstruction, will be `/tmp/foo/foo.c /tmp/bar/foo.c foo.h'. If you are not interested in this reconstruction, you can use `$$*' instead of `%' in the prerequisites list. @@ -1465,7 +1556,7 @@ Specify the Goals: Goals. * 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 recipes +* 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 @@ -1663,7 +1754,7 @@ specific file whose name consists of `foo', an asterisk, and `bar'. * Menu: -* Wildcard Examples:: Several examples +* Wildcard Examples:: Several examples. * Wildcard Pitfall:: Problems to avoid. * Wildcard Function:: How to cause wildcard expansion where it does not normally take place. @@ -1819,7 +1910,7 @@ do not need to change the individual rules, 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. -* Recipes/Search:: How to write recipes 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. @@ -2096,7 +2187,7 @@ and `libNAME.a', this is customizable via the `.LIBPATTERNS' variable. Each word in the value of this variable is a pattern string. When a prerequisite like `-lNAME' is seen, `make' will replace the percent in each pattern in the list with NAME and perform the above directory -searches using each library filename. +searches using each library file name. The default value for `.LIBPATTERNS' is `lib%.so lib%.a', which provides the default behavior described above. @@ -2154,9 +2245,9 @@ target, then you write the rule, like this: Another example of the usefulness of phony targets is in conjunction with recursive invocations of `make' (for more information, see *note Recursive Use of `make': Recursion.). In this case the makefile will -often contain a variable which lists a number of subdirectories to be +often contain a variable which lists a number of sub-directories to be built. One way to handle this is with one rule whose recipe is a shell -loop over the subdirectories, like this: +loop over the sub-directories, like this: SUBDIRS = foo bar baz @@ -2166,7 +2257,7 @@ loop over the subdirectories, like this: done There are problems with this method, however. First, any error -detected in a submake is ignored by this rule, so it will continue to +detected in a sub-make 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 `make' is invoked with the `-k' option, which is @@ -2174,9 +2265,9 @@ unfortunate. Second, and perhaps more importantly, you cannot take advantage of `make''s ability to build targets in parallel (*note Parallel Execution: Parallel.), 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) -you can remove these problems: + By declaring the sub-directories as phony targets (you must do this +as the sub-directory obviously always exists; otherwise it won't be +built) you can remove these problems: SUBDIRS = foo bar baz @@ -2189,8 +2280,8 @@ you can remove these problems: foo: baz - Here we've also declared that the `foo' subdirectory cannot be built -until after the `baz' subdirectory is complete; this kind of + Here we've also declared that the `foo' sub-directory cannot be +built until after the `baz' sub-directory is complete; this kind of relationship declaration is particularly important when attempting parallel builds. @@ -2391,16 +2482,16 @@ Certain names have special meanings if they appear as targets. lessen the chance of `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 `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 `.LOW_RESOLUTION_TIME' so that `make' does not - mistakenly conclude that the file is out of date. For example: + explicitly set a file's time stamp must discard its sub-second + part. If a file is created by such a command, you should list it + as a prerequisite of `.LOW_RESOLUTION_TIME' so that `make' does + not mistakenly conclude that the file is out of date. For example: .LOW_RESOLUTION_TIME: dst dst: src cp -p src dst - Since `cp -p' discards the subsecond part of `src''s time stamp, + Since `cp -p' discards the sub-second part of `src''s time stamp, `dst' is typically slightly older than `src' even when it is up to date. The `.LOW_RESOLUTION_TIME' line causes `make' to consider `dst' to be up to date if its time stamp is at the start of the @@ -2644,7 +2735,7 @@ the target; see *note Automatic Variables::. Each target specified must match the target pattern; a warning is issued for each target that does not. If you have a list of files, only some of which will match the pattern, you can use the `filter' -function to remove nonmatching file names (*note Functions for String +function to remove non-matching file names (*note Functions for String Substitution and Analysis: Text Functions.): files = foo.elc bar.o lose.o @@ -2776,10 +2867,10 @@ generates the output: Thus you no longer have to write all those rules yourself. The compiler will do it for you. - Note that such a prerequisite constitutes mentioning `main.o' in a -makefile, so it can never be considered an intermediate file by implicit -rule search. This means that `make' won't ever remove the file after -using it; *note Chains of Implicit Rules: Chained Rules. + Note that such a rule constitutes mentioning `main.o' in a makefile, +so it can never be considered an intermediate file by implicit rule +search. This means that `make' won't ever remove the file after using +it; *note Chains of Implicit Rules: Chained Rules. With old `make' programs, it was traditional practice to use this compiler feature to generate prerequisites on demand with a command like @@ -2814,8 +2905,8 @@ command (or any other command) fails (exits with a nonzero status). With the GNU C compiler, you may wish to use the `-MM' flag instead of `-M'. This omits prerequisites on system header files. *Note -Options Controlling the Preprocessor: (gcc.info)Preprocessor Options, -for details. +Options Controlling the Preprocessor: (gcc)Preprocessor Options, for +details. The purpose of the `sed' command is to translate (for example): @@ -2923,11 +3014,11 @@ they are ignored. * Menu: -* Splitting Lines:: Breaking long recipe lines for readability. +* Splitting Recipe Lines:: Breaking long recipe lines for readability. * Variables in Recipes:: Using `make' variables in recipes. -File: make.info, Node: Splitting Lines, Next: Variables in Recipes, Prev: Recipe Syntax, Up: Recipe Syntax +File: make.info, Node: Splitting Recipe Lines, Next: Variables in Recipes, Prev: Recipe Syntax, Up: Recipe Syntax 5.1.1 Splitting Recipe Lines ---------------------------- @@ -2940,13 +3031,14 @@ 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 _not_ removed from the 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 the recipe prefix character (a tab by default; -*note Special Variables::), then that character (and only that -character) is removed. Whitespace is never added to the recipe. +makefile (*note Splitting Long Lines: Splitting Lines.), +backslash/newline pairs are _not_ removed from the 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 +the recipe prefix character (a tab by default; *note Special +Variables::), then that character (and only that character) is removed. +Whitespace is never added to the recipe. For example, the recipe for the all target in this makefile: @@ -2993,13 +3085,13 @@ with single quotes (`'...''). This is the way the default shell different shell in your makefiles it may treat them differently. Sometimes you want to split a long line inside of single quotes, but -you don't want the backslash-newline to appear in the quoted content. +you don't want the backslash/newline to appear in the quoted content. 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 `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 +quoting rules for makefiles will be used, and the backslash/newline will be removed. If we rewrite our example above using this method: HELLO = 'hello \ @@ -3016,7 +3108,7 @@ Target-specific Variable Values: Target-specific.) to obtain a tighter correspondence between the variable and the recipe that uses it. -File: make.info, Node: Variables in Recipes, Prev: Splitting Lines, Up: Recipe Syntax +File: make.info, Node: Variables in Recipes, Prev: Splitting Recipe Lines, Up: Recipe Syntax 5.1.2 Using Variables in Recipes -------------------------------- @@ -3091,10 +3183,10 @@ File: make.info, Node: Execution, Next: Parallel, Prev: Echoing, Up: Recipes ==================== 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, unless -the `.ONESHELL' special target is in effect (*note Using One Shell: One -Shell.) (In practice, `make' may take shortcuts that do not affect the -results.) +executed by invoking a new sub-shell for each line of the recipe, +unless the `.ONESHELL' special target is in effect (*note Using One +Shell: One Shell.) (In practice, `make' may take shortcuts that do not +affect the results.) *Please note:* this implies that setting shell variables and invoking shell commands such as `cd' that set a context local to each @@ -3114,7 +3206,7 @@ case it would certainly cause `../foo' to be truncated, at least). * Menu: -* One Shell:: One shell for all lines in a recipe +* One Shell:: One shell for all lines in a recipe. * Choosing the Shell:: How `make' chooses the shell used to run recipes. @@ -3319,32 +3411,9 @@ If there is nothing looking like an integer after the `-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 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 recipe tries to take input -from the terminal at once, `make' will invalidate the standard input -streams of all but one running recipe. This means that attempting to -read from standard input will usually be a fatal error (a `Broken pipe' -signal) for most child processes if there are several. - - 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 `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 `make' works if we find a better -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 recipes. - - Finally, handling recursive `make' invocations raises issues. For -more information on this, see *note Communicating Options to a -Sub-`make': Options/Recursion. + Handling recursive `make' invocations raises issues for parallel +execution. For more information on this, see *note Communicating +Options to a Sub-`make': Options/Recursion. If a recipe fails (is killed by a signal or exits with a nonzero status), and errors are not ignored for that recipe (*note Errors in @@ -3374,6 +3443,126 @@ average goes below that limit, or until all the other jobs finish. By default, there is no load limit. +* Menu: + +* Parallel Output:: Handling output during parallel execution +* Parallel Input:: Handling input during parallel execution + + +File: make.info, Node: Parallel Output, Next: Parallel Input, Prev: Parallel, Up: Parallel + +5.4.1 Output During Parallel Execution +-------------------------------------- + +When running several recipes in parallel the output from each recipe +appears as soon as it is generated, with the result that messages from +different recipes may be interspersed, sometimes even appearing on the +same line. This can make reading the output very difficult. + + To avoid this you can use the `--output-sync' (`-O') option. This +option instructs `make' to save the output from the commands it invokes +and print it all once the commands are completed. Additionally, if +there are multiple recursive `make' invocations running in parallel, +they will communicate so that only one of them is generating output at +a time. + + If working directory printing is enabled (*note The +`--print-directory' Option: -w Option.), the enter/leave messages are +printed around each output grouping. If you prefer not to see these +messages add the `--no-print-directory' option to `MAKEFLAGS'. + + There are four levels of granularity when synchronizing output, +specified by giving an argument to the option (e.g., `-Oline' or +`--output-sync=recurse'). + +`none' + This is the default: all output is sent directly as it is + generated and no synchronization is performed. + +`line' + Output from each individual line of the recipe is grouped and + printed as soon as that line is complete. If a recipe consists of + multiple lines, they may be interspersed with lines from other + recipes. + +`target' + Output from the entire recipe for each target is grouped and + printed once the target is complete. This is the default if the + `--output-sync' or `-O' option is given with no argument. + +`recurse' + Output from each recursive invocation of `make' is grouped and + printed once the recursive invocation is complete. + + + Regardless of the mode chosen, the total build time will be the same. +The only difference is in how the output appears. + + The `target' and `recurse' modes both collect the output of the +entire recipe of a target and display it uninterrupted when the recipe +completes. The difference between them is in how recipes that contain +recursive invocations of `make' are treated (*note Recursive Use of +`make': Recursion.). For all recipes which have no recursive lines, +the `target' and `recurse' modes behave identically. + + If the `recurse' mode is chosen, recipes that contain recursive +`make' invocations are treated the same as other targets: the output +from the recipe, including the output from the recursive `make', is +saved and printed after the entire recipe is complete. This ensures +output from all the targets built by a given recursive `make' instance +are grouped together, which may make the output easier to understand. +However it also leads to long periods of time during the build where no +output is seen, followed by large bursts of output. If you are not +watching the build as it proceeds, but instead viewing a log of the +build after the fact, this may be the best option for you. + + If you are watching the output, the long gaps of quiet during the +build can be frustrating. The `target' output synchronization mode +detects when `make' is going to be invoked recursively, using the +standard methods, and it will not synchronize the output of those +lines. The recursive `make' will perform the synchronization for its +targets and the output from each will be displayed immediately when it +completes. Be aware that output from recursive lines of the recipe are +not synchronized (for example if the recursive line prints a message +before running `make', that message will not be synchronized). + + The `line' mode can be useful for front-ends that are watching the +output of `make' to track when recipes are started and completed. + + Some programs invoked by `make' may behave differently if they +determine they're writing output to a terminal versus a file (often +described as "interactive" vs. "non-interactive" modes). For example, +many programs that can display colorized output will not do so if they +determine they are not writing to a terminal. If your makefile invokes +a program like this then using the output synchronization options will +cause the program to believe it's running in "non-interactive" mode +even though the output will ultimately go to the terminal. + + +File: make.info, Node: Parallel Input, Prev: Parallel Output, Up: Parallel + +5.4.2 Input During Parallel Execution +------------------------------------- + +Two processes cannot both take input from the same device at the same +time. To make sure that only one recipe tries to take input from the +terminal at once, `make' will invalidate the standard input streams of +all but one running recipe. If another recipe attempts to read from +standard input it will usually incur a fatal error (a `Broken pipe' +signal). + + 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 `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 `make' works if we find a better +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 recipes. + File: make.info, Node: Errors, Next: Interrupts, Prev: Parallel, Up: Recipes @@ -3490,8 +3679,8 @@ File: make.info, Node: Recursion, Next: Canned Recipes, Prev: Interrupts, Up Recursive use of `make' means using `make' as a command in a makefile. This technique is useful when you want separate makefiles for various subsystems that compose a larger system. For example, suppose you have -a subdirectory `subdir' which has its own makefile, and you would like -the containing directory's makefile to run `make' on the subdirectory. +a sub-directory `subdir' which has its own makefile, and you would like +the containing directory's makefile to run `make' on the sub-directory. You can do it by writing this: subsystem: @@ -3581,9 +3770,9 @@ File: make.info, Node: Variables/Recursion, Next: Options/Recursion, Prev: MA Variable values of the top-level `make' can be passed to the sub-`make' through the environment by explicit request. These variables are -defined in the sub-`make' as defaults, but do not override what is -specified in the makefile used by the sub-`make' makefile unless you -use the `-e' switch (*note Summary of Options: Options Summary.). +defined in the sub-`make' as defaults, but they do not override +variables defined in the makefile used by the sub-`make' unless you use +the `-e' switch (*note Summary of Options: Options Summary.). To pass down, or "export", a variable, `make' adds the variable and its value to the environment for running each line of the recipe. The @@ -3813,6 +4002,22 @@ For instance, the `-t', `-n', and `-q' options, if put in one of these variables, could have disastrous consequences and would certainly have at least surprising and probably annoying effects. + If you'd like to run other implementations of `make' in addition to +GNU `make', and hence do not want to add GNU `make'-specific flags to +the `MAKEFLAGS' variable, you can add them to the `GNUMAKEFLAGS' +variable instead. This variable is parsed just before `MAKEFLAGS', in +the same way as `MAKEFLAGS'. When `make' constructs `MAKEFLAGS' to +pass to a recursive `make' it will include all flags, even those taken +from `GNUMAKEFLAGS'. As a result, after parsing `GNUMAKEFLAGS' GNU +`make' sets this variable to the empty string to avoid duplicating +flags during recursion. + + It's best to use `GNUMAKEFLAGS' only with flags which won't +materially change the behavior of your makefiles. If your makefiles +require GNU make anyway then simply use `MAKEFLAGS'. Flags such as +`--no-print-directory' or `--output-sync' may be appropriate for +`GNUMAKEFLAGS'. + File: make.info, Node: -w Option, Prev: Options/Recursion, Up: Recursion @@ -3890,7 +4095,7 @@ Implicit Rules.). 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, `make' invokes a separate subshell for each line. You can +particular, `make' invokes a separate sub-shell for each line. You can use the special prefix characters that affect command lines (`@', `-', and `+') on each line of a canned sequence. *Note Writing Recipes in Rules: Recipes. For example, using this canned sequence: @@ -3962,13 +4167,14 @@ definitions using `=', and the bodies of variable definitions using the compilers, programs to run, directories to look in for source files, directories to write output in, or anything else you can imagine. - A variable name may be any sequence of characters not containing `:', -`#', `=', or leading or trailing whitespace. However, variable names -containing characters other than letters, numbers, and underscores -should be avoided, as they may be given special meanings in the future, -and with some shells they cannot be passed through the environment to a -sub-`make' (*note Communicating Variables to a Sub-`make': -Variables/Recursion.). + A variable name may be any sequence of characters not containing +`:', `#', `=', or whitespace. However, variable names containing +characters other than letters, numbers, and underscores should be +considered carefully, as in some shells they cannot be passed through +the environment to a sub-`make' (*note Communicating Variables to a +Sub-`make': Variables/Recursion.). Variable names beginning with `.' +and an uppercase letter may be given special meaning in future versions +of `make'. Variable names are case-sensitive. The names `foo', `FOO', and `Foo' all refer to different variables. @@ -4077,9 +4283,9 @@ called "recursive expansion". will echo `Huh?': `$(foo)' expands to `$(bar)' which expands to `$(ugh)' which finally expands to `Huh?'. - This flavor of variable is the only sort supported by other versions -of `make'. It has its advantages and its disadvantages. An advantage -(most would say) is that: + This flavor of variable is the only sort supported by most other +versions of `make'. It has its advantages and its disadvantages. An +advantage (most would say) is that: CFLAGS = $(include_dirs) -O include_dirs = -Ifoo -Ibar @@ -4103,14 +4309,18 @@ called, or even how many times. To avoid all the problems and inconveniences of recursively expanded variables, there is another flavor: simply expanded variables. - "Simply expanded variables" are defined by lines using `:=' (*note -Setting Variables: Setting.). The value of a simply expanded variable -is scanned once and for all, expanding any references to other -variables and functions, when the variable is defined. The actual -value of the simply expanded variable is the result of expanding the -text that you write. It does not contain any references to other -variables; it contains their values _as of the time this variable was -defined_. Therefore, + "Simply expanded variables" are defined by lines using `:=' or `::=' +(*note Setting Variables: Setting.). Both forms are equivalent in GNU +`make'; however only the `::=' form is described by the POSIX standard +(support for `::=' was added to the POSIX standard in 2012, so older +versions of `make' won't accept this form either). + + The value of a simply expanded variable is scanned once and for all, +expanding any references to other variables and functions, when the +variable is defined. The actual value of the simply expanded variable +is the result of expanding the text that you write. It does not +contain any references to other variables; it contains their values _as +of the time this variable was defined_. Therefore, x := foo y := $(x) bar @@ -4289,7 +4499,7 @@ Here the innermost `$(x)' expands to `y', so `$($(x))' expands to `u'. References to recursively-expanded variables within a variable name -are reexpanded in the usual fashion. For example: +are re-expanded in the usual fashion. For example: x = $(y) y = z @@ -4424,8 +4634,8 @@ File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Var ===================== To set a variable from the makefile, write a line starting with the -variable name followed by `=' or `:='. Whatever follows the `=' or -`:=' on the line becomes the value. For example, +variable name followed by `=' `:=', or `::='. Whatever follows the +`=', `:=', or `::=' on the line becomes the value. For example, objects = main.o foo.o bar.o utils.o @@ -4433,21 +4643,19 @@ defines a variable named `objects'. Whitespace around the variable name and immediately after the `=' is ignored. Variables defined with `=' are "recursively expanded" variables. -Variables defined with `:=' are "simply expanded" variables; these -definitions can contain variable references which will be expanded -before the definition is made. *Note The Two Flavors of Variables: -Flavors. +Variables defined with `:=' or `::=' are "simply expanded" variables; +these definitions can contain variable references which will be +expanded before the definition is made. *Note The Two Flavors of +Variables: Flavors. The variable name may contain function and variable references, which are expanded when the line is read to find the actual variable name to use. There is no limit on the length of the value of a variable except the -amount of swapping space on the computer. When a variable definition is -long, it is a good idea to break it into several lines by inserting -backslash-newline at convenient places in the definition. This will not -affect the functioning of `make', but it will make the makefile easier -to read. +amount of memory on the computer. You can split the value of a +variable into multiple physical lines for readability (*note Splitting +Long Lines: Splitting Lines.). Most variable names are considered to have the empty string as a value if you have never set them. Several variables have built-in @@ -4470,6 +4678,27 @@ and FOO = bar endif + The shell assignment operator `!=' can be used to execute a program +and set a variable to its output. This operator first evaluates the +right-hand side, then passes that result to the shell for execution. +If the result of the execution ends in a newline, that one newline is +removed; all other newlines are replaced by spaces. The resulting +string is then placed into the named recursively-expanded variable. +For example: + + hash != printf '\043' + file_list != find . -name '*.c' + + If the result of the execution could produce a `$', and you don't +intend what follows that to be interpreted as a make variable or +function reference, then you must replace every `$' with `$$' as part +of the execution. Alternatively, you can set a simply expanded +variable to the result of running a program using the `shell' function +call. *Note The `shell' Function: Shell Function. For example: + + hash := $(shell printf '\043') + var := $(shell find . -name "*.c") + File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables @@ -4506,11 +4735,11 @@ flavors of variables. When you add to a variable's value with `+=', `make' acts essentially as if you had included the extra text in the initial -definition of the variable. If you defined it first with `:=', making -it a simply-expanded variable, `+=' adds to that simply-expanded -definition, and expands the new text before appending it to the old -value just as `:=' does (see *note Setting Variables: Setting, for a -full explanation of `:='). In fact, +definition of the variable. If you defined it first with `:=' or +`::=', making it a simply-expanded variable, `+=' adds to that +simply-expanded definition, and expands the new text before appending +it to the old value just as `:=' does (see *note Setting Variables: +Setting, for a full explanation of `:=' or `::='). In fact, variable := value variable += more @@ -4669,8 +4898,8 @@ equivalent to this: since two commands separated by semicolon behave much like two separate shell commands. However, note that using two separate lines means -`make' will invoke the shell twice, running an independent subshell for -each line. *Note Recipe Execution: Execution. +`make' will invoke the shell twice, running an independent sub-shell +for each line. *Note Recipe Execution: Execution. If you want variable definitions made with `define' to take precedence over command-line variable definitions, you can use the @@ -4787,13 +5016,13 @@ their normal behavior to this instance of the variable only. each member of the target list individually. The VARIABLE-ASSIGNMENT can be any valid form of assignment; -recursive (`='), static (`:='), appending (`+='), or conditional -(`?='). All variables that appear within the VARIABLE-ASSIGNMENT are -evaluated within the context of the target: thus, any -previously-defined target-specific variable values will be in effect. -Note that this variable is actually distinct from any "global" value: -the two variables do not have to have the same flavor (recursive vs. -static). +recursive (`='), simple (`:=' or `::='), appending (`+='), or +conditional (`?='). All variables that appear within the +VARIABLE-ASSIGNMENT are evaluated within the context of the target: +thus, any previously-defined target-specific variable values will be in +effect. Note that this variable is actually distinct from any "global" +value: the two variables do not have to have the same flavor (recursive +vs. simple). Target-specific variables have the same priority as any other makefile variable. Variables provided on the command line (and in the @@ -4903,7 +5132,7 @@ by any target, and hence will not be visible in any recipe. prog: a.o b.o Due to the `private' modifier, `a.o' and `b.o' will not inherit the -`EXTRA_CFLAGS' variable assignment from the `progs' target. +`EXTRA_CFLAGS' variable assignment from the `prog' target. File: make.info, Node: Special Variables, Prev: Suppressing Inheritance, Up: Using Variables @@ -4976,7 +5205,7 @@ GNU `make' supports some variables that have special properties. foo Note that assigning more than one target name to `.DEFAULT_GOAL' is - illegal and will result in an error. + invalid and will result in an error. `MAKE_RESTARTS' This variable is set only if this instance of `make' has restarted @@ -5009,10 +5238,10 @@ GNU `make' supports some variables that have special properties. `.FEATURES' Expands to a list of special features supported by this version of - `make'. Possible values include: + `make'. Possible values include, but are not limited to: `archives' - Supports `ar' (archive) files using special filename syntax. + Supports `ar' (archive) files using special file name syntax. *Note Using `make' to Update Archive Files: Archives. `check-symlink' @@ -5027,18 +5256,38 @@ GNU `make' supports some variables that have special properties. Supports "job server" enhanced parallel builds. *Note Parallel Execution: Parallel. - `second-expansion' - Supports secondary expansion of prerequisite lists. + `oneshell' + Supports the `.ONESHELL' special target. *Note Using One + Shell: One Shell. `order-only' Supports order-only prerequisites. *Note Types of Prerequisites: Prerequisite Types. + `second-expansion' + Supports secondary expansion of prerequisite lists. + + `shortest-stem' + Uses the "shortest stem" method of choosing which pattern, of + multiple applicable options, will be used. *Note How + Patterns Match: Pattern Match. + `target-specific' Supports target-specific and pattern-specific variable assignments. *Note Target-specific Variable Values: Target-specific. + `undefine' + Supports the `undefine' directive. *Note Undefine + Directive::. + + `guile' + Has GNU Guile available as an embedded extension language. + *Note GNU Guile Integration: Guile Integration. + + `load' + Supports dynamically loadable objects for creating custom + extensions. *Note Loading Dynamic Objects: Loading Objects. `.INCLUDE_DIRS' Expands to a list of directories that `make' searches for included @@ -5165,12 +5414,12 @@ text is used instead. or: - CONDITIONAL-DIRECTIVE + CONDITIONAL-DIRECTIVE-ONE TEXT-IF-ONE-IS-TRUE - else CONDITIONAL-DIRECTIVE - TEXT-IF-TRUE + else CONDITIONAL-DIRECTIVE-TWO + TEXT-IF-TWO-IS-TRUE else - TEXT-IF-FALSE + TEXT-IF-ONE-AND-TWO-ARE-FALSE endif There can be as many "`else' CONDITIONAL-DIRECTIVE" clauses as @@ -5349,13 +5598,15 @@ the point of the call, just as a variable might be substituted. * File Name Functions:: Functions for manipulating file names. * Conditional Functions:: Functions that implement conditions. * Foreach Function:: Repeat some text with controlled variation. +* File Function:: Write text to a file. * Call Function:: Expand a user-defined function. * Value Function:: Return the un-expanded value of a variable. * Eval Function:: Evaluate the arguments as makefile syntax. * Origin Function:: Find where a variable got its value. * Flavor Function:: Find out the flavor of a variable. -* Shell Function:: Substitute the output of a shell command. * Make Control Functions:: Functions that control how make runs. +* Shell Function:: Substitute the output of a shell command. +* Guile Function:: Use GNU Guile embedded scripting language. File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Functions, Up: Functions @@ -5363,7 +5614,9 @@ File: make.info, Node: Syntax of Functions, Next: Text Functions, Prev: Funct 8.1 Function Call Syntax ======================== -A function call resembles a variable reference. It looks like this: +A function call resembles a variable reference. It can appear anywhere +a variable reference can appear, and it is expanded using the same +rules as variable references. A function call looks like this: $(FUNCTION ARGUMENTS) @@ -5373,7 +5626,7 @@ or like this: Here FUNCTION is a function name; one of a short list of names that are part of `make'. You can also essentially create your own functions -by using the `call' builtin function. +by using the `call' built-in function. The ARGUMENTS are the arguments of the function. They are separated from the function name by one or more spaces or tabs, and if there is @@ -5827,7 +6080,7 @@ expanded. -File: make.info, Node: Foreach Function, Next: Call Function, Prev: Conditional Functions, Up: Functions +File: make.info, Node: Foreach Function, Next: File Function, Prev: Conditional Functions, Up: Functions 8.5 The `foreach' Function ========================== @@ -5878,9 +6131,9 @@ name, with an additional variable: Here we use the variable `find_files' this way. We use plain `=' to define a recursively-expanding variable, so that its value contains an -actual function call to be reexpanded under the control of `foreach'; a -simply-expanded variable would not do, since `wildcard' would be called -only once at the time of defining `find_files'. +actual function call to be re-expanded under the control of `foreach'; +a simply-expanded variable would not do, since `wildcard' would be +called only once at the time of defining `find_files'. The `foreach' function has no permanent effect on the variable VAR; its value and flavor after the `foreach' function call are the same as @@ -5895,16 +6148,66 @@ Flavors. result in variable names because many strange things are valid variable names, but are probably not what you intended. For example, - files := $(foreach Esta escrito en espanol!,b c ch,$(find_files)) + files := $(foreach Esta-escrito-en-espanol!,b c ch,$(find_files)) might be useful if the value of `find_files' references the variable -whose name is `Esta escrito en espanol!' (es un nombre bastante largo, +whose name is `Esta-escrito-en-espanol!' (es un nombre bastante largo, no?), but it is more likely to be a mistake. -File: make.info, Node: Call Function, Next: Value Function, Prev: Foreach Function, Up: Functions +File: make.info, Node: File Function, Next: Call Function, Prev: Foreach Function, Up: Functions + +8.6 The `file' Function +======================= + +The `file' function allows the makefile to write to a file. Two modes +of writing are supported: overwrite, where the text is written to the +beginning of the file and any existing content is lost, and append, +where the text is written to the end of the file, preserving the +existing content. In all cases the file is created if it does not +exist. + + The syntax of the `file' function is: + + $(file OP FILENAME,TEXT) + + The operator OP can be either `>' which indicates overwrite mode, or +`>>' which indicates append mode. The FILENAME indicates the file to +be written to. There may optionally be whitespace between the operator +and the file name. + + When the `file' function is expanded all its arguments are expanded +first, then the file indicated by FILENAME will be opened in the mode +described by OP. Finally TEXT will be written to the file. If TEXT +does not already end in a newline, a final newline will be written. +The result of evaluating the `file' function is always the empty string. + + It is a fatal error if the file cannot be opened for writing, or if +the write operation fails. + + For example, the `file' function can be useful if your build system +has a limited command line size and your recipe runs a command that can +accept arguments from a file as well. Many commands use the convention +that an argument prefixed with an `@' specifies a file containing more +arguments. Then you might write your recipe in this way: + + program: $(OBJECTS) + $(file >$@.in,$^) + $(CMD) $(CMDFLAGS) @$@.in + @rm $@.in + + If the command required each argument to be on a separate line of the +input file, you might write your recipe like this: + + program: $(OBJECTS) + $(file >$@.in,) $(foreach O,$^,$(file >>$@.in,$O)) + $(CMD) $(CMDFLAGS) @$@.in + @rm $@.in + + +File: make.info, Node: Call Function, Next: Value Function, Prev: File Function, Up: Functions -8.6 The `call' Function +8.7 The `call' Function ======================= The `call' function is unique in that it can be used to create new @@ -5931,12 +6234,12 @@ that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.) - If VARIABLE is the name of a builtin function, the builtin function + If VARIABLE is the name of a built-in function, the built-in function is always invoked (even if a `make' variable by that name also exists). The `call' function expands the PARAM arguments before assigning them to temporary variables. This means that VARIABLE values -containing references to builtin functions that have special expansion +containing references to built-in functions that have special expansion rules, like `foreach' or `if', may not work as you expect. Some examples may make this clearer. @@ -5981,7 +6284,7 @@ providing parameters to `call'. File: make.info, Node: Value Function, Next: Eval Function, Prev: Call Function, Up: Functions -8.7 The `value' Function +8.8 The `value' Function ======================== The `value' function provides a way for you to use the value of a @@ -5995,7 +6298,7 @@ the variable directly. $(value VARIABLE) - Note that VARIABLE is the _name_ of a variable; not a _reference_ to + Note that VARIABLE is the _name_ of a variable, not a _reference_ to that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.) @@ -6021,7 +6324,7 @@ avoided the expansion. File: make.info, Node: Eval Function, Next: Origin Function, Prev: Value Function, Up: Functions -8.8 The `eval' Function +8.9 The `eval' Function ======================= The `eval' function is very special: it allows you to define new @@ -6081,8 +6384,8 @@ Now your individual makefiles are quite straightforward. File: make.info, Node: Origin Function, Next: Flavor Function, Prev: Eval Function, Up: Functions -8.9 The `origin' Function -========================= +8.10 The `origin' Function +========================== The `origin' function is unlike most other functions in that it does not operate on the values of variables; it tells you something _about_ @@ -6092,7 +6395,7 @@ a variable. Specifically, it tells you where it came from. $(origin VARIABLE) - Note that VARIABLE is the _name_ of a variable to inquire about; not + Note that VARIABLE is the _name_ of a variable to inquire about, not a _reference_ to that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.) @@ -6165,21 +6468,21 @@ either `environment' or `environment override'. *Note Functions for String Substitution and Analysis: Text Functions. -File: make.info, Node: Flavor Function, Next: Shell Function, Prev: Origin Function, Up: Functions +File: make.info, Node: Flavor Function, Next: Make Control Functions, Prev: Origin Function, Up: Functions -8.10 The `flavor' Function +8.11 The `flavor' Function ========================== -The `flavor' function is unlike most other functions (and like `origin' -function) in that it does not operate on the values of variables; it -tells you something _about_ a variable. Specifically, it tells you the -flavor of a variable (*note The Two Flavors of Variables: Flavors.). +The `flavor' function, like the `origin' function, does not operate on +the values of variables but rather it tells you something _about_ a +variable. Specifically, it tells you the flavor of a variable (*note +The Two Flavors of Variables: Flavors.). The syntax of the `flavor' function is: $(flavor VARIABLE) - Note that VARIABLE is the _name_ of a variable to inquire about; not + Note that VARIABLE is the _name_ of a variable to inquire about, not a _reference_ to that variable. Therefore you would not normally use a `$' or parentheses when writing it. (You can, however, use a variable reference in the name if you want the name not to be a constant.) @@ -6198,45 +6501,7 @@ of the variable VARIABLE: -File: make.info, Node: Shell Function, Next: Make Control Functions, Prev: Flavor Function, Up: Functions - -8.11 The `shell' Function -========================= - -The `shell' function is unlike any other function other than the -`wildcard' function (*note The Function `wildcard': Wildcard Function.) -in that it communicates with the world outside of `make'. - - The `shell' function performs the same function that backquotes -(``') perform in most shells: it does "command expansion". This means -that it takes as an argument a shell command and evaluates to the -output of the command. The only processing `make' does on the result -is to convert each newline (or carriage-return / newline pair) to a -single space. If there is a trailing (carriage-return and) newline it -will simply be removed. - - The commands run by calls to the `shell' function are run when the -function calls are expanded (*note How `make' Reads a Makefile: Reading -Makefiles.). Because this function involves spawning a new shell, you -should carefully consider the performance implications of using the -`shell' function within recursively expanded variables vs. simply -expanded variables (*note The Two Flavors of Variables: Flavors.). - - Here are some examples of the use of the `shell' function: - - contents := $(shell cat foo) - -sets `contents' to the contents of the file `foo', with a space (rather -than a newline) separating each line. - - files := $(shell echo *.c) - -sets `files' to the expansion of `*.c'. Unless `make' is using a very -strange shell, this has the same result as `$(wildcard *.c)' (as long -as at least one `.c' file exists). - - -File: make.info, Node: Make Control Functions, Prev: Shell Function, Up: Functions +File: make.info, Node: Make Control Functions, Next: Shell Function, Prev: Flavor Function, Up: Functions 8.12 Functions That Control Make ================================ @@ -6284,6 +6549,62 @@ if some sort of environmental error is detected. empty string. +File: make.info, Node: Shell Function, Next: Guile Function, Prev: Make Control Functions, Up: Functions + +8.13 The `shell' Function +========================= + +The `shell' function is unlike any other function other than the +`wildcard' function (*note The Function `wildcard': Wildcard Function.) +in that it communicates with the world outside of `make'. + + The `shell' function performs the same function that backquotes +(``') perform in most shells: it does "command expansion". This means +that it takes as an argument a shell command and evaluates to the +output of the command. The only processing `make' does on the result +is to convert each newline (or carriage-return / newline pair) to a +single space. If there is a trailing (carriage-return and) newline it +will simply be removed. + + The commands run by calls to the `shell' function are run when the +function calls are expanded (*note How `make' Reads a Makefile: Reading +Makefiles.). Because this function involves spawning a new shell, you +should carefully consider the performance implications of using the +`shell' function within recursively expanded variables vs. simply +expanded variables (*note The Two Flavors of Variables: Flavors.). + + Here are some examples of the use of the `shell' function: + + contents := $(shell cat foo) + +sets `contents' to the contents of the file `foo', with a space (rather +than a newline) separating each line. + + files := $(shell echo *.c) + +sets `files' to the expansion of `*.c'. Unless `make' is using a very +strange shell, this has the same result as `$(wildcard *.c)' (as long +as at least one `.c' file exists). + + +File: make.info, Node: Guile Function, Prev: Shell Function, Up: Functions + +8.14 The `guile' Function +========================= + +If GNU `make' is built with support for GNU Guile as an embedded +extension language then the `guile' function will be available. The +`guile' function takes one argument which is first expanded by `make' +in the normal fashion, then passed to the GNU Guile evaluator. The +result of the evaluator is converted into a string and used as the +expansion of the `guile' function in the makefile. See *note GNU Guile +Integration: Guile Integration. for details on writing extensions to +`make' in Guile. + + You can determine whether GNU Guile support is available by checking +the `.FEATURES' variable for the word GUILE. + + File: make.info, Node: Running, Next: Implicit Rules, Prev: Functions, Up: Top 9 How to Run `make' @@ -6479,22 +6800,25 @@ what you want. Certain options specify other activities for `make'. `--just-print' `--dry-run' `--recon' - "No-op". The activity is to print what recipe would be used to - make the targets up to date, but not actually execute it. Some - recipes are still executed, even with this flag (*note How the - `MAKE' Variable Works: MAKE Variable.). + "No-op". Causes `make' to print the recipes that are needed to + make the targets up to date, but not actually execute them. Note + that some recipes are still executed, even with this flag (*note + How the `MAKE' Variable Works: MAKE Variable.). Also any recipes + needed to update included makefiles are still executed (*note How + Makefiles Are Remade: Remaking Makefiles.). `-t' `--touch' - "Touch". The activity is to mark the targets as up to date without - actually changing them. In other words, `make' pretends to compile - the targets but does not really change their contents. + "Touch". Marks targets as up to date without actually changing + them. In other words, `make' pretends to update the targets but + does not really change their contents; instead only their modified + times are updated. `-q' `--question' - "Question". The activity is to find out silently whether the - targets are up to date already; but execute no recipe in either - case. In other words, neither compilation nor output will occur. + "Question". Silently check whether the targets are up to date, but + do not execute recipes; the exit code shows whether any updates are + needed. `-W FILE' `--what-if=FILE' @@ -6636,10 +6960,10 @@ the makefile works by changing the variables. 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 `:=' instead of -`='. But, unless you want to include a variable reference or function -call in the _value_ that you specify, it makes no difference which kind -of variable you create. +variable; to make a simply-expanded variable, write `:=' or `::=' +instead of `='. But, unless you want to include a variable reference +or function call in the _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 `override' directive, which is a @@ -6682,385 +7006,3 @@ program, perhaps to find several independent problems so that you can correct them all before the next attempt to compile. This is why Emacs' `M-x compile' command passes the `-k' flag by default. - -File: make.info, Node: Options Summary, Prev: Testing, Up: Running - -9.7 Summary of Options -====================== - -Here is a table of all the options `make' understands: - -`-b' -`-m' - These options are ignored for compatibility with other versions of - `make'. - -`-B' -`--always-make' - Consider all targets out-of-date. GNU `make' proceeds to consider - targets and their prerequisites using the normal algorithms; - however, all targets so considered are always remade regardless of - the status of their prerequisites. To avoid infinite recursion, if - `MAKE_RESTARTS' (*note Other Special Variables: Special - Variables.) is set to a number greater than 0 this option is - disabled when considering whether to remake makefiles (*note How - Makefiles Are Remade: Remaking Makefiles.). - -`-C DIR' -`--directory=DIR' - Change to directory DIR before reading the makefiles. If multiple - `-C' options are specified, each is interpreted relative to the - previous one: `-C / -C etc' is equivalent to `-C /etc'. This is - typically used with recursive invocations of `make' (*note - Recursive Use of `make': Recursion.). - -`-d' - Print debugging information in addition to normal processing. The - debugging information says which files are being considered for - remaking, which file-times are being compared and with what - results, which files actually need to be remade, which implicit - rules are considered and which are applied--everything interesting - about how `make' decides what to do. The `-d' option is - equivalent to `--debug=a' (see below). - -`--debug[=OPTIONS]' - Print debugging information in addition to normal processing. - Various levels and types of output can be chosen. With no - arguments, print the "basic" level of debugging. Possible - arguments are below; only the first character is considered, and - values must be comma- or space-separated. - - `a (all)' - All types of debugging output are enabled. This is - equivalent to using `-d'. - - `b (basic)' - Basic debugging prints each target that was found to be - out-of-date, and whether the build was successful or not. - - `v (verbose)' - A level above `basic'; includes messages about which - makefiles were parsed, prerequisites that did not need to be - rebuilt, etc. This option also enables `basic' messages. - - `i (implicit)' - Prints messages describing the implicit rule searches for - each target. This option also enables `basic' messages. - - `j (jobs)' - Prints messages giving details on the invocation of specific - subcommands. - - `m (makefile)' - By default, the above messages are not enabled while trying - to remake the makefiles. This option enables messages while - rebuilding makefiles, too. Note that the `all' option does - enable this option. This option also enables `basic' - messages. - -`-e' -`--environment-overrides' - Give variables taken from the environment precedence over - variables from makefiles. *Note Variables from the Environment: - Environment. - -`--eval=STRING' - Evaluate STRING as makefile syntax. This is a command-line - version of the `eval' function (*note Eval Function::). The - evaluation is performed after the default rules and variables have - been defined, but before any makefiles are read. - -`-f FILE' -`--file=FILE' -`--makefile=FILE' - Read the file named FILE as a makefile. *Note Writing Makefiles: - Makefiles. - -`-h' -`--help' - Remind you of the options that `make' understands and then exit. - -`-i' -`--ignore-errors' - Ignore all errors in recipes executed to remake files. *Note - Errors in Recipes: Errors. - -`-I DIR' -`--include-dir=DIR' - Specifies a directory DIR to search for included makefiles. *Note - Including Other Makefiles: Include. If several `-I' options are - used to specify several directories, the directories are searched - in the order specified. - -`-j [JOBS]' -`--jobs[=JOBS]' - Specifies the number of recipes (jobs) to run simultaneously. - With no argument, `make' runs as many recipes simultaneously as - possible. If there is more than one `-j' option, the last one is - effective. *Note Parallel Execution: Parallel, for more - information on how recipes are run. Note that this option is - ignored on MS-DOS. - -`-k' -`--keep-going' - Continue as much as possible after an error. While the target that - failed, and those that depend on it, cannot be remade, the other - prerequisites of these targets can be processed all the same. - *Note Testing the Compilation of a Program: Testing. - -`-l [LOAD]' -`--load-average[=LOAD]' -`--max-load[=LOAD]' - Specifies that no new recipes should be started if there are other - recipes running and the load average is at least LOAD (a - floating-point number). With no argument, removes a previous load - limit. *Note Parallel Execution: Parallel. - -`-L' -`--check-symlink-times' - On systems that support symbolic links, this option causes `make' - to consider the timestamps on any symbolic links in addition to the - timestamp on the file referenced by those links. When this option - is provided, the most recent timestamp among the file and the - symbolic links is taken as the modification time for this target - file. - -`-n' -`--just-print' -`--dry-run' -`--recon' - Print the recipe that would be executed, but do not execute it - (except in certain circumstances). *Note Instead of Executing - Recipes: Instead of Execution. - -`-o FILE' -`--old-file=FILE' -`--assume-old=FILE' - Do not remake the file FILE even if it is older than its - prerequisites, and do not remake anything on account of changes in - FILE. Essentially the file is treated as very old and its rules - are ignored. *Note Avoiding Recompilation of Some Files: Avoiding - Compilation. - -`-p' -`--print-data-base' - 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 - `-v' switch (see below). To print the data base without trying to - remake any files, use `make -qp'. To print the data base of - predefined rules and variables, use `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. - -`-q' -`--question' - "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. *Note Instead of Executing Recipes: Instead - of Execution. - -`-r' -`--no-builtin-rules' - Eliminate use of the built-in implicit rules (*note Using Implicit - Rules: Implicit Rules.). You can still define your own by writing - pattern rules (*note Defining and Redefining Pattern Rules: - Pattern Rules.). The `-r' option also clears out the default list - of suffixes for suffix rules (*note Old-Fashioned Suffix Rules: - Suffix Rules.). But you can still define your own suffixes with a - rule for `.SUFFIXES', and then define your own suffix rules. Note - that only _rules_ are affected by the `-r' option; default - variables remain in effect (*note Variables Used by Implicit - Rules: Implicit Variables.); see the `-R' option below. - -`-R' -`--no-builtin-variables' - Eliminate use of the built-in rule-specific variables (*note - Variables Used by Implicit Rules: Implicit Variables.). You can - still define your own, of course. The `-R' option also - automatically enables the `-r' option (see above), since it - doesn't make sense to have implicit rules without any definitions - for the variables that they use. - -`-s' -`--silent' -`--quiet' - Silent operation; do not print the recipes as they are executed. - *Note Recipe Echoing: Echoing. - -`-S' -`--no-keep-going' -`--stop' - Cancel the effect of the `-k' option. This is never necessary - except in a recursive `make' where `-k' might be inherited from - the top-level `make' via `MAKEFLAGS' (*note Recursive Use of - `make': Recursion.) or if you set `-k' in `MAKEFLAGS' in your - environment. - -`-t' -`--touch' - Touch files (mark them up to date without really changing them) - instead of running their recipes. This is used to pretend that the - recipes were done, in order to fool future invocations of `make'. - *Note Instead of Executing Recipes: Instead of Execution. - -`-v' -`--version' - Print the version of the `make' program plus a copyright, a list - of authors, and a notice that there is no warranty; then exit. - -`-w' -`--print-directory' - Print a message containing the working directory both before and - after executing the makefile. This may be useful for tracking - down errors from complicated nests of recursive `make' commands. - *Note Recursive Use of `make': Recursion. (In practice, you - rarely need to specify this option since `make' does it for you; - see *note The `--print-directory' Option: -w Option.) - -`--no-print-directory' - Disable printing of the working directory under `-w'. This option - is useful when `-w' is turned on automatically, but you do not - want to see the extra messages. *Note The `--print-directory' - Option: -w Option. - -`-W FILE' -`--what-if=FILE' -`--new-file=FILE' -`--assume-new=FILE' - Pretend that the target FILE has just been modified. When used - with the `-n' flag, this shows you what would happen if you were - to modify that file. Without `-n', it is almost the same as - running a `touch' command on the given file before running `make', - except that the modification time is changed only in the - imagination of `make'. *Note Instead of Executing Recipes: - Instead of Execution. - -`--warn-undefined-variables' - Issue a warning message whenever `make' sees a reference to an - undefined variable. This can be helpful when you are trying to - debug makefiles which use variables in complex ways. - - -File: make.info, Node: Implicit Rules, Next: Archives, Prev: Running, Up: Top - -10 Using Implicit Rules -*********************** - -Certain standard ways of remaking target files are used very often. For -example, one customary way to make an object file is from a C source -file using the C compiler, `cc'. - - "Implicit rules" tell `make' how to use customary techniques so that -you do not have to specify them in detail when you want to use them. -For example, there is an implicit rule for C compilation. File names -determine which implicit rules are run. For example, C compilation -typically takes a `.c' file and makes a `.o' file. So `make' applies -the implicit rule for C compilation when it sees this combination of -file name endings. - - A chain of implicit rules can apply in sequence; for example, `make' -will remake a `.o' file from a `.y' file by way of a `.c' file. - - 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 `CFLAGS' controls -the flags given to the C compiler by the implicit rule for C -compilation. - - You can define your own implicit rules by writing "pattern rules". - - "Suffix rules" are a more limited way to define implicit rules. -Pattern rules are more general and clearer, but suffix rules are -retained for compatibility. - -* Menu: - -* Using Implicit:: How to use an existing implicit rule - 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 recipes for rules which - cannot find any. -* Suffix Rules:: The old-fashioned style of implicit rule. -* Implicit Rule Search:: The precise algorithm for applying - implicit rules. - - -File: make.info, Node: Using Implicit, Next: Catalogue of Rules, Prev: Implicit Rules, Up: Implicit Rules - -10.1 Using Implicit Rules -========================= - -To allow `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 `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: - - foo : foo.o bar.o - cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS) - -Because you mention `foo.o' but do not give a rule for it, `make' will -automatically look for an implicit rule that tells how to update it. -This happens whether or not the file `foo.o' currently exists. - - 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 `foo.o' with no recipe if you need to specify additional -prerequisites, such as header files, that the implicit rule cannot -supply. - - Each implicit rule has a target pattern and prerequisite patterns. -There may be many implicit rules with the same target pattern. For -example, numerous rules make `.o' files: one, from a `.c' file with the -C compiler; another, from a `.p' file with the Pascal compiler; and so -on. The rule that actually applies is the one whose prerequisites -exist or can be made. So, if you have a file `foo.c', `make' will run -the C compiler; otherwise, if you have a file `foo.p', `make' will run -the Pascal compiler; and so on. - - Of course, when you write the makefile, you know which implicit rule -you want `make' to use, and you know it will choose that one because you -know which possible prerequisite files are supposed to exist. *Note -Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all -the predefined implicit rules. - - Above, we said an implicit rule applies if the required -prerequisites "exist or can be made". A file "can be made" if it is -mentioned explicitly in the makefile as a target or a prerequisite, or -if an implicit rule can be recursively found for how to make it. When -an implicit prerequisite is the result of another implicit rule, we say -that "chaining" is occurring. *Note Chains of Implicit Rules: Chained -Rules. - - In general, `make' searches for an implicit rule for each target, and -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. *Note -Implicit Rule Search Algorithm: Implicit Rule Search, for the details -of how the search is done. - - Note that explicit prerequisites do not influence implicit rule -search. For example, consider this explicit rule: - - foo.o: foo.p - -The prerequisite on `foo.p' does not necessarily mean that `make' will -remake `foo.o' according to the implicit rule to make an object file, a -`.o' file, from a Pascal source file, a `.p' file. For example, if -`foo.c' also exists, the implicit rule to make an object file from a C -source file is used instead, because it appears before the Pascal rule -in the list of predefined implicit rules (*note Catalogue of Implicit -Rules: Catalogue of Rules.). - - If you do not want an implicit rule to be used for a target that has -no recipe, you can give that target an empty recipe by writing a -semicolon (*note Defining Empty Recipes: Empty Recipes.). - |