• Testing
• ABI_checker

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 CFLAGS="-g -Og"
$ make
$ make install

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 -Og options to contain DWARF debug info):

abi-dumper lib/libc-2.16.so -vnum 2.16 -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.

To filter out private ABI interfaces from the resulting ABI dump one can use additional -public-headers and -ignore-tags options of the tool:

abi-dumper lib/libc-2.16.so -vnum 2.16 -o libc-ABI.dump -public-headers glibc-2.16/include/ -ignore-tags ignore.tags

The ignore.tags file contents:

__THROW
__wur
__nonnull

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

The daily updated report for the oncoming releases of the glibc (from git) relative to the previous stable version on x86_64 is available here.

3.1. glibc 2.18

Relative to 2.17

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.

4. References

1. ABI Tracker reports for glibc releases in GNU/Linux on x86_64