Introduction

The Linux kernel is the heart of your Ubuntu Operating System. The kernel that comes with Ubuntu should contain all of the drivers you need, but just in case you would like to tweak your kernel or if for some reason you need to recompile for some special reason this guide will help you.

A less detailed document that shows essentially the same steps as this one can be found in the KernelCompileHowto.

Preparation

You will need the build-essential fakeroot and kernel-package packages, to build a kernel.

bash:~$ sudo apt-get install build-essential fakeroot kernel-package

You will need the gcc-3.4 compiler for 2.6 series kernels

bash:~$ sudo apt-get install gcc-3.4

You will need developer libraries for the kernel configuration tools

bash:~$ sudo apt-get install libqt3-mt-dev libncurses-dev

If apt-get cannot locate libqt3-mt-dev, try libqt3-dev (the older name)

Kernels are built in the /usr/src/ directory. To work there, add yourself to the src group.

bash:~$ sudo adduser my_username src
Adding user my_username to group src...
Done.

Log out and log back in, or use su to log in again:

bash:~$ su my_username
bash:~$ groups
my_username src audio adm dialout cdrom floppy video plugdev lpadmin

Will list all the groups you are in, src should be one of them.

Obtaining the Source

Find the kernel source you want with

bash:~$ apt-cache search source 2.6

Choose the kernel source of your liking.

• Question: The kernel source is sometimes called kernel-source-2.6.5 etc and sometimes linux-source-2.6.8.1. Why?

Answer: See this page about the new version numbering scheme.

kernel-source comes from Debian, linux-source comes from Ubuntu. Use linux-source if at all possible. All the dependencies haven't been changed over yet, though, so if you get warnings about "uninstalled package kernel-source" even though linux-source is installed, you can safely ignore them. -- Bronson

Download the kernel source which matches the running kernel with the following command.

bash:~$ sudo apt-get install linux-source-`uname --kernel-release`

If you have installed a custom kernel then use linux-source and choose from what is listed.

It will download and place the source in /usr/src

Unpacking the Source

I will use the 2.6.8.1 kernel as an example since this is the latest kernel Ubuntu ships at the moment of writing.

bash:~$ cd /usr/src
bash:/usr/src$ ls -l
linux-source-2.6.8.1.tar.bz2

If you see a link called linux to an older kernel source remove it.

bash:/usr/src$ rm linux

do not unpack your kernel if the link is still there. If your new source gets extracted in your old kernel source directory, building will not be successful.

and extract the archive with

bash:/usr/src$ tar jxvf linux-source<version>.tar.bz2

Do not do this with sudo, it is not necessary.

If the source is a .bz2 use tar jxvf, if it is a .gz use tar zxvf

This should create a directory called linux-source-2.6.8.1 owned by you and the src group.

Create a link called linux to the kernel source

bash:/usr/src$ ln -s linux-source-2.6.8.1 linux

Check if it's all in place. You should see something like:

bash:/usr/src$ ls
linux@  linux-source-2.6.8.1/  linux-source-2.6.8.1.tar.bz2

Configuring the kernel

There are several ways to configure the kernel. You will probably use "xconfig". Perform the following steps prior to configuring the kernel:

bash:/usr/src/$ cd kernel-source-version
bash:/usr/src/$ cp /boot/config-`uname --kernel-release` ./.config
bash:/usr/src/$ cd /usr/src/linux

There are two ways to configure the kernel - using an X-based menu or using an ncurses (command-line) menu. To use the X-based menu:

bash:/usr/src/linux$ make xconfig

If you are not using X, or don't want to use your mouse:

bash:/usr/src/linux$ make menuconfig

Warning: you need to ensure that, at a minimum, your bus, disk, and root filesystem drivers are statically compiled into your kernel. Otherwise, your new kernel image won't boot. See the KernelBuildpackageHowto for a technique that doesn't require reconfiguring the kernel.

{?} Question: Could some one confirm that since we start out by copying a config file from /boot, does that mean that if we don't configure we will end up with a copy of the running kernel? Or do we somehow still start from scratch?

Building your kernel

make-kpkg

To build the kernel you'll invoke "make-kpkg", a script which automates and replaces the sequence "make dep; make clean; make bzImage; make modules". Take a few minutes and read over the manual page for make-kpkg. The make-kpkg command line can be complex and at first intimidating. Its basic syntax is

bash:/usr/src$ make-kpkg <options> <target>

Your target will be "kernel_image". Let's examine two of the more important and common options, "--append-to-version" and "--revision".

--append-to-version

