X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=d32f8da5df69efa2d10682fa92dfef432e99adad;hb=e5a6714d02ac3db96ffd12e1bc9634aeedcc657d;hp=01ea29d1208e25c96c931c328ff9aef56b18b9e5;hpb=3fc0d6e82c20fcee926ba604d338afe433eaa24e;p=gnulib.git

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 01ea29d12..d32f8da5d 100644
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -1,7 +1,7 @@
 @node Invoking gnulib-tool
 @chapter Invoking gnulib-tool
 
-@c Copyright (C) 2005, 2006 Free Software Foundation, Inc.
+@c Copyright (C) 2005, 2006, 2007 Free Software Foundation, Inc.
 
 @c Permission is granted to copy, distribute and/or modify this document
 @c under the terms of the GNU Free Documentation License, Version 1.2 or
@@ -48,29 +48,42 @@ Gnulib is used.
 
 Our example will be a library that uses Autoconf, Automake and
 Libtool.  It calls @code{strdup}, and you wish to use gnulib to make
-the package portable to C89 (which doesn't have @code{strdup}).
+the package portable to C89 and C99 (which don't have @code{strdup}).
 
 @example
 ~/src/libfoo$ gnulib-tool --import strdup
 Module list with included dependencies:
+  absolute-header
+  extensions
   strdup
+  string
 File list:
+  lib/dummy.c
   lib/strdup.c
-  lib/strdup.h
-  m4/onceonly_2_57.m4
+  lib/string_.h
+  m4/absolute-header.m4
+  m4/extensions.m4
+  m4/gnulib-common.m4
   m4/strdup.m4
-Copying file m4/gnulib-tool.m4
-Copying file m4/onceonly_2_57.m4
+  m4/string_h.m4
+Creating directory ./lib
+Creating directory ./m4
+Copying file lib/dummy.c
 Copying file lib/strdup.c
-Copying file lib/strdup.h
+Copying file lib/string_.h
+Copying file m4/absolute-header.m4
+Copying file m4/extensions.m4
+Copying file m4/gnulib-common.m4
+Copying file m4/gnulib-tool.m4
 Copying file m4/strdup.m4
+Copying file m4/string_h.m4
 Creating lib/Makefile.am
 Creating m4/gnulib-cache.m4
 Creating m4/gnulib-comp.m4
 Finished.
 
 You may need to add #include directives for the following .h files.
-  #include "strdup.h"
+  #include <string.h>
 
 Don't forget to
   - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
@@ -212,21 +225,19 @@ LDADD = lib/libgnu.a
 @end example
 
 Don't forget to @code{#include} the various header files.  In this
-example, you would need to make sure that @samp{#include "strdup.h"}
+example, you would need to make sure that @samp{#include <string.h>}
 is evaluated when compiling all source code files, that want to make
 use of @code{strdup}.
 
-When an include file is provided by Gnulib
-you shouldn't try to include the corresponding system header files
-yourself, but let the gnulib header file do it.  The ordering
-of the definition for some symbols may be significant; the Gnulib
-header files take care of that.
-
-For example, to use the @code{time_r} gnulib module you should
-use include header file provided by the gnulib, and so
-@samp{#include "time_r.h"}, but you shouldn't explicitly
-@samp{#include <time.h>} as it is already done in @file{time_r.h}
-before the redefinition of some symbols.
+In the usual case where Autoconf is creating a @file{config.h} file,
+you should include @file{config.h} first, before any other include
+file.  That way, for example, if @file{config.h} defines
+@samp{restrict} to be the empty string on a pre-C99 host, or a macro
+like @samp{_FILE_OFFSET_BITS} that affects the layout of data
+structures, the definition is consistent for all include files.
+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
@@ -332,9 +343,19 @@ All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
 should be treated like generated source files, like for example a
 @file{parser.c} file is generated from @file{parser.y}.
 
+@itemize
+
+@item
 In projects which commit all source files, whether generated or not, into
 CVS, the @code{gnulib-tool} generated files should all be committed.
 
+Gnulib also contains files generated by @command{make} (and removed by
+@code{make clean}), using information determined by @command{configure}
+They should not be checked into CVS, but instead added to
+@file{.cvsignore}.  When you have a Gnulib source file of the form
+@file{lib/foo_.h}, the corresponding @file{lib/foo.h} is such a file.
+
+@item
 In projects which customarily omit from the CVS all files that generated
 from other source files, all these files and directories would not be
 added into CVS.  The only file that must be added to CVS is
@@ -351,3 +372,8 @@ The @samp{--update} option operates much like the @samp{--import} option,
 but it does not offer the possibility to change the way Gnulib is used.
 Also it does not report in the ChangeLogs the files that it had to add
 because they were missing.
+
+@end itemize
+
+The same holds for other version control systems than CVS, such as @samp{git}
+or @samp{svn}.