SPACE 2/SPACE - Library 2 - Volume 1.iso/program/318/utilsrc/make-2

Text File | 1988-10-20 | 48.5 KB | 1,204 lines


File: make,  Node: Multiple Targets,  Next: Multiple Rules,  Prev: Special Targets,  Up: Rules

Multiple Targets in a Rule
==========================

A rule with multiple targets is equivalent to writing many rules, each with
one target, and all identical aside from that.  The same commands apply to
all the targets, but their effects may vary because you can substitute the
actual target name into the command using `$@'.  The rule contributes the
same dependencies to all the targets also.

This is useful in two cases.

   * You want just dependencies, no commands.  For example:

          kbd.o commands.o files.o: command.h

     gives an additional dependency to each of the three object files
     mentioned.

   * Similar commands work for all the targets.  The commands do not need
     to be absolutely identical, since the automatic variable `$@' can be
     used to substitute the particular target to be remade into the
     commands (*Note Automatic::.).  For example:

          bigoutput littleoutput : text.g
                  generate text.g -$(subst output,,$@) > $@

     is equivalent to

          bigoutput : text.g
                  generate text.g -big > bigoutput
          littleoutput : text.g
                  generate text.g -little > littleoutput

     Here we assume the hypothetical program `generate' makes two types of
     output, one if given `-big' and one if given `-little'.

Suppose you would like to vary the dependencies according to the target,
much as the variable `$@' allows you to vary the commands.  You cannot do
this with multiple targets in an ordinary rule, but you can do it with a
"static pattern rule".  *note Static Pattern::.


File: make,  Node: Static Pattern,  Next: Multiple Rules,  Prev: Multiple Targets,  Up: Rules

Static Pattern Rules
====================

"Static pattern rules" are rules which specify multiple targets and
construct the dependency names for each target based on the target name.
They are more general than ordinary rules with multiple targets because the
targets don't have to have identical dependencies.  Their dependencies must
be *analogous*, but not necessarily *identical*.

* Menu:

* Usage: Static Usage.    How to use static pattern rules.
* Static vs Implicit::  When are they better than implicit rules?



File: make,  Node: Static Usage,  Next: Static vs Implicit,  Prev: Static Pattern,  Up: Static Pattern

Syntax of Static Pattern Rules
------------------------------

Here is the syntax of a static pattern rule:

     TARGETS: TARGET-PATTERN: DEP-PATTERNS ...
             COMMANDS
             ...

 The TARGETS gives the list of targets that the rule applies to.  The
targets can contain wildcard characters, just like the targets of ordinary
rules (*Note Wildcards::.).

The TARGET-PATTERN and DEP-PATTERNS say how to compute the dependencies of
each target.  Each target is matched against the TARGET-PATTERN to extract
a part of the target name, called the "stem".  This stem is substituted
into each of the DEP-PATTERNS to make the dependency names (one from each
DEP-PATTERN).

Each pattern normally contains the character `%' just once.  When the
TARGET-PATTERN matches a target, the `%' can match any part of the target
name; this part is called the "stem".  The rest of the pattern must match
exactly.  For example, the target `foo.o' matches the pattern `%.o', with
`foo' as the stem.  The targets `foo.c' and `foo.out' don't match that
pattern.

The dependency names for each target are made by substituting the stem for
the `%' in each dependency pattern.  For example, if one dependency pattern
is `%.c', then substitution of the stem `foo' gives the dependency name
`foo.c'.  It is fine to write a dependency pattern that doesn't contain
`%'; then this dependency is the same for all targets.

Here is an example, which compiles each of `foo.o' and `bar.o' from the
corresponding `.c' file:

     objects := foo.o bar.o

     $(objects): %.o: %.c
             $(CC) -c $(CFLAGS) $< -o $@

Each target specified must match the target pattern; a warning is issued
for each that does not.  If you have a list of files, only some of which
will match the pattern, you can use the `filter' function to remove
nonmatching filenames (*Note Text Functions::.):

     files := foo.elc bar.o

     $(filter %.o,$(files)): %.o: %.c
             $(CC) -c $(CFLAGS) $< -o $@
     $(filter %.elc,$(files)): %.elc: %.el
             emacs -f batch-byte-compile $<

