make.info-6   [plain text]


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


File: make.info,  Node: Options Summary,  Prev: Testing,  Up: Running

Summary of Options
==================

   Here is a table of all the options `make' understands:

`-b'
`-m'
     These options are ignored for compatibility with other versions of
     `make'.

`-B'
`--always-make'
     Consider all targets out-of-date.  GNU `make' proceeds to consider
     targets and their prerequisites using the normal algorithms;
     however, all these targets are remade, regardless of the status of
     their prerequisites.

`-C DIR'
`--directory=DIR'
     Change to directory DIR before reading the makefiles.  If multiple
     `-C' options are specified, each is interpreted relative to the
     previous one: `-C / -C etc' is equivalent to `-C /etc'.  This is
     typically used with recursive invocations of `make' (*note
     Recursive Use of `make': Recursion.).

`-d'
     Print debugging information in addition to normal processing.  The
     debugging information says which files are being considered for
     remaking, which file-times are being compared and with what
     results, which files actually need to be remade, which implicit
     rules are considered and which are applied--everything interesting
     about how `make' decides what to do.  The `-d' option is
     equivalent to `--debug=a' (see below).

`--debug[=OPTIONS]'
     Print debugging information in addition to normal processing.
     Various levels and types of output can be chosen.  With no
     arguments, print the "basic" level of debugging.  Possible
     arguments are below; only the first character is considered, and
     values must be comma- or space-separated.

    `a (all)'
          All types of debugging output are enabled.  This is
          equivalent to using `-d'.

    `b (basic)'
          Basic debugging prints each target that was found to be
          out-of-date, and whether the build was successful or not.

    `v (verbose)'
          A level above `basic'; includes messages about which
          makefiles were parsed, prerequisites that did not need to be
          rebuilt, etc.  This option also enables `basic' messages.

    `i (implicit)'
          Prints messages describing the implicit rule searches for
          each target.  This option also enables `basic' messages.

    `j (jobs)'
          Prints messages giving details on the invocation of specific
          subcommands.

    `m (makefile)'
          By default, the above messages are not enabled while trying
          to remake the makefiles.  This option enables messages while
          rebuilding makefiles, too.  Note that the `all' option does
          enable this option.  This option also enables `basic'
          messages.

`-e'
`--environment-overrides'
     Give variables taken from the environment precedence over
     variables from makefiles.  *Note Variables from the Environment:
     Environment.

`-f FILE'
`--file=FILE'
`--makefile=FILE'
     Read the file named FILE as a makefile.  *Note Writing Makefiles:
     Makefiles.

`-h'
`--help'
     Remind you of the options that `make' understands and then exit.

`-i'
`--ignore-errors'
     Ignore all errors in commands executed to remake files.  *Note
     Errors in Commands: Errors.

`-I DIR'
`--include-dir=DIR'
     Specifies a directory DIR to search for included makefiles.  *Note
     Including Other Makefiles: Include.  If several `-I' options are
     used to specify several directories, the directories are searched
     in the order specified.

`-j [JOBS]'
`--jobs[=JOBS]'
     Specifies the number of jobs (commands) to run simultaneously.
     With no argument, `make' runs as many jobs simultaneously as
     possible.  If there is more than one `-j' option, the last one is
     effective.  *Note Parallel Execution: Parallel, for more
     information on how commands are run.  Note that this option is
     ignored on MS-DOS.

`-k'
`--keep-going'
     Continue as much as possible after an error.  While the target that
     failed, and those that depend on it, cannot be remade, the other
     prerequisites of these targets can be processed all the same.
     *Note Testing the Compilation of a Program: Testing.

`-l [LOAD]'
`--load-average[=LOAD]'
`--max-load[=LOAD]'
     Specifies that no new jobs (commands) should be started if there
     are other jobs running and the load average is at least LOAD (a
     floating-point number).  With no argument, removes a previous load
     limit.  *Note Parallel Execution: Parallel.

`-n'
`--just-print'
`--dry-run'
`--recon'
     Print the commands that would be executed, but do not execute them.
     *Note Instead of Executing the Commands: Instead of Execution.

`-o FILE'
`--old-file=FILE'
`--assume-old=FILE'
     Do not remake the file FILE even if it is older than its
     prerequisites, and do not remake anything on account of changes in
     FILE.  Essentially the file is treated as very old and its rules
     are ignored.  *Note Avoiding Recompilation of Some Files: Avoiding
     Compilation.

`-p'
`--print-data-base'
     Print the data base (rules and variable values) that results from
     reading the makefiles; then execute as usual or as otherwise
     specified.  This also prints the version information given by the
     `-v' switch (see below).  To print the data base without trying to
     remake any files, use `make -qp'.  To print the data base of
     predefined rules and variables, use `make -p -f /dev/null'.  The
     data base output contains filename and linenumber information for
     command and variable definitions, so it can be a useful debugging
     tool in complex environments.

`-q'
`--question'
     "Question mode".  Do not run any commands, or print anything; just
     return an exit status that is zero if the specified targets are
     already up to date, one if any remaking is required, or two if an
     error is encountered.  *Note Instead of Executing the Commands:
     Instead of Execution.

