11. Manual Configuration

A few kinds of features can't be guessed automatically by running test programs. For example, the details of the object-file format, or special options that need to be passed to the compiler or linker. You can check for such features using ad-hoc means, such as having configure check the output of the uname program, or looking for libraries that are unique to particular systems. However, Autoconf provides a uniform method for handling unguessable features.

11.1 Specifying the System Type

Like other GNU configure scripts, Autoconf-generated configure scripts can make decisions based on a canonical name for the system type, which has the form: `cpu-vendor-os', where os can be `system' or `kernel-system'

configure can usually guess the canonical name for the type of system it's running on. To do so it runs a script called config.guess, which infers the name using the uname command or symbols predefined by the C preprocessor.

Alternately, the user can specify the system type with command line arguments to configure. Doing so is necessary when cross-compiling. In the most complex case of cross-compiling, three system types are involved. The options to specify them are:

` --build=build-type '

the type of system on which the package is being configured and compiled. It defaults to the result of running config.guess.

` --host=host-type '

the type of system on which the package will run. By default it is the same as the build machine. Specifying it enables the cross-compilation mode.

` --target=target-type '

the type of system for which any compiler tools in the package will produce code (rarely needed). By default, it is the same as host.

If you mean to override the result of config.guess, use `--build', not `--host', since the latter enables cross-compilation. For historical reasons, passing `--host' also changes the build type. Therefore, whenever you specify --host, be sure to specify --build too. This will be fixed in the future.

./configure --build=i686-pc-linux-gnu --host=m68k-coff

will enter cross-compilation mode, but configure will fail if it can't run the code generated by the specified compiler if you configure as follows:

./configure CC=m68k-coff-gcc

configure recognizes short aliases for many system types; for example, `decstation' can be used instead of `mips-dec-ultrix4.2'. configure runs a script called config.sub to canonicalize system type aliases.

This section deliberately omits the description of the obsolete interface; see Hosts and Cross-Compilation.

11.2 Getting the Canonical System Type

The following macros make the system type available to configure scripts.

The variables `build_alias', `host_alias', and `target_alias' are always exactly the arguments of `--build', `--host', and `--target'; in particular, they are left empty if the user did not use them, even if the corresponding AC_CANONICAL macro was run. Any configure script may use these variables anywhere. These are the variables that should be used when in interaction with the user.

If you need to recognize some special environments based on their system type, run the following macros to get canonical system names. These variables are not set before the macro call.

If you use these macros, you must distribute config.guess and config.sub along with your source code. See section Outputting Files, for information about the AC_CONFIG_AUX_DIR macro which you can use to control in which directory configure looks for those scripts.

Macro: AC_CANONICAL_BUILD

Compute the canonical build-system type variable, build, and its three individual parts build_cpu, build_vendor, and build_os.

If `--build' was specified, then build is the canonicalization of build_alias by config.sub, otherwise it is determined by the shell script config.guess.

Macro: AC_CANONICAL_HOST

Compute the canonical host-system type variable, host, and its three individual parts host_cpu, host_vendor, and host_os.

If `--host' was specified, then host is the canonicalization of host_alias by config.sub, otherwise it defaults to build.

Macro: AC_CANONICAL_TARGET

Compute the canonical target-system type variable, target, and its three individual parts target_cpu, target_vendor, and target_os.

If `--target' was specified, then target is the canonicalization of target_alias by config.sub, otherwise it defaults to host.

Note that there can be artifacts due to the backward compatibility code. See See section Hosts and Cross-Compilation, for more.

11.3 Using the System Type

How do you use a canonical system type? Usually, you use it in one or more case statements in `configure.ac' to select system-specific C files. Then, using AC_CONFIG_LINKS, link those files which have names based on the system name, to generic names, such as `host.h' or `target.c' (see section Creating Configuration Links). The case statement patterns can use shell wild cards to group several cases together, like in this fragment:

case $target in
i386-*-mach* | i386-*-gnu*)
             obj_format=aout emulation=mach bfd_gas=yes ;;
i960-*-bout) obj_format=bout ;;
esac

and later in `configure.ac', use:

AC_CONFIG_LINKS(host.h:config/$machine.h
                object.h:config/$obj_format.h)

Note that the above example uses $target because it's taken from a tool which can be built on some architecture ($build), run on another ($host), but yet handle data for a third architecture ($target). Such tools are usually part of a compiler suite, they generate code for a specific $target.

However $target should be meaningless for most packages. If you want to base a decision on the system where your program will be run, make sure you use the $host variable, as in the following excerpt:

case $host in
  *-*-msdos* | *-*-go32* | *-*-mingw32* | *-*-cygwin* | *-*-windows*)
    MUMBLE_INIT="mumble.ini"
    ;;
  *)
    MUMBLE_INIT=".mumbleinit"
    ;;
esac
AC_SUBST([MUMBLE_INIT])

You can also use the host system type to find cross-compilation tools. See section Generic Program and File Checks, for information about the AC_CHECK_TOOL macro which does that.

This document was generated by John Paul Wallington on October, 29 2003 using texi2html 1.67.