--- /dev/null
+ Building Kernel Modules
+
+Introduction
+
+ The easiest way to get AFS modules is to install prebuilt modules. For
+ example, if you are running kernel 2.6.26-2-686, you might try:
+
+ apt-get install openafs-modules-2.6.26-2-686
+
+ Pre-built modules are not provided with Debian (building and maintaining
+ them in Debian proper poses too many problems), but many organizations
+ that use OpenAFS build their own and provide them locally.
+
+ If this doesn't work, you will need to build your own modules. There
+ are three methods for doing this.
+
+ When following any of these methods, be aware that the Debian package
+ creates a module named openafs, not libafs as is used by upstream. It
+ also prefers not to add the .mp extension for modules built for SMP
+ kernels; the indication of whether the module is for an SMP kernel
+ should go into the package name via something like --append_to_version,
+ not into the file name of the module.
+
+DKMS
+
+ 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
+
+ This method is the best method for manually building kernel modules for
+ kernels that come with Debian, since module-assistant knows how to get
+ the right header files to build modules for your currently running
+ kernel. Generally, all you should have to do is:
+
+ apt-get install module-assistant
+ module-assistant auto-install openafs
+
+ This combines all of the following steps, taking the defaults. If you
+ want to do it more step-by-step, first prepare the kernel headers and
+ install openafs-modules-source with:
+
+ apt-get install module-assistant
+ module-assistant prepare openafs-modules
+
+ If you want to build modules for a different kernel than your currently
+ running one, pass the -l flag to module-assistant. See the man page.
+ module-assistant may be able to find the right packages itself or it may
+ tell you to install particular packages. Once you've finished with
+ that, build the module with:
+
+ module-assistant auto-build openafs-modules
+
+ You may prefer to pass module-assistant the -t flag to get more
+ conventional output. If everything works correctly, the openafs-modules
+ deb should be created in /usr/src. You can use dpkg -i to install it.
+
+ module-assistant will take care of naming the openafs-modules package
+ 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
+ building your own kernel rather than using the pre-packaged Debian one.
+
+ Install a kernel source package and untar it in /usr/src. Then, install
+ openafs-modules-source.
+
+ apt-get install openafs-modules-source
+
+ Next, unpack openafs-modules-source:
+
+ cd /usr/src
+ tar xzf openafs.tar.gz
+
+ Now, change into your kernel source tree. You should then create a
+ .config file; the easiest way to do this is to run make menuconfig or to
+ copy in a kernel configuration from the same version of the kernel.
+ Debian kernel packages store a copy of their kernel configuration in
+ /boot/config.version_number.
+
+ The kernel configuration needs to be identical to the configuration that
+ produced the kernel that you're using. Ideally, you would build the
+ kernel image you're going to use with make-kpkg kernel_image and install
+ that along with the module image, although as long as the configuration
+ is identical, you may be able to get away with using a pre-built kernel.
+ (A better approach, if you're using pre-built kernels, may be to use
+ module-assistant as described above.)
+
+ Finally, build the modules:
+
+ make-kpkg modules_image
+
+ You may need to use the --append_to_version switch to add version
+ suffixes like -686 or -smp to match your kernel and install the OpenAFS
+ module into a directory like /lib/modules/version-686. Be aware that
+ the Debian OpenAFS packages build either a regular module or an SMP
+ module, not both, so the generated package will only work with a kernel
+ with the same SMP configuration.
+
+ An openafs-modules deb should be created in /usr/src. Use dpkg -i to
+ install this package.