ABI Compliance Checker Options

Information Options

• -h|-help

Print help message.

• -i|-info

Print complete info.

• -v|-version

Print version information.

• -dumpversion

Print the tool version 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

Path to the descriptor of 1st (old) library version.

• -d2|-new|-n PATH

Path to the 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.

• -old-dumps

Enable support for old-version ABI dumps.

Extra Options

• -d|-descriptor-template

Create XML-descriptor template ./VERSION.xml

• -app|-application PATH

This option allow to specify the application that should be tested 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 location.

• -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 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.

• -v2|-version2 NUM

Specify 2nd library version outside the descriptor.

• -s|-strict

Treat all compatibility warnings as problems.

• -headers-only

Check header files without shared libraries. It is easy to run, but may provide provide a low quality compatibility report with false positives and without detecting of added/removed symbols.

• -objects-only

Check shared libraries without header files. It is easy to run, but may a low quality report with false positives and without analysis of changes in parameters and data types.

• -check-impl|-check-implementation

Compare canonified disassembled binary code of shared objects to detect changes in the implementation. Create section 'Changes in Implementation' in the report.

• -show-retval

Show the symbol's return type in the report.

• -symbols-list PATH

This option allow to specify a file with a list of interfaces (mangled names in C++) that should be checked, other library interfaces will not be checked.

• -skip-symbols PATH

The list of symbols 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 operative memory usage.

• -nostdinc

Do not search the 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 compiler (different from the host GCC). The system ABI dump will be generated to: sys_dumps/NAME/ARCH.

• -dump-system PATH

The same as the previous option but takes an XML descriptor of the target system.

• -sysinfo DIR

This option may be used with -dump-system to dump ABI of operating systems and configure the dumping process. Default: modules/SysInfo/<target> {unix, symbian, windows}

• -cmp-systems

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.

• -q|-quiet

Print all messages to the file instead of stdout and stderr.

• -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 FORMAT

Change format of compatibility report: html (default) or xml.

• -dump-format FORMAT

Change format of ABI dump: perl (default) or xml.

• -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.

• -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

• -affected-limit 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 to check if the tool works correctly in the current environment.

• -test-dump

Test ability to create, restore and compare ABI dumps.

• -debug

Debugging mode. Print debug info on the screen. Save intermediate analysis stages in the debug directory: debug/LIB_NAME/VER/.

• -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), then you can tell ACC 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 don't contain 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 (see -d1 option).

• -relpath2 PATH

Replace {RELPATH} macros to PATH in the 2nd XML-descriptor (see -d2 option).

• -dump-path PATH

Specify a *.abi.tar.gz or *.abi file path where to generate an ABI dump. Default path: abi_dumps/LIB_NAME/LIB_NAME_VERSION.abi.tar.gz

• -sort

Enable sorting of data in ABI dumps.

• -report-path PATH

Specify the file path where to generate the compatibility report. Default report path: compat_reports/LIB_NAME/V1_to_V2/abi_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 log path: logs/LIB_NAME/VER/log.txt

• -log1-path PATH

Log path for 1st version of a library. Default log path: logs/LIB_NAME/V1/log.txt

• -log2-path PATH

Log path for 2nd version of a library. Default log path: logs/LIB_NAME/V1/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 name: abi_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.

• -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 PATTERN

Do not check internal interfaces matched by the pattern.