standards.texi

早期freebsd实现

Delete @file{.dvi} files here if they are not part of the distribution.

@item distclean
Delete all files from the current directory that are created by
configuring or building the program.  If you have unpacked the source
and built the program without creating any other files, @samp{make
distclean} should leave only the files that were in the distribution.

@item mostlyclean
Like @samp{clean}, but may refrain from deleting a few files that people
normally don't want to recompile.  For example, the @samp{mostlyclean}
target for GCC does not delete @file{libgcc.a}, because recompiling it
is rarely necessary and takes a lot of time.

@item realclean
Delete everything from the current directory that can be reconstructed
with this Makefile.  This typically includes everything deleted by
distclean, plus more: C source files produced by Bison, tags tables,
info files, and so on.

@item TAGS
Update a tags table for this program.

@item dist
Create a distribution tar file for this program.  The tar file should be
set up so that the file names in the tar file start with a subdirectory
name which is the name of the package it is a distribution for.  This
name can include the version number.

For example, the distribution tar file of GCC version 1.40 unpacks into
a subdirectory named @file{gcc-1.40}.

The easiest way to do this is to create a subdirectory appropriately
named, use @code{ln} or @code{cp} to install the proper files in it, and
then @code{tar} that subdirectory.

The @code{dist} target should explicitly depend on all non-source files
that are in the distribution, to make sure they are up to date in the
distribution.  @xref{Releases}.

@item check
Perform self-tests (if any).  The user must build the program before
running the tests, but need not install the program; you should write
the self-tests so that they work when the program is built but not
installed.
@end table

@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 name @code{CFLAGS} is an exception to
this rule, but we keep it because it is 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:

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

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.

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 variables @code{INSTALL_PROGRAM} and
@code{INSTALL_DATA}.  (The default for each of these should be
@code{$(INSTALL)}.)  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

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

@table @samp
@item 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}
(at least for now).

