ABI Compliance Checker

ABI Compliance Checker (ACC) is an easy-to-use tool for checking backward binary compatibility (BC) of a shared C/C++ library. It checks header files along with shared libraries of old and new versions and analyzes changes in Application Binary Interface (ABI) that may cause compatibility problems: changes in call stack, v-table changes, removed interfaces, etc. Breakage of the BC 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 and operating system maintainers who are interested in ensuring BC (i.e. allow old applications to run with newer library versions without the need to recompile). 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.

See also: Upstream Tracker for OSS C/C++ libraries.

Downloads

The latest release can be downloaded from this page.

License

This program is free software. You may use, redistribute and/or modify it under the terms of either the GNU GPL or LGPL.

Supported Platforms

GNU/Linux, FreeBSD, Haiku (BeOS).

System Requirements

The tool requires GCC (3.0-4.5.1, recommended 4.0 or newer), binutils (c++filt, readelf, objdump) and Perl (base).
WARNING: if you are using ccache program (i.e. g++ points to /usr/lib/ccache/g++) then it should be newer than 3.1.2

Detectable Binary Compatibility Problems

The tool searches for the following kinds of binary compatibility problems:

Removed interfaces (functions, global variables)
Problems with Data Types
- Structural data types: added/removed fields (changes in layout of type structure), changes in fields, size changes
- Classes: added/removed virtual functions (changes in layout of v-table), virtual function positions, virtual function redefinition
- Enumerations: member value changes, renaming
Problems with Interfaces
- Added/removed parameters
- Parameters and return type changes
- Incorrect symbols versioning
- Changes in implementation
Problems with Constants (defines)

You can see detailed problem descriptions in the HTML ABI compliance report (see example) generated by the tool.

Usage

For using the tool, you should provide descriptors for two library versions: 1st_version.xml and 2nd_version.xml files. Library descriptor is a simple XML-file that specifies version number, paths to header files and shared libraries 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 one of the following instead of the standard XML descriptor:

Standalone header file or shared object
Directory with headers and/or shared objects
RPM or DEB "devel" package (experimental support)

Comparing Library Versions

Command to compare two versions of a library:
perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml>

In few minutes will be generated report in HTML format:
compat_reports/<library_name>/<1st_version>_to_<2nd_version>/abi_compat_report.html

Checking Applications Portability

To check an application portability to the newer library version specify its binary file using -app option:
perl abi-compliance-checker.pl -l <library_name> -d1 <older.xml> -d2 <newer.xml> -app <application>

Dumping Library ABI to TXT file

To compare library versions that are not co-existed on one machine you can dump ABI to gzipped TXT format file using -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:
   perl abi-compliance-checker.pl -l <library_name> -d1 <v1_dump.tar.gz> -d2 <v2_dump.tar.gz>

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

Compare installation directories:
   perl abi-compliance-checker.pl -l libssh -d1 installed/libssh/0.3.4/ -d2 installed/libssh/0.4.0/

Compare shared libraries:
   perl abi-compliance-checker.pl -l libssh -d1 libssh.so.0.3.4 -d2 libssh.so.0.4.0

Compare header files:
   perl abi-compliance-checker.pl -l libssh -d1 libssh/0.3.4/libssh.h -d2 libssh/0.4.0/libssh.h

Compare RPM packages:
   perl abi-compliance-checker.pl -l libssh -d1 libssh-0.3.4.rpm -d2 libssh-0.4.0.rpm

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.

Tutorial

An excellent tutorial "ABI: stability check" is available at Les RPM de Remi Blog.

Report Format

See examples of compatibility report:

For the libxml2 from 2.6.32 to 2.7.0
For the libssh from 0.3.4 to 0.4.0

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/removed interfaces.
Added Interfaces - List of added interfaces.
Withdrawn Interfaces - List of removed 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 in Constants - List of changed constants (#defines).
Changes in Implementation - List of changes in disassembled binary code.

Problems with low level of risk may be considered as warnings. Problems with high or medium level of risk or at least one removed interface lead to incompatible verdict.

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 libraries and header files to check ABI compliance?

Without header files it is impossible to determine public interfaces in ABI and data type definitions. Without shared libraries 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 - C interface ABI/API checker,
BCS - The Symbian Binary Compatibility Suite,
chkshlib, cmpdylib, cmpshlib - compare symbols presence.

Bugs

Please send your bug reports, feature requests and questions directly to abi-compliance-checker@linuxtesting.org or post them to the issue tracker at compat.sf.net/tickets (new).

Maintainers

The tool was developed by the Russian Linux Verification Center at ISPRAS. Andrey Ponomarenko is the leader of this project.

Credits

We would like to thank everyone who has contributed to the success of this project!

Articles

Here is the list of articles about shared libraries and ensuring binary compatibility: