Re: check_version

[Simon Josefsson]

Jim Meyering <address@hidden> writes:

> Simon Josefsson <address@hidden> wrote:
>> Not sure I follow the higher-level language part... Perhaps I should
>> explain more what I use this for.
>>
>> I use it in my libraries, which are all written in C.  The source code
>
> Thanks for explaining.
> That's what I suspected.
>
> What do you think about putting a description like this
> in the module itself?  Then potential users of the
> module won't have to go find uses of it in other packages
> to understand how it can be useful.

I added the following to the manual.  Please install improvements as
appropriate...  Should something like this go into the source code
too?  I think it is slightly noisy.

1.6 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
`check_version' function through a library API, your library header
file may contain:

     #define STRINGPREP_VERSION "0.5.18"
     ...
       extern const char *stringprep_check_version (const char *req_version);

   The implementation of `stringprep_check_version' would simply pass
on the call to `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:

       printf ("Stringprep version: header %s library %s",
               STRINGPREP_VERSION,
               stringprep_check_version (NULL));

   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:

            /* Check version of libgcrypt. */
            if (!gcry_check_version (GCRYPT_VERSION))
              die ("version mismatch\n");