.\" DO NOT MODIFY THIS FILE!  It was generated by help2man 1.47.4.
.TH ABI-COMPLIANCE-CHECKER "1" "July 2016" "abi-compliance-checker Compliance Checker (ABICC) 1.99.22" "User Commands"
.SH NAME
abi-compliance-checker \- tool to compare ABI compatibility of shared C/C++ library versions
.SH DESCRIPTION
.SS "NAME:"
.IP
ABI Compliance Checker (abi\-compliance\-checker)
Check backward compatibility of a C/C++ library API
.SS "DESCRIPTION:"
.IP
ABI Compliance Checker (ABICC) is a tool for checking backward binary and
source\-level compatibility of a shared C/C++ library. The tool checks
header files and shared libraries (*.so) of old and new versions and
analyzes changes in API and ABI (ABI=API+compiler ABI) that may break binary
and/or source\-level 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.
.IP
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.
.IP
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.
.IP
This tool is free software: you can redistribute it and/or modify it
under the terms of the GNU LGPL or GNU GPL.
.SS "USAGE:"
.IP
abi\-compliance\-checker [options]
.SS "EXAMPLE:"
.IP
abi\-compliance\-checker \fB\-lib\fR NAME \fB\-old\fR OLD.xml \fB\-new\fR NEW.xml
.IP
OLD.xml and NEW.xml are XML\-descriptors:
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<headers>
.IP
/path1/to/header(s)/
/path2/to/header(s)/
.IP
\&...
.IP
</headers>
.IP
<libs>
.IP
/path1/to/library(ies)/
/path2/to/library(ies)/
.IP
\&...
.IP
</libs>
.SS "INFORMATION OPTIONS:"
.HP
\fB\-h\fR|\-help
.IP
Print this help.
.HP
\fB\-i\fR|\-info
.IP
Print complete info.
.HP
\fB\-v\fR|\-version
.IP
Print version information.
.HP
\fB\-dumpversion\fR
.IP
Print the tool version (1.99.22) and don't do anything else.
.SS "GENERAL OPTIONS:"
.HP
\fB\-l\fR|\-lib|\-library NAME
.IP
Library name (without version).
.HP
\fB\-d1\fR|\-old|\-o PATH
.IP
Descriptor of 1st (old) library version.
It may be one of the following:
.IP
1. XML\-descriptor (VERSION.xml file):
.IP
<version>
.IP
1.0
.IP
</version>
.IP
<headers>
.IP
/path1/to/header(s)/
/path2/to/header(s)/
.IP
\&...
.IP
</headers>
.IP
<libs>
.IP
/path1/to/library(ies)/
/path2/to/library(ies)/
.IP
\&...
.IP
</libs>
.IP
\&...
.IP
2. ABI dump generated by \fB\-dump\fR option
3. Directory with headers and/or shared libraries
4. Single header file
.IP
If you are using an 2\-4 descriptor types then you should
specify version numbers with \fB\-v1\fR and \fB\-v2\fR options too.
.IP
For more information, please see:
.IP
http://ispras.linuxbase.org/index.php/Library_Descriptor
.HP
\fB\-d2\fR|\-new|\-n PATH
.IP
Descriptor of 2nd (new) library version.
.HP
\fB\-dump\fR|\-dump\-abi PATH
.IP
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.
.IP
Supported versions of ABI dump: 2.0<=V<=3.2
.SS "EXTRA OPTIONS:"
.HP
\fB\-app\fR|\-application PATH
.IP
This option allows one to specify the application that should be checked
for portability to the new library version.
.HP
\fB\-static\-libs\fR
.IP
Check static libraries instead of the shared ones. The <libs> section
of the XML\-descriptor should point to static libraries location.
.HP
\fB\-gcc\-path\fR PATH
.IP
Path to the cross GCC compiler to use instead of the usual (host) GCC.
.HP
\fB\-gcc\-prefix\fR PREFIX
.IP
GCC toolchain prefix.
.HP
\fB\-gcc\-options\fR OPTS
.IP
Additional compiler options.
.HP
\fB\-sysroot\fR DIR
.IP
Specify the alternative root directory. The tool will search for include
paths in the DIR/usr/include and DIR/usr/lib directories.
.HP
\fB\-v1\fR|\-version1 NUM
.IP
Specify 1st library version outside the descriptor. This option is needed
if you have preferred an alternative descriptor type (see \fB\-d1\fR option).
.IP
In general case you should specify it in the XML\-descriptor:
.IP
<version>
.IP
VERSION
.IP
</version>
.HP
\fB\-v2\fR|\-version2 NUM
.IP
Specify 2nd library version outside the descriptor.
.HP
\fB\-vnum\fR NUM
.IP
Specify the library version in the generated ABI dump. The <version> section
of the input XML descriptor will be overwritten in this case.
.HP
\fB\-s\fR|\-strict
.IP
Treat all compatibility warnings as problems. Add a number of "Low"
severity problems to the return value of the tool.
.HP
\fB\-headers\-only\fR
.IP
Check header files without shared libraries. It is easy to run, but may
provide a low quality compatibility report with false positives and
without detecting of added/removed symbols.
.IP
Alternatively you can write "none" word to the <libs> section
in the XML\-descriptor:
.IP
<libs>
.IP
none
.IP
</libs>
.HP
\fB\-show\-retval\fR
.IP
Show the symbol's return type in the report.
.HP
\fB\-symbols\-list\fR PATH
.IP
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.
.HP
\fB\-types\-list\fR PATH
.IP
This option allows one to specify a file with a list of types that should
be checked. Other types will not be checked.
.HP
\fB\-skip\-symbols\fR PATH
.IP
The list of symbols that should not be checked.
.HP
\fB\-skip\-types\fR PATH
.IP
The list of types that should not be checked.
.HP
\fB\-headers\-list\fR PATH
.IP
The file with a list of headers, that should be checked/dumped.
.HP
\fB\-skip\-headers\fR PATH
.IP
The file with the list of header files, that should not be checked.
.HP
\fB\-header\fR NAME
.IP
Check/Dump ABI of this header only.
.HP
\fB\-use\-dumps\fR
.IP
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.
.HP
\fB\-nostdinc\fR
.IP
Do not search in GCC standard system directories for header files.
.HP
\fB\-dump\-system\fR NAME \fB\-sysroot\fR DIR
.IP
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 (\fB\-\-cmp\-systems\fR) with the other one
created for other version of operating system in order to check them for
compatibility. Do not forget to specify \fB\-cross\-gcc\fR 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:
.IP
sys_dumps/NAME/ARCH
.HP
\fB\-dump\-system\fR DESCRIPTOR.xml
.IP
The same as the previous option but takes an XML descriptor of the target
system as input, where you should describe it:
.IP
/* Primary sections */
.IP
<name>
.IP
/* Name of the system */
.IP
</name>
.IP
<headers>
.IP
/* The list of paths to header files and/or
.IP
directories with header files, one per line */
.IP
</headers>
.IP
<libs>
.IP
/* The list of paths to shared libraries and/or
.IP
directories with shared libraries, one per line */
.IP
</libs>
.IP
/* Optional sections */
.IP
<search_headers>
.IP
/* List of directories to be searched
.IP
for header files to automatically
generate include paths, one per line */
.IP
</search_headers>
.IP
<search_libs>
.IP
/* List of directories to be searched
.IP
for shared libraries to resolve
dependencies, one per line */
.IP
</search_libs>
.IP
<tools>
.IP
/* List of directories with tools used
.IP
for analysis (GCC toolchain), one per line */
.IP
</tools>
.IP
<cross_prefix>
.IP
/* GCC toolchain prefix.
.TP
Examples:
arm\-linux\-gnueabi
arm\-none\-symbianelf */
.IP
</cross_prefix>
.IP
<gcc_options>
.IP
/* Additional GCC options, one per line */
.IP
</gcc_options>
.HP
\fB\-sysinfo\fR DIR
.IP
This option should be used with \fB\-dump\-system\fR option to dump
ABI of operating systems and configure the dumping process.
.HP
\fB\-cmp\-systems\fR \fB\-d1\fR sys_dumps/NAME1/ARCH \fB\-d2\fR sys_dumps/NAME2/ARCH
.IP
Compare two system ABI dumps. Create compatibility reports for each
library and the common HTML report including the summary of test
results for all checked libraries. Report will be generated to:
.IP
sys_compat_reports/NAME1_to_NAME2/ARCH
.HP
\fB\-libs\-list\fR PATH
.IP
The file with a list of libraries, that should be dumped by
the \fB\-dump\-system\fR option or should be checked by the \fB\-cmp\-systems\fR option.
.HP
\fB\-ext\fR|\-extended
.IP
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.
.IP
The short scheme is:
.IP
app C (broken) \-> lib B (broken ABI) \-> lib A (stable ABI)
.HP
\fB\-q\fR|\-quiet
.IP
Print all messages to the file instead of stdout and stderr.
Default path (can be changed by \fB\-log\-path\fR option):
.IP
logs/run.log
.HP
\fB\-stdout\fR
.IP
Print analysis results (compatibility reports and ABI dumps) to stdout
instead of creating a file. This would allow piping data to other programs.
.HP
\fB\-report\-format\fR FMT
.IP
Change format of compatibility report.
Formats:
.IP
htm \- HTML format (default)
xml \- XML format
.HP
\fB\-dump\-format\fR FMT
.IP
Change format of ABI dump.
Formats:
.IP
perl \- Data::Dumper format (default)
xml \- XML format
.HP
\fB\-xml\fR
.IP
Alias for: \fB\-\-report\-format\fR=\fI\,xml\/\fR or \fB\-\-dump\-format\fR=\fI\,xml\/\fR
.HP
\fB\-lang\fR LANG
.IP
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 (\fB\-\-lang\fR=\fI\,C\/\fR) in \fB\-\-headers\-only\fR or \fB\-\-extended\fR modes.
.HP
\fB\-arch\fR ARCH
.IP
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.
.HP
\fB\-binary\fR|\-bin|\-abi
.IP
Show "Binary" compatibility problems only.
Generate report to:
.IP
compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html
.HP
\fB\-source\fR|\-src|\-api
.IP
Show "Source" compatibility problems only.
Generate report to:
.IP
compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html
.HP
\fB\-limit\-affected\fR LIMIT
.IP
The maximum number of affected symbols listed under the description
of the changed type in the report.
.HP
\fB\-count\-symbols\fR PATH
.IP
Count total public symbols in the ABI dump.
.HP
\fB\-old\-style\fR
.IP
Generate old\-style report.
.SS "OTHER OPTIONS:"
.HP
\fB\-test\fR
.IP
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.
.HP
\fB\-test\-dump\fR
.IP
Test ability to create, read and compare ABI dumps.
.HP
\fB\-debug\fR
.IP
Debugging mode. Print debug info on the screen. Save intermediate
analysis stages in the debug directory:
.IP
debug/LIB_NAME/VERSION/
.IP
Also consider using \fB\-\-dump\fR option for debugging the tool.
.HP
\fB\-cpp\-compatible\fR
.IP
If your header files are written in C language and can be compiled
by the G++ compiler (i.e. don't use C++ keywords), then you can tell
the tool about this and speedup the analysis.
.HP
\fB\-cpp\-incompatible\fR
.IP
Set this option if input C header files use C++ keywords.
.HP
\fB\-p\fR|\-params PATH
.IP
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:
.IP
func1;param1;param2;param3 ...
func2;param1;param2;param3 ...
.IP
\&...
.HP
\fB\-relpath\fR PATH
.IP
Replace {RELPATH} macros to PATH in the XML\-descriptor used
for dumping the library ABI (see \fB\-dump\fR option).
.HP
\fB\-relpath1\fR PATH
.IP
Replace {RELPATH} macros to PATH in the 1st XML\-descriptor (\fB\-d1\fR).
.HP
\fB\-relpath2\fR PATH
.IP
Replace {RELPATH} macros to PATH in the 2nd XML\-descriptor (\fB\-d2\fR).
.HP
\fB\-dump\-path\fR PATH
.IP
Specify a *.abi.tar.gz or *.abi file path where to generate an ABI dump.
Default:
.IP
abi_dumps/LIB_NAME/LIB_NAME_VERSION.abi.tar.gz
.HP
\fB\-sort\fR
.IP
Enable sorting of data in ABI dumps.
.HP
\fB\-report\-path\fR PATH
.IP
Path to compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/compat_report.html
.HP
\fB\-bin\-report\-path\fR PATH
.IP
Path to "Binary" compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html
.HP
\fB\-src\-report\-path\fR PATH
.IP
Path to "Source" compatibility report.
Default:
.IP
compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html
.HP
\fB\-log\-path\fR PATH
.IP
Log path for all messages.
Default:
.IP
logs/LIB_NAME/VERSION/log.txt
.HP
\fB\-log1\-path\fR PATH
.IP
Log path for 1st version of a library.
Default:
.IP
logs/LIB_NAME/V1/log.txt
.HP
\fB\-log2\-path\fR PATH
.IP
Log path for 2nd version of a library.
Default:
.IP
logs/LIB_NAME/V2/log.txt
.HP
\fB\-logging\-mode\fR MODE
.IP
Change logging mode.
Modes:
.IP
w \- overwrite old logs (default)
a \- append old logs
n \- do not write any logs
.HP
\fB\-list\-affected\fR
.IP
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:
.IP
abi_affected.txt
src_affected.txt
.HP
\fB\-component\fR NAME
.IP
The component name in the title and summary of the HTML report.
Default:
.IP
library
.HP
\fB\-title\fR NAME
.IP
Change library name in the report title to NAME. By default
will be displayed a name specified by \fB\-l\fR option.
.HP
\fB\-extra\-info\fR DIR
.IP
Dump extra info to DIR.
.HP
\fB\-extra\-dump\fR
.IP
Create extended ABI dump containing all symbols
from the translation unit.
.HP
\fB\-force\fR
.IP
Try to use this option if the tool doesn't work.
.HP
\fB\-tolerance\fR LEVEL
.IP
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:
.IP
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
.HP
\fB\-tolerant\fR
.IP
Enable highest tolerance level [1234].
.HP
\fB\-check\fR
.IP
Check completeness of the ABI dump.
.HP
\fB\-quick\fR
.IP
Quick analysis. Disable check of some template instances.
.HP
\fB\-skip\-internal\-symbols\fR PATTERN
.IP
Do not check symbols matched by the pattern.
.HP
\fB\-skip\-internal\-types\fR PATTERN
.IP
Do not check types matched by the pattern.
.HP
\fB\-check\-private\-abi\fR
.IP
Check data types from the private part of the ABI when
comparing ABI dumps created by the ABI Dumper tool with
use of the \fB\-public\-headers\fR option.
.IP
Requires ABI Dumper >= 0.99.14
.SS "REPORT:"
.IP
Compatibility report will be generated to:
.IP
compat_reports/LIB_NAME/V1_to_V2/compat_report.html
.IP
Log will be generated to:
.IP
logs/LIB_NAME/V1/log.txt
logs/LIB_NAME/V2/log.txt
.SS "EXIT CODES:"
.IP
0 \- Compatible. The tool has run without any errors.
non\-zero \- Incompatible or the tool has run with errors.
.SS "MORE INFORMATION:"
.IP
http://lvc.github.io/abi\-compliance\-checker/
.SH AUTHOR
This manual page was written by Mathieu Malaterre <malat@debian.org> for the
Debian GNU/Linux system (but may be used by others).
.PP
Written by Andrey Ponomarenko.
.SH COPYRIGHT
Copyright \(co 2015 Andrey Ponomarenko's ABI Laboratory
License: LGPL or GPL <http://www.gnu.org/licenses/>
This program is free software: you can redistribute it and/or modify it.