[ome-devel] C++ library versioning

[Roger Leigh]

Briefly mentioned this when chatting with Josh earlier.  Here I've
double-checked what the current state of things is for 5.1 WRT ABI
versioning.

% ls -l /tmp/testinst/lib/*.so*
lrwxr-xr-x  1 rleigh  wheel        26 Mar 25 22:30
/tmp/testinst/lib/libome-bioformats.so -> libome-bioformats.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel   2808045 Mar 25 22:26
/tmp/testinst/lib/libome-bioformats.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        22 Mar 25 22:30
/tmp/testinst/lib/libome-common.so -> libome-common.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel    325002 Mar 25 22:23
/tmp/testinst/lib/libome-common.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        25 Mar 25 22:30
/tmp/testinst/lib/libome-qtwidgets.so -> libome-qtwidgets.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel    597844 Mar 25 22:27
/tmp/testinst/lib/libome-qtwidgets.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        19 Mar 25 22:30
/tmp/testinst/lib/libome-xml.so -> libome-xml.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel  13517916 Mar 25 22:25
/tmp/testinst/lib/libome-xml.so.5.1.0

% for lib in /tmp/testinst/lib/*.so.5.1.0; do echo "$lib"; echo -n '
'; objdump -p "$lib" | grep SONAME; done
/tmp/testinst/lib/libome-bioformats.so.5.1.0
       SONAME      libome-bioformats.so.5.1.0
/tmp/testinst/lib/libome-common.so.5.1.0
       SONAME      libome-common.so.5.1.0
/tmp/testinst/lib/libome-qtwidgets.so.5.1.0
       SONAME      libome-qtwidgets.so.5.1.0
/tmp/testinst/lib/libome-xml.so.5.1.0
       SONAME      libome-xml.so.5.1.0

As you can see, the DT_SONAME is the same as the library name.  We don't
have a symlink for the SONAME, i.e. libome-bioformats.so.5 linking to
libome-bioformats.so.5 with the SONAME set to libome-bioformats.so.5.
The implication of this is that every point release will break the
ABI--you'll need to relink your code against the new version of the
library, though it will certainly be possible to have multiple versions
of the library installed at the same time.

This is due to doing this for each library:
set_target_properties(ome-bioformats PROPERTIES VERSION
${OME_VERSION_SHORT})

If we change this by setting the SOVERSION explicitly:
set_target_properties(ome-bioformats PROPERTIES VERSION
${OME_VERSION_SHORT} SOVERSION ${OME_VERSION_MAJOR})

% ls -l /tmp/testinst/lib/*.so*
lrwxr-xr-x  1 rleigh  wheel        22 Mar 25 23:03
/tmp/testinst/lib/libome-bioformats.so -> libome-bioformats.so.5
lrwxr-xr-x  1 rleigh  wheel        26 Mar 25 23:03
/tmp/testinst/lib/libome-bioformats.so.5 -> libome-bioformats.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel   2808029 Mar 25 22:55
/tmp/testinst/lib/libome-bioformats.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        18 Mar 25 23:03
/tmp/testinst/lib/libome-common.so -> libome-common.so.5
lrwxr-xr-x  1 rleigh  wheel        22 Mar 25 23:03
/tmp/testinst/lib/libome-common.so.5 -> libome-common.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel    325002 Mar 25 22:52
/tmp/testinst/lib/libome-common.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        21 Mar 25 23:03
/tmp/testinst/lib/libome-qtwidgets.so -> libome-qtwidgets.so.5
lrwxr-xr-x  1 rleigh  wheel        25 Mar 25 23:03
/tmp/testinst/lib/libome-qtwidgets.so.5 -> libome-qtwidgets.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel    597829 Mar 25 22:56
/tmp/testinst/lib/libome-qtwidgets.so.5.1.0
lrwxr-xr-x  1 rleigh  wheel        15 Mar 25 23:03
/tmp/testinst/lib/libome-xml.so -> libome-xml.so.5
lrwxr-xr-x  1 rleigh  wheel        19 Mar 25 23:03
/tmp/testinst/lib/libome-xml.so.5 -> libome-xml.so.5.1.0
-rwxr-xr-x  1 rleigh  wheel  13518044 Mar 25 22:55
/tmp/testinst/lib/libome-xml.so.5.1.0

% for lib in /tmp/testinst/lib/*.so.5.1.0; do echo $lib; echo -n '    ';
objdump -p $lib | grep SONAME; done
/tmp/testinst/lib/libome-bioformats.so.5.1.0
       SONAME      libome-bioformats.so.5
/tmp/testinst/lib/libome-common.so.5.1.0
       SONAME      libome-common.so.5
/tmp/testinst/lib/libome-qtwidgets.so.5.1.0
       SONAME      libome-qtwidgets.so.5
/tmp/testinst/lib/libome-xml.so.5.1.0
       SONAME      libome-xml.so.5

Our options really come down to
- continue without SOVERSION at least for 5.1.x; this means we break ABI
with every point release, but we aren't guaranteeing a stable API for
5.1, so this might be the right thing to do
- use SOVERSION as above; since we're using the release version as the
library version, this implies bumping the major version for any
incompatible change and so might be undesirable while coupled to the
OMERO version
- use SOVERSION with a completely separate versioning scheme from the
release version; do-able but requires continual diligence to update it
correctly for every release

Additional considerations are handling the generated OME-XML which can
easily break ABI and require a major version bump with trivial schema
changes, since this is exposed in the interfaces of the other libraries,
their versions will also need to be changed as well.

I think what we're doing right now is probably the right choice for the
moment.  It does make things a bit annoying for end users who will need
to rebuild/link their code against new releases rather than having it
just work, but it does mean we have the flexibility to correct mistakes
as it becomes more widely used.


Regards,
Roger

The University of Dundee is a registered Scottish Charity, No: SC015096