`-r'
`--no-builtin-rules'
     Eliminate use of the built-in implicit rules (*note Using Implicit
     Rules: Implicit Rules.).  You can still define your own by writing
     pattern rules (*note Defining and Redefining Pattern Rules:
     Pattern Rules.).  The `-r' option also clears out the default list
     of suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
     Suffix Rules.).  But you can still define your own suffixes with a
     rule for `.SUFFIXES', and then define your own suffix rules.  Note
     that only _rules_ are affected by the `-r' option; default
     variables remain in effect (*note Variables Used by Implicit
     Rules: Implicit Variables.); see the `-R' option below.

`-R'
`--no-builtin-variables'
     Eliminate use of the built-in rule-specific variables (*note
     Variables Used by Implicit Rules: Implicit Variables.).  You can
     still define your own, of course.  The `-R' option also
     automatically enables the `-r' option (see above), since it
     doesn't make sense to have implicit rules without any definitions
     for the variables that they use.

`-s'
`--silent'
`--quiet'
     Silent operation; do not print the commands as they are executed.
     *Note Command Echoing: Echoing.

`-S'
`--no-keep-going'
`--stop'
     Cancel the effect of the `-k' option.  This is never necessary
     except in a recursive `make' where `-k' might be inherited from
     the top-level `make' via `MAKEFLAGS' (*note Recursive Use of
     `make': Recursion.)  or if you set `-k' in `MAKEFLAGS' in your
     environment.

`-t'
`--touch'
     Touch files (mark them up to date without really changing them)
     instead of running their commands.  This is used to pretend that
     the commands were done, in order to fool future invocations of
     `make'.  *Note Instead of Executing the Commands: Instead of
     Execution.

`-v'
`--version'
     Print the version of the `make' program plus a copyright, a list
     of authors, and a notice that there is no warranty; then exit.

`-w'
`--print-directory'
     Print a message containing the working directory both before and
     after executing the makefile.  This may be useful for tracking
     down errors from complicated nests of recursive `make' commands.
     *Note Recursive Use of `make': Recursion.  (In practice, you
     rarely need to specify this option since `make' does it for you;
     see *Note The `--print-directory' Option: -w Option.)

`--no-print-directory'
     Disable printing of the working directory under `-w'.  This option
     is useful when `-w' is turned on automatically, but you do not
     want to see the extra messages.  *Note The `--print-directory'
     Option: -w Option.

`-W FILE'
`--what-if=FILE'
`--new-file=FILE'
`--assume-new=FILE'
     Pretend that the target FILE has just been modified.  When used
     with the `-n' flag, this shows you what would happen if you were
     to modify that file.  Without `-n', it is almost the same as
     running a `touch' command on the given file before running `make',
     except that the modification time is changed only in the
     imagination of `make'.  *Note Instead of Executing the Commands:
     Instead of Execution.

`--warn-undefined-variables'
     Issue a warning message whenever `make' sees a reference to an
     undefined variable.  This can be helpful when you are trying to
     debug makefiles which use variables in complex ways.


File: make.info,  Node: Implicit Rules,  Next: Archives,  Prev: Running,  Up: Top

Using Implicit Rules
********************

   Certain standard ways of remaking target files are used very often.
For example, one customary way to make an object file is from a C
source file using the C compiler, `cc'.

   "Implicit rules" tell `make' how to use customary techniques so that
you do not have to specify them in detail when you want to use them.
For example, there is an implicit rule for C compilation.  File names
determine which implicit rules are run.  For example, C compilation
typically takes a `.c' file and makes a `.o' file.  So `make' applies
the implicit rule for C compilation when it sees this combination of
file name endings.

   A chain of implicit rules can apply in sequence; for example, `make'
will remake a `.o' file from a `.y' file by way of a `.c' file.

   The built-in implicit rules use several variables in their commands
so that, by changing the values of the variables, you can change the
way the implicit rule works.  For example, the variable `CFLAGS'
controls the flags given to the C compiler by the implicit rule for C
compilation.

   You can define your own implicit rules by writing "pattern rules".

   "Suffix rules" are a more limited way to define implicit rules.
Pattern rules are more general and clearer, but suffix rules are
retained for compatibility.

* Menu:

* Using Implicit::              How to use an existing implicit rule
                                  to get the commands for updating a file.
* Catalogue of Rules::          A list of built-in implicit rules.
* Implicit Variables::          How to change what predefined rules do.
* Chained Rules::               How to use a chain of implicit rules.
* Pattern Rules::               How to define new implicit rules.
* Last Resort::                 How to defining commands for rules
                                  which cannot find any.
* Suffix Rules::                The old-fashioned style of implicit rule.
* Implicit Rule Search::        The precise algorithm for applying
                                  implicit rules.


File: make.info,  Node: Using Implicit,  Next: Catalogue of Rules,  Prev: Implicit Rules,  Up: Implicit Rules

Using Implicit Rules
====================

   To allow `make' to find a customary method for updating a target
file, all you have to do is refrain from specifying commands yourself.
Either write a rule with no command lines, or don't write a rule at
all.  Then `make' will figure out which implicit rule to use based on
which kind of source file exists or can be made.

   For example, suppose the makefile looks like this:

     foo : foo.o bar.o
             cc -o foo foo.o bar.o $(CFLAGS) $(LDFLAGS)

Because you mention `foo.o' but do not give a rule for it, `make' will
automatically look for an implicit rule that tells how to update it.
This happens whether or not the file `foo.o' currently exists.

   If an implicit rule is found, it can supply both commands and one or
more prerequisites (the source files).  You would want to write a rule
for `foo.o' with no command lines if you need to specify additional
prerequisites, such as header files, that the implicit rule cannot
supply.

   Each implicit rule has a target pattern and prerequisite patterns.
