SIMPLE SOLUTIONS

ABI-COMPLIANCE-CHECKER - reference manual online

Tool to compare ABI compatibility of shared C/C++ library versions.

Chapter
November 2015
ABI-COMPLIANCE-CHECKER(1)                 User Commands                 ABI-COMPLIANCE-CHECKER(1)

NAME abi-compliance-checker - tool to compare ABI compatibility of shared C/C++ library ver‐ sions
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 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 incompati‐ bility may result in recompilation errors with a new library version. The tool is intended for developers of software libraries and maintainers of oper‐ ating 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 applica‐ tion 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.99.14) and don't do anything else. GENERAL OPTIONS: -l|-lib|-library NAME Library name (without version). -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> ... 2. ABI dump generated by -dump option 3. Directory with headers and/or shared libraries 4. Single header file If you are using an 2-4 descriptor types then you should specify version numbers with -v1 and -v2 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 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. Supported versions of ABI dump: 2.0<=V<=3.2 EXTRA OPTIONS: -app|-application PATH This option allows one to specify the application that should be checked for porta‐ bility 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 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. -sysroot DIR Specify the alternative root directory. The tool will search for include paths in the DIR/usr/include and DIR/usr/lib directories. -v1|-version1 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|-version2 NUM Specify 2nd library version outside the descriptor. -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. -s|-strict Treat all compatibility warnings as problems. Add a number of "Low" severity prob‐ lems 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 positives and without detecting of added/removed symbols. Alternatively you can write "none" word to the <libs> section in the XML-descrip‐ tor: <libs> none </libs> -show-retval Show the symbol's return type in the report. -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. -headers-list PATH The file with a list of headers, that should be checked/dumped. -skip-headers PATH The file with the list of header files, that should not be checked. -header NAME Check/Dump ABI of this header only. -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 in GCC standard system directories for 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 com‐ piler (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 should be used with -dump-system option to dump ABI of operating sys‐ tems and configure the dumping process. You can find a sample in the package: 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. -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 -dump-format FMT Change format of ABI dump. Formats: perl - Data::Dumper format (default) xml - XML format -xml Alias for: --report-format=xml or --dump-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. -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. -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 -limit-affected LIMIT The maximum number of affected symbols listed under the description of the changed type in the report. 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 one 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/LIB_NAME/VERSION/ Also consider using --dump option for debugging the tool. -cpp-compatible If your header files are written in C language and can be compiled by the G++ com‐ piler (i.e. don't use C++ keywords), then you can tell the tool about this and speedup the analysis. -cpp-incompatible Set this option if input C header files use C++ keywords. -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 ... ... -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 *.abi.tar.gz or *.abi file path where to generate an ABI dump. Default: abi_dumps/LIB_NAME/LIB_NAME_VERSION.abi.tar.gz -sort Enable sorting of data in ABI dumps. -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 -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 -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 -title NAME Change library name in the report title to NAME. By default will be displayed a name specified by -l option. -extra-info DIR Dump extra info to DIR. -extra-dump Create extended ABI dump containing all symbols from the translation unit. -force Try to use this option if the tool doesn't work. -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 iclude non-Linux headers 4 - skip headers included by others -tolerant Enable highest tolerance level [1234]. -check Check completeness of the ABI dump. -quick Quick analysis. Disable check of some template instances. -skip-internal-symbols PATTERN Do not check symbols matched by the pattern. -skip-internal-types PATTERN Do not check types matched by the pattern. REPORT: 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 EXIT CODES: 0 - Compatible. The tool has run without any errors. non-zero - Incompatible or the tool has run with errors. MORE INFORMATION: http://lvc.github.io/abi-compliance-checker/
AUTHOR This manual page was written by Mathieu Malaterre <@debian.org> for the Debian GNU/Linux system (but may be used by others). Written by Andrey Ponomarenko.
abi-compliance-checker Compliance Checker November1201514 ABI-COMPLIANCE-CHECKER(1)