/usr/bin/abi-compliance-checker

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
  compatibility and backward source compatibility of a C/C++ library API.

  The tool analyzes changes in API and ABI (ABI=API+compiler ABI) that may
  break binary compatibility and/or source 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 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.

  The tool is intended for developers of software libraries and maintainers
  of operating 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 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. Library should be compiled with "-g -Og" GCC options
     to contain 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

  3. You can filter public ABI with the help of
     additional -public-headers option of the ABI Dumper tool.

  4. Compare ABI dumps to create 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):

       <version>
           1.0
       </version>

       <headers>
           /path/to/headers/
       </headers>

       <libs>
           /path/to/libraries/
       </libs>

  2. Compare Xml-descriptors to create 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):

       <version>
           1.0
       </version>

       <headers>
           /path/to/headers/
       </headers>

       <libs>
           /path/to/libraries/
       </libs>

  2. Create 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

  3. Compare ABI dumps to create report:

       abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump

INFO OPTIONS:
  -h|-help
      Print this help.

  -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
      Descriptor of the 1st (old) library version.
      It may be one of the following:

         1. ABI dump generated by the ABI Dumper tool
         2. XML-descriptor (*.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>

                 ...

         3. ABI dump generated by -dump option
         4. Directory with headers and libraries
         5. Single header file

      If you are using 4-5 descriptor types then 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
      Descriptor of the 2nd (new) library version.

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

  -filter PATH
      A path to XML descriptor with skip_* rules to filter
      analyzed symbols in the report.

MORE OPTIONS:
     abi-compliance-checker --info