ABI Compliance Checker

ABI Compliance Checker is an easy-to-use tool for checking binary compatibility of a dynamic C/C++ library versions. It checks header files along with dynamic libraries of old and new versions and analyzes changes in Application Binary Interface (ABI) that can cause binary compatibility problems: changes in call stack, v-table changes, withdrawn interfaces, etc. 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.

1 Downloads
2 System Requirements
3 Supported Platforms
4 Detectable Binary Compatibility Problems
5 Usage
6 Report Format
7 FAQ
8 Similar tools
9 Bugs
10 Maintainers
11 Articles

Downloads

The latest release can be downloaded from this page.

System Requirements

The tool requires GCC (>=3.0.0), binutils (c++filt, readelf, objdump) and Perl (base).

Supported Platforms

GNU/Linux, FreeBSD, Haiku (BeOS)

Detectable Binary Compatibility Problems

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

Added/withdrawn interfaces (functions, global variables)
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 v-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
Changes in constants (defines)

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 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 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.

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 many 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 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

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.