Tag/tag.png

Content Cleanup Required
This article should be cleaned-up to follow the content standards in the Wiki Guide. More info...

Tag/tag.png

Needs Updating
This article needs updating to include the latest versions of Ubuntu. More info...

Disclaimer

Building and using a custom kernel will make it very difficult to get support for your system.

While it is a learning experience to compile your own kernel, you will not be allowed to file bugs on the custom-built kernel (if you do, they will be Rejected without further explanation).

Note: This page would need significant cleaning. You may want to refer to Kernel/BuildYourOwnKernel page in Ubuntu wiki instead which is a cleaner and more up-to-date guide to (simple) kernel building

If you have a commercial support contract with Ubuntu/Canonical, this will void such support.

Also note that this page describes how to do things for the Edgy (2.6.17) kernel and newer! Until this kernel source, we did not have any mechanisms in place that would allow people to build their own kernels easily. This was intentional.

This page does NOT describe how to build upstream kernels from kernel.org. This is how to rebuild the actual Ubuntu kernel starting from source.

Reasons for compiling a custom kernel

Reasons for NOT compiling a custom kernel

If you want to install a new kernel without compilation, you can use Synaptic, search for linux-image and select the kernel version you want to install.

An easier way is to click on System > Administration > Update Manager, then click on the Check button, and finally click on Apply all updates including the kernel.

Tools you'll need

To start, you will need to install a few packages. Use a following command line to install precisely the packages needed for the release you are using:

Hardy (8.04):

sudo apt-get install linux-kernel-devel fakeroot kernel-wedge build-essential

Note: The package makedumpfile is not available in Hardy.

Lucid (10.04):

sudo apt-get install fakeroot build-essential crash kexec-tools makedumpfile kernel-wedge
sudo apt-get build-dep linux
sudo apt-get install git-core libncurses5 libncurses5-dev libelf-dev asciidoc binutils-dev

Raring (13.04):

sudo apt-get build-dep linux-image-`uname -r`

Get the kernel source

There are a few ways to obtain the Ubuntu kernel source:

Option A) Use git


The git repository does not include necessary control files, so you must build them by:

fakeroot debian/rules clean

Option B) Download the source archive


Use a follow command to install the build dependencies and extract the source (to the current directory):

sudo apt-get build-dep --no-install-recommends --only-source linux
apt-get source --only-source linux

sudo apt-get build-dep --no-install-recommends linux-ubuntu-modules-$(uname -r)
apt-get source linux-ubuntu-modules-$(uname -r)

sudo apt-get build-dep --no-install-recommends linux-image-$(uname -r)
apt-get source linux-image-$(uname -r)

sudo apt-get source linux-image-`uname -r`

Option C) Download the source package

Modify the source for your needs

ls -l debian/config/i386/
total 108
-rw-r--r-- 1 root src  73962 2007-08-13 01:29 config
-rw-r--r-- 1 root root  1369 2007-08-13 01:29 config.386
-rw-r--r-- 1 root root  1330 2007-08-13 01:29 config.generic
-rw-r--r-- 1 root root  1395 2007-08-13 01:29 config.server
-rw-r--r-- 1 root root  1756 2007-08-13 01:29 config.server-bigiron
-rw-r--r-- 1 root root     8 2007-08-13 01:25 lowlatency
-rw-r--r-- 1 root root   194 2007-08-13 01:25 vars.386
-rw-r--r-- 1 root root   218 2007-08-13 01:25 vars.server-bigiron

If you do not find the config files under debian/config, you may find them in your /boot directory (for instance, /boot/config-2.6.22-14-generic) otherwise you should check to see if an alternate location has been specified within debian/debian.env of your kernel source directory.

If you need to change a config option, simply modify the file that contains the option. If you modify just the config file, it will affect all targets for this architecture. If you modify one of the target files, it only affects that target.

After applying a patch, or adjusting the configs, it is always best to regenerate the config files to ensure they are consistent. There is a helper command for this. To regenerate all architectures run:

