From: Akim Demaille Date: Tue, 8 Feb 2000 13:42:51 +0000 (+0000) Subject: Let the doc catch up. X-Git-Tag: autoconf-2.50~1197 X-Git-Url: http://git.ipfire.org/gitweb/?a=commitdiff_plain;h=11eaab70bdb467616228674aad27be8bf9b4fb36;p=thirdparty%2Fautoconf.git Let the doc catch up. * doc/autoconf.texi (Common Behavior): New section, to document the common behavior of the macros. (Standard Symbols): New subsection. Describes the transformation of the AC_DEFINEd names. (Default Includes): New subsection. Obvious content. All the ``callers'' updated. --- diff --git a/ChangeLog b/ChangeLog index 8de163394..3977d3a20 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,14 @@ +2000-02-08 Akim Demaille + + Let the doc catch up. + + * doc/autoconf.texi (Common Behavior): New section, to document + the common behavior of the macros. + (Standard Symbols): New subsection. Describes the transformation + of the AC_DEFINEd names. + (Default Includes): New subsection. Obvious content. + All the ``callers'' updated. + 2000-02-08 Akim Demaille * acgeneral.m4 (AC_OUTPUT_HEADERS): Don't use `break' to exit the diff --git a/acgeneral.m4 b/acgeneral.m4 index 3428b834f..1ad7014c8 100644 --- a/acgeneral.m4 +++ b/acgeneral.m4 @@ -508,6 +508,7 @@ ac_arg_enable_help= ac_arg_var_help= ac_default_prefix=/usr/local # Factorizing default headers for most tests. +dnl If ever you change this variable, please keep autoconf.texi in sync. ac_includes_default="\ #include #include diff --git a/autoconf.texi b/autoconf.texi index 85c7839b1..82be088c6 100644 --- a/autoconf.texi +++ b/autoconf.texi @@ -175,6 +175,7 @@ Configuration Header Files Existing Tests +* Common Behavior:: Macros' standard schemes * Alternative Programs:: Selecting between alternative programs * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -187,6 +188,11 @@ Existing Tests * System Services:: Operating system services * UNIX Variants:: Special kludges for specific UNIX variants +Common Behavior + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + Alternative Programs * Particular Programs:: Special handling to find certain programs @@ -1579,6 +1585,7 @@ preprocessor symbol @var{name} to the value 1''. @xref{Defining Symbols}, for how to get those symbol definitions into your program. @menu +* Common Behavior:: Macros' standard schemes * Alternative Programs:: Selecting between alternative programs * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -1592,7 +1599,99 @@ Symbols}, for how to get those symbol definitions into your program. * UNIX Variants:: Special kludges for specific UNIX variants @end menu -@node Alternative Programs, Libraries, Existing Tests, Existing Tests +@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests +@section Common Behavior + +Much effort is developed in Autoconf to make it easy to learn. The most +obvious means to reach this goal is simply to enforce standard and +rigorous schemes, and to avoid as much as possible exceptions. Because +of history and momentum, there are still too many exceptions in +Autoconf, nevertheless this section describes some of the common rules. + +@menu +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros +@end menu + +@node Standard Symbols, Default Includes, Common Behavior, Common Behavior +@subsection Standard Symbols + +All the generic macros which @code{AC_DEFINE} a symbol as a result of +their test transform their @var{argument}s to a standard alphabet. +First @var{argument} is mapped to upper case and any star @samp{*} to +@samp{P}. Any characters that remains which is not alpha-numerical or +underscore is mapped to an underscore. + +For instance + +@example +AC_CHECK_TYPES((struct $Expensive*)) +@end example + +@noindent +may define the symbol @samp{HAVE_STRUCT__EXPENSIVEP}. + + +@node Default Includes, , Standard Symbols, Common Behavior +@subsection Default Includes +@cindex Includes, default + +Several tests depend upon a set of headers. Since headers are not +universally available, you actually have to provide a set of protected +includes, such as + +@example +@group +#if TIME_WITH_SYS_TIME +# include +# include +#else +# if HAVE_SYS_TIME_H +# include +# else +# include +# endif +#endif +@end group +@end example + +@noindent +Unless you know exactly what you are doing, you should avoid to use +unconditional includes, and check the existence of the headers you +include beforehand (@pxref{Header Files}). + +Most generic macros provide the following default set of includes: + +@example +@group +#include +#include +#if STDC_HEADERS +# include +# include +#else +# if HAVE_STDLIB_H +# include +# endif +#endif +#if HAVE_STRING_H +# if !STDC_HEADERS && HAVE_MEMORY_H +# include +# endif +# include +#else +# if HAVE_STRINGS_H +# include +# endif +#endif +#if HAVE_UNISTD_H +# include +#endif +@end group +@end example + + +@node Alternative Programs, Libraries, Common Behavior, Existing Tests @section Alternative Programs @cindex Programs, checking @@ -2663,8 +2762,8 @@ test macros. If the declaration of @var{symbol} (a function or a variable) is needed because it is not declared in @var{includes}, run the shell commands @var{action-if-not-found}, otherwise @var{action-if-found}. If no -@var{includes} are given at all, FIXME: point to a node defining the -standard include. +@var{includes} are specified, the default includes are used +(@pxref{Default Includes}). This macro actually tests whether it is valid to use @var{symbol} as an r-value, not if it is really declared, because it is much safer to avoid @@ -2793,7 +2892,8 @@ particular test macros. @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) @maindex CHECK_MEMBER Check whether @var{member} is a member of the aggregate @var{aggregate}. -FIXME: Default @var{includes} are provided. +If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). @example AC_CHECK_MEMBER(struct passwd.pw_gecos,, [AC_FATAL([We need `struct passwd.pw_gecos'!])], @@ -2901,13 +3001,13 @@ test macros. @defmac AC_CHECK_TYPES ((@var{type}, @dots{}), @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) @maindex CHECK_TYPES -For each given @var{type} that is defined by the FIXME: @var{includes}, -define @code{HAVE_@var{type}} (in all capitals). If -@var{action-if-found} is given, it is additional shell code to execute -when one of the header files is found. You can give it a value of -@samp{break} to break out of the loop on the first match. If -@var{action-if-not-found} is given, it is executed when one of the -header files is not found. +For each defined @var{type} define @code{HAVE_@var{type}} (in all +capitals). If no @var{includes} are specified, the default includes are +used (@pxref{Default Includes}). If @var{action-if-found} is given, it +is additional shell code to execute when one of the header files is +found. You can give it a value of @samp{break} to break out of the loop +on the first match. If @var{action-if-not-found} is given, it is +executed when one of the header files is not found. This macro uses m4 lists: @example @@ -2925,9 +3025,10 @@ to incompatible code in the case of pointer types. @defmac AC_CHECK_TYPE (@var{type}, @var{default}, @ovar{includes}) @maindex CHECK_TYPE -If the type @var{type} is not defined in FIXME: @ovar{includes}, define -it to be the C (or C++) builtin type @var{default}; e.g., @samp{short} -or @samp{unsigned}. +If the type @var{type} is not defined, define it to be the C (or C++) +builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}. If +no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). This macro has a broken design. First, although it is a member of the @code{CHECK} clan, singular subfamily, it does more than just checking. @@ -3071,9 +3172,9 @@ size_t my_strlen PARAMS ((const char *)); Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or C++) type @var{type} (e.g. @samp{int}, @samp{char *} etc.). If @samp{type} is unknown, it gets a size of 0. If no @var{includes} are -provided, the default headers are used (FIXME: point to the right -node). If you provide default header, make sure to include -@file{stdio.h} which is required for this macro to run. +specified, the default includes are used (@pxref{Default Includes}). If +you provide @var{include}, make sure to include @file{stdio.h} which is +required for this macro to run. @var{uctype} is @var{type}, with lowercase converted to uppercase, spaces changed to underscores, and asterisks changed to @samp{P}. If diff --git a/doc/autoconf.texi b/doc/autoconf.texi index 85c7839b1..82be088c6 100644 --- a/doc/autoconf.texi +++ b/doc/autoconf.texi @@ -175,6 +175,7 @@ Configuration Header Files Existing Tests +* Common Behavior:: Macros' standard schemes * Alternative Programs:: Selecting between alternative programs * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -187,6 +188,11 @@ Existing Tests * System Services:: Operating system services * UNIX Variants:: Special kludges for specific UNIX variants +Common Behavior + +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros + Alternative Programs * Particular Programs:: Special handling to find certain programs @@ -1579,6 +1585,7 @@ preprocessor symbol @var{name} to the value 1''. @xref{Defining Symbols}, for how to get those symbol definitions into your program. @menu +* Common Behavior:: Macros' standard schemes * Alternative Programs:: Selecting between alternative programs * Libraries:: Library archives that might be missing * Library Functions:: C library functions that might be missing @@ -1592,7 +1599,99 @@ Symbols}, for how to get those symbol definitions into your program. * UNIX Variants:: Special kludges for specific UNIX variants @end menu -@node Alternative Programs, Libraries, Existing Tests, Existing Tests +@node Common Behavior, Alternative Programs, Existing Tests, Existing Tests +@section Common Behavior + +Much effort is developed in Autoconf to make it easy to learn. The most +obvious means to reach this goal is simply to enforce standard and +rigorous schemes, and to avoid as much as possible exceptions. Because +of history and momentum, there are still too many exceptions in +Autoconf, nevertheless this section describes some of the common rules. + +@menu +* Standard Symbols:: Symbols defined by the macros +* Default Includes:: Includes used by the generic macros +@end menu + +@node Standard Symbols, Default Includes, Common Behavior, Common Behavior +@subsection Standard Symbols + +All the generic macros which @code{AC_DEFINE} a symbol as a result of +their test transform their @var{argument}s to a standard alphabet. +First @var{argument} is mapped to upper case and any star @samp{*} to +@samp{P}. Any characters that remains which is not alpha-numerical or +underscore is mapped to an underscore. + +For instance + +@example +AC_CHECK_TYPES((struct $Expensive*)) +@end example + +@noindent +may define the symbol @samp{HAVE_STRUCT__EXPENSIVEP}. + + +@node Default Includes, , Standard Symbols, Common Behavior +@subsection Default Includes +@cindex Includes, default + +Several tests depend upon a set of headers. Since headers are not +universally available, you actually have to provide a set of protected +includes, such as + +@example +@group +#if TIME_WITH_SYS_TIME +# include +# include +#else +# if HAVE_SYS_TIME_H +# include +# else +# include +# endif +#endif +@end group +@end example + +@noindent +Unless you know exactly what you are doing, you should avoid to use +unconditional includes, and check the existence of the headers you +include beforehand (@pxref{Header Files}). + +Most generic macros provide the following default set of includes: + +@example +@group +#include +#include +#if STDC_HEADERS +# include +# include +#else +# if HAVE_STDLIB_H +# include +# endif +#endif +#if HAVE_STRING_H +# if !STDC_HEADERS && HAVE_MEMORY_H +# include +# endif +# include +#else +# if HAVE_STRINGS_H +# include +# endif +#endif +#if HAVE_UNISTD_H +# include +#endif +@end group +@end example + + +@node Alternative Programs, Libraries, Common Behavior, Existing Tests @section Alternative Programs @cindex Programs, checking @@ -2663,8 +2762,8 @@ test macros. If the declaration of @var{symbol} (a function or a variable) is needed because it is not declared in @var{includes}, run the shell commands @var{action-if-not-found}, otherwise @var{action-if-found}. If no -@var{includes} are given at all, FIXME: point to a node defining the -standard include. +@var{includes} are specified, the default includes are used +(@pxref{Default Includes}). This macro actually tests whether it is valid to use @var{symbol} as an r-value, not if it is really declared, because it is much safer to avoid @@ -2793,7 +2892,8 @@ particular test macros. @defmac AC_CHECK_MEMBER (@var{aggregate}.@var{member}, @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) @maindex CHECK_MEMBER Check whether @var{member} is a member of the aggregate @var{aggregate}. -FIXME: Default @var{includes} are provided. +If no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). @example AC_CHECK_MEMBER(struct passwd.pw_gecos,, [AC_FATAL([We need `struct passwd.pw_gecos'!])], @@ -2901,13 +3001,13 @@ test macros. @defmac AC_CHECK_TYPES ((@var{type}, @dots{}), @ovar{action-if-found}, @ovar{action-if-not-found}, @ovar{includes}) @maindex CHECK_TYPES -For each given @var{type} that is defined by the FIXME: @var{includes}, -define @code{HAVE_@var{type}} (in all capitals). If -@var{action-if-found} is given, it is additional shell code to execute -when one of the header files is found. You can give it a value of -@samp{break} to break out of the loop on the first match. If -@var{action-if-not-found} is given, it is executed when one of the -header files is not found. +For each defined @var{type} define @code{HAVE_@var{type}} (in all +capitals). If no @var{includes} are specified, the default includes are +used (@pxref{Default Includes}). If @var{action-if-found} is given, it +is additional shell code to execute when one of the header files is +found. You can give it a value of @samp{break} to break out of the loop +on the first match. If @var{action-if-not-found} is given, it is +executed when one of the header files is not found. This macro uses m4 lists: @example @@ -2925,9 +3025,10 @@ to incompatible code in the case of pointer types. @defmac AC_CHECK_TYPE (@var{type}, @var{default}, @ovar{includes}) @maindex CHECK_TYPE -If the type @var{type} is not defined in FIXME: @ovar{includes}, define -it to be the C (or C++) builtin type @var{default}; e.g., @samp{short} -or @samp{unsigned}. +If the type @var{type} is not defined, define it to be the C (or C++) +builtin type @var{default}; e.g., @samp{short} or @samp{unsigned}. If +no @var{includes} are specified, the default includes are used +(@pxref{Default Includes}). This macro has a broken design. First, although it is a member of the @code{CHECK} clan, singular subfamily, it does more than just checking. @@ -3071,9 +3172,9 @@ size_t my_strlen PARAMS ((const char *)); Define @code{SIZEOF_@var{uctype}} to be the size in bytes of the C (or C++) type @var{type} (e.g. @samp{int}, @samp{char *} etc.). If @samp{type} is unknown, it gets a size of 0. If no @var{includes} are -provided, the default headers are used (FIXME: point to the right -node). If you provide default header, make sure to include -@file{stdio.h} which is required for this macro to run. +specified, the default includes are used (@pxref{Default Includes}). If +you provide @var{include}, make sure to include @file{stdio.h} which is +required for this macro to run. @var{uctype} is @var{type}, with lowercase converted to uppercase, spaces changed to underscores, and asterisks changed to @samp{P}. If diff --git a/lib/autoconf/general.m4 b/lib/autoconf/general.m4 index 3428b834f..1ad7014c8 100644 --- a/lib/autoconf/general.m4 +++ b/lib/autoconf/general.m4 @@ -508,6 +508,7 @@ ac_arg_enable_help= ac_arg_var_help= ac_default_prefix=/usr/local # Factorizing default headers for most tests. +dnl If ever you change this variable, please keep autoconf.texi in sync. ac_includes_default="\ #include #include