[SCM] GNU Autoconf source repository branch, master, updated. v2.62-44-g6d04538

[Eric Blake]

This is an automated email from the git hooks/post-receive script. It was
generated because a ref change was pushed to the repository containing
the project "GNU Autoconf source repository".

http://git.sv.gnu.org/gitweb/?p=autoconf.git;a=commitdiff;h=6d04538831ab9e02826bbb951de43ff62ccd72e6

The branch, master has been updated
       via  6d04538831ab9e02826bbb951de43ff62ccd72e6 (commit)
      from  ebe1f38cbaff7c585be907af4b298f8e3a6e7005 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 6d04538831ab9e02826bbb951de43ff62ccd72e6
Author: Stepan Kasal <address@hidden>
Date:   Thu Jul 17 18:55:51 2008 -0600

    Improve documentation of config.h.in template rules.
    
    * doc/autoconf.texi (Header Templates): Mention rules on comments
    and whitespace, and that the user cannot rely on #undef to survive
    through config.status.
    
    Signed-off-by: Eric Blake <address@hidden>

-----------------------------------------------------------------------

Summary of changes:
 ChangeLog         |    8 ++++++
 doc/autoconf.texi |   62 +++++++++++++++++++++++++++++++++++-----------------
 2 files changed, 50 insertions(+), 20 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index ecf547b..da65cc7 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2008-07-17  Stepan Kasal  <address@hidden>
+       and Eric Blake  <address@hidden>
+
+       Improve documentation of config.h.in template rules.
+       * doc/autoconf.texi (Header Templates): Mention rules on comments
+       and whitespace, and that the user cannot rely on #undef to survive
+       through config.status.
+
 2008-07-16  Eric Blake  <address@hidden>
 
        Revert m4_prepend; it is less efficient, and unused by bison.
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index a785471..bfe5c1b 100644
--- a/doc/autoconf.texi
+++ b/doc/autoconf.texi
@@ -3082,10 +3082,9 @@ AC_CHECK_HEADERS([unistd.h])
 @end example
 
 @noindent
-Then you could have code like the following in @file{conf.h.in}.  On
-systems that have @file{unistd.h}, @command{configure} defines
address@hidden to 1.  On other systems, the whole line is
-commented out (in case the system predefines that symbol).
+Then you could have code like the following in @file{conf.h.in}.
+The @file{conf.h} created by @command{configure} defines @samp{HAVE_UNISTD_H}
+to 1, if and only if the system has @file{unistd.h}.
 
 @example
 @group
@@ -3094,29 +3093,52 @@ commented out (in case the system predefines that 
symbol).
 @end group
 @end example
 
-Pay attention that @samp{#undef} is in the first column, and there is
-nothing after @samp{HAVE_UNISTD_H}, not even white space.  You can
-then decode the configuration header using the preprocessor directives:
+The format of the template file is stricter than what the C preprocessor
+is required to accept.  A directive line should contain only whitespace,
address@hidden, and @samp{HAVE_UNISTD_H}.  The use of @samp{#define}
+instead of @samp{#undef}, or of comments on the same line as
address@hidden, is strongly discouraged.  Each hook should only be listed
+once.  Other preprocessor lines, such as @samp{#ifdef} or
address@hidden, are copied verbatim from the template into the
+generated header.
+
+Since it is a tedious task to keep a template header up to date, you may
+use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
+
+During the instantiation of the header, each @samp{#undef} line in the
+template file for each symbol defined by @samp{AC_DEFINE} is changed to an
+appropriate @samp{#define}. If the corresponding @samp{AC_DEFINE} has not
+been executed during the @command{configure} run, the @samp{#undef} line is
+commented out.  (This is important, e.g., for @samp{_POSIX_SOURCE}:
+on many systems, it can be implicitly defined by the compiler, and
+undefining it in the header would then break compilation of subsequent
+headers.)
+
+Currently, @emph{all} remaining @samp{#undef} lines in the header
+template are commented out, whether or not there was a corresponding
address@hidden for the macro name; but this behavior is not guaranteed
+for future releases of Autoconf.
+
+Generally speaking, since you should not use @samp{#define}, and you
+cannot guarantee whether a @samp{#undef} directive in the header
+template will be converted to a @samp{#define} or commented out in the
+generated header file, the template file cannot be used for conditional
+definition effects.  Consequently, if you need to use the construct
 
 @example
 @group
-#include <conf.h>
-
-#ifdef HAVE_UNISTD_H
-# include <unistd.h>
-#else
-/* We are in trouble.  */
+#ifdef THIS
+# define THAT
 #endif
 @end group
 @end example
 
-The use of old form templates, with @samp{#define} instead of
address@hidden is strongly discouraged.  Similarly with old templates
-with comments on the same line as the @samp{#undef}.  Anyway, putting
-comments in preprocessor macros has never been a good idea.
-
-Since it is a tedious task to keep a template header up to date, you may
-use @command{autoheader} to generate it, see @ref{autoheader Invocation}.
address@hidden
+you must place it outside of the template.
+If you absolutely need to hook it to the config header itself, please put
+the directives to a separate file, and @samp{#include} that file from the
+config header template.  If you are using @command{autoheader}, you would
+probably use @samp{AH_BOTTOM} to append the @samp{#include} directive.
 
 
 @node autoheader Invocation


hooks/post-receive
--
GNU Autoconf source repository