Debian library policy supplement draft for libc5->libc6 migration This document is meant to tell what a Debian package providing a library should do to support both libc6 (glibc2) and libc5. Note that these requirements are for Debian 2.0 (codename hamm). Contents 1. Run time packages 2. Development packages 3. Source packages 4. Requirements on libraries for Debian 2.0 5. Conflicts and Dependencies 6. Handling bugfix releases for Debian 1.3 (bo) 7. Requirements on compiler packages 1. Run time packages A package providing a shared library has to support both C library packages, libc5 and libc6 based libraries. This must be done using two Debian packages, each depending on the correct C library package. The package naming convention currently suggests to name these packages as follows. Some packages (mostly from base) may use locations in /lib. based on | package name | library location -------------------------------------------- libc6 | libfoog [1]| /usr/lib/libfoo.so. libc5 | libfoo | /usr/lib/libc5-compat/libfoo.so. [2] If a library runtime package contains files that are needed by both versions of the library, a new package should be made for just these files that both other packages depend on. This package naming convention does _not_ apply if a package uses different sonames for libc5 and libc6 based packages There are two exceptions from this rule. The shared linker ld-linux.so.1 and the C library files libc.so.5 and libm.so.5 should still be located in /lib, not in /lib/libc5-compat. Packages based on X have to use /usr/X11R6 as prefix, not /usr. Note that the X libraries are designed to work with both C libraries. 2. Development packages The Debian policy requires that all files needed for compiling/linking other packages with the library are in a separate package, the development package. Up to now this package simply was called libfoo-dev. As packages based on libc5 and libc6 usually cannot use the same development files there has to be a clear statement how to separate these. So for now the following packages are required: based on | package name | hierarchy locations --------------------------------------------------------------- libc6 | libfoog-dev | /usr/{lib,include} libc5 | libfoo-altdev | /usr/-linuxlibc1/{lib,include} Note that usually is i486, but may not be hardcoded in debian/rules. It should be obtained using dpkg --print-gnu-build-architecture Remember that the libfoo-altdev package has to include symlinks /usr/-linuxlibc1/lib/libfoo.so -> /usr/lib/libc5-compat/libfoo.so. to enable using the shared libraries when compiling. All documentation that is not depending on whether the library was compiled for libc5 or for libc6 should be either part of the libfoog-dev package or be put into a separate package if it is large. In particular this includes manpages which _have_ to be part of the libfoog-dev package. Note that the choice to base Debian 2.0 on libc6 fixed the fact that the main locations will be used for libc6 packages. The alternate locations are used for libc5 based packages. This decision does not necessarily mean that by default the compiler uses the libc6 packages, please read section 4 for more information. Using a four-way approach for library locations (standard and alternate locations for libc6 and libc5 based packages) will make Debian systems inconsistent with each other, something we should avoid at (nearly) all costs. 3. Source packages The source package name should _not_ be modified for hamm. If a bugfix for bo has to be released, use bo's source package to extract the bo source and add for each hamm release a line to debian/changelog stating that this release was a hamm release. Make your bugfix changes, including changes to the control file according to section 6. Then unpack the hamm source again, update debian/changelog and debian/control to figure the bo release, and release a new hamm package (including the bugfix, if it affects hamm as well). [3] 4. Requirements on libraries for Debian 2.0 Libraries (regardless of which library they're compiled against) need to have runtime dependencies on one of libc, libdl or libm to enable the shared linker to determine which library to use for a binary. These runtime dependencies are _NOT_ dependencies in the Debian way, but dependencies generated by the linker when generating the shared library. See the binutils manual for more information. In general we want libraries compiled for libc6 to be thread-safe. This is, however, not practical or feasible for every library package. Making a library thread-safe involves quite a lot of work, much of it nontrivial. Thread-safe means that the following changes must be made to the library packages: - compile the library using -D_REENTRANT or -D_THREAD_SAFE - there may be no permanent data residing in the library memory that can be different for different threads. this means in the first place no static or global variables that are not in some way protected from access by a different threads via mutexes. - all write access to files from a library must be both protected using some file locking mechanism in addition to using mutexes. - at least some library functions must be protected from being used at the same time by two threads sharing the same memory space. This is done using mutexes. As these usually are all nontrivial changes to a library if it isn't thread-safe already (in which case just using -D_REENTRANT should be used in addition to whatever the library uses to support threads), I suggest that no-one starts doing this without getting in contact with the upstream maintainer(s). If a library has a thread-safe version, the debian package should use this. The performance deficits usually are very small when not linking to libpthreads so only if there are serious reasons, the debian package may include the non-thread-safe version. There will be a list available that lists all libraries part of Debian and their current status regarding compliance with these standard requirements. This list will be posted regularly to debian-devel by Helmut Geyer . 5. Conflicts & Dependencies for hamm packages The libfoog package _has_ to conflict with all versions of the libfoo package before it was made to use the libc5-compat directory. Furthermore it should depend on libc6. The libfoog-dev package must depend on libc6-dev and the libfoog package of the same release. It has to conflict with the libfoo-dev package. The hamm libfoo package has to depend on libc6 and has to conflict with libfoo-dev and libc5-dev. The libfoo-altdev package has to depend on the libc5-altdev and libfoo package of the same release. 6. Handling bugfixes for Debian 1.3 (bo) Using the dependencies from Section 5. there will be problems with making bugfix releases for bo. These have to be handled carefully as otherwise there may be tremendous problems for people using hamm systems. As there is one package name used for both hamm and bo that stays the same (libfoo), we have to very careful. The following steps should be followed: i) when making a bo bugfix release, be sure to make a hamm release at the same time, using a higher release number for the hamm release. Update the hamm package's conflicts according to section 5. ii) Any bo package for libfoo _has_ to conflict with libc6, libfoo-altdev and libfoog. iii)The libfoo-dev package has to conflict with libc5-altdev and has to depend on libc5-dev. 7. Requirements on compiler packages The compiler and binutils packages have to provide working development environments for both C libraries. Basically (that is from the compiler standpoint) there is no real difference between the two environments, only some paths and automatic definitions have to be changed. All this can be done (and is in fact done) by supplying a different specs file in a different location. The gcc packages do this as follows: The gcc package uses libc6 by default and is installed in /usr/bin. The alt-gcc package uses libc5 by default and is located in /usr/i486-linuxlibc1/bin. By prepending this to the path this can be made the default. These requirements are fulfilled by the current gcc packages. Remarks: [1] the name of a library package often includes the major version number of the library. If so, the 'g' should come before this number, e.g. libgdbmg1 as package name for the libc6 based runtime package for libgdbm. [2] The location ../libc5-compat was introduced in the ldso package. As ldso is a package on all linus distributions we'll keep it for compatibility with other distributions even though /usr/i486-linuxlibc1/lib would be more consistent. [3] An example for relevant sections of the changelogs for a bugfix release for both bo and hamm (with the last bo release being libfoo 1.7.54-6 released on Mon, 16 Jun 1997 and the last hamm release being libfoo 1.7.54-8 released on Wed, 18 Jun 1997): -=-=-=-=-=-=-=-=-= bo changelog =-=-=-=-=-=-=-=-=- libfoo (1.7.54-9) stable; urgency=low * fixed bug #543547884 -- J.D. Maintainer Fri, 20 Jun 1997 08:32:03 +0200 libfoo (1.7.54-8) unstable; urgency=low * hamm release -- J.D. Maintainer Fri, 20 Jun 1997 08:32:03 +0200 libfoo (1.7.54-7) unstable; urgency=low * hamm release -- J.D. Maintainer Fri, 20 Jun 1997 08:32:03 +0200 libfoo (1.7.54-6) stable; urgency=low * added handling of bar. -- J.D. Maintainer Mon, 16 Jun 1997 18:45:14 +0200 -=-=-=-=-=-=-=-=-= hamm changelog =-=-=-=-=-=-=-=-=- libfoo (1.7.54-10) unstable; urgency=low * fixed bug #543547884 -- J.D. Maintainer Fri, 20 Jun 1997 08:52:09 +0200 libfoo (1.7.54-9) stable; urgency=low * bo release -- J.D. Maintainer Fri, 20 Jun 1997 08:52:09 +0200 libfoo (1.7.54-8) unstable; urgency=low * finally made package compliant with those strange policy for hamm libs. -- J.D. Maintainer Wed, 18 Jun 1997 15:34:12 +0200 -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- -- Helmut Geyer Helmut.Geyer@iwr.uni-heidelberg.de public PGP key available : finger geyer@saturn.iwr.uni-heidelberg.de