library versioning: summary of relevant bits and possible solution.

[Rob Browning]

After some discussion on debian-devel with Junichi (author and
maintainer of the Debian Library Packaging guide,
http://www.netfort.gr.jp/~dancer/column/libpkg-guide/libpkg-guide.html)
I thought I'd summarize what I learned.  This is somewhat long, and
all of it may not be of interest to everyone, but you should probably
at least skip to the last section which disusses the solution that
appears viable:

- First off, the whole versioning issue we've been discussing appears
  to be a real issue, not just our misunderstanding.  In Debian, if
  the maintainers follow Junichi's guidelines, the problems should be
  relatively limited, and should exclusively affect unstable.  The
  effect would be for there to be periods where packages linked
  against guile, perl, gtk, etc. may be broken during a major
  guile/perl/gtk upgrade until all of the libraries that link against
  those packages have been recompiled.  The build dependencies that
  Junichi recommends should cause the autobuilders to detect the
  problem, and force the package maintainers to update their packages
  and upload new source.

- Most of the serious problems occur when a library that many other
  libraries build against changes it's soname, and it's particularly
  severe for something like guile where the libraries that build
  against libguile actually publish unversioned guile data structures
  (i.e. SCM) as part of their public API.

- It is possible to do better than the Debian "only broken for a bit"
  approach above if you're the upstream.  One solution is to just name
  your library in such a way as to include all the names and versions
  of the sub-libraries the library depends on
  (i.e. libgwrap-glib1.2-guile1.6).  This prevents anyone from
  creating two versions of libgwrap-glib (built on different systems
  perhaps, or at different times) that are both soname 1, but are not
  binary compatible because one was linked against libguile 9 and the
  other was linked against libguile 12.

  Of course this solution is super-ugly because (among other things)
  it means when people want to link against your library, they have to
  figure out which particular name to use, i.e. that have to know to
  say -lgwrap-guile-glib1.2-guile1.6.

- Another possible solution is to just pick the library soname at
  configure time based on a "lookup table of sub-library
  dependencies".  So for a given release of your library (say
  libgwrap-glib's first release), you might decide to choose the
  soname at build time like this:

    glibversion  guileversion  gwrap-glib-soname
       1.2          1.4               1
       1.2          1.6               2
       2.0          1.4               3
       2.0          1.6               4

  then if you change gwrap-glib's API in a backward incompatible way,
  you'd change your table to update all the sonames:

    glibversion  guileversion  gwrap-glib-soname
       1.2          1.4               5
       1.2          1.6               6
       2.0          1.4               7
       2.0          1.6               8

  but of course this is a mess, chews up sonames, means that increases
  in soname values only *sometimes* mean a real API change.

  One modification that would avoid chewing up sonames would be to
  move the API version number into the library name,
  i.e. libgwrap-glib-1, and then just use the sonames to indicate the
  set of sub-library versions that the library was linked against.

  This solution is also somewhat a mess, and certainly not what people
  are likely to expect, and given the modification, means that people
  linking against your lib will still have to change their -lfoo-N
  compile-switches whenever a new version of the library comes out.

- Though there are good arguments against each of the above solutions
  to the versioning problem, if the library name and soname pair
  really is supposed to indicate binary compatibility, something has
  to be done.

  So what if libgwrap-guile were changed to place the sub-library
  version dependency information in the *soname*, but still maintained
  the normal libgwrap-guile.so development symlink?  For example, what
  if rather than libgwrap-wct.so.1, the soname for libgwrap-wct was
  changed to libgwrap-wct-1-glib-2-0-guile-12.so or something similar?
  (Note carefully -- I'm talking about the SONAME here, *not* the
  library basename, or the filename).

  As far as filenames go, you'd still want to have

    ./libgwrap-wct-1-glib-2-0-guile-12.so
    ./libgwrap-wct.so -> ./libgwrap-wct-1-glib-2-0-guile-12.so

  So -lgwrap-wct would still work just fine, but the actual
  sub-library version dependencies would have to match (via the lib
  SONAME), in order for runtime ld.so linking to succeed.

  It turns out that if you use the -release flag to libtool, the above
  is *exactly* what happens (i.e. -release 1-glib-2-0-guile-12), and
  it seems to solve nearly all of the relevant problems.  The only
  drawbacks I can see are the fact that it's not an approach people
  are used to, and it does make for some long library file names, but
  neither of those problems seems all that signficant when compared to
  the benefit.

  It may also be worthwhile to consider using -version-info
  CURRENT:REVISION:AGE in addition to -revision so that you can
  include a REVISION number in the filename that won't show up in the
  soname, but arguably, being able to have multiple revisions of a lib
  (i.e. 3.4.1 *and* 3.4.2) available at the same time is of dubious
  benefit.

  I'd love to hear any counter-arguments that would make this approach
  unviable.  Barring that, I'm probably going to switch to this method
  for the next version of g-wrap, and if that works out, we might want
  to consider the method for broader recommendation.

Thanks

-- 
Rob Browning
rlb @defaultvalue.org, @linuxdevel.com, and @debian.org
Previously @cs.utexas.edu
GPG starting 2002-11-03 = 14DD 432F AE39 534D B592  F9A0 25C8 D377 8C7E 73A4