bug-autoconf
[Top][All Lists]
Advanced

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

Please make the Autoconf manual less vague and add more examples


From: Eli Zaretskii
Subject: Please make the Autoconf manual less vague and add more examples
Date: Sat, 24 Nov 2012 11:50:44 +0200

(I'm not subscribed to the list, so please CC me on any responses.)

For the context, see

  https://lists.gnu.org/archive/html/emacs-devel/2012-11/msg00441.html

I never before had to do anything serious in Autoconf, so please take
the below with a grain of salt and consider it as a first impression
of a naive newbie.

I find the Autoconf manual too terse and cryptic to penetrate for
someone, such as myself, who needs to do a relatively simple Autoconf
job for the first time.  The manual describes the Autoconf facilities
in a way that is too abstract, using vague language, and includes too
few examples to help the reader understand that vague language.  I
found myself grepping configure.ac files on my disk for examples, to
be able to understand what to do.

Allow me to show a few examples.

  -- Macro: AC_CHECK_HEADER (HEADER-FILE, [ACTION-IF-FOUND],
           [ACTION-IF-NOT-FOUND], [INCLUDES])
      If the system header file HEADER-FILE is compilable, execute shell
      commands ACTION-IF-FOUND, otherwise execute ACTION-IF-NOT-FOUND.
      If you just want to define a symbol if the header file is
      available, consider using `AC_CHECK_HEADERS' instead.

      INCLUDES is decoded to determine the appropriate include
      directives.

My problem here was with the last sentence: what does it mean "decoded
to determine"?  What kind of stuff can I put in that argument, and in
what form?  I found this example in Emacs's configure.ac:

  AC_CHECK_HEADERS(net/if.h, , , [AC_INCLUDES_DEFAULT
  #if HAVE_SYS_SOCKET_H
  #include <sys/socket.h>
  #endif])

which looks like I can put any series of preprocessor directives
there.  (A similar example is where AC_CHECK_HEADERS is described in
the manual.)  But it still leaves me in the dark wrt whether C code
other than preprocessor directives can be used, or even whether
AC_CHECK_HEADER can also use such directives.

For the record, what I needed to do is this:

  AC_CHECK_HEADERS(X11/xpm.h, HAVE_XPM=yes, HAVE_XPM=no, [
  #define FOR_MSW 1])

Another example:

  -- Macro: AC_MSG_RESULT (RESULT-DESCRIPTION)
      Notify the user of the results of a check.  RESULT-DESCRIPTION is
      almost always the value of the cache variable for the check,
      typically `yes', `no', or a file name.

It says "almost always", but doesn't describe what else, in addition
to a cache variable, can be used as RESULT-DESCRIPTION.  Again,
grepping the uses, I find things like this:

      [if $PAXCTL -v conftest$EXEEXT >/dev/null 2>&1; then AC_MSG_RESULT(yes)
      else AC_MSG_RESULT(no); PAXCTL=""; fi])

or this:

      AC_MSG_RESULT([yes CFLAGS='$$1_CFLAGS' LIBS='$$1_LIBS'])

or this:

      AC_MSG_RESULT([$HAVE_GNU_MAKE])

or this:

      AC_MSG_RESULT(6 or newer)

Another example, with embedded comments:

  -- Macro: AC_DEFINE (VARIABLE, VALUE, [DESCRIPTION])
  -- Macro: AC_DEFINE (VARIABLE)
      Define VARIABLE to VALUE (verbatim), by defining a C preprocessor

What is the significance of "(verbatim)" here?

      macro for VARIABLE.  VARIABLE should be a C identifier, optionally
      suffixed by a parenthesized argument list to define a C
      preprocessor macro with arguments.  The macro argument list, if
      present, should be a comma-separated list of C identifiers,
      possibly terminated by an ellipsis `...' if C99 syntax is employed.
      VARIABLE should not contain comments, white space, trigraphs,
      backslash-newlines, universal character names, or non-ASCII
      characters.

      VALUE may contain backslash-escaped newlines, which will be
      preserved if you use `AC_CONFIG_HEADERS' but flattened if passed
      via address@hidden@' (with no effect on the compilation, since the
      preprocessor sees only one line in the first place).

Several potentially important issues packed into a single complex
sentence with no explanations or cross-references to help the
confused.  What does "use `AC_CONFIG_HEADERS'" mean?  What is "@DEFS@"
and how does it come into play?  The meaning of the "flattened" part
and the note in parens after that are left to guesswork.

                                                           VALUE should
      not contain raw newlines.  If you are not using
      `AC_CONFIG_HEADERS', VALUE should not contain any `#' characters,
      as `make' tends to eat them.  To use a shell variable, use
      `AC_DEFINE_UNQUOTED' instead.

      DESCRIPTION is only useful if you are using `AC_CONFIG_HEADERS'.
      In this case, DESCRIPTION is put into the generated `config.h.in'
      as the comment before the macro define.  The following example
      defines the C preprocessor variable `EQUATION' to be the string
      constant `"$a > $b"':

           AC_DEFINE([EQUATION], ["$a > $b"],
             [Equation string.])

      If neither VALUE nor DESCRIPTION are given, then VALUE defaults to
      1 instead of to the empty string.  This is for backwards
      compatibility with older versions of Autoconf, but this usage is
      obsolescent and may be withdrawn in future versions of Autoconf.

This doesn't say what happens if VALUE is not given, but DESCRIPTION
is.  I seem to see this in use, e.g.:

    AC_DEFINE(IRIX6_5, [], [Define if the system is IRIX.])

I also see this:

    AC_DEFINE(USG, [])

which is also doesn't seem to be covered.

I bump into such examples wherever I go in the manual.  I understand
that it can be hard to take a POV of a newbie, so I think adding more
examples, with emphasis on non-trivial uses of the described
facilities, will go a long way towards making the manual more useful
to newbies.

TIA



reply via email to

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