abi-compliance-checker - tool to compare ABI compatibility of
shared C/C++ library versions
- ABI Compliance Checker (abi-compliance-checker) Check backward
compatibility of a C/C++ library API
- 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):
- <version>
- 1.0
- </version>
- <headers>
- /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):
- <version>
- 1.0
- </version>
- <headers>
- /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
-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.
-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):
- <version>
- 1.0
- </version>
- <headers>
- /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.
-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
- </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
- 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.
-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 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
-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
-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.
-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.
-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.
-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.
-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.
-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>
- <headers>
- /* 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.
-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
- Compatibility report will be generated to:
- compat_reports/LIB_NAME/V1_to_V2/compat_report.html
- Log will be generated to:
- logs/LIB_NAME/V1/log.txt logs/LIB_NAME/V2/log.txt
- 0 - Compatible. The tool has run without any errors. non-zero -
Incompatible or the tool has run with errors.
- https://lvc.github.io/abi-compliance-checker/
https://github.com/lvc/abi-compliance-checker
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 © 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.