Home | History | Annotate | Download | only in info
      1 This is configure.info, produced by makeinfo version 4.8 from
      2 ./configure.texi.
      3 
      4 INFO-DIR-SECTION GNU admin
      5 START-INFO-DIR-ENTRY
      6 * configure: (configure).	The GNU configure and build system
      7 END-INFO-DIR-ENTRY
      8 
      9    This file documents the GNU configure and build system.
     10 
     11    Copyright (C) 1998 Cygnus Solutions.
     12 
     13    Permission is granted to make and distribute verbatim copies of this
     14 manual provided the copyright notice and this permission notice are
     15 preserved on all copies.
     16 
     17    Permission is granted to copy and distribute modified versions of
     18 this manual under the conditions for verbatim copying, provided that
     19 the entire resulting derived work is distributed under the terms of a
     20 permission notice identical to this one.
     21 
     22    Permission is granted to copy and distribute translations of this
     23 manual into another language, under the above conditions for modified
     24 versions, except that this permission notice may be stated in a
     25 translation approved by the Foundation.
     26 
     27 
     28 File: configure.info,  Node: Top,  Next: Introduction,  Up: (dir)
     29 
     30 GNU configure and build system
     31 ******************************
     32 
     33 The GNU configure and build system.
     34 
     35 * Menu:
     36 
     37 * Introduction::		Introduction.
     38 * Getting Started::		Getting Started.
     39 * Files::			Files.
     40 * Configuration Names::		Configuration Names.
     41 * Cross Compilation Tools::	Cross Compilation Tools.
     42 * Canadian Cross::		Canadian Cross.
     43 * Cygnus Configure::		Cygnus Configure.
     44 * Multilibs::			Multilibs.
     45 * FAQ::				Frequently Asked Questions.
     46 * Index::			Index.
     47 
     48 
     49 File: configure.info,  Node: Introduction,  Next: Getting Started,  Prev: Top,  Up: Top
     50 
     51 1 Introduction
     52 **************
     53 
     54 This document describes the GNU configure and build systems.  It
     55 describes how autoconf, automake, libtool, and make fit together.  It
     56 also includes a discussion of the older Cygnus configure system.
     57 
     58    This document does not describe in detail how to use each of the
     59 tools; see the respective manuals for that.  Instead, it describes
     60 which files the developer must write, which files are machine generated
     61 and how they are generated, and where certain common problems should be
     62 addressed.
     63 
     64    This document draws on several sources, including the autoconf
     65 manual by David MacKenzie (*note autoconf overview: (autoconf)Top.),
     66 the automake manual by David MacKenzie and Tom Tromey (*note automake
     67 overview: (automake)Top.), the libtool manual by Gordon Matzigkeit
     68 (*note libtool overview: (libtool)Top.), and the Cygnus configure
     69 manual by K. Richard Pixley.
     70 
     71 * Menu:
     72 
     73 * Goals::			Goals.
     74 * Tools::			The tools.
     75 * History::			History.
     76 * Building::			Building.
     77 
     78 
     79 File: configure.info,  Node: Goals,  Next: Tools,  Up: Introduction
     80 
     81 1.1 Goals
     82 =========
     83 
     84 The GNU configure and build system has two main goals.
     85 
     86    The first is to simplify the development of portable programs.  The
     87 system permits the developer to concentrate on writing the program,
     88 simplifying many details of portability across Unix and even Windows
     89 systems, and permitting the developer to describe how to build the
     90 program using simple rules rather than complex Makefiles.
     91 
     92    The second is to simplify the building of programs distributed as
     93 source code.  All programs are built using a simple, standardized, two
     94 step process.  The program builder need not install any special tools in
     95 order to build the program.
     96 
     97 
     98 File: configure.info,  Node: Tools,  Next: History,  Prev: Goals,  Up: Introduction
     99 
    100 1.2 Tools
    101 =========
    102 
    103 The GNU configure and build system is comprised of several different
    104 tools.  Program developers must build and install all of these tools.
    105 
    106    People who just want to build programs from distributed sources
    107 normally do not need any special tools beyond a Unix shell, a make
    108 program, and a C compiler.
    109 
    110 autoconf
    111      provides a general portability framework, based on testing the
    112      features of the host system at build time.
    113 
    114 automake
    115      a system for describing how to build a program, permitting the
    116      developer to write a simplified `Makefile'.
    117 
    118 libtool
    119      a standardized approach to building shared libraries.
    120 
    121 gettext
    122      provides a framework for translation of text messages into other
    123      languages; not really discussed in this document.
    124 
    125 m4
    126      autoconf requires the GNU version of m4; the standard Unix m4 does
    127      not suffice.
    128 
    129 perl
    130      automake requires perl.
    131 
    132 
    133 File: configure.info,  Node: History,  Next: Building,  Prev: Tools,  Up: Introduction
    134 
    135 1.3 History
    136 ===========
    137 
    138 This is a very brief and probably inaccurate history.
    139 
    140    As the number of Unix variants increased during the 1980s, it became
    141 harder to write programs which could run on all variants.  While it was
    142 often possible to use `#ifdef' to identify particular systems,
    143 developers frequently did not have access to every system, and the
    144 characteristics of some systems changed from version to version.
    145 
    146    By 1992, at least three different approaches had been developed:
    147    * The Metaconfig program, by Larry Wall, Harlan Stenn, and Raphael
    148      Manfredi.
    149 
    150    * The Cygnus configure script, by K. Richard Pixley, and the gcc
    151      configure script, by Richard Stallman.  These use essentially the
    152      same approach, and the developers communicated regularly.
    153 
    154    * The autoconf program, by David MacKenzie.
    155 
    156    The Metaconfig program is still used for Perl and a few other
    157 programs.  It is part of the Dist package.  I do not know if it is
    158 being developed.
    159 
    160    In 1994, David MacKenzie and others modified autoconf to incorporate
    161 all the features of Cygnus configure.  Since then, there has been a
    162 slow but steady conversion of GNU programs from Cygnus configure to
    163 autoconf. gcc has been converted, eliminating the gcc configure script.
    164 
    165    GNU autoconf was regularly maintained until late 1996.  As of this
    166 writing in June, 1998, it has no public maintainer.
    167 
    168    Most programs are built using the make program, which requires the
    169 developer to write Makefiles describing how to build the programs.
    170 Since most programs are built in pretty much the same way, this led to a
    171 lot of duplication.
    172 
    173    The X Window system is built using the imake tool, which uses a
    174 database of rules to eliminate the duplication.  However, building a
    175 tool which was developed using imake requires that the builder have
    176 imake installed, violating one of the goals of the GNU system.
    177 
    178    The new BSD make provides a standard library of Makefile fragments,
    179 which permits developers to write very simple Makefiles.  However, this
    180 requires that the builder install the new BSD make program.
    181 
    182    In 1994, David MacKenzie wrote the first version of automake, which
    183 permitted writing a simple build description which was converted into a
    184 Makefile which could be used by the standard make program.  In 1995, Tom
    185 Tromey completely rewrote automake in Perl, and he continues to enhance
    186 it.
    187 
    188    Various free packages built libraries, and by around 1995 several
    189 included support to build shared libraries on various platforms.
    190 However, there was no consistent approach.  In early 1996, Gordon
    191 Matzigkeit began working on libtool, which provided a standardized
    192 approach to building shared libraries.  This was integrated into
    193 automake from the start.
    194 
    195    The development of automake and libtool was driven by the GNITS
    196 project, a group of GNU maintainers who designed standardized tools to
    197 help meet the GNU coding standards.
    198 
    199 
    200 File: configure.info,  Node: Building,  Prev: History,  Up: Introduction
    201 
    202 1.4 Building
    203 ============
    204 
    205 Most readers of this document should already know how to build a tool by
    206 running `configure' and `make'.  This section may serve as a quick
    207 introduction or reminder.
    208 
    209    Building a tool is normally as simple as running `configure'
    210 followed by `make'.  You should normally run `configure' from an empty
    211 directory, using some path to refer to the `configure' script in the
    212 source directory.  The directory in which you run `configure' is called
    213 the "object directory".
    214 
    215    In order to use a object directory which is different from the source
    216 directory, you must be using the GNU version of `make', which has the
    217 required `VPATH' support.  Despite this restriction, using a different
    218 object directory is highly recommended:
    219    * It keeps the files generated during the build from cluttering up
    220      your sources.
    221 
    222    * It permits you to remove the built files by simply removing the
    223      entire build directory.
    224 
    225    * It permits you to build from the same sources with several sets of
    226      configure options simultaneously.
    227 
    228    If you don't have GNU `make', you will have to run `configure' in
    229 the source directory.  All GNU packages should support this; in
    230 particular, GNU packages should not assume the presence of GNU `make'.
    231 
    232    After running `configure', you can build the tools by running `make'.
    233 
    234    To install the tools, run `make install'.  Installing the tools will
    235 copy the programs and any required support files to the "installation
    236 directory".  The location of the installation directory is controlled
    237 by `configure' options, as described below.
    238 
    239    In the Cygnus tree at present, the info files are built and
    240 installed as a separate step.  To build them, run `make info'.  To
    241 install them, run `make install-info'. The equivalent html files are
    242 also built and installed in a separate step. To build the html files,
    243 run `make html'. To install the html files run `make install-html'.
    244 
    245    All `configure' scripts support a wide variety of options.  The most
    246 interesting ones are `--with' and `--enable' options which are
    247 generally specific to particular tools.  You can usually use the
    248 `--help' option to get a list of interesting options for a particular
    249 configure script.
    250 
    251    The only generic options you are likely to use are the `--prefix'
    252 and `--exec-prefix' options.  These options are used to specify the
    253 installation directory.
    254 
    255    The directory named by the `--prefix' option will hold machine
    256 independent files such as info files.
    257 
    258    The directory named by the `--exec-prefix' option, which is normally
    259 a subdirectory of the `--prefix' directory, will hold machine dependent
    260 files such as executables.
    261 
    262    The default for `--prefix' is `/usr/local'.  The default for
    263 `--exec-prefix' is the value used for `--prefix'.
    264 
    265    The convention used in Cygnus releases is to use a `--prefix' option
    266 of `/usr/cygnus/RELEASE', where RELEASE is the name of the release, and
    267 to use a `--exec-prefix' option of `/usr/cygnus/RELEASE/H-HOST', where
    268 HOST is the configuration name of the host system (*note Configuration
    269 Names::).
    270 
    271    Do not use either the source or the object directory as the
    272 installation directory.  That will just lead to confusion.
    273 
    274 
    275 File: configure.info,  Node: Getting Started,  Next: Files,  Prev: Introduction,  Up: Top
    276 
    277 2 Getting Started
    278 *****************
    279 
    280 To start using the GNU configure and build system with your software
    281 package, you must write three files, and you must run some tools to
    282 manually generate additional files.
    283 
    284 * Menu:
    285 
    286 * Write configure.in::		Write configure.in.
    287 * Write Makefile.am::		Write Makefile.am.
    288 * Write acconfig.h::		Write acconfig.h.
    289 * Generate files::		Generate files.
    290 * Getting Started Example::	Example.
    291 
    292 
    293 File: configure.info,  Node: Write configure.in,  Next: Write Makefile.am,  Up: Getting Started
    294 
    295 2.1 Write configure.in
    296 ======================
    297 
    298 You must first write the file `configure.in'.  This is an autoconf
    299 input file, and the autoconf manual describes in detail what this file
    300 should look like.
    301 
    302    You will write tests in your `configure.in' file to check for
    303 conditions that may change from one system to another, such as the
    304 presence of particular header files or functions.
    305 
    306    For example, not all systems support the `gettimeofday' function.
    307 If you want to use the `gettimeofday' function when it is available,
    308 and to use some other function when it is not, you would check for this
    309 by putting `AC_CHECK_FUNCS(gettimeofday)' in `configure.in'.
    310 
    311    When the configure script is run at build time, this will arrange to
    312 define the preprocessor macro `HAVE_GETTIMEOFDAY' to the value 1 if the
    313 `gettimeofday' function is available, and to not define the macro at
    314 all if the function is not available.  Your code can then use `#ifdef'
    315 to test whether it is safe to call `gettimeofday'.
    316 
    317    If you have an existing body of code, the `autoscan' program may
    318 help identify potential portability problems, and hence configure tests
    319 that you will want to use.  *Note Invoking autoscan: (autoconf)Invoking
    320 autoscan.
    321 
    322    Another handy tool for an existing body of code is `ifnames'.  This
    323 will show you all the preprocessor conditionals that the code already
    324 uses.  *Note Invoking ifnames: (autoconf)Invoking ifnames.
    325 
    326    Besides the portability tests which are specific to your particular
    327 package, every `configure.in' file should contain the following macros.
    328 
    329 `AC_INIT'
    330      This macro takes a single argument, which is the name of a file in
    331      your package.  For example, `AC_INIT(foo.c)'.
    332 
    333 `AC_PREREQ(VERSION)'
    334      This macro is optional.  It may be used to indicate the version of
    335      `autoconf' that you are using.  This will prevent users from
    336      running an earlier version of `autoconf' and perhaps getting an
    337      invalid `configure' script.  For example, `AC_PREREQ(2.12)'.
    338 
    339 `AM_INIT_AUTOMAKE'
    340      This macro takes two arguments: the name of the package, and a
    341      version number.  For example, `AM_INIT_AUTOMAKE(foo, 1.0)'.  (This
    342      macro is not needed if you are not using automake).
    343 
    344 `AM_CONFIG_HEADER'
    345      This macro names the header file which will hold the preprocessor
    346      macro definitions at run time.  Normally this should be
    347      `config.h'.  Your sources would then use `#include "config.h"' to
    348      include it.
    349 
    350      This macro may optionally name the input file for that header
    351      file; by default, this is `config.h.in', but that file name works
    352      poorly on DOS filesystems.  Therefore, it is often better to name
    353      it explicitly as `config.in'.
    354 
    355      This is what you should normally put in `configure.in':
    356           AM_CONFIG_HEADER(config.h:config.in)
    357 
    358      (If you are not using automake, use `AC_CONFIG_HEADER' rather than
    359      `AM_CONFIG_HEADER').
    360 
    361 `AM_MAINTAINER_MODE'
    362      This macro always appears in Cygnus configure scripts.  Other
    363      programs may or may not use it.
    364 
    365      If this macro is used, the `--enable-maintainer-mode' option is
    366      required to enable automatic rebuilding of generated files used by
    367      the configure system.  This of course requires that developers be
    368      aware of, and use, that option.
    369 
    370      If this macro is not used, then the generated files will always be
    371      rebuilt automatically.  This will cause problems if the wrong
    372      versions of autoconf, automake, or others are in the builder's
    373      `PATH'.
    374 
    375      (If you are not using automake, you do not need to use this macro).
    376 
    377 `AC_EXEEXT'
    378      Either this macro or `AM_EXEEXT' always appears in Cygnus configure
    379      files.  Other programs may or may not use one of them.
    380 
    381      This macro looks for the executable suffix used on the host
    382      system.  On Unix systems, this is the empty string.  On Windows
    383      systems, this is `.exe'.  This macro directs automake to use the
    384      executable suffix as appropriate when creating programs.  This
    385      macro does not take any arguments.
    386 
    387      The `AC_EXEEXT' form is new, and is part of a Cygnus patch to
    388      autoconf to support compiling with Visual C++.  Older programs use
    389      `AM_EXEEXT' instead.
    390 
    391      (Programs which do not use automake use neither `AC_EXEEXT' nor
    392      `AM_EXEEXT').
    393 
    394 `AC_PROG_CC'
    395      If you are writing C code, you will normally want to use this
    396      macro.  It locates the C compiler to use.  It does not take any
    397      arguments.
    398 
    399      However, if this `configure.in' file is for a library which is to
    400      be compiled by a cross compiler which may not fully work, then you
    401      will not want to use `AC_PROG_CC'.  Instead, you will want to use a
    402      variant which does not call the macro `AC_PROG_CC_WORKS'.  Examples
    403      can be found in various `configure.in' files for libraries that are
    404      compiled with cross compilers, such as libiberty or libgloss.
    405      This is essentially a bug in autoconf, and there will probably be
    406      a better workaround at some point.
    407 
    408 `AC_PROG_CXX'
    409      If you are writing C++ code, you will want to use this macro.  It
    410      locates the C++ compiler to use.  It does not take any arguments.
    411      The same cross compiler comments apply as for `AC_PROG_CC'.
    412 
    413 `AM_PROG_LIBTOOL'
    414      If you want to build libraries, and you want to permit them to be
    415      shared, or you want to link against libraries which were built
    416      using libtool, then you will need this macro.  This macro is
    417      required in order to use libtool.
    418 
    419      By default, this will cause all libraries to be built as shared
    420      libraries.  To prevent this-to change the default-use
    421      `AM_DISABLE_SHARED' before `AM_PROG_LIBTOOL'.  The configure
    422      options `--enable-shared' and `--disable-shared' may be used to
    423      override the default at build time.
    424 
    425 `AC_DEFINE(_GNU_SOURCE)'
    426      GNU packages should normally include this line before any other
    427      feature tests.  This defines the macro `_GNU_SOURCE' when
    428      compiling, which directs the libc header files to provide the
    429      standard GNU system interfaces including all GNU extensions.  If
    430      this macro is not defined, certain GNU extensions may not be
    431      available.
    432 
    433 `AC_OUTPUT'
    434      This macro takes a list of file names which the configure process
    435      should produce.  This is normally a list of one or more `Makefile'
    436      files in different directories.  If your package lives entirely in
    437      a single directory, you would use simply `AC_OUTPUT(Makefile)'.
    438      If you also have, for example, a `lib' subdirectory, you would use
    439      `AC_OUTPUT(Makefile lib/Makefile)'.
    440 
    441    If you want to use locally defined macros in your `configure.in'
    442 file, then you will need to write a `acinclude.m4' file which defines
    443 them (if not using automake, this file is called `aclocal.m4').
    444 Alternatively, you can put separate macros in an `m4' subdirectory, and
    445 put `ACLOCAL_AMFLAGS = -I m4' in your `Makefile.am' file so that the
    446 `aclocal' program will be able to find them.
    447 
    448    The different macro prefixes indicate which tool defines the macro.
    449 Macros which start with `AC_' are part of autoconf.  Macros which start
    450 with `AM_' are provided by automake or libtool.
    451 
    452 
    453 File: configure.info,  Node: Write Makefile.am,  Next: Write acconfig.h,  Prev: Write configure.in,  Up: Getting Started
    454 
    455 2.2 Write Makefile.am
    456 =====================
    457 
    458 You must write the file `Makefile.am'.  This is an automake input file,
    459 and the automake manual describes in detail what this file should look
    460 like.
    461 
    462    The automake commands in `Makefile.am' mostly look like variable
    463 assignments in a `Makefile'.  automake recognizes special variable
    464 names, and automatically add make rules to the output as needed.
    465 
    466    There will be one `Makefile.am' file for each directory in your
    467 package.  For each directory with subdirectories, the `Makefile.am'
    468 file should contain the line
    469      SUBDIRS = DIR DIR ...
    470    where each DIR is the name of a subdirectory.
    471 
    472    For each `Makefile.am', there should be a corresponding `Makefile'
    473 in the `AC_OUTPUT' macro in `configure.in'.
    474 
    475    Every `Makefile.am' written at Cygnus should contain the line
    476      AUTOMAKE_OPTIONS = cygnus
    477    This puts automake into Cygnus mode.  See the automake manual for
    478 details.
    479 
    480    You may to include the version number of `automake' that you are
    481 using on the `AUTOMAKE_OPTIONS' line.  For example,
    482      AUTOMAKE_OPTIONS = cygnus 1.3
    483    This will prevent users from running an earlier version of
    484 `automake' and perhaps getting an invalid `Makefile.in'.
    485 
    486    If your package builds a program, then in the directory where that
    487 program is built you will normally want a line like
    488      bin_PROGRAMS = PROGRAM
    489    where PROGRAM is the name of the program.  You will then want a line
    490 like
    491      PROGRAM_SOURCES = FILE FILE ...
    492    where each FILE is the name of a source file to link into the
    493 program (e.g., `foo.c').
    494 
    495    If your package builds a library, and you do not want the library to
    496 ever be built as a shared library, then in the directory where that
    497 library is built you will normally want a line like
    498      lib_LIBRARIES = libNAME.a
    499    where `libNAME.a' is the name of the library.  You will then want a
    500 line like
    501      libNAME_a_SOURCES = FILE FILE ...
    502    where each FILE is the name of a source file to add to the library.
    503 
    504    If your package builds a library, and you want to permit building the
    505 library as a shared library, then in the directory where that library is
    506 built you will normally want a line like
    507      lib_LTLIBRARIES = libNAME.la
    508    The use of `LTLIBRARIES', and the `.la' extension, indicate a
    509 library to be built using libtool.  As usual, you will then want a line
    510 like
    511      libNAME_la_SOURCES = FILE FILE ...
    512 
    513    The strings `bin' and `lib' that appear above in `bin_PROGRAMS' and
    514 `lib_LIBRARIES' are not arbitrary.  They refer to particular
    515 directories, which may be set by the `--bindir' and `--libdir' options
    516 to `configure'.  If those options are not used, the default values are
    517 based on the `--prefix' or `--exec-prefix' options to `configure'.  It
    518 is possible to use other names if the program or library should be
    519 installed in some other directory.
    520 
    521    The `Makefile.am' file may also contain almost anything that may
    522 appear in a normal `Makefile'.  automake also supports many other
    523 special variables, as well as conditionals.
    524 
    525    See the automake manual for more information.
    526 
    527 
    528 File: configure.info,  Node: Write acconfig.h,  Next: Generate files,  Prev: Write Makefile.am,  Up: Getting Started
    529 
    530 2.3 Write acconfig.h
    531 ====================
    532 
    533 If you are generating a portability header file, (i.e., you are using
    534 `AM_CONFIG_HEADER' in `configure.in'), then you will have to write a
    535 `acconfig.h' file.  It will have to contain the following lines.
    536 
    537      /* Name of package.  */
    538      #undef PACKAGE
    539 
    540      /* Version of package.  */
    541      #undef VERSION
    542 
    543    This requirement is really a bug in the system, and the requirement
    544 may be eliminated at some later date.
    545 
    546    The `acconfig.h' file will also similar comment and `#undef' lines
    547 for any unusual macros in the `configure.in' file, including any macro
    548 which appears in a `AC_DEFINE' macro.
    549 
    550    In particular, if you are writing a GNU package and therefore include
    551 `AC_DEFINE(_GNU_SOURCE)' in `configure.in' as suggested above, you will
    552 need lines like this in `acconfig.h':
    553      /* Enable GNU extensions.  */
    554      #undef _GNU_SOURCE
    555 
    556    Normally the `autoheader' program will inform you of any such
    557 requirements by printing an error message when it is run.  However, if
    558 you do anything particular odd in your `configure.in' file, you will
    559 have to make sure that the right entries appear in `acconfig.h', since
    560 otherwise the results of the tests may not be available in the
    561 `config.h' file which your code will use.
    562 
    563    (Thee `PACKAGE' and `VERSION' lines are not required if you are not
    564 using automake, and in that case you may not need a `acconfig.h' file
    565 at all).
    566 
    567 
    568 File: configure.info,  Node: Generate files,  Next: Getting Started Example,  Prev: Write acconfig.h,  Up: Getting Started
    569 
    570 2.4 Generate files
    571 ==================
    572 
    573 Once you have written `configure.in', `Makefile.am', `acconfig.h', and
    574 possibly `acinclude.m4', you must use autoconf and automake programs to
    575 produce the first versions of the generated files.  This is done by
    576 executing the following sequence of commands.
    577 
    578      aclocal
    579      autoconf
    580      autoheader
    581      automake
    582 
    583    The `aclocal' and `automake' commands are part of the automake
    584 package, and the `autoconf' and `autoheader' commands are part of the
    585 autoconf package.
    586 
    587    If you are using a `m4' subdirectory for your macros, you will need
    588 to use the `-I m4' option when you run `aclocal'.
    589 
    590    If you are not using the Cygnus tree, use the `-a' option when
    591 running `automake' command in order to copy the required support files
    592 into your source directory.
    593 
    594    If you are using libtool, you must build and install the libtool
    595 package with the same `--prefix' and `--exec-prefix' options as you
    596 used with the autoconf and automake packages.  You must do this before
    597 running any of the above commands.  If you are not using the Cygnus
    598 tree, you will need to run the `libtoolize' program to copy the libtool
    599 support files into your directory.
    600 
    601    Once you have managed to run these commands without getting any
    602 errors, you should create a new empty directory, and run the `configure'
    603 script which will have been created by `autoconf' with the
    604 `--enable-maintainer-mode' option.  This will give you a set of
    605 Makefiles which will include rules to automatically rebuild all the
    606 generated files.
    607 
    608    After doing that, whenever you have changed some of the input files
    609 and want to regenerated the other files, go to your object directory
    610 and run `make'.  Doing this is more reliable than trying to rebuild the
    611 files manually, because there are complex order dependencies and it is
    612 easy to forget something.
    613 
    614 
    615 File: configure.info,  Node: Getting Started Example,  Prev: Generate files,  Up: Getting Started
    616 
    617 2.5 Example
    618 ===========
    619 
    620 Let's consider a trivial example.
    621 
    622    Suppose we want to write a simple version of `touch'.  Our program,
    623 which we will call `poke', will take a single file name argument, and
    624 use the `utime' system call to set the modification and access times of
    625 the file to the current time.  We want this program to be highly
    626 portable.
    627 
    628    We'll first see what this looks like without using autoconf and
    629 automake, and then see what it looks like with them.
    630 
    631 * Menu:
    632 
    633 * Getting Started Example 1::		First Try.
    634 * Getting Started Example 2::		Second Try.
    635 * Getting Started Example 3::		Third Try.
    636 * Generate Files in Example::		Generate Files.
    637 
    638 
    639 File: configure.info,  Node: Getting Started Example 1,  Next: Getting Started Example 2,  Up: Getting Started Example
    640 
    641 2.5.1 First Try
    642 ---------------
    643 
    644 Here is our first try at `poke.c'.  Note that we've written it without
    645 ANSI/ISO C prototypes, since we want it to be highly portable.
    646 
    647      #include <stdio.h>
    648      #include <stdlib.h>
    649      #include <sys/types.h>
    650      #include <utime.h>
    651 
    652      int
    653      main (argc, argv)
    654           int argc;
    655           char **argv;
    656      {
    657        if (argc != 2)
    658          {
    659            fprintf (stderr, "Usage: poke file\n");
    660            exit (1);
    661          }
    662 
    663        if (utime (argv[1], NULL) < 0)
    664          {
    665            perror ("utime");
    666            exit (1);
    667          }
    668 
    669        exit (0);
    670      }
    671 
    672    We also write a simple `Makefile'.
    673 
    674      CC = gcc
    675      CFLAGS = -g -O2
    676 
    677      all: poke
    678 
    679      poke: poke.o
    680      	$(CC) -o poke $(CFLAGS) $(LDFLAGS) poke.o
    681 
    682    So far, so good.
    683 
    684    Unfortunately, there are a few problems.
    685 
    686    On older Unix systems derived from BSD 4.3, the `utime' system call
    687 does not accept a second argument of `NULL'.  On those systems, we need
    688 to pass a pointer to `struct utimbuf' structure.  Unfortunately, even
    689 older systems don't define that structure; on those systems, we need to
    690 pass an array of two `long' values.
    691 
    692    The header file `stdlib.h' was invented by ANSI C, and older systems
    693 don't have a copy.  We included it above to get a declaration of `exit'.
    694 
    695    We can find some of these portability problems by running
    696 `autoscan', which will create a `configure.scan' file which we can use
    697 as a prototype for our `configure.in' file.  I won't show the output,
    698 but it will notice the potential problems with `utime' and `stdlib.h'.
    699 
    700    In our `Makefile', we don't provide any way to install the program.
    701 This doesn't matter much for such a simple example, but a real program
    702 will need an `install' target.  For that matter, we will also want a
    703 `clean' target.
    704 
    705 
    706 File: configure.info,  Node: Getting Started Example 2,  Next: Getting Started Example 3,  Prev: Getting Started Example 1,  Up: Getting Started Example
    707 
    708 2.5.2 Second Try
    709 ----------------
    710 
    711 Here is our second try at this program.
    712 
    713    We modify `poke.c' to use preprocessor macros to control what
    714 features are available.  (I've cheated a bit by using the same macro
    715 names which autoconf will use).
    716 
    717      #include <stdio.h>
    718 
    719      #ifdef STDC_HEADERS
    720      #include <stdlib.h>
    721      #endif
    722 
    723      #include <sys/types.h>
    724 
    725      #ifdef HAVE_UTIME_H
    726      #include <utime.h>
    727      #endif
    728 
    729      #ifndef HAVE_UTIME_NULL
    730 
    731      #include <time.h>
    732 
    733      #ifndef HAVE_STRUCT_UTIMBUF
    734 
    735      struct utimbuf
    736      {
    737        long actime;
    738        long modtime;
    739      };
    740 
    741      #endif
    742 
    743      static int
    744      utime_now (file)
    745           char *file;
    746      {
    747        struct utimbuf now;
    748 
    749        now.actime = now.modtime = time (NULL);
    750        return utime (file, &now);
    751      }
    752 
    753      #define utime(f, p) utime_now (f)
    754 
    755      #endif /* HAVE_UTIME_NULL  */
    756 
    757      int
    758      main (argc, argv)
    759           int argc;
    760           char **argv;
    761      {
    762        if (argc != 2)
    763          {
    764            fprintf (stderr, "Usage: poke file\n");
    765            exit (1);
    766          }
    767 
    768        if (utime (argv[1], NULL) < 0)
    769          {
    770            perror ("utime");
    771            exit (1);
    772          }
    773 
    774        exit (0);
    775      }
    776 
    777    Here is the associated `Makefile'.  We've added support for the
    778 preprocessor flags we use.  We've also added `install' and `clean'
    779 targets.
    780 
    781      # Set this to your installation directory.
    782      bindir = /usr/local/bin
    783 
    784      # Uncomment this if you have the standard ANSI/ISO C header files.
    785      # STDC_HDRS = -DSTDC_HEADERS
    786 
    787      # Uncomment this if you have utime.h.
    788      # UTIME_H = -DHAVE_UTIME_H
    789 
    790      # Uncomment this if utime (FILE, NULL) works on your system.
    791      # UTIME_NULL = -DHAVE_UTIME_NULL
    792 
    793      # Uncomment this if struct utimbuf is defined in utime.h.
    794      # UTIMBUF = -DHAVE_STRUCT_UTIMBUF
    795 
    796      CC = gcc
    797      CFLAGS = -g -O2
    798 
    799      ALL_CFLAGS = $(STDC_HDRS) $(UTIME_H) $(UTIME_NULL) $(UTIMBUF) $(CFLAGS)
    800 
    801      all: poke
    802 
    803      poke: poke.o
    804      	$(CC) -o poke $(ALL_CFLAGS) $(LDFLAGS) poke.o
    805 
    806      .c.o:
    807      	$(CC) -c $(ALL_CFLAGS) poke.c
    808 
    809      install: poke
    810      	cp poke $(bindir)/poke
    811 
    812      clean:
    813      	rm poke poke.o
    814 
    815    Some problems with this approach should be clear.
    816 
    817    Users who want to compile poke will have to know how `utime' works
    818 on their systems, so that they can uncomment the `Makefile' correctly.
    819 
    820    The installation is done using `cp', but many systems have an
    821 `install' program which may be used, and which supports optional
    822 features such as stripping debugging information out of the installed
    823 binary.
    824 
    825    The use of `Makefile' variables like `CC', `CFLAGS' and `LDFLAGS'
    826 follows the requirements of the GNU standards.  This is convenient for
    827 all packages, since it reduces surprises for users.  However, it is
    828 easy to get the details wrong, and wind up with a slightly nonstandard
    829 distribution.
    830 
    831 
    832 File: configure.info,  Node: Getting Started Example 3,  Next: Generate Files in Example,  Prev: Getting Started Example 2,  Up: Getting Started Example
    833 
    834 2.5.3 Third Try
    835 ---------------
    836 
    837 For our third try at this program, we will write a `configure.in'
    838 script to discover the configuration features on the host system, rather
    839 than requiring the user to edit the `Makefile'.  We will also write a
    840 `Makefile.am' rather than a `Makefile'.
    841 
    842    The only change to `poke.c' is to add a line at the start of the
    843 file:
    844      #include "config.h"
    845 
    846    The new `configure.in' file is as follows.
    847 
    848      AC_INIT(poke.c)
    849      AM_INIT_AUTOMAKE(poke, 1.0)
    850      AM_CONFIG_HEADER(config.h:config.in)
    851      AC_PROG_CC
    852      AC_HEADER_STDC
    853      AC_CHECK_HEADERS(utime.h)
    854      AC_EGREP_HEADER(utimbuf, utime.h, AC_DEFINE(HAVE_STRUCT_UTIMBUF))
    855      AC_FUNC_UTIME_NULL
    856      AC_OUTPUT(Makefile)
    857 
    858    The first four macros in this file, and the last one, were described
    859 above; see *Note Write configure.in::.  If we omit these macros, then
    860 when we run `automake' we will get a reminder that we need them.
    861 
    862    The other macros are standard autoconf macros.
    863 
    864 `AC_HEADER_STDC'
    865      Check for standard C headers.
    866 
    867 `AC_CHECK_HEADERS'
    868      Check whether a particular header file exists.
    869 
    870 `AC_EGREP_HEADER'
    871      Check for a particular string in a particular header file, in this
    872      case checking for `utimbuf' in `utime.h'.
    873 
    874 `AC_FUNC_UTIME_NULL'
    875      Check whether `utime' accepts a NULL second argument to set the
    876      file change time to the current time.
    877 
    878    See the autoconf manual for a more complete description.
    879 
    880    The new `Makefile.am' file is as follows.  Note how simple this is
    881 compared to our earlier `Makefile'.
    882 
    883      bin_PROGRAMS = poke
    884 
    885      poke_SOURCES = poke.c
    886 
    887    This means that we should build a single program name `poke'.  It
    888 should be installed in the binary directory, which we called `bindir'
    889 earlier.  The program `poke' is built from the source file `poke.c'.
    890 
    891    We must also write a `acconfig.h' file.  Besides `PACKAGE' and
    892 `VERSION', which must be mentioned for all packages which use automake,
    893 we must include `HAVE_STRUCT_UTIMBUF', since we mentioned it in an
    894 `AC_DEFINE'.
    895 
    896      /* Name of package.  */
    897      #undef PACKAGE
    898 
    899      /* Version of package.  */
    900      #undef VERSION
    901 
    902      /* Whether utime.h defines struct utimbuf.  */
    903      #undef HAVE_STRUCT_UTIMBUF
    904 
    905 
    906 File: configure.info,  Node: Generate Files in Example,  Prev: Getting Started Example 3,  Up: Getting Started Example
    907 
    908 2.5.4 Generate Files
    909 --------------------
    910 
    911 We must now generate the other files, using the following commands.
    912 
    913      aclocal
    914      autoconf
    915      autoheader
    916      automake
    917 
    918    When we run `autoheader', it will remind us of any macros we forgot
    919 to add to `acconfig.h'.
    920 
    921    When we run `automake', it will want to add some files to our
    922 distribution.  It will add them automatically if we use the
    923 `--add-missing' option.
    924 
    925    By default, `automake' will run in GNU mode, which means that it
    926 will want us to create certain additional files; as of this writing, it
    927 will want `NEWS', `README', `AUTHORS', and `ChangeLog', all of which
    928 are files which should appear in a standard GNU distribution.  We can
    929 either add those files, or run `automake' with the `--foreign' option.
    930 
    931    Running these tools will generate the following files, all of which
    932 are described in the next chapter.
    933 
    934    * `aclocal.m4'
    935 
    936    * `configure'
    937 
    938    * `config.in'
    939 
    940    * `Makefile.in'
    941 
    942    * `stamp-h.in'
    943 
    944 
    945 File: configure.info,  Node: Files,  Next: Configuration Names,  Prev: Getting Started,  Up: Top
    946 
    947 3 Files
    948 *******
    949 
    950 As was seen in the previous chapter, the GNU configure and build system
    951 uses a number of different files.  The developer must write a few files.
    952 The others are generated by various tools.
    953 
    954    The system is rather flexible, and can be used in many different
    955 ways.  In describing the files that it uses, I will describe the common
    956 case, and mention some other cases that may arise.
    957 
    958 * Menu:
    959 
    960 * Developer Files::		Developer Files.
    961 * Build Files::			Build Files.
    962 * Support Files::		Support Files.
    963 
    964 
    965 File: configure.info,  Node: Developer Files,  Next: Build Files,  Up: Files
    966 
    967 3.1 Developer Files
    968 ===================
    969 
    970 This section describes the files written or generated by the developer
    971 of a package.
    972 
    973 * Menu:
    974 
    975 * Developer Files Picture::	Developer Files Picture.
    976 * Written Developer Files::	Written Developer Files.
    977 * Generated Developer Files::	Generated Developer Files.
    978 
    979 
    980 File: configure.info,  Node: Developer Files Picture,  Next: Written Developer Files,  Up: Developer Files
    981 
    982 3.1.1 Developer Files Picture
    983 -----------------------------
    984 
    985 Here is a picture of the files which are written by the developer, the
    986 generated files which would be included with a complete source
    987 distribution, and the tools which create those files.  The file names
    988 are plain text and the tool names are enclosed by `*' characters (e.g.,
    989 `autoheader' is the name of a tool, not the name of a file).
    990 
    991    acconfig.h       configure.in                 Makefile.am
    992        |                |                           |
    993        |  --------------+----------------------     |
    994        |  |             |                     |     |
    995        v  v             |    acinclude.m4     |     |
    996    *autoheader*         |         |           v     v
    997        |                |         v      --->*automake*
    998        v                |--->*aclocal*   |       |
    999    config.in            |         |      |       v
   1000                         |         v      |   Makefile.in
   1001                         |    aclocal.m4---
   1002                         |     |
   1003                         v     v
   1004                        *autoconf*
   1005                            |
   1006                            v
   1007                        configure
   1008 
   1009 
   1010 File: configure.info,  Node: Written Developer Files,  Next: Generated Developer Files,  Prev: Developer Files Picture,  Up: Developer Files
   1011 
   1012 3.1.2 Written Developer Files
   1013 -----------------------------
   1014 
   1015 The following files would be written by the developer.
   1016 
   1017 `configure.in'
   1018      This is the configuration script.  This script contains
   1019      invocations of autoconf macros.  It may also contain ordinary
   1020      shell script code.  This file will contain feature tests for
   1021      portability issues.  The last thing in the file will normally be
   1022      an `AC_OUTPUT' macro listing which files to create when the
   1023      builder runs the configure script.  This file is always required
   1024      when using the GNU configure system.  *Note Write configure.in::.
   1025 
   1026 `Makefile.am'
   1027      This is the automake input file.  It describes how the code should
   1028      be built.  It consists of definitions of automake variables.  It
   1029      may also contain ordinary Makefile targets.  This file is only
   1030      needed when using automake (newer tools normally use automake, but
   1031      there are still older tools which have not been converted, in
   1032      which the developer writes `Makefile.in' directly).  *Note Write
   1033      Makefile.am::.
   1034 
   1035 `acconfig.h'
   1036      When the configure script creates a portability header file, by
   1037      using `AM_CONFIG_HEADER' (or, if not using automake,
   1038      `AC_CONFIG_HEADER'), this file is used to describe macros which are
   1039      not recognized by the `autoheader' command.  This is normally a
   1040      fairly uninteresting file, consisting of a collection of `#undef'
   1041      lines with comments.  Normally any call to `AC_DEFINE' in
   1042      `configure.in' will require a line in this file. *Note Write
   1043      acconfig.h::.
   1044 
   1045 `acinclude.m4'
   1046      This file is not always required.  It defines local autoconf
   1047      macros.  These macros may then be used in `configure.in'.  If you
   1048      don't need any local autoconf macros, then you don't need this
   1049      file at all.  In fact, in general, you never need local autoconf
   1050      macros, since you can put everything in `configure.in', but
   1051      sometimes a local macro is convenient.
   1052 
   1053      Newer tools may omit `acinclude.m4', and instead use a
   1054      subdirectory, typically named `m4', and define `ACLOCAL_AMFLAGS =
   1055      -I m4' in `Makefile.am' to force `aclocal' to look there for macro
   1056      definitions.  The macro definitions are then placed in separate
   1057      files in that directory.
   1058 
   1059      The `acinclude.m4' file is only used when using automake; in older
   1060      tools, the developer writes `aclocal.m4' directly, if it is needed.
   1061 
   1062 
   1063 File: configure.info,  Node: Generated Developer Files,  Prev: Written Developer Files,  Up: Developer Files
   1064 
   1065 3.1.3 Generated Developer Files
   1066 -------------------------------
   1067 
   1068 The following files would be generated by the developer.
   1069 
   1070    When using automake, these files are normally not generated manually
   1071 after the first time.  Instead, the generated `Makefile' contains rules
   1072 to automatically rebuild the files as required.  When
   1073 `AM_MAINTAINER_MODE' is used in `configure.in' (the normal case in
   1074 Cygnus code), the automatic rebuilding rules will only be defined if
   1075 you configure using the `--enable-maintainer-mode' option.
   1076 
   1077    When using automatic rebuilding, it is important to ensure that all
   1078 the various tools have been built and installed on your `PATH'.  Using
   1079 automatic rebuilding is highly recommended, so much so that I'm not
   1080 going to explain what you have to do if you don't use it.
   1081 
   1082 `configure'
   1083      This is the configure script which will be run when building the
   1084      package.  This is generated by `autoconf' from `configure.in' and
   1085      `aclocal.m4'.  This is a shell script.
   1086 
   1087 `Makefile.in'
   1088      This is the file which the configure script will turn into the
   1089      `Makefile' at build time.  This file is generated by `automake'
   1090      from `Makefile.am'.  If you aren't using automake, you must write
   1091      this file yourself.  This file is pretty much a normal `Makefile',
   1092      with some configure substitutions for certain variables.
   1093 
   1094 `aclocal.m4'
   1095      This file is created by the `aclocal' program, based on the
   1096      contents of `configure.in' and `acinclude.m4' (or, as noted in the
   1097      description of `acinclude.m4' above, on the contents of an `m4'
   1098      subdirectory).  This file contains definitions of autoconf macros
   1099      which `autoconf' will use when generating the file `configure'.
   1100      These autoconf macros may be defined by you in `acinclude.m4' or
   1101      they may be defined by other packages such as automake, libtool or
   1102      gettext.  If you aren't using automake, you will normally write
   1103      this file yourself; in that case, if `configure.in' uses only
   1104      standard autoconf macros, this file will not be needed at all.
   1105 
   1106 `config.in'
   1107      This file is created by `autoheader' based on `acconfig.h' and
   1108      `configure.in'.  At build time, the configure script will define
   1109      some of the macros in it to create `config.h', which may then be
   1110      included by your program.  This permits your C code to use
   1111      preprocessor conditionals to change its behaviour based on the
   1112      characteristics of the host system.  This file may also be called
   1113      `config.h.in'.
   1114 
   1115 `stamp.h-in'
   1116      This rather uninteresting file, which I omitted from the picture,
   1117      is generated by `automake'.  It always contains the string
   1118      `timestamp'.  It is used as a timestamp file indicating whether
   1119      `config.in' is up to date.  Using a timestamp file means that
   1120      `config.in' can be marked as up to date without actually changing
   1121      its modification time.  This is useful since `config.in' depends
   1122      upon `configure.in', but it is easy to change `configure.in' in a
   1123      way which does not affect `config.in'.
   1124 
   1125 
   1126 File: configure.info,  Node: Build Files,  Next: Support Files,  Prev: Developer Files,  Up: Files
   1127 
   1128 3.2 Build Files
   1129 ===============
   1130 
   1131 This section describes the files which are created at configure and
   1132 build time.  These are the files which somebody who builds the package
   1133 will see.
   1134 
   1135    Of course, the developer will also build the package.  The
   1136 distinction between developer files and build files is not that the
   1137 developer does not see the build files, but that somebody who only
   1138 builds the package does not have to worry about the developer files.
   1139 
   1140 * Menu:
   1141 
   1142 * Build Files Picture::		Build Files Picture.
   1143 * Build Files Description::	Build Files Description.
   1144 
   1145 
   1146 File: configure.info,  Node: Build Files Picture,  Next: Build Files Description,  Up: Build Files
   1147 
   1148 3.2.1 Build Files Picture
   1149 -------------------------
   1150 
   1151 Here is a picture of the files which will be created at build time.
   1152 `config.status' is both a created file and a shell script which is run
   1153 to create other files, and the picture attempts to show that.
   1154 
   1155    config.in        *configure*      Makefile.in
   1156       |                  |               |
   1157       |                  v               |
   1158       |             config.status        |
   1159       |                  |               |
   1160    *config.status*<======+==========>*config.status*
   1161       |                                  |
   1162       v                                  v
   1163    config.h                          Makefile
   1164 
   1165 
   1166 File: configure.info,  Node: Build Files Description,  Prev: Build Files Picture,  Up: Build Files
   1167 
   1168 3.2.2 Build Files Description
   1169 -----------------------------
   1170 
   1171 This is a description of the files which are created at build time.
   1172 
   1173 `config.status'
   1174      The first step in building a package is to run the `configure'
   1175      script.  The `configure' script will create the file
   1176      `config.status', which is itself a shell script.  When you first
   1177      run `configure', it will automatically run `config.status'.  An
   1178      `Makefile' derived from an automake generated `Makefile.in' will
   1179      contain rules to automatically run `config.status' again when
   1180      necessary to recreate certain files if their inputs change.
   1181 
   1182 `Makefile'
   1183      This is the file which make will read to build the program.  The
   1184      `config.status' script will transform `Makefile.in' into
   1185      `Makefile'.
   1186 
   1187 `config.h'
   1188      This file defines C preprocessor macros which C code can use to
   1189      adjust its behaviour on different systems.  The `config.status'
   1190      script will transform `config.in' into `config.h'.
   1191 
   1192 `config.cache'
   1193      This file did not fit neatly into the picture, and I omitted it.
   1194      It is used by the `configure' script to cache results between
   1195      runs.  This can be an important speedup.  If you modify
   1196      `configure.in' in such a way that the results of old tests should
   1197      change (perhaps you have added a new library to `LDFLAGS'), then
   1198      you will have to remove `config.cache' to force the tests to be
   1199      rerun.
   1200 
   1201      The autoconf manual explains how to set up a site specific cache
   1202      file.  This can speed up running `configure' scripts on your
   1203      system.
   1204 
   1205 `stamp.h'
   1206      This file, which I omitted from the picture, is similar to
   1207      `stamp-h.in'.  It is used as a timestamp file indicating whether
   1208      `config.h' is up to date.  This is useful since `config.h' depends
   1209      upon `config.status', but it is easy for `config.status' to change
   1210      in a way which does not affect `config.h'.
   1211 
   1212 
   1213 File: configure.info,  Node: Support Files,  Prev: Build Files,  Up: Files
   1214 
   1215 3.3 Support Files
   1216 =================
   1217 
   1218 The GNU configure and build system requires several support files to be
   1219 included with your distribution.  You do not normally need to concern
   1220 yourself with these.  If you are using the Cygnus tree, most are already
   1221 present.  Otherwise, they will be installed with your source by
   1222 `automake' (with the `--add-missing' option) and `libtoolize'.
   1223 
   1224    You don't have to put the support files in the top level directory.
   1225 You can put them in a subdirectory, and use the `AC_CONFIG_AUX_DIR'
   1226 macro in `configure.in' to tell `automake' and the `configure' script
   1227 where they are.
   1228 
   1229    In this section, I describe the support files, so that you can know
   1230 what they are and why they are there.
   1231 
   1232 `ABOUT-NLS'
   1233      Added by automake if you are using gettext.  This is a
   1234      documentation file about the gettext project.
   1235 
   1236 `ansi2knr.c'
   1237      Used by an automake generated `Makefile' if you put `ansi2knr' in
   1238      `AUTOMAKE_OPTIONS' in `Makefile.am'.  This permits compiling ANSI
   1239      C code with a K&R C compiler.
   1240 
   1241 `ansi2knr.1'
   1242      The man page which goes with `ansi2knr.c'.
   1243 
   1244 `config.guess'
   1245      A shell script which determines the configuration name for the
   1246      system on which it is run.
   1247 
   1248 `config.sub'
   1249      A shell script which canonicalizes a configuration name entered by
   1250      a user.
   1251 
   1252 `elisp-comp'
   1253      Used to compile Emacs LISP files.
   1254 
   1255 `install-sh'
   1256      A shell script which installs a program.  This is used if the
   1257      configure script can not find an install binary.
   1258 
   1259 `ltconfig'
   1260      Used by libtool.  This is a shell script which configures libtool
   1261      for the particular system on which it is used.
   1262 
   1263 `ltmain.sh'
   1264      Used by libtool.  This is the actual libtool script which is used,
   1265      after it is configured by `ltconfig' to build a library.
   1266 
   1267 `mdate-sh'
   1268      A shell script used by an automake generated `Makefile' to pretty
   1269      print the modification time of a file.  This is used to maintain
   1270      version numbers for texinfo files.
   1271 
   1272 `missing'
   1273      A shell script used if some tool is missing entirely.  This is
   1274      used by an automake generated `Makefile' to avoid certain sorts of
   1275      timestamp problems.
   1276 
   1277 `mkinstalldirs'
   1278      A shell script which creates a directory, including all parent
   1279      directories.  This is used by an automake generated `Makefile'
   1280      during installation.
   1281 
   1282 `texinfo.tex'
   1283      Required if you have any texinfo files.  This is used when
   1284      converting Texinfo files into DVI using `texi2dvi' and TeX.
   1285 
   1286 `ylwrap'
   1287      A shell script used by an automake generated `Makefile' to run
   1288      programs like `bison', `yacc', `flex', and `lex'.  These programs
   1289      default to producing output files with a fixed name, and the
   1290      `ylwrap' script runs them in a subdirectory to avoid file name
   1291      conflicts when using a parallel make program.
   1292 
   1293 
   1294 File: configure.info,  Node: Configuration Names,  Next: Cross Compilation Tools,  Prev: Files,  Up: Top
   1295 
   1296 4 Configuration Names
   1297 *********************
   1298 
   1299 The GNU configure system names all systems using a "configuration
   1300 name".  All such names used to be triplets (they may now contain four
   1301 parts in certain cases), and the term "configuration triplet" is still
   1302 seen.
   1303 
   1304 * Menu:
   1305 
   1306 * Configuration Name Definition::	Configuration Name Definition.
   1307 * Using Configuration Names::		Using Configuration Names.
   1308 
   1309 
   1310 File: configure.info,  Node: Configuration Name Definition,  Next: Using Configuration Names,  Up: Configuration Names
   1311 
   1312 4.1 Configuration Name Definition
   1313 =================================
   1314 
   1315 This is a string of the form CPU-MANUFACTURER-OPERATING_SYSTEM.  In
   1316 some cases, this is extended to a four part form:
   1317 CPU-MANUFACTURER-KERNEL-OPERATING_SYSTEM.
   1318 
   1319    When using a configuration name in a configure option, it is normally
   1320 not necessary to specify an entire name.  In particular, the
   1321 MANUFACTURER field is often omitted, leading to strings such as
   1322 `i386-linux' or `sparc-sunos'.  The shell script `config.sub' will
   1323 translate these shortened strings into the canonical form.  autoconf
   1324 will arrange for `config.sub' to be run automatically when it is needed.
   1325 
   1326    The fields of a configuration name are as follows:
   1327 
   1328 CPU
   1329      The type of processor.  This is typically something like `i386' or
   1330      `sparc'.  More specific variants are used as well, such as
   1331      `mipsel' to indicate a little endian MIPS processor.
   1332 
   1333 MANUFACTURER
   1334      A somewhat freeform field which indicates the manufacturer of the
   1335      system.  This is often simply `unknown'.  Other common strings are
   1336      `pc' for an IBM PC compatible system, or the name of a workstation
   1337      vendor, such as `sun'.
   1338 
   1339 OPERATING_SYSTEM
   1340      The name of the operating system which is run on the system.  This
   1341      will be something like `solaris2.5' or `irix6.3'.  There is no
   1342      particular restriction on the version number, and strings like
   1343      `aix4.1.4.0' are seen.  For an embedded system, which has no
   1344      operating system, this field normally indicates the type of object
   1345      file format, such as `elf' or `coff'.
   1346 
   1347 KERNEL
   1348      This is used mainly for GNU/Linux.  A typical GNU/Linux
   1349      configuration name is `i586-pc-linux-gnulibc1'.  In this case the
   1350      kernel, `linux', is separated from the operating system,
   1351      `gnulibc1'.
   1352 
   1353    The shell script `config.guess' will normally print the correct
   1354 configuration name for the system on which it is run.  It does by
   1355 running `uname' and by examining other characteristics of the system.
   1356 
   1357    Because `config.guess' can normally determine the configuration name
   1358 for a machine, it is normally only necessary to specify a configuration
   1359 name when building a cross-compiler or when building using a
   1360 cross-compiler.
   1361 
   1362 
   1363 File: configure.info,  Node: Using Configuration Names,  Prev: Configuration Name Definition,  Up: Configuration Names
   1364 
   1365 4.2 Using Configuration Names
   1366 =============================
   1367 
   1368 A configure script will sometimes have to make a decision based on a
   1369 configuration name.  You will need to do this if you have to compile
   1370 code differently based on something which can not be tested using a
   1371 standard autoconf feature test.
   1372 
   1373    It is normally better to test for particular features, rather than to
   1374 test for a particular system.  This is because as Unix evolves,
   1375 different systems copy features from one another.  Even if you need to
   1376 determine whether the feature is supported based on a configuration
   1377 name, you should define a macro which describes the feature, rather than
   1378 defining a macro which describes the particular system you are on.
   1379 
   1380    Testing for a particular system is normally done using a case
   1381 statement in `configure.in'.  The case statement might look something
   1382 like the following, assuming that `host' is a shell variable holding a
   1383 canonical configuration name (which will be the case if `configure.in'
   1384 uses the `AC_CANONICAL_HOST' or `AC_CANONICAL_SYSTEM' macro).
   1385 
   1386      case "${host}" in
   1387      i[3-7]86-*-linux-gnu*) do something ;;
   1388      sparc*-sun-solaris2.[56789]*) do something ;;
   1389      sparc*-sun-solaris*) do something ;;
   1390      mips*-*-elf*) do something ;;
   1391      esac
   1392 
   1393    It is particularly important to use `*' after the operating system
   1394 field, in order to match the version number which will be generated by
   1395 `config.guess'.
   1396 
   1397    In most cases you must be careful to match a range of processor
   1398 types.  For most processor families, a trailing `*' suffices, as in
   1399 `mips*' above.  For the i386 family, something along the lines of
   1400 `i[3-7]86' suffices at present.  For the m68k family, you will need
   1401 something like `m68*'.  Of course, if you do not need to match on the
   1402 processor, it is simpler to just replace the entire field by a `*', as
   1403 in `*-*-irix*'.
   1404 
   1405 
   1406 File: configure.info,  Node: Cross Compilation Tools,  Next: Canadian Cross,  Prev: Configuration Names,  Up: Top
   1407 
   1408 5 Cross Compilation Tools
   1409 *************************
   1410 
   1411 The GNU configure and build system can be used to build "cross
   1412 compilation" tools.  A cross compilation tool is a tool which runs on
   1413 one system and produces code which runs on another system.
   1414 
   1415 * Menu:
   1416 
   1417 * Cross Compilation Concepts::		Cross Compilation Concepts.
   1418 * Host and Target::			Host and Target.
   1419 * Using the Host Type::			Using the Host Type.
   1420 * Specifying the Target::       	Specifying the Target.
   1421 * Using the Target Type::		Using the Target Type.
   1422 * Cross Tools in the Cygnus Tree::	Cross Tools in the Cygnus Tree
   1423 
   1424 
   1425 File: configure.info,  Node: Cross Compilation Concepts,  Next: Host and Target,  Up: Cross Compilation Tools
   1426 
   1427 5.1 Cross Compilation Concepts
   1428 ==============================
   1429 
   1430 A compiler which produces programs which run on a different system is a
   1431 cross compilation compiler, or simply a "cross compiler".  Similarly,
   1432 we speak of cross assemblers, cross linkers, etc.
   1433 
   1434    In the normal case, a compiler produces code which runs on the same
   1435 system as the one on which the compiler runs.  When it is necessary to
   1436 distinguish this case from the cross compilation case, such a compiler
   1437 is called a "native compiler".  Similarly, we speak of native
   1438 assemblers, etc.
   1439 
   1440    Although the debugger is not strictly speaking a compilation tool,
   1441 it is nevertheless meaningful to speak of a cross debugger: a debugger
   1442 which is used to debug code which runs on another system.  Everything
   1443 that is said below about configuring cross compilation tools applies to
   1444 the debugger as well.
   1445 
   1446 
   1447 File: configure.info,  Node: Host and Target,  Next: Using the Host Type,  Prev: Cross Compilation Concepts,  Up: Cross Compilation Tools
   1448 
   1449 5.2 Host and Target
   1450 ===================
   1451 
   1452 When building cross compilation tools, there are two different systems
   1453 involved: the system on which the tools will run, and the system for
   1454 which the tools generate code.
   1455 
   1456    The system on which the tools will run is called the "host" system.
   1457 
   1458    The system for which the tools generate code is called the "target"
   1459 system.
   1460 
   1461    For example, suppose you have a compiler which runs on a GNU/Linux
   1462 system and generates ELF programs for a MIPS embedded system.  In this
   1463 case the GNU/Linux system is the host, and the MIPS ELF system is the
   1464 target.  Such a compiler could be called a GNU/Linux cross MIPS ELF
   1465 compiler, or, equivalently, a `i386-linux-gnu' cross `mips-elf'
   1466 compiler.
   1467 
   1468    Naturally, most programs are not cross compilation tools.  For those
   1469 programs, it does not make sense to speak of a target.  It only makes
   1470 sense to speak of a target for tools like `gcc' or the `binutils' which
   1471 actually produce running code.  For example, it does not make sense to
   1472 speak of the target of a tool like `bison' or `make'.
   1473 
   1474    Most cross compilation tools can also serve as native tools.  For a
   1475 native compilation tool, it is still meaningful to speak of a target.
   1476 For a native tool, the target is the same as the host.  For example, for
   1477 a GNU/Linux native compiler, the host is GNU/Linux, and the target is
   1478 also GNU/Linux.
   1479 
   1480 
   1481 File: configure.info,  Node: Using the Host Type,  Next: Specifying the Target,  Prev: Host and Target,  Up: Cross Compilation Tools
   1482 
   1483 5.3 Using the Host Type
   1484 =======================
   1485 
   1486 In almost all cases the host system is the system on which you run the
   1487 `configure' script, and on which you build the tools (for the case when
   1488 they differ, *note Canadian Cross::).
   1489 
   1490    If your configure script needs to know the configuration name of the
   1491 host system, and the package is not a cross compilation tool and
   1492 therefore does not have a target, put `AC_CANONICAL_HOST' in
   1493 `configure.in'.  This macro will arrange to define a few shell
   1494 variables when the `configure' script is run.
   1495 
   1496 `host'
   1497      The canonical configuration name of the host.  This will normally
   1498      be determined by running the `config.guess' shell script, although
   1499      the user is permitted to override this by using an explicit
   1500      `--host' option.
   1501 
   1502 `host_alias'
   1503      In the unusual case that the user used an explicit `--host' option,
   1504      this will be the argument to `--host'.  In the normal case, this
   1505      will be the same as the `host' variable.
   1506 
   1507 `host_cpu'
   1508 `host_vendor'
   1509 `host_os'
   1510      The first three parts of the canonical configuration name.
   1511 
   1512    The shell variables may be used by putting shell code in
   1513 `configure.in'.  For an example, see *Note Using Configuration Names::.
   1514 
   1515 
   1516 File: configure.info,  Node: Specifying the Target,  Next: Using the Target Type,  Prev: Using the Host Type,  Up: Cross Compilation Tools
   1517 
   1518 5.4 Specifying the Target
   1519 =========================
   1520 
   1521 By default, the `configure' script will assume that the target is the
   1522 same as the host.  This is the more common case; for example, it leads
   1523 to a native compiler rather than a cross compiler.
   1524 
   1525    If you want to build a cross compilation tool, you must specify the
   1526 target explicitly by using the `--target' option when you run
   1527 `configure'.  The argument to `--target' is the configuration name of
   1528 the system for which you wish to generate code.  *Note Configuration
   1529 Names::.
   1530 
   1531    For example, to build tools which generate code for a MIPS ELF
   1532 embedded system, you would use `--target mips-elf'.
   1533 
   1534 
   1535 File: configure.info,  Node: Using the Target Type,  Next: Cross Tools in the Cygnus Tree,  Prev: Specifying the Target,  Up: Cross Compilation Tools
   1536 
   1537 5.5 Using the Target Type
   1538 =========================
   1539 
   1540 When writing `configure.in' for a cross compilation tool, you will need
   1541 to use information about the target.  To do this, put
   1542 `AC_CANONICAL_SYSTEM' in `configure.in'.
   1543 
   1544    `AC_CANONICAL_SYSTEM' will look for a `--target' option and
   1545 canonicalize it using the `config.sub' shell script.  It will also run
   1546 `AC_CANONICAL_HOST' (*note Using the Host Type::).
   1547 
   1548    The target type will be recorded in the following shell variables.
   1549 Note that the host versions of these variables will also be defined by
   1550 `AC_CANONICAL_HOST'.
   1551 
   1552 `target'
   1553      The canonical configuration name of the target.
   1554 
   1555 `target_alias'
   1556      The argument to the `--target' option.  If the user did not specify
   1557      a `--target' option, this will be the same as `host_alias'.
   1558 
   1559 `target_cpu'
   1560 `target_vendor'
   1561 `target_os'
   1562      The first three parts of the canonical target configuration name.
   1563 
   1564    Note that if `host' and `target' are the same string, you can assume
   1565 a native configuration.  If they are different, you can assume a cross
   1566 configuration.
   1567 
   1568    It is arguably possible for `host' and `target' to represent the
   1569 same system, but for the strings to not be identical.  For example, if
   1570 `config.guess' returns `sparc-sun-sunos4.1.4', and somebody configures
   1571 with `--target sparc-sun-sunos4.1', then the slight differences between
   1572 the two versions of SunOS may be unimportant for your tool.  However,
   1573 in the general case it can be quite difficult to determine whether the
   1574 differences between two configuration names are significant or not.
   1575 Therefore, by convention, if the user specifies a `--target' option
   1576 without specifying a `--host' option, it is assumed that the user wants
   1577 to configure a cross compilation tool.
   1578 
   1579    The variables `target' and `target_alias' should be handled
   1580 differently.
   1581 
   1582    In general, whenever the user may actually see a string,
   1583 `target_alias' should be used.  This includes anything which may appear
   1584 in the file system, such as a directory name or part of a tool name.
   1585 It also includes any tool output, unless it is clearly labelled as the
   1586 canonical target configuration name.  This permits the user to use the
   1587 `--target' option to specify how the tool will appear to the outside
   1588 world.
   1589 
   1590    On the other hand, when checking for characteristics of the target
   1591 system, `target' should be used.  This is because a wide variety of
   1592 `--target' options may map into the same canonical configuration name.
   1593 You should not attempt to duplicate the canonicalization done by
   1594 `config.sub' in your own code.
   1595 
   1596    By convention, cross tools are installed with a prefix of the
   1597 argument used with the `--target' option, also known as `target_alias'
   1598 (*note Using the Target Type::).  If the user does not use the
   1599 `--target' option, and thus is building a native tool, no prefix is
   1600 used.
   1601 
   1602    For example, if gcc is configured with `--target mips-elf', then the
   1603 installed binary will be named `mips-elf-gcc'.  If gcc is configured
   1604 without a `--target' option, then the installed binary will be named
   1605 `gcc'.
   1606 
   1607    The autoconf macro `AC_ARG_PROGRAM' will handle this for you.  If
   1608 you are using automake, no more need be done; the programs will
   1609 automatically be installed with the correct prefixes.  Otherwise, see
   1610 the autoconf documentation for `AC_ARG_PROGRAM'.
   1611 
   1612 
   1613 File: configure.info,  Node: Cross Tools in the Cygnus Tree,  Prev: Using the Target Type,  Up: Cross Compilation Tools
   1614 
   1615 5.6 Cross Tools in the Cygnus Tree
   1616 ==================================
   1617 
   1618 The Cygnus tree is used for various packages including gdb, the GNU
   1619 binutils, and egcs.  It is also, of course, used for Cygnus releases.
   1620 
   1621    In the Cygnus tree, the top level `configure' script uses the old
   1622 Cygnus configure system, not autoconf.  The top level `Makefile.in' is
   1623 written to build packages based on what is in the source tree, and
   1624 supports building a large number of tools in a single
   1625 `configure'/`make' step.
   1626 
   1627    The Cygnus tree may be configured with a `--target' option.  The
   1628 `--target' option applies recursively to every subdirectory, and
   1629 permits building an entire set of cross tools at once.
   1630 
   1631 * Menu:
   1632 
   1633 * Host and Target Libraries::		Host and Target Libraries.
   1634 * Target Library Configure Scripts::	Target Library Configure Scripts.
   1635 * Make Targets in Cygnus Tree::         Make Targets in Cygnus Tree.
   1636 * Target libiberty::			Target libiberty
   1637 
   1638 
   1639 File: configure.info,  Node: Host and Target Libraries,  Next: Target Library Configure Scripts,  Up: Cross Tools in the Cygnus Tree
   1640 
   1641 5.6.1 Host and Target Libraries
   1642 -------------------------------
   1643 
   1644 The Cygnus tree distinguishes host libraries from target libraries.
   1645 
   1646    Host libraries are built with the compiler used to build the programs
   1647 which run on the host, which is called the host compiler.  This includes
   1648 libraries such as `bfd' and `tcl'.  These libraries are built with the
   1649 host compiler, and are linked into programs like the binutils or gcc
   1650 which run on the host.
   1651 
   1652    Target libraries are built with the target compiler.  If gcc is
   1653 present in the source tree, then the target compiler is the gcc that is
   1654 built using the host compiler.  Target libraries are libraries such as
   1655 `newlib' and `libstdc++'.  These libraries are not linked into the host
   1656 programs, but are instead made available for use with programs built
   1657 with the target compiler.
   1658 
   1659    For the rest of this section, assume that gcc is present in the
   1660 source tree, so that it will be used to build the target libraries.
   1661 
   1662    There is a complication here.  The configure process needs to know
   1663 which compiler you are going to use to build a tool; otherwise, the
   1664 feature tests will not work correctly.  The Cygnus tree handles this by
   1665 not configuring the target libraries until the target compiler is
   1666 built.  In order to permit everything to build using a single
   1667 `configure'/`make', the configuration of the target libraries is
   1668 actually triggered during the make step.
   1669 
   1670    When the target libraries are configured, the `--target' option is
   1671 not used.  Instead, the `--host' option is used with the argument of
   1672 the `--target' option for the overall configuration.  If no `--target'
   1673 option was used for the overall configuration, the `--host' option will
   1674 be passed with the output of the `config.guess' shell script.  Any
   1675 `--build' option is passed down unchanged.
   1676 
   1677    This translation of configuration options is done because since the
   1678 target libraries are compiled with the target compiler, they are being
   1679 built in order to run on the target of the overall configuration.  By
   1680 the definition of host, this means that their host system is the same as
   1681 the target system of the overall configuration.
   1682 
   1683    The same process is used for both a native configuration and a cross
   1684 configuration.  Even when using a native configuration, the target
   1685 libraries will be configured and built using the newly built compiler.
   1686 This is particularly important for the C++ libraries, since there is no
   1687 reason to assume that the C++ compiler used to build the host tools (if
   1688 there even is one) uses the same ABI as the g++ compiler which will be
   1689 used to build the target libraries.
   1690 
   1691    There is one difference between a native configuration and a cross
   1692 configuration.  In a native configuration, the target libraries are
   1693 normally configured and built as siblings of the host tools.  In a cross
   1694 configuration, the target libraries are normally built in a subdirectory
   1695 whose name is the argument to `--target'.  This is mainly for
   1696 historical reasons.
   1697 
   1698    To summarize, running `configure' in the Cygnus tree configures all
   1699 the host libraries and tools, but does not configure any of the target
   1700 libraries.  Running `make' then does the following steps:
   1701 
   1702    * Build the host libraries.
   1703 
   1704    * Build the host programs, including gcc.  Note that we call gcc
   1705      both a host program (since it runs on the host) and a target
   1706      compiler (since it generates code for the target).
   1707 
   1708    * Using the newly built target compiler, configure the target
   1709      libraries.
   1710 
   1711    * Build the target libraries.
   1712 
   1713    The steps need not be done in precisely this order, since they are
   1714 actually controlled by `Makefile' targets.
   1715 
   1716 
   1717 File: configure.info,  Node: Target Library Configure Scripts,  Next: Make Targets in Cygnus Tree,  Prev: Host and Target Libraries,  Up: Cross Tools in the Cygnus Tree
   1718 
   1719 5.6.2 Target Library Configure Scripts
   1720 --------------------------------------
   1721 
   1722 There are a few things you must know in order to write a configure
   1723 script for a target library.  This is just a quick sketch, and beginners
   1724 shouldn't worry if they don't follow everything here.
   1725 
   1726    The target libraries are configured and built using a newly built
   1727 target compiler.  There may not be any startup files or libraries for
   1728 this target compiler.  In fact, those files will probably be built as
   1729 part of some target library, which naturally means that they will not
   1730 exist when your target library is configured.
   1731 
   1732    This means that the configure script for a target library may not use
   1733 any test which requires doing a link.  This unfortunately includes many
   1734 useful autoconf macros, such as `AC_CHECK_FUNCS'.  autoconf macros
   1735 which do a compile but not a link, such as `AC_CHECK_HEADERS', may be
   1736 used.
   1737 
   1738    This is a severe restriction, but normally not a fatal one, as target
   1739 libraries can often assume the presence of other target libraries, and
   1740 thus know which functions will be available.
   1741 
   1742    As of this writing, the autoconf macro `AC_PROG_CC' does a link to
   1743 make sure that the compiler works.  This may fail in a target library,
   1744 so target libraries must use a different set of macros to locate the
   1745 compiler.  See the `configure.in' file in a directory like `libiberty'
   1746 or `libgloss' for an example.
   1747 
   1748    As noted in the previous section, target libraries are sometimes
   1749 built in directories which are siblings to the host tools, and are
   1750 sometimes built in a subdirectory.  The `--with-target-subdir' configure
   1751 option will be passed when the library is configured.  Its value will be
   1752 an empty string if the target library is a sibling.  Its value will be
   1753 the name of the subdirectory if the target library is in a subdirectory.
   1754 
   1755    If the overall build is not a native build (i.e., the overall
   1756 configure used the `--target' option), then the library will be
   1757 configured with the `--with-cross-host' option.  The value of this
   1758 option will be the host system of the overall build.  Recall that the
   1759 host system of the library will be the target of the overall build.  If
   1760 the overall build is a native build, the `--with-cross-host' option
   1761 will not be used.
   1762 
   1763    A library which can be built both standalone and as a target library
   1764 may want to install itself into different directories depending upon the
   1765 case.  When built standalone, or when built native, the library should
   1766 be installed in `$(libdir)'.  When built as a target library which is
   1767 not native, the library should be installed in `$(tooldir)/lib'.  The
   1768 `--with-cross-host' option may be used to distinguish these cases.
   1769 
   1770    This same test of `--with-cross-host' may be used to see whether it
   1771 is OK to use link tests in the configure script.  If the
   1772 `--with-cross-host' option is not used, then the library is being built
   1773 either standalone or native, and a link should work.
   1774 
   1775 
   1776 File: configure.info,  Node: Make Targets in Cygnus Tree,  Next: Target libiberty,  Prev: Target Library Configure Scripts,  Up: Cross Tools in the Cygnus Tree
   1777 
   1778 5.6.3 Make Targets in Cygnus Tree
   1779 ---------------------------------
   1780 
   1781 The top level `Makefile' in the Cygnus tree defines targets for every
   1782 known subdirectory.
   1783 
   1784    For every subdirectory DIR which holds a host library or program,
   1785 the `Makefile' target `all-DIR' will build that library or program.
   1786 
   1787    There are dependencies among host tools.  For example, building gcc
   1788 requires first building gas, because the gcc build process invokes the
   1789 target assembler.  These dependencies are reflected in the top level
   1790 `Makefile'.
   1791 
   1792    For every subdirectory DIR which holds a target library, the
   1793 `Makefile' target `configure-target-DIR' will configure that library.
   1794 The `Makefile' target `all-target-DIR' will build that library.
   1795 
   1796    Every `configure-target-DIR' target depends upon `all-gcc', since
   1797 gcc, the target compiler, is required to configure the tool.  Every
   1798 `all-target-DIR' target depends upon the corresponding
   1799 `configure-target-DIR' target.
   1800 
   1801    There are several other targets which may be of interest for each
   1802 directory: `install-DIR', `clean-DIR', and `check-DIR'.  There are also
   1803 corresponding `target' versions of these for the target libraries ,
   1804 such as `install-target-DIR'.
   1805 
   1806 
   1807 File: configure.info,  Node: Target libiberty,  Prev: Make Targets in Cygnus Tree,  Up: Cross Tools in the Cygnus Tree
   1808 
   1809 5.6.4 Target libiberty
   1810 ----------------------
   1811 
   1812 The `libiberty' subdirectory is currently a special case, in that it is
   1813 the only directory which is built both using the host compiler and
   1814 using the target compiler.
   1815 
   1816    This is because the files in `libiberty' are used when building the
   1817 host tools, and they are also incorporated into the `libstdc++' target
   1818 library as support code.
   1819 
   1820    This duality does not pose any particular difficulties.  It means
   1821 that there are targets for both `all-libiberty' and
   1822 `all-target-libiberty'.
   1823 
   1824    In a native configuration, when target libraries are not built in a
   1825 subdirectory, the same objects are normally used as both the host build
   1826 and the target build.  This is normally OK, since libiberty contains
   1827 only C code, and in a native configuration the results of the host
   1828 compiler and the target compiler are normally interoperable.
   1829 
   1830    Irix 6 is again an exception here, since the SGI native compiler
   1831 defaults to using the `O32' ABI, and gcc defaults to using the `N32'
   1832 ABI.  On Irix 6, the target libraries are built in a subdirectory even
   1833 for a native configuration, avoiding this problem.
   1834 
   1835    There are currently no other libraries built for both the host and
   1836 the target, but there is no conceptual problem with adding more.
   1837 
   1838 
   1839 File: configure.info,  Node: Canadian Cross,  Next: Cygnus Configure,  Prev: Cross Compilation Tools,  Up: Top
   1840 
   1841 6 Canadian Cross
   1842 ****************
   1843 
   1844 It is possible to use the GNU configure and build system to build a
   1845 program which will run on a system which is different from the system on
   1846 which the tools are built.  In other words, it is possible to build
   1847 programs using a cross compiler.
   1848 
   1849    This is referred to as a "Canadian Cross".
   1850 
   1851 * Menu:
   1852 
   1853 * Canadian Cross Example::		Canadian Cross Example.
   1854 * Canadian Cross Concepts::		Canadian Cross Concepts.
   1855 * Build Cross Host Tools::		Build Cross Host Tools.
   1856 * Build and Host Options::		Build and Host Options.
   1857 * CCross not in Cygnus Tree::		Canadian Cross not in Cygnus Tree.
   1858 * CCross in Cygnus Tree::		Canadian Cross in Cygnus Tree.
   1859 * Supporting Canadian Cross::		Supporting Canadian Cross.
   1860 
   1861 
   1862 File: configure.info,  Node: Canadian Cross Example,  Next: Canadian Cross Concepts,  Up: Canadian Cross
   1863 
   1864 6.1 Canadian Cross Example
   1865 ==========================
   1866 
   1867 Here is an example of a Canadian Cross.
   1868 
   1869    While running on a GNU/Linux, you can build a program which will run
   1870 on a Solaris system.  You would use a GNU/Linux cross Solaris compiler
   1871 to build the program.
   1872 
   1873    Of course, you could not run the resulting program on your GNU/Linux
   1874 system.  You would have to copy it over to a Solaris system before you
   1875 would run it.
   1876 
   1877    Of course, you could also simply build the programs on the Solaris
   1878 system in the first place.  However, perhaps the Solaris system is not
   1879 available for some reason; perhaps you actually don't have one, but you
   1880 want to build the tools for somebody else to use.  Or perhaps your
   1881 GNU/Linux system is much faster than your Solaris system.
   1882 
   1883    A Canadian Cross build is most frequently used when building
   1884 programs to run on a non-Unix system, such as DOS or Windows.  It may
   1885 be simpler to configure and build on a Unix system than to support the
   1886 configuration machinery on a non-Unix system.
   1887 
   1888 
   1889 File: configure.info,  Node: Canadian Cross Concepts,  Next: Build Cross Host Tools,  Prev: Canadian Cross Example,  Up: Canadian Cross
   1890 
   1891 6.2 Canadian Cross Concepts
   1892 ===========================
   1893 
   1894 When building a Canadian Cross, there are at least two different systems
   1895 involved: the system on which the tools are being built, and the system
   1896 on which the tools will run.
   1897 
   1898    The system on which the tools are being built is called the "build"
   1899 system.
   1900 
   1901    The system on which the tools will run is called the host system.
   1902 
   1903    For example, if you are building a Solaris program on a GNU/Linux
   1904 system, as in the previous section, the build system would be GNU/Linux,
   1905 and the host system would be Solaris.
   1906 
   1907    It is, of course, possible to build a cross compiler using a Canadian
   1908 Cross (i.e., build a cross compiler using a cross compiler).  In this
   1909 case, the system for which the resulting cross compiler generates code
   1910 is called the target system.  (For a more complete discussion of host
   1911 and target systems, *note Host and Target::).
   1912 
   1913    An example of building a cross compiler using a Canadian Cross would
   1914 be building a Windows cross MIPS ELF compiler on a GNU/Linux system.  In
   1915 this case the build system would be GNU/Linux, the host system would be
   1916 Windows, and the target system would be MIPS ELF.
   1917 
   1918    The name Canadian Cross comes from the case when the build, host, and
   1919 target systems are all different.  At the time that these issues were
   1920 all being hashed out, Canada had three national political parties.
   1921 
   1922 
   1923 File: configure.info,  Node: Build Cross Host Tools,  Next: Build and Host Options,  Prev: Canadian Cross Concepts,  Up: Canadian Cross
   1924 
   1925 6.3 Build Cross Host Tools
   1926 ==========================
   1927 
   1928 In order to configure a program for a Canadian Cross build, you must
   1929 first build and install the set of cross tools you will use to build the
   1930 program.
   1931 
   1932    These tools will be build cross host tools.  That is, they will run
   1933 on the build system, and will produce code that runs on the host system.
   1934 
   1935    It is easy to confuse the meaning of build and host here.  Always
   1936 remember that the build system is where you are doing the build, and the
   1937 host system is where the resulting program will run.  Therefore, you
   1938 need a build cross host compiler.
   1939 
   1940    In general, you must have a complete cross environment in order to do
   1941 the build.  This normally means a cross compiler, cross assembler, and
   1942 so forth, as well as libraries and include files for the host system.
   1943 
   1944 
   1945 File: configure.info,  Node: Build and Host Options,  Next: CCross not in Cygnus Tree,  Prev: Build Cross Host Tools,  Up: Canadian Cross
   1946 
   1947 6.4 Build and Host Options
   1948 ==========================
   1949 
   1950 When you run `configure', you must use both the `--build' and `--host'
   1951 options.
   1952 
   1953    The `--build' option is used to specify the configuration name of
   1954 the build system.  This can normally be the result of running the
   1955 `config.guess' shell script, and it is reasonable to use
   1956 `--build=`config.guess`'.
   1957 
   1958    The `--host' option is used to specify the configuration name of the
   1959 host system.
   1960 
   1961    As we explained earlier, `config.guess' is used to set the default
   1962 value for the `--host' option (*note Using the Host Type::).  We can
   1963 now see that since `config.guess' returns the type of system on which
   1964 it is run, it really identifies the build system.  Since the host
   1965 system is normally the same as the build system (i.e., people do not
   1966 normally build using a cross compiler), it is reasonable to use the
   1967 result of `config.guess' as the default for the host system when the
   1968 `--host' option is not used.
   1969 
   1970    It might seem that if the `--host' option were used without the
   1971 `--build' option that the configure script could run `config.guess' to
   1972 determine the build system, and presume a Canadian Cross if the result
   1973 of `config.guess' differed from the `--host' option.  However, for
   1974 historical reasons, some configure scripts are routinely run using an
   1975 explicit `--host' option, rather than using the default from
   1976 `config.guess'.  As noted earlier, it is difficult or impossible to
   1977 reliably compare configuration names (*note Using the Target Type::).
   1978 Therefore, by convention, if the `--host' option is used, but the
   1979 `--build' option is not used, then the build system defaults to the
   1980 host system.
   1981 
   1982 
   1983 File: configure.info,  Node: CCross not in Cygnus Tree,  Next: CCross in Cygnus Tree,  Prev: Build and Host Options,  Up: Canadian Cross
   1984 
   1985 6.5 Canadian Cross not in Cygnus Tree.
   1986 ======================================
   1987 
   1988 If you are not using the Cygnus tree, you must explicitly specify the
   1989 cross tools which you want to use to build the program.  This is done by
   1990 setting environment variables before running the `configure' script.
   1991 
   1992    You must normally set at least the environment variables `CC', `AR',
   1993 and `RANLIB' to the cross tools which you want to use to build.
   1994 
   1995    For some programs, you must set additional cross tools as well, such
   1996 as `AS', `LD', or `NM'.
   1997 
   1998    You would set these environment variables to the build cross tools
   1999 which you are going to use.
   2000 
   2001    For example, if you are building a Solaris program on a GNU/Linux
   2002 system, and your GNU/Linux cross Solaris compiler were named
   2003 `solaris-gcc', then you would set the environment variable `CC' to
   2004 `solaris-gcc'.
   2005 
   2006 
   2007 File: configure.info,  Node: CCross in Cygnus Tree,  Next: Supporting Canadian Cross,  Prev: CCross not in Cygnus Tree,  Up: Canadian Cross
   2008 
   2009 6.6 Canadian Cross in Cygnus Tree
   2010 =================================
   2011 
   2012 This section describes configuring and building a Canadian Cross when
   2013 using the Cygnus tree.
   2014 
   2015 * Menu:
   2016 
   2017 * Standard Cygnus CCross::	Building a Normal Program.
   2018 * Cross Cygnus CCross::		Building a Cross Program.
   2019 
   2020 
   2021 File: configure.info,  Node: Standard Cygnus CCross,  Next: Cross Cygnus CCross,  Up: CCross in Cygnus Tree
   2022 
   2023 6.6.1 Building a Normal Program
   2024 -------------------------------
   2025 
   2026 When configuring a Canadian Cross in the Cygnus tree, all the
   2027 appropriate environment variables are automatically set to `HOST-TOOL',
   2028 where HOST is the value used for the `--host' option, and TOOL is the
   2029 name of the tool (e.g., `gcc', `as', etc.).  These tools must be on
   2030 your `PATH'.
   2031 
   2032    Adding a prefix of HOST will give the usual name for the build cross
   2033 host tools.  To see this, consider that when these cross tools were
   2034 built, they were configured to run on the build system and to produce
   2035 code for the host system.  That is, they were configured with a
   2036 `--target' option that is the same as the system which we are now
   2037 calling the host.  Recall that the default name for installed cross
   2038 tools uses the target system as a prefix (*note Using the Target
   2039 Type::).  Since that is the system which we are now calling the host,
   2040 HOST is the right prefix to use.
   2041 
   2042    For example, if you configure with `--build=i386-linux-gnu' and
   2043 `--host=solaris', then the Cygnus tree will automatically default to
   2044 using the compiler `solaris-gcc'.  You must have previously built and
   2045 installed this compiler, probably by doing a build with no `--host'
   2046 option and with a `--target' option of `solaris'.
   2047 
   2048 
   2049 File: configure.info,  Node: Cross Cygnus CCross,  Prev: Standard Cygnus CCross,  Up: CCross in Cygnus Tree
   2050 
   2051 6.6.2 Building a Cross Program
   2052 ------------------------------
   2053 
   2054 There are additional considerations if you want to build a cross
   2055 compiler, rather than a native compiler, in the Cygnus tree using a
   2056 Canadian Cross.
   2057 
   2058    When you build a cross compiler using the Cygnus tree, then the
   2059 target libraries will normally be built with the newly built target
   2060 compiler (*note Host and Target Libraries::).  However, this will not
   2061 work when building with a Canadian Cross.  This is because the newly
   2062 built target compiler will be a program which runs on the host system,
   2063 and therefore will not be able to run on the build system.
   2064 
   2065    Therefore, when building a cross compiler with the Cygnus tree, you
   2066 must first install a set of build cross target tools.  These tools will
   2067 be used when building the target libraries.
   2068 
   2069    Note that this is not a requirement of a Canadian Cross in general.
   2070 For example, it would be possible to build just the host cross target
   2071 tools on the build system, to copy the tools to the host system, and to
   2072 build the target libraries on the host system.  The requirement for
   2073 build cross target tools is imposed by the Cygnus tree, which expects
   2074 to be able to build both host programs and target libraries in a single
   2075 `configure'/`make' step.  Because it builds these in a single step, it
   2076 expects to be able to build the target libraries on the build system,
   2077 which means that it must use a build cross target toolchain.
   2078 
   2079    For example, suppose you want to build a Windows cross MIPS ELF
   2080 compiler on a GNU/Linux system.  You must have previously installed
   2081 both a GNU/Linux cross Windows compiler and a GNU/Linux cross MIPS ELF
   2082 compiler.
   2083 
   2084    In order to build the Windows (configuration name `i386-cygwin32')
   2085 cross MIPS ELF (configure name `mips-elf') compiler, you might execute
   2086 the following commands (long command lines are broken across lines with
   2087 a trailing backslash as a continuation character).
   2088 
   2089      mkdir linux-x-cygwin32
   2090      cd linux-x-cygwin32
   2091      SRCDIR/configure --target i386-cygwin32 --prefix=INSTALLDIR \
   2092        --exec-prefix=INSTALLDIR/H-i386-linux
   2093      make
   2094      make install
   2095      cd ..
   2096      mkdir linux-x-mips-elf
   2097      cd linux-x-mips-elf
   2098      SRCDIR/configure --target mips-elf --prefix=INSTALLDIR \
   2099        --exec-prefix=INSTALLDIR/H-i386-linux
   2100      make
   2101      make install
   2102      cd ..
   2103      mkdir cygwin32-x-mips-elf
   2104      cd cygwin32-x-mips-elf
   2105      SRCDIR/configure --build=i386-linux-gnu --host=i386-cygwin32 \
   2106        --target=mips-elf --prefix=WININSTALLDIR \
   2107        --exec-prefix=WININSTALLDIR/H-i386-cygwin32
   2108      make
   2109      make install
   2110 
   2111    You would then copy the contents of WININSTALLDIR over to the
   2112 Windows machine, and run the resulting programs.
   2113 
   2114 
   2115 File: configure.info,  Node: Supporting Canadian Cross,  Prev: CCross in Cygnus Tree,  Up: Canadian Cross
   2116 
   2117 6.7 Supporting Canadian Cross
   2118 =============================
   2119 
   2120 If you want to make it possible to build a program you are developing
   2121 using a Canadian Cross, you must take some care when writing your
   2122 configure and make rules.  Simple cases will normally work correctly.
   2123 However, it is not hard to write configure and make tests which will
   2124 fail in a Canadian Cross.
   2125 
   2126 * Menu:
   2127 
   2128 * CCross in Configure::		Supporting Canadian Cross in Configure Scripts.
   2129 * CCross in Make::		Supporting Canadian Cross in Makefiles.
   2130 
   2131 
   2132 File: configure.info,  Node: CCross in Configure,  Next: CCross in Make,  Up: Supporting Canadian Cross
   2133 
   2134 6.7.1 Supporting Canadian Cross in Configure Scripts
   2135 ----------------------------------------------------
   2136 
   2137 In a `configure.in' file, after calling `AC_PROG_CC', you can find out
   2138 whether this is a Canadian Cross configure by examining the shell
   2139 variable `cross_compiling'.  In a Canadian Cross, which means that the
   2140 compiler is a cross compiler, `cross_compiling' will be `yes'.  In a
   2141 normal configuration, `cross_compiling' will be `no'.
   2142 
   2143    You ordinarily do not need to know the type of the build system in a
   2144 configure script.  However, if you do need that information, you can get
   2145 it by using the macro `AC_CANONICAL_SYSTEM', the same macro that is
   2146 used to determine the target system.  This macro will set the variables
   2147 `build', `build_alias', `build_cpu', `build_vendor', and `build_os',
   2148 which correspond to the similar `target' and `host' variables, except
   2149 that they describe the build system.
   2150 
   2151    When writing tests in `configure.in', you must remember that you
   2152 want to test the host environment, not the build environment.
   2153 
   2154    Macros like `AC_CHECK_FUNCS' which use the compiler will test the
   2155 host environment.  That is because the tests will be done by running the
   2156 compiler, which is actually a build cross host compiler.  If the
   2157 compiler can find the function, that means that the function is present
   2158 in the host environment.
   2159 
   2160    Tests like `test -f /dev/ptyp0', on the other hand, will test the
   2161 build environment.  Remember that the configure script is running on the
   2162 build system, not the host system.  If your configure scripts examines
   2163 files, those files will be on the build system.  Whatever you determine
   2164 based on those files may or may not be the case on the host system.
   2165 
   2166    Most autoconf macros will work correctly for a Canadian Cross.  The
   2167 main exception is `AC_TRY_RUN'.  This macro tries to compile and run a
   2168 test program.  This will fail in a Canadian Cross, because the program
   2169 will be compiled for the host system, which means that it will not run
   2170 on the build system.
   2171 
   2172    The `AC_TRY_RUN' macro provides an optional argument to tell the
   2173 configure script what to do in a Canadian Cross.  If that argument is
   2174 not present, you will get a warning when you run `autoconf':
   2175      warning: AC_TRY_RUN called without default to allow cross compiling
   2176    This tells you that the resulting `configure' script will not work
   2177 with a Canadian Cross.
   2178 
   2179    In some cases while it may better to perform a test at configure
   2180 time, it is also possible to perform the test at run time.  In such a
   2181 case you can use the cross compiling argument to `AC_TRY_RUN' to tell
   2182 your program that the test could not be performed at configure time.
   2183 
   2184    There are a few other autoconf macros which will not work correctly
   2185 with a Canadian Cross: a partial list is `AC_FUNC_GETPGRP',
   2186 `AC_FUNC_SETPGRP', `AC_FUNC_SETVBUF_REVERSED', and
   2187 `AC_SYS_RESTARTABLE_SYSCALLS'.  The `AC_CHECK_SIZEOF' macro is
   2188 generally not very useful with a Canadian Cross; it permits an optional
   2189 argument indicating the default size, but there is no way to know what
   2190 the correct default should be.
   2191 
   2192 
   2193 File: configure.info,  Node: CCross in Make,  Prev: CCross in Configure,  Up: Supporting Canadian Cross
   2194 
   2195 6.7.2 Supporting Canadian Cross in Makefiles.
   2196 ---------------------------------------------
   2197 
   2198 The main Canadian Cross issue in a `Makefile' arises when you want to
   2199 use a subsidiary program to generate code or data which you will then
   2200 include in your real program.
   2201 
   2202    If you compile this subsidiary program using `$(CC)' in the usual
   2203 way, you will not be able to run it.  This is because `$(CC)' will
   2204 build a program for the host system, but the program is being built on
   2205 the build system.
   2206 
   2207    You must instead use a compiler for the build system, rather than the
   2208 host system.  In the Cygnus tree, this make variable `$(CC_FOR_BUILD)'
   2209 will hold a compiler for the build system.
   2210 
   2211    Note that you should not include `config.h' in a file you are
   2212 compiling with `$(CC_FOR_BUILD)'.  The `configure' script will build
   2213 `config.h' with information for the host system.  However, you are
   2214 compiling the file using a compiler for the build system (a native
   2215 compiler).  Subsidiary programs are normally simple filters which do no
   2216 user interaction, and it is normally possible to write them in a highly
   2217 portable fashion so that the absence of `config.h' is not crucial.
   2218 
   2219    The gcc `Makefile.in' shows a complex situation in which certain
   2220 files, such as `rtl.c', must be compiled into both subsidiary programs
   2221 run on the build system and into the final program.  This approach may
   2222 be of interest for advanced build system hackers.  Note that the build
   2223 system compiler is rather confusingly called `HOST_CC'.
   2224 
   2225 
   2226 File: configure.info,  Node: Cygnus Configure,  Next: Multilibs,  Prev: Canadian Cross,  Up: Top
   2227 
   2228 7 Cygnus Configure
   2229 ******************
   2230 
   2231 The Cygnus configure script predates autoconf.  All of its interesting
   2232 features have been incorporated into autoconf.  No new programs should
   2233 be written to use the Cygnus configure script.
   2234 
   2235    However, the Cygnus configure script is still used in a few places:
   2236 at the top of the Cygnus tree and in a few target libraries in the
   2237 Cygnus tree.  Until those uses have been replaced with autoconf, some
   2238 brief notes are appropriate here.  This is not complete documentation,
   2239 but it should be possible to use this as a guide while examining the
   2240 scripts themselves.
   2241 
   2242 * Menu:
   2243 
   2244 * Cygnus Configure Basics::		Cygnus Configure Basics.
   2245 * Cygnus Configure in C++ Libraries::	Cygnus Configure in C++ Libraries.
   2246 
   2247 
   2248 File: configure.info,  Node: Cygnus Configure Basics,  Next: Cygnus Configure in C++ Libraries,  Up: Cygnus Configure
   2249 
   2250 7.1 Cygnus Configure Basics
   2251 ===========================
   2252 
   2253 Cygnus configure does not use any generated files; there is no program
   2254 corresponding to `autoconf'.  Instead, there is a single shell script
   2255 named `configure' which may be found at the top of the Cygnus tree.
   2256 This shell script was written by hand; it was not generated by
   2257 autoconf, and it is incorrect, and indeed harmful, to run `autoconf' in
   2258 the top level of a Cygnus tree.
   2259 
   2260    Cygnus configure works in a particular directory by examining the
   2261 file `configure.in' in that directory.  That file is broken into four
   2262 separate shell scripts.
   2263 
   2264    The first is the contents of `configure.in' up to a line that starts
   2265 with `# per-host:'.  This is the common part.
   2266 
   2267    The second is the rest of `configure.in' up to a line that starts
   2268 with `# per-target:'.  This is the per host part.
   2269 
   2270    The third is the rest of `configure.in' up to a line that starts
   2271 with `# post-target:'.  This is the per target part.
   2272 
   2273    The fourth is the remainder of `configure.in'.  This is the post
   2274 target part.
   2275 
   2276    If any of these comment lines are missing, the corresponding shell
   2277 script is empty.
   2278 
   2279    Cygnus configure will first execute the common part.  This must set
   2280 the shell variable `srctrigger' to the name of a source file, to
   2281 confirm that Cygnus configure is looking at the right directory.  This
   2282 may set the shell variables `package_makefile_frag' and
   2283 `package_makefile_rules_frag'.
   2284 
   2285    Cygnus configure will next set the `build' and `host' shell
   2286 variables, and execute the per host part.  This may set the shell
   2287 variable `host_makefile_frag'.
   2288 
   2289    Cygnus configure will next set the `target' variable, and execute
   2290 the per target part.  This may set the shell variable
   2291 `target_makefile_frag'.
   2292 
   2293    Any of these scripts may set the `subdirs' shell variable.  This
   2294 variable is a list of subdirectories where a `Makefile.in' file may be
   2295 found.  Cygnus configure will automatically look for a `Makefile.in'
   2296 file in the current directory.  The `subdirs' shell variable is not
   2297 normally used, and I believe that the only directory which uses it at
   2298 present is `newlib'.
   2299 
   2300    For each `Makefile.in', Cygnus configure will automatically create a
   2301 `Makefile' by adding definitions for `make' variables such as `host'
   2302 and `target', and automatically editing the values of `make' variables
   2303 such as `prefix' if they are present.
   2304 
   2305    Also, if any of the `makefile_frag' shell variables are set, Cygnus
   2306 configure will interpret them as file names relative to either the
   2307 working directory or the source directory, and will read the contents of
   2308 the file into the generated `Makefile'.  The file contents will be read
   2309 in after the first line in `Makefile.in' which starts with `####'.
   2310 
   2311    These `Makefile' fragments are used to customize behaviour for a
   2312 particular host or target.  They serve to select particular files to
   2313 compile, and to define particular preprocessor macros by providing
   2314 values for `make' variables which are then used during compilation.
   2315 Cygnus configure, unlike autoconf, normally does not do feature tests,
   2316 and normally requires support to be added manually for each new host.
   2317 
   2318    The `Makefile' fragment support is similar to the autoconf
   2319 `AC_SUBST_FILE' macro.
   2320 
   2321    After creating each `Makefile', the post target script will be run
   2322 (i.e., it may be run several times).  This script may further customize
   2323 the `Makefile'.  When it is run, the shell variable `Makefile' will
   2324 hold the name of the `Makefile', including the appropriate directory
   2325 component.
   2326 
   2327    Like an autoconf generated `configure' script, Cygnus configure will
   2328 create a file named `config.status' which, when run, will automatically
   2329 recreate the configuration.  The `config.status' file will simply
   2330 execute the Cygnus configure script again with the appropriate
   2331 arguments.
   2332 
   2333    Any of the parts of `configure.in' may set the shell variables
   2334 `files' and `links'.  Cygnus configure will set up symlinks from the
   2335 names in `links' to the files named in `files'.  This is similar to the
   2336 autoconf `AC_LINK_FILES' macro.
   2337 
   2338    Finally, any of the parts of `configure.in' may set the shell
   2339 variable `configdirs' to a set of subdirectories.  If it is set, Cygnus
   2340 configure will recursively run the configure process in each
   2341 subdirectory.  If the subdirectory uses Cygnus configure, it will
   2342 contain a `configure.in' file but no `configure' file, in which case
   2343 Cygnus configure will invoke itself recursively.  If the subdirectory
   2344 has a `configure' file, Cygnus configure assumes that it is an autoconf
   2345 generated `configure' script, and simply invokes it directly.
   2346 
   2347 
   2348 File: configure.info,  Node: Cygnus Configure in C++ Libraries,  Prev: Cygnus Configure Basics,  Up: Cygnus Configure
   2349 
   2350 7.2 Cygnus Configure in C++ Libraries
   2351 =====================================
   2352 
   2353 The C++ library configure system, written by Per Bothner, deserves
   2354 special mention.  It uses Cygnus configure, but it does feature testing
   2355 like that done by autoconf generated `configure' scripts.  This
   2356 approach is used in the libraries `libio', `libstdc++', and `libg++'.
   2357 
   2358    Most of the `Makefile' information is written out by the shell
   2359 script `libio/config.shared'.  Each `configure.in' file sets certain
   2360 shell variables, and then invokes `config.shared' to create two package
   2361 `Makefile' fragments.  These fragments are then incorporated into the
   2362 resulting `Makefile' by the Cygnus configure script.
   2363 
   2364    The file `_G_config.h' is created in the `libio' object directory by
   2365 running the shell script `libio/gen-params'.  This shell script uses
   2366 feature tests to define macros and typedefs in `_G_config.h'.
   2367 
   2368 
   2369 File: configure.info,  Node: Multilibs,  Next: FAQ,  Prev: Cygnus Configure,  Up: Top
   2370 
   2371 8 Multilibs
   2372 ***********
   2373 
   2374 For some targets gcc may have different processor requirements depending
   2375 upon command line options.  An obvious example is the `-msoft-float'
   2376 option supported on several processors.  This option means that the
   2377 floating point registers are not available, which means that floating
   2378 point operations must be done by calling an emulation subroutine rather
   2379 than by using machine instructions.
   2380 
   2381    For such options, gcc is often configured to compile target libraries
   2382 twice: once with `-msoft-float' and once without.  When gcc compiles
   2383 target libraries more than once, the resulting libraries are called
   2384 "multilibs".
   2385 
   2386    Multilibs are not really part of the GNU configure and build system,
   2387 but we discuss them here since they require support in the `configure'
   2388 scripts and `Makefile's used for target libraries.
   2389 
   2390 * Menu:
   2391 
   2392 * Multilibs in gcc::		        Multilibs in gcc.
   2393 * Multilibs in Target Libraries::	Multilibs in Target Libraries.
   2394 
   2395 
   2396 File: configure.info,  Node: Multilibs in gcc,  Next: Multilibs in Target Libraries,  Up: Multilibs
   2397 
   2398 8.1 Multilibs in gcc
   2399 ====================
   2400 
   2401 In gcc, multilibs are defined by setting the variable
   2402 `MULTILIB_OPTIONS' in the target `Makefile' fragment.  Several other
   2403 `MULTILIB' variables may also be defined there.  *Note The Target
   2404 Makefile Fragment: (gcc)Target Fragment.
   2405 
   2406    If you have built gcc, you can see what multilibs it uses by running
   2407 it with the `-print-multi-lib' option.  The output `.;' means that no
   2408 multilibs are used.  In general, the output is a sequence of lines, one
   2409 per multilib.  The first part of each line, up to the `;', is the name
   2410 of the multilib directory.  The second part is a list of compiler
   2411 options separated by `@' characters.
   2412 
   2413    Multilibs are built in a tree of directories.  The top of the tree,
   2414 represented by `.' in the list of multilib directories, is the default
   2415 library to use when no special compiler options are used.  The
   2416 subdirectories of the tree hold versions of the library to use when
   2417 particular compiler options are used.
   2418 
   2419 
   2420 File: configure.info,  Node: Multilibs in Target Libraries,  Prev: Multilibs in gcc,  Up: Multilibs
   2421 
   2422 8.2 Multilibs in Target Libraries
   2423 =================================
   2424 
   2425 The target libraries in the Cygnus tree are automatically built with
   2426 multilibs.  That means that each library is built multiple times.
   2427 
   2428    This default is set in the top level `configure.in' file, by adding
   2429 `--enable-multilib' to the list of arguments passed to configure when
   2430 it is run for the target libraries (*note Host and Target Libraries::).
   2431 
   2432    Each target library uses the shell script `config-ml.in', written by
   2433 Doug Evans, to prepare to build target libraries.  This shell script is
   2434 invoked after the `Makefile' has been created by the `configure'
   2435 script.  If multilibs are not enabled, it does nothing, otherwise it
   2436 modifies the `Makefile' to support multilibs.
   2437 
   2438    The `config-ml.in' script makes one copy of the `Makefile' for each
   2439 multilib in the appropriate subdirectory.  When configuring in the
   2440 source directory (which is not recommended), it will build a symlink
   2441 tree of the sources in each subdirectory.
   2442 
   2443    The `config-ml.in' script sets several variables in the various
   2444 `Makefile's.  The `Makefile.in' must have definitions for these
   2445 variables already; `config-ml.in' simply changes the existing values.
   2446 The `Makefile' should use default values for these variables which will
   2447 do the right thing in the subdirectories.
   2448 
   2449 `MULTISRCTOP'
   2450      `config-ml.in' will set this to a sequence of `../' strings, where
   2451      the number of strings is the number of multilib levels in the
   2452      source tree.  The default value should be the empty string.
   2453 
   2454 `MULTIBUILDTOP'
   2455      `config-ml.in' will set this to a sequence of `../' strings, where
   2456      the number of strings is number of multilib levels in the object
   2457      directory.  The default value should be the empty string.  This
   2458      will differ from `MULTISRCTOP' when configuring in the source tree
   2459      (which is not recommended).
   2460 
   2461 `MULTIDIRS'
   2462      In the top level `Makefile' only, `config-ml.in' will set this to
   2463      the list of multilib subdirectories.  The default value should be
   2464      the empty string.
   2465 
   2466 `MULTISUBDIR'
   2467      `config-ml.in' will set this to the installed subdirectory name to
   2468      use for this subdirectory, with a leading `/'.  The default value
   2469      shold be the empty string.
   2470 
   2471 `MULTIDO'
   2472 `MULTICLEAN'
   2473      In the top level `Makefile' only, `config-ml.in' will set these
   2474      variables to commands to use when doing a recursive make.  These
   2475      variables should both default to the string `true', so that by
   2476      default nothing happens.
   2477 
   2478    All references to the parent of the source directory should use the
   2479 variable `MULTISRCTOP'.  Instead of writing `$(srcdir)/..', you must
   2480 write `$(srcdir)/$(MULTISRCTOP)..'.
   2481 
   2482    Similarly, references to the parent of the object directory should
   2483 use the variable `MULTIBUILDTOP'.
   2484 
   2485    In the installation target, the libraries should be installed in the
   2486 subdirectory `MULTISUBDIR'.  Instead of installing
   2487 `$(libdir)/libfoo.a', install `$(libdir)$(MULTISUBDIR)/libfoo.a'.
   2488 
   2489    The `config-ml.in' script also modifies the top level `Makefile' to
   2490 add `multi-do' and `multi-clean' targets which are used when building
   2491 multilibs.
   2492 
   2493    The default target of the `Makefile' should include the following
   2494 command:
   2495      @$(MULTIDO) $(FLAGS_TO_PASS) DO=all multi-do
   2496    This assumes that `$(FLAGS_TO_PASS)' is defined as a set of
   2497 variables to pass to a recursive invocation of `make'.  This will build
   2498 all the multilibs.  Note that the default value of `MULTIDO' is `true',
   2499 so by default this command will do nothing.  It will only do something
   2500 in the top level `Makefile' if multilibs were enabled.
   2501 
   2502    The `install' target of the `Makefile' should include the following
   2503 command:
   2504      @$(MULTIDO) $(FLAGS_TO_PASS) DO=install multi-do
   2505 
   2506    In general, any operation, other than clean, which should be
   2507 performed on all the multilibs should use a `$(MULTIDO)' line, setting
   2508 the variable `DO' to the target of each recursive call to `make'.
   2509 
   2510    The `clean' targets (`clean', `mostlyclean', etc.) should use
   2511 `$(MULTICLEAN)'.  For example, the `clean' target should do this:
   2512      @$(MULTICLEAN) DO=clean multi-clean
   2513 
   2514 
   2515 File: configure.info,  Node: FAQ,  Next: Index,  Prev: Multilibs,  Up: Top
   2516 
   2517 9 Frequently Asked Questions
   2518 ****************************
   2519 
   2520 Which do I run first, `autoconf' or `automake'?
   2521      Except when you first add autoconf or automake support to a
   2522      package, you shouldn't run either by hand.  Instead, configure
   2523      with the `--enable-maintainer-mode' option, and let `make' take
   2524      care of it.
   2525 
   2526 `autoconf' says something about undefined macros.
   2527      This means that you have macros in your `configure.in' which are
   2528      not defined by `autoconf'.  You may be using an old version of
   2529      `autoconf'; try building and installing a newer one.  Make sure the
   2530      newly installled `autoconf' is first on your `PATH'.  Also, see
   2531      the next question.
   2532 
   2533 My `configure' script has stuff like `CY_GNU_GETTEXT' in it.
   2534      This means that you have macros in your `configure.in' which should
   2535      be defined in your `aclocal.m4' file, but aren't.  This usually
   2536      means that `aclocal' was not able to appropriate definitions of the
   2537      macros.  Make sure that you have installed all the packages you
   2538      need.  In particular, make sure that you have installed libtool
   2539      (this is where `AM_PROG_LIBTOOL' is defined) and gettext (this is
   2540      where `CY_GNU_GETTEXT' is defined, at least in the Cygnus version
   2541      of gettext).
   2542 
   2543 My `Makefile' has `@' characters in it.
   2544      This may mean that you tried to use an autoconf substitution in
   2545      your `Makefile.in' without adding the appropriate `AC_SUBST' call
   2546      to your `configure' script.  Or it may just mean that you need to
   2547      rebuild `Makefile' in your build directory.  To rebuild `Makefile'
   2548      from `Makefile.in', run the shell script `config.status' with no
   2549      arguments.  If you need to force `configure' to run again, first
   2550      run `config.status --recheck'.  These runs are normally done
   2551      automatically by `Makefile' targets, but if your `Makefile' has
   2552      gotten messed up you'll need to help them along.
   2553 
   2554 Why do I have to run both `config.status --recheck' and `config.status'?
   2555      Normally, you don't; they will be run automatically by `Makefile'
   2556      targets.  If you do need to run them, use `config.status --recheck'
   2557      to run the `configure' script again with the same arguments as the
   2558      first time you ran it.  Use `config.status' (with no arguments) to
   2559      regenerate all files (`Makefile', `config.h', etc.) based on the
   2560      results of the configure script.  The two cases are separate
   2561      because it isn't always necessary to regenerate all the files
   2562      after running `config.status --recheck'.  The `Makefile' targets
   2563      generated by automake will use the environment variables
   2564      `CONFIG_FILES' and `CONFIG_HEADERS' to only regenerate files as
   2565      they are needed.
   2566 
   2567 What is the Cygnus tree?
   2568      The Cygnus tree is used for various packages including gdb, the GNU
   2569      binutils, and egcs.  It is also, of course, used for Cygnus
   2570      releases.  It is the build system which was developed at Cygnus,
   2571      using the Cygnus configure script.  It permits building many
   2572      different packages with a single configure and make.  The
   2573      configure scripts in the tree are being converted to autoconf, but
   2574      the general build structure remains intact.
   2575 
   2576 Why do I have to keep rebuilding and reinstalling the tools?
   2577      I know, it's a pain.  Unfortunately, there are bugs in the tools
   2578      themselves which need to be fixed, and each time that happens
   2579      everybody who uses the tools need to reinstall new versions of
   2580      them.  I don't know if there is going to be a clever fix until the
   2581      tools stabilize.
   2582 
   2583 Why not just have a Cygnus tree `make' target to update the tools?
   2584      The tools unfortunately need to be installed before they can be
   2585      used.  That means that they must be built using an appropriate
   2586      prefix, and it seems unwise to assume that every configuration
   2587      uses an appropriate prefix.  It might be possible to make them
   2588      work in place, or it might be possible to install them in some
   2589      subdirectory; so far these approaches have not been implemented.
   2590 
   2591 
   2592 File: configure.info,  Node: Index,  Prev: FAQ,  Up: Top
   2593 
   2594 Index
   2595 *****
   2596 
   2597 [index]
   2598 * Menu:
   2599 
   2600 * --build option:                        Build and Host Options.
   2601                                                               (line   9)
   2602 * --host option:                         Build and Host Options.
   2603                                                               (line  14)
   2604 * --target option:                       Specifying the Target.
   2605                                                               (line  10)
   2606 * _GNU_SOURCE:                           Write configure.in.  (line 134)
   2607 * AC_CANONICAL_HOST:                     Using the Host Type. (line  10)
   2608 * AC_CANONICAL_SYSTEM:                   Using the Target Type.
   2609                                                               (line   6)
   2610 * AC_CONFIG_HEADER:                      Write configure.in.  (line  66)
   2611 * AC_EXEEXT:                             Write configure.in.  (line  86)
   2612 * AC_INIT:                               Write configure.in.  (line  38)
   2613 * AC_OUTPUT:                             Write configure.in.  (line 142)
   2614 * AC_PREREQ:                             Write configure.in.  (line  42)
   2615 * AC_PROG_CC:                            Write configure.in.  (line 103)
   2616 * AC_PROG_CXX:                           Write configure.in.  (line 117)
   2617 * acconfig.h:                            Written Developer Files.
   2618                                                               (line  27)
   2619 * acconfig.h, writing:                   Write acconfig.h.    (line   6)
   2620 * acinclude.m4:                          Written Developer Files.
   2621                                                               (line  37)
   2622 * aclocal.m4:                            Generated Developer Files.
   2623                                                               (line  33)
   2624 * AM_CONFIG_HEADER:                      Write configure.in.  (line  53)
   2625 * AM_DISABLE_SHARED:                     Write configure.in.  (line 127)
   2626 * AM_EXEEXT:                             Write configure.in.  (line  86)
   2627 * AM_INIT_AUTOMAKE:                      Write configure.in.  (line  48)
   2628 * AM_MAINTAINER_MODE:                    Write configure.in.  (line  70)
   2629 * AM_PROG_LIBTOOL:                       Write configure.in.  (line 122)
   2630 * AM_PROG_LIBTOOL in configure:          FAQ.                 (line  19)
   2631 * build option:                          Build and Host Options.
   2632                                                               (line   9)
   2633 * building with a cross compiler:        Canadian Cross.      (line   6)
   2634 * canadian cross:                        Canadian Cross.      (line   6)
   2635 * canadian cross in configure:           CCross in Configure. (line   6)
   2636 * canadian cross in cygnus tree:         CCross in Cygnus Tree.
   2637                                                               (line   6)
   2638 * canadian cross in makefile:            CCross in Make.      (line   6)
   2639 * canadian cross, configuring:           Build and Host Options.
   2640                                                               (line   6)
   2641 * canonical system names:                Configuration Names. (line   6)
   2642 * config.cache:                          Build Files Description.
   2643                                                               (line  28)
   2644 * config.h:                              Build Files Description.
   2645                                                               (line  23)
   2646 * config.h.in:                           Generated Developer Files.
   2647                                                               (line  45)
   2648 * config.in:                             Generated Developer Files.
   2649                                                               (line  45)
   2650 * config.status:                         Build Files Description.
   2651                                                               (line   9)
   2652 * config.status --recheck:               FAQ.                 (line  40)
   2653 * configuration names:                   Configuration Names. (line   6)
   2654 * configuration triplets:                Configuration Names. (line   6)
   2655 * configure:                             Generated Developer Files.
   2656                                                               (line  21)
   2657 * configure build system:                Build and Host Options.
   2658                                                               (line   9)
   2659 * configure host:                        Build and Host Options.
   2660                                                               (line  14)
   2661 * configure target:                      Specifying the Target.
   2662                                                               (line  10)
   2663 * configure.in:                          Written Developer Files.
   2664                                                               (line   9)
   2665 * configure.in, writing:                 Write configure.in.  (line   6)
   2666 * configuring a canadian cross:          Build and Host Options.
   2667                                                               (line   6)
   2668 * cross compiler:                        Cross Compilation Concepts.
   2669                                                               (line   6)
   2670 * cross compiler, building with:         Canadian Cross.      (line   6)
   2671 * cross tools:                           Cross Compilation Tools.
   2672                                                               (line   6)
   2673 * CY_GNU_GETTEXT in configure:           FAQ.                 (line  19)
   2674 * cygnus configure:                      Cygnus Configure.    (line   6)
   2675 * goals:                                 Goals.               (line   6)
   2676 * history:                               History.             (line   6)
   2677 * host names:                            Configuration Names. (line   6)
   2678 * host option:                           Build and Host Options.
   2679                                                               (line  14)
   2680 * host system:                           Host and Target.     (line   6)
   2681 * host triplets:                         Configuration Names. (line   6)
   2682 * HOST_CC:                               CCross in Make.      (line  27)
   2683 * libg++ configure:                      Cygnus Configure in C++ Libraries.
   2684                                                               (line   6)
   2685 * libio configure:                       Cygnus Configure in C++ Libraries.
   2686                                                               (line   6)
   2687 * libstdc++ configure:                   Cygnus Configure in C++ Libraries.
   2688                                                               (line   6)
   2689 * Makefile:                              Build Files Description.
   2690                                                               (line  18)
   2691 * Makefile, garbage characters:          FAQ.                 (line  29)
   2692 * Makefile.am:                           Written Developer Files.
   2693                                                               (line  18)
   2694 * Makefile.am, writing:                  Write Makefile.am.   (line   6)
   2695 * Makefile.in:                           Generated Developer Files.
   2696                                                               (line  26)
   2697 * multilibs:                             Multilibs.           (line   6)
   2698 * stamp-h:                               Build Files Description.
   2699                                                               (line  41)
   2700 * stamp-h.in:                            Generated Developer Files.
   2701                                                               (line  54)
   2702 * system names:                          Configuration Names. (line   6)
   2703 * system types:                          Configuration Names. (line   6)
   2704 * target option:                         Specifying the Target.
   2705                                                               (line  10)
   2706 * target system:                         Host and Target.     (line   6)
   2707 * triplets:                              Configuration Names. (line   6)
   2708 * undefined macros:                      FAQ.                 (line  12)
   2709 
   2710 
   2711 
   2712 Tag Table:
   2713 Node: Top971
   2714 Node: Introduction1499
   2715 Node: Goals2581
   2716 Node: Tools3305
   2717 Node: History4299
   2718 Node: Building7297
   2719 Node: Getting Started10560
   2720 Node: Write configure.in11073
   2721 Node: Write Makefile.am18324
   2722 Node: Write acconfig.h21501
   2723 Node: Generate files23038
   2724 Node: Getting Started Example25004
   2725 Node: Getting Started Example 125759
   2726 Node: Getting Started Example 227680
   2727 Node: Getting Started Example 330675
   2728 Node: Generate Files in Example33039
   2729 Node: Files34129
   2730 Node: Developer Files34740
   2731 Node: Developer Files Picture35120
   2732 Node: Written Developer Files36408
   2733 Node: Generated Developer Files38960
   2734 Node: Build Files42104
   2735 Node: Build Files Picture42765
   2736 Node: Build Files Description43529
   2737 Node: Support Files45535
   2738 Node: Configuration Names48417
   2739 Node: Configuration Name Definition48917
   2740 Node: Using Configuration Names51240
   2741 Node: Cross Compilation Tools53210
   2742 Node: Cross Compilation Concepts53901
   2743 Node: Host and Target54869
   2744 Node: Using the Host Type56370
   2745 Node: Specifying the Target57719
   2746 Node: Using the Target Type58508
   2747 Node: Cross Tools in the Cygnus Tree61939
   2748 Node: Host and Target Libraries62996
   2749 Node: Target Library Configure Scripts66745
   2750 Node: Make Targets in Cygnus Tree69837
   2751 Node: Target libiberty71185
   2752 Node: Canadian Cross72572
   2753 Node: Canadian Cross Example73413
   2754 Node: Canadian Cross Concepts74532
   2755 Node: Build Cross Host Tools76044
   2756 Node: Build and Host Options76996
   2757 Node: CCross not in Cygnus Tree78782
   2758 Node: CCross in Cygnus Tree79760
   2759 Node: Standard Cygnus CCross80181
   2760 Node: Cross Cygnus CCross81545
   2761 Node: Supporting Canadian Cross84345
   2762 Node: CCross in Configure84960
   2763 Node: CCross in Make88128
   2764 Node: Cygnus Configure89731
   2765 Node: Cygnus Configure Basics90566
   2766 Node: Cygnus Configure in C++ Libraries95244
   2767 Node: Multilibs96251
   2768 Node: Multilibs in gcc97296
   2769 Node: Multilibs in Target Libraries98374
   2770 Node: FAQ102565
   2771 Node: Index106665
   2772 
   2773 End Tag Table
   2774