   This document describes the Cygnus Support version of `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.

   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.

Adding information about local conventions
==========================================

   If you find that a tool does not get configured to your liking, or if
`configure''s conventions differ from your local conventions, you should
probably consider "site-specific `Makefile' fragments".  See also
Adding site info.

   These are probably not the right choice for options that can be set
from the `configure' command line or for differences that are host or
target dependent.

   Cygnus `configure' uses three types of `Makefile' fragments.  In a
generated `Makefile' they appear in the order: "target fragment", "host
fragment", and "site fragment".  This allows host fragments to override
target fragments, and site fragments to override both.

   Host-specific `Makefile' fragments conventionally reside in the
`./config/' subdirectory with names of the form `mh-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 `Makefile' fragments conventionally reside in the
`./config/' subdirectory with names of the form `mt-TARGET'.  They are
used for target dependent compile time options.

   Site specific `Makefile' fragments conventionally reside in the
`./config/' subdirectory with names of the form `ms-SITE'.  They are
used to override host- and target-independent compile time options.
Note that you can also override these options on the `make' invocation
line.

Extensions to the GNU coding standards
======================================

   The following additions to the GNU coding standards are required for
Cygnus `configure' to work properly.

   * The `Makefile' must contain exactly one line starting with `####'.
     This line should follow any default macro definitions but precede
     any rules.  Host, target, and site-specific `Makefile' fragments
     will be inserted immediately after this line.  If the line is
     missing, the fragments will not be inserted.

   * Cygnus adds the following targets to each `Makefile'.  Their
     existence is not required for Cygnus `configure', but they are
     documented here for completeness.

    `info'
          Build all info files from texinfo source.

    `install-info'
          Install all info files.

    `clean-info'
          Remove all info files and any intermediate files that can be
          generated from texinfo source.

    `Makefile'
          Calls `./config.status' to rebuild the `Makefile' in this
          directory.

   * The following `Makefile' targets have revised semantics:

    `install'
          Should *not* depend on the target `all'.  If the program is
          not already built, `make install' should fail.  This allows
          you to install programs even when `make' would otherwise
          determine them to be out of date.  This can happen, for
          example, when the result of a `make all' is transported via
          tape to another machine for installation.

    `clean'
          Should remove any file that can be regenerated by the
          `Makefile', excepting only the `Makefile' itself, and any
          links created by `configure'.  That is, `make all clean'
          should return all directories to their original condition.
          If this is not done, then the command sequence

               configure HOST1 ; make all install clean ;
               configure HOST2 ; make all install

          will fail because of intermediate files intended for HOST1.

   * Cygnus adds the following macros to all `Makefile.in' files, but
     you are not required to use them to run Cygnus `configure'.

    `docdir'
          The directory in which to install any documentation that is
          not either a `man' page or an `info' file.  For `man' pages,
          see `mandir'; for `info', see `infodir'.

    `includedir'
          The directory in which to install any header files that
          should be made available to users.  This is distinct from the
          `gcc' include directory, which is intended for `gcc' only.
          Files in `includedir' may be used by `cc' as well.

   * The following macros have revised semantics.  Most of them describe
     installation directories; see also Full description of all installation subdirectories.

    `datadir'
          is used for host independent data files.

    `mandir'
          The default path for `mandir' depends on `prefix'.

    `infodir'
          The default path for `infodir' depends on `prefix'.

    `BISON'
          is assumed to have a `yacc' calling convention.  To use GNU
          `bison', use `BISON=bison -y'.

   * Each Cygnus `Makefile' also conforms to one additional restriction:

     When libraries are installed, the line containing the call to
     `INSTALL_DATA' should always be followed by a line containing a
     call to `RANLIB' on the installed library.  This is to accommodate
     systems that use `ranlib'.  Systems that do not use `ranlib' can
     set `RANLIB' to "`echo'" in a host specific `Makefile' fragment.

Porting with `configure'
************************

   This section explains how to add programs, host and target
configuration names, and site-specific information to Cygnus
`configure'.

Adding `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 `configure' script that meets the GNU
standards (see How Configuration Should Work (standards),
please do not add Cygnus `configure'.  It
should be possible to add this program without change to a Cygnus
`configure' style source tree.

   If the program is not target dependent, please consider using
`autoconf' instead of Cygnus `configure'.  `autoconf' is available from
the Free Software Foundation; it is a program which generates an
executable shell script called `configure' by automatically finding
information on the system to be configured on and embedding this
information in the shell script.  `configure' scripts generated by
`autoconf' require no arguments, and accept the same options as Cygnus
`configure'.  For detailed instructions on using `autoconf', see
How to organize and produce Autoconf scripts (autoconf).

   To add Cygnus `configure' to an existing program, do the following:

*Make sure the `Makefile' conforms to the GNU standard
     The coding standard for writing a GNU `Makefile' is described in
     Makefile Conventions (standards).  For technical
     information on writing a `Makefile', see Writing Makefiles (make).

*Add Cygnus extensions to the `Makefile'
     These are described in Extensions to the GNU coding standards.

*Collect package specific definitions in a single file
     Many packages are best configured using a common `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 `package_makefile_fragment' to the name of
     the file.  It will be inserted into the final `Makefile' before
     the target-specific fragment.

*Move host support from `Makefile' to fragments
     This usually involves finding sections of the `Makefile' that say
     things like "uncomment these lines for host HOSTTYPE" and moving
     them to a new file called `./config/mh-HOSTTYPE'. For more
     information, see Adding hosts and targets.

*Choose defaults
     If the program has compile-time options that determine the way the
     program should behave, choose reasonable defaults and make these
     `Makefile' variables.  Be sure the variables are assigned their
     default values before the `####' line so that site-specific
     `Makefile' fragments can override them (see Extensions to the GNU coding standards).

*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
     `./config/' subdirectory.

*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.  "Host specific" information is the
     information needed to compile the program.  "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 `./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 "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.

*Write `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 `./config' to files in the
     build directory with more generic names.  (See also Build directories.)
     The format of `configure.in' is
     described in The `configure.in' input file.in.

*Rename `Makefile' to `Makefile.in'
   At this point you should have a program that can be configured using
Cygnus `configure'.

Adding hosts and targets
========================

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

   * Make sure the new configuration name is represented in
     `config.sub'.  If not, add it.  For more details, see the comments
     in the shell script `config.sub'.

   * If you are adding a host configuration, look in `configure.in', in
     the "per-host" section.  Make sure that your configuration name is
     represented in the mapping from host configuration names to
     configuration files.  If not, add it.  Also see The `configure.in' input file.
     in.

   * If you are adding a target configuration, look in `configure.in',
     in the "per-target" section.  Make sure that your configuration
     name is represented in the mapping from target configuration names
     to configuration files.  If not, add it.  Also see The `configure.in' input file.
     in.

   * Look in `configure.in' for the variables `files', `links',
     `host_makefile_frag', and `target_makefile_frag'.  The values
     assigned to these variables are the names of the configuration
     files, (relative to `srcdir') that the program uses.  Make sure
     that copies of the files exist for your host.  If not, create
     them.  See also Variables available to `configure.in'.

   This should be enough to `configure' for a new host or target
configuration name.  Getting the program to compile and run properly
represents the hardest work of any port.

Adding site info
================

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

   * Choose a name for your site.  It must currently be less than
     eleven characters.

   * If the program source does not have a `./config/' subdirectory,
     create it.

   * Create a file called `./config/ms-SITE' where SITE is the name of
     your site.  In it, set whatever `Makefile' variables you need to
     override to match your site's conventions.

   * Configure the program with:

          configure ... --site=SITE