1831 lines
73 KiB
Plaintext
1831 lines
73 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
@setfilename configure.info
|
|
@settitle Cygnus configure
|
|
|
|
@synindex ky cp
|
|
|
|
@setchapternewpage odd
|
|
|
|
@ifinfo
|
|
@format
|
|
START-INFO-DIR-ENTRY
|
|
* configure: (configure). Cygnus configure.
|
|
END-INFO-DIR-ENTRY
|
|
@end format
|
|
@end ifinfo
|
|
|
|
@ifinfo
|
|
This document describes the Cygnus Support version of @code{configure}.
|
|
|
|
Copyright (C) 1991, 1992, 1993 Cygnus Support
|
|
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.
|
|
|
|
@ignore
|
|
Permission is granted to process this file through TeX and print the
|
|
results, provided the printed document carries copying permission
|
|
notice identical to this one except for the removal of this paragraph
|
|
(this paragraph not being relevant to the printed manual).
|
|
@end ignore
|
|
|
|
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 Cygnus Support.
|
|
@end ifinfo
|
|
|
|
@c We should not distribute texinfo files with smallbook enabled.
|
|
@c @smallbook
|
|
@finalout
|
|
@titlepage
|
|
@title Cygnus configure
|
|
@author K. Richard Pixley
|
|
@author Cygnus Support
|
|
@page
|
|
@cindex copyleft
|
|
|
|
@vskip 0pt plus 1filll
|
|
Edited January, 1993, by Jeffrey Osier, Cygnus Support.
|
|
|
|
Copyright @copyright{} 1991, 1992, 1993 Cygnus Support
|
|
|
|
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 Cygnus Support.
|
|
@end titlepage
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@ifinfo
|
|
@node Top
|
|
@top Cygnus configure
|
|
|
|
This file documents the configuration system used and distributed by
|
|
Cygnus Support.
|
|
|
|
@menu
|
|
* What configure does:: What configure does
|
|
* Invoking configure:: Invoking configure---basic usage
|
|
* Using configure:: More than you ever wanted to know
|
|
* Porting:: How to use configure with new programs
|
|
* Variables Index::
|
|
* Concept Index::
|
|
@end menu
|
|
@end ifinfo
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node What configure does
|
|
@chapter What @code{configure} does
|
|
@cindex Introduction
|
|
@cindex Overview
|
|
@cindex What @code{configure} does
|
|
@kindex Cygnus Support Developer's Kit
|
|
|
|
This manual documents Cygnus @code{configure}, a program which helps to
|
|
automate much of the setup activity associated with building large suites of
|
|
programs, such the Cygnus Support Developer's Kit. This manual is therefore
|
|
geared toward readers who are likely to face the problem of configuring
|
|
software in source form before compiling and installing it. We assume you are
|
|
an experienced programmer or system administrator.
|
|
@ifinfo
|
|
For further background on this topic, see @ref{Some Basic Terms, , Apologia
|
|
Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
|
|
Pixley.
|
|
@end ifinfo
|
|
@iftex
|
|
For further background on this topic, see @cite{On Configuring Development
|
|
Tools} by K. Richard Pixley.
|
|
@end iftex
|
|
|
|
When @code{configure} runs, it does the following things:
|
|
|
|
@table @emph
|
|
@item @bullet{} creates build directories
|
|
@vindex srcdir
|
|
@cindex @code{srcdir}
|
|
@cindex Build directories
|
|
When you run @code{configure} with the @samp{--srcdir} option, it uses the
|
|
current directory as the @dfn{build directory}, creating under it a directory
|
|
tree that parallels the directory structure of the source directory. If you
|
|
don't specify a @samp{srcdir}, @code{configure} first assumes that the source
|
|
code you wish to configure is in your current directory; if it finds no
|
|
@file{configure.in} input file there, it searches in the directory
|
|
@code{configure} itself lies in. (For details, see @ref{Build directories, ,
|
|
Build directories}.)
|
|
|
|
@item @bullet{} generates @file{Makefile}
|
|
@cindex @code{Makefile} generation
|
|
A @file{Makefile} template from the source directory, usually called
|
|
@file{Makefile.in}, is copied to an output file in the build directory which is
|
|
most often named @file{Makefile}. @code{configure} places definitions for a
|
|
number of standard @file{Makefile} macros at the beginning of the output file.
|
|
If @w{@samp{--prefix=@var{dir}}} or @w{@samp{--exec_prefix=@var{dir}}} are
|
|
specified on the @code{configure} command line, corresponding @file{Makefile}
|
|
variables are set accordingly. If host, target, or site-specific
|
|
@file{Makefile} fragments exist, these are inserted into the output file. (For
|
|
details, see @ref{Makefile generation, , @code{Makefile} generation}.)
|
|
|
|
@item @bullet{} generates @file{.gdbinit}
|
|
@cindex @code{.gdbinit}
|
|
If the source directory contains a @file{.gdbinit} file and the build directory
|
|
is not the same as the source directory, a @file{.gdbinit} file is created in
|
|
the build directory. This @file{.gdbinit} file contains commands which allow
|
|
the source directory to be read when debugging with the @sc{gnu} debugger,
|
|
@code{gdb}. (@xref{Command Files, , Command Files, gdb, Debugging With GDB}.)
|
|
|
|
@item @bullet{} makes symbolic links
|
|
@cindex Symbolic links
|
|
Most build directories require that some symbolic links with generic names are
|
|
built pointing to specific files in the source directory. If the system where
|
|
@code{configure} runs cannot support symbolic links, hard links are used
|
|
instead. (For details, see @ref{configure.in, , The @code{configure.in} input
|
|
file}.)
|
|
|
|
@item @bullet{} generates @file{config.status}
|
|
@cindex @code{config.status}
|
|
@code{configure} creates a shell script named @file{config.status} in the build
|
|
directory. This shell script, when run from the build directory (usually from
|
|
within a @file{Makefile}), will reconfigure the build directory (but not its
|
|
subdirectories). This is most often used to have a @file{Makefile} update
|
|
itself automatically if a new source directory is available.
|
|
|
|
@item @bullet{} calls itself recursively
|
|
@cindex Recursion
|
|
If the source directory has subdirectories that should also be configured,
|
|
@code{configure} is called for each.
|
|
@end table
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Invoking configure
|
|
@chapter Invoking @code{configure}
|
|
@cindex Invoking @code{configure}
|
|
@cindex Usage
|
|
|
|
Cygnus @code{configure} is a shell script which resides in a source tree. The
|
|
usual way to invoke @code{configure} is from the shell, as follows:
|
|
|
|
@cindex Example session
|
|
@example
|
|
eg$ ./configure @var{hosttype}
|
|
@end example
|
|
|
|
@noindent
|
|
This prepares the source in the current directory (@file{.}) to be
|
|
compiled for a @var{hosttype} environment. It assumes that you wish to
|
|
build programs and files in the default @dfn{build directory} (also the
|
|
current directory, @file{.}). If you do not specify a value for
|
|
@var{hosttype}, Cygnus @code{configure} will attempt to discover this
|
|
information by itself (@pxref{config.guess, , Determining system
|
|
information}). For information on @var{hosttype} environments,
|
|
@xref{Host, , Host}.
|
|
|
|
All @sc{gnu} software is packaged with one or more @code{configure} script(s)
|
|
(@pxref{Configuration, , How Configuration Should Work, standards, GNU Coding
|
|
Standards}). By using @code{configure} you prepare the source for your
|
|
specific environment by selecting and using @file{Makefile} fragments and
|
|
fragments of shell scripts, which are prepared in advance and stored with the
|
|
source.
|
|
|
|
@code{configure}'s command-line options also allow you to specify other aspects
|
|
of the source configuration:
|
|
|
|
@smallexample
|
|
configure @var{hosttype} [--target=@var{target}] [--srcdir=@var{dir}] [--rm]
|
|
[--site=@var{site}] [--prefix=@var{dir}] [--exec-prefix=@var{dir}]
|
|
[--program-prefix=@var{string}] [--tmpdir=@var{dir}]
|
|
[--with-@var{package}[=@var{yes/no}]] [--without-@var{package}]
|
|
[--enable-@var{feature}[=@var{yes/no}]] [--disable-@var{feature}]
|
|
[--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
|
|
@end smallexample
|
|
|
|
@table @code
|
|
@item --target=@var{target}
|
|
@cindex @code{--target}
|
|
@cindex @code{target} option
|
|
@vindex target
|
|
Requests that the sources be configured to target the @var{target} machine. If
|
|
no target is specified explicitly, the target is assumed to be the same as the
|
|
host (i.e., a @dfn{native} configuration). @xref{Host, , Host}, and
|
|
@ref{Target, , Target}, for
|
|
discussions of each.
|
|
|
|
@item --srcdir=@var{dir}
|
|
@cindex @code{--srcdir}
|
|
@cindex @code{srcdir} option
|
|
@vindex srcdir
|
|
Direct each generated @file{Makefile} to use the sources located in directory
|
|
@var{dir}. Use this option whenever you wish the object code to reside in a
|
|
different place from the source code. The @dfn{build directory} is always
|
|
assumed to be the directory you call @code{configure} from. See @ref{Build
|
|
directories, , Build directories}, for an example. If the source directory is
|
|
not specified, @code{configure} assumes that the source is in your current
|
|
directory. If @code{configure} finds no @file{configure.in} there, it searches
|
|
in the same directory that the @code{configure} script itself lies in.
|
|
Pathnames specified (Values for @var{dir}) can be either absolute relative to
|
|
the @emph{build} directory.
|
|
|
|
@item --rm
|
|
@cindex @code{--rm}
|
|
@cindex @code{rm} option
|
|
@vindex rm
|
|
@emph{Remove} the configuration specified by @var{hosttype} and the other
|
|
command-line options, rather than create it.
|
|
|
|
@c FIXME: check @ref
|
|
@quotation
|
|
@emph{Note:} We recommend that you use @samp{make distclean} rather than
|
|
use this option; see @ref{Invoking make,,Invoking @code{make},make,GNU
|
|
Make}, for details on @samp{make distclean}.
|
|
@end quotation
|
|
|
|
@item --site=@var{site}
|
|
@cindex @code{--site}
|
|
@cindex @code{site} option
|
|
@vindex site
|
|
Generate the @file{Makefile} using site-specific @file{Makefile} fragments for
|
|
@var{site}. @xref{Makefile fragments, , Adding information about local
|
|
conventions}.
|
|
|
|
@item --prefix=@var{dir}
|
|
@cindex @code{--prefix}
|
|
@cindex @code{prefix} option
|
|
@vindex prefix
|
|
Configure the source to install programs and files under directory @var{dir}.
|
|
|
|
This option sets the variable @samp{prefix}. Each generated @file{Makefile}
|
|
will have its @samp{prefix} variables set to this value. (@xref{What configure
|
|
really does, , What @code{configure} really does}.)
|
|
|
|
@item --exec-prefix=@var{dir}
|
|
@cindex @code{--exec-prefix}
|
|
@cindex @code{exec-prefix} option
|
|
@vindex exec-prefix
|
|
Configure the source to install @dfn{host dependent} files in @var{dir}.
|
|
|
|
This option sets the variable @samp{exec_prefix}. Each generated
|
|
@file{Makefile} will have its @samp{exec_prefix} variables set to this value.
|
|
(@xref{What configure really does, , What @code{configure} really does}.)
|
|
|
|
@item --program-prefix=@var{string}
|
|
@cindex @code{--program-prefix}
|
|
@cindex @code{program-prefix} option
|
|
@vindex program-prefix
|
|
Configure the source to install certain programs using @var{string} as a
|
|
prefix. This applies to programs which might be used for cross-compilation,
|
|
such as the compiler and the binary utilities, and also to programs which have
|
|
the same names as common Unix programs, such as @code{make}.
|
|
|
|
This option sets the variable @samp{program_prefix}. Each generated
|
|
@file{Makefile} will have its @samp{program_prefix} variables set to this
|
|
value. (@xref{What configure really does, , What @code{configure} really
|
|
does}.)
|
|
|
|
@item --tmpdir=@var{tmpdir}
|
|
@cindex @code{--tmpdir}
|
|
@cindex @code{tmpdir} option
|
|
@vindex tmpdir
|
|
Use the directory @var{tmpdir} for @code{configure}'s temporary files. The
|
|
default is the value of the environment variable @w{@code{TMPDIR}}, or
|
|
@file{/tmp} if the environment variable is not set.
|
|
|
|
@item --with-@var{package}[=@var{yes/no}]
|
|
@itemx --without-@var{package}
|
|
@cindex @code{--with-@var{package}}
|
|
@cindex @code{with-@var{package}} option
|
|
@vindex with-@var{package}
|
|
@cindex @code{--without-@var{package}}
|
|
@cindex @code{without-@var{package}} option
|
|
@vindex without-@var{package}
|
|
Indicate that @var{package} is present, or not present, depending on
|
|
@var{yes/no}. If @var{yes/no} is nonexistent, its value is assumed to be
|
|
@code{yes}. @samp{--without-@var{package}} is equivalent to
|
|
@samp{--with-@var{package}=no}.
|
|
|
|
For example, if you wish to configure the program @code{gcc} for a Sun
|
|
SPARCstation running SunOS 4.x, and you want @code{gcc} to use the
|
|
@sc{gnu} linker @code{ld}, you can configure @code{gcc} using
|
|
|
|
@cindex Example session
|
|
@smallexample
|
|
eg$ configure --with-gnu-ld sun4
|
|
@end smallexample
|
|
|
|
@noindent
|
|
@xref{What configure really does, , What @code{configure} really does}, for
|
|
details. See the installation or release notes for your particular package for
|
|
details on which other @var{package} options are recognized.
|
|
@c FIXME - need to include info about --with-* in other dox!
|
|
|
|
@item --enable-@var{feature}[=@var{yes/no}]
|
|
@itemx --disable-@var{feature}
|
|
@cindex @code{--enable-@var{feature}}
|
|
@cindex @code{enable-@var{feature}} option
|
|
@vindex enable-@var{feature}
|
|
@cindex @code{--disable-@var{feature}}
|
|
@cindex @code{disable-@var{feature}} option
|
|
@vindex disable-@var{feature}
|
|
Include @var{feature}, or not, depending on @var{yes/no}. If @var{yes/no} is
|
|
nonexistent, its value is assumed to be @code{yes}.
|
|
@samp{--disable-@var{feature}} is equivalent to
|
|
@samp{--enable-@var{feature}=no}.
|
|
|
|
@noindent
|
|
@xref{What configure really does, , What @code{configure} really does}, for
|
|
details. See the installation or release notes for your particular package for
|
|
details on which other @var{feature} options are recognized.
|
|
@c FIXME - need to include info about --enable-* in other dox!
|
|
|
|
@item --norecursion
|
|
@cindex @code{--norecursion}
|
|
@cindex @code{norecursion} option
|
|
@vindex norecursion
|
|
Configure only this directory; ignore any subdirectories. This is used by the
|
|
executable shell script @file{config.status} to reconfigure only the current
|
|
directory; it is most often used non-interactively, when @code{make} is
|
|
invoked. (@xref{config.status, , @code{config.status}}.)
|
|
|
|
@item --nfp
|
|
@cindex @code{--nfp}
|
|
@cindex @code{nfp} option
|
|
@vindex nfp
|
|
Assume that the intended @var{hosttype} has no floating point unit.
|
|
|
|
@item -s
|
|
@cindex @code{-s}
|
|
@cindex @code{s} option
|
|
Suppress status output. This option is used internally by
|
|
@code{configure} when calling itself recursively in subdirectories. You
|
|
can override this option with the @code{--verbose} option.
|
|
|
|
@item -v
|
|
@itemx --verbose
|
|
@cindex @code{-v}
|
|
@cindex @code{--verbose}
|
|
@cindex @code{v} option
|
|
@cindex @code{verbose} option
|
|
@cindex Verbose Output
|
|
@vindex verbose
|
|
Print status lines for each directory configured. Normally, only the
|
|
status lines for the initial working directory are printed.
|
|
|
|
@item --version
|
|
@itemx -V
|
|
@cindex version
|
|
@cindex @code{--version}
|
|
@cindex version
|
|
Print the @code{configure} version number.
|
|
|
|
@item --help
|
|
@cindex Usage
|
|
@cindex @code{--help}
|
|
@cindex @code{help} option
|
|
Print a short summary of how to invoke @code{configure}.
|
|
@end table
|
|
|
|
@cindex Abbreviating option names
|
|
@cindex Truncating option names
|
|
@cartouche
|
|
@emph{Note:} You may introduce options with a single dash, @samp{-}, rather
|
|
than two dashes, @samp{--}. However, you may not be able to truncate long
|
|
option names when using a single dash. When using two dashes, options may be
|
|
abbreviated as long as each option can be uniquely identified. For example,
|
|
@smallexample
|
|
eg$ configure --s=/u/me/src @var{hosttype}
|
|
@end smallexample
|
|
@noindent
|
|
is ambiguous, as @w{@samp{--s}} could refer to either @w{@samp{--site}} or
|
|
@w{@samp{--srcdir}}. However,
|
|
@smallexample
|
|
eg$ configure --src=/u/me/src @var{hosttype}
|
|
@end smallexample
|
|
@noindent
|
|
is a valid abbreviation.
|
|
@end cartouche
|
|
|
|
|
|
@c ========================================================================
|
|
@node Using configure
|
|
@chapter Using @code{configure}
|
|
@cindex Using @code{configure}
|
|
@cindex Detailed usage
|
|
@cindex Usage: detailed
|
|
|
|
@code{configure} prepares source directories for building programs in
|
|
them. ``Configuring'' is the process of preparing software to compile
|
|
correctly on a given @dfn{host}, for a given @dfn{target}.
|
|
|
|
@code{configure} subsequently writes a configured @file{Makefile} from a
|
|
pre-built template; @code{configure} uses variables that have been set in the
|
|
configuring process to determine the values of some variables in the
|
|
@file{Makefile}. Because of this we will refer to both @code{configure}
|
|
variables and @file{Makefile} variables. This convention allows us to
|
|
determine where the variable should be set initially, in either
|
|
@file{configure.in} or @file{Makefile.in}.
|
|
|
|
@menu
|
|
* What configure really does:: What configure really does
|
|
* configure.in:: The configure.in input file
|
|
* Install locations:: Where to install things once they are built
|
|
* Host:: Telling configure what will source will be built
|
|
* Target:: Telling configure what the source will target
|
|
* Makefile fragments:: Adding information about local conventions
|
|
* Makefile extensions:: Extensions to the GNU coding standards
|
|
@end menu
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node What configure really does
|
|
@section What @code{configure} really does
|
|
@cindex What @code{configure} really does
|
|
@cindex Behind the scenes
|
|
@cindex @code{configure} back end
|
|
@cindex @code{configure} details
|
|
|
|
Cygnus @code{configure} is a shell script that sets up an environment in
|
|
which your programs will compile correctly for your machine and
|
|
operating system, and will install in proper places. @code{configure}
|
|
accomplishes this task by doing the following:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
it generates a @file{Makefile} from a custom template called
|
|
@file{Makefile.in} in each relevant source directory;
|
|
|
|
@item
|
|
it customizes the build process to your specifications; you set certain
|
|
variables for @code{configure}, either on the command line or in the
|
|
file @file{configure.in}, which subsequently sets variables in each
|
|
generated @file{Makefile} to be used by @code{make} when actually
|
|
building the software;
|
|
|
|
@item
|
|
it creates @dfn{build directories}, places for your code to be compiled
|
|
in before being installed;
|
|
|
|
@item
|
|
it generates a @file{.gdbinit} in the build directory, if needed, to
|
|
communicate to @code{gdb} where to find the program's source code;
|
|
|
|
@item
|
|
it generates a shell script called @file{config.status}
|
|
which is used most often by the @file{Makefile} to reconfigure itself;
|
|
|
|
@item
|
|
it recurses in subdirectories, setting up entire trees so that they build
|
|
correctly; if @code{configure} finds another @code{configure} script
|
|
further down in a given source tree, it knows to use this script and not
|
|
recur.
|
|
@end itemize
|
|
|
|
For the sake of safety (i.e., in order to prevent broken installations), the
|
|
@sc{gnu} coding standards call for software to be @dfn{configured} in such a
|
|
way that an end user trying to build a given package will be able to do so by
|
|
affecting a finite number of variables. All @sc{gnu} software comes with an
|
|
executable @code{configure} shell script which sets up an environment within a
|
|
build directory which will correctly compile your new package for your host
|
|
(or, alternatively, whatever host you specify to @code{configure}).
|
|
@ifinfo
|
|
For further background on this topic, see @ref{Some Basic Terms, , Apologia
|
|
Configure, cfg-paper, On Configuring Development Tools}, by K. Richard
|
|
Pixley.
|
|
@end ifinfo
|
|
@iftex
|
|
For further background on this topic, see @cite{On Configuring Development
|
|
Tools} by K. Richard Pixley.
|
|
@end iftex
|
|
|
|
Use @code{configure} to set for the build process:
|
|
|
|
@itemize @bullet
|
|
@item
|
|
correct values for certain variables;
|
|
|
|
@item
|
|
which type of host you wish to configure a given package for
|
|
(@pxref{Host, , Host});
|
|
|
|
@item
|
|
where you want to install this package (by using @samp{prefix},
|
|
@samp{exec-prefix} and @samp{program-prefix}; @pxref{Install details, ,
|
|
Full descriptions of all installation directories});
|
|
|
|
@item
|
|
optionally, which type of machine you wish to @dfn{target} this
|
|
package's output to (@pxref{Target, , Target});
|
|
|
|
@item
|
|
which other @sc{gnu} packages are already installed and available to
|
|
this particular build (by using the @samp{--with-@var{package}} option;
|
|
@pxref{Invoking configure, , Invoking @code{configure}});
|
|
|
|
@item
|
|
where to place temporary files (by using the @samp{--tmpdir=@var{dir}}
|
|
option; @pxref{Invoking configure, , Invoking @code{configure}});
|
|
|
|
@item whether to recur in subdirectories (changeable through the
|
|
@w{@samp{--norecursion}} option; @pxref{Invoking configure, , Invoking
|
|
@code{configure}}).
|
|
@end itemize
|
|
|
|
@code{configure} uses a few other files to complete its tasks. These are
|
|
discussed in detail where noted.
|
|
|
|
@table @code
|
|
@cindex Other files
|
|
@item configure.in
|
|
@cindex @code{configure.in} definition
|
|
Input file for @code{configure}. Shell script fragments reside here.
|
|
@xref{configure.in, , The @code{configure.in} input file}.
|
|
|
|
@item Makefile.in
|
|
@cindex @code{Makefile.in} definition
|
|
Template which @code{configure} uses to build a file called @file{Makefile} in
|
|
the @dfn{build directory}. @xref{Makefile generation, , @code{Makefile}
|
|
generation}.
|
|
|
|
@item config.sub
|
|
@cindex @code{config.sub} definition
|
|
Shell script used by @code{configure} to expand referents to the
|
|
@var{hosttype} argument into a single specification of the form
|
|
@w{@var{cpu-vendor-os}}. For instance, on the command line you can
|
|
specify
|
|
|
|
@cindex Example session
|
|
@example
|
|
eg$ ./configure sun4
|
|
@end example
|
|
|
|
@noindent
|
|
to configure for a Sun SPARCstation running SunOS 4.x. @code{configure}
|
|
consults @code{config.sub} to find that the three-part specification for this
|
|
is
|
|
|
|
@example
|
|
sparc-sun-sunos4.1.1
|
|
@end example
|
|
|
|
@noindent
|
|
which notes the @var{cpu} as @samp{sparc}, the @var{manufacturer} as @samp{sun}
|
|
(Sun Microsystems), and the @var{os} (operating system) as @samp{sunos4.1.1},
|
|
the SunOS 4.1.1 release. @xref{configure variables, , Variables available to @code{configure}}.
|
|
|
|
@item config.guess
|
|
@cindex @code{config.guess} definition
|
|
If you do not put the @var{hosttype} argument on the command line,
|
|
@code{configure} uses the @code{config.guess} shell script to make an
|
|
analysis of your machine (it assumes that you wish to configure your
|
|
software for the type of machine on which you are running). The output
|
|
of @code{config.guess} is a three-part identifier as described above.
|
|
|
|
@item config.status
|
|
@cindex @code{config.status} definition
|
|
The final step in configuring a directory is to create a shell script,
|
|
@code{config.status}. The main purpose of this file is to allow the
|
|
@file{Makefile} for the current directory to rebuild itself, if
|
|
necessary. @xref{config.status, , @code{config.status}}.
|
|
|
|
@item config/*
|
|
@cindex @code{config/} subdirectory
|
|
@code{configure} uses three types of @file{Makefile} @dfn{fragments}, which
|
|
reside in the directory @file{@var{srcdir}/config/}. @xref{Makefile fragments,
|
|
, Adding information about local conventions}.
|
|
@end table
|
|
|
|
@menu
|
|
* Build variables:: Variable-spaghetti made simple
|
|
* Build directories:: Build directories described well
|
|
* Makefile generation:: To build a Makefile
|
|
* config.guess:: Be vewwy quiet, I'm hunting system information
|
|
* config.status:: To rebuild a Makefile
|
|
@end menu
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Build variables
|
|
@subsection Build variables
|
|
@cindex Build variables
|
|
@cindex Cygnus Support Developer's Kit
|
|
@cindex Variables
|
|
|
|
There are several variables in the build process which you can control through
|
|
build programs such as @code{make}. These include machine definitions, local
|
|
conventions, installation locations, locations for temporary files, etc. This
|
|
data is accessible through certain variables which are configurable in the
|
|
build process; we refer to them as @dfn{build variables}.
|
|
|
|
For lists of build variables which you can affect by using @code{configure},
|
|
see @ref{configure variables, , Variables available to @code{configure.in}},
|
|
and @ref{Install details, , Full descriptions of all installation directories}.
|
|
|
|
Generally, build variables, which are used by the @file{Makefile} to
|
|
determine various aspects of the build and installation processes, are
|
|
changeable with command-line options to @code{configure}. In most large
|
|
suites of programs, like the Cygnus Support Developer's Kit, the
|
|
individual programs reside in several subdirectories of a single source
|
|
code ``tree''. All of these subdirectories need to be configured with
|
|
information relative to the @dfn{build directory}, which is not known
|
|
until @code{configure} is run. Unless specified otherwise,
|
|
@code{configure} recursively configures every subdirectory in the source
|
|
tree.
|
|
|
|
Build variables are passed from @code{configure} directly into the
|
|
@file{Makefile}, and use the same names (except that dashes are
|
|
transformed into underbars; for example, when you specify the option
|
|
@samp{--exec-prefix} on the command line, the @file{Makefile} variable
|
|
@samp{exec_prefix} is set). In other words, if you specify
|
|
|
|
@cindex Example session
|
|
@example
|
|
eg$ ./configure --prefix=/usr/gnu/local @dots{} @var{hosttype}
|
|
@end example
|
|
|
|
@noindent
|
|
on the command line, @code{configure} sets an variable called @samp{prefix} to
|
|
@samp{/usr/gnu/local}, and passes this into the @file{Makefile} in the same
|
|
manner. After this command, each @file{Makefile} generated by @code{configure}
|
|
will contain a line that reads:
|
|
|
|
@example
|
|
prefix = /usr/gnu/local
|
|
@end example
|
|
|
|
For a list of the @file{Makefile} variables @code{configure} can change, and
|
|
instructions on how to change them, see @ref{configure variables, , Variables
|
|
available to @code{configure.in}}, and @ref{Invoking configure, , Invoking
|
|
@code{configure}}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Build directories
|
|
@subsection Build directories
|
|
@cindex Build directories
|
|
@cindex Object directories
|
|
@cindex Building for multiple hosts
|
|
@cindex Building for multiple targets
|
|
|
|
By default, @code{configure} builds a @file{Makefile} and symbolic links in the
|
|
same directory as the source files. This default works for many cases, but it
|
|
has limitations. For instance, using this approach, you can only build object
|
|
code for one host at a time.
|
|
|
|
We refer to each directory where @code{configure} builds a @file{Makefile} as
|
|
a @dfn{build directory}.
|
|
|
|
The build directory for any given build is always the directory from which you
|
|
call @code{configure}, or @file{.} relative to your prompt. The default
|
|
@dfn{source directory}, the place @code{configure} looks to find source code,
|
|
is also @file{.}. For instance, if we have a directory @file{/gnu-stuff/src/}
|
|
that is the top branch of a tree of @sc{gnu} source code we wish to configure,
|
|
then the program we will use to configure this code is
|
|
@file{/gnu-stuff/src/configure}, as follows. (Assume for the sake of argument
|
|
that our machine is a sun4.)
|
|
|
|
@cindex Example session
|
|
@smallexample
|
|
@group
|
|
eg$ cd /gnu-stuff/src
|
|
eg$ ./configure sun4
|
|
Created "Makefile" in /gnu-stuff/src
|
|
eg$
|
|
@end group
|
|
@end smallexample
|
|
|
|
We just configured the code in @file{/gnu-stuff/src} to run on a Sun
|
|
SPARCstation using SunOS 4.x by creating a @file{Makefile} in
|
|
@file{/gnu-stuff/src}. By default, we also specified that when this code is
|
|
built, the object code should reside in the same directory,
|
|
@file{/gnu-stuff/src}.
|
|
|
|
However, if we wanted to build this code for more than one host, we would be in
|
|
trouble, because the new configuration would write over the old one, destroying
|
|
it in the process. What we can do is to make a new @dfn{build directory} and
|
|
configure from there. Running @code{configure} from the new directory will
|
|
place a correct @file{Makefile} and a @file{config.status} in this new file.
|
|
That is all @code{configure} does; we must run @code{make} to generate any
|
|
object code.
|
|
|
|
The new @file{Makefile} in @file{/gnu-stuff/sun4-obj}, created from the
|
|
template file @file{/gnu-stuff/src/Makefile.in}, contains all the information
|
|
needed to build the program.
|
|
|
|
@cindex Example session
|
|
@smallexample
|
|
@group
|
|
eg$ mkdir /gnu-stuff/sun4-obj
|
|
eg$ cd /gnu-stuff/sun4-obj
|
|
eg$ ../src/configure --srcdir=../src sun4
|
|
Created "Makefile" in /gnu-stuff/sun4-obj
|
|
eg$ ls
|
|
Makefile config.status
|
|
eg$ make all info install install-info clean
|
|
@var{compilation messages@dots{}}
|
|
eg$ mkdir /gnu-stuff/solaris2
|
|
eg$ cd /gnu-stuff/solaris2
|
|
eg$ ../src/configure --srcdir=../src sol2
|
|
Created "Makefile" in /gnu-stuff/solaris2
|
|
eg$ ls
|
|
Makefile config.status
|
|
eg$ make all info install install-info clean
|
|
@var{compilation messages@dots{}}
|
|
@end group
|
|
@end smallexample
|
|
|
|
We can repeat this for other configurations of the same software simply
|
|
by making a new build directory and reconfiguring from inside it. If
|
|
you do not specify the @var{hosttype} argument, @code{configure}
|
|
will attempt to figure out what kind of machine and operating system you
|
|
happen to be using. @xref{config.guess, , Determining system
|
|
information}. Of course, this may not always be the configuration you
|
|
wish to build.
|
|
|
|
@emph{Caution:} If you build more than one configuration for a single program,
|
|
remember that you must also specify a different @samp{--prefix} for each
|
|
configuration at configure-time. Otherwise, both configurations will be
|
|
installed in the same default location (@file{/usr/local}); the configuration
|
|
to be installed last would overwrite previously installed configurations.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Makefile generation
|
|
@subsection @code{Makefile} generation
|
|
@cindex @code{Makefile} generation
|
|
|
|
Cygnus @code{configure} creates a file called @file{Makefile} in the build
|
|
directory which can be used with @code{make} to automatically build a given
|
|
program or package. @code{configure} also builds a @file{Makefile} for each
|
|
relevant subdirectory for a given program or package (irrelevant subdirectories
|
|
would be those which contain no code which needs configuring, and which
|
|
therefore have no @code{configure} input file @file{configure.in} and no
|
|
@file{Makefile} template @file{Makefile.in}). @xref{Running, @code{make}
|
|
Invocation, How to Run @code{make}, make, GNU Make}, for details on using
|
|
@code{make} to compile your source code.
|
|
|
|
Each @file{Makefile} contains variables which have been configured for a
|
|
specific build. These build variables are determined when @code{configure} is
|
|
run. All build variables have defaults. By default, @code{configure}
|
|
generates a @file{Makefile} which specifies:
|
|
|
|
@cindex Default configuration
|
|
@itemize @bullet
|
|
@item a @dfn{native} build, which is to occur
|
|
|
|
@item in the current directory, and which will be installed
|
|
|
|
@item in the default installation directory (@file{/usr/local}) when the code
|
|
is compiled with @code{make}.
|
|
@end itemize
|
|
|
|
@noindent
|
|
Variables are changeable through command-line options to @code{configure}
|
|
(@pxref{Invoking configure, , Invoking @code{configure}}).
|
|
|
|
If you are porting a new program and intend to use @code{configure}, see
|
|
@ref{Porting, , Porting with @code{configure}}, as well as @ref{Makefiles, ,
|
|
Writing Makefiles, make, GNU Make}, and @ref{Makefiles, , Makefile Conventions,
|
|
standards, GNU Coding Standards}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node config.guess
|
|
@subsection Determining system information
|
|
@cindex @code{config.guess}
|
|
|
|
The shell script @code{config.guess} is called when you do not specify a
|
|
@var{hosttype} on the command line to @code{configure}. @code{config.guess}
|
|
acquires available system information from your local machine through the shell
|
|
command @code{uname}. It compares this information to a database and attempts
|
|
to determine a usable three-part system identifier (known as a @dfn{triple}) to
|
|
use as your @var{hosttype}. @xref{What configure really does, , What
|
|
@code{configure} really does}, to see how this information is used.
|
|
|
|
@emph{Note:} If you do not specify a @var{hosttype} on the command line,
|
|
@code{configure} will attempt to configure your software to run on the machine
|
|
you happen to be using. This may not be the configuration you desire.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node config.status
|
|
@subsection @code{config.status}
|
|
@cindex @code{config.status}
|
|
|
|
The final step in configuring a directory is to create an executable shell
|
|
script, @file{config.status}. The main purpose of this file is to allow the
|
|
@file{Makefile} for the current directory to rebuild itself, if necessary. It
|
|
is usually run from within the @file{Makefile}. @xref{Makefile extensions, ,
|
|
Extensions to the @sc{gnu} coding standards}.
|
|
|
|
@file{config.status} also contains a record of the @code{configure} session
|
|
which created it.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node configure.in
|
|
@section The @code{configure.in} input file
|
|
@cindex @code{configure.in}
|
|
|
|
A @file{configure.in} file for Cygnus @code{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 executed by the
|
|
@code{configure} shell script at an appropriate time. Values are passed among
|
|
@code{configure} and the shell fragments through a set of shell variables.
|
|
When each section is being interpreted 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 @samp{$(srcdir)/} to the desired file name.
|
|
|
|
@cindex @i{per-invocation} section
|
|
The beginning of the @file{configure.in} file begins the @dfn{per-invocation}
|
|
section.
|
|
|
|
@cindex @i{per-host} section
|
|
A line beginning with @samp{# per-host:} begins the @dfn{per-host} section.
|
|
|
|
@cindex @i{per-target} section
|
|
A line beginning with @samp{# per-target:} begins the @dfn{per-target} section.
|
|
|
|
@cindex @i{post-target} section
|
|
If it exists, the @dfn{post-target} section begins with @samp{# post-target:}.
|
|
|
|
@menu
|
|
* configure variables:: Variables available to configure.in
|
|
* Minimal:: A minimal configure.in
|
|
* Declarations:: For each invocation
|
|
* per-host:: Host-specific instructions
|
|
* per-target:: Target-specific instructions
|
|
* post-target:: Instructions to be executed after target info
|
|
* Example:: An example configure.in
|
|
@end menu
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node configure variables
|
|
@subsection Variables available to @code{configure.in}
|
|
@cindex @file{configure.in} interface
|
|
@cindex configure variables
|
|
|
|
The following variables pass information between the standard parts of
|
|
@code{configure} and the shell-script fragments in @file{configure.in}:
|
|
|
|
@table @code
|
|
@item srctrigger
|
|
@cindex @code{srctrigger}
|
|
@vindex srctrigger
|
|
Contains the name of a source file that is expected to live in the source
|
|
directory. You must usually set this in the @dfn{per-invocation} section of
|
|
@file{configure.in}. @code{configure} tests to see that this file exists. If
|
|
the file does not exist, @code{configure} prints an error message. This is
|
|
used as a sanity check that @file{configure.in} matches the source directory.
|
|
|
|
@item srcname
|
|
@cindex @code{srcname}
|
|
@vindex srcname
|
|
Contains the name of the source collection contained in the source directory.
|
|
You must usually set this in the @dfn{per-invocation} section of
|
|
@file{configure.in}. If the file named in @samp{srctrigger} does not exist,
|
|
@code{configure} uses the value of @samp{srcname} when it prints the error
|
|
message.
|
|
|
|
@item configdirs
|
|
@cindex @code{configdirs}
|
|
@vindex configdirs
|
|
Contains the names of any subdirectories in which @code{configure} should
|
|
recurse. You must usually set this in the @dfn{per-invocation} section of
|
|
@file{configure.in}.
|
|
If @file{Makefile.in} contains a line starting with @samp{SUBDIRS =},
|
|
then it will be replaced with an assignment to @samp{SUBDIRS} using
|
|
the value of @samp{configdirs} (if @samp{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 @samp{configdirs} (instead of the @samp{subdirs} variable
|
|
described below) if you want to be able to partition the
|
|
subdirectories, or use independent @file{Makefile} fragments.
|
|
Each subdirectory can be independent, and independently reconfigured.
|
|
|
|
@item subdirs
|
|
@cindex @code{subdirs}
|
|
@vindex subdirs
|
|
Contains the names of any subdirectories where @code{configure} should create a
|
|
@file{Makefile} (in addition to the current directory), @emph{without}
|
|
recursively running @code{configure}. Use @samp{subdirs} (instead of the
|
|
@samp{configdirs} variable described above) if you want to configure all of the
|
|
directories as a unit. Since there is a single invocation of @code{configure}
|
|
that configures many directories, all the directories can use the same
|
|
@file{Makefile} fragments, and the same @code{configure.in}.
|
|
|
|
@item host
|
|
@cindex @code{host}
|
|
@cindex Canonical ``triple''
|
|
@vindex host
|
|
Contains the full configuration name for the host (generated by the script
|
|
@file{config.sub} from the name that you entered). This is a three-part
|
|
name (commonly referred to as a @dfn{triple}) of the form
|
|
@var{cpu}-@var{vendor}-@var{os}.
|
|
|
|
There are separate variables @samp{host_cpu}, @samp{host_vendor}, and
|
|
@samp{host_os} that you can use to test each of the three parts; this variable
|
|
is useful, however, for error messages, and for testing combinations of the
|
|
three components.
|
|
|
|
@item host_cpu
|
|
@vindex host_cpu
|
|
Contains the first element of the canonical triple representing the host
|
|
as returned by @file{config.sub}. This is occasionally used to
|
|
distinguish between minor variations of a particular vendor's operating
|
|
system and sometimes to determine variations in binary format between
|
|
the host and the target.
|
|
|
|
@item host_vendor
|
|
@vindex host_vendor
|
|
Contains the second element of the canonical triple representing the host as
|
|
returned by @file{config.sub}. This is usually used to distinguish among the
|
|
numerous variations of @emph{common} operating systems.
|
|
@c "@emph{common} OS" doesn't convey much to me. Is this meant to cover
|
|
@c cases like Unix, widespread but with many variations?
|
|
|
|
@item host_os
|
|
@vindex host_os
|
|
Contains the the third element of the canonical triple representing the
|
|
host as returned by @file{config.sub}.
|
|
|
|
@item target
|
|
@cindex @code{target}
|
|
@cindex Canonical ``triple''
|
|
@vindex target
|
|
Contains the full configuration name (generated by the script @file{config.sub}
|
|
from the name that you entered) for the target. Like the host, this is a
|
|
three-part name of the form @var{cpu}-@var{vendor}-@var{os}.
|
|
|
|
There are separate variables @samp{target_cpu}, @samp{target_vendor}, and
|
|
@samp{target_os} that you can use to test each of the three parts; this
|
|
variable is useful, however, for error messages, and for testing combinations
|
|
of the three components.
|
|
|
|
@item target_cpu
|
|
@vindex target_cpu
|
|
Contains the first element of the canonical triple representing the target as
|
|
returned by @file{config.sub}. This variable is used heavily by programs which
|
|
are involved in building other programs, like the compiler, assembler, linker,
|
|
etc. Most programs will not need the @samp{target} variables at all, but this
|
|
one could conceivably be used to build a program, for instance, that operated
|
|
on binary data files whose byte order or alignment differ from the system where
|
|
the program is running.
|
|
|
|
@item target_vendor
|
|
@vindex target_vendor
|
|
Contains the second element of the canonical triple representing the target as
|
|
returned by @file{config.sub}. This is usually used to distinguish among the
|
|
numerous variations of @emph{common} operating systems or object file
|
|
formats. It is sometimes used to switch between different flavors of user
|
|
interfaces.
|
|
@c above query re "@emph{common} OS" applies here too
|
|
|
|
@item target_os
|
|
@vindex target_os
|
|
Contains the the third element of the canonical triple representing the
|
|
target as returned by @file{config.sub}. This variable is used by
|
|
development tools to distinguish between subtle variations in object
|
|
file formats that some vendors use across operating system releases. It
|
|
might also be use to decide which libraries to build or what user
|
|
interface the tool should provide.
|
|
|
|
@item floating_point
|
|
@cindex @code{floating_point}
|
|
@cindex @code{nfp} option
|
|
@vindex floating_point
|
|
Set to @samp{no} if you invoked @code{configure} with the @samp{--nfp}
|
|
command-line option, otherwise it is empty. This is a request to target
|
|
machines with @dfn{no floating point} unit, even if the targets ordinarily have
|
|
floating point units available.
|
|
|
|
@item gas
|
|
@cindex @code{with-gnu-as} option
|
|
@vindex gas
|
|
Set to @samp{true} if you invoked @code{configure} with the
|
|
@w{@samp{--with-gnu-as}} command line option, otherwise it is empty. This is a
|
|
request to assume that the specified @var{hosttype} machine has @sc{gnu} @code{as}
|
|
available even if it ordinarily does not.
|
|
|
|
@item srcdir
|
|
@cindex @code{srcdir}
|
|
@vindex srcdir
|
|
Set to the name of the directory containing the source for this program.
|
|
This will be different from @file{.} if you have specified the
|
|
@samp{--srcdir=@var{dir}} option. @samp{srcdir} can indicate either an
|
|
absolute path or a path relative to the build directory.
|
|
|
|
@item package_makefile_frag
|
|
@vindex package_makefile_frag
|
|
If set in @file{configure.in}, this variable should be the name a file relative
|
|
to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named
|
|
file does not exist, @code{configure} will print a warning message. This
|
|
variable is not set by @code{configure}.
|
|
|
|
@item host_makefile_frag
|
|
@vindex host_makefile_frag
|
|
If set in @file{configure.in}, this variable should be the name a file relative
|
|
to @samp{srcdir} to be included in the resulting @file{Makefile}. If the named
|
|
file does not exist, @code{configure} will print a warning message. This
|
|
variable is not set by @code{configure}.
|
|
|
|
@item target_makefile_frag
|
|
@vindex target_makefile_frag
|
|
If set in @file{configure.in}, this variable should be the name of a file,
|
|
relative to @samp{srcdir}, to be included in the resulting @file{Makefile}. If
|
|
the named file does not exist, @code{configure} will print a warning message.
|
|
This variable is not set by @code{configure}.
|
|
|
|
@item site_makefile_frag
|
|
@vindex site_makefile_frag
|
|
Set to a file name representing to the default @file{Makefile} fragment for
|
|
this host. It may be set in @file{configure.in} to override this default.
|
|
Normally @samp{site_makefile_frag} is empty, but will have a value if you
|
|
specify @samp{--site=@var{site}} on the command line.
|
|
@ignore -- this doesn't fit
|
|
It is probably not a good idea to override this variable from
|
|
@file{configure.in}, since that may defeat the @code{configure} user's
|
|
intentions.
|
|
@end ignore
|
|
|
|
@item Makefile
|
|
@vindex Makefile
|
|
Set to the name of the generated @file{Makefile}. Normally this value is
|
|
precisely @file{Makefile}, but some programs may want something else.
|
|
|
|
@item removing
|
|
@cindex @code{rm} option
|
|
@vindex removing
|
|
Normally empty but will be set to some non-null value if you specified
|
|
@samp{--rm} on the command line. That is, if @samp{removing} is not empty,
|
|
then @code{configure} is @emph{removing} a configuration rather than creating
|
|
one.
|
|
|
|
@item files
|
|
@cindex Symbolic links
|
|
@vindex files
|
|
If this variable is not empty following the @dfn{per-target} section,
|
|
then each word in its value will be the target of a symbolic link named
|
|
in the corresponding word from the @samp{links} variable.
|
|
|
|
@item links
|
|
@cindex Symbolic links
|
|
@vindex links
|
|
If the @samp{files} variable is not empty following the @dfn{per-target}
|
|
section, then @code{configure} creates symbolic links with the first word of
|
|
@samp{links} pointing to the first word of @samp{files}, the second word of
|
|
@samp{links} pointing to the second word of @samp{files}, and so on.
|
|
@end table
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Minimal
|
|
@subsection A minimal @code{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 @file{Makefile} fragments if they exist.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Declarations
|
|
@subsection For each invocation
|
|
@cindex For each invocation
|
|
@cindex Declarations section
|
|
@cindex @i{per-invocation} section
|
|
|
|
@code{configure} invokes the entire shell script fragment from the start of
|
|
@file{configure.in} up to a line beginning with @w{@samp{# per-host:}}
|
|
immediately after parsing command line arguments. The variables
|
|
@samp{srctrigger} and @samp{srcname} @emph{must} be set here.
|
|
|
|
You might also want to set the variables @samp{configdirs} and
|
|
@samp{package_makefile_frag} here.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node per-host
|
|
@subsection Host-specific instructions
|
|
@cindex Host-specific instructions
|
|
@cindex @i{host} shell-script fragment
|
|
@cindex @i{per-host} section
|
|
|
|
The @dfn{per-host} section of @file{configure.in} starts with the line that
|
|
begins with @w{@samp{# per-host:}} and ends before a line beginning with
|
|
@w{@samp{# per-target:}}. @code{configure} invokes the commands in the
|
|
@dfn{per-host} section when determining host-specific information.
|
|
|
|
This section usually contains a big @code{case} statement using the variable
|
|
@samp{host} to determine appropriate values for @samp{host_makefile_frag} and
|
|
@samp{files}, although @samp{files} is not usually set here. Usually, it is
|
|
set at the end of the @dfn{per-target} section after determining the names of
|
|
the target specific configuration files.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node per-target
|
|
@subsection Target-specific instructions
|
|
@cindex Target-specific instructions
|
|
@cindex target shell-script fragment
|
|
@cindex @i{per-target} section
|
|
|
|
The @dfn{per-target} section of @file{configure.in} starts with the line that
|
|
begins with @w{@samp{# per-target:}} and ends before the line that begins with
|
|
@w{@samp{# post-target:}}, if there is such a line. Otherwise the
|
|
@dfn{per-target} section extends to the end of the file. @code{configure}
|
|
invokes the commands in the @dfn{per-target} section when determining
|
|
target-specific information, and before building any files, directories, or
|
|
links.
|
|
|
|
This section usually contains a big @code{case} statement using the variable
|
|
@samp{target} to determine appropriate values for @samp{target_makefile_frag}
|
|
and @samp{files}. The last lines in the @dfn{per-target} section normally set
|
|
the variables @samp{files} and @samp{links}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node post-target
|
|
@subsection Instructions to be executed after target info
|
|
@cindex Post-target shell-script fragment
|
|
@cindex @i{post-target} section
|
|
|
|
The @dfn{post-target} section is optional. If it exists, the
|
|
@samp{post-target} section starts with a line beginning with @w{@samp{#
|
|
Post-target:}} and extends to the end of the file. If it exists,
|
|
@code{configure} invokes this section once for each target after
|
|
building all files, directories, or links.
|
|
|
|
This section is seldom needed, but you can use it to edit the @file{Makefile}
|
|
generated by @code{configure}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Example
|
|
@subsection An example @code{configure.in}
|
|
@cindex Example @file{configure.in}
|
|
@cindex Sample @file{configure.in}
|
|
@c @cindex @code{bison} @file{configure.in}
|
|
@c this won't be the bison configure.in for long.. need better example
|
|
|
|
Here is a small example of a @file{configure.in} file.
|
|
|
|
@cartouche
|
|
@example
|
|
@group
|
|
# This file is a collection of shell script fragments
|
|
# used to tailor a template configure script as
|
|
# appropriate for this directory. For more information,
|
|
# see configure.texi.
|
|
|
|
configdirs=
|
|
srctrigger=warshall.c
|
|
srcname="bison"
|
|
|
|
# per-host:
|
|
case "$@{host@}" in
|
|
m88k-motorola-*)
|
|
host_makefile_frag=config/mh-delta88
|
|
;;
|
|
esac
|
|
|
|
# per-target:
|
|
files="bison_in.hairy"
|
|
links="bison.hairy"
|
|
|
|
# post-target:
|
|
@end group
|
|
@end example
|
|
@end cartouche
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Install locations
|
|
@section Install locations
|
|
@cindex Where to install
|
|
@cindex Install locations
|
|
|
|
Using the default configuration, @samp{make install} creates a single tree of
|
|
files, some of which are programs. The location of this tree is determined by
|
|
the value of the variable @samp{prefix}. The default value of @samp{prefix} is
|
|
@samp{/usr/local}. This is often correct for native tools installed on only
|
|
one host.
|
|
|
|
@menu
|
|
* prefix:: Changing the default install directory
|
|
* exec_prefix:: How to separate host independent files
|
|
from host dependent files when
|
|
installing for multiple hosts
|
|
* Install details:: Full descriptions of all installation subdirectories
|
|
@end menu
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node prefix
|
|
@subsection Changing the default install directory
|
|
@cindex Changing the install directory
|
|
@cindex @code{prefix} option
|
|
@vindex prefix
|
|
|
|
In the default configuration, all files are installed in subdirectories
|
|
of @file{/usr/local}. The location is determined by the value of
|
|
the @code{configure} variable @samp{prefix}; in turn, this determines the
|
|
value of the @file{Makefile} variable of the same name (@samp{prefix}).
|
|
|
|
You can also set the value of the @file{Makefile} variable @samp{prefix}
|
|
explicitly each time you invoke @code{make} if you are so inclined. However,
|
|
because many programs have this location compiled in, you must specify the
|
|
@samp{prefix} value consistently on each invocation of @code{make}, or you will
|
|
end up with a broken installation.
|
|
|
|
To make this easier, the value of the @code{configure} variable
|
|
@samp{prefix} can be set on the command line to @code{configure}
|
|
using the option @samp{--prefix=}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node exec_prefix
|
|
@subsection Installing for multiple hosts
|
|
@cindex Configuring for multiple hosts
|
|
@cindex Sharing host-independent files
|
|
@cindex Installing host-independent files
|
|
@cindex The @code{exec_prefix} directory
|
|
@vindex exec_prefix
|
|
|
|
By default, host dependent files are installed in subdirectories of
|
|
@file{$(exec_prefix)}. The location is determined by the value of the
|
|
@code{configure} variable @samp{exec_prefix}, which determines the value of the
|
|
@file{Makefile} variable @samp{exec_prefix}. This makes it easier to install
|
|
for a single host, and simplifies changing the default location for the install
|
|
tree. The default doesn't allow for multiple hosts to effectively share
|
|
host independent files, however.
|
|
|
|
To configure so that multiple hosts can share common files, use something like:
|
|
|
|
@cindex Example session
|
|
@smallexample
|
|
configure @var{host1} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
|
|
make all info install install-info clean
|
|
|
|
configure @var{host2} -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
|
|
make all info install install-info
|
|
@end smallexample
|
|
|
|
The first line configures the source for @var{host1} to place host-specific
|
|
programs in subdirectories of @file{/usr/gnu/H-@var{host1}}.
|
|
|
|
The second line builds and installs all programs for @var{host1},
|
|
including both host-independent and host-specific files, as well as removing
|
|
the host-specific object files from of the build directory.
|
|
|
|
The third line reconfigures the source for @var{host2} to place host
|
|
specific programs in subdirectories of @file{/usr/gnu/H-@var{host2}}.
|
|
|
|
The fourth line builds and installs all programs for @var{host2}. Host
|
|
specific files are installed in new directories, but the host
|
|
independent files are installed @emph{on top of} the host
|
|
independent files installed for @var{host1}. This results in a single
|
|
copy of the host independent files, suitable for use by both hosts.
|
|
|
|
@xref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}, for
|
|
more information.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Install details
|
|
@subsection Full descriptions of all installation subdirectories
|
|
@cindex Install details
|
|
@cindex Installation subdirectories
|
|
@cindex Subdirectories
|
|
|
|
During any install, a number of standard directories are created. Their names
|
|
are determined by @file{Makefile} variables. Some of the defaults for
|
|
@file{Makefile} variables can be changed at configuration time using command
|
|
line options to @code{configure}. For more information on the standard
|
|
directories or the @file{Makefile} variables, please refer to @ref{Makefiles, ,
|
|
Makefile Conventions, standards, GNU Coding Standards}. See also @ref{Makefile
|
|
extensions, , Extensions to the @sc{gnu} coding standards}.
|
|
|
|
Note that @code{configure} does not create the directory indicated by the
|
|
variable @samp{srcdir} at any time. @code{$(srcdir)} is not an installation
|
|
directory.
|
|
|
|
You can override all @file{Makefile} variables on the command line to
|
|
@code{make}. (@xref{Overriding, , Overriding Variables, make, GNU Make}.) If
|
|
you do so, you will need to specify the value precisely the same way for each
|
|
invocation of @code{make}, or you risk ending up with a broken installation.
|
|
This is because many programs have the locations of other programs or files
|
|
compiled into them. If you find yourself overriding any of the variables
|
|
frequently, you should consider site dependent @file{Makefile} fragments. See
|
|
also @ref{Sites, , Adding site info}.
|
|
|
|
During @samp{make install}, a number of standard directories are created and
|
|
populated. The following @file{Makefile} variables define them. Those whose
|
|
defaults are set by corresponding @code{configure} variables are marked
|
|
``@code{Makefile} and @code{configure}''.
|
|
|
|
@table @code
|
|
@item prefix (@code{Makefile} and @code{configure})
|
|
@cindex @code{prefix}
|
|
@vindex prefix
|
|
The root of the installation tree. You can set its @file{Makefile} default
|
|
with the @samp{--prefix=} command line option to @code{configure}
|
|
(@pxref{Invoking configure, , Invoking @code{configure}}). The default value
|
|
for @samp{prefix} is @samp{/usr/local}.
|
|
|
|
@item bindir
|
|
@cindex @code{bindir}
|
|
@vindex bindir
|
|
A directory for binary programs that users can run. The default value for
|
|
@samp{bindir} depends on @samp{prefix}; @samp{bindir} is normally changed only
|
|
indirectly through @samp{prefix}. The default value for @samp{bindir} is
|
|
@samp{$(prefix)/bin}.
|
|
|
|
@item exec_prefix (@code{Makefile} and @code{configure})
|
|
@cindex @code{exec_prefix}
|
|
@vindex exec_prefix
|
|
A directory for host dependent files. You can specify the @file{Makefile}
|
|
default value by using the @samp{--exec_prefix=} option to @code{configure}.
|
|
(@xref{Invoking configure, , Invoking @code{configure}}.) The default value
|
|
for @samp{exec_prefix} is @samp{$(prefix)}.
|
|
|
|
@item libdir
|
|
@cindex @code{libdir}
|
|
@vindex libdir
|
|
A directory for libraries and support programs. The default value for
|
|
@samp{libdir} depends on @samp{prefix}; @samp{libdir} is normally changed only
|
|
indirectly through @samp{prefix}. The default value for @samp{libdir} is
|
|
@samp{$(prefix)/lib}.
|
|
|
|
@item mandir
|
|
@cindex @code{mandir}
|
|
@vindex mandir
|
|
A directory for @code{man} format documentation (``man pages''). The default
|
|
value for @samp{mandir} depends on @samp{prefix}; @samp{mandir} is normally
|
|
changed only indirectly through @samp{prefix}. The default value for
|
|
@samp{mandir} is @samp{$(prefix)/man}.
|
|
|
|
@item man@var{N}dir
|
|
@cindex @code{man@var{N}dir}
|
|
@vindex man@var{N}dir
|
|
These are eight variables named @samp{man1dir}, @samp{man2dir}, etc. They name
|
|
the specific directories for each man page section. For example,
|
|
@samp{man1dir} by default holds the filename @file{$(mandir)/man1}; this
|
|
directory contains @file{emacs.1} (the man page for @sc{gnu} Emacs).
|
|
Similarly, @samp{man5dir} contains the value @file{$(mandir)/man5}, indicating
|
|
the directory which holds @file{rcsfile.5} (the man page describing the
|
|
@code{rcs} data file format). The default value for any of the
|
|
@samp{man@var{N}dir} variables depends indirectly on @samp{prefix}, and is
|
|
normally changed only through @samp{prefix}. The default value for
|
|
@samp{man@var{N}dir} is @samp{$(mandir)/man@var{N}}.
|
|
|
|
@item man@var{N}ext
|
|
@cindex @code{man@var{N}ext}
|
|
@vindex man@var{N}ext
|
|
@emph{Not supported by Cygnus @code{configure}}. The @cite{@sc{gnu} Coding
|
|
Standards} do not call for @samp{man1ext}, @samp{man2ext}, so the intended use
|
|
for @code{manext} is apparently not parallel to @samp{mandir}. Its use is not
|
|
clear. (See also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding
|
|
standards}.)
|
|
|
|
@item infodir
|
|
@cindex @code{infodir}
|
|
@vindex infodir
|
|
A directory for @code{info} format documentation. The default value for
|
|
@samp{infodir} depends indirectly on @samp{prefix}; @samp{infodir} is
|
|
normally changed only through @samp{prefix}. The default value for
|
|
@samp{infodir} is @samp{$(prefix)/info}.
|
|
|
|
@item docdir
|
|
@cindex @code{docdir}
|
|
@vindex docdir
|
|
A directory for any documentation that is in a format other than those used by
|
|
@code{info} or @code{man}. The default value for @samp{docdir} depends
|
|
indirectly on @samp{prefix}; @samp{docdir} is normally changed only through
|
|
@samp{prefix}. The default value for @samp{docdir} is @samp{$(datadir)/doc}.
|
|
@emph{This variable is an extension to the @sc{gnu} coding standards}. (See
|
|
also @ref{Makefile extensions, , Extensions to the @sc{gnu} coding standards}.)
|
|
|
|
@item includedir
|
|
@cindex @code{includedir}
|
|
@vindex includedir
|
|
A directory for the header files accompanying the libraries installed in
|
|
@samp{libdir}. The default value for @samp{includedir} depends on
|
|
@samp{prefix}; @samp{includedir} is normally changed only indirectly
|
|
through @samp{prefix}. The default value for @samp{includedir} is
|
|
@samp{$(prefix)/include}.
|
|
@end table
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Host
|
|
@section Host
|
|
@cindex Host
|
|
|
|
The arguments to @code{configure} are @dfn{hosttypes}. By
|
|
@dfn{hosttype} we mean the @dfn{environment} in which the source will be
|
|
compiled. This need not necessarily be the same as the physical machine
|
|
involved, although it usually is.
|
|
|
|
For example, if some obscure machine had the @sc{gnu} @code{POSIX} emulation
|
|
libraries available, it would be possible to configure most @sc{gnu} source for
|
|
a @code{POSIX} system and build it on the obscure host.
|
|
|
|
For more on this topic, see @ref{Host Environments, On Configuring Development
|
|
Tools, Host Environments, cfg-paper, On Configuring Development Tools}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Target
|
|
@section Target
|
|
@cindex Target
|
|
|
|
For building native development tools, or most of the other @sc{gnu}
|
|
tools, you need not worry about the target. The @dfn{target} of a
|
|
configuration defaults to the same as the @dfn{host}.
|
|
|
|
For building cross development tools, please see @ref{Building Development
|
|
Environments, On Configuring Development Tools, Building Development
|
|
Environments, cfg-paper, On Configuring Development Tools}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Makefile fragments
|
|
@section Adding information about local conventions
|
|
@cindex @code{Makefile} fragments
|
|
@cindex Local conventions
|
|
@cindex Adding local info
|
|
@cindex Adding site info
|
|
|
|
If you find that a tool does not get configured to your liking, or if
|
|
@code{configure}'s conventions differ from your local conventions, you should
|
|
probably consider @dfn{site-specific @file{Makefile} fragments}. See also
|
|
@ref{Sites, , Adding site info}.
|
|
|
|
These are probably not the right choice for options that can be set from
|
|
the @code{configure} command line or for differences that are host or
|
|
target dependent.
|
|
|
|
Cygnus @code{configure} uses three types of @file{Makefile} fragments. In a
|
|
generated @file{Makefile} they appear in the order: @dfn{target fragment},
|
|
@dfn{host fragment}, and @dfn{site fragment}. This allows host fragments to
|
|
override target fragments, and site fragments to override both.
|
|
|
|
Host-specific @file{Makefile} fragments conventionally reside in the
|
|
@file{./config/} subdirectory with names of the form @file{mh-@var{hosttype}}.
|
|
They are used for hosts that require odd options to the standard compiler and
|
|
for compile time options based on the host configuration.
|
|
|
|
Target-specific @file{Makefile} fragments conventionally reside in the
|
|
@file{./config/} subdirectory with names of the form @file{mt-@var{target}}.
|
|
They are used for target dependent compile time options.
|
|
|
|
Site specific @file{Makefile} fragments conventionally reside in the
|
|
@file{./config/} subdirectory with names of the form @file{ms-@var{site}}.
|
|
They are used to override host- and target-independent compile time options.
|
|
Note that you can also override these options on the @code{make} invocation
|
|
line.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Makefile extensions
|
|
@section Extensions to the @sc{gnu} coding standards
|
|
@cindex @code{Makefile} extensions
|
|
@cindex Cygnus extensions
|
|
@cindex Coding standards extensions
|
|
|
|
The following additions to the @sc{gnu} coding standards are required for
|
|
Cygnus @code{configure} to work properly.
|
|
|
|
@itemize @bullet
|
|
@item
|
|
The @file{Makefile} must contain exactly one line starting with @samp{####}.
|
|
This line should follow any default macro definitions but precede any rules.
|
|
Host, target, and site-specific @file{Makefile} fragments will be inserted
|
|
immediately after this line. If the line is missing, the fragments will not be
|
|
inserted.
|
|
|
|
@item
|
|
Cygnus adds the following targets to each @file{Makefile}. Their existence is
|
|
not required for Cygnus @code{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 Makefile
|
|
@item Makefile
|
|
Calls @code{./config.status} to rebuild the @file{Makefile} in this directory.
|
|
@end table
|
|
|
|
@item
|
|
The following @file{Makefile} targets have revised semantics:
|
|
|
|
@table @code
|
|
@kindex install
|
|
@item install
|
|
Should @emph{not} depend on the target @samp{all}. If the program is not
|
|
already built, @samp{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, for example, when the result of a @samp{make all} is
|
|
transported via tape to another machine for installation.
|
|
|
|
@kindex clean
|
|
@item clean
|
|
Should remove any file that can be regenerated by the @file{Makefile},
|
|
excepting only the @file{Makefile} itself, and any links created by
|
|
@code{configure}. That is, @code{make all clean} should return all directories
|
|
to their original condition. If this is not done, then the command sequence
|
|
|
|
@cindex Example session
|
|
@example
|
|
configure @var{host1} ; make all install clean ;
|
|
configure @var{host2} ; make all install
|
|
@end example
|
|
|
|
@noindent
|
|
will fail because of intermediate files intended for @var{host1}.
|
|
@end table
|
|
|
|
@item
|
|
Cygnus adds the following macros to all @file{Makefile.in} files, but
|
|
you are not required to use them to run Cygnus @code{configure}.
|
|
|
|
@table @code
|
|
@kindex docdir
|
|
@item docdir
|
|
The directory in which to install any documentation that is not either a
|
|
@code{man} page or an @code{info} file. For @code{man} pages, see
|
|
@samp{mandir}; for @code{info}, see @samp{infodir}.
|
|
|
|
@kindex includedir
|
|
@item includedir
|
|
The directory in which to install any header 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 @samp{includedir} may be used
|
|
by @code{cc} as well.
|
|
@end table
|
|
|
|
@item
|
|
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 datadir
|
|
@item datadir
|
|
is used for host independent data files.
|
|
|
|
@kindex mandir
|
|
@item mandir
|
|
The default path for @samp{mandir} depends on @samp{prefix}.
|
|
|
|
@kindex infodir
|
|
@item infodir
|
|
The default path for @samp{infodir} depends on @samp{prefix}.
|
|
|
|
@kindex BISON
|
|
@item BISON
|
|
is assumed to have a @code{yacc} calling convention. To use @sc{gnu}
|
|
@code{bison}, use @samp{BISON=bison -y}.
|
|
@end table
|
|
|
|
@item
|
|
Each Cygnus @file{Makefile} also conforms to one additional restriction:
|
|
|
|
When libraries are installed, the line containing the call to
|
|
@samp{INSTALL_DATA} should always be followed by a line containing a call to
|
|
@samp{RANLIB} on the installed library. This is to accommodate systems that
|
|
use @code{ranlib}. Systems that do not use @code{ranlib} can set @samp{RANLIB}
|
|
to ``@code{echo}'' in a host specific @file{Makefile} fragment.
|
|
@end itemize
|
|
|
|
@c ========================================================================
|
|
@node Porting
|
|
@chapter Porting with @code{configure}
|
|
@cindex Porting with @code{configure}
|
|
|
|
This section explains how to add programs, host and target configuration
|
|
names, and site-specific information to Cygnus @code{configure}.
|
|
|
|
@menu
|
|
* Programs:: Adding configure to new programs
|
|
* Hosts and targets:: Adding hosts and targets
|
|
* Sites:: Adding site info
|
|
@end menu
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Programs
|
|
@section Adding @code{configure} to new programs
|
|
@cindex Adding @code{configure} to new programs
|
|
|
|
If you are writing a new program, you probably shouldn't worry about porting or
|
|
configuration issues until it is running reasonably on some host. Then refer
|
|
back to this section.
|
|
|
|
If your program currently has a @code{configure} script that meets the @sc{gnu}
|
|
standards (@pxref{Configuration, , How Configuration Should Work, standards,
|
|
GNU Coding Standards}, please do not add Cygnus @code{configure}. It should be
|
|
possible to add this program without change to a Cygnus @code{configure} style
|
|
source tree.
|
|
|
|
@cindex @code{autoconf}
|
|
If the program is not target dependent, please consider using @code{autoconf}
|
|
instead of Cygnus @code{configure}. @code{autoconf} is available from the Free
|
|
Software Foundation; it is a program which generates an executable shell script
|
|
called @file{configure} by automatically finding information on the system to
|
|
be configured on and embedding this information in the shell script.
|
|
@file{configure} scripts generated by @code{autoconf} require no arguments, and
|
|
accept the same options as Cygnus @code{configure}. For detailed instructions
|
|
on using @code{autoconf}, see @ref{Making configure Scripts, , How to organize
|
|
and produce Autoconf scripts, autoconf, Autoconf}.
|
|
|
|
|
|
To add Cygnus @code{configure} to an existing program, do the following:
|
|
|
|
@table @bullet
|
|
@item Make sure the @file{Makefile} conforms to the @sc{gnu} standard
|
|
The coding standard for writing a @sc{gnu} @file{Makefile} is described in
|
|
@ref{Makefiles, , Makefile Conventions, standards, GNU Coding Standards}. For
|
|
technical information on writing a @file{Makefile}, see @ref{Makefiles, ,
|
|
Writing Makefiles, make, GNU Make}.
|
|
|
|
@item Add Cygnus extensions to the @file{Makefile}
|
|
These are described in @ref{Makefile extensions, , Extensions to the @sc{gnu}
|
|
coding standards}.
|
|
|
|
@item Collect package specific definitions in a single file
|
|
Many packages are best configured using a common @file{Makefile} fragment which
|
|
is included by all of the makefiles in the different directories of the
|
|
package. In order to accomplish this, set the variable
|
|
@samp{package_makefile_fragment} to the name of the file. It will be inserted
|
|
into the final @file{Makefile} before the target-specific fragment.
|
|
|
|
@item Move host support from @file{Makefile} to fragments
|
|
This usually involves finding sections of the @file{Makefile} that say things
|
|
like ``uncomment these lines for host @var{hosttype}'' and moving them to a new
|
|
file called @file{./config/mh-@var{hosttype}}. For more information, see @ref{Hosts
|
|
and targets, , Adding hosts and targets}.
|
|
|
|
@item Choose defaults
|
|
If the program has compile-time options that determine the way the program
|
|
should behave, choose reasonable defaults and make these @file{Makefile}
|
|
variables. Be sure the variables are assigned their default values before the
|
|
@samp{####} line so that site-specific @file{Makefile} fragments can override
|
|
them (@pxref{Makefile extensions, , Extensions to the @sc{gnu} coding
|
|
standards}).
|
|
|
|
@item Locate configuration files
|
|
If there is configuration information in header files or source files, separate
|
|
it in such a way that the files have generic names. Then move the specific
|
|
instances of those files into the @file{./config/} subdirectory.
|
|
|
|
@item Separate host and target information
|
|
Some programs already have this information separated. If yours does not, you
|
|
will need to separate these two kinds of configuration information. @dfn{Host
|
|
specific} information is the information needed to compile the program.
|
|
@dfn{Target specific} information is information on the format of data files
|
|
that the program will read or write. This information should live in separate
|
|
files in the @file{./config/} subdirectory with names that reflect the
|
|
configuration for which they are intended.
|
|
|
|
At this point you might skip this step and simply move on. If you do, you
|
|
should end up with a program that can be configured only to build @dfn{native}
|
|
tools, that is, tools for which the host system is also the target system.
|
|
Later, you could attempt to build a cross tool and separate out the
|
|
target-specific information by figuring out what went wrong. This is often
|
|
simpler than combing through all of the source code.
|
|
|
|
@item Write @code{configure.in}
|
|
Usually this involves writing shell script fragments to map from canonical
|
|
configuration names into the names of the configuration files. These files
|
|
will then be linked at configure time from the specific instances of those
|
|
files in @file{./config} to files in the build directory with more generic
|
|
names. (See also @ref{Build directories, , Build directories}.) The format of
|
|
@file{configure.in} is described in @ref{configure.in, , The
|
|
@code{configure.in} input file}.
|
|
|
|
@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}.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Hosts and targets
|
|
@section Adding hosts and targets
|
|
@cindex Adding hosts and targets
|
|
@cindex Hosts and targets
|
|
|
|
To add a host or target to a program that already uses Cygnus @code{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
|
|
@dfn{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, , The @code{configure.in} input file}.
|
|
|
|
@item
|
|
If you are adding a target configuration, look in @file{configure.in}, in the
|
|
@dfn{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, , The @code{configure.in}
|
|
input file}.
|
|
|
|
@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 @samp{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,
|
|
, Variables available to @code{configure.in}}.
|
|
@end itemize
|
|
|
|
This should be enough to @code{configure} for a new host or target
|
|
configuration name. Getting the program to compile and run properly represents
|
|
the hardest work of any port.
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Sites
|
|
@section Adding site info
|
|
@cindex Sites
|
|
@cindex Adding site info
|
|
|
|
If some of the @file{Makefile} defaults are not right for your site, you can
|
|
build site-specific @file{Makefile} fragments. To do this, do the following.
|
|
|
|
@itemize @bullet
|
|
|
|
@item
|
|
Choose a name for your site. It must currently be less than eleven characters.
|
|
|
|
@item
|
|
If the program source does not have a @file{./config/} subdirectory, 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 @file{Makefile} variables you need to
|
|
override to match your site's conventions.
|
|
|
|
@item
|
|
Configure the program with:
|
|
|
|
@cindex Example session
|
|
@example
|
|
configure @dots{} --site=@var{site}
|
|
@end example
|
|
|
|
@end itemize
|
|
|
|
@c ---------------------------------------------------------------------
|
|
@node Variables Index
|
|
@unnumbered Variable Index
|
|
|
|
@printindex vr
|
|
|
|
@page
|
|
@c ---------------------------------------------------------------------
|
|
@node Concept Index
|
|
@unnumbered Concept Index
|
|
|
|
@printindex cp
|
|
@contents
|
|
@bye
|
|
|
|
@c Local Variables:
|
|
@c fill-column: 79
|
|
@c outline-regexp: "@chap"
|
|
@c End:
|
|
@c (setq outline-regexp "@chapt\\\|@unnum\\\|@setf\\\|@conte\\\|@sectio\\\|@subsect\\\|@itemize\\\|@defvar{")
|
|
|