make-stds.texi

autoconf是一个产生可以自动配置源代码包

@comment This file is included by both standards.texi and make.texinfo.
@comment It was broken out of standards.texi on 1/6/93 by roland.

@node Makefile Conventions
@chapter Makefile Conventions
@comment standards.texi does not print an index, but make.texinfo does.
@cindex makefile, conventions for
@cindex conventions for makefiles
@cindex standards for makefiles

@c Copyright (C) 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001,
@c 2004, 2005, 2006 Free Software Foundation, Inc.

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

This
@ifinfo
node
@end ifinfo
@iftex
@ifset CODESTD
section
@end ifset
@ifclear CODESTD
chapter
@end ifclear
@end iftex
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 to be used in Makefiles.
* Command Variables::           Variables for specifying commands.
* Directory Variables::         Variables for installation directories.
* DESTDIR::                     Supporting staged installs.
* Standard Targets::            Standard targets for users.
* Install Command Categories::  Three categories of commands in the `install'
                                  rule: normal, pre-install and post-install.
@end menu

@node Makefile Basics
@section General Conventions for Makefiles

Every Makefile should contain this line:

@example
SHELL = /bin/sh
@end example

@noindent
to avoid trouble on systems where the @code{SHELL} variable might be
inherited from the environment.  (This is never a problem with GNU
@code{make}.)

Different @code{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:

@example
.SUFFIXES:
.SUFFIXES: .c .o
@end example

@noindent
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 @file{.} 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 @file{./} if the program is built as
part of the make or @file{$(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 @file{./} (the @dfn{build directory}) and
@file{$(srcdir)/} (the @dfn{source directory}) is important because
users can build in a separate directory using the @samp{--srcdir} option
to @file{configure}.  A rule of the form:

@smallexample
foo.1 : foo.man sedscript
        sed -e sedscript foo.man > foo.1
@end smallexample

@noindent
will fail when the build directory is not the source directory, because
@file{foo.man} and @file{sedscript} are in the source directory.

When using GNU @code{make}, relying on @samp{VPATH} to find the source
file will work in the case where there is a single dependency file,
since the @code{make} automatic variable @samp{$<} will represent the
source file wherever it is.  (Many versions of @code{make} set @samp{$<}
only in implicit rules.)  A Makefile target like

@smallexample
foo.o : bar.c
        $(CC) -I. -I$(srcdir) $(CFLAGS) -c bar.c -o foo.o
@end smallexample

@noindent
should instead be written as

@smallexample
foo.o : bar.c
        $(CC) -I. -I$(srcdir) $(CFLAGS) -c $< -o $@@
@end smallexample

@noindent
in order to allow @samp{VPATH} to work correctly.  When the target has
multiple dependencies, using an explicit @samp{$(srcdir)} is the easiest
way to make the rule work well.  For example, the target above for
@file{foo.1} is best written as:

@smallexample
foo.1 : foo.man sedscript
        sed -e $(srcdir)/sedscript $(srcdir)/foo.man > $@@
@end smallexample

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 @code{make}.

@node Utilities in Makefiles
@section Utilities in Makefiles

Write the Makefile commands (and any shell scripts, such as
@code{configure}) to run in @code{sh}, not in @code{csh}.  Don't use any
special features of @code{ksh} or @code{bash}.

The @code{configure} script and the Makefile rules for building and
installation should not use any utilities directly except these:

@c dd find
@c gunzip gzip md5sum
@c mkfifo mknod tee uname

@example
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
@end example

The compression program @code{gzip} can be used in the @code{dist} rule.

Stick to the generally supported options for these programs.  For
example, don't use @samp{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 @code{make} variables so that the
user can substitute alternatives.  Here are some of the programs we
mean:

@example
ar bison cc flex install ld ldconfig lex
make makeinfo ranlib texi2dvi yacc
@end example

Use the following @code{make} variables to run those programs:

@example
$(AR) $(BISON) $(CC) $(FLEX) $(INSTALL) $(LD) $(LDCONFIG) $(LEX)
$(MAKE) $(MAKEINFO) $(RANLIB) $(TEXI2DVI) $(YACC)
@end example

When you use @code{ranlib} or @code{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 @samp{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:

@example
chgrp chmod chown mknod
@end example

It is ok to use other utilities in Makefile portions (or scripts)
intended only for particular systems where you know those utilities
exist.

@node Command Variables
@section 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 @code{BISON} whose default
value is set with @samp{BISON = bison}, and refer to it with
@code{$(BISON)} whenever you need to use Bison.

File management utilities such as @code{ln}, @code{rm}, @code{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 @samp{FLAGS} to the
program-name variable name to get the options variable name---for
example, @code{BISONFLAGS}.  (The names @code{CFLAGS} for the C
compiler, @code{YFLAGS} for yacc, and @code{LFLAGS} for lex, are
exceptions to this rule, but we keep them because they are standard.)
Use @code{CPPFLAGS} in any compilation command that runs the
preprocessor, and use @code{LDFLAGS} in any compilation command that
does linking as well as in any direct use of @code{ld}.

If there are C compiler options that @emph{must} be used for proper
compilation of certain files, do not include them in @code{CFLAGS}.
Users expect to be able to specify @code{CFLAGS} freely themselves.
Instead, arrange to pass the necessary options to the C compiler
independently of @code{CFLAGS}, by writing them explicitly in the
compilation commands or by defining an implicit rule, like this:

@smallexample
CFLAGS = -g
ALL_CFLAGS = -I. $(CFLAGS)
.c.o:
        $(CC) -c $(CPPFLAGS) $(ALL_CFLAGS) $<
@end smallexample

Do include the @samp{-g} option in @code{CFLAGS}, because that is not
@emph{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 @samp{-O}
in the default value of @code{CFLAGS} as well.

Put @code{CFLAGS} last in the compilation command, after other variables
containing compiler options, so the user can use @code{CFLAGS} to
override the others.

@code{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 @code{INSTALL}, which is the
basic command for installing a file into the system.

Every Makefile should also define the variables @code{INSTALL_PROGRAM}
and @code{INSTALL_DATA}.  (The default for @code{INSTALL_PROGRAM} should
be @code{$(INSTALL)}; the default for @code{INSTALL_DATA} should be
@code{$@{INSTALL@} -m 644}.)  Then it should use those variables as the
commands for actual installation, for executables and nonexecutables
respectively.  Minimal use of these variables is as follows:

@example
$(INSTALL_PROGRAM) foo $(bindir)/foo
$(INSTALL_DATA) libfoo.a $(libdir)/libfoo.a
@end example

However, it is preferable to support a @code{DESTDIR} prefix on the
target files, as explained in the next section.

@noindent
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.


@node DESTDIR
@section @code{DESTDIR}: support for staged installs

@vindex DESTDIR
@cindex staged installs
@cindex installations, staged

@code{DESTDIR} is a variable prepended to each installed target file,
like this:

@example
$(INSTALL_PROGRAM) foo $(DESTDIR)$(bindir)/foo
$(INSTALL_DATA) libfoo.a $(DESTDIR)$(libdir)/libfoo.a
@end example

The @code{DESTDIR} variable is specified by the user, either to the
@file{configure} script or, more commonly, on the @code{make} command
line.  For example:

@example
make DESTDIR=/tmp/stage install
@end example

@noindent
(Since the value of @code{DESTDIR} is only used during installation it
is not necessary to provide it with other @code{make} commands.)

If your installation step would normally install
@file{/usr/local/bin/foo} and @file{/usr/local/lib/libfoo.a}, then an
installation invoked as in the example above would install
@file{/tmp/stage/usr/local/bin/foo} and
@file{/tmp/stage/usr/local/lib/libfoo.a} instead.

Prepending the variable @code{DESTDIR} to each target in this way
provides for @dfn{staged installs}, where the installed files are not
placed directly into their expected location but are instead copied
into a temporary location (@code{DESTDIR}).  However, installed files
maintain their relative directory structure and any embedded file names
will not be modified.

You should not set the value of @code{DESTDIR} in your @file{Makefile}
at all; then the files are installed into their expected locations by
default.  Also, specifying @code{DESTDIR} should not change the
operation of the software in any way, so its value should not be
included in any file contents.

@code{DESTDIR} support is commonly used in package creation.  It is
also helpful to users who want to understand what a given package will
install where, and to allow users who don't normally have permissions
to install into protected areas to build and install before gaining
those permissions.  Finally, it can be useful with tools such as
@code{stow}, where code is installed in one place but made to appear
to be installed somewhere else using symbolic links or special mount
operations.  So, we recommend GNU packages support @code{DESTDIR},
though it is not an absolute requirement.


@node Directory Variables
@section 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 and the values they should have in GNU packages are
described below.  They are based on a standard file system layout;
variants of it are used in GNU/Linux and other modern operating
systems.

Installers are expected to override these values when calling
@command{make} (e.g., @kbd{make prefix=/usr install} or
@command{configure} (e.g., @kbd{configure --prefix=/usr}).  GNU
packages should not try to guess which value should be appropriate for
these variables on the system they are being installed onto: use the
default settings specified here so that all GNU packages behave
identically, allowing the installer to achieve any desired layout.

These first 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.

@table @code
@item prefix
@vindex prefix
A prefix used in constructing the default values of the variables listed
below.  The default value of @code{prefix} should be @file{/usr/local}.
When building the complete GNU system, the prefix will be empty and
@file{/usr} will be a symbolic link to @file{/}.
(If you are using Autoconf, write it as @samp{@@prefix@@}.)

Running @samp{make install} with a different value of @code{prefix} from
the one used to build the program should @emph{not} recompile the
program.