@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
* 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
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.in.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.in.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,
neither is specified, the current directory is assumed.
@code{gnulib-tool} can make symbolic links instead of copying the
-source files. Use the @samp{--symbolic} (or @samp{-s} for short) option
-to do this.
+source files. The option to specify for this is @samp{--symlink}, or
+@samp{-s} for short. This can be useful to save a few kilobytes of disk
+space. But it is likely to introduce bugs when @code{gnulib} is updated;
+it is more reliable to use @samp{gnulib-tool --update} (see below)
+to update to newer versions of @code{gnulib}. Furthermore it requires
+extra effort to create self-contained tarballs, and it may disturb some
+mechanism the maintainer applies to the sources. For these reasons,
+this option is generally discouraged.
@code{gnulib-tool} will overwrite any pre-existing files, in
particular @file{Makefile.am}. Unfortunately, separating the
@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
...
@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.
-
-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.
+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.
+
+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
@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
file. Corresponds to the @samp{--macro-prefix} command line argument.
@end table
+
@node Simple update
@section Simple update
$ 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{<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
+
+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
@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.
+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 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.
-In projects which customarily omit from the CVS all files that generated
+@item
+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:
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
projects / gnulib.git / blobdiff