2005-06-28 Simon Josefsson <jas@extundo.com>

	* gnulib.texi (Library version handling): New section.

diff --git a/doc/ChangeLog b/doc/ChangeLog
index 5cda64e101d83a0a96e9e94f16ac453fde3464fb..398b70f98b5c2ac2d0a23751395e85354e2fdc3f 100644 (file)
--- a/doc/ChangeLog
+++ b/doc/ChangeLog
@@ -1,3 +1,7 @@
+2005-06-28  Simon Josefsson  <jas@extundo.com>
+
+       * gnulib.texi (Library version handling): New section.
+
 2005-05-11  Paul Eggert  <eggert@cs.ucla.edu>
 
        * getdate.texi (General date syntax): Don't say that date

diff --git a/doc/gnulib.texi b/doc/gnulib.texi
index 59a9338ba64e740efe16c8afd222e6c93d870eb1..34353d3eb2a20efc9fea46f74a4fd5acf8d9da28 100644 (file)
--- a/doc/gnulib.texi
+++ b/doc/gnulib.texi
@@ -1,5 +1,5 @@
 \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.10 2005-06-27 22:36:50 jas Exp $
 @comment %**start of header
 @setfilename gnulib.info
 @settitle GNU Gnulib
@@ -7,7 +7,7 @@
 @syncodeindex pg cp
 @comment %**end of header
 
-@set UPDATED $Date: 2005-05-23 11:05:53 $
+@set UPDATED $Date: 2005-06-27 22:36:50 $
 
 @copying
 This manual is for GNU Gnulib (updated @value{UPDATED}),
@@ -85,6 +85,7 @@ Getting started:
 * ctime::
 * inet_ntoa::
 * Out of memory handling::
+* Library version handling::
 @end menu
 
 @node Comments
@@ -251,6 +252,51 @@ must be taken to not allocate more memory, as that will likely also
 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