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