Symbols Files

Updated 2,603 Days AgoPublic

Actions

WIP help for dealing with symbols files.

The big picture

TODO

Interesting chat about symbols files (vol I): https://irclogs.ubuntu.com/2017/02/22/%23kubuntu-devel.html#t15:31
Interesting chat about symbols files (vol II): https://irclogs.ubuntu.com/2017/02/27/%23kubuntu-devel.html#t16:06

Debian Library Packaging Guide

https://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html

Debian Policy for shared libraries

https://www.debian.org/doc/debian-policy/ch-sharedlibs.html

"Working with symbols files" section from the Debian Qt/KDE team webpage

https://pkg-kde.alioth.debian.org/symbolfiles.html

KDE depeloper's documentation about Binary Compatibility

https://community.kde.org/Policies/Binary_Compatibility_Issues_With_C%2B%2B

It's specially interesting the "The Do's and Don'ts" section from that document.

The Debian ABI Manager

The Debian ABI Manager is an invention to bump the SONAME of a library. This invention can be used to bump the SONAME of a library with:

1. Binary incompatible changes compared with previous version in the Ubuntu repositories
2. No SONAME bump done by upstream KDE developers

Manual for the Debian ABI Manager

If you install the pkg-kde-tools package you can read the /usr/share/doc/pkg-kde-tools/README.DebianABIManager file, which provides a section named "BC handling with DebianABIManager" explaining how to use the Debian ABI manager.

Origins of the Debian ABI Manager

There is an old thread in the pkg-kde-talk which explains the origins of the abi manager: http://lists.alioth.debian.org/pipermail/pkg-kde-talk/2011-March/001574.html It's specially interesting how it explains the previous technique to handle ABI breaks and one of its most important issues:

1. [ Package level ]. Rename the library package and add Breaks/Replaces against the previous versions, keep library SONAME (and filenames) unchanged.
   
   [...]
   
   Cons:
   
   a) apt unfriendly because two library packages cannot be co-installed. Library packages are typically deep in the dependency chain so apt may require to force removal/installation in some cases;
   
   [...]

Examples of usage of the debian ABI Manager

• https://git.launchpad.net/~kubuntu-packagers/kubuntu-packaging/+git/pimcommon/commit/?id=ff3c98997f83738aa3cd0fea3fcc050b172bbdf9
• https://git.launchpad.net/~kubuntu-packagers/kubuntu-packaging/+git/libkleo/commit/?id=923909dcab2a88f90855d4d2df48465c18eb2795

When you must NOT use the ABI manager

In general, you must not use the ABI manager for KDE Frameworks libraries. By KDE rules, developers are not allowed to make binary incompatible changes, therefore if there's an ABI break in any Frameworks library, that has to be an accident. So the correct solution for Frameworks would be fixing that accident sending KDE developers a patch; example:
https://git.reviewboard.kde.org/r/129032/

Debian-ABI-managered libraries checklist

So, lets supose you already checked there's an ABI break and you decided to use the Debian ABI manager to handle a library, following the ABI manager manual mentioned above. To make sure you have done everything you have to do to manage your ABI break successfully you can check these things (in order):

1. Add a patch called enable_debianabimanager.diff
   • This patch must add this line at the bottom of the main CMakeLists.txt:
   • include(/usr/share/pkg-kde-tools/cmake/DebianABIManager.cmake)
   • Note: don't forget to do "git add debian/patches" before commiting to git ;)
2. Add the ABI management fields to debian/control
   • X-Debian-ABI: <abi_version>
   • X-CMake-Target: <cmake_target_for_the_managed_lib>
     • To find out the cmake target you have to inspect the CMakeLists.txt, usually the src/CMakeLists.txt is the right one. Look for a line like this one:
     • add_library(KF5IncidenceEditor ${incidenceeditors_ng_desktop_LIB_SRCS})
     • For that example ↑ X-CMake-Target would be KF5IncidenceEditor
3. Rename the package to, for instance, libfoo5abiX (if the previous SOVERSION was 5, the final X is the same version you have set with 'X-Debian-ABI' in the previous step). Don't forget to update also the -dev dependency and any other intra-dependencies in the debian/control file.
4. Rename the *.install file and update its contents
5. Update the symbols file, to do this you can proceeed this way:
   • Rename the file name
   • Update the contents of the second line of the symbols file to match the new library and package names
   • Rebuild the package in a PPA (it will fail due to symbols mismatch)
   • Update the symbols file with the failing build log
   • Rebuild the package again in the PPA with the updated symbols file; this time it should build fine.
6. Update the debian/changelog explaining the change