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