Re: Uploaded new version 1.6 of htslib, samtools & bcftools to experimental - any known issues with reverse dependencies
On 13 Dec 2017, at 10:47, Mattia Rizzolo <mattia@debian.org> wrote:
> These three symbols are from fuctions that are clearly aimed at debug.
> The functions do dumb fprintf() of some data structures to stderr,
> clearly something that nobody would ever use in a production system.
> The fuctions themselves are still there, hidden by some #ifdef. I
> reckon they were also never intended to be so widely available.
Indeed.
> Nonetheless, that's an ABI break, and for the sake of peace of mind,
> I'd re-enable them until the next SONAME bump (or anyway, the next
> defined ABI break), even if they hopefully are used by nothing.
Why? Don't people who go far out of their way (see below) to use such internal functions deserve what they get?
Even if the function signature were unchanged, what expectation do third parties have that an undocumented internal function still has the behaviour they're expecting in an updated library version?
>> hopen_json_redirect
>
> This was removed (well, replaced by hopen_htsget_redirect) with:
> https://github.com/samtools/htslib/commit/7cdd5749e8054527912df184be87ac7663b01115
> IMHO, that's a clear ABI break, except for the fact that happened in a
> file that is clearly something that is part of some private internal.
> All the other functions from the same file are static, I wonder why that
> one is not.
Because it's the external entry point that is called by code in other source files within HTSlib.
> I'd try to engage upstream for this, they were very helpfully in the
> past itarations and in pointing out our packaging faults, I hope they
> can be of help again.
Me, I have limited time for this this week, but would hope to be able to look at the changes you folks have made next week sometime.
But in short, upstream's guiding principle is this: API and ABI are tightly related. If functions that are not declared within htslib/*.h (therefore are not part of HTSlib's documented public API) are changed, we do not consider that to be an ABI change. Third-party code should not be calling such functions, end of story.
To use debug_vbuf() or hopen_json_redirect() or these other functions, authors of client code would have to search for them in the internal part of HTSlib's source code and copy suitable declarations into their own code in order to call them or otherwise use them. We do not consider that to be a supported use of the HTSlib library, and I think you would struggle to find any other library that supported such use. If such things were supported, how could library authors make changes to the behaviour of any (non-static) internal functions ever [1]?
This argument applies to all of the functions mentioned in your email.
What is the argument in favour of considering clearly unsupported undocumented internal functions to be part of a library's interface just because symbols are visible — in the binary but not the headers?
John
[1] Yes, we're aware of non-portable visibility declarations, and have historically had limited interest in taking up that maintenance burden in HTSlib.
Reply to: