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 or add an AC_CONFIG_MACRO_DIRS([m4]) invocation in ./configure.ac,
160 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
161 - invoke gl_INIT in ./configure.ac.
165 By default, the source code is copied into @file{lib/} and the M4
166 macros in @file{m4/}. You can override these paths by using
167 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
168 modules also provide other files necessary for building. These files
169 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
170 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
171 neither is specified, the current directory is assumed.
173 @code{gnulib-tool} can make symbolic links instead of copying the
174 source files. The option to specify for this is @samp{--symlink}, or
175 @samp{-s} for short. This can be useful to save a few kilobytes of disk
176 space. But it is likely to introduce bugs when @code{gnulib} is updated;
177 it is more reliable to use @samp{gnulib-tool --update} (see below)
178 to update to newer versions of @code{gnulib}. Furthermore it requires
179 extra effort to create self-contained tarballs, and it may disturb some
180 mechanism the maintainer applies to the sources. For these reasons,
181 this option is generally discouraged.
183 @code{gnulib-tool} will overwrite any preexisting files, in
184 particular @file{Makefile.am}. It is also possible to separate the
185 generated @file{Makefile.am} content (for building the gnulib library)
186 into a separate file, say @file{gnulib.mk}, that can be included by your
187 handwritten @file{Makefile.am}, but this is a more advanced use of
190 Consequently, it is a good idea to choose directories that are not
191 already used by your projects, to separate gnulib imported files from
192 your own files. This approach is also useful if you want to avoid
193 conflicts between other tools (e.g., @code{gettextize} that also copy
194 M4 files into your package. Simon Josefsson successfully uses a source
195 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
198 After the @samp{--import} option on the command line comes the list of
199 Gnulib modules that you want to incorporate in your package. The names
200 of the modules coincide with the filenames in Gnulib's @file{modules/}
203 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
204 will automatically add the needed modules as well; you need not list
205 them explicitly. @code{gnulib-tool} will also memorize which dependent
206 modules it has added, so that when someday a dependency is dropped, the
207 implicitly added module is dropped as well (unless you have explicitly
208 requested that module).
210 If you want to cut a dependency, i.e., not add a module although one of
211 your requested modules depends on it, you may use the option
212 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
213 possible. Of course, you will then need to implement the same interface
214 as the removed module.
216 A few manual steps are required to finish the initial import.
217 @code{gnulib-tool} printed a summary of these steps.
219 First, you must ensure Autoconf can find the macro definitions in
220 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
221 your top-level @file{Makefile.am} file, as in:
224 ACLOCAL_AMFLAGS = -I m4
227 Alternatively, add an @code{AC_CONFIG_MACRO_DIRS} invocation in your
228 @file{configure.ac} file, as in:
231 AC_CONFIG_MACRO_DIRS([m4])
234 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
235 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
236 as possible after verifying that the C compiler is working.
237 Typically, this is immediately after @code{AC_PROG_CC}, as in:
246 The core part of the gnulib checks are done by the macro
247 @code{gl_INIT}. Place it further down in the file, typically where
248 you normally check for header files or functions. It must come after
249 other checks which may affect the compiler invocation, such as
250 @code{AC_MINIX}. For example:
259 @code{gl_INIT} will in turn call the macros related with the
260 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
261 or Autoconf or Automake macros like @code{AC_FUNC_ALLOCA} or
262 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
263 when you use the corresponding gnulib modules.
265 You must also make sure that the gnulib library is built. Add the
266 @code{Makefile} in the gnulib source base directory to
267 @code{AC_CONFIG_FILES}, as in:
270 AC_CONFIG_FILES(... lib/Makefile ...)
273 You must also make sure that @code{make} will recurse into the gnulib
274 directory. To achieve this, add the gnulib source base directory to a
275 @code{SUBDIRS} Makefile.am statement, as in:
281 or if you, more likely, already have a few entries in @code{SUBDIRS},
282 you can add something like:
288 Finally, you have to add compiler and linker flags in the appropriate
289 source directories, so that you can make use of the gnulib library.
290 Since some modules (@samp{getopt}, for example) may copy files into
291 the build directory, @file{top_builddir/lib} is needed as well
292 as @file{top_srcdir/lib}. For example:
296 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
302 Don't forget to @code{#include} the various header files. In this
303 example, you would need to make sure that @samp{#include <string.h>}
304 is evaluated when compiling all source code files, that want to make
305 use of @code{strdup}.
307 In the usual case where Autoconf is creating a @file{config.h} file,
308 you should include @file{config.h} first, before any other include
309 file. That way, for example, if @file{config.h} defines
310 @samp{restrict} to be the empty string on a non-C99 host, or a macro
311 like @samp{_FILE_OFFSET_BITS} that affects the layout of data
312 structures, the definition is consistent for all include files.
313 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
314 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
315 effect, if defined after the first system header file is included.
317 Finally, note that you cannot use @code{AC_LIBOBJ} or
318 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
319 resulting object files to be automatically added to @file{lib/libgnu.a}.
320 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
321 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
322 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
323 is built from the contents of a different variable, usually
324 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
327 @node Modified imports
328 @section Modified imports
330 You can at any moment decide to use Gnulib differently than the last time.
332 There are two ways to change how Gnulib is used. Which one you'll use,
333 depends on where you keep track of options and module names that you pass
334 to @code{gnulib-tool}.
338 If you store the options and module names in a file under your own
339 control, such as @file{autogen.sh}, @file{bootstrap},
340 @file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool}
341 again, with modified options and more or fewer module names.
344 @code{gnulib-tool} remembers which modules were used last time. If you
345 want to rely on @code{gnulib-tool}'s own memory of the last used
346 options and module names, you can use the commands
347 @command{gnulib-tool --add-import} and
348 @command{gnulib-tool --remove-import}.
350 So, if you only want to use more Gnulib modules, simply invoke
351 @command{gnulib-tool --add-import @var{new-modules}}. The list of
352 modules that you pass after @samp{--add-import} is @emph{added} to the
353 previous list of modules.
355 Similarly, if you want to use fewer Gnulib modules, simply invoke
356 @command{gnulib-tool --remove-import @var{unneeded-modules}}. The list
357 of modules that you pass after @samp{--remove-import} is @emph{removed}
358 from the previous list of modules. Note that if a module is then still
359 needed as dependency of other modules, it will be used nevertheless.
360 If you want to @emph{really} not use a module any more, regardless of
361 whether other modules may need it, you need to use the @samp{--avoid}
364 For other changes, such as different choices of @samp{--lib},
365 @samp{--source-base} or @samp{--aux-dir}, the normal way is to
366 modify manually the file @file{gnulib-cache.m4} in the M4 macros
367 directory, then launch @samp{gnulib-tool --add-import}.
369 The only change for which this doesn't work is a change of the
370 @samp{--m4-base} directory. Because, when you pass a different value of
371 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
372 @file{gnulib-cache.m4} file any more. A possible solution is to
373 manually copy the @file{gnulib-cache.m4} into the new M4 macro directory.
375 In the @file{gnulib-cache.m4} file, the macros have the following meaning:
378 The argument is a colon separated list of local directories where
379 @code{gnulib-tool} will search before looking at gnulib's directory.
380 Corresponds to the @samp{--local-dir} command line argument.
383 The argument is a space separated list of the requested modules, not including
386 @item gl_WITH_OBSOLETE
387 The presence of this macro corresponds to the @samp{--with-obsolete} command
388 line argument. It takes no arguments.
390 @item gl_WITH_CXX_TESTS
391 The presence of this macro corresponds to the @samp{--with-c++-tests} command
392 line argument and to the absence of the @samp{--without-c++-tests} command line
393 argument. It takes no arguments.
395 @item gl_WITH_LONGRUNNING_TESTS
396 The presence of this macro corresponds to the @samp{--with-longrunning-tests}
397 command line argument and to the absence of the
398 @samp{--without-longrunning-tests} command line argument. It takes no
401 @item gl_WITH_PRIVILEGED_TESTS
402 The presence of this macro corresponds to the @samp{--with-longrunning-tests}
403 command line argument and to the absence of the
404 @samp{--without-longrunning-tests} command line argument. It takes no
407 @item gl_WITH_UNPORTABLE_TESTS
408 The presence of this macro corresponds to the @samp{--with-unportable-tests}
409 command line argument and to the absence of the
410 @samp{--without-unportable-tests} command line argument. It takes no arguments.
412 @item gl_WITH_ALL_TESTS
413 The presence of this macro corresponds to the @samp{--with-all-tests} command
414 line argument. It takes no arguments.
417 The argument is a space separated list of modules that should not be used,
418 even if they occur as dependencies. Corresponds to the @samp{--avoid}
419 command line argument.
422 The argument is the relative file name of the directory containing the gnulib
423 source files (mostly *.c and *.h files). Corresponds to the
424 @samp{--source-base} command line argument.
427 The argument is the relative file name of the directory containing the gnulib
428 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
432 The argument is the relative file name of the directory containing *.po files.
433 Corresponds to the @samp{--po-base} command line argument.
436 The argument is the relative file name of the directory containing documentation
437 files. Corresponds to the @samp{--doc-base} command line argument.
440 The argument is the relative file name of the directory containing the gnulib
441 unit test files. Corresponds to the @samp{--tests-base} command line argument.
444 The presence of this macro corresponds to the @samp{--with-tests} command line
445 argument. It takes no arguments.
448 The argument is the name of the library to be created. Corresponds to the
449 @samp{--lib} command line argument.
452 The presence of this macro without arguments corresponds to the @samp{--lgpl}
453 command line argument. The presence of this macro with an argument (whose
454 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
457 @item gl_MAKEFILE_NAME
458 The argument is the name of the makefile in the source-base and tests-base
459 directories. Corresponds to the @samp{--makefile-name} command line argument.
461 @item gl_TESTS_MAKEFILE_NAME
462 The argument is the name of the makefile in the tests-base directory.
463 Corresponds to the @samp{--tests-makefile-name} command line argument.
465 @item gl_AUTOMAKE_SUBDIR
466 The presence of this macro corresponds to the @samp{--automake-subdir} command
467 line argument. It takes no arguments.
469 @item gl_CONDITIONAL_DEPENDENCIES
470 The presence of this macro corresponds to the @samp{--conditional-dependencies}
471 command line argument and to the absence of the
472 @samp{--no-conditional-dependencies} command line argument. It takes no
476 The presence of this macro corresponds to the @samp{--libtool} command line
477 argument and to the absence of the @samp{--no-libtool} command line argument.
478 It takes no arguments.
480 @item gl_MACRO_PREFIX
481 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
482 file. Corresponds to the @samp{--macro-prefix} command line argument.
485 The argument is the prefix of the i18n domain, typically matching the package
486 name. Corresponds to the @samp{--po-domain} command line argument.
488 @item gl_WITNESS_C_MACRO
489 The argument is the C macro that is defined when the sources in this directory
490 are compiled or used. Corresponds to the @samp{--witness-c-macro} command line
494 The argument to this macro is @code{true} or @code{false}. The former
495 corresponds to the @samp{--vc-files} command line argument and the latter
496 corresponds to the @samp{--no-vc-files} command line argument.
502 @section Simple update
504 When you want to update to a more recent version of Gnulib, without
505 changing the list of modules or other parameters, a simple call
509 $ gnulib-tool --add-import
513 This will create, update or remove files, as needed.
515 Note: From time to time, changes are made in Gnulib that are not backward
516 compatible. When updating to a more recent Gnulib, you should consult
517 Gnulib's @file{NEWS} file to check whether the incompatible changes affect
522 @section Changing your sources for use with Gnulib
524 When you use Gnulib, you need to make some small changes to your source code
528 @subsection -I options
530 Gnulib contains some header file overrides. This means that when building
531 on systems with deficient header files in @file{/usr/include/}, it may create
532 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
533 the build directory. In the other source directories of your package you
534 will usually pass @samp{-I} options to the compiler, so that these Gnulib
535 substitutes are visible and take precedence over the files in
536 @file{/usr/include/}.
538 @node Include <config.h>
539 @subsection Include <config.h>
541 These Gnulib substitute header files rely on @file{<config.h>} being
542 already included. Furthermore @file{<config.h>} must be the first include
543 in every compilation unit. This means that to @emph{all your source files}
544 and likely also to @emph{all your tests source files} you need to add an
545 @samp{#include <config.h>} at the top. Which source files are affected?
546 Exactly those whose compilation includes a @samp{-I} option that refers to
547 the Gnulib library directory.
549 This is annoying, but inevitable: On many systems, @file{<config.h>} is
550 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
551 and these flags have no effect after any system header file has been included.
553 @node Style of #include statements
554 @subsection Style of #include statements
556 When including including specific header files, you need to use the
557 @samp{#include <...>} syntax, not the @samp{#include "..."} syntax.
558 This is true for the following POSIX or ISO C standardized header files:
560 @item @code{arpa/inet.h}
561 @item @code{assert.h}
563 @item @code{dirent.h}
564 @item @code{endian.h}
569 @item @code{fnmatch.h}
572 @item @code{inttypes.h}
573 @item @code{langinfo.h}
574 @item @code{limits.h}
575 @item @code{locale.h}
577 @item @code{monetary.h}
579 @item @code{net/if.h}
580 @item @code{netinet/in.h}
582 @item @code{pthread.h}
584 @item @code{search.h}
585 @item @code{signal.h}
587 @item @code{stdalign.h}
588 @item @code{stdarg.h}
589 @item @code{stdbit.h}
590 @item @code{stddef.h}
591 @item @code{stdint.h}
593 @item @code{stdlib.h}
594 @item @code{string.h}
595 @item @code{strings.h}
596 @item @code{sys/msg.h}
597 @item @code{sys/resource.h}
598 @item @code{sys/select.h}
599 @item @code{sys/sem.h}
600 @item @code{sys/shm.h}
601 @item @code{sys/socket.h}
602 @item @code{sys/stat.h}
603 @item @code{sys/time.h}
604 @item @code{sys/times.h}
605 @item @code{sys/types.h}
606 @item @code{sys/uio.h}
607 @item @code{sys/utsname.h}
608 @item @code{sys/wait.h}
609 @item @code{termios.h}
610 @item @code{threads.h}
613 @item @code{unistd.h}
616 @item @code{wctype.h}
619 as well as for the following header files that exist in the GNU C library
620 but are not standardized:
622 @item @code{alloca.h}
623 @item @code{byteswap.h}
625 @item @code{getopt.h}
626 @item @code{malloc.h}
629 @item @code{selinux/selinux.h}
630 @item @code{sys/file.h}
631 @item @code{sys/ioctl.h}
632 @item @code{sys/random.h}
633 @item @code{sysexits.h}
637 The reason for this requirement is that for these header files, the Gnulib
638 override uses @code{#include_next} to include the system-provided header
639 of the same name, and @code{#include_next} may not work right with the
640 @samp{#include "..."} syntax.
642 @node Link-time requirements
643 @section Changing your link commands for use with Gnulib
645 When you use Gnulib, you need to augment the set of libraries against which
646 your programs and libraries are linked. This is done by augmenting the
647 Automake variable @code{LDADD} (for all programs) or
648 @code{@var{prog}_LDADD} (for a single program @code{@var{prog}}) or
649 @code{@var{library}_la_LIBADD} (for a single library @code{@var{library}.la}).
651 What do you need to add to this Automake variable?
654 The reference to the Gnulib library. In the example of section
655 @ref{Initial import}, this would be @code{lib/libgnu.a} for source in the
656 top-level directory, or @code{../lib/libgnu.a} for source in a sibling
657 directory of @code{lib/}.
660 References to additional libraries, brought in by some of the Gnulib
661 modules that you use (directly or indirectly). The complete list of such
662 libraries is printed when you invoke @code{gnulib-tool}. Alternatively,
663 you can retrieve the set of additional libraries required by a specific
664 Gnulib module by running
666 ./gnulib-tool --extract-recursive-link-directive @var{module}
669 Beware: By looking into the module description file @code{modules/@var{module}}
672 ./gnulib-tool --extract-link-directive @var{module}
675 you would miss the link dependencies of indirectly used modules.
679 @node Finding POSIX substitutes
680 @section Finding recommended ISO C and POSIX function substitutes
682 Gnulib contains a wealth of portability workarounds for ISO C and POSIX
683 functions. They are listed in detail in the chapter @ref{Function Substitutes}.
684 If you want to know which function substitutes are recommended for your
685 package, you can search your source code for ISO C and POSIX functions
686 that it uses and read the corresponding sections of said documentation
687 chapter. But this is a tedious task. Here is an alternative approach
688 that makes this task easier.
692 Add the Gnulib module @samp{posixcheck} to the Gnulib imports of your package,
693 as described earlier in this chapter.
696 Do a @code{make distclean} if you previously built in the top-level directory.
697 Then regenerate the Autotools-generated parts of the package.
700 On a glibc system, build your package. Pay attention to the compiler warnings.
701 Warnings are generated for uses of ISO C and POSIX functions that have
702 portability problems or other important pitfalls and for which you have not yet
703 imported the corresponding Gnulib module. If you get, say, a warning
704 ``warning: call to 'close' declared with attribute warning: close does not
705 portably work on sockets - use gnulib module close for portability'',
706 put @samp{close} on your list of modules to import.
709 Add the modules you noted to the Gnulib imports of your package.
712 Optionally, you can do the same steps again, and make sure that there are no
713 warnings left except those that you want to intentionally ignore.
716 Finally, remove the Gnulib module @samp{posixcheck} from the Gnulib imports,
717 and run @code{make distclean}.
721 @node Modified build rules
722 @section Modifying the build rules of a Gnulib import directory
724 In some cases, you may want to set additional compiler options for
725 use within the Gnulib import directory. For example, the
726 @samp{relocatable} module operates better if you define the C macros
727 @code{ENABLE_COSTLY_RELOCATABLE} and @code{INSTALLDIR} during its
730 There are two ways to do so: Use of the @code{gnulib-tool} option
731 @code{--makefile-name}, and a kitchen-sink module.
733 With the @code{gnulib-tool} option @code{--makefile-name}, you are
734 telling @code{gnulib-tool} to generate an includable @code{Makefile.am}
735 portion, rather than a self-contained @code{Makefile.am}. For example,
736 when you use @code{--makefile-name=Makefile.gnulib}, @code{gnulib-tool}
737 will generate @code{Makefile.gnulib}, and you will provide a
738 hand-written @code{Makefile.am} that includes @code{Makefile.gnulib}
739 through a line such as
741 include Makefile.gnulib
743 Before this include, you need to initialize this set of @code{Makefile.am}
747 @code{AUTOMAKE_OPTIONS}
751 @code{noinst_HEADERS}
753 @code{noinst_LIBRARIES}
755 @code{noinst_LTLIBRARIES}
757 @code{pkgdata_DATA} (only with Automake @geq{} 1.11.4)
765 @code{MOSTLYCLEANFILES}
767 @code{MOSTLYCLEANDIRS}
771 @code{DISTCLEANFILES}
773 @code{MAINTAINERCLEANFILES}
779 @code{AUTOMAKE_OPTIONS} should be initialized as described in
780 @ref{Options,,Changing Automake's Behavior,automake,GNU Automake}.
781 The other variables can be initialized to empty. However, you will most
782 likely want to initialize some of them with non-empty values, in order
783 to achieve the desired customization.
785 The other approach, the kitchen-sink module, is more advanced. See
786 chapter @ref{Extending Gnulib}.
789 @node Non-recursive make
790 @section Building directly from the top-level directory
792 By default, the Gnulib import directory will contain a generated
793 @code{Makefile.am} file. After configuring, this produces a generated
794 @code{Makefile} in this directory. As a consequence, the build from the
795 top-level directory will use a recursive @code{make} invocation for this
798 Some people prefer a build system where the @code{Makefile} in the
799 top-level directory directly builds the artifacts in the subdirectories,
800 without an intermediate @code{make} invocation. This is called
801 ``non-recursive make'' and is supported by Automake. For more details,
802 see @url{https://autotools.io/automake/nonrecursive.html}.
804 Gnulib supports this flavour of build system too. To use it, pass two
805 options to @code{gnulib-tool}: @samp{--makefile-name} and
806 @samp{--automake-subdir}.
808 With the @code{gnulib-tool} option @samp{--makefile-name}, you are
809 telling @code{gnulib-tool} to generate an includable @code{Makefile.am}
810 portion in the Gnulib import directory, rather than a self-contained
811 @code{Makefile.am}. For example, when you use
812 @samp{--makefile-name=Makefile.gnulib}, @code{gnulib-tool} will generate
813 @code{Makefile.gnulib}.
815 With the option @samp{--automake-subdir}, you are telling
816 @code{gnulib-tool} that you will include the generated file from the
817 @code{Makefile.am} in the top-level directory, rather than from a
818 @code{Makefile.am} in the same directory. For example, the top-level
819 @code{Makefile.am} might contain this directive:
822 include lib/Makefile.gnulib
825 The option @samp{--automake-subdir} is also supported in combination
826 with @samp{--with-tests} (@pxref{Unit tests}). Note that in this case,
827 however, the generated unit tests directory will contains a
828 @code{Makefile.am} and thus use a recursive @code{make} invocation.
829 This is not a problem, since the built artifacts of your package have
830 no dependencies towards the Gnulib unit tests, nor vice versa.
833 @node Multiple instances
834 @section Using Gnulib for both a library and a program
836 Your project might build both a library and some accompanying programs
837 in the same source tree. In that case you might want to use different
838 modules for the library than for the programs. Typically the programs
839 might want to make use of @code{getopt-posix} or @code{version-etc},
840 while the library wants to stay clear of these modules for technical
841 or licensing reasons.
843 Let's assume that your project contains a @file{lib} directory where
844 the source of the library resides and a @file{src} directory for the
845 sources of the programs as follows.
859 You can now add two instances of Gnulib to your project in separate
863 ~/src/libfoo$ gnulib-tool --import --lib=libgnu --source-base=gnulib \
864 --m4-base=gnulib/m4 --macro-prefix=gl strndup
865 ~/src/libfoo$ gnulib-tool --import --lib=libgnutools \
866 --source-base=src/gnulib --m4-base=src/gnulib/m4 \
867 --macro-prefix=gl_tools getopt-gnu
870 The first one will import the module @code{strndup} in @file{gnulib}
871 and the second one will import @code{getopt-gnu} in @file{src/gnulib}
872 and you will end up with the following source tree (many files omitted
873 in the interest of brevity):
894 As discussed in @ref{Unit tests}, you may not use @samp{--with-tests}
895 for this project since the @code{configure.ac} is shared.
897 Integration with your code is basically the same as outlined in
898 @ref{Initial import} with the one exception that you have to add both
899 the macro @code{gl_EARLY} and the macro @code{gl_tools_EARLY} to your
900 @file{configure.ac} (and of course also both macros @code{gl_INIT} and
901 @code{gl_tools_INIT}). Obviously the name of the second macro is
902 dependent on the value of the @option{--macro-prefix} option in your
903 @command{gnulib-tool} invocation.
917 Also as outlined in @ref{Initial import} you will have to add compiler
918 and linker flags. For the library you might have to add something
919 along the line of the following to your @file{Makefile.am}:
923 AM_CPPFLAGS = -I$(top_srcdir)/gnulib -I$(top_builddir)/gnulib
925 libfoo_la_LIBADD = $(top_builddir)/gnulib/libgnu.la
929 Correspondingly for the programs you will have to add something like
934 AM_CPPFLAGS = -I$(top_srcdir)/src/gnulib -I$(top_builddir)/src/gnulib
936 LDADD = $(top_builddir)/src/gnulib/libgnutools.la
940 The name of the library that you have pass in the linker option
941 depends on the @option{--lib} option in @command{gnulib-tool}
945 @node gettextize and autopoint
946 @section Caveat: @code{gettextize} and @code{autopoint} users
948 @cindex gettextize, caveat
949 @cindex autopoint, caveat
950 The programs @code{gettextize} and @code{autopoint}, part of
951 GNU @code{gettext}, import or update the internationalization infrastructure.
952 Some of this infrastructure, namely ca.@: 20 Autoconf macro files and the
953 @file{config.rpath} file, is also contained in Gnulib and may be imported
954 by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint}
955 will therefore overwrite some of the files that @code{gnulib-tool} has
956 imported, and vice versa.
958 Avoiding to use @code{gettextize} (manually, as package maintainer) or
959 @code{autopoint} (as part of a script like @code{autoreconf} or
960 @code{autogen.sh}) is not the solution: These programs also import the
961 infrastructure in the @file{po/} and optionally in the @file{intl/} directory.
963 The copies of the conflicting files in Gnulib are more up-to-date than
964 the copies brought in by @code{gettextize} and @code{autopoint}. When a
965 new @code{gettext} release is made, the copies of the files in Gnulib will
966 be updated immediately.
968 The choice of which version of gettext to require depends on the needs
969 of your package. For a package that wants to comply to GNU Coding
970 Standards, the steps are:
974 When you run @code{gettextize}, always use the @code{gettextize} from the
975 matching GNU gettext release. For the most recent Gnulib checkout, this is
976 the newest release found on @url{https://ftp.gnu.org/gnu/gettext/}. For an
977 older Gnulib snapshot, it is the release that was the most recent release
978 at the time the Gnulib snapshot was taken.
981 After running @code{gettextize}, invoke @code{gnulib-tool} and import
982 the @code{gettext} module. Also, copy the latest version of gnulib's
983 @file{build-aux/po/Makefile.in.in} to your @file{po/} directory (this
984 is done for you if you use gnulib's @file{autogen.sh} script).
987 If you get an error message like
988 @code{*** error: gettext infrastructure mismatch:
989 using a Makefile.in.in from gettext version ...
990 but the Autoconf macros are from gettext version ...},
991 it means that a new GNU gettext release was made, and its Autoconf macros
992 were integrated into Gnulib and now mismatch the @file{po/} infrastructure.
993 In this case, fetch and install the new GNU gettext release and run
994 @code{gettextize} followed by @code{gnulib-tool}.
997 On the other hand, if your package is not as concerned with compliance
998 to the latest standards, but instead favors development on stable
999 environments, the steps are:
1003 Determine the oldest version of @code{gettext} that you intend to
1004 support during development (at this time, gnulib recommends going no
1005 older than version 0.17). Run @code{autopoint} (not
1006 @code{gettextize}) to copy infrastructure into place (newer versions
1007 of gettext will install the older infrastructure that you requested).
1010 Invoke @code{gnulib-tool}, and import the @code{gettext-h} module.
1013 Regardless of which approach you used to get the infrastructure in
1014 place, the following steps must then be used to preserve that
1015 infrastructure (gnulib's @file{autogen.sh} script follows these rules):
1019 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
1023 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
1024 not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT}
1025 environment variable, like this:
1027 $ env AUTOPOINT=true autoreconf --install
1033 @section Handling Gnulib's own message translations
1035 Gnulib provides some functions that emit translatable messages using GNU
1036 @code{gettext}. The @samp{gnulib} domain at the
1037 @url{https://translationproject.org/, Translation Project} collects
1038 translations of these messages, which you should incorporate into your
1041 There are two basic ways to achieve this. The first, and older, method
1042 is to list all the source files you use from Gnulib in your own
1043 @file{po/POTFILES.in} file. This will cause all the relevant
1044 translatable strings to be included in your POT file. When you send
1045 this POT file to the Translation Project, translators will normally fill
1046 in the translations of the Gnulib strings from their ``translation
1047 memory'', and send you back updated PO files.
1049 However, this process is error-prone: you might forget to list some
1050 source files, or the translator might not be using a translation memory
1051 and provide a different translation than another translator, or the
1052 translation might not be kept in sync between Gnulib and your package.
1053 It is also slow and causes substantial extra work, because a human
1054 translator must be in the loop for each language and you will need to
1055 incorporate their work on request.
1057 For these reasons, a new method was designed and is now recommended. If
1058 you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}}
1059 options to @code{gnulib-tool}, then @code{gnulib-tool} will create a
1060 separate directory with its own @file{POTFILES.in}, and fetch current
1061 translations directly from the Translation Project (using
1062 @command{rsync} or @command{wget}, whichever is available).
1063 The POT file in this directory will be called
1064 @file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the
1065 @code{--po-domain} option (typically the same as the package name).
1066 This causes these translations to reside in a separate message domain,
1067 so that they do not clash either with the translations for the main part
1068 of your package nor with those of other packages on the system that use
1069 possibly different versions of Gnulib.
1070 When you use these options, the functions in Gnulib are built
1071 in such a way that they will always use this domain regardless of the
1072 default domain set by @code{textdomain}.
1074 In order to use this method, you must---in each program that might use
1075 Gnulib code---add an extra line to the part of the program that
1076 initializes locale-dependent behavior. Where you would normally write
1081 setlocale (LC_ALL, "");
1082 bindtextdomain (PACKAGE, LOCALEDIR);
1083 textdomain (PACKAGE);
1088 you should add an additional @code{bindtextdomain} call to inform
1089 gettext of where the MO files for the extra message domain may be found:
1093 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
1097 (This example assumes that the @var{domain} that you specified
1098 to @code{gnulib-tool} is the same as the value of the @code{PACKAGE}
1099 preprocessor macro.)
1101 Since you do not change the @code{textdomain} call, the default message
1102 domain for your program remains the same and your own use of @code{gettext}
1103 functions will not be affected.
1107 @section Integration with Version Control Systems
1109 If a project stores its source files in a version control system (VCS),
1110 such as CVS, Subversion, or Git, one needs to decide which files to commit.
1112 In principle, all files created by @code{gnulib-tool}, except
1113 @file{gnulib-cache.m4}, can be treated like generated source files,
1114 like for example a @file{parser.c} file generated from
1115 @file{parser.y}. Alternatively, they can be considered source files
1116 and updated manually.
1118 Here are the three different approaches in common use. Each has its
1119 place, and you should use whichever best suits your particular project
1120 and development methods.
1124 In projects which commit all source files, whether generated or not,
1125 into their VCS, the @code{gnulib-tool} generated files should all be
1126 committed. In this case, you should pass the option
1127 @samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
1128 VCS-related files such as @file{.gitignore}.
1130 Gnulib also contains files generated by @command{make} (and removed by
1131 @code{make clean}), using information determined by
1132 @command{configure}. For a Gnulib source file of the form
1133 @file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
1134 @command{make}-generated file. These should @emph{not} be checked
1135 into the VCS, but instead added to @file{.gitignore} or equivalent.
1138 In projects which customarily omit from their VCS all files that are
1139 generated from other source files, none of these files and directories
1140 are added into the VCS@. As described in @ref{Modified imports}, there
1141 are two ways to keep track of options and module names that are passed
1142 to @code{gnulib-tool}. The command for restoring the omitted files
1147 If they are stored in a file other than @code{gnulib-cache.m4}, such as
1148 @file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar,
1149 the restoration command is the entire @code{gnulib-tool ... --import ...}
1150 invocation with all options and module names.
1153 If the project relies on @code{gnulib-tool}'s memory of the last used
1154 options and module names, then the file @file{gnulib-cache.m4} in the M4
1155 macros directory must be added to the VCS, and the restoration command
1159 $ gnulib-tool --update
1162 The @samp{--update} option operates much like the @samp{--add-import}
1163 option, but it does not offer the possibility to change the way Gnulib is
1164 used. Also it does not report in the ChangeLogs the files that it had to
1165 add because they were missing.
1169 Most packages nowadays use the first among these two approaches. Over
1170 time, three ways of handling version control have evolved.
1172 In the cases (A) and (B), a ``git submodule'' is used to reference
1173 the precise commit of the gnulib repository, so that each developer
1174 running @samp{./bootstrap --pull} or @file{autopull.sh}
1175 will get the same version of all gnulib-provided
1178 The alternative is to always follow the newest Gnulib automatically.
1179 Note that this can cause breakages at unexpected moments, namely
1180 when a broken commit is pushed in Gnulib. It does not happen often,
1185 In this approach, the developers use a git submodule manually.
1187 The location of the submodule can be chosen to fit the package's needs;
1188 here's how to initially create the submodule in the directory @file{gnulib}:
1191 $ git submodule add -- https://git.savannah.gnu.org/git/gnulib.git gnulib
1195 Thereafter, the developer will run this command to update the
1196 submodule to the recorded checkout level:
1199 $ git submodule update --init gnulib
1203 Use this sequence to update to a newer version of gnulib:
1206 $ git submodule update --remote gnulib
1208 $ ./bootstrap --bootstrap-sync
1211 If multiple submodules are used, the following may be useful:
1214 $ git config alias.syncsub "submodule foreach git pull origin master"
1219 In this approach, the @code{build-aux/bootstrap} or @code{autopull.sh}
1220 program (see @ref{Developer tools}) is used to aid a developer in
1221 using this setup. You copy this program (and if it's
1222 @code{autopull.sh}, its companion files) into your package and place
1223 the copy or copies under version control. The program can be
1224 customized using @file{bootstrap.conf} which you also put under
1228 In this approach, you write the @code{autopull.sh} and @code{autogen.sh}
1231 @code{autopull.sh} is most easily written as a script that
1234 ./gitsub.sh pull || exit 1
1237 where @code{gitsub.sh} is described in @ref{Developer tools}.
1239 @code{autogen.sh} typically contains an explicit @code{gnulib-tool}
1240 invocation, followed by
1244 && autoheader && touch config.h.in \
1245 && automake --add-missing --copy \
1246 && rm -rf autom4te.cache \
1252 Some projects take a ``middle road'': they do commit Gnulib source
1253 files as in the first approach, but they do not commit other derived
1254 files, such as a @code{Makefile.in} generated by Automake. This
1255 increases the size and complexity of the repository, but can help
1256 occasional contributors by not requiring them to have a full Gnulib
1257 checkout to do a build, and all developers by ensuring that all
1258 developers are working with the same version of Gnulib in the
1259 repository. It also supports multiple Gnulib instances within a
1260 project. It remains important not to commit the
1261 @command{make}-generated files, as described above.
1267 @section Bundling the unit tests of the Gnulib modules
1269 You can bundle the unit tests of the Gnulib modules together with your
1270 package, through the @samp{--with-tests} option. Together with
1271 @samp{--with-tests}, you also specify the directory for these tests
1272 through the @samp{--tests-base} option. Of course, you need to add this
1273 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of
1274 the parent directory.
1276 The advantage of having the unit tests bundled is that when your program
1277 has a problem on a particular platform, running the unit tests may help
1278 determine quickly if the problem is on Gnulib's side or on your package's
1279 side. Also, it helps verifying Gnulib's portability, of course.
1281 The unit tests will be compiled and run when the user runs @samp{make check}.
1282 When the user runs only @samp{make}, the unit tests will not be compiled.
1284 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory
1285 after the directory containing the other tests, not before:
1288 SUBDIRS = gnulib-lib src man tests gnulib-tests
1292 This will ensure that on platforms where there are test failures in either
1293 directory, users will see and report the failures from the tests of your
1296 Note: In packages which use more than one invocation of @code{gnulib-tool}
1297 in the scope of the same @code{configure.ac}, you cannot use
1298 @samp{--with-tests}. You will have to use a separate @code{configure.ac}
1302 @node Conditional dependencies
1303 @section Avoiding unnecessary checks and compilations
1305 @cindex conditional dependencies
1306 In some cases, a module is needed by another module only on specific
1307 platforms. But when a module is present, its Autoconf checks are always
1308 executed, and its @code{Makefile.am} additions are always enabled. So
1309 it can happen that some Autoconf checks are executed and some source files
1310 are compiled, although no other module needs them on this particular
1311 platform, just @emph{in case} some other module would need them.
1313 The option @samp{--conditional-dependencies} enables an optimization of
1314 configure checks and @code{Makefile.am} snippets that avoids this. With
1315 this option, whether a module is considered ``present'' is no longer decided
1316 when @code{gnulib-tool} is invoked, but later, when @code{configure} is run.
1317 This applies to modules that were added as dependencies while
1318 @code{gnulib-tool} was run; modules that were passed on the command line
1319 explicitly are always ``present''.
1321 For example, the @code{timegm} module needs, on platforms
1322 where the system's @code{timegm} function is missing or buggy, a replacement
1323 that is based on a function @code{mktime_internal}. The module
1324 @code{mktime-internal} that provides this function provides it on all
1325 platforms. So, by default, the file @file{mktime-internal.c} will be
1326 compiled on all platforms, even on glibc and BSD systems which have a
1327 working @code{timegm} function. When the option
1328 @samp{--conditional-dependencies} is given, on the other hand, and if
1329 @code{mktime-internal} was not explicitly required on the command line,
1330 the file @file{mktime-internal.c} will only be compiled on the platforms
1331 where the @code{timegm} needs them.
1333 Conditional dependencies are specified in the module description by putting
1334 the condition on the same line as the dependent module, enclosed in brackets.
1335 The condition is a boolean shell expression that can assume that the
1336 @code{configure.ac} snippet from the module description has already been
1337 executed. In the example above, the dependency from @code{timegm} to
1338 @code{mktime-internal} is written like this:
1343 mktime-internal [test $HAVE_TIMEGM = 0 || test $REPLACE_TIMEGM = 1]
1347 Note: The option @samp{--conditional-dependencies} cannot be used together
1348 with the option @samp{--with-tests}. It also cannot be used when a package
1349 uses @code{gnulib-tool} for several subdirectories, with different values
1350 of @samp{--source-base}, in the scope of a single @code{configure.ac} file.