From Fedora Project Wiki

Line 1: Line 1:
== Requirements ==
+
== Requirements for comparing ABIs of binaries contained in ''two versions of a package'' ==
  
 
It is assumed that you already have a [[How_to_create_an_RPM_package#Preparing_your_system|development environment]] setup which can build packages. Other than that all that is required is the tool [https://apps.fedoraproject.org/packages/abi-compliance-checker abi-compliance-checker].
 
It is assumed that you already have a [[How_to_create_an_RPM_package#Preparing_your_system|development environment]] setup which can build packages. Other than that all that is required is the tool [https://apps.fedoraproject.org/packages/abi-compliance-checker abi-compliance-checker].
 +
 +
If you are willing to compare the ABIs of binaries that are carried in packages that you have at hand, then here are the command to type to install the required tools:
 +
 +
<pre>
 +
$ sudo yum install abi-compliance-checker
 +
(or as root)
 +
# yum install abi-compliance-checker
 +
</pre>
 +
 +
== Requirements for comparing ABIs of ''two versions of a binary'' ==
 +
 +
If you are willing to compare the ABIs of two binaries, then here are the commands to type to install the required tools:
  
 
<pre>
 
<pre>
Line 7: Line 19:
 
(or as root)
 
(or as root)
 
# yum install abi-compliance-checker
 
# yum install abi-compliance-checker
 +
 +
$ sudo yum install abi-dumper
 +
(or as root)
 +
# yum install abi-dumper
 
</pre>
 
</pre>
  
== Procedure ==
+
== Procedure for comparing the ABIs of two versions of a ''package'' ==
  
 
<code>abi-compliance-checker</code> has a lot of options and while it's not difficult to use it's not necessarily intuitive either. This example is one way to use the tool and should be considered the best practice.
 
<code>abi-compliance-checker</code> has a lot of options and while it's not difficult to use it's not necessarily intuitive either. This example is one way to use the tool and should be considered the best practice.
Line 63: Line 79:
  
 
The html report will be created in a directory under <code>compat_reports/<package>/<version_old>_to_<version_new></code>.
 
The html report will be created in a directory under <code>compat_reports/<package>/<version_old>_to_<version_new></code>.
 +
 +
== procedure for comparing the ABIs of two ''Elf binaries'' ==
 +
 +
Note that the libraries should be compiled with debug info generation turned on.  For GCC compilers, the option to use is <code>'-g'</code>.
 +
 +
=== Step 1: Generate a dump of the ABIs of the two binaries ===
 +
 +
Create ABI dumps for both binaries versions using the ABI Dumper tool:
 +
 +
<pre>
 +
$ abi-dumper <first-binary-version> -o first-binary.dump -lver 0
 +
$ abi-dumper <second-binary-version> -o second-binary.dump -lver 1
 +
</pre>
 +
 +
=== Step 2: Compare the ABI dumps of the two binaries ===
 +
 +
Compare the ABIs by comparing the ABI dumps:
 +
 +
<pre>
 +
$ abi-compliance-checker -l <an-arbitrary-name-used-in-the-report> -old <first-binary-version>.dump -new <second-binary-version>.dump 
 +
</pre>
 +
 +
The HTML report about the ABI changes will be generated to:
 +
 +
<pre>
 +
compat_reports/<an-arbitrary-name-used-in-the-report>/X_to_1/compat_report.html
 +
</pre>
  
 
== Tips & Tricks ==
 
== Tips & Tricks ==

Revision as of 09:05, 20 November 2015

Requirements for comparing ABIs of binaries contained in two versions of a package

It is assumed that you already have a development environment setup which can build packages. Other than that all that is required is the tool abi-compliance-checker.

If you are willing to compare the ABIs of binaries that are carried in packages that you have at hand, then here are the command to type to install the required tools:

$ sudo yum install abi-compliance-checker
(or as root)
# yum install abi-compliance-checker

Requirements for comparing ABIs of two versions of a binary

If you are willing to compare the ABIs of two binaries, then here are the commands to type to install the required tools:

$ sudo yum install abi-compliance-checker
(or as root)
# yum install abi-compliance-checker

$ sudo yum install abi-dumper
(or as root)
# yum install abi-dumper

Procedure for comparing the ABIs of two versions of a package

abi-compliance-checker has a lot of options and while it's not difficult to use it's not necessarily intuitive either. This example is one way to use the tool and should be considered the best practice.

Step 1: Preparing

First you need to unpack the packages to a location. You can use the these commands directly or add these to a shell script which will be called rpmunpack:

#!/bin/bash

if [ ! -n "$1" ]
then
  echo "Unpacks an RPM into the current directory."
  echo ""
  echo "Usage: `basename $0` <package1> [package2]..."
fi

for file in $*; do
rpm2cpio $file | cpio -idmv
done

Now create a directory structure and unpack the packages:

$ mkdir -p <package>/<version_old>
$ mkdir -p <package>/<version_new>
$ cd <package>/<version_old>
$ rpmunpack <package>-<version_old> <package>-<version_old>-devel
$ cd ../<package>/<version_new>
$ rpmunpack <package>-<version_new> <package>-<version_new>-devel
$ cd ..

Step 2: Dump the ABIs to a file

By default abi-compliance-checker will assign the version based on the directories created previously. If it doesn't get it right use the -vnum option to override it.

Execute the following command for both packages:

$ abi-compliance-checker -l <package> -dump <path to unpacked RPM>

The -l option needs to stay the same for all operations and is the name used in the resultant html report.

Step 3: Compare the to ABI dumps

The ABI dumps will be created in a sub-directory of where abi-compliance-checker was run, abi_dumps/<package>. To compare the to ABI dumps:

$ abi-compliance-checker -l <package> -old abi_dumps/<package>/<package>_<version_old>.abi.tar.gz -new abi_dumps/<package>/<package>_<version_old>.abi.tar.gz

The html report will be created in a directory under compat_reports/<package>/<version_old>_to_<version_new>.

procedure for comparing the ABIs of two Elf binaries

Note that the libraries should be compiled with debug info generation turned on. For GCC compilers, the option to use is '-g'.

Step 1: Generate a dump of the ABIs of the two binaries

Create ABI dumps for both binaries versions using the ABI Dumper tool:

$ abi-dumper <first-binary-version> -o first-binary.dump -lver 0 
$ abi-dumper <second-binary-version> -o second-binary.dump -lver 1 

Step 2: Compare the ABI dumps of the two binaries

Compare the ABIs by comparing the ABI dumps:

$ abi-compliance-checker -l <an-arbitrary-name-used-in-the-report> -old <first-binary-version>.dump -new <second-binary-version>.dump  

The HTML report about the ABI changes will be generated to:

compat_reports/<an-arbitrary-name-used-in-the-report>/X_to_1/compat_report.html

Tips & Tricks

Important.png
False Positives
abi-compliance-checker is just a tool and doesn't always get it right. The results need to be reviewed as false positives are common. This happens frequently if the old package was compiled with a different version of the compiler or different flags were used. To minimize this, it can be beneficial to rebuild the older package using the same environment as the new package.

ABI dumps error out

This often happens when upstream installs headers for other platforms. Adding the -tolerant option can often work around this problem. As a last resort, simply look through the log and remove the offending header.

External links

Deprecated:

New project at ABI Laboratory: