1 @node Invoking gnulib-tool
2 @chapter Invoking gnulib-tool
4 @c Copyright (C) 2005--2024 Free Software Foundation, Inc.
6 @c Permission is granted to copy, distribute and/or modify this document
7 @c under the terms of the GNU Free Documentation License, Version 1.3 or
8 @c any later version published by the Free Software Foundation; with no
9 @c Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
10 @c copy of the license is at <https://www.gnu.org/licenses/fdl-1.3.en.html>.
13 @cindex invoking @command{gnulib-tool}
15 The @command{gnulib-tool} command is the recommended way to import
16 Gnulib modules. It is possible to borrow Gnulib modules in a package
17 without using @command{gnulib-tool}, relying only on the
18 meta-information stored in the @file{modules/*} files, but with a
19 growing number of modules this becomes tedious. @command{gnulib-tool}
20 simplifies the management of source files, @file{Makefile.am}s and
21 @file{configure.ac} in packages incorporating Gnulib modules.
23 @file{gnulib-tool} is not installed in a standard directory that is
24 contained in the @code{PATH} variable. It needs to be run directly in
25 the directory that contains the Gnulib source code. You can do this
26 either by specifying the absolute filename of @file{gnulib-tool}, or
27 you can also use a symbolic link from a place inside your @code{PATH}
28 to the @file{gnulib-tool} file of your preferred and most up-to-date
29 Gnulib checkout, like this:
31 $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
34 Run @samp{gnulib-tool --help} for information. To get familiar with
35 @command{gnulib-tool} without affecting your sources, you can also try
36 some commands with the option @samp{--dry-run}; then
37 @code{gnulib-tool} will only report which actions it would perform in
38 a real run without changing anything.
41 * Which modules?:: Determining the needed set of Gnulib modules
42 * Initial import:: First import of Gnulib modules.
43 * Modified imports:: Changing the import specification.
44 * Simple update:: Tracking Gnulib development.
45 * Source changes:: Impact of Gnulib on your source files.
46 * Link-time requirements:: Which libraries to link against
47 * Finding POSIX substitutes:: Determining additional suitable Gnulib modules
48 * Modified build rules:: Modifying the build rules of a Gnulib import
49 * Non-recursive make:: Building directly from the top-level directory
50 * Multiple instances:: Using Gnulib for both a library and a program
51 * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users!
52 * Localization:: Handling Gnulib's own message translations.
53 * VCS Issues:: Integration with Version Control Systems.
54 * Unit tests:: Bundling the unit tests of the Gnulib modules.
55 * Conditional dependencies:: Avoiding unnecessary checks and compilations.
60 @section Finding modules
61 @cindex Finding modules
63 There are four ways of finding the names of Gnulib modules that you can use
68 You have the complete module list, sorted according to categories, in
69 @url{https://www.gnu.org/software/gnulib/MODULES.html}.
72 If you are looking for POSIX function replacements that you don't know about
73 yet, follow the procedure described in section @ref{Finding POSIX substitutes}.
76 If you are looking for a particular POSIX header or function replacement,
77 look in the chapters @ref{Header File Substitutes} and
78 @ref{Function Substitutes}. For headers and functions that are provided by
79 Glibc but not standardized by POSIX, look in the chapters
80 @ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}.
83 If you have already found the source file in Gnulib and are looking for the
84 module that contains this source file, you can use the command
85 @samp{gnulib-tool --find @var{filename}}.
90 @section Initial import
91 @cindex initial import
93 Gnulib assumes that your project uses Autoconf. When using Gnulib, you
94 will need to have Autoconf among your build tools.
96 Gnulib also assumes that your project's @file{configure.ac} contains the
99 AC_CONFIG_HEADERS([config.h])
101 The @file{config.h} file gets generated with platform dependent C macro
102 definitions, and the source files include it (see @ref{Source changes}).
104 Unless you use @command{gnulib-tool}'s @option{--gnu-make} option,
105 Gnulib also assumes that your project uses Automake at least in a
106 subdirectory of your project. While the use of Automake in your
107 project's top level directory is an easy way to fulfil the Makefile
108 conventions of the GNU coding standards, Gnulib does not require it.
110 Invoking @samp{gnulib-tool --import} will copy source files, create a
111 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
112 Autoconf M4 macro declarations used by @file{configure.ac}, and generate
113 a file @file{gnulib-cache.m4} containing the cached specification of how
116 Our example will be a library that uses Autoconf, Automake and
117 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
118 the package portable to C99 and C11 (which don't have @code{strdup}).
121 ~/src/libfoo$ gnulib-tool --import strdup
122 Module list with included dependencies:
131 m4/absolute-header.m4
136 Creating directory ./lib
137 Creating directory ./m4
138 Copying file lib/dummy.c
139 Copying file lib/strdup.c
140 Copying file lib/string.in.h
141 Copying file m4/absolute-header.m4
142 Copying file m4/extensions.m4
143 Copying file m4/gnulib-common.m4
144 Copying file m4/gnulib-tool.m4
145 Copying file m4/strdup.m4
146 Copying file m4/string_h.m4
147 Creating lib/Makefile.am
148 Creating m4/gnulib-cache.m4
149 Creating m4/gnulib-comp.m4
152 You may need to add #include directives for the following .h files.
156 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
157 - mention "lib" in SUBDIRS in Makefile.am,
158 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
159 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
160 - invoke gl_INIT in ./configure.ac.
164 By default, the source code is copied into @file{lib/} and the M4
165 macros in @file{m4/}. You can override these paths by using
166 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
167 modules also provide other files necessary for building. These files
168 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
169 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
170 neither is specified, the current directory is assumed.
172 @code{gnulib-tool} can make symbolic links instead of copying the
173 source files. The option to specify for this is @samp{--symlink}, or
174 @samp{-s} for short. This can be useful to save a few kilobytes of disk
175 space. But it is likely to introduce bugs when @code{gnulib} is updated;
176 it is more reliable to use @samp{gnulib-tool --update} (see below)
177 to update to newer versions of @code{gnulib}. Furthermore it requires
178 extra effort to create self-contained tarballs, and it may disturb some
179 mechanism the maintainer applies to the sources. For these reasons,
180 this option is generally discouraged.
182 @code{gnulib-tool} will overwrite any preexisting files, in
183 particular @file{Makefile.am}. It is also possible to separate the
184 generated @file{Makefile.am} content (for building the gnulib library)
185 into a separate file, say @file{gnulib.mk}, that can be included by your
186 handwritten @file{Makefile.am}, but this is a more advanced use of
189 Consequently, it is a good idea to choose directories that are not
190 already used by your projects, to separate gnulib imported files from
191 your own files. This approach is also useful if you want to avoid
192 conflicts between other tools (e.g., @code{gettextize} that also copy
193 M4 files into your package. Simon Josefsson successfully uses a source
194 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
197 After the @samp{--import} option on the command line comes the list of
198 Gnulib modules that you want to incorporate in your package. The names
199 of the modules coincide with the filenames in Gnulib's @file{modules/}
202 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
203 will automatically add the needed modules as well; you need not list
204 them explicitly. @code{gnulib-tool} will also memorize which dependent
205 modules it has added, so that when someday a dependency is dropped, the
206 implicitly added module is dropped as well (unless you have explicitly
207 requested that module).
209 If you want to cut a dependency, i.e., not add a module although one of
210 your requested modules depends on it, you may use the option
211 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
212 possible. Of course, you will then need to implement the same interface
213 as the removed module.
215 A few manual steps are required to finish the initial import.
216 @code{gnulib-tool} printed a summary of these steps.
218 First, you must ensure Autoconf can find the macro definitions in
219 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
220 your top-level @file{Makefile.am} file, as in:
223 ACLOCAL_AMFLAGS = -I m4
226 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
227 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
228 as possible after verifying that the C compiler is working.
229 Typically, this is immediately after @code{AC_PROG_CC}, as in:
238 The core part of the gnulib checks are done by the macro
239 @code{gl_INIT}. Place it further down in the file, typically where
240 you normally check for header files or functions. It must come after
241 other checks which may affect the compiler invocation, such as
242 @code{AC_MINIX}. For example:
251 @code{gl_INIT} will in turn call the macros related with the
252 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
253 or Autoconf or Automake macros like @code{AC_FUNC_ALLOCA} or
254 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
255 when you use the corresponding gnulib modules.
257 You must also make sure that the gnulib library is built. Add the
258 @code{Makefile} in the gnulib source base directory to
259 @code{AC_CONFIG_FILES}, as in:
262 AC_CONFIG_FILES(... lib/Makefile ...)
265 You must also make sure that @code{make} will recurse into the gnulib
266 directory. To achieve this, add the gnulib source base directory to a
267 @code{SUBDIRS} Makefile.am statement, as in:
273 or if you, more likely, already have a few entries in @code{SUBDIRS},
274 you can add something like:
280 Finally, you have to add compiler and linker flags in the appropriate
281 source directories, so that you can make use of the gnulib library.
282 Since some modules (@samp{getopt}, for example) may copy files into
283 the build directory, @file{top_builddir/lib} is needed as well
284 as @file{top_srcdir/lib}. For example:
288 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
294 Don't forget to @code{#include} the various header files. In this
295 example, you would need to make sure that @samp{#include <string.h>}
296 is evaluated when compiling all source code files, that want to make
297 use of @code{strdup}.
299 In the usual case where Autoconf is creating a @file{config.h} file,
300 you should include @file{config.h} first, before any other include
301 file. That way, for example, if @file{config.h} defines
302 @samp{restrict} to be the empty string on a non-C99 host, or a macro
303 like @samp{_FILE_OFFSET_BITS} that affects the layout of data
304 structures, the definition is consistent for all include files.
305 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
306 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
307 effect, if defined after the first system header file is included.
309 Finally, note that you cannot use @code{AC_LIBOBJ} or
310 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
311 resulting object files to be automatically added to @file{lib/libgnu.a}.
312 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
313 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
314 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
315 is built from the contents of a different variable, usually
316 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
319 @node Modified imports
320 @section Modified imports
322 You can at any moment decide to use Gnulib differently than the last time.
324 There are two ways to change how Gnulib is used. Which one you'll use,
325 depends on where you keep track of options and module names that you pass
326 to @code{gnulib-tool}.
330 If you store the options and module names in a file under your own
331 control, such as @file{autogen.sh}, @file{bootstrap},
332 @file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool}
333 again, with modified options and more or fewer module names.
336 @code{gnulib-tool} remembers which modules were used last time. If you
337 want to rely on @code{gnulib-tool}'s own memory of the last used
338 options and module names, you can use the commands
339 @command{gnulib-tool --add-import} and
340 @command{gnulib-tool --remove-import}.
342 So, if you only want to use more Gnulib modules, simply invoke
343 @command{gnulib-tool --add-import @var{new-modules}}. The list of
344 modules that you pass after @samp{--add-import} is @emph{added} to the
345 previous list of modules.
347 Similarly, if you want to use fewer Gnulib modules, simply invoke
348 @command{gnulib-tool --remove-import @var{unneeded-modules}}. The list
349 of modules that you pass after @samp{--remove-import} is @emph{removed}
350 from the previous list of modules. Note that if a module is then still
351 needed as dependency of other modules, it will be used nevertheless.
352 If you want to @emph{really} not use a module any more, regardless of
353 whether other modules may need it, you need to use the @samp{--avoid}
356 For other changes, such as different choices of @samp{--lib},
357 @samp{--source-base} or @samp{--aux-dir}, the normal way is to
358 modify manually the file @file{gnulib-cache.m4} in the M4 macros
359 directory, then launch @samp{gnulib-tool --add-import}.
361 The only change for which this doesn't work is a change of the
362 @samp{--m4-base} directory. Because, when you pass a different value of
363 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
364 @file{gnulib-cache.m4} file any more. A possible solution is to
365 manually copy the @file{gnulib-cache.m4} into the new M4 macro directory.
367 In the @file{gnulib-cache.m4} file, the macros have the following meaning:
370 The argument is a space separated list of the requested modules, not including
374 The argument is a space separated list of modules that should not be used,
375 even if they occur as dependencies. Corresponds to the @samp{--avoid}
376 command line argument.
379 The argument is the relative file name of the directory containing the gnulib
380 source files (mostly *.c and *.h files). Corresponds to the
381 @samp{--source-base} command line argument.
384 The argument is the relative file name of the directory containing the gnulib
385 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
389 The argument is the relative file name of the directory containing the gnulib
390 unit test files. Corresponds to the @samp{--tests-base} command line argument.
393 The argument is the name of the library to be created. Corresponds to the
394 @samp{--lib} command line argument.
397 The presence of this macro without arguments corresponds to the @samp{--lgpl}
398 command line argument. The presence of this macro with an argument (whose
399 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
403 The presence of this macro corresponds to the @samp{--libtool} command line
404 argument and to the absence of the @samp{--no-libtool} command line argument.
405 It takes no arguments.
407 @item gl_MACRO_PREFIX
408 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
409 file. Corresponds to the @samp{--macro-prefix} command line argument.
415 @section Simple update
417 When you want to update to a more recent version of Gnulib, without
418 changing the list of modules or other parameters, a simple call
422 $ gnulib-tool --add-import
426 This will create, update or remove files, as needed.
428 Note: From time to time, changes are made in Gnulib that are not backward
429 compatible. When updating to a more recent Gnulib, you should consult
430 Gnulib's @file{NEWS} file to check whether the incompatible changes affect
435 @section Changing your sources for use with Gnulib
437 When you use Gnulib, you need to make some small changes to your source code
441 @subsection -I options
443 Gnulib contains some header file overrides. This means that when building
444 on systems with deficient header files in @file{/usr/include/}, it may create
445 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
446 the build directory. In the other source directories of your package you
447 will usually pass @samp{-I} options to the compiler, so that these Gnulib
448 substitutes are visible and take precedence over the files in
449 @file{/usr/include/}.
451 @node Include <config.h>
452 @subsection Include <config.h>
454 These Gnulib substitute header files rely on @file{<config.h>} being
455 already included. Furthermore @file{<config.h>} must be the first include
456 in every compilation unit. This means that to @emph{all your source files}
457 and likely also to @emph{all your tests source files} you need to add an
458 @samp{#include <config.h>} at the top. Which source files are affected?
459 Exactly those whose compilation includes a @samp{-I} option that refers to
460 the Gnulib library directory.
462 This is annoying, but inevitable: On many systems, @file{<config.h>} is
463 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
464 and these flags have no effect after any system header file has been included.
466 @node Style of #include statements
467 @subsection Style of #include statements
469 When including including specific header files, you need to use the
470 @samp{#include <...>} syntax, not the @samp{#include "..."} syntax.
471 This is true for the following POSIX or ISO C standardized header files:
473 @item @code{arpa/inet.h}
474 @item @code{assert.h}
476 @item @code{dirent.h}
481 @item @code{fnmatch.h}
484 @item @code{inttypes.h}
485 @item @code{langinfo.h}
486 @item @code{limits.h}
487 @item @code{locale.h}
489 @item @code{monetary.h}
491 @item @code{net/if.h}
492 @item @code{netinet/in.h}
494 @item @code{pthread.h}
496 @item @code{search.h}
497 @item @code{signal.h}
499 @item @code{stdalign.h}
500 @item @code{stdarg.h}
501 @item @code{stddef.h}
502 @item @code{stdint.h}
504 @item @code{stdlib.h}
505 @item @code{string.h}
506 @item @code{strings.h}
507 @item @code{sys/msg.h}
508 @item @code{sys/resource.h}
509 @item @code{sys/select.h}
510 @item @code{sys/sem.h}
511 @item @code{sys/shm.h}
512 @item @code{sys/socket.h}
513 @item @code{sys/stat.h}
514 @item @code{sys/time.h}
515 @item @code{sys/times.h}
516 @item @code{sys/types.h}
517 @item @code{sys/uio.h}
518 @item @code{sys/utsname.h}
519 @item @code{sys/wait.h}
520 @item @code{termios.h}
521 @item @code{threads.h}
524 @item @code{unistd.h}
527 @item @code{wctype.h}
530 as well as for the following header files that exist in the GNU C library
531 but are not standardized:
533 @item @code{alloca.h}
535 @item @code{getopt.h}
536 @item @code{malloc.h}
539 @item @code{selinux/selinux.h}
540 @item @code{sys/file.h}
541 @item @code{sys/ioctl.h}
542 @item @code{sys/random.h}
543 @item @code{sysexits.h}
547 The reason for this requirement is that for these header files, the Gnulib
548 override uses @code{#include_next} to include the system-provided header
549 of the same name, and @code{#include_next} may not work right with the
550 @samp{#include "..."} syntax.
552 @node Link-time requirements
553 @section Changing your link commands for use with Gnulib
555 When you use Gnulib, you need to augment the set of libraries against which
556 your programs and libraries are linked. This is done by augmenting the
557 Automake variable @code{LDADD} (for all programs) or
558 @code{@var{prog}_LDADD} (for a single program @code{@var{prog}}) or
559 @code{@var{library}_la_LIBADD} (for a single library @code{@var{library}.la}).
561 What do you need to add to this Automake variable?
564 The reference to the Gnulib library. In the example of section
565 @ref{Initial import}, this would be @code{lib/libgnu.a} for source in the
566 top-level directory, or @code{../lib/libgnu.a} for source in a sibling
567 directory of @code{lib/}.
570 References to additional libraries, brought in by some of the Gnulib
571 modules that you use (directly or indirectly). The complete list of such
572 libraries is printed when you invoke @code{gnulib-tool}. Alternatively,
573 you can retrieve the set of additional libraries required by a specific
574 Gnulib module by running
576 ./gnulib-tool --extract-recursive-link-directive @var{module}
579 Beware: By looking into the module description file @code{modules/@var{module}}
582 ./gnulib-tool --extract-link-directive @var{module}
585 you would miss the link dependencies of indirectly used modules.
589 @node Finding POSIX substitutes
590 @section Finding recommended ISO C and POSIX function substitutes
592 Gnulib contains a wealth of portability workarounds for ISO C and POSIX
593 functions. They are listed in detail in the chapter @ref{Function Substitutes}.
594 If you want to know which function substitutes are recommended for your
595 package, you can search your source code for ISO C and POSIX functions
596 that it uses and read the corresponding sections of said documentation
597 chapter. But this is a tedious task. Here is an alternative approach
598 that makes this task easier.
602 Add the Gnulib module @samp{posixcheck} to the Gnulib imports of your package,
603 as described earlier in this chapter.
606 Do a @code{make distclean} if you previously built in the top-level directory.
607 Then regenerate the Autotools-generated parts of the package.
610 On a glibc system, build your package. Pay attention to the compiler warnings.
611 Warnings are generated for uses of ISO C and POSIX functions that have
612 portability problems or other important pitfalls and for which you have not yet
613 imported the corresponding Gnulib module. If you get, say, a warning
614 ``warning: call to 'close' declared with attribute warning: close does not
615 portably work on sockets - use gnulib module close for portability'',
616 put @samp{close} on your list of modules to import.
619 Add the modules you noted to the Gnulib imports of your package.
622 Optionally, you can do the same steps again, and make sure that there are no
623 warnings left except those that you want to intentionally ignore.
626 Finally, remove the Gnulib module @samp{posixcheck} from the Gnulib imports,
627 and run @code{make distclean}.
631 @node Modified build rules
632 @section Modifying the build rules of a Gnulib import directory
634 In some cases, you may want to set additional compiler options for
635 use within the Gnulib import directory. For example, the
636 @samp{relocatable} module operates better if you define the C macros
637 @code{ENABLE_COSTLY_RELOCATABLE} and @code{INSTALLDIR} during its
640 There are two ways to do so: Use of the @code{gnulib-tool} option
641 @code{--makefile-name}, and a kitchen-sink module.
643 With the @code{gnulib-tool} option @code{--makefile-name}, you are
644 telling @code{gnulib-tool} to generate an includable @code{Makefile.am}
645 portion, rather than a self-contained @code{Makefile.am}. For example,
646 when you use @code{--makefile-name=Makefile.gnulib}, @code{gnulib-tool}
647 will generate @code{Makefile.gnulib}, and you will provide a
648 hand-written @code{Makefile.am} that includes @code{Makefile.gnulib}
649 through a line such as
651 include Makefile.gnulib
653 Before this include, you need to initialize this set of @code{Makefile.am}
657 @code{AUTOMAKE_OPTIONS}
661 @code{noinst_HEADERS}
663 @code{noinst_LIBRARIES}
665 @code{noinst_LTLIBRARIES}
667 @code{pkgdata_DATA} (only with Automake @geq{} 1.11.4)
675 @code{MOSTLYCLEANFILES}
677 @code{MOSTLYCLEANDIRS}
681 @code{DISTCLEANFILES}
683 @code{MAINTAINERCLEANFILES}
689 @code{AUTOMAKE_OPTIONS} should be initialized as described in
690 @ref{Options,,Changing Automake's Behavior,automake,GNU Automake}.
691 The other variables can be initialized to empty. However, you will most
692 likely want to initialize some of them with non-empty values, in order
693 to achieve the desired customization.
695 The other approach, the kitchen-sink module, is more advanced. See
696 chapter @ref{Extending Gnulib}.
699 @node Non-recursive make
700 @section Building directly from the top-level directory
702 By default, the Gnulib import directory will contain a generated
703 @code{Makefile.am} file. After configuring, this produces a generated
704 @code{Makefile} in this directory. As a consequence, the build from the
705 top-level directory will use a recursive @code{make} invocation for this
708 Some people prefer a build system where the @code{Makefile} in the
709 top-level directory directly builds the artifacts in the subdirectories,
710 without an intermediate @code{make} invocation. This is called
711 ``non-recursive make'' and is supported by Automake. For more details,
712 see @url{https://autotools.io/automake/nonrecursive.html}.
714 Gnulib supports this flavour of build system too. To use it, pass two
715 options to @code{gnulib-tool}: @samp{--makefile-name} and
716 @samp{--automake-subdir}.
718 With the @code{gnulib-tool} option @samp{--makefile-name}, you are
719 telling @code{gnulib-tool} to generate an includable @code{Makefile.am}
720 portion in the Gnulib import directory, rather than a self-contained
721 @code{Makefile.am}. For example, when you use
722 @samp{--makefile-name=Makefile.gnulib}, @code{gnulib-tool} will generate
723 @code{Makefile.gnulib}.
725 With the option @samp{--automake-subdir}, you are telling
726 @code{gnulib-tool} that you will include the generated file from the
727 @code{Makefile.am} in the top-level directory, rather than from a
728 @code{Makefile.am} in the same directory. For example, the top-level
729 @code{Makefile.am} might contain this directive:
732 include lib/Makefile.gnulib
735 The option @samp{--automake-subdir} is also supported in combination
736 with @samp{--with-tests} (@pxref{Unit tests}). Note that in this case,
737 however, the generated unit tests directory will contains a
738 @code{Makefile.am} and thus use a recursive @code{make} invocation.
739 This is not a problem, since the built artifacts of your package have
740 no dependencies towards the Gnulib unit tests, nor vice versa.
743 @node Multiple instances
744 @section Using Gnulib for both a library and a program
746 Your project might build both a library and some accompanying programs
747 in the same source tree. In that case you might want to use different
748 modules for the library than for the programs. Typically the programs
749 might want to make use of @code{getopt-posix} or @code{version-etc},
750 while the library wants to stay clear of these modules for technical
751 or licensing reasons.
753 Let's assume that your project contains a @file{lib} directory where
754 the source of the library resides and a @file{src} directory for the
755 sources of the programs as follows.
769 You can now add two instances of Gnulib to your project in separate
773 ~/src/libfoo$ gnulib-tool --import --lib=libgnu --source-base=gnulib \
774 --m4-base=gnulib/m4 --macro-prefix=gl strndup
775 ~/src/libfoo$ gnulib-tool --import --lib=libgnutools \
776 --source-base=src/gnulib --m4-base=src/gnulib/m4 \
777 --macro-prefix=gl_tools getopt-gnu
780 The first one will import the module @code{strndup} in @file{gnulib}
781 and the second one will import @code{getopt-gnu} in @file{src/gnulib}
782 and you will end up with the following source tree (many files omitted
783 in the interest of brevity):
804 As discussed in @ref{Unit tests}, you may not use @samp{--with-tests}
805 for this project since the @code{configure.ac} is shared.
807 Integration with your code is basically the same as outlined in
808 @ref{Initial import} with the one exception that you have to add both
809 the macro @code{gl_EARLY} and the macro @code{gl_tools_EARLY} to your
810 @file{configure.ac} (and of course also both macros @code{gl_INIT} and
811 @code{gl_tools_INIT}). Obviously the name of the second macro is
812 dependent on the value of the @option{--macro-prefix} option in your
813 @command{gnulib-tool} invocation.
827 Also as outlined in @ref{Initial import} you will have to add compiler
828 and linker flags. For the library you might have to add something
829 along the line of the following to your @file{Makefile.am}:
833 AM_CPPFLAGS = -I$(top_srcdir)/gnulib -I$(top_builddir)/gnulib
835 libfoo_la_LIBADD = $(top_builddir)/gnulib/libgnu.la
839 Correspondingly for the programs you will have to add something like
844 AM_CPPFLAGS = -I$(top_srcdir)/src/gnulib -I$(top_builddir)/src/gnulib
846 LDADD = $(top_builddir)/src/gnulib/libgnutools.la
850 The name of the library that you have pass in the linker option
851 depends on the @option{--lib} option in @command{gnulib-tool}
855 @node gettextize and autopoint
856 @section Caveat: @code{gettextize} and @code{autopoint} users
858 @cindex gettextize, caveat
859 @cindex autopoint, caveat
860 The programs @code{gettextize} and @code{autopoint}, part of
861 GNU @code{gettext}, import or update the internationalization infrastructure.
862 Some of this infrastructure, namely ca.@: 20 Autoconf macro files and the
863 @file{config.rpath} file, is also contained in Gnulib and may be imported
864 by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint}
865 will therefore overwrite some of the files that @code{gnulib-tool} has
866 imported, and vice versa.
868 Avoiding to use @code{gettextize} (manually, as package maintainer) or
869 @code{autopoint} (as part of a script like @code{autoreconf} or
870 @code{autogen.sh}) is not the solution: These programs also import the
871 infrastructure in the @file{po/} and optionally in the @file{intl/} directory.
873 The copies of the conflicting files in Gnulib are more up-to-date than
874 the copies brought in by @code{gettextize} and @code{autopoint}. When a
875 new @code{gettext} release is made, the copies of the files in Gnulib will
876 be updated immediately.
878 The choice of which version of gettext to require depends on the needs
879 of your package. For a package that wants to comply to GNU Coding
880 Standards, the steps are:
884 When you run @code{gettextize}, always use the @code{gettextize} from the
885 matching GNU gettext release. For the most recent Gnulib checkout, this is
886 the newest release found on @url{https://ftp.gnu.org/gnu/gettext/}. For an
887 older Gnulib snapshot, it is the release that was the most recent release
888 at the time the Gnulib snapshot was taken.
891 After running @code{gettextize}, invoke @code{gnulib-tool} and import
892 the @code{gettext} module. Also, copy the latest version of gnulib's
893 @file{build-aux/po/Makefile.in.in} to your @file{po/} directory (this
894 is done for you if you use gnulib's @file{autogen.sh} script).
897 If you get an error message like
898 @code{*** error: gettext infrastructure mismatch:
899 using a Makefile.in.in from gettext version ...
900 but the Autoconf macros are from gettext version ...},
901 it means that a new GNU gettext release was made, and its Autoconf macros
902 were integrated into Gnulib and now mismatch the @file{po/} infrastructure.
903 In this case, fetch and install the new GNU gettext release and run
904 @code{gettextize} followed by @code{gnulib-tool}.
907 On the other hand, if your package is not as concerned with compliance
908 to the latest standards, but instead favors development on stable
909 environments, the steps are:
913 Determine the oldest version of @code{gettext} that you intend to
914 support during development (at this time, gnulib recommends going no
915 older than version 0.17). Run @code{autopoint} (not
916 @code{gettextize}) to copy infrastructure into place (newer versions
917 of gettext will install the older infrastructure that you requested).
920 Invoke @code{gnulib-tool}, and import the @code{gettext-h} module.
923 Regardless of which approach you used to get the infrastructure in
924 place, the following steps must then be used to preserve that
925 infrastructure (gnulib's @file{autogen.sh} script follows these rules):
929 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
933 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
934 not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT}
935 environment variable, like this:
937 $ env AUTOPOINT=true autoreconf --install
943 @section Handling Gnulib's own message translations
945 Gnulib provides some functions that emit translatable messages using GNU
946 @code{gettext}. The @samp{gnulib} domain at the
947 @url{https://translationproject.org/, Translation Project} collects
948 translations of these messages, which you should incorporate into your
951 There are two basic ways to achieve this. The first, and older, method
952 is to list all the source files you use from Gnulib in your own
953 @file{po/POTFILES.in} file. This will cause all the relevant
954 translatable strings to be included in your POT file. When you send
955 this POT file to the Translation Project, translators will normally fill
956 in the translations of the Gnulib strings from their ``translation
957 memory'', and send you back updated PO files.
959 However, this process is error-prone: you might forget to list some
960 source files, or the translator might not be using a translation memory
961 and provide a different translation than another translator, or the
962 translation might not be kept in sync between Gnulib and your package.
963 It is also slow and causes substantial extra work, because a human
964 translator must be in the loop for each language and you will need to
965 incorporate their work on request.
967 For these reasons, a new method was designed and is now recommended. If
968 you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}}
969 options to @code{gnulib-tool}, then @code{gnulib-tool} will create a
970 separate directory with its own @file{POTFILES.in}, and fetch current
971 translations directly from the Translation Project (using
972 @command{rsync} or @command{wget}, whichever is available).
973 The POT file in this directory will be called
974 @file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the
975 @code{--po-domain} option (typically the same as the package name).
976 This causes these translations to reside in a separate message domain,
977 so that they do not clash either with the translations for the main part
978 of your package nor with those of other packages on the system that use
979 possibly different versions of Gnulib.
980 When you use these options, the functions in Gnulib are built
981 in such a way that they will always use this domain regardless of the
982 default domain set by @code{textdomain}.
984 In order to use this method, you must---in each program that might use
985 Gnulib code---add an extra line to the part of the program that
986 initializes locale-dependent behavior. Where you would normally write
991 setlocale (LC_ALL, "");
992 bindtextdomain (PACKAGE, LOCALEDIR);
993 textdomain (PACKAGE);
998 you should add an additional @code{bindtextdomain} call to inform
999 gettext of where the MO files for the extra message domain may be found:
1003 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
1007 (This example assumes that the @var{domain} that you specified
1008 to @code{gnulib-tool} is the same as the value of the @code{PACKAGE}
1009 preprocessor macro.)
1011 Since you do not change the @code{textdomain} call, the default message
1012 domain for your program remains the same and your own use of @code{gettext}
1013 functions will not be affected.
1017 @section Integration with Version Control Systems
1019 If a project stores its source files in a version control system (VCS),
1020 such as CVS, Subversion, or Git, one needs to decide which files to commit.
1022 In principle, all files created by @code{gnulib-tool}, except
1023 @file{gnulib-cache.m4}, can be treated like generated source files,
1024 like for example a @file{parser.c} file generated from
1025 @file{parser.y}. Alternatively, they can be considered source files
1026 and updated manually.
1028 Here are the three different approaches in common use. Each has its
1029 place, and you should use whichever best suits your particular project
1030 and development methods.
1034 In projects which commit all source files, whether generated or not,
1035 into their VCS, the @code{gnulib-tool} generated files should all be
1036 committed. In this case, you should pass the option
1037 @samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
1038 VCS-related files such as @file{.gitignore}.
1040 Gnulib also contains files generated by @command{make} (and removed by
1041 @code{make clean}), using information determined by
1042 @command{configure}. For a Gnulib source file of the form
1043 @file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
1044 @command{make}-generated file. These should @emph{not} be checked
1045 into the VCS, but instead added to @file{.gitignore} or equivalent.
1048 In projects which customarily omit from their VCS all files that are
1049 generated from other source files, none of these files and directories
1050 are added into the VCS@. As described in @ref{Modified imports}, there
1051 are two ways to keep track of options and module names that are passed
1052 to @code{gnulib-tool}. The command for restoring the omitted files
1057 If they are stored in a file other than @code{gnulib-cache.m4}, such as
1058 @file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar,
1059 the restoration command is the entire @code{gnulib-tool ... --import ...}
1060 invocation with all options and module names.
1063 If the project relies on @code{gnulib-tool}'s memory of the last used
1064 options and module names, then the file @file{gnulib-cache.m4} in the M4
1065 macros directory must be added to the VCS, and the restoration command
1069 $ gnulib-tool --update
1072 The @samp{--update} option operates much like the @samp{--add-import}
1073 option, but it does not offer the possibility to change the way Gnulib is
1074 used. Also it does not report in the ChangeLogs the files that it had to
1075 add because they were missing.
1079 Most packages nowadays use the first among these two approaches. Over
1080 time, three ways of handling version control have evolved.
1082 In the cases (A) and (B), a ``git submodule'' is used to reference
1083 the precise commit of the gnulib repository, so that each developer
1084 running @samp{./bootstrap --pull} or @file{autopull.sh}
1085 will get the same version of all gnulib-provided
1088 The alternative is to always follow the newest Gnulib automatically.
1089 Note that this can cause breakages at unexpected moments, namely
1090 when a broken commit is pushed in Gnulib. It does not happen often,
1095 In this approach, the developers use a git submodule manually.
1097 The location of the submodule can be chosen to fit the package's needs;
1098 here's how to initially create the submodule in the directory @file{gnulib}:
1101 $ git submodule add -- https://git.savannah.gnu.org/git/gnulib.git gnulib
1105 Thereafter, the developer will run this command to update the
1106 submodule to the recorded checkout level:
1109 $ git submodule update --init gnulib
1113 Use this sequence to update to a newer version of gnulib:
1116 $ git submodule update --remote gnulib
1118 $ ./bootstrap --bootstrap-sync
1121 If multiple submodules are used, the following may be useful:
1124 $ git config alias.syncsub "submodule foreach git pull origin master"
1129 In this approach, the @code{build-aux/bootstrap} or @code{autopull.sh}
1130 program (see @ref{Developer tools}) is used to aid a developer in
1131 using this setup. You copy this program (and if it's
1132 @code{autopull.sh}, its companion files) into your package and place
1133 the copy or copies under version control. The program can be
1134 customized using @file{bootstrap.conf} which you also put under
1138 In this approach, you write the @code{autopull.sh} and @code{autogen.sh}
1141 @code{autopull.sh} is most easily written as a script that
1144 ./gitsub.sh pull || exit 1
1147 where @code{gitsub.sh} is described in @ref{Developer tools}.
1149 @code{autogen.sh} typically contains an explicit @code{gnulib-tool}
1150 invocation, followed by
1154 && autoheader && touch config.h.in \
1155 && automake --add-missing --copy \
1156 && rm -rf autom4te.cache \
1162 Some projects take a ``middle road'': they do commit Gnulib source
1163 files as in the first approach, but they do not commit other derived
1164 files, such as a @code{Makefile.in} generated by Automake. This
1165 increases the size and complexity of the repository, but can help
1166 occasional contributors by not requiring them to have a full Gnulib
1167 checkout to do a build, and all developers by ensuring that all
1168 developers are working with the same version of Gnulib in the
1169 repository. It also supports multiple Gnulib instances within a
1170 project. It remains important not to commit the
1171 @command{make}-generated files, as described above.
1177 @section Bundling the unit tests of the Gnulib modules
1179 You can bundle the unit tests of the Gnulib modules together with your
1180 package, through the @samp{--with-tests} option. Together with
1181 @samp{--with-tests}, you also specify the directory for these tests
1182 through the @samp{--tests-base} option. Of course, you need to add this
1183 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of
1184 the parent directory.
1186 The advantage of having the unit tests bundled is that when your program
1187 has a problem on a particular platform, running the unit tests may help
1188 determine quickly if the problem is on Gnulib's side or on your package's
1189 side. Also, it helps verifying Gnulib's portability, of course.
1191 The unit tests will be compiled and run when the user runs @samp{make check}.
1192 When the user runs only @samp{make}, the unit tests will not be compiled.
1194 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory
1195 after the directory containing the other tests, not before:
1198 SUBDIRS = gnulib-lib src man tests gnulib-tests
1202 This will ensure that on platforms where there are test failures in either
1203 directory, users will see and report the failures from the tests of your
1206 Note: In packages which use more than one invocation of @code{gnulib-tool}
1207 in the scope of the same @code{configure.ac}, you cannot use
1208 @samp{--with-tests}. You will have to use a separate @code{configure.ac}
1212 @node Conditional dependencies
1213 @section Avoiding unnecessary checks and compilations
1215 @cindex conditional dependencies
1216 In some cases, a module is needed by another module only on specific
1217 platforms. But when a module is present, its Autoconf checks are always
1218 executed, and its @code{Makefile.am} additions are always enabled. So
1219 it can happen that some Autoconf checks are executed and some source files
1220 are compiled, although no other module needs them on this particular
1221 platform, just @emph{in case} some other module would need them.
1223 The option @samp{--conditional-dependencies} enables an optimization of
1224 configure checks and @code{Makefile.am} snippets that avoids this. With
1225 this option, whether a module is considered ``present'' is no longer decided
1226 when @code{gnulib-tool} is invoked, but later, when @code{configure} is run.
1227 This applies to modules that were added as dependencies while
1228 @code{gnulib-tool} was run; modules that were passed on the command line
1229 explicitly are always ``present''.
1231 For example, the @code{timegm} module needs, on platforms
1232 where the system's @code{timegm} function is missing or buggy, a replacement
1233 that is based on a function @code{mktime_internal}. The module
1234 @code{mktime-internal} that provides this function provides it on all
1235 platforms. So, by default, the file @file{mktime-internal.c} will be
1236 compiled on all platforms, even on glibc and BSD systems which have a
1237 working @code{timegm} function. When the option
1238 @samp{--conditional-dependencies} is given, on the other hand, and if
1239 @code{mktime-internal} was not explicitly required on the command line,
1240 the file @file{mktime-internal.c} will only be compiled on the platforms
1241 where the @code{timegm} needs them.
1243 Conditional dependencies are specified in the module description by putting
1244 the condition on the same line as the dependent module, enclosed in brackets.
1245 The condition is a boolean shell expression that can assume that the
1246 @code{configure.ac} snippet from the module description has already been
1247 executed. In the example above, the dependency from @code{timegm} to
1248 @code{mktime-internal} is written like this:
1253 mktime-internal [test $HAVE_TIMEGM = 0 || test $REPLACE_TIMEGM = 1]
1257 Note: The option @samp{--conditional-dependencies} cannot be used together
1258 with the option @samp{--with-tests}. It also cannot be used when a package
1259 uses @code{gnulib-tool} for several subdirectories, with different values
1260 of @samp{--source-base}, in the scope of a single @code{configure.ac} file.