Here the result of `$(filter %.o,$(files))' is just `bar.o', and the first
static pattern rule causes it to be made from `bar.c'.  The result of
`$(filter %.elc,$(files))' is `foo.elc', which is made from `foo.el'.


File: make,  Node: Static vs Implicit,  Prev: Static Usage,  Up: Static Pattern

Static Pattern Rules versus Implicit Rules
------------------------------------------

A static pattern rule has much in common with an implicit rule defined as a
pattern rule (*Note Pattern Rules::.).  Both have a pattern for the target
and patterns for constructing the names of dependencies.  The difference is
in how `make' decides *when* the rule applies.

An implicit rule *can* apply to any target that matches its pattern, but it
*does* apply only when the target has no commands otherwise specified, and
only when the dependencies can be found.  If more than one implicit rule
appears applicable, only one applies; the choice depends on the order of
rules.

By contrast, a static pattern rule applies to the precise list of targets
that you specify in the rule.  It cannot apply to any other target and it
invariably does apply to each of the targets specified.  If two conflicting
rules apply, and both have commands, that's an error.

The static pattern rule can be better than an implicit rule for these
reasons:

   * You may wish to override the usual implicit rule for a few files whose
     names cannot be categorized syntactically but can be given in an
     explicit list.

   * If you cannot be sure of the precise contents of the directories you
     are using, you may not be sure which other irrelevant files might lead
     `make' to use the wrong implicit rule.  The choice might depend on the
     order in which the implicit rule search is done.  With static pattern
     rules, there is no uncertainty: each rule applies to precisely the
     targets specified.


File: make,  Node: Multiple Rules,  Next: Double-Colon,  Prev: Static Pattern,  Up: Rules

Multiple Rules for One Target
=============================

One file can be the target of several rules if at most one rule has commands.
 The other rules can only have dependencies.  All the dependencies
mentioned in all the rules are merged into one list of dependencies for the
target.  If the target is older than any dependency from any rule, the
commands are executed.

An extra rule with just dependencies can be used to give a few extra
dependencies to many files at once.  For example, one usually has a
variable named `objects' containing a list of all the compiler output files
in the system being made.  An easy way to say that all of them must be
recompiled if `config.h' changes is to write

     objects = foo.o bar.o
     foo.o : defs.h
     bar.o : defs.h test.h
     $(objects) : config.h

This could be inserted or taken out without changing the rules that really
say how to make the object files, making it a convenient form to use if you
wish to add the additional dependency intermittently.

Another wrinkle is that the additional dependencies could be specified with
a variable that you could set with a command argument to `make' (*Note
Overriding::.).  For example,

     extradeps=
     $(objects) : $(extradeps)

means that the command `make extradeps=foo.h' will consider `foo.h' as a
dependency of each object file, but plain `make' will not.

If none of the explicit rules for a target has commands, then `make'
searches for an applicable implicit rule to find some commands.  *note
Implicit::.


File: make,  Node: Double-Colon,  Prev: Multiple Rules,  Up: Rules

Double-Colon Rules
==================

"Double-colon" rules are rules written with `::' instead of `:' after the
target names.  They are handled differently from ordinary rules when the
same target appears in more than one rule.

When a target appears in multiple rules, all the rules must be the same
type: all ordinary, or all double-colon.  If they are double-colon, each of
them is independent of the others.  Each double-colon rule's commands are
executed if the target is older than any dependencies of that rule.  This
can result in executing none, any or all of the double-colon rules.

The double-colon rules for a target are executed in the order they appear
in the makefile.  However, the cases where double-colon rules really make
sense are those where the order of executing the commands would not matter.

Each double-colon rule should specify commands; if it does not, an implicit
rule will be used if one applies.  *note Implicit::.


