Move some old documents to a historical directory

* Move README.shlibdeps and libc6-migration.txt to a new historical
  subdirectory and add a README explaining that the files in this
  directory are of historical interest only and are not included in the
  debian-policy binary package.

3 files changed, 384 insertions, 0 deletions

diff --git a/historical/README b/historical/README
new file mode 100644
index 0000000..c67db0c
--- /dev/null
+++ b/historical/README
@@ -0,0 +1,3 @@
+This directory contains some informal specifications that may be of
+historical interest.  They are part of the debian-policy source package
+but are no longer included in the debian-policy binary package.
diff --git a/historical/README.shlibdeps b/historical/README.shlibdeps
new file mode 100644
index 0000000..34a4285
--- /dev/null
+++ b/historical/README.shlibdeps
@@ -0,0 +1,118 @@
+In woody dpkg will use a different method to determine on which
+libraries a package should depend. Until now dpkg-shlibdeps has
+used the output of ldd to determine which libraries are needed.
+This will be changed to using objdump. This however changes
+will need a couple of changes in the way that packages are build.
+      
+Let me first explain the differences between ldd and objdump.
+A binary itself is linked against 0 or more dynamic libraries, depending
+on how it is linked. Some of those libraries may need other libraries
+to do their work, so the linker will need to load those as well when
+the binary is executed. For example, to run xcdrgtk needs the following
+libraries according to ldd:
+            
+        libgtk-1.2.so.0 => /usr/lib/libgtk-1.2.so.0 (0x40019000)
+        libgdk-1.2.so.0 => /usr/lib/libgdk-1.2.so.0 (0x4013d000)
+        libImlib.so.1 => /usr/lib/libImlib.so.1 (0x40170000)
+        libgdk_imlib.so.1 => /usr/lib/libgdk_imlib.so.1 (0x401ab000)
+        libc.so.6 => /lib/libc.so.6 (0x401d9000)
+        libgmodule-1.2.so.0 => /usr/lib/libgmodule-1.2.so.0 (0x402b5000)
+        libglib-1.2.so.0 => /usr/lib/libglib-1.2.so.0 (0x402b8000)
+        libdl.so.2 => /lib/libdl.so.2 (0x402da000)
+        libXi.so.6 => /usr/X11R6/lib/libXi.so.6 (0x402de000)
+        libXext.so.6 => /usr/X11R6/lib/libXext.so.6 (0x402e6000)
+        libX11.so.6 => /usr/X11R6/lib/libX11.so.6 (0x402f3000)
+        libm.so.6 => /lib/libm.so.6 (0x40392000)
+        libjpeg.so.62 => /usr/lib/libjpeg.so.62 (0x403af000)
+        libtiff.so.3 => /usr/lib/libtiff.so.3 (0x403cf000)
+        libungif.so.3 => /usr/lib/libungif.so.3 (0x40411000)
+        libpng.so.2 => /usr/lib/libpng.so.2 (0x4041a000)
+        libz.so.1 => /usr/lib/libz.so.1 (0x40442000)
+        /lib/ld-linux.so.2 => /lib/ld-linux.so.2 (0x40000000)
+
+Now if we leek a bit closed we see that xcdrgtk actually only links to
+a couple of those libraries directly. The actual depencies are a tree
+which looks something like this: (anyone interested in writing a tool
+to make such a graph?)
+
+      xcdrgtk
+      +- libc
+      +- gtk
+      +- gdk
+      |  +- libXi
+      |  +- libXext
+      |  \- libX11
+      +- Imlib
+      |  +- libjpeg
+      |  +- libtiff
+      |  |  +- libjpeg
+      |  |  +- libm
+      |  |  \- libz
+      |  +- libungif
+      |  |  \- libX11
+      |  +- libpng
+      |  |  +- libz
+      |  |  \- libm
+      |  +- libz
+      |  \- libm
+      \- gdk_imlib
+         +- libgmodule-1.2
+         |   \- libdl
+         +- libglib-1.2
+         \- libdl
+            \- ld-linux
+
+(I haven't listed libc in here, but all libraries are also linked to
+libc).
+
+What ldd does is give us a complete list of every library that is needed
+to run the binary (in other words, if flattens this tree). objdump
+however can tell us exactly what library something is linked with. For
+the same xcdrgtk binary it will tell us:
+
+  NEEDED      libgtk-1.2.so.0
+  NEEDED      libgdk-1.2.so.0
+  NEEDED      libImlib.so.1
+  NEEDED      libgdk_imlib.so.1
+  NEEDED      libc.so.6
+
+All the other libraries are automatically pulled in by the dynamic
+loader.
+        
+And now for the connection to package management: a package only
+needs to depend on the libraries it is directly linked to, since the
+dependencies for those libraries should automatically pull in the
+other libraries.
+
+This change does mean a change in the way packages are build though:
+currently dpkg-shlibdeps is only run on binaries. But since we will
+now depend on the libraries to depend on the libraries they need
+the packages containing those libraries will need to run dpkg-shlibdeps
+on the libraries. That may sound a bit strange, so here is an example:
+      
+Generally a package does this in debian/rules:
+      
+        dpkg-shlibdeps debian/tmp/usr/bin/*
+      
+This will need to be changes to:
+      
+        dpkg-shlibdeps debian/tmp/usr/bin/* debian/tmp/usr/lib/lib*.so.*
+
+For lib* packages which don't generally contain libraries and didn't
+run dpkg-shlibdeps a dpkg-shlibdeps call will need to be added as well.
+      
+This gives us a lot more flexibility in the way libraries are packaged.
+      
+A good example where this would help us is the current mess with
+multiple version of the mesa library. With the ldd-based system
+every package that uses mesa need to add a dependency on
+svgalib|svgalib-dummy in order to handle the glide mesa variant.
+With an objdump-based system this isn't necessary anymore and would
+have saved everyone a lot of work.
+         
+Another example: we could update libimlib with a new version that supports
+a new graphics format called dgf. If we use the old ldd method every
+package that uses libimlib would need to be recompiled so it would also
+depend on libdgf or it wouldn't run due to missing symbols. However with
+the new system packages using libimlib can depend on libimlib itself
+having the dependency on libgdh and wouldn't need to be updated.
diff --git a/historical/libc6-migration.txt b/historical/libc6-migration.txt
new file mode 100644
index 0000000..7c8134f
--- /dev/null
+++ b/historical/libc6-migration.txt
@@ -0,0 +1,263 @@
+
+ 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.<ver>
+         libc5   |   libfoo     | /usr/lib/libc5-compat/libfoo.so.<ver> [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/<a>-linuxlibc1/{lib,include}
+   
+   Note that <a> 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/<a>-linuxlibc1/lib/libfoo.so -> /usr/lib/libc5-compat/libfoo.so.<ver>
+   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 <Helmut.Geyer@iwr.uni-heidelberg.de>.    
+
+  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 <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-8) unstable; urgency=low
+
+  * hamm release
+
+ -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-7) unstable; urgency=low
+
+  * hamm release
+
+ -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:32:03 +0200
+
+libfoo (1.7.54-6) stable; urgency=low
+
+  * added handling of bar.
+
+ -- J.D. Maintainer <jdm@debian.org>  Mon, 16 Jun 1997 18:45:14 +0200
+-=-=-=-=-=-=-=-=-= hamm changelog =-=-=-=-=-=-=-=-=-
+libfoo (1.7.54-10) unstable; urgency=low
+
+  * fixed bug #543547884
+
+ -- J.D. Maintainer <jdm@debian.org>  Fri, 20 Jun 1997 08:52:09 +0200
+
+libfoo (1.7.54-9) stable; urgency=low
+
+  * bo release
+
+ -- J.D. Maintainer <jdm@debian.org>  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 <jdm@debian.org>  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
+