Re: [libdbi-devel] Library version macro

[Andreas E. <ae...@op...>]

Florian Forster wrote:
> Hi again,
> 
> On Tue, Mar 17, 2009 at 05:09:15PM +0100, Markus Hoenicka wrote:
>> I'm not going to do that, as discussed before on this list. In brief,
>> we forgot to update the libtool interface version info in the past. In
>> the worst case your suggestion will cause us to forget to uptate the
>> interface version *and* the library version :-(
> 
> updating the ABI version is basically not possible to do automatically,
> that's true. Updating the defines suggested automatically would be easy,
> though:
> -- 8< (configure.{ac,in}) --
>  LIBDBI_VERSION_MAJOR=`echo $PACKAGE_VERSION | cut -d'.' -f1`
>  LIBDBI_VERSION_MINOR=`echo $PACKAGE_VERSION | cut -d'.' -f2`
>  LIBDBI_VERSION_PATCH=`echo $PACKAGE_VERSION | cut -d'.' -f3`
>  AC_SUBST(LIBDBI_VERSION_MAJOR)
>  AC_SUBST(LIBDBI_VERSION_MINOR)
>  AC_SUBST(LIBDBI_VERSION_PATCH)
> -- >8 --
> 
> -- 8< (dbi_version.h.in) --
>  #define LIBDBI_VERSION_MAJOR @LIBDBI_VERSION_MAJOR@
>  #define LIBDBI_VERSION_MINOR @LIBDBI_VERSION_MINOR@
>  #define LIBDBI_VERSION_PATCH @LIBDBI_VERSION_PATCH@
>  #define LIBDBI_VERSION_STRING "@LIBDBI_VERSION_MAJOR@." \
>            "@LIBDBI_VERSION_MINOR@.@LIBDBI_VERSION_PATCH@"

#define LIBDBI_VERSION ((LIBDBI_VERSION_MAJOR * 10000) + \
     (LIBDBI_VERSION_MINOR * 100) + LIBDBI_VERSION_PATCH)

Noone wants to use 3 #ifdef's if they can get away with a
single #if ;-)

> 
>> But  instead of abusing the library version as an interface version,
>> I'd  like to use the interface version as the library version.
> 
> Yeah, that should work, too..
> 
>> I've never  understood why a library needs a version number that is
>> different from the interface number.
> 
> Well, I usually think of the API as being whatever is *documented*. For
> example, changing the order of members in a struct would, in my opinion,
> not break API compatibility but would break ABI compatibility. As a
> developer, i. e. an ``API user'', this would not be of importance to me.
> Or course, this is a trivial example. I'm sure you can think of some
> more practical examples, a bitfield being widened or a struct being
> changed but the API only documents macros to access the struct or
> something.
> 

It can be uglier than that. If you use the long datatype and and change
it to an int later, you're breaking the ABI on 64-bit platforms but not
on 32-bit ones.

> Personally, I like the package version to make a statement towards API
> compatibility, because I mainly use libraries from the viewpoint of a
> developer. The system I'm usually using is the following:
> - The major version increases upon backwards-incompatible API changes.
> - The minor version increases upon backwards-compatible API changes,
>   usually additions.
> - The patch version is increased if the API has not been changed at all.
> 
> The ``major'' number of this schema would roughly equal `current - age'.
> 
>> What changes would justify increasing  LIBDBI_MAJOR without affecting
>> LIBDBI_LIB_CURRENT?
> 
> If you use `current' as major version, it is increased whenever anything
> in the API changes (assuming you don't start doing extensive
> preprocessor trickery to keep the functions as they are ;)

You can use versioned symbols for that. I don't know if that's considered
preprocessor trickery (as it's actually linker trickery). Almost all the
actual preprocessor trickery I can think of breaks the ABI and requires a
bump of the .so-version at the very least.

> - whether
> backwards compatible or not. So my point is the other way around: The
> `current' version must be increased when I would keep the `major'
> version as is.
> 
>> Why would changes  that require a new interface be reflected by an
>> increase of  LIBDBI_MINOR instead of LIBDBI_MAJOR?
> 
> In the schema above: When a function is *added*. In that case:
> - current would be increased.
> - revision would be reset to zero.
> - age would be increased.
> 
> - major would stay the same.
> - minor would be increased.
> - patch would be reset to zero.
> 

That's how 99% of the library developing world does it. When in doubt,
follow the path of least surprise ;-)

-- 
Andreas Ericsson                   and...@op...
OP5 AB                             www.op5.se
Tel: +46 8-230225                  Fax: +46 8-230231

Considering the successes of the wars on alcohol, poverty, drugs and
terror, I think we should give some serious thought to declaring war
on peace.