File: make,  Node: Commands,  Next: Variables,  Prev: Rules,  Up: Top

Writing the Commands in Rules
*****************************

The commands of a rule consist of shell command lines to be executed one by
one.  Each command line must start with a tab, except that the first
command line may be attached to the target-and-dependencies line with a
semicolon in between.  Blank lines and lines of just comments may appear
among the command lines; they are ignored.

Users use many different shell programs, but commands in makefiles are
always interpreted by `/bin/sh' unless the makefile specifies otherwise.

Whether comments can be written on command lines, and what syntax they use,
is under the control of the shell that is in use.  If it is `/bin/sh', a
`#' at the start of a word starts a comment.

* Menu:

* Echoing::       Normally commands are echoed before execution,
                    but you can control this in several ways.
* Execution::     How commands are executed.
* Errors::      What happens after an error in command execution.
           How to ignore errors in certain commands.
* Interrupts::      If a command is interrupted or killed,
           the target may be deleted.
* Recursion::      Invoking `make' from commands in makefiles.
* Sequences::     Defining canned sequences of commands.



File: make,  Node: Echoing,  Next: Execution,  Prev: Commands,  Up: Commands

Command Echoing
===============

Normally `make' prints each command line before it is executed.  We call
this "echoing" because it gives the appearance that you are typing the
commands yourself.

When a line starts with `@', it is normally not echoed.  The `@' is
discarded before the command is passed to the shell.  Typically you would
use this for a command whose only effect is to print something, such as an
`echo' command.

When `make' is given the flag `-n', echoing is all that happens, no
execution.  *note Options::.  In this case and only this case, even the
commands starting with `@' are printed.  This flag is useful for finding
out which commands `make' thinks are necessary without actually doing them.

The `-s' flag to `make' prevents all echoing, as if all commands started
with `@'.  A rule in the makefile for the special target `.SILENT' has the
same effect (*Note Special Targets::.).  `.SILENT' is essentially obsolete
since `@' is more general.


File: make,  Node: Execution,  Next: Errors,  Prev: Echoing,  Up: Commands

Command Execution
=================

