make-stds.texi

autoconf 2.59版,可用于redhat系统.用于编译原码,编写makefile文件.

@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 1992, 1993, 1994, 1995, 1996, 1997, 1998, 2000, 2001 Free
@c 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 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.
@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.  Use these variables as follows:

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

Optionally, you may prepend the value of @code{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 @code{DESTDIR} in your Makefile, and do not include it
in any installed files.  With support for @code{DESTDIR}, the above
examples become:

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

@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 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 are described below.  They are based on a standard filesystem
layout; variants of it are used in SVR4, 4.4BSD, GNU/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.

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

@item exec_prefix
@vindex exec_prefix
A prefix used in constructing the default values of some of the
variables listed below.  The default value of @code{exec_prefix} should
be @code{$(prefix)}.
(If you are using Autoconf, write it as @samp{@@exec_prefix@@}.)

Generally, @code{$(exec_prefix)} is used for directories that contain
machine-specific files (such as executables and subroutine libraries),
while @code{$(prefix)} is used directly for other directories.