1 @node Invoking gnulib-tool
2 @chapter Invoking gnulib-tool
4 @c Copyright (C) 2005-2011 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, with no Front-Cover Texts, and with no Back-Cover
10 @c Texts. A copy of the license is included in the ``GNU Free
11 @c Documentation License'' file as part of this distribution.
14 @cindex invoking @command{gnulib-tool}
16 The @command{gnulib-tool} command is the recommended way to import
17 Gnulib modules. It is possible to borrow Gnulib modules in a package
18 without using @command{gnulib-tool}, relying only on the
19 meta-information stored in the @file{modules/*} files, but with a
20 growing number of modules this becomes tedious. @command{gnulib-tool}
21 simplifies the management of source files, @file{Makefile.am}s and
22 @file{configure.ac} in packages incorporating Gnulib modules.
24 @file{gnulib-tool} is not installed in a standard directory that is
25 contained in the @code{PATH} variable. It needs to be run directly in
26 the directory that contains the Gnulib source code. You can do this
27 either by specifying the absolute filename of @file{gnulib-tool}, or
28 you can also use a symbolic link from a place inside your @code{PATH}
29 to the @file{gnulib-tool} file of your preferred and most up-to-date
30 Gnulib checkout, like this:
32 $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool
35 Run @samp{gnulib-tool --help} for information. To get familiar with
36 @command{gnulib-tool} without affecting your sources, you can also try
37 some commands with the option @samp{--dry-run}; then
38 @code{gnulib-tool} will only report which actions it would perform in
39 a real run without changing anything.
42 * Which modules?:: Determining the needed set of Gnulib modules
43 * Initial import:: First import of Gnulib modules.
44 * Modified imports:: Changing the import specification.
45 * Simple update:: Tracking Gnulib development.
46 * Source changes:: Impact of Gnulib on your source files.
47 * gettextize and autopoint:: Caveat: @code{gettextize} and @code{autopoint} users!
48 * Localization:: Handling Gnulib's own message translations.
49 * VCS Issues:: Integration with Version Control Systems.
50 * Unit tests:: Bundling the unit tests of the Gnulib modules.
55 @section Finding modules
56 @cindex Finding modules
58 There are three ways of finding the names of Gnulib modules that you can use
63 You have the complete module list, sorted according to categories, in
64 @url{http://www.gnu.org/software/gnulib/MODULES.html}.
67 If you are looking for a particular POSIX header or function replacement,
68 look in the chapters @ref{Header File Substitutes} and
69 @ref{Function Substitutes}. For headers and functions that are provided by
70 Glibc but not standardized by POSIX, look in the chapters
71 @ref{Glibc Header File Substitutes} and @ref{Glibc Function Substitutes}.
74 If you have already found the source file in Gnulib and are looking for the
75 module that contains this source file, you can use the command
76 @samp{gnulib-tool --find @var{filename}}.
81 @section Initial import
82 @cindex initial import
84 Gnulib assumes that your project uses Autoconf. When using Gnulib, you
85 will need to have Autoconf and Automake among your build tools. Note that
86 while the use of Automake in your project's top level directory is an
87 easy way to fulfil the Makefile conventions of the GNU coding standards,
88 Gnulib does not require it. But when you use Gnulib, Automake will be
89 used at least in a subdirectory of your project.
91 Invoking @samp{gnulib-tool --import} will copy source files, create a
92 @file{Makefile.am} to build them, generate a file @file{gnulib-comp.m4} with
93 Autoconf M4 macro declarations used by @file{configure.ac}, and generate
94 a file @file{gnulib-cache.m4} containing the cached specification of how
97 Our example will be a library that uses Autoconf, Automake and
98 Libtool. It calls @code{strdup}, and you wish to use gnulib to make
99 the package portable to C89 and C99 (which don't have @code{strdup}).
102 ~/src/libfoo$ gnulib-tool --import strdup
103 Module list with included dependencies:
112 m4/absolute-header.m4
117 Creating directory ./lib
118 Creating directory ./m4
119 Copying file lib/dummy.c
120 Copying file lib/strdup.c
121 Copying file lib/string.in.h
122 Copying file m4/absolute-header.m4
123 Copying file m4/extensions.m4
124 Copying file m4/gnulib-common.m4
125 Copying file m4/gnulib-tool.m4
126 Copying file m4/strdup.m4
127 Copying file m4/string_h.m4
128 Creating lib/Makefile.am
129 Creating m4/gnulib-cache.m4
130 Creating m4/gnulib-comp.m4
133 You may need to add #include directives for the following .h files.
137 - add "lib/Makefile" to AC_CONFIG_FILES in ./configure.ac,
138 - mention "lib" in SUBDIRS in Makefile.am,
139 - mention "-I m4" in ACLOCAL_AMFLAGS in Makefile.am,
140 - invoke gl_EARLY in ./configure.ac, right after AC_PROG_CC,
141 - invoke gl_INIT in ./configure.ac.
145 By default, the source code is copied into @file{lib/} and the M4
146 macros in @file{m4/}. You can override these paths by using
147 @code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}. Some
148 modules also provide other files necessary for building. These files
149 are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in
150 @file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If
151 neither is specified, the current directory is assumed.
153 @code{gnulib-tool} can make symbolic links instead of copying the
154 source files. The option to specify for this is @samp{--symlink}, or
155 @samp{-s} for short. This can be useful to save a few kilobytes of disk
156 space. But it is likely to introduce bugs when @code{gnulib} is updated;
157 it is more reliable to use @samp{gnulib-tool --update} (see below)
158 to update to newer versions of @code{gnulib}. Furthermore it requires
159 extra effort to create self-contained tarballs, and it may disturb some
160 mechanism the maintainer applies to the sources. For these reasons,
161 this option is generally discouraged.
163 @code{gnulib-tool} will overwrite any pre-existing files, in
164 particular @file{Makefile.am}. It is also possible to separate the
165 generated @file{Makefile.am} content (for building the gnulib library)
166 into a separate file, say @file{gnulib.mk}, that can be included by your
167 handwritten @file{Makefile.am}, but this is a more advanced use of
170 Consequently, it is a good idea to choose directories that are not
171 already used by your projects, to separate gnulib imported files from
172 your own files. This approach is also useful if you want to avoid
173 conflicts between other tools (e.g., @code{gettextize} that also copy
174 M4 files into your package. Simon Josefsson successfully uses a source
175 base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several
178 After the @samp{--import} option on the command line comes the list of
179 Gnulib modules that you want to incorporate in your package. The names
180 of the modules coincide with the filenames in Gnulib's @file{modules/}
183 Some Gnulib modules depend on other Gnulib modules. @code{gnulib-tool}
184 will automatically add the needed modules as well; you need not list
185 them explicitly. @code{gnulib-tool} will also memorize which dependent
186 modules it has added, so that when someday a dependency is dropped, the
187 implicitly added module is dropped as well (unless you have explicitly
188 requested that module).
190 If you want to cut a dependency, i.e., not add a module although one of
191 your requested modules depends on it, you may use the option
192 @samp{--avoid=@var{module}} to do so. Multiple uses of this option are
193 possible. Of course, you will then need to implement the same interface
194 as the removed module.
196 A few manual steps are required to finish the initial import.
197 @code{gnulib-tool} printed a summary of these steps.
199 First, you must ensure Autoconf can find the macro definitions in
200 @file{gnulib-comp.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in
201 your top-level @file{Makefile.am} file, as in:
204 ACLOCAL_AMFLAGS = -I m4
207 You are now ready to call the M4 macros in @code{gnulib-comp.m4} from
208 @file{configure.ac}. The macro @code{gl_EARLY} must be called as soon
209 as possible after verifying that the C compiler is working.
210 Typically, this is immediately after @code{AC_PROG_CC}, as in:
219 The core part of the gnulib checks are done by the macro
220 @code{gl_INIT}. Place it further down in the file, typically where
221 you normally check for header files or functions. It must come after
222 other checks which may affect the compiler invocation, such as
223 @code{AC_MINIX}. For example:
232 @code{gl_INIT} will in turn call the macros related with the
233 gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA}
234 or autoconf or automake macros like @code{AC_FUNC_ALLOCA} or
235 @code{AM_FUNC_GETLINE}. So there is no need to call those macros yourself
236 when you use the corresponding gnulib modules.
238 You must also make sure that the gnulib library is built. Add the
239 @code{Makefile} in the gnulib source base directory to
240 @code{AC_CONFIG_FILES}, as in:
243 AC_CONFIG_FILES(... lib/Makefile ...)
246 You must also make sure that @code{make} will recurse into the gnulib
247 directory. To achieve this, add the gnulib source base directory to a
248 @code{SUBDIRS} Makefile.am statement, as in:
254 or if you, more likely, already have a few entries in @code{SUBDIRS},
255 you can add something like:
261 Finally, you have to add compiler and linker flags in the appropriate
262 source directories, so that you can make use of the gnulib library.
263 Since some modules (@samp{getopt}, for example) may copy files into
264 the build directory, @file{top_builddir/lib} is needed as well
265 as @file{top_srcdir/lib}. For example:
269 AM_CPPFLAGS = -I$(top_builddir)/lib -I$(top_srcdir)/lib
275 Don't forget to @code{#include} the various header files. In this
276 example, you would need to make sure that @samp{#include <string.h>}
277 is evaluated when compiling all source code files, that want to make
278 use of @code{strdup}.
280 In the usual case where Autoconf is creating a @file{config.h} file,
281 you should include @file{config.h} first, before any other include
282 file. That way, for example, if @file{config.h} defines
283 @samp{restrict} to be the empty string on a pre-C99 host, or a macro
284 like @samp{_FILE_OFFSET_BITS} that affects the layout of data
285 structures, the definition is consistent for all include files.
286 Also, on some platforms macros like @samp{_FILE_OFFSET_BITS} and
287 @samp{_GNU_SOURCE} may be ineffective, or may have only a limited
288 effect, if defined after the first system header file is included.
290 Finally, note that you cannot use @code{AC_LIBOBJ} or
291 @code{AC_REPLACE_FUNCS} in your @file{configure.ac} and expect the
292 resulting object files to be automatically added to @file{lib/libgnu.a}.
293 This is because your @code{AC_LIBOBJ} and @code{AC_REPLACE_FUNCS} invocations
294 from @file{configure.ac} augment a variable @code{@@LIBOBJS@@} (and/or
295 @code{@@LTLIBOBJS@@} if using Libtool), whereas @file{lib/libgnu.a}
296 is built from the contents of a different variable, usually
297 @code{@@gl_LIBOBJS@@} (or @code{@@gl_LTLIBOBJS@@} if using Libtool).
300 @node Modified imports
301 @section Modified imports
303 You can at any moment decide to use Gnulib differently than the last time.
305 There are two ways to change how Gnulib is used. Which one you'll use,
306 depends on where you keep track of options and module names that you pass
307 to @code{gnulib-tool}.
311 If you store the options and module names in a file under your own
312 control, such as @file{autogen.sh}, @file{bootstrap},
313 @file{bootstrap.conf}, or similar, simply invoke @command{gnulib-tool}
314 again, with modified options and more or fewer module names.
317 @code{gnulib-tool} remembers which modules were used last time. If you
318 want to rely on @code{gnulib-tool}'s own memory of the last used
319 options and module names, you can use the commands
320 @command{gnulib-tool --add-import} and
321 @command{gnulib-tool --remove-import}.
323 So, if you only want to use more Gnulib modules, simply invoke
324 @command{gnulib-tool --add-import @var{new-modules}}. The list of
325 modules that you pass after @samp{--add-import} is @emph{added} to the
326 previous list of modules.
328 Similarly, if you want to use fewer Gnulib modules, simply invoke
329 @command{gnulib-tool --remove-import @var{unneeded-modules}}. The list
330 of modules that you pass after @samp{--remove-import} is @emph{removed}
331 from the previous list of modules. Note that if a module is then still
332 needed as dependency of other modules, it will be used nevertheless.
333 If you want to @emph{really} not use a module any more, regardless of
334 whether other modules may need it, you need to use the @samp{--avoid}
337 For other changes, such as different choices of @samp{--lib},
338 @samp{--source-base} or @samp{--aux-dir}, the normal way is to
339 modify manually the file @file{gnulib-cache.m4} in the M4 macros
340 directory, then launch @samp{gnulib-tool --add-import}.
342 The only change for which this doesn't work is a change of the
343 @samp{--m4-base} directory. Because, when you pass a different value of
344 @samp{--m4-base}, @code{gnulib-tool} will not find the previous
345 @file{gnulib-cache.m4} file any more. A possible solution is to
346 manually copy the @file{gnulib-cache.m4} into the new M4 macro directory.
348 In the @file{gnulib-cache.m4} file, the macros have the following meaning:
351 The argument is a space separated list of the requested modules, not including
355 The argument is a space separated list of modules that should not be used,
356 even if they occur as dependencies. Corresponds to the @samp{--avoid}
357 command line argument.
360 The argument is the relative file name of the directory containing the gnulib
361 source files (mostly *.c and *.h files). Corresponds to the
362 @samp{--source-base} command line argument.
365 The argument is the relative file name of the directory containing the gnulib
366 M4 macros (*.m4 files). Corresponds to the @samp{--m4-base} command line
370 The argument is the relative file name of the directory containing the gnulib
371 unit test files. Corresponds to the @samp{--tests-base} command line argument.
374 The argument is the name of the library to be created. Corresponds to the
375 @samp{--lib} command line argument.
378 The presence of this macro without arguments corresponds to the @samp{--lgpl}
379 command line argument. The presence of this macro with an argument (whose
380 value must be 2 or 3) corresponds to the @samp{--lgpl=@var{arg}} command line
384 The presence of this macro corresponds to the @samp{--libtool} command line
385 argument and to the absence of the @samp{--no-libtool} command line argument.
386 It takes no arguments.
388 @item gl_MACRO_PREFIX
389 The argument is the prefix to use for macros in the @file{gnulib-comp.m4}
390 file. Corresponds to the @samp{--macro-prefix} command line argument.
396 @section Simple update
398 When you want to update to a more recent version of Gnulib, without
399 changing the list of modules or other parameters, a simple call
403 $ gnulib-tool --add-import
407 This will create, update or remove files, as needed.
409 Note: From time to time, changes are made in Gnulib that are not backward
410 compatible. When updating to a more recent Gnulib, you should consult
411 Gnulib's @file{NEWS} file to check whether the incompatible changes affect
416 @section Changing your sources for use with Gnulib
418 Gnulib contains some header file overrides. This means that when building
419 on systems with deficient header files in @file{/usr/include/}, it may create
420 files named @file{string.h}, @file{stdlib.h}, @file{stdint.h} or similar in
421 the build directory. In the other source directories of your package you
422 will usually pass @samp{-I} options to the compiler, so that these Gnulib
423 substitutes are visible and take precedence over the files in
424 @file{/usr/include/}.
426 These Gnulib substitute header files rely on @file{<config.h>} being
427 already included. Furthermore @file{<config.h>} must be the first include
428 in every compilation unit. This means that to @emph{all your source files}
429 and likely also to @emph{all your tests source files} you need to add an
430 @samp{#include <config.h>} at the top. Which source files are affected?
431 Exactly those whose compilation includes a @samp{-I} option that refers to
432 the Gnulib library directory.
434 This is annoying, but inevitable: On many systems, @file{<config.h>} is
435 used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
436 and these flags have no effect after any system header file has been included.
439 @node gettextize and autopoint
440 @section Caveat: @code{gettextize} and @code{autopoint} users
442 @cindex gettextize, caveat
443 @cindex autopoint, caveat
444 The programs @code{gettextize} and @code{autopoint}, part of
445 GNU @code{gettext}, import or update the internationalization infrastructure.
446 Some of this infrastructure, namely ca.@: 20 autoconf macro files and the
447 @file{config.rpath} file, is also contained in Gnulib and may be imported
448 by @code{gnulib-tool}. The use of @code{gettextize} or @code{autopoint}
449 will therefore overwrite some of the files that @code{gnulib-tool} has
450 imported, and vice versa.
452 Avoiding to use @code{gettextize} (manually, as package maintainer) or
453 @code{autopoint} (as part of a script like @code{autoreconf} or
454 @code{autogen.sh}) is not the solution: These programs also import the
455 infrastructure in the @file{po/} and optionally in the @file{intl/} directory.
457 The copies of the conflicting files in Gnulib are more up-to-date than
458 the copies brought in by @code{gettextize} and @code{autopoint}. When a
459 new @code{gettext} release is made, the copies of the files in Gnulib will
460 be updated immediately.
462 The solution is therefore:
466 When you run @code{gettextize}, always use the @code{gettextize} from the
467 matching GNU gettext release. For the most recent Gnulib checkout, this is
468 the newest release found on @url{http://ftp.gnu.org/gnu/gettext/}. For an
469 older Gnulib snapshot, it is the release that was the most recent release
470 at the time the Gnulib snapshot was taken. Then, after @code{gettextize},
471 invoke @code{gnulib-tool}.
474 When a script of yours run @code{autopoint}, invoke @code{gnulib-tool}
478 If you get an error message like
479 @code{*** error: gettext infrastructure mismatch:
480 using a Makefile.in.in from gettext version ...
481 but the autoconf macros are from gettext version ...},
482 it means that a new GNU gettext release was made, and its autoconf macros
483 were integrated into Gnulib and now mismatch the @file{po/} infrastructure.
484 In this case, fetch and install the new GNU gettext release and run
485 @code{gettextize} followed by @code{gnulib-tool}.
488 When you invoke @code{autoreconf} after @code{gnulib-tool}, make sure to
489 not invoke @code{autopoint} a second time, by setting the @code{AUTOPOINT}
490 environment variable, like this:
492 $ env AUTOPOINT=true autoreconf --install
498 @section Handling Gnulib's own message translations
500 Gnulib provides some functions that emit translatable messages using GNU
501 @code{gettext}. The @samp{gnulib} domain at the
502 @url{http://translationproject.org/, Translation Project} collects
503 translations of these messages, which you should incorporate into your
506 There are two basic ways to achieve this. The first, and older, method
507 is to list all the source files you use from Gnulib in your own
508 @file{po/POTFILES.in} file. This will cause all the relevant
509 translatable strings to be included in your POT file. When you send
510 this POT file to the Translation Project, translators will normally fill
511 in the translations of the Gnulib strings from their ``translation
512 memory'', and send you back updated PO files.
514 However, this process is error-prone: you might forget to list some
515 source files, or the translator might not be using a translation memory
516 and provide a different translation than another translator, or the
517 translation might not be kept in sync between Gnulib and your package.
518 It is also slow and causes substantial extra work, because a human
519 translator must be in the loop for each language and you will need to
520 incorporate their work on request.
522 For these reasons, a new method was designed and is now recommended. If
523 you pass the @code{--po-base=@var{directory}} and @code{--po-domain=@var{domain}}
524 options to @code{gnulib-tool}, then @code{gnulib-tool} will create a
525 separate directory with its own @file{POTFILES.in}, and fetch current
526 translations directly from the Translation Project (using
527 @command{rsync} or @command{wget}, whichever is available).
528 The POT file in this directory will be called
529 @file{@var{domain}-gnulib.pot}, depending on the @var{domain} you gave to the
530 @code{--po-domain} option (typically the same as the package name).
531 This causes these translations to reside in a separate message domain,
532 so that they do not clash either with the translations for the main part
533 of your package nor with those of other packages on the system that use
534 possibly different versions of Gnulib.
535 When you use these options, the functions in Gnulib are built
536 in such a way that they will always use this domain regardless of the
537 default domain set by @code{textdomain}.
539 In order to use this method, you must -- in each program that might use
540 Gnulib code -- add an extra line to the part of the program that
541 initializes locale-dependent behavior. Where you would normally write
546 setlocale (LC_ALL, "");
547 bindtextdomain (PACKAGE, LOCALEDIR);
548 textdomain (PACKAGE);
553 you should add an additional @code{bindtextdomain} call to inform
554 gettext of where the MO files for the extra message domain may be found:
558 bindtextdomain (PACKAGE "-gnulib", LOCALEDIR);
562 (This example assumes that the @var{domain} that you specified
563 to @code{gnulib-tool} is the same as the value of the @code{PACKAGE}
566 Since you do not change the @code{textdomain} call, the default message
567 domain for your program remains the same and your own use of @code{gettext}
568 functions will not be affected.
572 @section Issues with Version Control Systems
574 If a project stores its source files in a version control system (VCS),
575 such as CVS, Subversion, or Git, one needs to decide which files to commit.
577 In principle, all files created by @code{gnulib-tool}, except
578 @file{gnulib-cache.m4}, can be treated like generated source files,
579 like for example a @file{parser.c} file generated from
580 @file{parser.y}. Alternatively, they can be considered source files
581 and updated manually.
583 Here are the three different approaches in common use. Each has its
584 place, and you should use whichever best suits your particular project
585 and development methods.
589 In projects which commit all source files, whether generated or not,
590 into their VCS, the @code{gnulib-tool} generated files should all be
591 committed. In this case, you should pass the option
592 @samp{--no-vc-files} to @code{gnulib-tool}, which avoids alteration of
593 VCS-related files such as @file{.cvsignore}.
595 Gnulib also contains files generated by @command{make} (and removed by
596 @code{make clean}), using information determined by
597 @command{configure}. For a Gnulib source file of the form
598 @file{lib/foo.in.h}, the corresponding @file{lib/foo.h} is such a
599 @command{make}-generated file. These should @emph{not} be checked
600 into the VCS, but instead added to @file{.cvsignore} or equivalent.
603 In projects which customarily omit from their VCS all files that are
604 generated from other source files, none of these files and directories
605 are added into the VCS. As described in @ref{Modified imports}, there
606 are two ways to keep track of options and module names that are passed
607 to @code{gnulib-tool}. The command for restoring the omitted files
612 If they are stored in a file other than @code{gnulib-cache.m4}, such as
613 @file{autogen.sh}, @file{bootstrap}, @file{bootstrap.conf}, or similar,
614 the restoration command is the entire @code{gnulib-tool ... --import ...}
615 invocation with all options and module names.
618 If the project relies on @code{gnulib-tool}'s memory of the last used
619 options and module names, then the file @file{gnulib-cache.m4} in the M4
620 macros directory must be added to the VCS, and the restoration command
624 $ gnulib-tool --update
627 The @samp{--update} option operates much like the @samp{--add-import}
628 option, but it does not offer the possibility to change the way Gnulib is
629 used. Also it does not report in the ChangeLogs the files that it had to
630 add because they were missing.
634 Gnulib includes the file @file{build-aux/bootstrap} to aid a developer
635 in using this setup. Furthermore, in projects that use git for
636 version control, it is possible to use a git submodule containing the
637 precise commit of the gnulib repository, so that each developer
638 running @file{bootstrap} will get the same version of all
639 gnulib-provided files. The location of the submodule can be chosen to
640 fit the package's needs; here's how to initially create the submodule
641 in the directory @file{.gnulib}:
645 $ git submodule add -- git://git.sv.gnu.org/gnulib.git $dir
646 $ git config alias.syncsub "submodule foreach git pull origin master"
650 Thereafter, @file{bootstrap} can run this command to update the
651 submodule to the recorded checkout level:
654 git submodule update --init $dir
658 and a developer can use this sequence to update to a newer version of
668 Some projects take a ``middle road'': they do commit Gnulib source
669 files as in the first approach, but they do not commit other derived
670 files, such as a @code{Makefile.in} generated by Automake. This
671 increases the size and complexity of the repository, but can help
672 occasional contributors by not requiring them to have a full Gnulib
673 checkout to do a build, and all developers by ensuring that all
674 developers are working with the same version of Gnulib in the
675 repository. It also supports multiple Gnulib instances within a
676 project. It remains important not to commit the
677 @command{make}-generated files, as described above.
683 @section Bundling the unit tests of the Gnulib modules
685 You can bundle the unit tests of the Gnulib modules together with your
686 package, through the @samp{--with-tests} option. Together with
687 @samp{--with-tests}, you also specify the directory for these tests
688 through the @samp{--tests-base} option. Of course, you need to add this
689 directory to the @code{SUBDIRS} variable in the @code{Makefile.am} of
690 the parent directory.
692 The advantage of having the unit tests bundled is that when your program
693 has a problem on a particular platform, running the unit tests may help
694 determine quickly if the problem is on Gnulib's side or on your package's
695 side. Also, it helps verifying Gnulib's portability, of course.
697 The unit tests will be compiled and run when the user runs @samp{make check}.
698 When the user runs only @samp{make}, the unit tests will not be compiled.
700 In the @code{SUBDIRS} variable, it is useful to put the Gnulib tests directory
701 after the directory containing the other tests, not before:
704 SUBDIRS = gnulib-lib src man tests gnulib-tests
708 This will ensure that on platforms where there are test failures in either
709 directory, users will see and report the failures from the tests of your
712 Note: In packages which use more than one invocation of @code{gnulib-tool}
713 in the scope of the same @code{configure.ac}, you cannot use
714 @samp{--with-tests}. You will have to use a separate @code{configure.ac}