From: Bruno Haible Date: Sat, 12 Dec 2020 23:28:20 +0000 (+0100) Subject: Fix gnulib-tool error when some modules occur in tests/. X-Git-Tag: v1.0~3377 X-Git-Url: https://gitweb.git.savannah.gnu.org/gitweb/?a=commitdiff_plain;h=0f1b9440bc719abcee7cbdf137e723cfe153038a;p=gnulib.git 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. --- diff --git a/ChangeLog b/ChangeLog index 86a1a12c11..86293259b7 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,17 @@ +2020-12-12 Bruno Haible + + 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 sh-quote, execute, spawn-pipe, etc.: Make better use of 'const'. diff --git a/check-AC_LIBOBJ b/check-AC_LIBOBJ new file mode 100755 index 0000000000..f0c5a074d4 --- /dev/null +++ b/check-AC_LIBOBJ @@ -0,0 +1,32 @@ +#!/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 . +# + +# 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 diff --git a/doc/gnulib.texi b/doc/gnulib.texi index bddb80624b..d646d6de1c 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -166,6 +166,7 @@ consistency with gnulib. * Specification:: * Module description:: * Autoconf macros:: +* Using @code{AC_LIBOBJ}:: * Unit test modules:: * Incompatible changes:: @end menu @@ -345,8 +346,8 @@ or changing the implementation, you have both elements side by side. 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. @@ -525,7 +526,8 @@ because sometimes a header and a function name coincide (for example, 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 @@ -541,6 +543,61 @@ maintenance. @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 diff --git a/modules/fnmatch-gnu b/modules/fnmatch-gnu index f2c49de101..ed47df2caf 100644 --- a/modules/fnmatch-gnu +++ b/modules/fnmatch-gnu @@ -2,6 +2,7 @@ Description: fnmatch() function: wildcard matching, with GNU extensions. Files: +lib/fnmatch.c Depends-on: fnmatch diff --git a/modules/fopen-gnu b/modules/fopen-gnu index f0f20548ee..9252c749b3 100644 --- a/modules/fopen-gnu +++ b/modules/fopen-gnu @@ -2,6 +2,7 @@ Description: fopen() function: open a stream to a file, with GNU extensions. Files: +lib/fopen.c Depends-on: fopen diff --git a/modules/memmem b/modules/memmem index 63bd3efce1..08fce4f144 100644 --- a/modules/memmem +++ b/modules/memmem @@ -2,6 +2,7 @@ Description: memmem() function: efficiently locate first substring in a buffer. Files: +lib/memmem.c Depends-on: memmem-simple diff --git a/modules/renameat b/modules/renameat index 48b32c3692..6103558a31 100644 --- a/modules/renameat +++ b/modules/renameat @@ -3,6 +3,7 @@ renameat() function: rename a file, relative to two directories Files: lib/renameat.c +lib/at-func2.c m4/renameat.m4 Depends-on: diff --git a/modules/strcasestr b/modules/strcasestr index 82fc67f33f..ed7b327ec2 100644 --- a/modules/strcasestr +++ b/modules/strcasestr @@ -2,6 +2,7 @@ Description: strcasestr() function: efficient case-insensitive search for unibyte substring. Files: +lib/strcasestr.c Depends-on: strcasestr-simple diff --git a/modules/strstr b/modules/strstr index 49367614df..1653c9167b 100644 --- a/modules/strstr +++ b/modules/strstr @@ -2,6 +2,7 @@ Description: strstr() function: efficiently locate first substring in a buffer. Files: +lib/strstr.c Depends-on: strstr-simple