Ubuntu Wiki

This document is an elaboration over the KernelMaintenance page with a focus on the Debian build system.

Suggested reading

A working knowledge of git, kernel build, debian packaging, chroot etc. will be helpful.

Please Note

You should always build the kernel on the release that the kernel is targeted for. If you are building a jaunty kernel, please build on a jaunty system or use a chroot environment. As a good general practice always build kernels under a chroot environment.

Building in a chroot environment

This is especially useful when you are building for different architectures that are supported by the CPU (like LPIA (low power Intel architecture) on i386 or i386 on x86_64). Or to build for newer release without having to upgrade the installed distribution.

You can create a chroot environment manually (the hard way) or automatically (the easy way). chroot environment will bindmount the users home directory, deleting files in the environment will delete files in the users home directory as well. If a chroot session is not ended cleanly, it leaves around files under /var/run/schroot//. It may be necessary to unmount all the directories and remove session files manually.

Manual chroot setup

This section is mainly meant for reference. Everything described here is done the same way by the script described in the next chapter. There is an utility called debootstrap that will simplify this task a lot. First install it with apt-get, then call (as root)

Please make sure that you have debootstrap installed on your system:

sudo apt-get install debootstrap

Invoke debootstrap with admin privileges:

sudo debootstrap --arch <arch> <suite> <target>

debootstrap will then create a directory specified under target, for release specified by suite say for example hardy, for architecture specified by arch say for example i386 or LPIA. Note, if you are building kernel for hardy on gutsy please enable gutsy-backports in system->administration->software sources->updates

The following command sets up the chroot build environment.

sudo chroot <target> apt-get install debhelper build-essential fakeroot kernel-wedge

You may want to copy /etc/hosts and /etc/sudoers from the system to the chroot for convenience.

schroot is better than chroot, it allows privileged users to prepare the build environment.

Following is the configuration (/etc/schroot/schroot.conf) setup for schroot in hardy:

[hardy]
type=directory
description=Ubuntu hardy
location=/srv/hardy-chroot
priority=2
users=foo
run-setup-scripts=true
personality=linux32

Note, the personality option is optional, and useful in a amd64 environment.

schroot -chardy

Automated chroot setup

Under the KernelTeam/KernelBuildScripts directory is a git repository containing several helper scripts for building the kernel. You may download them as follows:

git clone git://kernel.ubuntu.com/ubuntu/buildscripts.git

To automatically create the chroot environment use:

build-mkschroot [--arch=<arch>] <suite> <target-dir> [<mirror>]

OR

sudo build-mkschroot --arch=i386 hardy /var/chroot/hardy http://archive.ubuntu.com/ubuntu

Where:

• arch stands for different arch supported by the CPU, for example i386 on AMD64 or LPIA on i386 etc.

• suite stands for release name such as hardy, gutsy, intrepid etc.

• target-dir stands for the directory where the chroot environment will be installed.

• mirror stands for the http location to download environment from, http://host[:port]/dir/

If you encounter the following error

manjo@adlai:~/devel/ubuntu/kernel$ sudo ~/bin/buildscripts/build-mkschroot --arch=i386 jaunty jaunty-chroot  http://archive.ubuntu.com/ubuntu 
debootstrap --arch=i386 jaunty jaunty-chroot http://archive.ubuntu.com/ubuntu
E: No such script: /usr/share/debootstrap/scripts/jaunty
manjo@adlai:~/devel/ubuntu/kernel$ 

copy the latest script (intrepid) to the release name (jaunty) under /usr/share/debootstrap/scripts/

manjo@adlai:~/devel/ubuntu/kernel$ sudo cp  /usr/share/debootstrap/scripts/intrepid /usr/share/debootstrap/scripts/jaunty
manjo@adlai:~/devel/ubuntu/kernel$

The script will create the directory, do the initial debootstrap. Then create a config section for schroot, and pull additional packages that are required for kernel builds.

The naming of the chroots follows the naming scheme on the DC machines, which is <suite>[-<arch>]. The arch part will be omitted if it is the same as the host architecture. For example on i386 the chroot for hardy is named hardy, but on a amd64 it will be named hardy-i386.

Please note that above chroot command will mount your home directory & other system directories under /var/lib/schroot/mount/harty-i386-*/home etc.

/dev/pts on /var/lib/schroot/mount/jaunty-i386-cb08e67a-bea3-465a-9e44-02cf0985f1ba/dev/pts type none (rw,bind)
tmpfs on /var/lib/schroot/mount/jaunty-i386-cb08e67a-bea3-465a-9e44-02cf0985f1ba/dev/shm type tmpfs (rw)
/home on /var/lib/schroot/mount/jaunty-i386-cb08e67a-bea3-465a-9e44-02cf0985f1ba/home type none (rw,bind)

OR

manjo@adlai:~/devel/ubuntu/kernel$ mount | grep jaunty | cut -f 3 -d " "
/var/lib/schroot/mount/jaunty-i386-103b0edb-2972-4ba0-8448-0804bd55da53
/var/lib/schroot/mount/jaunty-i386-103b0edb-2972-4ba0-8448-0804bd55da53/proc
/var/lib/schroot/mount/jaunty-i386-103b0edb-2972-4ba0-8448-0804bd55da53/dev/pts
/var/lib/schroot/mount/jaunty-i386-103b0edb-2972-4ba0-8448-0804bd55da53/dev/shm

