From 03a8314d59f5cb0ec52073b34e14a6a108504a27 Mon Sep 17 00:00:00 2001 From: Paul Eggert
Date: Sun, 23 Apr 2017 20:54:35 -0700 Subject: [PATCH] Target a C99 subset, not a C89 subset For many years Gnulib has targeted C89 and has resisted using C99 features, as some Gnulib-using programs still wanted to target C89. As this no longer seems to be the case, relax the porting requirements to allow some C99 features. This is merely a change to the documentation, to give other Gnulib developers a chance to weigh in on the topic. * doc/extern-inline.texi (extern inline): * doc/gnulib-readme.texi (Portability guidelines): * doc/gnulib-tool.texi (Initial import): * doc/gnulib.texi (Header files): Modernize to talk about C99 and C11 instead of C89 and C99. * doc/gnulib-readme.texi (Portability guidelines): Now a section, not merely a subsection, so that it can be split up. Modernize a bit. (C language versions, C99 features assumed) (C99 features avoided): New sections. --- ChangeLog | 21 ++++++++ doc/extern-inline.texi | 10 ++-- doc/gnulib-readme.texi | 141 ++++++++++++++++++++++++++++++++++++++++--------- doc/gnulib-tool.texi | 4 +- doc/gnulib.texi | 2 +- 5 files changed, 146 insertions(+), 32 deletions(-) diff --git a/ChangeLog b/ChangeLog index f3f20b6..75e7d8a 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,24 @@ +2017-04-23 Paul Eggert + + Target a C99 subset, not a C89 subset + For many years Gnulib has targeted C89 and has resisted using C99 + features, as some Gnulib-using programs still wanted to target + C89. As this no longer seems to be the case, relax the porting + requirements to allow some C99 features. This is merely a change + to the documentation, to give other Gnulib developers a chance to + weigh in on the topic. + * doc/extern-inline.texi (extern inline): + * doc/gnulib-readme.texi (Portability guidelines): + * doc/gnulib-tool.texi (Initial import): + * doc/gnulib.texi (Header files): + Modernize to talk about C99 and C11 instead of C89 and C99. + * doc/gnulib-readme.texi (Portability guidelines): + Now a section, not merely a subsection, so that it + can be split up. Modernize a bit. + (C language versions, C99 features assumed) + (C99 features avoided): + New sections. + 2017-04-23 Bruno Haible doc: New section "Modules that modify the way other modules work". diff --git a/doc/extern-inline.texi b/doc/extern-inline.texi index 60cfc0a..2494742 100644 --- a/doc/extern-inline.texi +++ b/doc/extern-inline.texi @@ -18,8 +18,8 @@ @cindex inline The @code{extern-inline} module supports the use of C99-style address@hidden inline} functions so that the code still runs on pre-C99 -compilers. address@hidden inline} functions so that the code still runs on +compilers that do not support this feature correctly. C code ordinarily should not use @code{inline}. Typically it is better to let the compiler figure out whether to inline, as compilers @@ -31,7 +31,7 @@ Functions defined (not merely declared) in headers are an exception, as avoiding @code{inline} would commonly cause problems for these functions. Suppose @file{aaa.h} defines the function @code{aaa_fun}, and @file{aaa.c}, @file{bbb.c} and @file{ccc.c} all include address@hidden If code is intended to portable to pre-C99 compilers, address@hidden If code is intended to portable to non-C99 compilers, @code{aaa_fun} cannot be declared with the C99 @code{inline} keyword. This problem cannot be worked around by making @code{aaa_fun} an ordinary function, as it would be defined three times with external @@ -77,8 +77,8 @@ whereas @file{bbb.c} and @file{ccc.c} can include @file{aaa.h} in the usual way. C99 compilers expand @code{AAA_INLINE} to C99-style @code{inline} usage, where @code{aaa_fun} is declared @code{extern inline} in @file{aaa.c} and plain @code{inline} in other modules. -Pre-C99 compilers that are compatible with GCC use GCC-specific syntax -to accomplish the same ends. Other pre-C99 compilers use @code{static +Non-C99 compilers that are compatible with GCC use GCC-specific syntax +to accomplish the same ends. Other non-C99 compilers use @code{static inline} so they suffer from code bloat, but they are not mainline platforms and will die out eventually. diff --git a/doc/gnulib-readme.texi b/doc/gnulib-readme.texi index 142143f..1422135 100644 --- a/doc/gnulib-readme.texi +++ b/doc/gnulib-readme.texi @@ -14,6 +14,7 @@ * Git Checkout:: * Keeping Up-to-date:: * Contributing to Gnulib:: +* Portability guidelines:: * High Quality:: @end menu @@ -124,7 +125,6 @@ you should probably consider packaging it as a separate library. * Gnulib licensing:: * Indent with spaces not TABs:: * How to add a new module:: -* Portability guidelines:: @end menu @node Gnulib licensing @@ -278,33 +278,54 @@ is not empty after preprocessing. One way to do this is to @end itemize @node Portability guidelines address@hidden Portability guidelines address@hidden Portability guidelines Gnulib code is intended to be portable to a wide variety of platforms, -not just GNU platforms. See the documentation section ``Target Platforms'' -for details. +not just GNU platforms. Gnulib typically attempts to support a +platform as long as it is still supported by its provider, even if the +platform is not the latest version. @xref{Target Platforms}. Many Gnulib modules exist so that applications need not worry about undesirable variability in implementations. For example, an application that uses the @code{malloc} module need not worry about @code{malloc@ (0)} returning @code{NULL} on some Standard C -platforms; and @code{time_r} users need not worry about address@hidden returning @code{int} (not @code{char@ *}) on some -platforms that predate POSIX 1003.1-2001. - -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 +platforms; and @code{glob} users need not worry about @code{glob} +silently omitting symbolic links to nonexistent files on some +platforms that do not conform to POSIX. + +Gnulib code is intended to port without problem to new 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 @code{vararrays} +module to check whether they are supported. + +The following subsections discuss some exceptions and caveats to the +general Gnulib portability guidelines. + address@hidden +* C language versions:: +* C99 features assumed:: +* C99 features avoided:: +* Other portability assumptions:: address@hidden menu + address@hidden C language versions address@hidden C language versions + +Currently Gnulib assumes at least a freestanding C99 compiler, +possibly operating with a C library that predates C99; 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 many fixes for obsolete platforms, fixes that may be removed in the future. -Because of the freestanding C89 assumption, Gnulib code can include address@hidden