[Pkg-crosswire-devel] API/ABI compatibility, and choice of SONAME for libsword

[Daniel Glassey]

On Sat, Jan 24, 2009 at 4:54 AM, Jonathan Marsden <jmarsden at fastmail.fm> wrote:
> Matthew Talbert wrote:

> Cool!  Here are a few questions for the upstream developers I'd be
> interested in the answers to, as we ramp up here:
>
> (1) Can you confirm Refdoc's comment that there is significant new
> functionality in the sword-1.5.11 libraries compared to 1.5.9?  Can we
> get any documentation on what has been added and changed in what library
> version, from the perspective of an application developer using the library?
>
> (2) Can we get confirmation as to whether the ABI or API has changed
> incompatibly since 1.5.9?  In other words, per the Debian Library
> Packaging Guide ( see
> http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html )

Thanks, I didn't know about that! (no mention on debian.org/devel).

> , do we need to bump the SONAME and create libsword7 from 1.5.11 ?  I'm
> guessing yes, but we should be able to do better than guess :)

Yes. You can confirm what changes have been made in the include
directory through svn

svn diff -N -x -uw
http://crosswire.org/svn/sword/tags/sword-1-5-9/include
http://crosswire.org/svn/sword/tags/sword-1-5-11/include

There are additions and removals from classes. Can someone confirm
that this makes it incompatible?

> (3) More generally, how are interested parties (like us!) supposed to
> find out this kind of version (in)compatibility information among
> upstream sword library releases as development of those libraries
> continues?  The upstream tarball contains a changelog, but that does not
> seem to me to clearly distinguish between straightforward bug fixes and
> more significant changes that break compatibility of either ABI or API.

Rightly or wrongly I've just assumed that every new version is binary
incompatible as afaiu there is no  deliberate effort to maintain
compatibility.

> (4) Going even further... Section 5.1 of that Guide says (tongue in
> cheek, and perhaps almost arrogantly):
>
> "In most cases, if a package version matches the SONAME, it is a sign
> that there is a problem with the versioning scheme. Scrap it, and bash
> the upstream with the libtool manual. It is usually a good sign that
> either he has not read the manual thoroughly, or he has not understood
> it, or both."
>
> I'm no expert on library packaging and libtool, but it looks to me as
> though sword currently qualifies for this approach (!), since in the
> upstream original lib/Makefile.am we currently see:
>
> libsword_la_LDFLAGS = -release $(VERSION)

This was because upstream wanted the version number 1.5.x to be in the lib.

> and this has to be patched out ("scrapped" to use the language of the
> Guide!) in the Debian and Ubuntu packages (currently patched by
> debian/patches/02_libver.diff ).

and I kept the diff to keep things consistent with previous packages.

> Can someone please confirm that I am understanding this correctly?  If
> so, what might it take to persuade the upstream library developers to
> reconsider this "SONAME version == package version" approach?  Can we
> begin that discussion with them, either here on on sword-devel?  Or
> should that kind of discussion wait a while longer (is there past
> history on this issue that I am unaware of)?
>
>> For several reasons, I think this list would be better than using the
>> sword-devel list.
>
> OK, I'm a newcomer and will defer to your judgement on that!  BTW, if
> you can do anything to speed approval of my subscription to sword-devel,
> that would be good (I'll probably listen for a while before I say too
> much there!); it seems to be awaiting human intervention at this point.

For discussion about packaging and the decision about what package
names and sonames to use for sword 1.5.11 package are more relevant
here.

Should we go for libsword7 to follow libsword6, or libsword8 to leave
space for the unpackaged 1.5.10?

But there should be a discussion on sword-devel about what should be
done for 1.5.12 (the next release which may be coming soon). I don't
understand the details very well so I haven't been able to make a good
argument on the list for what is a good idea.

There was a recent thread that I haven't replied to yet on:
http://www.crosswire.org/pipermail/sword-devel/2008-October/029376.html

Thanks,
Daniel