+2020-12-12 Bruno Haible <bruno@clisp.org>
+
+ Fix gnulib-tool error when some modules occur in tests/.
+ * doc/gnulib.texi (Specification): Update statistics.
+ (Autoconf macros): Don't suggest to use AC_LIBOBJ in a .m4 file.
+ (Using AC_LIBOBJ): New section.
+ * check-AC_LIBOBJ: New file.
+ * modules/fnmatch-gnu (Files): Add lib/fnmatch.c.
+ * modules/fopen-gnu (Files): Add lib/fopen.c.
+ * modules/memmem (Files): Add lib/memmem.c.
+ * modules/renameat (Files): Add lib/at-func2.c.
+ * modules/strcasestr (Files): Add lib/strcasestr.c.
+ * modules/strstr (Files): Add lib/strstr.c.
+
2020-12-11 Bruno Haible <bruno@clisp.org>
sh-quote, execute, spawn-pipe, etc.: Make better use of 'const'.
--- /dev/null
+#!/bin/sh
+#
+# Copyright (C) 2020 Free Software Foundation, Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program. If not, see <https://www.gnu.org/licenses/>.
+#
+
+# Check that all AC_LIBOBJ invocations in module descriptions follow the rules.
+exitcode=0
+for module in `./gnulib-tool --list`; do
+ f=modules/$module
+ for g in `sed -n -e 's/^ *AC_LIBOBJ(\[\(.*\)\]).*/\1/p' < $f`; do
+ if grep "^lib/$g\.c\$" $f >/dev/null; then
+ :
+ else
+ echo "$f lacks file lib/$g.c"
+ exitcode=1
+ fi
+ done
+done
+exit $exitcode
* Specification::
* Module description::
* Autoconf macros::
+* Using @code{AC_LIBOBJ}::
* Unit test modules::
* Incompatible changes::
@end menu
The advantage of texinfo formatted documentation is that it is easily
published in HTML or Info format.
-Currently (as of 2010), half of gnulib uses the first practice, nearly half
-of gnulib uses the second practice, and a small minority uses the texinfo
+Currently (as of 2020), 70% of gnulib uses the first practice, 25% of
+gnulib uses the second practice, and a small minority uses the texinfo
practice.
For modules that provide a replacement, it is useful to split the Autoconf
macro into two macro definitions: one that detects whether the replacement
-is needed and requests the replacement using @code{AC_LIBOBJ} (this is the
+is needed and requests the replacement by setting a @code{HAVE_FOO}
+variable to 0 or a @code{REPLACE_FOO} variable to 1 (this is the
entry point, say @code{gl_FUNC_FOO}), and one that arranges for the macros
needed by the replacement code @code{lib/foo.c} (typically called
@code{gl_PREREQ_FOO}). The reason of this separation is
@end enumerate
+@node Using @code{AC_LIBOBJ}
+@section Making proper use of @code{AC_LIBOBJ}
+
+Source files that provide a replacement should be only compiled on the
+platforms that need this replacement. While it is actually possible
+to compile a @code{.c} file whose contents is entirely @code{#ifdef}'ed
+out on the platforms that don't need the replacement, this practice is
+discouraged because
+@itemize @bullet
+@item
+It makes the build time longer than needed, by invoking the compiler for
+nothing.
+@item
+It produces a @code{.o} file that suggests that a replacement was needed.
+@item
+Empty object files produce a linker warning on some platforms: MSVC.
+@end itemize
+
+The typical idiom for invoking @code{AC_LIBOBJ} is thus the following,
+in the module description:
+
+@smallexample
+if test $HAVE_FOO = 0 || test $REPLACE_FOO = 1; then
+ AC_LIBOBJ([foo])
+ gl_PREREQ_FOO
+fi
+@end smallexample
+
+Important: Do not place @code{AC_LIBOBJ} invocations in the Autoconf
+macros in the @code{m4/} directory. The purpose of the Autoconf macros
+is to determine what features or bugs the platform has, and to make
+decisions about which replacements are needed. The purpose of the
+@code{configure.ac} and @code{Makefile.am} sections of the module
+descriptions is to arrange for the replacements to be compiled.
+@strong{Source file names do not belong in the @code{m4/} directory.}
+
+When an @code{AC_LIBOBJ} invocation is unconditional, it is simpler
+to just have the source file compiled through an Automake variable
+augmentation: In the @code{Makefile.am} section write
+
+@smallexample
+lib_SOURCES += foo.c
+@end smallexample
+
+When a module description contains an @code{AC_LIBOBJ([foo])}
+invocation, you @strong{must} list the source file @code{lib/foo.c}
+in the @code{Files} section. This is needed even if the module
+depends on another module that already lists @code{lib/foo.c} in its
+@code{Files} section --- because your module might be used among
+the test modules (in the directory specified through @samp{--tests-base})
+and the other module among the main modules (in the directory specified
+through @samp{--source-base}), and in this situation, the
+@code{AC_LIBOBJ([foo])} of your module can only be satisfied by having
+@code{foo.c} be present in the tests source directory as well.
+
@node Unit test modules
@section Unit test modules