There may be many implicit rules with the same target pattern.  For
example, numerous rules make `.o' files: one, from a `.c' file with the
C compiler; another, from a `.p' file with the Pascal compiler; and so
on.  The rule that actually applies is the one whose prerequisites
exist or can be made.  So, if you have a file `foo.c', `make' will run
the C compiler; otherwise, if you have a file `foo.p', `make' will run
the Pascal compiler; and so on.

   Of course, when you write the makefile, you know which implicit rule
you want `make' to use, and you know it will choose that one because you
know which possible prerequisite files are supposed to exist.  *Note
Catalogue of Implicit Rules: Catalogue of Rules, for a catalogue of all
the predefined implicit rules.

   Above, we said an implicit rule applies if the required
prerequisites "exist or can be made".  A file "can be made" if it is
mentioned explicitly in the makefile as a target or a prerequisite, or
if an implicit rule can be recursively found for how to make it.  When
an implicit prerequisite is the result of another implicit rule, we say
that "chaining" is occurring.  *Note Chains of Implicit Rules: Chained
Rules.

   In general, `make' searches for an implicit rule for each target, and
for each double-colon rule, that has no commands.  A file that is
mentioned only as a prerequisite is considered a target whose rule
specifies nothing, so implicit rule search happens for it.  *Note
Implicit Rule Search Algorithm: Implicit Rule Search, for the details
of how the search is done.

   Note that explicit prerequisites do not influence implicit rule
search.  For example, consider this explicit rule:

     foo.o: foo.p

The prerequisite on `foo.p' does not necessarily mean that `make' will
remake `foo.o' according to the implicit rule to make an object file, a
`.o' file, from a Pascal source file, a `.p' file.  For example, if
`foo.c' also exists, the implicit rule to make an object file from a C
source file is used instead, because it appears before the Pascal rule
in the list of predefined implicit rules (*note Catalogue of Implicit
Rules: Catalogue of Rules.).

   If you do not want an implicit rule to be used for a target that has
no commands, you can give that target empty commands by writing a
semicolon (*note Defining Empty Commands: Empty Commands.).


File: make.info,  Node: Catalogue of Rules,  Next: Implicit Variables,  Prev: Using Implicit,  Up: Implicit Rules

Catalogue of Implicit Rules
===========================

   Here is a catalogue of predefined implicit rules which are always
available unless the makefile explicitly overrides or cancels them.
*Note Canceling Implicit Rules: Canceling Rules, for information on
canceling or overriding an implicit rule.  The `-r' or
`--no-builtin-rules' option cancels all predefined rules.

   Not all of these rules will always be defined, even when the `-r'
option is not given.  Many of the predefined implicit rules are
implemented in `make' as suffix rules, so which ones will be defined
depends on the "suffix list" (the list of prerequisites of the special
target `.SUFFIXES').  The default suffix list is: `.out', `.a', `.ln',
`.o', `.c', `.cc', `.C', `.p', `.f', `.F', `.r', `.y', `.l', `.s',
`.S', `.mod', `.sym', `.def', `.h', `.info', `.dvi', `.tex', `.texinfo',
`.texi', `.txinfo', `.w', `.ch' `.web', `.sh', `.elc', `.el'.  All of
the implicit rules described below whose prerequisites have one of
these suffixes are actually suffix rules.  If you modify the suffix
list, the only predefined suffix rules in effect will be those named by
one or two of the suffixes that are on the list you specify; rules
whose suffixes fail to be on the list are disabled.  *Note
Old-Fashioned Suffix Rules: Suffix Rules, for full details on suffix
rules.

Compiling C programs
     `N.o' is made automatically from `N.c' with a command of the form
     `$(CC) -c $(CPPFLAGS) $(CFLAGS)'.

Compiling C++ programs
     `N.o' is made automatically from `N.cc' or `N.C' with a command of
     the form `$(CXX) -c $(CPPFLAGS) $(CXXFLAGS)'.  We encourage you to
     use the suffix `.cc' for C++ source files instead of `.C'.

Compiling Pascal programs
     `N.o' is made automatically from `N.p' with the command `$(PC) -c
     $(PFLAGS)'.

Compiling Fortran and Ratfor programs
     `N.o' is made automatically from `N.r', `N.F' or `N.f' by running
     the Fortran compiler.  The precise command used is as follows:

    `.f'
          `$(FC) -c $(FFLAGS)'.

    `.F'
          `$(FC) -c $(FFLAGS) $(CPPFLAGS)'.

    `.r'
          `$(FC) -c $(FFLAGS) $(RFLAGS)'.

Preprocessing Fortran and Ratfor programs
     `N.f' is made automatically from `N.r' or `N.F'.  This rule runs
     just the preprocessor to convert a Ratfor or preprocessable
     Fortran program into a strict Fortran program.  The precise
     command used is as follows:

    `.F'
          `$(FC) -F $(CPPFLAGS) $(FFLAGS)'.

    `.r'
          `$(FC) -F $(FFLAGS) $(RFLAGS)'.

Compiling Modula-2 programs
     `N.sym' is made from `N.def' with a command of the form `$(M2C)
     $(M2FLAGS) $(DEFFLAGS)'.  `N.o' is made from `N.mod'; the form is:
     `$(M2C) $(M2FLAGS) $(MODFLAGS)'.

Assembling and preprocessing assembler programs
     `N.o' is made automatically from `N.s' by running the assembler,
     `as'.  The precise command is `$(AS) $(ASFLAGS)'.

     `N.s' is made automatically from `N.S' by running the C
     preprocessor, `cpp'.  The precise command is `$(CPP) $(CPPFLAGS)'.

