X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=a1f54461cf987c13216342262160dfa431864218;hb=32fa5a49695a1e738873537bc5db98be2d83d4a8;hp=0a8469194340d8be5086d1d26db489d99f2494a8;hpb=368e66277a1fdb07a508f9c3ff5d5669e4b4e838;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 0a8469194..a1f54461c 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -54,6 +54,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. @@ -117,8 +118,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,12 +609,92 @@ 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 @menu * Out of memory handling:: * Obsolete modules:: +* Extra tests modules:: +* A C++ namespace for gnulib:: A different way of using Gnulib in C++ * Library version handling:: * Windows sockets:: * Libtool and Windows:: @@ -688,6 +769,147 @@ This module is obsolete. @end example +@node Extra tests modules +@section Extra tests modules + +@cindex Extra tests modules +@cindex C++ tests modules +@cindex tests modules, C++ +@cindex long-running tests modules +@cindex tests modules, long-running +@cindex privileged tests modules +@cindex tests modules, privileged +@cindex unportable tests modules +@cindex tests modules, unportable +Test modules can be marked with some special status attributes. When a +test module has such an attribute, @code{gnulib-tool --import} will not +include it by default. + +The supported status attributes are: + +@table @code +@item c++-test +Indicates that the test is testing C++ interoperability. Such a test is +useful in a C++ or mixed C/C++ package, but is useless in a C package. + +@item longrunning-test +Indicates that the test takes a long time to compile or execute (more +than five minutes or so). Such a test is better avoided in a release +that is made for the general public. + +@item privileged-test +Indicates that the test will request special privileges, for example, +ask for the superuser password. Such a test may hang when run +non-interactively and is therefore better avoided in a release that is +made for the general public. + +@item unportable-test +Indicates that the test is known to fail on some systems, and that +there is no workaround about it. Such a test is better avoided in a +release that is made for the general public. +@end table + +@code{gnulib-tool --import} will not include tests marked with these +attributes by default. When @code{gnulib-tool} is invoked with one +of the options @code{--with-c++-tests}, @code{--with-longrunning-tests}, +@code{--with-privileged-tests}, @code{--with-unportable-tests}, it +will include tests despite the corresponding special status attribute. +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} 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: + +@example +Status: +longrunning-test +@end example + +If only a part of a test deserves a particular status attribute, you +can split the module into a primary and a secondary test module, +say @code{foo-tests} and @code{foo-extra-tests}. Then add a dependency +from @code{foo-tests} to @code{foo-extra-tests}, and mark the +@code{foo-extra-tests} with the particular status attribute. + + +@node A C++ namespace for gnulib +@section A C++ namespace for gnulib + +The function definitions provided by Gnulib (@code{.c} code) are meant +to be compiled by a C compiler. The header files (@code{.h} files), +on the other hand, can be used in either C or C++. + +By default, when used in a C++ compilation unit, the @code{.h} files +declare the same symbols and overrides as in C mode, except that functions +defined by Gnulib or by the system are declared as @samp{extern "C"}. + +It is also possible to indicate to Gnulib to provide many of its symbols +in a dedicated C++ namespace. If you define the macro +@code{GNULIB_NAMESPACE} to an identifier, many functions will be defined +in the namespace specified by the identifier instead of the global +namespace. For example, after you have defined +@smallexample +#define GNULIB_NAMESPACE gnulib +@end smallexample +@noindent +at the beginning of a compilation unit, Gnulib's @code{} header +file will make available the @code{open} function as @code{gnulib::open}. +The symbol @code{open} will still refer to the system's @code{open} function, +with its platform specific bugs and limitations. + +The symbols provided in the Gnulib namespace are those for which the +corresponding header file contains a @code{_GL_CXXALIAS_RPL} or +@code{_GL_CXXALIAS_SYS} macro invocation. + +The benefits of this namespace mode are: +@itemize +@item +Gnulib defines fewer symbols as preprocessor macros. For example, on a +platform where @code{open} has to be overridden, Gnulib normally does +@code{#define open rpl_open}. If your package has a class with a member +@code{open}, for example a class @code{foo} with a method @code{foo::open}, +then if you define this member in a compilation unit that includes +@code{} and use it in a compilation unit that does not include +@code{}, or vice versa, you will get a link error. Worse: You +will not notice this problem on the platform where the system's @code{open} +function works fine. This problem goes away in namespace mode. + +@item +It provides a safety check whether the set of modules your package requests +from Gnulib is sufficient. For example, if you use the function +@code{gnulib::open} in your code, and you forgot to request the module +@samp{open} from Gnulib, you will get a compilation error (regardless of +the platform). +@end itemize + +The drawback of this namespace mode is that the system provided symbols in +the global namespace are still present, even when they contain bugs that +Gnulib fixes. For example, if you call @code{open (...)} in your code, +it will invoke the possibly buggy system function, even if you have +requested the module @samp{open} from gnulib-tool. + +You can turn on the namespace mode in some compilation units and keep it +turned off in others. This can be useful if your package consists of +an application layer that does not need to invoke POSIX functions and +an operating system interface layer that contains all the OS function +calls. In such a situation, you will want to turn on the namespace mode +for the application layer --- to avoid many preprocessor macro +definitions --- and turn it off for the OS interface layer --- to avoid +the drawback of the namespace mode, mentioned above. + + @node Library version handling @section Library version handling @@ -6169,6 +6391,7 @@ This list of functions is sorted according to the header that declares them. * setutent:: * updwtmp:: * utmpname:: +* login_tty:: @end menu @include glibc-functions/endutent.texi @@ -6182,6 +6405,7 @@ This list of functions is sorted according to the header that declares them. @include glibc-functions/setutent.texi @include glibc-functions/updwtmp.texi @include glibc-functions/utmpname.texi +@include glibc-functions/login_tty.texi @node Glibc utmpx.h @section Glibc Extensions to @code{} @@ -6271,6 +6495,7 @@ This list of functions is sorted according to the header that declares them. * func:: * warnings:: * manywarnings:: +* Running self-tests under valgrind:: @end menu @node alloca @@ -6369,6 +6594,8 @@ generated automatically. @include manywarnings.texi +@include valgrind-tests.texi + @node GNU Free Documentation License @appendix GNU Free Documentation License