debian/rules updateconfigs

If you just want to update one architecture, run:

debian/scripts/misc/oldconfig ARCH

Note: If you don't have the debian/ directory after using apt-get source, use dpkg-source -x *dsc to extract the sources properly.

For these two commands to work, you need to give the scripts in the debian/scripts/misc and debian/scripts directories execute permission with the following command:

chmod -R u+x debian/scripts/*

Build the Kernel(s)

There are two listed ways to build the Ubuntu kernel:

Build Method A: Build the kernel (when source is from git repository, or from apt-get source)

Note: Though these outside instructions include making a separate and unique branch of the kernel, unlike here, they include thorough explanations of all necessary steps from start to finish.

These instructions are specific to the git-tree and for the source downloaded via apt-get source, not when downloading the linux-source package from kernel.org

Use this command to build all targets for the architecture you are building on:

fakeroot debian/rules clean
AUTOBUILD=1 fakeroot debian/rules binary-debs

debian/rules clean creates debian/control, debian/changelog, and so on from debian.<branchname>/* (e.g. debian.master). It is necessary in git trees following git commit 3ebd3729ce35b784056239131408b9a72b0288ef "UBUNTU: [Config] Abstract the debian directory".

The AUTOBUILD environment variable triggers special features in the kernel build. First, it skips normal ABI checks (ABI is the binary compatibility). It can do this because it also creates a unique ABI ID. If you used a git repo, this unique ID is generated from the git HEAD SHA. If not, it is generated from the uuidgen program (which means every time you execute the debian/rules build, the UUID will be different!). Your packages will be named using this ID. (Note that in Intrepid and newer, you will need skipabi=true to skip ABI checks.)

To build a specific target, use this command:

fakeroot debian/rules clean
AUTOBUILD=1 NOEXTRAS=1 fakeroot debian/rules binary-FLAVOUR

Where FLAVOUR is one of the main flavours of the kernel (e.g. generic)

To build one of the custom flavours (found in debian/binary-custom.d/), use:

fakeroot debian/rules clean
AUTOBUILD=1 NOEXTRAS=1 fakeroot debian/rules custom-binary-FLAVOUR

As of this documentation, custom flavours include xen and rt.

If you have a more than one processor or more than one core, you can speed things up by running concurrent compile commands. Prepend CONCURRENCY_LEVEL=2 for two processors or two cores; replace '2' with whatever number suits your hardware setup (for Gutsy and later, you can alternatively use DEB_BUILD_OPTIONS=parallel=2).

fakeroot debian/rules clean
DEB_BUILD_OPTIONS=parallel=2 AUTOBUILD=1 NOEXTRAS=1 fakeroot debian/rules binary-generic

If you get ABI errors, you can avoid the ABI check with skipabi=true. For example,

fakeroot debian/rules clean
DEB_BUILD_OPTIONS=parallel=2 AUTOBUILD=1 NOEXTRAS=1 skipabi=true fakeroot debian/rules binary-generic

To trigger a rebuild, remove the appropriate stamp file from debian/stamps (e.g. stamp-build-server for the server flavour, etc.).

The debs are placed in your the parent directory of the kernel source directory.

If needed, the Ubuntu modules source for Hardy (8.04) can be built in a similar way.

cd linux-ubuntu-modules-2.6.24-2.6.24
AUTOBUILD=1 fakeroot debian/rules binary-debs

Alternatively, if you need to specify a different kernel than the running one, use

cd linux-ubuntu-modules-2.6.24-2.6.24
AUTOBUILD=1 fakeroot debian/rules binary-debs KDIR=/path/to/kerneldir

If you get an error, try running this in the kerneldir: (example for the generic flavour)

cat debian/config/i386/config debian/config/i386/config.generic > .config
make prepare scripts

Alternate Build Method (B): The Old-Fashioned Debian Way

The new Ubuntu build system is great for developers, for people who need the absolute latest bleeding-edge kernel, and people who need to build a diverse set of kernels (several "flavours"). However it can be a little complex for ordinary users. If you don't need the latest development sources, there is a simpler way to compile your kernel from the linux-source package. As suggested above, all you need for this is:

sudo apt-get install linux-source device-tree-compiler # device-tree-compiler is only needed if you are targeting the PowerPC architecture
mkdir ~/src; cd ~/src
tar xjvf /usr/src/linux-source-<version-number-here>.tar.bz2
cd linux-source-<version-number-here>

The last command in the sequence brings you into the top directory of a kernel source tree.

Before building the kernel, you must configure it. If you wish to re-use the configuration of your currently-running kernel, start with

cp -vi /boot/config-`uname -r` .config

Before you run make menuconfig or make xconfig (which is what the next step tells you to do), make sure you have the necessary packages:

sudo apt-get install qt3-dev-tools libqt3-mt-dev # if you plan to use 'make xconfig'
sudo apt-get install libncurses5 libncurses5-dev # if you plan to use 'make menuconfig'

If you would like to see what is different between your original kernel config and the new one (and decide whether you want any of the new features), you can run:

make oldconfig

Since the 2.6.32 kernel, a new feature allows you to update the configuration to only compile modules that are actually used in your system:

make localmodconfig

Then, regardless of whether you're re-using an existing configuration or starting from scratch:

make menuconfig # or "make xconfig" if you prefer
or


What about this... ? (which is from the Kernel/BuildYourOwnKernel Page in the section "Modifying the configuration")

chmod a+x debian/scripts/*
chmod a+x debian/scripts/misc/*
fakeroot debian/rules clean
fakeroot debian/rules editconfigs


If you re-used the existing configuration, note that Ubuntu kernels build with debugging information on, which makes the resulting kernel modules (*.ko files) much larger than they would otherwise be. To turn this off, go into the config's "Kernel hacking"<!-- ; then, under "Kernel debugging", --> and turn OFF "Compile the kernel with debug info".

Now you can compile the kernel and create the packages:

make clean # only needed if you want to do a "clean" build
make deb-pkg

You can enable parallel make use make -j). Try 1+number of processor cores, e.g. 3 if you have a dual core processor:

make -j3 deb-pkg

On a newer kernel, if you only need binary packages and want several builds (while editing the source) to not cause everything to be rebuilt, use:

make -j3 bindeb-pkg

The *.deb packages will be created in the parent directory of your Linux source directory (in this example, they would be placed in ~/src because our Linux source directory is ~/src/linux-source-<version-number-here>).

Install the new kernel

If you want to see the Ubuntu splash screen (or use text mode) before you get to X instead of just a black screen, you'll want to make sure the framebuffer driver loads:

echo vesafb | sudo tee -a /etc/initramfs-tools/modules
echo fbcon | sudo tee -a /etc/initramfs-tools/modules

Now that you've told initramfs-tools which modules it should include, and once the build is complete, you can install the generated debs using dpkg:

sudo dpkg -i linux-image-2.6.20-16-2be-k7_2.6.20-16_i386.deb
sudo dpkg -i linux-headers-2.6.20-16-2be-k7_2.6.20-16_i386.deb

Similarly, if you have built the Ubuntu module for Hardy (8.04) earlier, install them as follows:

sudo dpkg -i linux-ubuntu-modules-2.6.24-16-generic_2.6.24-16.23_i386.deb
sudo dpkg -i linux-headers-lum-2.6.24-16-generic_2.6.24-16.23_i386.deb

If you use modules from linux-restricted-modules, you will need to recompile this against your new linux-headers package.

Note: In response to the various comments in the remainder of this section: On Ubuntu Precise (12.04) it appears that postinst DOES take care of the initramfs stuff. After installing the package my new kernel booted just fine without following any of the methods below. Someone please correct me if I'm mistaken.

Since Ubuntu Lucid (10.04) the image postinst no longer runs the initramfs creation commands. Instead, there are example scripts provided that will perform the task. These scripts will work for official kernel images as well. For example:

sudo cp /usr/share/doc/kernel-package/examples/etc/kernel/postinst.d/initramfs /etc/kernel/postinst.d/initramfs
sudo mkdir -p /etc/kernel/postrm.d/
sudo cp /usr/share/doc/kernel-package/examples/etc/kernel/postrm.d/initramfs /etc/kernel/postrm.d/initramfs

Note: I couldn't get the above scripts to help in generating an initrd for the kernel - and so the built kernel couldn't boot; the only thing that worked for me was the recommendation in http://www.debian-administration.org/article/How_Do_I_Make_an_initrd_image, "use initramfs command. It is real solution."; what I used (after the custom-built kernel's *.deb's were installed), was:

cd /boot
sudo mkinitramfs -k -o initrd.img-2.6.32.15+drm33.5-mylucid 2.6.32.15+drm33.5-mylucid
sudo update-grub2

Note (Michael): that is because you need to include the right package scripts to build the initrd at package install time. The make-kpkg option is --overlay-dir. By default, make-kpkg uses /usr/share/kernel-package as an overlay directory, which contains the default, uncustomised scripts for a Debian distribution, and not the ones needed for building a Ubuntu kernel.

The following instructions are based on this link: http://crashcourse.ca/introduction-linux-kernel-programming/intermission-building-new-ubuntu-1004-kernel-free-lesson

First copy the default overlay directory to your home directory:

$ cp -r /usr/share/kernel-package $HOME

Then install the source of the kernel you are using currently, using the exact package name, e.g.

$ cd
$ apt-get source linux-image-2.6.32-24-generic

which will unpack the sources to $HOME/linux-2.6.32. Now copy the control scripts into your new overlay:

$ cp linux-2.6.32/debian/control-scripts/{postinst,postrm,preinst,prerm} kernel-package/pkg/image/
$ cp linux-2.6.32/debian/control-scripts/headers-postinst kernel-package/pkg/headers/

And now you can execute make-kpkg with the additional command line option --overlay-dir=$HOME/kernel-package.

Rebuilding ''linux-restricted-modules''

The linux-restricted-modules (l-r-m) package contains a number of non-DFSG-free drivers (as well as some firmware and the ipw3945 wireless networking daemon) which, in a perfect world, wouldn't have to be packaged separately, but which unfortunately are not available under a GPL-compatible license. If you use any of the hardware supported by the l-r-m package, you will likely find that your system does not work as well after switching to a custom kernel. In this case you should try to compile the l-r-m package.

See CustomRestrictedModules on how to rebuild l-r-m (if you use nVidia or ATI binary drivers, you do).

Note: you will need around 8 hours of compilation time and around 10 Gb of hard drive space to compile all kernel flavours and restricted modules.

Further note: There are no l-r-m or linux-restricted-modules packages in Lucid.

Speeding Up the Build

Use distcc and, if you're rebuilding often, ccache. A good overview of using distcc on a debian-based system is available at http://myrddin.org/howto/using-distcc-with-debian. If you have AMD64 machines available on your local area network, they can still participate in building 32-bit code; distcc seems to handle that automatically. However, with distcc taking over all compiles by default, you will need to set HOSTCC so that when kernel builds want to use the compiler on the host itself, they don't end up distributing jobs to the 64-bit server. If you fail to do that, you'll get link-compatibility failures between 64-bit and 32-bit code. My make-kpkg command, with /usr/lib/ccache at the head of my $PATH, looks like:

MAKEFLAGS="HOSTCC=/usr/bin/gcc CCACHE_PREFIX=distcc" make-kpkg --rootcmd fakeroot --initrd --append-to-version=-suspend2 kernel-image kernel-headers kernel-source

More documentation

Comments

Please go to the community wiki page for comments, questions and discussion: https://wiki.ubuntu.com/KernelCustomBuild

External information


CategoryKernel CategoryKernel

Kernel/Compile (last edited 2018-09-25 23:41:04 by shadbolt)