9b12bf288a
version, based off of 3.74, seems to have problems with NSPR autoconf. r=cls. git-svn-id: svn://10.0.0.236/trunk@85225 18797224-902f-48f8-a5cc-f745e15eee43
994 lines
41 KiB
Plaintext
994 lines
41 KiB
Plaintext
This is make.info, produced by makeinfo version 4.0 from make.texinfo.
|
||
|
||
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.55, last updated 04 April 2000, of `The GNU Make
|
||
Manual', for `make', Version 3.79.
|
||
|
||
Copyright (C) 1988, '89, '90, '91, '92, '93, '94, '95, '96, '97,
|
||
'98, '99, 2000 Free Software Foundation, Inc.
|
||
|
||
Permission is granted to make and distribute verbatim copies of this
|
||
manual provided the copyright notice and this permission notice are
|
||
preserved on all copies.
|
||
|
||
Permission is granted to copy and distribute modified versions of
|
||
this manual under the conditions for verbatim copying, provided that
|
||
the entire resulting derived work is distributed under the terms of a
|
||
permission notice identical to this one.
|
||
|
||
Permission is granted to copy and distribute translations of this
|
||
manual into another language, under the above conditions for modified
|
||
versions, except that this permission notice may be stated in a
|
||
translation approved by the Free Software Foundation.
|
||
|
||
|
||
File: make.info, Node: Archive Members, Next: Archive Update, Up: Archives
|
||
|
||
Archive Members as Targets
|
||
==========================
|
||
|
||
An individual member of an archive file can be used as a target or
|
||
prerequisite in `make'. You specify the member named MEMBER in archive
|
||
file ARCHIVE as follows:
|
||
|
||
ARCHIVE(MEMBER)
|
||
|
||
This construct is available only in targets and prerequisites, not in
|
||
commands! Most programs that you might use in commands do not support
|
||
this syntax and cannot act directly on archive members. Only `ar' and
|
||
other programs specifically designed to operate on archives can do so.
|
||
Therefore, valid commands to update an archive member target probably
|
||
must use `ar'. For example, this rule says to create a member `hack.o'
|
||
in archive `foolib' by copying the file `hack.o':
|
||
|
||
foolib(hack.o) : hack.o
|
||
ar cr foolib hack.o
|
||
|
||
In fact, nearly all archive member targets are updated in just this
|
||
way and there is an implicit rule to do it for you. *Note:* The `c'
|
||
flag to `ar' is required if the archive file does not already exist.
|
||
|
||
To specify several members in the same archive, you can write all the
|
||
member names together between the parentheses. For example:
|
||
|
||
foolib(hack.o kludge.o)
|
||
|
||
is equivalent to:
|
||
|
||
foolib(hack.o) foolib(kludge.o)
|
||
|
||
You can also use shell-style wildcards in an archive member
|
||
reference. *Note Using Wildcard Characters in File Names: Wildcards.
|
||
For example, `foolib(*.o)' expands to all existing members of the
|
||
`foolib' archive whose names end in `.o'; perhaps `foolib(hack.o)
|
||
foolib(kludge.o)'.
|
||
|
||
|
||
File: make.info, Node: Archive Update, Next: Archive Pitfalls, Prev: Archive Members, Up: Archives
|
||
|
||
Implicit Rule for Archive Member Targets
|
||
========================================
|
||
|
||
Recall that a target that looks like `A(M)' stands for the member
|
||
named M in the archive file A.
|
||
|
||
When `make' looks for an implicit rule for such a target, as a
|
||
special feature it considers implicit rules that match `(M)', as well as
|
||
those that match the actual target `A(M)'.
|
||
|
||
This causes one special rule whose target is `(%)' to match. This
|
||
rule updates the target `A(M)' by copying the file M into the archive.
|
||
For example, it will update the archive member target `foo.a(bar.o)' by
|
||
copying the _file_ `bar.o' into the archive `foo.a' as a _member_ named
|
||
`bar.o'.
|
||
|
||
When this rule is chained with others, the result is very powerful.
|
||
Thus, `make "foo.a(bar.o)"' (the quotes are needed to protect the `('
|
||
and `)' from being interpreted specially by the shell) in the presence
|
||
of a file `bar.c' is enough to cause the following commands to be run,
|
||
even without a makefile:
|
||
|
||
cc -c bar.c -o bar.o
|
||
ar r foo.a bar.o
|
||
rm -f bar.o
|
||
|
||
Here `make' has envisioned the file `bar.o' as an intermediate file.
|
||
*Note Chains of Implicit Rules: Chained Rules.
|
||
|
||
Implicit rules such as this one are written using the automatic
|
||
variable `$%'. *Note Automatic Variables: Automatic.
|
||
|
||
An archive member name in an archive cannot contain a directory
|
||
name, but it may be useful in a makefile to pretend that it does. If
|
||
you write an archive member target `foo.a(dir/file.o)', `make' will
|
||
perform automatic updating with this command:
|
||
|
||
ar r foo.a dir/file.o
|
||
|
||
which has the effect of copying the file `dir/file.o' into a member
|
||
named `file.o'. In connection with such usage, the automatic variables
|
||
`%D' and `%F' may be useful.
|
||
|
||
* Menu:
|
||
|
||
* Archive Symbols:: How to update archive symbol directories.
|
||
|
||
|
||
File: make.info, Node: Archive Symbols, Up: Archive Update
|
||
|
||
Updating Archive Symbol Directories
|
||
-----------------------------------
|
||
|
||
An archive file that is used as a library usually contains a special
|
||
member named `__.SYMDEF' that contains a directory of the external
|
||
symbol names defined by all the other members. After you update any
|
||
other members, you need to update `__.SYMDEF' so that it will summarize
|
||
the other members properly. This is done by running the `ranlib'
|
||
program:
|
||
|
||
ranlib ARCHIVEFILE
|
||
|
||
Normally you would put this command in the rule for the archive file,
|
||
and make all the members of the archive file prerequisites of that rule.
|
||
For example,
|
||
|
||
libfoo.a: libfoo.a(x.o) libfoo.a(y.o) ...
|
||
ranlib libfoo.a
|
||
|
||
The effect of this is to update archive members `x.o', `y.o', etc., and
|
||
then update the symbol directory member `__.SYMDEF' by running
|
||
`ranlib'. The rules for updating the members are not shown here; most
|
||
likely you can omit them and use the implicit rule which copies files
|
||
into the archive, as described in the preceding section.
|
||
|
||
This is not necessary when using the GNU `ar' program, which updates
|
||
the `__.SYMDEF' member automatically.
|
||
|
||
|
||
File: make.info, Node: Archive Pitfalls, Next: Archive Suffix Rules, Prev: Archive Update, Up: Archives
|
||
|
||
Dangers When Using Archives
|
||
===========================
|
||
|
||
It is important to be careful when using parallel execution (the
|
||
`-j' switch; *note Parallel Execution: Parallel.) and archives. If
|
||
multiple `ar' commands run at the same time on the same archive file,
|
||
they will not know about each other and can corrupt the file.
|
||
|
||
Possibly a future version of `make' will provide a mechanism to
|
||
circumvent this problem by serializing all commands that operate on the
|
||
same archive file. But for the time being, you must either write your
|
||
makefiles to avoid this problem in some other way, or not use `-j'.
|
||
|
||
|
||
File: make.info, Node: Archive Suffix Rules, Prev: Archive Pitfalls, Up: Archives
|
||
|
||
Suffix Rules for Archive Files
|
||
==============================
|
||
|
||
You can write a special kind of suffix rule for dealing with archive
|
||
files. *Note Suffix Rules::, for a full explanation of suffix rules.
|
||
Archive suffix rules are obsolete in GNU `make', because pattern rules
|
||
for archives are a more general mechanism (*note Archive Update::).
|
||
But they are retained for compatibility with other `make's.
|
||
|
||
To write a suffix rule for archives, you simply write a suffix rule
|
||
using the target suffix `.a' (the usual suffix for archive files). For
|
||
example, here is the old-fashioned suffix rule to update a library
|
||
archive from C source files:
|
||
|
||
.c.a:
|
||
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
|
||
$(AR) r $@ $*.o
|
||
$(RM) $*.o
|
||
|
||
This works just as if you had written the pattern rule:
|
||
|
||
(%.o): %.c
|
||
$(CC) $(CFLAGS) $(CPPFLAGS) -c $< -o $*.o
|
||
$(AR) r $@ $*.o
|
||
$(RM) $*.o
|
||
|
||
In fact, this is just what `make' does when it sees a suffix rule
|
||
with `.a' as the target suffix. Any double-suffix rule `.X.a' is
|
||
converted to a pattern rule with the target pattern `(%.o)' and a
|
||
prerequisite pattern of `%.X'.
|
||
|
||
Since you might want to use `.a' as the suffix for some other kind
|
||
of file, `make' also converts archive suffix rules to pattern rules in
|
||
the normal way (*note Suffix Rules::). Thus a double-suffix rule
|
||
`.X.a' produces two pattern rules: `(%.o): %.X' and `%.a: %.X'.
|
||
|
||
|
||
File: make.info, Node: Features, Next: Missing, Prev: Archives, Up: Top
|
||
|
||
Features of GNU `make'
|
||
**********************
|
||
|
||
Here is a summary of the features of GNU `make', for comparison with
|
||
and credit to other versions of `make'. We consider the features of
|
||
`make' in 4.2 BSD systems as a baseline. If you are concerned with
|
||
writing portable makefiles, you should not use the features of `make'
|
||
listed here, nor the ones in *Note Missing::.
|
||
|
||
Many features come from the version of `make' in System V.
|
||
|
||
* The `VPATH' variable and its special meaning. *Note Searching
|
||
Directories for Prerequisites: Directory Search. This feature
|
||
exists in System V `make', but is undocumented. It is documented
|
||
in 4.3 BSD `make' (which says it mimics System V's `VPATH'
|
||
feature).
|
||
|
||
* Included makefiles. *Note Including Other Makefiles: Include.
|
||
Allowing multiple files to be included with a single directive is
|
||
a GNU extension.
|
||
|
||
* Variables are read from and communicated via the environment.
|
||
*Note Variables from the Environment: Environment.
|
||
|
||
* Options passed through the variable `MAKEFLAGS' to recursive
|
||
invocations of `make'. *Note Communicating Options to a
|
||
Sub-`make': Options/Recursion.
|
||
|
||
* The automatic variable `$%' is set to the member name in an
|
||
archive reference. *Note Automatic Variables: Automatic.
|
||
|
||
* The automatic variables `$@', `$*', `$<', `$%', and `$?' have
|
||
corresponding forms like `$(@F)' and `$(@D)'. We have generalized
|
||
this to `$^' as an obvious extension. *Note Automatic Variables:
|
||
Automatic.
|
||
|
||
* Substitution variable references. *Note Basics of Variable
|
||
References: Reference.
|
||
|
||
* The command-line options `-b' and `-m', accepted and ignored. In
|
||
System V `make', these options actually do something.
|
||
|
||
* Execution of recursive commands to run `make' via the variable
|
||
`MAKE' even if `-n', `-q' or `-t' is specified. *Note Recursive
|
||
Use of `make': Recursion.
|
||
|
||
* Support for suffix `.a' in suffix rules. *Note Archive Suffix
|
||
Rules::. This feature is obsolete in GNU `make', because the
|
||
general feature of rule chaining (*note Chains of Implicit Rules:
|
||
Chained Rules.) allows one pattern rule for installing members in
|
||
an archive (*note Archive Update::) to be sufficient.
|
||
|
||
* The arrangement of lines and backslash-newline combinations in
|
||
commands is retained when the commands are printed, so they appear
|
||
as they do in the makefile, except for the stripping of initial
|
||
whitespace.
|
||
|
||
The following features were inspired by various other versions of
|
||
`make'. In some cases it is unclear exactly which versions inspired
|
||
which others.
|
||
|
||
* Pattern rules using `%'. This has been implemented in several
|
||
versions of `make'. We're not sure who invented it first, but
|
||
it's been spread around a bit. *Note Defining and Redefining
|
||
Pattern Rules: Pattern Rules.
|
||
|
||
* Rule chaining and implicit intermediate files. This was
|
||
implemented by Stu Feldman in his version of `make' for AT&T
|
||
Eighth Edition Research Unix, and later by Andrew Hume of AT&T
|
||
Bell Labs in his `mk' program (where he terms it "transitive
|
||
closure"). We do not really know if we got this from either of
|
||
them or thought it up ourselves at the same time. *Note Chains of
|
||
Implicit Rules: Chained Rules.
|
||
|
||
* The automatic variable `$^' containing a list of all prerequisites
|
||
of the current target. We did not invent this, but we have no
|
||
idea who did. *Note Automatic Variables: Automatic. The
|
||
automatic variable `$+' is a simple extension of `$^'.
|
||
|
||
* The "what if" flag (`-W' in GNU `make') was (as far as we know)
|
||
invented by Andrew Hume in `mk'. *Note Instead of Executing the
|
||
Commands: Instead of Execution.
|
||
|
||
* The concept of doing several things at once (parallelism) exists in
|
||
many incarnations of `make' and similar programs, though not in the
|
||
System V or BSD implementations. *Note Command Execution:
|
||
Execution.
|
||
|
||
* Modified variable references using pattern substitution come from
|
||
SunOS 4. *Note Basics of Variable References: Reference. This
|
||
functionality was provided in GNU `make' by the `patsubst'
|
||
function before the alternate syntax was implemented for
|
||
compatibility with SunOS 4. It is not altogether clear who
|
||
inspired whom, since GNU `make' had `patsubst' before SunOS 4 was
|
||
released.
|
||
|
||
* The special significance of `+' characters preceding command lines
|
||
(*note Instead of Executing the Commands: Instead of Execution.) is
|
||
mandated by `IEEE Standard 1003.2-1992' (POSIX.2).
|
||
|
||
* The `+=' syntax to append to the value of a variable comes from
|
||
SunOS 4 `make'. *Note Appending More Text to Variables: Appending.
|
||
|
||
* The syntax `ARCHIVE(MEM1 MEM2...)' to list multiple members in a
|
||
single archive file comes from SunOS 4 `make'. *Note Archive
|
||
Members::.
|
||
|
||
* The `-include' directive to include makefiles with no error for a
|
||
nonexistent file comes from SunOS 4 `make'. (But note that SunOS 4
|
||
`make' does not allow multiple makefiles to be specified in one
|
||
`-include' directive.) The same feature appears with the name
|
||
`sinclude' in SGI `make' and perhaps others.
|
||
|
||
The remaining features are inventions new in GNU `make':
|
||
|
||
* Use the `-v' or `--version' option to print version and copyright
|
||
information.
|
||
|
||
* Use the `-h' or `--help' option to summarize the options to `make'.
|
||
|
||
* Simply-expanded variables. *Note The Two Flavors of Variables:
|
||
Flavors.
|
||
|
||
* Pass command-line variable assignments automatically through the
|
||
variable `MAKE' to recursive `make' invocations. *Note Recursive
|
||
Use of `make': Recursion.
|
||
|
||
* Use the `-C' or `--directory' command option to change directory.
|
||
*Note Summary of Options: Options Summary.
|
||
|
||
* Make verbatim variable definitions with `define'. *Note Defining
|
||
Variables Verbatim: Defining.
|
||
|
||
* Declare phony targets with the special target `.PHONY'.
|
||
|
||
Andrew Hume of AT&T Bell Labs implemented a similar feature with a
|
||
different syntax in his `mk' program. This seems to be a case of
|
||
parallel discovery. *Note Phony Targets: Phony Targets.
|
||
|
||
* Manipulate text by calling functions. *Note Functions for
|
||
Transforming Text: Functions.
|
||
|
||
* Use the `-o' or `--old-file' option to pretend a file's
|
||
modification-time is old. *Note Avoiding Recompilation of Some
|
||
Files: Avoiding Compilation.
|
||
|
||
* Conditional execution.
|
||
|
||
This feature has been implemented numerous times in various
|
||
versions of `make'; it seems a natural extension derived from the
|
||
features of the C preprocessor and similar macro languages and is
|
||
not a revolutionary concept. *Note Conditional Parts of
|
||
Makefiles: Conditionals.
|
||
|
||
* Specify a search path for included makefiles. *Note Including
|
||
Other Makefiles: Include.
|
||
|
||
* Specify extra makefiles to read with an environment variable.
|
||
*Note The Variable `MAKEFILES': MAKEFILES Variable.
|
||
|
||
* Strip leading sequences of `./' from file names, so that `./FILE'
|
||
and `FILE' are considered to be the same file.
|
||
|
||
* Use a special search method for library prerequisites written in
|
||
the form `-lNAME'. *Note Directory Search for Link Libraries:
|
||
Libraries/Search.
|
||
|
||
* Allow suffixes for suffix rules (*note Old-Fashioned Suffix Rules:
|
||
Suffix Rules.) to contain any characters. In other versions of
|
||
`make', they must begin with `.' and not contain any `/'
|
||
characters.
|
||
|
||
* Keep track of the current level of `make' recursion using the
|
||
variable `MAKELEVEL'. *Note Recursive Use of `make': Recursion.
|
||
|
||
* Provide any goals given on the command line in the variable
|
||
`MAKECMDGOALS'. *Note Arguments to Specify the Goals: Goals.
|
||
|
||
* Specify static pattern rules. *Note Static Pattern Rules: Static
|
||
Pattern.
|
||
|
||
* Provide selective `vpath' search. *Note Searching Directories for
|
||
Prerequisites: Directory Search.
|
||
|
||
* Provide computed variable references. *Note Basics of Variable
|
||
References: Reference.
|
||
|
||
* Update makefiles. *Note How Makefiles Are Remade: Remaking
|
||
Makefiles. System V `make' has a very, very limited form of this
|
||
functionality in that it will check out SCCS files for makefiles.
|
||
|
||
* Various new built-in implicit rules. *Note Catalogue of Implicit
|
||
Rules: Catalogue of Rules.
|
||
|
||
* The built-in variable `MAKE_VERSION' gives the version number of
|
||
`make'.
|
||
|
||
|
||
File: make.info, Node: Missing, Next: Makefile Conventions, Prev: Features, Up: Top
|
||
|
||
Incompatibilities and Missing Features
|
||
**************************************
|
||
|
||
The `make' programs in various other systems support a few features
|
||
that are not implemented in GNU `make'. The POSIX.2 standard (`IEEE
|
||
Standard 1003.2-1992') which specifies `make' does not require any of
|
||
these features.
|
||
|
||
* A target of the form `FILE((ENTRY))' stands for a member of
|
||
archive file FILE. The member is chosen, not by name, but by
|
||
being an object file which defines the linker symbol ENTRY.
|
||
|
||
This feature was not put into GNU `make' because of the
|
||
nonmodularity of putting knowledge into `make' of the internal
|
||
format of archive file symbol tables. *Note Updating Archive
|
||
Symbol Directories: Archive Symbols.
|
||
|
||
* Suffixes (used in suffix rules) that end with the character `~'
|
||
have a special meaning to System V `make'; they refer to the SCCS
|
||
file that corresponds to the file one would get without the `~'.
|
||
For example, the suffix rule `.c~.o' would make the file `N.o' from
|
||
the SCCS file `s.N.c'. For complete coverage, a whole series of
|
||
such suffix rules is required. *Note Old-Fashioned Suffix Rules:
|
||
Suffix Rules.
|
||
|
||
In GNU `make', this entire series of cases is handled by two
|
||
pattern rules for extraction from SCCS, in combination with the
|
||
general feature of rule chaining. *Note Chains of Implicit Rules:
|
||
Chained Rules.
|
||
|
||
* In System V `make', the string `$$@' has the strange meaning that,
|
||
in the prerequisites of a rule with multiple targets, it stands
|
||
for the particular target that is being processed.
|
||
|
||
This is not defined in GNU `make' because `$$' should always stand
|
||
for an ordinary `$'.
|
||
|
||
It is possible to get portions of this functionality through the
|
||
use of static pattern rules (*note Static Pattern Rules: Static
|
||
Pattern.). The System V `make' rule:
|
||
|
||
$(targets): $$@.o lib.a
|
||
|
||
can be replaced with the GNU `make' static pattern rule:
|
||
|
||
$(targets): %: %.o lib.a
|
||
|
||
* In System V and 4.3 BSD `make', files found by `VPATH' search
|
||
(*note Searching Directories for Prerequisites: Directory Search.)
|
||
have their names changed inside command strings. We feel it is
|
||
much cleaner to always use automatic variables and thus make this
|
||
feature obsolete.
|
||
|
||
* In some Unix `make's, the automatic variable `$*' appearing in the
|
||
prerequisites of a rule has the amazingly strange "feature" of
|
||
expanding to the full name of the _target of that rule_. We cannot
|
||
imagine what went on in the minds of Unix `make' developers to do
|
||
this; it is utterly inconsistent with the normal definition of
|
||
`$*'.
|
||
|
||
* In some Unix `make's, implicit rule search (*note Using Implicit
|
||
Rules: Implicit Rules.) is apparently done for _all_ targets, not
|
||
just those without commands. This means you can do:
|
||
|
||
foo.o:
|
||
cc -c foo.c
|
||
|
||
and Unix `make' will intuit that `foo.o' depends on `foo.c'.
|
||
|
||
We feel that such usage is broken. The prerequisite properties of
|
||
`make' are well-defined (for GNU `make', at least), and doing such
|
||
a thing simply does not fit the model.
|
||
|
||
* GNU `make' does not include any built-in implicit rules for
|
||
compiling or preprocessing EFL programs. If we hear of anyone who
|
||
is using EFL, we will gladly add them.
|
||
|
||
* It appears that in SVR4 `make', a suffix rule can be specified with
|
||
no commands, and it is treated as if it had empty commands (*note
|
||
Empty Commands::). For example:
|
||
|
||
.c.a:
|
||
|
||
will override the built-in `.c.a' suffix rule.
|
||
|
||
We feel that it is cleaner for a rule without commands to always
|
||
simply add to the prerequisite list for the target. The above
|
||
example can be easily rewritten to get the desired behavior in GNU
|
||
`make':
|
||
|
||
.c.a: ;
|
||
|
||
* Some versions of `make' invoke the shell with the `-e' flag,
|
||
except under `-k' (*note Testing the Compilation of a Program:
|
||
Testing.). The `-e' flag tells the shell to exit as soon as any
|
||
program it runs returns a nonzero status. We feel it is cleaner to
|
||
write each shell command line to stand on its own and not require
|
||
this special treatment.
|
||
|
||
|
||
File: make.info, Node: Makefile Conventions, Next: Quick Reference, Prev: Missing, Up: Top
|
||
|
||
Makefile Conventions
|
||
********************
|
||
|
||
This node describes conventions for writing the Makefiles for GNU
|
||
programs. Using Automake will help you write a Makefile that follows
|
||
these conventions.
|
||
|
||
* Menu:
|
||
|
||
* Makefile Basics:: General Conventions for Makefiles
|
||
* Utilities in Makefiles:: Utilities in Makefiles
|
||
* Command Variables:: Variables for Specifying Commands
|
||
* Directory Variables:: Variables for Installation Directories
|
||
* Standard Targets:: Standard Targets for Users
|
||
* Install Command Categories:: Three categories of commands in the `install'
|
||
rule: normal, pre-install and post-install.
|
||
|
||
|
||
File: make.info, Node: Makefile Basics, Next: Utilities in Makefiles, Up: Makefile Conventions
|
||
|
||
General Conventions for Makefiles
|
||
=================================
|
||
|
||
Every Makefile should contain this line:
|
||
|
||
SHELL = /bin/sh
|
||
|
||
to avoid trouble on systems where the `SHELL' variable might be
|
||
inherited from the environment. (This is never a problem with GNU
|
||
`make'.)
|
||
|
||
Different `make' programs have incompatible suffix lists and
|
||
implicit rules, and this sometimes creates confusion or misbehavior. So
|
||
it is a good idea to set the suffix list explicitly using only the
|
||
suffixes you need in the particular Makefile, like this:
|
||
|
||
.SUFFIXES:
|
||
.SUFFIXES: .c .o
|
||
|
||
The first line clears out the suffix list, the second introduces all
|
||
suffixes which may be subject to implicit rules in this Makefile.
|
||
|
||
Don't assume that `.' is in the path for command execution. When
|
||
you need to run programs that are a part of your package during the
|
||
make, please make sure that it uses `./' if the program is built as
|
||
part of the make or `$(srcdir)/' if the file is an unchanging part of
|
||
the source code. Without one of these prefixes, the current search
|
||
path is used.
|
||
|
||
The distinction between `./' (the "build directory") and
|
||
`$(srcdir)/' (the "source directory") is important because users can
|
||
build in a separate directory using the `--srcdir' option to
|
||
`configure'. A rule of the form:
|
||
|
||
foo.1 : foo.man sedscript
|
||
sed -e sedscript foo.man > foo.1
|
||
|
||
will fail when the build directory is not the source directory, because
|
||
`foo.man' and `sedscript' are in the the source directory.
|
||
|
||
When using GNU `make', relying on `VPATH' to find the source file
|
||
will work in the case where there is a single dependency file, since
|
||
the `make' automatic variable `$<' will represent the source file
|
||
wherever it is. (Many versions of `make' set `$<' only in implicit
|
||
rules.) A Makefile target like
|
||
|
||
foo.o : bar.c
|
||
$(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
|
||
|
||
should instead be written as
|
||
|
||
foo.o : bar.c
|
||
$(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@
|
||
|
||
in order to allow `VPATH' to work correctly. When the target has
|
||
multiple dependencies, using an explicit `$(srcdir)' is the easiest way
|
||
to make the rule work well. For example, the target above for `foo.1'
|
||
is best written as:
|
||
|
||
foo.1 : foo.man sedscript
|
||
sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@
|
||
|
||
GNU distributions usually contain some files which are not source
|
||
files--for example, Info files, and the output from Autoconf, Automake,
|
||
Bison or Flex. Since these files normally appear in the source
|
||
directory, they should always appear in the source directory, not in the
|
||
build directory. So Makefile rules to update them should put the
|
||
updated files in the source directory.
|
||
|
||
However, if a file does not appear in the distribution, then the
|
||
Makefile should not put it in the source directory, because building a
|
||
program in ordinary circumstances should not modify the source directory
|
||
in any way.
|
||
|
||
Try to make the build and installation targets, at least (and all
|
||
their subtargets) work correctly with a parallel `make'.
|
||
|
||
|
||
File: make.info, Node: Utilities in Makefiles, Next: Command Variables, Prev: Makefile Basics, Up: Makefile Conventions
|
||
|
||
Utilities in Makefiles
|
||
======================
|
||
|
||
Write the Makefile commands (and any shell scripts, such as
|
||
`configure') to run in `sh', not in `csh'. Don't use any special
|
||
features of `ksh' or `bash'.
|
||
|
||
The `configure' script and the Makefile rules for building and
|
||
installation should not use any utilities directly except these:
|
||
|
||
cat cmp cp diff echo egrep expr false grep install-info
|
||
ln ls mkdir mv pwd rm rmdir sed sleep sort tar test touch true
|
||
|
||
The compression program `gzip' can be used in the `dist' rule.
|
||
|
||
Stick to the generally supported options for these programs. For
|
||
example, don't use `mkdir -p', convenient as it may be, because most
|
||
systems don't support it.
|
||
|
||
It is a good idea to avoid creating symbolic links in makefiles,
|
||
since a few systems don't support them.
|
||
|
||
The Makefile rules for building and installation can also use
|
||
compilers and related programs, but should do so via `make' variables
|
||
so that the user can substitute alternatives. Here are some of the
|
||
programs we mean:
|
||
|
||
ar bison cc flex install ld ldconfig lex
|
||
make makeinfo ranlib texi2dvi yacc
|
||
|
||
Use the following `make' variables to run those programs:
|
||
|
||
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
|
||
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
|
||
|
||
When you use `ranlib' or `ldconfig', you should make sure nothing
|
||
bad happens if the system does not have the program in question.
|
||
Arrange to ignore an error from that command, and print a message before
|
||
the command to tell the user that failure of this command does not mean
|
||
a problem. (The Autoconf `AC_PROG_RANLIB' macro can help with this.)
|
||
|
||
If you use symbolic links, you should implement a fallback for
|
||
systems that don't have symbolic links.
|
||
|
||
Additional utilities that can be used via Make variables are:
|
||
|
||
chgrp chmod chown mknod
|
||
|
||
It is ok to use other utilities in Makefile portions (or scripts)
|
||
intended only for particular systems where you know those utilities
|
||
exist.
|
||
|
||
|
||
File: make.info, Node: Command Variables, Next: Directory Variables, Prev: Utilities in Makefiles, Up: Makefile Conventions
|
||
|
||
Variables for Specifying Commands
|
||
=================================
|
||
|
||
Makefiles should provide variables for overriding certain commands,
|
||
options, and so on.
|
||
|
||
In particular, you should run most utility programs via variables.
|
||
Thus, if you use Bison, have a variable named `BISON' whose default
|
||
value is set with `BISON = bison', and refer to it with `$(BISON)'
|
||
whenever you need to use Bison.
|
||
|
||
File management utilities such as `ln', `rm', `mv', and so on, need
|
||
not be referred to through variables in this way, since users don't
|
||
need to replace them with other programs.
|
||
|
||
Each program-name variable should come with an options variable that
|
||
is used to supply options to the program. Append `FLAGS' to the
|
||
program-name variable name to get the options variable name--for
|
||
example, `BISONFLAGS'. (The names `CFLAGS' for the C compiler,
|
||
`YFLAGS' for yacc, and `LFLAGS' for lex, are exceptions to this rule,
|
||
but we keep them because they are standard.) Use `CPPFLAGS' in any
|
||
compilation command that runs the preprocessor, and use `LDFLAGS' in
|
||
any compilation command that does linking as well as in any direct use
|
||
of `ld'.
|
||
|
||
If there are C compiler options that _must_ be used for proper
|
||
compilation of certain files, do not include them in `CFLAGS'. Users
|
||
expect to be able to specify `CFLAGS' freely themselves. Instead,
|
||
arrange to pass the necessary options to the C compiler independently
|
||
of `CFLAGS', by writing them explicitly in the compilation commands or
|
||
by defining an implicit rule, like this:
|
||
|
||
CFLAGS = -g
|
||
ALL_CFLAGS = -I. $(CFLAGS)
|
||
.c.o:
|
||
$(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
|
||
|
||
Do include the `-g' option in `CFLAGS', because that is not
|
||
_required_ for proper compilation. You can consider it a default that
|
||
is only recommended. If the package is set up so that it is compiled
|
||
with GCC by default, then you might as well include `-O' in the default
|
||
value of `CFLAGS' as well.
|
||
|
||
Put `CFLAGS' last in the compilation command, after other variables
|
||
containing compiler options, so the user can use `CFLAGS' to override
|
||
the others.
|
||
|
||
`CFLAGS' should be used in every invocation of the C compiler, both
|
||
those which do compilation and those which do linking.
|
||
|
||
Every Makefile should define the variable `INSTALL', which is the
|
||
basic command for installing a file into the system.
|
||
|
||
Every Makefile should also define the variables `INSTALL_PROGRAM'
|
||
and `INSTALL_DATA'. (The default for each of these should be
|
||
`$(INSTALL)'.) Then it should use those variables as the commands for
|
||
actual installation, for executables and nonexecutables respectively.
|
||
Use these variables as follows:
|
||
|
||
$(INSTALL_PROGRAM) foo $(bindir)/foo
|
||
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
|
||
|
||
Optionally, you may prepend the value of `DESTDIR' to the target
|
||
filename. Doing this allows the installer to create a snapshot of the
|
||
installation to be copied onto the real target filesystem later. Do not
|
||
set the value of `DESTDIR' in your Makefile, and do not include it in
|
||
any installed files. With support for `DESTDIR', the above examples
|
||
become:
|
||
|
||
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
|
||
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
|
||
|
||
Always use a file name, not a directory name, as the second argument of
|
||
the installation commands. Use a separate command for each file to be
|
||
installed.
|
||
|
||
|
||
File: make.info, Node: Directory Variables, Next: Standard Targets, Prev: Command Variables, Up: Makefile Conventions
|
||
|
||
Variables for Installation Directories
|
||
======================================
|
||
|
||
Installation directories should always be named by variables, so it
|
||
is easy to install in a nonstandard place. The standard names for these
|
||
variables are described below. They are based on a standard filesystem
|
||
layout; variants of it are used in SVR4, 4.4BSD, Linux, Ultrix v4, and
|
||
other modern operating systems.
|
||
|
||
These two variables set the root for the installation. All the other
|
||
installation directories should be subdirectories of one of these two,
|
||
and nothing should be directly installed into these two directories.
|
||
|
||
`prefix'
|
||
A prefix used in constructing the default values of the variables
|
||
listed below. The default value of `prefix' should be
|
||
`/usr/local'. When building the complete GNU system, the prefix
|
||
will be empty and `/usr' will be a symbolic link to `/'. (If you
|
||
are using Autoconf, write it as `@prefix@'.)
|
||
|
||
Running `make install' with a different value of `prefix' from the
|
||
one used to build the program should NOT recompile the program.
|
||
|
||
`exec_prefix'
|
||
A prefix used in constructing the default values of some of the
|
||
variables listed below. The default value of `exec_prefix' should
|
||
be `$(prefix)'. (If you are using Autoconf, write it as
|
||
`@exec_prefix@'.)
|
||
|
||
Generally, `$(exec_prefix)' is used for directories that contain
|
||
machine-specific files (such as executables and subroutine
|
||
libraries), while `$(prefix)' is used directly for other
|
||
directories.
|
||
|
||
Running `make install' with a different value of `exec_prefix'
|
||
from the one used to build the program should NOT recompile the
|
||
program.
|
||
|
||
Executable programs are installed in one of the following
|
||
directories.
|
||
|
||
`bindir'
|
||
The directory for installing executable programs that users can
|
||
run. This should normally be `/usr/local/bin', but write it as
|
||
`$(exec_prefix)/bin'. (If you are using Autoconf, write it as
|
||
`@bindir@'.)
|
||
|
||
`sbindir'
|
||
The directory for installing executable programs that can be run
|
||
from the shell, but are only generally useful to system
|
||
administrators. This should normally be `/usr/local/sbin', but
|
||
write it as `$(exec_prefix)/sbin'. (If you are using Autoconf,
|
||
write it as `@sbindir@'.)
|
||
|
||
`libexecdir'
|
||
The directory for installing executable programs to be run by other
|
||
programs rather than by users. This directory should normally be
|
||
`/usr/local/libexec', but write it as `$(exec_prefix)/libexec'.
|
||
(If you are using Autoconf, write it as `@libexecdir@'.)
|
||
|
||
Data files used by the program during its execution are divided into
|
||
categories in two ways.
|
||
|
||
* Some files are normally modified by programs; others are never
|
||
normally modified (though users may edit some of these).
|
||
|
||
* Some files are architecture-independent and can be shared by all
|
||
machines at a site; some are architecture-dependent and can be
|
||
shared only by machines of the same kind and operating system;
|
||
others may never be shared between two machines.
|
||
|
||
This makes for six different possibilities. However, we want to
|
||
discourage the use of architecture-dependent files, aside from object
|
||
files and libraries. It is much cleaner to make other data files
|
||
architecture-independent, and it is generally not hard.
|
||
|
||
Therefore, here are the variables Makefiles should use to specify
|
||
directories:
|
||
|
||
`datadir'
|
||
The directory for installing read-only architecture independent
|
||
data files. This should normally be `/usr/local/share', but write
|
||
it as `$(prefix)/share'. (If you are using Autoconf, write it as
|
||
`@datadir@'.) As a special exception, see `$(infodir)' and
|
||
`$(includedir)' below.
|
||
|
||
`sysconfdir'
|
||
The directory for installing read-only data files that pertain to a
|
||
single machine-that is to say, files for configuring a host.
|
||
Mailer and network configuration files, `/etc/passwd', and so
|
||
forth belong here. All the files in this directory should be
|
||
ordinary ASCII text files. This directory should normally be
|
||
`/usr/local/etc', but write it as `$(prefix)/etc'. (If you are
|
||
using Autoconf, write it as `@sysconfdir@'.)
|
||
|
||
Do not install executables here in this directory (they probably
|
||
belong in `$(libexecdir)' or `$(sbindir)'). Also do not install
|
||
files that are modified in the normal course of their use (programs
|
||
whose purpose is to change the configuration of the system
|
||
excluded). Those probably belong in `$(localstatedir)'.
|
||
|
||
`sharedstatedir'
|
||
The directory for installing architecture-independent data files
|
||
which the programs modify while they run. This should normally be
|
||
`/usr/local/com', but write it as `$(prefix)/com'. (If you are
|
||
using Autoconf, write it as `@sharedstatedir@'.)
|
||
|
||
`localstatedir'
|
||
The directory for installing data files which the programs modify
|
||
while they run, and that pertain to one specific machine. Users
|
||
should never need to modify files in this directory to configure
|
||
the package's operation; put such configuration information in
|
||
separate files that go in `$(datadir)' or `$(sysconfdir)'.
|
||
`$(localstatedir)' should normally be `/usr/local/var', but write
|
||
it as `$(prefix)/var'. (If you are using Autoconf, write it as
|
||
`@localstatedir@'.)
|
||
|
||
`libdir'
|
||
The directory for object files and libraries of object code. Do
|
||
not install executables here, they probably ought to go in
|
||
`$(libexecdir)' instead. The value of `libdir' should normally be
|
||
`/usr/local/lib', but write it as `$(exec_prefix)/lib'. (If you
|
||
are using Autoconf, write it as `@libdir@'.)
|
||
|
||
`infodir'
|
||
The directory for installing the Info files for this package. By
|
||
default, it should be `/usr/local/info', but it should be written
|
||
as `$(prefix)/info'. (If you are using Autoconf, write it as
|
||
`@infodir@'.)
|
||
|
||
`lispdir'
|
||
The directory for installing any Emacs Lisp files in this package.
|
||
By default, it should be `/usr/local/share/emacs/site-lisp', but
|
||
it should be written as `$(prefix)/share/emacs/site-lisp'.
|
||
|
||
If you are using Autoconf, write the default as `@lispdir@'. In
|
||
order to make `@lispdir@' work, you need the following lines in
|
||
your `configure.in' file:
|
||
|
||
lispdir='${datadir}/emacs/site-lisp'
|
||
AC_SUBST(lispdir)
|
||
|
||
`includedir'
|
||
The directory for installing header files to be included by user
|
||
programs with the C `#include' preprocessor directive. This
|
||
should normally be `/usr/local/include', but write it as
|
||
`$(prefix)/include'. (If you are using Autoconf, write it as
|
||
`@includedir@'.)
|
||
|
||
Most compilers other than GCC do not look for header files in
|
||
directory `/usr/local/include'. So installing the header files
|
||
this way is only useful with GCC. Sometimes this is not a problem
|
||
because some libraries are only really intended to work with GCC.
|
||
But some libraries are intended to work with other compilers.
|
||
They should install their header files in two places, one
|
||
specified by `includedir' and one specified by `oldincludedir'.
|
||
|
||
`oldincludedir'
|
||
The directory for installing `#include' header files for use with
|
||
compilers other than GCC. This should normally be `/usr/include'.
|
||
(If you are using Autoconf, you can write it as `@oldincludedir@'.)
|
||
|
||
The Makefile commands should check whether the value of
|
||
`oldincludedir' is empty. If it is, they should not try to use
|
||
it; they should cancel the second installation of the header files.
|
||
|
||
A package should not replace an existing header in this directory
|
||
unless the header came from the same package. Thus, if your Foo
|
||
package provides a header file `foo.h', then it should install the
|
||
header file in the `oldincludedir' directory if either (1) there
|
||
is no `foo.h' there or (2) the `foo.h' that exists came from the
|
||
Foo package.
|
||
|
||
To tell whether `foo.h' came from the Foo package, put a magic
|
||
string in the file--part of a comment--and `grep' for that string.
|
||
|
||
Unix-style man pages are installed in one of the following:
|
||
|
||
`mandir'
|
||
The top-level directory for installing the man pages (if any) for
|
||
this package. It will normally be `/usr/local/man', but you should
|
||
write it as `$(prefix)/man'. (If you are using Autoconf, write it
|
||
as `@mandir@'.)
|
||
|
||
`man1dir'
|
||
The directory for installing section 1 man pages. Write it as
|
||
`$(mandir)/man1'.
|
||
|
||
`man2dir'
|
||
The directory for installing section 2 man pages. Write it as
|
||
`$(mandir)/man2'
|
||
|
||
`...'
|
||
*Don't make the primary documentation for any GNU software be a
|
||
man page. Write a manual in Texinfo instead. Man pages are just
|
||
for the sake of people running GNU software on Unix, which is a
|
||
secondary application only.*
|
||
|
||
`manext'
|
||
The file name extension for the installed man page. This should
|
||
contain a period followed by the appropriate digit; it should
|
||
normally be `.1'.
|
||
|
||
`man1ext'
|
||
The file name extension for installed section 1 man pages.
|
||
|
||
`man2ext'
|
||
The file name extension for installed section 2 man pages.
|
||
|
||
`...'
|
||
Use these names instead of `manext' if the package needs to
|
||
install man pages in more than one section of the manual.
|
||
|
||
And finally, you should set the following variable:
|
||
|
||
`srcdir'
|
||
The directory for the sources being compiled. The value of this
|
||
variable is normally inserted by the `configure' shell script.
|
||
(If you are using Autconf, use `srcdir = @srcdir@'.)
|
||
|
||
For example:
|
||
|
||
# Common prefix for installation directories.
|
||
# NOTE: This directory must exist when you start the install.
|
||
prefix = /usr/local
|
||
exec_prefix = $(prefix)
|
||
# Where to put the executable for the command `gcc'.
|
||
bindir = $(exec_prefix)/bin
|
||
# Where to put the directories used by the compiler.
|
||
libexecdir = $(exec_prefix)/libexec
|
||
# Where to put the Info files.
|
||
infodir = $(prefix)/info
|
||
|
||
If your program installs a large number of files into one of the
|
||
standard user-specified directories, it might be useful to group them
|
||
into a subdirectory particular to that program. If you do this, you
|
||
should write the `install' rule to create these subdirectories.
|
||
|
||
Do not expect the user to include the subdirectory name in the value
|
||
of any of the variables listed above. The idea of having a uniform set
|
||
of variable names for installation directories is to enable the user to
|
||
specify the exact same values for several different GNU packages. In
|
||
order for this to be useful, all the packages must be designed so that
|
||
they will work sensibly when the user does so.
|
||
|