TOS Silver 2000

home *** CD-ROM | disk | FTP | other *** search

/ TOS Silver 2000 / TOS Silver 2000.iso / programm / GNU_C++ / LIB / MAKE3761.LZH / info / make.info-4 < prev next >

Wrap

GNU Info File | 1998-07-20 | 48.0 KB | 1,235 lines

This is Info file make.info, produced by Makeinfo version 1.67 from the input file make.texinfo. INFO-DIR-SECTION The GNU make utility START-INFO-DIR-ENTRY * GNU make: (make.info). The GNU make utility. END-INFO-DIR-ENTRY 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.51, last updated 26 Aug 1997, of `The GNU Make Manual', for `make', Version 3.76 Beta. Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by the Free Software Foundation.  File: make.info, Node: Setting, Next: Appending, Prev: Values, Up: Using Variables Setting Variables ================= 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, objects = main.o foo.o bar.o utils.o 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. 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. Most variable names are considered to have the empty string as a value if you have never set them. Several variables have built-in initial values that are not empty, but you can set them in the usual ways (*note Variables Used by Implicit Rules: Implicit Variables.). Several special variables are set automatically to a new value for each rule; these are called the "automatic" variables (*note Automatic Variables: Automatic.).  File: make.info, Node: Appending, Next: Override Directive, Prev: Setting, Up: Using Variables Appending More Text to Variables ================================ Often it is useful to add more text to the value of a variable already defined. You do this with a line containing `+=', like this: objects += another.o This takes the value of the variable `objects', and adds the text `another.o' to it (preceded by a single space). Thus: objects = main.o foo.o bar.o utils.o objects += another.o sets `objects' to `main.o foo.o bar.o utils.o another.o'. Using `+=' is similar to: objects = main.o foo.o bar.o utils.o objects := $(objects) another.o but differs in ways that become important when you use more complex values. When the variable in question has not been defined before, `+=' acts just like normal `=': it defines a recursively-expanded variable. However, when there *is* a previous definition, exactly what `+=' does depends on what flavor of variable you defined originally. *Note The Two Flavors of Variables: Flavors, for an explanation of the two 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 (*note Setting Variables: Setting., for a full explanation of `:='). In fact, variable := value variable += more is exactly equivalent to: variable := value variable := $(variable) more On the other hand, when you use `+=' with a variable that you defined first to be recursively-expanded using plain `=', `make' does something a bit different. Recall that when you define a recursively-expanded variable, `make' does not expand the value you set for variable and function references immediately. Instead it stores the text verbatim, and saves these variable and function references to be expanded later, when you refer to the new variable (*note The Two Flavors of Variables: Flavors.). When you use `+=' on a recursively-expanded variable, it is this unexpanded text to which `make' appends the new text you specify. variable = value variable += more is roughly equivalent to: temp = value variable = $(temp) more except that of course it never defines a variable called `temp'. The importance of this comes when the variable's old value contains variable references. Take this common example: CFLAGS = $(includes) -O ... CFLAGS += -pg # enable profiling The first line defines the `CFLAGS' variable with a reference to another variable, `includes'. (`CFLAGS' is used by the rules for C compilation; *note Catalogue of Implicit Rules: Catalogue of Rules..) Using `=' for the definition makes `CFLAGS' a recursively-expanded variable, meaning `$(includes) -O' is *not* expanded when `make' processes the definition of `CFLAGS'. Thus, `includes' need not be defined yet for its value to take effect. It only has to be defined before any reference to `CFLAGS'. If we tried to append to the value of `CFLAGS' without using `+=', we might do it like this: CFLAGS := $(CFLAGS) -pg # enable profiling This is pretty close, but not quite what we want. Using `:=' redefines `CFLAGS' as a simply-expanded variable; this means `make' expands the text `$(CFLAGS) -pg' before setting the variable. If `includes' is not yet defined, we get ` -O -pg', and a later definition of `includes' will have no effect. Conversely, by using `+=' we set `CFLAGS' to the *unexpanded* value `$(includes) -O -pg'. Thus we preserve the reference to `includes', so if that variable gets defined at any later point, a reference like `$(CFLAGS)' still uses its value.  File: make.info, Node: Override Directive, Next: Defining, Prev: Appending, Up: Using Variables The `override' Directive ======================== If a variable has been set with a command argument (*note Overriding Variables: Overriding.), then ordinary assignments in the makefile are ignored. If you want to set the variable in the makefile even though it was set with a command argument, you can use an `override' directive, which is a line that looks like this: override VARIABLE = VALUE or override VARIABLE := VALUE To append more text to a variable defined on the command line, use: override VARIABLE += MORE TEXT *Note Appending More Text to Variables: Appending. The `override' directive was not invented for escalation in the war between makefiles and command arguments. It was invented so you can alter and add to values that the user specifies with command arguments. For example, suppose you always want the `-g' switch when you run the C compiler, but you would like to allow the user to specify the other switches with a command argument just as usual. You could use this `override' directive: override CFLAGS += -g You can also use `override' directives with `define' directives. This is done as you might expect: override define foo bar endef *Note Defining Variables Verbatim: Defining.  File: make.info, Node: Defining, Next: Environment, Prev: Override Directive, Up: Using Variables Defining Variables Verbatim =========================== Another way to set the value of a variable is to use the `define' directive. This directive has an unusual syntax which allows newline characters to be included in the value, which is convenient for defining canned sequences of commands (*note Defining Canned Command Sequences: Sequences.). The `define' directive is followed on the same line by the name of the variable and nothing more. The value to give the variable appears on the following lines. The end of the value is marked by a line containing just the word `endef'. Aside from this difference in syntax, `define' works just like `=': it creates a recursively-expanded variable (*note The Two Flavors of Variables: Flavors.). The variable name may contain function and variable references, which are expanded when the directive is read to find the actual variable name to use. define two-lines echo foo echo $(bar) endef The value in an ordinary assignment cannot contain a newline; but the newlines that separate the lines of the value in a `define' become part of the variable's value (except for the final newline which precedes the `endef' and is not considered part of the value). The previous example is functionally equivalent to this: 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 `make' will invoke the shell twice, running an independent subshell for each line. *Note Command Execution: Execution. If you want variable definitions made with `define' to take precedence over command-line variable definitions, you can use the `override' directive together with `define': override define two-lines foo $(bar) endef *Note The `override' Directive: Override Directive.  File: make.info, Node: Environment, Prev: Defining, Up: Using Variables Variables from the Environment ============================== Variables in `make' can come from the environment in which `make' is run. Every environment variable that `make' sees when it starts up is transformed into a `make' variable with the same name and value. But an explicit assignment in the makefile, or with a command argument, overrides the environment. (If the `-e' flag is specified, then values from the environment override assignments in the makefile. *Note Summary of Options: Options Summary. But this is not recommended practice.) Thus, by setting the variable `CFLAGS' in your environment, you can cause all C compilations in most makefiles to use the compiler switches you prefer. This is safe for variables with standard or conventional meanings because you know that no makefile will use them for other things. (But this is not totally reliable; some makefiles set `CFLAGS' explicitly and therefore are not affected by the value in the environment.) When `make' is invoked recursively, variables defined in the outer invocation can be passed to inner invocations through the environment (*note Recursive Use of `make': Recursion.). By default, only variables that came from the environment or the command line are passed to recursive invocations. You can use the `export' directive to pass other variables. *Note Communicating Variables to a Sub-`make': Variables/Recursion, for full details. Other use of variables from the environment is not recommended. It is not wise for makefiles to depend for their functioning on environment variables set up outside their control, since this would cause different users to get different results from the same makefile. This is against the whole purpose of most makefiles. Such problems would be especially likely with the variable `SHELL', which is normally present in the environment to specify the user's choice of interactive shell. It would be very undesirable for this choice to affect `make'. So `make' ignores the environment value of `SHELL' (except on MS-DOS and MS-Windows, where `SHELL' is usually not set. *Note Special handling of SHELL on MS-DOS: Execution.)  File: make.info, Node: Conditionals, Next: Functions, Prev: Using Variables, Up: Top Conditional Parts of Makefiles ****************************** A "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 `make' actually "sees" in the makefile, so they *cannot* be used to control shell commands at the time of execution. * Menu: * Conditional Example:: Example of a conditional * Conditional Syntax:: The syntax of conditionals. * Testing Flags:: Conditionals that test flags.  File: make.info, Node: Conditional Example, Next: Conditional Syntax, Up: Conditionals Example of a Conditional ======================== The following example of a conditional tells `make' to use one set of libraries if the `CC' variable is `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 `CC=gcc' as an argument to `make' changes not only which compiler is used but also which libraries are linked. libs_for_gcc = -lgnu normal_libs = foo: $(objects) ifeq ($(CC),gcc) $(CC) -o foo $(objects) $(libs_for_gcc) else $(CC) -o foo $(objects) $(normal_libs) endif This conditional uses three directives: one `ifeq', one `else' and one `endif'. The `ifeq' directive begins the conditional, and specifies the condition. It contains two arguments, separated by a comma and surrounded by parentheses. Variable substitution is performed on both arguments and then they are compared. The lines of the makefile following the `ifeq' are obeyed if the two arguments match; otherwise they are ignored. The `else' directive causes the following lines to be obeyed if the previous conditional failed. In the example above, this means that the second alternative linking command is used whenever the first alternative is not used. It is optional to have an `else' in a conditional. The `endif' directive ends the conditional. Every conditional must end with an `endif'. Unconditional makefile text follows. As this example illustrates, conditionals work at the textual level: the lines of the conditional are treated as part of the makefile, or ignored, according to the condition. This is why the larger syntactic units of the makefile, such as rules, may cross the beginning or the end of the conditional. When the variable `CC' has the value `gcc', the above example has this effect: foo: $(objects) $(CC) -o foo $(objects) $(libs_for_gcc) When the variable `CC' has any other value, the effect is this: foo: $(objects) $(CC) -o foo $(objects) $(normal_libs) Equivalent results can be obtained in another way by conditionalizing a variable assignment and then using the variable unconditionally: libs_for_gcc = -lgnu normal_libs = ifeq ($(CC),gcc) libs=$(libs_for_gcc) else libs=$(normal_libs) endif foo: $(objects) $(CC) -o foo $(objects) $(libs)  File: make.info, Node: Conditional Syntax, Next: Testing Flags, Prev: Conditional Example, Up: Conditionals Syntax of Conditionals ====================== The syntax of a simple conditional with no `else' is as follows: CONDITIONAL-DIRECTIVE TEXT-IF-TRUE endif The TEXT-IF-TRUE may be any lines of text, to be considered as part of the makefile if the condition is true. If the condition is false, no text is used instead. The syntax of a complex conditional is as follows: CONDITIONAL-DIRECTIVE TEXT-IF-TRUE else TEXT-IF-FALSE endif If the condition is true, TEXT-IF-TRUE is used; otherwise, TEXT-IF-FALSE is used instead. The TEXT-IF-FALSE can be any number of lines of text. The syntax of the CONDITIONAL-DIRECTIVE is the same whether the conditional is simple or complex. There are four different directives that test different conditions. Here is a table of them: `ifeq (ARG1, ARG2)' `ifeq 'ARG1' 'ARG2'' `ifeq "ARG1" "ARG2"' `ifeq "ARG1" 'ARG2'' `ifeq 'ARG1' "ARG2"' Expand all variable references in ARG1 and ARG2 and compare them. If they are identical, the TEXT-IF-TRUE is effective; otherwise, the TEXT-IF-FALSE, if any, is effective. Often you want to test if a variable has a non-empty value. When the value results from complex expansions of variables and functions, expansions you would consider empty may actually contain whitespace characters and thus are not seen as empty. However, you can use the `strip' function (*note Text Functions::.) to avoid interpreting whitespace as a non-empty value. For example: ifeq ($(strip $(foo)),) TEXT-IF-EMPTY endif will evaluate TEXT-IF-EMPTY even if the expansion of `$(foo)' contains whitespace characters. `ifneq (ARG1, ARG2)' `ifneq 'ARG1' 'ARG2'' `ifneq "ARG1" "ARG2"' `ifneq "ARG1" 'ARG2'' `ifneq 'ARG1' "ARG2"' Expand all variable references in ARG1 and ARG2 and compare them. If they are different, the TEXT-IF-TRUE is effective; otherwise, the TEXT-IF-FALSE, if any, is effective. `ifdef VARIABLE-NAME' If the variable VARIABLE-NAME has a non-empty value, the TEXT-IF-TRUE is effective; otherwise, the TEXT-IF-FALSE, if any, is effective. Variables that have never been defined have an empty value. Note that `ifdef' only tests whether a variable has a value. It does not expand the variable to see if that value is nonempty. Consequently, tests using `ifdef' return true for all definitions except those like `foo ='. To test for an empty value, use `ifeq ($(foo),)'. For example, bar = foo = $(bar) ifdef foo frobozz = yes else frobozz = no endif sets `frobozz' to `yes', while: foo = ifdef foo frobozz = yes else frobozz = no endif sets `frobozz' to `no'. `ifndef VARIABLE-NAME' If the variable VARIABLE-NAME has an empty value, the TEXT-IF-TRUE is effective; otherwise, the TEXT-IF-FALSE, if any, is effective. 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 `#' may appear at the end of the line. The other two directives that play a part in a conditional are `else' and `endif'. Each of these directives is written as one word, with no arguments. Extra spaces are allowed and ignored at the beginning of the line, and spaces or tabs at the end. A comment starting with `#' may appear at the end of the line. Conditionals affect which lines of the makefile `make' uses. If the condition is true, `make' reads the lines of the TEXT-IF-TRUE as part of the makefile; if the condition is false, `make' ignores those lines completely. It follows that syntactic units of the makefile, such as rules, may safely be split across the beginning or the end of the conditional. `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 (*note Automatic Variables: Automatic.). To prevent intolerable confusion, it is not permitted to start a conditional in one makefile and end it in another. However, you may write an `include' directive within a conditional, provided you do not attempt to terminate the conditional inside the included file.  File: make.info, Node: Testing Flags, Prev: Conditional Syntax, Up: Conditionals Conditionals that Test Flags ============================ You can write a conditional that tests `make' command flags such as `-t' by using the variable `MAKEFLAGS' together with the `findstring' function (*note Functions for String Substitution and Analysis: Text Functions.). This is useful when `touch' is not enough to make a file appear up to date. The `findstring' function determines whether one string appears as a substring of another. If you want to test for the `-t' flag, use `t' as the first string and the value of `MAKEFLAGS' as the other. For example, here is how to arrange to use `ranlib -t' to finish marking an archive file up to date: archive.a: ... ifneq (,$(findstring t,$(MAKEFLAGS))) +touch archive.a +ranlib -t archive.a else ranlib archive.a endif The `+' prefix marks those command lines as "recursive" so that they will be executed despite use of the `-t' flag. *Note Recursive Use of `make': Recursion.  File: make.info, Node: Functions, Next: Running, Prev: Conditionals, Up: Top Functions for Transforming Text ******************************* "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 "function call", where you give the name of the function and some text (the "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. * Text Functions:: General-purpose text manipulation functions. * File Name Functions:: Functions for manipulating file names. * Foreach Function:: Repeat some text with controlled variation. * Origin Function:: Find where a variable got its value. * Shell Function:: Substitute the output of a shell command.  File: make.info, Node: Syntax of Functions, Next: Text Functions, Up: Functions Function Call Syntax ==================== A function call resembles a variable reference. It looks like this: $(FUNCTION ARGUMENTS) or like this: ${FUNCTION ARGUMENTS} Here FUNCTION is a function name; one of a short list of names that are part of `make'. There is no provision for defining new functions. 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 more than one argument, then they are separated by commas. Such whitespace and commas are not part of an argument's value. The delimiters which you use to surround the function call, whether parentheses or braces, can appear in an argument only in matching pairs; the other kind of delimiters may appear singly. If the arguments themselves contain other function calls or variable references, it is wisest to use the same kind of delimiters for all the references; write `$(subst a,b,$(x))', not `$(subst a,b,${x})'. This is because it is clearer, and because only one type of delimiter is matched to find the end of the reference. The text written for each argument is processed by substitution of variables and function calls to produce the argument value, which is the text on which the function acts. The substitution is done in the order in which the arguments appear. Commas and unmatched parentheses or braces cannot appear in the text of an argument as written; leading spaces cannot appear in the text of the first argument as written. These characters can be put into the argument value by variable substitution. First define variables `comma' and `space' whose values are isolated comma and space characters, then substitute these variables where such characters are wanted, like this: comma:= , empty:= space:= $(empty) $(empty) foo:= a b c bar:= $(subst $(space),$(comma),$(foo)) # bar is now `a,b,c'. Here the `subst' function replaces each space with a comma, through the value of `foo', and substitutes the result.  File: make.info, Node: Text Functions, Next: File Name Functions, Prev: Syntax of Functions, Up: Functions Functions for String Substitution and Analysis ============================================== Here are some functions that operate on strings: `$(subst FROM,TO,TEXT)' Performs a textual replacement on the text TEXT: each occurrence of FROM is replaced by TO. The result is substituted for the function call. For example, $(subst ee,EE,feet on the street) substitutes the string `fEEt on the strEEt'. `$(patsubst PATTERN,REPLACEMENT,TEXT)' Finds whitespace-separated words in TEXT that match PATTERN and replaces them with REPLACEMENT. Here PATTERN may contain a `%' which acts as a wildcard, matching any number of any characters within a word. If REPLACEMENT also contains a `%', the `%' is replaced by the text that matched the `%' in PATTERN. `%' characters in `patsubst' function invocations can be quoted with preceding backslashes (`\'). Backslashes that would otherwise quote `%' characters can be quoted with more backslashes. Backslashes that quote `%' characters or other backslashes are removed from the pattern before it is compared file names or has a stem substituted into it. Backslashes that are not in danger of quoting `%' characters go unmolested. For example, the pattern `the\%weird\\%pattern\\' has `the%weird\' preceding the operative `%' character, and `pattern\\' following it. The final two backslashes are left alone because they cannot affect any `%' character. Whitespace between words is folded into single space characters; leading and trailing whitespace is discarded. For example, $(patsubst %.c,%.o,x.c.c bar.c) produces the value `x.c.o bar.o'. Substitution references (*note Substitution References: Substitution Refs.) are a simpler way to get the effect of the `patsubst' function: $(VAR:PATTERN=REPLACEMENT) is equivalent to $(patsubst PATTERN,REPLACEMENT,$(VAR)) The second shorthand simplifies one of the most common uses of `patsubst': replacing the suffix at the end of file names. $(VAR:SUFFIX=REPLACEMENT) is equivalent to $(patsubst %SUFFIX,%REPLACEMENT,$(VAR)) For example, you might have a list of object files: objects = foo.o bar.o baz.o To get the list of corresponding source files, you could simply write: $(objects:.o=.c) instead of using the general form: $(patsubst %.o,%.c,$(objects)) `$(strip STRING)' Removes leading and trailing whitespace from STRING and replaces each internal sequence of one or more whitespace characters with a single space. Thus, `$(strip a b c )' results in `a b c'. The function `strip' can be very useful when used in conjunction with conditionals. When comparing something with the empty string `' using `ifeq' or `ifneq', you usually want a string of just whitespace to match the empty string (*note Conditionals::.). Thus, the following may fail to have the desired results: .PHONY: all ifneq "$(needs_made)" "" all: $(needs_made) else all:;@echo 'Nothing to make!' endif Replacing the variable reference `$(needs_made)' with the function call `$(strip $(needs_made))' in the `ifneq' directive would make it more robust. `$(findstring FIND,IN)' Searches IN for an occurrence of FIND. If it occurs, the value is FIND; otherwise, the value is empty. You can use this function in a conditional to test for the presence of a specific substring in a given string. Thus, the two examples, $(findstring a,a b c) $(findstring a,b c) produce the values `a' and `' (the empty string), respectively. *Note Testing Flags::, for a practical application of `findstring'. `$(filter PATTERN...,TEXT)' Removes all whitespace-separated words in TEXT that do *not* match any of the PATTERN words, returning only matching words. The patterns are written using `%', just like the patterns used in the `patsubst' function above. The `filter' function can be used to separate out different types of strings (such as file names) in a variable. For example: sources := foo.c bar.c baz.s ugh.h foo: $(sources) cc $(filter %.c %.s,$(sources)) -o foo says that `foo' depends of `foo.c', `bar.c', `baz.s' and `ugh.h' but only `foo.c', `bar.c' and `baz.s' should be specified in the command to the compiler. `$(filter-out PATTERN...,TEXT)' Removes all whitespace-separated words in TEXT that *do* match the PATTERN words, returning only the words that *do not* match. This is the exact opposite of the `filter' function. For example, given: objects=main1.o foo.o main2.o bar.o mains=main1.o main2.o the following generates a list which contains all the object files not in `mains': $(filter-out $(mains),$(objects)) `$(sort LIST)' Sorts the words of LIST in lexical order, removing duplicate words. The output is a list of words separated by single spaces. Thus, $(sort foo bar lose) returns the value `bar foo lose'. Incidentally, since `sort' removes duplicate words, you can use it for this purpose even if you don't care about the sort order. Here is a realistic example of the use of `subst' and `patsubst'. Suppose that a makefile uses the `VPATH' variable to specify a list of directories that `make' should search for dependency files (*note `VPATH' Search Path for All Dependencies: General Search.). This example shows how to tell the C compiler to search for header files in the same list of directories. The value of `VPATH' is a list of directories separated by colons, such as `src:../headers'. First, the `subst' function is used to change the colons to spaces: $(subst :, ,$(VPATH)) This produces `src ../headers'. Then `patsubst' is used to turn each directory name into a `-I' flag. These can be added to the value of the variable `CFLAGS', which is passed automatically to the C compiler, like this: override CFLAGS += $(patsubst %,-I%,$(subst :, ,$(VPATH))) The effect is to append the text `-Isrc -I../headers' to the previously given value of `CFLAGS'. The `override' directive is used so that the new value is assigned even if the previous value of `CFLAGS' was specified with a command argument (*note The `override' Directive: Override Directive.).  File: make.info, Node: File Name Functions, Next: Foreach Function, Prev: Text Functions, Up: Functions Functions for File Names ======================== Several of the built-in expansion functions relate specifically to taking apart file names or lists of file names. Each of the following functions performs a specific transformation on a file name. The argument of the function is regarded as a series of file names, separated by whitespace. (Leading and trailing whitespace is ignored.) Each file name in the series is transformed in the same way and the results are concatenated with single spaces between them. `$(dir NAMES...)' Extracts the directory-part of each file name in NAMES. The directory-part of the file name is everything up through (and including) the last slash in it. If the file name contains no slash, the directory part is the string `./'. For example, $(dir src/foo.c hacks) produces the result `src/ ./'. `$(notdir NAMES...)' Extracts all but the directory-part of each file name in NAMES. If the file name contains no slash, it is left unchanged. Otherwise, everything through the last slash is removed from it. A file name that ends with a slash becomes an empty string. This is unfortunate, because it means that the result does not always have the same number of whitespace-separated file names as the argument had; but we do not see any other valid alternative. For example, $(notdir src/foo.c hacks) produces the result `foo.c hacks'. `$(suffix NAMES...)' Extracts the suffix of each file name in NAMES. If the file name contains a period, the suffix is everything starting with the last period. Otherwise, the suffix is the empty string. This frequently means that the result will be empty when NAMES is not, and if NAMES contains multiple file names, the result may contain fewer file names. For example, $(suffix src/foo.c src-1.0/bar.c hacks) produces the result `.c .c'. `$(basename NAMES...)' Extracts all but the suffix of each file name in NAMES. If the file name contains a period, the basename is everything starting up to (and not including) the last period. Periods in the directory part are ignored. If there is no period, the basename is the entire file name. For example, $(basename src/foo.c src-1.0/bar hacks) produces the result `src/foo src-1.0/bar hacks'. `$(addsuffix SUFFIX,NAMES...)' The argument NAMES is regarded as a series of names, separated by whitespace; SUFFIX is used as a unit. The value of SUFFIX is appended to the end of each individual name and the resulting larger names are concatenated with single spaces between them. For example, $(addsuffix .c,foo bar) produces the result `foo.c bar.c'. `$(addprefix PREFIX,NAMES...)' The argument NAMES is regarded as a series of names, separated by whitespace; PREFIX is used as a unit. The value of PREFIX is prepended to the front of each individual name and the resulting larger names are concatenated with single spaces between them. For example, $(addprefix src/,foo bar) produces the result `src/foo src/bar'. `$(join LIST1,LIST2)' Concatenates the two arguments word by word: the two first words (one from each argument) concatenated form the first word of the result, the two second words form the second word of the result, and so on. So the Nth word of the result comes from the Nth word of each argument. If one argument has more words that the other, the extra words are copied unchanged into the result. For example, `$(join a b,.c .o)' produces `a.c b.o'. Whitespace between the words in the lists is not preserved; it is replaced with a single space. This function can merge the results of the `dir' and `notdir' functions, to produce the original list of files which was given to those two functions. `$(word N,TEXT)' Returns the Nth word of TEXT. The legitimate values of N start from 1. If N is bigger than the number of words in TEXT, the value is empty. For example, $(word 2, foo bar baz) returns `bar'. `$(wordlist S,E,TEXT)' Returns the list of words in TEXT starting with word S and ending with word E (inclusive). The legitimate values of S and E start from 1. If S is bigger than the number of words in TEXT, the value is empty. If E is bigger than the number of words in TEXT, words up to the end of TEXT are returned. If S is greater than E, `make' swaps them for you. For example, $(wordlist 2, 3, foo bar baz) returns `bar baz'. `$(words TEXT)' Returns the number of words in TEXT. Thus, the last word of TEXT is `$(word $(words TEXT),TEXT)'. `$(firstword NAMES...)' The argument NAMES is regarded as a series of names, separated by whitespace. The value is the first name in the series. The rest of the names are ignored. For example, $(firstword foo bar) produces the result `foo'. Although `$(firstword TEXT)' is the same as `$(word 1,TEXT)', the `firstword' function is retained for its simplicity. `$(wildcard PATTERN)' The argument PATTERN is a file name pattern, typically containing wildcard characters (as in shell file name patterns). The result of `wildcard' is a space-separated list of the names of existing files that match the pattern. *Note Using Wildcard Characters in File Names: Wildcards.  File: make.info, Node: Foreach Function, Next: Origin Function, Prev: File Name Functions, Up: Functions The `foreach' Function ====================== The `foreach' function is very different from other functions. It causes one piece of text to be used repeatedly, each time with a different substitution performed on it. It resembles the `for' command in the shell `sh' and the `foreach' command in the C-shell `csh'. The syntax of the `foreach' function is: $(foreach VAR,LIST,TEXT) The first two arguments, VAR and LIST, are expanded before anything else is done; note that the last argument, TEXT, is *not* expanded at the same time. Then for each word of the expanded value of LIST, the variable named by the expanded value of VAR is set to that word, and TEXT is expanded. Presumably TEXT contains references to that variable, so its expansion will be different each time. The result is that TEXT is expanded as many times as there are whitespace-separated words in LIST. The multiple expansions of TEXT are concatenated, with spaces between them, to make the result of `foreach'. This simple example sets the variable `files' to the list of all files in the directories in the list `dirs': dirs := a b c d files := $(foreach dir,$(dirs),$(wildcard $(dir)/*)) Here TEXT is `$(wildcard $(dir)/*)'. The first repetition finds the value `a' for `dir', so it produces the same result as `$(wildcard a/*)'; the second repetition produces the result of `$(wildcard b/*)'; and the third, that of `$(wildcard c/*)'. This example has the same result (except for setting `dirs') as the following example: files := $(wildcard a/* b/* c/* d/*) When TEXT is complicated, you can improve readability by giving it a name, with an additional variable: find_files = $(wildcard $(dir)/*) dirs := a b c d files := $(foreach dir,$(dirs),$(find_files)) 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'. The `foreach' function has no permanent effect on the variable VAR; its value and flavor after the `foreach' function call are the same as they were beforehand. The other values which are taken from LIST are in effect only temporarily, during the execution of `foreach'. The variable VAR is a simply-expanded variable during the execution of `foreach'. If VAR was undefined before the `foreach' function call, it is undefined after the call. *Note The Two Flavors of Variables: Flavors. You must take care when using complex variable expressions that 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)) might be useful if the value of `find_files' references the variable 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: Origin Function, Next: Shell Function, Prev: Foreach Function, Up: Functions 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* a variable. Specifically, it tells you where it came from. The syntax of the `origin' function is: $(origin VARIABLE) 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.) The result of this function is a string telling you how the variable VARIABLE was defined: `undefined' if VARIABLE was never defined. `default' if VARIABLE has a default definition, as is usual with `CC' and so on. *Note Variables Used by Implicit Rules: Implicit Variables. Note that if you have redefined a default variable, the `origin' function will return the origin of the later definition. `environment' if VARIABLE was defined as an environment variable and the `-e' option is *not* turned on (*note Summary of Options: Options Summary.). `environment override' if VARIABLE was defined as an environment variable and the `-e' option *is* turned on (*note Summary of Options: Options Summary.). `file' if VARIABLE was defined in a makefile. `command line' if VARIABLE was defined on the command line. `override' if VARIABLE was defined with an `override' directive in a makefile (*note The `override' Directive: Override Directive.). `automatic' if VARIABLE is an automatic variable defined for the execution of the commands for each rule (*note Automatic Variables: Automatic.). This information is primarily useful (other than for your curiosity) to determine if you want to believe the value of a variable. For example, suppose you have a makefile `foo' that includes another makefile `bar'. You want a variable `bletch' to be defined in `bar' if you run the command `make -f bar', even if the environment contains a definition of `bletch'. However, if `foo' defined `bletch' before including `bar', you do not want to override that definition. This could be done by using an `override' directive in `foo', giving that definition precedence over the later definition in `bar'; unfortunately, the `override' directive would also override any command line definitions. So, `bar' could include: ifdef bletch ifeq "$(origin bletch)" "environment" bletch = barf, gag, etc. endif endif If `bletch' has been defined from the environment, this will redefine it. If you want to override a previous definition of `bletch' if it came from the environment, even under `-e', you could instead write: ifneq "$(findstring environment,$(origin bletch))" "" bletch = barf, gag, etc. endif Here the redefinition takes place if `$(origin bletch)' returns either `environment' or `environment override'. *Note Functions for String Substitution and Analysis: Text Functions.  File: make.info, Node: Shell Function, Prev: Origin Function, Up: Functions The `shell' Function ==================== The `shell' function is unlike any other function except 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 an argument that is a shell command and returns the output of the command. The only processing `make' does on the result, before substituting it into the surrounding text, is to convert each newline or carriage-return / newline pair to a single space. It also removes the trailing (carriage-return and) newline, if it's the last thing in the result. The commands run by calls to the `shell' function are run when the function calls are expanded. In most cases, this is when the makefile is read in. The exception is that function calls in the commands of the rules are expanded when the commands are run, and this applies to `shell' function calls like all others. 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)'.  File: make.info, Node: Running, Next: Implicit Rules, Prev: Functions, Up: Top How to Run `make' ***************** A makefile that says how to recompile a program can be used in more than one way. The simplest use is to recompile every file that is out of date. Usually, makefiles are written so that if you run `make' with no arguments, it does just that. But you might want to update only some of the files; you might want to use a different compiler or different compiler options; you might want just to find out which files are out of date without changing them. By giving arguments when you run `make', you can do any of these things and many others. The exit status of `make' is always one of three values: `0' The exit status is zero if `make' is successful. `2' The exit status is two if `make' encounters any errors. It will print messages describing the particular errors. `1' The exit status is one if you use the `-q' flag and `make' determines that some target is not already up to date. *Note Instead of Executing the Commands: Instead of Execution. * Menu: * Makefile Arguments:: How to specify which makefile to use. * 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 in the makefile other than simply execute them. * Avoiding Compilation:: How to avoid recompiling certain files. * Overriding:: How to override a variable to specify an alternate compiler and other things. * Testing:: How to proceed past some errors, to test compilation. * Options Summary:: Summary of Options  File: make.info, Node: Makefile Arguments, Next: Goals, Up: Running Arguments to Specify the Makefile ================================= The way to specify the name of the makefile is with the `-f' or `--file' option (`--makefile' also works). For example, `-f altmake' says to use the file `altmake' as the makefile. If you use the `-f' flag several times and follow each `-f' with an argument, all the specified files are used jointly as makefiles. If you do not use the `-f' or `--file' flag, the default is to try `GNUmakefile', `makefile', and `Makefile', in that order, and use the first of these three which exists or can be made (*note Writing Makefiles: Makefiles.).