X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=ce510cb0c7df1eb32477702963f9b1beb9068c41;hb=f1c88d2ef7d0860d2374e325d0b26febc11479b7;hp=7b5d315a8582930f6914d830d714a5bee79d0da6;hpb=5f10cf252efbd67b0936436dcc3c4d4765a0086d;p=gnulib.git

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 7b5d315a8..ce510cb0c 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -31,6 +31,7 @@ a real run without changing anything.
 * 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
 
@@ -218,7 +219,7 @@ as @file{top_srcdir/lib}.  For example:
 
 @example
 ...
-AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
+AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
 ...
 LDADD = lib/libgnu.a
 ...
@@ -239,15 +240,14 @@ Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
 effect, if defined after the first system header file is included.
 
-A final word of warning: Gnulib currently assumes it will be
-responsible for @emph{all} functions that end up in the Autoconf
-@code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
-Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
-@file{configure.ac}.  Therefore, if you have any functions which are
-not covered by Gnulib which need that treatment, you have to
-essentially reimplement AC_REPLACE_FUNCS using different names; for an
-example, see the Findutils sources.  Perhaps this will be improved in
-the future.
+Finally, note that you can not use @code{AC_LIBOBJ} or
+@code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
+resulting object files to be automatically added to @file{lib/libgnu.a}.
+This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
+from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
+@code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
+is built from the contents of a different variable, usually
+@code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
 
 
 @node Modified imports
@@ -310,8 +310,10 @@ The argument is the name of the library to be created.  Corresponds to the
 @samp{--lib} command line argument.
 
 @item gl_LGPL
-The presence of this macro corresponds to the @samp{--lgpl} command line
-argument.  It takes no arguments.
+The presence of this macro without arguments corresponds to the @samp{--lgpl}
+command line argument.  The presence of this macro with an argument (whose
+value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
+argument.
 
 @item gl_LIBTOOL
 The presence of this macro corresponds to the @samp{--libtool} command line
@@ -323,6 +325,7 @@ The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
 file.  Corresponds to the @samp{--macro-prefix} command line argument.
 @end table
 
+
 @node Simple update
 @section Simple update
 
@@ -334,8 +337,39 @@ does it:
 $ gnulib-tool --import
 @end smallexample
 
+@noindent
 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.
+
+
+@node Source changes
+@section 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
+@file{/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
+@samp{#include <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