@set EDITION 1.6
@set VERSION 1.6
-@set UPDATED August 1993
+@set UPDATED September 1993
@iftex
@finalout
* VPATH Substitutions:: Compiling in a different directory.
* Automatic Remaking:: Makefile rules for configuring.
+Running @code{configure} Scripts
+
+* Overriding variables:: Workarounds for unusual systems.
+* Running config.status:: Recreating a configuration.
+
An Example
* Sample configure.in:: An example of a @file{configure} template.
@item
optionally, a C header file, the name of which is configurable,
-containing @code{#define} statements;
+containing @code{#define} statements (@pxref{Setup});
@item
a shell script called @file{config.status} that, when run, will recreate
-the current configuration parameter settings.
+the current configuration parameter settings
+(@pxref{Running config.status}).
@end itemize
To create a @code{configure} script with Autoconf, you need to write an
@defmac AC_FIND_X
@maindex FIND_X
-Try to locate the X Window System include files and libraries by running
-@code{xmkmf} on a trivial @file{Imakefile} and examining the
-@file{Makefile} that it produces. If successful, set the shell
-variables @code{x_includes} and @code{x_libraries} to their locations;
-otherwise (such as if @code{xmkmf} is not present), do nothing.
+Try to locate the X Window System include files and libraries. Try
+first by running @code{xmkmf} on a trivial @file{Imakefile} and
+examining the @file{Makefile} that it produces. If that fails (such as
+if @code{xmkmf} is not present), look for them in several directories
+where they often reside. If either method is successful, set the shell
+variables @code{x_includes} and @code{x_libraries} to their locations,
+unless they are in directories the compiler searches by default. If
+both methods fail, set the shell variable @code{no_x} to @samp{true};
+otherwise set it to the empty string.
@end defmac
@defmac AC_HAVE_POUNDBANG (@var{action-if-supported} @r{[}, @var{action-if-unsupported}@r{]})
@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{})
@maindex CONFIG_HEADER
@vindex HAVE_CONFIG_H
-Make @code{AC_OUTPUT} create one or more files @var{header-to-create}
-containing C preprocessor @code{#define} statements and replace
-@samp{@@DEFS@@} in generated files with @samp{-DHAVE_CONFIG_H} instead
-of the value of @code{DEFS}. @xref{Setup}, for more information on
-@code{AC_OUTPUT}. This macro should be called right after
-@code{AC_INIT}. The usual name for @var{header-to-create} is
-@file{config.h}.
+Make @code{AC_OUTPUT} create the file(s) in the
+whitespace-separated list @var{header-to-create} containing C
+preprocessor @code{#define} statements and replace @samp{@@DEFS@@} in
+generated files with @samp{-DHAVE_CONFIG_H} instead of the value of
+@code{DEFS}. @xref{Setup}, for more information on @code{AC_OUTPUT}.
+This macro should be called right after @code{AC_INIT}. The usual name
+for @var{header-to-create} is @file{config.h}.
If @var{header-to-create} already exists and its contents are identical
to what @code{AC_OUTPUT} would put in it, it is left alone. Doing this
@node Running configure Scripts, Example, Makefiles, Top
@chapter Running @code{configure} Scripts
-A software package that uses a @code{configure} script generated by
-Autoconf should be distributed with a file @file{Makefile.in}, but no
+A software package that uses a @code{configure} script
+should be distributed with a file @file{Makefile.in}, but no
@file{Makefile}; that way, the user has to properly configure the
-package for the local system before compiling it. Normally, configuring
-consists of simply doing a @code{cd} to the package's source code
-directory and typing:
-
-@example
-configure
-@end example
-
-If the @code{PATH} environment variable does not contain the directory
-@samp{.}, the command is instead:
-
-@example
-./configure
-@end example
+package for the local system before compiling it.
+Here is how to configure a package that uses a @code{configure} script.
-Users running @code{csh} on old versions of System V might have to
-explicitly run @code{sh} on @code{configure}:
-
-@example
-sh configure
-@end example
+Normally, you just @code{cd} to the directory containing the package's
+source code and type @samp{./configure}. If you're using @code{csh} on
+an old version of System V, you might need to type @samp{sh configure}
+instead to prevent @code{csh} from trying to execute @code{configure}
+itself.
Running @code{configure} takes a minute or two. While it is running, it
prints some messages that tell what it is doing. If you don't want to
the source code, you must use a version of @code{make} that supports the
@code{VPATH} variable, such as GNU @code{make}. @code{cd} to the
directory where you want the object files and executables to go and run
-@code{configure}. @code{configure} automatically checks for the source
-code in the directory that @code{configure} is in and in @file{..}. If
-for some reason @code{configure} is not in the source code directory
-that you are configuring, then it will report that it can't find the
-source code. In that case, run @code{configure} with the option
-@samp{--srcdir=@var{dir}}, where @var{dir} is the directory that
+the @code{configure} script. @code{configure} automatically checks for
+the source code in the directory that @code{configure} is in and in
+@file{..}. If for some reason @code{configure} is not in the source
+code directory that you are configuring, then it will report that it
+can't find the source code. In that case, run @code{configure} with the
+option @samp{--srcdir=@var{dir}}, where @var{dir} is the directory that
contains the source code.
By default, @samp{make install} will install the package's files in
@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can specify an
installation prefix other than @file{/usr/local} by giving
@code{configure} the option @samp{--prefix=@var{path}}. Alternately,
-you can do so by giving a value for the @samp{prefix} variable when you
-run @code{make}, e.g.,
+you can do so by consistently giving a value for the @samp{prefix}
+variable when you run @code{make}, e.g.,
@example
make prefix=/usr/gnu
+make prefix=/usr/gnu install
@end example
-You can specify separate installation prefixes for machine-specific
-files and machine-independent files. If you give @code{configure} the
-option @samp{--exec-prefix=@var{path}} or set the @code{make} variable
-@samp{exec_prefix} to @var{path}, the package will use @var{path} as the
-prefix for installing programs and libraries. Normally, all files are
-installed using the same prefix.
-
-Another @code{configure} option is useful mainly in @file{Makefile}
-rules for updating @file{config.status} and @file{Makefile}. The
-@samp{--no-create} option figures out the configuration for your system
-and records it in @file{config.status}, without actually configuring the
-package (creating @file{Makefile}s and perhaps a configuration header
-file). Later, you can run @file{./config.status} to actually configure
-the package. You can also give @file{config.status} the
-@samp{--recheck} option, which makes it re-run @code{configure} with the
-same arguments you used before. This option is useful if you change
-@code{configure}.
+You can specify separate installation prefixes for architecture-specific
+files and architecture-independent files. If you give @code{configure}
+the option @samp{--exec-prefix=@var{path}} or set the @code{make}
+variable @samp{exec_prefix} to @var{path}, the package will use
+@var{path} as the prefix for installing programs and libraries. Data
+files and documentation will still use the regular prefix. Normally,
+all files are installed using the same prefix.
Some packages pay attention to @samp{--with-@var{package}} options to
-@code{configure}, where @var{package} is something like @samp{gnu-libc}
-or @samp{x} (for X windows). The README should mention any
+@code{configure}, where @var{package} is something like @samp{gnu-as} or
+@samp{x} (for the X Window System). The README should mention any
@samp{--with-} options that the package recognizes.
@code{configure} ignores any other arguments that you give it.
+@menu
+* Overriding variables:: Workarounds for unusual systems.
+* Running config.status:: Recreating a configuration.
+@end menu
+
+@node Overriding variables, Running config.status, , Running configure Scripts
+@section Overriding variables
+
On systems that require unusual options for compilation or linking that
the package's @code{configure} script does not know about, you can give
@code{configure} initial values for variables by setting them in the
CC='gcc -traditional' LIBS=-lposix ./configure
@end example
-The @code{make} variables that you might want to override with
-environment variables when running @code{configure} are:
+Here are the @code{make} variables that you might want to override with
+environment variables when running @code{configure}.
For these variables, any value given in the environment overrides the
value that @code{configure} would choose:
@defvar CC
-C compiler program. The default is @code{cc}, or @code{gcc} if
-@code{gcc} is in your @code{PATH}.
+C compiler program. The default is @code{cc}.
@end defvar
@defvar INSTALL
@defvar DEFS
Configuration options, in the form @samp{-Dfoo -Dbar@dots{}}. Do not
-use this variable in packages that use @code{AC_CONFIG_HEADER}.
+use this variable in packages that create a configuration header file.
@end defvar
@defvar LIBS
Libraries to link with, in the form @samp{-lfoo -lbar@dots{}}.
@end defvar
-Of course, in the long term, most problems requiring manual intervention
-should be fixed by updating either the Autoconf macros or the
-@file{configure.in} file for that package. @xref{Making configure
-Scripts}, for a discussion of that subject.
+In the long term, most problems requiring manual intervention should be
+fixed by updating either the Autoconf macros or the @file{configure.in}
+file for that package. @xref{Making configure Scripts}, for a
+discussion of that subject.
+
+@node Running config.status, , Overriding variables, Running configure Scripts
+@section Recreating a Configuration
+
+The @code{configure} script creates a file named @file{config.status}
+which describes which configuration options were specified when the
+package was last configured. This file is a shell script which,
+if run, will recreate the same configuration.
+
+You can give @file{config.status} the @samp{--recheck} option, which
+makes it re-run @code{configure} with the same arguments you used
+before. This option is useful if you change @code{configure}, so that
+the results of some tests might be different from the previous run.
+
+@file{config.status} checks several optional environment variables that
+can alter its behavior:
+
+@defvar CONFIG_SHELL
+The shell with which to run @code{configure} for the @samp{--recheck}
+option. The default is @file{/bin/sh}.
+@end defvar
+
+The following two variables provide one way for separately distributed
+packages to share the values computed by @code{configure}. Doing so can
+be useful if some of the packages need a superset of the features that
+one of them, perhaps a common library, does. These variables allow a
+@file{config.status} file to create files other than the ones that its
+@file{configure.in} specifies, so it can be used for a different package.
+
+@defvar CONFIG_FILES
+The files in which to perform @samp{@@@var{variable}@@} substitutions.
+The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}.
+@end defvar
+
+@defvar CONFIG_HEADERS
+The files in which to substitute C @code{#define} statements.
+The default is the arguments given to @code{AC_CONFIG_HEADER}; if that
+macro was not called, @file{config.status} ignores this variable.
+@end defvar
@node Example, Preprocessor Symbol Index, Running configure Scripts, Top
@chapter An Example
@set EDITION 1.6
@set VERSION 1.6
-@set UPDATED August 1993
+@set UPDATED September 1993
@iftex
@finalout
* VPATH Substitutions:: Compiling in a different directory.
* Automatic Remaking:: Makefile rules for configuring.
+Running @code{configure} Scripts
+
+* Overriding variables:: Workarounds for unusual systems.
+* Running config.status:: Recreating a configuration.
+
An Example
* Sample configure.in:: An example of a @file{configure} template.
@item
optionally, a C header file, the name of which is configurable,
-containing @code{#define} statements;
+containing @code{#define} statements (@pxref{Setup});
@item
a shell script called @file{config.status} that, when run, will recreate
-the current configuration parameter settings.
+the current configuration parameter settings
+(@pxref{Running config.status}).
@end itemize
To create a @code{configure} script with Autoconf, you need to write an
@defmac AC_FIND_X
@maindex FIND_X
-Try to locate the X Window System include files and libraries by running
-@code{xmkmf} on a trivial @file{Imakefile} and examining the
-@file{Makefile} that it produces. If successful, set the shell
-variables @code{x_includes} and @code{x_libraries} to their locations;
-otherwise (such as if @code{xmkmf} is not present), do nothing.
+Try to locate the X Window System include files and libraries. Try
+first by running @code{xmkmf} on a trivial @file{Imakefile} and
+examining the @file{Makefile} that it produces. If that fails (such as
+if @code{xmkmf} is not present), look for them in several directories
+where they often reside. If either method is successful, set the shell
+variables @code{x_includes} and @code{x_libraries} to their locations,
+unless they are in directories the compiler searches by default. If
+both methods fail, set the shell variable @code{no_x} to @samp{true};
+otherwise set it to the empty string.
@end defmac
@defmac AC_HAVE_POUNDBANG (@var{action-if-supported} @r{[}, @var{action-if-unsupported}@r{]})
@defmac AC_CONFIG_HEADER (@var{header-to-create} @dots{})
@maindex CONFIG_HEADER
@vindex HAVE_CONFIG_H
-Make @code{AC_OUTPUT} create one or more files @var{header-to-create}
-containing C preprocessor @code{#define} statements and replace
-@samp{@@DEFS@@} in generated files with @samp{-DHAVE_CONFIG_H} instead
-of the value of @code{DEFS}. @xref{Setup}, for more information on
-@code{AC_OUTPUT}. This macro should be called right after
-@code{AC_INIT}. The usual name for @var{header-to-create} is
-@file{config.h}.
+Make @code{AC_OUTPUT} create the file(s) in the
+whitespace-separated list @var{header-to-create} containing C
+preprocessor @code{#define} statements and replace @samp{@@DEFS@@} in
+generated files with @samp{-DHAVE_CONFIG_H} instead of the value of
+@code{DEFS}. @xref{Setup}, for more information on @code{AC_OUTPUT}.
+This macro should be called right after @code{AC_INIT}. The usual name
+for @var{header-to-create} is @file{config.h}.
If @var{header-to-create} already exists and its contents are identical
to what @code{AC_OUTPUT} would put in it, it is left alone. Doing this
@node Running configure Scripts, Example, Makefiles, Top
@chapter Running @code{configure} Scripts
-A software package that uses a @code{configure} script generated by
-Autoconf should be distributed with a file @file{Makefile.in}, but no
+A software package that uses a @code{configure} script
+should be distributed with a file @file{Makefile.in}, but no
@file{Makefile}; that way, the user has to properly configure the
-package for the local system before compiling it. Normally, configuring
-consists of simply doing a @code{cd} to the package's source code
-directory and typing:
-
-@example
-configure
-@end example
-
-If the @code{PATH} environment variable does not contain the directory
-@samp{.}, the command is instead:
-
-@example
-./configure
-@end example
+package for the local system before compiling it.
+Here is how to configure a package that uses a @code{configure} script.
-Users running @code{csh} on old versions of System V might have to
-explicitly run @code{sh} on @code{configure}:
-
-@example
-sh configure
-@end example
+Normally, you just @code{cd} to the directory containing the package's
+source code and type @samp{./configure}. If you're using @code{csh} on
+an old version of System V, you might need to type @samp{sh configure}
+instead to prevent @code{csh} from trying to execute @code{configure}
+itself.
Running @code{configure} takes a minute or two. While it is running, it
prints some messages that tell what it is doing. If you don't want to
the source code, you must use a version of @code{make} that supports the
@code{VPATH} variable, such as GNU @code{make}. @code{cd} to the
directory where you want the object files and executables to go and run
-@code{configure}. @code{configure} automatically checks for the source
-code in the directory that @code{configure} is in and in @file{..}. If
-for some reason @code{configure} is not in the source code directory
-that you are configuring, then it will report that it can't find the
-source code. In that case, run @code{configure} with the option
-@samp{--srcdir=@var{dir}}, where @var{dir} is the directory that
+the @code{configure} script. @code{configure} automatically checks for
+the source code in the directory that @code{configure} is in and in
+@file{..}. If for some reason @code{configure} is not in the source
+code directory that you are configuring, then it will report that it
+can't find the source code. In that case, run @code{configure} with the
+option @samp{--srcdir=@var{dir}}, where @var{dir} is the directory that
contains the source code.
By default, @samp{make install} will install the package's files in
@file{/usr/local/bin}, @file{/usr/local/man}, etc. You can specify an
installation prefix other than @file{/usr/local} by giving
@code{configure} the option @samp{--prefix=@var{path}}. Alternately,
-you can do so by giving a value for the @samp{prefix} variable when you
-run @code{make}, e.g.,
+you can do so by consistently giving a value for the @samp{prefix}
+variable when you run @code{make}, e.g.,
@example
make prefix=/usr/gnu
+make prefix=/usr/gnu install
@end example
-You can specify separate installation prefixes for machine-specific
-files and machine-independent files. If you give @code{configure} the
-option @samp{--exec-prefix=@var{path}} or set the @code{make} variable
-@samp{exec_prefix} to @var{path}, the package will use @var{path} as the
-prefix for installing programs and libraries. Normally, all files are
-installed using the same prefix.
-
-Another @code{configure} option is useful mainly in @file{Makefile}
-rules for updating @file{config.status} and @file{Makefile}. The
-@samp{--no-create} option figures out the configuration for your system
-and records it in @file{config.status}, without actually configuring the
-package (creating @file{Makefile}s and perhaps a configuration header
-file). Later, you can run @file{./config.status} to actually configure
-the package. You can also give @file{config.status} the
-@samp{--recheck} option, which makes it re-run @code{configure} with the
-same arguments you used before. This option is useful if you change
-@code{configure}.
+You can specify separate installation prefixes for architecture-specific
+files and architecture-independent files. If you give @code{configure}
+the option @samp{--exec-prefix=@var{path}} or set the @code{make}
+variable @samp{exec_prefix} to @var{path}, the package will use
+@var{path} as the prefix for installing programs and libraries. Data
+files and documentation will still use the regular prefix. Normally,
+all files are installed using the same prefix.
Some packages pay attention to @samp{--with-@var{package}} options to
-@code{configure}, where @var{package} is something like @samp{gnu-libc}
-or @samp{x} (for X windows). The README should mention any
+@code{configure}, where @var{package} is something like @samp{gnu-as} or
+@samp{x} (for the X Window System). The README should mention any
@samp{--with-} options that the package recognizes.
@code{configure} ignores any other arguments that you give it.
+@menu
+* Overriding variables:: Workarounds for unusual systems.
+* Running config.status:: Recreating a configuration.
+@end menu
+
+@node Overriding variables, Running config.status, , Running configure Scripts
+@section Overriding variables
+
On systems that require unusual options for compilation or linking that
the package's @code{configure} script does not know about, you can give
@code{configure} initial values for variables by setting them in the
CC='gcc -traditional' LIBS=-lposix ./configure
@end example
-The @code{make} variables that you might want to override with
-environment variables when running @code{configure} are:
+Here are the @code{make} variables that you might want to override with
+environment variables when running @code{configure}.
For these variables, any value given in the environment overrides the
value that @code{configure} would choose:
@defvar CC
-C compiler program. The default is @code{cc}, or @code{gcc} if
-@code{gcc} is in your @code{PATH}.
+C compiler program. The default is @code{cc}.
@end defvar
@defvar INSTALL
@defvar DEFS
Configuration options, in the form @samp{-Dfoo -Dbar@dots{}}. Do not
-use this variable in packages that use @code{AC_CONFIG_HEADER}.
+use this variable in packages that create a configuration header file.
@end defvar
@defvar LIBS
Libraries to link with, in the form @samp{-lfoo -lbar@dots{}}.
@end defvar
-Of course, in the long term, most problems requiring manual intervention
-should be fixed by updating either the Autoconf macros or the
-@file{configure.in} file for that package. @xref{Making configure
-Scripts}, for a discussion of that subject.
+In the long term, most problems requiring manual intervention should be
+fixed by updating either the Autoconf macros or the @file{configure.in}
+file for that package. @xref{Making configure Scripts}, for a
+discussion of that subject.
+
+@node Running config.status, , Overriding variables, Running configure Scripts
+@section Recreating a Configuration
+
+The @code{configure} script creates a file named @file{config.status}
+which describes which configuration options were specified when the
+package was last configured. This file is a shell script which,
+if run, will recreate the same configuration.
+
+You can give @file{config.status} the @samp{--recheck} option, which
+makes it re-run @code{configure} with the same arguments you used
+before. This option is useful if you change @code{configure}, so that
+the results of some tests might be different from the previous run.
+
+@file{config.status} checks several optional environment variables that
+can alter its behavior:
+
+@defvar CONFIG_SHELL
+The shell with which to run @code{configure} for the @samp{--recheck}
+option. The default is @file{/bin/sh}.
+@end defvar
+
+The following two variables provide one way for separately distributed
+packages to share the values computed by @code{configure}. Doing so can
+be useful if some of the packages need a superset of the features that
+one of them, perhaps a common library, does. These variables allow a
+@file{config.status} file to create files other than the ones that its
+@file{configure.in} specifies, so it can be used for a different package.
+
+@defvar CONFIG_FILES
+The files in which to perform @samp{@@@var{variable}@@} substitutions.
+The default is the arguments given to @code{AC_OUTPUT} in @file{configure.in}.
+@end defvar
+
+@defvar CONFIG_HEADERS
+The files in which to substitute C @code{#define} statements.
+The default is the arguments given to @code{AC_CONFIG_HEADER}; if that
+macro was not called, @file{config.status} ignores this variable.
+@end defvar
@node Example, Preprocessor Symbol Index, Running configure Scripts, Top
@chapter An Example
projects / thirdparty / autoconf.git / commitdiff
