updated library packaging FAQ(Re: Library packaging)
Junichi Uekawa <dancer@netfort.gr.jp> cum veritate scripsit:
Well, now I updated the doc a little bit, I'll post it here.
I've received exactly one response so far, and I'm feeling a bit
naive about the contents of this document.
Please comment:
Library packaging Guide (very much a draft).
This is just something to get the ball rolling, not the definitive guide.
10 Jan 2002, 13 Jan 2002. Junichi Uekawa.
Revised to be up-to-date on 17 Mar 2002.
Distributed under the terms of GPL version 2 or later
This guide tries to make the problems related with
library packaging to be clear to the Developers of Debian Project,
to hopefully raise the general awareness, and to fill the gap of
Debian documentation lacking in the direction of library package.
Hopefully this document will be more accurate as criticisms come,
and will improve the general quality of Debian,
and provide a good reading for newbie Debian developers,
instead of the "don't even dare packaging libraries if you
are a newbie" guide.
[Traits of Debian]
First, let us check what Debian is in the perspective of
maintaining library packages, and why Debian is different to
other systems.
Debian is a binary-distribution-centric system.
Binary is created from source, and they are the ones that
gets distributed mainly.
Binary is compiled from the source at time as a snapshot for one architecture,
and several copies of binary is built from the same source at different points
for different architectures, against different versions of the library
that may exist at that point.
Thus, unless one is careful, one has no control over which version of
specific development package a binary will be compiled with.
Debian has a packaging scheme for libraries, with having
libfooX package for run-time required library files,
and libfooX-dev package for buid-time required library files.
[Recommended reading before doing library packages]
It is recommended to read the info page for libtool,
which is contained in the libtool-doc package.
It explains many things in detail, and it talks about
generic aspects of library programs not specific to Debian.
Also, please read the Debian Policy carefully,
and New Maintainer's Guide, and Developers Reference.
An experience of having your package broken by some
random library upgrade might be a plus.
[Naming library packages]
The policy documents how to name library packages.
"lib<package><soname>"
like
"libc6" for /lib/libc.so.6
However, there are packages which contain libraries that look like this:
/usr/lib/libsomepackage-1.2.so.0
This is a library with a name of "libsomepackage-1.2", and a soname of "0".
The current practice in packaging such package seems to be to have
"libsomepackage-1.2-0"
as the package name.
It is taking the form of "lib<package>-<soname>" format
to distinguish the package name and the soname, using the "-".
This applies to all library packages which the name ends in a
numeric.
[-DEV package names]
It is ideal to have the soname in the package name, like the following:
Package: libpackage2-dev
Provides: libpackage-dev
Conflicts: libpackage-dev
This ensures that only one version of libpackageX-dev
is installed, and also allows the maintainer of each package
to selectively link with the expected library with the
expected soname version.
It is possible to create
Package: libpackage-dev
and it is allowed by policy. However, this allows
any version of library libpackage to be linked.
This has caused much problems, in libpng, and other
packages. libpackage-dev notation should not be used
if it is going to be linked in by other library packages.
[-DEV package dependencies]
-dev package should depend on all -dev packages that the library
package depends upon, with the version that the library package is compiled
against.
e.g.
libFOO2-dev -> libBAR2-dev
because libFOO2 depends on libBAR2
If you want libFOO2-dev that can compile with libBAR3-dev,
the soname or something else should be fixed. The possible situation
will be:
libFOO3-dev -> libBAR3-dev
(discuss with upstream to coordinate the soname change)
or
libFOO2-libBAR3-dev -> libBAR3-dev
and have libFOO2 and libFOO2-libBAR3 conflicting with each other.
[Packages which Build-depend on a -DEV package]
It is advised to
Build-Depend: libpackage<soname>-dev | libpackage-dev
(this can cause undesired effect of linking with a source-incompatible
library version, i.e. a serious "cannot build from source" bug)
or
Build-Depend: libpackage<soname>-dev
(This needs to be updated every time a new -dev comes out, and
the new soname becomes the standard, and the old one becomes obsolete)
[WHY "Build-Depend: libpackage-dev" IS NOT OPTIMAL]
Answer the following question:
Are you really sure all past/present/future version of that
-dev package can be used with the source to build the package?
[SONAMES]
If a package version matches the soname.
scrap it, and bash the upstream with the libtool manual.
It is usually a good sign that either he has not read the manual
thoroughly, or he has not understood it, or both.
If a package keeps the same soname, the BINARY COMPATIBILITY IS KEPT.
If a new version of a library package breaks currently existing and
working package, the SONAME should be bumped up, or
the change be reverted, or both.
To bump up the soname, there should really be a working compatibility
library under the old soname.
Signs of binary incompatibility include:
function declaration change
contents of struct's changing
changing semantics of functions (hard to detect).
[HOW To FIX UPSTREAM PACKAGES WITH SOMEWHAT BROKEN SONAMES]
Refer to libssl and other packages which used to handle it.
They basically had sonames which matched the package version, and
every version: e.g. 0.9.4 and 0.9.6 had incompatibility.
The solution was to create a SONAME of 0.9.6, so that :
$ objdump -p /usr/lib/libssl.so.0.9.6 | grep SONAME
SONAME libssl.so.0.9.6
libssl-dev contains the symlink
/usr/lib/libssl.so -> /usr/lib/libssl.so.0.9.6
This way, binary programs linked with libssl.so via "-lssl" command
line option passed to gcc will be look for libssl.so.0.9.6 at runtime.
It is quite important that Debian does not lose binary compatibility
with other distributions, so changing the soname specifically for
Debian is generally a bad idea. Discuss and convince the upstream to
use a saner method for setting up the sonames.
[WHEN BINARY COMPATIBILITY BREAKS]
Soname needs to be updated when a binary compatibility is broken.
When the library itself changes the interface, the soname
needs to be changed, because the binary compatibility has changed.
Also when the library that the library depends has changed incompatibly,
it means that the library depending on the changed library have
changed incompatibly.
The soname needs to be updated to reflect this change.
However, it is not always possible to increase the soname,
possibly to remedy past problems, and experiences.
To do that, it is also possible to change just the package name.
libfooX may have been broken, and to fix it, introduce a new package
libfooXSOMETHING. Alter the shlibs files so that building with
libfooX-dev will cause the binary package to depend on
libfooXSOMETHING, like the following:
libfoo X libfooXSOMETHING
Also libfooXSOMETHING should have the following:
Package: libfooXSOMETHING
Provides: libfooX
COnflicts: libfooX
to reflect that libfooXSOMETHING is not installable alongside with
libfooX.
And start recompiling every package that is linked against
libfooX against the libfooX-dev, updating the Build-Depends
accordingly (to build-depend on a version greater than the newly
created libfooX-dev).
"apt-cache showpkg libfooX"
or
"grep-available -F Depends -s Package,Depends libfooX"
will give a rough idea of what needs to be done (although possibly
not complete).
[WHAT TO DO WHEN SONAMES CHANGE TOO OFTEN]
There are some cases where the library sonames change too often.
It might be a legitimate thing, but the upstream may be doing it
just for the sake of it.
Check their modifications, and suggest increase of soname
only when the library has an incompatible change.
When you only see ChangeLog file and configure.in and
such files being modified, and yet you see soname changes,
it is a good sign that the upstream is not taking sonames seriously.
There are libraries which are under heavy development.
It is a pain anyway, because people have to follow it,
accept that it is a pain. It is almost impossible to package
a moving target into a stable distribution.
[WHAT TO PUT IN SHLIBS FILE]
in shlibs file, put something like
libpcap 0 libpcap0 (>= 0.6.1-1)
When compatibility breaks, make it look like
libpcap 1 libpcap1
or,
libpcap 0 libpcap0a
and create a new libpcap0a package, conflicting with libpcap0
Doing something like :
libpcap 0 libpcap0 (>= 0.6.1-1), libpcap0 (<< 0.7.0)
is not good because it does not survive the
epochs in version, and really unnecessary if
sonames are used properly.
--
dancer@debian.org : Junichi Uekawa http://www.netfort.gr.jp/~dancer
GPG Fingerprint : 17D6 120E 4455 1832 9423 7447 3059 BF92 CD37 56F4
Reply to: