* 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
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
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
@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
...
@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
@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
@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
+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:
because they were missing.
@end itemize
-
-The same holds for other version control systems than CVS, such as @samp{git}
-or @samp{svn}.
projects / gnulib.git / blobdiff