home *** CD-ROM | disk | FTP | other *** search
/ PC Welt 2006 November (DVD) / PCWELT_11_2006.ISO / casper / filesystem.squashfs / usr / src / linux-headers-2.6.17-6 / debian / docs / README.modules < prev    next >
Encoding:
Text File  |  2005-11-08  |  11.5 KB  |  240 lines
  1.  
  2.         Add on modules and the kernel-package
  3.                 === == ======= === === ==============
  4.  
  5.     There are a number of add-on modules (that is, kernel modules
  6.  are developed apart from the Linux kernel and do not appear in the 
  7.  mainstream kernel sources). Notables, at the time of writing, are the 
  8.  pcmcia-cs and and the alsa sound modules.
  9.  
  10.     Most of these modules need to be compiled for each kernel
  11.  version; they are very dependent on kernel structures. It was
  12.  suggested that it would be nice to be able to build the add-on
  13.  modules whenever one created a new kernel, and kernel-package
  14.  provides some mechanisms to do so for co-operating add-on modules. 
  15.  
  16.     In order for this to work, the add-on modules must appear in
  17.  a standard location, chosen to be $(MODULE_LOC)/<mod-name>/
  18.  (MODULE_LOC defaults to /usr/src/modules, and can be set either in
  19.  the environment or the configuration file), and must arrange to be
  20.  manipulated by the kernel-package mechanisms.
  21.  
  22. USER INSTRUCTIONS
  23. ==== ============
  24.  
  25.      1)   install the source for your module package in a subdirectory of 
  26.           the $(MODULE_LOC)[/usr/src/modules] directory.  Use a
  27.           symbolic link to the actual source tree if you must.
  28.  
  29.      2)   Get kernel sources from your favorite location. (For
  30.           pre-packaged kernels, it may be possible to build third
  31.           party modules by getting the kernel-headers package that
  32.           corresponds to the kernel-image package you have installed,
  33.           and pointing the build system of the kernel headers -- some
  34.           packaged modules packages provide an easy way to use the
  35.           kernel-headers packages, by allowing you to specify it like so:
  36.             [cd $MODULE_LOC/$module/;
  37.               ./debian/rules  KSRC=/usr/src/kernel-headers-X.Y.ZZ binary
  38.              ])
  39.  
  40.      3)   Make sure you have the versions of packages as recommended
  41.           in the Documentation/Changes file. 
  42.  
  43.      4)   Unpack the kernel sources.  Change dir to the unpacked sources.
  44.  
  45.      5)   If you are building a kernel that is custom configured to your
  46.           specifications at this time, go ahead and configure the
  47.           kernel with `make config', `make menuconfig', or `make
  48.           xconfig.'  To build a new kernel-image package, execute:
  49.                make-kpkg --revision number kernel_image
  50.           This will generate a kernel-image-<kernel version> deb file
  51.           in the parent directory.  Here number (the argument supplied
  52.           after the --revision flag) is a version number for your
  53.           custom built kernel.  You may also do this on the fly by
  54.           setting the DEBIAN_REVISION environmental variable.  It is
  55.           important that you choose the revision number in such a way
  56.           that a generic kernel-image package will not override the
  57.           custom package while using dselect (or `dpkg -BOGiE').  I
  58.           recommend a two-level scheme where the major level starts
  59.           with a letter.  One such scheme is your (short) host name
  60.           followed by a dot (.) and a number.  For example, if your
  61.           machine is named myhost, you would use --revision myhost.1
  62.           in the command line.  If you had to rebuild your custom
  63.           kernel, you would use --revision myhost.2 and so on.  See
  64.           /usr/share/doc/kernel-package/README.gz for more information on
  65.           revision numbers.
  66.  
  67.      6)   To build the actual module packages, execute:
  68.                make-kpkg modules_image
  69.           This will generate a  <name>-modules-<kernel version>.deb file in
  70.           the parent directory. The revision you supplied while building the
  71.           kernel shall be used automatically.
  72.  
  73.           If you are using an official Debian kernel-image with specific
  74.           options (kernel-image-x.y.z-foo), you should append this version
  75.           for modules compilation:
  76.                make-kpkg --append-to-version -foo modules_image
  77.           (e.g. of foo at this time are "386", "k6", "586tsc"...)
  78.           A revision number based on the date shall be used automatically.
  79.           You can however force the revision number using the --revision
  80.           flag (see 3.1).
  81.  
  82.      7) Install the two newly created deb files (you can use `dpkg -i
  83.           file').
  84.  
  85.      8)   Clean the source trees:
  86.                make-kpkg modules_clean clean 
  87.  
  88. MODULE MAINTAINER INSTRUCTIONS
  89. ====== ========== ============
  90.  
  91.      1)   install the source for your module package in a subdirectory of 
  92.           the $(MODULE_LOC)[/usr/src/modules] directory.  Use a
  93.           symbolic link to the actual source tree if you must.
  94.  
  95.      2)   if you are modules maintainer and want to build the set of
  96.           binary modules packages that will work with each of the
  97.           variants of the kernel that are in the archive, you want to
  98.           use the sources for the official kernel-images.
  99.           
  100.           apt-get source kernel-image-2.4.18-386 (substitute as
  101.            appropriate for kernel version and architecture)
  102.  
  103.      3)   satisfy the build-deps of that image.
  104.  
  105.      4)   debian/rules unpack
  106.  
  107.      5) If you are building a whole set of modules for all
  108.          sub-architectures, you can do something like:
  109.            for i in 386 586tsc 686 686-smp k6 k7; do
  110.          cd build-$i
  111.          make-kpkg modules --append_to_version -$i
  112.          make-kpkg modules_clean
  113.          cd ..
  114.           done
  115.           Change the list of flavours as appropriate for your
  116.           architecture of course. See configs in config/ directory.
  117.           cp /boot/config-<kernel version> build-$i.config, etc, as needed. 
  118.  
  119.      6)  Test, sign and upload the various .changes and .deb files
  120.          that result.
  121.  
  122. ======================================================================
  123.  
  124.         kernel-package provides for four targets for the use of
  125.  stand-alone kernel modules packages.
  126.  
  127.     The special targets to give to make-kpkg are:
  128.  a) modules-image modules_image:   only generate module binary
  129.                    packages. Please remember to clean
  130.                    the modules after the build; see
  131.                    the sample files for an example. 
  132.  b) modules:                       generate the modules packages and
  133.                                    sign them with dchanges (this
  134.                                    creates the source and diff packages
  135.                                    as well)
  136.  c) modules-config modules_config: only configure the module
  137.  d) modules-clean  modules_clean:  Clean the modules source tree, and
  138.                    undo all changes made by the above
  139.                    commands. 
  140.     
  141.     So, add to the 
  142. 4% fakeroot make-kpkg --revision=custom.1.0 kernel_image 
  143. 4a% fakeroot make-kpkg --revision=custom.1.0 modules_image,
  144.         and remember to install the modules (after you have installed
  145.  the kernel-image) by saying 
  146. 5# dpkg -i ../kernel-image-X.XXX_1.0_<arch>.deb
  147. 5a# dpkg -i $(MODULE_LOC:-/usr/src/modules)/<mode-name>-<version>.deb
  148.     
  149. MODULE Packaging hints
  150. ====== ========= =====
  151.  
  152.         make-kpkg arranges to cd into each modules top directory,
  153.  $(MODULE_LOC:-/usr/src/modules)/<mod-name>/, and runs ./debian/rules
  154.  <target>.
  155.  
  156.  <target> can be one of:                                                       
  157.  kdist_image           Create the binary image of the module                   
  158.                        * Called for make-kpkg modules_image                    
  159.  kdist                 Generate the modules packages and sign them             
  160.                        * Called for make-kpkg modules                          
  161.  kdist_configure       Configure the modules packages                          
  162.                        * Called for make-kpkg modules_config                   
  163.  kdist_clean           Clean the modules source tree                           
  164.                        * Called for make-kpkg modules_clean                    
  165.                                                                   
  166.      Starting with kernel version 2.6.X, the build process is
  167.  for third party modules has been modified; now modules are expected
  168.  to build in the kernel sources dir, and you set the SUBDIR arg to
  169.  point to the source for the module itself. This arranges for the
  170.  kernel makefiles to do all the boilerplate work of building/running
  171.  modpost, dependencies, et cetera.  Here's the "new" way of building a
  172.  kernel module (both as used by alsa-source and as recommended by the
  173.  kbuild maintainer):
  174.                                                                                 
  175.  ifdef NEW_KBUILD                                                               
  176.          $(MAKE) -C $(CONFIG_SND_KERNELDIR) SUBDIRS=$(MAINSRCDIR)/kbuild modules
  177.  else                                
  178.  
  179.     The problem is that unless the module passes in the same
  180.  EXTRAVERSION=XYZ argument that the main kernel build process did,
  181.  include/linux/version.h shall be regenerated, with a different value
  182.  now than when the kernel was compiled. The only way to avoid this is
  183.  to make sure the module passes EXTRAVERSION also; the 2.6 kernel
  184.  makefile is very enthusiastic about making sure version.h is up to
  185.  date.
  186.  
  187.     So, make-kpkg now passes a new parameter, KPKG_EXTRAV_ARG, to
  188.  the module; the value is either empty, or a string like
  189.   "EXTRAVERSION=X.Y.Z". The idea is that you can call 
  190.      $(MAKE) $(KPKG_EXTRAV_ARG) ... 
  191.  and have the same version.h info as the main kernel image does.
  192.  
  193.      Additionally, the following information is provided in the
  194.  environment:
  195.  a) KVERS  Contains the kernel version
  196.  b) KSRC   Contains the location of the kernel sources 
  197.  c) KMAINT Contains the Name of the maintainer to pass to PGP
  198.  d) KEMAIL Contains the email address of the maintainer
  199.  e) KPKG_DEST_DIR Contains the destination directory where the .debs are put
  200.  f) KDREV  Contains the Debian revision used for the kernel image
  201.  g) KPKG_MAINTAINER Contains the Name of the maintainer (may be different from 
  202.                     KMAINT, since the latter can be a key id)
  203.  
  204.     Additionally, the following variables may also be present in the 
  205.  environment:
  206.    h) APPEND_TO_VERSION This contains a string to be appended to the 
  207.                         EXTRAVERSION variable. This is already factored 
  208.                         into the KVERS variable above.
  209.    i) INT_SUBARCH Contains the SUB arch if any if and only if the 
  210.                   ARCH_IN_NAME variable has been set. I suspect that the
  211.                   user wants the .deb names to be modified (but not the
  212.                   kernel version or the location of the dir in which to
  213.                   find modules if this is set. This is *NOT* factored
  214.                   into KVERS above, and is there to be used at your
  215.                   discretion. 
  216.    j) UNSIGN_CHANGELOG  A boolean
  217.    k) UNSIGN_SOURCE     A boolean
  218.    l) ROOT_CMD          a program, like sudo or fakeroot
  219.    m) root_cmd This is a misnomer. That variable actually holds arguments
  220.                for dpkg, specifically, -uc -us -r<blah>, or any
  221.                combination thereof, asd requested by the user. This
  222.                may be set in the config file, so if this variable
  223.                exists, it incorporates and over rides the env vars
  224.                UNSIGN_CHANGELOG, UNSIGN_SOURCE, and ROOT_CMD
  225.    n) CONCURRENCY_LEVEL The setting from the user passed in to pass to
  226.       make -j. kernel-package itself does not call the modules target
  227.       with -j since it does not know if that is safe; it is up to
  228.       module maintainers to see if this parallel compilation setting
  229.       may be used.
  230.    o) KPKG_EXTRAV_ARG A string. It is either empty, or contains a
  231.       directive to set the EXTRAVERSION variable.
  232.  
  233.     Have fun,
  234.  
  235.     manoj
  236. -- 
  237. Manoj Srivastava  <srivasta@acm.org> <http://www.datasync.com/%7Esrivasta/>
  238. Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05  CC 2D 27 12 1D F5 E8 6E
  239.  
  240.