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