* 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.
@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
Here, the @code{TESTS_ENVIRONMENT} variable can be used to pass values
determined by @code{configure} or by the @code{Makefile} to the shell
-script, as environment variables.
+script, as environment variables. The values of @code{EXEEXT} and of
+@code{srcdir}, from Autoconf and Automake, are already provided as
+environment variables, through an initial value of @code{TESTS_ENVIRONMENT}
+that @code{gnulib-tool} puts in place.
Regardless of the specific form of the unit test, the following guidelines
should be respected:
@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::
@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{<fcntl.h>} 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{<fcntl.h>} and use it in a compilation unit that does not include
+@code{<fcntl.h>}, 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
* setutent::
* updwtmp::
* utmpname::
+* login_tty::
@end menu
@include glibc-functions/endutent.texi
@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{<utmpx.h>}
* func::
* warnings::
* manywarnings::
+* Running self-tests under valgrind::
@end menu
@node alloca
@include manywarnings.texi
+@include valgrind-tests.texi
+
@node GNU Free Documentation License
@appendix GNU Free Documentation License
projects / gnulib.git / blobdiff