Re: [libdbi-devel] Library version macro

[Florian F. <oc...@ve...>]

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@"
-- >8 --

> 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.

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 ;) - 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.

> Would that cause any grief?

No, it'd be fine by me. Please don't get me wrong, I'm not trying to
convince you. You asked, so I felt inclined to explain the schema that
has worked very well for me in more detail.. ;)

Maybe a define such as
 #define LIBDBI_API_MAJOR (LIBDBI_MAJOR - LIBDBI_AGE)
would be nice to have though ;)

Regards,
-octo
-- 
Florian octo Forster
Hacker in training
GnuPG: 0x91523C3D
http://verplant.org/