/usr/share/kernel-package/docs/README

$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
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=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 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. 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/kerne-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!!

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 built-in, 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 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
(or just rm -rf ./debian, if you do not want to rebuild from the
beginning)
$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
(or just rm -rf ./debian)
$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 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 thus 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:custom.2.0 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 do 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_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, 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 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
symbolic link 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.

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

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

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

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=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) |
| % test ! -d debian || rm -rf debian |
| % 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
(or rm -rf ./debian)
% $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).

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 #
# # $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 #
# 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". 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
make-kpkg -rootcmd fakeroot --append-to-version -custom.${VER} \
--revision custom.${VER} 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

kernel-package 12.036+nmu3 / usr / share / kernel-package / docs / README