@item exec_prefix
A prefix used in constructing the default values of the some of the
variables listed below.  The default value of @code{exec_prefix} should
be @code{$(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.

@item bindir
The directory for installing executable programs that users can run.
This should normally be @file{/usr/local/bin}, but it should be written
as @file{$(exec_prefix)/bin}.

@item libdir
The directory for installing executable files to be run by the program
rather than by users.  Object files and libraries of object code should
also go in this directory.  The idea is that this directory is used for
files that pertain to a specific machine architecture, but need not be
in the path for commands.  The value of @code{libdir} should normally be
@file{/usr/local/lib}, but it should be written as
@file{$(exec_prefix)/lib}.

@item datadir
The directory for installing read-only data files which the programs
refer to while they run.  This directory is used for files which are
independent of the type of machine being used.  This should normally be
@file{/usr/local/lib}, but it should be written as
@file{$(prefix)/lib}.

@item statedir
The directory for installing data files which the programs modify while
they run.  These files should be independent of the type of machine
being used, and it should be possible to share them among machines at a
network installation.  This should normally be @file{/usr/local/lib},
but it should be written as @file{$(prefix)/lib}.

@item includedir
The directory for installing @samp{#include} header files to be included
by user programs.  This should normally be @file{/usr/local/include},
but it should be written as @file{$(prefix)/include}.

Most compilers other than GCC do not look for header files in
@file{/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 @code{includedir} and one
specified by @code{oldincludedir}.

@item oldincludedir
The directory for installing @samp{#include} header files for use with
compilers other than GCC.  This should normally be @file{/usr/include}.

The Makefile commands should check whether the value of
@code{oldincludedir} is empty.  If it is, they should not try to use
it; they should cancel the second installation of the header files.

@item mandir
The directory for installing the man pages (if any) for this package.
It should include the suffix for the proper section of the
manual---usually @samp{1} for a utility.

@item man1dir
The directory for installing section 1 man pages.
@item man2dir
The directory for installing section 2 man pages.
@item @dots{}
Use these names instead of @samp{mandir} if the package needs to install man
pages in more than one section of the manual.

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

@item manext
The file name extension for the installed man page.  This should contain
a period followed by the appropriate digit.

@item infodir
The directory for installing the info files for this package.  By
default, it should be @file{/usr/local/info}, but it should be written
as @file{$(prefix)/info}.

@item srcdir
The directory for the sources being compiled.  The value of this
variable is normally inserted by the @code{configure} shell script.
@end table

For example:

@example
# Common prefix for installation directories.
# NOTE: This directory must exist when you start installation.
prefix = /usr/local
exec_prefix = $(prefix)
# Directory in which to put the executable for the command `gcc'
bindir = $(exec_prefix)/bin
# Directory in which to put the directories used by the compiler.
libdir = $(exec_prefix)/lib
# Directory in which to put the Info files.
infodir = $(prefix)/info
@end example

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

@node Configuration
@chapter How Configuration Should Work

Each GNU distribution should come with a shell script named
@code{configure}.  This script is given arguments which describe the
kind of machine and system you want to compile the program for.

The @code{configure} script must record the configuration options so
that they affect compilation.

One way to do this is to make a link from a standard name such as
@file{config.h} to the proper configuration file for the chosen system.
If you use this technique, the distribution should @emph{not} contain a
file named @file{config.h}.  This is so that people won't be able to
build the program without configuring it first.

Another thing that @code{configure} can do is to edit the Makefile.  If
you do this, the distribution should @emph{not} contain a file named
@file{Makefile}.  Instead, include a file @file{Makefile.in} which
contains the input used for editing.  Once again, this is so that people
won't be able to build the program without configuring it first.

If @code{configure} does write the @file{Makefile}, then @file{Makefile}
should have a target named @file{Makefile} which causes @code{configure}
to be rerun, setting up the same configuration that was set up last
time.  The files that @code{configure} reads should be listed as
dependencies of @file{Makefile}.

All the files which are output from the @code{configure} script should
have comments at the beginning explaining that they were generated
automatically using @code{configure}.  This is so that users won't think
of trying to edit them by hand.

The @code{configure} script should write a file named @file{config.status}
which describes which configuration options were specified when the
program was last configured.  This file should be a shell script which,
if run, will recreate the same configuration.

The @code{configure} script should accept an option of the form
@samp{--srcdir=@var{dirname}} to specify the directory where sources are found
(if it is not the current directory).  This makes it possible to build
the program in a separate directory, so that the actual source directory
is not modified.

If the user does not specify @samp{--srcdir}, then @code{configure} should
check both @file{.} and @file{..} to see if it can find the sources.  If
it finds the sources in one of these places, it should use them from
there.  Otherwise, it should report that it cannot find the sources, and
should exit with nonzero status.

Usually the easy way to support @samp{--srcdir} is by editing a
definition of @code{VPATH} into the Makefile.  Some rules may need to
refer explicitly to the specified source directory.  To make this
possible, @code{configure} can add to the Makefile a variable named
@code{srcdir} whose value is precisely the specified directory.

The @code{configure} script should also take an argument which specifies the
type of system to build the program for.  This argument should look like
this:

@example
@var{cpu}-@var{company}-@var{system}
@end example

For example, a Sun 3 might be @samp{m68k-sun-sunos4.1}.

The @code{configure} script needs to be able to decode all plausible
alternatives for how to describe a machine.  Thus, @samp{sun3-sunos4.1}
would be a valid alias.  So would @samp{sun3-bsd4.2}, since SunOS is
basically @sc{BSD} and no other @sc{BSD} system is used on a Sun.  For many
programs, @samp{vax-dec-ultrix} would be an alias for
@samp{vax-dec-bsd}, simply because the differences between Ultrix and
@sc{BSD} are rarely noticeable, but a few programs might need to distinguish
them.

There is a shell script called @file{config.sub} that you can use
as a subroutine to validate system types and canonicalize aliases.

Other options are permitted to specify in more detail the software
or hardware are present on the machine:

@table @samp
@item --with-@var{package}
The package @var{package} will be installed, so configure this package
to work with @var{package}.

Possible values of @var{package} include @samp{x}, @samp{gnu-as} (or
@samp{gas}), @samp{gnu-ld}, @samp{gnu-libc}, and @samp{gdb}.

@item --nfp
The target machine has no floating point processor.

@item --gas
The target machine assembler is GAS, the GNU assembler.
This is obsolete; use @samp{--with-gnu-as} instead.

@item --x
The target machine has the X Window system installed.
This is obsolete; use @samp{--with-x} instead.
@end table

All @code{configure} scripts should accept all of these ``detail''
options, whether or not they make any difference to the particular
package at hand.  In particular, they should accept any option that
starts with @samp{--with-}.  This is so users will be able to configure
an entire GNU source tree at once with a single set of options.

Packages that perform part of compilation may support cross-compilation.
In such a case, the host and target machines for the program may be
different.  The @code{configure} script should normally treat the
specified type of system as both the host and the target, thus producing
a program which works for the same type of machine that it runs on.

The way to build a cross-compiler, cross-assembler, or what have you, is
to specify the option @samp{--host=@var{hosttype}} when running
@code{configure}.  This specifies the host system without changing the
type of target system.  The syntax for @var{hosttype} is the same as
described above.

Programs for which cross-operation is not meaningful need not accept the
@samp{--host} option, because configuring an entire operating system for