Re: bool and C23

[Zack Weinberg]

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