From: Bruno Haible Date: Sat, 4 Aug 2018 15:25:57 +0000 (+0200) Subject: New module 'posixcheck'. X-Git-Tag: v1.0~5501 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=68bfa44c8f03e2f554f6fc6c42d637bb72b368fa;p=thirdparty%2Fgnulib.git 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 5fe884826e..eee980ac26 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,11 @@ +2018-08-04 Bruno Haible + + 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 dfa: fix memory leak diff --git a/doc/gnulib-tool.texi b/doc/gnulib-tool.texi index 302fe880b9..e3b8eeccdf 100644 --- 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 index 0000000000..86f906aa93 --- /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 index 0000000000..85da0a853c --- /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