libc6-migration.txt

   1
   2  Debian library policy supplement draft for libc5->libc6 migration
   3
   4    This document is meant to tell what a Debian package providing a
   5    library should do to support both libc6 (glibc2) and libc5.
   6    Note that these requirements are for Debian 2.0 (codename hamm).
   7
   8  Contents
   9  1.  Run time packages
  10  2.  Development packages
  11  3.  Source packages
  12  4.  Requirements on libraries for Debian 2.0
  13  5.  Conflicts and Dependencies
  14  6.  Handling bugfix releases for Debian 1.3 (bo)
  15  7.  Requirements on compiler packages
  16
  17  1. Run time packages
  18
  19     A package providing a shared library has to support both C library
  20     packages, libc5 and libc6 based libraries. This must be done using
  21     two Debian packages, each depending on the correct C library
  22     package.
  23     The package naming convention currently suggests to name these
  24     packages as follows. Some packages (mostly from base) may use
  25     locations in /lib.
  26
  27        based on  | package name | library location
  28        --------------------------------------------
  29          libc6   |   libfoog [1]| /usr/lib/libfoo.so.<ver>
  30          libc5   |   libfoo     | /usr/lib/libc5-compat/libfoo.so.<ver> [2]
  31
  32     If a library runtime package contains files that are needed by
  33     both versions of the library, a new package should be made for
  34     just these files that both other packages depend on.
  35
  36     This package naming convention does _not_ apply if a package uses
  37     different sonames for libc5 and libc6 based packages
  38
  39     There are two exceptions from this rule. The shared linker
  40     ld-linux.so.1 and the C library files libc.so.5 and libm.so.5
  41     should still be located in /lib, not in /lib/libc5-compat.
  42
  43     Packages based on X have to use /usr/X11R6 as prefix, not /usr.
  44     Note that the X libraries are designed to work with both C libraries.
  45
  46   2.  Development packages
  47
  48     The Debian policy requires that all files needed for compiling/linking
  49     other packages with the library are in a separate package, the
  50     development package. Up to now this package simply was called
  51     libfoo-dev. As packages based on libc5 and libc6 usually cannot
  52     use the same development files there has to be a clear statement
  53     how to separate these. So for now the following packages are
  54     required:
  55
  56       based on  | package name        | hierarchy locations
  57       ---------------------------------------------------------------
  58       libc6     | libfoog-dev         | /usr/{lib,include}
  59       libc5     | libfoo-altdev       | /usr/<a>-linuxlibc1/{lib,include}
  60
  61    Note that <a> usually is i486, but may not be hardcoded in
  62    debian/rules. It should be obtained using
  63         dpkg --print-gnu-build-architecture
  64
  65    Remember that the libfoo-altdev package has to include symlinks
  66    /usr/<a>-linuxlibc1/lib/libfoo.so -> /usr/lib/libc5-compat/libfoo.so.<ver>
  67    to enable using the shared libraries when compiling.
  68
  69    All documentation that is not depending on whether the library was
  70    compiled for libc5 or for libc6 should be either part of the
  71    libfoog-dev package or be put into a separate package if it is
  72    large. In particular this includes manpages which _have_ to be part
  73    of the libfoog-dev package.
  74
  75    Note that the choice to base Debian 2.0 on libc6 fixed the fact
  76    that the main locations will be used for libc6 packages. The
  77    alternate locations are used for libc5 based packages.
  78    This decision does not necessarily mean that by default the
  79    compiler uses the libc6 packages, please read section 4 for more
  80    information. Using a four-way approach for library locations
  81    (standard and alternate locations for libc6 and libc5 based
  82    packages) will make Debian systems inconsistent with each other,
  83    something we should avoid at (nearly) all costs.
  84
  85
  86   3. Source packages
  87
  88    The source package name should _not_ be modified for hamm.
  89
  90    If a bugfix for bo has to be released, use bo's source package  to
  91    extract the bo source and add for each hamm release a line to
  92    debian/changelog stating that this release was a hamm release.
  93    Make your bugfix changes, including changes to the control file
  94    according to section 6.
  95
  96    Then unpack the hamm source again, update debian/changelog and
  97    debian/control to figure the bo release, and release a new hamm
  98    package (including the bugfix, if it affects hamm as well). [3]
  99
 100   4.  Requirements on libraries for Debian 2.0
 101
 102    Libraries (regardless of which library they're compiled against) need
 103    to have runtime dependencies on one of libc, libdl or libm to enable
 104    the shared linker to determine which library to use for a binary.
 105    These runtime dependencies are _NOT_ dependencies in the Debian
 106    way, but dependencies generated by the linker when generating the
 107    shared library. See the binutils manual for more information.
 108
 109    In general we want libraries compiled for libc6 to be thread-safe.
 110    This is, however, not practical or feasible for every library
 111    package. Making a library thread-safe involves quite a lot of work,
 112    much of it nontrivial.
 113    Thread-safe means that the following changes must be made to the
 114    library packages:
 115
 116     - compile the library using -D_REENTRANT or -D_THREAD_SAFE
 117     - there may be no permanent data residing in the library memory that
 118       can be different for different threads.
 119       this means in the first place no static or global variables that
 120       are not in some way protected from access by a different threads
 121       via mutexes.
 122     - all write access to files from a library must be both protected
 123       using some file locking mechanism in addition to using mutexes.
 124     - at least some library functions must be protected from being
 125       used at the same time by two threads sharing the same memory
 126       space. This is done using mutexes.
 127
 128    As these usually are all nontrivial changes to a library if it isn't
 129    thread-safe already (in which case just using -D_REENTRANT should
 130    be used in addition to whatever the library uses to support threads),
 131    I suggest that no-one starts doing this without getting in contact with
 132    the upstream maintainer(s).
 133
 134    If a library has a thread-safe version, the debian package should
 135    use this. The performance deficits usually are very small when not
 136    linking to libpthreads so only if there are serious reasons, the
 137    debian package may include the non-thread-safe version.
 138
 139    There will be a list available that lists all libraries part of
 140    Debian and their current status regarding compliance with these
 141    standard requirements. This list will be posted regularly to
 142    debian-devel by Helmut Geyer <Helmut.Geyer@iwr.uni-heidelberg.de>.
 143
 144   5. Conflicts & Dependencies for hamm packages
 145
 146    The libfoog package _has_ to conflict with all versions of the
 147    libfoo package before it was made to use the libc5-compat
 148    directory. Furthermore it should depend on libc6.
 149
 150    The libfoog-dev package must depend on libc6-dev and the libfoog
 151    package of the same release. It has to conflict with the libfoo-dev
 152    package.
 153
 154    The hamm libfoo package has to depend on libc6 and has to conflict
 155    with libfoo-dev and libc5-dev.
 156
 157    The libfoo-altdev package has to depend on the libc5-altdev and
 158    libfoo package of the same release.
 159
 160   6. Handling bugfixes for Debian 1.3 (bo)
 161
 162    Using the dependencies from Section 5. there will be problems with
 163    making bugfix releases for bo. These have to be handled carefully
 164    as otherwise there may be tremendous problems for people using
 165    hamm systems.
 166    As there is one package name used for both hamm and bo that stays
 167    the same (libfoo), we have to very careful.
 168    The following steps should be followed:
 169
 170    i)  when making a bo bugfix release, be sure to make a hamm release
 171        at the same time, using a higher release number for the hamm
 172        release. Update the hamm package's conflicts according to
 173        section 5.
 174    ii) Any bo package for libfoo _has_ to conflict with libc6,
 175        libfoo-altdev and libfoog.
 176    iii)The libfoo-dev package has to conflict with libc5-altdev and
 177        has to depend on libc5-dev.
 178
 179
 180   7. Requirements on compiler packages
 181
 182    The compiler and binutils packages have to provide working
 183    development environments for both C libraries. Basically (that is
 184    from the compiler standpoint) there is no real difference between
 185    the two environments, only some paths and automatic definitions
 186    have to be changed. All this can be done (and is in fact done) by
 187    supplying a different specs file in a different location.
 188
 189    The gcc packages do this as follows:
 190
 191    The gcc package uses libc6 by default and is installed in /usr/bin.
 192
 193    The alt-gcc package uses libc5 by default and is located in
 194    /usr/i486-linuxlibc1/bin. By prepending this to the path this can
 195    be made the default.
 196
 197    These requirements are fulfilled by the current gcc packages.
 198
 199 Remarks:
 200
 201  [1] the name of a library package often includes the major version
 202      number of the library. If so, the 'g' should come before this
 203      number, e.g. libgdbmg1 as package name for the libc6 based
 204      runtime package for libgdbm.
 205
 206  [2] The location ../libc5-compat was introduced in the ldso package. As
 207      ldso is a package on all linus distributions we'll keep it for
 208      compatibility with other distributions even though
 209      /usr/i486-linuxlibc1/lib would be more consistent.
 210
 211  [3] An example for relevant sections of the changelogs for a bugfix
 212      release for both bo and hamm (with the last bo release being
 213      libfoo 1.7.54-6 released on Mon, 16 Jun 1997 and the last hamm
 214      release being libfoo 1.7.54-8 released on Wed, 18 Jun 1997):
 215
 216 -=-=-=-=-=-=-=-=-= bo changelog =-=-=-=-=-=-=-=-=-
 217 libfoo (1.7.54-9) stable; urgency=low
 218
 219   * fixed bug #543547884
 220
 221  -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
 222
 223 libfoo (1.7.54-8) unstable; urgency=low
 224
 225   * hamm release
 226
 227  -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
 228
 229 libfoo (1.7.54-7) unstable; urgency=low
 230
 231   * hamm release
 232
 233  -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
 234
 235 libfoo (1.7.54-6) stable; urgency=low
 236
 237   * added handling of bar.
 238
 239  -- J.D. Maintainer <jdm@debian.org>  Mon, 16 Jun 1997 18:45:14 +0200
 240 -=-=-=-=-=-=-=-=-= hamm changelog =-=-=-=-=-=-=-=-=-
 241 libfoo (1.7.54-10) unstable; urgency=low
 242
 243   * fixed bug #543547884
 244
 245  -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:52:09 +0200
 246
 247 libfoo (1.7.54-9) stable; urgency=low
 248
 249   * bo release
 250
 251  -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:52:09 +0200
 252
 253 libfoo (1.7.54-8) unstable; urgency=low
 254
 255   * finally made package compliant with those strange policy for hamm
 256     libs.
 257
 258  -- J.D. Maintainer <jdm@debian.org>  Wed, 18 Jun 1997 15:34:12 +0200
 259 -=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-
 260 --
 261 Helmut Geyer                                Helmut.Geyer@iwr.uni-heidelberg.de
 262 public PGP key available :           finger geyer@saturn.iwr.uni-heidelberg.de
 263