SYNOPSIS

configure [-d] [-f makefile] [-o configfile] [-t] [--enable=OPT…​][--build] [path-option…​] [--help] [var=val…​]

DESCRIPTION

This program reads magic comments in a Makefile, performs the tests they require, and generates a config.mk that carries Makefile variables configuring a project build. In projects using this convention, each Makefile contains an include of config.mk from its top-level directory.

Optionally, configure can be told to create a config.h (the same convention historically used by autotools) with the #defines moved to that. This may be necessary if you have a large enough number of configuration switches to make your compilation logs confusing. Note, however that there is a maintainance advantage to haing only one communication path from your configurator; this is preferable if you have few enough configuration switches.

The intent is that the base Makefile is stable and not modified for build configuration. All such modifications belong in config.mk, which is a volatile product of configure and should not be committed to the project repository. The Makefile can, and should, contain default settings for all configuration variables so the build can proceed with no config.mk.

Lines in such a config.mk are in Makefile syntax; they typically consist of modifications to CFLAGS and LDFLAGS variables, or their analog for whatever language your project is using. They may also set Makefile variables. These may be used to enable or disable features and to link optional libraries.

CHECK DIRECTIVES

The magic comments in the Makefile inform configure what tests it should perform. Tests may include interrogation of properties of the host environment or of options passed to configure at invocation time.

It is expected that projects using this tool will carry a copy in the top level of their source directory. It replaces the generated configure scripts in autotools build recipes.

The set of check directives deliberately resembles those found in configure.ac files from autotools builds in order to make transition easier, but is much smaller as we assume a POSIX-conformant execution environment including a POSIX-conformant shell and tools.

Each of the check directives below takes a comma-separated list of arguments. Generally speaking the result from each argument generates one or more -D options to be appended to CFLAGS if the feature is found. LDFLAGS may also be appended to. To get the macro name, non-alphamerics in the feature name are mapped to "_", then the result is upppercased.

Most of these tests may take any number of arguments that are include-file names; these are detected by the presence of ".h" in the argument name and are included in the test compilation source. Normally one compilation attempt is performed for each instance of these tests.

Some special arguments are placed as #defines before the file inclusions. Any argument led with an underscore and ending with "SOURCE" is treated this way - including in particular _DEFAULT_SOURCE, _GNU_SOURCE, _BSD_SOURCE, _NETBSD_SOURCE, _OPENBSD_SOURCE, and _XOPEN_SOURCE. Any text after one of these is pasted as the remainder of the #define line.

CHECK_HAVE(feature…​)

Sets HAVE_ macros. Checks for each specified include file, function, global variable, struct, union, or typedef (types are distinguished by having a t suffix). Compiler intrinsic types and functions can be tested for this way. For each one found, CHECK_HAVE will set a -DHAVE${feature} option for each feature/.

CHECK_DECL(feature…​)

Like CHECK_HAVE, but tests whether feature names that don’t look like include files are defined as macros when all headers are included. For include files this will be -DHAVE_${feature}; for macros it will be -DHAVE_DECL_${feature}.

CHECK_LIB(lib, func…​)

Test whether a library exists and provides the specified function(s). Appends an option to CFLAGS that looks like -DHAVE_LIB${lib}; appends an option to LDFLAGS that looks like -llib. Accepts any number of include-header arguments.

CHECK_MEMBERS(name.member…​)

Check whether, given all includes in the argument list, each other non-include argument exists as a declared member of the specified struct or union; if so, it generates a -DHAVE_STRUCT_${name}_{member} or -DHAVE_UNION_${name}_{member}.

CHECK_ENABLE(name, description)

If configure was called with --enable=name, generate a -DENABLE_{name} symbol. The second argument becomes the explanation for the option; it can be string-quoted to include spaces. (This test doesn’t do a compilation check.)

CHECK_PROGRAM(names…​)

Check that each name is that of an excutable on your $PATH. If it is, set a macro -DHAVE_PROGRAM_$(name). (This test doesn’t do a compilation check.)

CHECK_WORDS_BIGENDIAN

