Mercurial > hg > octave-nkf > gnulib-hg
changeset 17221:b1657348957e
doc: move README into manual
* README: Move contents to new file doc/gnulib-readme.texi.
Replace with a one-line summary.
* doc/gnulib.texi (Brief Overview): New section,
with old intro preface. Include gnulib-readme.texi for contents.
(Philosophy): Rename from "Introduction", since this
section no longer introduces the rest. Write a new preface.
* doc/gnulib-readme.texi: New file, with the old contents of
README texinfo-ized. This way, the README info appears
in the online and printed manual.
author | Paul Eggert <eggert@cs.ucla.edu> |
---|---|
date | Wed, 26 Dec 2012 13:38:22 -0800 |
parents | 4c84368f0916 |
children | 1c4d62fce4a1 |
files | ChangeLog README doc/gnulib-readme.texi doc/gnulib.texi |
diffstat | 4 files changed, 459 insertions(+), 323 deletions(-) [+] |
line wrap: on
line diff
--- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,16 @@ +2012-12-27 Paul Eggert <eggert@cs.ucla.edu> + + doc: move README into manual + * README: Move contents to new file doc/gnulib-readme.texi. + Replace with a one-line summary. + * doc/gnulib.texi (Brief Overview): New section, + with old intro preface. Include gnulib-readme.texi for contents. + (Philosophy): Rename from "Introduction", since this + section no longer introduces the rest. Write a new preface. + * doc/gnulib-readme.texi: New file, with the old contents of + README texinfo-ized. This way, the README info appears + in the online and printed manual. + 2012-12-25 Ben Pfaff <blp@cs.stanford.edu> c-xvasprintf: Fix "implicit declaration of function" GCC warning.
--- a/README +++ b/README @@ -1,320 +1,1 @@ -Gnulib -====== - -While portability across operating systems is not one of GNU's primary -goals, it has helped introduce many people to the GNU system, and is -worthwhile when it can be achieved at a low cost. This collection helps -lower that cost. - -Gnulib is intended to be the canonical source for most of the important -"portability" and/or common files for GNU projects. These are files -intended to be shared at the source level; Gnulib is not a typical -library meant to be installed and linked against. Thus, unlike most -projects, Gnulib does not normally generate a source tarball -distribution; instead, developers grab modules directly from the -source repository. - -The easiest, and recommended, way to do this is to use the gnulib-tool -script. Since there is no installation procedure for Gnulib, -gnulib-tool needs to be run directly in the directory that contains the -Gnulib source code. You can do this either by specifying the absolute -filename of gnulib-tool, or by using a symbolic link from a -place inside your PATH to the gnulib-tool file of your preferred -Gnulib checkout. For example: - $ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool - -The home page for Gnulib is http://www.gnu.org/software/gnulib. - - -git and CVS -=========== - -Gnulib is available for anonymous checkout. In any Bourne-shell the -following should work: - $ git clone git://git.sv.gnu.org/gnulib.git - -For a read-write checkout you need to have a login on savannah.gnu.org and be -a member of the gnulib project at http://savannah.gnu.org/projects/gnulib . -Then, instead of the URL - git://git.sv.gnu.org/gnulib -use the URL - ssh://<user>@git.sv.gnu.org/srv/git/gnulib -where <user> is your login name on savannah.gnu.org. - -git resources: - Overview: http://en.wikipedia.org/wiki/Git_(software) - Homepage: http://git.or.cz/ - Download: http://www.kernel.org/pub/software/scm/git/ - Tutorial: http://git.or.cz/course/ - http://www.kernel.org/pub/software/scm/git/docs/tutorial.html - FAQ: http://git.or.cz/gitwiki/GitFaq - -When you use "git annotate" or "git blame" with gnulib, it's recommended that -you use the "-w" option, in order to ignore massive whitespace changes that -happened in 2009. - -CVS checkouts are also supported: - $ cvs -d :pserver:anonymous@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD - -Gnulib is hosted on savannah.gnu.org. The project page is -http://savannah.gnu.org/projects/gnulib. - - -Keeping Up-to-date -================== - -The best way to work with Gnulib is to check it out of git. -Subscribing to the bug-gnulib@gnu.org mailing list will help you to -plan when to update your local copy of Gnulib (which you use to -maintain your software) from git. To synchronize, you can use "git pull", -or "cvs update -dP" if you are still using CVS. - -Sometimes, using an updated version of Gnulib will require you to use -newer versions of GNU Automake or Autoconf. You may find it helpful -to join the autotools-announce mailing list to be advised of such -changes. - - -Contributing to Gnulib -====================== - -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 Mac OS), - 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. - - ------ -Copyright 2001, 2003-2012 Free Software Foundation, Inc. - -This program is free software: you can redistribute it and/or modify -it under the terms of the GNU General Public License as published by -the Free Software Foundation; either version 3 of the License, or -(at your option) any later version. - -This program is distributed in the hope that it will be useful, -but WITHOUT ANY WARRANTY; without even the implied warranty of -MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the -GNU General Public License for more details. - -You should have received a copy of the GNU General Public License -along with this program. If not, see <http://www.gnu.org/licenses/>. +Please see doc/gnulib-readme.texi for basic information about Gnulib.
new file mode 100644 --- /dev/null +++ b/doc/gnulib-readme.texi @@ -0,0 +1,432 @@ +@c Gnulib README + +@c Copyright 2001, 2003-2012 Free Software Foundation, Inc. + +@c Permission is granted to copy, distribute and/or modify this document +@c under the terms of the GNU Free Documentation License, Version 1.3 +@c or any later version published by the Free Software Foundation; +@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover +@c Texts. A copy of the license is included in the ``GNU Free +@c Documentation License'' file as part of this distribution. + +@menu +* Gnulib Basics:: +* git and CVS:: +* Keeping Up-to-date:: +* Contributing to Gnulib:: +* High Quality:: +@end menu + +@node Gnulib Basics +@section Gnulib Basics + +While portability across operating systems is not one of GNU's primary +goals, it has helped introduce many people to the GNU system, and is +worthwhile when it can be achieved at a low cost. This collection helps +lower that cost. + +Gnulib is intended to be the canonical source for most of the important +``portability'' and/or common files for GNU projects. These are files +intended to be shared at the source level; Gnulib is not a typical +library meant to be installed and linked against. Thus, unlike most +projects, Gnulib does not normally generate a source tarball +distribution; instead, developers grab modules directly from the +source repository. + +The easiest, and recommended, way to do this is to use the +@command{gnulib-tool} script. Since there is no installation +procedure for Gnulib, @command{gnulib-tool} needs to be run directly +in the directory that contains the Gnulib source code. You can do +this either by specifying the absolute filename of +@command{gnulib-tool}, or by using a symbolic link from a place inside +your @env{PATH} to the @command{gnulib-tool} file of your preferred +Gnulib checkout. For example: + +@example +$ ln -s $HOME/gnu/src/gnulib.git/gnulib-tool $HOME/bin/gnulib-tool +@end example + +The home page for Gnulib is @url{http://www.gnu.org/software/gnulib}. + +@node git and CVS +@section git and CVS + +Gnulib is available for anonymous checkout. In any Bourne-shell the +following should work: + +@example +$ git clone git://git.sv.gnu.org/gnulib.git +@end example + +For a read-write checkout you need to have a login on +@samp{savannah.gnu.org} and be a member of the Gnulib project at +@url{http://savannah.gnu.org/projects/gnulib}. Then, instead of the +URL @url{git://git.sv.gnu.org/gnulib}, use the URL +@samp{ssh://@var{user}@@git.sv.gnu.org/srv/git/gnulib} where +@var{user} is your login name on savannah.gnu.org. + +git resources: + +@table @asis +@item Overview: +@url{http://en.wikipedia.org/wiki/Git_(software)} +@item Homepage: +@url{http://git.or.cz/} +@item Download: +@url{http://www.kernel.org/pub/software/scm/git/} +@item Tutorial: +@url{http://git.or.cz/course/} +@url{http://www.kernel.org/pub/software/scm/git/docs/tutorial.html} +@item FAQ: +@url{http://git.or.cz/gitwiki/GitFaq} +@end table + +When you use @code{git annotate} or @code{git blame} with Gnulib, it's +recommended that you use the @option{-w} option, in order to ignore +massive whitespace changes that happened in 2009. + +CVS checkouts are also supported: + +@example +$ cvs -d :pserver:anonymous@@pserver.git.sv.gnu.org:/gnulib.git co -d gnulib HEAD +@end example + +Gnulib is hosted on @samp{savannah.gnu.org}. The project page is +@url{http://savannah.gnu.org/projects/gnulib}. + +@node Keeping Up-to-date +@section Keeping Up-to-date + +The best way to work with Gnulib is to check it out of git. +Subscribing to the @email{bug-gnulib@@gnu.org} mailing list will help you to +plan when to update your local copy of Gnulib (which you use to +maintain your software) from git. To synchronize, you can use @code{git pull}, +or @code{cvs update -dP} if you are still using CVS. + +Sometimes, using an updated version of Gnulib will require you to use +newer versions of GNU Automake or Autoconf. You may find it helpful +to join the autotools-announce mailing list to be advised of such +changes. + +@node Contributing to Gnulib +@section Contributing to Gnulib + +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 @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 @file{.c} and @file{.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. +@end itemize + +If your functions define completely new but rarely used functionality, +you should probably consider packaging it as a separate library. + +@menu +* Gnulib licensing:: +* Indent with spaces not TABs:: +* How to add a new module:: +* Portability guidelines:: +@end menu + +@node Gnulib licensing +@subsection Gnulib licensing + +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. + +@node Indent with spaces not TABs +@subsection Indent with spaces not TABs + +We use space-only indentation in nearly all files. This includes all +@file{*.h}, @file{*.c}, @file{*.y} files, except for the @code{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. + +@itemize +@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 Mac OS), + +@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 + +If you use the GNU indent program, pass it the option @option{--no-tabs}. +@end itemize + +@node How to add a new module +@subsection How to add a new module + +@itemize +@item +Add the header files and source files to @file{lib/}. + +@item +If the module needs configure-time checks, write an Autoconf +macro for it in @file{m4/@var{module}.m4}. See @file{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 (= 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 @samp{gl_*} prefix. The @samp{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 @file{.c} file that +leads to an empty @file{.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 +@subsection 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 @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 +@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 +@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 @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. +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. +@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. +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. + +@item +Objects with all bits zero are treated as 0 or NULL@. For example, +@code{memset@ (A, 0, sizeof@ A)} initializes an array @code{A} of +pointers to NULL. + +@item +Adding zero to a null pointer does not change the pointer. +For example, @code{0 + (char *) NULL == (char *) NULL}. +@end itemize +@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 High Quality +@section 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 @emph{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. + +@c This copyright notice applies to this file. +@c Generate it as output too, if the file is being formatted by itself. +@c Otherwise, it should be formatted as part of a larger document +@c that contains the relevant copyright notice. +@ifset standalone +Copyright @copyright{} 2001, 2003--2012 Free Software Foundation, Inc. + +Permission is granted to copy, distribute and/or modify this document +under the terms of the GNU Free Documentation License, Version 1.3 or +any later version published by the Free Software Foundation; with no +Invariant Sections, with no Front-Cover Texts, and with no Back-Cover +Texts. A copy of the license is included in the ``GNU Free +Documentation License'' file as part of this distribution. +@end ifset
--- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -57,7 +57,8 @@ @end ifnottex @menu -* Introduction:: +* Brief Overview:: +* Philosophy:: * Invoking gnulib-tool:: * Writing modules:: * Extending Gnulib:: @@ -87,8 +88,8 @@ @end macro -@node Introduction -@chapter Introduction +@node Brief Overview +@chapter Brief Overview Gnulib is a source code library. It provides basic functionality to programs and libraries. Currently (as of October 2006) more than 30 @@ -104,6 +105,15 @@ @url{http://www.gnu.org/software/gnulib/}. @end itemize +@include gnulib-readme.texi + +@node Philosophy +@chapter Philosophy + +Gnulib's design and development philosophy is organized around steady, +collaborative, and open development of reusable modules that are +suitable for a reasonably wide variety of platforms. + @menu * Benefits:: * Library vs Reusable Code::