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.

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
+Determine a C compiler to use.
-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.
 
-This macro may, however, be invoked with an optional first argument
+If the environment variable @code{CC} is set, its value will be taken as
-which, if specified, must be a blank-separated list of C compilers to
+the name of the C compiler to use.  Otherwise, search for a C compiler
-search for.  This just gives the user an opportunity to specify an
+under a series of likely names, trying @code{gcc} and @code{cc} first.
-alternative search list for the C compiler.  For example, if you didn't
+Regardless, the output variable @code{CC} is set to the chosen compiler.
-like the default order, then you could invoke @code{AC_PROG_CC} like
+
-this:
+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])
+: $@{CFLAGS="@var{options}"@}
 @end example
 
-If necessary, add an option to output variable @code{CC} to enable
+where @var{options} are the appropriate set of options to use by
-support for ISO Standard C features with extensions.  Prefer the newest
+default.  (It is important to use this construct rather than a normal
-C standard that is supported.  Currently the newest standard is ISO C11,
+assignment, so that @code{CFLAGS} can still be overridden by the
-with ISO C99 and ANSI C89 (ISO C90) being the older versions.
+person building the package.  @xref{Preset Output Variables}.)
-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
+If necessary, options are added to @code{CC} to enable support for ISO
-to strict conformance: the goal is to enable whatever standard features
+Standard C features with extensions, preferring the newest C standard
-that are available, not to check for full conformance to the standard or
+that is supported.  Currently the newest standard Autoconf knows how to
-to prohibit incompatible extensions.  Test for C11 support by checking
+detect support for is ISO C 2011.  After calling this macro you can
-for @code{_Alignas}, @code{_Alignof}, @code{_Noreturn},
+check whether the C compiler has been set to accept Standard C by
-@code{_Static_assert}, UTF-8 string literals, duplicate @code{typedef}s,
+inspecting cache variables.  If @code{ac_cv_prog_cc_c11} is set to any
-and anonymous structures and unions.  Test for C99 support by checking
+value other than @samp{no} (including the empty string), then @code{CC}
-for @code{_Bool}, @code{//} comments, flexible array members,
+can compile code as standard C 2011, and this mode has been enabled.
-@code{inline}, signed and unsigned @code{long long int}, mixed code and
+Otherwise, if @code{ac_cv_prog_cc_c99} is set to any value other than
-declarations, named initialization of structs, @code{restrict},
+@samp{no} (including the empty string), then @code{CC} can compile code
-@code{va_copy}, varargs macros, variable declarations in @code{for}
+as standard C 1999, and this mode has been enabled.  Otherwise, if
-loops, and variable length arrays.  Test for C89 support by checking for
+@code{ac_cv_prog_cc_c89} is set to any value other than @samp{no}
-function prototypes.
+(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.
 
-If using a compiler that supports GNU C, set shell variable @code{GCC} to
+The tests for standard conformance are not comprehensive.  They test the
-@samp{yes}.  If output variable @code{CFLAGS} was not already set, set
+values of @code{__STDC__} and @code{__STDC_VERSION__}, and a
-it to @option{-g -O2} for a GNU C compiler (@option{-O2} on systems
+representative sample of the language features added in each version of
-where the compiler does not accept @option{-g}), or @option{-g} for
+the C standard.  They do not test the C standard library, because the C
-other compilers.  If your package does not like this default, then it is
+compiler might be generating code for a ``freestanding environment''
-acceptable to insert the line @samp{: $@{CFLAGS=""@}} after @code{AC_INIT}
+(in which most of the standard library is optional).  If you need to know
-and before @code{AC_PROG_CC} to select an empty default instead.
+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
+language features added in each version of the C++ standard.  They
-not exercise the C++ standard library, because this can be extremely
+do not test the C++ standard library, because this can be extremely
-slow.  If you need to know whether a particular C++ standard header
+slow, and because the C++ compiler might be generating code for a
-exists, use @code{AC_CHECK_HEADER}.
+``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,

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
+# to add an option to output variable CC to make it so.
-# 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).
 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
+# option to output variable CC to make it so.
-# 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.
 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
+# option to output variable CC to make it so.
-# 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.
 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
+// These inclusions are to reject old compilers that
-// reliably reject old compilers that lack the unsuffixed header files.
+// 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
+# an option to output variable CXX to make it so.
-# 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.
 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
+# an option to output variable CXX to make it so.
-# 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.
 AC_DEFUN([_AC_PROG_CXX_CXX11],
 [AC_REQUIRE([_AC_CXX_CXX11_TEST_PROGRAM])]dnl
 [_AC_CXX_STD_TRY([cxx11], [ac_cxx_conftest_cxx11_program],