home *** CD-ROM | disk | FTP | other *** search
/ Geek Gadgets 1 / ADE-1.bin / ade-dist / gdb-4.16-base.tgz / gdb-4.16-base.tar / fsf / gdb / etc / configure.info-1 (.txt) < prev    next >
GNU Info File  |  1996-04-23  |  50KB  |  906 lines
  1. This is Info file configure.info, produced by Makeinfo-1.55 from the
  2. input file ./configure.texi.
  3. START-INFO-DIR-ENTRY
  4. * configure: (configure).        Cygnus configure.
  5. END-INFO-DIR-ENTRY
  6.    This document describes the Cygnus Support version of `configure'.
  7.    Copyright (C) 1991, 1992, 1993 Cygnus Support Permission is granted
  8. to make and distribute verbatim copies of this manual provided the
  9. copyright notice and this permission notice are preserved on all copies.
  10.    Permission is granted to copy and distribute modified versions of
  11. this manual under the conditions for verbatim copying, provided that
  12. the entire resulting derived work is distributed under the terms of a
  13. permission notice identical to this one.
  14.    Permission is granted to copy and distribute translations of this
  15. manual into another language, under the above conditions for modified
  16. versions, except that this permission notice may be stated in a
  17. translation approved by Cygnus Support.
  18. File: configure.info,  Node: Top,  Next: What configure does,  Prev: (DIR),  Up: (DIR)
  19. Cygnus configure
  20. ****************
  21.    This file documents the configuration system used and distributed by
  22. Cygnus Support.
  23. * Menu:
  24. * What configure does::    What configure does
  25. * Invoking configure::     Invoking configure--basic usage
  26. * Using configure::        More than you ever wanted to know
  27. * Porting::                How to use configure with new programs
  28. * Variables Index::
  29. * Concept Index::
  30. File: configure.info,  Node: What configure does,  Next: Invoking configure,  Prev: Top,  Up: Top
  31. What `configure' does
  32. *********************
  33.    This manual documents Cygnus `configure', a program which helps to
  34. automate much of the setup activity associated with building large
  35. suites of programs, such the Cygnus Support Developer's Kit.  This
  36. manual is therefore geared toward readers who are likely to face the
  37. problem of configuring software in source form before compiling and
  38. installing it.  We assume you are an experienced programmer or system
  39. administrator.  For further background on this topic, see *Note
  40. Apologia Configure: (cfg-paper)Some Basic Terms, by K. Richard Pixley.
  41.    When `configure' runs, it does the following things:
  42. ** creates build directories*
  43.      When you run `configure' with the `--srcdir' option, it uses the
  44.      current directory as the "build directory", creating under it a
  45.      directory tree that parallels the directory structure of the
  46.      source directory.  If you don't specify a `srcdir', `configure'
  47.      first assumes that the source code you wish to configure is in
  48.      your current directory; if it finds no `configure.in' input file
  49.      there, it searches in the directory `configure' itself lies in.
  50.      (For details, see *Note Build directories: Build directories.)
  51. ** generates `Makefile'*
  52.      A `Makefile' template from the source directory, usually called
  53.      `Makefile.in', is copied to an output file in the build directory
  54.      which is most often named `Makefile'.  `configure' places
  55.      definitions for a number of standard `Makefile' macros at the
  56.      beginning of the output file.  If `--prefix=DIR' or
  57.      `--exec_prefix=DIR' are specified on the `configure' command line,
  58.      corresponding `Makefile' variables are set accordingly.  If host,
  59.      target, or site-specific `Makefile' fragments exist, these are
  60.      inserted into the output file.  (For details, see *Note `Makefile'
  61.      generation: Makefile generation.)
  62. ** generates `.gdbinit'*
  63.      If the source directory contains a `.gdbinit' file and the build
  64.      directory is not the same as the source directory, a `.gdbinit'
  65.      file is created in the build directory.  This `.gdbinit' file
  66.      contains commands which allow the source directory to be read when
  67.      debugging with the GNU debugger, `gdb'.  (*Note Command Files:
  68.      (gdb)Command Files.)
  69. ** makes symbolic links*
  70.      Most build directories require that some symbolic links with
  71.      generic names are built pointing to specific files in the source
  72.      directory.  If the system where `configure' runs cannot support
  73.      symbolic links, hard links are used instead.  (For details, see
  74.      *Note The `configure.in' input file: configure.in.)
  75. ** generates `config.status'*
  76.      `configure' creates a shell script named `config.status' in the
  77.      build directory.  This shell script, when run from the build
  78.      directory (usually from within a `Makefile'), will reconfigure the
  79.      build directory (but not its subdirectories).  This is most often
  80.      used to have a `Makefile' update itself automatically if a new
  81.      source directory is available.
  82. ** calls itself recursively*
  83.      If the source directory has subdirectories that should also be
  84.      configured, `configure' is called for each.
  85. File: configure.info,  Node: Invoking configure,  Next: Using configure,  Prev: What configure does,  Up: Top
  86. Invoking `configure'
  87. ********************
  88.    Cygnus `configure' is a shell script which resides in a source tree.
  89. The usual way to invoke `configure' is from the shell, as follows:
  90.      eg$ ./configure HOSTTYPE
  91. This prepares the source in the current directory (`.') to be compiled
  92. for a HOSTTYPE environment.  It assumes that you wish to build programs
  93. and files in the default "build directory" (also the current directory,
  94. `.').  If you do not specify a value for HOSTTYPE, Cygnus `configure'
  95. will attempt to discover this information by itself (*note Determining
  96. system information: config.guess.).  For information on HOSTTYPE
  97. environments, *Note Host: Host.
  98.    All GNU software is packaged with one or more `configure' script(s)
  99. (*note How Configuration Should Work: (standards)Configuration.).  By
  100. using `configure' you prepare the source for your specific environment
  101. by selecting and using `Makefile' fragments and fragments of shell
  102. scripts, which are prepared in advance and stored with the source.
  103.    `configure''s command-line options also allow you to specify other
  104. aspects of the source configuration:
  105.        configure HOSTTYPE  [--target=TARGET] [--srcdir=DIR] [--rm]
  106.                  [--site=SITE] [--prefix=DIR] [--exec-prefix=DIR]
  107.                  [--program-prefix=STRING] [--tmpdir=DIR]
  108.                  [--with-PACKAGE[=YES/NO]] [--without-PACKAGE]
  109.                  [--enable-FEATURE[=YES/NO]] [--disable-FEATURE]
  110.                  [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help]
  111. `--target=TARGET'
  112.      Requests that the sources be configured to target the TARGET
  113.      machine.  If no target is specified explicitly, the target is
  114.      assumed to be the same as the host (i.e., a "native"
  115.      configuration).  *Note Host: Host, and *Note Target: Target, for
  116.      discussions of each.
  117. `--srcdir=DIR'
  118.      Direct each generated `Makefile' to use the sources located in
  119.      directory DIR.  Use this option whenever you wish the object code
  120.      to reside in a different place from the source code.  The "build
  121.      directory" is always assumed to be the directory you call
  122.      `configure' from.  See *Note Build directories: Build directories,
  123.      for an example.  If the source directory is not specified,
  124.      `configure' assumes that the source is in your current directory.
  125.      If `configure' finds no `configure.in' there, it searches in the
  126.      same directory that the `configure' script itself lies in.
  127.      Pathnames specified (Values for DIR) can be either absolute
  128.      relative to the *build* directory.
  129. `--rm'
  130.      *Remove* the configuration specified by HOSTTYPE and the other
  131.      command-line options, rather than create it.
  132.           *Note:* We recommend that you use `make distclean' rather than
  133.           use this option; see *Note Invoking `make': (make)Invoking
  134.           make, for details on `make distclean'.
  135. `--site=SITE'
  136.      Generate the `Makefile' using site-specific `Makefile' fragments
  137.      for SITE.  *Note Adding information about local conventions:
  138.      Makefile fragments.
  139. `--prefix=DIR'
  140.      Configure the source to install programs and files under directory
  141.      DIR.
  142.      This option sets the variable `prefix'.  Each generated `Makefile'
  143.      will have its `prefix' variables set to this value.  (*Note What
  144.      `configure' really does: What configure really does.)
  145. `--exec-prefix=DIR'
  146.      Configure the source to install "host dependent" files in DIR.
  147.      This option sets the variable `exec_prefix'.  Each generated
  148.      `Makefile' will have its `exec_prefix' variables set to this value.
  149.      (*Note What `configure' really does: What configure really does.)
  150. `--program-prefix=STRING'
  151.      Configure the source to install certain programs using STRING as a
  152.      prefix.  This applies to programs which might be used for
  153.      cross-compilation, such as the compiler and the binary utilities,
  154.      and also to programs which have the same names as common Unix
  155.      programs, such as `make'.
  156.      This option sets the variable `program_prefix'.  Each generated
  157.      `Makefile' will have its `program_prefix' variables set to this
  158.      value.  (*Note What `configure' really does: What configure really
  159.      does.)
  160. `--tmpdir=TMPDIR'
  161.      Use the directory TMPDIR for `configure''s temporary files.  The
  162.      default is the value of the environment variable `TMPDIR', or
  163.      `/tmp' if the environment variable is not set.
  164. `--with-PACKAGE[=YES/NO]'
  165. `--without-PACKAGE'
  166.      Indicate that PACKAGE is present, or not present, depending on
  167.      YES/NO.  If YES/NO is nonexistent, its value is assumed to be
  168.      `yes'.  `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'.
  169.      For example, if you wish to configure the program `gcc' for a Sun
  170.      SPARCstation running SunOS 4.x, and you want `gcc' to use the GNU
  171.      linker `ld', you can configure `gcc' using
  172.           eg$ configure --with-gnu-ld sun4
  173.      *Note What `configure' really does: What configure really does, for
  174.      details.  See the installation or release notes for your
  175.      particular package for details on which other PACKAGE options are
  176.      recognized.
  177. `--enable-FEATURE[=YES/NO]'
  178. `--disable-FEATURE'
  179.      Include FEATURE, or not, depending on YES/NO.  If YES/NO is
  180.      nonexistent, its value is assumed to be `yes'.
  181.      `--disable-FEATURE' is equivalent to `--enable-FEATURE=no'.
  182.      *Note What `configure' really does: What configure really does, for
  183.      details.  See the installation or release notes for your
  184.      particular package for details on which other FEATURE options are
  185.      recognized.
  186. `--norecursion'
  187.      Configure only this directory; ignore any subdirectories.  This is
  188.      used by the executable shell script `config.status' to reconfigure
  189.      only the current directory; it is most often used
  190.      non-interactively, when `make' is invoked.  (*Note
  191.      `config.status': config.status.)
  192. `--nfp'
  193.      Assume that the intended HOSTTYPE has no floating point unit.
  194.      Suppress status output.  This option is used internally by
  195.      `configure' when calling itself recursively in subdirectories.  You
  196.      can override this option with the `--verbose' option.
  197. `--verbose'
  198.      Print status lines for each directory configured.  Normally, only
  199.      the status lines for the initial working directory are printed.
  200. `--version'
  201.      Print the `configure' version number.
  202. `--help'
  203.      Print a short summary of how to invoke `configure'.
  204.    *Note:* You may introduce options with a single dash, `-', rather
  205. than two dashes, `--'.  However, you may not be able to truncate long
  206. option names when using a single dash.  When using two dashes, options
  207. may be abbreviated as long as each option can be uniquely identified.
  208. For example,
  209.      eg$ configure --s=/u/me/src HOSTTYPE
  210. is ambiguous, as `--s' could refer to either `--site' or `--srcdir'.
  211. However,
  212.      eg$ configure --src=/u/me/src HOSTTYPE
  213. is a valid abbreviation.
  214. File: configure.info,  Node: Using configure,  Next: Porting,  Prev: Invoking configure,  Up: Top
  215. Using `configure'
  216. *****************
  217.    `configure' prepares source directories for building programs in
  218. them.  "Configuring" is the process of preparing software to compile
  219. correctly on a given "host", for a given "target".
  220.    `configure' subsequently writes a configured `Makefile' from a
  221. pre-built template; `configure' uses variables that have been set in the
  222. configuring process to determine the values of some variables in the
  223. `Makefile'.  Because of this we will refer to both `configure'
  224. variables and `Makefile' variables.  This convention allows us to
  225. determine where the variable should be set initially, in either
  226. `configure.in' or `Makefile.in'.
  227. * Menu:
  228. * What configure really does:: What configure really does
  229. * configure.in::               The configure.in input file
  230. * Install locations::          Where to install things once they are built
  231. * Host::                       Telling configure what will source will be built
  232. * Target::                     Telling configure what the source will target
  233. * Makefile fragments::         Adding information about local conventions
  234. * Makefile extensions::        Extensions to the GNU coding standards
  235. File: configure.info,  Node: What configure really does,  Next: configure.in,  Up: Using configure
  236. What `configure' really does
  237. ============================
  238.    Cygnus `configure' is a shell script that sets up an environment in
  239. which your programs will compile correctly for your machine and
  240. operating system, and will install in proper places.  `configure'
  241. accomplishes this task by doing the following:
  242.    * it generates a `Makefile' from a custom template called
  243.      `Makefile.in' in each relevant source directory;
  244.    * it customizes the build process to your specifications; you set
  245.      certain variables for `configure', either on the command line or
  246.      in the file `configure.in', which subsequently sets variables in
  247.      each generated `Makefile' to be used by `make' when actually
  248.      building the software;
  249.    * it creates "build directories", places for your code to be compiled
  250.      in before being installed;
  251.    * it generates a `.gdbinit' in the build directory, if needed, to
  252.      communicate to `gdb' where to find the program's source code;
  253.    * it generates a shell script called `config.status' which is used
  254.      most often by the `Makefile' to reconfigure itself;
  255.    * it recurses in subdirectories, setting up entire trees so that
  256.      they build correctly; if `configure' finds another `configure'
  257.      script further down in a given source tree, it knows to use this
  258.      script and not recur.
  259.    For the sake of safety (i.e., in order to prevent broken
  260. installations), the GNU coding standards call for software to be
  261. "configured" in such a way that an end user trying to build a given
  262. package will be able to do so by affecting a finite number of
  263. variables.  All GNU software comes with an executable `configure' shell
  264. script which sets up an environment within a build directory which will
  265. correctly compile your new package for your host (or, alternatively,
  266. whatever host you specify to `configure').  For further background on
  267. this topic, see *Note Apologia Configure: (cfg-paper)Some Basic Terms,
  268. by K. Richard Pixley.
  269.    Use `configure' to set for the build process:
  270.    * correct values for certain variables;
  271.    * which type of host you wish to configure a given package for
  272.      (*note Host: Host.);
  273.    * where you want to install this package (by using `prefix',
  274.      `exec-prefix' and `program-prefix'; *note Full descriptions of all
  275.      installation directories: Install details.);
  276.    * optionally, which type of machine you wish to "target" this
  277.      package's output to (*note Target: Target.);
  278.    * which other GNU packages are already installed and available to
  279.      this particular build (by using the `--with-PACKAGE' option; *note
  280.      Invoking `configure': Invoking configure.);
  281.    * where to place temporary files (by using the `--tmpdir=DIR'
  282.      option; *note Invoking `configure': Invoking configure.);
  283.    * whether to recur in subdirectories (changeable through the
  284.      `--norecursion' option; *note Invoking `configure': Invoking
  285.      configure.).
  286.    `configure' uses a few other files to complete its tasks.  These are
  287. discussed in detail where noted.
  288. `configure.in'
  289.      Input file for `configure'.  Shell script fragments reside here.
  290.      *Note The `configure.in' input file: configure.in.
  291. `Makefile.in'
  292.      Template which `configure' uses to build a file called `Makefile'
  293.      in the "build directory".  *Note `Makefile' generation: Makefile
  294.      generation.
  295. `config.sub'
  296.      Shell script used by `configure' to expand referents to the
  297.      HOSTTYPE argument into a single specification of the form
  298.      CPU-VENDOR-OS.  For instance, on the command line you can specify
  299.           eg$ ./configure sun4
  300.      to configure for a Sun SPARCstation running SunOS 4.x.  `configure'
  301.      consults `config.sub' to find that the three-part specification
  302.      for this is
  303.           sparc-sun-sunos4.1.1
  304.      which notes the CPU as `sparc', the MANUFACTURER as `sun' (Sun
  305.      Microsystems), and the OS (operating system) as `sunos4.1.1', the
  306.      SunOS 4.1.1 release.  *Note Variables available to `configure':
  307.      configure variables.
  308. `config.guess'
  309.      If you do not put the HOSTTYPE argument on the command line,
  310.      `configure' uses the `config.guess' shell script to make an
  311.      analysis of your machine (it assumes that you wish to configure
  312.      your software for the type of machine on which you are running).
  313.      The output of `config.guess' is a three-part identifier as
  314.      described above.
  315. `config.status'
  316.      The final step in configuring a directory is to create a shell
  317.      script, `config.status'.  The main purpose of this file is to
  318.      allow the `Makefile' for the current directory to rebuild itself,
  319.      if necessary.  *Note `config.status': config.status.
  320. `config/*'
  321.      `configure' uses three types of `Makefile' "fragments", which
  322.      reside in the directory `SRCDIR/config/'.  *Note Adding
  323.      information about local conventions: Makefile fragments.
  324. * Menu:
  325. * Build variables::         Variable-spaghetti made simple
  326. * Build directories::       Build directories described well
  327. * Makefile generation::     To build a Makefile
  328. * config.guess::            Be vewwy quiet, I'm hunting system information
  329. * config.status::           To rebuild a Makefile
  330. File: configure.info,  Node: Build variables,  Next: Build directories,  Up: What configure really does
  331. Build variables
  332. ---------------
  333.    There are several variables in the build process which you can
  334. control through build programs such as `make'.  These include machine
  335. definitions, local conventions, installation locations, locations for
  336. temporary files, etc.  This data is accessible through certain
  337. variables which are configurable in the build process; we refer to them
  338. as "build variables".
  339.    For lists of build variables which you can affect by using
  340. `configure', see *Note Variables available to `configure.in': configure
  341. variables, and *Note Full descriptions of all installation directories:
  342. Install details.
  343.    Generally, build variables, which are used by the `Makefile' to
  344. determine various aspects of the build and installation processes, are
  345. changeable with command-line options to `configure'.  In most large
  346. suites of programs, like the Cygnus Support Developer's Kit, the
  347. individual programs reside in several subdirectories of a single source
  348. code "tree".  All of these subdirectories need to be configured with
  349. information relative to the "build directory", which is not known until
  350. `configure' is run.  Unless specified otherwise, `configure'
  351. recursively configures every subdirectory in the source tree.
  352.    Build variables are passed from `configure' directly into the
  353. `Makefile', and use the same names (except that dashes are transformed
  354. into underbars; for example, when you specify the option
  355. `--exec-prefix' on the command line, the `Makefile' variable
  356. `exec_prefix' is set).  In other words, if you specify
  357.      eg$ ./configure --prefix=/usr/gnu/local ... HOSTTYPE
  358. on the command line, `configure' sets an variable called `prefix' to
  359. `/usr/gnu/local', and passes this into the `Makefile' in the same
  360. manner.  After this command, each `Makefile' generated by `configure'
  361. will contain a line that reads:
  362.      prefix = /usr/gnu/local
  363.    For a list of the `Makefile' variables `configure' can change, and
  364. instructions on how to change them, see *Note Variables available to
  365. `configure.in': configure variables, and *Note Invoking `configure':
  366. Invoking configure.
  367. File: configure.info,  Node: Build directories,  Next: Makefile generation,  Prev: Build variables,  Up: What configure really does
  368. Build directories
  369. -----------------
  370.    By default, `configure' builds a `Makefile' and symbolic links in the
  371. same directory as the source files.  This default works for many cases,
  372. but it has limitations.  For instance, using this approach, you can
  373. only build object code for one host at a time.
  374.    We refer to each directory where `configure' builds a `Makefile' as
  375. a "build directory".
  376.    The build directory for any given build is always the directory from
  377. which you call `configure', or `.' relative to your prompt.  The default
  378. "source directory", the place `configure' looks to find source code, is
  379. also `.'.  For instance, if we have a directory `/gnu-stuff/src/' that
  380. is the top branch of a tree of GNU source code we wish to configure,
  381. then the program we will use to configure this code is
  382. `/gnu-stuff/src/configure', as follows.  (Assume for the sake of
  383. argument that our machine is a sun4.)
  384.      eg$ cd /gnu-stuff/src
  385.      eg$ ./configure sun4
  386.      Created "Makefile" in /gnu-stuff/src
  387.      eg$
  388.    We just configured the code in `/gnu-stuff/src' to run on a Sun
  389. SPARCstation using SunOS 4.x by creating a `Makefile' in
  390. `/gnu-stuff/src'.  By default, we also specified that when this code is
  391. built, the object code should reside in the same directory,
  392. `/gnu-stuff/src'.
  393.    However, if we wanted to build this code for more than one host, we
  394. would be in trouble, because the new configuration would write over the
  395. old one, destroying it in the process.  What we can do is to make a new
  396. "build directory" and configure from there.  Running `configure' from
  397. the new directory will place a correct `Makefile' and a `config.status'
  398. in this new file.  That is all `configure' does; we must run `make' to
  399. generate any object code.
  400.    The new `Makefile' in `/gnu-stuff/sun4-obj', created from the
  401. template file `/gnu-stuff/src/Makefile.in', contains all the information
  402. needed to build the program.
  403.      eg$ mkdir /gnu-stuff/sun4-obj
  404.      eg$ cd /gnu-stuff/sun4-obj
  405.      eg$ ../src/configure --srcdir=../src sun4
  406.      Created "Makefile" in /gnu-stuff/sun4-obj
  407.      eg$ ls
  408.      Makefile       config.status
  409.      eg$ make all info install install-info clean
  410.      COMPILATION MESSAGES...
  411.      eg$ mkdir /gnu-stuff/solaris2
  412.      eg$ cd /gnu-stuff/solaris2
  413.      eg$ ../src/configure --srcdir=../src sol2
  414.      Created "Makefile" in /gnu-stuff/solaris2
  415.      eg$ ls
  416.      Makefile       config.status
  417.      eg$ make all info install install-info clean
  418.      COMPILATION MESSAGES...
  419.    We can repeat this for other configurations of the same software
  420. simply by making a new build directory and reconfiguring from inside
  421. it.  If you do not specify the HOSTTYPE argument, `configure' will
  422. attempt to figure out what kind of machine and operating system you
  423. happen to be using.  *Note Determining system information:
  424. config.guess.  Of course, this may not always be the configuration you
  425. wish to build.
  426.    *Caution:* If you build more than one configuration for a single
  427. program, remember that you must also specify a different `--prefix' for
  428. each configuration at configure-time.  Otherwise, both configurations
  429. will be installed in the same default location (`/usr/local'); the
  430. configuration to be installed last would overwrite previously installed
  431. configurations.
  432. File: configure.info,  Node: Makefile generation,  Next: config.guess,  Prev: Build directories,  Up: What configure really does
  433. `Makefile' generation
  434. ---------------------
  435.    Cygnus `configure' creates a file called `Makefile' in the build
  436. directory which can be used with `make' to automatically build a given
  437. program or package.  `configure' also builds a `Makefile' for each
  438. relevant subdirectory for a given program or package (irrelevant
  439. subdirectories would be those which contain no code which needs
  440. configuring, and which therefore have no `configure' input file
  441. `configure.in' and no `Makefile' template `Makefile.in').  *Note `make'
  442. Invocation: (make)Running, for details on using `make' to compile your
  443. source code.
  444.    Each `Makefile' contains variables which have been configured for a
  445. specific build.  These build variables are determined when `configure'
  446. is run.  All build variables have defaults.  By default, `configure'
  447. generates a `Makefile' which specifies:
  448.    * a "native" build, which is to occur
  449.    * in the current directory, and which will be installed
  450.    * in the default installation directory (`/usr/local') when the code
  451.      is compiled with `make'.
  452. Variables are changeable through command-line options to `configure'
  453. (*note Invoking `configure': Invoking configure.).
  454.    If you are porting a new program and intend to use `configure', see
  455. *Note Porting with `configure': Porting, as well as *Note Writing
  456. Makefiles: (make)Makefiles, and *Note Makefile Conventions:
  457. (standards)Makefiles.
  458. File: configure.info,  Node: config.guess,  Next: config.status,  Prev: Makefile generation,  Up: What configure really does
  459. Determining system information
  460. ------------------------------
  461.    The shell script `config.guess' is called when you do not specify a
  462. HOSTTYPE on the command line to `configure'.  `config.guess' acquires
  463. available system information from your local machine through the shell
  464. command `uname'.  It compares this information to a database and
  465. attempts to determine a usable three-part system identifier (known as a
  466. "triple") to use as your HOSTTYPE.  *Note What `configure' really does:
  467. What configure really does, to see how this information is used.
  468.    *Note:*  If you do not specify a HOSTTYPE on the command line,
  469. `configure' will attempt to configure your software to run on the
  470. machine you happen to be using.  This may not be the configuration you
  471. desire.
  472. File: configure.info,  Node: config.status,  Prev: config.guess,  Up: What configure really does
  473. `config.status'
  474. ---------------
  475.    The final step in configuring a directory is to create an executable
  476. shell script, `config.status'.  The main purpose of this file is to
  477. allow the `Makefile' for the current directory to rebuild itself, if
  478. necessary.  It is usually run from within the `Makefile'.  *Note
  479. Extensions to the GNU coding standards: Makefile extensions.
  480.    `config.status' also contains a record of the `configure' session
  481. which created it.
  482. File: configure.info,  Node: configure.in,  Next: Install locations,  Prev: What configure really does,  Up: Using configure
  483. The `configure.in' input file
  484. =============================
  485.    A `configure.in' file for Cygnus `configure' consists of a
  486. "per-invocation" section, followed by a "per-host" section, followed by
  487. a "per-target" section, optionally followed by a "post-target" section.
  488. Each section is a shell script fragment, which is executed by the
  489. `configure' shell script at an appropriate time.  Values are passed
  490. among `configure' and the shell fragments through a set of shell
  491. variables.  When each section is being interpreted by the shell, the
  492. shell's current directory is the build directory, and any files created
  493. by the section (or referred to by the section) will be relative to the
  494. build directory.  To reference files in other places (such as the
  495. source directory), prepend a shell variable such as `$(srcdir)/' to the
  496. desired file name.
  497.    The beginning of the `configure.in' file begins the "per-invocation"
  498. section.
  499.    A line beginning with `# per-host:' begins the "per-host" section.
  500.    A line beginning with `# per-target:' begins the "per-target"
  501. section.
  502.    If it exists, the "post-target" section begins with `# post-target:'.
  503. * Menu:
  504. * configure variables::    Variables available to configure.in
  505. * Minimal::                A minimal configure.in
  506. * Declarations::           For each invocation
  507. * per-host::               Host-specific instructions
  508. * per-target::             Target-specific instructions
  509. * post-target::            Instructions to be executed after target info
  510. * Example::                An example configure.in
  511. File: configure.info,  Node: configure variables,  Next: Minimal,  Up: configure.in
  512. Variables available to `configure.in'
  513. -------------------------------------
  514.    The following variables pass information between the standard parts
  515. of `configure' and the shell-script fragments in `configure.in':
  516. `srctrigger'
  517.      Contains the name of a source file that is expected to live in the
  518.      source directory.  You must usually set this in the
  519.      "per-invocation" section of `configure.in'.  `configure' tests to
  520.      see that this file exists.  If the file does not exist,
  521.      `configure' prints an error message.  This is used as a sanity
  522.      check that `configure.in' matches the source directory.
  523. `srcname'
  524.      Contains the name of the source collection contained in the source
  525.      directory.  You must usually set this in the "per-invocation"
  526.      section of `configure.in'.  If the file named in `srctrigger' does
  527.      not exist, `configure' uses the value of `srcname' when it prints
  528.      the error message.
  529. `configdirs'
  530.      Contains the names of any subdirectories in which `configure'
  531.      should recurse.  You must usually set this in the "per-invocation"
  532.      section of `configure.in'.  If `Makefile.in' contains a line
  533.      starting with `SUBDIRS =', then it will be replaced with an
  534.      assignment to `SUBDIRS' using the value of `configdirs' (if
  535.      `subdirs' is empty).  This can be used to determine which
  536.      directories to configure and build depending on the host and
  537.      target configurations.  Use `configdirs' (instead of the `subdirs'
  538.      variable described below) if you want to be able to partition the
  539.      subdirectories, or use independent `Makefile' fragments.  Each
  540.      subdirectory can be independent, and independently reconfigured.
  541. `subdirs'
  542.      Contains the names of any subdirectories where `configure' should
  543.      create a `Makefile' (in addition to the current directory),
  544.      *without* recursively running `configure'.  Use `subdirs' (instead
  545.      of the `configdirs' variable described above) if you want to
  546.      configure all of the directories as a unit.  Since there is a
  547.      single invocation of `configure' that configures many directories,
  548.      all the directories can use the same `Makefile' fragments, and the
  549.      same `configure.in'.
  550. `host'
  551.      Contains the full configuration name for the host (generated by
  552.      the script `config.sub' from the name that you entered).  This is
  553.      a three-part name (commonly referred to as a "triple") of the form
  554.      CPU-VENDOR-OS.
  555.      There are separate variables `host_cpu', `host_vendor', and
  556.      `host_os' that you can use to test each of the three parts; this
  557.      variable is useful, however, for error messages, and for testing
  558.      combinations of the three components.
  559. `host_cpu'
  560.      Contains the first element of the canonical triple representing
  561.      the host as returned by `config.sub'.  This is occasionally used to
  562.      distinguish between minor variations of a particular vendor's
  563.      operating system and sometimes to determine variations in binary
  564.      format between the host and the target.
  565. `host_vendor'
  566.      Contains the second element of the canonical triple representing
  567.      the host as returned by `config.sub'.  This is usually used to
  568.      distinguish among the numerous variations of *common* operating
  569.      systems.
  570. `host_os'
  571.      Contains the the third element of the canonical triple
  572.      representing the host as returned by `config.sub'.
  573. `target'
  574.      Contains the full configuration name (generated by the script
  575.      `config.sub' from the name that you entered) for the target.  Like
  576.      the host, this is a three-part name of the form CPU-VENDOR-OS.
  577.      There are separate variables `target_cpu', `target_vendor', and
  578.      `target_os' that you can use to test each of the three parts; this
  579.      variable is useful, however, for error messages, and for testing
  580.      combinations of the three components.
  581. `target_cpu'
  582.      Contains the first element of the canonical triple representing
  583.      the target as returned by `config.sub'.  This variable is used
  584.      heavily by programs which are involved in building other programs,
  585.      like the compiler, assembler, linker, etc.  Most programs will not
  586.      need the `target' variables at all, but this one could conceivably
  587.      be used to build a program, for instance, that operated on binary
  588.      data files whose byte order or alignment differ from the system
  589.      where the program is running.
  590. `target_vendor'
  591.      Contains the second element of the canonical triple representing
  592.      the target as returned by `config.sub'.  This is usually used to
  593.      distinguish among the numerous variations of *common* operating
  594.      systems or object file formats.  It is sometimes used to switch
  595.      between different flavors of user interfaces.
  596. `target_os'
  597.      Contains the the third element of the canonical triple
  598.      representing the target as returned by `config.sub'.  This
  599.      variable is used by development tools to distinguish between
  600.      subtle variations in object file formats that some vendors use
  601.      across operating system releases.  It might also be use to decide
  602.      which libraries to build or what user interface the tool should
  603.      provide.
  604. `floating_point'
  605.      Set to `no' if you invoked `configure' with the `--nfp'
  606.      command-line option, otherwise it is empty.  This is a request to
  607.      target machines with "no floating point" unit, even if the targets
  608.      ordinarily have floating point units available.
  609. `gas'
  610.      Set to `true' if you invoked `configure' with the `--with-gnu-as'
  611.      command line option, otherwise it is empty.  This is a request to
  612.      assume that the specified HOSTTYPE machine has GNU `as' available
  613.      even if it ordinarily does not.
  614. `srcdir'
  615.      Set to the name of the directory containing the source for this
  616.      program.  This will be different from `.' if you have specified the
  617.      `--srcdir=DIR' option.  `srcdir' can indicate either an absolute
  618.      path or a path relative to the build directory.
  619. `package_makefile_frag'
  620.      If set in `configure.in', this variable should be the name a file
  621.      relative to `srcdir' to be included in the resulting `Makefile'.
  622.      If the named file does not exist, `configure' will print a warning
  623.      message.  This variable is not set by `configure'.
  624. `host_makefile_frag'
  625.      If set in `configure.in', this variable should be the name a file
  626.      relative to `srcdir' to be included in the resulting `Makefile'.
  627.      If the named file does not exist, `configure' will print a warning
  628.      message.  This variable is not set by `configure'.
  629. `target_makefile_frag'
  630.      If set in `configure.in', this variable should be the name of a
  631.      file, relative to `srcdir', to be included in the resulting
  632.      `Makefile'.  If the named file does not exist, `configure' will
  633.      print a warning message.  This variable is not set by `configure'.
  634. `site_makefile_frag'
  635.      Set to a file name representing to the default `Makefile' fragment
  636.      for this host.  It may be set in `configure.in' to override this
  637.      default.  Normally `site_makefile_frag' is empty, but will have a
  638.      value if you specify `--site=SITE' on the command line.
  639. `Makefile'
  640.      Set to the name of the generated `Makefile'.  Normally this value
  641.      is precisely `Makefile', but some programs may want something else.
  642. `removing'
  643.      Normally empty but will be set to some non-null value if you
  644.      specified `--rm' on the command line.  That is, if `removing' is
  645.      not empty, then `configure' is *removing* a configuration rather
  646.      than creating one.
  647. `files'
  648.      If this variable is not empty following the "per-target" section,
  649.      then each word in its value will be the target of a symbolic link
  650.      named in the corresponding word from the `links' variable.
  651. `links'
  652.      If the `files' variable is not empty following the "per-target"
  653.      section, then `configure' creates symbolic links with the first
  654.      word of `links' pointing to the first word of `files', the second
  655.      word of `links' pointing to the second word of `files', and so on.
  656. File: configure.info,  Node: Minimal,  Next: Declarations,  Prev: configure variables,  Up: configure.in
  657. A minimal `configure.in'
  658. ------------------------
  659.    A minimal `configure.in' consists of four lines.
  660.      srctrigger=foo.c
  661.      srcname="source for the foo program"
  662.      # per-host:
  663.      # per-target:
  664.    The `# per-host:' and `# per-target:' lines divide the file into the
  665. three required sections.  The `srctrigger' line names a file.
  666. `configure' checks to see that this file exists in the source directory
  667. before configuring.  If the `srctrigger' file does not exist,
  668. `configure' uses the value of `srcname' to print an error message about
  669. not finding the source.
  670.    This particular example uses no links, and only the default host,
  671. target, and site-specific `Makefile' fragments if they exist.
  672. File: configure.info,  Node: Declarations,  Next: per-host,  Prev: Minimal,  Up: configure.in
  673. For each invocation
  674. -------------------
  675.    `configure' invokes the entire shell script fragment from the start
  676. of `configure.in' up to a line beginning with `# per-host:' immediately
  677. after parsing command line arguments.  The variables `srctrigger' and
  678. `srcname' *must* be set here.
  679.    You might also want to set the variables `configdirs' and
  680. `package_makefile_frag' here.
  681. File: configure.info,  Node: per-host,  Next: per-target,  Prev: Declarations,  Up: configure.in
  682. Host-specific instructions
  683. --------------------------
  684.    The "per-host" section of `configure.in' starts with the line that
  685. begins with `# per-host:' and ends before a line beginning with
  686. `# per-target:'.  `configure' invokes the commands in the "per-host"
  687. section when determining host-specific information.
  688.    This section usually contains a big `case' statement using the
  689. variable `host' to determine appropriate values for
  690. `host_makefile_frag' and `files', although `files' is not usually set
  691. here.  Usually, it is set at the end of the "per-target" section after
  692. determining the names of the target specific configuration files.
  693. File: configure.info,  Node: per-target,  Next: post-target,  Prev: per-host,  Up: configure.in
  694. Target-specific instructions
  695. ----------------------------
  696.    The "per-target" section of `configure.in' starts with the line that
  697. begins with `# per-target:' and ends before the line that begins with
  698. `# post-target:', if there is such a line.  Otherwise the "per-target"
  699. section extends to the end of the file.  `configure' invokes the
  700. commands in the "per-target" section when determining target-specific
  701. information, and before building any files, directories, or links.
  702.    This section usually contains a big `case' statement using the
  703. variable `target' to determine appropriate values for
  704. `target_makefile_frag' and `files'.  The last lines in the "per-target"
  705. section normally set the variables `files' and `links'.
  706. File: configure.info,  Node: post-target,  Next: Example,  Prev: per-target,  Up: configure.in
  707. Instructions to be executed after target info
  708. ---------------------------------------------
  709.    The "post-target" section is optional.  If it exists, the
  710. `post-target' section starts with a line beginning with
  711. `# Post-target:' and extends to the end of the file.  If it exists,
  712. `configure' invokes this section once for each target after building
  713. all files, directories, or links.
  714.    This section is seldom needed, but you can use it to edit the
  715. `Makefile' generated by `configure'.
  716. File: configure.info,  Node: Example,  Prev: post-target,  Up: configure.in
  717. An example `configure.in'
  718. -------------------------
  719.    Here is a small example of a `configure.in' file.
  720.      # This file is a collection of shell script fragments
  721.      # used to tailor a template configure script as
  722.      # appropriate for this directory.  For more information,
  723.      # see configure.texi.
  724.      
  725.      configdirs=
  726.      srctrigger=warshall.c
  727.      srcname="bison"
  728.      
  729.      # per-host:
  730.      case "${host}" in
  731.      m88k-motorola-*)
  732.              host_makefile_frag=config/mh-delta88
  733.              ;;
  734.      esac
  735.      
  736.      # per-target:
  737.      files="bison_in.hairy"
  738.      links="bison.hairy"
  739.      
  740.      # post-target:
  741. File: configure.info,  Node: Install locations,  Next: Host,  Prev: configure.in,  Up: Using configure
  742. Install locations
  743. =================
  744.    Using the default configuration, `make install' creates a single
  745. tree of files, some of which are programs.  The location of this tree
  746. is determined by the value of the variable `prefix'.  The default value
  747. of `prefix' is `/usr/local'.  This is often correct for native tools
  748. installed on only one host.
  749. * Menu:
  750. * prefix::            Changing the default install directory
  751. * exec_prefix::       How to separate host independent files
  752.                                          from host dependent files when
  753.                                          installing for multiple hosts
  754. * Install details::   Full descriptions of all installation subdirectories
  755. File: configure.info,  Node: prefix,  Next: exec_prefix,  Up: Install locations
  756. Changing the default install directory
  757. --------------------------------------
  758.    In the default configuration, all files are installed in
  759. subdirectories of `/usr/local'.  The location is determined by the
  760. value of the `configure' variable `prefix'; in turn, this determines the
  761. value of the `Makefile' variable of the same name (`prefix').
  762.    You can also set the value of the `Makefile' variable `prefix'
  763. explicitly each time you invoke `make' if you are so inclined.  However,
  764. because many programs have this location compiled in, you must specify
  765. the `prefix' value consistently on each invocation of `make', or you
  766. will end up with a broken installation.
  767.    To make this easier, the value of the `configure' variable `prefix'
  768. can be set on the command line to `configure' using the option
  769. `--prefix='.
  770. File: configure.info,  Node: exec_prefix,  Next: Install details,  Prev: prefix,  Up: Install locations
  771. Installing for multiple hosts
  772. -----------------------------
  773.    By default, host dependent files are installed in subdirectories of
  774. `$(exec_prefix)'.  The location is determined by the value of the
  775. `configure' variable `exec_prefix', which determines the value of the
  776. `Makefile' variable `exec_prefix'.  This makes it easier to install for
  777. a single host, and simplifies changing the default location for the
  778. install tree.  The default doesn't allow for multiple hosts to
  779. effectively share host independent files, however.
  780.    To configure so that multiple hosts can share common files, use
  781. something like:
  782.      configure HOST1 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1
  783.      make all info install install-info clean
  784.      
  785.      configure HOST2 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2
  786.      make all info install install-info
  787.    The first line configures the source for HOST1 to place host-specific
  788. programs in subdirectories of `/usr/gnu/H-HOST1'.
  789.    The second line builds and installs all programs for HOST1,
  790. including both host-independent and host-specific files, as well as
  791. removing the host-specific object files from of the build directory.
  792.    The third line reconfigures the source for HOST2 to place host
  793. specific programs in subdirectories of `/usr/gnu/H-HOST2'.
  794.    The fourth line builds and installs all programs for HOST2.  Host
  795. specific files are installed in new directories, but the host
  796. independent files are installed *on top of* the host independent files
  797. installed for HOST1.  This results in a single copy of the host
  798. independent files, suitable for use by both hosts.
  799.    *Note Extensions to the GNU coding standards: Makefile extensions,
  800. for more information.
  801. File: configure.info,  Node: Install details,  Prev: exec_prefix,  Up: Install locations
  802. Full descriptions of all installation subdirectories
  803. ----------------------------------------------------
  804.    During any install, a number of standard directories are created.
  805. Their names are determined by `Makefile' variables.  Some of the
  806. defaults for `Makefile' variables can be changed at configuration time
  807. using command line options to `configure'.  For more information on the
  808. standard directories or the `Makefile' variables, please refer to *Note
  809. Makefile Conventions: (standards)Makefiles.  See also *Note Extensions
  810. to the GNU coding standards: Makefile extensions.
  811.    Note that `configure' does not create the directory indicated by the
  812. variable `srcdir' at any time.  `$(srcdir)' is not an installation
  813. directory.
  814.    You can override all `Makefile' variables on the command line to
  815. `make'.  (*Note Overriding Variables: (make)Overriding.)  If you do so,
  816. you will need to specify the value precisely the same way for each
  817. invocation of `make', or you risk ending up with a broken installation.
  818. This is because many programs have the locations of other programs or
  819. files compiled into them.  If you find yourself overriding any of the
  820. variables frequently, you should consider site dependent `Makefile'
  821. fragments.  See also *Note Adding site info: Sites.
  822.    During `make install', a number of standard directories are created
  823. and populated.  The following `Makefile' variables define them.  Those
  824. whose defaults are set by corresponding `configure' variables are marked
  825. "`Makefile' and `configure'".
  826. `prefix (`Makefile' and `configure')'
  827.      The root of the installation tree.  You can set its `Makefile'
  828.      default with the `--prefix=' command line option to `configure'
  829.      (*note Invoking `configure': Invoking configure.).  The default
  830.      value for `prefix' is `/usr/local'.
  831. `bindir'
  832.      A directory for binary programs that users can run.  The default
  833.      value for `bindir' depends on `prefix'; `bindir' is normally
  834.      changed only indirectly through `prefix'.  The default value for
  835.      `bindir' is `$(prefix)/bin'.
  836. `exec_prefix (`Makefile' and `configure')'
  837.      A directory for host dependent files.  You can specify the
  838.      `Makefile' default value by using the `--exec_prefix=' option to
  839.      `configure'.  (*Note Invoking `configure': Invoking configure.)
  840.      The default value for `exec_prefix' is `$(prefix)'.
  841. `libdir'
  842.      A directory for libraries and support programs.  The default value
  843.      for `libdir' depends on `prefix'; `libdir' is normally changed only
  844.      indirectly through `prefix'.  The default value for `libdir' is
  845.      `$(prefix)/lib'.
  846. `mandir'
  847.      A directory for `man' format documentation ("man pages").  The
  848.      default value for `mandir' depends on `prefix'; `mandir' is
  849.      normally changed only indirectly through `prefix'.  The default
  850.      value for `mandir' is `$(prefix)/man'.
  851. `manNdir'
  852.      These are eight variables named `man1dir', `man2dir', etc.  They
  853.      name the specific directories for each man page section.  For
  854.      example, `man1dir' by default holds the filename `$(mandir)/man1';
  855.      this directory contains `emacs.1' (the man page for GNU Emacs).
  856.      Similarly, `man5dir' contains the value `$(mandir)/man5',
  857.      indicating the directory which holds `rcsfile.5' (the man page
  858.      describing the `rcs' data file format).  The default value for any
  859.      of the `manNdir' variables depends indirectly on `prefix', and is
  860.      normally changed only through `prefix'.  The default value for
  861.      `manNdir' is `$(mandir)/manN'.
  862. `manNext'
  863.      *Not supported by Cygnus `configure'*.  The `GNU Coding Standards'
  864.      do not call for `man1ext', `man2ext', so the intended use for
  865.      `manext' is apparently not parallel to `mandir'.  Its use is not
  866.      clear.  (See also *Note Extensions to the GNU coding standards:
  867.      Makefile extensions.)
  868. `infodir'
  869.      A directory for `info' format documentation.  The default value for
  870.      `infodir' depends indirectly on `prefix'; `infodir' is normally
  871.      changed only through `prefix'.  The default value for `infodir' is
  872.      `$(prefix)/info'.
  873. `docdir'
  874.      A directory for any documentation that is in a format other than
  875.      those used by `info' or `man'.  The default value for `docdir'
  876.      depends indirectly on `prefix'; `docdir' is normally changed only
  877.      through `prefix'.  The default value for `docdir' is
  878.      `$(datadir)/doc'.  *This variable is an extension to the GNU
  879.      coding standards*.  (See also *Note Extensions to the GNU coding
  880.      standards: Makefile extensions.)
  881. `includedir'
  882.      A directory for the header files accompanying the libraries
  883.      installed in `libdir'.  The default value for `includedir' depends
  884.      on `prefix'; `includedir' is normally changed only indirectly
  885.      through `prefix'.  The default value for `includedir' is
  886.      `$(prefix)/include'.
  887. File: configure.info,  Node: Host,  Next: Target,  Prev: Install locations,  Up: Using configure
  888.    The arguments to `configure' are "hosttypes".  By "hosttype" we mean
  889. the "environment" in which the source will be compiled.  This need not
  890. necessarily be the same as the physical machine involved, although it
  891. usually is.
  892.    For example, if some obscure machine had the GNU `POSIX' emulation
  893. libraries available, it would be possible to configure most GNU source
  894. for a `POSIX' system and build it on the obscure host.
  895.    For more on this topic, see *Note On Configuring Development Tools:
  896. (cfg-paper)Host Environments.
  897. File: configure.info,  Node: Target,  Next: Makefile fragments,  Prev: Host,  Up: Using configure
  898. Target
  899. ======
  900.    For building native development tools, or most of the other GNU
  901. tools, you need not worry about the target.  The "target" of a
  902. configuration defaults to the same as the "host".
  903.    For building cross development tools, please see *Note On
  904. Configuring Development Tools: (cfg-paper)Building Development
  905. Environments.
  906.