The first option lets you specify an addition to the kernel version, which then becomes part of the kernel's name. You may use alphanumeric characters, "+" and "." (period or full stop); do not use underscore "_".

Here's the kernel I'm running now:

bash:/usr/src$ /usr/src/$ uname -a
Linux da5id 2.6.8.1-2-k7 #1 Sat Sep 18 11:23:11 BST 2004 i686 GNU/Linux

You should avoid using --append-to-version values such as "-686", "-K7", and "-sparc". They are commonly used for Debian pre-compiled kernels.

Kernel modules live in subdirectories of /lib/modules; each kernel has its own subdirectory. Every time you install a kernel image with a new name, the package installer creates a new subdirectory of /lib/modules to hold its modules.

This means that by using a new value for --append-to-version each time you build a kernel image, you can ensure that the new kernel will have a new name, and that its modules won't conflict with those of other kernels.

If you install a kernel with the same name (the same version and --append-to-version) as an already-installed kernel, installing the new kernel package will overwrite the old kernel and its modules. You will be warned and offered the chance to abort. Take it. Use another value for --append-to-version and rebuild.

--revision

Another make-kpkg option is "--revision", which affects the name of the Debian package itself but not the kernel name. As with --append-to-version, you may use only alphanumeric characters, "+" and ".". Do not use underscores "_". If you do not supply a value for --revision, make-kpkg will use "10.00.Custom".

Using different values of --revision will not prevent conflicts between kernels with the same name. They are just for you to see the difference, for example recompiling the same kernel with a very small change.

Kernel package names

Debian kernel-image file names have the form

kernel-image-(kernel-version)(--append-to-version)_(--revision)_(architecture).deb

The package name is everything before the first underscore.

bash:/usr/src$ ls
kernel-image-2.6.8.1.181004_10.00.Custom_i386.deb

Now you can see why underscores are not allowed in make-kpkg options — they separate the elements of package names.

I recommend using a different --append-to-version value for each kernel you compile, and letting make-kpkg assign the default revision. Date-based values work for me, but you are free to invent your own scheme.

Please read /usr/share/doc/kernel-package/README.gz if --append-to-version or --revision is unclear, or if you plan on using options different from the ones I suggest. (One way to do this is "zless README.gz".) Ignore the discussions of flavours and epochs until you are more familiar with make-kpkg and with Debian packages generally; they are not likely to be useful to you now.

fakeroot

When you added yourself to the src group you made it possible to do most kernel-package work with normal user privilege. However the files that are part of a kernel package (like the kernel and kernel modules) will be owned by root and run with root privilege; they must be created with root privilege.

Using fakeroot you can start make-kpkg as a normal user, and most of the job will be run with normal permissions. Near the end of the job, fakeroot will simulate a root environment to create the kernel-image package.

The manual page for make-kpkg describes one way to use fakeroot; we will use the simpler method of putting "fakeroot" at the beginning of the make-kpkg command line, like this:

fakeroot make-kpkg <options> <target> 

Making the kernel image

Finally! The time has arrived — you're ready to make the kernel image.

bash:/usr/src/linux $ fakeroot make-kpkg clean

Then do:

bash:/usr/src/linux $ fakeroot make-kpkg --append-to-version=.181004 kernel_image --initrd binary

Now all you can do is wait for the computer to finish. Take a few minutes off and enjoy yourself while the computer does its fair share of the work.

Installing the kernel-image package

Once the kernel image is built you will install the kernel-image package, which includes the kernel and its modules. First check to make sure it was built successfully by changing to the /usr/src directory and listing its contents:

bash:/usr/src/linux$ cd ..
bash:/usr/src$ ls
kernel-image-2.6.8.1.181004_10.00.Custom_i386.deb
linux@
linux-source-2.6.8.1/
linux-source-2.6.8.1.tar.bz2

There it is! Notice how the --append-to-version value became part of the kernel name.

To install the kernel and all its modules:

bash:/usr/src$ sudo dpkg -i kernel-image-2.6.8.1.181004_10.00.Custom_i386.deb

To install a kernel-image package from disk (as opposed to installing from a Debian archive) use the full file name. You can use tab for command-line-completion.

If everything went well, all you need to do now is reboot. If your new kernel doesn't boot, boot your previous kernel or insert your boot floppy and restart. Go back to Configuring the kernel, tweak your configuration, and try again.

Wrapping it all up

Hold that kernel!

If you used --append-to-version you shouldn't need to worry about apt-get trying to "upgrade" your kernel. If you're paranoid (it is out to get you) you can make sure by doing this:

bash:~$ echo "kernel-image-2.6.8.1.181004 hold" | sudo dpkg --set-selections

