How to use symbols files
This page is meant to collect some generic recommendations for handling symbols files. It's related to the improved dpkg-shlibdeps project.
Maintainers should not drop symbols file directly into Debian without understanding the mechanism behind. Please read this page carefully (and the manual pages of dpkg-shlibdeps / dpkg-gensymbols) to have a good grasp on the various issues that need to be taken into account.
How to manage the content of symbols files
The initial list of symbols for a previously build library package, e.g., libfoo can be obtained as follows.
$ dpkg-deb -x libfoo_<version>-<rev>.deb /tmp/libfoo $ dpkg-gensymbols -v<version> -plibfoo -P/tmp/libfoo -Olibfoo.symbols
If a library package contains multiple versions of library files, you may need to specify the path to each of them with -e for each version instead of using -P.
You can create a symbols file which contains the minimal version by scanning successively oldstable + stable + testing + unstable versions (or all versions from Debian snapshots) of the library as above.
In addition to this, we need to check the following.
You want to verify if there are no cases of backwards-compatible ABI extension that would require a version bump for some symbols. This is the case for example when a function accepts new values (in existing parameters) that were previously rejected. You need to check the upstream ChangeLog to discover such cases.
You probably want to get rid of the Debian revision in all the versions listed in symbols files. This will make it easier to backport the package because otherwise you might generate dependencies which are too strong if the version of the backported library is smaller than the version indicated in the symbols files (ex: 2.10-1~bpo40+1 << 2.10-1).
Check the list of symbols exported by the library
If you find (on some arches) symbols that are exported which are not supposed to be public, you must not use symbols versioning at all. You might want to update the libtool scripts of your package from the latest version in Debian to fix the problem. There are old libtool versions which are not doing their job properly on some arches.
If your library exports private symbols, you might want to discuss with upstream to implement a version script to fix this. For libtool using packages, it can be easily generated using libtool's -export-symbols and -export-symbols-regex options.
Be responsive to porters
In some cases, the usage of symbols file might create problems to unofficial architectures. Be kind to them and incorporate quickly their patches, or offer them to NMU your package if you're busy.
See also about C++
Essays from Russ Allbery about symbols files in C++ libraries:
In essence from above one can apply C++ filter to the generated symbols to ease maintenance and understanding:
$ cat libfoo.symbols libqtubuntu_sensors.so.1 qtubuntu-sensors #MINVER# _ZN17OrientationSensor11qt_metacallEN11QMetaObject4CallEiPPv@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensor11qt_metacastEPKc@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensor16staticMetaObjectE@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensor4typeE@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensorD0Ev@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensorD1Ev@Base 0.5.1daily13.04.16ubuntu.unity.next _ZN17OrientationSensorD2Ev@Base 0.5.1daily13.04.16ubuntu.unity.next $ sed 's/ \(_.*\) \(.*\)/ (c++)"\1" \2/' libfoo.symbols | c++filt libqtubuntu_sensors.so.1 qtubuntu-sensors #MINVER# (c++)"OrientationSensor::qt_metacall(QMetaObject::Call, int, void**)@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::qt_metacast(char const*)@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::staticMetaObject@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::type@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::~OrientationSensor()@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::~OrientationSensor()@Base" 0.5.1daily13.04.16ubuntu.unity.next (c++)"OrientationSensor::~OrientationSensor()@Base" 0.5.1daily13.04.16ubuntu.unity.next
Other tags and symbol patters are: optional, arch, ignore-blacklist, symver and regex. See man dpkg-gensymbols(1) for further reference.