configure.texi

早期freebsd实现

@item Rename @file{Makefile} to @file{Makefile.in}
@end table

At this point you should have a program that can be configured using
Cygnus @code{configure}.

@node Hosts and Targets, Sites, Programs, Porting
@section Adding hosts and targets

To add a host or target to a program that already uses Cygnus
configure, do the following.

@itemize @bullet

@item
Make sure the new configuration name is represented in
@file{config.sub}.  If not, add it.  For more details, see the comments
in the shell script @file{config.sub}.

@item
If you are adding a host configuration, look in @file{configure.in}, in
the per-host section.  Make sure that your configuration name is
represented in the mapping from host configuration names to
configuration files.  If not, add it.  Also see @ref{configure.in}.

@item
If you are adding a target configuration, look in @file{configure.in},
in the per-target section.  Make sure that your configuration name is
represented in the mapping from target configuration names to
configuration files.  If not, add it.  Also see @ref{configure.in}.

@item
Look in @file{configure.in} for the variables @samp{files},
@samp{links}, @samp{host_makefile_frag}, and
@samp{target_makefile_frag}.  The values assigned to these variables are
the names of the configuration files, relative to @code{srcdir} that the
program uses.  Make sure that copies of the files exist for your host.
If not, create them.  See also @ref{Configure Variables}.
@end itemize

This should be enough to configure for a new host or target
configuration name.  Getting the program to compile and run properly
remains the hard work of the port.

@node Sites,  , Hosts and Targets, Porting
@section Adding site info

If some of the Makefile defaults are not right for your site, you can
build site specific Makefile fragments.  To do this, do the following.

@itemize @bullet

@item
Choose a name for your site.  It must be less than eleven characters for
now.

@item
If the program source does not have a @file{./config} directory, create it.

@item
Create a file called @file{./config/ms-@var{site}} where @var{site} is
the name of your site.  In it, set whatever Makefile variables you need
to override to match your site's conventions.

@item
Configure the program with:

@example
configure @dots{} +site=@var{site}
@end example

@end itemize

@node Reference, Known Bugs, Porting, top
@chapter Gory details described

@cindex Backends
Here we describe the backend support.

@menu
* Makefile Extensions::		Extensions to the @sc{gnu} coding standards
* configure.in::		The format of the configure.in file
* config.status::		config.status
* Makefile Fragments::		Makefile Fragments
@end menu

@node Makefile Extensions, configure.in, Reference, Reference
@section Extensions to the @sc{gnu} coding standards

@cindex Makefile extensions
@cindex Cygnus extensions

The following additions to the @sc{gnu} coding standards are required
for Cygnus configure to work properly.

