Ubuntu Manpage: abi-compliance-checker - tool to compare ABI compatibility of shared C/C++ library

Provided by: abi-compliance-checker_2.3-2_all

NAME

       abi-compliance-checker  -  tool  to  compare  ABI  compatibility  of  shared C/C++ library
       versions

DESCRIPTION

NAME:
ABI Compliance Checker (abi-compliance-checker) Check backward compatibility of a
C/C++ library API

DESCRIPTION:
ABI Compliance Checker (ABICC) is a tool for checking backward binary compatibility
and backward source compatibility of a C/C++ library API.

The tool analyzes changes in API and ABI (ABI=API+compiler ABI) that may break
binary compatibility 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 can create and compare ABI dumps for header files and shared objects of a
library. The ABI dump for a library can also be created by the ABI Dumper tool
(https://github.com/lvc/abi-dumper) if shared objects include debug-info.

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.

Also the tool can be used by ISVs for checking applications portability to new
library versions. Found issues can be taken into account when adapting the
application to a new library version.

This tool is free software: you can redistribute it and/or modify it under the
terms of the GNU LGPL 2.1.

USAGE #1 (WITH ABI DUMPER):

1. Library should be compiled with "-g -Og" GCC options

to contain DWARF debug info

2. Create ABI dumps for both library versions

using the ABI Dumper (https://github.com/lvc/abi-dumper) tool:

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

3. You can filter public ABI with the help of

additional -public-headers option of the ABI Dumper tool.

4. Compare ABI dumps to create report:

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

USAGE #2 (ORIGINAL):

1. Create XML-descriptors for two versions

of a library (OLD.xml and NEW.xml):

1.0

</version>

/path/to/headers/

</headers>

<libs>

/path/to/libraries/

</libs>

2. Compare Xml-descriptors to create report:

abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml

USAGE #3 (CREATE ABI DUMPS):

1. Create XML-descriptors for two versions

of a library (OLD.xml and NEW.xml):

1.0

</version>

/path/to/headers/

</headers>

<libs>

/path/to/libraries/

</libs>

2. Create ABI dumps:

abi-compliance-checker -lib NAME -dump OLD.xml -dump-path ./ABI-0.dump
abi-compliance-checker -lib NAME -dump NEW.xml -dump-path ./ABI-1.dump

3. Compare ABI dumps to create report:

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

INFO OPTIONS:
-h|-help

Print this help.

-i|-info

Print complete info including all options.

-v|-version

Print version information.

-dumpversion

Print the tool version (2.3) and don't do anything else.

GENERAL OPTIONS:
-l|-library NAME

Any name of the library.

-old|-d1 PATH

Descriptor of the 1st (old) library version. It may be one of the following:

1. ABI dump generated by the ABI Dumper tool 2. XML-descriptor (*.xml file):

1.0

</version>

/path1/to/header(s)/ /path2/to/header(s)/

...

</headers>

<libs>

/path1/to/library(ies)/ /path2/to/library(ies)/

...

</libs>

...

3. ABI dump generated by -dump option 4. Directory with headers and libraries 5.
Single header file

If you are using 4-5 descriptor types then you should specify version numbers with
-v1 and -v2 options.

For more information, please see:

https://lvc.github.io/abi-compliance-checker/Xml-Descriptor.html

-new|-d2 PATH

Descriptor of the 2nd (new) library version.

-dump PATH

Create library ABI dump for the input XML descriptor. You can transfer it anywhere
and pass instead of the descriptor. Also it can be used for debugging the tool.

-filter PATH

A path to XML descriptor with skip_* rules to filter analyzed symbols in the
report.

EXTRA OPTIONS:
-debug

Debugging mode. Print debug info on the screen. Save intermediate analysis stages
in the debug directory:

debug/LIB_NAME/VERSION/

Also consider using -dump option for debugging the tool.

-ext|-extended

If your library A is supposed to be used by other library B and you want to control
the ABI of B, then you should enable this option. The tool will check for changes
in all data types, even if they are not used by any function in the library A. Such
data types are not part of the A library ABI, but may be a part of the ABI of the B
library.

The short scheme is:

app C (broken) -> lib B (broken ABI) -> lib A (stable ABI)

-static

Check static libraries instead of the shared ones. The <libs> section of the
XML-descriptor should point to static libraries location.

-gcc-path PATH

Path to the cross GCC compiler to use instead of the usual (host) GCC.

-gcc-prefix PREFIX

GCC toolchain prefix.

-gcc-options OPTS

Additional compiler options.

-count-symbols PATH

Count total public symbols in the ABI dump.

-use-dumps

Make dumps for two versions of a library and compare dumps. This should increase
the performance of the tool and decrease the system memory usage.

-xml

Alias for: --report-format=xml or --dump-format=xml

-app|-application PATH

This option allows one to specify the application that should be checked for
portability to the new library version.

-headers-only

Check header files without libraries. It is easy to run, but may provide a low
quality compatibility report with false positives and without detecting of
added/removed symbols.

-v1|-vnum1 NUM

Specify 1st library version outside the descriptor. This option is needed if you
have preferred an alternative descriptor type (see -d1 option).

In general case you should specify it in the XML-descriptor:

VERSION

</version>

-v2|-vnum2 NUM

Specify 2nd library version outside the descriptor.

-relpath1 PATH

Replace {RELPATH} macros to PATH in the 1st XML-descriptor (-d1).

-relpath2 PATH

Replace {RELPATH} macros to PATH in the 2nd XML-descriptor (-d2).

TEST OPTIONS:
-test

Run internal tests. Create two binary incompatible versions of a sample library and
run the tool to check them for compatibility. This option allows one to check if
the tool works correctly in the current environment.

-test-dump

Test ability to create, read and compare ABI dumps.

-test-abi-dumper

Compare ABI dumps created by the ABI Dumper tool.

REPORT OPTIONS:
-binary|-bin|-abi

Show binary compatibility problems only. Generate report to:

compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html

-source|-src|-api

Show source compatibility problems only. Generate report to:

compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html

-s|-strict

Treat all compatibility warnings as problems. Add a number of "Low" severity
problems to the return value of the tool.

REPORT PATH OPTIONS:
-report-path PATH

Path to compatibility report. Default:

compat_reports/LIB_NAME/V1_to_V2/compat_report.html

-bin-report-path PATH

Path to binary compatibility report. Default:

compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html

-src-report-path PATH

Path to source compatibility report. Default:

compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html

REPORT FORMAT OPTIONS:
-show-retval

Show the symbol's return type in the report.

-stdout

Print analysis results (compatibility reports and ABI dumps) to stdout instead of
creating a file. This would allow piping data to other programs.

-report-format FMT

Change format of compatibility report. Formats:

htm - HTML format (default) xml - XML format

-old-style

Generate old-style report.

-title NAME

Change library name in the report title to NAME. By default will be displayed a
name specified by -l option.

-component NAME

The component name in the title and summary of the HTML report. Default:

library

-p|-params PATH

Path to file with the function parameter names. It can be used for improving report
view if the library header files have no parameter names. File format:

func1;param1;param2;param3 ... func2;param1;param2;param3 ...

...

-limit-affected LIMIT

The maximum number of affected symbols listed under the description of the changed
type in the report.

-list-affected

Generate file with the list of incompatible symbols beside the HTML compatibility
report. Use 'c++filt @file' command from GNU binutils to unmangle C++ symbols in
the generated file. Default names:

abi_affected.txt src_affected.txt

ABI DUMP OPTIONS:
-dump-path PATH

Specify a *.dump file path where to generate an ABI dump. Default:

abi_dumps/LIB_NAME/VERSION/ABI.dump

-dump-format FMT

Change format of ABI dump. Formats:

perl - Data::Dumper format (default) xml - XML format

-check

Check completeness of the ABI dump.

-extra-info DIR

Dump extra info to DIR.

-extra-dump

Create extended ABI dump containing all symbols from the translation unit.

-relpath PATH

Replace {RELPATH} macros to PATH in the XML-descriptor used for dumping the library
ABI (see -dump option).

-vnum NUM

Specify the library version in the generated ABI dump. The <version> section of the
input XML descriptor will be overwritten in this case.

-sort

Enable sorting of data in ABI dumps.

FILTER SYMBOLS OPTIONS:
-symbols-list PATH

This option allows one to specify a file with a list of symbols (mangled names in
C++) that should be checked. Other symbols will not be checked.

-types-list PATH

This option allows one to specify a file with a list of types that should be
checked. Other types will not be checked.

-skip-symbols PATH

The list of symbols that should not be checked.

-skip-types PATH

The list of types that should not be checked.

-skip-internal-symbols PATTERN

Do not check symbols matched by the regular expression.

-skip-internal-types PATTERN

Do not check types matched by the regular expression. It's matched against full
qualified type names (e.g. 'struct xyz::Name<T>'). It has to match any part of
type name.

-keep-cxx

Check _ZS*, _ZNS* and _ZNKS* symbols.

-keep-reserved

Report changes in reserved fields.

FILTER HEADERS OPTIONS:
-skip-headers PATH

The file with the list of header files, that should not be checked.

-headers-list PATH

The file with a list of headers, that should be checked/dumped.

-header NAME

Check/Dump ABI of this header only.

-nostdinc

Do not search in GCC standard system directories for header files.

-tolerance LEVEL

Apply a set of heuristics to successfully compile input header files. You can
enable several tolerance levels by joining them into one string (e.g. 13, 124,
etc.). Levels:

1 - skip non-Linux headers (e.g. win32_*.h, etc.) 2 - skip internal headers (e.g.
*_p.h, impl/*.h, etc.) 3 - skip headers that include non-Linux headers 4 - skip
headers included by others

-tolerant

Enable highest tolerance level [1234].

-skip-unidentified

Skip header files in 'headers' and 'include_preamble' sections of the XML
descriptor that cannot be found. This is useful if you are trying to use the same
descriptor for different targets.

FILTER RULES OPTIONS:
-skip-typedef-uncover

Do not report a problem if type is covered or uncovered by typedef (useful for
broken debug info).

-check-private-abi

Check data types from the private part of the ABI when comparing ABI dumps created
by the ABI Dumper tool with use of the -public-headers option.

Requires ABI Dumper >= 0.99.14

-disable-constants-check

Do not check for changes in constants.

-skip-added-constants

Do not detect added constants.

-skip-removed-constants

Do not detect removed constants.

OTHER OPTIONS:
-lang LANG

Set library language (C or C++). You can use this option if the tool cannot
auto-detect a language. This option may be useful for checking C-library headers
(--lang=C) in --headers-only or --extended modes.

-arch ARCH

Set library architecture (x86, x86_64, ia64, arm, ppc32, ppc64, s390, ect.). The
option is useful if the tool cannot detect correct architecture of the input
objects.

-mingw-compatible

If input header files are compatible with the MinGW GCC compiler, then you can tell
the tool about this and speedup the analysis.

-cxx-incompatible

Set this option if input C header files use C++ keywords. The tool will try to
replace such keywords at preprocessor stage and replace them back in the final TU
dump.

-cpp-compatible

Do nothing.

-quick

Quick analysis. Disable check of some template instances.

-force

Try to enable this option if the tool checked not all types and symbols in header
files.

OS ANALYSIS OPTIONS:
-dump-system NAME -sysroot DIR

Find all the shared libraries and header files in DIR directory, create XML
descriptors and make ABI dumps for each library. The result set of ABI dumps can be
compared (--cmp-systems) with the other one created for other version of operating
system in order to check them for compatibility. Do not forget to specify
-cross-gcc option if your target system requires some specific version of GCC
compiler (different from the host GCC). The system ABI dump will be generated to:

sys_dumps/NAME/ARCH

-dump-system DESCRIPTOR.xml

The same as the previous option but takes an XML descriptor of the target system as
input, where you should describe it:

/* Primary sections */

<name>

/* Name of the system */

</name>

/* The list of paths to header files and/or

directories with header files, one per line */

</headers>

<libs>

/* The list of paths to shared libraries and/or

directories with shared libraries, one per line */

</libs>

/* Optional sections */

<search_headers>

/* List of directories to be searched

for header files to automatically generate include paths, one per line */

</search_headers>

<search_libs>

/* List of directories to be searched

for shared libraries to resolve dependencies, one per line */

</search_libs>

<tools>

/* List of directories with tools used

for analysis (GCC toolchain), one per line */

</tools>

<cross_prefix>

/* GCC toolchain prefix.

Examples:
arm-linux-gnueabi arm-none-symbianelf */

</cross_prefix>

<gcc_options>

/* Additional GCC options, one per line */

</gcc_options>

-cmp-systems -d1 sys_dumps/NAME1/ARCH -d2 sys_dumps/NAME2/ARCH

Compare two ABI dumps of a system. Create compatibility reports for each system
library and the common HTML report including the summary of test results for all
checked libraries.

Summary report will be generated to:

sys_compat_reports/NAME1_to_NAME2/ARCH

-sysroot DIR

Specify the alternative root directory. The tool will search for include paths in
the DIR/usr/include and DIR/usr/lib directories.

-sysinfo DIR

This option should be used with -dump-system option to dump ABI of operating
systems and configure the dumping process.

-libs-list PATH

The file with a list of libraries, that should be dumped by the -dump-system option
or should be checked by the -cmp-systems option.

LOGGING OPTIONS:
-log-path PATH

Log path for all messages. Default:

logs/LIB_NAME/VERSION/log.txt

-log1-path PATH

Log path for 1st version of a library. Default:

logs/LIB_NAME/V1/log.txt

-log2-path PATH

Log path for 2nd version of a library. Default:

logs/LIB_NAME/V2/log.txt

-logging-mode MODE

Change logging mode. Modes:

w - overwrite old logs (default) a - append old logs n - do not write any logs

-q|-quiet

Print all messages to the file instead of stdout and stderr. Default path (can be
changed by -log-path option):

logs/run.log

REPORT PATH:
Compatibility report will be generated to:

compat_reports/LIB_NAME/V1_to_V2/compat_report.html

LOG PATH:
Log will be generated to:

logs/LIB_NAME/V1/log.txt logs/LIB_NAME/V2/log.txt

EXIT CODES:
0 - Compatible. The tool has run without any errors. non-zero - Incompatible or
the tool has run with errors.

MORE INFO:
https://lvc.github.io/abi-compliance-checker/
https://github.com/lvc/abi-compliance-checker

AUTHOR

       This manual page was written  by  Mathieu  Malaterre  <malat@debian.org>  for  the  Debian
       GNU/Linux system (but may be used by others).

       Written by Andrey Ponomarenko.

COPYRIGHT

       Copyright   ©   2018   Andrey   Ponomarenko's   ABI   Laboratory  License:  GNU  LGPL  2.1
       <http://www.gnu.org/licenses/> This program is free  software:  you  can  redistribute  it
       and/or modify it.