Linking a single object file
     `N' is made automatically from `N.o' by running the linker
     (usually called `ld') via the C compiler.  The precise command
     used is `$(CC) $(LDFLAGS) N.o $(LOADLIBES) $(LDLIBS)'.

     This rule does the right thing for a simple program with only one
     source file.  It will also do the right thing if there are multiple
     object files (presumably coming from various other source files),
     one of which has a name matching that of the executable file.
     Thus,

          x: y.o z.o

     when `x.c', `y.c' and `z.c' all exist will execute:

          cc -c x.c -o x.o
          cc -c y.c -o y.o
          cc -c z.c -o z.o
          cc x.o y.o z.o -o x
          rm -f x.o
          rm -f y.o
          rm -f z.o

     In more complicated cases, such as when there is no object file
     whose name derives from the executable file name, you must write
     an explicit command for linking.

     Each kind of file automatically made into `.o' object files will
     be automatically linked by using the compiler (`$(CC)', `$(FC)' or
     `$(PC)'; the C compiler `$(CC)' is used to assemble `.s' files)
     without the `-c' option.  This could be done by using the `.o'
     object files as intermediates, but it is faster to do the
     compiling and linking in one step, so that's how it's done.

Yacc for C programs
     `N.c' is made automatically from `N.y' by running Yacc with the
     command `$(YACC) $(YFLAGS)'.

Lex for C programs
     `N.c' is made automatically from `N.l' by running Lex.  The actual
     command is `$(LEX) $(LFLAGS)'.

Lex for Ratfor programs
     `N.r' is made automatically from `N.l' by running Lex.  The actual
     command is `$(LEX) $(LFLAGS)'.

     The convention of using the same suffix `.l' for all Lex files
     regardless of whether they produce C code or Ratfor code makes it
     impossible for `make' to determine automatically which of the two
     languages you are using in any particular case.  If `make' is
     called upon to remake an object file from a `.l' file, it must
     guess which compiler to use.  It will guess the C compiler, because
     that is more common.  If you are using Ratfor, make sure `make'
     knows this by mentioning `N.r' in the makefile.  Or, if you are
     using Ratfor exclusively, with no C files, remove `.c' from the
     list of implicit rule suffixes with:

          .SUFFIXES:
          .SUFFIXES: .o .r .f .l ...

Making Lint Libraries from C, Yacc, or Lex programs
     `N.ln' is made from `N.c' by running `lint'.  The precise command
     is `$(LINT) $(LINTFLAGS) $(CPPFLAGS) -i'.  The same command is
     used on the C code produced from `N.y' or `N.l'.

TeX and Web
     `N.dvi' is made from `N.tex' with the command `$(TEX)'.  `N.tex'
     is made from `N.web' with `$(WEAVE)', or from `N.w' (and from
     `N.ch' if it exists or can be made) with `$(CWEAVE)'.  `N.p' is
     made from `N.web' with `$(TANGLE)' and `N.c' is made from `N.w'
     (and from `N.ch' if it exists or can be made) with `$(CTANGLE)'.

Texinfo and Info
     `N.dvi' is made from `N.texinfo', `N.texi', or `N.txinfo', with
     the command `$(TEXI2DVI) $(TEXI2DVI_FLAGS)'.  `N.info' is made from
     `N.texinfo', `N.texi', or `N.txinfo', with the command
     `$(MAKEINFO) $(MAKEINFO_FLAGS)'.

RCS
     Any file `N' is extracted if necessary from an RCS file named
     either `N,v' or `RCS/N,v'.  The precise command used is
     `$(CO) $(COFLAGS)'.  `N' will not be extracted from RCS if it
     already exists, even if the RCS file is newer.  The rules for RCS
     are terminal (*note Match-Anything Pattern Rules: Match-Anything
     Rules.), so RCS files cannot be generated from another source;
     they must actually exist.

SCCS
     Any file `N' is extracted if necessary from an SCCS file named
     either `s.N' or `SCCS/s.N'.  The precise command used is
     `$(GET) $(GFLAGS)'.  The rules for SCCS are terminal (*note
     Match-Anything Pattern Rules: Match-Anything Rules.), so SCCS
     files cannot be generated from another source; they must actually
     exist.

     For the benefit of SCCS, a file `N' is copied from `N.sh' and made
     executable (by everyone).  This is for shell scripts that are
     checked into SCCS.  Since RCS preserves the execution permission
     of a file, you do not need to use this feature with RCS.

     We recommend that you avoid using of SCCS.  RCS is widely held to
     be superior, and is also free.  By choosing free software in place
     of comparable (or inferior) proprietary software, you support the
     free software movement.

   Usually, you want to change only the variables listed in the table
above, which are documented in the following section.

   However, the commands in built-in implicit rules actually use
variables such as `COMPILE.c', `LINK.p', and `PREPROCESS.S', whose
values contain the commands listed above.

   `make' follows the convention that the rule to compile a `.X' source
file uses the variable `COMPILE.X'.  Similarly, the rule to produce an
executable from a `.X' file uses `LINK.X'; and the rule to preprocess a
`.X' file uses `PREPROCESS.X'.

   Every rule that produces an object file uses the variable
`OUTPUT_OPTION'.  `make' defines this variable either to contain `-o
$@', or to be empty, depending on a compile-time option.  You need the
`-o' option to ensure that the output goes into the right file when the
source file is in a different directory, as when using `VPATH' (*note
Directory Search::).  However, compilers on some systems do not accept
a `-o' switch for object files.  If you use such a system, and use
`VPATH', some compilations will put their output in the wrong place.  A
possible workaround for this problem is to give `OUTPUT_OPTION' the
value `; mv $*.o $@'.


File: make.info,  Node: Implicit Variables,  Next: Chained Rules,  Prev: Catalogue of Rules,  Up: Implicit Rules

Variables Used by Implicit Rules
================================

   The commands in built-in implicit rules make liberal use of certain
predefined variables.  You can alter these variables in the makefile,
with arguments to `make', or in the environment to alter how the
implicit rules work without redefining the rules themselves.  You can
cancel all variables used by implicit rules with the `-R' or
`--no-builtin-variables' option.

   For example, the command used to compile a C source file actually
says `$(CC) -c $(CFLAGS) $(CPPFLAGS)'.  The default values of the
variables used are `cc' and nothing, resulting in the command `cc -c'.
By redefining `CC' to `ncc', you could cause `ncc' to be used for all C
compilations performed by the implicit rule.  By redefining `CFLAGS' to
be `-g', you could pass the `-g' option to each compilation.  _All_
implicit rules that do C compilation use `$(CC)' to get the program
name for the compiler and _all_ include `$(CFLAGS)' among the arguments
given to the compiler.

   The variables used in implicit rules fall into two classes: those
that are names of programs (like `CC') and those that contain arguments
for the programs (like `CFLAGS').  (The "name of a program" may also
contain some command arguments, but it must start with an actual
executable program name.)  If a variable value contains more than one
argument, separate them with spaces.

   Here is a table of variables used as names of programs in built-in
rules:

`AR'
     Archive-maintaining program; default `ar'.

`AS'
     Program for doing assembly; default `as'.

`CC'
     Program for compiling C programs; default `cc'.

`CXX'
     Program for compiling C++ programs; default `g++'.

`CO'
     Program for extracting a file from RCS; default `co'.

`CPP'
     Program for running the C preprocessor, with results to standard
     output; default `$(CC) -E'.

`FC'
     Program for compiling or preprocessing Fortran and Ratfor programs;
     default `f77'.

`GET'
     Program for extracting a file from SCCS; default `get'.

`LEX'
     Program to use to turn Lex grammars into C programs or Ratfor
     programs; default `lex'.

`PC'
     Program for compiling Pascal programs; default `pc'.

`YACC'
     Program to use to turn Yacc grammars into C programs; default
     `yacc'.

`YACCR'
     Program to use to turn Yacc grammars into Ratfor programs; default
     `yacc -r'.

`MAKEINFO'
     Program to convert a Texinfo source file into an Info file; default
     `makeinfo'.

`TEX'
     Program to make TeX DVI files from TeX source; default `tex'.

`TEXI2DVI'
     Program to make TeX DVI files from Texinfo source; default
     `texi2dvi'.

`WEAVE'
     Program to translate Web into TeX; default `weave'.

`CWEAVE'
     Program to translate C Web into TeX; default `cweave'.

`TANGLE'
     Program to translate Web into Pascal; default `tangle'.

`CTANGLE'
     Program to translate C Web into C; default `ctangle'.

`RM'
     Command to remove a file; default `rm -f'.

   Here is a table of variables whose values are additional arguments
for the programs above.  The default values for all of these is the
empty string, unless otherwise noted.

`ARFLAGS'
     Flags to give the archive-maintaining program; default `rv'.

`ASFLAGS'
     Extra flags to give to the assembler (when explicitly invoked on a
     `.s' or `.S' file).

`CFLAGS'
     Extra flags to give to the C compiler.

`CXXFLAGS'
     Extra flags to give to the C++ compiler.

`COFLAGS'
     Extra flags to give to the RCS `co' program.

`CPPFLAGS'
     Extra flags to give to the C preprocessor and programs that use it
     (the C and Fortran compilers).

`FFLAGS'
     Extra flags to give to the Fortran compiler.

`GFLAGS'
     Extra flags to give to the SCCS `get' program.

`LDFLAGS'
     Extra flags to give to compilers when they are supposed to invoke
     the linker, `ld'.

`LFLAGS'
     Extra flags to give to Lex.

`PFLAGS'
     Extra flags to give to the Pascal compiler.

`RFLAGS'
     Extra flags to give to the Fortran compiler for Ratfor programs.

`YFLAGS'
     Extra flags to give to Yacc.


File: make.info,  Node: Chained Rules,  Next: Pattern Rules,  Prev: Implicit Variables,  Up: Implicit Rules

Chains of Implicit Rules
========================

   Sometimes a file can be made by a sequence of implicit rules.  For
example, a file `N.o' could be made from `N.y' by running first Yacc
and then `cc'.  Such a sequence is called a "chain".

   If the file `N.c' exists, or is mentioned in the makefile, no
special searching is required: `make' finds that the object file can be
made by C compilation from `N.c'; later on, when considering how to
make `N.c', the rule for running Yacc is used.  Ultimately both `N.c'
and `N.o' are updated.

   However, even if `N.c' does not exist and is not mentioned, `make'
