preparing new RtMidi release, question about SO version

[Felipe Sateler]

On 15 February 2016 at 16:38, Stephen Sinclair <radarsat1 at gmail.com> wrote:
> On Mon, Feb 15, 2016 at 12:05 PM, Felipe Sateler <fsateler at debian.org> wrote:
>> Hi Stephen
>>
>> On 10 February 2016 at 14:21, Stephen Sinclair <radarsat1 at gmail.com> wrote:
>>>
>>> Hello,
>>>
>>> I am helping to update RtMidi, a C++ class for cross-platform MIDI
>>> support.  There is a Debian librtmidi package.  Although this is just
>>> a bug-fix release, and is planned to go from 2.1.0 to 2.1.1, we have
>>> added some automake/libtool infrastructure, and a last debate is
>>> whether to properly start supporting SO version according to libtool's
>>> rules.
>>
>> Cool. I would be careful, though, because for C++ seemingly innocent
>> changes can break the ABI. STK[1] was recently updated to use
>> libtool's -release style versioning to avoid problems, as some changes
>> broke ABI and were not noticed by upstream as such. This is
>> particularly important for libraries that are used as static libraries
>> (as this kind of breakage might go unnoticed for a  while).
>
> So that's sort of part of my question -- I'd like to integrate better
> ABI testing into the usual procedure, so as to avoid changes that
> "were not noticed by upstream."  If such problems are more likely
> noticed by packagers, would it be good practice to always request a
> pre-release review by packagers before doing an upstream release?  Or
> would that be too much noise?  (Not that releases are done very
> often.. but I'm asking in the general case, I'll likely apply this as
> a rule of thumb to other software I maintain.)

Well, I'm not sure packagers do anything special. We do have symbols
files that can help, but those are not currently in use by rtmidi (in
c++ in general they can be a bit of a pain). There are external tools
that can help (like the
abi-{compliance-checker,monitor,viewer,tracker} tools), but I think
the main way to keep this is to do it pre-emptively: be aware of
changes that can change ABI and do not merge those. For C++, this is
quite limiting, though[1]. ABI stability of C++ libraries is hard.


[1] https://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B#The_Do.27s_and_Don.27ts

>
>> [1] https://github.com/thestk/stk/pull/27
>>>
>>> Previous versions have made the error of treating SO version like the
>>> version number, and producing binaries e.g. librtmidi.so.2.1.0.
>>>
>>> I was recommending changing this to properly reflect ABI
>>> compatibility.  What would Debian maintainers prefer here?
>>
>> If (and only if) proper ABI versioning can be done, then I'd prefer
>> that, of course. But using a -release style versioning would also be
>> ok, and force rebuild of all reverse depedends on each upstream
>> version. This should be ok, as there aren't many (6 by my count). This
>> has the advantagae for upstream that they do not have to care about
>> abi.
>
> I don't think it's a huge overhead to check for ABI changes between
> releases, provided this can be done (largely) automatically.  Which
> should be possible, although I haven't explored the available tools
> yet.  I'm not 100% sure what you mean by -release style versioning.
> You mean append the library version as if it were the SO name?
> Doesn't that lead to complications when there's a bugfix release that
> happens to change the ABI? Or rather you seem to be suggesting a full
> SO bump on every release.  I'm not sure if I follow.

Yes, I suggest a full bump on every release. That, while not optimal
from a downstream perspective, is still manageable, and is much more
convenient for upstream and less error-prone.

Note that -release style versioning is setting SONAME as
libfoo-x.y.z.so instead of libfoo.x

>
>>> I proposed making the new SO version 3.0.0, to really emphasize that
>>> the ABI version is new, however since it's a bugfix release I don't
>>> know if that's the recommended strategy.
>>>
>>> https://github.com/thestk/rtmidi/pull/59
>>>
>>> In any case I notice that the interface has changed a bit, e.g. some
>>> functions have lost parameters, others have new parameters, since the
>>> last release.
>>
>> I see the pull request has already been merged. I hope this message
>> doesn't come too late.
>
> Yes, the release has been done.  However, I think bumping the SO name
> was the right call, seeing as the ABI signature of setErrorCallback()
> changed.  I just figured we may as well use it as an opportunity to
> make it significantly different from the release version while we're
> at it.

I agree a bump was required.

In summary:

1. C++ ABI compatibility is hard.
2. If you can (as upstream) commit to ABI stability and manage it,
this is the best for downstreams.
3. If you cannot, then I find -release style versioning acceptable as
well. While it is inconvenient to have to rebuild all reverse
dependencies, it beats having to figure out weird crashes when library
versions don't match.




-- 

Saludos,
Felipe Sateler