X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=4f7025055d142c37f459895dcda23ef8339dae75;hb=bc6100152d4491ef14ef778c7c05293e5cd9d431;hp=9ecca8183a88912b8facd9599e2c6b54d0bbd84f;hpb=9923a4664ef3dfc9d3d74ef9fff00bcd16a434d7;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index 9ecca8183..4f7025055 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.5 2004-09-28 22:58:00 eggert Exp $ +@comment $Id: gnulib.texi,v 1.21 2006-04-30 13:38:54 karl Exp $ @comment %**start of header @setfilename gnulib.info @settitle GNU Gnulib @@ -7,14 +7,14 @@ @syncodeindex pg cp @comment %**end of header -@set UPDATED $Date: 2004-09-28 22:58:00 $ +@set UPDATED $Date: 2006-04-30 13:38:54 $ @copying 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 Free Software Foundation, Inc. +Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. @quotation Permission is granted to copy, distribute and/or modify this document @@ -65,8 +65,9 @@ Software Foundation raise funds for GNU development.'' @node Gnulib @chapter Gnulib -This is not a real manual. It's just a place to store random notes -until someone (you?) gets around to actually writing a manual. +This manual contains some bare-bones documentation, but not much more. +It's mostly been a place to store notes until someone (you?)@ gets +around to writing a coherent manual. Getting started: @@ -81,11 +82,16 @@ Getting started: @menu * Comments:: * Header files:: +* Quoting:: * ctime:: * inet_ntoa:: +* gcd:: * Out of memory handling:: +* Library version handling:: +* Regular expressions:: @end menu + @node Comments @section Comments @@ -123,8 +129,9 @@ underscore and either an uppercase letter or another underscore, for any use. Thus, in theory, an application might not safely assume that @code{_FOO_H} has not already been defined by a library. On the other hand, using @code{FOO_H} will likely lead the higher risk of -collisions with other symbols (e.g., @code{COFF_LONG_H} which is a CPP -macro function). Your preference may depeend on whether you consider +collisions with other symbols (e.g., @code{KEY_H}, @code{XK_H}, @code{BPF_H}, +which are CPP macro constants, or @code{COFF_LONG_H}, which is a CPP +macro function). Your preference may depend on whether you consider the header file under discussion as part of the application (which has its own namespace for CPP symbols) or a supporting library (that shouldn't interfere with the application's CPP symbol namespace). @@ -157,42 +164,27 @@ preference might depend on whether you consider the API exported by your header file as something available for C programs only, or for C and C++ programs alike. -@node ctime -@section ctime -@findex ctime +@subheading Include ordering + +When writing a gnulib module, or even in general, a good way to order +the @samp{#include} directives is the following. -The @code{ctime} function need not be reentrant, and consequently is -not required to be thread safe. Implementations of @code{ctime} -typically write the time stamp into static buffer. If two threads -call @code{ctime} at roughly the same time, you might end up with the -wrong date in one of the threads, or some undefined string. There is -a re-entrant interface @code{ctime_r}, that take a pre-allocated -buffer and length of the buffer, and return @code{NULL} on errors. -The input buffer should be at least 26 bytes in size. The output -string is locale-independent. However, years can have more than 4 -digits if @code{time_t} is sufficiently wide, so the length of the -required output buffer is not easy to determine. Increasing the -buffer size when @code{ctime_r} return @code{NULL} is not necessarily -sufficient. The @code{NULL} return value could mean some other error -condition, which will not go away by increasing the buffer size. +@itemize +@item First comes the #include "..." specifying the module being implemented. +@item Then come all the #include <...> of system or system-replacement headers, +in arbitrary order. +@item Then come all the #include "..." of gnulib and private headers, in +arbitrary order. +@end itemize -A more flexible function is @code{strftime}. However, note that it is -locale dependent. +@include quote.texi -@node inet_ntoa -@section inet_ntoa -@findex inet_ntoa +@include ctime.texi -The @code{inet_ntoa} function need not be reentrant, and consequently -is not required to be thread safe. Implementations of -@code{inet_ntoa} typically write the time stamp into static buffer. -If two threads call @code{inet_ntoa} at roughly the same time, you -might end up with the wrong date in one of the threads, or some -undefined string. Further, @code{inet_ntoa} is specific for -@acronym{IPv4} addresses. +@include gcd.texi -A protocol independent function is @code{inet_ntop}. +@include inet_ntoa.texi @node Out of memory handling @@ -236,239 +228,72 @@ must be taken to not allocate more memory, as that will likely also fail. -@node Invoking gnulib-tool -@chapter Invoking gnulib-tool - -@pindex gnulib-tool -@cindex invoking @command{gnulib-tool} - -Run @samp{gnulib-tool --help}, and use the source. -@command{gnulib-tool} is the way to import Gnulib modules. - -@menu -* Initial import:: First import of Gnulib modules. -* Importing updated files:: Subsequent imports. -* Finishing touches:: Simplifying imports. -@end menu - - -@node Initial import -@section Initial import -@cindex initial import - -Gnulib assumes your project uses Autoconf and Automake. Invoking -@samp{gnulib-tool --import} will copy source files, create a -@file{Makefile.am} to build them, and generate a @file{gnulib.m4} with -Autoconf M4 macro declarations used by @file{configure.ac}. - -Our example will be a library that uses Autoconf, Automake and -Libtool. It calls @code{strdup}, and you wish to use gnulib to make -the package portable to C89 (which doesn't have @code{strdup}). - -@example -~/src/libfoo$ gnulib-tool --import strdup -Module list with included dependencies: - strdup -File list: - lib/strdup.c - lib/strdup.h - m4/onceonly_2_57.m4 - m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... -Finished. - -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. -~/src/libfoo$ -@end example +@node Library version handling +@section Library version handling -By default, the source code is copied into @file{lib/} and the M4 -macros in @file{m4/}. You can override these paths by using -@code{--source-base=DIRECTORY} and @code{--m4-base=DIRECTORY}, or by -adding @samp{gl_SOURCE_BASE(DIRECTORY)} and -@samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}. - -@code{gnulib-tool} will overwrite any pre-existing files, in -particular @file{Makefile.am}. Unfortunately, separating the -generated @file{Makefile.am} content (for building the gnulib library) -into a separate file, say @file{gnulib.mk}, that could be included -by your handwritten @file{Makefile.am} is not possible, due to how -variable assignments are handled by Automake. - -Consequently, it can be a good idea to chose directories that are not -already used by your projects, to separate gnulib imported files from -your own files. This approach can also be useful if you want to avoid -conflicts between other tools (e.g., @code{getextize} that also copy -M4 files into your package. Simon Josefsson successfully uses a source -base of @file{gl/}, and a M4 base of @file{gl/m4/}, in several -packages. - -A few manual steps are required to finish the initial import. - -First, you need to make sure Autoconf can find the macro definitions -in @file{gnulib.m4}. Use the @code{ACLOCAL_AMFLAGS} specifier in your -top-level @file{Makefile.am} file, as in: - -@example -ACLOCAL_AMFLAGS = -I m4 -@end example - -Naturally, replace @file{m4} with the value from @code{--m4-base} or -@code{gl_M4_BASE}. If the M4 base is @file{gl/m4} you would use: - -@example -ACLOCAL_AMFLAGS = -I gl/m4 -@end example - -You are now ready to call the M4 macros in @code{gnulib.m4} from -@file{configure.ac}. The macro @code{gl_EARLY} must be called as soon -as possible after verifying that the C compiler is working. -Typically, this is immediately after @code{AC_PROG_CC}, as in: +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" ... -AC_PROG_CC -gl_EARLY -... + extern const char *stringprep_check_version (const char *req_version); @end example -The core part of the gnulib checks are done by the macro -@code{gl_INIT}. Place it further down in the file, typically where -you normally check for header files or functions. Or in a separate -section with other gnulib statements, such as @code{gl_SOURCE_BASE}. -For 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 -... -# For gnulib. -gl_INIT -... +AC_DEFINE(check_version, stringprep_check_version, [Rename check_version.]) @end example -You must also make sure that the gnulib library is built. Add the -@code{Makefile} in the gnulib source base directory to -@code{AC_CONFIG_FILES}, as in: +The @code{stringprep_check_version} function will thus be implemented +by the @code{check_version} module. -@example -AC_CONFIG_FILES(... lib/Makefile ...) -@end example - -If your gnulib source base is @file{gl}, you would use: +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 -AC_CONFIG_FILES(... gl/Makefile ...) + printf ("Stringprep version: header %s library %s", + STRINGPREP_VERSION, + stringprep_check_version (NULL)); @end example -You must also make sure that @code{make} work in the gnulib directory. -Add the gnulib source base directory to a @code{SUBDIRS} Makefile.am -statement, as in: +Separating the library and header file version can be useful when +searching for version mismatch related problems. -@example -SUBDIRS = lib -@end example - -or if you, more likely, already have a few entries in @code{SUBDIRS}, -you can add something like: - -@example -SUBDIRS += lib -@end example - -If you are using a gnulib source base of @code{gl}, you would use: - -@example -SUBDIRS += gl -@end example - -Finally, you have add C flags and LD flags, so that you can make use -of the gnulib library. For example: - -@example -... -AM_CPPFLAGS = -I$(top_srcdir)/lib -... -LIBADD = lib/libgnu.la -... -@end example - -Don't forget to @code{#include} the various header files. In this -example, you would need to make sure that @samp{#include } -is evaluated when compiling all source code files, that want to make -use of @code{strdup}. - - -@node Importing updated files -@section Importing updated files +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. -From time to time, you may want to invoke @samp{gnulib-tool --import} -to update the files in your package. Once you have set up your -package for gnulib, this step is quite simple. For example: +Typical uses look like: @example -~/src/libfoo$ gnulib-tool --import --source-base gl --m4-base gl/m4 strdup -Module list with included dependencies: - strdup -File list: - lib/strdup.c - lib/strdup.h - m4/onceonly_2_57.m4 - m4/strdup.m4 -Creating ./lib/Makefile.am... -Creating ./m4/gnulib.m4... -Finished. - -Don't forget to add "lib/Makefile" -to AC_CONFIG_FILES in "./configure.ac" and to mention -"lib" in SUBDIRS in some Makefile.am. -~/src/libfoo$ + /* Check version of libgcrypt. */ + if (!gcry_check_version (GCRYPT_VERSION)) + die ("version mismatch\n"); @end example -If you don't recall how you invoked the tool last time, the commands -used (and the operations it resulted in) are placed in comments within -the generated @file{Makefile.am} and @file{gnulib.m4}, as in: -@example -... -# Invoked as: gnulib-tool --import strdup -# Reproduce by: gnulib-tool --import --dir=. --lib=libgnu --source-base=lib --m4-base=m4 --libtool strdup -... -@end example +@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. -@node Finishing touches -@section Finishing touches - -Invoking @samp{gnulib-tool --import} with the proper parameters (e.g., -@samp{--m4-base gl/m4}) and list of modules (e.g., @samp{strdup -snprintf getline minmax}) can be tedious. To simplify this procedure, -you may put the command line parameters in your @file{configure.ac}. -For example: - -@example -... -AC_PROG_CC -gl_EARLY -... -# For gnulib. -gl_SOURCE_BASE(gl) -gl_M4_BASE(gl/m4) -gl_LIB(libgl) -gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo) -gl_INIT -... -@end example +@include regexprops-generic.texi -This illustrate all macros defined in @file{gnulib.m4}. With the -above, importing new files are as simple as running @samp{gnulib-tool ---import} with no additional parameters. -The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and -@code{gl_M4_BASE} have been discussed earlier. The @code{gl_LIB} -macro can be used if you wish to change the library name (by default -@file{libgnu.a} or @file{libgnu.la} if you use libtool). The -@code{gl_MODULES} macro is used to specify which modules to import. +@include gnulib-tool.texi @node Copying This Manual