ABI compliance checker
From ISP_RAS
ABI Compliance Checker is a lightweight tool for statically checking backward binary compatibility of shared C/C++ libraries in Linux. It checks header files along with shared objects in two library versions and searches for ABI changes that may lead to incompatibility. Breakage of the binary compatibility may result in crashing or incorrect behavior of applications built with an old version of a library when it is running with a new one. ABI Compliance Checker was intended for library developers that are interested in ensuring backward binary compatibility. Also it can be used for checking forward binary compatibility and checking applications portability to the new library version. This tool is free software: you can redistribute it and/or modify it under the terms of the GNU GPL.
Contents |
Downloads
The latest release of ABI Compliance Checker can be downloaded from this page.
System requirements
ABI Compliance Checker requires gcc, binutils and perl.
Supported compatibility problems
ABI Compliance Checker searches for the following kinds of binary compatibility problems:
- Added/withdrawn interfaces (functions, global variables)
- Constants changes
- Problems in Data Types
- Structural data types: added/withdrawn members (changes in layout of type structure), changes in members, size changes
- Classes: added/withdrawn virtual functions (changes in layout of virtual table), virtual function positions, virtual function redefinition
- Enumerations: member value changes
- Interface problems
- Parameters and return type changes
- Incorrect symbols versioning
More detailed problem descriptions you can see in the ABI compliance report (see example here) generated by ABI Compliance Checker.
Usage
For using ABI Compliance Checker you must provide the so-called descriptors for two library versions. Library descriptor is a simple file with an XML-like structure that specifies version number, paths to header files and shared objects and optionally some other information.
Command for running ABI Compliance Checker:
./abi-compliance-checker.pl -l <library_name> -d1 <1st_version_descriptor> -d2 <2nd_version_descriptor>
In few minutes will be generated report:
compat_reports/<library_name>/<1st_version>_to_<2nd_version>/abi_compat_report.html
Checking applications portability
For checking applications portability to the new library version specify its binary file using -app option:
./abi-compliance-checker.pl -l <library_name> -d1 <1st_version_descriptor> -d2 <2nd_version_descriptor> -app <application>
Dumping library ABI
For checking ABI compliance of the library versions that are not co-existed on one machine you must at first dump all necessary library ABI information about the 1st version using the following command:
./abi-compliance-checker.pl -l <library_name> -dump_info <1st_version_descriptor>
After a time will be created <library_name>_<1st_version>.abi.tar.gz file in the directory abi_dumps/<library_name>/. Then transfer and pass it instead of library descriptor on the other machine:
./abi-compliance-checker.pl -l <library_name> -d1 <library_name>_<1st_version>.abi.tar.gz -d2 <2nd_version_descriptor>
Report format
The ABI compliance report generated by ABI Compliance Checker consists of:
- Summary - information about checked header files and shared objects, compatibility verdict.
- Problem Summary - statistics of backward binary compatibility problems and also some forward binary compatibility problems (number of added interfaces).
- Added interfaces - list of added interfaces.
- Withdrawn interfaces - list of withdrawn interfaces.
- Problems in Data Types, high|medium|low risk - backward binary compatibility problems with high, medium or low level of risk introduced by changes in data types and list of affected library interfaces.
- Interface problems, high|medium|low risk - backward binary compatibility problems with high, medium or low level of risk introduced by changes in parameters or in return value of library interfaces.
Problems with low level of risk can be considered as warnings. Only problems with high or medium level of risk or at least one withdrawn interface lead to incompatible verdict.
See the example of ABI compliance report for libxml2 from 2.6.32 to 2.7.0
FAQ
- What is an ABI and how does it differ from an API?
An Application Binary Interface (ABI) is the set of supported run-time interfaces provided by a software component or set of components for applications to use, whereas an Application Programming Interface (API) is the set of build-time interfaces (this explanation has been taken from here).
- Why does this tool need both shared objects and header files for checking ABI compliance?
Without header files it is impossible to determine public interfaces in ABI and data type definitions. Without shared objects it is impossible to exactly determine interfaces that are included in ABI for the specified library and also impossible to detect added/withdrawn interfaces.
Similar tools
Bugs
Bug reports, feature requests and questions please send to abi-compliance-checker@linuxtesting.org
Author
Andrey Ponomarenko, Institute for System Programming of Russian Academy of Sciences (ISP RAS)
References
- Mike Hearn, “Writing shared libraries”
- KDE TechBase, “Policies/Binary Compatibility Issues With C++”
- Linux.org, “Program Library HOWTO”
- Ulrich Drepper, "How To Write Shared Libraries"
- gcc.gnu.org, "ABI Policy and Guidelines"
- gcc.gnu.org, "Binary Compatibility"
- Stephen Clamage, "Stability of the C++ ABI: Evolution of a Programing Language"
- David J. Brown and Karl Runge, "Library Interface Versioning in Solaris and Linux"
- Generic ABI (gABI) Standard
- Processor Supplement ABI (psABI) documents: Intel386, AMD64, PowerPC, S/390, Itanium, ARM, MIPS, SPARC, PA-RISK, M32R
- freestandards.org, "ELF and ABI Standards"
- Itanium C++ ABI
- Computer Desktop Encyclopedia, "Application Binary Interface"