diff --git a/autoconf.texi b/autoconf.texi index 97a80641..0fe22555 100644 --- a/autoconf.texi +++ b/autoconf.texi @@ -8,7 +8,7 @@ @set EDITION 1.6 @set VERSION 1.6 -@set UPDATED August 1993 +@set UPDATED September 1993 @iftex @finalout @@ -150,6 +150,11 @@ Makefiles * 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. @@ -264,11 +269,12 @@ package), from template @file{Makefile.in} files (@pxref{Makefiles}); @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 @@ -1113,11 +1119,15 @@ The following macros check for operating system services: @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{]}) @@ -1250,13 +1260,13 @@ The following macros control the kind of output that Autoconf produces. @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 @@ -2225,30 +2235,17 @@ config.h.in: configure.in @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: +package for the local system before compiling it. +Here is how to configure a package that uses a @code{configure} script. -@example -configure -@end example - -If the @code{PATH} environment variable does not contain the directory -@samp{.}, the command is instead: - -@example -./configure -@end example - -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 @@ -2259,49 +2256,48 @@ To compile the package in a different directory from the one containing 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 @@ -2312,15 +2308,14 @@ command line like this: 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 @@ -2333,17 +2328,56 @@ the value that @code{configure} chooses: @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 diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 97a80641..0fe22555 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -8,7 +8,7 @@ @set EDITION 1.6 @set VERSION 1.6 -@set UPDATED August 1993 +@set UPDATED September 1993 @iftex @finalout @@ -150,6 +150,11 @@ Makefiles * 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. @@ -264,11 +269,12 @@ package), from template @file{Makefile.in} files (@pxref{Makefiles}); @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 @@ -1113,11 +1119,15 @@ The following macros check for operating system services: @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{]}) @@ -1250,13 +1260,13 @@ The following macros control the kind of output that Autoconf produces. @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 @@ -2225,30 +2235,17 @@ config.h.in: configure.in @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: +package for the local system before compiling it. +Here is how to configure a package that uses a @code{configure} script. -@example -configure -@end example - -If the @code{PATH} environment variable does not contain the directory -@samp{.}, the command is instead: - -@example -./configure -@end example - -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 @@ -2259,49 +2256,48 @@ To compile the package in a different directory from the one containing 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 @@ -2312,15 +2308,14 @@ command line like this: 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 @@ -2333,17 +2328,56 @@ the value that @code{configure} chooses: @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