⟦6cdf91f5e⟧

TextFile

Info file make-info, produced by Makeinfo, -*- Text -*- from input
file make.texinfo.

This file documents the GNU Make utility.

Copyright (C) 1988, 1989 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 also
that the section entitled ``GNU General Public License'' is included
exactly as in the original, and 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 the text of the translations of the section
entitled ``GNU General Public License'' must be approved for accuracy
by the Foundation.


▶1f◀
File: make-info,  Node: Variables,  Next: Conditionals,  Prev: Commands,  Up: Top

How to Use Variables
********************

A "variable" is a name defined within `make' to represent a string of
text, called the variable's "value".  These values can be substituted
by explicit request into targets, dependencies, commands and other
parts of the makefile.

Variables can represent lists of file names, options to pass to
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 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 they are not passed through the environment to a
sub-`make' (*note Variables/Recursion::.).

It is traditional to use upper case letters in variable names, but we
recommend using lower case letters for variable names that serve
internal purposes in the makefile, and reserving upper case for
parameters that control implicit rules or for parameters that the
user should override with command options (*note Overriding::.).

* Menu:

* Reference::   How to use the value of a variable.
* Flavors::     Variables come in two flavors.
* Advanced::    Advanced features for referencing a variable.
* Values::      All the ways variables get their values.
* Setting::     How to set a variable in the makefile.
* Override Directive:: Setting a variable in the makefile
                 even if the user has set it with a command argument.
* Defining::    An alternate way to set a variable to a verbatim string.
* Environment:: Variable values can come from the environment.

 
▶1f◀
File: make-info,  Node: Reference,  Next: Flavors,  Prev: Variables,  Up: Variables

Basics of Variable References
=============================

To substitute a variable's value, write a dollar sign followed by the
name of the variable in parentheses or braces: either `$(foo)' or
`${foo}' is a valid reference to the variable `foo'.  This special
significance of `$' is why you must write `$$' to have the effect of
a single dollar sign in a file name or command.

Variable references can be used in any context: targets,
dependencies, commands, most directives, and new variable values. 
Here is a common kind of example, where a variable holds the names of
all the object files in a program:

     objects = program.o foo.o utils.o
     program : $(objects)
             cc -o program $(objects)
     
     $(objects) : defs.h

Variable references work by strict textual substitution.  Thus, the
rule

     foo = c
     prog.o : prog.c
             $(foo)$(foo) prog.c

could be used to compile a C program `prog.c'.  Since spaces around
the variable value are ignored in variable assignments, the value of
`foo' is precisely `c'.  (Don't actually write your makefiles this
way!)

A dollar sign followed by a character other than a dollar sign,
open-parenthesis or open-brace treats that single character as the
variable name.  Thus, you could reference the variable `x' with `$x'.
However, this practice is strongly discouraged, except in the case of
the automatic variables (*note Automatic::.).


▶1f◀
File: make-info,  Node: Flavors,  Next: Advanced,  Prev: Reference,  Up: Variables

The Two Flavors of Variables
============================

There are two ways that a variables in GNU `make' can have a value;
we call them two "flavors" of variables.  The two flavors are
distinguished in how they are defined and in what they do when
expanded.

The first flavor of variable is a "recursively expanded" variable. 
Variables of this sort are defined by lines using `=' (*note
Setting::.).  The value you specify is installed verbatim; if it
contains references to other variables, these references are expanded
whenever this variable is substituted (in the course of expanding
some other string).  When this happens, it is called "recursive
expansion".

For example,

     foo = $(bar)
     bar = $(ugh)
     ugh = Huh?
     
     all:;echo $(foo)

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:

     CFLAGS = $(include_dirs) -O
     include_dirs = -Ifoo -Ibar

will do what was intended: when `CFLAGS' is expanded in a command, it
will expand to `-Ifoo -Ibar -O'.  A major disadvantage is that you
can't append something on the end of a variable, as in

     CFLAGS = $(CFLAGS) -O

because it will cause an infinite loop in the variable expansion. 
(Actually `make' detects the infinite loop and reports an error.)

Another disadvantage is that any functions (*note Functions::.)
referenced in the definition will be executed every time the variable
is expanded.  This makes `make' run slower; worse, it causes the
`wildcard' and `shell' functions to give unpredictable results
because you cannot easily control when they are 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::.).  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
     x := later

is equivalent to

     y := foo bar
     x := later

When a simply expanded variable is referenced, its value is
substituted verbatim.

