doc/check-version.texi

   1 @node Library version handling
   2 @section Library version handling
   3
   4 The module @samp{check-version} can be useful when your gnulib
   5 application is a system library.  You will typically wrap the call to
   6 the @code{check_version} function through a library API, your library
   7 header file may contain:
   8
   9 @example
  10 #define STRINGPREP_VERSION "0.5.18"
  11 ...
  12   extern const char *stringprep_check_version (const char *req_version);
  13 @end example
  14
  15 To avoid ELF symbol collisions with other libraries that use the
  16 @samp{check-version} module, add to @file{config.h} through a
  17 AC_DEFINE something like:
  18
  19 @example
  20 AC_DEFINE(check_version, stringprep_check_version,
  21           [Rename check_version.])
  22 @end example
  23
  24 The @code{stringprep_check_version} function will thus be implemented
  25 by the @code{check_version} module.
  26
  27 There are two uses of the interface.  The first is a way to provide
  28 for applications to find out the version number of the library it
  29 uses.  The application may contain diagnostic code such as:
  30
  31 @example
  32   printf ("Stringprep version: header %s library %s",
  33           STRINGPREP_VERSION,
  34           stringprep_check_version (NULL));
  35 @end example
  36
  37 Separating the library and header file version can be useful when
  38 searching for version mismatch related problems.
  39
  40 The second uses is as a rudimentary test of proper library version, by
  41 making sure the application get a library version that is the same, or
  42 newer, than the header file used when building the application.  This
  43 doesn't catch all problems, libraries may change backwards incompatibly
  44 in later versions, but enable applications to require a certain
  45 minimum version before it may proceed.
  46
  47 Typical uses look like:
  48
  49 @example
  50        /* Check version of libgcrypt. */
  51        if (!gcry_check_version (GCRYPT_VERSION))
  52          die ("version mismatch\n");
  53 @end example