[pkg-otr-team] Bug#767230: libotr transition started by mistake :-/ [Was: Bug#767230: bitlbee-plugin-otr: bitlbee no longer starts: libotr API version 4.1.0 incompatible with actual version 4.0.0]

[Niels Thykier]

On 2014-10-31 00:41, Ian Goldberg wrote:
> On Thu, Oct 30, 2014 at 11:05:20PM +0100, Niels Thykier wrote:
>> Control: severity 767230 serious
>>
>> On 2014-10-29 17:09, intrigeri wrote:
>>> Hi Sebastian, hi release team,
>>>
>>> [...]
>>
>> Looking through the diff between the version of libotr in testing vs.
>> the version in sid.  I saw no obvious ABI / API breakage myself - that
>> said I would certainly would not mind a second (third?) reviewer
>> reviewing this assertion though.  Preferably one who knows the C ABI
>> rules by heart.

Hi Ian,

> 
> For the record, the difference between the APIs of libotr 4.0.0 and
> libotr 4.1.0 is that two functions that existed in 4.0.0 but were not
> contained in the .h files (and thus could not appear in applications)
> were added to the .h files in 4.1.0.

Actually, the deciding factor is whether they were "exported" by the
shared library[0].  If they were exported, then an external program
could use them regardless of whether they appeared in a header file of
libotr[1].  This also implies that the functions would already have been
a part of the ABI.

In summary, if libotr exported those functions in 4.0.0 *and* broke
their ABI as well, libotr would have broken its ABI in 4.1.0 and would
require a SONAME bump.  Otherwise, I think we are good.

> So if an application uses those
> functions, it would require to be built against libotr 4.1.0.  Any
> application compiled against 4.0.0 will work with 4.1.0, but not vice
> versa (because of those two new functions).  That's the reason for the
> minor version number change, and the corresponding libtool version
> 6:0:1.  It's also why if you build against the 4.1.0 header files, it
> wants you to have at least 4.1.0 at runtime.
> 
>    - Ian
> 
> 

Certainly.  In Debian, we use "shlib" or "symbols" file to declare such
changes and our build tools will compute the necessary dependency
automatically.
  Assuming these files were correct in the 4.1.0 upload, this would not
be an issue for any Debian maintained reverse dependency.  As noted
above, it might /not/ be a mistake if these files are identical to the
ones in 4.0.0 (assuming 4.0.0 already exported the symbols).

~Niels

[0] I know of several people (upstream and debian maintainers alike)
that were surprised by a library exporting what they thought were
"internal" functions.

As I recall, C static functions are never exported. Others usually need
explicit symbol hiding or a symbol file to declare them as private.  I
believe

 readelf -Ws path/to/libotr.so

will tell you what is exported (and what is imported).  I sadly don't
remember the relevant "grep -v" magic to filter out all the parts you
don't need.

[1] E.g. the reverse dependency could declare the function themselves
without ever implementing a la:

extern int * unmentioned_libotr_function(void *arg1, size_t arg2, ...);