Fork me on GitHub

ABI Compliance Checker

A tool for checking backward API/ABI compatibility of a C/C++ library

ABI Compliance Checker (ABICC) is a tool for checking backward binary and source-level compatibility of a C/C++ library.

The tool analyzes changes in API/ABI (ABI=API+compiler ABI) that may break binary compatibility and/or source compatibility: changes in calling stack, v-table changes, removed symbols, renamed fields, etc.

The tool can create and compare ABI dumps for header files and shared objects of a library. The ABI dump for a library can also be created by the ABI Dumper tool if shared objects include debug-info.

Binary incompatibility may result in crashing or incorrect behavior of applications built with an old version of a library if they run on a new one. Source incompatibility may result in recompilation errors with a new library version. The tool is intended for developers of software libraries and Linux maintainers who are interested in ensuring backward compatibility, i.e. allow old applications to run or to be recompiled with newer library versions.

The tool is developed by Andrey Ponomarenko. You can order additional reports for visualization of the ABI structure and high detailed binary compatibility analysis here: https://abi-laboratory.pro/

The tool is a core of the ABI Tracker and Upstream Tracker projects.

Table of Contents

Downloads

The latest release can be downloaded from this page.

Read-only access to the latest development version:

git clone https://github.com/lvc/abi-compliance-checker.git

License

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

Supported Platforms

GNU/Linux, FreeBSD, Mac OS X, MS Windows.

Dependencies

WARNING: if you are using ccache program (i.e. gcc points to /usr/lib/ccache/gcc) then it should be newer than 3.1.2 or disabled.

On Mac OS X the tool also requires Xcode (g++, c++filt, nm and otool).

On MS Windows the tool also requires MinGW, MS Visual C++ (dumpbin, undname, cl), Active Perl 5, adding of tool locations to the PATH and execution of vcvars64.bat script (C:\Microsoft Visual Studio 9.0\VC\bin\).

Installation

The tool is ready-to-use after extracting the archive.

You can also use a Makefile to install the tool into the system:

sudo make install prefix=PREFIX [/usr, /usr/local]

This command will install the abi-compliance-checker program into the PREFIX/bin system directory and private modules into the PREFIX/share.

To verify that the tool is installed correctly and it works on your host run:

cd tmp/

abi-compliance-checker -test

Usage with ABI Dumper

This new way is based on the analysis of the debug-info from binary objects. It's more reliable, faster and simple way.

The analyzed library should be compiled with "-g -Og" GCC options to contain DWARF debug info.

Create ABI dumps for both library versions first using the ABI Dumper tool:

abi-dumper OLD.so -o ABI-0.dump -lver 0

abi-dumper NEW.so -o ABI-1.dump -lver 1

And then compare ABI dumps to create report:

abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump

The compatibility report will be generated to:

compat_reports/NAME/V0_to_V1/compat_report.html

You can filter out private symbols from the ABI dumps by specifying of additional -public-headers option of the ABI Dumper tool.

Usage (Original)

The original usage is based on the analysis of header files and shared objects (without debug-info).

You should provide XML descriptors for two library versions (v1.xml and v2.xml files) in order to run the analysis. Library descriptor is a simple XML-file that specifies version number, paths to header files and shared libraries and other optional 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>

Command to compare two versions of a library:

abi-compliance-checker -lib NAME -old V1.xml -new V2.xml

The compatibility report will be generated to:

compat_reports/NAME/V1_to_V2/compat_report.html

Tutorial

An excellent tutorial "ABI: stability check" is available at Les RPM de Remi Blog. See also ABI compliance checker Notes at glibc wiki.

Examples

LibraryVersionsReport
libhttpd 2.2.31 vs 2.4.1 report
libMagick++ 6.9.0-0 vs 6.9.0-10 report
libssh 0.3.4 vs 0.3.91 report

See more report examples at http://abi-laboratory.pro/tracker/.

Detectable Binary Compatibility Problems

See "Binary Compatibility Issues With C++" article from KDE TechBase for more info.

Detectable Source Compatibility Problems

Test Suite

The tool is tested properly in the ABI Tracker and Upstream Tracker projects, by the community and by the internal test suite:

abi-compliance-checker -test

There are about 100 basic tests for C and about 200 basic tests for C++ API/ABI breaks.

Create ABI Dumps

The library ABI is a representation of the library API at the binary level. The ABI dump is a dump of the model of the ABI used in the tool.

The ABI dump consists of:

The ABI dump can be used to create a snapshot of a library ABI in the particular environment and then compare it with any other state of the ABI changed due to changes in the environment (compiler version, external libraries, etc.) or changes in the library API (header files).

The typical case is the comparing of two versions of the same library that require incompatible states of the environment (i.e. these versions cannot be installed simultaneously). In this case one can create a dump for one version of the library and then switch the environment and create ABI dump for other version of the library. Two ABI dumps can be compared by the tool to create the API compatibility report.

To create an ABI dump use -dump option:

abi-compliance-checker -lib NAME -dump VER.xml

The ABI dump will be generated to:

abi_dumps/NAME/NAME_VER.abi.tar.gz

To compare ABI dumps pass them as the descriptors:

abi-compliance-checker -lib NAME -old V1.abi.tar.gz -new V2.abi.tar.gz

Report Format

The tool supports two formats of a compatibility report: HTML (default) and XML. To generate XML report you should specify -xml additional option.

The report consists of:

Verdict on Compatibility

If the tool detects problems with high or medium level of severity or at least one removed symbol then the compatibility verdict is incompatible (otherwise compatible). Low-severity problems can be considered as warnings and don't affect the compatibility verdict unless the -strict option is specified.

Error Codes

CodeMeaning
0Compatible. The tool has run without any errors.
1Incompatible. The tool has run without any errors.
2Common error code (undifferentiated).
3A system command is not found.
4Cannot access input files.
5Cannot compile header files.
6Headers have been compiled with minor errors.
7Invalid input ABI dump.
8Unsupported version of input ABI dump.
9Cannot find a module.
10Empty intersection between headers and shared objects.
11Empty set of symbols in headers.

FAQ

Similar Tools

Bugs

Please post bug reports, feature requests and questions to the issue tracker.

Maintainers

The tool is developed by Andrey Ponomarenko.

Changes

You can find changelog here.

Articles

get the source code on GitHub : lvc/abi-compliance-checker