So if you remove the home directory under /var/lib/schroot/mount/jaunty*/home, this could do damage to your /home. If you decide to kill the chroot creation process prematurely you may also want to remove these mounts. You could do it as follows:

sudo umount $(mount | grep jaunty | cut -f 3 -d " ")

Basic system setup

Please make sure that the following packages are installed on your system.

• git-core
• debhelper
• build-essential
• fakeroot
• kernel-wedge

To install the packages listed above use the following command:

sudo apt-get install git-core debhelper build-essential fakeroot kernel-wedge

Optionally you may also install the following packages, these packages provide the user with build tools that might come handy in building and packaging a new kernel.

• ccache package: For faster kernel re-build. (Fast compiler cache)

sudo apt-get install ccache

After installing the ccache package, please modify your .bashrc file to include the following. This will ensure that ccache is first in your $PATH environment variable. Please refer man pages for more information on ccache.

if [ -d /usr/lib/ccache ]; then
        export PATH=/usr/lib/ccache:"${PATH}"
        export CCACHE_NLEVELS=5
fi

CAUTION: Setting CCACHE_NLEVELS to a high value causes cache reaping. For instance, setting CCACHE_NLEVELS to 8 caused over 20sec delay between compiles. Good performance has been observed for CCACHE_NLEVELS set to 3.

• devscripts package: scripts to make the life of a Debian Package maintainer easier.

sudo apt-get install devscripts

Please note that installing devscripts will install/upgrade a large number of dependent packages. please see the file /usr/share/doc/devscripts/README.gz, and for full details on these scripts. The most useful devscript is debuild. debuild can be used to check if build dependencies are satisfied for the current installation.

Optionally you may also install the following packages that might help debuild to function flawlessly.

• xmlto
• docbook-utils
• gs
• transfig
• sharutils

Continue reading without doing a debuild -b if you want to build kernel with debian/rules.

manjo@adlai:~/devel/ubuntu/kernel/ubuntu-jaunty$ debuild -b
 dpkg-buildpackage -rfakeroot -D -us -uc -b
dpkg-buildpackage: set CFLAGS to default value: -g -O2
dpkg-buildpackage: set CPPFLAGS to default value: 
dpkg-buildpackage: set LDFLAGS to default value: -Wl,-Bsymbolic-functions
dpkg-buildpackage: set FFLAGS to default value: -g -O2
dpkg-buildpackage: set CXXFLAGS to default value: -g -O2
dpkg-buildpackage: source package linux
dpkg-buildpackage: source version 2.6.28-7.18
dpkg-buildpackage: source changed by Tim Gardner <tim.gardner@canonical.com>
dpkg-buildpackage: host architecture i386
dpkg-checkbuilddeps: Unmet build dependencies: makedumpfile xmlto docbook-utils
dpkg-buildpackage: warning: Build dependencies/conflicts unsatisfied; aborting.
dpkg-buildpackage: warning: (Use -d flag to override.)
debuild: fatal error at line 1329:
dpkg-buildpackage -rfakeroot -D -us -uc -b failed
manjo@adlai:~/devel/ubuntu/kernel/ubuntu-jaunty$ 

if makedumpfile is missing then make sure you have makedumpfile is installed or setup chroot environment.

Build system breakdown

The kernel is built when executable rules [target] is invoked from linux/debian directory. Commonly used debian target names are as follows.

• clean
• binary
• binary-arch
• binary-indep
• binary-generic
• build
• build-arch
• build-indep

Other kernels (each are under a separate source tree) that are supported are:

• LUM (Linux User Mode) - Limited to Gutsy and Hardy
• LRM (Linux Restricted Modules) - For all releases.
• LBM (Linux Backport Modules) - Ubuntu specific, details to follow later in the document.

Building the kernel

To download the kernel source, please follow the documentation in KernelGuide, or use the command below:

git clone <user>@zinc.ubuntu.com:/srv/kernel.ubuntu.com/git/ubuntu/ubuntu-<release>.git <dir>

where release stands for hardy/intrepid/jaunty etc.

chroot into the chroot environment you have already created.

cd /var/chroot
chroot ubuntu-<release>

In the top-level kernel directory invoke the fakeroot command. This will build the binary packages for all kernel flavours. The kernel packages will be located (by Debian convention) in the directory one level above the current directory. Other files created during the process are located in the debian directory. In order to compile only a specific flavor, replace arch with your favorite arch, as below.

specific arch:

fakeroot debian/rules binary-generic

OR

All archs:

fakeroot debian/rules binary-arch

== Building the Headers ==

Build and install the binary-headers package before compiling the modules package. This package contains the kernel headers that are required to build the modules. The headers package generated by calling this target is not sufficient to build linux modules. This also requires the flavor specific headers package generated by calling the binary-<flavor> target.

fakeroot debian/rules binary-headers

followed by:

fakeroot debian/rules binary-i386
}}


=== Building linux-ubuntu-modules ===

First get the source

{{{
git clone <user>@zinc.ubuntu.com:/srv/kernel.ubuntu.com/ubuntu/ubuntu-hardy-lum.git <dir>

Then check for the ABI version (debian/changelog) and install the linux-headers (all and flavor specific) package that matches that and the flavor of modules that are to be build.

After that the modules can be build by

fakeroot debian/rules binary-modules-<flavor>

where flavor is one of generic, rt, ume, xen, etc.