Differences between revisions 24 and 30 (spanning 6 versions)
Revision 24 as of 2022-08-14 09:28:45
Size: 6214
Editor: ZugSchlus
Comment: give example for Build-Depends-Package
Revision 30 as of 2022-09-12 01:18:46
Size: 6551
Editor: PaulWise
Comment: add the KDE team docs, reorganise Russ' links
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
<<TableOfContents>>
Line 5: Line 7:
Maintainers should not drop symbols file directly into Debian without understanding the mechanism for packaging these symbols files. Please read this page carefully (and the manual pages of dpkg-shlibdeps / dpkg-gensymbols) to understand the various issues. Maintainers should not drop symbols file directly into Debian without understanding the mechanism for packaging these symbols files. Please read this page carefully (and the manual pages of [[DebianMan:dpkg-shlibdeps]]/[[DebianMan:dpkg-gensymbols]]) to understand the various issues.
Line 9: Line 11:
## mole service has been discontinued http://bugs.debian.org/543640 ## mole service has been discontinued https://bugs.debian.org/543640
Line 14: Line 16:
$ dpkg-deb -x libfoo_<version>-<rev>.deb /tmp/libfoo
$ dpkg-gensymbols -v<version> -plibfoo -P/tmp/libfoo -Olibfoo.symbols
$ dpkg-deb -x libfoo_<version>-<rev>.deb libfoo
$ dpkg-gensymbols -v<version> -plibfoo -Plibfoo -Olibfoo.symbols
Line 20: Line 22:
You can create a symbols file which contains the minimal version by scanning successively oldstable + stable + testing + unstable versions (or all versions from [[http://snapshot.debian.org|Debian snapshots]]) of the library as above. You can create a symbols file which contains the minimal version by scanning successively oldstable + stable + testing + unstable versions (or all versions from [[https://snapshot.debian.org|Debian snapshots]]) of the library as above.
Line 24: Line 26:
 * Please verify that there are no cases of a backwards-compatible ABI extension that would require a version bump for some symbols. For example when a function accepts new values (in existing parameters) that were previously rejected. You need to check the upstream !ChangeLog to discoverhttps://salsa.debian.org/debian/gensio.git such cases.  * Please verify that there are no cases of a backwards-compatible ABI extension that would require a version bump for some symbols. 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.
Line 51: Line 53:
Line 60: Line 61:
Essays from Russ Allbery about symbols files in C++ libraries:
 * [[http://www.eyrie.org/~eagle/journal/2012-01/008.html|Summary of C++ symbols experience]]
 * [[http
://www.eyrie.org/~eagle/journal/2012-02/001.html|C++ symbols wrapup]]

Documentation
about symbols files in C++ libraries:
 * Russ Allbery's essays [[https://www.eyrie.org/~eagle/journal/2012-01/008.html|Summary of C++ symbols experience]] and [[https://www.eyrie.org/~eagle/journal/2012-02/001.html|C++ symbols wrapup]]
 * Debian KDE Team's [[https://qt-kde-team.pages.debian.net/symbolfiles.html|Working with symbols files]]
Line 88: Line 90:
Other tags and symbol patterns are: optional, arch, ignore-blacklist, symver and regex. See man dpkg-gensymbols(1) and deb-src-symbols(5) for further reference. Other tags and symbol patterns are: optional, arch, ignore-blacklist, symver and regex. See the [[DebianMan:dpkg-gensymbols|dpkg-gensymbols(1)]] and [[DebianMan:deb-src-symbols|deb-src-symbols(5)]] manual pages for further reference.
Line 94: Line 96:
Line 112: Line 113:
 * deb-src-symbols(5)
 * deb-symbols(5)
 * dpkg-gensymbols(1)
 * c++filt(1)
 * [[Projects/ImprovedDpkgShlibdeps]]
 * [[DebianMan:deb-src-symbols|deb-src-symbols(5)]]
 * [[DebianMan:deb-symbols|deb-symbols(5)]]
 * [[DebianMan:dpkg-gensymbols|dpkg-gensymbols(1)]]
 * [[DebianMan:c++filt|c++filt(1)]]

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 for packaging these symbols files. Please read this page carefully (and the manual pages of dpkg-shlibdeps/dpkg-gensymbols) to understand the various issues.

How to manage the content of symbols files

The initial list of symbols for a previously built library package, e.g., libfoo can be obtained as follows.

$ dpkg-deb -x libfoo_<version>-<rev>.deb libfoo
$ dpkg-gensymbols -v<version> -plibfoo -Plibfoo -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.

One needs to also check the following;

  • Please verify that there are no cases of a backwards-compatible ABI extension that would require a version bump for some symbols. 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.

Build-Depends-Packages

The "Build-Depends-Packages" field is entered for each library in the symbols file and it is part of the library definition. For example:

libfoo.so.0 libfoo0 #MINVER#
* Build-Depends-Package: libfoo-dev
 alloc_foo_avahi_poll@Base 2.5.1
 ax25_addr_encode@Base 2.5.1
 ax25_addr_encode_len@Base 2.5.1
libfoo_python_swig.so.0 libfoo0 #MINVER#
* Build-Depends-Package: libfoo-dev
 check_os_funcs_free@Base 2.5.1
 foo_python_deref_swig_cb_val@Base 2.5.1
 foo_python_ref_swig_cb_i@Base 2.5.1

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.

C++ libraries

For C++ libraries it is often better not to ship symbols files.

Documentation 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 patterns are: optional, arch, ignore-blacklist, symver and regex. See the dpkg-gensymbols(1) and deb-src-symbols(5) manual pages for further reference.

Architecture dependent symbols can be written in the file as

 (arch=foo,bar|c++)"...."

Proper visibility for C++ symbols

If your upstream is on board with this, they should be building with -fvisibility=hidden, and decorate everything intentionally public with a macro that (when building with gcc or clang) expands to __attribute__((__visibility__("default"))).

Some upstreams will be doing something similar already, because they are portable to Windows and need to decorate public symbols with __declspec(dllexport) on Windows.

For further information please read:

Literature