Simply expanded variables generally make complicated makefile
programming more predictable because they work like variables in most
programming languages.  They allow you to redefine a variable using
its own value (or its value processed in some way by one of the
expansion functions) and to use the expansion functions much more
efficiently (*note Functions::.).

You can also use them to introduce controlled leading or trailing
spaces into variable values.  Such spaces are discarded from your
input before substitution of variable references and function calls;
this means you can include leading or trailing spaces in a variable
value by protecting them with variable references, like this:

     nullstring :=
     space := $(nullstring) $(nullstring)

Here the value of the variable `space' is precisely one space.


▶1f◀
File: make-info,  Node: Advanced,  Next: Values,  Prev: Flavors,  Up: Variables

Advanced Features for Reference to Variables
============================================

This section describes some advanced features you can use to
reference variables in more flexible ways.

* Menu:

* Substitution Refs::   Referencing a variable with substitutions on the value.
* Computed Names::      Computing the name of the variable to refer to.

 
▶1f◀
File: make-info,  Node: Substitution Refs,  Next: Computed Names,  Prev: Advanced,  Up: Advanced

Substitution References
-----------------------

A "substitution reference" substitutes the value of a variable with
alterations that you specify.  It has the form `$(VAR:A=B)' (or
`${VAR:A=B}') and its meaning is to take the value of the variable
VAR, replace every A at the end of a word with B in that value, and
substitute the resulting string.

When we say ``at the end of a word'', we mean that A must appear
either followed by whitespace or at the end of the value in order to
be replaced; other occurrences of A in the value are unaltered.  For
example:

     foo := a.o b.o c.o
     bar := $(foo:.o=.c)

sets `bar' to `a.c b.c c.c'.  *Note Setting::.

A substitution reference is actually an abbreviation for use of the
`patsubst' expansion function (*note Functions::.).  We provide
substitution references as well as `patsubst' for compatibility with
other implementations of `make'.

Another type of substitution reference lets you use the full power of
the `patsubst' function.  It has the same form `$(VAR:A=B)' described
above, except that now A must contain a single `%' character.  This
case is equivalent to `$(patsubst A,B,$(VAR))'.  For example:

     foo := a.o b.o c.o
     bar := $(foo:%.o=%.c)

sets `bar' to `a.c b.c c.c'.


▶1f◀
File: make-info,  Node: Computed Names,  Prev: Substitution Refs,  Up: Advanced

Computed Variable Names
-----------------------

Computed variable names are a complicated concept needed only for
sophisticated makefile programming.  For most purposes you need not
consider about them, except to know that making a variable with a
dollar sign in its name might have strange results.  However, if you
are the type that wants to understand everything, or you are actually
interested in what they do, read on.

Variables may be referenced inside the name of a variable.  This is
called a "computed variable name" or a "nested variable reference". 
For example,

     x = y
     y = z
     a := $($(x))

defines `a' as `z': the `$(x)' inside `$($(x))' expands to `y', so
`$($(x))' expands to `$(y)' which in turn expands to `z'.  Here the
name of the variable to reference is not stated explicitly; it is
computed by expansion of `$(x)'.  The reference `$(x)' here is nested
within the outer variable reference.

The previous example shows two levels of nesting, but any number of
levels is possible.  For example, here are three levels:

     x = y
     y = z
     z = u
     a := $($($(x)))

Here the innermost `$(x)' expands to `y', so `$($(x))' expands to
`$(y)' which in turn expands to `z'; now we have `$(z)', which
becomes `u'.

References to recursively-expanded variables within a variable name
are reexpanded in the usual fashion.  For example:

     x = $(y)
     y = z
     z = Hello
     a := $($(x))

defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes
`$(z)' which becomes `Hello'.

Nested variable references can also contain modified references and
function invocations (*note Functions::.), just like any other
reference.  For example, using the `subst' function (*note Text
Functions::.):

     x = variable1
     variable2 := Hello
     y = $(subst 1,2,$(x))
     z = y
     a := $($($(z)))

eventually defines `a' as `Hello'.  It is doubtful that anyone would
ever want to write a nested reference as convoluted as this one, but
it works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst
1,2,$(x)))'.  This gets the value `variable1' from `x' and changes it
by substitution to `variable2', so that the entire string becomes
`$(variable2)', a simple variable reference whose value is `Hello'.

A computed variable name need not consist entirely of a single
variable reference.  It can contain several variable references, as
well as some invariant text.  For example,

     a_dirs := dira dirb
     1_dirs := dir1 dir2
     
     a_files := filea fileb
     1_files := file1 file2
     
     ifeq "$(use_a)" "yes"
     a1 := a
     else
     a1 := 1
     endif
     
     ifeq "$(use_dirs)" "yes"
     df := dirs
     else
     df := files
     endif
     
     dirs := $($(a1)_$(df))

