bug-autoconf
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Lack of clarity in description of AC_CHECK_DECL(S)


From: Eric Blake
Subject: Re: Lack of clarity in description of AC_CHECK_DECL(S)
Date: Mon, 21 Jan 2008 19:49:18 +0000 (UTC)
User-agent: Loom/3.14 (http://gmane.org/)

Reuben Thomas <rrt <at> sc3d.org> writes:

> 
> In the autoconf 2.61 info manual, the syntax of AC_CHECK_DECL is given as:
> 
>   -- Macro: AC_CHECK_DECL (SYMBOL, [ACTION-IF-FOUND],
>            [ACTION-IF-NOT-FOUND], [INCLUDES = `default-includes'])
> 
> Only by searching for an example of its use did I discover that the INCLUDES 
> argument is actually some #include lines, and not, as I first thought, the 
> text:
> 
> INCLUDES = list-of-include files

I agree that an example right there would be beneficial.  So I added one, 
looking for j0() in <math.h> (required by POSIX but not C99, and <math.h> is 
not a default include).

> 
> This rather odd meta-syntax confused me (the default values for 
> ACTION-IF-FOUND &c. are not given, and the default for INCLUDES is explained 
> below anyway.

This meta-syntax is used consistently throughout the rest of the manual.  In 
short, if an argument is optional, with the empty string as its default value, 
then we omit the "= `value'" clause.  On the other hand, if the argument is 
optional, but omitting it results in default replacement text, then the macro 
definition shows what that default text is (in this case, the default text is 
the expansion of AC_INCLUDES_DEFAULTS, which is in turn documented as a series 
of include directives).

> 
> I would suggest removing "= `default-includes'" from the syntax description, 
> and adding a note to the effect that it is a list of #include directives.
> 

Here's what I'm committing instead, hopefully making it more obvious what 
format the INCLUDES argument must take, by giving better cross-references to 
those defaults:

From: Eric Blake <address@hidden>
Date: Mon, 21 Jan 2008 12:45:44 -0700
Subject: [PATCH] Improve documentation about default include directives.

* doc/autoconf.texi (Generic Headers, Generic Declarations)
(Generic Structures, Generic Types)
(Generic Compiler Characteristics): Add links to
AC_INCLUDES_DEFAULT.
Reported by Reuben Thomas.

Signed-off-by: Eric Blake <address@hidden>
---
 ChangeLog         |    9 ++++++++
 doc/autoconf.texi |   60 ++++++++++++++++++++++++++++++++++++----------------
 2 files changed, 50 insertions(+), 19 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5f70b64..d7fbdf5 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,12 @@
+2008-01-21  Eric Blake  <address@hidden>
+
+       Improve documentation about default include directives.
+       * doc/autoconf.texi (Generic Headers, Generic Declarations)
+       (Generic Structures, Generic Types)
+       (Generic Compiler Characteristics): Add links to
+       AC_INCLUDES_DEFAULT.
+       Reported by Reuben Thomas.
+
 2008-01-15  Eric Blake  <address@hidden>
 
        * lib/m4sugar/m4sugar.m4 (m4_qlen): Use fewer macros.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 3d76b3e..c71bffd 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -5700,7 +5700,7 @@ test for it (@pxref{Writing Tests}).
 
 @anchor{AC_CHECK_HEADER}
 @defmac AC_CHECK_HEADER (@var{header-file}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_HEADER}
 If the system header file @var{header-file} is compilable, execute shell
 commands @var{action-if-found}, otherwise execute
@@ -5708,6 +5708,10 @@ commands @var{action-if-found}, otherwise execute
 header file is available, consider using @code{AC_CHECK_HEADERS}
 instead.
 
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the header under test.
+
 For compatibility issues with older versions of Autoconf, please read
 below.
 @end defmac
@@ -5715,7 +5719,7 @@ below.
 @anchor{AC_CHECK_HEADERS}
 @defmac AC_CHECK_HEADERS (@address@hidden, @
   @ovar{action-if-found}, @ovar{action-if-not-found}, @
-  @dvar{includes, default-includes})
+  @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_HEADERS}
 @cvindex address@hidden
 For each given system header file @var{header-file} in the
@@ -5726,6 +5730,10 @@ 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.
 
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the headers under test.
+
 For compatibility issues with older versions of Autoconf, please read
 below.
 @end defmac
@@ -5796,13 +5804,14 @@ These macros are used to find declarations not covered 
by the ``particular''
 test macros.
 
 @defmac AC_CHECK_DECL (@var{symbol}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_DECL}
 If @var{symbol} (a function, variable, or constant) is not declared in
 @var{includes} and a declaration is needed, run the shell commands
address@hidden, otherwise @var{action-if-found}.  If no
address@hidden are specified, the default includes are used
-(@pxref{Default Includes}).
address@hidden, otherwise @var{action-if-found}.
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the declaration under test.
 
 This macro actually tests whether @var{symbol} is defined as a macro or
 can be used as an r-value, not whether it is really declared, because it
@@ -5812,7 +5821,7 @@ introducing extra declarations when they are not needed.
 
 @anchor{AC_CHECK_DECLS}
 @defmac AC_CHECK_DECLS (@var{symbols}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_DECLS}
 @cvindex address@hidden
 For each of the @var{symbols} (@emph{comma}-separated list), define
@@ -5822,11 +5831,16 @@ For each of the @var{symbols} (@emph{comma}-separated 
list), define
 execute when one of the function declarations is needed, otherwise
 @var{action-if-found} is executed.
 
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the declarations under test.
+
 This macro uses an M4 list as first argument:
 @example
 AC_CHECK_DECLS([strdup])
 AC_CHECK_DECLS([strlen])
 AC_CHECK_DECLS([malloc, realloc, calloc, free])
+AC_CHECK_DECLS([j0], [], [], [[#include <math.h>]])
 @end example
 
 Unlike the other @samp{AC_CHECK_*S} macros, when a @var{symbol} is not
@@ -5963,7 +5977,7 @@ These macros are used to find structure members not 
covered by the
 
 @defmac AC_CHECK_MEMBER (@address@hidden, @
   @ovar{action-if-found}, @ovar{action-if-not-found}, @
-  @dvar{includes, default-includes})
+  @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_MEMBER}
 Check whether @var{member} is a member of the aggregate @var{aggregate}.
 If no @var{includes} are specified, the default includes are used
@@ -5972,7 +5986,7 @@ If no @var{includes} are specified, the default includes 
are used
 @example
 AC_CHECK_MEMBER([struct passwd.pw_gecos], [],
                 [AC_MSG_ERROR([We need `passwd.pw_gecos'!])],
-                [#include <pwd.h>])
+                [[#include <pwd.h>]])
 @end example
 
 You can use this macro for submembers:
@@ -5984,7 +5998,7 @@ AC_CHECK_MEMBER(struct top.middle.bot)
 
 @anchor{AC_CHECK_MEMBERS}
 @defmac AC_CHECK_MEMBERS (@var{members}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_MEMBERS}
 @cvindex address@hidden@var{member}
 Check for the existence of each @address@hidden@var{member}} of
@@ -5995,6 +6009,10 @@ capitals, with spaces and dots replaced by 
underscores).  If
 members.  If @var{action-if-not-found} is given, it is executed for each
 of the members that could not be found.
 
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the members under test.
+
 This macro uses M4 lists:
 @example
 AC_CHECK_MEMBERS([struct stat.st_rdev, struct stat.st_blksize])
@@ -6279,10 +6297,12 @@ These macros are used to check for types not covered by 
the ``particular''
 test macros.
 
 @defmac AC_CHECK_TYPE (@var{type}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_TYPE}
 Check whether @var{type} is defined.  It may be a compiler builtin type
-or defined by the @var{includes} (@pxref{Default Includes}).
+or defined by the @var{includes}.  @var{includes} is a series of include
+directives, defaulting to @code{AC_INCLUDES_DEFAULT} (@pxref{Default
+Includes}), which are used prior to the type under test.
 
 In C, @var{type} must be a type-name, so that the expression @samp{sizeof
 (@var{type})} is valid (but @samp{sizeof ((@var{type}))} is not).  The
@@ -6293,7 +6313,7 @@ same test is applied when compiling for C++, which means 
that in C++
 
 
 @defmac AC_CHECK_TYPES (@var{types}, @ovar{action-if-found}, @
-  @ovar{action-if-not-found}, @dvar{includes, default-includes})
+  @ovar{action-if-not-found}, @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_TYPES}
 @cvindex address@hidden
 For each @var{type} of the @var{types} that is defined, define
@@ -6308,6 +6328,7 @@ This macro uses M4 lists:
 @example
 AC_CHECK_TYPES([ptrdiff_t])
 AC_CHECK_TYPES([unsigned long long int, uintmax_t])
+AC_CHECK_TYPES([float_t], [], [], [[#include <math.h>]])
 @end example
 
 @end defmac
@@ -6383,15 +6404,16 @@ Autoconf works around this problem by casting @code
{sizeof (int)} to
 
 @anchor{AC_CHECK_SIZEOF}
 @defmac AC_CHECK_SIZEOF (@var{type-or-expr}, @ovar{unused}, @
-  @dvar{includes, default-includes})
+  @dvar{includes, AC_INCLUDES_DEFAULT})
 @acindex{CHECK_SIZEOF}
 @cvindex address@hidden
 Define @address@hidden (@pxref{Standard Symbols}) to be
 the size in bytes of @var{type-or-expr}, which may be either a type or
 an expression returning a value that has a size.  If the expression
address@hidden (@var{type-or-expr})} is invalid, the result is 0.  If no
address@hidden are specified, the default includes are used
-(@pxref{Default Includes}).
address@hidden (@var{type-or-expr})} is invalid, the result is 0.
address@hidden is a series of include directives, defaulting to
address@hidden (@pxref{Default Includes}), which are used
+prior to the expression under test.
 
 This macro now works even when cross-compiling.  The @var{unused}
 argument was used when cross-compiling.
@@ -6406,7 +6428,7 @@ AC_CHECK_SIZEOF([int *])
 defines @code{SIZEOF_INT_P} to be 8 on DEC Alpha AXP systems.
 @end defmac
 
address@hidden AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, default-includes})
address@hidden AC_CHECK_ALIGNOF (@var{type}, @dvar{includes, 
AC_INCLUDES_DEFAULT})
 @acindex{CHECK_ALIGNOF}
 @cvindex address@hidden
 Define @address@hidden (@pxref{Standard Symbols}) to be the
@@ -6417,7 +6439,7 @@ is 0.  If no @var{includes} are specified, the default 
includes are used
 @end defmac
 
 @defmac AC_COMPUTE_INT (@var{var}, @var{expression}, @
-  @dvar{includes, default-includes}, @ovar{action-if-fails})
+  @dvar{includes, AC_INCLUDES_DEFAULT}, @ovar{action-if-fails})
 @acindex{COMPUTE_INT}
 Store into the shell variable @var{var} the value of the integer
 @var{expression}.  The
-- 
1.5.3.8







reply via email to

[Prev in Thread] Current Thread [Next in Thread]