Re: Programming Tutorial
Hi,
Please look at the following README, and see if you can use
the information about how to compile the kernel image into a .deb
file for the tutorial. Actually, there are two documents embedded
within: the rationale for using kernel-package, and instructions for
compilation.
manoj
Advantages of using make-kpkg
---------- -- ----- ---------
I have been asked several times about the advantages of using
the kernel-package package over the traditional Linux way of hand
compiling kernels, and I have come up with this list. This is off the
top of my head, I'm sure to have missed points yet. Any additions
welcomed.
i) Convenience. I used to compile kernels manually, and it
involved a series of steps to be taken in order;
kernel-package was written to take all the required steps (it
has grown beyond that now, but essentially, that is what it
does). This is especially important to novices: make-kpkg
takes all the steps required to compile a kernel, and
installation of kernels is a snap.
ii) It allows you to keep multiple version of kernel images on
your machine with no fuss.
iii) It has a facility for you to keep multiple flavours of the
same kernel version on your machine (you could have a stable
2.0.33 version, and a 2.0.33 version patched with the latest
drivers, and not worry about contaminating the modules in
/lib/modules)
iv) It knows that some architectures do not have vmlinuz (using
vmlinux instead), and other use zImage rather than bzImage,
and calls the appropriate target, and takes care of moving the
correct file into place.
v) Several other kernel module packages are hooked into
kernel-package, so one can seamlessly compile, say, pcmcia
modules at the same time as one compiles a kernel, and be
assured that the modules so compiled are compatible.
vi) It enables you to use the package management system to keep
track of the kernels created. Using make-kpkg creates a .deb
file, and dpkg can track it for you. This facilitates the task
of other packages that depend on the kernel packages.
vii) It keeps track of the configuration file for each kernel image
in /boot, which is part of the image package, and hence is
the kernel image and the configuration file are always
together.
viii) It allows to create a package with the headers, or the
sources, also as a deb file, and enables the package
management system to keep track of those (and there are
packages that depend on the package management system being
aware of these packages)
ix) Since the kernel image package is a full fledged Debian
package, it comes with maintainer scripts, which take care of
details like offering to make a boot disk, manipulating
symbolic links in / so that you can make boot loader scripts
static (just refer to the symbolic links, rather than the real
image files; the names of the symbolic links do not change,
but the kernel image file names change with the version)
x) There is support for the multitudinous sub architectures that
have blossomed under the umbrella of the m68k architecture.
xi) There is support there for optionally applying patches to the
kernel provided as a kernel-patch .deb file, and building a
patched kernel auto-magically, and still retain an UN-patched
kernel source tree
xii) It allows you compile kernel images for other machines on a
central, possibly faster machine, and transport the kernel image
and modules in a .deb file.
Disadvantages of using make-kpkg
------------- -- ----- ---------
i) This is a cookie cutter approach to compiling kernels, and
there are people who like being close to the bare metal.
ii) This is not how it is done in the non-Debian world. This
flouts tradition. (It has been pointed out, though, that this
is fast becoming Debian tradition)
iii) It forces you to use fakeroot or sudo or super or be root to
create a kernel image .deb file (this is not as bad as it
used to be before fakeroot)
______________________________________________________________________
$Id: README,v 1.17 1998/05/11 06:54:54 srivasta Exp $
This is the Debian Linux packaging scripts for the Linux kernel.
This package has been put together by Manoj Srivastava <srivasta@debian.org>.
INSTALLATION NOTES:
To use this package to create kernel-image packages, you need to get
the kernel source (available from your favorite Linux archive),
unpack your kernel somewhere. Preferably somewhere other than
/usr/src/linux (more on this later).
Before you go any further, please allow me to point out that you need to
have a few other packages installed before you can compile your own kernels
(it is difficult to compile anything without a compiler ;-).
Firstly, you will need gcc, the libc development package (libc5-dev or
libc6-dev at the time of writing), and, on Intel platforms, bin86. [If
you use the menuconfig target of make, you will need ncursesX.X-dev,
and make xconfig also requires tkX.X-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).
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.
Of course, pretty gui front ends to kernel configuration require more
packages, but they are not strictly essential (though quite nice really).
For the Brave and the impatient:
1% cd <kernel source tree>
2% make config # or make menuconfig or make xconfig and configure
3% make-kpkg clean
4% make-kpkg --rootcmd fakeroot --revision=custom.1.0 kernel_image
5% dpkg -i ../kernel-image-X.XXX_1.0_<arch>.deb
6% shutdown -r now # If and only if LILO 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 priviledges.
Unpacking kernel sources:
-------------------------
On a debian system, /usr/src/linux always either contains
include/{linux,asm} or points to a directory which contains
those subdirectories, usually a directory with the full kernel
source or a directory with just the kernel headers.
Debian has standardized on /usr/src/linux being a link (that is the
case if you install released debian kernel packages, and has been
for a while now).
If you like living on the edge and compiling your own kernel
packages ;-), you have to follow the convention of letting
/usr/src/linux be a link, and unpack the pristine kernel sources
someplace else.
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. Remember to re-link /usr/src/linux to point to this
directory, like: (cd /usr/src; rm linux; ln -s linux-X.X.XX)
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).
Now, cd linux (wherever you have created the kernel sources).
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.
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.
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 for it to have an
effect). So, if you re-run make-kpkg with a different revision number,
you have to reconfigure the kernel.
b) It may contain only alphanumerics and the characters + . (full stop,
and plus) and should contain a digit. NOTE: No hyphens allowed. (Look
at Chapter 5 of the Programmers 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; (which makes older dpkg very
confused), 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 BGO 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 ( eg. "a" > "2" like "b" > "a". ) This way,
dselect will not try to upgrade your "roll-it-yourself" kernel-image when
the 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 --rootcmd fakeroot --revision=3:custom.1.0 kernel_image
And the next time when you build a kernel, because you just bought a new
soundcard or you discovered that you suddenly want masquerading in your
kernel enabled, you'll type:
make-kpkg --rootcmd fakeroot --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
bootfloppy 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.
yesPeople who want to have multiple flavours of the same kernel version
around should look at the file /usr/doc/kernel-package/Flavours.gz for
details (Note: This involves modifying the kernel sources top level
Makefile; not recommended unless you are *sure* you need it).
You may also place long term directives (like your name and email
address) in the file /etc/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 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
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
/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.00.
image_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 IMAGE_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_symlink Mutualy exclusive to reverse_symlink. Can be used with
image_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 differes 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_symlink Mutualy exclusive to no_symlink. Can be used with
image_in_boot. Just like no_symlink, except that the
/boot/vmlinuz-X.XX is sym linked to the real new
image, vmlinuz. This too restricts you to just two
images unless futher 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.
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. This
is still evolving.
root_cmd This should be set to a means of gaining super user
access (for example, `sudo' or `fakeroot') as needed
by dpkg-buildpackages's -r option. Ths is only
relevant for the buildpackage taregt, when it is used
to call dpkg-buildpackage with the proper
options. The environment variable ROOT_CMD over-rides
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 over-rides this.
make_libc_headers This is meant to be used by the libc6 maintianer,
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 instablity in all code
compiled on your machine. You have been warned. The
environment variable MAKE_LIBC_HEADERS over-rides
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.
These values over ride the defaults.
c) Variables can also be set by setting a corresponding environment
variable. These values over ride 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
over rides all the above methods.
Please see kernel-pkg.conf (5).
To generate a new kernel image, just run
% make-kpkg clean
% make-kpkg --rootcmd fakeroot --revision custom.1.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 will
offer you a chance to create a boot disk, or to run LILO, 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.
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
% make-kpkg --rootcmd fakeroot --revision custom.1.0 kernel_image
To create a source or header package, run
% make-kpkg clean
% make-kpkg --rootcmd fakeroot --revision custom.1.0 kernel_source
% make-kpkg --rootcmd fakeroot --revision custom.1.0 kernel_headers
Note: You only need one of these.
Similarly, the documentation package is built by:
% make-kpkg --rootcmd fakeroot --revision=custom.1.0 kernel_doc
Or if you want to generate the whole package,
% make-kpkg --rootcmd fakeroot --revision custom.1.0 \
-pgpsign "Your pgp id" buildpackage
Note that this needs a pgp key.
A note on LILO: 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 LILO take
advantage of this by putting image = /vmlinuz and image = /vmlinuz.old
lines in your lilo.conf (please read documentation on LILO for
details)
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.
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 sym
links 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.
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).
--
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
--
Manoj Srivastava <srivasta@acm.org> <http://www.datasync.com/%7Esrivasta/>
Key C7261095 fingerprint = CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
--
To UNSUBSCRIBE, email to debian-doc-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
Reply to: