Bug#571776: document symbols
Jakub Wilk <jwilk@debian.org> writes:
> * Russ Allbery <rra@debian.org>, 2012-01-02, 13:51:
>> <p>
>> A common example of when a change
>> to <var>minimal-version</var> is required is a function that
>> takes an enum or struct argument that controls what the
>> function does. For example:
>> <example>
>>enum library_op { OP_FOO, OP_BAR };
>>int library_do_operation(enum library_op);
>> </example>
>> If a new operation, <tt>OP_BAZ</tt>, is added,
>> the <var>minimal-version</var>
>> of <tt>library_do_operation</tt> must be increased to the
>> version at which <tt>OP_BAZ</tt> was introduced. Otherwise, a
>> binary built against the new version of the library (having
>> detected at compile-time that the library
>> supports <tt>OP_BAZ</tt>) may be installed with a shared
>> library that doesn't support <tt>OP_BAZ</tt> and will fail at
>> runtime when it tries to pass <tt>OP_BAZ</tt> into this
>> function.
>> </p>
> Hmm. It was my understanding that one of the purposes of
> Build-Depends-Package is to avoid bumping symbol versions in situations
> like this.
That moves the onus from the library maintainer to the client package
maintainer, who then has to know whether the code is sensitive to this
sort of change and be constantly tightening the Build-Depends. That
sounds wrong; determining whether a particular library client cares about
a behavior change can be quite difficult, particularly compared to just
bumping the symbol revision if the implementation has changed.
Hm, I suppose that if the client upstream knows about this sort of thing,
they may document it somewhere, which would make it easier. But I'm
thinking about a library client that, say, probes for the version of the
package in configure or via a version provided by the library and
selectively enables behavior based on those results without otherwise
saying anything about it. That sort of thing is pretty common and
sometimes hard to notice.
Also, historically, this sort of version bump was required for shlibs, so
this is just moving the requirement along to symbols.
--
Russ Allbery (rra@debian.org) <http://www.eyrie.org/~eagle/>
Reply to: