Introduction
The abicheck task helps verify that the Application Binary Interface (a.k.a. ABI) of a new version of a Fedora C or C++ shared library stays compatible with its previous version. This task is executed when a new Fedora package is built by the Koji build service.
Where to see the results of the task?
The results of the abicheck Taskotron Task for Fedora packages that are build by the Koji build system can be browsed from the ResultDB database.
How does abicheck task work?
For each new Koji build, all sub-packages for all architectures (armv7hl, i686 and x86_64) are downloaded along with their debug info packages. Sub-packages of the previous latest stable corresponding build available in koji are downloaded along with their debug info packages as well.
The task then invokes the abipkgdiff tool to compare the ABIs of each new sub-package against its previous stable counterpart. The ABI comparison is only performed on shared libraries presents in those packages.
Known deficiencies
Comparing the ABI of two shared libraries involves performing a deep static analysis of the binaries and their debug information. Information about (possibly all) types and declarations present in the binaries are loaded in main memory and analyzed. The bigger the library and its debug information, the more memory is needed to perform the analysis.
The amount of memory needed by the abipkgdiff tool can vary from a few Kilobytes for small libraries to many Gigabytes for huge libraries.
Right now, taskotron executes the abicheck task on a system with 6GB of RAM. This task will fail to run if the amount of memory required for ABI comparison is greater than 6 GB.
Dealing with Result
The outcome of the abicheck task run can be PASSED, FAILED or NEEDS_INSPECTION. Depending on the outcome, either one of the following actions should be taken:
- PASSED: No ABI change has been found. No review of the ABI change report logs is thus required.
- FAILED: Incompatible ABI changes have been found in one or more libraries contained in the package. These changes will almost certainly break applications or libraries that depend on this package. A thorough review of the ABI changes reported in the logs is thus required. Please provide a relevant justification for these ABI changes or come with a new build that fixes those changes.
- NEEDS_INSPECTION: Some ABI changes have been found. As a result, the ABI of the package might or might not be incompatible with its previous version. It is thus highly recommended to look into the log containing the ABI change report and verify that the ABI changes are harmless. If the changes are harmful, then please submit new version of the package that fixes the issue.
How to filter some change reports out?
Some package maintainers might want to avoid comparing some binaries inside their packages, for various reasons. Or, they might want to filter out some ABI changes that are not problematic in their particular context. Luckily, there are ways to suppress parts of the ABI change report by defining suppression specifications. Checkout how to define ABI change suppression specifications in task-abicheck!
Getting Help
For further help on understanding logs containing ABI change reports, you can subscribe to the libabigail mailing list and send an email there. You can also ask us on IRC by joining the #libabigail channel on the irc.oftc.net network.
If you see any issue in the generated ABI change report log, please report a bug to libabigail's bugzilla
For any feature request on the abicheck taskotron task, please create an issue on the abicheck task issue tracker.
Additional Information
- Browse abicheck taskotron task source code at pagure