Junichi Uekawa <[EMAIL PROTECTED]> 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. -- [EMAIL PROTECTED] : Junichi Uekawa http://www.netfort.gr.jp/~dancer GPG Fingerprint : 17D6 120E 4455 1832 9423 7447 3059 BF92 CD37 56F4 -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]