
    $Id: README,v 1.64 2003/08/26 01:47:23 srivasta Exp $

This is the Debian GNU/Linux packaging scripts for the Linux kernel. 
This package has been put together by Manoj Srivastava <srivasta@debian.org>.

INSTALLATION NOTES:

To use this package to create kernel-image packages, you need to get
the kernel source (available from your favorite Linux archive),
unpack your kernel somewhere. Preferably somewhere other than
/usr/src/linux (more on this later).

Before you go any further, please allow me to point out that you need to
have a few other packages installed before you can compile your own kernels
(it is difficult to compile anything without a compiler ;-). 

Firstly, you will need gcc, the libc development package (libc5-dev or
libc6-dev at the time of writing), and, on Intel platforms, bin86. [If
you use the menuconfig target of make, you will need ncursesX.X-dev,
and make xconfig also requires either tkX.X-dev for 2.4.X kernels, or
libqt3-mt-dev and g++ >= 3.0 for the new 2.6 kernel versions, and 2.6.X
kernels also have an additional option, make gconfig, which requires
libglade2-dev, and other packages these depend on]

The packages suggested are:
devel:        gcc, libc5-dev/libc6-dev, binutils, make, and, for intel
              x86 platforms, bin86 (non-Intel platforms don't need
              this), modutils (or module-init-tools for 2.5.x+ kernels).
interpreters: awk, which is contained in either the mawk or gawk packages
base:         gzip, shellutils, and grep.

Some of these packages are marked essential, and hence are going to be
present on your machine already. Others you have to check and install.

Also, please note that some versions of gcc do not interact well with
the kernel sources (gcc 2.95 has problems compiling the kernel without
the flag '-fno-strict-aliasing'. This issue has been taken care of for
recent kernels (2.2 and 2.4 series are fine) (I think you may have to
edit the makefile for older kernels, or something).  You may control
which version of gcc used in kernel compilation by setting the
Makefile variables CC and HOSTCC in the top level kernel Makefile. You
can do this simply by 
  % MAKEFLAGS="CC=gcc-3.2" make-kpkg ...
(please see the top level kernel Makefile).

Of course, pretty GUI front ends to kernel configuration require more
packages, but they are not strictly essential (though quite nice really). 


 For the Brave and the impatient: (Look for Kent's 10-Step Procedure
 to Compiling a Debian Kernel near the tail end of this file for
 more detailed HOWTO)

Phase ONE: Getting and configuring the kernel
 1% cd <kernel source tree> (make sure you have write permission there)
 2% make config # or make menuconfig or make xconfig (or, for 2.6.x
    kernels, make gconfig) and configure

Phase TWO: Create a portable kernel image .deb file
 3% make-kpkg clean 
    Or just rm -rf ./debian, if you do not want to get rid of the
    previous state and only rebuild whatever required for any
    changes. 
 4% $Get_Root make-kpkg --revision=1.0.custom kernel_image 
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).  NOTE: if you have
      instructed your boot loader to expect initrd kernels (which is
      the norm for recent kernel image packages) you need to
      add --initrd to the line above.
   % $Get_Root make-kpkg --initrd --revision=1.0.custom kernel_image 
      Personally, I prefer non initrd images for my personal machines,
      since then adding third party modules to the machine has fewer
      gotchas. Note that you will have to arrange for the actual
      initrd creation to take place by installing a script like
      /usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/yaird
      or, alternately,
      /usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/initramfs 
      into the corresponding directories /etc/kernel/post{inst,rm}.d,
      since the kernel-postinst does not arrange for the initramfs
      creator to be called. You can thus select your own;
      initramfs-tools or yaird.

Phase THREE: Install the kernel image on one or more machines
 5# dpkg -i ../kernel-image-X.XXX_1.0_<arch>.deb
 6# shutdown -r now # If and only if LILO/SILO/QUIK/PALO/VMELILO/ZIPL/yaboot/..
                    # worked or you have a means of
                    # booting the new kernel. YOU HAVE BEEN WARNED!!

Also, make sure you have configured /etc/kernel-img.conf and also
/etc/kernel/*.d by dropping in the correct scripts there. (symlink
creation, initramfs generation, running boot loaders, etc)

 With the addition of fakeroot ( a really nice program, I recommend
 it). Steps 1 to 4 can be carried out as a non root user. Step 5 does
 require root privileges.

Getting the kernel source
------- --- ------ ------

 You can get kernel sources in several different ways: by installing a
 prepackaged Debian kernel source package created by make-kpkg. This
 shall create a file /usr/src/kernel-source-2.4.20.tar.bz2, which can
 be unpacked wherever you wish. Alternately, you can get
 linux-2.4.20.tar.bz2 from you favorite ftp.kernel.org mirror,
 (/pub/linux/kernel/v2.4/ in the ftp site).

Unpacking kernel sources:
-------------------------

Some of the suggestions about where to unpack the kernel packages are
a) /tmp/linux
b) /var/tmp/linux
c) /usr/local/src/<whatever>
d) /usr/src/linux-X.X.XX; where X.X.XX is the version number of the
   kernel. 

In any case, choose a partition that has a large amount of free space,
since recent kernels, unpacked, run to about 23MB, and you need more
than double that in order to create kernel-image, kernel-source, and
the tar file (that is, if you choose to build everything together with
the dist target in debian.rules -- say if you want, for whatever
reason, to run dchanges on the files created). I needed nearly 60MB to
create the full spectrum of packages for version 1.99.7 (and doubtless
this size will go up in the future) [It has. Now even an gzipped kernel
source is over 23MB].

Make sure that the user who is building the kernel has adequate write
permissions in the kernel source tree, and also has write permissions
in MODULES_LOC and its parent directory, or is using sudo or some
other means of getting these write permission while building.

[ EXAMPLE
So, suppose you have chosen /usr/local/src/kernel as the place to
build kernels.
% cd  /usr/local/src/kernel # or cd /path/to/where-ever/you/have/space
% tar jvvfx /usr/src/kernel-source-2.4.20.tar.bz2
  (or, tar jvvfx /path/to/download/linux-2.4.20.tar.bz2)

	The next two steps are optional, you only need them if you are
 going to create third party modules (stuff in
 /usr/src/module-name.tar.gz)

 % export MODULE_LOC=/usr/local/src/kernel/modules
 % tar jvvfx /usr/src/some-module.tar.gz
]

Now, cd linux (wherever you have created the kernel sources). Make
sure you have the permission to write in that dir, or that you are
using sudo or some other means of getting this write permission while
building.

Configuration File
------------- ----

The kernel now needs to be configured, that is you have to set the
kernel options and select the drivers which are going to be included,
either as builtin, or as external modules. These setting are saved in
a file ./config.  The kernel build infrastructure offers a number of
targets, which invoke different configuration front ends. 

Kernel package by itself does not create any configuration file
(.config); it uses whatever you have. You can use the previous version
made for you machine by copying it over from /boot/config-Y.Y.YY, like
so:
 % cp /boot/config-Y.Y.YY .config
where Y.Y.YY stands for the old version of the kernel that you had
hand tuned.

If you do not wish to copy the old copy over, you can create a new one
from scratch using console-based menu configuration command "make
menuconfig" (please look at the kernel documentation for help on
configuring your kernel). Instead of menuconfig one can use config
(text-based line-by-line configuration front-end) or xconfig (graphical
configuration front-end).

After the configuration process is finished, the new or updated kernel
configuration will be stored in .config file in the top-level
directory.


Versions and revisions
----------------------

The version number is deduced from the kernel Makefile directly to
ensure that the version numbers are in sync[1], so you don't have to
worry about that.

Then, remember to change the revision number (using the --revision
option of make-kpkg).  It has been suggested that you renumber the
revision number in such a way that a generic kernel image package will
not override the custom package while using dselect (or dpkg
-BOGiE). You may also do this on the fly by setting the
DEBIAN_REVISION environmental variable.

"--revision" affects the name of the Debian package itself but not the
kernel name, so "uname -r" won't show the revision, and it will use
the same modules as other revisions of the same version.

If I may digress to talk about "--append-to-version",
"--append-to-version=bla" affects the name of the Debian package
itself, and also appends the append-to-version text to the kernel name
AND to the modules directory name when dpkg installs the kernel, so
this kernel will have its own set of modules, separate from the
modules used by the default kernel with the same version.

The revision number (the argument supplied after the --revision flag)
has certain constraints: 
a) It only has an effect during the configure phase. 
   So, if you want to re-run make-kpkg with a different revision
   number, you have to make sure you start with a clean slate.
   (just rm -rf ./debian should work)
b) It may contain only alphanumerics and the characters + . (full
   stop, and plus) and should contain a digit.  NOTE: No hyphens
   allowed (Look at the Debian Policy manual for details). Optionally,
   you may prepend the revision with a digit followed by a colon (:);
   this shall put your revision into a new epoch; more on this later.

You should _not_ use a "_" in the revision number! As tempting as it may
seem, it actually interferes with the policy.

The revision number is required because dpkg imposes an ordering on
version numbers, so that it can tell whether packages are being up- or
downgraded and so that dselect can tell whether a package it finds
available is newer than the one installed on the system. Dselect uses
an option that prevents a package from being downgraded, for example.

Packaged kernel-images in the distribution also have a version number -
not at all coincidentally coinciding with the kernel version, because it
is used to reflect the upstream version number. Note that the kernel
version is also part of the package's name, thus it appears twice in the
package's file name. It also gets a debian revision number relating to
differences in builds. It then looks like: 
  kernel-image-2.0.29_2.0.29-8.deb

I've found that using a two-level scheme where the major level starts
with a letter nicely does the job -- unless epochs are used,
(--revision Y.custom, so the image package become
kernel-image-X.X.XX-Y.custom.deb), and dselect and dpkg -BOGiE will
refuse to downgrade to a generic kernel (don't give the BOG arguments
to dpkg if you actually do want to downgrade later).

The reason for telling kernel-package that the package has a version
"x.y.whatever.you-want.to+add.more-just.do.not+use.an=underscore" 
is that to dpkg that is always a higher version number than any version
number starting with a numeral ( e.g. "a" > "2" like "b" > "a". ) This way,
dselect will not try to upgrade your "roll-it-yourself" kernel-image when
a new build of the distribution default kernel appears in the archive. 


Unfortunately, this fails if the upstream maintainer uses epochs to
correct a version misnumbering ;-(. The good news is that you can add
your own epoch to your customized image, ugly though that may
be. (--revision 1:Y.custom; the kernel image file shall remain
kernel-image-X.X.XX-Y.custom.deb, but dpkg shall know that it should
not replace that with a standard kernel with an epoch. Hopefully, we
shall never see an epoch greater than 1 on a standard kernel, but who
knows. Choose your epoch, if you must use it, wisely. I fear, though,
that with the introduction of epochs in kernel image versions shame
has entered the garden of eden, and we must forever use epochs to
guard against forced upgrades.

So, try using an epoch for your custom packages: 
  make-kpkg clean
      (or just rm -rf ./debian, if you do not want to rebuild from the
      beginning)
  $Get_Root make-kpkg --revision=3:1.0.custom kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).

And the next time when you build a kernel, because you just bought a new
sound card or you discovered that you suddenly want masquerading in your
kernel enabled, you'll type: 
  make-kpkg clean
      (or just rm -rf ./debian)
  $Get_Root make-kpkg --revision=3:2.0.custom kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
(remember to do rm -rf ./debian or a make-kpkg clean before you
compile again with a different revision, or else the revision flag
shall not have any effect)


Note that you will have to arrange for the actual initrd creation to
take place by installing a script like
/usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/yaird
or, alternately, 
/usr/share/kernel-package/examples/etc/kernel/post{inst,rm}.d/initramfs
into the corresponding directories /etc/kernel/post{inst,rm}.d, since
the kernel-postinst does not arrange for the initramfs creator to be
called. You can thuse select your own; initramfs-tools or yaird


 NOTE about using initial ram disk images (initrd).  Recent
 kitchen sink kernel image packages tend to use this, in order to
 accommodate as wide a variety of root file system types as humanly
 possible without building them all into the kernel. In order to use
 these images, you need to instruct you boot loader that this is a
 kernel image using initrd, and tell the boot loader where to find the
 initrd image.  Unfortunately, you can't just substitute a non initrd
 image afterwards without changing the boot loader instructions.  So,
 if your boot loader configuration expects to see an initrd image, add
 --initrd to the above invocation, like so:
   make-kpkg clean
        (or just rm -rf ./debian, if you do not want to rebuild from the
         beginning)
   $Get_Root make-kpkg --initrd --revision=3:2.0.custom kernel_image

With the new kernel-package conventions, you also need the example
scripts in /etc/kernel/postinst.d/ and /etc/kernel/postrm.d, to create
and remove the initramfs. Make sure that these scripts pay attention
to the INITRD env variable to determine whether or not to take any
action. 


 Let me repeat: 
 Since nothing is created automatically. you need to provide a hook
 script for things to happen when you install the kernel image
 package.  The user provides such scripts. For example, to invoke
 mkinitramfs, I did:
--8<---------------cut here---------------start------------->8---
 cp /usr/share/kernel-package/examples/etc/kernel/postinst.d/yaird \
    /etc/kernel/postinst.d/
 cp /usr/share/kernel-package/examples/etc/kernel/postrm.d/yaird \
    /etc/kernel/postrm.d/
--8<---------------cut here---------------end--------------->8---

        Or, alternately, you could do:
--8<---------------cut here---------------start------------->8---
 cp /usr/share/kernel-package/examples/etc/kernel/postinst.d/initramfs \
    /etc/kernel/postinst.d/
 cp /usr/share/kernel-package/examples/etc/kernel/postrm.d/initramfs \
    /etc/kernel/postrm.d/
--8<---------------cut here---------------end--------------->8---

        These scripts above to nothing unless the corresponding
 packages are installed (initramfs-tools or yaird), so you could
 potentially cp both over -- as long as you never install both yaird
 and initramfs-tools at the same time.

        To run grub, I have in /etc/kernel-img.conf:
--8<---------------cut here---------------start------------->8---
postinst_hook = update-grub
postrm_hook   = update-grub
--8<---------------cut here---------------end--------------->8---

You can look at other example in the examples directory:
/usr/share/kernel-package/examples/ to see if there are other example
script you want to cp into /etc/kernel -- and you can create your own
scripts.

For example, if you use linux-headers-* packages to compile third
party modules so that you do not have to keep the sources directory
around, you might be interested in:
--8<---------------cut here---------------start------------->8---
/etc/kernel/header_postinst.d/link
/etc/kernel/header_postrm.d/link
/etc/kernel/header_prerm.d/link
/etc/kernel/postinst.d/force-build-link
/etc/kernel/postrm.d/force-build-link
--8<---------------cut here---------------end--------------->8---

        These scripts will try to make sure that the symlink
 /lib/modules/$VERSION/build 
 is sane -- that is points to the header packages whether you install
 the image packages first, or the header packages first -- and takes
 care of cleanup when either of the packages are installed.


When make-kpkg is finished, you'll have 
kernel-image-2.0.29_1.0.custom_i386.deb and all it takes now is to
install the package (as root):
# dpkg -i kernel-image-2.0.29_1.0.custom_i386.deb

This will install the kernel, the modules, the map file and do some other
administrativia and finally it will ask you if you want to make a
boot floppy and if you want to run lilo now. 

Now, there is a caveat: If you already have kernel 2.0.29 installed,
and you have a freshly created custom 2.0.29 kernel, just installing
the new 2.0.29 kernel shall install modules (as it should) in
/lib/modules/2.0.29, which is where the old modules were! If you have
added or removed modules relative to the old 2.0.29 kernel (very
likely if your old kernel was the default gigantic generic kernel),
then you shall have a mish-mash of modules in /lib/modules/2.0.29 ;-(

Unfortunately, there is no reasonable solution; I suggest moving the
old modules directory before installation, like so (need to be root):

	# mv /lib/modules/2.0.29 /lib/modules/2.0.29.save
	# dpkg -i kernel-image-2.0.29_1.0.custom_i386.deb
and later get rid of the .save directory.

People who want to have multiple flavors of the same kernel version
around should look at the append_to_version flag of make-kpkg. This
appends to the EXTRAVERSION variable of the kernel Makefile, and does
not require one to edit that makefile manually.  This can also be done
by setting the environment variable APPEND_TO_VERSION. The command
line invocation overrides the env variable. 

You may also place long term directives (like your name and email
address) in the file /etc/kernel-pkg.conf (or ~/.kernel-pkg.conf).
Putting your name and address in that file is a good idea, to remind
you that this is not an official package, unless, of course, you
happen to be the maintainer (Hi Herbert). The file
/etc/kernel-pkg.conf (or ~/.kernel-pkg.conf) is actually a Makefile
snippet included during the kernel packages build process, and hence
you may put any legal Makefile directive in that file (just make very
sure you know what you are doing ;-).

        At the moment, the user modifiable variables supported are:

maintainer	Local kernel-* package maintainer.  Please note that
                any apostrophes "'" shall have to be quoted like so: 
                maintainer = John O'\\''Brien. 
                Yes, this is ugly, but this works.

email           The email address of that person.

pgp             Name to search for in the pgp database _iff_ separate
                modules (like pcmcia etc) are being built in
                $(MODULE_LOC:-/usr/src/modules)/*. Can be set from
                environment variable PGP_SIGNATURE. Defaults to
                maintainer.

debian 		The Debian revision of the kernel packages. Can be set
		from the environment variable DEBIAN_REVISION. Defaults
		to 1.0.

kimage		The kernel image type (i.e. zImage or bzImage). Can be
		set from the environment variable IMAGE_TYPE. Defaults
		to bzImage.

image_dest    If  you  want  the  symbolic  link  (or  image,  if
              move_image is set) to be stored elsewhere than /
              set this variable to the dir  where  you  want  the
              symbolic  link.   Please  note  that  this is not a
              boolean variable.  This may be of help  to  loadlin
              users,  who  may  set  both  this  and  move_image.
              Defaults to /. 

root_cmd         This should be set to a means of gaining superuser
                 access (for example, `sudo' or `fakeroot') as needed
                 by dpkg-buildpackages' -r option. This is  used
                 to call dpkg-buildpackage with the proper
                 options. The environment variable ROOT_CMD overrides
                 this.

do_clean	 Set to anything but YES, this shall forego the make
                 clean done in the kernel source tree after building
                 the kernel image package. The environment variable
                 CLEAN_SOURCE overrides this.

install_vmlinux  Set to YES to install the uncompressed kernel
                 ELF image along with the bootable compressed kernel
		 image (vmlinuz).
		 This image is necessary for profiling kernel and
		 userspace with oprofile (oprofile.sourceforge.net,
		 i386 only).

kpkg_follow_symlinks_in_src
              This option is especially useful for people who use
              symlink farms to compile kernels. With this option,
              kernel-source and kernel-header packages shall not be
              just full of dangling symlinks, instead, the symbolic
              links shall be followed. Please note that any symbolic
              links in the kernel sources would be flattened as well.
              The environment variable KPKG_FOLLOW_SYMLINKS_IN_SRC
              overrides this. Symlink farming is described below.

make_libc_headers  This is meant to be used by the libc6 maintainer,
                   when he compiles libc6, to also package up the
                   corresponding headers. DO NOT SET THIS as a
                   mismatch between the headers you package and libc6
                   may well create a subtle instability in all code
                   compiled on your machine. You have been warned. The
                   environment variable MAKE_LIBC_HEADERS overrides
                   this. 

The value of a variable can be set so: 
  a) Defaults exist in the rules file. These are the values used if no
     customization is done.
  b) Variables can be set in the config file /etc/kernel-pkg.conf (or
     ~/.kernel-pkg.conf).  These values override the defaults.
  c) Variables can also be set by setting a corresponding environment
     variable.  These values override the config file and the defaults.
  d) Using make-kpkg options, or, if using the rules file directly, on 
     command line ( # xxx/rules DEBIAN_REVISION=2.0a kernel_image). This 
     overrides all the above methods.

Please see kernel-pkg.conf (5).

However, most of these are done on the machine you compile on: but you
may need to install generic kernel image packages from time to time,
and you need control over where the image sticks the symbolic links
and such. With this in mind, there is the configuration file
/etc/kernel-img.conf which sits on the target machine (the machine
that the dpkg -i is run on, which need not be the same machine the
kernel was compiled on), and that allows you to tweak these variables: 

image_dest    If  you  want  the  symbolic  link  (or  image,  if
              move_image is set)   to be stored elsewhere than  /
              set this variable to the dir  where  you  want  the
              symbolic  link.   Please  note  that  this is not a
              Boolean variable.  This may be of help  to  loadlin
              users,  who  may  set  both  this  and  move_image.
              Defaults to /. This can be used in conjunction with
              all above options except link_in_boot, which would
              not   make   sense.   (If   both   image_dest   and
              link_in_boot are set, link_in_boot overrides).

move_image    Instead  of  creating  symbolic  links  to  (or, if
              reverse_symlinks  is  set,  from)  image_dest,  the
              image  is  moved  from  its  location in /boot into
              image_dest.   If  reverse_symlinks  is  set,  /boot
              shall  contain a symbolic link to the actual image.
              This option can be useful to people using  loadlin,
              who  may need the image to be moved to a  different
              dos partition.  This variable is unset by  default.

clobber_modules
              If  set,  the  preinst  shall  silently try to move
              /lib/modules/version out of the way if  it  is  the
              same  version  as the image being installed. Use at
              your own risk.  This variable is unset by  default.

postinst_hook
              Set this variable to a script to be executed during
              installation. This script shall be called with two
              arguments, the first being the version of the kernel
              image, and the second argument being the location of the
              kernel image itself. Errors in the script shall produce
              a warning message, but shall be otherwise ignored.  An
              example script for grub users is present in
              /usr/share/doc/kernel-package/ directory.
postrm_hook
              Set this variable to a script to be executed in the
              postrm (that is, after the image has been  removed)
              after  all  the remove actions have been performed.
              This script shall be called with two arguments, the
              first  being  the  version of the kernel image, and
              the second argument being the location of the  ker-
              nel  image  itself. Errors in the script shall pro-
              duce a warning  message,  but  shall  be  otherwise
              ignored.

Please see kernel-img.conf (5).


To generate a new kernel image, just run
% make-kpkg clean
  (or just rm -rf ./debian)
% $Get_Root make-kpkg --revision=1.0.custom kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind) or (if you use initrd)
   $Get_Root make-kpkg --initrd --revision=3:2.0.custom kernel_image

This will create a default kernel image (as in the image package or
available on the boot disks.  The kernel image package produced, on
installation, shall offer you a chance to create a boot disk, or to
run LILO (or SILO, QUIK, VMELILO, ZIPL, yaboot, PALO, or update the
grub menu), but the default is not to do either, and you may choose to
ignore these friendly overtures by the postinst.

If you want a custom kernel, you may generate a config file by any of
these methods (just follow the directions).
% make config          # boring old tty based method
or
% make menuconfig      # curses based menu driven method (uses color if 
                         you have any)
% make xconfig         # An X window system based method -- make sure
                         you are running X windows when you call this.
% make gconfig         # The gnome version, if you have version 2.6.X.
All these methods ultimately generate a .config file.  If you already 
have a .config file, just copy it to this directory, and you are go.

With a custom .config file in place (created as above) run again:
% make-kpkg clean
     (or just rm -rf ./debian)
% $Get_Root make-kpkg --revision=1.0.custom kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
   $Get_Root make-kpkg --initrd --revision=3:2.0.custom kernel_image

|-----------------------------------------------------------------------|
|                           Special needs                               |
| Or, for people who want to minimize time spent in fakeroot (for       |
| whatever reasons that maybe -- I think that the separate step as      |
| non-fake-root is not required, but that is a personal opinion)        |
| % test ! -d debian || rm -rf debian                                   |
| % make-kpkg  --revision=1.0.custom build                              |
| % $Get_Root make-kpkg --revision=1.0.custom kernel_image              |
|     (Get_Root is whatever you need to become root -- fakeroot or      |
|     sudo are examples that come to mind)                              |
|                                                                       |
| For people who wish to see the username (not root) when they do a     |
| uname -a on the machine when they install the kernel, there is a      |
| trick:                                                                |
|  % make config                                                        |
|  % make-kpkg build                                                    |
|  % $Get_Root make -f debian/rules stamp-kernel-image                  |
| shall generate a kernel image with the username of the user embedded  |
| in it.                                                                |
|                                                                       |
| If you use initrd images (and have told your boot loader so) you need |
| to include the --initrd option on the command line, like so           |
|                                                                       |
| % $Get_Root make-kpkg --initrd --revision=3:2.0.custom kernel_image   |
|                                                                       |
-------------------------------------------------------------------------

To create a source or header package, run
% make-kpkg clean
  (or rm -rf ./debian)
% $Get_Root make-kpkg --revision=1.0.custom kernel_source
% $Get_Root make-kpkg --revision=1.0.custom kernel_headers
Note: You only need one of these.
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).

Similarly, the documentation package is built by:
% $Get_Root make-kpkg --revision=1.0.custom kernel_doc

Or if you want to generate the whole package, 
% $Get_Root make-kpkg --revision=1.0.custom \
            --pgpsign="Your pgp ID" buildpackage
Note that this needs a pgp key.
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
Here is a nice, practical example:
% make-kpkg -rfakeroot --append-to-version $(hostname) \
             --revision $(date +'%Y%m%d')


For folks using grub, there are now postinst_hook and postrm_hook
variables that can be pointed to scripts that add or remove  a line
from the grub menu list at kernel image install and remove times. A
sample script to add lines to a grub menu file is included in the dir
/usr/share/doc/kernel-package/; and simple scripts like:

  # perl -nle 'print unless /^#Autogenerated by kernel-image $version/ \
                        .. /^#End kernel-image '$version/'

 or for awk fans
  #  awk 'BEGIN{printit=1} 
      /^#Autogenerated by kernel-image $version/{printit=0}
      /^#End kernel-image '$version/{printit=1}
      {if (printit) {print}}'. 
 or
  #  awk '{p=0} 
          /^#Autogenerated by kernel-image $version$/,
          /^#End kernel-image '$version$/ {p=1}
     {if(!p) print}' < foo

 can be put in a script and added to the postrm hook script to remove
 the lines added by kernel_grub_conf.sh


 [1]# dpkg -BRGiE kernel-image-X.X.XX, # need to be root
        and then
 [2]% cp /boot/vmlinuz-X.X.XX <place where loadlin needs image>
 [3]% echo '' > /boot/vmlinuz-X.X.XX

        So you don't have the image taking up space, but still leave a
target for the /vmlinuz symlink.

 MODULES_LOC, SYMLINK FARMING, AND MORE
 ============ ======= ======== === ====

Oh, a quick recipe for people who want to build kernel-module
packages, and don't want to be root to do so (the following assumes
/usr/local/src/kernel is an appropriate location to build kernels):

###############################################################################
# % sudo echo 'MODULE_LOC=/usr/local/src/kernel/modules' \                    #
#                                             >> /etc/kernel-pkg.conf         #
# % sudo echo 'debian := 5:501c' >> /etc/kernel-pkg.conf                      #
# % sudo mkdir -p /usr/local/src/kernel/modules                               #
# % sudo chown -R $(id -n -u) /usr/local/src/kernel/                          #
# % sudo aptitude install cryptoapi-core cryptoloop # for example             #
#                                                                             #
#         Now, we no longer need to be root                                   #
#                                                                             #
# % cd /usr/local/src/kernel/                                                 #
# % wget ftp://ftp.us.kernel.org/pub/linux/kernel/v2.4/linux-2.4.21.tar.bz2   #
# % tar zvvfx /usr/src/cryptoapi-core.tar.gz                                  #
# % tar zvvfx /usr/src/cryptoloop.tar.gz                                      #
# % tar jvvfx linux-2.4.21.tar.bz2                                            #
# % mkdir 2.4.21                                                              #
# % cd 2.4.21                                                                 #
# % lndir ../linux-2.4.21                                                     #
# % cp /boot/config-2.4.20 .config                                            #
# % make-kpkg --rootcmd fakeroot --append-to-version -cryptoloop kernel_image #
# % fakeroot make-kpkg --append-to-version -cryptoloop modules_image          #
###############################################################################

	The above also demonstrates a technique called symlink farming. I like
 to upgrade between kernel version using patches from
 ftp.us.kernel.org; so I need to keep a source tree in as near a
 pristine state as I can. Once I have
 /usr/local/src/kernel/linux-2.4.20, say, I do this:
#########################################################################
#  last_version=2.4.18                        # I never went for 2.4.19 #
#  for machine in kallissin ember smaug scatha glaurung, tiamat ;do     #
#    mkdir $machine                                                     #
#    scp $machine:/boot/config-$last_version $machine/.config           #
#    cd $machine                                                        #
#    lndir ../linux-2.4.20                                              #
#    cd ..                                                              #
#  done                                                                 #
#                                                                       #
#  for machine in kallissin ember smaug scatha glaurung, tiamat ;do     #
#    if [ -f . configdirs/$machine ]; then                              #
#      . configdirs/$machine                                            #
#    fi                                                                 #
#    cd $machine                                                        #
#    make-kpkg --rootcmd fakeroot --append-to-version $machine \        #
#        $modules kernel_image                                          #
#    if [ "X$modules" != "X" ]; then                                    #
#       fakeroot make-kpkg  --append-to-version $machine \              #
#            $modules modules_image                                     #
#    fi                                                                 #
#    test ! -d debian || rm -rf debian                                  #
#  done                                                                 #
#########################################################################

        See? Each lndir directory only has files that were patched, or
 object files; and the ../linux-2.4.20 is pristine, ready to be
 patched up to 2.4.21.


Recompiling a kernel image
----------- - ------ -----

It happens to all of us. When we configured the kernel, we missed out
on an module. Or we added in more things than we really need, and need
to compile again. If you just recompile a kernel image, it shall, when
installed, contain the same /boot/{System.map,config,vmlinuz}-X.X.XX
files and the /lib/modules/X.X.XX directory that the previous kernel
image contained.

If you try to install the recompiled kernel image over the previous
kernel image (same version), then the install scripts detect that, and
ask you to move at least the /lib/modules/X.X.XX dir away. If you
continue anyway, the files in /boot shall be overwritten.

Also, if you try to recompile with a changed --revision option or a
different debian revision, you shall have to remove ./debian, and then
recompile. 

Cross Compiling for a subarchitecture
----- --------- --- - ---------------

Suppose you want to compile a 32 bit kernel on a 64 bit (amd64, say)
machine, this is the incantation to use:

DEB_HOST_ARCH=i386 make-kpkg --arch i386 --cross-compile - <other options>

Tecras and other notebooks 
--------------------------
          (Many thanks to Philip Hands <phil@hands.com> and
           Avery Pennarun <apenwarr@worldvisions.ca> for this explanation)

Tecras and other notebooks, and some PCs have a problem where they
fail to flush the cache when switching on the a20 gate (IIRC), which
is provoked by bzImage kernels, but not by zImage kernels. 

bzImage files are actually "big zImage" not "bzipped Image".  bzImage
kernels can be as large as you like, but because they need to decompress
into extended memory, they aggravate this problem.  zImage kernels just
compress into conventional memory, so they never need to touch the a20 gate,
but they hit the 640k limit.

There are two solutions that I know of:

  1) Apply a patch, which flushes the cache.  Unfortunately this
     causes other machines to crash so is not universally applicable
     (hence the tecra disks being segregated from the mainstream).

  2) Build a zImage, rather than bzImage kernel.  This seems to get
     round the problem. use the --zimage option to make-kpkg, or even
     set this as the default in /etc/kernel-pkg.conf (or
     ~/.kernel-pkg.conf).

There some add-on modules that hook into make-kpkg and the kernel
sources so that they may be kept in synchrony with the kernel you
run. If you have such a module source package, for example,
pcmcia-source, then please read README.modules as well. If you don't
never mind. (The file is in /usr/share/doc/kernel-source-X.X.XX/. If you
don't have kernel-source packages installed [that's OK], there is a
copy in /usr/share/kernel-package/README.modules).

Have fun,

	Manoj Srivastava


Foot note 1:
  For an explanation on why this synchronization is required, consider
  this. The kernel knows what version it is, as given in the kernel
  Makefile as the variables VERSION, PATCHLEVEL, and SUBLEVEL. It will
  look for the modules in /lib/modules/$VERSION.$PATCHLEVEL.$SUBLEVEL.
  The Debian scripts think they know what the kernel version is, as
  given in the Debian file rules as the variable v (near the top). It
  then proceeds to put the modules in /lib/modules/$v.  So, it is
  essential that the kernel (Makefile) and the Debian script (rules)
  agree about the version number, or the kernel will never figure out
  where the Debian scripts hid the modules. So change the version
  number in the file rules (v = X.X.XX) to be the same version as
  given in the kernel Makefile (this will be
  $VERSION.$PATCHLEVEL.$SUBLEVEL).
#############################################################################
#############################################################################
## This is a working script contributed by Don Armstrong 

#!/bin/sh
# Copyright 2004 Don Armstrong (~don@archimedes.ucr.edu)
# This script is licensed under the GPL v2
KERNEL="linux-2.4.24"
MAKE_KPKG="make-kpkg"
EXTRAVERSION=`date +'%m%d%Y'`
MAKE_KPKG_OPTIONS="--rootcmd fakeroot --revision=$EXTRAVERSION"
DATE=`date +'%m_%d_%Y'`

for CONFIG in `cd config; ls *.gz; cd ..`; do
	  MACHINE=$(echo $CONFIG|cut -d _ -f 1);
	  gzip -dc config/$CONFIG > $KERNEL/.config
	  cd $KERNEL
          test ! -d debian || rm -rf debian
	  $MAKE_KPKG $MAKE_KPKG_OPTIONS --append-to-version $MACHINE kernel_image modules_image
    gzip -c .config > ../config/${MACHINE}_config_${KERNEL}_${DATE}.gz
    cd ..;
done;

#############################################################################
#############################################################################
-- 
Manoj Srivastava                        <srivasta@debian.org>
PGP Key ID: 1024/C7261095 
Key fingerprint =  CB D9 F4 12 68 07 E4 05  CC 2D 27 12 1D F5 E8 6E 
======================================================================



	Kent's 10-Step Procedure to Compiling a Debian Kernel
		  Kent West <westk@nicanor.acu.edu>

(I may leave a step or two out, but this is the gist. This example
uses the latest kernel version at the time of writing, which was
2.4.18)

1. Run "dselect". Choose "Update". Choose "Select". "space bar" to get
   out of the Help screens. Use "/" (without the quotes) to start
   search.  Search for "kernel-source". Mark for installation the
   2.4.18 or so.

1b. Use "/" to search for "kernel-package". Mark it for installation 
    also. "Enter" to get back to the main dselect menu.

1c. Choose "Install". This will download a file in /usr/src with a .tgz 
    extension, as well as install "kernel-package".

2. "cd /usr/local/src"

3. "bunzip2 /usr/src/kernel-source-2.4.18.tar.bz2" (or whatever the file is 
   named). This will unzip (decompress) the file.

4. "tar -xvf kernel-source-2.4.18.tar". This will untar the file (x
   means extract, v means "be verbose", f means "use the file named
   ...").  A new subdirectory named kernel-source-2.4.18 will be
   created with all the untarred files under it. You can also do steps
   3 and 4 in one tar command, but I never do; habit is the only
   reason. I think you just add the "j" switch to tar, such as "tar
   -xvjf 'filename'". (It used to be the I switch to tar, but they
   moved from I to j).


Pause and Breathe. You now have the kernel sources installed. You 
haven't done anything with them yet, but they're installed.

5. "cd /usr/local/src/kernel-source-2.4.18" 

6. "make menuconfig". This will start a curses-based (text-based) 
     menu-driven application. There are a lot of choices here, and
     many of them won't make sense to you at all. Take the time to
     look at most all of them (some of them you'll know you don't
     need, like SCSI support if you have an all-IDE system, or Amateur
     Radio Support if you're not a ham) and read the HELP on them if
     they look relevant. A lot of the time the HELP will suggest
     whether you should include it or not, and generally when in
     doubt, leave things set the way they are. Some things to check
     out:
       * the correct processor for your system (AMD vs Pentium vs P4, etc)
       * Symmetric Multi-Processing; "No" if you only have a single processor
       * Loadable module support; "Yes" to all three sub-items.
       * Parallel port support; "Yes" if you have a parallel
         printer. "No" to keep things simple for now if you can live
         without the printer for a while. 
       * Plug-N-Play; "Yes"; ISA P-N-P; only if you have any ISA cards
         installed. 
       * Character devices; turn on Direct Rendering if your video card is 
         listed, and turn on agpgart if your video chipset is listed;
         mice if you  have a PS/2 mouse
       * Sound - find the driver for your card
       * Input core support (some USB stuff needs this, but I'm hazy
         on it - use your best guess) 
       * USB support (make your best guesses; I'm hazy on it)
       * You probably won't need to touch the following:
              - General Setup
              - Memory Technology
              - Block devices
              - Multi-device support
              - Networking options
              - Telephony support
              - ATA/IDE/MFM/RLL support
              - Fusion MPT device support
              - I20 device support
              - Amateur Radio support
              - Infrared support
              - ISDN subsystem
              - Old CD-ROM drivers (unless you have a non-ATAPI CD-ROM
                drive for now; wait till you've compiled a kernel or
                two) 
              - Multimedia devices (unless you have a tv tuner, etc;
                too complicated for now; wait) 
              - File Systems (unless you'll be accessing a
                DOS/FAT/NTFS/etc partition, or Windows shares via smb,
                etc) 
              - Console Drivers (play with different text modes at bootup)
              - kernel hacking

     It's by turning off unneeded stuff that the hackers get their kernels 
     down in size and up in efficiency. But you're not really worried about 
     either at this point.

6b. Exit and save your configuration. This will create a hidden file
    named ".config" in the "/usr/local/src/kernel-source-2.4.18"
    directory. You could edit this file directly to make changes to
    your configuration, but I wouldn't. All that this step (6 and 6b))
    has done is to set up this configuration file. This file is read
    by the actual kernel compilation process to compile the options
    you've specified.


Pause and breathe again. You have now configured your options for the 
next kernel compilation, but you have not yet compiled it.


7. Compile the kernel: use the command "make-kpkg clean; make-kpkg
   kernel_image". This will cause a bunch of grinding and text;
   depending on the speed of your computer and the options you chose,
   this could take minutes (fast computer) to hours (slow
   computer). This step is a Debian-way of compiling the kernel. The
   "other" way is to do it manually, which consists of several steps
   such as "make dep" and "make modules" and "make modules_install"
   and manually finding and moving the kernel to where it needs to
   be. The Debian-way is much easier. The result will be a file named
   something like "kernel-image-2.4.18_2.4.18-10.00.Custom_i386.deb",
   one level up, in "/usr/local/src".

   You can try reading the documentation in the "kernel-package"
   package.  A more complicated command line to build your kernel
   image, with all kinds of bells and whistles, is:

   make-kpkg clean   
     (or just rm -rf ./debian)
   make-kpkg -rootcmd fakeroot --append-to-version -custom.${VER} \
        --revision ${VER}.custom kernel_image modules-image
   This one also builds any stand-alone modules packages you may have
   installed on your machine.


Pause and breathe. You have now compiled your kernel and made a .deb 
file out of it for easy installation.


If you're (re)compiling a kernel with the same version number as your
current version, you'll probably want to run the command "mv
/lib/modules/2.[whateverversion] /lib/modules/2.[whateverversion].old"
to move the old modules out of the way in preparation for the creation
of new modules. If you forget, then step 8 shall warn you that you
need to do this before it overwrites the old modules, and you can just
open a new terminal and do it then without canceling whichever step it
concerns. This is only applicable when (re)compiling the same version
number of kernel as your existing version.

8. Install the new .deb file. Use the command "dpkg -i
   /usr/local/src/kernel-image-2.14.18*.deb". This will install the
   new kernel to where it needs to be (and I believe configure
   /etc/lilo.conf if [and only if] /etc/lilo.conf does not exist) and
   run lilo.


Pause and breathe. You are ready for a reboot to start running your new 
kernel. Make sure you have a backup method for getting into your box (a 
Debian install CD, or boot floppy, etc) in case something goes
wrong. I generally have a lilo.conf file that includes at least one
other image than /vmlinuz and /vmlinuz.old


9. Reboot. After the reboot, you should be running the new kernel.
   Typing "uname -a" will tell you what version of kernel you are
   running.  Test the machine and see if things work properly.


Pause, breathe, celebrate. You've successfully compiled and installed 
your first kernel! You may not have a working sound card or USB stuff 
yet, and other things may have broken, but now that you know the basic 
procedure you can go back and try again.

10: Celebrate.


Have fun!

Kent


