Eric Blake wrote:
> the gnulib policy is that <config.h> must be included first in all .c
> files, and never in gnulib's .h files. If you consistently follow this
> rule in your projects, then you won't run into problems with inconsistent
> parsing of gnulib .h files.
Yes. Thanks for saying it so clearly: This was undocumented so far. I'm
documenting it:
2007-10-27 Bruno Haible <[EMAIL PROTECTED]>
* doc/gnulib.texi: Invoke @firstparagraphindent.
* doc/gnulib-tool.texi (Simple update): Mention possible incompatible
changes in gnulib.
(Source changes): New section.
--- doc/gnulib.texi.orig 2007-10-28 01:32:36.000000000 +0200
+++ doc/gnulib.texi 2007-10-28 00:58:14.000000000 +0200
@@ -5,6 +5,9 @@
@settitle GNU Gnulib
@syncodeindex fn cp
@syncodeindex pg cp
[EMAIL PROTECTED] texi2html
[EMAIL PROTECTED] insert
[EMAIL PROTECTED] ifclear
@comment %**end of header
@set UPDATED $Date: 2007-09-09 13:20:45 $
--- doc/gnulib-tool.texi.orig 2007-10-28 01:32:36.000000000 +0200
+++ doc/gnulib-tool.texi 2007-10-28 01:29:17.000000000 +0200
@@ -31,6 +31,7 @@
* Initial import:: First import of Gnulib modules.
* Modified imports:: Changing the import specification.
* Simple update:: Tracking Gnulib development.
+* Source changes:: Impact of Gnulib on your source files.
* VCS Issues:: Integration with Version Control Systems.
@end menu
@@ -322,6 +323,7 @@
file. Corresponds to the @samp{--macro-prefix} command line argument.
@end table
+
@node Simple update
@section Simple update
@@ -333,8 +335,39 @@
$ gnulib-tool --import
@end smallexample
[EMAIL PROTECTED]
This will create, update or remove files, as needed.
+Note: From time to time, changes are made in Gnulib that are not backward
+compatible. When updating to a more recent Gnulib, you should consult
+Gnulib's @file{NEWS} file to check whether the incompatible changes affect
+your project.
+
+
[EMAIL PROTECTED] Source changes
[EMAIL PROTECTED] Changing your sources for use with Gnulib
+
+Gnulib contains some header file overrides. This means that when building
+on systems with deficient header files in @file{/usr/include/}, it may create
+files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
+the build directory. In the other source directories of your package you
+will usually pass @samp{-I} options to the compiler, so that these Gnulib
+substitutes are visible and take precedence over the files in
[EMAIL PROTECTED]/usr/include/}.
+
+These Gnulib substitute header files rely on @file{<config.h>} being
+already included. Furthermore @file{<config.h>} must be the first include
+in every compilation unit. This means that to @emph{all your source files}
+and likely also to @emph{all your tests source files} you need to add an
[EMAIL PROTECTED] <config.h>} at the top. Which source files are affected?
+Exactly those whose compilation includes a @samp{-I} option that refers to
+the Gnulib library directory.
+
+This is annoying, but inevitable: On many systems, @file{<config.h>} is
+used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
+and these flags have no effect after any system header file has been included.
+
+
@node VCS Issues
@section Issues with Version Control Systems