Sets -DWORDS_BIGENDIAN if the machine has big-endian ints.

CHECK_CONFIG(filename)

This sets the name of the file where you want the configuration switches to be written as #defines. To emulate autotools behavior, say "CHECK_CONFIG(config.h)". (This test doesn’t do a compilation check.)

CHECK_SCRIPT(arguments)

Expect each argument to be the filename of a Python script to be exceuted. The script may append name-value pair tuples to a global named "report"; a name beginning with a -D or -U will be interpreted as an option to be appended to CFLAGS, anything else will be treated as a name=value make variable setting. These settings will be appended to the makefile snippet and/or config.h-style include file generated by configure.

The keyword REQUIRED following a check directive on the same line denotes a hard requirement. If none of the specified symbols are defined, configure exits with an error message identifying the problem and returns status 1.

It is safe to test for the same feature or header multiple times, only one option definition will be generated.

Here are some example test specifications for flavor:

# CHECK_ENABLE(ipv6)
# CHECK_DECL(sys/socket.h, netinet/in.h, netinet/tcp.h, TCP_KEEPCNT)
# CHECK_DECL(sys/socket.h, netinet/in.h, netinet/tcp.h, TCP_KEEPIDLE)
# CHECK_DECL(sys/socket.h, netinet/in.h, netinet/tcp.h, TCP_KEEPINTVL)
# CHECK_HAVE(getopt.h, getopt_long)
# CHECK_HAVE(_GNU_SOURCE, unistd.h, getresuid)
# CHECK_LIB(m) REQUIRED
# CHECK_LIB(nsl)
# CHECK_LIB(resolv)
# CHECK_LIB(rt)
# CHECK_HAVE(linux/if/tun.h)
# CHECK_HAVE(linux/ipv6.h)
# CHECK_HAVE(_GNU_SOURCE, string.h, memrchr)
# CHECK_HAVE(_GNU_SOURCE, unistd.h, setresuid)
# CHECK_SIZEOF(int)
# CHECK_SIZEOF(int *)
# CHECK_SIZEOF(long)
# CHECK_SIZEOF(long long)
# CHECK_SIZEOF(sys/types.h, off_t)
# CHECK_SIZEOF(pthread.h, pthread_t)
# CHECK_SIZEOF(stddef.h, size_t)

HOST AND BUILD CONFIGURATION

Out-of-directory builds are supported. Simply move to an empty directory and run configure there with a --srcdir option pointing back to your source-code tree. The makefile will be copied in, configure will creatre a config.mk (and/or a config.h) as normal, and the Makefile will perform a VPATH build drawing prerequisites from your source tree. The source tree can be read-only.

The makefile variables "host_cpu", "build_cpu", "host_os" and "build_os" are also set in the generated config.mk.

The variable "host_cpu" is set to the return value of the Python platform_machine() value on your host. The variable "host_os" is set to the return value of the Python platform_system() value on your host.

You force build_cpu and build_os if you specify a --build option; otherwise they are set to the same values as host_cpu and host_os.

See the section on Autotools compatibility for important caveats about these variables.

OPTIONS

Options modify the behavior of this program:

-d

Bump debug verbosity level. One bump echoes directives just before they run; another displays compiler command lines; a third dumps the code snippets and compilation error messages, if any.

-f

Read directives from the specified file rather than Makefile in the current directory. An argument of "-" means read standard input.

-o

Write to the specified file rather than config.mk in the current directory. An argument of "-" means write to standard output.

-t

Test mode. Take directives on stdin, ship to stdout. More convenient than -f - -o -; also suppresses the ID header.

-u

Generate undefines as well as defines. Mainly useful for testing. If you use it for production, be aware that it can give surprising results if you test for the same feature multiple times from different include files and the last include file is not found.

--enable=OPT

Set an ENABLE_${OPT} symbol. Note that this syntax is slightly different from the historical autotools --enable options.

--srcdir=DIR

Find the sources in DIR. Use this for out-of-directory builds. Running configure in an empty directory with a --srcdir option will copy in the Makefile from the source directory, generate a local config.mk and/or config.h, then preform a build. It is not necessary to say --srcdir=.. as configure defaults to looking in the parent directory if there is no Makefile in the current directory.

