No empty .Rs/.Re

[netbsd-mini2440.git] / gnu / dist / gmake / doc / make.info-4

This is make.info, produced by makeinfo version 4.2 from make.texi.

INFO-DIR-SECTION GNU Packages
START-INFO-DIR-ENTRY
* Make: (make).            Remake files automatically.
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.60, last updated 08 July 2002, of `The GNU Make
Manual', for `make', Version 3.80.

   Copyright 1988, 1989, 1990, 1991, 1992, 1993, 1994, 1995, 1996,
1997, 1998, 1999, 2000, 2002 Free Software Foundation, Inc.

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.  A copy of the license is included in the section entitled "GNU
Free Documentation License".

\x1f
File: make.info,  Node: Sequences,  Next: Empty Commands,  Prev: Recursion,  Up: Commands

Defining Canned Command Sequences
=================================

   When the same sequence of commands is useful in making various
targets, you can define it as a canned sequence with the `define'
directive, and refer to the canned sequence from the rules for those
targets.  The canned sequence is actually a variable, so the name must
not conflict with other variable names.

   Here is an example of defining a canned sequence of commands:

     define run-yacc
     yacc $(firstword $^)
     mv y.tab.c $@
     endef

Here `run-yacc' is the name of the variable being defined; `endef'
marks the end of the definition; the lines in between are the commands.
The `define' directive does not expand variable references and
function calls in the canned sequence; the `$' characters, parentheses,
variable names, and so on, all become part of the value of the variable
you are defining.  *Note Defining Variables Verbatim: Defining, for a
complete explanation of `define'.

   The first command in this example runs Yacc on the first
prerequisite of whichever rule uses the canned sequence.  The output
file from Yacc is always named `y.tab.c'.  The second command moves the
output to the rule's target file name.

   To use the canned sequence, substitute the variable into the
commands of a rule.  You can substitute it like any other variable
(*note Basics of Variable References: Reference.).  Because variables
defined by `define' are recursively expanded variables, all the
variable references you wrote inside the `define' are expanded now.
For example:

     foo.c : foo.y
             $(run-yacc)

`foo.y' will be substituted for the variable `$^' when it occurs in
`run-yacc''s value, and `foo.c' for `$@'.

   This is a realistic example, but this particular one is not needed in
practice because `make' has an implicit rule to figure out these
commands based on the file names involved (*note Using Implicit Rules:
Implicit Rules.).

   In command execution, each line of a canned sequence is treated just
as if the line appeared on its own in the rule, preceded by a tab.  In
particular, `make' invokes a separate subshell for each line.  You can
use the special prefix characters that affect command lines (`@', `-',
and `+') on each line of a canned sequence.  *Note Writing the Commands
in Rules: Commands.  For example, using this canned sequence:

     define frobnicate
     @echo "frobnicating target $@"
     frob-step-1 $< -o $@-step-1
     frob-step-2 $@-step-1 -o $@
     endef

`make' will not echo the first line, the `echo' command.  But it _will_
echo the following two command lines.

   On the other hand, prefix characters on the command line that refers
to a canned sequence apply to every line in the sequence.  So the rule:

     frob.out: frob.in
             @$(frobnicate)

does not echo _any_ commands.  (*Note Command Echoing: Echoing, for a
full explanation of `@'.)

\x1f
File: make.info,  Node: Empty Commands,  Prev: Sequences,  Up: Commands

Using Empty Commands
====================

   It is sometimes useful to define commands which do nothing.  This is
done simply by giving a command that consists of nothing but
whitespace.  For example:

     target: ;

defines an empty command string for `target'.  You could also use a
line beginning with a tab character to define an empty command string,
but this would be confusing because such a line looks empty.

   You may be wondering why you would want to define a command string
that does nothing.  The only reason this is useful is to prevent a
target from getting implicit commands (from implicit rules or the
`.DEFAULT' special target; *note Implicit Rules:: and *note Defining
Last-Resort Default Rules: Last Resort.).

   You may be inclined to define empty command strings for targets that
are not actual files, but only exist so that their prerequisites can be
remade.  However, this is not the best way to do that, because the
prerequisites may not be remade properly if the target file actually
does exist.  *Note Phony Targets: Phony Targets, for a better way to do
this.

\x1f
File: make.info,  Node: Using Variables,  Next: Conditionals,  Prev: Commands,  Up: Top

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

   A "variable" is a name defined in a makefile to represent a string
of text, called the variable's "value".  These values are substituted
by explicit request into targets, prerequisites, commands, and other
parts of the makefile.  (In some other versions of `make', variables
are called "macros".)

   Variables and functions in all parts of a makefile are expanded when
read, except for the shell commands in rules, the right-hand sides of
variable definitions using `=', and the bodies of variable definitions
using the `define' directive.

   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 of characters not containing `:',
`#', `=', or leading or trailing whitespace.  However, variable names
containing characters other than letters, numbers, and underscores
should be avoided, as they may be given special meanings in the future,
and with some shells they cannot be passed through the environment to a
sub-`make' (*note Communicating Variables to a Sub-`make':
Variables/Recursion.).

   Variable names are case-sensitive.  The names `foo', `FOO', and
`Foo' all refer to different variables.

   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 Variables:
Overriding.).

   A few variables have names that are a single punctuation character or
just a few characters.  These are the "automatic variables", and they
have particular specialized uses.  *Note Automatic Variables: Automatic.

* 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.
* Appending::                   How to append more text to the old value
                                  of a variable.
* Override Directive::          How to set 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.
* Target-specific::             Variable values can be defined on a per-target
                                  basis.
* Pattern-specific::            Target-specific variable values can be applied
                                  to a group of targets that match a pattern.

\x1f
File: make.info,  Node: Reference,  Next: Flavors,  Prev: Using Variables,  Up: Using 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,
prerequisites, commands, most directives, and new variable values.
Here is an example of a common case, where a variable holds the names
of all the object files in a program:

     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.$(foo)
             $(foo)$(foo) -$(foo) prog.$(foo)

could be used to compile a C program `prog.c'.  Since spaces before 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 Variables: Automatic.).

\x1f
File: make.info,  Node: Flavors,  Next: Advanced,  Prev: Reference,  Up: Using Variables

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

   There are two ways that a variable in GNU `make' can have a value;
we call them the 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
Variables: Setting.) or by the `define' directive (*note Defining
Variables Verbatim: Defining.).  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
cannot 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 for
Transforming Text: 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 Variables: Setting.).  The value of a simply expanded variable
is scanned once and for all, expanding any references to other
variables and functions, when the variable is defined.  The actual
value of the simply expanded variable is the result of expanding the
text that you write.  It does not contain any references to other
variables; it contains their values _as of the time this variable was
defined_.  Therefore,

     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.

   Here is a somewhat more complicated example, illustrating the use of
