ABI Compliance Checker

ABI Compliance Checker (ACC) is an easy-to-use tool for checking backward binary compatibility (BC) of a shared C/C++ library. It checks header files along with shared libraries of old and new versions and analyzes changes in Application Binary Interface (ABI) that may cause compatibility problems: changes in calling stack, v-table changes, removed symbols, etc. 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 and operating system maintainers who are interested in ensuring binary compatibility, i.e. allow old applications to run with newer library versions without the need to recompile.

  See also: Upstream Tracker for C/C++ libraries; Java ACC prototype.

Contents 1 Downloads 2 License 3 Supported Platforms 4 System Requirements 5 Detectable Compatibility Problems 6 Usage 6.1 Compare Library Versions 6.2 Check Applications Portability 6.3 Dump Library ABI to TXT file 6.4 Command-Line Options 6.5 Examples 7 Tutorial 8 Report Format 9 Verdict on Compatibility 10 FAQ 11 Similar Tools 12 How the Tool Works 13 Bugs 14 Maintainers 15 Credits 16 Articles

Downloads

The latest release can be downloaded from this page.

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, Haiku (BeOS).

System Requirements

The tool requires GCC (3.0-4.6.0, recommended 4.4 or newer), binutils (c++filt, readelf, objdump) and Perl (base).
WARNING: if you are using ccache program (i.e. g++ points to /usr/lib/ccache/g++) then it should be newer than 3.1.2

Detectable Compatibility Problems

The tool searches for the following list of changes in the API that may break binary compatibility:

• Removed Symbols (functions, global data)
• Problems with Data Types
  • Structures:
    • added/removed fields (change of structure layout)
    • change of size
    • changes in fields (recursive analysis)
  • Classes:
    • added/removed virtual functions (change of v-table layout)
    • change of virtual function position
    • overridden virtual functions
  • Enumerations:
    • change of a member value
    • renamed members
• Problems with Symbols (functions, methods)
  • Stack Frame:
    • added/removed parameters
    • change of parameter type
  • Other:
    • changed attributes
    • change of return value type
    • incorrect version change
• Problems with Constants (#defines)
  • changed value
• Problems with Implementation
  • changes in disassembled binary code

You can see detailed problem descriptions in the HTML ABI compliance report (see example) generated by the tool.

Usage

For using the tool, you should provide the XML descriptors for two library versions: 1st_version.xml and 2nd_version.xml files. Library descriptor is a simple XML-file that specifies version number, paths to header files and shared libraries 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>

Compare Library Versions

Command to compare two versions of a library:
   perl abi-compliance-checker.pl -l <library_name> -d1 <1st_version.xml> -d2 <2nd_version.xml> 

The compatibility report will be generated to:
   compat_reports/<library_name>/<1st_version>_to_<2nd_version>/abi_compat_report.html 

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:
   perl abi-compliance-checker.pl -l <library_name> -d1 <older.xml> -d2 <newer.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:
   perl abi-compliance-checker.pl -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:
   perl abi-compliance-checker.pl -l <library_name> -d1 <v1_dump.tar.gz> -d2 <v2_dump.tar.gz> 

Command-Line Options

See the list of all options on this page.

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 

The compatibility report will be generated 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 

Tutorial

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

Report Format

See examples of compatibility report:

• For the libxml2 from 2.6.32 to 2.7.0
• For the libssh from 0.3.4 to 0.4.0

The report consists of:

• Summary - Number of header files, shared libraries, symbols and data types checked by the tool. Verdict on binary compatibility.
• Problem Summary - Number of binary compatibility problems and added/removed symbols.
• Added Symbols - List of added symbols.
• Removed Symbols - List of removed symbols.
• Problems with Data Types - List of binary compatibility problems caused by changes in data types (divided by the severity level: High, Medium, Low). List of affected symbols.
• Problems with Symbols - List of binary compatibility problems caused by changes in symbol parameters and attributes (divided by the severity level).
• Problems with Constants - List of changed constants (#defines).
• Problems with Implementation - List of changes in disassembled binary code. Use -check-implementation option to enable this section.

Verdict on Compatibility

Problems with high or medium level of severity or at least one removed symbol lead to incompatible verdict. Problems with low level of severity may be considered as warnings.

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:

   library API + compiler ABI = library 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 exactly determine symbols that are included in ABI for the specified 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.

How the Tool Works

The main steps of the automated BC analysis are the following:

• Automatic detection of include paths for target library headers:
  • Indexing of header files in system directories
  • Recursive search for included header files
  • Create a complete list of GCC -I options to compile headers
• Parse header files:
  • Create the GCC translation unit (TU) dump for header files
  • Parse the TU dump
  • Create the model of library ABI
• Parse shared libraries:
  • Extract the list of exported symbols
  • Intersect it with the list of public symbols from header files
  • Create the model of "public" ABI (you can dump it using -dump option)
• Compatibility check:
  • Compare ABI models of two versions
  • Collect the list of all ABI changes
  • Check it against the list of known BC rules
  • Collect the list of ABI breaks in the library
• Report generation:
  • Detect the list of affected symbols for each ABI break
  • Group ABI breaks by the level of severity (High, Medium, Low)
  • Generate HTML report

Bugs

Please send your bug reports, feature requests and questions directly 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.

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 and ensuring binary compatibility:

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