I've started working on a new AC_C_BOOL. I still need to do a bunch of testing (and write regression tests) but how does this look for the documentation? Note in particular that I agree with Paul that we should be able to get away with including <stdbool.h> from config.h as long as we're careful not to include it at all from C++. The code in the @smallexample is basically what I would AH_VERBATIM into config.h.
Question for the peanut gallery: do we need to worry about Objective-C here? The problem scenario I foresee is when the C compiler implements C2x but the Objective-C compiler doesn't. With GCC this could only happen as a result of version skew between cc1 and cc1obj, and I don't mind telling people not to do that, but maybe if someone's using GCC for C but Apple's compilers for Objective-C. (Obviously AC_C_BOOL cannot AC_REQUIRE([AC_PROG_OBJC]), so if this is a concern we should add AC_OBJC_BOOL as well, but then we have to make their config.h logic play nice with each other, which may involve adding features to autoheader.) I _presume_ Objective-C++ inherits 'bool' and '__cplusplus' from C++, so it should be covered already.
zw
@anchor{AC_C_BOOL}
@defmac AC_C_BOOL (@ovar{if-required})
@cvindex C_HAVE_BOOLEAN_TYPE
@cvindex C_NEED_STDBOOL_H
@cvindex C_TYPE_FOR_BOOL
@cvindex HAVE_BOOLEAN_TYPE
@cvindex HAVE__BOOL
@cvindex HAVE_STDBOOL_H
@cvindex _Bool
@cvindex bool
@hdrindex{stdbool.h}
@caindex c_boolean_type
@caindex header_stdbool_h
@caindex type__bool
Ensure that @code{false} and @code{true} are usable as integer constants
that are equal to 0 and 1, respectively. If possible, also arrange for
@code{bool} to be a type name for a @dfn{true Boolean type}, i.e.@: a
type that can @emph{only} take on the values 0 and 1. Any nonzero
value, when converted to such a type, becomes 1.
When it is not possible for @code{bool} to be a true Boolean type, the
behavior depends on the argument @var{if-required}. If it is the word
@code{required}, @command{configure} will fail the build when a true
Boolean type is not available. If it is the word @code{optional},
@command{configure} will arrange to make @code{bool} a synonym for
@code{int}, and it will define the macro @code{HAVE_BOOLEAN_TYPE} with
value 1 if @code{bool} is a true Boolean type, or 0 if it is not.
In this release, omitting @var{if-required} is the same as setting it to
@code{optional}. In future releases we may change this so it behaves
the same as @code{required} instead.
This macro requires the configure script to be in @samp{AC_LANG([C])}
mode.
Programs using @code{AC_C_BOOL} and a @file{config.h.in} generated by
@command{autoheader} can use @code{bool}, @code{false}, @code{true}, and
@code{HAVE_BOOLEAN_TYPE} immediately after including @code{config.h}; no
other ceremony is required. In particular, if it is necessary to
include @file{stdbool.h}, @file{config.h} will do this for you.
Programs that do not use @file{config.h}, or do not use
@command{autoheader}, however, will need to reimplement a bit of
preprocessor logic which handles the possibility that @file{config.h} is
being included from C++@. The @emph{actual} result macros defined by
@code{AC_C_BOOL} are
@table @code
@item C_HAVE_BOOLEAN_TYPE
Always defined; has value 1 if the C compiler supplies a true Boolean
type, or 0 if it does not.
@item C_NEED_STDBOOL_H
Defined with value 1 if @file{stdbool.h} should be included; undefined
if it should not be included.
@item C_TYPE_FOR_BOOL
If it is necessary to define @code{bool} by hand, this macro is defined
and provides the appropriate definition.
@end table
These are intended to be used with preprocessor logic similar to:
@smallexample
#include "config.h"
#ifdef __cplusplus
/* 'bool', 'false', and 'true' are always available in C++. */
#define HAVE_BOOLEAN_TYPE 1
#else
# define HAVE_BOOLEAN_TYPE C_HAVE_BOOLEAN_TYPE
# if defined C_NEED_STDBOOL_H
# include <stdbool.h>
# elif defined C_BOOL_DEFINITION
# define bool C_BOOL_DEFINITION
# define false 0
# define true 1
# else
/* This C compiler makes 'bool', 'false', and 'true' available
automatically (as required by ISO C 2023 and later). */
# endif
#endif
@end smallexample
Of course, the C++-related logic can be omitted in programs that do not
use C++, and @code{HAVE_BOOLEAN_TYPE} need not be defined if you do not
have any use for it.
>From within an Autoconf script, the result of @code{AC_C_BOOL} is
available in the cache variable @code{ac_cv_c_boolean_type},
which currently can have one of the following values:
@table @samp
@item bool
The C compiler makes @code{bool}, @code{false}, and @code{true}
available automatically.
@item bool (stdbool.h)
Including @file{stdbool.h} makes @code{bool}, @code{false}, and
@code{true} available.
@item _Bool
@file{stdbool.h} either does not exist or does not work; however,
the type name @code{_Bool} is accepted and works correctly.
@item no
A true Boolean type is not available.
@end table
Other possibilities may be added in the future.
@strong{Portability Note:} C++ has always included a true Boolean type
under the name @code{bool}, and keyword constants @code{false} and
@code{true}. However, prior to the 1999 revision of the C standard, C
did not include a true Boolean type at all. This is why the
@samp{HAVE_BOOLEAN_TYPE == 0} case exists. The only programs that need
to worry about this case are those that still intend to be portable to
ISO C 1989 and/or pre-standardization (``K&R'') environments.
We encourage maintainers of programs that already require C 1999
or later to use @samp{AC_C_BOOL([required])}.
C 1999 added a true Boolean type, but its built-in name was
@code{_Bool}, not @code{bool}; programs wishing to use @code{bool},
@code{false}, and @code{true} needed to include @file{stdbool.h} to opt
into the new keywords. Unfortunately, compilers do exist that implement
@code{_Bool} but not @file{stdbool.h}.
@c Revise this sentence after C2x is officially published. -zw 2022-08-19
C 2023 is expected to make @code{bool}, @code{false}, and @code{true}
available by default and to deprecate @code{_Bool} and @file{stdbool.h}.
This brings C in line with the way C++ has always worked.
Since C 2023 is expected to deprecate @code{_Bool}, portable programs
need to avoid it---always use @code{bool}, with the appropriate
conditionals for when C 1999 or 2011 compilers are in use. Portable
programs should also avoid using the macro @code{__bool_true_false_are_defined},
and should avoid including @file{stdbool.h} from C++@.
@strong{Autoconf Compatibility Note:} @code{AC_C_BOOL} is new in
Autoconf 2.72. It replaces two older macros, @code{AC_HEADER_STDBOOL}
and @code{AC_CHECK_HEADER_STDBOOL}, both of which were designed at a
time when it seemed unthinkable that the C committee would ever add
@code{bool}, @code{false}, and @code{true} as keywords, or, having added
@code{_Bool}, deprecate it again. As such, the way they work is quite
different.
@command{autoupdate} will replace either of these macros with
@code{AC_C_BOOL} plus in-line code that sets the same result variables
and macros as the old macros did. You should delete this in-line code
(and the @code{m4_warn} message reminding you to do so). Then, check
over @file{configure.ac} and third-party M4 macros for code depending on
the cache variables @code{ac_cv_header_stdbool_h} or
@code{ac_cv_type__bool}; any such code is probably no longer necessary.
Also search your C code for any direct uses of @code{_Bool}, which
should be changed to @code{bool}, and for logic depending on the result
macros @code{HAVE_STDBOOL_H} or @code{HAVE__BOOL}, which can probably be
removed. As described above, if you are using a @file{config.h}
generated by @command{autoheader}, all the work is done in there.
If you are using the Gnulib @samp{stdbool} package (@pxref{Gnulib}) you
should not need it any more either.
@end defmac
@c ...
@node Obsolete Macros
@defmac AC_CHECK_HEADER_STDBOOL
@acindex{CHECK_HEADER_STDBOOL}
Replaced by @code{AC_C_BOOL} (@pxref{AC_C_BOOL}).
@end defmac
@defmac AC_HEADER_STDBOOL
@acindex{HEADER_STDBOOL}
Replaced by @code{AC_C_BOOL} (@pxref{AC_C_BOOL}).
@end defmac
