KernelNewbies:

Guide to building the Linux kernel.

Where do I find the kernel?

The latest source code for the Linux kernel is kept on [http://www.kernel.org/ kernel.org]. You can either download the full source code as a tar ball (not recommended and will take forever to download), or you can check out the code from the read-only [http://git.kernel.org/ git repositories].

What tools do I need?

To build the Linux kernel from source, you need several tools: git, ncurses-dev, make, gcc, and (optionally) ctags. The tool packages may be called something else in your Linux distribution, so you may need to search for the package.

On Ubuntu, you can get these tools by running 

sudo apt-get install libncurses5-dev gcc make git exuberant-ctags

Which kernel to build?

When testing whether a bug is fixed, the best kernel to test with is the latest stable kernel, or (if you are brave and your system is backed up) the latest release candidate from Linus's tree. Sometimes the maintainer may want you to use an experimental branch from their own git tree. You should use the git URL they gave you instead of the git URLs below.

If you're doing development for a new feature, or trying to test a bug fix, you should use Linus' tree, or the subsystem maintainer's -next tree. Most subsystem maintainers keep their [http://git.kernel.org/ git trees] on kernel.org. When in doubt, use Linus' tree.

If you don't understand what a stable or release candidate kernel is, you should read the KernelDevProcess page.

Downloading the latest stable tree

First, checkout the stable kernel git repository: 

git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git
cd linux-stable

Next, find the latest stable kernel tag by running 

git tag -l | less

Find the latest stable kernel by looking for the largest vX.Y.Z values. For example, use the v3.1 tag over the v3.0.46 tag. If v3.1.1 is available, use that instead of v3.1. The kernel tags that end with -rcX are release candidate kernels, not stable kernels.

Now checkout the code associated with that kernel with the command 

git checkout -b stable tag

Where tag is the latest vX.Y.Z tag you found.

Downloading the latest -rc tree

First, check out Linus' tree: 

git clone git://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
cd linux.git

Setting up your kernel configuration

Many kernel drivers can be turned on or off, or built as modules. The .config file in the kernel source directory determines which drivers are built. When you download the source tree, it doesn't come with a .config file.

Duplicating your current config

If you're trying to see if a bug is fixed, you probably want to duplicate the configuration on your running kernel. That config file is stored somewhere in /boot/. There might be several files that start with config, so you want the one associated with your running kernel. You can find that by running uname -a and finding the config file that ends with your kernel version number. Copy that file into the source directory as .config. Or just run this command: 

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

Making the default config

Run 

make defconfig

Making a minimal config

Compiling a kernel from scratch from a distribution configuration can take "forever" because the distros turn on every hardware configuration possible. For people wanting to do kernel development fast, you want to make a minimal configuration. Steve Rostedt uses ktest.pl make_min_config to get a truely minimum config, but it will take a day or two to build. Warning: make sure you have all your USB devices plugged into the system, or you won't get the drivers for them!

Changing your config

If you need to make any changes to your configuration, you can run the command 

make menuconfig

Building the kernel

Run 

make

Or, if you have a multi-core processor, run 

make -jX

Where X is a number like 2 or 4. If you have a dual core, 2 or 3 might be good. Quad core, 4 or 6. Do not run with really big numbers unless you want your machine to be dog-slow!

Walk away, get some coffee, lunch, or go [http://xkcd.com/303/ read some comics].

Installing the kernel

To install a kernel, you will need to either manually update your GRUB configuration file, or have an installkernel script. This script installs the kernel to /boot/, installs modules to /lib/modules/X.Y.Z/ (where X.Y.Z is something like 3.1.5), and updates file /boot/grub/grub.conf. Fortunately, Ubuntu provides an installkernel script in /sbin/installkernel.

If you have an installkernel script, you can just run 

sudo make modules_install install

Or if you don't have sudo installed, run 

su -c "make modules_install install"

Running your kernel

First, make sure you know how to select a kernel at boot time. If your new kernel is broken, you want a way to boot into your old kernel.

The grub bootloader usually presents users with a choice of kernels, but some distros hide that menu or exit out of that menu after a short timeout. You can usually get the menu to appear by mashing the ESC key during boot after the BIOS display disappears. To make the grub menu always appear on boot under Ubuntu, remove the GRUB_HIDDEN_TIMEOUT_QUIET line from /etc/default/grub. You may want to increase the GRUB_DEFAULT timeout from 0 to 15 or 30 seconds. After you've finished editing the grub file, run 

sudo update-grub2

Ubuntu grub documentation is [https://help.ubuntu.com/community/Grub2#Boot_Display_Behavior here].

You will (usually) need to reboot into your new kernel.

Tips and Tricks

If you have a driver installed as a module, you can recompile just that driver. This saves time, because the kernel build system doesn't have to look for changes across the entire kernel tree or compile any of the built-in code.

All module files end with .ko. The kernel make system will compile just one .ko file if you give it the full path to the file: 

make drivers/usb/host/xhci-hcd.ko

Note you will need to be in the base kernel source directory for this to work. You can't make from a different directory.

You can also reload drivers without rebooting your kernel. For example, I can remove the xHCI driver and reload it with 

sudo rmmod xhci-hcd && sudo insmod drivers/usb/host/xhci-hcd.ko

Make sure that you understand the consequences of unloading your driver! For instance, if you unload the USB core driver in order to try out changes, your USB mouse and keyboard aren't going to work until the USB core driver is reloaded.

You may have to unload other drivers that depend on your driver before you can reload it. Use lsmod to find which drivers that are loaded depend on your driver. E.g. 

$ lsmod | grep usb
usbnet                 26596  2 rndis_host,cdc_ether
mii                     5198  1 usbnet
btusb                  16575  0 
usbhid                 44621  1 hid_logitech
usbcore               191078  9 xhci_hcd,rndis_host,cdc_ether,usbnet,btusb,uvcvideo,usbhid,ehci_hcd
usb_common              1093  1 usbcore

In this case, usbcore is used by xhci_hcd, rndis_host, cdc_ether, usbnet, btusb, uvcvideo, usbhid, and ehci_hcd. I would have to unload all those drivers in order to reload the usbcore module.

more

KernelNewbies: KernelBuild (last edited 2012-10-18 20:52:00 by SarahSharp)