Hello Eric,
On Tue, Jun 17, 2008 at 09:20:52PM -0600, Eric Blake wrote:
> | ``
> | Generally speaking, all #define and #undef directives in the header
> | template may be modified by config.status, under some circumstances.
> | Consequently, if you need to define or undefine a symbol under some
> | circumstances (#ifdef THIS #define THAT, etc.), you should place
> | those directives outside the config headers. If you absolutely need
> | to hook that to the config header itself, please put these directives
> | to a separate file, and #include it from the config header template.
> | (If you are using autoheader, you would probably use AH_TOP or
> | AH_BOTTOM to inject the #include directive.)
> |
> | For certain symbols it is important to avoid #undef ... [explanation
> | about _POSIX_WHATEVER].
> | To achive this, current Autoconf comments out _all_ remaining #undef
> | directives remaining in the config header at the end of the
> | instatiation, but this may change in future releases.
> | ''
> |
> | WDYT?
>
> Looks like a reasonable start, but be careful for typos (such as symbold).
> ~ I'll gladly review a texinfo-markup version, if I don't get around to
> writing one first.
I tried to write something, and I ended up with a different version.
I have also removed a trivial example; IMHO, it does not belong to
this node and I guess the information is available elsewhere in the
manual.
Please find the proposal attached to this mail. Eric, could you
please merge the two and check for errors? (Then toss it back to me
or commit.)
Comments from others are very welcome, too, of course.
Have a nice day,
Stepan
diff --git a/doc/autoconf.texi b/doc/autoconf.texi
index 43a84bc..31a55c0 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
[EMAIL PROTECTED] 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
@@ -3095,28 +3094,40 @@ commented out (in case the system predefines that
symbol).
@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:
+nothing after @samp{HAVE_UNISTD_H}, not even white space.
+(The use of old form templates, with @samp{#define} instead of @samp{#undef}
+or comments on the same line as the @samp{#undef}, is strongly discouraged.)
+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 shall not be undefined nor redefined, yet
[EMAIL PROTECTED] has to define it on Minix.)
+
+Currently, @emph{all} remaining @samp{#undef} lines in the header
+template are commented out; but this behavior is not guaranteed for future
+releases of Autoconf.
+
+Generally speaking, all @samp{#define} and @samp{#undef} directives in the
+header template might be replaced, under some circumstances.
+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. */
-#endif
+#ifdef THIS
+# define THAT
+...
@end group
@end example
-
-The use of old form templates, with @samp{#define} instead of
[EMAIL PROTECTED] 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}.
+you should better 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
