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.

1. Installation

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

To install the tool run

$ git clone git://github.com/lvc/abi-compliance-checker.git
$ cd abi-compliance-checker
$ 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

To install the library with debug-info add CFLAGS="-g -O2" configure option.

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

2.1. Create ABI dumps

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>

<defines>
    #define __STDC_LIMIT_MACROS
    #define __STDC_FORMAT_MACROS
</defines>

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

ABI Dumper

There is also an alternative simple way to create ABI dumps by the ABI Dumper tool (the library should be compiled with -g option to contain DWARF debug info):

abi-dumper libc.so -lver 2.18 -o libc-ABI.dump

The advantage of this approach is that it doesn't require input XML descriptor and compilation of header files. The disadvantage - the resulting ABI dump contains info about private interfaces too, so ABI checker will create a report about changes in both public and private interfaces. Also this kind of ABI dump allows to check only 98% of compatibility rules.

2.2. 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 -report-path 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.

3. Current results

This section provides information about current test results for the oncoming releases of glibc (from git) relative to the previous stable version. The daily updated report on x86 is available here.

3.1. glibc 2.19

Relative to 2.18

CPU \ Kernel

GNU/Linux

x86

OK (2014/01/28)

x86_64

OK (2014/01/28)

arm

???

There are several changes in private ABI.

3.2. glibc 2.18

Relative to 2.17

CPU \ Kernel

GNU/Linux

x86

OK (2013/07/25)

x86_64

OK (2013/07/25)

arm

Added _elision field (short) to _pthread_mutex_s structure and changed type of _spins field from int to short on x86_64. Both fields are for internal use only. Size of the container structure is not affected. So this change is safe. See related discussion on the mailing list from 10 Jan 2013.

Added field si_addr_lsb to anon-struct-siginfo.h-108 which is a part of siginfo_t::anon-union-siginfo.h-70. The size of the siginfo_t struct is not changed. This change is safe. See related discussion on the mailing list from 07 May 2013.

4 changed constants: E_MIPS_ARCH_32, E_MIPS_ARCH_64, EF_MIPS_ARCH_32 and EF_MIPS_ARCH_64 (elf.h). This change is safe. See related discussion on the mailing list from 10 Jan 2013.

3 removed constants: EPOLL_NONBLOCK (epoll.h), GLIBC_HAVE_LONG_LONG and USE_ANSI (features.h). This is safe change too. See related discussions on the mailing list: 1, 2 and 3.

See also changes in private ABI.

3.3. glibc 2.17

Relative to 2.16.0

CPU \ Kernel

GNU/Linux

GNU/Hurd

GNU/kFreeBSD

x86

OK (2012/11/30)

x86_64

OK (2012/11/30)

arm

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

None: Testing/ABI_checker (last edited 2014-01-28 15:42:20 by AndreyPonomarenko)