Cygnus <CODE>configure</CODE> is a shell script which resides in a source tree. The
usual way to invoke <CODE>configure</CODE> is from the shell, as follows:
<A NAME="IDX16"></A>
<P>
<PRE>
eg$ ./configure <VAR>hosttype</VAR>
</PRE>
<P>
This prepares the source in the current directory (<TT>`.'</TT>) to be
compiled for a <VAR>hosttype</VAR> environment. It assumes that you wish to
build programs and files in the default <DFN>build directory</DFN> (also the
current directory, <TT>`.'</TT>). If you do not specify a value for
<VAR>hosttype</VAR>, Cygnus <CODE>configure</CODE> will attempt to discover this
information by itself (see section <A HREF="CONFIGUR.000#SEC8">Determining system information</A>). For information on <VAR>hosttype</VAR> environments,
See section <A HREF="CONFIGUR.000#SEC22">Host</A>.
<P>
All GNU software is packaged with one or more <CODE>configure</CODE> script(s)
(see section `How Configuration Should Work' in <CITE>GNU Coding Standards</CITE>). By using <CODE>configure</CODE> you prepare the source for your
specific environment by selecting and using <TT>`Makefile'</TT> fragments and
fragments of shell scripts, which are prepared in advance and stored with the
source.
<P>
<CODE>configure</CODE>'s command-line options also allow you to specify other aspects
<DD>Requests that the sources be configured to target the <VAR>target</VAR> machine. If
no target is specified explicitly, the target is assumed to be the same as the
host (i.e., a <DFN>native</DFN> configuration). See section <A HREF="CONFIGUR.000#SEC22">Host</A>, and
section <A HREF="CONFIGUR.000#SEC23">Target</A>, for
discussions of each.
<A NAME="IDX20"></A>
<A NAME="IDX21"></A>
<A NAME="IDX22"></A>
<DT><CODE>--srcdir=<VAR>dir</VAR></CODE>
<DD>Direct each generated <TT>`Makefile'</TT> to use the sources located in directory
<VAR>dir</VAR>. Use this option whenever you wish the object code to reside in a
different place from the source code. The <DFN>build directory</DFN> is always
assumed to be the directory you call <CODE>configure</CODE> from. See section <A HREF="CONFIGUR.000#SEC6">Build directories</A>, for an example. If the source directory is
not specified, <CODE>configure</CODE> assumes that the source is in your current
directory. If <CODE>configure</CODE> finds no <TT>`configure.in'</TT> there, it searches
in the same directory that the <CODE>configure</CODE> script itself lies in.
Pathnames specified (Values for <VAR>dir</VAR>) can be either absolute relative to
the <EM>build</EM> directory.
<A NAME="IDX23"></A>
<A NAME="IDX24"></A>
<A NAME="IDX25"></A>
<DT><CODE>--rm</CODE>
<DD><EM>Remove</EM> the configuration specified by <VAR>hosttype</VAR> and the other
command-line options, rather than create it.
<BLOCKQUOTE>
<EM>Note:</EM> We recommend that you use <SAMP>`make distclean'</SAMP> rather than
use this option; see section `Invoking <CODE>make</CODE>' in <CITE>GNU Make</CITE>, for details on <SAMP>`make distclean'</SAMP>.
</BLOCKQUOTE>
<A NAME="IDX26"></A>
<A NAME="IDX27"></A>
<A NAME="IDX28"></A>
<DT><CODE>--site=<VAR>site</VAR></CODE>
<DD>Generate the <TT>`Makefile'</TT> using site-specific <TT>`Makefile'</TT> fragments for
<VAR>site</VAR>. See section <A HREF="CONFIGUR.000#SEC24">Adding information about local conventions</A>.
<A NAME="IDX29"></A>
<A NAME="IDX30"></A>
<A NAME="IDX31"></A>
<DT><CODE>--prefix=<VAR>dir</VAR></CODE>
<DD>Configure the source to install programs and files under directory <VAR>dir</VAR>.
This option sets the variable <SAMP>`prefix'</SAMP>. Each generated <TT>`Makefile'</TT>
will have its <SAMP>`prefix'</SAMP> variables set to this value. (See section <A HREF="CONFIGUR.000#SEC4">What <CODE>configure</CODE> really does</A>.)
<A NAME="IDX32"></A>
<A NAME="IDX33"></A>
<A NAME="IDX34"></A>
<DT><CODE>--exec-prefix=<VAR>dir</VAR></CODE>
<DD>Configure the source to install <DFN>host dependent</DFN> files in <VAR>dir</VAR>.
This option sets the variable <SAMP>`exec_prefix'</SAMP>. Each generated
<TT>`Makefile'</TT> will have its <SAMP>`exec_prefix'</SAMP> variables set to this value.
(See section <A HREF="CONFIGUR.000#SEC4">What <CODE>configure</CODE> really does</A>.)
Cygnus <CODE>configure</CODE> 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</CODE>
accomplishes this task by doing the following:
<P>
<UL>
<LI>
it generates a <TT>`Makefile'</TT> from a custom template called
<TT>`Makefile.in'</TT> in each relevant source directory;
<LI>
it customizes the build process to your specifications; you set certain
variables for <CODE>configure</CODE>, either on the command line or in the
file <TT>`configure.in'</TT>, which subsequently sets variables in each
generated <TT>`Makefile'</TT> to be used by <CODE>make</CODE> when actually
building the software;
<LI>
it creates <DFN>build directories</DFN>, places for your code to be compiled
in before being installed;
<LI>
it generates a <TT>`.gdbinit'</TT> in the build directory, if needed, to
communicate to <CODE>gdb</CODE> where to find the program's source code;
<LI>
it generates a shell script called <TT>`config.status'</TT>
which is used most often by the <TT>`Makefile'</TT> to reconfigure itself;
<LI>
it recurses in subdirectories, setting up entire trees so that they build
correctly; if <CODE>configure</CODE> finds another <CODE>configure</CODE> script
further down in a given source tree, it knows to use this script and not
recur.
</UL>
<P>
For the sake of safety (i.e., in order to prevent broken installations), the
GNU coding standards call for software to be <DFN>configured</DFN> 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 GNU software comes with an
executable <CODE>configure</CODE> 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</CODE>).
For further background on this topic, see <CITE>On Configuring Development
Tools</CITE> by K. Richard Pixley.
<P>
Use <CODE>configure</CODE> to set for the build process:
<P>
<UL>
<LI>
correct values for certain variables;
<LI>
which type of host you wish to configure a given package for
(see section <A HREF="CONFIGUR.000#SEC22">Host</A>);
<LI>
where you want to install this package (by using <SAMP>`prefix'</SAMP>,
<SAMP>`exec-prefix'</SAMP> and <SAMP>`program-prefix'</SAMP>; see section <A HREF="CONFIGUR.000#SEC21">Full descriptions of all installation subdirectories</A>);
<LI>
optionally, which type of machine you wish to <DFN>target</DFN> this
package's output to (see section <A HREF="CONFIGUR.000#SEC23">Target</A>);
<LI>
which other GNU packages are already installed and available to
this particular build (by using the <SAMP>`--with-<VAR>package</VAR>'</SAMP> option;
see section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>);
<LI>
where to place temporary files (by using the <SAMP>`--tmpdir=<VAR>dir</VAR>'</SAMP>
option; see section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>);
<LI>whether to recur in subdirectories (changeable through the
<SAMP>`--norecursion'</SAMP> option; see section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>).
</UL>
<P>
<CODE>configure</CODE> uses a few other files to complete its tasks. These are
discussed in detail where noted.
<P>
<A NAME="IDX74"></A>
<DL COMPACT>
<A NAME="IDX75"></A>
<DT><CODE>configure.in</CODE>
<DD>Input file for <CODE>configure</CODE>. Shell script fragments reside here.
See section <A HREF="CONFIGUR.000#SEC10">The <CODE>configure.in</CODE> input file</A>.
<A NAME="IDX76"></A>
<DT><CODE>Makefile.in</CODE>
<DD>Template which <CODE>configure</CODE> uses to build a file called <TT>`Makefile'</TT> in
the <DFN>build directory</DFN>. See section <A HREF="CONFIGUR.000#SEC7"><CODE>Makefile</CODE> generation</A>.
<A NAME="IDX77"></A>
<DT><CODE>config.sub</CODE>
<DD>Shell script used by <CODE>configure</CODE> to expand referents to the
<VAR>hosttype</VAR> argument into a single specification of the form
<VAR>cpu-vendor-os</VAR>. For instance, on the command line you can
specify
<A NAME="IDX78"></A>
<PRE>
eg$ ./configure sun4
</PRE>
to configure for a Sun SPARCstation running SunOS 4.x. <CODE>configure</CODE>
consults <CODE>config.sub</CODE> to find that the three-part specification for this
is
<PRE>
sparc-sun-sunos4.1.1
</PRE>
which notes the <VAR>cpu</VAR> as <SAMP>`sparc'</SAMP>, the <VAR>manufacturer</VAR> as <SAMP>`sun'</SAMP>
(Sun Microsystems), and the <VAR>os</VAR> (operating system) as <SAMP>`sunos4.1.1'</SAMP>,
the SunOS 4.1.1 release. See section <A HREF="CONFIGUR.000#SEC11">Variables available to <CODE>configure.in</CODE></A>.
<A NAME="IDX79"></A>
<DT><CODE>config.guess</CODE>
<DD>If you do not put the <VAR>hosttype</VAR> argument on the command line,
<CODE>configure</CODE> uses the <CODE>config.guess</CODE> 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</CODE> is a three-part identifier as described above.
<A NAME="IDX80"></A>
<DT><CODE>config.status</CODE>
<DD>The final step in configuring a directory is to create a shell script,
<CODE>config.status</CODE>. The main purpose of this file is to allow the
<TT>`Makefile'</TT> for the current directory to rebuild itself, if
necessary. See section <A HREF="CONFIGUR.000#SEC9"><CODE>config.status</CODE></A>.
<A NAME="IDX81"></A>
<DT><CODE>config/*</CODE>
<DD><CODE>configure</CODE> uses three types of <TT>`Makefile'</TT> <DFN>fragments</DFN>, which
reside in the directory <TT>`<VAR>srcdir</VAR>/config/'</TT>. See section <A HREF="CONFIGUR.000#SEC24">Adding information about local conventions</A>.
on the command line, <CODE>configure</CODE> sets an variable called <SAMP>`prefix'</SAMP> to
<SAMP>`/usr/gnu/local'</SAMP>, and passes this into the <TT>`Makefile'</TT> in the same
manner. After this command, each <TT>`Makefile'</TT> generated by <CODE>configure</CODE>
will contain a line that reads:
<P>
<PRE>
prefix = /usr/gnu/local
</PRE>
<P>
For a list of the <TT>`Makefile'</TT> variables <CODE>configure</CODE> can change, and
instructions on how to change them, see section <A HREF="CONFIGUR.000#SEC11">Variables available to <CODE>configure.in</CODE></A>, and section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>.
By default, <CODE>configure</CODE> builds a <TT>`Makefile'</TT> 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.
<P>
We refer to each directory where <CODE>configure</CODE> builds a <TT>`Makefile'</TT> as
a <DFN>build directory</DFN>.
<P>
The build directory for any given build is always the directory from which you
call <CODE>configure</CODE>, or <TT>`.'</TT> relative to your prompt. The default
<DFN>source directory</DFN>, the place <CODE>configure</CODE> looks to find source code,
is also <TT>`.'</TT>. For instance, if we have a directory <TT>`/gnu-stuff/src/'</TT>
that is the top branch of a tree of GNU source code we wish to configure,
then the program we will use to configure this code is
<TT>`/gnu-stuff/src/configure'</TT>, as follows. (Assume for the sake of argument
that our machine is a sun4.)
<A NAME="IDX90"></A>
<P>
<PRE>
eg$ cd /gnu-stuff/src
eg$ ./configure sun4
Created "Makefile" in /gnu-stuff/src
eg$
</PRE>
<P>
We just configured the code in <TT>`/gnu-stuff/src'</TT> to run on a Sun
SPARCstation using SunOS 4.x by creating a <TT>`Makefile'</TT> in
<TT>`/gnu-stuff/src'</TT>. By default, we also specified that when this code is
built, the object code should reside in the same directory,
<TT>`/gnu-stuff/src'</TT>.
<P>
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</DFN> and
configure from there. Running <CODE>configure</CODE> from the new directory will
place a correct <TT>`Makefile'</TT> and a <TT>`config.status'</TT> in this new file.
That is all <CODE>configure</CODE> does; we must run <CODE>make</CODE> to generate any
object code.
<P>
The new <TT>`Makefile'</TT> in <TT>`/gnu-stuff/sun4-obj'</TT>, created from the
template file <TT>`/gnu-stuff/src/Makefile.in'</TT>, contains all the information
needed to build the program.
<A NAME="IDX91"></A>
<P>
<PRE>
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...</VAR>
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...</VAR>
</PRE>
<P>
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</VAR> argument, <CODE>configure</CODE>
will attempt to figure out what kind of machine and operating system you
happen to be using. See section <A HREF="CONFIGUR.000#SEC8">Determining system information</A>. Of course, this may not always be the configuration you
wish to build.
<P>
<EM>Caution:</EM> If you build more than one configuration for a single program,
remember that you must also specify a different <SAMP>`--prefix'</SAMP> for each
configuration at configure-time. Otherwise, both configurations will be
installed in the same default location (<TT>`/usr/local'</TT>); the configuration
to be installed last would overwrite previously installed configurations.
Cygnus <CODE>configure</CODE> creates a file called <TT>`Makefile'</TT> in the build
directory which can be used with <CODE>make</CODE> to automatically build a given
program or package. <CODE>configure</CODE> also builds a <TT>`Makefile'</TT> 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</CODE> input file <TT>`configure.in'</TT> and no
<TT>`Makefile'</TT> template <TT>`Makefile.in'</TT>). See section `How to Run <CODE>make</CODE>' in <CITE>GNU Make</CITE>, for details on using
<CODE>make</CODE> to compile your source code.
<P>
Each <TT>`Makefile'</TT> contains variables which have been configured for a
specific build. These build variables are determined when <CODE>configure</CODE> is
run. All build variables have defaults. By default, <CODE>configure</CODE>
generates a <TT>`Makefile'</TT> which specifies:
<A NAME="IDX93"></A>
<P>
<UL>
<LI>a <DFN>native</DFN> build, which is to occur
<LI>in the current directory, and which will be installed
<LI>in the default installation directory (<TT>`/usr/local'</TT>) when the code
is compiled with <CODE>make</CODE>.
</UL>
<P>
Variables are changeable through command-line options to <CODE>configure</CODE>
(see section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>).
<P>
If you are porting a new program and intend to use <CODE>configure</CODE>, see
section <A HREF="CONFIGUR.000#SEC26">Porting with <CODE>configure</CODE></A>, as well as section `Writing Makefiles' in <CITE>GNU Make</CITE>, and section `Makefile Conventions' in <CITE>GNU Coding Standards</CITE>.
<P>
<A NAME="IDX94"></A>
<H3><A NAME="SEC8" HREF="CONFIGUR.HTM#SEC8">Determining system information</A></H3>
<P>
The shell script <CODE>config.guess</CODE> is called when you do not specify a
<VAR>hosttype</VAR> on the command line to <CODE>configure</CODE>. <CODE>config.guess</CODE>
acquires available system information from your local machine through the shell
command <CODE>uname</CODE>. It compares this information to a database and attempts
to determine a usable three-part system identifier (known as a <DFN>triple</DFN>) to
use as your <VAR>hosttype</VAR>. See section <A HREF="CONFIGUR.000#SEC4">What <CODE>configure</CODE> really does</A>, to see how this information is used.
<P>
<EM>Note:</EM> If you do not specify a <VAR>hosttype</VAR> on the command line,
<CODE>configure</CODE> will attempt to configure your software to run on the machine
you happen to be using. This may not be the configuration you desire.
The first line configures the source for <VAR>host1</VAR> to place host-specific
programs in subdirectories of <TT>`/usr/gnu/H-<VAR>host1</VAR>'</TT>.
<P>
The second line builds and installs all programs for <VAR>host1</VAR>,
including both host-independent and host-specific files, as well as removing
the host-specific object files from of the build directory.
<P>
The third line reconfigures the source for <VAR>host2</VAR> to place host
specific programs in subdirectories of <TT>`/usr/gnu/H-<VAR>host2</VAR>'</TT>.
<P>
The fourth line builds and installs all programs for <VAR>host2</VAR>. Host
specific files are installed in new directories, but the host
independent files are installed <EM>on top of</EM> the host
independent files installed for <VAR>host1</VAR>. This results in a single
copy of the host independent files, suitable for use by both hosts.
<P>
See section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>, for
more information.
<P>
<A NAME="IDX166"></A>
<A NAME="IDX167"></A>
<A NAME="IDX168"></A>
<H3><A NAME="SEC21" HREF="CONFIGUR.HTM#SEC21">Full descriptions of all installation subdirectories</A></H3>
<P>
During any install, a number of standard directories are created. Their names
are determined by <TT>`Makefile'</TT> variables. Some of the defaults for
<TT>`Makefile'</TT> variables can be changed at configuration time using command
line options to <CODE>configure</CODE>. For more information on the standard
directories or the <TT>`Makefile'</TT> variables, please refer to section `Makefile Conventions' in <CITE>GNU Coding Standards</CITE>. See also section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>.
<P>
Note that <CODE>configure</CODE> does not create the directory indicated by the
variable <SAMP>`srcdir'</SAMP> at any time. <CODE>$(srcdir)</CODE> is not an installation
directory.
<P>
You can override all <TT>`Makefile'</TT> variables on the command line to
<CODE>make</CODE>. (See section `Overriding Variables' in <CITE>GNU Make</CITE>.) If
you do so, you will need to specify the value precisely the same way for each
invocation of <CODE>make</CODE>, 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 <TT>`Makefile'</TT> fragments. See
also section <A HREF="CONFIGUR.000#SEC29">Adding site info</A>.
<P>
During <SAMP>`make install'</SAMP>, a number of standard directories are created and
populated. The following <TT>`Makefile'</TT> variables define them. Those whose
defaults are set by corresponding <CODE>configure</CODE> variables are marked
"<CODE>Makefile</CODE> and <CODE>configure</CODE>".
<P>
<DL COMPACT>
<A NAME="IDX169"></A>
<A NAME="IDX170"></A>
<DT><CODE>prefix (<CODE>Makefile</CODE> and <CODE>configure</CODE>)</CODE>
<DD>The root of the installation tree. You can set its <TT>`Makefile'</TT> default
with the <SAMP>`--prefix='</SAMP> command line option to <CODE>configure</CODE>
(see section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>). The default value
for <SAMP>`prefix'</SAMP> is <SAMP>`/usr/local'</SAMP>.
<A NAME="IDX171"></A>
<A NAME="IDX172"></A>
<DT><CODE>bindir</CODE>
<DD>A directory for binary programs that users can run. The default value for
<SAMP>`bindir'</SAMP> depends on <SAMP>`prefix'</SAMP>; <SAMP>`bindir'</SAMP> is normally changed only
indirectly through <SAMP>`prefix'</SAMP>. The default value for <SAMP>`bindir'</SAMP> is
<SAMP>`$(prefix)/bin'</SAMP>.
<A NAME="IDX173"></A>
<A NAME="IDX174"></A>
<DT><CODE>exec_prefix (<CODE>Makefile</CODE> and <CODE>configure</CODE>)</CODE>
<DD>A directory for host dependent files. You can specify the <TT>`Makefile'</TT>
default value by using the <SAMP>`--exec_prefix='</SAMP> option to <CODE>configure</CODE>.
(See section <A HREF="CONFIGUR.000#SEC2">Invoking <CODE>configure</CODE></A>.) The default value
for <SAMP>`exec_prefix'</SAMP> is <SAMP>`$(prefix)'</SAMP>.
<A NAME="IDX175"></A>
<A NAME="IDX176"></A>
<DT><CODE>libdir</CODE>
<DD>A directory for libraries and support programs. The default value for
<SAMP>`libdir'</SAMP> depends on <SAMP>`prefix'</SAMP>; <SAMP>`libdir'</SAMP> is normally changed only
indirectly through <SAMP>`prefix'</SAMP>. The default value for <SAMP>`libdir'</SAMP> is
<SAMP>`$(prefix)/lib'</SAMP>.
<A NAME="IDX177"></A>
<A NAME="IDX178"></A>
<DT><CODE>mandir</CODE>
<DD>A directory for <CODE>man</CODE> format documentation ("man pages"). The default
value for <SAMP>`mandir'</SAMP> depends on <SAMP>`prefix'</SAMP>; <SAMP>`mandir'</SAMP> is normally
changed only indirectly through <SAMP>`prefix'</SAMP>. The default value for
<SAMP>`mandir'</SAMP> is <SAMP>`$(prefix)/man'</SAMP>.
<A NAME="IDX179"></A>
<A NAME="IDX180"></A>
<DT><CODE>man<VAR>N</VAR>dir</CODE>
<DD>These are eight variables named <SAMP>`man1dir'</SAMP>, <SAMP>`man2dir'</SAMP>, etc. They name
the specific directories for each man page section. For example,
<SAMP>`man1dir'</SAMP> by default holds the filename <TT>`$(mandir)/man1'</TT>; this
directory contains <TT>`emacs.1'</TT> (the man page for GNU Emacs).
Similarly, <SAMP>`man5dir'</SAMP> contains the value <TT>`$(mandir)/man5'</TT>, indicating
the directory which holds <TT>`rcsfile.5'</TT> (the man page describing the
<CODE>rcs</CODE> data file format). The default value for any of the
<SAMP>`man<VAR>N</VAR>dir'</SAMP> variables depends indirectly on <SAMP>`prefix'</SAMP>, and is
normally changed only through <SAMP>`prefix'</SAMP>. The default value for
<SAMP>`man<VAR>N</VAR>dir'</SAMP> is <SAMP>`$(mandir)/man<VAR>N</VAR>'</SAMP>.
<A NAME="IDX181"></A>
<A NAME="IDX182"></A>
<DT><CODE>man<VAR>N</VAR>ext</CODE>
<DD><EM>Not supported by Cygnus <CODE>configure</CODE></EM>. The <CITE>GNU Coding
Standards</CITE> do not call for <SAMP>`man1ext'</SAMP>, <SAMP>`man2ext'</SAMP>, so the intended use
for <CODE>manext</CODE> is apparently not parallel to <SAMP>`mandir'</SAMP>. Its use is not
clear. (See also section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>.)
<A NAME="IDX183"></A>
<A NAME="IDX184"></A>
<DT><CODE>infodir</CODE>
<DD>A directory for <CODE>info</CODE> format documentation. The default value for
<SAMP>`infodir'</SAMP> depends indirectly on <SAMP>`prefix'</SAMP>; <SAMP>`infodir'</SAMP> is
normally changed only through <SAMP>`prefix'</SAMP>. The default value for
<SAMP>`infodir'</SAMP> is <SAMP>`$(prefix)/info'</SAMP>.
<A NAME="IDX185"></A>
<A NAME="IDX186"></A>
<DT><CODE>docdir</CODE>
<DD>A directory for any documentation that is in a format other than those used by
<CODE>info</CODE> or <CODE>man</CODE>. The default value for <SAMP>`docdir'</SAMP> depends
indirectly on <SAMP>`prefix'</SAMP>; <SAMP>`docdir'</SAMP> is normally changed only through
<SAMP>`prefix'</SAMP>. The default value for <SAMP>`docdir'</SAMP> is <SAMP>`$(datadir)/doc'</SAMP>.
<EM>This variable is an extension to the GNU coding standards</EM>. (See
also section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>.)
<A NAME="IDX187"></A>
<A NAME="IDX188"></A>
<DT><CODE>includedir</CODE>
<DD>A directory for the header files accompanying the libraries installed in
<SAMP>`libdir'</SAMP>. The default value for <SAMP>`includedir'</SAMP> depends on
<SAMP>`prefix'</SAMP>; <SAMP>`includedir'</SAMP> is normally changed only indirectly
through <SAMP>`prefix'</SAMP>. The default value for <SAMP>`includedir'</SAMP> is
For building native development tools, or most of the other GNU
tools, you need not worry about the target. The <DFN>target</DFN> of a
configuration defaults to the same as the <DFN>host</DFN>.
<P>
For building cross development tools, please see section `Building Development Environments' in <CITE>On Configuring Development Tools</CITE>.
<P>
<A NAME="IDX191"></A>
<A NAME="IDX192"></A>
<A NAME="IDX193"></A>
<A NAME="IDX194"></A>
<H2><A NAME="SEC24" HREF="CONFIGUR.HTM#SEC24">Adding information about local conventions</A></H2>
<P>
If you find that a tool does not get configured to your liking, or if
<CODE>configure</CODE>'s conventions differ from your local conventions, you should
probably consider <DFN>site-specific <TT>`Makefile'</TT> fragments</DFN>. See also
section <A HREF="CONFIGUR.000#SEC29">Adding site info</A>.
<P>
These are probably not the right choice for options that can be set from
the <CODE>configure</CODE> command line or for differences that are host or
target dependent.
<P>
Cygnus <CODE>configure</CODE> uses three types of <TT>`Makefile'</TT> fragments. In a
generated <TT>`Makefile'</TT> they appear in the order: <DFN>target fragment</DFN>,
<DFN>host fragment</DFN>, and <DFN>site fragment</DFN>. This allows host fragments to
override target fragments, and site fragments to override both.
<P>
Host-specific <TT>`Makefile'</TT> fragments conventionally reside in the
<TT>`./config/'</TT> subdirectory with names of the form <TT>`mh-<VAR>hosttype</VAR>'</TT>.
They are used for hosts that require odd options to the standard compiler and
for compile time options based on the host configuration.
<P>
Target-specific <TT>`Makefile'</TT> fragments conventionally reside in the
<TT>`./config/'</TT> subdirectory with names of the form <TT>`mt-<VAR>target</VAR>'</TT>.
They are used for target dependent compile time options.
<P>
Site specific <TT>`Makefile'</TT> fragments conventionally reside in the
<TT>`./config/'</TT> subdirectory with names of the form <TT>`ms-<VAR>site</VAR>'</TT>.
They are used to override host- and target-independent compile time options.
Note that you can also override these options on the <CODE>make</CODE> invocation
line.
<P>
<A NAME="IDX195"></A>
<A NAME="IDX196"></A>
<A NAME="IDX197"></A>
<H2><A NAME="SEC25" HREF="CONFIGUR.HTM#SEC25">Extensions to the GNU coding standards</A></H2>
<P>
The following additions to the GNU coding standards are required for
Cygnus <CODE>configure</CODE> to work properly.
<P>
<UL>
<LI>
The <TT>`Makefile'</TT> must contain exactly one line starting with <SAMP>`####'</SAMP>.
This line should follow any default macro definitions but precede any rules.
Host, target, and site-specific <TT>`Makefile'</TT> fragments will be inserted
immediately after this line. If the line is missing, the fragments will not be
inserted.
<LI>
Cygnus adds the following targets to each <TT>`Makefile'</TT>. Their existence is
not required for Cygnus <CODE>configure</CODE>, but they are documented here for
completeness.
<A NAME="IDX198"></A>
<DL COMPACT>
<DT><CODE>info</CODE>
<DD>Build all info files from texinfo source.
<A NAME="IDX199"></A>
<DT><CODE>install-info</CODE>
<DD>Install all info files.
<A NAME="IDX200"></A>
<DT><CODE>clean-info</CODE>
<DD>Remove all info files and any intermediate files that can be generated
from texinfo source.
<A NAME="IDX201"></A>
<DT><CODE>Makefile</CODE>
<DD>Calls <CODE>./config.status</CODE> to rebuild the <TT>`Makefile'</TT> in this directory.
</DL>
<LI>
The following <TT>`Makefile'</TT> targets have revised semantics:
<A NAME="IDX202"></A>
<DL COMPACT>
<DT><CODE>install</CODE>
<DD>Should <EM>not</EM> depend on the target <SAMP>`all'</SAMP>. If the program is not
already built, <SAMP>`make install'</SAMP> should fail. This allows you to install
programs even when <CODE>make</CODE> would otherwise determine them to be out of
date. This can happen, for example, when the result of a <SAMP>`make all'</SAMP> is
transported via tape to another machine for installation.
<A NAME="IDX203"></A>
<DT><CODE>clean</CODE>
<DD>Should remove any file that can be regenerated by the <TT>`Makefile'</TT>,
excepting only the <TT>`Makefile'</TT> itself, and any links created by
<CODE>configure</CODE>. That is, <CODE>make all clean</CODE> should return all directories
to their original condition. If this is not done, then the command sequence
<A NAME="IDX204"></A>
<PRE>
configure <VAR>host1</VAR> ; make all install clean ;
configure <VAR>host2</VAR> ; make all install
</PRE>
will fail because of intermediate files intended for <VAR>host1</VAR>.
</DL>
<LI>
Cygnus adds the following macros to all <TT>`Makefile.in'</TT> files, but
you are not required to use them to run Cygnus <CODE>configure</CODE>.
<A NAME="IDX205"></A>
<DL COMPACT>
<DT><CODE>docdir</CODE>
<DD>The directory in which to install any documentation that is not either a
<CODE>man</CODE> page or an <CODE>info</CODE> file. For <CODE>man</CODE> pages, see
<SAMP>`mandir'</SAMP>; for <CODE>info</CODE>, see <SAMP>`infodir'</SAMP>.
<A NAME="IDX206"></A>
<DT><CODE>includedir</CODE>
<DD>The directory in which to install any header files that should be made
available to users. This is distinct from the <CODE>gcc</CODE> include directory,
which is intended for <CODE>gcc</CODE> only. Files in <SAMP>`includedir'</SAMP> may be used
by <CODE>cc</CODE> as well.
</DL>
<LI>
The following macros have revised semantics. Most of them describe
installation directories; see also section <A HREF="CONFIGUR.000#SEC21">Full descriptions of all installation subdirectories</A>.
<A NAME="IDX207"></A>
<DL COMPACT>
<DT><CODE>datadir</CODE>
<DD>is used for host independent data files.
<A NAME="IDX208"></A>
<DT><CODE>mandir</CODE>
<DD>The default path for <SAMP>`mandir'</SAMP> depends on <SAMP>`prefix'</SAMP>.
<A NAME="IDX209"></A>
<DT><CODE>infodir</CODE>
<DD>The default path for <SAMP>`infodir'</SAMP> depends on <SAMP>`prefix'</SAMP>.
<A NAME="IDX210"></A>
<DT><CODE>BISON</CODE>
<DD>is assumed to have a <CODE>yacc</CODE> calling convention. To use GNU
<CODE>bison</CODE>, use <SAMP>`BISON=bison -y'</SAMP>.
</DL>
<LI>
Each Cygnus <TT>`Makefile'</TT> also conforms to one additional restriction:
When libraries are installed, the line containing the call to
<SAMP>`INSTALL_DATA'</SAMP> should always be followed by a line containing a call to
<SAMP>`RANLIB'</SAMP> on the installed library. This is to accommodate systems that
use <CODE>ranlib</CODE>. Systems that do not use <CODE>ranlib</CODE> can set <SAMP>`RANLIB'</SAMP>
to "<CODE>echo</CODE>" in a host specific <TT>`Makefile'</TT> fragment.
</UL>
<P>
<A NAME="IDX211"></A>
<H1><A NAME="SEC26" HREF="CONFIGUR.HTM#SEC26">Porting with <CODE>configure</CODE></A></H1>
<P>
This section explains how to add programs, host and target configuration
names, and site-specific information to Cygnus <CODE>configure</CODE>.
<P>
<A NAME="IDX212"></A>
<H2><A NAME="SEC27" HREF="CONFIGUR.HTM#SEC27">Adding <CODE>configure</CODE> to new programs</A></H2>
<P>
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.
<P>
If your program currently has a <CODE>configure</CODE> script that meets the GNU
standards (see section `How Configuration Should Work' in <CITE>GNU Coding Standards</CITE>, please do not add Cygnus <CODE>configure</CODE>. It should be
possible to add this program without change to a Cygnus <CODE>configure</CODE> style
source tree.
<A NAME="IDX213"></A>
<P>
If the program is not target dependent, please consider using <CODE>autoconf</CODE>
instead of Cygnus <CODE>configure</CODE>. <CODE>autoconf</CODE> is available from the Free
Software Foundation; it is a program which generates an executable shell script
called <TT>`configure'</TT> by automatically finding information on the system to
be configured on and embedding this information in the shell script.
<TT>`configure'</TT> scripts generated by <CODE>autoconf</CODE> require no arguments, and
accept the same options as Cygnus <CODE>configure</CODE>. For detailed instructions
on using <CODE>autoconf</CODE>, see section `How to organize and produce Autoconf scripts' in <CITE>Autoconf</CITE>.
<P>
To add Cygnus <CODE>configure</CODE> to an existing program, do the following:
<P>
<DL COMPACT>
<DT>@bullet{Make sure the <TT>`Makefile'</TT> conforms to the GNU standard}
<DD>The coding standard for writing a GNU <TT>`Makefile'</TT> is described in
section `Makefile Conventions' in <CITE>GNU Coding Standards</CITE>. For
technical information on writing a <TT>`Makefile'</TT>, see section `Writing Makefiles' in <CITE>GNU Make</CITE>.
<DT>@bullet{Add Cygnus extensions to the <TT>`Makefile'</TT>}
<DD>These are described in section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>.
<DT>@bullet{Collect package specific definitions in a single file}
<DD>Many packages are best configured using a common <TT>`Makefile'</TT> 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'</SAMP> to the name of the file. It will be inserted
into the final <TT>`Makefile'</TT> before the target-specific fragment.
<DT>@bullet{Move host support from <TT>`Makefile'</TT> to fragments}
<DD>This usually involves finding sections of the <TT>`Makefile'</TT> that say things
like "uncomment these lines for host <VAR>hosttype</VAR>" and moving them to a new
file called <TT>`./config/mh-<VAR>hosttype</VAR>'</TT>. For more information, see section <A HREF="CONFIGUR.000#SEC28">Adding hosts and targets</A>.
<DT>@bullet{Choose defaults}
<DD>If the program has compile-time options that determine the way the program
should behave, choose reasonable defaults and make these <TT>`Makefile'</TT>
variables. Be sure the variables are assigned their default values before the
<SAMP>`####'</SAMP> line so that site-specific <TT>`Makefile'</TT> fragments can override
them (see section <A HREF="CONFIGUR.000#SEC25">Extensions to the GNU coding standards</A>).
<DT>@bullet{Locate configuration files}
<DD>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 <TT>`./config/'</TT> subdirectory.
<DT>@bullet{Separate host and target information}
<DD>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</DFN> information is the information needed to compile the program.
<DFN>Target specific</DFN> 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 <TT>`./config/'</TT> 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</DFN>
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.
<DT>@bullet{Write <CODE>configure.in</CODE>}
<DD>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 <TT>`./config'</TT> to files in the build directory with more generic
names. (See also section <A HREF="CONFIGUR.000#SEC6">Build directories</A>.) The format of
<TT>`configure.in'</TT> is described in section <A HREF="CONFIGUR.000#SEC10">The <CODE>configure.in</CODE> input file</A>.
<DT>@bullet{Rename <TT>`Makefile'</TT> to <TT>`Makefile.in'</TT>}
<DD></DL>
<P>
At this point you should have a program that can be configured using
Cygnus <CODE>configure</CODE>.
<P>
<A NAME="IDX214"></A>
<A NAME="IDX215"></A>
<H2><A NAME="SEC28" HREF="CONFIGUR.HTM#SEC28">Adding hosts and targets</A></H2>
<P>
To add a host or target to a program that already uses Cygnus <CODE>configure</CODE>,
do the following.
<P>
<UL>
<LI>
Make sure the new configuration name is represented in <TT>`config.sub'</TT>. If
not, add it. For more details, see the comments in the shell script
<TT>`config.sub'</TT>.
<LI>
If you are adding a host configuration, look in <TT>`configure.in'</TT>, in the
<DFN>per-host</DFN> 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 section <A HREF="CONFIGUR.000#SEC10">The <CODE>configure.in</CODE> input file</A>.
<LI>
If you are adding a target configuration, look in <TT>`configure.in'</TT>, in the
<DFN>per-target</DFN> 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 section <A HREF="CONFIGUR.000#SEC10">The <CODE>configure.in</CODE> input file</A>.
<LI>
Look in <TT>`configure.in'</TT> for the variables <SAMP>`files'</SAMP>, <SAMP>`links'</SAMP>,
<SAMP>`host_makefile_frag'</SAMP>, and <SAMP>`target_makefile_frag'</SAMP>. The values
assigned to these variables are the names of the configuration files, (relative
to <SAMP>`srcdir'</SAMP>) that the program uses. Make sure that copies of the files
exist for your host. If not, create them. See also section <A HREF="CONFIGUR.000#SEC11">Variables available to <CODE>configure.in</CODE></A>.
</UL>
<P>
This should be enough to <CODE>configure</CODE> for a new host or target
configuration name. Getting the program to compile and run properly represents
the hardest work of any port.
<P>
<A NAME="IDX216"></A>
<A NAME="IDX217"></A>
<H2><A NAME="SEC29" HREF="CONFIGUR.HTM#SEC29">Adding site info</A></H2>
<P>
If some of the <TT>`Makefile'</TT> defaults are not right for your site, you can
build site-specific <TT>`Makefile'</TT> fragments. To do this, do the following.
<P>
<UL>
<LI>
Choose a name for your site. It must currently be less than eleven characters.
<LI>
If the program source does not have a <TT>`./config/'</TT> subdirectory, create it.
<LI>
Create a file called <TT>`./config/ms-<VAR>site</VAR>'</TT> where <VAR>site</VAR> is the name
of your site. In it, set whatever <TT>`Makefile'</TT> variables you need to
