Re: Shishi/GSS no-symbols-control-file lintian warning

[Russ Allbery]

Hi Simon,

I'm sorry it took me so long to reply to this message.  It got stuck in my
backlog and got put off due to a very chaotic last quarter of last year.

Simon Josefsson <address@hidden> writes:

> Hi Russ.  I am building new Shishi/GSS packages (don't worry, I won't
> upload to unstable until after lenny has been released) and ran into:
>
> I: libgss0: no-symbols-control-file usr/lib/libgss.so.0.0.24

> I tried to read up about this...  I am able to generate a symbols list
> using 'dpkg-gensymbols -plibgss0 -Ofoo':

You should check the generated symbols file against the one that was done
in the archive-wide symbols file run by mole:

    http://qa.debian.org/cgi-bin/mole/seedsymbols/

just to be sure that there aren't any weird architecture-dependent issues,
although there shouldn't be for a C library.

> However, I haven't found a simple to understand explanation of best
> practices on how to modify this file.  deb-symbols man page doesn't help
> me, nor does <http://wiki.debian.org/Projects/ImprovedDpkgShlibdeps>.

http://wiki.debian.org/UsingSymbolsFiles is the new URL that explains how
to implement this.  I'm going to add that as an additional reference in
Lintian for the no-symbols-control-file tag, since it's somewhat easier to
follow than the dpkg-gensymbols(1) man page and includes a link to mole.

> I tried to just put the output above into libgss0.dev, however that
> resulted in lintian warnings:

> E: libgss0: symbols-file-contains-current-version-with-debian-revision on 
> symbol address@hidden and 90 others

> IMHO, dpkg-gensymbols could have avoided adding the -1 itself...
> Anyway, I removed the '-1' part in the .symbols file, rebuild the
> packages, and now lintian is quiet.

The reason why it doesn't do this itself is because it doesn't know for
sure when the symbol was introduced (it could have been introduced in a
Debian revision), and more fundamentally, what it really would like you to
do is update the symbols file to reflect when the symbol first appeared in
Debian.

The point of symbols files is to allow relaxation of shared library
dependencies to make it easier to install binaries that would function
properly with older versions of libraries.  Currently, in the Debian
shlibs system, you have to bump the interpackage dependency whenever a new
symbol is introduced, since at that point other packages may start using
that symbol and hence require at least that version of the library.
Symbols files provide the interpackage dependency system with much more
information and allow them to relax the dependency to the first version of
the shared library containing all the symbols that theh binary actually
uses.  This means that introducing a new, infrequently used symbol doesn't
cause all packages to have an unnecessarily tight dependency.

> However questions remains:
>
> * Did I do the right thing above?  The symbols file is part of
>   debian-gss CVS if you want to take a look.

> * Do I have to modify the file considering that debian unstable contains
>   0.0.23 with the same ABI?

You should ideally adjust the 0.0.24 versions to instead be the first
version at which those symbols existed with their current ABI.  It doesn't
matter a tremendous amount the first time around, though; what matters
most is how the file is maintained in the future.

> * What should I do on next release with no ABI changes?  Keep the
>   version number as is in the .symbols file?

Correct.  The version number indicates the minimum library version
required to use that symbol with its current ABI.

> * What should I do on next release with ABI changes?  Add the new ABI to
>   the .symbols file with the newer version number?

Correct.

> * Generally, should I bother with a *.symbols file at all?  I get a
>   feeling from the wiki page that people haven't really decided that
>   this is the way to go, and I haven't found many debian packages that
>   use a *.symbols file either.

The utility of the symbols file is directly proportional to how many
packages depend on that shared library.  I plan on introducing them for
every package I maintain (with the the exception of C++ libraries) just
because they're fairly easy to maintain if you already know how the ABI is
changing.  But they're particularly valuable for glibc, libpng, and
similar libraries that are very widely linked against.  I think most of
the focus and attention so far has been on those libraries rather than on
every library package in Debian.

I expect symbols files will get gradually more attention as time goes on.
(For example, they're not in Debian Policy yet, and I want to add them.)

-- 
Russ Allbery (address@hidden)               <http://www.eyrie.org/~eagle/>