installer/doc/custom-kernel.txt

Building Debian Installer images with a custom kernel.

So you want to build a custom version of the Debian Installer? This
document assumes basic familiarity with bilding Debian packages from
source. The techniques described here are aimed mostly at replacing the
kernel, which is the most common piece to need to replace, but similar
techniques can be used to replace any other udeb used by this modular
installer with a custom version.

If you have questions about this document, mail the Debian Installer team
at: <debian-boot@lists.debian.org>.

Step 1. Kernel deb

You need to find or produce a kernel deb for the kernel you want to use
with d-i. This can be built in the standard Debian way with make-kpkg. The
kernel should be built with the following things built in:

        devfs (does not need to automount on boot)
        tmpfs
        unix domain sockets support
        ext2

Most everything else can be modular, and it's a good idea to enable pretty
much everything. A good starting place is the kernel config from an
existing official Debian kernel.

Once you have the kernel-image.deb, install it for the next step. On i386,
you should also install the kernel-pcmcia-modules file. You do not need to
boot into the new kernel.

Step 2. Kernel udebs

Unpack the source package linux-kernel-di-386 (other arches, replace
386 with your arch). In its source tree, edit the kernel-versions file.
Each line in this file is a kernel version, you can comment out all but
one, and modify that one to match the version of your custom kernel.

Make sure the build dependencies of linux-kernel-di-386 are satisfied
(you will need to install the kernel-wedge package), and build the package.
This will produce several udebs.

Step 3. Initrds and images

Unpack the debian-installer source package. Make sure the many build
dependencies are satisfied. Check that build/config/i386.cfg has a
KERNELVERSION field that matches the version of your custom kernel (other
arches, replace 386 with your arch).

Copy the udebs that were produced in step 2 into the build/localudebs
directory. Go to the build directory and type "make list" to see a list
of possible targets. For example, if you want to build floppy images, use
this command:

        fakeroot make build_floppy_boot build_floppy_root

If you're looking to build a complete Debian CD, the target to use is
"build_cdrom_isolinux" (and see step 4).

It turns out to be much easier to build a mini CD containing just d-i,
which you can do with the "build_monolithic" target. You will need a
network connection to install using this image.

Look in the build/dest directory for the images. The MANIFEST file will
list every file you built and its purpose. Note that the
build_cdrom_isolinux target does not produce an entire ISO image, but just
the initrd to go on one. However, the build_monolithic target does produce
a bootable ISO image, and the floppy targets do produce floppy images.

Step 4. Building a full Debian CD image

If you have an initrd for a CD, and some kernel udebs, and a kernel deb,
you probably want to stick them all on a Debian CD. There are two ways to
do this. You can install the debian-cd package and read its documentation.
Be warned that using debian-cd is difficult, and requires a local Debian
mirror. Or you could try to remaster an existing Debian ISO using the
technique described here: 
        http://wiki.debian.net/index.cgi?DebianInstallerModify

Neither of these routes will be as relatively polished or easy as steps
1-3. We recommend that you don't try to build a full Debian CD unless you
really absolutely need one, and have plenty of time to set up debian-cd. An
alternative is to build a monolithic mini iso (as described in step 3).
1	joeyh	12375	Building Debian Installer images with a custom kernel.
2
3			So you want to build a custom version of the Debian Installer? This
4			document assumes basic familiarity with bilding Debian packages from
5			source. The techniques described here are aimed mostly at replacing the
6			kernel, which is the most common piece to need to replace, but similar
7			techniques can be used to replace any other udeb used by this modular
8			installer with a custom version.
9
10	joeyh	12383	If you have questions about this document, mail the Debian Installer team
11	joeyh	12380	at: <debian-boot@lists.debian.org>.
12
13	joeyh	12375	Step 1. Kernel deb
14
15			You need to find or produce a kernel deb for the kernel you want to use
16			with d-i. This can be built in the standard Debian way with make-kpkg. The
17			kernel should be built with the following things built in:
18
19			devfs (does not need to automount on boot)
20			tmpfs
21			unix domain sockets support
22			ext2
23
24			Most everything else can be modular, and it's a good idea to enable pretty
25			much everything. A good starting place is the kernel config from an
26			existing official Debian kernel.
27
28			Once you have the kernel-image.deb, install it for the next step. On i386,
29			you should also install the kernel-pcmcia-modules file. You do not need to
30			boot into the new kernel.
31
32			Step 2. Kernel udebs
33
34			Unpack the source package linux-kernel-di-386 (other arches, replace
35			386 with your arch). In its source tree, edit the kernel-versions file.
36			Each line in this file is a kernel version, you can comment out all but
37			one, and modify that one to match the version of your custom kernel.
38
39			Make sure the build dependencies of linux-kernel-di-386 are satisfied
40			(you will need to install the kernel-wedge package), and build the package.
41			This will produce several udebs.
42
43			Step 3. Initrds and images
44
45			Unpack the debian-installer source package. Make sure the many build
46			dependencies are satisfied. Check that build/config/i386.cfg has a
47			KERNELVERSION field that matches the version of your custom kernel (other
48			arches, replace 386 with your arch).
49
50			Copy the udebs that were produced in step 2 into the build/localudebs
51			directory. Go to the build directory and type "make list" to see a list
52			of possible targets. For example, if you want to build floppy images, use
53			this command:
54
55			fakeroot make build_floppy_boot build_floppy_root
56
57			If you're looking to build a complete Debian CD, the target to use is
58			"build_cdrom_isolinux" (and see step 4).
59
60			It turns out to be much easier to build a mini CD containing just d-i,
61	joeyh	12385	which you can do with the "build_monolithic" target. You will need a
62			network connection to install using this image.
63	joeyh	12375
64			Look in the build/dest directory for the images. The MANIFEST file will
65			list every file you built and its purpose. Note that the
66			build_cdrom_isolinux target does not produce an entire ISO image, but just
67	joeyh	12385	the initrd to go on one. However, the build_monolithic target does produce
68			a bootable ISO image, and the floppy targets do produce floppy images.
69	joeyh	12375
70			Step 4. Building a full Debian CD image
71
72			If you have an initrd for a CD, and some kernel udebs, and a kernel deb,
73			you probably want to stick them all on a Debian CD. There are two ways to
74			do this. You can install the debian-cd package and read its documentation.
75			Be warned that using debian-cd is difficult, and requires a local Debian
76			mirror. Or you could try to remaster an existing Debian ISO using the
77			technique described here:
78			http://wiki.debian.net/index.cgi?DebianInstallerModify
79
80	joeyh	12380	Neither of these routes will be as relatively polished or easy as steps
81			1-3. We recommend that you don't try to build a full Debian CD unless you
82			really absolutely need one, and have plenty of time to set up debian-cd. An
83	joeyh	12385	alternative is to build a monolithic mini iso (as described in step 3).