This is Info file configure.info, produced by Makeinfo-1.64 from the input file ./configure.texi. START-INFO-DIR-ENTRY * configure: (configure). Cygnus configure. END-INFO-DIR-ENTRY This document describes the Cygnus Support version of `configure'. Copyright (C) 1991, 1992, 1993 Cygnus Support Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, provided that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions, except that this permission notice may be stated in a translation approved by Cygnus Support.  File: configure.info, Node: Top, Next: What configure does, Up: (dir) Cygnus configure **************** This file documents the configuration system used and distributed by Cygnus Support. * Menu: * What configure does:: What configure does * Invoking configure:: Invoking configure--basic usage * Using configure:: More than you ever wanted to know * Porting:: How to use configure with new programs * Variables Index:: * Concept Index::  File: configure.info, Node: What configure does, Next: Invoking configure, Prev: Top, Up: Top What `configure' does ********************* This manual documents Cygnus `configure', a program which helps to automate much of the setup activity associated with building large suites of programs, such the Cygnus Support Developer's Kit. This manual is therefore geared toward readers who are likely to face the problem of configuring software in source form before compiling and installing it. We assume you are an experienced programmer or system administrator. For further background on this topic, see *Note Apologia Configure: (cfg-paper)Some Basic Terms, by K. Richard Pixley. When `configure' runs, it does the following things: ** creates build directories* When you run `configure' with the `--srcdir' option, it uses the current directory as the "build directory", creating under it a directory tree that parallels the directory structure of the source directory. If you don't specify a `srcdir', `configure' first assumes that the source code you wish to configure is in your current directory; if it finds no `configure.in' input file there, it searches in the directory `configure' itself lies in. (For details, see *Note Build directories: Build directories.) ** generates `Makefile'* A `Makefile' template from the source directory, usually called `Makefile.in', is copied to an output file in the build directory which is most often named `Makefile'. `configure' places definitions for a number of standard `Makefile' macros at the beginning of the output file. If `--prefix=DIR' or `--exec_prefix=DIR' are specified on the `configure' command line, corresponding `Makefile' variables are set accordingly. If host, target, or site-specific `Makefile' fragments exist, these are inserted into the output file. (For details, see *Note `Makefile' generation: Makefile generation.) ** generates `.gdbinit'* If the source directory contains a `.gdbinit' file and the build directory is not the same as the source directory, a `.gdbinit' file is created in the build directory. This `.gdbinit' file contains commands which allow the source directory to be read when debugging with the GNU debugger, `gdb'. (*Note Command Files: (gdb)Command Files.) ** makes symbolic links* Most build directories require that some symbolic links with generic names are built pointing to specific files in the source directory. If the system where `configure' runs cannot support symbolic links, hard links are used instead. (For details, see *Note The `configure.in' input file: configure.in.) ** generates `config.status'* `configure' creates a shell script named `config.status' in the build directory. This shell script, when run from the build directory (usually from within a `Makefile'), will reconfigure the build directory (but not its subdirectories). This is most often used to have a `Makefile' update itself automatically if a new source directory is available. ** calls itself recursively* If the source directory has subdirectories that should also be configured, `configure' is called for each.  File: configure.info, Node: Invoking configure, Next: Using configure, Prev: What configure does, Up: Top Invoking `configure' ******************** Cygnus `configure' is a shell script which resides in a source tree. The usual way to invoke `configure' is from the shell, as follows: eg$ ./configure HOSTTYPE This prepares the source in the current directory (`.') to be compiled for a HOSTTYPE environment. It assumes that you wish to build programs and files in the default "build directory" (also the current directory, `.'). If you do not specify a value for HOSTTYPE, Cygnus `configure' will attempt to discover this information by itself (*note Determining system information: config.guess.). For information on HOSTTYPE environments, *Note Host: Host. All GNU software is packaged with one or more `configure' script(s) (*note How Configuration Should Work: (standards)Configuration.). By using `configure' you prepare the source for your specific environment by selecting and using `Makefile' fragments and fragments of shell scripts, which are prepared in advance and stored with the source. `configure''s command-line options also allow you to specify other aspects of the source configuration: configure HOSTTYPE [--target=TARGET] [--srcdir=DIR] [--rm] [--site=SITE] [--prefix=DIR] [--exec-prefix=DIR] [--program-prefix=STRING] [--tmpdir=DIR] [--with-PACKAGE[=YES/NO]] [--without-PACKAGE] [--enable-FEATURE[=YES/NO]] [--disable-FEATURE] [--norecursion] [--nfp] [-s] [-v] [-V | --version] [--help] `--target=TARGET' Requests that the sources be configured to target the TARGET machine. If no target is specified explicitly, the target is assumed to be the same as the host (i.e., a "native" configuration). *Note Host: Host, and *Note Target: Target, for discussions of each. `--srcdir=DIR' Direct each generated `Makefile' to use the sources located in directory DIR. Use this option whenever you wish the object code to reside in a different place from the source code. The "build directory" is always assumed to be the directory you call `configure' from. See *Note Build directories: Build directories, for an example. If the source directory is not specified, `configure' assumes that the source is in your current directory. If `configure' finds no `configure.in' there, it searches in the same directory that the `configure' script itself lies in. Pathnames specified (Values for DIR) can be either absolute relative to the *build* directory. `--rm' *Remove* the configuration specified by HOSTTYPE and the other command-line options, rather than create it. *Note:* We recommend that you use `make distclean' rather than use this option; see *Note Invoking `make': (make)Invoking make, for details on `make distclean'. `--site=SITE' Generate the `Makefile' using site-specific `Makefile' fragments for SITE. *Note Adding information about local conventions: Makefile fragments. `--prefix=DIR' Configure the source to install programs and files under directory DIR. This option sets the variable `prefix'. Each generated `Makefile' will have its `prefix' variables set to this value. (*Note What `configure' really does: What configure really does.) `--exec-prefix=DIR' Configure the source to install "host dependent" files in DIR. This option sets the variable `exec_prefix'. Each generated `Makefile' will have its `exec_prefix' variables set to this value. (*Note What `configure' really does: What configure really does.) `--program-prefix=STRING' Configure the source to install certain programs using STRING as a prefix. This applies to programs which might be used for cross-compilation, such as the compiler and the binary utilities, and also to programs which have the same names as common Unix programs, such as `make'. This option sets the variable `program_prefix'. Each generated `Makefile' will have its `program_prefix' variables set to this value. (*Note What `configure' really does: What configure really does.) `--tmpdir=TMPDIR' Use the directory TMPDIR for `configure''s temporary files. The default is the value of the environment variable `TMPDIR', or `/tmp' if the environment variable is not set. `--with-PACKAGE[=YES/NO]' `--without-PACKAGE' Indicate that PACKAGE is present, or not present, depending on YES/NO. If YES/NO is nonexistent, its value is assumed to be `yes'. `--without-PACKAGE' is equivalent to `--with-PACKAGE=no'. For example, if you wish to configure the program `gcc' for a Sun SPARCstation running SunOS 4.x, and you want `gcc' to use the GNU linker `ld', you can configure `gcc' using eg$ configure --with-gnu-ld sun4 *Note What `configure' really does: What configure really does, for details. See the installation or release notes for your particular package for details on which other PACKAGE options are recognized. `--enable-FEATURE[=YES/NO]' `--disable-FEATURE' Include FEATURE, or not, depending on YES/NO. If YES/NO is nonexistent, its value is assumed to be `yes'. `--disable-FEATURE' is equivalent to `--enable-FEATURE=no'. *Note What `configure' really does: What configure really does, for details. See the installation or release notes for your particular package for details on which other FEATURE options are recognized. `--norecursion' Configure only this directory; ignore any subdirectories. This is used by the executable shell script `config.status' to reconfigure only the current directory; it is most often used non-interactively, when `make' is invoked. (*Note `config.status': config.status.) `--nfp' Assume that the intended HOSTTYPE has no floating point unit. `-s' Suppress status output. This option is used internally by `configure' when calling itself recursively in subdirectories. You can override this option with the `--verbose' option. `-v' `--verbose' Print status lines for each directory configured. Normally, only the status lines for the initial working directory are printed. `--version' `-V' Print the `configure' version number. `--help' Print a short summary of how to invoke `configure'. *Note:* You may introduce options with a single dash, `-', rather than two dashes, `--'. However, you may not be able to truncate long option names when using a single dash. When using two dashes, options may be abbreviated as long as each option can be uniquely identified. For example, eg$ configure --s=/u/me/src HOSTTYPE is ambiguous, as `--s' could refer to either `--site' or `--srcdir'. However, eg$ configure --src=/u/me/src HOSTTYPE is a valid abbreviation.  File: configure.info, Node: Using configure, Next: Porting, Prev: Invoking configure, Up: Top Using `configure' ***************** `configure' prepares source directories for building programs in them. "Configuring" is the process of preparing software to compile correctly on a given "host", for a given "target". `configure' subsequently writes a configured `Makefile' from a pre-built template; `configure' uses variables that have been set in the configuring process to determine the values of some variables in the `Makefile'. Because of this we will refer to both `configure' variables and `Makefile' variables. This convention allows us to determine where the variable should be set initially, in either `configure.in' or `Makefile.in'. * Menu: * What configure really does:: What configure really does * configure.in:: The configure.in input file * Install locations:: Where to install things once they are built * Host:: Telling configure what will source will be built * Target:: Telling configure what the source will target * Makefile fragments:: Adding information about local conventions * Makefile extensions:: Extensions to the GNU coding standards  File: configure.info, Node: What configure really does, Next: configure.in, Up: Using configure What `configure' really does ============================ Cygnus `configure' is a shell script that sets up an environment in which your programs will compile correctly for your machine and operating system, and will install in proper places. `configure' accomplishes this task by doing the following: * it generates a `Makefile' from a custom template called `Makefile.in' in each relevant source directory; * it customizes the build process to your specifications; you set certain variables for `configure', either on the command line or in the file `configure.in', which subsequently sets variables in each generated `Makefile' to be used by `make' when actually building the software; * it creates "build directories", places for your code to be compiled in before being installed; * it generates a `.gdbinit' in the build directory, if needed, to communicate to `gdb' where to find the program's source code; * it generates a shell script called `config.status' which is used most often by the `Makefile' to reconfigure itself; * it recurses in subdirectories, setting up entire trees so that they build correctly; if `configure' finds another `configure' script further down in a given source tree, it knows to use this script and not recur. For the sake of safety (i.e., in order to prevent broken installations), the GNU coding standards call for software to be "configured" in such a way that an end user trying to build a given package will be able to do so by affecting a finite number of variables. All GNU software comes with an executable `configure' shell script which sets up an environment within a build directory which will correctly compile your new package for your host (or, alternatively, whatever host you specify to `configure'). For further background on this topic, see *Note Apologia Configure: (cfg-paper)Some Basic Terms, by K. Richard Pixley. Use `configure' to set for the build process: * correct values for certain variables; * which type of host you wish to configure a given package for (*note Host: Host.); * where you want to install this package (by using `prefix', `exec-prefix' and `program-prefix'; *note Full descriptions of all installation directories: Install details.); * optionally, which type of machine you wish to "target" this package's output to (*note Target: Target.); * which other GNU packages are already installed and available to this particular build (by using the `--with-PACKAGE' option; *note Invoking `configure': Invoking configure.); * where to place temporary files (by using the `--tmpdir=DIR' option; *note Invoking `configure': Invoking configure.); * whether to recur in subdirectories (changeable through the `--norecursion' option; *note Invoking `configure': Invoking configure.). `configure' uses a few other files to complete its tasks. These are discussed in detail where noted. `configure.in' Input file for `configure'. Shell script fragments reside here. *Note The `configure.in' input file: configure.in. `Makefile.in' Template which `configure' uses to build a file called `Makefile' in the "build directory". *Note `Makefile' generation: Makefile generation. `config.sub' Shell script used by `configure' to expand referents to the HOSTTYPE argument into a single specification of the form CPU-VENDOR-OS. For instance, on the command line you can specify eg$ ./configure sun4 to configure for a Sun SPARCstation running SunOS 4.x. `configure' consults `config.sub' to find that the three-part specification for this is sparc-sun-sunos4.1.1 which notes the CPU as `sparc', the MANUFACTURER as `sun' (Sun Microsystems), and the OS (operating system) as `sunos4.1.1', the SunOS 4.1.1 release. *Note Variables available to `configure': configure variables. `config.guess' If you do not put the HOSTTYPE argument on the command line, `configure' uses the `config.guess' shell script to make an analysis of your machine (it assumes that you wish to configure your software for the type of machine on which you are running). The output of `config.guess' is a three-part identifier as described above. `config.status' The final step in configuring a directory is to create a shell script, `config.status'. The main purpose of this file is to allow the `Makefile' for the current directory to rebuild itself, if necessary. *Note `config.status': config.status. `config/*' `configure' uses three types of `Makefile' "fragments", which reside in the directory `SRCDIR/config/'. *Note Adding information about local conventions: Makefile fragments. * Menu: * Build variables:: Variable-spaghetti made simple * Build directories:: Build directories described well * Makefile generation:: To build a Makefile * config.guess:: Be vewwy quiet, I'm hunting system information * config.status:: To rebuild a Makefile  File: configure.info, Node: Build variables, Next: Build directories, Up: What configure really does Build variables --------------- There are several variables in the build process which you can control through build programs such as `make'. These include machine definitions, local conventions, installation locations, locations for temporary files, etc. This data is accessible through certain variables which are configurable in the build process; we refer to them as "build variables". For lists of build variables which you can affect by using `configure', see *Note Variables available to `configure.in': configure variables, and *Note Full descriptions of all installation directories: Install details. Generally, build variables, which are used by the `Makefile' to determine various aspects of the build and installation processes, are changeable with command-line options to `configure'. In most large suites of programs, like the Cygnus Support Developer's Kit, the individual programs reside in several subdirectories of a single source code "tree". All of these subdirectories need to be configured with information relative to the "build directory", which is not known until `configure' is run. Unless specified otherwise, `configure' recursively configures every subdirectory in the source tree. Build variables are passed from `configure' directly into the `Makefile', and use the same names (except that dashes are transformed into underbars; for example, when you specify the option `--exec-prefix' on the command line, the `Makefile' variable `exec_prefix' is set). In other words, if you specify eg$ ./configure --prefix=/usr/gnu/local ... HOSTTYPE on the command line, `configure' sets an variable called `prefix' to `/usr/gnu/local', and passes this into the `Makefile' in the same manner. After this command, each `Makefile' generated by `configure' will contain a line that reads: prefix = /usr/gnu/local For a list of the `Makefile' variables `configure' can change, and instructions on how to change them, see *Note Variables available to `configure.in': configure variables, and *Note Invoking `configure': Invoking configure.  File: configure.info, Node: Build directories, Next: Makefile generation, Prev: Build variables, Up: What configure really does Build directories ----------------- By default, `configure' builds a `Makefile' and symbolic links in the same directory as the source files. This default works for many cases, but it has limitations. For instance, using this approach, you can only build object code for one host at a time. We refer to each directory where `configure' builds a `Makefile' as a "build directory". The build directory for any given build is always the directory from which you call `configure', or `.' relative to your prompt. The default "source directory", the place `configure' looks to find source code, is also `.'. For instance, if we have a directory `/gnu-stuff/src/' that is the top branch of a tree of GNU source code we wish to configure, then the program we will use to configure this code is `/gnu-stuff/src/configure', as follows. (Assume for the sake of argument that our machine is a sun4.) eg$ cd /gnu-stuff/src eg$ ./configure sun4 Created "Makefile" in /gnu-stuff/src eg$ We just configured the code in `/gnu-stuff/src' to run on a Sun SPARCstation using SunOS 4.x by creating a `Makefile' in `/gnu-stuff/src'. By default, we also specified that when this code is built, the object code should reside in the same directory, `/gnu-stuff/src'. However, if we wanted to build this code for more than one host, we would be in trouble, because the new configuration would write over the old one, destroying it in the process. What we can do is to make a new "build directory" and configure from there. Running `configure' from the new directory will place a correct `Makefile' and a `config.status' in this new file. That is all `configure' does; we must run `make' to generate any object code. The new `Makefile' in `/gnu-stuff/sun4-obj', created from the template file `/gnu-stuff/src/Makefile.in', contains all the information needed to build the program. eg$ mkdir /gnu-stuff/sun4-obj eg$ cd /gnu-stuff/sun4-obj eg$ ../src/configure --srcdir=../src sun4 Created "Makefile" in /gnu-stuff/sun4-obj eg$ ls Makefile config.status eg$ make all info install install-info clean COMPILATION MESSAGES... eg$ mkdir /gnu-stuff/solaris2 eg$ cd /gnu-stuff/solaris2 eg$ ../src/configure --srcdir=../src sol2 Created "Makefile" in /gnu-stuff/solaris2 eg$ ls Makefile config.status eg$ make all info install install-info clean COMPILATION MESSAGES... We can repeat this for other configurations of the same software simply by making a new build directory and reconfiguring from inside it. If you do not specify the HOSTTYPE argument, `configure' will attempt to figure out what kind of machine and operating system you happen to be using. *Note Determining system information: config.guess. Of course, this may not always be the configuration you wish to build. *Caution:* If you build more than one configuration for a single program, remember that you must also specify a different `--prefix' for each configuration at configure-time. Otherwise, both configurations will be installed in the same default location (`/usr/local'); the configuration to be installed last would overwrite previously installed configurations.  File: configure.info, Node: Makefile generation, Next: config.guess, Prev: Build directories, Up: What configure really does `Makefile' generation --------------------- Cygnus `configure' creates a file called `Makefile' in the build directory which can be used with `make' to automatically build a given program or package. `configure' also builds a `Makefile' for each relevant subdirectory for a given program or package (irrelevant subdirectories would be those which contain no code which needs configuring, and which therefore have no `configure' input file `configure.in' and no `Makefile' template `Makefile.in'). *Note `make' Invocation: (make)Running, for details on using `make' to compile your source code. Each `Makefile' contains variables which have been configured for a specific build. These build variables are determined when `configure' is run. All build variables have defaults. By default, `configure' generates a `Makefile' which specifies: * a "native" build, which is to occur * in the current directory, and which will be installed * in the default installation directory (`/usr/local') when the code is compiled with `make'. Variables are changeable through command-line options to `configure' (*note Invoking `configure': Invoking configure.). If you are porting a new program and intend to use `configure', see *Note Porting with `configure': Porting, as well as *Note Writing Makefiles: (make)Makefiles, and *Note Makefile Conventions: (standards)Makefiles.  File: configure.info, Node: config.guess, Next: config.status, Prev: Makefile generation, Up: What configure really does Determining system information ------------------------------ The shell script `config.guess' is called when you do not specify a HOSTTYPE on the command line to `configure'. `config.guess' acquires available system information from your local machine through the shell command `uname'. It compares this information to a database and attempts to determine a usable three-part system identifier (known as a "triple") to use as your HOSTTYPE. *Note What `configure' really does: What configure really does, to see how this information is used. *Note:* If you do not specify a HOSTTYPE on the command line, `configure' will attempt to configure your software to run on the machine you happen to be using. This may not be the configuration you desire.  File: configure.info, Node: config.status, Prev: config.guess, Up: What configure really does `config.status' --------------- The final step in configuring a directory is to create an executable shell script, `config.status'. The main purpose of this file is to allow the `Makefile' for the current directory to rebuild itself, if necessary. It is usually run from within the `Makefile'. *Note Extensions to the GNU coding standards: Makefile extensions. `config.status' also contains a record of the `configure' session which created it.  File: configure.info, Node: configure.in, Next: Install locations, Prev: What configure really does, Up: Using configure The `configure.in' input file ============================= A `configure.in' file for Cygnus `configure' consists of a "per-invocation" section, followed by a "per-host" section, followed by a "per-target" section, optionally followed by a "post-target" section. Each section is a shell script fragment, which is executed by the `configure' shell script at an appropriate time. Values are passed among `configure' and the shell fragments through a set of shell variables. When each section is being interpreted by the shell, the shell's current directory is the build directory, and any files created by the section (or referred to by the section) will be relative to the build directory. To reference files in other places (such as the source directory), prepend a shell variable such as `$(srcdir)/' to the desired file name. The beginning of the `configure.in' file begins the "per-invocation" section. A line beginning with `# per-host:' begins the "per-host" section. A line beginning with `# per-target:' begins the "per-target" section. If it exists, the "post-target" section begins with `# post-target:'. * Menu: * configure variables:: Variables available to configure.in * Minimal:: A minimal configure.in * Declarations:: For each invocation * per-host:: Host-specific instructions * per-target:: Target-specific instructions * post-target:: Instructions to be executed after target info * Example:: An example configure.in  File: configure.info, Node: configure variables, Next: Minimal, Up: configure.in Variables available to `configure.in' ------------------------------------- The following variables pass information between the standard parts of `configure' and the shell-script fragments in `configure.in': `srctrigger' Contains the name of a source file that is expected to live in the source directory. You must usually set this in the "per-invocation" section of `configure.in'. `configure' tests to see that this file exists. If the file does not exist, `configure' prints an error message. This is used as a sanity check that `configure.in' matches the source directory. `srcname' Contains the name of the source collection contained in the source directory. You must usually set this in the "per-invocation" section of `configure.in'. If the file named in `srctrigger' does not exist, `configure' uses the value of `srcname' when it prints the error message. `configdirs' Contains the names of any subdirectories in which `configure' should recurse. You must usually set this in the "per-invocation" section of `configure.in'. If `Makefile.in' contains a line starting with `SUBDIRS =', then it will be replaced with an assignment to `SUBDIRS' using the value of `configdirs' (if `subdirs' is empty). This can be used to determine which directories to configure and build depending on the host and target configurations. Use `configdirs' (instead of the `subdirs' variable described below) if you want to be able to partition the subdirectories, or use independent `Makefile' fragments. Each subdirectory can be independent, and independently reconfigured. `subdirs' Contains the names of any subdirectories where `configure' should create a `Makefile' (in addition to the current directory), *without* recursively running `configure'. Use `subdirs' (instead of the `configdirs' variable described above) if you want to configure all of the directories as a unit. Since there is a single invocation of `configure' that configures many directories, all the directories can use the same `Makefile' fragments, and the same `configure.in'. `host' Contains the full configuration name for the host (generated by the script `config.sub' from the name that you entered). This is a three-part name (commonly referred to as a "triple") of the form CPU-VENDOR-OS. There are separate variables `host_cpu', `host_vendor', and `host_os' that you can use to test each of the three parts; this variable is useful, however, for error messages, and for testing combinations of the three components. `host_cpu' Contains the first element of the canonical triple representing the host as returned by `config.sub'. This is occasionally used to distinguish between minor variations of a particular vendor's operating system and sometimes to determine variations in binary format between the host and the target. `host_vendor' Contains the second element of the canonical triple representing the host as returned by `config.sub'. This is usually used to distinguish among the numerous variations of *common* operating systems. `host_os' Contains the the third element of the canonical triple representing the host as returned by `config.sub'. `target' Contains the full configuration name (generated by the script `config.sub' from the name that you entered) for the target. Like the host, this is a three-part name of the form CPU-VENDOR-OS. There are separate variables `target_cpu', `target_vendor', and `target_os' that you can use to test each of the three parts; this variable is useful, however, for error messages, and for testing combinations of the three components. `target_cpu' Contains the first element of the canonical triple representing the target as returned by `config.sub'. This variable is used heavily by programs which are involved in building other programs, like the compiler, assembler, linker, etc. Most programs will not need the `target' variables at all, but this one could conceivably be used to build a program, for instance, that operated on binary data files whose byte order or alignment differ from the system where the program is running. `target_vendor' Contains the second element of the canonical triple representing the target as returned by `config.sub'. This is usually used to distinguish among the numerous variations of *common* operating systems or object file formats. It is sometimes used to switch between different flavors of user interfaces. `target_os' Contains the the third element of the canonical triple representing the target as returned by `config.sub'. This variable is used by development tools to distinguish between subtle variations in object file formats that some vendors use across operating system releases. It might also be use to decide which libraries to build or what user interface the tool should provide. `floating_point' Set to `no' if you invoked `configure' with the `--nfp' command-line option, otherwise it is empty. This is a request to target machines with "no floating point" unit, even if the targets ordinarily have floating point units available. `gas' Set to `true' if you invoked `configure' with the `--with-gnu-as' command line option, otherwise it is empty. This is a request to assume that the specified HOSTTYPE machine has GNU `as' available even if it ordinarily does not. `srcdir' Set to the name of the directory containing the source for this program. This will be different from `.' if you have specified the `--srcdir=DIR' option. `srcdir' can indicate either an absolute path or a path relative to the build directory. `package_makefile_frag' If set in `configure.in', this variable should be the name a file relative to `srcdir' to be included in the resulting `Makefile'. If the named file does not exist, `configure' will print a warning message. This variable is not set by `configure'. `host_makefile_frag' If set in `configure.in', this variable should be the name a file relative to `srcdir' to be included in the resulting `Makefile'. If the named file does not exist, `configure' will print a warning message. This variable is not set by `configure'. `target_makefile_frag' If set in `configure.in', this variable should be the name of a file, relative to `srcdir', to be included in the resulting `Makefile'. If the named file does not exist, `configure' will print a warning message. This variable is not set by `configure'. `site_makefile_frag' Set to a file name representing to the default `Makefile' fragment for this host. It may be set in `configure.in' to override this default. Normally `site_makefile_frag' is empty, but will have a value if you specify `--site=SITE' on the command line. `Makefile' Set to the name of the generated `Makefile'. Normally this value is precisely `Makefile', but some programs may want something else. `removing' Normally empty but will be set to some non-null value if you specified `--rm' on the command line. That is, if `removing' is not empty, then `configure' is *removing* a configuration rather than creating one. `files' If this variable is not empty following the "per-target" section, then each word in its value will be the target of a symbolic link named in the corresponding word from the `links' variable. `links' If the `files' variable is not empty following the "per-target" section, then `configure' creates symbolic links with the first word of `links' pointing to the first word of `files', the second word of `links' pointing to the second word of `files', and so on.  File: configure.info, Node: Minimal, Next: Declarations, Prev: configure variables, Up: configure.in A minimal `configure.in' ------------------------ A minimal `configure.in' consists of four lines. srctrigger=foo.c srcname="source for the foo program" # per-host: # per-target: The `# per-host:' and `# per-target:' lines divide the file into the three required sections. The `srctrigger' line names a file. `configure' checks to see that this file exists in the source directory before configuring. If the `srctrigger' file does not exist, `configure' uses the value of `srcname' to print an error message about not finding the source. This particular example uses no links, and only the default host, target, and site-specific `Makefile' fragments if they exist.  File: configure.info, Node: Declarations, Next: per-host, Prev: Minimal, Up: configure.in For each invocation ------------------- `configure' invokes the entire shell script fragment from the start of `configure.in' up to a line beginning with `# per-host:' immediately after parsing command line arguments. The variables `srctrigger' and `srcname' *must* be set here. You might also want to set the variables `configdirs' and `package_makefile_frag' here.  File: configure.info, Node: per-host, Next: per-target, Prev: Declarations, Up: configure.in Host-specific instructions -------------------------- The "per-host" section of `configure.in' starts with the line that begins with `# per-host:' and ends before a line beginning with `# per-target:'. `configure' invokes the commands in the "per-host" section when determining host-specific information. This section usually contains a big `case' statement using the variable `host' to determine appropriate values for `host_makefile_frag' and `files', although `files' is not usually set here. Usually, it is set at the end of the "per-target" section after determining the names of the target specific configuration files.  File: configure.info, Node: per-target, Next: post-target, Prev: per-host, Up: configure.in Target-specific instructions ---------------------------- The "per-target" section of `configure.in' starts with the line that begins with `# per-target:' and ends before the line that begins with `# post-target:', if there is such a line. Otherwise the "per-target" section extends to the end of the file. `configure' invokes the commands in the "per-target" section when determining target-specific information, and before building any files, directories, or links. This section usually contains a big `case' statement using the variable `target' to determine appropriate values for `target_makefile_frag' and `files'. The last lines in the "per-target" section normally set the variables `files' and `links'.  File: configure.info, Node: post-target, Next: Example, Prev: per-target, Up: configure.in Instructions to be executed after target info --------------------------------------------- The "post-target" section is optional. If it exists, the `post-target' section starts with a line beginning with `# Post-target:' and extends to the end of the file. If it exists, `configure' invokes this section once for each target after building all files, directories, or links. This section is seldom needed, but you can use it to edit the `Makefile' generated by `configure'.  File: configure.info, Node: Example, Prev: post-target, Up: configure.in An example `configure.in' ------------------------- Here is a small example of a `configure.in' file. # This file is a collection of shell script fragments # used to tailor a template configure script as # appropriate for this directory. For more information, # see configure.texi. configdirs= srctrigger=warshall.c srcname="bison" # per-host: case "${host}" in m88k-motorola-*) host_makefile_frag=config/mh-delta88 ;; esac # per-target: files="bison_in.hairy" links="bison.hairy" # post-target:  File: configure.info, Node: Install locations, Next: Host, Prev: configure.in, Up: Using configure Install locations ================= Using the default configuration, `make install' creates a single tree of files, some of which are programs. The location of this tree is determined by the value of the variable `prefix'. The default value of `prefix' is `/usr/local'. This is often correct for native tools installed on only one host. * Menu: * prefix:: Changing the default install directory * exec_prefix:: How to separate host independent files from host dependent files when installing for multiple hosts * Install details:: Full descriptions of all installation subdirectories  File: configure.info, Node: prefix, Next: exec_prefix, Up: Install locations Changing the default install directory -------------------------------------- In the default configuration, all files are installed in subdirectories of `/usr/local'. The location is determined by the value of the `configure' variable `prefix'; in turn, this determines the value of the `Makefile' variable of the same name (`prefix'). You can also set the value of the `Makefile' variable `prefix' explicitly each time you invoke `make' if you are so inclined. However, because many programs have this location compiled in, you must specify the `prefix' value consistently on each invocation of `make', or you will end up with a broken installation. To make this easier, the value of the `configure' variable `prefix' can be set on the command line to `configure' using the option `--prefix='.  File: configure.info, Node: exec_prefix, Next: Install details, Prev: prefix, Up: Install locations Installing for multiple hosts ----------------------------- By default, host dependent files are installed in subdirectories of `$(exec_prefix)'. The location is determined by the value of the `configure' variable `exec_prefix', which determines the value of the `Makefile' variable `exec_prefix'. This makes it easier to install for a single host, and simplifies changing the default location for the install tree. The default doesn't allow for multiple hosts to effectively share host independent files, however. To configure so that multiple hosts can share common files, use something like: configure HOST1 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host1 make all info install install-info clean configure HOST2 -prefix=/usr/gnu -exec_prefix=/usr/gnu/H-host2 make all info install install-info The first line configures the source for HOST1 to place host-specific programs in subdirectories of `/usr/gnu/H-HOST1'. The second line builds and installs all programs for HOST1, including both host-independent and host-specific files, as well as removing the host-specific object files from of the build directory. The third line reconfigures the source for HOST2 to place host specific programs in subdirectories of `/usr/gnu/H-HOST2'. The fourth line builds and installs all programs for HOST2. Host specific files are installed in new directories, but the host independent files are installed *on top of* the host independent files installed for HOST1. This results in a single copy of the host independent files, suitable for use by both hosts. *Note Extensions to the GNU coding standards: Makefile extensions, for more information.  File: configure.info, Node: Install details, Prev: exec_prefix, Up: Install locations Full descriptions of all installation subdirectories ---------------------------------------------------- During any install, a number of standard directories are created. Their names are determined by `Makefile' variables. Some of the defaults for `Makefile' variables can be changed at configuration time using command line options to `configure'. For more information on the standard directories or the `Makefile' variables, please refer to *Note Makefile Conventions: (standards)Makefiles. See also *Note Extensions to the GNU coding standards: Makefile extensions. Note that `configure' does not create the directory indicated by the variable `srcdir' at any time. `$(srcdir)' is not an installation directory. You can override all `Makefile' variables on the command line to `make'. (*Note Overriding Variables: (make)Overriding.) If you do so, you will need to specify the value precisely the same way for each invocation of `make', or you risk ending up with a broken installation. This is because many programs have the locations of other programs or files compiled into them. If you find yourself overriding any of the variables frequently, you should consider site dependent `Makefile' fragments. See also *Note Adding site info: Sites. During `make install', a number of standard directories are created and populated. The following `Makefile' variables define them. Those whose defaults are set by corresponding `configure' variables are marked "`Makefile' and `configure'". `prefix (`Makefile' and `configure')' The root of the installation tree. You can set its `Makefile' default with the `--prefix=' command line option to `configure' (*note Invoking `configure': Invoking configure.). The default value for `prefix' is `/usr/local'. `bindir' A directory for binary programs that users can run. The default value for `bindir' depends on `prefix'; `bindir' is normally changed only indirectly through `prefix'. The default value for `bindir' is `$(prefix)/bin'. `exec_prefix (`Makefile' and `configure')' A directory for host dependent files. You can specify the `Makefile' default value by using the `--exec_prefix=' option to `configure'. (*Note Invoking `configure': Invoking configure.) The default value for `exec_prefix' is `$(prefix)'. `libdir' A directory for libraries and support programs. The default value for `libdir' depends on `prefix'; `libdir' is normally changed only indirectly through `prefix'. The default value for `libdir' is `$(prefix)/lib'. `mandir' A directory for `man' format documentation ("man pages"). The default value for `mandir' depends on `prefix'; `mandir' is normally changed only indirectly through `prefix'. The default value for `mandir' is `$(prefix)/man'. `manNdir' These are eight variables named `man1dir', `man2dir', etc. They name the specific directories for each man page section. For example, `man1dir' by default holds the filename `$(mandir)/man1'; this directory contains `emacs.1' (the man page for GNU Emacs). Similarly, `man5dir' contains the value `$(mandir)/man5', indicating the directory which holds `rcsfile.5' (the man page describing the `rcs' data file format). The default value for any of the `manNdir' variables depends indirectly on `prefix', and is normally changed only through `prefix'. The default value for `manNdir' is `$(mandir)/manN'. `manNext' *Not supported by Cygnus `configure'*. The `GNU Coding Standards' do not call for `man1ext', `man2ext', so the intended use for `manext' is apparently not parallel to `mandir'. Its use is not clear. (See also *Note Extensions to the GNU coding standards: Makefile extensions.) `infodir' A directory for `info' format documentation. The default value for `infodir' depends indirectly on `prefix'; `infodir' is normally changed only through `prefix'. The default value for `infodir' is `$(prefix)/info'. `docdir' A directory for any documentation that is in a format other than those used by `info' or `man'. The default value for `docdir' depends indirectly on `prefix'; `docdir' is normally changed only through `prefix'. The default value for `docdir' is `$(datadir)/doc'. *This variable is an extension to the GNU coding standards*. (See also *Note Extensions to the GNU coding standards: Makefile extensions.) `includedir' A directory for the header files accompanying the libraries installed in `libdir'. The default value for `includedir' depends on `prefix'; `includedir' is normally changed only indirectly through `prefix'. The default value for `includedir' is `$(prefix)/include'.  File: configure.info, Node: Host, Next: Target, Prev: Install locations, Up: Using configure Host ==== The arguments to `configure' are "hosttypes". By "hosttype" we mean the "environment" in which the source will be compiled. This need not necessarily be the same as the physical machine involved, although it usually is. For example, if some obscure machine had the GNU `POSIX' emulation libraries available, it would be possible to configure most GNU source for a `POSIX' system and build it on the obscure host. For more on this topic, see *Note On Configuring Development Tools: (cfg-paper)Host Environments.  File: configure.info, Node: Target, Next: Makefile fragments, Prev: Host, Up: Using configure Target ====== For building native development tools, or most of the other GNU tools, you need not worry about the target. The "target" of a configuration defaults to the same as the "host". For building cross development tools, please see *Note On Configuring Development Tools: (cfg-paper)Building Development Environments.