doc/check-version.texi

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