so库二进制兼容性检测

http://stackoverflow.com/questions/1970296/how-to-test-binary-compatibility-automatically

v

ABI Compliance Checker — a tool for checking backward API/ABI compatibility of a C/C++ library: abi-compliance-checker -lib NAME -old OLD.abidump -new NEW.abidump *.abidump files are ABI dumps of OLD and NEW library versions generated by the ABI Dumper tool. icheck - C interface ABI/API checker: icheck --canonify -o old_version -I/usr/include/foo/ bar.h icheck --compare -o results.txt old_version new_version shlib-compat - ABI compatibility checker that uses DWARF debug info: python shlib-compat -vv OLD.so NEW.so

关于checker的下载：

       A tool for checking backward API/ABI compatibility of a C/C++ library

ABI Compliance Checker (ABICC) 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 Linux maintainers who are interested in ensuring backward compatibility, i.e. allow old applications to run or to be recompiled with newer library versions.

The tool is developed by Andrey Ponomarenko. You can order additional reports for visualization of the ABI structure and high detailed binary compatibility analysis here: https://abi-laboratory.pro/

The tool is a core of the ABI Tracker and Upstream Tracker projects.

Table of Contents Downloads License Supported Platforms Dependencies Installation Usage with ABI Dumper Usage (Original) Tutorial Examples Detectable Binary-Compatibility Problems Detectable Source-Compatibility Problems Test Suite Create ABI Dumps Report Format Verdict on Compatibility Error Codes FAQ Similar Tools Bugs Maintainers Changes Articles

Downloads

The latest release can be downloaded from this page.

Read-only access to the latest development version:

git clone https://github.com/lvc/abi-compliance-checker.git

License

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

Supported Platforms

GNU/Linux, FreeBSD, Mac OS X, MS Windows.

Dependencies

• G++ (3.0-4.7, 4.8.3 or newer)
• GNU Binutils (readelf, c++filt, objdump)
• Perl 5
• Ctags
• ABI Dumper

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.

On Mac OS X the tool also requires Xcode (g++, c++filt, nm and otool).

On MS Windows the tool also requires MinGW, MS Visual C++ (dumpbin, undname, cl), Active Perl 5, adding of tool locations to the PATH and execution of vcvars64.bat script (C:\Microsoft Visual Studio 9.0\VC\bin\).

Installation

The tool is ready-to-use after extracting the archive.

You can also use a Makefile to install the tool into the system:

sudo make install prefix=PREFIX [/usr, /usr/local]

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

To verify that the tool is installed correctly and it works on your host run:

cd tmp/

abi-compliance-checker -test

Usage with ABI Dumper

This new way is based on the analysis of the debug-info from binary objects. It's more reliable, faster and simple way.

The analyzed library should be compiled with "-g -Og" GCC options to contain DWARF debug info.

Create ABI dumps for both library versions first using the ABI Dumper tool:

abi-dumper OLD.so -o ABI-0.dump -lver 0

abi-dumper NEW.so -o ABI-1.dump -lver 1

And then compare ABI dumps to create report:

abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump

The compatibility report will be generated to:

compat_reports/NAME/V0_to_V1/compat_report.html

You can filter out private symbols from the ABI dumps by specifying of additional -public-headers option of the ABI Dumper tool.

Usage (Original)

The original usage is based on the analysis of header files and shared objects (without debug-info).

You should provide XML descriptors for two library versions (v1.xml and v2.xml files) in order to run the analysis. 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>

Command to compare two versions of a library:

abi-compliance-checker -lib NAME -old V1.xml -new V2.xml

The compatibility report will be generated to:

compat_reports/NAME/V1_to_V2/compat_report.html

Tutorial

An excellent tutorial "ABI: stability check" is available at Les RPM de Remi Blog. See also ABI compliance checker Notes at glibc wiki.

Examples

Library	Versions	Report
libhttpd	2.2.31 vs 2.4.1	report
libMagick++	6.9.0-0 vs 6.9.0-10	report
libssh	0.3.4 vs 0.3.91	report

See more report examples at http://abi-laboratory.pro/tracker/.

Detectable Binary Compatibility Problems

• 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
  • removed symbols (functions or global data)
  • added/removed parameters
  • change of a parameter/return value type
  • change of default parameter value
  • renamed parameters
  • incorrect version change
  • changed attributes (const, volatile, static, etc.)
    
    
