ABI Compliance Checker Options

Contents

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 <descriptor.xml>
Dump library ABI to gzipped TXT format file. You can transfer it anywhere and pass instead of the XML-descriptor. Also it may 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.

  • -cross-gcc <path>
Path to the cross GCC compiler to use instead of the usual (host) GCC.

  • -sysroot <dirpath>
Specify the alternative root directory. The tool will search for include paths in the <dirpath>/usr/include and <dirpath>/usr/lib directories.

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

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

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

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

  • -dump-system <name>
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 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:
   <name>
       /* Name of the system */
   </name>
   <headers>
       /* List of directories with header
             files, one per line. */
   </headers>
   <libs>
       /* List of directories with shared
           libraries, one per line. */
   </libs>
   <tools>
       /* List of directories with tools
           (gcc, readelf, objdump, c++filt, ...) */
   </tools>

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

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/<library>/<version>/.

  • -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 the path to a file (*.abi.tar.gz) where to generate the ABI dump. Default dump path: abi_dumps/<library>/<library>_<version>.abi.tar.gz

  • -report-path <path>
Specify the file path where to generate the compatibility report. Default report path: compat_reports/<library name>/<v1>_to_<v2>/abi_compat_report.html

  • -log-path <path>
Specify the file path where to generate the \"dumping\" log (see -dump option). Default log path: logs/<library>/<version>/log.txt

  • -log1-path <path>
Specify the file path where to generate the log for 1st version of a library. Default log path: logs/<library name>/<v1>/log.txt

  • -log2-path <path>
Specify the file path where to generate the log for 2nd version of a library. Default log path: logs/<library name>/<v1>/log.txt

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