$Id: README,v 1.31.2.1 2000/05/07 17:08:01 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.

Also, please note that some versions of gcc do not interact well with
the kernel sources (the upcoming gcc 2.95 has problems compiling the
kernel without the flag '-fno-strict-aliasing' (I think you may have
to edit the makefile for this, or something). This is an universal
problem, hopefully there shall be a compromise somewhere. 

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:
Phase ONE: Getting and configuring the kernel
 1% cd <kernel source tree>
 2% make config   # or make menuconfig or make xconfig 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).
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 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). To use fake root, try setting ROOT_CMD to 'fakeroot --'. Steps 1
 to 4 can be carried out as a non root user. Step 5 does require root
 privileges.
 
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).

Now, cd linux (wherever you have created the kernel sources).

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.

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 sources,
   (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,
   hyphen, and plus) and should contain a digit.  (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 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
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 mis numbering ;-(. 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: 
  $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)

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 file /usr/share/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). Also, if
recompiling and using a different flavour, one needs to do a make-kpkg
clean in between compiles.

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.  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
                /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_symlinks      Mutually 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 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_symlink Mutually exclusive to no_symlinks. Can be used with
                image_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 image to  be  stored  in  elsewhere
              than  /boot  set this variable to the dir where you
              want the image. This may  be  of  help  to  loadlin
              users.Defaults  to  /boot.  This over rides all the
              above methods.
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. 
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. This is only
                 relevant for the buildpackage target, 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 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 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).

However, most if 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_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 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_symlink Mutually exclusive to no_symlinks. Can be used with
                image_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 image to  be  stored  in  elsewhere
              than  /boot  set this variable to the dir where you
              want the image. This may  be  of  help  to  loadlin
              users.Defaults  to  /boot.  This over rides all the
              above methods.
do_symlink    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 config uration scripts 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.
image_in_boot:	Set to True if you want the kernel image symlink (vmlinuz)
                in /boot rather than the default /. defaults to
		undefined. 
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).

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, 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
% $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).

|-----------------------------------------------------------------------|
|                           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 user name (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 kernel-image-deb                    |
| shall generate a kernel image with the user name of the user embedded |
| in it.                                                                |
-------------------------------------------------------------------------

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

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.

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

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 and flavour), 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 over
written. 

Also, if you try to recompile with a changed --revison option or a
different flavour, 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 segragated 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.


There some add on modules that hook into make-kpkg and the kernel
sources so that they may be kept in synchrony woth 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).

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