On 04/21/2012 05:17 PM, Bruno Haible wrote: > Patches welcome!
Here's a quick first cut. --- ChangeLog | 15 +++ README | 230 +------------------------------------ doc/gnulib-intro.texi | 15 +++ doc/gnulib.texi | 303 +++++++++++++++++++++++++++++++++++++++++++++++++ 4 files changed, 338 insertions(+), 225 deletions(-) diff --git a/ChangeLog b/ChangeLog index c99459a..081e74d 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,18 @@ +2012-04-21 Paul Eggert <egg...@cs.ucla.edu> + + doc: move contributor's guide from README to manual + Prompted by Karl Berry's suggestion in + <http://lists.gnu.org/archive/html/bug-gnulib/2012-04/msg00140.html> + and by Bruno Haible's followup suggestion in that thread. + * README (For more Information): New section. + (Contributing to Gnulib): Move contents to .texi files; see below. + * doc/gnulib-intro.texi (Target Platforms): Mention C version. + (Tested Development): New section, taken from README. + * doc/gnulib.texi (Contributing to Gnulib, Gnulib's Licensing) + (Indent with Spaces, How to Add a New Module) + (Portability Guidelines): New sections. + (Unit test modules): Add material about test suite. + 2012-04-22 Bruno Haible <br...@clisp.org> users.txt: Update. diff --git a/README b/README index 4bf10dd..2888c7c 100644 --- a/README +++ b/README @@ -75,232 +75,12 @@ to join the autotools-announce mailing list to be advised of such changes. -Contributing to Gnulib -====================== +For more Information +==================== -All software here is copyrighted by the Free Software Foundation - you need -to have filled out an assignment form for a project that uses the -module for that contribution to be accepted here. - -If you have a piece of code that you would like to contribute, please -email bug-gnulib@gnu.org. You can review the archives, subscribe, etc., -via http://lists.gnu.org/mailman/listinfo/bug-gnulib. - -Generally we are looking for files that fulfill at least one of the -following requirements: - - * If your .c and .h files define functions that are broken or -missing on some other system, we should be able to include it. - - * If your functions remove arbitrary limits from existing -functions (either under the same name, or as a slightly different -name), we should be able to include it. - -If your functions define completely new but rarely used functionality, -you should probably consider packaging it as a separate library. - - -License -------- -Gnulib contains code both under GPL and LGPL. Because several packages -that use Gnulib are GPL, the files state they are licensed under GPL. -However, to support LGPL projects as well, you may use some of the -files under LGPL. The "License:" information in the files under -modules/ clarifies the real license that applies to the module source. - -Keep in mind that if you submit patches to files in Gnulib, you should -license them under a compatible license, which means that sometimes -the contribution will have to be LGPL, if the original file is -available under LGPL via a "License: LGPL" information in the -projects' modules/ file. - - -Indent with spaces, not TABs ----------------------------- -We use space-only indentation in nearly all files. This includes all -*.h, *.c, *.y files, except for the regex module. Makefile and ChangeLog -files are excluded, since TAB characters are part of their format. - -In order to tell your editor to produce space-only indentation, you -can use these instructions. - - * For Emacs: Add these lines to your Emacs initialization file - ($HOME/.emacs or similar): - - ;; In gnulib, indent with spaces everywhere (not TABs). - ;; Exceptions: Makefile and ChangeLog modes. - (add-hook 'find-file-hook '(lambda () - (if (and buffer-file-name - (string-match "/gnulib\\>" (buffer-file-name)) - (not (string-equal mode-name "Change Log")) - (not (string-equal mode-name "Makefile"))) - (setq indent-tabs-mode nil)))) - - * For vi (vim): Add these lines to your $HOME/.vimrc file: - - " Don't use tabs for indentation. Spaces are nicer to work with. - set expandtab - - For Makefile and ChangeLog files, compensate this by adding this to - your $HOME/.vim/after/indent/make.vim and - $HOME/.vim/after/indent/changelog.vim files: - - " Use tabs for indentation, regardless of the global setting. - set noexpandtab - - * For Eclipse: In the "Window|Preferences" dialog (or "Eclipse|Preferences" - dialog on MacOS), - 1. Under "General|Editors|Text Editors", select the "Insert spaces for tabs" - checkbox. - 2. Under "C/C++|Code Style", select a code style profile that has the - "Indentation|Tab policy" combobox set to "Spaces only", such as the - "GNU [built-in]" policy. - -If you use the GNU indent program, pass it the option '--no-tabs'. - - -How to add a new module ------------------------ -* Add the header files and source files to lib/. -* If the module needs configure-time checks, write an autoconf - macro for it in m4/<module>.m4. See m4/README for details. -* Write a module description modules/<module>, based on modules/TEMPLATE. -* If the module contributes a section to the end-user documentation, - put this documentation in doc/<module>.texi and add it to the "Files" - section of modules/<module>. Most modules don't do this; they have only - documentation for the programmer (= gnulib user). Such documentation - usually goes into the lib/ source files. It may also go into doc/; - but don't add it to the module description in this case. -* Add the module to the list in MODULES.html.sh. - -You can test that a module builds correctly with: - $ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN - $ cd /tmp/testdir - $ ./configure && make - -Other things: -* Check the license and copyright year of headers. -* Check that the source code follows the GNU coding standards; - see <http://www.gnu.org/prep/standards>. -* Add source files to config/srclist* if they are identical to upstream - and should be upgraded in gnulib whenever the upstream source changes. -* Include header files in source files to verify the function prototypes. -* Make sure a replacement function doesn't cause warnings or clashes on - systems that have the function. -* Autoconf functions can use gl_* prefix. The AC_* prefix is for - autoconf internal functions. -* Build files only if they are needed on a platform. Look at the - alloca and fnmatch modules for how to achieve this. If for some - reason you cannot do this, and you have a .c file that leads to an - empty .o file on some platforms (through some big #if around all the - code), then ensure that the compilation unit is not empty after - preprocessing. One way to do this is to #include <stddef.h> or - <stdio.h> before the big #if. - - -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. - -Many Gnulib modules exist so that applications need not worry about -undesirable variability in implementations. For example, an -application that uses the 'malloc' module need not worry about (malloc -(0)) returning NULL on some Standard C platforms; and 'time_r' users -need not worry about localtime_r returning int (not 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 -<float.h>, <limits.h>, <stdarg.h>, and <stddef.h> unconditionally. It -can also assume the existence of <ctime.h>, <errno.h>, <fcntl.h>, -<locale.h>, <signal.h>, <stdio.h>, <stdlib.h>, <string.h>, and <time.h>. -Similarly, many modules include <sys/types.h> even though it's not even -in C99; that's OK since <sys/types.h> has been around nearly forever. - -Even if the include files exist, they may not conform to C89. -However, GCC has a "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. -For example, strtod and mktime have some bugs on some platforms. -You can work around some of these problems by requiring the relevant -modules, e.g., the Gnulib 'mktime' module supplies a working and -conforming 'mktime'. - -The GNU coding standards allow one departure from strict C99: Gnulib -code can assume that standard internal types like size_t are no wider -than 'long'. POSIX 1003.1-2001 and the GNU coding standards both -require 'int' to be at least 32 bits wide, so Gnulib code assumes this -as well. Gnulib code makes the following additional assumptions: - - * Signed integer arithmetic is two's complement. - - Previously, gnulib code sometimes assumed that signed integer - arithmetic wraps around, but modern compiler optimizations - sometimes do not guarantee this, and gnulib code with this - assumption is now considered to be questionable. For more, please - see the file doc/intprops.texi. - - 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. - All practical gnulib targets use two's complement. - - * There are no "holes" in integer values: all the bits of an integer - contribute to its value in the usual way. - - * Addresses and sizes behave as if objects reside in a flat address space. - In particular: - - - If two nonoverlapping objects have sizes S and T represented as - size_t values, then S + T cannot overflow. - - - A pointer P points within an object O if and only if - (char *) &O <= (char *) P && (char *) P < (char *) (&O + 1). - - - If an existing object has size S, and if T is sufficiently small - (e.g., 8 KiB), then S + T cannot overflow. Overflow in this case - would mean that the rest of your program fits into T bytes, which - can't happen in realistic flat-address-space hosts. - - * Objects with all bits zero are treated as 0 or NULL. For example, - memset (A, 0, sizeof A) initializes an array A of pointers to NULL. - - * Adding zero to a null pointer does not change the pointer. - For example, 0 + (char *) NULL == (char *) NULL. - -The above assumptions are not required by the C or POSIX standards but -hold on all practical porting targets that we're familiar with. If -you have a porting target where these assumptions are not true, we'd -appreciate hearing of any fixes. We need fixes that do not increase -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 'int') that do not conform to C99. - - -High Quality -============ - -We develop and maintain a testsuite for Gnulib. The goal is to have a -100% firm interface so that maintainers can feel free to update to the -code in git at *any* time and know that their application will not -break. This means that before any change can be committed to the -repository, a test suite program must be produced that exposes the bug -for regression testing. All experimental work should be done on -branches to help promote this. +For more information about Gnulib, including instructions about how to +contribute to Gnulib, please see the Gnulib manual, which can be found +at <http://www.gnu.org/software/gnulib/manual/>. ----- diff --git a/doc/gnulib-intro.texi b/doc/gnulib-intro.texi index d962ace..73ae140 100644 --- a/doc/gnulib-intro.texi +++ b/doc/gnulib-intro.texi @@ -77,6 +77,10 @@ failed. @node Target Platforms @section Target Platforms +Gnulib requires support for the C programming language. Most Gnulib +modules require only features from C89, the 1989 version of the C +standard. One module, @code{fts}, requires some C99 features. + Gnulib supports a number of platforms that we call the ``reasonable portability targets''. This class consists of widespread operating systems, for three years after their last availability, or --- for proprietary @@ -421,6 +425,17 @@ contribution will have to be LGPL, if the original file is available under LGPL. You can find out about it by looking for a "License: LGPL" information in the corresponding module description. +@node Tested Development +@section Tested Development +Gnulib has a test suite that is developed and maintained along with +the rest of the code. The goal is to have a +100% firm interface so that maintainers can feel free to update the +code in Git at any time and know that their application will not +break. This means that before any change can be committed to the +repository, a test suite program must be produced that exposes the bug +for regression testing. All experimental work should be done on +branches to help promote this. + @node Steady Development @section Steady Development diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 8725634..12e204d 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -59,6 +59,7 @@ Documentation License''. @menu * Introduction:: * Invoking gnulib-tool:: +* Contributing to Gnulib:: * Writing modules:: * Extending Gnulib:: * Miscellaneous Notes:: @@ -113,6 +114,7 @@ Resources: * Various Kinds of Modules:: * Collaborative Development:: * Copyright:: +* Tested Development:: * Steady Development:: * Openness:: @end menu @@ -122,6 +124,298 @@ Resources: @include gnulib-tool.texi +@node Contributing to Gnulib +@chapter Contributing to Gnulib + +All Gnulib software is copyrighted by the Free Software Foundation. +You need to have filled out an assignment form for a project that uses the +module for that contribution to be accepted here. + +If you have a piece of code that you would like to contribute, please +email @email{bug-gnulib@@gnu.org}. You can review the archives, +subscribe, etc., via @url{http://lists.gnu.org/mailman/listinfo/bug-gnulib}. + +Generally we are looking for files that fulfill at least one of the +following requirements: + +@itemize +@item +If your @code{.c} and @code{.h} files define functions that are broken or +missing on some other system, we should be able to include it. + +@item +If your functions remove arbitrary limits from existing functions +(either under the same name, or as a slightly different name), we +should be able to include it. + +@item +If your functions define completely new but rarely used functionality, +you should probably consider packaging it as a separate library. +@end itemize + +@menu +* Gnulib's Licensing:: +* Indent with Spaces:: +* How to Add a New Module:: +* Portability Guidelines:: +@end menu + +@node Gnulib's Licensing +@section Gnulib's Licensing + +Gnulib contains code both under the GPL and the LGPL@. Because +several packages that use Gnulib are GPLed, the files state they are +licensed under the GPL@. However, to support LGPLed projects as well, +you may use some of the files under the LGPL@. The ``License:'' +information in the files under @file{modules/} clarifies the real license +that applies to the module source. + +Keep in mind that if you submit patches to files in Gnulib, you should +license them under a compatible license, which means that sometimes +the contribution will have to be LGPLed if the original file is +available under LGPL via a ``License: LGPL'' information in the +projects' @file{modules/} file. + +@node Indent with Spaces +@section Indent with Spaces, not TABs + +We use space-only indentation in nearly all files. This includes all +@code{*.h}, @code{*.c}, @code{*.y} files, except for the @code{regex} module. +@file{Makefile} and @file{ChangeLog} +files are excluded, since TAB characters are part of their format. + +In order to tell your editor to produce space-only indentation, you +can use these instructions. + +@table @asis +@item For Emacs: +Add these lines to your Emacs initialization file +(@file{$HOME/.emacs} or similar): + +@example +;; In gnulib, indent with spaces everywhere (not TABs). +;; Exceptions: Makefile and ChangeLog modes. +(add-hook 'find-file-hook '(lambda () + (if (and buffer-file-name + (string-match "/gnulib\\>" (buffer-file-name)) + (not (string-equal mode-name "Change Log")) + (not (string-equal mode-name "Makefile"))) + (setq indent-tabs-mode nil)))) +@end example + +@item For vi (vim): +Add these lines to your @file{$HOME/.vimrc} file: + +@example +" Don't use tabs for indentation. Spaces are nicer to work with. +set expandtab +@end example + +For Makefile and ChangeLog files, compensate this by adding this to +your @file{$HOME/.vim/after/indent/make.vim} and +@file{$HOME/.vim/after/indent/changelog.vim} files: + +@example +" Use tabs for indentation, regardless of the global setting. +set noexpandtab +@end example + +@item For Eclipse: +In the ``Window|Preferences'' dialog (or ``Eclipse|Preferences'' +dialog on MacOS), + +@enumerate +@item +Under ``General|Editors|Text Editors'', select the ``Insert spaces for tabs'' +checkbox. +@item +Under ``C/C++|Code Style'', select a code style profile that has the +``Indentation|Tab policy'' combobox set to ``Spaces only'', such as the +``GNU [built-in]'' policy. +@end enumerate +@end table + +If you use the GNU indent program, pass it the option '--no-tabs'. + + +@node How to Add a New Module +@section How to Add a New Module + +@itemize +@item +Add the header files and source files to lib/. + +@item +If the module needs configure-time checks, write an autoconf +macro for it in @file{m4/@var{module}.m4}. See m4/README for details. + +@item +Write a module description @file{modules/@var{module}}, based on +@file{modules/TEMPLATE}. + +@item +If the module contributes a section to the end-user documentation, put +this documentation in @file{doc/@var{module}.texi} and add it to the +``Files'' section of @file{modules/@var{module}}. Most modules don't +do this; they have only documentation for the programmer (the gnulib +user). Such documentation usually goes into the @file{lib/} source +files. It may also go into @file{doc/}; but don't add it to the +module description in this case. + +@item +Add the module to the list in @file{MODULES.html.sh}. +@end itemize + +@noindent +You can test that a module builds correctly with: + +@example +$ ./gnulib-tool --create-testdir --dir=/tmp/testdir module1 ... moduleN +$ cd /tmp/testdir +$ ./configure && make +@end example + +@noindent +Other things: + +@itemize +@item +Check the license and copyright year of headers. +@item +Check that the source code follows the GNU coding standards; +see @url{http://www.gnu.org/prep/standards}. +@item +Add source files to @file{config/srclist*} if they are identical to upstream +and should be upgraded in gnulib whenever the upstream source changes. +@item +Include header files in source files to verify the function prototypes. +@item +Make sure a replacement function doesn't cause warnings or clashes on +systems that have the function. +@item +Autoconf functions can use the @code{gl_*} prefix. The @code{AC_*} prefix is for +Autoconf internal functions. +@item +Build files only if they are needed on a platform. Look at the +@code{alloca} and @code{fnmatch} modules for how to achieve this. If for some +reason you cannot do this, and you have a @code{.c} file that leads to an +empty @code{.o} file on some platforms (through some big @code{#if} around all the +code), then ensure that the compilation unit is not empty after +preprocessing. One way to do this is to @code{#include <stddef.h>} or +@code{<stdio.h>} before the big @code{#if}. +@end itemize + +@node Portability Guidelines +@section Portability Guidelines + +Gnulib code is intended to be portable to a wide variety of platforms, +not just GNU platforms. @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 NULL on some Standard C 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 Gnulib assumes 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 Gnulib assumes a freestanding C89 compiler, Gnulib code can include +@code{<float.h>}, @code{<limits.h>}, @code{<stdarg.h>}, and +@code{<stddef.h>} unconditionally. It can also assume the existence +of @code{<ctime.h>}, @code{<errno.h>}, @code{<fcntl.h>}, +@code{<locale.h>}, @code{<signal.h>}, @code{<stdio.h>}, +@code{<stdlib.h>}, @code{<string.h>}, and @code{<time.h>}. Similarly, +many modules include @code{<sys/types.h>} even though it's not even in +C99; that's OK since @code{<sys/types.h>} has been around nearly +forever. + +Even if the include files exist, they may not conform to C89. +However, GCC has a @code{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. +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: + +@itemize +@item +Signed integer arithmetic is two's complement. + +Previously, Gnulib code sometimes assumed that signed integer +arithmetic wraps around, but modern compiler optimizations +sometimes do not guarantee this, and Gnulib code with this +assumption is now considered to be questionable. For more, please +see the file doc/intprops.texi. + +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. +All practical Gnulib targets use two's complement. + +@item +There are no ``holes'' in integer values: all the bits of an integer +contribute to its value in the usual way. + +@item +Addresses and sizes behave as if objects reside in a flat address space. +In particular: + +@itemize +@item +If two nonoverlapping objects have sizes @var{S} and @var{T} +represented as @code{size_t} values, then @code{@var{S} + @var{T}} +cannot overflow. + +@item +A pointer @var{P} points within an object @var{O} if and only if +@code{(char *) &@var{O} <= (char *) @var{P} && (char *) @var{P} < +(char *) (&@var{O} + 1)}. + +@item +If an existing object has size @var{S}, and if @var{T} is sufficiently +small (e.g., 8 KiB), then @code{@var{S} + @var{T}} cannot overflow. +Overflow in this case would mean that the rest of your program fits +into @var{T} bytes, which can't happen in realistic flat-address-space +hosts. +@end itemize + +@item +Objects with all bits zero are treated as 0 or @code{NULL}@. For +example, @code{memset (A, 0, sizeof A)} initializes an array @code{A} +of pointers to @code{NULL}@. + +@item +Adding zero to a null pointer does not change the pointer. +For example, @code{0 + (char *) NULL == (char *) NULL}@. +@end itemize + +The above assumptions are not required by the C or POSIX standards but +hold on all practical porting targets that we're familiar with. If +you have a porting target where these assumptions are not true, we'd +appreciate hearing of any fixes. We need fixes that do not increase +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. @node Writing modules @chapter Writing modules @@ -518,6 +812,15 @@ maintenance. @node Unit test modules @section Unit test modules +Gnulib has a test suite that is developed and maintained along with +the rest of the code. The goal is to have a +100% firm interface so that maintainers can feel free to update the +code in Git at any time and know that their application will not +break. This means that before any change can be committed to the +repository, a test suite program must be produced that exposes the bug +for regression testing. All experimental work should be done on +branches to help promote this. + A unit test that is a simple C program usually has a module description as simple as this: -- 1.7.6.5
