\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.10 2005-06-27 22:36:50 jas 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-06-27 22:36:50 $
@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:
* ctime::
* inet_ntoa::
* Out of memory handling::
+* Library version handling::
@end menu
@node 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.
+@subsection 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 ctime
@section ctime
@findex ctime
fail.
+@node Library version handling
+@section Library version handling
+
+The module ``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
+
+The implementation of @code{stringprep_check_version} would simply
+pass on the call to @code{check_version}.
+
+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 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
SUBDIRS += gl
@end example
-Finally, you have add C flags and LD flags, so that you can make use
+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:
@example
...
AM_CPPFLAGS = -I$(top_srcdir)/lib
...
-LIBADD = lib/libgnu.la
+LIBADD = lib/libgnu.a
...
@end example
projects / gnulib.git / blobdiff