knows how to envision it as the missing link between `N.o' and `N.y'!
In this case, `N.c' is called an "intermediate file".  Once `make' has
decided to use the intermediate file, it is entered in the data base as
if it had been mentioned in the makefile, along with the implicit rule
that says how to create it.

   Intermediate files are remade using their rules just like all other
files.  But intermediate files are treated differently in two ways.

   The first difference is what happens if the intermediate file does
not exist.  If an ordinary file B does not exist, and `make' considers
a target that depends on B, it invariably creates B and then updates
the target from B.  But if B is an intermediate file, then `make' can
leave well enough alone.  It won't bother updating B, or the ultimate
target, unless some prerequisite of B is newer than that target or
there is some other reason to update that target.

   The second difference is that if `make' _does_ create B in order to
update something else, it deletes B later on after it is no longer
needed.  Therefore, an intermediate file which did not exist before
`make' also does not exist after `make'.  `make' reports the deletion
to you by printing a `rm -f' command showing which file it is deleting.

   Ordinarily, a file cannot be intermediate if it is mentioned in the
makefile as a target or prerequisite.  However, you can explicitly mark
a file as intermediate by listing it as a prerequisite of the special
target `.INTERMEDIATE'.  This takes effect even if the file is mentioned
explicitly in some other way.

   You can prevent automatic deletion of an intermediate file by
marking it as a "secondary" file.  To do this, list it as a
prerequisite of the special target `.SECONDARY'.  When a file is
secondary, `make' will not create the file merely because it does not
already exist, but `make' does not automatically delete the file.
Marking a file as secondary also marks it as intermediate.

   You can list the target pattern of an implicit rule (such as `%.o')
as a prerequisite of the special target `.PRECIOUS' to preserve
intermediate files made by implicit rules whose target patterns match
that file's name; see *Note Interrupts::.

   A chain can involve more than two implicit rules.  For example, it is
possible to make a file `foo' from `RCS/foo.y,v' by running RCS, Yacc
and `cc'.  Then both `foo.y' and `foo.c' are intermediate files that
are deleted at the end.

   No single implicit rule can appear more than once in a chain.  This
means that `make' will not even consider such a ridiculous thing as
making `foo' from `foo.o.o' by running the linker twice.  This
constraint has the added benefit of preventing any infinite loop in the
search for an implicit rule chain.

   There are some special implicit rules to optimize certain cases that
would otherwise be handled by rule chains.  For example, making `foo'
from `foo.c' could be handled by compiling and linking with separate
chained rules, using `foo.o' as an intermediate file.  But what
actually happens is that a special rule for this case does the
compilation and linking with a single `cc' command.  The optimized rule
is used in preference to the step-by-step chain because it comes
earlier in the ordering of rules.


File: make.info,  Node: Pattern Rules,  Next: Last Resort,  Prev: Chained Rules,  Up: Implicit Rules

Defining and Redefining Pattern Rules
=====================================

   You define an implicit rule by writing a "pattern rule".  A pattern
rule looks like an ordinary rule, except that its target contains the
character `%' (exactly one of them).  The target is considered a
pattern for matching file names; the `%' can match any nonempty
substring, while other characters match only themselves.  The
prerequisites likewise use `%' to show how their names relate to the
target name.

   Thus, a pattern rule `%.o : %.c' says how to make any file `STEM.o'
from another file `STEM.c'.

   Note that expansion using `%' in pattern rules occurs *after* any
variable or function expansions, which take place when the makefile is
read.  *Note How to Use Variables: Using Variables, and *Note Functions
for Transforming Text: Functions.

* Menu:

* Pattern Intro::               An introduction to pattern rules.
* Pattern Examples::            Examples of pattern rules.
* Automatic::                   How to use automatic variables in the
                                  commands of implicit rules.
* Pattern Match::               How patterns match.
* Match-Anything Rules::        Precautions you should take prior to
                                  defining rules that can match any
                                  target file whatever.
* Canceling Rules::             How to override or cancel built-in rules.


File: make.info,  Node: Pattern Intro,  Next: Pattern Examples,  Prev: Pattern Rules,  Up: Pattern Rules

Introduction to Pattern Rules
-----------------------------

   A pattern rule contains the character `%' (exactly one of them) in
the target; otherwise, it looks exactly like an ordinary rule.  The
target is a pattern for matching file names; the `%' matches any
nonempty substring, while other characters match only themselves.

   For example, `%.c' as a pattern matches any file name that ends in
`.c'.  `s.%.c' as a pattern matches any file name that starts with
`s.', ends in `.c' and is at least five characters long.  (There must
be at least one character to match the `%'.)  The substring that the
`%' matches is called the "stem".

   `%' in a prerequisite of a pattern rule stands for the same stem
that was matched by the `%' in the target.  In order for the pattern
rule to apply, its target pattern must match the file name under
consideration, and its prerequisite patterns must name files that exist
or can be made.  These files become prerequisites of the target.

   Thus, a rule of the form

     %.o : %.c ; COMMAND...

specifies how to make a file `N.o', with another file `N.c' as its
prerequisite, provided that `N.c' exists or can be made.

   There may also be prerequisites that do not use `%'; such a
prerequisite attaches to every file made by this pattern rule.  These
unvarying prerequisites are useful occasionally.

   A pattern rule need not have any prerequisites that contain `%', or
in fact any prerequisites at all.  Such a rule is effectively a general
wildcard.  It provides a way to make any file that matches the target
pattern.  *Note Last Resort::.

   Pattern rules may have more than one target.  Unlike normal rules,
this does not act as many different rules with the same prerequisites
and commands.  If a pattern rule has multiple targets, `make' knows that
the rule's commands are responsible for making all of the targets.  The
commands are executed only once to make all the targets.  When searching
for a pattern rule to match a target, the target patterns of a rule
other than the one that matches the target in need of a rule are
incidental: `make' worries only about giving commands and prerequisites
to the file presently in question.  However, when this file's commands
are run, the other targets are marked as having been updated themselves.

   The order in which pattern rules appear in the makefile is important
since this is the order in which they are considered.  Of equally
applicable rules, only the first one found is used.  The rules you
write take precedence over those that are built in.  Note however, that
a rule whose prerequisites actually exist or are mentioned always takes
priority over a rule with prerequisites that must be made by chaining
other implicit rules.


File: make.info,  Node: Pattern Examples,  Next: Automatic,  Prev: Pattern Intro,  Up: Pattern Rules

Pattern Rule Examples
---------------------

   Here are some examples of pattern rules actually predefined in
`make'.  First, the rule that compiles `.c' files into `.o' files:

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

defines a rule that can make any file `X.o' from `X.c'.  The command
uses the automatic variables `$@' and `$<' to substitute the names of
the target file and the source file in each case where the rule applies
(*note Automatic Variables: Automatic.).

   Here is a second built-in rule:

     % :: RCS/%,v
             $(CO) $(COFLAGS) $<

defines a rule that can make any file `X' whatsoever from a
corresponding file `X,v' in the subdirectory `RCS'.  Since the target
is `%', this rule will apply to any file whatever, provided the
appropriate prerequisite file exists.  The double colon makes the rule
"terminal", which means that its prerequisite may not be an intermediate
file (*note Match-Anything Pattern Rules: Match-Anything Rules.).

   This pattern rule has two targets:

     %.tab.c %.tab.h: %.y
             bison -d $<

This tells `make' that the command `bison -d X.y' will make both
`X.tab.c' and `X.tab.h'.  If the file `foo' depends on the files
`parse.tab.o' and `scan.o' and the file `scan.o' depends on the file
`parse.tab.h', when `parse.y' is changed, the command `bison -d parse.y'
will be executed only once, and the prerequisites of both `parse.tab.o'
and `scan.o' will be satisfied.  (Presumably the file `parse.tab.o'
will be recompiled from `parse.tab.c' and the file `scan.o' from
`scan.c', while `foo' is linked from `parse.tab.o', `scan.o', and its
other prerequisites, and it will execute happily ever after.)


File: make.info,  Node: Automatic,  Next: Pattern Match,  Prev: Pattern Examples,  Up: Pattern Rules

Automatic Variables
-------------------

   Suppose you are writing a pattern rule to compile a `.c' file into a
`.o' file: how do you write the `cc' command so that it operates on the
right source file name?  You cannot write the name in the command,
because the name is different each time the implicit rule is applied.

   What you do is use a special feature of `make', the "automatic
variables".  These variables have values computed afresh for each rule
that is executed, based on the target and prerequisites of the rule.
In this example, you would use `$@' for the object file name and `$<'
for the source file name.

   Here is a table of automatic variables:

`$@'
     The file name of the target of the rule.  If the target is an
     archive member, then `$@' is the name of the archive file.  In a
     pattern rule that has multiple targets (*note Introduction to
     Pattern Rules: Pattern Intro.), `$@' is the name of whichever
     target caused the rule's commands to be run.

`$%'
     The target member name, when the target is an archive member.
     *Note Archives::.  For example, if the target is `foo.a(bar.o)'
     then `$%' is `bar.o' and `$@' is `foo.a'.  `$%' is empty when the
     target is not an archive member.

`$<'
     The name of the first prerequisite.  If the target got its
     commands from an implicit rule, this will be the first
     prerequisite added by the implicit rule (*note Implicit Rules::).

`$?'
     The names of all the prerequisites that are newer than the target,
     with spaces between them.  For prerequisites which are archive
     members, only the member named is used (*note Archives::).

`$^'
     The names of all the prerequisites, with spaces between them.  For
     prerequisites which are archive members, only the member named is
     used (*note Archives::).  A target has only one prerequisite on
     each other file it depends on, no matter how many times each file
     is listed as a prerequisite.  So if you list a prerequisite more
     than once for a target, the value of `$^' contains just one copy
     of the name.

`$+'
     This is like `$^', but prerequisites listed more than once are
     duplicated in the order they were listed in the makefile.  This is
     primarily useful for use in linking commands where it is
     meaningful to repeat library file names in a particular order.

`$*'
     The stem with which an implicit rule matches (*note How Patterns
     Match: Pattern Match.).  If the target is `dir/a.foo.b' and the
     target pattern is `a.%.b' then the stem is `dir/foo'.  The stem is
     useful for constructing names of related files.

     In a static pattern rule, the stem is part of the file name that
     matched the `%' in the target pattern.

     In an explicit rule, there is no stem; so `$*' cannot be determined
     in that way.  Instead, if the target name ends with a recognized
     suffix (*note Old-Fashioned Suffix Rules: Suffix Rules.), `$*' is
     set to the target name minus the suffix.  For example, if the
     target name is `foo.c', then `$*' is set to `foo', since `.c' is a
     suffix.  GNU `make' does this bizarre thing only for compatibility
     with other implementations of `make'.  You should generally avoid
     using `$*' except in implicit rules or static pattern rules.

     If the target name in an explicit rule does not end with a
     recognized suffix, `$*' is set to the empty string for that rule.

   `$?' is useful even in explicit rules when you wish to operate on
only the prerequisites that have changed.  For example, suppose that an
archive named `lib' is supposed to contain copies of several object
files.  This rule copies just the changed object files into the archive:

     lib: foo.o bar.o lose.o win.o
             ar r lib $?

   Of the variables listed above, four have values that are single file
names, and three have values that are lists of file names.  These seven
have variants that get just the file's directory name or just the file
name within the directory.  The variant variables' names are formed by
appending `D' or `F', respectively.  These variants are semi-obsolete
in GNU `make' since the functions `dir' and `notdir' can be used to get
a similar effect (*note Functions for File Names: File Name
Functions.).  Note, however, that the `D' variants all omit the
trailing slash which always appears in the output of the `dir'
function.  Here is a table of the variants:

`$(@D)'
     The directory part of the file name of the target, with the
     trailing slash removed.  If the value of `$@' is `dir/foo.o' then
     `$(@D)' is `dir'.  This value is `.' if `$@' does not contain a
     slash.

`$(@F)'
     The file-within-directory part of the file name of the target.  If
     the value of `$@' is `dir/foo.o' then `$(@F)' is `foo.o'.  `$(@F)'
     is equivalent to `$(notdir $@)'.

`$(*D)'
`$(*F)'
     The directory part and the file-within-directory part of the stem;
     `dir' and `foo' in this example.

`$(%D)'
`$(%F)'
     The directory part and the file-within-directory part of the target
     archive member name.  This makes sense only for archive member
     targets of the form `ARCHIVE(MEMBER)' and is useful only when
     MEMBER may contain a directory name.  (*Note Archive Members as
     Targets: Archive Members.)

`$(<D)'
`$(<F)'
     The directory part and the file-within-directory part of the first
     prerequisite.

`$(^D)'
`$(^F)'
     Lists of the directory parts and the file-within-directory parts
     of all prerequisites.

`$(+D)'
`$(+F)'
     Lists of the directory parts and the file-within-directory parts
     of all prerequisites, including multiple instances of duplicated
     prerequisites.

`$(?D)'
`$(?F)'
     Lists of the directory parts and the file-within-directory parts of
     all prerequisites that are newer than the target.

   Note that we use a special stylistic convention when we talk about
these automatic variables; we write "the value of `$<'", rather than
"the variable `<'" as we would write for ordinary variables such as
`objects' and `CFLAGS'.  We think this convention looks more natural in
this special case.  Please do not assume it has a deep significance;
`$<' refers to the variable named `<' just as `$(CFLAGS)' refers to the
variable named `CFLAGS'.  You could just as well use `$(<)' in place of
`$<'.

   GNU `make' provides support for the SysV `make' feature that allows
special variable references `$$@', `$$(@D)', and `$$(@F)' (note the
required double-"$"!) to appear with the _prerequisites list_ (normal
automatic variables are available only within a command script).  When
appearing in a prerequisites list, these variables are expanded to the
name of the target, the directory component of the target, and the file
component of the target, respectively.

   Note that these variables are available only within explicit and
static pattern (*note Static Pattern Rules: Static Pattern.) rules;
they have no special significance within implicit (suffix or pattern)
rules.  Also note that while SysV `make' actually expands its entire
prerequisite list _twice_, GNU `make' does not behave this way: instead
it simply expands these special variables without re-expanding any
other part of the prerequisites list.

   This somewhat bizarre feature is included only to provide some
compatibility with SysV makefiles.  In a native GNU `make' file there
are other ways to accomplish the same results.  This feature is
disabled if the special pseudo target `.POSIX' is defined.


File: make.info,  Node: Pattern Match,  Next: Match-Anything Rules,  Prev: Automatic,  Up: Pattern Rules

How Patterns Match
------------------

   A target pattern is composed of a `%' between a prefix and a suffix,
either or both of which may be empty.  The pattern matches a file name
only if the file name starts with the prefix and ends with the suffix,
without overlap.  The text between the prefix and the suffix is called
the "stem".  Thus, when the pattern `%.o' matches the file name
`test.o', the stem is `test'.  The pattern rule prerequisites are
turned into actual file names by substituting the stem for the character
`%'.  Thus, if in the same example one of the prerequisites is written
as `%.c', it expands to `test.c'.

   When the target pattern does not contain a slash (and it usually does
not), directory names in the file names are removed from the file name
before it is compared with the target prefix and suffix.  After the
comparison of the file name to the target pattern, the directory names,
along with the slash that ends them, are added on to the prerequisite
file names generated from the pattern rule's prerequisite patterns and
the file name. The directories are ignored only for the purpose of
finding an implicit rule to use, not in the application of that rule.
Thus, `e%t' matches the file name `src/eat', with `src/a' as the stem.
When prerequisites are turned into file names, the directories from the
stem are added at the front, while the rest of the stem is substituted
for the `%'.  The stem `src/a' with a prerequisite pattern `c%r' gives
the file name `src/car'.