\input texinfo @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.9 2005-05-23 11:05:53 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
@syncodeindex pg cp
@comment %**end of header
-@set UPDATED $Date: 2005-05-23 11:05:53 $
+@set UPDATED $Date: 2005-08-11 10:08:57 $
@copying
This manual is for GNU Gnulib (updated @value{UPDATED}),
@chapter Gnulib
This manual contains some bare-bones documentation, but not much more.
-It's mostly been a place to store notes until someone (you?) gets
+It's mostly been a place to store notes until someone (you?)@ gets
around to writing a coherent manual.
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
your header file as something available for C programs only, or for C
and C++ programs alike.
-@subsection Include ordering
+@subheading Include ordering
When writing a gnulib module, or even in general, a good way to order
the @samp{#include} directives is the following.
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 <quote.h>
+ ...
+ 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
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
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}
...
@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:
@end 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. For example:
+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.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 <strdup.h>}
+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 <time.h>} as it is already done in @file{time_r.h}
+before the redefinition of some symbols.
@node Importing updated files
@section Importing updated files
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
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
projects / gnulib.git / blobdiff