Very exciting stuff altogether, I'm sure you'll agree.
What it all means is that just before release we need to make sure we hold to this promise. In the past, we've done this with varying degrees of success. API stability is fairly easy to hold to, but ABI stability is trickier - knowing the rules for what makes or breaks the ABI is half the battle. To be fair, the reason it has been so difficult is because there was no automated tool for sorting this all out for us.
Finally, a couple of years ago, the ABI Compliance Checker appeared which makes the whole thing a doddle. So today I compiled OB 2.3.1 and OB 2.3.2 and installed locally on a Linux system. Then, for each, I made an XML file like so:
<version>
2.3.1
</version>
<headers>
/home/noel/Tools/ABIComplianceChecker/openbabel-2-3-1/tree/include/openbabel-2.0/openbabel
/home/noel/Tools/ABIComplianceChecker/openbabel-2-3-1/tree/include/inchi
</headers>
<libs>
/home/noel/Tools/ABIComplianceChecker/openbabel-2-3-1/tree/lib
</libs>
And finally, I just ran the checker:
$abi-compliance-checker-1.98.3/abi-compliance-checker.pl -lib openbabel -old 2.3.1.xml -new 2.3.2.xml preparation, please wait ... Using GCC 4.8.0 (x86_64-unknown-linux-gnu) checking header(s) 2.3.1 ... ERROR: some errors occurred when compiling headers ERROR: see log for details: /home/noel/Tools/ABIComplianceChecker/logs/openbabel/2.3.1/log.txt checking header(s) 2.3.2 ... ERROR: some errors occurred when compiling headers ERROR: see log for details: /home/noel/Tools/ABIComplianceChecker/logs/openbabel/2.3.2/log.txt comparing ABIs ... comparing APIs ... creating compatibility report ... result: COMPATIBLE total "Binary" compatibility problems: 0, warnings: 4 total "Source" compatibility problems: 0, warnings: 8 see detailed report: compat_reports/openbabel/2.3.1_to_2.3.2/compat_report.html
You can check out the detailed report here.
Notes:
(1) I also had to delete openbabel/math/align.h as I had compiled without Eigen in each case. This header file probably shouldn't have been installed in that case.
(2) The error messages in the log files were related to the use of abs(double). Not sure why.
Nice!
ReplyDeletePartly due to you asking about it, the CDK is more strict about API compatibility (not sure of ABI compat is applicable to Java?), but sometimes the only way to fix a bug is to change the API... we very much limit that, but it occasionally happens...
How does OpenBabel handle that?
Egon
I think the ABI issue is just C/C++. Basically, it means that if a Linux distro updates from OB 2.3.1 to OB 2.3.2 all other software that links to it (e.g. Avogadro) should still work. The rules regarding this are arcane (at least to me).
ReplyDeleteRe API changes to fix bugs: I know what you mean; sometimes you need to get extra information to an object and have no obvious way to pass it in without extending the ABI. Well, we just squeeze that information in somehow, and work around the API; naturally it's not always the cleanest solution. However, if you know that Geoff won't let the patch go out in the next release, then it really spurs the imagination to do it somehow.
It probably also helps that OB has a very flat structure, so that the information does not have to be passed through multiple layers.
To be clear, we can extend the API in 2.x releases. So we could add an optional parameter to a function, and pass extra information in. So that's one way we can and do change the API to fix bugs...
ReplyDeleteI think you got API and ABI backwards in the article. We maintain stable API between 2.x releases (API can be extended tough) and stable ABI for 2.3.x.
ReplyDeleteHmm... Your log contains error messages (probably due to some headers are not self-compiled), so the output compatibility report may be incomplete. Could you please check your */log.txt files and then correct input XML-files (descriptors) to avoid errors? Probably you will need to add include_preamble sections to your input descriptors.
ReplyDeleteAlso GCC 4.8.0 is not yet officially supported by the tool.
Upstream-Tracker page for OB: http://upstream-tracker.org/versions/openbabel.html
@Reinis: Thanks. I've updated the text.
ReplyDelete@Andrey: I did check the logs when running the checker. I've added note (2) above. The error message does not seem important. (I can send you if you are interested.)
Regarding GCC 4.8.0, sure. :-) This was by accident, as my boss likes to compile pre-release versions of GCC.
I'm aware of the upstream tracker, but I didn't link to it as it gives the impression that OB 2.3.1 was not ABI compataible with OB 2.3.0. On the tracker, OB 2.3.1 was not compiled with Eigen, and so is missing two classes.
I see that while generating the compatibility report , the ACC report that
ReplyDelete"ERROR: some errors occurred when compiling headers"
Can these errors be ignored? I get the same tupe of output and when IO check the error logs , I see that it reports errors in boost.