Add additional DKMS and module-assistant documentation

* In README.modules, document the need to install the Linux headers
  package in the DKMS instructions and the need for module-assistant
  clean openafs in the module-assitant instructions.  (Closes: #606235)

diff --git a/debian/README.modules b/debian/README.modules
index d71a8b959197e33183e75414a4b6d17bfa00bf53..b82fcc60ba7f07a901ee2ecd0b1bb2525d940d04 100644 (file)
--- a/debian/README.modules
+++ b/debian/README.modules
@@ -23,17 +23,24 @@ Introduction
 
 DKMS
 
-  DKMS is relatively new and untested compared to the other mechanisms for
-  building kernel modules, but if it works for you, it's the easiest.
-  DKMS stands for Dynamic Kernel Module Support.  It provides
-  infrastructure that will automatically rebuild kernel modules when the
-  source package or the kernel has been upgraded.
-
-  To build OpenAFS kernel modules via DKMS, just install the
-  openafs-modules-dkms package.  This depends on DKMS and will install it
-  as well.  The OpenAFS kernel modules should then be built automatically
-  and will be installed under updates/dkms in the module tree for your
-  kernel.
+  DKMS has some caveats, but it's the easiest method of building modules.
+  It provides infrastructure that will automatically rebuild kernel
+  modules when the source package or the kernel has been upgraded.
+
+  To build OpenAFS kernel modules via DKMS, install the linux-headers
+  package corresponding to the version of the kernel that you have
+  installed and then install the openafs-modules-dkms package.  This
+  depends on DKMS and will install it as well.  The OpenAFS kernel modules
+  should then be built automatically and will be installed under
+  updates/dkms in the module tree for your kernel.
+
+  Please note that DKMS will only build modules for kernels that have the
+  Linux headers installed.  When you upgrade your kernel, you need to
+  install the new linux-headers package at the same time, or you'll end up
+  without an OpenAFS module for the new kernel.  If you're using the
+  tracking packages for the kernel (linux-image-2.6-686 or the like), also
+  install the tracking package for the kernel headers
+  (linux-headers-2.6-686 in that example).
 
 module-assistant
 
@@ -68,6 +75,15 @@ module-assistant
   correctly so that it matches the name of the kernel-image package and
   installs its modules into the correct directory.
 
+  If you have ever previously built a module with module-assistant, always
+  run:
+
+      module-assistant clean openafs
+
+  before building a new module.  module-assistant doesn't always properly
+  clean up after itself, and the mix of files from old and new versions of
+  OpenAFS can cause serious problems with the resulting module.
+
 make-kpkg
 
   This method may work better than module-assistant if you're also

diff --git a/debian/changelog b/debian/changelog
index c0e18873d1f645f6400e085bf67fe9f3b2990afe..11264e6bb13f557a66e28beb8f258dd8dbf0db84 100644 (file)
--- a/debian/changelog
+++ b/debian/changelog
@@ -1,3 +1,11 @@
+openafs (1.6.0~pre1-2) UNRELEASED; urgency=low
+
+  * In README.modules, document the need to install the Linux headers
+    package in the DKMS instructions and the need for module-assistant
+    clean openafs in the module-assitant instructions.  (Closes: #606235)
+
+ -- Russ Allbery <rra@debian.org>  Thu, 06 Jan 2011 20:03:48 -0800
+
 openafs (1.6.0~pre1-1) experimental; urgency=low
 
   * New upstream prerelease.