From 67d14683778cb3fd8dbfda5a03f5fe407f57389a Mon Sep 17 00:00:00 2001 From: Bruno Haible Date: Wed, 10 May 2017 19:19:51 +0200 Subject: [PATCH] Prepare for reordering sections in the manual. * doc/gnulib.texi: Move several sections to separate files. Include these files. * doc/out-of-memory.texi: New file, extracted from doc/gnulib.texi. * doc/obsolete.texi: Likewise. * doc/extra-tests.texi: Likewise. * doc/transversal.texi: Likewise. * doc/namespace.texi: Likewise. * doc/check-version.texi: Likewise. * doc/windows-sockets.texi: Likewise. * doc/windows-libtool.texi: Likewise. * doc/licenses-texi.texi: Likewise. * doc/build-automation.texi: Likewise. * doc/c-locale.texi: Likewise. --- ChangeLog | 17 ++ doc/build-automation.texi | 57 +++++ doc/c-locale.texi | 51 ++++ doc/check-version.texi | 53 ++++ doc/extra-tests.texi | 73 ++++++ doc/gnulib.texi | 508 +------------------------------------- doc/licenses-texi.texi | 14 ++ doc/namespace.texi | 64 +++++ doc/obsolete.texi | 23 ++ doc/out-of-memory.texi | 36 +++ doc/transversal.texi | 69 ++++++ doc/windows-libtool.texi | 21 ++ doc/windows-sockets.texi | 27 ++ 13 files changed, 516 insertions(+), 497 deletions(-) create mode 100644 doc/build-automation.texi create mode 100644 doc/c-locale.texi create mode 100644 doc/check-version.texi create mode 100644 doc/extra-tests.texi create mode 100644 doc/licenses-texi.texi create mode 100644 doc/namespace.texi create mode 100644 doc/obsolete.texi create mode 100644 doc/out-of-memory.texi create mode 100644 doc/transversal.texi create mode 100644 doc/windows-libtool.texi create mode 100644 doc/windows-sockets.texi diff --git a/ChangeLog b/ChangeLog index 314767e1a4..8def009d11 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,20 @@ +2017-05-10 Bruno Haible + + Prepare for reordering sections in the manual. + * doc/gnulib.texi: Move several sections to separate files. Include + these files. + * doc/out-of-memory.texi: New file, extracted from doc/gnulib.texi. + * doc/obsolete.texi: Likewise. + * doc/extra-tests.texi: Likewise. + * doc/transversal.texi: Likewise. + * doc/namespace.texi: Likewise. + * doc/check-version.texi: Likewise. + * doc/windows-sockets.texi: Likewise. + * doc/windows-libtool.texi: Likewise. + * doc/licenses-texi.texi: Likewise. + * doc/build-automation.texi: Likewise. + * doc/c-locale.texi: Likewise. + 2017-05-10 Bruno Haible Fix instructions how to update manual on www.gnu.org. diff --git a/doc/build-automation.texi b/doc/build-automation.texi new file mode 100644 index 0000000000..c9ceee5aee --- /dev/null +++ b/doc/build-automation.texi @@ -0,0 +1,57 @@ +@node Build robot for gnulib +@section Build robot for gnulib + +To simplify testing on a wide set of platforms, gnulib is built on +many platforms every day and the results are uploaded to: + +@url{http://autobuild.josefsson.org/gnulib/} + +If you wish to help the gnulib development effort with build logs for +your favorite platform, you may perform these steps: + +@enumerate + +@item Create gnulib directory + +On a machine with GNU development tools installed and with a gnulib +git checkout, use + +@example +gnulib-tool --create-megatestdir --with-tests --dir=... +@end example + +Note: The created directory uses ca. 512 MB on disk. + +@item Transfer gnulib directory + +Transfer this directory to a build machine (HP-UX, Cygwin, or +whatever). Often it is easier to transfer one file, and this can be +achieved by running, inside the directory the following commands: + +@example +./configure +make dist +@end example + +And then transferring the @file{dummy-0.tar.gz} file. + +@item Build modules + +On the build machine, run ./do-autobuild (or "nohup ./do-autobuild"). +It creates a directory @file{logs/} with a log file for each module. + +@item Submit build logs + +Submit each log file to Simon's site, either through a + +@example +mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/` +@end example + +or through netcat + +@example +autobuild-submit logs/* +@end example + +@end enumerate diff --git a/doc/c-locale.texi b/doc/c-locale.texi new file mode 100644 index 0000000000..63d11384bd --- /dev/null +++ b/doc/c-locale.texi @@ -0,0 +1,51 @@ +@node String Functions in C Locale +@section Character and String Functions in C Locale + +The functions in this section are similar to the generic string functions +from the standard C library, except that +@itemize +@item +They behave as if the locale was set to the "C" locale, even when the +locale is different, and/or +@item +They are specially optimized for the case where all characters are plain +ASCII characters. +@end itemize + +@menu +* c-ctype:: +* c-strcase:: +* c-strcaseeq:: +* c-strcasestr:: +* c-strstr:: +* c-strtod:: +* c-strtold:: +@end menu + +@node c-ctype +@subsection c-ctype +@include c-ctype.texi + +@node c-strcase +@subsection c-strcase +@include c-strcase.texi + +@node c-strcaseeq +@subsection c-strcaseeq +@include c-strcaseeq.texi + +@node c-strcasestr +@subsection c-strcasestr +@include c-strcasestr.texi + +@node c-strstr +@subsection c-strstr +@include c-strstr.texi + +@node c-strtod +@subsection c-strtod +@include c-strtod.texi + +@node c-strtold +@subsection c-strtold +@include c-strtold.texi diff --git a/doc/check-version.texi b/doc/check-version.texi new file mode 100644 index 0000000000..f22266b50c --- /dev/null +++ b/doc/check-version.texi @@ -0,0 +1,53 @@ +@node Library version handling +@section Library version handling + +The module @samp{check-version} can be useful when your gnulib +application is a system library. You will typically wrap the call to +the @code{check_version} function through a library API, your library +header file may contain: + +@example +#define STRINGPREP_VERSION "0.5.18" +... + extern const char *stringprep_check_version (const char *req_version); +@end example + +To avoid ELF symbol collisions with other libraries that use the +@samp{check-version} module, add to @file{config.h} through a +AC_DEFINE something like: + +@example +AC_DEFINE(check_version, stringprep_check_version, + [Rename check_version.]) +@end example + +The @code{stringprep_check_version} function will thus be implemented +by the @code{check_version} module. + +There are two uses of the interface. The first is a way to provide +for applications to find out the version number of the library it +uses. The application may contain diagnostic code such as: + +@example + printf ("Stringprep version: header %s library %s", + STRINGPREP_VERSION, + stringprep_check_version (NULL)); +@end example + +Separating the library and header file version can be useful when +searching for version mismatch related problems. + +The second uses is as a rudimentary test of proper library version, by +making sure the application get a library version that is the same, or +newer, than the header file used when building the application. This +doesn't catch all problems, libraries may change backwards incompatibly +in later versions, but enable applications to require a certain +minimum version before it may proceed. + +Typical uses look like: + +@example + /* Check version of libgcrypt. */ + if (!gcry_check_version (GCRYPT_VERSION)) + die ("version mismatch\n"); +@end example diff --git a/doc/extra-tests.texi b/doc/extra-tests.texi new file mode 100644 index 0000000000..fcbad12d17 --- /dev/null +++ b/doc/extra-tests.texi @@ -0,0 +1,73 @@ +@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 --with-tests} 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 --with-tests} and +@code{gnulib-tool --create-megatestdir --with-tests} 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. diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 86e9f107ef..023ddc8440 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -715,7 +715,6 @@ hold back modifications you make to Gnulib macros in cases it may be better to share them. - @node Miscellaneous Notes @chapter Miscellaneous Notes @@ -732,461 +731,26 @@ better to share them. * Build robot for gnulib:: @end menu +@include out-of-memory.texi -@node Out of memory handling -@section Out of memory handling - -@cindex Out of Memory handling -@cindex Memory allocation failure -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 (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_die) (void); -@end example - -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 -@section Obsolete modules - -@cindex Obsolete modules -Modules can be marked obsolete. This means that the problems they fix -don't occur any more on the platforms that are reasonable porting targets -now. @code{gnulib-tool} warns when obsolete modules are mentioned on the -command line, and by default ignores dependencies from modules to obsolete -modules. When you pass the option @code{--with-obsolete} to -@code{gnulib-tool}, dependencies to obsolete modules will be included, -however, unless blocked through an @code{--avoid} option. This option -is useful if your package should be portable even to very old platforms. - -In order to mark a module obsolete, you need to add this to the module -description: - -@example -Status: -obsolete - -Notice: -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 --with-tests} 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 --with-tests} and -@code{gnulib-tool --create-megatestdir --with-tests} 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 Modules that modify the way other modules work -@section Modules that modify the way other modules work - -The normal way to design modules is that each module has its own code, -and the module dependencies provide the facilities on which this code -can rely. But sometimes it is necessary to use more advanced -techniques. For example: -@itemize -@item -You may want to have optional module dependencies: Let module A use -facilities provided by module B, if module B is present, but without -requiring that module B is present. -@item -A module can indicate support for particular behaviours. For example, -Gnulib has a module @samp{sigpipe} that requests POSIX compatible -SIGPIPE behaviour from all other modules -- something that is not -enabled by default. Or consider the @samp{nonblocking} module, that is -an indicator that all I/O functions should handle non-blocking file -descriptors -- something that, equally, is not enabled by default. -@item -A module can indicate to other modules that they can rely on certain -guarantees, and thus omit specific code. For example, when Gnulib's -@samp{malloc-gnu} module is present, you can omit code that test -@code{n} against zero when you call @code{malloc (n)}. -@end itemize - -Be aware that these advanced techniques likely cause breakage in the -situation of multiple @code{gnulib-tool} invocations in the scope of a -single @code{configure} file. This is because the question ``is module -B present?'' does not have a unique answer in such situations. -@code{gnulib-tool} has support for these techniques in the situation of -@code{--create-testdir --single-configure}, which basically has two -@code{gnulib-tool} invocations, one for a set of modules that end up in -@code{gllib}, and one for the set of modules that end up in -@code{gltests}. But you should be aware that this does not cover the -general situation. - -Which technique to use, depends on the answer to the question: ``If my -module occurs among the modules of @code{gltests}, should it have an -effect on the modules in @code{gllib}?'' - -If the answer is ``no'', your module description should invoke the -Autoconf macro @code{gl_MODULE_INDICATOR}. This Autoconf macro takes -one argument: the name of your module. The effect of -@code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in -@code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates -whether your macro is considered to be present. This works even when -your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}} -will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}. - -If the answer is ``yes'', you have two techniques available. The first -one is to invoke a similar Autoconf macro, named -@code{gl_MODULE_INDICATOR_FOR_TESTS}. It works similarly. However, -when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}} -will evaluate to 1 both in @code{gltests} and in @code{gllib}. - -The second one is to define a shell variable in the @code{configure} -file that tells whether your module is present, through use of -@code{m4_divert_text}. The Autoconf macros of a dependency module will -initialize this shell variable, through -@samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}. The -Autoconf macros of your module will override this value, through -@samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}. Then -you can use @code{@var{my_shell_var}} in the Autoconf macros of both -modules. You can find more details about this technique in the Gnulib -module @code{getopt-gnu}. - -Reminder: These techniques are advanced. They have the potential to -cause lots of headaches if you apply them incorrectly. - - -@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 - -The module @samp{check-version} can be useful when your gnulib -application is a system library. You will typically wrap the call to -the @code{check_version} function through a library API, your library -header file may contain: - -@example -#define STRINGPREP_VERSION "0.5.18" -... - extern const char *stringprep_check_version (const char *req_version); -@end example - -To avoid ELF symbol collisions with other libraries that use the -@samp{check-version} module, add to @file{config.h} through a -AC_DEFINE something like: - -@example -AC_DEFINE(check_version, stringprep_check_version, - [Rename check_version.]) -@end example - -The @code{stringprep_check_version} function will thus be implemented -by the @code{check_version} module. - -There are two uses of the interface. The first is a way to provide -for applications to find out the version number of the library it -uses. The application may contain diagnostic code such as: - -@example - printf ("Stringprep version: header %s library %s", - STRINGPREP_VERSION, - stringprep_check_version (NULL)); -@end example - -Separating the library and header file version can be useful when -searching for version mismatch related problems. - -The second uses is as a rudimentary test of proper library version, by -making sure the application get a library version that is the same, or -newer, than the header file used when building the application. This -doesn't catch all problems, libraries may change backwards incompatibly -in later versions, but enable applications to require a certain -minimum version before it may proceed. - -Typical uses look like: - -@example - /* Check version of libgcrypt. */ - if (!gcry_check_version (GCRYPT_VERSION)) - die ("version mismatch\n"); -@end example - - -@node Windows sockets -@section Windows sockets - -There are several issues when building applications that should work -under Windows. The most problematic part is for applications that use -sockets. - -Hopefully, we can add helpful notes to this section that will help you -port your application to Windows using gnulib. - -@subsection Getaddrinfo and WINVER - -This was written for the getaddrinfo module, but may be applicable to -other functions too. - -The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows -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 the (partial) getaddrinfo -implementation. - -If you want to support Windows 2000, don't do anything. The -replacement function will open @file{WS2_32.DLL} during run-time to -see if there is a getaddrinfo function available, and use it when -available. - -@node Libtool and Windows -@section Libtool and Windows - -If you want it to be possible to cross-compile your program to MinGW -and you use Libtool, you need to use the @code{win32-dll} option of -@code{LT_INIT}. In other words, put: - -@example -LT_INIT([win32-dll]) -@end example - -in your @file{configure.ac}. This sets the correct names for the -@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build. +@include obsolete.texi -If you are building a library, you will also need to pass -@code{-no-undefined} to make sure Libtool produces a DLL for your -library. From a @file{Makefile.am}: - -@example -libgsasl_la_LDFLAGS += -no-undefined -@end example - - -@node License Texinfo sources -@section License Texinfo sources - -Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses -in Texinfo form. (The master location is -@url{http://www.gnu.org/licenses/}). These Texinfo documents do not -have any node names and structures built into them; for your manual, -you should @code{@@include} them in an appropriate @code{@@node}. - -The conventional name for the GPL node is @samp{Copying} and for the FDL -@samp{GNU Free Documentation License}. The LGPL doesn't seem to have -a conventional node name. - -Of course the license texts themselves should not be changed at all. +@include extra-tests.texi +@include transversal.texi -@node Build robot for gnulib -@section Build robot for gnulib +@include namespace.texi -To simplify testing on a wide set of platforms, gnulib is built on -many platforms every day and the results are uploaded to: +@include check-version.texi -@url{http://autobuild.josefsson.org/gnulib/} +@include windows-sockets.texi -If you wish to help the gnulib development effort with build logs for -your favorite platform, you may perform these steps: +@include windows-libtool.texi -@enumerate - -@item Create gnulib directory - -On a machine with GNU development tools installed and with a gnulib -git checkout, use - -@example -gnulib-tool --create-megatestdir --with-tests --dir=... -@end example +@include licenses-texi.texi -Note: The created directory uses ca. 512 MB on disk. +@include build-automation.texi -@item Transfer gnulib directory - -Transfer this directory to a build machine (HP-UX, Cygwin, or -whatever). Often it is easier to transfer one file, and this can be -achieved by running, inside the directory the following commands: - -@example -./configure -make dist -@end example - -And then transferring the @file{dummy-0.tar.gz} file. - -@item Build modules - -On the build machine, run ./do-autobuild (or "nohup ./do-autobuild"). -It creates a directory @file{logs/} with a log file for each module. - -@item Submit build logs - -Submit each log file to Simon's site, either through a - -@example -mail `echo gnulib__at__autobuild.josefsson.org | sed -e s/__at__/@@/` -@end example - -or through netcat - -@example -autobuild-submit logs/* -@end example - -@end enumerate @node POSIX Substitutes Library @chapter Building the ISO C and POSIX Substitutes @@ -6788,57 +6352,7 @@ This list of functions is sorted according to the header that declares them. @include extern-inline.texi -@node String Functions in C Locale -@section Character and String Functions in C Locale - -The functions in this section are similar to the generic string functions -from the standard C library, except that -@itemize -@item -They behave as if the locale was set to the "C" locale, even when the -locale is different, and/or -@item -They are specially optimized for the case where all characters are plain -ASCII characters. -@end itemize - -@menu -* c-ctype:: -* c-strcase:: -* c-strcaseeq:: -* c-strcasestr:: -* c-strstr:: -* c-strtod:: -* c-strtold:: -@end menu - -@node c-ctype -@subsection c-ctype -@include c-ctype.texi - -@node c-strcase -@subsection c-strcase -@include c-strcase.texi - -@node c-strcaseeq -@subsection c-strcaseeq -@include c-strcaseeq.texi - -@node c-strcasestr -@subsection c-strcasestr -@include c-strcasestr.texi - -@node c-strstr -@subsection c-strstr -@include c-strstr.texi - -@node c-strtod -@subsection c-strtod -@include c-strtod.texi - -@node c-strtold -@subsection c-strtold -@include c-strtold.texi +@include c-locale.texi @include quote.texi diff --git a/doc/licenses-texi.texi b/doc/licenses-texi.texi new file mode 100644 index 0000000000..325e2efdd8 --- /dev/null +++ b/doc/licenses-texi.texi @@ -0,0 +1,14 @@ +@node License Texinfo sources +@section License Texinfo sources + +Gnulib provides copies of the GNU GPL, GNU LGPL, and GNU FDL licenses +in Texinfo form. (The master location is +@url{http://www.gnu.org/licenses/}). These Texinfo documents do not +have any node names and structures built into them; for your manual, +you should @code{@@include} them in an appropriate @code{@@node}. + +The conventional name for the GPL node is @samp{Copying} and for the FDL +@samp{GNU Free Documentation License}. The LGPL doesn't seem to have +a conventional node name. + +Of course the license texts themselves should not be changed at all. diff --git a/doc/namespace.texi b/doc/namespace.texi new file mode 100644 index 0000000000..4214ba169e --- /dev/null +++ b/doc/namespace.texi @@ -0,0 +1,64 @@ +@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. diff --git a/doc/obsolete.texi b/doc/obsolete.texi new file mode 100644 index 0000000000..90280ce392 --- /dev/null +++ b/doc/obsolete.texi @@ -0,0 +1,23 @@ +@node Obsolete modules +@section Obsolete modules + +@cindex Obsolete modules +Modules can be marked obsolete. This means that the problems they fix +don't occur any more on the platforms that are reasonable porting targets +now. @code{gnulib-tool} warns when obsolete modules are mentioned on the +command line, and by default ignores dependencies from modules to obsolete +modules. When you pass the option @code{--with-obsolete} to +@code{gnulib-tool}, dependencies to obsolete modules will be included, +however, unless blocked through an @code{--avoid} option. This option +is useful if your package should be portable even to very old platforms. + +In order to mark a module obsolete, you need to add this to the module +description: + +@example +Status: +obsolete + +Notice: +This module is obsolete. +@end example diff --git a/doc/out-of-memory.texi b/doc/out-of-memory.texi new file mode 100644 index 0000000000..bd33964b97 --- /dev/null +++ b/doc/out-of-memory.texi @@ -0,0 +1,36 @@ +@node Out of memory handling +@section Out of memory handling + +@cindex Out of Memory handling +@cindex Memory allocation failure +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 (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_die) (void); +@end example + +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. diff --git a/doc/transversal.texi b/doc/transversal.texi new file mode 100644 index 0000000000..6c814a9a8f --- /dev/null +++ b/doc/transversal.texi @@ -0,0 +1,69 @@ +@node Modules that modify the way other modules work +@section Modules that modify the way other modules work + +The normal way to design modules is that each module has its own code, +and the module dependencies provide the facilities on which this code +can rely. But sometimes it is necessary to use more advanced +techniques. For example: +@itemize +@item +You may want to have optional module dependencies: Let module A use +facilities provided by module B, if module B is present, but without +requiring that module B is present. +@item +A module can indicate support for particular behaviours. For example, +Gnulib has a module @samp{sigpipe} that requests POSIX compatible +SIGPIPE behaviour from all other modules -- something that is not +enabled by default. Or consider the @samp{nonblocking} module, that is +an indicator that all I/O functions should handle non-blocking file +descriptors -- something that, equally, is not enabled by default. +@item +A module can indicate to other modules that they can rely on certain +guarantees, and thus omit specific code. For example, when Gnulib's +@samp{malloc-gnu} module is present, you can omit code that test +@code{n} against zero when you call @code{malloc (n)}. +@end itemize + +Be aware that these advanced techniques likely cause breakage in the +situation of multiple @code{gnulib-tool} invocations in the scope of a +single @code{configure} file. This is because the question ``is module +B present?'' does not have a unique answer in such situations. +@code{gnulib-tool} has support for these techniques in the situation of +@code{--create-testdir --single-configure}, which basically has two +@code{gnulib-tool} invocations, one for a set of modules that end up in +@code{gllib}, and one for the set of modules that end up in +@code{gltests}. But you should be aware that this does not cover the +general situation. + +Which technique to use, depends on the answer to the question: ``If my +module occurs among the modules of @code{gltests}, should it have an +effect on the modules in @code{gllib}?'' + +If the answer is ``no'', your module description should invoke the +Autoconf macro @code{gl_MODULE_INDICATOR}. This Autoconf macro takes +one argument: the name of your module. The effect of +@code{gl_MODULE_INDICATOR([@var{my-module}])} is to define, in +@code{config.h}, a C macro @code{GNULIB_@var{MY_MODULE}} that indicates +whether your macro is considered to be present. This works even when +your macro is used in @code{gltests}: @code{GNULIB_@var{MY_MODULE}} +will then evaluate to 1 in @code{gltests} but to 0 in @code{gllib}. + +If the answer is ``yes'', you have two techniques available. The first +one is to invoke a similar Autoconf macro, named +@code{gl_MODULE_INDICATOR_FOR_TESTS}. It works similarly. However, +when your macro is used in @code{gltests}, @code{GNULIB_@var{MY_MODULE}} +will evaluate to 1 both in @code{gltests} and in @code{gllib}. + +The second one is to define a shell variable in the @code{configure} +file that tells whether your module is present, through use of +@code{m4_divert_text}. The Autoconf macros of a dependency module will +initialize this shell variable, through +@samp{m4_divert_text([DEFAULTS], [@var{my_shell_var}=no])}. The +Autoconf macros of your module will override this value, through +@samp{m4_divert_text([INIT_PREPARE], [@var{my_shell_var}=yes])}. Then +you can use @code{@var{my_shell_var}} in the Autoconf macros of both +modules. You can find more details about this technique in the Gnulib +module @code{getopt-gnu}. + +Reminder: These techniques are advanced. They have the potential to +cause lots of headaches if you apply them incorrectly. diff --git a/doc/windows-libtool.texi b/doc/windows-libtool.texi new file mode 100644 index 0000000000..d6eb314a1a --- /dev/null +++ b/doc/windows-libtool.texi @@ -0,0 +1,21 @@ +@node Libtool and Windows +@section Libtool and Windows + +If you want it to be possible to cross-compile your program to MinGW +and you use Libtool, you need to use the @code{win32-dll} option of +@code{LT_INIT}. In other words, put: + +@example +LT_INIT([win32-dll]) +@end example + +in your @file{configure.ac}. This sets the correct names for the +@code{OBJDUMP}, @code{DLLTOOL}, and @code{AS} tools for the build. + +If you are building a library, you will also need to pass +@code{-no-undefined} to make sure Libtool produces a DLL for your +library. From a @file{Makefile.am}: + +@example +libgsasl_la_LDFLAGS += -no-undefined +@end example diff --git a/doc/windows-sockets.texi b/doc/windows-sockets.texi new file mode 100644 index 0000000000..bdace46bd5 --- /dev/null +++ b/doc/windows-sockets.texi @@ -0,0 +1,27 @@ +@node Windows sockets +@section Windows sockets + +There are several issues when building applications that should work +under Windows. The most problematic part is for applications that use +sockets. + +Hopefully, we can add helpful notes to this section that will help you +port your application to Windows using gnulib. + +@subsection Getaddrinfo and WINVER + +This was written for the getaddrinfo module, but may be applicable to +other functions too. + +The getaddrinfo function exists in ws2tcpip.h and -lws2_32 on Windows +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 the (partial) getaddrinfo +implementation. + +If you want to support Windows 2000, don't do anything. The +replacement function will open @file{WS2_32.DLL} during run-time to +see if there is a getaddrinfo function available, and use it when +available. -- 2.39.5