--build=target

Cross-compilation: pass the specified target type as a -target option to both configuration checks and the main compile.

--help

Dump a usage message and a synopsis of local options.

The following options set the Makefile variables used in installation and uninstallation productions:

--prefix=PREFIX

install architecture-independent files in PREFIX [/usr/local]

--exec-prefix=EPREFIX

install architecture-dependent files in EPREFIX [PREFIX]

--bindir=DIR

user executables [EPREFIX/bin]

--sbindir=DIR

system admin executables [EPREFIX/sbin]

--libexecdir=DIR

program executables [EPREFIX/libexec]

--sysconfdir=DIR

read-only single-machine data [PREFIX/etc]

--sharedstatedir=DIR

modifiable architecture-independent data [PREFIX/com]

--localstatedir=DIR

modifiable single-machine data [PREFIX/var]

--libdir=DIR

object code libraries [EPREFIX/lib]

--includedir=DIR

C header files [PREFIX/include]

--oldincludedir=DIR

C header files for non-gcc [/usr/include]

--datarootdir=DIR

read-only arch.-independent data root [PREFIX/share]

--datadir=DIR

read-only architecture-independent data [DATAROOTDIR]

--infodir=DIR

info documentation [DATAROOTDIR/info]

--localedir=DIR

locale-dependent data [DATAROOTDIR/locale]

--mandir=DIR

man documentation [DATAROOTDIR/man]

--docdir=DIR

documentation root [DATAROOTDIR/doc/giflib]

--htmldir=DIR

html documentation [DOCDIR]

--dvidir=DIR

dvi documentation [DOCDIR]

--pdfdir=DIR

pdf documentation [DOCDIR]

--psdir=DIR

ps documentation [DOCDIR]

Additionally, variable-value pairs passed in the style of shell environment settings on the configure command line behave like envronment variables for the CHECK probes, and are appended to config.mk. They can be overridden by var=val settings on your make command line.

CROSS-COMPILATION

Here are some things to know when configuring for a cross-compile:

The CC environment variable can be used to override the compiler (by default "cc") used for capability and feature tests. If CXX, CFLAGS, CPPFLAGS, CXXFLAGS, or LDFLAGS are set on the configure command line, their values are appended to the compilation line used for these tests.

Most of the tests configure does are safe for cross-compilation when you pass in an an option to set the comiler’s target architecture. CHECK_WORDS_BIGENDIAN is not. CHECK_PROGRAM is also unsafe, as the availability of a binary in your host environment does not guarantee it’s also present in the target environment. CHECK_SCRIPT may be safe or unsafe depending on what kinds of custom tests it does.

AUTOTOOLS COMPATIBILITY

As configure is intended to replace autotools configure, attention has been paid to giving it a compatible scripting interface. It supports the same set of options for setting installation paths as autotools configure.

The syntax for --enable options is different. Where autotools would want "--enable-FEATURE", this configure needs "--enable=FEATURE" (equal sign rather than minus sign).

Out-of-directory builds and --srcdir work the same way they would in autotools, including the fallback to parent directory if the current directory where configure is run is empty.

The "host_cpu" variable is intended to be used like the autotools variable of the same name. It is not guaranteed to have the same range of string values as in autotools, though common values like "x86_64", "arm", and "ppc64" do match up.

The "host_os" variable is intended to be used like the autotools variable of the same name. However, the values do not in general match up, and if you rely on this variable you will need to do some manual adjustments to your build.

The autotools variables host_vendor and build_vendor are not set. The vendor part of the triple accepted by the --build option is ignored by configure (though not by the compiler).

The --build option does not interpretet aliases for well-known systems as autotools config.sub does; the argument must be an explicit machine-os-vendor triple.

The names of macro guards generated by tests in this configure follow autotools conventions.

REPORTING BUGS

Report bugs to Eric S. Raymond <esr@thyrsus.com>. The project page is at http://catb.org/~esr/autodafe

SEE ALSO

deconfig(1), makemake(1).