ABI compliance checker
From ISPRAS
ABI Compliance Checker is an easy-to-use tool for checking binary compatibility of shared C/C++ library versions. It checks header files along with shared objects of two library versions and analyzes changes that can cause ABI compatibility problems. Breakage of the binary compatibility may result in crashing or incorrect behavior of applications built with an old version of the library if they run on a new one. The tool is intended for library developers who are interested in ensuring backward binary compatibility (i.e. allow old applications to run with new library versions without recompilation). Also it can be used by ISVs for checking applications portability to new library versions. Found issues can be taken into account when adapting the application to a new library version. This tool is free software: you can redistribute it and/or modify it under the terms of the GNU GPL or LGPL.
Contents |
Downloads
The latest release can be downloaded from this page.
System requirements
The tool requires gcc (>=3.0.0), binutils and perl.
Supported compatibility problems
The tool searches for the following kinds of binary compatibility problems:
- Added/withdrawn interfaces (functions, global variables)
- Changes in constants (defines)
- 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, renaming
- Interface problems
- Added/withdrawn parameters
- Parameters and return type changes
- Incorrect symbols versioning
- Changes in implementation
You can see detailed problem descriptions in the HTML ABI compliance report (see example here) generated by the tool.
Usage
For using the tool, you should provide the descriptors for two library versions: 1st_version.xml and 2nd_version.xml files. 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. An example of the descriptor is the following (0.3.4.xml):
<version> 0.3.4 </version> <headers> /usr/local/libssh/0.3.4/include/ </headers> <libs> /usr/local/libssh/0.3.4/lib/ </libs>
Alternatively you can specify RPM or DEB "devel" package, standalone header, standalone shared object or directory with headers and shared objects instead of the standard XML descriptor.
Comparing ABI versions
Command for running the tool:
perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml>
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:
perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml> -app <application>
Dumping library ABI
For comparing the library versions that are not co-existed on one machine you can at first dump ABI of the 1st library version using the -dump option:
perl abi-compliance-checker.pl -l <library_name> -dump <some_version.xml>
After a time will be created an ABI dump:
abi_dumps/<library_name>/<library_name>_<some_version>.abi.tar.gz
Then transfer and pass it instead of the library descriptor.
Examples
Check the libssh library versions for ABI compatibility:
perl abi-compliance-checker.pl -l libssh -d1 0.3.4.xml -d2 0.4.0.xml
or
perl abi-compliance-checker.pl -l libssh -d1 libssh-dev_0.3.4.dfsg-1_i386.deb -d2 libssh-dev_0.4.0.dfsg-4_i386.deb
or
perl abi-compliance-checker.pl -l libssh -d1 libssh-devel-0.3.4-1.i386.rpm -d2 libssh-devel-0.4.0-1.i386.rpm
or
perl abi-compliance-checker.pl -l libssh -d1 installed/libssh/0.3.4/ -d2 installed/libssh/0.4.0/ -v1 0.3.4 -v2 0.4.0
or
perl abi-compliance-checker.pl -l libssh -d1 libssh.so.0.3.4 -d2 libssh.so.0.4.0 -v1 0.3.4 -v2 0.4.0
or
perl abi-compliance-checker.pl -l libssh -d1 libssh/0.3.4/libssh.h -d2 libssh/0.4.0/libssh.h -v1 0.3.4 -v2 0.4.0
The report will be placed to:
compat_reports/libssh/0.3.4_to_0.4.0/abi_compat_report.html
Dump library ABI:
perl abi-compliance-checker.pl -l libssh -dump 0.3.4.xml
The ABI will be dumped to:
abi_dumps/libssh/libssh_0.3.4.abi.tar.gz
Use previously dumped ABI:
perl abi-compliance-checker.pl -l libssh -d1 libssh_0.3.4.abi.tar.gz -d2 0.4.0.xml
Check application (csync) portability between libssh versions:
perl abi-compliance-checker.pl -l libssh -d1 0.3.4.xml -d2 0.4.0.xml -app /usr/bin/csync
Options
See the list of all options on this page.
Report format
See the examples of ABI compliance report:
- For the library libxml2 from 2.6.32 to 2.7.0
- For the library libssh from 0.3.4 to 0.4.0
- For more than 140 libraries in the Upstream Tracker system.
The report consists of:
- Summary - Number of header files, shared objects, interfaces and data types checked by the tool. Compatibility verdict.
- Problem Summary - Number of binary compatibility problems and added/withdrawn interfaces.
- Added Interfaces - List of added interfaces.
- Withdrawn Interfaces - List of withdrawn interfaces.
- Problems in Data Types - Binary compatibility problems divided by the level of risk introduced by changes in data types. List of affected library interfaces.
- Interface Problems - Binary compatibility problems divided by the level of risk introduced by changes in the interface parameters.
Problems with low level of risk can be considered as warnings. Problems with high or medium level of risk or at least one withdrawn interface lead to incompatible verdict.
- Problems in Constants - List of changed constants (defines).
- Changes in Implementation - List of changes in disassembled binary code.
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.
- 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
- icheck
- chkshlib
- cmpdylib
- cmpshlib
Bugs
Bug reports, feature requests and questions please send to abi-compliance-checker@linuxtesting.org
Maintainers
The tool was developed by the Russian Linux Verification Center at ISPRAS. Andrey Ponomarenko is the leader of this project.
Articles
- Mike Hearn, “Writing shared libraries”
- KDE TechBase, “Policies/Binary Compatibility Issues With C++”
- Linux.org, “Program Library HOWTO”
- Andreas Jonsson, "Calling conventions on the x86 platform"
- Ulrich Drepper, "How To Write Shared Libraries"
- GNU.org, "ABI Policy and Guidelines", "Binary Compatibility"
- Stephen Clamage, "Stability of the C++ ABI: Evolution of a Programing Language"
- Pavel Shved, Denis Silakov, "Binary Compatibility of C++ shared libraries on GNU/Linux"
- David J. Brown and Karl Runge, "Library Interface Versioning in Solaris and Linux"
- Sergey Ayukov, "Shared libraries in Linux: growing pains or fundamental problem?"
- 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"
- hp.com, "Steps to Version Your Shared Library"
- "ABI : stability check"