Of course substitute the real name of your kernel. To refer to a package that dpkg knows about (an installed package or one in an archive's list) use the package name rather than the full file name. Also, the "|" character is made by typing Shift-/. Check that the package really is on hold; if it is you should see:

bash:~$ dpkg --get-selections | grep kernel-image
 kernel-image-2.6.8.1.181004_10.00.Custom_i386.deb    hold

Somebody should write about holding packages, what it does etc.

Removing the symlink

Next, you should get rid of the symlink you created in the /usr/src directory. There are several reasons for this:

1. The next time you download a kernel it might not be from a Debian archive. When you expand the source tarball it could overwrite your old source tree right through the old symlink. Bummer.

2. The next time you download the kernel source from the Debian archive, you might expand the source into its own tree without problems. But since you already have a symlink called "linux" in the src directory, you might go ahead and compile (forgetting of course that it's linked to your old source tree.)

3. When you download patches or other source code into a specific source tree, you don't want anything else messing with it. By removing the symlink you might prevent #1 from happening.

To remove the link do this:

bash:~$ rm /usr/src/linux

Backing up your kernel

While not required, it's a good idea to back up your custom kernel .deb. Copy it to a secure undisclosed location.

Once your kernel has been packaged with its modules, you can install it on any machine that has the hardware you specified in your kernel configuration. You could even reinstall it on your current machine after reinstalling your system.

Making a new boot diskette

Create another boot diskette, this one for the kernel you just installed. Grab another floppy — it's not a good idea to overwrite your old boot disk; you haven't been using your new kernel long enough to be sure it works. A boot disk is only necessary if you messed up your system.

bash:/usr/src# cd /boot
bash:/boot# mkboot /boot/vmlinuz-2.4.18.030320

Building your next kernel

If you want to rebuild your kernel because you just bought a new sound card, or you want to enable a new feature you forgot to include the first time, all you need to do is reconfigure, do "fakeroot make-kpkg clean", and rebuild with a different value for --append-to-version. Your session should look something like this:

bash:~$ cd /usr/src
bash:/usr/src$ ln -s linux-source-2.6.8.1 linux
bash:/usr/src$ cd linux
bash:/usr/src/linux$ make xconfig
  (reconfigure your kernel)
bash:/usr/src/linux$ fakeroot make-kpkg clean
  (lots of cleaning here)
bash:/usr/src/linux$ fakeroot make-kpkg --append-to-version=.181004 kernel_image --initrd binary
  (screens and screens of stuff)

Using an existing configuration

When you installed your custom kernel, its configuration was copied to /boot/config-x.y.z. You may want to squirrel it away in another location (or several other locations) for safekeeping or later re-use.

Suppose that just last week you picked your way through the maze of options, and settled on a configuration that supports all the hardware and features you want. Today a new stable kernel is released and of course you want to upgrade right away. Is it necessary to start from scratch configuring the new kernel? Not at all.

Download and expand the new source tarball and make a new symlink. Then change directory to /usr/src/linux, copy your existing configuration there and do "make oldconfig":

bash:/usr/src/linux$ cp /boot/config-2.4.18.030320 .config
bash:/usr/src/linux$ make oldconfig

You'll be asked questions about new kernel options. It's generally safe to answer "no" to all the questions; make notes of the new options that interest you.

After you finish oldconfig you can run xconfig or menuconfig to review your selections, change your answers, or investigate the options you noted.

Build the latest stable kernel with your own configuration.

fakeroot make-kpkg clean

Checklist

1. Make backup boot diskette.

2. Install required packages.

   1. build-essential fakeroot kernel-package

3. Setup source tree.

   1. Add yourself to src. Logout, login. Use groups to confirm.

   2. Remove old symlink.

   3. Expand source tarball.

   4. Make and check new symlink.

4. Configure kernel.

   1. Use old config file if available. cp /boot/config-x.y.z .config

   2. make oldconfig or make xconfig or make menuconfig.

   3. Save .config file somewhere else for later use.

5. Build kernel-image package.

   1. fakeroot make-kpkg clean

   2. fakeroot make-kpkg --append-to-version=alpha+numeric.but.no.underscore kernel_image --initrd binary

6. Install kernel-image package.

   1. dpkg -i kernel-image-x.y.z.yy.mm.dd_10.00.Custom_i386.deb

   2. Reboot.

7. What next?

8. Hold your package. echo "kernel-image-x.y.z.yymmdd hold" | dpkg --set-selections

9. Remove symlink.

10. Back up kernel image.

11. Remove old kernel image packages.

12. Make new boot diskette.