X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib-tool.texi;h=ce510cb0c7df1eb32477702963f9b1beb9068c41;hb=f1c88d2ef7d0860d2374e325d0b26febc11479b7;hp=db3e223dab18163d1415880639fb5ff838824343;hpb=c65ab984161ef321947cfdfefad8ea80242f338a;p=gnulib.git diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index db3e223da..ce510cb0c 100644 --- a/doc/gnulib-tool.texi +++ b/doc/gnulib-tool.texi @@ -31,7 +31,8 @@ a real run without changing anything. * Initial import:: First import of Gnulib modules. * Modified imports:: Changing the import specification. * Simple update:: Tracking Gnulib development. -* CVS Issues:: Integration with CVS. +* Source changes:: Impact of Gnulib on your source files. +* VCS Issues:: Integration with Version Control Systems. @end menu @@ -60,7 +61,7 @@ Module list with included dependencies: File list: lib/dummy.c lib/strdup.c - lib/string_.h + lib/string.in.h m4/absolute-header.m4 m4/extensions.m4 m4/gnulib-common.m4 @@ -70,7 +71,7 @@ Creating directory ./lib Creating directory ./m4 Copying file lib/dummy.c Copying file lib/strdup.c -Copying file lib/string_.h +Copying file lib/string.in.h Copying file m4/absolute-header.m4 Copying file m4/extensions.m4 Copying file m4/gnulib-common.m4 @@ -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,10 +337,44 @@ does it: $ gnulib-tool --import @end smallexample +@noindent This will create, update or remove files, as needed. -@node CVS Issues -@section CVS Issues +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{} being +already included. Furthermore @file{} 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 } 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{} 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 + +If a project stores its source files in a version control system (VCS), +such as CVS, SVN, or Git, one needs to decide which files to commit. All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4}, should be treated like generated source files, like for example a @@ -347,21 +384,20 @@ should be treated like generated source files, like for example a @item In projects which commit all source files, whether generated or not, into -CVS, the @code{gnulib-tool} generated files should all be committed. +their VCS, 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 +@code{make clean}), using information determined by @command{configure} +They should not be checked into the VCS, 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 +In projects which customarily omit from their VCS all files that are 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 +added into the VCS. The only file that must be added to the VCS is @file{gnulib-cache.m4} in the M4 macros directory. Also, the script for -restoring files not in CVS, customarily called @file{autogen.sh} or +restoring files not in the VCS, customarily called @file{autogen.sh} or @file{bootstrap.sh}, will typically contain the statement for restoring the omitted files: