abi-compliance-checker

Langue: en

Version: 7 August 2009 (ubuntu - 24/10/10)

Section: 1 (Commandes utilisateur)

NAME

abi-compliance-checker - Compare ABI/binary compatibility for C/C++ shared library

SYNOPSIS

abi-compliance-checker -d
abi-compliance-checker -l <libname> -d1 <v1.xml> -d2 <v2.xml> [-fast]


DESCRIPTION

Compare backward binary compatibility of shared C/C++ libraries.

This can be used to help reduce the possibility of an application crashing when the shared libraries it links against have changed. Signatures and data type definations from two separate versions of a library are compared by examining the shared objects (.so) files themselves, and by analysing the header files (.h) provided for the two versions of the library and their dependencies.

Shared developers trying to strive for binary compatibility between releases may also use this tool to detect if an any accidental application binary interface (ABI) changes have been introduced.


GETTING STARTED

Two XML descriptors must be generated and passed to the tool. These configuration files inform abi-compliance-checker where to look for the actual data to compare.


OPTIONS

-help
Help message and examples (similar to this man page).
-d
Spit out example template files named lib_descriptor.v1 and lib_descriptor.v2 in the current directory. The two template files are identical and will both require customising. Any existing files of the same names will be overwritten without warning.
-l libraryname
Library name.
-d1 descriptor.xml
Path to descriptor of 1st library version (described in DATAFILES below).
-d2 descriptor.xml
Path to descriptor of 2nd library version.
-fast
Compiling of all headers together for speed. (Note that this is very fast, but any compiler errors shown for one header may affect files others).


DATAFILES

Library descriptor XML format:

<version>
    /* Library version */
</version>

<headers>

    /* The list of header paths or directories, one per line */
</headers>

<libs>

    /* The list of shared object paths or directories, one per line */
</libs>

<include_paths>

    /* The list of directories to be searched for header files needed for compiling of library headers, one per line */

    /* This section is not necessary */
</include_paths>

<gcc_options>

    /* Addition gcc options, one per line */

    /* This section is not necessary */
</gcc_options>

<opaque_types>

    /* The list of types that should be skipped while checking, one per line */

    /* This section is not necessary */
</opaque_types>

<internal_functions>

    /* The list of functions that should be skipped while checking, one mangled name per line */

    /* This section is not necessary */
</internal_functions>

<include_preamble>

    /* The list of headers that will be included before each analyzed header */

    /* For example, it is a tree.h for libxml2 and ft2build.h for freetype2 */

    /* This section is not necessary */

    /* This section is useless when -fast option selected */
</include_preamble>


EXAMPLES

Command lines:

abi-compliance-checker -l glib -d1 descriptor_glib_2.20.3 -d2 descriptor_glib_2.20.4
abi-compliance-checker -l gtk2 -d1 descriptor_gtk2_2.16.4 -d2 descriptor_gtk2_2.17.3

Library descriptor example:

<version>2.26.0</version>
<headers>

  /usr/local/librsvg/librsvg-2.26.0/include
</headers>
<libs>

  /usr/local/librsvg/librsvg-2.26.0/lib
</libs>
<include_paths>

    /usr/include/glib-2.0

    /usr/include/gtk-2.0

    /usr/include/atk-1.0

    /usr/include/cairo

    /usr/include/pango-1.0

    /usr/include/pixman-1

    /usr/include/freetype2

    /usr/include/libpng12
</include_paths>


BUGS

Upstream bug reports for abi-compliance-checker should be emailed to <abi.compliance.checker@gmail.com>.

AUTHOR

Andrey Ponomarenko <andrei.moscow@mail.ru> - Institute for System Programming, Russian Academy of Sciences and the The Linux Foundation. Distributed under the terms of the GNU General Public License version 3 or later.
This manual page was written for Debian/Ubuntu by Paul Sladen <debian@paul.sladen.org> and is hereby also distributed under the GPLv3 or later.


SEE ALSO

Website: http://ispras.linux-foundation.org/index.php/ABI_compliance_checker