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

This is the Debian GNU/Linux prepackaged version of the Linux kernel.
Linux was written by Linus Torvalds <Linus.Torvalds@cs.Helsinki.FI> and
others.

This package was put together by Herbert Xu <herbert@greathan.apana.org.au>

Linux is copyrighted by Linus Torvalds and others.

   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License as published by
   the Free Software Foundation; version 2 dated June, 1991.

   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
   GNU General Public License for more details.

   You should have received a copy of the GNU General Public License
   along with this program;  if not, write to the Free Software
   Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
   02111-1307  USA 

On Debian GNU/Linux systems, the complete text of the GNU General
Public License can be found in `/usr/share/common-licenses/GPL'.

INSTALLATION NOTES:

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). 

Oh, and of course, make-kpkg is part of kernel-package, usually found
in section misc.


 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
 4% $Get_Root make-kpkg --revision=custom.1.0 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 official kernel image packages) you need to
      add --initrd to the line above.
   % $Get_Root make-kpkg --initrd --revision=custom.1.0 kernel_image 
      Personally, I prefer non initrd images for my personal machines,
      since then adding third party modules to the machine has fewer
      gotchas
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!!

 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.

 If you're using the patch_the_kernel facility, you may want to remove
 step 2 and instead insert `--config=menuconfig' into the make-kpkg
 command-line of step 4 (or perhaps use `xconfig' or `config' (or, for
 2.6.X kernels, `gconfig') in place of `menuconfig').  This way,
 patching the kernel happens before menuconfig (or whichever), and
 you'll get better defaults for any questions introduced by the
 patches. (Also look at the --added_patches command line option to
 selectively apply some patches in conjunction with patch_the_kernel)

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

 You can get kerel sources in several different ways: by installing a
 prepackaged Debian kernel source package (at the time of writing, it
 is kernel-source-2.4.20_2.4.20-6_all.deb). 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
 favourite 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 optionsl, 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
------------- ----

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 make menuconfig (please look at the kenrel
documentaion for help on configuring your kernel).

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 (in other words,
   if a file called stamp-configure exists, this option has no effect
   -- run make-kpkg clean or manually remove stamp-configure,
   stamp-debian, and debian/official for it to have an effect -- I
   strongly suggest make-kpkg clean unless you know what you are
   doing).  Additionally, official source package maintainers provide
   their own version numbers and data for the official uploads, and
   hence a number of things, including the Debian revision, is not
   modified by make-kpkg.  If you happen to have an official source,
   (that would mean that the file debian/official exists), and want to
   use your own revision number, make sure you remove debian/official
   before running make-kpkg clean for this option to have an effect.
   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.
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 custom.Y, so the image package become
kernel-image-X.X.XX-custom.Y.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
"custom-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:custom.Y; the kernel image file shall remain
kernel-image-X.X.XX-custom.Y.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
  $Get_Root make-kpkg --revision=3:custom.1.0 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
  $Get_Root make-kpkg --revision=3:custom.2.0 kernel_image
      (Get_Root is whatever you need to become root -- fakeroot or
      sudo are examples that come to mind).
(remember to do a make-kpkg clean before you compile again with a
different revision, or else the revision flag shall not have any
effect)

 NOTE about using initial ram disk images (initrd).  Recent official
 kitchen sink kernel image packages tend to use this, in order to
 accomodate as wide a vareity 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 intrd, 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
   $Get_Root make-kpkg --initrd --revision=3:custom.2.0 kernel_image

When make-kpkg is finished, you'll have 
kernel-image-2.0.29_custom.1.0_i386.deb and all it takes now is to
install the package (as root):
# dpkg -i kernel-image-2.0.29_custom.1.0_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 [having remembered
to do a make-kpkg clean in between ;-], 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_custom.1.0_i386.deb
and later get rid of the .save directory.

People who want to have multiple flavours 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.

link_in_boot	Set to True if you want the kernel image symlink (vmlinuz)
                in /boot rather than the default /. Can be set from the
		environment variable LINK_IN_BOOT. Defaults to
		undefined. 

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

no_symlinks     Mutually exclusive to reverse_symlinks Can be used with
                link_in_boot. The image is placed in vmlinuz (instead
                of /boot/vmlinuz-X.X.XX). The old vmlinuz is moved to
                vmlinuz.old unconditionally. (Normally, that is only
                done if the version of the new image differs from the
                old one). This restricts you to two images, unless you
                take additional action and save copies of older
                images. This is for people who have /boot on a system
                that does not use symlinks (and say, they use loadlin)
                This is a Hack.

reverse_symlinks Mutually exclusive to no_symlinks. Can be used with
                link_in_boot. Just like no_symlinks, except that the
                /boot/vmlinuz-X.XX is symlinked to the real new
                image, vmlinuz. This too restricts you to just two
                images unless further action is taken. The older
                symlinks are left dangling. This is for people with
                /boot on umsdos, and who can't see the link in dos, 
                but do want to know the image version when in Linux. 
                This is a Hack.

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).

patch_the_kernel This is an experts only variable. If set to YES (ENV
                 variable PATCH_THE_KERNEL overrides this), the build
                 process causes run-parts to be run over
                 /usr/src/kernel-patches/$(architecture)/apply and
                 (hopefully) reverses the process during clean by
                 running run-parts over
                 /usr/src/kernel-patches/$(architecture)/unpatch. The
                 special architecture all is used for arch independent
                 patches. You may use the --added_patches command line
                 in conjunction with this variable to selectively
                 apply only some patches from that directory. The
                 people who package the pacthes should have arranged
                 to have the order of application and unapplication be
                 sane. This variable is automatically set to YES if
                 you use the option --added-patches.

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
              symlinc 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 woudl 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: 

This file is automatically created by the installation script if it
does not exist, and neither does the symbolic link /vmlinuz.  The
script asks the user whether the symbolic link should be created, and
stashes the answer into /etc/kernel-img.conf

no_symlinks     Mutually exclusive to reverse_symlinks Can be used with
                link_in_boot. The image is placed in vmlinuz (instead
                of /boot/vmlinuz-X.X.XX). The old vmlinuz is moved to
                vmlinuz.old unconditionally. (Normally, that is only
                done if the version of the new image differs from the
                old one). This restricts you to two images, unless you
                take additional action and save copies of older
                images. This is for people who have /boot on a system
                that does not use symlinks (and say, they use loadlin)
                This is a Hack.

reverse_symlinks Mutually exclusive to no_symlinks. Can be used with
                link_in_boot. Just like no_symlinks, except that the
                /boot/vmlinuz-X.XX is symlinked to the real new
                image, vmlinuz. This too restricts you to just two
                images unless further action is taken. The older
                symlinks are left dangling. This is for people with
                /boot on umsdos, and who can't see the link in dos, but
                do want to know the image version when in Linux. 
                This is a Hack.

do_symlinks  By default,  the  kernel  image  post installation
              script shall create or update the /vmlinuz and
              /vmlinuz.old symbolic links.  This is true if a /vmlinuz
              link already exists, however, in absence of /vmlinuz,
              the script looks to see if this configuration file
              exists. If it does not, the configuration script asks
              the user whether to create the symbolic link, and
              stashes the answer in a newly created
              /etc/kernel-img.conf.  If the configuration file already
              exists, and if this option is set to no, no symbolic
              link is ever created. This for people who have other
              means of booting their machines, and do not like the
              symbolic links cluttering up their / directory.

link_in_boot	Set to True if you want the kernel image symlink
                (vmlinuz) in /boot rather than the default /.
                Defaults to undefined. 

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.

do_boot_enable
              If set to NO, this shortcircuits all attempts to create
              boot floppies, run lilo, etc. This has the additional
              side effect that the postinst is silent. Setting both
              do_bootfloppy and do_bootloader to NO implies setting
              do_boot_enable to NO. Defaults to Yes.

do_bootfloppy
              If set to NO, this prevents the postinst from asking
              questions about creating a boot floppy, and no boot
              floppy is created. The bootloader shall still be run.
              This may cut down on the interaction the postinst has.
              (It still prompts before formatting /dev/fd0). Defaults
              to Yes.

do_bootloader
              If set to NO, this prevents the postinst from running
              the bootloader. The user may still be asked to create a
              floppy, unless do_bootfloppy is also set to NO. Defaults
              to Yes.

postinst_hook
              Set this variable to a script to be executed during
              installation after all the symbolic links are  cre-
              ated,  but before running the bootloader or  offer-
              ing to create a floppy. 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
% $Get_Root make-kpkg --revision=custom.1.0 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:custom.2.0 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
% $Get_Root make-kpkg --revision=custom.1.0 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:custom.2.0 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)        |
| % make-kpkg clean                                                     |
| % make-kpkg  --revision=custom.1.0 build                              |
| % $Get_Root make-kpkg --revision=custom.1.0 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:custom.2.0 kernel_image   |
|                                                                       |
-------------------------------------------------------------------------

To create a source or header package, run
% make-kpkg clean
% $Get_Root make-kpkg --revision=custom.1.0 kernel_source
% $Get_Root make-kpkg --revision=custom.1.0 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).
Here is a nice, practical example:
% make-kpkg -rfakeroot --append-to-version $(hostname) \
               --revision $(date +'%Y%m%d')

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

Or if you want to generate the whole package, 
% $Get_Root make-kpkg --revision=custom.1.0 \
            --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).

A note on boot loaders: the kernel-image install-scripts arrange to
have /vmlinuz and /vmlinuz.old point to the latest kernel image and
the next most recent one, respectively.  You may choose to have your
boot loader take advantage of this by putting image = /vmlinuz and
image = /vmlinuz.old lines in your lilo.conf (or whatever config files
your boot loader uses -- please read documentation on your boot loader
for details). Oh, and if your kernel image package uses initrd (as do
the newer official kernel image packages), please do not forget to add
a line (initrd=/boot/initrd-2.4.X-foo) in your lilo.conf file
pointing out this fact to your boot loader.

Conversely, people who wish to tightly control the versions in
lilo.conf (believe me, people, this gets to be a pain in the neck
fast) can use image = /boot/vmlinuz-X.X.XX.

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

So that loadlin people don't feel left out, all this talk about LILO
does not mean to ignore loadlin, you can use the generated
kernel-image just as easily (simply ignore the fol-de-rol with symlinks
in /). For instance, you could:

 [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                                            #
#      # $patches is now either empty, or it has --added-patches=a,b    #
#    fi                                                                 #
#    cd $machine                                                        #
#    make-kpkg --rootcmd fakeroot --append-to-version $machine \        #
#        $patches $modules kernel_image                                 #
#    if [ "X$modules" != "X" ]; then                                    #
#       fakeroot make-kpkg  --append-to-version $machine \              #
#            $patches $modules modules_image                            #
#    fi                                                                 #
#    make-kpkg clean                                                    #
#  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 --revison option or a
different debian revision, you shall have to make-kpkg clean, and then
recompile. 

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
         $MAKE_KPKG $MAKE_KPKG_OPTIONS --append-to-version $MACHINE clean
         $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
   and setting up symlinks and configuring lilo.conf and running
   lilo. 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 comman line to build your kernel
   image, with all kinds of bells and whistels, is:

   make-kpkg clean   
   make-kpkg -rootcmd fakeroot --append-to-version -custom.${VER} \
        --revision custom.${VER} kernel_image modules-image
   This one also builds any standalone 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
