ABI compliance checker

From ISPRAS

ABI Compliance Checker is an easy-to-use tool for checking binary compatibility of shared C/C++ library versions. It checks header files along with shared objects of two library versions and analyzes changes that can cause ABI compatibility problems. 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.

Contents

Downloads

The latest release can be downloaded from this page.

System requirements

The tool requires gcc (>=3.0.0), binutils and perl.

Supported compatibility problems

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

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

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 the 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 RPM or DEB "devel" package, standalone header, standalone shared object or directory with headers and shared objects instead of the standard XML descriptor.

Comparing ABI versions

Command for running the tool:
   perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml> 

In few minutes will be generated report:
   compat_reports/<library_name>/<1st_version>_to_<2nd_version>/abi_compat_report.html 

Checking applications portability

For checking applications portability to the new library version specify its binary file using -app option:
   perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml> -app <application> 

Dumping library ABI

For comparing the library versions that are not co-existed on one machine you can at first dump ABI of the 1st library version using the -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.

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 
or
   perl abi-compliance-checker.pl -l libssh -d1 libssh-dev_0.3.4.dfsg-1_i386.deb -d2 libssh-dev_0.4.0.dfsg-4_i386.deb 
or
   perl abi-compliance-checker.pl -l libssh -d1 libssh-devel-0.3.4-1.i386.rpm -d2 libssh-devel-0.4.0-1.i386.rpm 
or
   perl abi-compliance-checker.pl -l libssh -d1 installed/libssh/0.3.4/ -d2 installed/libssh/0.4.0/ -v1 0.3.4 -v2 0.4.0 
or
   perl abi-compliance-checker.pl -l libssh -d1 libssh.so.0.3.4 -d2 libssh.so.0.4.0 -v1 0.3.4 -v2 0.4.0 
or
   perl abi-compliance-checker.pl -l libssh -d1 libssh/0.3.4/libssh.h -d2 libssh/0.4.0/libssh.h -v1 0.3.4 -v2 0.4.0 

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:

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 objects and header files for checking ABI compliance?

Without header files it is impossible to determine public interfaces in ABI and data type definitions. Without shared objects 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

  1. icheck
  2. chkshlib
  3. cmpdylib
  4. cmpshlib

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.

Articles

  1. Mike Hearn, “Writing shared libraries”
  2. KDE TechBase, “Policies/Binary Compatibility Issues With C++”
  3. Linux.org, “Program Library HOWTO”
  4. Andreas Jonsson, "Calling conventions on the x86 platform"
  5. Ulrich Drepper, "How To Write Shared Libraries"
  6. GNU.org, "ABI Policy and Guidelines", "Binary Compatibility"
  7. Stephen Clamage, "Stability of the C++ ABI: Evolution of a Programing Language"
  8. Pavel Shved, Denis Silakov, "Binary Compatibility of C++ shared libraries on GNU/Linux"
  9. David J. Brown and Karl Runge, "Library Interface Versioning in Solaris and Linux"
  10. Sergey Ayukov, "Shared libraries in Linux: growing pains or fundamental problem?"
  11. Generic ABI (gABI) Standard
  12. Processor Supplement ABI (psABI) documents: Intel386, AMD64, PowerPC, S/390, Itanium, ARM, MIPS, SPARC, PA-RISK, M32R
  13. FreeStandards.org, "ELF and ABI Standards"
  14. Itanium C++ ABI
  15. Computer Desktop Encyclopedia, "Application Binary Interface"
  16. hp.com, "Steps to Version Your Shared Library"
  17. "ABI : stability check"