ABI-COMPLIANCE-CHECKER(1)

📦
version 2.3 · 5 versions
, in debian bookworm, ubuntu noble

okay bestie, welcome to the abi-compliance-checker(1) manual page (User Commands) 💖 let's get into it 🫶

✨ NAME ✨

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

✨ DESCRIPTION ✨

✨ NAME: ✨

ABI Compliance Checker (abi-compliance-checker) is all about checking backward compatibility of a C/C++ library API 💅

✨ DESCRIPTION: ✨

okay so ABI Compliance Checker (ABICC) is a tool for checking backward binary compatibility and backward source compatibility of a C/C++ library API ✨

It analyzes changes in API and ABI (ABI=API+compiler ABI) that could break binary compatibility and/or source compatibility. We're talking changes in calling stack, v-table changes, removed symbols, renamed fields, etc. 👀

Binary incompatibility can make applications built with an old version of a library crash or behave incorrectly if they run on a new one 💀 Source incompatibility can cause 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 🌸

This tool is for developers of software libraries and maintainers of operating systems who care about backward compatibility, meaning old applications can still run or be recompiled with newer library versions 🧚

The tool can also be used by ISVs to check application 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. Compile the library with "-g -Og" GCC options so it contains 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
  1. You can filter the public ABI with the help of the additional -public-headers option of the ABI Dumper tool 🦋
  2. Compare the ABI dumps to create a 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) that look like this:
<version>
1.0
</version>
<headers>
/path/to/headers/
</headers>
<libs>
/path/to/libraries/
</libs>
  1. Compare the XML-descriptors to create a 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) using the same format as above:
<version>
1.0
</version>
<headers>
/path/to/headers/
</headers>
<libs>
/path/to/libraries/
</libs>
  1. Create the 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
  1. Compare the ABI dumps to create a report:
abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump

✨ INFO OPTIONS ✨

  • -h|-help — Print this help, bestie 🙈
  • -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 — The descriptor of the 1st (old) library version. It can be one of the following types ✨
  1. ABI dump generated by the ABI Dumper tool
  2. XML-descriptor (*.xml file), which looks like this:
<version>
1.0
</version>
<headers>
/path1/to/header(s)/ /path2/to/header(s)/
...
</headers>
<libs>
/path1/to/library(ies)/ /path2/to/library(ies)/
...
</libs>
...
  1. ABI dump generated by the -dump option
  2. Directory with headers and libraries
  3. Single header file

If you're using descriptor types 4-5, 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 — The descriptor of the 2nd (new) library version 💅
  • -dump PATH — Create a library ABI dump for the input XML descriptor. You can transfer it anywhere and pass it instead of the descriptor. It can also be used for debugging the tool 🫶
  • -filter PATH — A path to an XML descriptor with skip_* rules to filter analyzed symbols in the report 🎀

✨ EXTRA OPTIONS ✨

  • -debug — Debugging mode, periodt 🔥 Prints debug info on the screen and saves intermediate analysis stages in the debug directory: debug/LIB_NAME/VERSION/ Also consider using the -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 enable this option 👑 The tool will check for changes in all data types, even if they aren't used by any function in library A. Those data types aren't part of the A library ABI, but they may be 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 shared ones. The <libs> section of the XML-descriptor should point to the 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 the total public symbols in the ABI dump 🍓
  • -use-dumps — Make dumps for two versions of a library and compare the dumps. This should boost the tool's performance and decrease system memory usage ⭐
  • -xml — Alias for: --report-format=xml or --dump-format=xml 💜
  • -app|-application PATH — Specify the application that should be checked for portability to the new library version 💅
  • -headers-only — Check header files without libraries. It's easy to run, but it may provide a low quality compatibility report with false positives and without detecting added/removed symbols 😭
Heads up: the -headers-only report can be low quality, with false positives, and it won't detect added or removed symbols. Use it knowing that 🙈
  • -v1|-vnum1 NUM — Specify the 1st library version outside the descriptor. You need this if you've preferred an alternative descriptor type (see -d1 option). In the general case, you should specify it in the XML-descriptor:
<version>
VERSION
</version>
  • -v2|-vnum2 NUM — Specify the 2nd library version outside the descriptor 🌸
  • -relpath1 PATH — Replace {RELPATH} macros with PATH in the 1st XML-descriptor (-d1) 🧚
  • -relpath2 PATH — Replace {RELPATH} macros with PATH in the 2nd XML-descriptor (-d2) 🎀

✨ TEST OPTIONS ✨

  • -test — Run internal tests. This creates two binary incompatible versions of a sample library and runs the tool to check them for compatibility. It's a good way to see whether the tool works correctly in your current environment 🔥
  • -test-dump — Test the 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. The report is generated to compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html 💖
  • -source|-src|-api — Show source compatibility problems only. The report is generated to compat_reports/LIB_NAME/V1_to_V2/src_compat_report.html 🫶
  • -s|-strict — Treat all compatibility warnings as problems. This adds a number of "Low" severity problems to the return value of the tool 👑

✨ REPORT PATH OPTIONS ✨

  • -report-path PATH — Path to the compatibility report. Default: compat_reports/LIB_NAME/V1_to_V2/compat_report.html 🔖
  • -bin-report-path PATH — Path to the binary compatibility report. Default: compat_reports/LIB_NAME/V1_to_V2/abi_compat_report.html 💅
  • -src-report-path PATH — Path to the 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 lets you pipe the data to other programs 🧚
  • -report-format FMT — Change the format of the compatibility report. Formats:
    • htm — HTML format (default)
    • xml — XML format
  • -old-style — Generate an old-style report 🙈
  • -title NAME — Change the library name in the report title to NAME. By default, the name specified by the -l option is displayed 🎀
  • -component NAME — The component name in the title and summary of the HTML report. Default: library 🦋
  • -p|-params PATH — Path to a file with the function parameter names. It can improve the 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 a file with the list of incompatible symbols beside the HTML compatibility report. Use c++filt @file from GNU binutils to unmangle C++ symbols in the generated file. Default names: abi_affected.txt and src_affected.txt 🌈

✨ ABI DUMP OPTIONS ✨

  • -dump-path PATH — Specify a *.dump file path where the ABI dump will be generated. Default: abi_dumps/LIB_NAME/VERSION/ABI.dump 🍓
  • -dump-format FMT — Change the format of the ABI dump. Formats:
  • perl, the Data::Dumper format and the default one 💖
  • xml, the XML format 🫶
  • -check, checks completeness of the ABI dump 🔍
  • -extra-info DIR, dumps extra info into DIR 📂
  • -extra-dump, makes an extended ABI dump with all symbols from the translation unit ✨
  • -relpath PATH, swaps every {RELPATH} macro for PATH in the XML descriptor used for dumping the library ABI (see -dump option) 🦋
  • -vnum NUM, sets the library version in the generated ABI dump. Heads up, the <version> section of the input XML descriptor gets overwritten in this case ⚠️
  • -sort, turns on sorting of data in ABI dumps 🗂️

✨ FILTER SYMBOLS OPTIONS ✨

  • -symbols-list PATH, a file with a list of symbols (mangled names in C++) that should be checked. Everything else is skipped 🎯
  • -types-list PATH, a file with a list of types that should be checked. Other types won't 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, don't check symbols matched by the regular expression 🧚
  • -skip-internal-types PATTERN, don't check types matched by the regular expression. It gets matched against full qualified type names (e.g. struct xyz::Name<T>), and it only has to match any part of the type name 💅
  • -keep-cxx, checks _ZS*, _ZNS* and _ZNKS* symbols 👑
  • -keep-reserved, reports 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 the ABI of this header only 🎯
  • -nostdinc, don't search GCC standard system directories for header files 🚫
  • -tolerance LEVEL, applies a set of heuristics so the input header files compile successfully. You can turn on several tolerance levels by joining them into one string (e.g. 13, 124, etc.). The levels are:
    • 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, enables the highest tolerance level [1234] 💖
  • -skip-unidentified, skips header files in the headers and include_preamble sections of the XML descriptor that can't be found. This is super useful if you're using the same descriptor for different targets 🌸

✨ FILTER RULES OPTIONS ✨

  • -skip-typedef-uncover, doesn't report a problem if a type is covered or uncovered by a typedef (useful for broken debug info) 🤷‍♀️
  • -check-private-abi, checks data types from the private part of the ABI when comparing ABI dumps created by the ABI Dumper tool with the -public-headers option 🔐
Requires ABI Dumper >= 0.99.14 ⚠️
  • -disable-constants-check, don't check for changes in constants 😴
  • -skip-added-constants, don't detect added constants 🚫
  • -skip-removed-constants, don't detect removed constants 🚫

✨ OTHER OPTIONS ✨

  • -lang LANG, sets the library language (C or C++). Use this if the tool can't auto-detect the language. It can be handy for checking C library headers (--lang=C) in --headers-only or --extended modes 🌈
  • -arch ARCH, sets the library architecture (x86, x86_64, ia64, arm, ppc32, ppc64, s390, ect.). This comes in clutch if the tool can't detect the correct architecture of the input objects 🦾
  • -mingw-compatible, if the input header files are compatible with the MinGW GCC compiler, tell the tool so it can speed up the analysis 🏃‍♀️
  • -cxx-incompatible, set this if the input C header files use C++ keywords. The tool will try to swap those keywords out at the preprocessor stage and put them back in the final TU dump 🔄
  • -cpp-compatible, does nothing. Literally nothing 🫠
  • -quick, quick analysis. Disables checking of some template instances ⚡
  • -force, try enabling this if the tool didn't check all the types and symbols in the header files 💪

✨ OS ANALYSIS OPTIONS ✨

  • -dump-system NAME -sysroot DIR, finds all the shared libraries and header files in the DIR directory, creates XML descriptors, and makes ABI dumps for each library. The result set can be compared (--cmp-systems) with another one made for a different version of the operating system, to check them for compatibility. Don't forget the -cross-gcc option if your target system needs a specific version of GCC (different from the host GCC) 🖥️

The system ABI dump gets generated to:

sys_dumps/NAME/ARCH
  • -dump-system DESCRIPTOR.xml, the same as the previous option, but it takes an XML descriptor of the target system as input. This is where you describe your system, like so:
/* 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, compares two ABI dumps of a system. It creates compatibility reports for each system library, plus a common HTML report with the summary of test results for all checked libraries 🥊

The summary report gets generated to:

sys_compat_reports/NAME1_to_NAME2/ARCH
  • -sysroot DIR, specifies an alternative root directory. The tool will search for include paths in DIR/usr/include and DIR/usr/lib 📁
  • -sysinfo DIR, use this with the -dump-system option to dump the ABI of operating systems and configure the dumping process ⚙️
  • -libs-list PATH, a file with a list of libraries that should be dumped by the -dump-system option or checked by the -cmp-systems option 📚

✨ LOGGING OPTIONS ✨

  • -log-path PATH, the log path for all messages. Default: logs/LIB_NAME/VERSION/log.txt 📝
  • -log1-path PATH, the log path for the 1st version of a library. Default: logs/LIB_NAME/V1/log.txt 📝
  • -log2-path PATH, the log path for the 2nd version of a library. Default: logs/LIB_NAME/V2/log.txt 📝
  • -logging-mode MODE, changes the logging mode. Modes:
    • w, overwrite old logs (default)
    • a, append to old logs
    • n, don't write any logs
  • -q|-quiet, prints all messages to the file instead of stdout and stderr. Default path (can be changed with the -log-path option): logs/run.log 🤫

✨ REPORT PATH ✨

The compatibility report gets generated to:

compat_reports/LIB_NAME/V1_to_V2/compat_report.html

✨ LOG PATH ✨

The log gets generated to:

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

✨ EXIT CODES ✨

  • 0, compatible. The tool ran without any errors 🥳
  • non-zero, incompatible, or the tool ran with errors 💀

✨ MORE INFO ✨

✨ 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 © 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. 💖

And that's the whole page, bestie! 🎀 This manual is from the ABI Compliance Checker (ABICC) project, dated February 2023. Go forth and check those ABIs, you're literally unstoppable 💅✨

📦 where this page comes from