ABI compliance checker Notes

This document describes how to use the ABI compliance checker tool to determine if the ABI of a new version of glibc has changed in a backward-incompatible way. The tool checks for removed symbols, changes in the layout and size of data structures, changes in enumerations and constants (#defines), changes in function parameters and return values, etc. It also checks the source-compatibility of the API.

The tool uses the concept of ABI dumps which are similar to glibc abilist files, but include much more ABI information. An ABI dump can be created for a reference glibc version, say 2.16, and compared with that of a newer version in order to create a compatibility report. See instructions below on how to create and compare ABI dumps for glibc.

Installation

The tool needs G++, Perl 5 and GNU Binutils to be installed on your host.

To install the tool run

$ wget https://github.com/lvc/abi-compliance-checker/downloads/abi-compliance-checker-1.98.3.tar.gz
$ tar -xzf abi-compliance-checker-1.98.3.tar.gz
$ cd abi-compliance-checker-1.98.3
$ sudo perl Makefile.pl -install --prefix=/usr

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

$ cd tmp/
$ abi-compliance-checker -test

Install glibc to a local directory (/home/user/glibc-2.16 for example)

$ wget http://ftp.gnu.org/gnu/glibc/glibc-2.16.0.tar.gz
$ tar -xzf glibc-2.16.0.tar.gz
$ cd glibc-2.16.0
$ mkdir build
$ cd build
$ ../configure --prefix=/home/user/glibc-2.16
$ make
$ make install

Create XML-descriptor file (glibc-descriptor.xml)

<headers>
    {RELPATH}/include/
</headers>

<libs>
    {RELPATH}/lib/
</libs>

<skip_including>
    bits/
    elf.h
    vm86.h
    regexp.h
    /rpcsvc/
</skip_including>

<skip_libs>
    gconv/
</skip_libs>

Usage

The analysis consists of the three steps:

1. Create the ABI dump for the reference glibc version (eg. 2.16),
2. Create the ABI dump for the new glibc version (eg. 2.17),
3. Compare these ABI dumps and look at the generated HTML compatibility report.

Create ABI dumps

To create the ABI dump (glibc-2.16.abi) run

$ abi-compliance-checker -l glibc -dump glibc-descriptor.xml -vnum 2.16 -relpath /home/user/glibc-2.16 -stdout > glibc-2.16.abi

The /home/user/glibc-2.16 is an example of path to the installed glibc tree. Please also look at the file logs/glibc/2.16/log.txt, that may contain headers compilation errors and fix them by extending the input XML-descriptor. Consider adding non-compiled headers to skip_including section of the descriptor or use other sections.

Note that an ABI dump should be created for each supported CPU type (x86, x86_64, arm, etc.) and operating system (GNU/Linux, GNU/Hurd, GNU/kFreeBSD, etc.) because the size and layout of data types can differ depending on environment and some ABI breaks may only occur in one of them. The ABI may also vary depending on the selected configuration options.

The default format of ABI dump is Perl Data::Dumper, but one can change it to XML by specifying of additional -xml option on the command line.

Create report

Once ABI dumps for the reference (2.16) and new (2.17) versions are created then you can compare them to create a compatibility report (abi-report.html)

$ abi-compliance-checker -l glibc -old glibc-2.16.abi -new glibc-2.17.abi -stdout > abi-report.html

The report contains two tabs for binary and source-level compatibility analysis results. Select Binary Compatibility tab to view changes in the ABI.

Current results

This section provides information about current test results for the oncoming release of glibc (2.17 from git) relative to the reference version (2.16).

Samples

1. ABI dump for glibc 2.16 in GNU/Linux on x86_64 (and the same in XML)

2. Compatibility report between glibc 2.11.3 and 2.13 in GNU/Linux on x86

3. Upstream Tracker reports for glibc releases in GNU/Linux on x86