4576
Comment:
|
8159
|
Deletions are marked like this. | Additions are marked like this. |
Line 1: | Line 1: |
The following is a true idiot's guide - not for idiots, but written by an idiot - so please correct/extend/update as appropriate. | Guide to building the Linux kernel. |
Line 3: | Line 3: |
== Download == First of all we need to download the kernel sources. There are three different ways you can do this, depending on what you want to do with the kernel. |
= Where do I find the kernel? = |
Line 6: | Line 5: |
If you only want to recompile your kernel to add extra device drivers or change other kernel configfuration parameters, then by far your best course is to install/use the kernel sources package that comes with the Linux Distribution you're using. The same is true if you just want to learn about how the kernel works. | 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]. |
Line 8: | Line 7: |
If for some reason you need the latest kernel, and are willing to work with an unstable version, then you can download one of the tarballs from kernel.org. | = What tools do I need? = |
Line 10: | Line 9: |
If you think you've reached the stage where you may eventually need to submit some changes back to the kernel development tree, then you need to use Git (the kernel source code control system) to get the latest and greatest versions, and to keep up to date with them. | 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. |
Line 12: | Line 11: |
== Download Using a Distribution Kernel Source Code Package == The method of downloading the package will vary according to the distribution you are using, so you're pretty much on your own there. Note that the source code will probably be placed in a sub-directory under /usr/src. |
On Ubuntu, you can get these tools by running {{{ sudo apt-get install libncurses5-dev gcc make git exuberant-ctags }}} |
Line 15: | Line 16: |
When using this method you need to be very careful that your newly compiled kernel won't overwrite the existing one (or you might not be able to boot any more...). Most distributions keep the two separately, but you need to understand how your system boots, and how kernels are selected before going too far down this route. | = Which kernel to build? = |
Line 17: | Line 18: |
== Download Using a Tarball from kernel.org == * Download your tarball from ftp.XX.kernel.org where XX is your country code. If there isn't a mirror for your country, just pick a near one. * Unpack the tarball in your home directory {{{ bzip2 -dc linux-2.6.0.tar.bz2 | tar xvf - }}} (Replace bzip2 with gzip if you downloaded the .gz) |
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. |
Line 25: | Line 20: |
== Download Using Git == | 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. |
Line 27: | Line 22: |
Git is the source code control system used in the kernel. You need to download and install it. | If you don't understand what a stable or release candidate kernel is, you should read the KernelDevProcess page. |
Line 29: | Line 24: |
Next you need to choose a repository. The different kernel repositories are listed at [http://git.kernel.org/]. | == Downloading the latest stable tree == |
Line 31: | Line 26: |
I've no idea how you choose which one to use, but say, for example, we're using linux/kernel/git/linville/wireless-2.6.git. Create a new directory (which can be under your home directory), and cd to it, and run: |
First, checkout the stable kernel git repository: |
Line 37: | Line 29: |
git clone git://git.kernel.org/pub/scm/ + project path | git clone git://git.kernel.org/pub/scm/linux/kernel/git/stable/linux-stable.git cd linux-stable |
Line 40: | Line 33: |
which in our example would be: | 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: |
Line 43: | Line 130: |
git clone git://git.kernel.org/pub/scm/linux/kernel/git/linville/wireless-2.6.git | make drivers/usb/host/xhci-hcd.ko |
Line 46: | Line 133: |
== Compile == === Configure the Kernel === |
Note you will need to be in the base kernel source directory for this to work. You can't make from a different directory. |
Line 49: | Line 135: |
You need to update the .config file in the root of your kernel tree to specify which facilities/drivers are built into the kernel. | 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 }}} |
Line 51: | Line 140: |
If you have used your distribution's source code distribution then it may have come with a suitably configured .configure. Alternatively there may be a suitable configure file in /boot that you can use with {{{make oldconfig}} | 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. |
Line 53: | Line 142: |
If you're using a tarball, or git to get the source code, then using an old .config file is a bit risky as it may not have all the new options defined for the new version of the kernel. You probably need to fall back on editing whatever .config came with your sourcode using either {{{make xconfig}}} or {{{make gconfig}}} depending on which one runs on your system. | 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 }}} |
Line 55: | Line 153: |
If you are running on a system with a SATA interface disk, then the default kernel configuration probably won't build. You'll need to convert some device drivers from modules to being compiled into the kernel. | 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. |
Line 57: | Line 155: |
=== Build the Kernel === make && sudo make install === Configure the Boot System === You need to configure your boot system to make the new kernel one of the options. You probably don't want it to be the default at this stage. ==== Grub ==== The build should have installed the kernel in /boot and told you what it's called. If you're using grub, you now need to edit /boot/grub/menu.lst to add it to the list of possible kernels to boot from. You need an entry something like: title My development kernel root /dev/sda1 kernel /boot/vmlinuz-2.6.24-rc3 root=/dev/sda1 ro root=UUID options don't seem to work at this stage. == Test == === Run the Kernel === Reboot, and select your development kernel from the list of kernels. === Useful Commands === dmesg will print out the kernel's ring buffer of trace messages. |
== more == * [http://lxr.free-electrons.com/source/README#050 linux/README] * '''Linux Kernel in a Nutshell''' by Greg Kroah-Hartman, http://www.kroah.com/lkn/, online: [http://www.linuxtopia.org/online_books/linux_kernel/kernel_configuration/ html] * [http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html Kernel Rebuild Guide], Kwan Lowe, 2004 * in Debian * [http://www.debian.org/doc/FAQ/ch-kernel.en.html Debian and the kernel, FAQ] * [http://www.debian.org/doc/manuals/reference/ch-kernel.en.html The Linux kernel under Debian, Reference] * http://kernel-handbook.alioth.debian.org/ |
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
[http://lxr.free-electrons.com/source/README#050 linux/README]
Linux Kernel in a Nutshell by Greg Kroah-Hartman, http://www.kroah.com/lkn/, online: [http://www.linuxtopia.org/online_books/linux_kernel/kernel_configuration/ html]
[http://www.digitalhermit.com/linux/Kernel-Build-HOWTO.html Kernel Rebuild Guide], Kwan Lowe, 2004
- in Debian
[http://www.debian.org/doc/FAQ/ch-kernel.en.html Debian and the kernel, FAQ]
[http://www.debian.org/doc/manuals/reference/ch-kernel.en.html The Linux kernel under Debian, Reference]