When it is time to execute commands to update a target, they are executed
one at a time by making a new subshell for each line.  (In practice, `make'
may take shortcuts that do not affect the results.)

This implies that shell commands such as `cd' that set variables local to
each process will not affect the following command lines.  If you want to
use `cd' to affect the next command, put the two on a single line with a
semicolon between them.  Then `make' will consider them a single command
and pass them, together, to a shell which will execute them in sequence.
For example:

     foo : bar/lose
             cd bar; gobble lose > ../foo

If you would like to split a single shell command into multiple lines of
text, you must use a backslash at the end of all but the last subline.
Such a sequence of lines is combined into a single line, by deleting the
backslash-newline sequences, before passing it to the shell.  Thus, the
following is equivalent to the preceding example:

     foo : bar/lose
             cd bar;  \
             gobble lose > ../foo

The program used as the shell is taken from the variable `SHELL'.  By
default, the program `/bin/sh' is used.

Unlike most variables, the variable `SHELL' will not be set from the
environment, except in a recursive `make'.  This is because the environment
variable `SHELL' is used to specify your personal choice of shell program
for interactive use.  It would be very bad for personal choices like this
to affect the functioning of makefiles.  *note Environment::.


File: make,  Node: Errors,  Next: Interrupts,  Prev: Execution,  Up: Commands

Errors in Commands
==================

After each shell command returns, `make' looks at its exit status.  If the
command completed successfully, the next command line is executed in a new
shell, or after the last command line the rule is finished.

If there is an error (the exit status is nonzero), `make' gives up on the
current rule, and perhaps on all rules.

Sometimes it does not matter whether a command fails.  For example, you may
use the `mkdir' command to insure that a directory exists.  If the
directory already exists, `mkdir' will report an error, but you probably
want `make' to continue regardless.

To ignore errors in a command line, write a `-' at the beginning of the
line's text (after the initial tab).  The `-' is discarded before the
command is passed to the shell for execution.

When `make' is run with the `-i' flag, errors are ignored in all commands
of all rules.  A rule in the makefile for the special target `.IGNORE' has
the same effect.  These ways of ignoring errors are obsolete because `-' is
more general.

When errors are to be ignored, because of either a `-' or the `-i' flag,
`make' treats an error return just like success.

When an error happens that `make' has not been told to ignore, it implies
that the current target cannot be correctly remade, and neither can any
other that depends on it either directly or indirectly.  No further
commands will be executed for these targets, since their preconditions have
not been achieved.

Normally `make' gives up immediately in this circumstance, returning a
nonzero status.  However, if the `-k' flag is specified, `make' continues
to consider the other dependencies of the pending targets, remaking them if
necessary, before it gives up and returns nonzero status.  For example,
after an error in compiling one object file, `make -k' will continue
compiling other object files even though it already knows that linking them
will be impossible.  *note Options::.

The usual behavior assumes that your purpose is to get the specified
targets up to date; once `make' learns that this is impossible, it might as
well report the failure immediately.  The `-k' option says that the real
purpose is to test as much as possible of the changes made in the program,
perhaps to find several independent problems so that you can correct them
all before the next attempt to compile.  This is why Emacs's `compile'
command passes the `-k' flag by default.


File: make,  Node: Interrupts,  Next: Recursion,  Prev: Errors,  Up: Commands

Interrupting or Killing `make'
==============================

If `make' gets a fatal signal while a command is executing, it may delete
the target file that the command was supposed to update.  This is done if
the target file's last-modification time has changed since `make' first
checked it.

The purpose of deleting the target is to make sure that it is remade from
scratch when `make' is next run.  Otherwise, a partially written file could
appear to be valid, since it is more recent than the dependencies.

You can prevent the deletion of a target file in this way by making the
special target `.PRECIOUS' depend on it.  Before remaking a target, `make'
checks to see whether it appears on the dependencies of `.PRECIOUS', and
thereby decides whether the target should be deleted if a signal happens.
Some reasons why you might do this are that the target is updated in some
atomic fashion or exists only to record a modification-time (its contents
do not matter) or will cause trouble if it ever fails to exist.


File: make,  Node: Recursion,  Next: Sequences,  Prev: Interrupts,  Up: Commands

Recursive Use of `make'
=======================

Recursive use of `make' means using `make' as a command in a makefile.
This technique is useful when you want separate makefiles for various
subsystems that compose a larger system.  For example, suppose you have a
subdirectory `subdir' which has its own makefile, and you would like the
containing directory's makefile to run `make' on the subdirectory.  You can
do it by writing this:

     subsystem:
             cd subdir; $(MAKE)

or, equivalently, this (*Note Options::.):

     subsystem:
             $(MAKE) -c subdir

You can write recursive `make' commands just by copying this example, but
there are many things to know about how they work and why, and about how
the sub-`make' relates to the top-level `make'.

* Menu:

* MAKE Variable::        Special effects of using `$(MAKE)'.
* Variables/Recursion::  How variables are communicated to a sub-`make'.
* Options/Recursion::    How options are communicated to a sub-`make'.
* -w Option::            The `-w' option facilitates debugging
                           makefiles with recursive `make' commands.



File: make,  Node: MAKE Variable,  Next: Variables/Recursion,  Prev: Recursion,  Up: Recursion

How the `MAKE' Variable Works
-----------------------------

Recursive `make' commands should always use the variable `MAKE', not the
explicit command name `make', as shown here:

     subsystem:
             cd subdir; $(MAKE)

The value of this variable is the file name with which `make' was invoked.
If this file name was `/bin/make', then the command executed is `cd subdir;
/bin/make'.  If you use a special version of `make' to run the top-level
makefile, the same special version will be executed for recursive
invocations.

Also, any arguments that define variable values are added to `MAKE', so the
sub-`make' gets them too.  Thus, if you do `make CFLAGS=-O', so that all
C-compilations will be optimized, the sub-`make' is run with `cd subdir;
/bin/make CFLAGS=-O'.

As a special feature, using the variable `MAKE' in the commands of a rule
alters the effects of the `-t', `-n' or `-q' option.  (*note Instead of
Execution::.)

Consider the command `make -t' in the above example.  Following the usual
definition of `-t', this would create a file named `subsystem' and do
nothing else.  What you really want it to do is run `cd subdir; make -t';
but that would require executing the command, and `-t' says not to execute
commands.

The special feature makes this do what you want: whenever a rule's commands
use the variable `MAKE', the flags `-t', `-n' or `-q' do not apply to that
rule.  The commands of that rule are executed normally despite the presence
of a flag that causes most commands not to be run.  The usual `MAKEFLAGS'
mechanism passes the flags to the sub-`make' (*Note Options/Recursion::.),
so your request to touch the files, or print the commands, is propagated to
the subsystem.


File: make,  Node: Variables/Recursion,  Next: Options/Recursion,  Prev: MAKE Variable,  Up: Recursion

Communicating Variables to a Sub-`make'
---------------------------------------

Most variable values of the top-level `make' are passed to the sub-`make'
through the environment.  These variables are defined in the sub-`make' as
defaults, but do not override what is specified in the sub-`make''s
makefile.  (Variables are passed down if their names consist of letters,
numbers and underscores.)

The way this works is that `make' adds each variable and its value to the
environment for running each command.  (Variables whose names start with
non-alphanumeric characters are left out.)  The sub-`make', in turn, uses
the environment to initialize its table of variable values.  *note
Environment::.

As a special feature, the variable `MAKELEVEL' is changed when it is passed
down from level to level.  This variable's value is a string which is the
depth of the level as a decimal number.  The value is `0' for the top-level
`make'; `1' for a sub-`make', `2' for a sub-sub-`make', and so on.  The
incrementation happens when `make' sets up the environment for a command.

The main use of `MAKELEVEL' is to test it in a conditional directive (*Note
Conditionals::.); this way you can write a makefile that behaves one way if
run recursively and another way if run directly by you.

You can use the variable `MAKEFILES' to cause all sub-`make' commands to
use additional makefiles.  The value of `MAKEFILES' is a
whitespace-separated list of filenames.  This variable, if defined in the
outer-level makefile, is passed down through the environment as usual; then
it serves as a list of extra makefiles for the sub-`make' to read before
the usual or specified ones.  *note MAKEFILES Variable::.


File: make,  Node: Options/Recursion,  Next: -w Option,  Prev: Variables/Recursion,  Up: Recursion

Communicating Options to a Sub-`make'
-------------------------------------

Flags such as `-s' and `-k' are passed automatically to the sub-`make'
through the variable `MAKEFLAGS'.  This variable is set up automatically by
`make' to contain the flag letters that `make' received.  Thus, if you do
`make -ks' then `MAKEFLAGS' gets the value `ks'.

As a consequence, every sub-`make' gets a value for `MAKEFLAGS' in its
environment.  In response, it takes the flags from that value and processes
them as if they had been given as arguments.  *note Options::.

The options `-c', `-d', `-f', `-I', `-o', and `-p' are not put into
`MAKEFLAGS'; these options are not passed down.

If you don't want to pass the other the flags down, you must change the
value of `MAKEFLAGS', like this:

     subsystem:
             cd subdir; $(MAKE) MAKEFLAGS=

A similar variable `MFLAGS' exists also, for historical compatibility.  It
has the same value as `MAKEFLAGS' except that a hyphen is added at the
beginning if it is not empty.  `MFLAGS' was traditionally used explicitly
in the recursive `make' command, like this:

     subsystem:
             cd subdir; $(MAKE) $(MFLAGS)

but now `MAKEFLAGS' makes this usage redundant.


File: make,  Node: -w Option,  Prev: Options/Recursion,  Up: Recursion

The `-w' Option
---------------

