ABI : stability check
Before upgrading a library, it is mandatory to ensure that ABI is stable.
Here is a sample case.
When ABI is stable, an application build with version N of a library will works with version N+1. This allow update without need to rebuild a lot of packages.
For example, when an application use the MySQL client, it is linked with libmysqlclient.so. In reality, it will use the libmysqlclient.so.16 library. This version "16" (soname) will be the same for all the MySQL 5.1 libraries. (MySQL 5.0 provides libmysqlclient.so.15). ABI stability is guaranteed. RPM implement this check using dependencies on the versionned name of the used libraries.
$ rpm -q --provides mysql-libs
$ rpm -q --requires mysql++
Normally, it's the developer job to ensure, upstream, this stability. When a change is necessary the library version must change (no link with the sources version). The package maintainer must rebuild all applications which use it or provide a compatibility librayry.
Of course, this is a good practice, for a packager, to check this stability before pushing an update in the distribution.
For the update of new version 3.1.0 of mysql++, I've done this check and write this blog's entry to keep a reminder on the used method, and share it with others.
I used a simple and free tool : ABI compliance checker and the trivial test of running a simple application.
With version 3.0.9
Build the examples provided (without the version check provided)
$ su -lc "yum install mysql++-devel"
$ cp -r /usr/share/doc/mysql++-devel-3.0.9/examples /tmp/ex309
$ cd /tmp/ex309
$ vi resetdb.cpp # delete the return 1 after the version check
Install the tool and run the analysis for version 3.0.9
$ wget http://ispras.linux-foundation.org/images/6/6e/Abi-compliance-checker-1.17.2.tar.gz
$ tar xzf Abi-compliance-checker-1.17.2.tar.gz
$ cd abi-compliance-checker-1.17.2
$ ./abi-compliance-checker.pl -d
$ mv lib_ver.xml my309.xml
$ gedit mysql++309.xml
$ abi-compliance-checker -l mysql++ -dump_abi mysql++309.xml
mysql++309.xml file, describing the library, is quite simple:
<?xml version="1.0" encoding="UTF-8"?>
The result file will be used later.
With version 3.1.0
update the library. Examples must still works.
$ su -lc "rpm -Uvh mysql++*3.1.0*"
$ cd /tmp/ex309
$ ./simple1 -u toto -p secret
$ ./cpool -u toto -p secret
Segmentation fault (core dumped)
It seems there is a problem.
Run the analysis
$ cp mysql++309.xml mysql++310.xml
$ gedit mysql++310.xml
$ abi-compliance-checker -l mysql++ -dump_abi mysql++310.xml
Run comparison of the 2 results.
$ ./abi-compliance-checker.pl -l mysql++ \
-d1 abi_dumps/mysql++/mysql++_3.0.9.abi.tar.gz \
$ firefox file:$PWD/compat_reports/mysql++/3.0.9_to_3.1.0/abi_compat_report.html
Here is the report : ABI compliance report for the library mysql++ from version 3.0.9 to 3.1.0 on x86_64
In the case, it confirm the ABI breakage between the 2 versions. So, of course, the update in the stable repository will not happen.
When I start maintaining this package (version 2.x), the library was even not versionned. So I have to work with developers to include this feature. Now I need to convince them to respect the pratices.