X-Git-Url: http://erislabs.net/gitweb/?a=blobdiff_plain;f=doc%2Fgnulib.texi;h=15c19b22a9032771475094edbb13ce865e3b2b2e;hb=e1122a27ec42a7425ff3c18db93816112a2c7562;hp=e23e5ce5fc7e648cc9090dcc8f2c6e4925b8e2fc;hpb=c0978facaf6b68c3702c306a3bcbd09280a8950c;p=gnulib.git diff --git a/doc/gnulib.texi b/doc/gnulib.texi index e23e5ce5f..15c19b22a 100644 --- a/doc/gnulib.texi +++ b/doc/gnulib.texi @@ -1,5 +1,5 @@ \input texinfo @c -*-texinfo-*- -@comment $Id: gnulib.texi,v 1.7 2005-04-18 20:58:20 jas Exp $ +@comment $Id: gnulib.texi,v 1.16 2005-08-11 10:08:57 jas 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: 2005-04-18 20:58:20 $ +@set UPDATED $Date: 2005-08-11 10:08:57 $ @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 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,15 @@ Getting started: @menu * Comments:: * Header files:: +* Quoting:: * ctime:: * inet_ntoa:: * Out of memory handling:: +* Library version handling:: +* Regular expressions:: @end menu + @node Comments @section Comments @@ -158,6 +163,57 @@ 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. +@subheading Include ordering + +When writing a gnulib module, or even in general, a good way to order +the @samp{#include} directives is the following. + +@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 + + +@node Quoting +@section Quoting + +@cindex Quoting +@findex quote +@findex quotearg + +Gnulib provides @samp{quote} and @samp{quotearg} modules to help with +quoting text, such as file names, in messages to the user. Here's an +example of using @samp{quote}: + +@example +#include + ... + error (0, errno, _("cannot change owner of %s"), quote (fname)); +@end example + +This differs from + +@example + error (0, errno, _("cannot change owner of `%s'"), fname); +@end example + +@noindent in that @code{quote} escapes unusual characters in +@code{fname}, e.g., @samp{'} and control characters like @samp{\n}. + +@findex quote_n +However, a caveat: @code{quote} reuses the storage that it returns. +Hence if you need more than one thing quoted at the same time, you +need to use @code{quote_n}. + +@findex quotearg_alloc +Also, the quote module is not suited for multithreaded applications. +In that case, you have to use @code{quotearg_alloc}, defined in the +@samp{quotearg} module, which is decidedly less convenient. + + @node ctime @section ctime @findex ctime @@ -237,6 +293,71 @@ must be taken to not allocate more memory, as that will likely also fail. +@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 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 + + @node Invoking gnulib-tool @chapter Invoking gnulib-tool @@ -292,12 +413,15 @@ 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}. -Some modules also provide other files necessary -for building. These files are copied into the directory specified -by @samp{AC_CONFIG_AUX_DIR} in @file{configure.ac} or by the -@code{--aux-dir=DIRECTORY} option. If neither is specified, the -current directory is assumed. +@samp{gl_M4_BASE(DIRECTORY)} to your @file{configure.ac}. Some +modules also provide other files necessary for building. These files +are copied into the directory specified by @samp{AC_CONFIG_AUX_DIR} in +@file{configure.ac} or by the @code{--aux-dir=DIRECTORY} option. If +neither is specified, the current directory is assumed. If a module +is automatically added as a dependency is added, that you wish to +avoid, you may use @code{--avoid=MODULE}, possibly several times. Of +course, you will then need to implement the same interface as the +removed module. @code{gnulib-tool} can make symbolic links instead of copying the source files. Use the @code{--symbolic} @@ -360,6 +484,12 @@ gl_INIT ... @end example +@code{gl_INIT} will in turn call the macros related with the +gnulib functions, be it specific gnulib macros, like @code{gl_FUNC_ALLOCA} +or autoconf or automake macro like @code{AC_FUNC_ALLOCA} or +@code{AM_FUNC_GETLINE} so there is no need to call those macros yourself +when you use the corresponding gnulib modules. + 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: @@ -395,22 +525,35 @@ If you are using a gnulib source base of @code{gl}, you would use: 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: +Finally, you have to add compiler and linker flags in the appropriate +source directories, so that you can make use of the gnulib library. +Since some modules (@samp{getopt}, for example) may copy files into +the build directory, @file{top_builddir/lib} is needed as well +as @file{top_srcdir/lib}. For example: @example ... -AM_CPPFLAGS = -I$(top_srcdir)/lib +AM_CPPFLAGS = -I$(top_srcdir)/lib -I$(top_builddir)/lib ... -LIBADD = lib/libgnu.la +LIBADD = lib/libgnu.a ... @end example Don't forget to @code{#include} the various header files. In this -example, you would need to make sure that @samp{#include } +example, you would need to make sure that @samp{#include "strdup.h"} is evaluated when compiling all source code files, that want to make -use of @code{strdup}. +use of @code{strdup}. + +When an include file is provided by the gnulib +you shouldn't try to include the corresponding system header files +yourself but let the gnulib header file do it as the ordering +of the definition for some symbols may be significant. +For example, to use the @code{time_r} gnulib module you should +use include header file provided by the gnulib, and so +@samp{#include "time_r.h"}, but you shouldn't explicitely +@samp{#include } as it is already done in @file{time_r.h} +before the redefinition of some symbols. @node Importing updated files @section Importing updated files @@ -468,7 +611,8 @@ gl_EARLY gl_SOURCE_BASE(gl) gl_M4_BASE(gl/m4) gl_LIB(libgl) -gl_MODULES(getopt progname strdup dummy exit error getpass-gnu getaddrinfo) +gl_MODULES(xmalloc progname strdup dummy exit error getpass-gnu getaddrinfo) +gl_AVOID(xalloc-die) gl_INIT ... @end example @@ -482,7 +626,8 @@ The macros @code{gl_EARLY}, @code{gl_INIT}, @code{gl_SOURCE_BASE}, and 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. - +@code{gl_AVOID} macro is used to specify which modules, that are +normally automatically added as a dependency, to avoid. @node Copying This Manual @appendix Copying This Manual