will give `dirs' the same value as `a_dirs', `1_dirs', `a_files' or
`1_files' depending on the settings of `use_a' and `use_dirs'.

Computed variable names can also be used in substitution references:

     a_objects := a.o b.o c.o
     1_objects := 1.o 2.o 3.o
     
     sources := $($(a1)_object:.o=.c)

defines `sources' as either `a.c b.c c.c' or `1.c 2.c 3.c', depending
on the value of `a1'.

The only restriction on this sort of use of nested variable
references is that they cannot specify part of the name of a function
to be called.  This is because the test for a recognized function
name is done before the expansion of nested references.  For example,

     ifdef do_sort
     func := sort
     else
     func := strip
     endif
     
     bar := a d b g q c
     
     foo := $($(func) $(bar))

attempts to give `foo' the value of the variable `sort a d b g q c'
or `strip a d b g q c', rather than giving `a d b g q c' as the
argument to either the `sort' or the `strip' function.  This
restriction could be removed in the future if that change is shown to
be a good idea.

Note that "nested variable references" are quite different from
"recursively expanded variables" (*note Flavors::.), though both are
used together in complex ways when doing makefile programming.


▶1f◀
File: make-info,  Node: Values,  Next: Setting,  Prev: Advanced,  Up: Variables

How Variables Get Their Values
==============================

Variables can get values in several different ways:

   * You can specify an overriding value when you run `make'.  *Note
     Overriding::.

   * You can specify a value in the makefile, either with an
     assignment (*note Setting::.) or with a verbatim definition
     (*note Defining::.).

   * Values are inherited from the environment.  *Note Environment::.

   * Several "automatic" variables are given new values for each rule.
     Each of these has a single conventional use.  *Note Automatic::.

   * Several variables have constant initial values.  *Note Implicit
     Variables::.


▶1f◀
File: make-info,  Node: Setting,  Next: Override Directive,  Prev: Values,  Up: 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 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 Flavors::.

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 can be set by you in the usual
ways (*note Implicit Variables::.).  Several special variables are
set automatically to a new value for each rule; these are called the
"automatic" variables (*note Automatic::.).


▶1f◀
File: make-info,  Node: Override Directive,  Next: Defining,  Prev: Setting,  Up: Variables

The `override' Directive
========================

If a variable has been set with a command argument (*note
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

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 := $(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::.


▶1f◀
File: make-info,  Node: Defining,  Next: Environment,  Prev: Override Directive,  Up: Variables

Defining Variables Verbatim
===========================

Another way to set the value of a variable is to use the `define'
directive.  This directive has a different syntax which allows
newline characters to be included in the value, which is convenient
for defining canned sequences of commands (*note 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 Flavors::.).

     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 the shell will interpret the semicolon and the newline
identically.

If you want variable definitions made with `define' to take
precedence over command-line variable definitions, the `override'
directive can be used together with `define':

     override define two-lines
     foo
     $(bar)
     endef

*Note Override Directive::.


▶1f◀
File: make-info,  Node: Environment,  Prev: Defining,  Up: Variables

Variables from the Environment
==============================

Variables in `make' can come from the environment with 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 Options::.  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 are automatically passed to inner invocations through the
environment (*note Recursion::.).  This is the main purpose of
turning environment variables into `make' variables, and it requires
no attention from you.

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' if the value of `MAKELEVEL' is zero (which is normally true
except in recursive invocations of `make').


▶1f◀
File: make-info,  Node: Conditionals,  Next: Functions,  Prev: 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 with another, or the value of a variable with 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:

* Example: Conditional Example.   An annotated example.
* Syntax: Conditional Syntax.     Precise rules for syntax of conditionals.
* Flags: Testing Flags.           Conditionals testing flags such as `-t'.

 
▶1f◀
File: make-info,  Node: Conditional Example,  Next: Conditional Syntax,  Prev: Conditionals,  Up: Conditionals

Example of a Conditional
========================

This 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.

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)


▶1f◀
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.

`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.

`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 work at the textual level.  The lines of the
TEXT-IF-TRUE are read as part of the makefile if the condition is
true; if the condition is false, those lines are ignored 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.

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.


▶1f◀
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.  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)))
             @echo $(MAKE) > /dev/null
             touch archive.a
             ranlib -t archive.a
     else
             ranlib archive.a
     endif

The `echo' command does nothing when executed; but its presence, with
a reference to the variable `MAKE', marks the rule as ``recursive''
so that its commands will be executed despite use of the `-t' flag. 
*Note Recursion::.


▶1f◀
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.
* Filename 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.

 
▶1f◀
File: make-info,  Node: Syntax of Functions,  Next: Text Functions,  Prev: 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 and/or tabs, and if
there is more than one argument they are separated by commas.  Such
whitespace and commas are not part of any 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; in other words, write `$(subst a,b,$(x))', not
`$(subst a,b,${x})'.

The text written for each argument is processed by substitution of
variables and function calls in order to produce the argument value,
which is the text on which the function acts.

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 those variables where such characters are
wanted, like this:

     comma:= ,
     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.


▶1f◀
File: make-info,  Node: Text Functions,  Next: Filename 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 can't
     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'.

`$(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'.

`$(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 `', respectively.  *Note Testing
     Flags::, for a practical application of `findstring'.

`$(filter PATTERN,TEXT)'
     Removes all whitespace-separated words in TEXT that do *not*
     match PATTERN, returning only matching words.  The pattern is
     written using `%', just like the patterns used in `patsubst'
     function above.

     The `filter' function can be used to separate out different
     types of strings (such as filenames) in a variable.  For example:

          sources := foo.c bar.c ugh.h
          foo: $(sources)
                  cc $(filter %.c,$(sources)) -o foo

     says that `foo' depends of `foo.c', `bar.c' and `ugh.h' but only
     `foo.c' and `bar.c' should be specified in the command to the
     compiler.

`$(filter-out PATTERN,TEXT)'
     Removes all whitespace-separated words in TEXT that *do* match
     PATTERN, returning only the words that match.  This is the exact
     opposite of the `filter' function.

`$(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'.

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.  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:= $(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 Override
Directive::.).

The function `strip' can be very useful when used in conjunction with
conditionals.  When comparing something with the null string `""'
using `ifeq' or `ifneq', you usually want a string of just whitespace
to match the null string.  Thus,

     .PHONY: all
     ifneq   "$(needs_made)" ""
     all: $(needs_made)
     else
     all:;@echo 'Nothing to make!'
     endif

might fail to have the desired results.  Replacing the variable
reference `"$(needs_made)"' with the function call `"$(strip
$(needs_made))"' in the `ifneq' directive would make it more robust.


▶1f◀
File: make-info,  Node: Filename 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 hacks)

     produces the result `.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.  Otherwise, the
     basename is the entire file name.  For example,

          $(basename src/foo.c hacks)

     produces the result `src/foo 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
     appended 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'.

`$(words TEXT)'
     Returns the number of words in TEXT.  Thus, `$(word $(words
     TEXT),TEXT)' is the last word of 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.  The result of `wildcard' is a
     space-separated list of the names of existing files that match
     the pattern.

     Wildcards are expanded automatically in rules.  *Note Wildcards::.
     But they are not normally expanded when a variable is set, or
     inside the arguments of other functions.  Those occasions are
     when the `wildcard' function is useful.


▶1f◀
File: make-info,  Node: Foreach Function,  Next: Origin Function,  Prev: Filename 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 `find_files',
`dirs' and `dir') 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 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 Es escrito en espanol!,b c ch,$(find_files))

might be useful if the value of `find_files' references the variable
whose name is `Es escrito en espanol!' (es un nombre bastante largo,
que no?), but it is more likely to be a mistake.


▶1f◀
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 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 Options::.).

`environment override'
     if VARIABLE was defined as an environment variable and the `-e'
     option *is* turned on (*note Options::.).

`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 Override Directive::.).

`automatic'
     if VARIABLE is an automatic variable defined for the execution
     of the commands for each rule.

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 don't 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'.


▶1f◀
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 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
newlines to spaces.

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)'.


▶1f◀
File: make-info,  Node: Running,  Next: Implicit,  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.  This is what `make' will do if run with no arguments.

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 specifying arguments when you run `make', you can do any of these
things or many others.

* Menu:

* Makefile Arguments::    Arguments to specify which makefile to use.

* Goals::                 Goal arguments specify which parts of the makefile
                           should be used.

* Instead of Execution::  Mode flags 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::            Overriding a variable can specify an alternate
                           compiler, or alternate flags for the compiler,
                           or whatever else you program into the makefile.

* Testing::               How to proceed past some errors, to test compilation.

* Options::               Summary of all options `make' accepts.
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦6cdf91f5e⟧ TextFile

Derivation

TextFile
