Provided by: abi-compliance-checker_1.99.14-1_all bug


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


              ABI Compliance Checker (abi-compliance-checker) Check backward compatibility  of  a
              C/C++ library API

              ABI  Compliance  Checker  (ABICC)  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.

              abi-compliance-checker [options]

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

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





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




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




              Print this help.


              Print complete info.


              Print version information.


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

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





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




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




              2.  ABI  dump  generated  by  -dump  option 3. Directory with headers and/or shared
              libraries 4. Single header file

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

              For more information, please see:


       -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 versions of ABI dump: 2.0<=V<=3.2

       -app|-application PATH

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


              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.

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




       -v2|-version2 NUM

              Specify 2nd library version outside the descriptor.

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


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


              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





              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.

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

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


              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.


              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:


       -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 of the system */



              /* The list of paths to header files and/or

              directories with header files, one per line */



              /* The list of paths to shared libraries and/or

              directories with shared libraries, one per line */


              /* Optional sections */


              /* List of directories to be searched

              for header files to automatically generate include paths, one per line */



              /* List of directories to be searched

              for shared libraries to resolve dependencies, one per line */



              /* List of directories with tools used

              for analysis (GCC toolchain), one per line */



              /* GCC toolchain prefix.

              arm-linux-gnueabi arm-none-symbianelf */



              /* Additional GCC options, one per line */


       -sysinfo DIR

              This option should be used with  -dump-system  option  to  dump  ABI  of  operating
              systems and configure the dumping process.  You can find a sample in the package:

              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:


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


              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

              The short scheme is:

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


              Print all messages to the file instead of stdout and stderr.  Default path (can  be
              changed by -log-path option):



              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


              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.

       -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


              Show "Binary" compatibility problems only.  Generate report to:



              Show "Source" compatibility problems only.  Generate report to:


       -limit-affected LIMIT

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


              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 ability to create, read and compare ABI dumps.


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


              Also consider using --dump option for debugging the tool.


              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.


              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:



              Enable sorting of data in ABI dumps.

       -report-path PATH

              Path to compatibility report.  Default:


       -bin-report-path PATH

              Path to "Binary" compatibility report.  Default:


       -src-report-path PATH

              Path to "Source" compatibility report.  Default:


       -log-path PATH

              Log path for all messages.  Default:


       -log1-path PATH

              Log path for 1st version of a library.  Default:


       -log2-path PATH

              Log path for 2nd version of a library.  Default:


       -logging-mode MODE

              Change logging mode.  Modes:

              w - overwrite old logs (default) a - append old logs n - do not write any logs


              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:


       -title NAME

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

       -extra-info DIR

              Dump extra info to DIR.


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


              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


              Enable highest tolerance level [1234].


              Check completeness of the ABI dump.


              Quick analysis. Disable check of some template instances.

       -skip-internal-symbols PATTERN

              Do not check symbols matched by the pattern.

       -skip-internal-types PATTERN

              Do not check types matched by the pattern.

              Compatibility report will be generated to:


              Log will be generated to:

              logs/LIB_NAME/V1/log.txt logs/LIB_NAME/V2/log.txt

              0  -  Compatible.  The tool has run without any errors.  non-zero - Incompatible or
              the tool has run with errors.



       This manual page was written  by  Mathieu  Malaterre  <>  for  the  Debian
       GNU/Linux system (but may be used by others).

       Written by Andrey Ponomarenko.


       Copyright   ©   2015   Andrey   Ponomarenko's   ABI   Laboratory   License:  LGPL  or  GPL
       <> This program is free  software:  you  can  redistribute  it
       and/or modify it.

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