Provided by: abi-compliance-checker_2.3-2_all bug

NAME

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

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

   EXTRA OPTIONS:
       -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.

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

       -static

              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.

       -count-symbols PATH

              Count total public symbols in the ABI dump.

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

       -xml

              Alias for: --report-format=xml or --dump-format=xml

       -app|-application PATH

              This  option  allows  one  to  specify  the  application that should be checked for
              portability to the new library version.

       -headers-only

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

       -v1|-vnum1 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|-vnum2 NUM

              Specify 2nd library version outside the descriptor.

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

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

       -test-abi-dumper

              Compare ABI dumps created by the ABI Dumper tool.

   REPORT OPTIONS:
       -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

       -s|-strict

              Treat  all  compatibility  warnings  as  problems.  Add  a number of "Low" severity
              problems to the return value of the tool.

   REPORT PATH OPTIONS:
       -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

   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 would allow piping data to other programs.

       -report-format FMT

              Change format of compatibility report.  Formats:

              htm - HTML format (default) xml - XML format

       -old-style

              Generate old-style report.

       -title NAME

              Change  library  name  in  the report title to NAME. By default will be displayed a
              name specified by -l option.

       -component NAME

              The component name in the title and summary of the HTML report.  Default:

              library

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

              ...

       -limit-affected LIMIT

              The  maximum number of affected symbols listed under the description of the changed
              type in the report.

       -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

   ABI DUMP OPTIONS:
       -dump-path PATH

              Specify a *.dump file path where to generate an ABI dump.  Default:

              abi_dumps/LIB_NAME/VERSION/ABI.dump

       -dump-format FMT

              Change format of ABI dump.  Formats:

              perl - Data::Dumper format (default) xml - XML format

       -check

              Check completeness of the ABI dump.

       -extra-info DIR

              Dump extra info to DIR.

       -extra-dump

              Create extended ABI dump containing all symbols from the translation unit.

       -relpath PATH

              Replace {RELPATH} macros to PATH in the XML-descriptor used for dumping the library
              ABI (see -dump option).

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

       -sort

              Enable sorting of data in ABI dumps.

   FILTER SYMBOLS OPTIONS:
       -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.

       -skip-internal-symbols PATTERN

              Do not check symbols matched by the regular expression.

       -skip-internal-types PATTERN

              Do not check types matched by the regular expression.  It's  matched  against  full
              qualified  type  names  (e.g.  'struct xyz::Name<T>').  It has to match any part of
              type name.

       -keep-cxx

              Check _ZS*, _ZNS* and _ZNKS* symbols.

       -keep-reserved

              Report 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 ABI of this header only.

       -nostdinc

              Do not search in GCC standard system directories for header files.

       -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 include non-Linux headers 4 - skip
              headers included by others

       -tolerant

              Enable highest tolerance level [1234].

       -skip-unidentified

              Skip  header  files  in  'headers'  and  'include_preamble'  sections  of  the  XML
              descriptor  that  cannot be found. This is useful if you are trying to use the same
              descriptor for different targets.

   FILTER RULES OPTIONS:
       -skip-typedef-uncover

              Do not report a problem if type is covered or  uncovered  by  typedef  (useful  for
              broken debug info).

       -check-private-abi

              Check  data types from the private part of the ABI when comparing ABI dumps created
              by the ABI Dumper tool with use of the -public-headers option.

              Requires ABI Dumper >= 0.99.14

       -disable-constants-check

              Do not check for changes in constants.

       -skip-added-constants

              Do not detect added constants.

       -skip-removed-constants

              Do not detect removed constants.

   OTHER OPTIONS:
       -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.

       -mingw-compatible

              If input header files are compatible with the MinGW GCC compiler, then you can tell
              the tool about this and speedup the analysis.

       -cxx-incompatible

              Set  this  option  if  input  C header files use C++ keywords. The tool will try to
              replace such keywords at preprocessor stage and replace them back in the  final  TU
              dump.

       -cpp-compatible

              Do nothing.

       -quick

              Quick analysis. Disable check of some template instances.

       -force

              Try  to  enable this option if the tool checked not all types and symbols in header
              files.

   OS ANALYSIS OPTIONS:
       -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 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>

       -cmp-systems -d1 sys_dumps/NAME1/ARCH -d2 sys_dumps/NAME2/ARCH

              Compare two ABI dumps of a system. Create compatibility  reports  for  each  system
              library  and  the  common HTML report including the summary of test results for all
              checked libraries.

              Summary report will be generated to:

              sys_compat_reports/NAME1_to_NAME2/ARCH

       -sysroot DIR

              Specify the alternative root directory. The tool will search for include  paths  in
              the DIR/usr/include and DIR/usr/lib directories.

       -sysinfo DIR

              This  option  should  be  used  with  -dump-system  option to dump ABI of operating
              systems and configure the dumping process.

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

   LOGGING OPTIONS:
       -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

       -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

   REPORT PATH:
              Compatibility report will be generated to:

              compat_reports/LIB_NAME/V1_to_V2/compat_report.html

   LOG PATH:
              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 INFO:
              https://lvc.github.io/abi-compliance-checker/
              https://github.com/lvc/abi-compliance-checker

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

       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.