@itemize @bullet
@item
The Makefile must contain exactly one line starting with @code{####}.
This line should follow any default macro definitions but precede any
rules.  Host, target, and site specific Makefile fragments will be
inserted immediately after this line.  If the line is missing, the
fragments will not be inserted.
@end itemize

Cygnus adds the following targets to our Makefiles.  Their existence is
not required for Cygnus configure, but they are documented here for
completeness.

@table @code
@kindex info
@item info
Build all info files from texinfo source.

@kindex install-info
@item install-info
Install all info files.

@kindex clean-info
@item clean-info
Remove all info files and any intermediate files that can be generated
from texinfo source.

@kindex stage1
@item stage1
@kindex stage2
@itemx stage2
@kindex stage3
@itemx stage3
@kindex stage4
@itemx stage4
@kindex de-stage1
@itemx de-stage1
@kindex de-stage2
@itemx de-stage2
@kindex de-stage3
@itemx de-stage3
@kindex de-stage4
@itemx de-stage4
@kindex bootstrap
@itemx bootstrap
@kindex comparison
@itemx comparison
@kindex Makefile
@itemx Makefile
These targets are in transition and may be removed shortly.
@end table

In addition, the following Makefile targets have revised semantics:

@table @code
@kindex install
@item install
Should @emph{not} depend on the target @code{all}.  If the program is
not already built, @code{make install} should fail.  This allows you
to install programs even when @code{make} would otherwise determine
them to be out of date.  This can happen when the result of a @code{make
all} is transported via tape to another machine for installation as
well as in a number of other cases.

@kindex clean
@item clean
Should remove any file that can be regenerated by the Makefile,
excepting only the Makefile itself, and any links created by configure.
That is, @code{make all clean} should return all directories to their
original condition.  If this is not done, then:

@example
configure @var{host1} ; make all clean ; configure @var{host2} ; make all
@end example

@noindent
will fail because of intermediate files intended for @var{host1}.
@end table

Cygnus adds the following macros to all @file{Makefile.in} files, but
you are not required to use them to run Cygnus configure.

@table @code
@kindex docdir
@item docdir
The directory in which to install any documentation that is not either a
man page or an info file.  For man pages, see mandir, for info, see
infodir.

@kindex includedir
@item includedir
The directory in which to install any headers files that should be made
available to users.  This is distinct from the @code{gcc} include
directory which is intended for @code{gcc} only.  Files in
@code{includedir} may be used by @code{cc} as well.
@end table

In addition, the following macros have revised semantics.  Most of them
describe installation directories; see also @ref{Install Details,,Full
description of all installation subdirectories}.

@table @code

@kindex manext
@item manext
is not used.  The intended usage is not clear.  For example, if you have a
@file{foo.man} and a @file{bar.man}, and @file{foo.man} is destined for
@file{/usr/local/lib/man/man1/foo.1} while @file{bar.man} is destined
for @file{/usr/local/lib/man/man5/bar.5}, then what is the desired value
of @code{manext}?

@kindex datadir
@item datadir
is used for host independent data files.

@kindex mandir
@item mandir
The default path for @code{mandir} depends on @code{prefix}.

@kindex infodir
@item infodir
The default path for @code{infodir} depends on @code{prefix}.

@kindex BISON
@item BISON
is assumed to have a @code{yacc} calling convention.  To  use
@code{bison}, use @code{BISON=bison -y}.
@end table

Cygnus Makefiles also conform to one additional restriction:

@itemize @bullet
@item
When libraries are installed, the line containing the call to
@code{INSTALL_DATA} should always be followed by a line containing a
call to @code{RANLIB} on the installed library.  This is to accomodate
systems that use @code{ranlib}.  Systems that do not use @code{ranlib}
can set @code{RANLIB} to @code{echo} in a host specific Makefile
fragment.
@end itemize

@node configure.in, config.status, Makefile Extensions, Reference
@section The format of the @file{configure.in} file
@kindex configure.in

A @file{configure.in} file for Cygnus configure consists of a
@dfn{per-invocation} section, followed by a @dfn{per-host} section,
followed by a @dfn{per-target} section, optionally followed by a
@dfn{post-target} section.  Each section is a shell script fragment,
which is sourced by the configure shell script at an appropriate time.
Values are passed among configure and the shell fragments through a
set of shell variables.  When each section is being interpreted
(sourced) by the shell, the shell's current directory is the build
directory, and any files created by the section (or referred to by the
section) will be relative to the build directory.  To reference files
in other places (such as the source directory), prepend a shell
variable such as @code{srcdir} to the desired file name.

@cindex Per-invocation section
The beginning of the @file{configure.in} file begins the per-invocation
section.

@cindex Per-host section
A line beginning with @code{# Per-host:} begins the per-host section.

@cindex Per-target section
A line beginning with @code{# Per-target:} begins the per-target
section.

@cindex Post-target section
If it exists, the post-target section begins with @code{# Per-target:}.

@menu
* Minimal::			A minimal configure.in
* Configure Variables::		Variables available to configure.in
* Declarations::		For each invocation
* Per-host::			For each host
* Per-target::			For each target
* Post-target::			After each target
* Example::			An example configure.in
@end menu

@node Minimal, Configure Variables, configure.in, configure.in
@subsection A minimal @file{configure.in}

@cindex Minimal @file{configure.in} example
A minimal @file{configure.in} consists of four lines.

@example
srctrigger=foo.c
srcname="source for the foo program"
# Per-host:
# Per-target:
@end example

The @samp{Per-host} and @samp{Per-target} lines divide the file into the
three required sections.  The @samp{srctrigger} line names a file.
@code{configure} checks to see that this file exists in the source
directory before configuring.  If the @samp{srctrigger} file does not
exist, @code{configure} uses the value of @samp{srcname} to print an
error message about not finding the source.

This particular example uses no links, and only the default host,
target, and site specific Makefile fragments if they exist.

@node Configure Variables, Declarations, Minimal, configure.in
@subsection Variables available to configure.in

@cindex @file{configure.in} interface

The following variables pass information between the standard parts of
@code{configure} and the shell-script fragments in @file{configure.in}:

@defvar{srctrigger}
Contains the name of a source file that is expected to live in the
source directory.  You must usually set this in the per-invocation
section of @file{configure.in}.  Configure tests to see that this file
exists.  If the file does not exist, configure prints an error message.
This is used as a sanity check that configure.in matches the source
directory.
@end defvar

@defvar{srcname}
Contains the name of the source collection contained in the source
directory.  You must usually set this in the per-invocation section of
@file{configure.in}.  If the file named in @code{srctrigger} does not
exist, configure uses the value of this variable when it prints the
error message.
@end defvar

@defvar{configdirs}
Contains the names of any subdirectories where @code{configure} should
recur.  You must usually set this in the per-invocation section of
@file{configure.in}.
If @file{Makefile.in} contains a line starting with @code{SUBDIRS =},
then it will be replaced with an assignment to @code{SUBDIRS} using
the value of @code{configdirs} (if @code{subdirs} is empty).  This can
be used to determine which directories to configure and build depending
on the host and target configurations.
@c Most other matching makefile/config vars use the same name.  Why not
@c this? (FIXME).
@c Can we get rid of SUBDIRS-substitution?  It doesn't work well with subdirs.
Use @code{configdirs} (instead of the @code{subdirs} variable
described below) if you want to be able to partition the
sub-directories, or use independent Makefile fragments.
Each sub-directory can be independent, and independently re-configured.
@end defvar