Provided by: abi-compliance-checker_1.99.9-1_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  (ACC)  is  a  tool  for  checking  backward  binary  and
              source-level compatibility of a shared C/C++ library. The tool checks header  files
              and shared libraries (*.so) of old and new versions and analyzes changes in API and
              ABI (ABI=API+compiler ABI) that may break binary and/or source-level 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 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 or GNU GPL.

   USAGE:
              abi-compliance-checker [options]

   EXAMPLE:
              abi-compliance-checker -lib NAME -old OLD.xml -new NEW.xml

              OLD.xml and NEW.xml are XML-descriptors:

              <version>

              1.0

              </version>

              <headers>

              /path1/to/header(s)/ /path2/to/header(s)/

              ...

              </headers>

              <libs>

              /path1/to/library(ies)/ /path2/to/library(ies)/

              ...

              </libs>

   INFORMATION OPTIONS:
       -h|-help

              Print this help.

       -i|-info

              Print complete info.

       -v|-version

              Print version information.

       -dumpversion

              Print the tool version (1.99.9) and don't do anything else.

   GENERAL OPTIONS:
       -l|-lib|-library NAME

              Library name (without version).

       -d1|-old|-o PATH

              Descriptor of 1st (old) library version.  It may be one of the following:

              1. XML-descriptor (VERSION.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>

              ... (XML-descriptor template

              can be generated by -d option)

              2.  ABI  dump  generated  by  -dump  option 3. Directory with headers and/or shared
              libraries 4. Single header file 5. Single shared library 6. Comma separated list of
              headers and/or libraries

              If  you  are  using an 2-6 descriptor types then you should specify version numbers
              with -v1 and -v2 options too.

              For more information, please see:

              http://ispras.linuxbase.org/index.php/Library_Descriptor

       -d2|-new|-n PATH

              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.

              Supported ABI dump versions: 2.0<=V<=3.2

       -old-dumps

              Enable support for old-version ABI dumps (1.18<=V<2.0).

   EXTRA OPTIONS:
       -d|-descriptor-template

              Create XML-descriptor template ./VERSION.xml

       -app|-application PATH

              This  option  allows  one  to  specify  the  application that should be checked 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. 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|-version2 NUM

              Specify 2nd library version outside the descriptor.

       -s|-strict

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

       -headers-only

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

              Alternatively  you  can  write  "none"  word  to  the   <libs>   section   in   the
              XML-descriptor:

              <libs>

              none

              </libs>

       -objects-only

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

              Alternatively   you  can  write  "none"  word  to  the  <headers>  section  in  the
              XML-descriptor:

              <headers>

              none

              </headers>

       -check-impl|-check-implementation

              Compare canonified disassembled binary code of shared libraries to  detect  changes
              in the implementation. Add 'Problems with Implementation' section to the report.

       -show-retval

              Show the symbol's return type in the report.

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

       -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 system memory usage.

       -nostdinc

              Do not search in 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 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>

       -sysinfo DIR

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

              modules/Targets/{unix, symbian, windows}

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

              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.

              The short scheme is:

              app C (broken) -> lib B (broken ABI) -> lib A (stable ABI)

       -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

       -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

       -dump-format FMT

              Change format of ABI dump.  Formats:

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

       -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

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

       -test-dump

              Test ability to create, read and compare ABI dumps.

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

       -cpp-compatible

              If  your  header  files  are  written  in C language and can be compiled by the G++
              compiler (i.e. don't use C++ keywords), then you can tell the tool 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 have no 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 (-d1).

       -relpath2 PATH

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

       -dump-path PATH

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

              abi_dumps/LIB_NAME/LIB_NAME_VERSION.abi.tar.gz

       -sort

              Enable sorting of data in ABI dumps.

       -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

       -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

       -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

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

   REPORT:
              Compatibility report will be generated to:

              compat_reports/LIB_NAME/V1_to_V2/compat_report.html

              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.

   REPORT BUGS TO:
              Andrey Ponomarenko <aponomarenko@rosalab.ru>

   MORE INFORMATION:
              http://ispras.linuxbase.org/index.php/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  © 2014 ROSA Laboratory License: LGPL or GPL <http://www.gnu.org/licenses/> This
       program is free software: you can redistribute it and/or modify it.

abi-compliance-checker Compliance Checker February92014                 ABI-COMPLIANCE-CHECKER(1)