| |
| <!DOCTYPE html> |
| <html lang="en" dir="ltr" class="client-nojs"> |
| <head> |
| <title>ABI Compliance Checker</title> |
| <meta charset="UTF-8" /> |
| <meta name="generator" content="MediaWiki 1.18.1" /> |
| <link rel="shortcut icon" href="/favicon.ico" /> |
| <link rel="search" type="application/opensearchdescription+xml" href="/opensearch_desc.php" title="ISP_RAS (en)" /> |
| <link rel="EditURI" type="application/rsd+xml" href="http://ispras.linuxbase.org/api.php?action=rsd" /> |
| <link rel="alternate" type="application/atom+xml" title="ISP_RAS Atom feed" href="/index.php?title=Special:RecentChanges&feed=atom" /> |
| <link rel="stylesheet" href="/load.php?debug=false&lang=en&modules=mediawiki.legacy.commonPrint%2Cshared%7Cskins.monobook&only=styles&skin=monobook&*" /> |
| <!--[if lt IE 5.5000]><link rel="stylesheet" href="/skins/monobook/IE50Fixes.css?303" media="screen" /><![endif]--> |
| <!--[if IE 5.5000]><link rel="stylesheet" href="/skins/monobook/IE55Fixes.css?303" media="screen" /><![endif]--> |
| <!--[if IE 6]><link rel="stylesheet" href="/skins/monobook/IE60Fixes.css?303" media="screen" /><![endif]--> |
| <!--[if IE 7]><link rel="stylesheet" href="/skins/monobook/IE70Fixes.css?303" media="screen" /><![endif]--><meta name="ResourceLoaderDynamicStyles" content="" /> |
| <link rel="stylesheet" href="/load.php?debug=false&lang=en&modules=site&only=styles&skin=monobook&*" /> |
| <style>a:lang(ar),a:lang(ckb),a:lang(fa),a:lang(kk-arab),a:lang(mzn),a:lang(ps),a:lang(ur){text-decoration:none}a.new,#quickbar a.new{color:#ba0000} |
| |
| /* cache key: rasispdb:resourceloader:filter:minify-css:4:c88e2bcd56513749bec09a7e29cb3ffa */ |
| </style> |
| <script src="/load.php?debug=false&lang=en&modules=startup&only=scripts&skin=monobook&*"></script> |
| <script>if(window.mw){ |
| mw.config.set({"wgCanonicalNamespace": "", "wgCanonicalSpecialPageName": false, "wgNamespaceNumber": 0, "wgPageName": "ABI_compliance_checker", "wgTitle": "ABI Compliance Checker", "wgCurRevisionId": 8308, "wgArticleId": 2292, "wgIsArticle": true, "wgAction": "view", "wgUserName": null, "wgUserGroups": ["*"], "wgCategories": ["ABI Compliance Checker"], "wgBreakFrames": false, "wgRestrictionEdit": [], "wgRestrictionMove": []}); |
| } |
| </script><script>if(window.mw){ |
| mw.loader.load(["mediawiki.page.startup"]); |
| } |
| </script> |
| </head> |
| <body class="mediawiki ltr sitedir-ltr ns-0 ns-subject page-ABI_compliance_checker action-view skin-monobook"> |
| <div id="globalWrapper"> |
| <div id="column-content"><div id="content"> |
| <a id="top"></a> |
| |
| <h1 id="firstHeading" class="firstHeading">ABI Compliance Checker</h1> |
| <div id="bodyContent"> |
| <div id="siteSub"></div> |
| <div id="contentSub"></div> |
| |
| <!-- start content --> |
| <div lang="en" dir="ltr" class="mw-content-ltr"><p><i>ABI Compliance Checker (ACC)</i> is a tool for checking backward <b>binary</b> and <b>source-level compatibility</b> of a C/C++ library. The tool checks header files and shared libraries of old and new versions and analyzes changes in API and ABI (ABI=API+compiler ABI) that may break binary 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 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. |
| </p><p>See also: |
| </p> |
| <ul><li> <a rel="nofollow" class="external text" href="https://github.com/lvc/abi-dumper">ABI Dumper</a> |
| </li><li> <a rel="nofollow" class="external text" href="http://upstream-tracker.org/">Upstream Tracker</a> |
| </li><li> <a rel="nofollow" class="external text" href="http://pkgdiff.github.com/pkgdiff/">PkgDiff</a> |
| </li></ul> |
| <p><br /> |
| </p> |
| <table id="toc" class="toc"><tr><td><div id="toctitle"><h2>Contents</h2></div> |
| <ul> |
| <li class="toclevel-1 tocsection-1"><a href="#Downloads"><span class="tocnumber">1</span> <span class="toctext">Downloads</span></a> |
| <ul> |
| <li class="toclevel-2 tocsection-2"><a href="#Releases"><span class="tocnumber">1.1</span> <span class="toctext">Releases</span></a></li> |
| <li class="toclevel-2 tocsection-3"><a href="#Git"><span class="tocnumber">1.2</span> <span class="toctext">Git</span></a></li> |
| </ul> |
| </li> |
| <li class="toclevel-1 tocsection-4"><a href="#License"><span class="tocnumber">2</span> <span class="toctext">License</span></a></li> |
| <li class="toclevel-1 tocsection-5"><a href="#Supported_Platforms"><span class="tocnumber">3</span> <span class="toctext">Supported Platforms</span></a></li> |
| <li class="toclevel-1 tocsection-6"><a href="#System_Requirements"><span class="tocnumber">4</span> <span class="toctext">System Requirements</span></a></li> |
| <li class="toclevel-1 tocsection-7"><a href="#Detectable_Compatibility_Problems"><span class="tocnumber">5</span> <span class="toctext">Detectable Compatibility Problems</span></a> |
| <ul> |
| <li class="toclevel-2 tocsection-8"><a href="#Binary_Compatibility"><span class="tocnumber">5.1</span> <span class="toctext">Binary Compatibility</span></a></li> |
| <li class="toclevel-2 tocsection-9"><a href="#Source_Compatibility"><span class="tocnumber">5.2</span> <span class="toctext">Source Compatibility</span></a></li> |
| </ul> |
| </li> |
| <li class="toclevel-1 tocsection-10"><a href="#Installation"><span class="tocnumber">6</span> <span class="toctext">Installation</span></a></li> |
| <li class="toclevel-1 tocsection-11"><a href="#Usage"><span class="tocnumber">7</span> <span class="toctext">Usage</span></a> |
| <ul> |
| <li class="toclevel-2 tocsection-12"><a href="#Compare_Libraries"><span class="tocnumber">7.1</span> <span class="toctext">Compare Libraries</span></a></li> |
| <li class="toclevel-2 tocsection-13"><a href="#Create_ABI_Dumps"><span class="tocnumber">7.2</span> <span class="toctext">Create ABI Dumps</span></a></li> |
| <li class="toclevel-2 tocsection-14"><a href="#Usage_with_ABI_Dumper"><span class="tocnumber">7.3</span> <span class="toctext">Usage with ABI Dumper</span></a></li> |
| <li class="toclevel-2 tocsection-15"><a href="#Usage_as_a_Parser_of_API"><span class="tocnumber">7.4</span> <span class="toctext">Usage as a Parser of API</span></a></li> |
| <li class="toclevel-2 tocsection-16"><a href="#Compare_Operating_Systems"><span class="tocnumber">7.5</span> <span class="toctext">Compare Operating Systems</span></a></li> |
| <li class="toclevel-2 tocsection-17"><a href="#Check_Applications_Portability"><span class="tocnumber">7.6</span> <span class="toctext">Check Applications Portability</span></a></li> |
| <li class="toclevel-2 tocsection-18"><a href="#Command-Line_Options"><span class="tocnumber">7.7</span> <span class="toctext">Command-Line Options</span></a></li> |
| <li class="toclevel-2 tocsection-19"><a href="#Examples"><span class="tocnumber">7.8</span> <span class="toctext">Examples</span></a></li> |
| </ul> |
| </li> |
| <li class="toclevel-1 tocsection-20"><a href="#Tutorial"><span class="tocnumber">8</span> <span class="toctext">Tutorial</span></a></li> |
| <li class="toclevel-1 tocsection-21"><a href="#Report_Format"><span class="tocnumber">9</span> <span class="toctext">Report Format</span></a></li> |
| <li class="toclevel-1 tocsection-22"><a href="#Verdict_on_Compatibility"><span class="tocnumber">10</span> <span class="toctext">Verdict on Compatibility</span></a></li> |
| <li class="toclevel-1 tocsection-23"><a href="#Error_Codes"><span class="tocnumber">11</span> <span class="toctext">Error Codes</span></a></li> |
| <li class="toclevel-1 tocsection-24"><a href="#FAQ"><span class="tocnumber">12</span> <span class="toctext">FAQ</span></a></li> |
| <li class="toclevel-1 tocsection-25"><a href="#Similar_Tools"><span class="tocnumber">13</span> <span class="toctext">Similar Tools</span></a></li> |
| <li class="toclevel-1 tocsection-26"><a href="#Bugs"><span class="tocnumber">14</span> <span class="toctext">Bugs</span></a></li> |
| <li class="toclevel-1 tocsection-27"><a href="#Maintainers"><span class="tocnumber">15</span> <span class="toctext">Maintainers</span></a></li> |
| <li class="toclevel-1 tocsection-28"><a href="#Credits"><span class="tocnumber">16</span> <span class="toctext">Credits</span></a></li> |
| <li class="toclevel-1 tocsection-29"><a href="#Articles"><span class="tocnumber">17</span> <span class="toctext">Articles</span></a></li> |
| </ul> |
| </td></tr></table> |
| <h2> <span class="mw-headline" id="Downloads"> Downloads </span></h2> |
| <h3> <span class="mw-headline" id="Releases"> Releases </span></h3> |
| <p>All releases can be downloaded from <b><a href="Changes.html" title="ABI Compliance Checker Downloads">this page</a></b> or <b><a rel="nofollow" class="external text" href="https://github.com/lvc/abi-compliance-checker/">github.com</a></b>. |
| </p><p>Latest release: <a rel="nofollow" class="external text" href="https://github.com/lvc/abi-compliance-checker/archive/1.99.8.tar.gz">1.99.8</a> |
| </p> |
| <h3> <span class="mw-headline" id="Git"> Git </span></h3> |
| <p>Read-only access to the latest development version:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> git clone <a rel="nofollow" class="external text" href="https://github.com/lvc/abi-compliance-checker">git://github.com/lvc/abi-compliance-checker.git</a>  </code><br /> |
| </p> |
| <h2> <span class="mw-headline" id="License"> License </span></h2> |
| <p>This program is free software. You may use, redistribute and/or modify it under the terms of either the <b>GNU GPL</b> or <b>LGPL</b>. |
| </p> |
| <h2> <span class="mw-headline" id="Supported_Platforms"> Supported Platforms </span></h2> |
| <p>GNU/Linux, FreeBSD, Mac OS X, MS Windows, Haiku/BeOS. |
| </p> |
| <h2> <span class="mw-headline" id="System_Requirements"> System Requirements </span></h2> |
| <ul><li><b>Linux, FreeBSD</b> |
| <ul><li> <a rel="nofollow" class="external text" href="http://gcc.gnu.org/">G++</a> (3.0-4.7, recommended 4.5 or newer) |
| </li><li> <a rel="nofollow" class="external text" href="http://www.gnu.org/software/binutils/">GNU Binutils</a> (readelf, c++filt, objdump) |
| </li><li> <a rel="nofollow" class="external text" href="http://www.perl.org/">Perl 5</a> (5.8 or newer) |
| </li><li> <a rel="nofollow" class="external text" href="http://ctags.sourceforge.net/">Ctags</a> (5.8 or newer) |
| </li><li> WARNING: if you are using ccache program (i.e. gcc points to /usr/lib/ccache/gcc) then it should be newer than 3.1.2 or disabled. |
| </li></ul> |
| </li></ul> |
| <ul><li><b>Mac OS X</b> |
| <ul><li> <a rel="nofollow" class="external text" href="http://developer.apple.com/technologies/tools/xcode.html">Xcode</a> (gcc, c++filt, nm, otool) |
| </li><li> <a rel="nofollow" class="external text" href="http://ctags.sourceforge.net/">Ctags</a> (5.8 or newer) |
| </li></ul> |
| </li></ul> |
| <ul><li><b>MS Windows</b> |
| <ul><li> <a rel="nofollow" class="external text" href="http://www.mingw.org/">MinGW</a> (3.0-4.7, recommended 4.5 or newer) |
| </li><li> MS Visual C++ (dumpbin, undname, cl) |
| </li><li> <a rel="nofollow" class="external text" href="http://www.activestate.com/activeperl">Active Perl 5</a> (5.8 or newer) |
| </li><li> Sigcheck v1.71 or newer |
| </li><li> <a rel="nofollow" class="external text" href="http://ctags.sourceforge.net/">Ctags</a> (5.8 or newer) |
| </li><li> Info-ZIP 3.0 (zip, unzip) |
| </li><li> Add tool locations to the PATH environment variable |
| </li><li> Run vsvars32.bat script (C:\Microsoft Visual Studio 9.0\Common7\Tools\) |
| </li></ul> |
| </li></ul> |
| <h2> <span class="mw-headline" id="Detectable_Compatibility_Problems"> Detectable Compatibility Problems </span></h2> |
| <p>The tool searches for the following list of changes in the API that may break <b>binary/source-level</b> compatibility. See <a rel="nofollow" class="external text" href="#Articles" title="ABI Compliance Checker">this list</a> of articles for more info. |
| </p> |
| <h3> <span class="mw-headline" id="Binary_Compatibility"> Binary Compatibility </span></h3> |
| <ul><li> <b>Removed Symbols</b> (functions, global data) |
| </li><li> <b>Problems with Data Types</b> |
| <ul><li> <b>Structures</b> and <b>Classes</b> |
| <ul><li> added/removed fields (change of a memory layout) |
| </li><li> change of size |
| </li><li> changed order of fields |
| </li><li> change of a field type |
| </li><li> changes in fields (recursive analysis) |
| </li></ul> |
| </li><li> <b>Classes</b> |
| <ul><li> added/removed virtual functions (change of a v-table layout) |
| </li><li> change of virtual function position |
| </li><li> overridden virtual functions |
| </li><li> added/removed base classes |
| </li><li> changes in base classes (recursive analysis) |
| </li></ul> |
| </li><li> <b>Unions</b> |
| <ul><li> added/removed fields |
| </li><li> change of size |
| </li><li> change of a field type |
| </li><li> changes in fields (recursive analysis) |
| </li></ul> |
| </li><li> <b>Enumerations</b> |
| <ul><li> change of a member value |
| </li><li> removed/renamed members |
| </li></ul> |
| </li></ul> |
| </li><li> <b>Problems with Symbols</b> |
| <ul><li> <b>Stack Frame</b> |
| <ul><li> added/removed parameters |
| </li><li> change of a parameter/return value type |
| </li><li> change of default parameter value |
| </li><li> renamed parameters |
| </li></ul> |
| </li><li> <b>Other</b> |
| <ul><li> incorrect version change |
| </li><li> changed attributes (const, volatile, static, etc.) |
| </li></ul> |
| </li></ul> |
| </li><li> <b>Problems with Constants</b> (#defines) |
| <ul><li> changed value |
| </li></ul> |
| </li><li> <b>Problems with Implementation</b> |
| <ul><li> changes in disassembled binary code |
| </li></ul> |
| </li></ul> |
| <h3> <span class="mw-headline" id="Source_Compatibility"> Source Compatibility </span></h3> |
| <ul><li> <b>Removed Symbols</b> (functions, global data) |
| </li><li> <b>Problems with Data Types</b> |
| <ul><li> <b>Structures</b>, <b>Classes</b> and <b>Unions</b> |
| <ul><li> removed/renamed fields |
| </li><li> change of a field type |
| </li><li> changes in fields (recursive analysis) |
| </li></ul> |
| </li><li> <b>Classes</b> |
| <ul><li> added/removed base classes |
| </li><li> change access level of a field or method |
| </li><li> added pure virtual methods |
| </li></ul> |
| </li><li> <b>Enumerations</b> |
| <ul><li> removed/renamed members |
| </li></ul> |
| </li></ul> |
| </li><li> <b>Problems with Symbols</b> |
| <ul><li> <b>Parameters</b> |
| <ul><li> added/removed parameters |
| </li><li> change of a parameter type |
| </li><li> removed default value |
| </li></ul> |
| </li><li> <b>Other</b> |
| <ul><li> change of return value type |
| </li><li> changed attributes (const, static, etc.) |
| </li></ul> |
| </li></ul> |
| </li><li> <b>Problems with Constants</b> (#defines) |
| <ul><li> changed value |
| </li></ul> |
| </li></ul> |
| <p><br /> |
| You can see detailed problem descriptions in the visual interactive HTML-format compatibility report (see <a rel="nofollow" class="external text" href="http://upstream-tracker.org/compat_reports/mysql++/3.0.9_to_3.1.0/compat_report.html">this example</a>) generated by the tool. |
| </p> |
| <h2> <span class="mw-headline" id="Installation"> Installation </span></h2> |
| <p>The tool is <b>ready-to-use</b> after extracting the archive. You can also use a <b>Makefile</b> to install the tool into the system:<br /> |
| <code style="border: dashed 1px gray; background-color: #f0f0f0;"> cd abi-compliance-checker-x.y.z/ </code><br /><br /> |
| <code style="border: dashed 1px gray; background-color: #f0f0f0;"> sudo perl Makefile.pl -install --prefix=PREFIX [/usr, /usr/local, ...] </code> |
| </p><p>This command will install an <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker </code> program in the <code style="border: dashed 1px gray; background-color: #f0f0f0;"> PREFIX/bin </code> system directory and private modules into the <code style="border: dashed 1px gray; background-color: #f0f0f0;"> PREFIX/share </code>. |
| </p><p>To verify that the tool is installed correctly and it works on your host run:<br /> |
| <code style="border: dashed 1px gray; background-color: #f0f0f0;"> cd tmp/ </code><br /><br /> |
| <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -test </code><br /><br /> |
| </p> |
| <h2> <span class="mw-headline" id="Usage"> Usage </span></h2> |
| <p>For using the tool, you should provide the <a href="Descriptor.html" title="Library Descriptor"><b>XML descriptors</b></a> for two library versions: <a href="Descriptor.html" title="Library Descriptor"><b>v1.xml</b></a> and <a href="Descriptor.html" title="Library Descriptor"><b>v2.xml</b></a> files. Library descriptor is a simple XML-file that specifies version number, paths to header files and shared libraries and other optional information. An example of the descriptor is the following (0.3.4.xml): |
| </p> |
| <pre><span style="color:Green;"><version></span> |
| 0.3.4 |
| <span style="color:Green;"></version></span> |
| |
| <span style="color:Green;"><headers></span> |
| /usr/local/libssh/0.3.4/include/ |
| <span style="color:Green;"></headers></span> |
| |
| <span style="color:Green;"><libs></span> |
| /usr/local/libssh/0.3.4/lib/ |
| <span style="color:Green;"></libs></span> |
| </pre> |
| <h3> <span class="mw-headline" id="Compare_Libraries"> Compare Libraries </span></h3> |
| <p>Command to compare two versions of a library:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -old <i><a href="Descriptor.html" title="Library Descriptor">V1.xml</a></i> -new <i><a href="Descriptor.html" title="Library Descriptor">V2.xml</a></i> </code><br /><br /> |
| The compatibility report will be generated to:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> compat_reports/<i>NAME</i>/<i>V1</i>_to_<i>V2</i>/compat_report.html </code><br /><br /> |
| </p> |
| <h3> <span class="mw-headline" id="Create_ABI_Dumps"> Create ABI Dumps </span></h3> |
| <p>The library ABI is a representation of the library API at the binary level. The ABI dump is a dump of the model of the ABI used in the tool. |
| </p><p>The ABI dump consists of: |
| </p> |
| <ul><li> Types Information |
| <ul><li> Attributes (name, size, header, access, base types, etc.) |
| </li><li> Fields (name, type, size, position, alignment, access, specifiers, etc.) |
| </li><li> V-table structure (offsets, entries) |
| </li><li> Etc. |
| </li></ul> |
| </li><li> Symbols Information |
| <ul><li> Attributes (name, mangled name, header, access, specifiers, etc.) |
| </li><li> Parameters (name, type, position, alignment, etc.) |
| </li><li> Etc. |
| </li></ul> |
| </li><li> Etc. |
| </li></ul> |
| <p>The ABI dump can be used to create a snapshot of a library ABI in the particular environment and then compare it with any other state of the ABI changed due to changes in the environment (compiler version, external libraries, etc.) or changes in the library API (header files). The typical case is the comparing of two versions of the same library that require incompatible states of the environment (i.e. these versions cannot be installed simultaneously). In this case one can create a dump for one version of the library and then switch the environment and create ABI dump for other version of the library. Two ABI dumps can be compared by the tool to create the API compatibility report. |
| </p><p>To create an ABI dump use <a href="Options.html" title="ABI Compliance Checker Options">-dump</a> option:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -dump <i><a href="Descriptor.html" title="Library Descriptor">VER.xml</a></i> </code><br /><br /> |
| The ABI dump will be generated to:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi_dumps/<i>NAME</i>/<i>NAME</i>_<i>VER</i>.abi.tar.gz </code><br /><br /> |
| To compare ABI dumps pass them as the descriptors:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -old <i>V1.abi.tar.gz</i> -new <i>V2.abi.tar.gz</i> </code><br /><br /> |
| </p> |
| <h3> <span class="mw-headline" id="Usage_with_ABI_Dumper"> Usage with ABI Dumper </span></h3> |
| <p>Library should be compiled with <b>-g</b> option to contain DWARF debug info. |
| </p><p>Create ABI dumps for both library versions using the <a rel="nofollow" class="external text" href="https://github.com/lvc/abi-dumper">ABI Dumper</a> tool: |
| </p><p>  <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-dumper OLD.so -o ABI-0.dump -lver 0 </code><br /><br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-dumper NEW.so -o ABI-1.dump -lver 1 </code><br /><br /> |
| </p><p>Compare ABI dumps: |
| </p><p>  <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -l NAME -old ABI-0.dump -new ABI-1.dump </code><br /><br /> |
| </p> |
| <h3> <span class="mw-headline" id="Usage_as_a_Parser_of_API"> Usage as a Parser of API </span></h3> |
| <p>The tool can be used as a parser of C/C++ API. Use <a href="Options.html" title="ABI Compliance Checker Options">-dump</a> and <a href="Options.html" title="ABI Compliance Checker Options">-xml</a> options to create ABI dump in the XML format:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -dump <i><a href="Descriptor.html" title="Library Descriptor">VER.xml</a></i> -xml </code><br /><br /> |
| The ABI dump will be generated to:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi_dumps/<i>NAME</i>/<i>NAME</i>_<i>VER</i>.abi.tar.gz </code><br /><br /> |
| You can use additional <a href="Options.html" title="ABI Compliance Checker Options">-stdout</a> option to print ABI dump on the screen instead of creating gzipped file:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -dump <i><a href="Descriptor.html" title="Library Descriptor">VER.xml</a></i> -xml -stdout </code><br /><br /> |
| </p><p>See examples of ABI dumps for MeeGo Touch library in <a href="http://ispras.linuxbase.org/images/2/2a/MeeGoTouch_XML.abi.tar.gz" class="internal" title="MeeGoTouch XML.abi.tar.gz">XML</a> and <a href="http://ispras.linuxbase.org/images/4/47/MeeGoTouch.abi.tar.gz" class="internal" title="MeeGoTouch.abi.tar.gz">Perl</a> (default) formats. |
| <br /> |
| </p> |
| <h3> <span class="mw-headline" id="Compare_Operating_Systems"> Compare Operating Systems </span></h3> |
| <p>The detailed explanation on how to check compatibility between operating systems you can read on <b><a href="SysCheck/Usage.html" title="Operating Systems Compatibility">this page</a></b>. |
| </p><p>See current test results for <b>Symbian</b>, <b>Windows</b>, <b>MeeGo</b> and <b>Maemo</b> on <b><a rel="nofollow" class="external text" href="http://upstream-tracker.org/compatibility/index.html">this page</a></b>. |
| </p> |
| <h3> <span class="mw-headline" id="Check_Applications_Portability"> Check Applications Portability </span></h3> |
| <p>The ACC tool can be used by independent software vendors (ISV) to check applications portability to new library versions by specifying of its binary using <a href="Options.html" title="ABI Compliance Checker Options">-app</a> option:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -lib <i>NAME</i> -old <i><a href="Descriptor.html" title="Library Descriptor">V1.xml</a></i> -new <i><a href="Descriptor.html" title="Library Descriptor">V2.xml</a></i> -app <i>APP</i> </code> |
| </p><p>Found issues can be taken into account when adapting the application to a new library version. |
| </p> |
| <h3> <span class="mw-headline" id="Command-Line_Options"> Command-Line Options </span></h3> |
| <p>See the list of all options on <b><a href="Options.html" title="ABI Compliance Checker Options">this page</a></b>. |
| </p><p>Up-to-date list of all supported options can be obtained by this command: |
| </p><p>  <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker --info </code><br /> |
| </p><p>Most useful options: |
| </p> |
| <ul><li> <a href="Options.html" title="ABI Compliance Checker Options">-debug</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-extra-info</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-dump</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-tolerance</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-headers-only</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-xml</a> |
| </li><li> <a href="Options.html" title="ABI Compliance Checker Options">-test</a> |
| </li></ul> |
| <h3> <span class="mw-headline" id="Examples"> Examples </span></h3> |
| <p>Check the libssh library versions for ABI compatibility:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -l libssh -old <a href="Descriptor.html" title="Library Descriptor">0.3.4.xml</a> -new <a href="Descriptor.html" title="Library Descriptor">0.4.0.xml</a> </code><br /><br /> |
| The compatibility report will be generated to:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> compat_reports/libssh/0.3.4_to_0.4.0/compat_report.html </code><br /><br /> |
| Dump library ABI:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -l libssh -dump <a href="Descriptor.html" title="Library Descriptor">0.3.4.xml</a> </code><br /><br /> |
| The ABI will be dumped to:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi_dumps/libssh/libssh_0.3.4.abi.tar.gz </code><br /><br /> |
| Use previously dumped ABI:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -l libssh -old libssh_0.3.4.abi.tar.gz -new libssh_0.4.0.abi.tar.gz </code><br /><br /> |
| Check client application portability between libssh versions:<br /> |
|   <code style="border: dashed 1px gray; background-color: #f0f0f0;"> abi-compliance-checker -l libssh -old <a href="Descriptor.html" title="Library Descriptor">0.3.4.xml</a> -new <a href="Descriptor.html" title="Library Descriptor">0.4.0.xml</a> -app /usr/bin/csync </code><br /><br /> |
| </p> |
| <h2> <span class="mw-headline" id="Tutorial"> Tutorial </span></h2> |
| <p>An excellent tutorial <a rel="nofollow" class="external text" href="http://blog.famillecollet.com/post/2010/06/20/ABI-%3A-stability-check">"ABI: stability check"</a> is available at Les RPM de Remi Blog. See also <a rel="nofollow" class="external text" href="http://sourceware.org/glibc/wiki/Testing/ABI_checker">ABI Compliance Checker Notes</a> at glibc wiki. |
| </p> |
| <h2> <span class="mw-headline" id="Report_Format"> Report Format </span></h2> |
| <p>The tool supports two formats of a compatibility report: visual interactive HTML (default) and XML. To generate XML report you should specify <a href="Options.html" title="ABI Compliance Checker Options">-xml</a> additional option. |
| </p><p>The HTML-format compatibility report consists of: |
| </p> |
| <ul><li> <b>Test Info</b> - The library name and compared version numbers. Environment info: GCC version and CPU type; |
| </li><li> <b>Test Results</b> - Verdict on compatibility. Number of header files, shared libraries, symbols and data types checked by the tool; |
| </li><li> <b>Problem Summary</b> - Classification of compatibility problems; |
| </li><li> <b>Added Symbols</b> - The list of added symbols; |
| </li><li> <b>Removed Symbols</b> - The list of removed symbols; |
| </li><li> <b>Problems with Data Types</b> - The list of compatibility problems caused by changes in data types (divided by the severity level: High, Medium and Low). List of affected symbols; |
| </li><li> <b>Problems with Symbols</b> - The list of compatibility problems caused by changes in symbol parameters or attributes (divided by the severity level); |
| </li><li> <b>Problems with Constants</b> - The list of changed constants (#defines); |
| </li><li> <b>Other Changes in Data Types</b> - The list of compatible changes in data types; |
| </li><li> <b>Other Changes in Symbols</b> - The list of compatible changes in symbols; |
| </li><li> <b>Problems with Implementation</b> - The list of changes in disassembled binary code. Use <a href="Options.html" title="ABI Compliance Checker Options">-check-implementation</a> option to enable this section. |
| </li></ul> |
| <p>Examples of HTML-format report: |
| </p> |
| <ul><li> NetCDF: 4.0.1 to 4.1.1 API compatibility <a rel="nofollow" class="external text" href="http://upstream-tracker.org/compat_reports/netcdf/4.0.1_to_4.1.1/compat_report.html">report</a> |
| </li><li> MySQL++: 3.0.9 to 3.1.0 binary compatibility <a rel="nofollow" class="external text" href="http://upstream-tracker.org/compat_reports/mysql++/3.0.9_to_3.1.0/abi_compat_report.html">report</a> |
| </li><li> libssh: 0.3.4 to 0.4.0 binary compatibility <a rel="nofollow" class="external text" href="http://upstream-tracker.org/compat_reports/libssh/0.3.4_to_0.4.0/abi_compat_report.html">report</a> |
| </li></ul> |
| <h2> <span class="mw-headline" id="Verdict_on_Compatibility"> Verdict on Compatibility </span></h2> |
| <p>If the tool detected problems with high or medium level of severity or at least one removed symbol then the compatibility verdict is <b>incompatible</b> (otherwise <b>compatible</b>). Low-severity problems can be considered as <b>warnings</b> and don't affect the compatibility verdict unless the <a href="Options.html" title="ABI Compliance Checker Options">-strict</a> option is specified. |
| </p> |
| <h2> <span class="mw-headline" id="Error_Codes"> Error Codes </span></h2> |
| <table class="wikitable"> |
| <tr> |
| <th> Code |
| </th> |
| <th> Meaning |
| </th></tr> |
| <tr align="left"> |
| <td> 0 |
| </td> |
| <td> Compatible. The tool has run without any errors. |
| </td></tr> |
| <tr align="left"> |
| <td> 1 |
| </td> |
| <td> Incompatible. The tool has run without any errors. |
| </td></tr> |
| <tr align="left"> |
| <td> 2 |
| </td> |
| <td> Common error code (undifferentiated). |
| </td></tr> |
| <tr align="left"> |
| <td> 3 |
| </td> |
| <td> A system command is not found. |
| </td></tr> |
| <tr align="left"> |
| <td> 4 |
| </td> |
| <td> Cannot access input files. |
| </td></tr> |
| <tr align="left"> |
| <td> 5 |
| </td> |
| <td> Cannot compile header files. |
| </td></tr> |
| <tr align="left"> |
| <td> 6 |
| </td> |
| <td> Headers have been compiled with minor errors. |
| </td></tr> |
| <tr align="left"> |
| <td> 7 |
| </td> |
| <td> Invalid input ABI dump. |
| </td></tr> |
| <tr align="left"> |
| <td> 8 |
| </td> |
| <td> Unsupported version of input ABI dump. |
| </td></tr> |
| <tr align="left"> |
| <td> 9 |
| </td> |
| <td> Cannot find a module. |
| </td></tr> |
| <tr align="left"> |
| <td> 10 |
| </td> |
| <td> Empty intersection between headers and shared objects. |
| </td></tr> |
| <tr align="left"> |
| <td> 11 |
| </td> |
| <td> Empty set of symbols in headers. |
| </td></tr></table> |
| <h2> <span class="mw-headline" id="FAQ"> FAQ </span></h2> |
| <ul><li> <b>What is an ABI and how does it differ from an API?</b> |
| </li></ul> |
| <p>An Application Binary Interface (ABI) is the set of supported run-time interfaces provided by a software component or set of components for applications to use, whereas an Application Programming Interface (API) is the set of build-time interfaces. The ABI may be defined by the formula: |
| </p> |
| <pre> ABI = API + compiler ABI |
| </pre> |
| <ul><li> <b>Why does this tool need both shared libraries and header files to check ABI compliance?</b> |
| </li></ul> |
| <p>Without header files it is impossible to determine public symbols in ABI and data type definitions. Without shared libraries it is impossible to determine exported symbols in the ABI of the target library and also impossible to detect added/removed symbols. |
| </p> |
| <h2> <span class="mw-headline" id="Similar_Tools"> Similar Tools </span></h2> |
| <ol><li> <b>icheck</b> - C interface ABI/API checker |
| </li><li> <b>BCS</b> - The Symbian binary compatibility suite |
| </li><li> <b>shlib-compat</b> - ABI compatibility checker that uses DWARF debug info |
| </li><li> <b>qbic</b> - A tool to check for binary incompatibilities in Qt4 Toolkit |
| </li><li> <b>chkshlib</b>, <b>cmpdylib</b>, <b>cmpshlib</b> - Tools to compare binary symbols |
| </li></ol> |
| <h2> <span class="mw-headline" id="Bugs"> Bugs </span></h2> |
| <p>Please send your bug reports, feature requests and questions to the <a rel="nofollow" class="external text" href="mailto:aponomarenko@rosalab.ru">the maintainer</a>, post to <a rel="nofollow" class="external text" href="http://forge.ispras.ru/projects/abi-compliance-checker">issue tracker</a> or <a rel="nofollow" class="external text" href="https://groups.google.com/forum/#!forum/lvc-tools">mailing list</a>. |
| </p> |
| <h2> <span class="mw-headline" id="Maintainers"> Maintainers </span></h2> |
| <p>The tool was originally developed by the <a rel="nofollow" class="external text" href="http://linuxtesting.org">Russian Linux Verification Center</a> at <a href="http://ispras.linuxbase.org/index.php/ISP_RAS_Company_Profile" title="ISP RAS Company Profile">ISPRAS</a> and since <b>1.93</b> version it's developed by the <a rel="nofollow" class="external text" href="http://www.rosalab.com/">ROSA Laboratory</a> in Russia. <a rel="nofollow" class="external text" href="http://www.linkedin.com/pub/andrey-ponomarenko/67/366/818">Andrey Ponomarenko</a> is the leader of this project. |
| </p> |
| <h2> <span class="mw-headline" id="Credits"> Credits </span></h2> |
| <p>We would like to thank <a href="http://ispras.linuxbase.org/index.php/Thanks" title="Thanks">everyone</a> who has contributed to the success of this project! |
| </p> |
| <h2> <span class="mw-headline" id="Articles"> Articles </span></h2> |
| <p>Here is the list of articles about shared libraries and binary compatibility: |
| </p> |
| <ol><li> <a rel="nofollow" class="external text" href="http://techbase.kde.org/Policies/Binary_Compatibility_Issues_With_C++"><b>“Binary Compatibility Issues With C++”</b></a>, KDE TechBase |
| </li><li> <a rel="nofollow" class="external text" href="http://techbase.kde.org/Policies/Binary_Compatibility_Examples"><b>“Binary Compatibility Examples”</b></a>, KDE TechBase |
| </li><li> <a rel="nofollow" class="external text" href="http://refspecs.linux-foundation.org/cxxabi-1.83.html"><b>"Itanium C++ ABI"</b></a>, linux-foundation.org |
| </li><li> <a rel="nofollow" class="external text" href="http://www.ros.org/reps/rep-0009.html"><b>"ABI Compatibility"</b></a>, Josh Faust |
| </li><li> <a rel="nofollow" class="external text" href="http://blog.famillecollet.com/post/2010/06/20/ABI-%3A-stability-check"><b>"ABI : stability check"</b></a>, Les RPM de Remi - Blog |
| </li><li> <a rel="nofollow" class="external text" href="http://www.agner.org/optimize/calling_conventions.pdf"><b>“Calling conventions for different C++ compilers and operating systems”</b></a>, Agner Fog |
| </li><li> <a rel="nofollow" class="external text" href="http://www.angelcode.com/dev/callconv/callconv.html"><b>"Calling conventions on the x86 platform"</b></a>, Andreas Jonsson |
| </li><li> <a rel="nofollow" class="external text" href="http://labs.qt.nokia.com/2009/08/12/some-thoughts-on-binary-compatibility/"><b>“Some thoughts on binary compatibility”</b></a>, Thiago Macieira |
| </li><li> <a rel="nofollow" class="external text" href="http://syrcose.ispras.ru/2009/files/02_paper.pdf"><b>"Binary Compatibility of C++ shared libraries on GNU/Linux"</b></a>, Pavel Shved, Denis Silakov |
| </li><li> <a rel="nofollow" class="external text" href="http://www.usenix.org/publications/library/proceedings/als00/2000papers/papers/full_papers/browndavid/browndavid_html/"><b>"Library Interface Versioning in Solaris and Linux"</b></a>, David J. Brown and Karl Runge |
| </li><li> <a rel="nofollow" class="external text" href="http://docs.hp.com/en/950/v4vers.pdf"><b>"Steps to Version Your Shared Library"</b></a>, hp.com |
| </li><li> <a rel="nofollow" class="external text" href="http://developer.apple.com/tools/mpw-tools/compilers/docs/abi.html"><b>"Macintosh C/C++ ABI Overview"</b></a>, developer.apple.com |
| </li><li> <a rel="nofollow" class="external text" href="http://chadaustin.me/cppinterface.html"><b>“Binary-compatible C++ Interfaces”</b></a>, Chad Austin |
| </li><li> <a rel="nofollow" class="external text" href="http://gcc.gnu.org/onlinedocs/libstdc++/manual/abi.html"><b>"ABI Policy and Guidelines"</b></a>, gnu.org |
| </li><li> <a rel="nofollow" class="external text" href="http://gcc.gnu.org/onlinedocs/gcc/Compatibility.html"><b>"Binary Compatibility"</b></a>, gnu.org |
| </li><li> <a rel="nofollow" class="external text" href="http://developers.sun.com/solaris/articles/CC_abi/CC_abi_content.html"><b>"Stability of the C++ ABI: Evolution of a Programing Language"</b></a>, Stephen Clamage |
| </li><li> <a rel="nofollow" class="external text" href="http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html#binarycompat"><b>"When binary compatibility breaks"</b></a>, Debian Library Packaging guide |
| </li><li> <a rel="nofollow" class="external text" href="http://techbase.kde.org/Policies/Library_Code_Policy"><b>“Library Code Policy”</b></a>, KDE TechBase |
| </li><li> <a rel="nofollow" class="external text" href="http://people.redhat.com/drepper/dsohowto.pdf"><b>"How To Write Shared Libraries"</b></a>, Ulrich Drepper |
| </li><li> <a rel="nofollow" class="external text" href="http://lookup.computerlanguage.com/host_app/search?cid=C000401&term=ABI"><b>"Application Binary Interface"</b></a>, Computer Desktop Encyclopedia |
| </li><li> <a rel="nofollow" class="external text" href="http://www.linux.org/docs/ldp/howto/Program-Library-HOWTO/shared-libraries.html"><b>“Program Library HOWTO”</b></a>, linux.org |
| </li><li> <a rel="nofollow" class="external text" href="http://plan99.net/~mike/writing-shared-libraries.html"><b>“Writing shared libraries”</b></a>, Mike Hearn |
| </li><li> <a rel="nofollow" class="external text" href="http://www.ayukov.com/essays/linuxdll.html"><b>"Shared libraries in Linux: growing pains or fundamental problem?"</b></a>, Sergey Ayukov |
| </li><li> <a rel="nofollow" class="external text" href="http://2f.ru/holy-wars/fbc.html"><b>“What's the Fragile Base Class (FBC) Problem?”</b></a>, Peter Potrebic |
| </li><li> <a rel="nofollow" class="external text" href="http://c2.com/cgi/wiki?FragileBinaryInterfaceProblem"><b>“Fragile Binary Interface Problem”</b></a>, Steven Newton |
| </li><li> <a rel="nofollow" class="external text" href="http://www.oocities.org/mrshrap/linker.html"><b>“The amazing world of library incompatibility”</b></a>, oocities.org |
| </li><li> <a rel="nofollow" class="external text" href="http://library.forum.nokia.com/index.jsp?topic=/S60_5th_Edition_Cpp_Developers_Library/GUID-35228542-8C95-4849-A73F-2B4F082F0C44/sdk/doc_source/faqSDK/faq_0444.html"><b>“The Theory of Binary Compatibility”</b></a>, Forum.Nokia |
| </li><li> <a rel="nofollow" class="external text" href="http://library.developer.nokia.com/index.jsp?topic=/S60_5th_Edition_Cpp_Developers_Library/GUID-35228542-8C95-4849-A73F-2B4F082F0C44/sdk/doc_source/ToolsAndUtilities94/BuildTools/bc.guide.html"><b>“How to control binary compatibility”</b></a>, Forum.Nokia |
| </li><li> <a rel="nofollow" class="external text" href="http://www.elpauer.org/?p=230"><b>“ABI compatibility in C++”</b></a>, elpauer.org |
| </li><li> <a rel="nofollow" class="external text" href="http://blogs.gentoo.org/mgorny/2012/08/20/the-impact-of-cxx-templates-on-library-abi/"><b>“The impact of C++ templates on library ABI”</b></a>, Michał Górny |
| </li><li> <a rel="nofollow" class="external text" href="http://sourceware.org/glibc/wiki/Testing/ABI_checker"><b>“ABI Compliance Checker Notes”</b></a>, sourceware.org |
| </li><li> <a rel="nofollow" class="external text" href="http://developer.symbian.org/wiki/index.php/Preserving_Compatibility"><b>"Preserving Compatibility"</b></a>, symbian.org |
| </li><li> <a rel="nofollow" class="external text" href="http://doi.ieeecomputersociety.org/10.1109/VALID.2010.27"><b>"Automated Verification of Shared Libraries for Backward Binary Compatibility"</b></a>, A. Ponomarenko and V. Rubanov, VALID 2010 |
| </li><li> <a rel="nofollow" class="external text" href="http://www.springerlink.com/content/905067689q7n0166/"><b>"Backward compatibility of software interfaces: Steps towards automatic verification"</b></a>, A. Ponomarenko and V. Rubanov, Programming and Computer Software 2012 |
| </li><li> <a rel="nofollow" class="external text" href="http://www.macieira.org/blog/2012/01/architectures-and-abis-detailed/"><b>"Architectures and ABIs detailed"</b></a>, Thiago Macieira's blog |
| </li><li> <a rel="nofollow" class="external text" href="http://accu.org/index.php/journals/1718"><b>"Interface Versioning in C++"</b></a>, ACCU |
| </li><li> <a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/gabi41.pdf"><b>"Generic ABI Standard"</b></a>, <a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/"><b>"ELF and ABI Standards"</b></a>, freestandards.org |
| </li><li> Processor ABI standards: <b><a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/abi386-4.pdf">Intel386</a></b>, <b><a rel="nofollow" class="external text" href="http://www.x86-64.org/documentation/abi.pdf">AMD64</a></b>, <b><a rel="nofollow" class="external text" href="http://infocenter.arm.com/help/topic/com.arm.doc.ihi0042d/IHI0042D_aapcs.pdf">ARM</a></b>, <b><a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/elfspec_ppc.pdf">PowerPC</a></b>, <b><a rel="nofollow" class="external text" href="http://download.boulder.ibm.com/ibmdl/pub/software/dw/linux390/docu/l390abi0.pdf">S/390</a></b>, <b><a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/IA64-SysV-psABI.pdf">Itanium</a></b>, <b><a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/mipsabi.pdf">MIPS</a></b>, <b><a rel="nofollow" class="external text" href="http://www.sparc.org/standards/psABI3rd.pdf">SPARC</a></b>, <b><a rel="nofollow" class="external text" href="http://refspecs.freestandards.org/elf/elf-pa.pdf">PA-RISK</a></b>, <b><a rel="nofollow" class="external text" href="http://www.linux-m32r.org/cmn/m32r/M32R-elf-abi.pdf">M32R</a></b> |
| </li><li> <a rel="nofollow" class="external text" href="http://science.webhostinggeeks.com/abi-compliance-checker"><b>Translation of this article to Serbo-Croatian</b></a>, Jovana Milutinovich |
| </li></ol> |
| |
| <!-- |
| NewPP limit report |
| Preprocessor node count: 148/1000000 |
| Post-expand include size: 0/2097152 bytes |
| Template argument size: 0/2097152 bytes |
| Expensive parser function count: 0/100 |
| --> |
| |
| <!-- Saved in parser cache with key rasispdb:pcache:idhash:2292-0!*!0!!en!*!* and timestamp 20130730150425 --> |
| </div></div></div></div></div></body></html> |