`:=' in conjunction with the `shell' function.  (*Note The `shell'
Function: Shell Function.)  This example also shows use of the variable
`MAKELEVEL', which is changed when it is passed down from level to
level.  (*Note Communicating Variables to a Sub-`make':
Variables/Recursion, for information about `MAKELEVEL'.)

     ifeq (0,${MAKELEVEL})
     cur-dir   := $(shell pwd)
     whoami    := $(shell whoami)
     host-type := $(shell arch)
     MAKE := ${MAKE} host-type=${host-type} whoami=${whoami}
     endif

An advantage of this use of `:=' is that a typical `descend into a
directory' command then looks like this:

     ${subdirs}:
           ${MAKE} cur-dir=${cur-dir}/$@ -C $@ all

   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 for Transforming Text: Functions.).

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

     nullstring :=
     space := $(nullstring) # end of the line

Here the value of the variable `space' is precisely one space.  The
comment `# end of the line' is included here just for clarity.  Since
trailing space characters are _not_ stripped from variable values, just
a space at the end of the line would have the same effect (but be
rather hard to read).  If you put whitespace at the end of a variable
value, it is a good idea to put a comment like that at the end of the
line to make your intent clear.  Conversely, if you do _not_ want any
whitespace characters at the end of your variable value, you must
remember not to put a random comment on the end of the line after some
whitespace, such as this:

     dir := /foo/bar    # directory to put the frobs in

