diff options
author | Zack Weinberg <zackw@panix.com> | 2020-12-07 11:53:06 -0500 |
---|---|---|
committer | Zack Weinberg <zackw@panix.com> | 2020-12-07 11:53:06 -0500 |
commit | 6cf0eff684320d447a91d624f50192cdf3e9a2c1 (patch) | |
tree | 888c4a77cf1989bd285c13b3902b298df2e3a9a3 | |
parent | d132ea0278f574fbb3c8d433ea094e36ece73ba1 (diff) | |
download | autoconf-6cf0eff684320d447a91d624f50192cdf3e9a2c1.tar.gz |
Revise documentation of AC_PROG_CC and comments on conformance checks.
Makes the documentation of AC_PROG_CC consistent with the
documentation of AC_PROG_CXX. Also removes a bunch of redundant text
from c.m4 and adds lists of the headers that *can* be used in the
conformance tests, so future hackers don’t have to look them up.
* doc/autoconf.texi (AC_PROG_CC): Make description consistent with
description of AC_PROG_CXX.
* lib/autoconf/c.m4: Clean up some outdated or repetitive commentary
and add lists of the freestanding headers above the code that needs
to avoid using non-freestanding headers.
-rw-r--r-- | doc/autoconf.texi | 110 | ||||
-rw-r--r-- | lib/autoconf/c.m4 | 87 |
2 files changed, 97 insertions, 100 deletions
diff --git a/doc/autoconf.texi b/doc/autoconf.texi index cdd056c5..264ec29a 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -7466,51 +7466,67 @@ makes this invalid. That is why Autoconf stopped issuing @ovindex CC @ovindex CFLAGS @caindex prog_cc_stdc -Determine a C compiler to use. If @code{CC} is not already set in the -environment, check for @code{gcc} and @code{cc}, then for other C -compilers. Set output variable @code{CC} to the name of the compiler -found. +Determine a C compiler to use. -This macro may, however, be invoked with an optional first argument -which, if specified, must be a blank-separated list of C compilers to -search for. This just gives the user an opportunity to specify an -alternative search list for the C compiler. For example, if you didn't -like the default order, then you could invoke @code{AC_PROG_CC} like -this: +If the environment variable @code{CC} is set, its value will be taken as +the name of the C compiler to use. Otherwise, search for a C compiler +under a series of likely names, trying @code{gcc} and @code{cc} first. +Regardless, the output variable @code{CC} is set to the chosen compiler. + +If the optional first argument to the macro is used, it must be a +whitespace-separated list of potential names for a C compiler, +which overrides the built-in list. + +If no C compiler can be found, @command{configure} will error out. + +If the selected C compiler is found to be GNU C (regardless of +its name), the shell variable @code{GCC} will be set to @samp{yes}. +If the shell variable @code{CFLAGS} was not already set, it is set +to @option{-g -O2} for the GNU C compiler (@option{-O2} on systems +where GCC does not accept @option{-g}), or @option{-g} for other +compilers. @code{CFLAGS} is then made an output variable. +You can override the default for @code{CFLAGS} by inserting a shell +default assignment between @code{AC_INIT} and @code{AC_PROG_CC}: @example -AC_PROG_CC([gcc cl cc]) -@end example - -If necessary, add an option to output variable @code{CC} to enable -support for ISO Standard C features with extensions. Prefer the newest -C standard that is supported. Currently the newest standard is ISO C11, -with ISO C99 and ANSI C89 (ISO C90) being the older versions. -After calling this macro you can check whether the C compiler has been -set to accept Standard C; if not, the shell variable -@code{ac_cv_prog_cc_stdc} is set to @samp{no}. - -When attempting to add compiler options, prefer extended functionality -to strict conformance: the goal is to enable whatever standard features -that are available, not to check for full conformance to the standard or -to prohibit incompatible extensions. Test for C11 support by checking -for @code{_Alignas}, @code{_Alignof}, @code{_Noreturn}, -@code{_Static_assert}, UTF-8 string literals, duplicate @code{typedef}s, -and anonymous structures and unions. Test for C99 support by checking -for @code{_Bool}, @code{//} comments, flexible array members, -@code{inline}, signed and unsigned @code{long long int}, mixed code and -declarations, named initialization of structs, @code{restrict}, -@code{va_copy}, varargs macros, variable declarations in @code{for} -loops, and variable length arrays. Test for C89 support by checking for -function prototypes. - -If using a compiler that supports GNU C, set shell variable @code{GCC} to -@samp{yes}. If output variable @code{CFLAGS} was not already set, set -it to @option{-g -O2} for a GNU C compiler (@option{-O2} on systems -where the compiler does not accept @option{-g}), or @option{-g} for -other compilers. If your package does not like this default, then it is -acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT} -and before @code{AC_PROG_CC} to select an empty default instead. +: $@{CFLAGS="@var{options}"@} +@end example + +where @var{options} are the appropriate set of options to use by +default. (It is important to use this construct rather than a normal +assignment, so that @code{CFLAGS} can still be overridden by the +person building the package. @xref{Preset Output Variables}.) + +If necessary, options are added to @code{CC} to enable support for ISO +Standard C features with extensions, preferring the newest C standard +that is supported. Currently the newest standard Autoconf knows how to +detect support for is ISO C 2011. After calling this macro you can +check whether the C compiler has been set to accept Standard C by +inspecting cache variables. If @code{ac_cv_prog_cc_c11} is set to any +value other than @samp{no} (including the empty string), then @code{CC} +can compile code as standard C 2011, and this mode has been enabled. +Otherwise, if @code{ac_cv_prog_cc_c99} is set to any value other than +@samp{no} (including the empty string), then @code{CC} can compile code +as standard C 1999, and this mode has been enabled. Otherwise, if +@code{ac_cv_prog_cc_c89} is set to any value other than @samp{no} +(including the empty string), then @code{CC} can compile code as +standard C 1989, and this mode has been enabled. Finally, if all +three variables are set to @samp{no}, then @code{CC} cannot compile +standard C at all. + +The tests for standard conformance are not comprehensive. They test the +values of @code{__STDC__} and @code{__STDC_VERSION__}, and a +representative sample of the language features added in each version of +the C standard. They do not test the C standard library, because the C +compiler might be generating code for a ``freestanding environment'' +(in which most of the standard library is optional). If you need to know +whether a particular C standard header exists, use @code{AC_CHECK_HEADER}. + +None of the options that may be added to @code{CC} by this macro +enable @emph{strict} conformance to the C standard. In particular, +system-specific extensions are not disabled. (For example, for GNU C, +the @option{-std=gnu@var{nn}} options may be used, but not the +@option{-std=c@var{nn}} options.) Many Autoconf macros use a compiler, and thus call @samp{AC_REQUIRE([AC_PROG_CC])} to ensure that the compiler has been @@ -7900,10 +7916,12 @@ been enabled. Finally, if both variables are set to @samp{no}, then The tests for standard conformance are not comprehensive. They test the value of @code{__cplusplus} and a representative sample of the -language features added in each version of the C++ standard. They do -not exercise the C++ standard library, because this can be extremely -slow. If you need to know whether a particular C++ standard header -exists, use @code{AC_CHECK_HEADER}. +language features added in each version of the C++ standard. They +do not test the C++ standard library, because this can be extremely +slow, and because the C++ compiler might be generating code for a +``freestanding environment'' (in which most of the C++ standard library +is optional). If you need to know whether a particular C++ standard +header exists, use @code{AC_CHECK_HEADER}. None of the options that may be added to @code{CXX} by this macro enable @emph{strict} conformance to the C++ standard. In particular, diff --git a/lib/autoconf/c.m4 b/lib/autoconf/c.m4 index 7984f25f..fe217cad 100644 --- a/lib/autoconf/c.m4 +++ b/lib/autoconf/c.m4 @@ -1123,13 +1123,6 @@ fi[]dnl # because putting single quotes into a single-quoted shell string is # awkward (you must write '\'' for each ' you want in the program). # -# Warning: each test program may only use the headers required to -# exist in the relevant standard's *freestanding* environment. -# For instance, <stdio.h> may not be available. However, these -# programs are only compiled and not linked, so it is ok to declare -# external functions and then call them without worrying about whether -# they actually exist. -# # Warning: to avoid incorrect answers due to unused-variable warnings # and/or overly aggressive optimizers, each variable (global or not) # in these programs should be used, and each function should be @@ -1138,6 +1131,22 @@ fi[]dnl # convenient non-compile-time-constant values to pass around. In main, # there is an int variable 'ok' which will eventually become the return # value; use `ok |= ...' to consume the results of operations. +# +# Warning: each test program may only use the headers required to +# exist in the relevant standard's *freestanding* environment, in case +# the C compiler targets such an environment. (Therefore, almost no +# features of the C89/C99/C11 standard *library* are probed. Use +# AC_CHECK_HEADER, AC_CHECK_FUNC, etc. for that.) However, these +# programs are only compiled and not linked, so it is ok to declare +# external functions and then call them without worrying about whether +# they actually exist. +# +# The C89 freestanding headers are: +# <float.h> <limits.h> <stdarg.h> <stddef.h> +# C99 adds: +# <iso646.h> <stdbool.h> <stdint.h> +# C11 adds: +# <stdalign.h> <stdnoreturn.h> AC_DEFUN([_AC_C_C89_TEST_GLOBALS], [m4_divert_text([INIT_PREPARE], @@ -1527,13 +1536,7 @@ AS_IF([test "x$ac_cv_prog_cc_$1" != xno], [$4], [$5]) # _AC_PROG_CC_C89 ([ACTION-IF-AVAILABLE], [ACTION-IF-UNAVAILABLE]) # ---------------------------------------------------------------- # If the C compiler is not in ANSI C89 (ISO C90) mode by default, try -# to add an option to output variable CC to make it so. This macro -# tries various options that select ANSI C89 on some system or -# another. It considers the compiler to be in ANSI C89 mode if it -# handles function prototypes correctly. -# Note: the test program may only depend on the headers required to -# exist in C89 *freestanding* environments (e.g. stdio.h may not be -# available). +# to add an option to output variable CC to make it so. AC_DEFUN([_AC_PROG_CC_C89], [AC_REQUIRE([_AC_C_C89_TEST_PROGRAM])]dnl [_AC_C_STD_TRY([c89], [ac_c_conftest_c89_program], @@ -1553,13 +1556,7 @@ dnl SVR4 -Xc -D__EXTENSIONS__ # _AC_PROG_CC_C99 ([ACTION-IF-AVAILABLE], [ACTION-IF-UNAVAILABLE]) # ---------------------------------------------------------------- # If the C compiler is not in ISO C99 mode by default, try to add an -# option to output variable CC to make it so. This macro tries -# various options that select ISO C99 on some system or another. It -# considers the compiler to be in ISO C99 mode if it handles _Bool, -# // comments, flexible array members, inline, long long int, mixed -# code and declarations, named initialization of structs, restrict, -# va_copy, varargs macros, variable declarations in for loops and -# variable length arrays. +# option to output variable CC to make it so. AC_DEFUN([_AC_PROG_CC_C99], [AC_REQUIRE([_AC_C_C99_TEST_PROGRAM])]dnl [_AC_C_STD_TRY([c99], [ac_c_conftest_c89_program], @@ -1591,16 +1588,7 @@ dnl with extended modes being tried first. # _AC_PROG_CC_C11 ([ACTION-IF-AVAILABLE], [ACTION-IF-UNAVAILABLE]) # ---------------------------------------------------------------- # If the C compiler is not in ISO C11 mode by default, try to add an -# option to output variable CC to make it so. This macro tries -# various options that select ISO C11 on some system or another. It -# considers the compiler to be in ISO C11 mode if it handles _Alignas, -# _Alignof, _Noreturn, _Static_assert, UTF-8 string literals, -# duplicate typedefs, and anonymous structures and unions. -# Note: the test program may only depend on the headers required to -# exist in C11 *freestanding* environments (e.g. stdio.h may not be -# available). However, it may safely declare and refer to -# hosted-environment functions itself, as the test program will only -# be compiled, not linked. +# option to output variable CC to make it so. AC_DEFUN([_AC_PROG_CC_C11], [AC_REQUIRE([_AC_C_C11_TEST_PROGRAM])]dnl [_AC_C_STD_TRY([c11], [ac_c_conftest_c11_program], @@ -2393,7 +2381,16 @@ fi]) # See the long comment at the beginning of section 4a for rationale # for these macros, and constraints on how the test programs should # be written. - +# +# The C++98 freestanding headers are: +# <cstdarg> <cstddef> <cstdlib> <exception> <limits> <new> <typeinfo> +# C++11 adds: +# <atomic> <cfloat> <ciso646> <climits> <cstdalign> <cstdbool> +# <cstdint> <initializer_list> <type_traits> +# +# No other headers can safely be included. Therefore, almost no C++ +# standard library features are tested for. Use AC_CHECK_HEADER, etc. +# if you need that. AC_DEFUN([_AC_CXX_CXX98_TEST_GLOBALS], [m4_divert_text([INIT_PREPARE], @@ -2404,8 +2401,8 @@ ac_cxx_conftest_cxx98_globals=' # error "Compiler does not advertise C++98 conformance" #endif -// These inclusions are cheap compared to including any STL header, but will -// reliably reject old compilers that lack the unsuffixed header files. +// These inclusions are to reject old compilers that +// lack the unsuffixed header files. #include <cstdlib> #include <exception> @@ -2677,14 +2674,7 @@ AS_IF([test "x$ac_cv_prog_cxx_$1" != xno], [$4], [$5]) # _AC_PROG_CXX_CXX98 ([ACTION-IF-AVAILABLE], [ACTION-IF-UNAVAILABLE]) # ------------------------------------------------------------------- # If the C++ compiler is not in ISO C++98 mode by default, try to add -# an option to output variable CXX to make it so. This macro tries -# various options that select ISO C++98 on some system or another. -# It considers the compiler to be in ISO C++98 mode if it defines -# the __cplusplus macro appropriately and it supports language -# features that were added since "C++ 2.0" (namespaces, exceptions, -# and templates). It does not check for the presence of any STL -# headers, as this was found to make AC_PROG_CXX unacceptably slow. -# Use AC_CHECK_HEADER if you need that. +# an option to output variable CXX to make it so. AC_DEFUN([_AC_PROG_CXX_CXX98], [AC_REQUIRE([_AC_CXX_CXX98_TEST_PROGRAM])]dnl [_AC_CXX_STD_TRY([cxx98], [ac_cxx_conftest_cxx98_program], @@ -2702,18 +2692,7 @@ dnl with extended modes being tried first. # _AC_PROG_CXX_CXX11 ([ACTION-IF-AVAILABLE], [ACTION-IF-UNAVAILABLE]) # ------------------------------------------------------------------- # If the C++ compiler is not in ISO CXX11 mode by default, try to add -# an option to output variable CXX to make it so. This macro tries -# various options that select ISO C++11 on some system or another. -# It considers the compiler to be in ISO C++11 mode if it defines the -# __cplusplus macro appropriately, can compile all of the code from -# the C++98 test, and can also handle many of the new language -# features in C++11 (auto, constexpr, decltype, default/deleted -# constructors, delegate constructors, final, initializer lists, -# lambda functions, nullptr, override, range-based for loops, template -# brackets without spaces, variadic templates, trailing return types, -# unicode literals). It does not check for the presence of the new -# library headers; again, this was found to make AC_PROG_CXX -# unacceptably slow. Use AC_CHECK_HEADER if you need that. +# an option to output variable CXX to make it so. AC_DEFUN([_AC_PROG_CXX_CXX11], [AC_REQUIRE([_AC_CXX_CXX11_TEST_PROGRAM])]dnl [_AC_CXX_STD_TRY([cxx11], [ac_cxx_conftest_cxx11_program], |