doc/gnulib-tool.texi

   1 @node Invoking gnulib-tool
   2 @chapter Invoking gnulib-tool
   3
   4 @pindex gnulib-tool
   5 @cindex invoking @command{gnulib-tool}
   6
   7 The @command{gnulib-tool} command is the recommended way to import
   8 Gnulib modules.  It is possible to borrow Gnulib modules in a package
   9 without using @command{gnulib-tool}, relying only on the
  10 meta-information stored in the @file{modules/*} files, but with a
  11 growing number of modules this becomes tedious.  @command{gnulib-tool}
  12 simplifies the management of source files, @file{Makefile.am}s and
  13 @file{configure.ac} in packages incorporating Gnulib modules.
  14
  15 Run @samp{gnulib-tool --help} for information.  To get familiar with
  16 @command{gnulib-tool} without affecting your sources, you can also try
  17 some commands with the option @samp{--dry-run}; then
  18 @code{gnulib-tool} will only report which actions it would perform in
  19 a real run without changing anything.
  20
  21 @menu
  22 * Initial import::              First import of Gnulib modules.
  23 * Modified imports::            Changing the import specification.
  24 * Simple update::               Tracking Gnulib development.
  25 * CVS Issues::                  Integration with CVS.
  26 @end menu
  27
  28
  29 @node Initial import
  30 @section Initial import
  31 @cindex initial import
  32
  33 Gnulib assumes your project uses Autoconf and Automake.  Invoking
  34 @samp{gnulib-tool --import} will copy source files, create a
  35 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
  36 Autoconf M4 macro declarations used by @file{configure.ac}, and generate
  37 a file @file{gnulib-cache.m4} containing the cached specification of how
  38 Gnulib is used.
  39
  40 Our example will be a library that uses Autoconf, Automake and
  41 Libtool.  It calls @code{strdup}, and you wish to use gnulib to make
  42 the package portable to C89 (which doesn't have @code{strdup}).
  43
  44 @example
  45 ~/src/libfoo$ gnulib-tool --import strdup
  46 Module list with included dependencies:
  47   strdup
  48 File list:
  49   lib/strdup.c
  50   lib/strdup.h
  51   m4/onceonly_2_57.m4
  52   m4/strdup.m4
  53 Copying file m4/gnulib-tool.m4
  54 Copying file m4/onceonly_2_57.m4
  55 Copying file lib/strdup.c
  56 Copying file lib/strdup.h
  57 Copying file m4/strdup.m4
  58 Creating lib/Makefile.am
  59 Creating m4/gnulib-cache.m4
  60 Creating m4/gnulib-comp.m4
  61 Finished.
  62
  63 You may need to add #include directives for the following .h files.
  64   #include "strdup.h"
  65
  66 Don't forget to
  67   - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
  68   - mention "lib" in SUBDIRS in Makefile.am,
  69   - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
  70   - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
  71   - invoke gl_INIT in ./configure.ac.
  72 ~/src/libfoo$
  73 @end example
  74
  75 By default, the source code is copied into @file{lib/} and the M4
  76 macros in @file{m4/}.  You can override these paths by using
  77 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}.  Some
  78 modules also provide other files necessary for building. These files
  79 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
  80 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option.  If
  81 neither is specified, the current directory is assumed.
  82
  83 @code{gnulib-tool} can make symbolic links instead of copying the
  84 source files.  Use the @samp{--symbolic} (or @samp{-s} for short) option
  85 to do this.
  86
  87 @code{gnulib-tool} will overwrite any pre-existing files, in
  88 particular @file{Makefile.am}.  Unfortunately, separating the
  89 generated @file{Makefile.am} content (for building the gnulib library)
  90 into a separate file, say @file{gnulib.mk}, that could be included
  91 by your handwritten @file{Makefile.am} is not possible, due to how
  92 variable assignments are handled by Automake.
  93
  94 Consequently, it is a good idea to choose directories that are not
  95 already used by your projects, to separate gnulib imported files from
  96 your own files.  This approach is also useful if you want to avoid
  97 conflicts between other tools (e.g., @code{gettextize} that also copy
  98 M4 files into your package.  Simon Josefsson successfully uses a source
  99 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
 100 packages.
 101
 102 After the @samp{--import} option on the command line comes the list of
 103 Gnulib modules that you want to incorporate in your package.  The names
 104 of the modules coincide with the filenames in Gnulib's @file{modules/}
 105 directory.
 106
 107 Some Gnulib modules depend on other Gnulib modules.  @code{gnulib-tool}
 108 will automatically add the needed modules as well; you need not list
 109 them explicitly.  @code{gnulib-tool} will also memorize which dependent
 110 modules it has added, so that when someday a dependency is dropped, the
 111 implicitly added module is dropped as well (unless you have explicitly
 112 requested that module).
 113
 114 If you want to cut a dependency, i.e., not add a module although one of
 115 your requested modules depends on it, you may use the option
 116 @samp{--avoid=@var{module}} to do so.  Multiple uses of this option are
 117 possible.  Of course, you will then need to implement the same interface
 118 as the removed module.
 119
 120 A few manual steps are required to finish the initial import.
 121 @code{gnulib-tool} printed a summary of these steps.
 122
 123 First, you must ensure Autoconf can find the macro definitions in
 124 @file{gnulib-comp.m4}.  Use the @code{ACLOCAL_AMFLAGS} specifier in
 125 your top-level @file{Makefile.am} file, as in:
 126
 127 @example
 128 ACLOCAL_AMFLAGS = -I m4
 129 @end example
 130
 131 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
 132 @file{configure.ac}.  The macro @code{gl_EARLY} must be called as soon
 133 as possible after verifying that the C compiler is working.
 134 Typically, this is immediately after @code{AC_PROG_CC}, as in:
 135
 136 @example
 137 ...
 138 AC_PROG_CC
 139 gl_EARLY
 140 ...
 141 @end example
 142
 143 The core part of the gnulib checks are done by the macro
 144 @code{gl_INIT}.  Place it further down in the file, typically where
 145 you normally check for header files or functions.  It must come after
 146 other checks which may affect the compiler invocation, such as
 147 @code{AC_MINIX}.  For example:
 148
 149 @example
 150 ...
 151 # For gnulib.
 152 gl_INIT
 153 ...
 154 @end example
 155
 156 @code{gl_INIT} will in turn call the macros related with the
 157 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
 158 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
 159 @code{AM_FUNC_GETLINE}.  So there is no need to call those macros yourself
 160 when you use the corresponding gnulib modules.
 161
 162 You must also make sure that the gnulib library is built.  Add the
 163 @code{Makefile} in the gnulib source base directory to
 164 @code{AC_CONFIG_FILES}, as in:
 165
 166 @example
 167 AC_CONFIG_FILES(... lib/Makefile ...)
 168 @end example
 169
 170 You must also make sure that @code{make} will recurse into the gnulib
 171 directory.  To achieve this, add the gnulib source base directory to a
 172 @code{SUBDIRS} Makefile.am statement, as in:
 173
 174 @example
 175 SUBDIRS = lib
 176 @end example
 177
 178 or if you, more likely, already have a few entries in @code{SUBDIRS},
 179 you can add something like:
 180
 181 @example
 182 SUBDIRS += lib
 183 @end example
 184
 185 Finally, you have to add compiler and linker flags in the appropriate
 186 source directories, so that you can make use of the gnulib library.
 187 Since some modules (@samp{getopt}, for example) may copy files into
 188 the build directory, @file{top_builddir/lib} is needed as well
 189 as @file{top_srcdir/lib}.  For example:
 190
 191 @example
 192 ...
 193 AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib
 194 ...
 195 LDADD = lib/libgnu.a
 196 ...
 197 @end example
 198
 199 Don't forget to @code{#include} the various header files.  In this
 200 example, you would need to make sure that @samp{#include "strdup.h"}
 201 is evaluated when compiling all source code files, that want to make
 202 use of @code{strdup}.
 203
 204 When an include file is provided by Gnulib
 205 you shouldn't try to include the corresponding system header files
 206 yourself, but let the gnulib header file do it.  The ordering
 207 of the definition for some symbols may be significant; the Gnulib
 208 header files take care of that.
 209
 210 For example, to use the @code{time_r} gnulib module you should
 211 use include header file provided by the gnulib, and so
 212 @samp{#include "time_r.h"}, but you shouldn't explicitly
 213 @samp{#include <time.h>} as it is already done in @file{time_r.h}
 214 before the redefinition of some symbols.
 215
 216 A final word of warning: Gnulib currently assumes it will be
 217 responsible for @emph{all} functions that end up in the Autoconf
 218 @code{@@LIBOBJS@@} variables (and/or @code{@@LTLIBOBJS@@} if using
 219 Libtool), e.g., those specified in @code{AC_REPLACE_FUNCS} in your
 220 @file{configure.ac}.  Therefore, if you have any functions which are
 221 not covered by Gnulib which need that treatment, you have to
 222 essentially reimplement AC_REPLACE_FUNCS using different names; for an
 223 example, see the Findutils sources.  Perhaps this will be improved in
 224 the future.
 225
 226
 227 @node Modified imports
 228 @section Modified imports
 229
 230 You can at any moment decide to use Gnulib differently than the last time.
 231
 232 If you only want to use more Gnulib modules, simply invoke
 233 @command{gnulib-tool --import @var{new-modules}}.  @code{gnulib-tool}
 234 remembers which modules were used last time.  The list of modules that
 235 you pass after @samp{--import} is @emph{added} to the previous list of
 236 modules.
 237
 238 For most changes, such as added or removed modules, or even different
 239 choices of @samp{--lib}, @samp{--source-base} or @samp{--aux-dir}, there
 240 are two ways to perform the change.
 241
 242 The standard way is to modify manually the file @file{gnulib-cache.m4}
 243 in the M4 macros directory, then launch @samp{gnulib-tool --import}.
 244
 245 The other way is to call @command{gnulib-tool} again, with the changed
 246 command-line options.  Note that this doesn't let you remove modules,
 247 because as you just learned, the list of modules is always cumulated.
 248 Also this way is often impractical, because you don't remember the way
 249 you invoked @code{gnulib-tool} last time.
 250
 251 The only change for which this doesn't work is a change of the
 252 @samp{--m4-base} directory.  Because, when you pass a different value of
 253 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
 254 @file{gnulib-cache.m4} file any more... A possible solution is to manually
 255 copy the @file{gnulib-cache.m4} into the new M4 macro directory.
 256
 257 In the @file{gnulib-cache.m4}, the macros have the following meaning:
 258 @table @code
 259 @item gl_MODULES
 260 The argument is a space separated list of the requested modules, not including
 261 dependencies.
 262
 263 @item gl_AVOID
 264 The argument is a space separated list of modules that should not be used,
 265 even if they occur as dependencies.  Corresponds to the @samp{--avoid}
 266 command line argument.
 267
 268 @item gl_SOURCE_BASE
 269 The argument is the relative file name of the directory containing the gnulib
 270 source files (mostly *.c and *.h files).  Corresponds to the
 271 @samp{--source-base} command line argument.
 272
 273 @item gl_M4_BASE
 274 The argument is the relative file name of the directory containing the gnulib
 275 M4 macros (*.m4 files).  Corresponds to the @samp{--m4-base} command line
 276 argument.
 277
 278 @item gl_TESTS_BASE
 279 The argument is the relative file name of the directory containing the gnulib
 280 unit test files.  Corresponds to the @samp{--tests-base} command line argument.
 281
 282 @item gl_LIB
 283 The argument is the name of the library to be created.  Corresponds to the
 284 @samp{--lib} command line argument.
 285
 286 @item gl_LGPL
 287 The presence of this macro corresponds to the @samp{--lgpl} command line
 288 argument.  It takes no arguments.
 289
 290 @item gl_LIBTOOL
 291 The presence of this macro corresponds to the @samp{--libtool} command line
 292 argument and to the absence of the @samp{--no-libtool} command line argument.
 293 It takes no arguments.
 294
 295 @item gl_MACRO_PREFIX
 296 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
 297 file.  Corresponds to the @samp{--macro-prefix} command line argument.
 298 @end table
 299
 300 @node Simple update
 301 @section Simple update
 302
 303 When you want to update to a more recent version of Gnulib, without
 304 changing the list of modules or other parameters, a simple call
 305 does it:
 306
 307 @smallexample
 308 $ gnulib-tool --import
 309 @end smallexample
 310
 311 This will create, update or remove files, as needed.
 312
 313 @node CVS Issues
 314 @section CVS Issues
 315
 316 All files created by @code{gnulib-tool}, except @file{gnulib-cache.m4},
 317 should be treated like generated source files, like for example a
 318 @file{parser.c} file is generated from @file{parser.y}.
 319
 320 In projects which commit all source files, whether generated or not, into
 321 CVS, the @code{gnulib-tool} generated files should all be committed.
 322
 323 In projects which customarily omit from the CVS all files that generated
 324 from other source files, all these files and directories would not be
 325 added into CVS.  The only file that must be added to CVS is
 326 @file{gnulib-cache.m4} in the M4 macros directory.  Also, the script for
 327 restoring files not in CVS, customarily called @file{autogen.sh} or
 328 @file{bootstrap.sh}, will typically contain the statement for restoring
 329 the omitted files:
 330
 331 @smallexample
 332 $ gnulib-tool --update
 333 @end smallexample
 334
 335 The @samp{--update} option operates much like the @samp{--import} option,
 336 but it does not offer the possibility to change the way Gnulib is used.
 337 Also it does not report in the ChangeLogs the files that it had to add
 338 because they were missing.