debian/README.modules

   1                          Building Kernel Modules
   2
   3 Introduction
   4
   5   The easiest way to get AFS modules is to install prebuilt modules.  For
   6   example, if you are running kernel 2.6.26-2-686, you might try:
   7
   8       apt-get install openafs-modules-2.6.26-2-686
   9
  10   Pre-built modules are not provided with Debian (building and maintaining
  11   them in Debian proper poses too many problems), but many organizations
  12   that use OpenAFS build their own and provide them locally.
  13
  14   If this doesn't work, you will need to build your own modules.  There
  15   are three methods for doing this.
  16
  17   When following any of these methods, be aware that the Debian package
  18   creates a module named openafs, not libafs as is used by upstream.  It
  19   also prefers not to add the .mp extension for modules built for SMP
  20   kernels; the indication of whether the module is for an SMP kernel
  21   should go into the package name via something like --append_to_version,
  22   not into the file name of the module.
  23
  24 DKMS
  25
  26   DKMS has some caveats, but it's the easiest method of building modules.
  27   It provides infrastructure that will automatically rebuild kernel
  28   modules when the source package or the kernel has been upgraded.
  29
  30   To build OpenAFS kernel modules via DKMS, install the linux-headers
  31   package corresponding to the version of the kernel that you have
  32   installed and then install the openafs-modules-dkms package.  This
  33   depends on DKMS and will install it as well.  The OpenAFS kernel modules
  34   should then be built automatically and will be installed under
  35   updates/dkms in the module tree for your kernel.
  36
  37   Please note that DKMS will only build modules for kernels that have the
  38   Linux headers installed.  When you upgrade your kernel, you need to
  39   install the new linux-headers package at the same time, or you'll end up
  40   without an OpenAFS module for the new kernel.  If you're using the
  41   tracking packages for the kernel (linux-image-2.6-686 or the like), also
  42   install the tracking package for the kernel headers
  43   (linux-headers-2.6-686 in that example).
  44
  45 module-assistant
  46
  47   This method is the best method for manually building kernel modules for
  48   kernels that come with Debian, since module-assistant knows how to get
  49   the right header files to build modules for your currently running
  50   kernel.  Generally, all you should have to do is:
  51
  52       apt-get install module-assistant
  53       module-assistant auto-install openafs
  54
  55   This combines all of the following steps, taking the defaults.  If you
  56   want to do it more step-by-step, first prepare the kernel headers and
  57   install openafs-modules-source with:
  58
  59       apt-get install module-assistant
  60       module-assistant prepare openafs-modules
  61
  62   If you want to build modules for a different kernel than your currently
  63   running one, pass the -l flag to module-assistant.  See the man page.
  64   module-assistant may be able to find the right packages itself or it may
  65   tell you to install particular packages.  Once you've finished with
  66   that, build the module with:
  67
  68       module-assistant auto-build openafs-modules
  69
  70   You may prefer to pass module-assistant the -t flag to get more
  71   conventional output.  If everything works correctly, the openafs-modules
  72   deb should be created in /usr/src.  You can use dpkg -i to install it.
  73
  74   module-assistant will take care of naming the openafs-modules package
  75   correctly so that it matches the name of the kernel-image package and
  76   installs its modules into the correct directory.
  77
  78   If you have ever previously built a module with module-assistant, always
  79   run:
  80
  81       module-assistant clean openafs
  82
  83   before building a new module.  module-assistant doesn't always properly
  84   clean up after itself, and the mix of files from old and new versions of
  85   OpenAFS can cause serious problems with the resulting module.
  86
  87 make-kpkg
  88
  89   This method may work better than module-assistant if you're also
  90   building your own kernel rather than using the pre-packaged Debian one.
  91
  92   Install a kernel source package and untar it in /usr/src.  Then, install
  93   openafs-modules-source.
  94
  95       apt-get install openafs-modules-source
  96
  97   Next, unpack openafs-modules-source:
  98
  99       cd /usr/src
 100       tar xzf openafs.tar.gz
 101
 102   Now, change into your kernel source tree.  You should then create a
 103   .config file; the easiest way to do this is to run make menuconfig or to
 104   copy in a kernel configuration from the same version of the kernel.
 105   Debian kernel packages store a copy of their kernel configuration in
 106   /boot/config.version_number.
 107
 108   The kernel configuration needs to be identical to the configuration that
 109   produced the kernel that you're using.  Ideally, you would build the
 110   kernel image you're going to use with make-kpkg kernel_image and install
 111   that along with the module image, although as long as the configuration
 112   is identical, you may be able to get away with using a pre-built kernel.
 113   (A better approach, if you're using pre-built kernels, may be to use
 114   module-assistant as described above.)
 115
 116   Finally, build the modules:
 117
 118       make-kpkg modules_image
 119
 120   You may need to use the --append_to_version switch to add version
 121   suffixes like -686 or -smp to match your kernel and install the OpenAFS
 122   module into a directory like /lib/modules/version-686.  Be aware that
 123   the Debian OpenAFS packages build either a regular module or an SMP
 124   module, not both, so the generated package will only work with a kernel
 125   with the same SMP configuration.
 126
 127   An openafs-modules deb should be created in /usr/src.  Use dpkg -i to
 128   install this package.