mirror/autoconf
2
0
Fork 0
mirror of git://git.sv.gnu.org/autoconf synced 2025-02-11 13:51:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

Revise documentation of AC_PROG_CC and comments on conformance checks.

Browse Source 
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.
This commit is contained in:
Zack Weinberg 2020-12-07 11:53:06 -05:00
parent d132ea0278
commit 6cf0eff684
No known key found for this signature in database
GPG Key ID: 384F8E68AC65B0D5
2 changed files with 93 additions and 96 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

102
doc/autoconf.texi
View File

@ -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])
: $@{CFLAGS="@var{options}"@}
@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}.
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}.)
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 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.
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.
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,

87
lib/autoconf/c.m4
View File

@ -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],