• Problems with Constants (#defines)
  • changed value

See "Binary Compatibility Issues With C++" article from KDE TechBase for more info.

Detectable Source Compatibility Problems

• 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
    • change access level of a field or method
    • added pure virtual methods
  • Enumerations
    • removed/renamed members
      
      
• Problems with Symbols
  • removed symbols (functions or global data)
  • added/removed parameters
  • change of a parameter type
  • removed default value of parameter
  • change of return value type
  • changed attributes (const, static, etc.)

Test Suite

The tool is tested properly in the ABI Tracker and Upstream Tracker projects, by the community and by the internal test suite:

abi-compliance-checker -test

There are about 100 basic tests for C and about 200 basic tests for C++ API/ABI breaks.

Create ABI Dumps

The library ABI is a representation of the library API at the binary level. The ABI dump is a dump of the model of the ABI used in the tool.

The ABI dump consists of:

• Types Information
  • Attributes (name, size, header, access, base types, etc.)
  • Fields (name, type, size, position, alignment, access, specifiers, etc.)
  • V-table structure (offsets, entries)
  • Etc.
• Symbols Information
  • Attributes (name, mangled name, header, access, specifiers, etc.)
  • Parameters (name, type, position, alignment, etc.)
  • Etc.
• Etc.

The ABI dump can be used to create a snapshot of a library ABI in the particular environment and then compare it with any other state of the ABI changed due to changes in the environment (compiler version, external libraries, etc.) or changes in the library API (header files).

The typical case is the comparing of two versions of the same library that require incompatible states of the environment (i.e. these versions cannot be installed simultaneously). In this case one can create a dump for one version of the library and then switch the environment and create ABI dump for other version of the library. Two ABI dumps can be compared by the tool to create the API compatibility report.

To create an ABI dump use -dump option:

abi-compliance-checker -lib NAME -dump VER.xml

The ABI dump will be generated to:

abi_dumps/NAME/NAME_VER.abi.tar.gz

To compare ABI dumps pass them as the descriptors:

abi-compliance-checker -lib NAME -old V1.abi.tar.gz -new V2.abi.tar.gz

Report Format

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

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

Verdict on Compatibility

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

• icheck - C interface ABI/API checker.
• BCS - The Symbian binary compatibility suite.
• shlib-compat - ABI compatibility checker that uses DWARF debug info.
• qbic - A tool to check for binary incompatibilities in Qt4 Toolkit.
• libabigail - A C++ library for ABI analysis.
• chkshlib, cmpdylib, cmpshlib - Tools to compare binary symbols.

Bugs

Please post bug reports, feature requests and questions to the issue tracker.

Maintainers

The tool is developed by Andrey Ponomarenko.

Changes

You can find changelog here.

Articles

• "Binary Compatibility Issues With C++", KDE TechBase
• "Binary Compatibility Examples", KDE TechBase
• "Automated Verification of Shared Libraries for Backward Binary Compatibility", A. Ponomarenko and V. Rubanov, VALID 2010
• "Backward compatibility of software interfaces: Steps towards automatic verification", A. Ponomarenko and V. Rubanov, Programming and Computer Software 2012
• "Itanium C++ ABI", linux-foundation.org
• "ABI Compatibility", Josh Faust
• "ABI : stability check", Les RPM de Remi - Blog
• "Calling conventions for different C++ compilers and operating systems", Agner Fog
• "Calling conventions on the x86 platform", Andreas Jonsson
• "Some thoughts on binary compatibility", Thiago Macieira
• "Binary Compatibility of C++ shared libraries on GNU/Linux", Pavel Shved, Denis Silakov
• "Library Interface Versioning in Solaris and Linux", David J. Brown and Karl Runge
• "Steps to Version Your Shared Library", hp.com
• "Binary-compatible C++ Interfaces", Chad Austin
• "ABI Policy and Guidelines", gnu.org
• "Binary Compatibility", gnu.org
• "Stability of the C++ ABI: Evolution of a Programing Language", Stephen Clamage
• "When binary compatibility breaks", Debian Library Packaging guide
• "Library Code Policy", KDE TechBase
• "How To Write Shared Libraries", Ulrich Drepper
• "Program Library HOWTO", linux.org
• "Writing shared libraries", Mike Hearn
• "Shared libraries in Linux: growing pains or fundamental problem?", Sergey Ayukov
• "Fragile Binary Interface Problem", Steven Newton
• "The amazing world of library incompatibility", oocities.org
• "ABI compatibility in C++", elpauer.org
• "The impact of C++ templates on library ABI", Michał Górny
• "ABI compliance checker Notes", sourceware.org
• "Preserving Compatibility", symbian.org
• "Architectures and ABIs detailed", Thiago Macieira's blog
• "Interface Versioning in C++", ACCU
• Processor ABI standards: Intel386, AMD64, ARM, PowerPC, S/390, Itanium, MIPS, SPARC, PA-RISK, M32R
• "Generic ABI Standard", "ELF and ABI Standards", freestandards.org
• "Binary compatibility for library developers", Video, Thiago Macieira
• "ACC for abi breaks", Dimitri Ledkov