New module 'posixcheck'.

* modules/posixcheck: New file.
* m4/posixcheck.m4: New file.
* doc/gnulib-tool.texi (Finding POSIX substitutes): New section.
(Which modules?): Reference it.

diff --git a/ChangeLog b/ChangeLog
index 5fe884826e86ed3ccc7b175950273807e5ea1001..eee980ac2661a082bbedf1819590da1e8c171f8d 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,11 @@
+2018-08-04  Bruno Haible  <bruno@clisp.org>
+
+       New module 'posixcheck'.
+       * modules/posixcheck: New file.
+       * m4/posixcheck.m4: New file.
+       * doc/gnulib-tool.texi (Finding POSIX substitutes): New section.
+       (Which modules?): Reference it.
+
 2018-08-01  Assaf Gordon <assafgordon@gmail.com>
 
        dfa: fix memory leak

diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi
index 302fe880b9147db7258355f848cbab820ebd79f7..e3b8eeccdf962c9f909bdd0a62f8de987e0756c7 100644 (file)
--- a/doc/gnulib-tool.texi
+++ b/doc/gnulib-tool.texi
@@ -44,6 +44,7 @@ a real run without changing anything.
 * Modified imports::            Changing the import specification.
 * Simple update::               Tracking Gnulib development.
 * Source changes::              Impact of Gnulib on your source files.
+* Finding POSIX substitutes::   Determining additional suitable Gnulib modules
 * Modified build rules::        Modifying the build rules of a Gnulib import
 * Multiple instances::          Using Gnulib for both a library and a program
 * gettextize and autopoint::    Caveat: @code{gettextize} and @code{autopoint} users!
@@ -58,7 +59,7 @@ a real run without changing anything.
 @section Finding modules
 @cindex Finding modules
 
-There are three ways of finding the names of Gnulib modules that you can use
+There are four ways of finding the names of Gnulib modules that you can use
 in your package:
 
 @itemize
@@ -66,6 +67,10 @@ in your package:
 You have the complete module list, sorted according to categories, in
 @url{https://www.gnu.org/software/gnulib/MODULES.html}.
 
+@item
+If you are looking for POSIX function replacements that you don't know about
+yet, follow the procedure described in section @ref{Finding POSIX substitutes}.
+
 @item
 If you are looking for a particular POSIX header or function replacement,
 look in the chapters @ref{Header File Substitutes} and
@@ -460,6 +465,48 @@ used to set system dependent flags (such as @code{_GNU_SOURCE} on GNU systems),
 and these flags have no effect after any system header file has been included.
 
 
+@node Finding POSIX substitutes
+@section Finding recommended ISO C and POSIX function substitutes
+
+Gnulib contains a wealth of portability workarounds for ISO C and POSIX
+functions.  They are listed in detail in the chapter @ref{Function Substitutes}.
+If you want to know which function substitutes are recommended for your
+package, you can search your source code for ISO C and POSIX functions
+that it uses and read the corresponding sections of said documentation
+chapter.  But this is a tedious task.  Here is an alternative approach
+that makes this task easier.
+
+@enumerate
+@item
+Add the Gnulib module @samp{posixcheck} to the Gnulib imports of your package,
+as described earlier in this chapter.
+
+@item
+Do a @code{make distclean} if you previously built in the top-level directory.
+Then regenerate the Autotools-generated parts of the package.
+
+@item
+On a glibc system, build your package.  Pay attention to the compiler warnings.
+Warnings are generated for uses of ISO C and POSIX functions that have
+portability problems or other important pitfalls and for which you have not yet
+imported the corresponding Gnulib module.  If you get, say, a warning
+``warning: call to 'close' declared with attribute warning: close does not
+portably work on sockets - use gnulib module close for portability'',
+put @samp{close} on your list of modules to import.
+
+@item
+Add the modules you noted to the Gnulib imports of your package.
+
+@item
+Optionally, you can do the same steps again, and make sure that there are no
+warnings left except those that you want to intentionally ignore.
+
+@item
+Finally, remove the Gnulib module @samp{posixcheck} from the Gnulib imports,
+and run @code{make distclean}.
+@end enumerate
+
+
 @node Modified build rules
 @section Modifying the build rules of a Gnulib import directory
 

diff --git a/m4/posixcheck.m4 b/m4/posixcheck.m4
new file mode 100644 (file)
index 0000000..86f906a
--- /dev/null
+++ b/m4/posixcheck.m4
@@ -0,0 +1,12 @@
+# posixcheck.m4 serial 1
+dnl Copyright (C) 2018 Free Software Foundation, Inc.
+dnl This file is free software; the Free Software Foundation
+dnl gives unlimited permission to copy and/or distribute it,
+dnl with or without modifications, as long as this notice is preserved.
+
+AC_DEFUN([gl_POSIXCHECK],
+[
+  AC_DEFINE([GNULIB_POSIXCHECK], [1],
+    [Define to enable warnings for determining which Gnulib modules to use,
+     for portability of POSIX functions.])
+])

diff --git a/modules/posixcheck b/modules/posixcheck
new file mode 100644 (file)
index 0000000..85da0a8
--- /dev/null
+++ b/modules/posixcheck
@@ -0,0 +1,58 @@
+Description:
+Enable warnings for determining which Gnulib modules to use,
+for portability of POSIX functions.
+
+Files:
+m4/posixcheck.m4
+
+Depends-on:
+# All modules that depend on 'snippet/warn-on-use'.
+arpa_inet
+ctype
+dirent
+fcntl-h
+iconv-h
+inttypes-incomplete
+langinfo
+locale
+math
+monetary
+netdb
+poll-h
+pty
+search
+signal-h
+spawn
+stdio
+stdlib
+string
+strings
+sys_file
+sys_ioctl
+sys_resource
+sys_select
+sys_socket
+sys_stat
+sys_time
+sys_times
+sys_utsname
+sys_wait
+termios
+time
+unistd
+utime-h
+wchar
+wctype-h
+
+configure.ac:
+gl_POSIXCHECK
+
+Makefile.am:
+
+Include:
+
+License:
+LGPLv2+
+
+Maintainer:
+Bruno Haible