X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=966560d595aa52f9714e3a9e102a838adaf312f1;hb=52c4f309aad0bce5307f2cca26b59b76ed7574ab;hp=74499b5d5e4a7257e1ec87ea4c647def795ac036;hpb=1d19f103323b9ad6c43a27049f5ce7c4a586d989;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 74499b5d5..966560d59 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -2,8 +2,14 @@ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib +@c Define a new index for the magic constants in regex.texi. +@defcodeindex cn @syncodeindex fn cp +@syncodeindex ky cp @syncodeindex pg cp +@syncodeindex tp cp +@syncodeindex vr cp +@syncodeindex cn cp @ifclear texi2html @firstparagraphindent insert @end ifclear @@ -17,7 +23,7 @@ This manual is for GNU Gnulib (updated @value{UPDATED}), which is a library of common routines intended to be shared at the source level. -Copyright @copyright{} 2004-2010 Free Software Foundation, Inc. +Copyright @copyright{} 2004-2011 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 @@ -54,6 +60,7 @@ Documentation License''. * Introduction:: * Invoking gnulib-tool:: * Writing modules:: +* Extending Gnulib:: * Miscellaneous Notes:: * POSIX Substitutes Library:: Building as a separate substitutes library. * Header File Substitutes:: Overriding system headers. @@ -62,6 +69,7 @@ Documentation License''. * Glibc Header File Substitutes:: Overriding system headers. * Glibc Function Substitutes:: Replacing system functions. * Particular Modules:: Documentation of individual modules. +* Regular expressions:: The regex module. * GNU Free Documentation License:: Copying and sharing this manual. * Index:: @end menu @@ -117,8 +125,8 @@ Resources: @node Writing modules @chapter Writing modules -This chapter explains how to write modules of your own, either for your own -package (to be used with gnulib-tool's @samp{--local-dir} option), or for +This chapter explains how to write modules of your own, either to +extend Gnulib for your own package (@pxref{Extending Gnulib}), or for inclusion in gnulib proper. The guidelines in this chapter do not necessarily need to be followed for @@ -608,6 +616,84 @@ before every release. @end enumerate +@node Extending Gnulib +@chapter Extending Gnulib + +Gnulib modules are intended to be suitable for widespread use. Most +problems with Gnulib can and should be fixed in a generic way, so that +all of Gnulib's users can benefit from the change. But occasionally a +problem arises that is difficult or undesirable to fix generically, or +a project that uses Gnulib may need to work around an issue before the +Gnulib maintainers commit a final fix. Maintainers may also want to +add their own pools of modules to projects as Gnulib ``staging +areas.'' + +The obvious way to make local changes to Gnulib modules is to use +@command{gnulib-tool} to check out pristine modules, then to modify +the results in-place. This works well enough for short-lived +experiments. It is harder to keep modified versions of Gnulib modules +for a long time, even though Git (or another distributed version +control systems) can help out a lot with this during the development +process. + +Git, however, doesn't address the distribution issue. When a package +``foobar'' needs a modified version of, say, @file{stdint.in.h}, it +either has to put a comment into @file{foobar/autogen.sh} saying +``Attention! This doesn't work with a pristine Gnulib, you need this +and that patch after checking out Gnulib,'' or it has to use the +@samp{--avoid=stdint} option and provide the modified @code{stdint} +module in a different directory. + +The @option{--local-dir} option to @command{gnulib-tool} solves this +problem. It allows the package to override or augment Gnulib. This +means: + +@itemize @bullet +@item +You can store files that are to override Gnulib files or modules. + +@item +You can store context diffs to be applied to Gnulib files. + +@item +You can add modules of your own, that are not (yet) in Gnulib. + +@item +You can also add unstructured amounts of code to the library, by +grouping the non-Gnulib files of the library in a single kitchen-sink +``module.'' (This kind of kitchen-sink module is not needed when you +use the @command{gnulib-tool} option @samp{--makefile-name}.) +@end itemize + +In a release tarball, you can distribute the contents of this +@option{--local-dir} directory that will be combinable with newer +versions of Gnulib, barring incompatible changes to Gnulib. + +If the @samp{--local-dir=@var{directory}} option is specified, then +@command{gnulib-tool} looks in @file{@var{directory}} whenever it +reads a file from the Gnulib directory. Suppose @command{gnulib-tool} +is looking for @var{file}. Then: + +@itemize @bullet +@item +If @file{@var{directory}/@var{file}} exists, then @samp{gnulib-tool} uses +it instead of the file included in Gnulib. + +@item +Otherwise, if @file{@var{directory}/@var{file}.diff} exists, then +@command{gnulib-tool} uses the file from Gnulib after applying the diff +using the @command{patch} program. + +@item +Otherwise, @command{gnulib-tool} uses the file included in Gnulib. +@end itemize + +Please make wise use of this option. It also allows you to easily +hold back modifications you make to Gnulib macros in cases it may be +better to share them. + + + @node Miscellaneous Notes @chapter Miscellaneous Notes @@ -629,40 +715,37 @@ before every release. @cindex Out of Memory handling @cindex Memory allocation failure -The GSS API does not have a standard error code for the out of memory -error condition. Instead of adding a non-standard error code, this -library has chosen to adopt a different strategy. Out of memory -handling happens in rare situations, but performing the out of memory -error handling after almost all API function invocations pollute your -source code and might make it harder to spot more serious problems. -The strategy chosen improves code readability and robustness. +The gnulib API does not have a standard error code for the out of memory +error condition. Instead of adding a non-standard error code, gnulib +has chosen to adopt a different strategy. Out of memory handling +happens in rare situations, but performing the out of memory error +handling after almost all API function invocations pollute your source +code and might make it harder to spot more serious problems. The +strategy chosen improves code readability and robustness. @cindex Aborting execution For most applications, aborting the application with an error message when the out of memory situation occurs is the best that can be wished -for. This is how the library behaves by default. - -@vindex xalloc_fail_func -However, we realize that some applications may not want to have the -GSS library abort execution in any situation. The GSS library supports -a hook to let the application regain control and perform its own -cleanups when an out of memory situation has occurred. The application -can define a function (having a @code{void} prototype, i.e., no return -value and no parameters) and set the library variable -@code{xalloc_fail_func} to that function. The variable should be +for. This is how the library behaves by default (using +the @samp{xalloc-die} module). + +@vindex xalloc_die +However, we realize that some applications may not want to abort +execution in any situation. Gnulib supports a hook to let the +application regain control and perform its own cleanups when an out of +memory situation has occurred. The application can define a function +(having a @code{void} prototype, i.e., no return value and no +parameters) and set the library variable +@code{xalloc_die} to that function. The variable should be declared as follows. @example -extern void (*xalloc_fail_func) (void); +extern void (*xalloc_die) (void); @end example -The GSS library will invoke this function if an out of memory error -occurs. Note that after this the GSS library is in an undefined -state, so you must unload or restart the application to continue call -GSS library functions. The hook is only intended to allow the -application to log the situation in a special way. Of course, care -must be taken to not allocate more memory, as that will likely also -fail. +Gnulib will invoke this function if an out of memory error occurs. Note +that the function should not return. Of course, care must be taken to +not allocate more memory, as that will likely also fail. @node Obsolete modules @@ -739,8 +822,16 @@ When @code{gnulib-tool} receives the option @code{--with-all-tests}, it will include all tests regardless of their status attributes. @code{gnulib-tool --create-testdir} and -@code{gnulib-tool --create-megatestdir} always include all tests -regardless of their status attributes. +@code{gnulib-tool --create-megatestdir} by default include all tests of +modules specified on the command line, regardless of their status +attributes. Tests of modules occurring as dependencies are not included +by default if they have one of these status attributes. The options +@code{--with-c++-tests}, @code{--with-longrunning-tests}, +@code{--with-privileged-tests}, @code{--with-unportable-tests} are +recognized here as well. Additionally, @code{gnulib-tool} also +understands the options @code{--without-c++-tests}, +@code{--without-longrunning-tests}, @code{--without-privileged-tests}, +@code{--without-unportable-tests}. In order to mark a module with a status attribute, you need to add it to the module description, like this: @@ -898,7 +989,7 @@ XP. The function declaration is present if @code{WINVER >= 0x0501}. Windows 2000 does not have getaddrinfo in its @file{WS2_32.DLL}. Thus, if you want to assume Windows XP or later, you can add -AC_DEFINE(WINVER, 0x0501) to avoid compiling to (partial) getaddrinfo +AC_DEFINE(WINVER, 0x0501) to avoid compiling the (partial) getaddrinfo implementation. If you want to support Windows 2000, don't do anything. The @@ -6399,15 +6490,16 @@ This list of functions is sorted according to the header that declares them. * Quoting:: * error and progname:: * gcd:: -* Regular expressions:: * Searching for Libraries:: * Exported Symbols of Shared Libraries:: * LD Version Scripts:: * Visual Studio Compatibility:: * Supporting Relocation:: * func:: +* configmake:: * warnings:: * manywarnings:: +* Running self-tests under valgrind:: @end menu @node alloca @@ -6480,16 +6572,6 @@ ASCII characters. @include gcd.texi -@node Regular expressions -@section Regular expressions - -Gnulib supports many different types of regular expressions; although -the underlying features are the same or identical, the syntax used -varies. The descriptions given here for the different types are -generated automatically. - -@include regexprops-generic.texi - @include havelib.texi @include lib-symbol-visibility.texi @@ -6502,10 +6584,42 @@ generated automatically. @include func.texi +@include configmake.texi + @include warnings.texi @include manywarnings.texi +@include valgrind-tests.texi + +@node Regular expressions +@chapter Regular expressions + +@menu +* Overview:: +* Regular Expression Syntax:: +* Common Operators:: +* GNU Operators:: +* GNU Emacs Operators:: +* What Gets Matched?:: +* Programming with Regex:: +* Regular expression syntaxes:: +@end menu + +@lowersections +@include regex.texi +@raisesections + +@node Regular expression syntaxes +@section Regular expression syntaxes + +Gnulib supports many different types of regular expressions; although +the underlying features are the same or identical, the syntax used +varies. The descriptions given here for the different types are +generated automatically. + +@include regexprops-generic.texi + @node GNU Free Documentation License @appendix GNU Free Documentation License