diff options
Diffstat (limited to 'contrib/binutils/etc/configure.texi')
| -rw-r--r-- | contrib/binutils/etc/configure.texi | 1830 |
1 files changed, 1830 insertions, 0 deletions
diff --git a/contrib/binutils/etc/configure.texi b/contrib/binutils/etc/configure.texi new file mode 100644 index 0000000..4457774 --- /dev/null +++ b/contrib/binutils/etc/configure.texi @@ -0,0 +1,1830 @@ +\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{") + |
