From b7eca6196a6abd767971ccb360d0bbe4a60b247c Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Mon, 2 Jan 2017 16:05:14 -0800 Subject: [PATCH] doc: modernize for C11 etc. * doc/gnulib-readme.texi (Portability guidelines): Modernize a bit for C11, MinGW, etc. This responds to Paul Smith's question in: http://lists.gnu.org/archive/html/bug-gnulib/2017-01/msg00014.html --- ChangeLog | 5 +++++ doc/gnulib-readme.texi | 59 +++++++++++++++++++++++++++++++++----------------- 2 files changed, 44 insertions(+), 20 deletions(-) diff --git a/ChangeLog b/ChangeLog index 66ea430..76c7569 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,5 +1,10 @@ 2017-01-02 Paul Eggert + doc: modernize for C11 etc. + * doc/gnulib-readme.texi (Portability guidelines): Modernize a bit + for C11, MinGW, etc. This responds to Paul Smith's question in: + http://lists.gnu.org/archive/html/bug-gnulib/2017-01/msg00014.html + dfa: prefer functions to FETCH_WC macro * lib/dfa.c (FETCH_WC): Remove, replacing with ... (fetch_wc, bracket_fetch_wc): ... new functions. These store the diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi index 256a289..ecd94c3 100644 --- a/doc/gnulib-readme.texi +++ b/doc/gnulib-readme.texi @@ -292,41 +292,57 @@ platforms; and @code{time_r} users need not worry about @code{localtime_r} returning @code{int} (not @code{char@ *}) on some platforms that predate POSIX 1003.1-2001. -Currently we assume at least a freestanding C89 compiler, possibly -operating with a C library that predates C89. The oldest environments -currently ported to are probably HP-UX 10.20 and IRIX 5.3, though we -are not testing these platforms very often. - -Because we assume a freestanding C89 compiler, Gnulib code can include +Gnulib attempts to be portable to platforms that are still supported +by their providers, even if these systems are not the latest version. +Currently Gnulib assumes at least a freestanding C89 compiler, +possibly operating with a C library that predates C89; with time this +assumption will likely be strengthened to later versions of the C +standard. Old platforms currently supported include AIX 6.1, HP-UX +11i v1 and Solaris 10, though these platforms are rarely tested. +Gnulib itself is so old that it contains contains many fixes for +obsolete platforms, fixes that may be removed in the future. + +Because of the freestanding C89 assumption, Gnulib code can include @code{}, @code{}, @code{}, and @code{} unconditionally. It can also assume the existence of @code{}, @code{}, @code{}, @code{}, @code{}, @code{}, @code{}, @code{}, and @code{}. Similarly, many modules include @code{} even though it's not even in -C99; that's OK since @code{} has been around nearly +C11; that's OK since @code{} has been around nearly forever. -Even if the include files exist, they may not conform to C89. +Even if the include files exist, they may not conform to the C standard. However, GCC has a @command{fixincludes} script that attempts to fix most C89-conformance problems. So Gnulib currently assumes include files largely conform to C89 or better. People still using ancient hosts should use fixincludes or fix their include files manually. -Even if the include files conform to C89, the library itself may not. +Even if the include files conform, the library itself may not. For example, @code{strtod} and @code{mktime} have some bugs on some platforms. You can work around some of these problems by requiring the relevant modules, e.g., the Gnulib @code{mktime} module supplies a working and conforming @code{mktime}. -The GNU coding standards allow one departure from strict C99: Gnulib -code can assume that standard internal types like @code{size_t} are no wider -than @code{long}. POSIX 1003.1-2001 and the GNU coding standards both -require @code{int} to be at least 32 bits wide, so Gnulib code assumes this -as well. Gnulib code makes the following additional assumptions: +The GNU coding standards allow one departure from strict C: Gnulib +code can assume that standard internal types like @code{size_t} are no +wider than @code{long}. POSIX requires implementations to support at +least one programming environment where this is true, and such +environments are recommended for Gnulib-using applications. When it +is easy to port to non-POSIX platforms like MinGW where these types +are wider than @code{long}, new Gnulib code should do so, e.g., by +using @code{ptrdiff_t} instead of @code{long}. However, it is not +always that easy, and no effort has been made to check that all Gnulib +modules work on MinGW-like environments. + +Gnulib code makes the following additional assumptions: @itemize @item address@hidden and @code{unsigned int} are at least 32 bits wide. POSIX +and the GNU coding standards both require this. + address@hidden Signed integer arithmetic is two's complement. Previously, Gnulib code sometimes assumed that signed integer @@ -335,9 +351,9 @@ sometimes do not guarantee this, and Gnulib code with this assumption is now considered to be questionable. @xref{Integer Properties}. -Some Gnulib modules contain explicit support for the other signed -integer representations allowed by C99 (ones' complement and signed -magnitude), but these modules are the exception rather than the rule. +Although some Gnulib modules contain explicit support for the other signed +integer representations allowed by the C standard (ones' complement and signed +magnitude), these modules are the exception rather than the rule. All practical Gnulib targets use two's complement. @item @@ -384,9 +400,12 @@ runtime overhead on standard hosts and that are relatively easy to maintain. With the above caveats, Gnulib code should port without problem to new -hosts, e.g., hosts conforming to C99 or to recent POSIX standards. -Hence Gnulib code should avoid using constructs (e.g., undeclared -functions return @code{int}) that do not conform to C99. +hosts, e.g., hosts conforming to recent C and POSIX standards. Hence +Gnulib code should avoid using constructs that these newer standards +no longer require, without first testing for the presence of these +constructs. For example, because C11 made variable length arrays +optional, Gnulib code should avoid them unless it first uses the address@hidden module to check whether they are supported. @node High Quality @section High Quality -- 2.7.4