\input texinfo @c -*-texinfo-*-
-@comment $Id: gnulib.texi,v 1.4 2004-09-28 22:19:08 karl Exp $
+@comment $Id: gnulib.texi,v 1.15 2005-07-30 13:47:19 karl Exp $
@comment %**start of header
@setfilename gnulib.info
@settitle GNU Gnulib
@syncodeindex pg cp
@comment %**end of header
-@set UPDATED $Date: 2004-09-28 22:19:08 $
+@set UPDATED $Date: 2005-07-30 13:47:19 $
@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
@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:
@menu
* Comments::
* Header files::
+* Quoting::
* ctime::
* inet_ntoa::
* Out of memory handling::
+* Library version handling::
+* Regular expressions::
@end menu
+
@node Comments
@section Comments
@end example
Whether to use @code{FOO_H} or @code{_FOO_H} is a matter of taste and
-style. The C99 standard reserve all identifiers that begin with an
+style. The C89 and C99 standards reserve all identifiers that begin with an
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 interfer with the application's CPP symbol namespace).
+shouldn't interfere with the application's CPP symbol namespace).
@cindex C++ header files
@cindex Header files and C++
# endif
@end example
-The idea here is that @code{__cplusplus} is only defined when C++ run
-the preprocessor. It will wrap the header file in a @samp{extern "C"}
+The idea here is that @code{__cplusplus} is defined only by C++
+implementations, which will wrap the header file in an @samp{extern "C"}
block. Again, whether to use this trick is a matter of taste and
style. While the above can be seen as harmless, it could be argued
that the header file is written in C, and any C++ application using it
should explicitly use the @samp{extern "C"} block itself. Your
preference might depend on whether you consider the API exported by
-your header file as something available for only C programs, or for C
+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 <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
Creating ./m4/gnulib.m4...
Finished.
+You may need to add #include directives for the following .h files.
+ #include "strdup.h"
+
Don't forget to add "lib/Makefile"
to AC_CONFIG_FILES in "./configure.ac" and to mention
"lib" in SUBDIRS in some Makefile.am.
@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.
+
+@code{gnulib-tool} can make symbolic links instead
+of copying the source files. Use the @code{--symbolic}
+(or @code{-s} for short) option to do this.
@code{gnulib-tool} will overwrite any pre-existing files, in
particular @file{Makefile.am}. Unfortunately, separating the
...
@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:
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 <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
projects / gnulib.git / blobdiff