If you are running `make' over a large directory tree, the `-w' option can
make the output a lot easier to understand by showing each directory as it
is entered and exited.  For example, if `make -w' is run in the directory
`/u/gnu/make', `make' will print a line of the form:

     make: Entering directory `/u/gnu/make'.

 before doing anything else, and a line of this form:

     make: Leaving directory `/u/gnu/make'.

 when processing is completed.


File: make,  Node: Sequences,  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::, for a complete explanation of `define'.

The first command in this example runs Yacc on the first dependency (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 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 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 Implicit::.


File: make,  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 `:', `#',
`=', 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.
* Values::      All the ways variables get their values.
* Flavors::    Variables come in two flavors.
* 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.



File: make,  Node: Reference,  Next: Values,  Prev: Variables,  Up: Variables

Reference to Variables
======================

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

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 with the automatic variables
(*Note Automatic::.).

Modified References
-------------------

In addition to simple references, variables can be referenced in a manner
which modifies the value of the reference but do not modify the value of
the variable referenced.  Such a reference is a "substitution reference".

A "substitution reference" is really a simplified form of the `patsubst'
expansion function (*Note Functions::.).  It has the form `$(var:a=b)' (or
`${var:a=b}') and is equivalent to `$(patsubst %a,%b,$(var))'.  This means
that it replaces every `a' at the end of a whitespace-separated word with a
`b'.  For example:

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

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

Recursive References
--------------------

Variables may be referenced inside a variable reference.  This is called a
"recursive 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'.

Recursive variable references can get yet more recursive.  For example,

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

defines `a' as `Hello': `$($(x))' becomes `$($(y))' which becomes `$(z)'
which becomes `Hello'.  This sort of recursion can go on for as many levels
as you like (and can comprehend), though it's not clear that very many
levels of recursion are useful.

Recursive variable references can also contain modified references and
function invokations (*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 recursive reference as convoluted as this one, but it
works: `$($($(z)))' expands to `$($(y))' which becomes `$($(subst
1,2,$(x)))' which changes `variable1' to `variable2' in `$(x)' and finally
expands to `$(variable2)', a simple variable reference that becomes `Hello'.

Recursive variable references are a complicated concept needed only for
very complex makefile programming.  You need not worry about them in
general, except to know that making a variable with a dollar sign in its
name might have strange results.  Note also that "recursive variable
references" are quite different from "recursive variables" (*Note
Flavors::.), though both are used together in complex ways when doing
makefile programming.


File: make,  Node: Values,  Next: Flavors,  Prev: Reference,  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.
     *note Automatic::.

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


File: make,  Node: Flavors,  Next: Setting,  Prev: Values,  Up: Variables

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

There are two kinds of variables in GNU `make'.  They are distinguished by
two things: how they are defined and how they are 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 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'.  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' function to
give unpredictable results.

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


File: make,  Node: Setting,  Next: Override Directive,  Prev: Flavors,  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'.  Spaces around the variable name are
ignored, and so are spaces after the `=' or at the end of the line.

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


File: make,  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


File: make,  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 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.


File: make,  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.)

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


File: make,  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'.



File: make,  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' not only
changes 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 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.

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, this effect is this:

     foo: $(objects)
             $(CC) -o foo $(objects) $(normal_libs)

Equivalent results can be obtained in another way by conditionalizing a
variable assignment and then using the variable unconditionally:

     libs_for_gcc = -lgnu
     normal_libs =

     ifeq ($(CC),gcc)
       libs=$(libs_for_gcc)
     else
       libs=$(normal_libs)
     endif

     foo: $(objects)
             $(CC) -o foo $(objects) $(libs)


File: make,  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.

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.

You may use an `include' directive within a conditional, but you may not
start a conditional in one file and end it in another.

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


File: make,  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::.


File: make,  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: Function Syntax.  Syntax of function calls in general.
* Text Functions::          Text manipulation functions.
* Foreach Function::        The `foreach' function.
* Filename Functions::      Functions for manipulating file names.


