ABI-COMPLIANCE-CHECKER(1) User Commands ABI-COMPLIANCE-CHECKER(1)
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 (ACC) 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.
The tool is intended for developers of software libraries and maintainers of operating systems who are interested in ensuring back-
ward 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 or GNU GPL.
USAGE:
abi-compliance-checker [options]
EXAMPLE:
abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml
OLD.xml and NEW.xml are XML-descriptors:
<version>
1.0
</version>
<headers>
/path1/to/header(s)/ /path2/to/header(s)/
...
</headers>
<libs>
/path1/to/library(ies)/ /path2/to/library(ies)/
...
</libs>
INFORMATION OPTIONS:
-h|-help
Print this help.
-i|-info
Print complete info.
-v|-version
Print version information.
-dumpversion
Print the tool version (1.97.7) and don't do anything else.
GENERAL OPTIONS:
-l|-lib|-library <name>
Library name (without version). It affects only on the path and the title of the report.
-d1|-old|-o <path>
Descriptor of 1st (old) library version. It may be one of the following:
1. XML-descriptor (VERSION.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>
... (XML-descriptor template
can be generated by -d option)
2. ABI dump generated by -dump option 3. Directory with headers and/or shared libraries 4. Single header file 5. Single shared
library 6. Comma separated list of headers and/or libraries
If you are using an 2-6 descriptor types then you should specify version numbers with -v1 <num> and -v2 <num> options too.
For more information, please see:
http://ispras.linuxbase.org/index.php/Library_Descriptor
-d2|-new|-n <path>
Descriptor of 2nd (new) library version.
-dump|-dump-abi <descriptor path(s)>
Dump library ABI to gzipped TXT format file. You can transfer it anywhere and pass instead of the descriptor. Also it can be used
for debugging the tool. Compatible dump versions: 2.0<=V<=2.16
-old-dumps
Enable support for old-version ABI dumps (1.18<=V<2.0).
EXTRA OPTIONS:
-d|-descriptor-template
Create XML-descriptor template ./VERSION.xml
-app|-application <path>
This option allows to specify the application that should be checked for portability to the new library version.
-static-libs
Check static libraries instead of the shared ones. The <libs> section of the XML-descriptor should point to static libraries loca-
tion.
-cross-gcc|-gcc-path <path>
Path to the cross GCC compiler to use instead of the usual (host) GCC.
-cross-prefix|-gcc-prefix <prefix>
GCC toolchain prefix.
-sysroot <dirpath>
Specify the alternative root directory. The tool will search for include paths in the <dirpath>/usr/include and <dirpath>/usr/lib
directories.
-v1|-version1 <num>
Specify 1st library version outside the descriptor. This option is needed if you have prefered an alternative descriptor type (see
-d1 option).
In general case you should specify it in the XML-descriptor:
<version>
VERSION
</version>
-v2|-version2 <num>
Specify 2nd library version outside the descriptor.
-s|-strict
Treat all compatibility warnings as problems. Add a number of "Low" severity problems to the return value of the tool.
-headers-only
Check header files without shared libraries. It is easy to run, but may provide a low quality compatibility report with false posi-
tives and without detecting of added/removed symbols.
Alternatively you can write "none" word to the <libs> section in the XML-descriptor:
<libs>
none
</libs>
-objects-only
Check shared libraries without header files. It is easy to run, but may provide a low quality compatibility report with false posi-
tives and without analysis of changes in parameters and data types.
Alternatively you can write "none" word to the <headers> section in the XML-descriptor:
<headers>
none
</headers>
-check-impl|-check-implementation
Compare canonified disassembled binary code of shared libraries to detect changes in the implementation. Add 'Problems with Imple-
mentation' section to the report.
-show-retval
Show the symbol's return type in the report.
-symbols-list <path>
This option allows to specify a file with a list of symbols (mangled names in C++) that should be checked, other symbols will not be
checked.
-skip-headers <path>
The file with the list of header files, that should not be checked.
-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.
-nostdinc
Do not search the GCC standard system directories for header files.
-dump-system <name> -sysroot <dirpath>
Find all the shared libraries and header files in <dirpath> 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 ver-
sion 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>
-sysinfo <dir>
This option may be used with -dump-system to dump ABI of operating systems and configure the dumping process. Default:
modules/Targets/{unix, symbian, windows}
-cmp-systems -d1 sys_dumps/<name1>/<arch> -d2 sys_dumps/<name2>/<arch>
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:
sys_compat_reports/<name1>_to_<name2>/<arch>
-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.
-header <name>
Check/Dump ABI of this header only.
-headers-list <path>
The file with a list of headers, that should be checked/dumped.
-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)
-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
-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
-xml
Alias for: --report-format=xml
-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.
-binary|-bin|-abi
Show "Binary" compatibility problems only. Generate report to:
compat_reports/<library name>/<v1>_to_<v2>/abi_compat_report.html
-source|-src|-api
Show "Source" compatibility problems only. Generate report to:
compat_reports/<library name>/<v1>_to_<v2>/src_compat_report.html
OTHER 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 to check if the tool works correctly in the current environment.
-test-dump
Test ability to create, read and compare ABI dumps.
-debug
Debugging mode. Print debug info on the screen. Save intermediate analysis stages in the debug directory:
debug/<library>/<version>/
Also consider using --dump option for debugging the tool.
-cpp-compatible
If your header file is written in C language and can be compiled by the C++ compiler (i.e. doesn't contain C++-keywords and other
bad things), then you can tell ACC about this and speedup the analysis.
-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 parame-
ter names. File format:
func1;param1;param2;param3 ... func2;param1;param2;param3 ...
...
-relpath <path>
Replace {RELPATH} macros to <path> in the XML-descriptor used for dumping the library ABI (see -dump option).
-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).
-dump-path <path>
Specify a file path (*.abi.tar.gz) where to generate an ABI dump. Default:
abi_dumps/<library>/<library>_<version>.abi.tar.gz
-sort
Enable sorting of data in ABI dumps.
-report-path <path>
Path to compatibility report. Default:
compat_reports/<library name>/<v1>_to_<v2>/compat_report.html
-bin-report-path <path>
Path to "Binary" compatibility report. Default:
compat_reports/<library name>/<v1>_to_<v2>/abi_compat_report.html
-src-report-path <path>
Path to "Source" compatibility report. Default:
compat_reports/<library name>/<v1>_to_<v2>/src_compat_report.html
-log-path <path>
Log path for all messages. Default:
logs/<library>/<version>/log.txt
-log1-path <path>
Log path for 1st version of a library. Default:
logs/<library name>/<v1>/log.txt
-log2-path <path>
Log path for 2nd version of a library. Default:
logs/<library 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
-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
-component <name>
The component name in the title and summary of the HTML report. Default:
library
-l-full|-lib-full <name>
Change library name in the report title to <name>. By default will be displayed a name specified by -l option.
-b|-browse <program>
Open report(s) in the browser (firefox, opera, etc.).
-open
Open report(s) in the default browser.
REPORT:
Compatibility report will be generated to:
compat_reports/<library name>/<v1>_to_<v2>/compat_report.html
Log will be generated to:
logs/<library name>/<v1>/log.txt logs/<library 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.
REPORT BUGS TO:
Andrey Ponomarenko <aponomarenko@rosalab.ru>
MORE INFORMATION:
http://ispras.linuxbase.org/index.php/ABI_compliance_checker https://github.com/lvc/abi-compliance-checker
AUTHOR
Written by Andrey Ponomarenko.
COPYRIGHT
Copyright (C) 2012 ROSA Laboratory License: LGPL or GPL <http://www.gnu.org/licenses/> This program is free software: you can redistribute
it and/or modify it.
abi-compliance-checker Compliance Checker (ACC) 1.97.7 May 2012 ABI-COMPLIANCE-CHECKER(1)