X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=3e1599c801ee9cb591bb253039e5ac01d3329bde;hb=a88d2561c2cdb9bde56bec1c858a5f64c6ad28c0;hp=4cbc9e74b75c2466d0fbc8839ab46e3d0f837913;hpb=e85c3f8fb0807bed4ce05f5b410d1e4d3929bc6e;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 4cbc9e74b..3e1599c80 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 @@ -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 @@ -906,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 @@ -6407,7 +6490,6 @@ 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:: @@ -6489,16 +6571,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 @@ -6517,6 +6589,34 @@ generated automatically. @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