ABI Compliance Checker

ABI Compliance Checker (ACC) is a tool for checking backward binary and source-level compatibility of a C/C++ library. The tool checks header files and shared libraries of old and new versions and analyzes changes in API and ABI (ABI=API+compiler ABI) that may break binary and/or source compatibility: changes in calling stack, v-table changes, removed symbols, renamed fields, etc. 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 maintainers of operating systems who are interested in ensuring backward compatibility, i.e. allow old applications to run or to be recompiled with newer library versions.

See also:


Contents

Downloads

Releases

All releases can be downloaded from this page or github.com.

Latest release: 1.97.5

Git

Read-only access to the latest development version:
   git clone git://github.com/lvc/abi-compliance-checker.git  

SVN (obsolete)

Read-only access to the latest development version:
   svn co http://forge.ispras.ru/svn/abi-compliance-checker 

License

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

Supported Platforms

GNU/Linux, FreeBSD, Mac OS X, MS Windows (Xp, Vista, 7), Haiku (BeOS).

System Requirements

  • Linux, FreeBSD
    • G++ (3.0-4.7, recommended 4.5 or newer)
    • GNU Binutils (readelf, c++filt, objdump)
    • Perl (5.8 or newer)
    • 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.
  • Mac OS X
    • Xcode (gcc, otool, c++filt)
  • MS Windows
    • MinGW (3.0-4.7, recommended 4.5 or newer)
    • MS Visual C++ (dumpbin, undname, cl)
    • Active Perl (5.8 or newer)
    • Sigcheck v1.71 or newer
    • Info-ZIP 3.0 (zip, unzip)
    • Add gcc.exe path (C:\MinGW\bin\) to your system PATH variable
    • Run vsvars32.bat script (C:\Microsoft Visual Studio 9.0\Common7\Tools\)

Detectable Compatibility Problems

The tool searches for the following list of changes in the API that may break binary/source-level compatibility. See “Binary Compatibility Issues With C++” from KDE TechBase and this list of articles for more info.

Binary Compatibility

  • Removed Symbols (functions, global data)
  • Problems with Data Types
    • Structures and Classes
      • added/removed fields (change of a memory layout)
      • change of size
      • changed order of fields
      • change of a field type
      • changes in fields (recursive analysis)
    • Classes
      • added/removed virtual functions (change of a v-table layout)
      • change of virtual function position
      • overridden virtual functions
      • added/removed base classes
      • changes in base classes (recursive analysis)
    • Unions
      • added/removed fields
      • change of size
      • change of a field type
      • changes in fields (recursive analysis)
    • Enumerations
      • change of a member value
      • removed/renamed members
  • Problems with Symbols
    • Stack Frame
      • added/removed parameters
      • change of a parameter/return value type
      • change of default parameter value
      • renamed parameters
    • Other
      • incorrect version change
      • changed attributes (const, volatile, static, etc.)
  • Problems with Constants (#defines)
    • changed value
  • Problems with Implementation
    • changes in disassembled binary code

Source Compatibility

  • Removed Symbols (functions, global data)
  • Problems with Data Types
    • Structures, Classes and Unions
      • removed/renamed fields
      • change of a field type
      • changes in fields (recursive analysis)
    • Classes
      • added/removed base classes
    • Enumerations
      • removed/renamed members
  • Problems with Symbols
    • Parameters
      • added/removed parameters
      • change of a parameter type
    • Other
      • change of return value type
      • changed attributes (const, static, etc.)
  • Problems with Constants (#defines)
    • changed value


You can see detailed problem descriptions in the visual interactive HTML-format compatibility report (see this example) generated by the tool.

Installation

The tool is ready-to-use after extracting the archive. You can also use a Makefile to install the tool into the system:
 cd abi-compliance-checker-x.y.z/ 

 sudo perl Makefile.pl -install --prefix=PREFIX [/usr, /usr/local, ...] 

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

Usage

For using the tool, you should provide the XML descriptors for two library versions: v1.xml and v2.xml files. 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>

Compare Libraries

Command to compare two versions of a library:
   abi-compliance-checker -l <library_name> -old <v1.xml> -new <v2.xml> 

The compatibility report will be generated to:
   compat_reports/<library_name>/<v1>_to_<v2>/compat_report.html 

Compare Operating Systems

The detailed explanation on how to check compatibility between operating systems you can read on this page.

See current test results for Symbian, Windows, MeeGo and Maemo on this page.

Check Applications Portability

The ACC tool can be used by ISVs for checking applications portability to new library versions by specifying of its binary using -app option:
   abi-compliance-checker -l <library_name> -old <v1.xml> -new <v2.xml> -app <application> 

Found issues can be taken into account when adapting the application to a new library version.

Dump Library ABI to TXT file

To compare library versions that are not co-existed on one machine you can dump ABI to gzipped TXT format file using -dump option:
   abi-compliance-checker -l <library_name> -dump <some_version.xml> 

The ABI dump will be generated to:
   abi_dumps/<library_name>/<library_name>_<some_version>.abi.tar.gz 

Then transfer and pass it instead of the library descriptor:
   abi-compliance-checker -l <library_name> -old <v1_dump.tar.gz> -new <v2_dump.tar.gz> 

Command-Line Options

See the list of all options on this page.

Up-to-date list of all supported options can be obtained using the following command:

   abi-compliance-checker --info 

Examples

Check the libssh library versions for ABI compatibility:
   abi-compliance-checker -l libssh -old 0.3.4.xml -new 0.4.0.xml 

The compatibility report will be generated to:
   compat_reports/libssh/0.3.4_to_0.4.0/compat_report.html 

Dump library ABI:
   abi-compliance-checker -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:
   abi-compliance-checker -l libssh -old libssh_0.3.4.abi.tar.gz -new libssh_0.4.0.abi.tar.gz 

Check client application portability between libssh versions:
   abi-compliance-checker -l libssh -old 0.3.4.xml -new 0.4.0.xml -app /usr/bin/csync 

Tutorial

An excellent tutorial "ABI: stability check" is available at Les RPM de Remi Blog.

Report Format

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

The HTML-format compatibility report consists of:

  • Test Info - The library name and compared version numbers. Environment info: GCC version and CPU type;
  • Test Results - Verdict on compatibility. Number of header files, shared libraries, symbols and data types checked by the tool;
  • Problem Summary - Classification of compatibility problems;
  • Added Symbols - The list of added symbols;
  • Removed Symbols - The list of removed symbols;
  • Problems with Data Types - The list of compatibility problems caused by changes in data types (divided by the severity level: High, Medium and Low). List of affected symbols;
  • Problems with Symbols - The list of compatibility problems caused by changes in symbol parameters or attributes (divided by the severity level);
  • Problems with Constants - The list of changed constants (#defines);
  • Other Changes in Data Types - The list of compatible changes in data types;
  • Other Changes in Symbols - The list of compatible changes in symbols;
  • Problems with Implementation - The list of changes in disassembled binary code. Use -check-implementation option to enable this section.

Examples:

  • NetCDF: 4.0.1 to 4.1.1 API compatibility report
  • MySQL++: 3.0.9 to 3.1.0 binary compatibility report
  • libssh: 0.3.4 to 0.4.0 binary compatibility report

Verdict on Compatibility

If the tool detected 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

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

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. The ABI may be defined by the formula: 

   ABI = API + compiler ABI
  • Why does this tool need both shared libraries and header files to check ABI compliance?

Without header files it is impossible to determine public symbols in ABI and data type definitions. Without shared libraries it is impossible to determine exported symbols in the ABI of the target library and also impossible to detect added/removed symbols.

Similar Tools

  1. icheck - C interface ABI/API checker,
  2. BCS - The Symbian Binary Compatibility Suite,
  3. shlib-compat - ABI compatibility checker that uses DWARF debug info,
  4. qbic - A tool to check for binary incompatibilities in Qt4 Toolkit,
  5. chkshlib, cmpdylib, cmpshlib - compare symbols presence.

Bugs

Please post your bug reports, feature requests and questions to the issue tracker or send to this address.

Maintainers

The tool was initially developed by the Russian Linux Verification Center at ISPRAS and is now developed by ROSA Laboratory in Russia. Andrey Ponomarenko is the leader of this project.

Sponsors

The development of this tool is currently sponsored by Nokia.

Logo nokia.gif

If you want to be a sponsor and move the development of the tool in the way you need then please contact us at this address.

Credits

We would like to thank everyone who has contributed to the success of this project!

Articles

Here is the list of articles about shared libraries, ABI and binary compatibility:

  1. KDE TechBase, “Binary Compatibility Issues With C++”
  2. KDE TechBase, “Binary Compatibility Examples”
  3. codesourcery.com, "Itanium C++ ABI"
  4. Josh Faust, "ABI Compatibility"
  5. Les RPM de Remi - Blog, "ABI : stability check"
  6. Agner Fog, “Calling conventions for different C++ compilers and operating systems”
  7. Andreas Jonsson, "Calling conventions on the x86 platform"
  8. Thiago Macieira, “Some thoughts on binary compatibility”
  9. Pavel Shved, Denis Silakov, "Binary Compatibility of C++ shared libraries on GNU/Linux"
  10. David J. Brown and Karl Runge, "Library Interface Versioning in Solaris and Linux"
  11. HP.com, "Steps to Version Your Shared Library"
  12. developer.apple.com, "Macintosh C/C++ ABI Overview"
  13. Chad Austin, “Binary-compatible C++ Interfaces”
  14. GNU.org, "ABI Policy and Guidelines"
  15. GNU.org, "Binary Compatibility"
  16. Stephen Clamage, "Stability of the C++ ABI: Evolution of a Programing Language"
  17. Debian Library Packaging guide, "When binary compatibility breaks"
  18. KDE TechBase, “Library Code Policy”
  19. Ulrich Drepper, "How To Write Shared Libraries"
  20. Computer Desktop Encyclopedia, "Application Binary Interface"
  21. Linux.org, “Program Library HOWTO”
  22. Mike Hearn, “Writing shared libraries”
  23. Sergey Ayukov, "Shared libraries in Linux: growing pains or fundamental problem?"
  24. Peter Potrebic, “What's the Fragile Base Class (FBC) Problem?”
  25. OoCities.org, “The amazing world of library incompatibility”
  26. Forum.Nokia, “The Theory of Binary Compatibility”
  27. Forum.Nokia, “How to control binary compatibility”
  28. elpauer.org, “ABI compatibility in C++”
  29. symbian.org, "Preserving Compatibility"
  30. Ponomarenko A., Rubanov V., VALID 2010, "Automated Verification of Shared Libraries for Backward Binary Compatibility"
  31. Thiago Macieira's blog, "Architectures and ABIs detailed"
  32. FreeStandards.org, Generic ABI (gABI) Standard, "ELF and ABI Standards"
  33. Processor Supplement ABI (psABI) documents: Intel386, AMD64, PowerPC, S/390, Itanium, ARM, MIPS, SPARC, PA-RISK, M32R