If you maintain packages written in C or C++, chances are you're already familiar with the following tools:
If you're not, please click the links and read more about them, they're great tools.
There are two modes in which abi-compliance-checker may be executed:
-
It may run in a mode that requires binaries/libraries to be compiled including debuginfo. This mode is more accurate, and it's this mode that
py-abi-compliance-checkerfocuses on. -
It may also run in a mode that doesn't require debuginfo. This mode is less accurate, but also good, the downsides are:
- It requires specially crafted XML files.
- It requires your host system to compile headers for the target OS you're trying to analyse. If there's enough of a gap between your system and the target system, it becomes a hassle.
py-abi-compliance-checker is simply a wrapper around abi-dumper and abi-compliance-checker that makes them much easier to use for large-scale API/ABI comparisons.
py-abi-compliance-checker generates a very detailed report with the following information:
- All headers.
- All shared objects.
- All debuginfo files.
- It then relates all shared objects to their debuginfo files. If a debuginfo file can't be located, it exits.
- It then compares all shared objects across V1 and V2, the versions we're trying to compare, reporting if any shared objects are in V1, but are not in V2, and vice-versa. So we get insights if any
.sofiles have been deprecated across versions. - It then invokes
abi-dumperand creates the ABI dump for each.sothat is present in both V1 and V2. - And then it invokes
abi-compliance-checkerfor each ABI dump, finally giving us the HTML reports, which are all neatly named.
-
Install
abi-compliance-checkerandabi-dumperusing your package manager of choice. -
Clone this repository, maybe place its scripts in your
$PATH. Make sure they're executable.extract-rpmis a tiny, convenient Bash script that extracts RPMs. -
If you're running Debian, Ubuntu, or some other system, you just need to be able to extract the package files to a single location, populating a given directory for the specific version of the package you're trying to compare.
-
For example, if we're comparing the differences between 4 packages:
perl-5.26.rpm/perl-debuginfo-5.26.rpmandperl-5.28.rpm/perl-debuginfo-5.28.rpm, we could extract the contents ofperl-5.26.rpm/perl-debuginfo-5.26.rpmto a directory namedperl-5.26, and the contents ofperl-5.28.rpm/perl-debuginfo-5.28.rpmto a directory namedperl-5.28. -
We should now have two directories:
perl-5.26andperl-5.28, with those packages' contents. -
Now you can finally use this tool :D
The syntax is:
py-abi-compliance-checker <package name> <version 1> <directory with version 1 files> <version 2> <directory with version 2 files>.So we could do:
py-abi-compliance-checker perl 5.26 perl-5.26 5.28 perl-5.28. -
All output data will be written inside a newly created directory named
perl-5.26-to-5.28.The
.jsonfiles contain a report generated bypy-abi-compliance-checkeritself. It shows all the data that was found by the tool itself, and that was used for the analysis.The
htmldirectory contains the HTML reports generated byabi-compliance-checker. Theabidumpsdirectory contains all ABI dumps generated byabi-dumper.
-
If you're running openSUSE or SLE, you'll be able to retrieve the RPMs using
osc getbinaries --debuginfo. Suppose we wanted to compare Perl5 from Factory to Perl5 from SLE-15-SP5:For Factory:
osc getbinaries openSUSE:Factory perl standard x86_64 --debuginfomv binaries perl-factorycd perl-factoryextract-rpm *.rpmcd ..For SUSE:SLE-15-SP5:Update:
isc getbinaries SUSE:SLE-15-SP5:Update perl standard x86_64 --debuginfomv binaries perl-sle15-sp5cd perl-sle15-sp5extract-rpm *.rpmcd .. -
And then run this tool:
py-abi-compliance-checker perl 5.26.1 perl-sle15-sp5 5.38.2 perl-factory.