Here the value of the variable `dir' is `/foo/bar    ' (with four
trailing spaces), which was probably not the intention.  (Imagine
something like `$(dir)/file' with this definition!)

   There is another assignment operator for variables, `?='.  This is
called a conditional variable assignment operator, because it only has
an effect if the variable is not yet defined.  This statement:

     FOO ?= bar

is exactly equivalent to this (*note The `origin' Function: Origin
Function.):

     ifeq ($(origin FOO), undefined)
       FOO = bar
     endif

   Note that a variable set to an empty value is still defined, so `?='
will not set that variable.

\x1f
File: make.info,  Node: Advanced,  Next: Values,  Prev: Flavors,  Up: Using 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.

\x1f
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 Variables: Setting.

   A substitution reference is actually an abbreviation for use of the
`patsubst' expansion function (*note Functions for String Substitution
and Analysis: Text 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))'.  *Note Functions for
String Substitution and Analysis: Text Functions, for a description of
the `patsubst' function.

For example:

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

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

\x1f
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 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 for Transforming Text:
Functions.), just like any other reference.  For example, using the
`subst' function (*note Functions for String Substitution and Analysis:
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)_objects:.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.

   You can also use computed variable names in the left-hand side of a
variable assignment, or in a `define' directive, as in:

     dir = foo
     $(dir)_sources := $(wildcard $(dir)/*.c)
     define $(dir)_print
     lpr $($(dir)_sources)
     endef

This example defines the variables `dir', `foo_sources', and
`foo_print'.

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

\x1f
File: make.info,  Node: Values,  Next: Setting,  Prev: Advanced,  Up: Using 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 Variables: Overriding.

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

   * Variables in the environment become `make' variables.  *Note
     Variables from the Environment: Environment.

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

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

\x1f
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.).

   If you'd like a variable to be set to a value only if it's not
already set, then you can use the shorthand operator `?=' instead of
`='.  These two settings of the variable `FOO' are identical (*note The
`origin' Function: Origin Function.):

     FOO ?= bar

and

     ifeq ($(origin FOO), undefined)
     FOO = bar
     endif

\x1f
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.

\x1f
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.

\x1f
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
both canned sequences of commands (*note Defining Canned Command
Sequences: Sequences.), and also sections of makefile syntax to use
with `eval' (*note Eval Function::).

   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.

   You may nest `define' directives: `make' will keep track of nested
directives and report an error if they are not all properly closed with
`endef'.  Note that lines beginning with tab characters are considered
part of a command script, so any `define' or `endef' strings appearing
on such a line will not be considered `make' operators.

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

   When used in a command script, 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.

\x1f
File: make.info,  Node: Environment,  Next: Target-specific,  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.)

\x1f
File: make.info,  Node: Target-specific,  Next: Pattern-specific,  Prev: Environment,  Up: Using Variables

Target-specific Variable Values
===============================

   Variable values in `make' are usually global; that is, they are the
same regardless of where they are evaluated (unless they're reset, of
course).  One exception to that is automatic variables (*note Automatic
Variables: Automatic.).

   The other exception is "target-specific variable values".  This
feature allows you to define different values for the same variable,
based on the target that `make' is currently building.  As with
automatic variables, these values are only available within the context
of a target's command script (and in other target-specific assignments).

   Set a target-specific variable value like this:

     TARGET ... : VARIABLE-ASSIGNMENT

or like this:

     TARGET ... : override VARIABLE-ASSIGNMENT

   Multiple TARGET values create a target-specific variable value for
each member of the target list individually.

   The VARIABLE-ASSIGNMENT can be any valid form of assignment;
recursive (`='), static (`:='), appending (`+='), or conditional
(`?=').  All variables that appear within the VARIABLE-ASSIGNMENT are
evaluated within the context of the target: thus, any
previously-defined target-specific variable values will be in effect.
Note that this variable is actually distinct from any "global" value:
the two variables do not have to have the same flavor (recursive vs.
static).

   Target-specific variables have the same priority as any other
makefile variable.  Variables provided on the command-line (and in the
environment if the `-e' option is in force) will take precedence.
Specifying the `override' directive will allow the target-specific
variable value to be preferred.

   There is one more special feature of target-specific variables: when
you define a target-specific variable, that variable value is also in
effect for all prerequisites of this target (unless those prerequisites
override it with their own target-specific variable value).  So, for
example, a statement like this:

     prog : CFLAGS = -g
     prog : prog.o foo.o bar.o

will set `CFLAGS' to `-g' in the command script for `prog', but it will
also set `CFLAGS' to `-g' in the command scripts that create `prog.o',
`foo.o', and `bar.o', and any command scripts which create their
prerequisites.

\x1f
File: make.info,  Node: Pattern-specific,  Prev: Target-specific,  Up: Using Variables

Pattern-specific Variable Values
================================

   In addition to target-specific variable values (*note
Target-specific Variable Values: Target-specific.), GNU `make' supports
pattern-specific variable values.  In this form, a variable is defined
for any target that matches the pattern specified.  Variables defined in
this way are searched after any target-specific variables defined
explicitly for that target, and before target-specific variables defined
for the parent target.

   Set a pattern-specific variable value like this:

     PATTERN ... : VARIABLE-ASSIGNMENT

or like this:

     PATTERN ... : override VARIABLE-ASSIGNMENT

where PATTERN is a %-pattern.  As with target-specific variable values,
multiple PATTERN values create a pattern-specific variable value for
each pattern individually.  The VARIABLE-ASSIGNMENT can be any valid
form of assignment.  Any command-line variable setting will take
precedence, unless `override' is specified.

   For example:

     %.o : CFLAGS = -O

will assign `CFLAGS' the value of `-O' for all targets matching the
pattern `%.o'.

\x1f
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.

\x1f
File: make.info,  Node: Conditional Example,  Next: Conditional Syntax,  Prev: Conditionals,  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)

\x1f
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.  The variable VARIABLE-NAME is itself expanded, so it
     could be a variable or function that expands to the name of a
     variable.

     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.

\x1f
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.

\x1f
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.
* If Function::                 Conditionally expand a value.
* Call Function::               Expand a user-defined function.
* Value Function::              Return the un-expanded value of a variable.
* Eval Function::               Evaluate the arguments as makefile syntax.
* Origin Function::             Find where a variable got its value.
* Shell Function::              Substitute the output of a shell command.
* Make Control Functions::      Functions that control how make runs.