]> Savannah Git Hosting - gnulib.git/commitdiff
Fix gnulib-tool error when some modules occur in tests/.
authorBruno Haible <bruno@clisp.org>
Sat, 12 Dec 2020 23:28:20 +0000 (00:28 +0100)
committerBruno Haible <bruno@clisp.org>
Sat, 12 Dec 2020 23:28:20 +0000 (00:28 +0100)
* 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.

ChangeLog
check-AC_LIBOBJ [new file with mode: 0755]
doc/gnulib.texi
modules/fnmatch-gnu
modules/fopen-gnu
modules/memmem
modules/renameat
modules/strcasestr
modules/strstr

index 86a1a12c11289d1b3f37d4d493a9d41256808b25..86293259b70fd50f5296b2d5b55abadaa08a5b9f 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,17 @@
+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'.
diff --git a/check-AC_LIBOBJ b/check-AC_LIBOBJ
new file mode 100755 (executable)
index 0000000..f0c5a07
--- /dev/null
@@ -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 <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
index bddb80624b0961f435dfc906829881a6813ed369..d646d6de1ced30f69aaf4e239217033f32a7ebc8 100644 (file)
@@ -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
 
index f2c49de101ed1334d9094c949872be3c3ccb08e9..ed47df2cafd094bae55c79c4f0a7ea671d8dc974 100644 (file)
@@ -2,6 +2,7 @@ Description:
 fnmatch() function: wildcard matching, with GNU extensions.
 
 Files:
+lib/fnmatch.c
 
 Depends-on:
 fnmatch
index f0f20548eeb65b25e07bfcc1c6fa027ddc17e4ce..9252c749b3d78d7ae377ec5fdc9e82abf443fe0d 100644 (file)
@@ -2,6 +2,7 @@ Description:
 fopen() function: open a stream to a file, with GNU extensions.
 
 Files:
+lib/fopen.c
 
 Depends-on:
 fopen
index 63bd3efce10abff6ab4421650eb9df1c6bdfb2c7..08fce4f144a964878d9564e19ac22871e92ae92e 100644 (file)
@@ -2,6 +2,7 @@ Description:
 memmem() function: efficiently locate first substring in a buffer.
 
 Files:
+lib/memmem.c
 
 Depends-on:
 memmem-simple
index 48b32c3692d52abdbf381514913f04efd5f24dd8..6103558a31e909834516669bdd6303ab903de8d6 100644 (file)
@@ -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:
index 82fc67f33f35f38e6f9b94174b5f09ee9755483d..ed7b327ec2d412aeeb45dbef9ea3a03176ab31da 100644 (file)
@@ -2,6 +2,7 @@ Description:
 strcasestr() function: efficient case-insensitive search for unibyte substring.
 
 Files:
+lib/strcasestr.c
 
 Depends-on:
 strcasestr-simple
index 49367614dfe6f2b63a27253d711b3b005fd78bbf..1653c9167ba96ea7bf15af9db2360c61e187823c 100644 (file)
@@ -2,6 +2,7 @@ Description:
 strstr() function: efficiently locate first substring in a buffer.
 
 Files:
+lib/strstr.c
 
 Depends-on:
 strstr-simple