Differences between revisions 4 and 5
Revision 4 as of 2007-11-21 08:18:39
Size: 2303
Comment:
Revision 5 as of 2007-12-14 08:18:07
Size: 2362
Comment: point to the man pages too
Deletions are marked like this. Additions are marked like this.
Line 5: Line 5:
Maintainers should not drop symbols file directly into debian/ without understanding the mechanisms behind. Please read carefull this page to have a good grasp on the various issues that need to be taken into account. Maintainers should not drop symbols file directly into debian/ without understanding the mechanisms behind. Please read carefull this page (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 use symbols files

This page is meant to collect some generic recommendations for handling symbols files. It's related to the [wiki:Projects/ImprovedDpkgShlibdeps improved dpkg-shlibdeps project].

Maintainers should not drop symbols file directly into debian/ without understanding the mechanisms behind. Please read carefull this page (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.

Check the content of symbols files

[http://qa.debian.org/cgi-bin/mole/seedsymbols/ Pre-generated files on mole] associate to each symbol the first version of the package where the symbol has appeared. However symbols files are supposed to contain the minimal version for the dependency that we want when we know that the application is using this symbol.

  • 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 exitsing 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 might want to update the libtool scripts of your package from the latest version in Debian. 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.