This page will describe how to easily build the kernel.
The majority of users that are interested in building their own kernel are doing so because they have installed Ubuntu on their system and they wish to make a small change to the kernel for that system. In many cases the user just wants to make a kernel configuration change.
The purpose of this page is to give that user a minimum amount of information for them to meet the goal of making a simple change to the kernel, building it and installing their kernel. It is not intended to be the definitive guide to doing Ubuntu kernel development.
Obtaining the source for an Ubuntu release
There are a number of different ways of getting the kernel sources. The two main ways will be documented here.
If you have installed a version of Ubuntu and you want to make changes to the kernel that is installed on your system, use the apt-get method (described below) to obtain the sources.
However, if you wish to get the most up to date sources for the Ubuntu release you are running and make changes to that, use the git method (described below) to obtain the sources.
apt-get
The source code which generated a specific binary package may be obtained using the apt-get source <package> command. For example to obtain the source for the currently running kernel you can use the command:
apt-get source linux-image-$(uname -r)
git
All of the Ubuntu Kernel source is maintained under git. The source for each release is maintained in its own git repository on kernel.ubuntu.com. To obtain a local copy you can simply git clone the repository for the release you are interested in as shown below.
git clone git://kernel.ubuntu.com/ubuntu/ubuntu-<release codename>.git
For example to obtain the precise tree:
git clone git://kernel.ubuntu.com/ubuntu/ubuntu-precise.git
Build Environment
If
you've not built a kernel on your system before, there are some
packages needed before you can successfully build. You can get these
installed with:
sudo apt-get build-dep linux-image-$(uname -r)
Modifying the configuration
This
step can be skipped if no configuration changes are wanted. The build
process will use a configuration that is put together from various
sub-config files. The simplest way to modify anything here is to run:
chmod a+x debian/rules chmod a+x debian/scripts/* chmod a+x debian/scripts/misc/* fakeroot debian/rules clean fakeroot debian/rules editconfigs # you need to go through each (Y, Exit, Y, Exit..) or get a complaint about config later
This
takes the current configuration for each architecture/flavour supported
and calls menuconfig to edit its config file. The chmod is needed
because the way the source package is created, it loses the executable
bits on the scripts.
In
order to make your kernel "newer" than the stock Ubuntu kernel from
which you are based you should add a local version modifier. Add
something like "+test1" to the end of the first version number in the debian.master/changelog file, before building. This will help identify your kernel when running as it also appears in uname -a.
Note that when a new Ubuntu kernel is released that will be newer than
your kernel (which needs regenerating), so care is needed when
upgrading. NOTE: do not attempt to use CONFIG_LOCALVERSION as this
_will_ break the build.
Building the kernel
Building the kernel is quite easy. Change your working directory to the root of the kernel source tree and then type the following commands:
fakeroot debian/rules clean # quicker build: fakeroot debian/rules binary-headers binary-generic binary-perarch # if you need linux-tools or lowlatency kernel, run instead: fakeroot debian/rules binary
If
the build is successful, a set of three .deb binary package files will
be produced in the directory above the build root directory. For
example after building a kernel with version "4.8.0-17.19" on an amd64
system, these three (or four) .deb packages would be produced:
cd .. ls *.deb linux-headers-4.8.0-17_4.8.0-17.19_all.deb linux-headers-4.8.0-17-generic_4.8.0-17.19_amd64.deb linux-image-4.8.0-17-generic_4.8.0-17.19_amd64.deb
on later releases you will also find a linux-extra- package which you should also install if present.
Testing the new kernel
Install the three-package set (on your build system, or on a different target system) with dpkg -i and then reboot:
sudo dpkg -i linux*4.8.0-17.19*.deb sudo reboot
Debug Symbols
Sometimes
it is useful to have debug symbols built as well. Two additional steps
are needed. First pkg-config-dbgsym needs to be installed. Second when
executing the binary-* targets you need to add 'skipdbg=false'.
sudo apt-get install pkg-config-dbgsym fakeroot debian/rules clean fakeroot debian/rules binary-headers binary-generic binary-perarch skipdbg=false
Reasons for compiling a custom kernel
- You are a kernel developer.
- You need the kernel compiled in a special way, that the official kernel is not compiled in (for example, with some experimental feature enabled).
- You are attempting to debug a problem in the stock Ubuntu kernel for which you have filed or will file a bug report.
- You have hardware the stock Ubuntu kernel does not support.
- You love computers and are curious and interested in hacking on your own GNU/Linux system to learn more about how it works (with the understanding that you'll need to fix anything you break).
Reasons for NOT compiling a custom kernel
- You merely need to compile a special driver. For this, you only need to install the linux-headers packages.
- You have no idea what you are doing, and if you break something, you'll need help fixing it. Depending on what you do wrong, you might end up having to reinstall your system from scratch.
- You got to this page by mistake, and checked it out because it looked interesting, but you don't really want to learn a lot about kernels.
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
- Use git - This is for users who always want to stay in sync with the latest Ubuntu kernel source. For your information, detailed instructions on it can be found in the Kernel Git Guide
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
- Download the source archive - This is for users who want to rebuild the standard Ubuntu packages with additional patches. Note that this will almost always be out of date compared to the latest development source, so you should use git (option A) if you need the latest patches.
Use a follow command to install the build dependencies and extract the source (to the current directory):
- Ubuntu Hardy (8.04)
sudo apt-get build-dep --no-install-recommends --only-source linux apt-get source --only-source linux
- Ubuntu modules source may also be needed if you plan to enable PAE and 64 GiB support in the kernel for 32-bit Hardy (8.04). The Ubuntu supplied modules may not be compatible with a PAE enabled kernel.
sudo apt-get build-dep --no-install-recommends linux-ubuntu-modules-$(uname -r) apt-get source linux-ubuntu-modules-$(uname -r)
- The source will be downloaded to a subdirectory inside the current directory. Ubuntu Karmic Koala (9.10) and newer releases
sudo apt-get build-dep --no-install-recommends linux-image-$(uname -r) apt-get source linux-image-$(uname -r)
- The source will be downloaded to the current directory as a trio of files (for Lucid, at least) (.orig.tar.gz, .diff.gz, and .dsc) and a sub-directory. For instance, if uname -r returns 2.6.32-25-generic, you'll obtain linux_2.6.32.orig.tar.gz, linux_2.6.32-25.44.diff.gz, linux_2.6.32-25.44.dsc and the sub-directory linux-2.6.32.Raring (13.04):
sudo apt-get source linux-image-`uname -r`
Option C) Download the source package
- Download the source package (detailed instructions are further down this page under Alternate Build Method (B): The Old-Fashioned Debian Way) - This is for users who simply want to modify, or play around with, the Ubuntu-patched kernel source. Again, this will not be the most up-to-date (use Option A/git if you need the latest source). Please be aware this is NOT the same as Option B/Download the source archive.
Modify the source for your needs
- For
most people, simply modifying the configs is enough. If you need to
install a patch, read the instructions from the patch provider to learn
how to apply it. The stock Ubuntu configs are located in debian/config/ARCH/ where ARCH is the architecture you are building for (Starting with Jaunty this is debian.master/config/ARCH/). In this directory there are several files. The config file is the base for all targets in that architecture. Then there are several config.FLAVOUR files that contain options specific to that target. For example, here are the files for 2.6.20, i386:
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)
- To build the kernel(s) is very simple. Depending on your needs, you may want to build all the kernel targets, or just one specific to your system. However, you also want to make sure that you do not clash with the stock kernels.
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.
- Oneiric (11.10) Kernel 3.2 : http://blog.avirtualhome.com/2012/01/13/compile-linux-kernel-3-2-for-ubuntu-11-10/
- Maverick on Lucid (10.04): http://blog.avirtualhome.com/2010/07/14/how-to-compile-a-ubuntu-2-6-35-kernel-for-lucid/
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
No comments:
Post a Comment