# Kernel Rebuild Guide

2004-04-22
Kwan
Lowe
Digital Hermit

    kwan@digitalhermit.com

Doug
Jensen
Language and technical review
Michael
Kerrisk
Language review
Emma Jane
Hogbin
Metadata review
1.4
2004-04-22
ejh
Added the GNU FDL text.
1.3
2004-04-22
kll
Ao initial revision to gather feedback.

This is a guide to building the 2.4.x and 2.6.x Linux kernels. It is intended for moderately experienced Linux users who are interested in learning more about the kernel and the rebuild process.

kernel
rebuild

## Dedication

To penguin lovers everywhere...

## Introduction

### Copyright and License

This document, Kernel Build HOWTO, is copyrighted (c) 2004 by Kwan L. Lowe. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License Version 1.1 published by the Free Software Foundation; with no Invariant Sections, with no Front-Cover Texts, and with no Back-Cover Texts. A copy of the license is included in the appendix entitled "GNU Free Documentation License."

### What is the kernel?

The Linux kernel is often likened to the conductor in an orchestra. Among other things, it makes sure that all other processes in the system work together coherently. Though it is only a small part of the operating system, the kernel has the most important job of keeping everything else synchronized.

### Why Rebuild?

The main reason to build a custom kernel was once to optimize the it to your environment (hardware and usage patterns). With modern hardware, there is rarely a need to recompile unless there is a particular feature of a new kernel that you must have. The performance gains are probably not noticeable unless specific benchmarks are being run.

This said, the newest Linux kernel (2.6.5 as of this writing) has noticeable improvements for the typical desktop user as a result of the improved scheduling system. Even for older kernels, rebuilding is often necessary for low memory situations, esoteric hardware, and in cases where every ounce of performance must be extracted.

This guide covers the steps necessary to build both the 2.4.x and 2.6.x series of kernels. Because the process is quite different from one version to the next, the two kernel versions are described in separate chapters.

## Preparation

### Hardware Requirements

Hardware requirements can differ greatly between kernel versions, and indeed, within versions depending upon the configuration. Though the Linux 2.4.x kernel can boot with as little as 8M of RAM, a more realistic number is about 64M. As of this writing, the published minimum hardware required for the typical distribution is about 128M RAM, 2G of hard drive space, and 200MhZ Pentium or equivalent CPU. To actually build the kernel, however, requires a little extra hardware. The kernel sources themselves will occupy anywhere from 40M to 80M of filesystem space. To build them requires a minimum of 400M of drive space for all the interim files. The actual kernel and included modules will require anywhere from 4M for an almost useless, bare minimum kernel to about 40M fully loaded. I have successfully installed a serviceable machine on an original Pentium 100, 64M RAM, and 1.2G of drive space. A full build of the 2.6.0test9 kernel took approximately 4 hours to complete. Luckily, the kernel does not need to be built on the same machine on which it will be deployed. This means that you can compile and package your kernel on a more robust machine and then install on the minimal system.

### Software Requirements

The minimum software versions for a kernel build are found in the `./Documentation/Changes` file of the installed sources. They are as follows:

    2.4.x series

    o  Gnu C                  2.91.66     # gcc --version
    o  Gnu make               3.77        # make --version
    o  binutils               2.9.1.0.25  # ld -v
    o  util-linux             2.10o       # fdformat --version
    o  modutils               2.4.2       # insmod -V
    o  e2fsprogs              1.19        # tune2fs
    o  reiserfsprogs          3.x.0b      # reiserfsck 2>&1|grep reiserfsprogs
    o  pcmcia-cs              3.1.21      # cardmgr -V
    o  PPP                    2.4.0       # pppd --version
    o  isdn4k-utils           3.1pre1     # isdnctrl 2>&1|grep version

    2.6.x series

    o  Gnu C                  2.95.3       # gcc --version
    o  Gnu make               3.78         # make --version
    o  binutils               2.12         # ld -v
    o  util-linux             2.10o        # fdformat --version
    o  module-init-tools      0.9.10       # depmod -V
    o  e2fsprogs              1.29         # tune2fs
    o  jfsutils               1.1.3        # fsck.jfs -V
    o  reiserfsprogs          3.6.3        # reiserfsck -V 2>&1|grep reiserfsprogs
    o  xfsprogs               2.1.0        # xfs_db -V
    o  pcmcia-cs              3.1.21       # cardmgr -V
    o  quota-tools            3.09         # quota -V
    o  PPP                    2.4.0        # pppd --version
    o  isdn4k-utils           3.1pre1      # isdnctrl 2>&1|grep version
    o  nfs-utils              1.0.5        # showmount --version
    o  procps                 3.1.13       # ps --version
    o  oprofile               0.5.3        # oprofiled --version

A common sticking point on distributions transitioning between 2.4.x and 2.6.x kernels is the `module-init-tools` package which must be updated to work with the 2.6.x kernel. Also, be aware that the underlying version of glibc, the GNU libc package, is implied. If you are upgrading from particularly old distributions then you will likely need to upgrade glibc itself.

On an RPM-based system you can query a minimal version with a command such as:

    $ rpm -q --requires gcc|grep glibc

### Determine Current Hardware

Once you have determined that your hardware and software meet the minimum requirements for the kernel build, we will need to collect more detailed information about the system. This is needed during the configuration process when we decide which hardware will be supported under our new kernel. Among the information we will gather include: Processor, Drive type and Controller (SCSI, IDE), Ethernet devices, Graphics and Sound Cards, USB HUB.

We start by running the `/sbin/lspci` utility to print information about our hardware:

    $ /sbin/lspci

    00:00.0 Host bridge: Silicon Integrated Systems [SiS] 735 Host (rev 01)
    00:01.0 PCI bridge: Silicon Integrated Systems [SiS] 5591/5592 AGP
    00:02.0 ISA bridge: Silicon Integrated Systems [SiS] 85C503/5513
    00:02.2 USB Controller: Silicon Integrated Systems [SiS] 7001 (rev 07)
    00:02.3 USB Controller: Silicon Integrated Systems [SiS] 7001 (rev 07)
    00:02.5 IDE interface: Silicon Integrated Systems [SiS] 5513 [IDE] (rev d0)
    00:02.7 Multimedia audio controller: SiS7012 PCI Audio Accelerator (rev a0)
    00:03.0 Ethernet controller: [SiS] SiS900 10/100 Ethernet (rev 90)
    01:00.0 VGA compatible controller: ATI Technologies Inc Rage 128 RF/SG AGP

Next, we must determine our processor type if not known. Some Linux systems contain a `/proc` filesystem that allows a user to view raw information about the system. If `/proc` exists you can issue the following command to get CPU information:

    $ cat /proc/cpuinfo

    processor       : 0
    vendor_id       : AuthenticAMD
    cpu family      : 6
    model           : 6
    model name      : AMD Athlon(tm) XP 1800+
    stepping        : 2
    cpu MHz         : 1526.870
    cache size      : 256 KB
    fdiv_bug        : no
    hlt_bug         : no
    f00f_bug        : no
    coma_bug        : no
    fpu             : yes
    fpu_exception   : yes
    cpuid level     : 1
    wp              : yes
    flags           : fpu vme de pse tsc msr pae mce cx8 sep mtrr pge
    bogomips        : 3047.42

### Acquiring the Sources

There are many ways to acquire the Linux kernel sources. If you are using a packaged distribution then most likely the distributor will bundle a kernel source package. These are installable via the package installation method, whether RPM, apt, YAST, portage, etc.. If you decide to go this route, please consult your distribution's documentation for specifics.

The other option is to use the pristine sources, either the official sources from Linus Torvalds himself, or one of the regularly maintained trees from people such as Alan Cox, Robert Love, Andrew Morton, et al.. These sources are often on the bleeding-edge of kernel development, full of new features and untested code.

Untested code? This is a feature of the distributed development model of Linux and Open Source (??) in general. The traditional model of a software release is somewhat antithetical to this model, as new code must be released to allow all developers to test and improve the code. However, because Linux is used in production environments throughout world it is necessary to separate the unstable development tree from the tested, stable tree. This is done through the version number of the kernel. There are three main numbers associated with the kernel -- the Major, Minor, and PatchLevel fields. The Major number rarely changes, and then only when/if the entire architecture is revamped. The Minor number changes more frequently, perhaps once every couple years. Kernels with an odd Minor number are considered unstable, testing branches. Kerenels with an even Minor number are generally rock solid. The PatchLevel is updated frequently, sometimes more than once a week in extreme cases.

To recap, you can build either from your distribution's modified kernel sources or from the stable or unstable branch of the offical sources. If you are making minor modifications to the configuration it is perhaps safest to install your distributor's version. These kernels usually include stability and feature patches that may be missing from the stock kernels. For example, some distributors will include low-latency or security patches and do the more difficult work of integrating these into their system. The downside is that the distributors tend to lag the bleeding-edge kernels. If you would like to test the improved responsiveness of the 2.6.x series then you will need the "pristine" source from Linus or the tree maintainer of your choice.

### Download the Source

Though the latest sources are always available from http://kernel.org, to be kind to the Internet, always use one of the mirrors listed at http://kernel.org/mirrors. In general, geographically close mirrors tend to be faster. You can either browse the sites with an Internet browser or with a dedicated FTP client.

You will see several links to `/pub/linux` on the mirror site. Select the `kernel` directory, then the kernel version that you would like to install. As of this writing, 2.4.22 is the latest stable version and 2.6.0 is in pre-release state. Once you select a kernel version you will see several files.

    ChangeLog-2.6.0-test9          25-Oct-2003 14:51    41k
    LATEST-IS-2.6.0-test9          25-Oct-2003 14:51     0k
    linux-2.6.0-test9.tar.bz2.sign 25-Oct-2003 15:14     1k
    linux-2.6.0-test9.tar.gz       25-Oct-2003 15:14  39.7M
    linux-2.6.0-test9.tar.gz.sign  25-Oct-2003 15:14     1k
    linux-2.6.0-test9.tar.sign     25-Oct-2003 15:14     1k
    patch-2.6.0-test9.bz2.sign     25-Oct-2003 15:14     1k
    patch-2.6.0-test9.gz           25-Oct-2003 15:14   123k
    patch-2.6.0-test9.gz.sign      25-Oct-2003 15:14     1k
    patch-2.6.0-test9.sign         25-Oct-2003 15:14     1k

The Changelog files detail the differences between versions. The linux- files are the compressed sources for the entire Linux kernel. Most sites will contain both gzip and bzip packages. The bzip packages tend to be about 20% smaller than the GZIP versions, so it is usually the best option since all modern Linux distributions contain BZIP utilities. Finally, the patch files are a list of differences between versions of the kernel. If you have previously downloaded an earlier source package you will only need to download the patch file (which is much smaller) to bring those up to date. We will discuss patch application in the next section.

There are also some `.sign` files that contain OpenPGP signature information. The `.sign` file can be used to prove that a file obtained from a mirror site is same as the one found on the http://kernel.org archive. The signature for `patch-2.6.0-test9.gz` is in `patch-2.6.0-test9.gz.sign` and can be verified using

    $ gpg --verify patch-2.6.0-test9.gz.sign patch-2.6.0-test9.gz

    gpg: Signature made Sun Apr  4 09:57:25 2004 IST using DSA key ID 517D0F0E
    gpg: Good signature from "Linux Kernel Archives Verification Key <ftpadmin@kernel.org>"
    gpg:                 aka "Linux Kernel Archives Verification Key <ftpadmin@kernel.org>"
    gpg: WARNING: This key is not certified with a trusted signature!
    gpg:          There is no indication that the signature belongs to the owner.
    Primary key fingerprint: C75D C40A 11D7 AF88 9981  ED5B C86B A06A 517D 0F0E

See http://www.kernel.org/signature.html for information on how to use the verification information.

The http://kernel.org website is not the only place to retrieve patches. Many other vendors and individuals have developed patches to improve aspects of the kernel's performance, support new hardware, or introduce features that are too esoteric or experimental to make it to the stock kernel. For example, kernel hacker Robert Love had developed the pre-emptible kernel modifications that made dramatic improvements to the responsiveness of a Linux system. These patches were not part of the standard 2.4.x kernel but were of such usefulness that they were officially adopted into the 2.6.x series. For the most part these third-party patches are stable but do use your judgment when downloading and applying them.

### Extract and Patch

Once you have retrieved the kernel sources and patches, you will need to extract them and apply the patches. The pristine 2.4.x and 2.6.x sources can be built as a regular, unprivileged user and this is recommended. Distributions will often install the kernel sources into `/usr/src/linux`. To build in this directory will require root access. Note that there are usually two source packages -- one called something like `kernel-source-VERSION-i386.rpm` and another called `kernel-VERSION.src.rpm`. You can generally rebuild the `src.rpm` as an unpriveleged user.

We will begin by creating a directory to hold all the source tarballs and patches, then proceed to extract the sources. For these examples we will assume that you have previously downloaded an earlier release of the kernel and will now need to patch to bring it up to the current version.

    $ mkdir src
    $ cd src

If your Linux sources are in BZIP compressed format (that is, end with a `.bz2` extenstion, then use the following command:

    $ tar xfvj /path/to/linux-2.6.0-test7.tar.bz2

Otherwise, use the options for GZIP compressed data:

    $ tar xfvz /path/to/linux-2.6.0-test7.tar.gz

You should see a list of filenames scroll by as they are being extracted. Verify that the new kernel source directory is created:

    $ ls -l

    total 4
    drwxr-xr-x   18 kwan   users   4096 Oct  8 15:24 linux-2.6.0-test7
    -rw-r--r--    1 kwan   users 276260 Nov 15 02:05 patch-2.6.0-test8.gz
    -rw-r--r--    1 kwan   users 126184 Nov 15 02:07 patch-2.6.0-test9.gz

Next we must apply the patches in order. Patch files are created by the `diff` program, and can selectively modify one or more files by adding, deleting, or modifying lines in the source code. Because they contain only the differences between files it is usually a lot faster (and better for the Internet in general) if you patch to the current release. Appendix FIXME shows a typical patch file. Like the kernel sources, the patch files are also compressed.

    $ gunzip patch-2.6.0-test8.gz
    $ gunzip patch-2.6.0-test9.gz
    $ ls -l

    -rw-r--r--    1 kwan  users  1072806 Nov 15 02:05 patch-2.6.0-test8
    -rw-r--r--    1 kwan  users   486902 Nov 15 02:07 patch-2.6.0-test9

Once the patches are uncompressed we can apply them to the kernel sources. Remember that it is important to apply them in the right order.

    $ cd linux-2.6.0-test7
    $ patch -p1 <../patch-2.6.0.test8
    $ patch -p1 <../patch-2.6.0.test9

If it is successful you will see messages similar to the following scroll by:

    patching file Documentation/filesystems/jfs.txt
    patching file Documentation/filesystems/xfs.txt
    patching file Documentation/ia64/fsys.txt
    patching file Documentation/ide.txt
    patching file Documentation/x86_64/boot-options.txt
    patching file Makefile

If unsuccessful you will get a warning and be prompted for a file to patch. If this occurs, press CtrlC to break out of the patch utility and verify that you are using the correct patch and applying them in the correct order.

Once all the patches are applied you might consider backing up the directory.

    $ cd ..
    $ mv linux-2.6.0-test7 linux-2.6.0-test9
    $ tar cfvj linux-2.6.0-test9.tar.bz2 linux-2.6.0-test9

## Configuration

### The Configuration Process

The configuration process is the most strenous portion of the kernel rebuild process. In this step you are deciding which features will be included in the final kernel and it can require lots of hardware knowledge. In truth, it is not too onerous. The current kernels have graphical configuration programs and though not perfect, provide help screens for most of the configuration options.

Many changes were made to the configuration subsystem in the 2.6.x kernel series. It is easier to add modules and much more robust than before. It has also changed dramatically in appearance especially when using the X-based configuration tool, `xconfig`. For this reason the configuration steps for the different branches have been split into two sections in this chapter.

As mentioned, both configuration tools provide context sensitive help screens for the different options. Because this help is readily available to the user (and more importantly, because there are several hundred options) this guide will only cover a fraction of the choices.

### Compile Modules or Static

One of the first choices you will make is whether or not to build device support directly into the kernel or as a module. In the early days of Linux, when module support was in its infancy, it was possible that static (i.e., compiled in) drivers were faster. With any modern CPU the time to load and unload the modules and the memory required for the module loader subsystem is negligible even to benchmarking utilities. Some devices, notably the disk controller, can be built directly into the kernel in order to simplify the boot process.

This is a relative thing. The initrd utility is robust and easy to use. Bootloaders have also improved to the point that little effort is saved by using static kernels. My two cents.

You may also choose to disable some options entirely. Though you will not have any performance increases, there are advantages to disabling features that are not required. For one, the compile times will be drastically reduced depending on which subsystem is disabled. For another, the final kernel and installed modules will require less space. On modern hard drives of 40G, 60G, and even 250G, an extra 20M or so is negligible but is significant on embedded or older systems. The disadvantage is that you will not have support for those features until you recompile the kernel. One other thing to keep in mind, as noted in KERNELTRAP.ORG (http://www.kerneltrap.org/node/view/799):

> kerneltrap.org

>     			Having unnecessary drivers will make the kernel bigger, and can under some
>     			circumstances lead to problems: probing for a nonexistent controller card may
>     			confuse your other controllers.

### Assign Unique Name

We have so far extracted and patched the Linux sources. During our preparation we also determined what hardware is installed in the system so that we will know which modules will need compilation. Before we proceed to actually configuring the kernel there are a couple minor but important details to complete.

Inside the Linux source directory is the default `Makefile`. This file is used by the make utility to compile the Linux sources. The first few lines of the `Makefile` contains some versioning information:

    VERSION = 2
    PATCHLEVEL = 4
    SUBLEVEL = 22
    EXTRAVERSION = -1

Note that there is an additional EXTRAVERSION field. To prevent overwriting any existing kernel modules on the system we will change this EXTRAVERSION to something unique. When the final installation steps are run, kernel module files will then get written to `/lib/modules/$VERSION.$PATCHLEVEL.$SUBLEVEL-$EXTRAVERSION.`

### Backup `.config`

Finally, before we begin, please note that the configuration choices are kept in the `../linux/.config` file. If you have not already run any configurations, this file will not exist. If you have, and would like to save your configuration, copy the `.config` to another file:

    $ cd linux
    $ cp .config config.save

If you are using the sources from a vendor, then the default configuration files are usually included in the `configs` or in the `./arch/i386/defconfig` (for i386 machines) file. You can use these configurations as a starting point for your customizations. The `.config` will be overwritten in the next step, so do make a backup before proceeding!

We begin the configuration by wiping out all previous configurations and resetting the source directory to a pristine state. The main reason for doing this is that some files do not automatically get rebuilt which can lead to failed builds, or at worst, a buggy kernel.

    $ make mrproper

In the 2.4.x series, a few dozen lines of `rm -f` commands will appear as all generated files get removed. The 2.6.x process is less noisy and returns only a few CLEAN messages. Please note that it is generally safe to omit the `make mrproper` step during subsequent rebuilds.

As of this writing (December 15, 2003), the 2.4.x kernel is in wide deployment. The 2.6.0 has just been released to the world. Though the configuration and build procedures are quite similar, there are enough differences to warrant separate sections for each kernel. If you are building a 2.6.0 series kernel, skip to . Otherwise, proceed to the next section, .

### Configuring the 2.4.x kernels

Our next step is to run the configuration utility. In the 2.4.x kernels there are four main frontends: config, oldconfig, menuconfig, xconfig. We choose one configuration method and run it, for example:

    $ make config

`config` is the least user-friendly option as it merely presents a series of questions that must be answered sequentially. Alas, if an error is made you must begin the process from the top. Pressing Enter will accept the default entry, which is in upper case.

`oldconfig` will read the defaults from an existing `.config` and rewrite necessary links and files. Use this option if you've made minor changes to source files or need to script the rebuild process. Note that `oldconfig` will only work within the same major version of the kernel. You cannot, for example, use a 2.4.x `.config` with the 2.6.x kernel.

`menuconfig` is an ncurses-based frontend. Your system must have the `ncurses-devel` libraries installed in order to use this utility. As the help text at the top of the screen indicates, use the arrow keys to navigate the menu. Press Enter to select sub-menus. Press the highlighted letter on each option to jump directly to that option. To build an option directly into the kernel, press Y. To disable an option entirely, press N. To build an option as a loadable module, press M. You can also access content-specific help screens by pressing ? on each page or selecting `HELP` from the lower menu. shows an example screen. I have noticed some minor screen corruption when using menuconfig in slightly non-standard terminals. Though it functions normally some of the menu entries may be difficult to read until the screen is refreshed.

#### make menuconfig

make menuconfig example graphic

`xconfig`, as the name suggests, is an X Window based frontend. It requires the Tcl/Tk and X libraries to work, and of course, an X server. shows an example screen.

#### make xconfig

make xconfig example graphic

For the purposes of this next section we will assume that `make xconfig` is used. The options are identical otherwise. As mentioned, there are literally hundreds of configuration options and this precludes us from listing every one of them. If you are unsure of an option use the online help or consult the kernel documentation found in the `../linux/Documentation` directory. We begin by typing:

    $ make xconfig

The main configuration menu will appear. Selecting an item will bring up another window with further options. These in turn can spawn other sub-menus.

Code Maturity Level Options

  This option allows configuration of alpha-quality software. It is best to disable this option if the kernel is intended for a stable production system. If you require an experimental feature in the kernel, such as a driver for new hardware, then enable this option but be aware that it may not meet the normal level of reliability as tested code.

Loadable Module Support

  You will almost certainly want to enable module support. If you will need third-party kernel modules you will also need to enable Set Version Information on All Module Symbols.

Processor Type and Features

  This is perhaps the most important option to choose. In the Preparation section we determined our processor type by examining `/proc/cpuinfo` and we use that information here to select the appropriate processor. Included in this submenu are features such as Low Latency Scheduling which can improve desktop responsiveness, Symmetric Multi-processing Support for machines with multiple CPUs, and High Memory Support for machines with more than 1G of RAM. Laptop users can also benefit from the CPU Frequency Scaling feature.

General Setup

  Choices for PCI, ISA, PCMCIA and other architectural support such as Advanced Power Management are found here.

Memory Technology Devices

  MTD devices include Compact Flash devices. Some digital cameras will require this support.

Block Devices

  The Block Device section contains options for floppy and hard drives, including parallel port devices, tape drives and RAID controllers. Important options include loopback device support, which allows mounting on disk images, and initrd support, which is needed to preload drivers necessary to boot the system.

Multi-Device support (RAID and LVM)

  Important for servers, these options include RAID support for combining multiple disks. Note that this option is not needed for certain hardware RAID that function below the operating system level. LVM is a useful subsystem that allows, among other things, dynamic resizing of filesystems.

ATA/IDE/MFM/RLL support.

  This section includes options for IDE/ATAPI chipsets, including performance tweaks such as DMA. Most systems will need this support.

Cryptography Support (CryptoAPI)

  Useful options include Loopback Crypto Support, which allows encrypted filesystem images to be mounted. Even with full access to the PC, loopback encryption can help safeguard data.

Networking Options

  Many choices are available for networking. TCP/IP, IP tunneling, packet filtering, IPv4 and IPv6, routing support and network QoS are among the most useful. If your kernel is intended for a dedicated firewall or router device, then the options here can significantly improve performance. Read the online and kernel documentation.

SCSI Support

  SCSI support is needed for not only true SCSI devices, but also for IDE CDR/W drives in SCSI emulation mode. If your root filesystem is mounted on a SCSI disk, then you must build support directly into the kernel and not as a module.

Character Devices

  Dozens of options are available here, including support for many serial and parallel devices, hardware sensors (for system monitors), mice, joysticks and DRM. Many of the options can be safely disabled without problem.

File Systems

  It is a good idea to build support for your root filesystem directly into the kernel. Though the initrd utilities can get around the chicken-and-egg boot problem, it is generally safer and easier to just build the fs modules directly. Many options can also be safely disabled if you have no use for the feature.

Once all the configuration changes have been made, you can go ahead and save settings. By defaulti, the configuration is placed in the `.config` file in the topmost directory. Because this file is deleted by `make mrproper` and is also hidden, it is a good idea to use the Save to Alternate File before exiting. It will prompt for another save location. Enter something outside of the source tree and with a useful name such as `kernel-2.4.22-lowlatency.config`. Once this is done, exit the configuration menu. You will be prompted to save the configuration again. Select `Yes` and continue.

The configuration for the 2.4.x kernel is now complete. You may now skip to .

### Configuring the 2.6.x kernels

Our next step is to run the configuration utility. On the 2.6.x kernels there are four main frontend programs: config, menuconfig, and xconfig.

`config` is the least user-friendly option as it merely presents a series of questions that must be answered sequentially. Alas, if an error is made you must begin the process from the top. Pressing Enter will accept the default entry which is in upper case.

`oldconfig` will read the defaults from an existing `.config` and rewrite necessary links and files. Use this option if you've made minor changes to source files or need to script the rebuild process.

`menuconfig` is an ncurses based frontend. Your system must have the `ncurses-devel` libraries installed in order to use this utility. As the help text at the top of the screen indicates, use the arrow keys to navigate the menu. Press Enter to select sub-menus. Press the highlighted letter on each option to jump directly to that option. To build an option directly into the kernel, press Y. To disable an option entirely, press N. To build an option as a loadable module, press M. You can also access content-specific help screens by pressing ? on each page or selecting `HELP` from the lower menu. shows an example screen from the 2.4.x kernel series.

`xconfig` is a graphical frontend using qconf by Roman Zippel. It requires the qt and X libraries to build and use. The interface is intuitive and customizable. Online help is automatically shown for each kernel configuration option. It also can show dependency information for each module which can help diagnose build errors. shows an example of the `xconfig` screen. From the online help:

> qconf help

>     			For each option, a blank box indicates the feature is disabled, a check
>     			indicates it is enabled, and a dot indicates that it is to be compiled
>     			as a module. Clicking on the box will cycle through the three states.
>     			If you do not see an option (e.g., a device driver) that you believe
>     			should be present, try turning on Show All Options under the Options menu.
>     			Although there is no cross reference yet to help you figure out what other
>     			options must be enabled to support the option you are interested in, you can
>     			still view the help of a grayed-out option.

#### make xconfig

make xconfig example graphic

Once you have decided which configuration option to use, start the process with `make` followed by either `config`, `menuconfig`, or `xconfig`. For example:

    $ make menuconfig

The system will take a few moments to build the configuration utility. Next you will be presented with the configuration menus. Though similar to the 2.4.x series, the 2.6.x menu is more logically organized with better grouping of sub-modules. Following are some of the top level configuration options in the 2.6 kernel.

Code Maturity Level Options

  This option allows configuration of alpha-quality software or obsoleted drivers. It is best to disable this option if the kernel is intended for a stable production system. If you require an experimental feature in the kernel, such as a driver for new hardware, then enable this option but be aware that it may not meet the normal level of reliability as more rigorously tested code.

General Setup

  This section contains options for `sysctl` support, a feature allowing run-time configuration of the kernel. A new feature, kernel `.config` support, allows the complete kernel configuration to be viewed during run-time. This addresses many requests to be able to see what features were compiled into the kernel.

Loadable Module Support

  You will almost certainly want to enable module support. If you will need third-party kernel modules you will also need to enable Set Version Information on All Module Symbols.

Processor Type and Features

  This is perhaps the most important configuration choice. In the Preparation section we determined our processor type by examining `/proc/cpuinfo` and we use that information here to select the appropriate processor. Included in this submenu are features such as Preemptible Kernel which can improve desktop responsiveness, Symmetric Multi-processing Support for machines with multiple CPUs, and High Memory Support for machines with more than 1G of RAM.

Power Management Options

  Found here are options for ACPI and CPU Frequency Scaling which can dramatically improve laptop power usage. Read the `Documentation/power` file for more information.

Bus Options ( PCI, PCMCIA, EISA, MCA, ISA)

  Here are found options for all system bus devices. On modern machines the ISA and MCA support can often be disabled.

Executable File Formats

  Interesting features here include the kernel support for miscellaneous binaries, which can allow seamless operation of non-Linux binaries with a little userland help.

Device Drivers

  All the device-driver configuration options that were previously scattered throughout the 2.4.x menus are now neatly organized under this option. Features such as SCSI support, graphic card optimizations, sound, USB and other hardware are configured here.

File Systems

  Found here are options for filesystems which are supported by the kernel, such as EXT2 and ReiserFS. It is best to build support for the root filesystems directly into the kernel rather than as a module.

Security Options

  Interesting options here include support for NSA Security Enhanced Linux and other, somewhat experimental, features to increase security.

## Build

### Dependencies

The next step is to create the necessary include files and generate dependency information. This step is only required for the 2.4.x kernel tree.

    $ make dep

Lots of messages will scroll by. Depending on the speed of your machine and on what options you chose, this may take several minutes to complete. Once the dependency information is created we can clean up some miscellaneous object files. This step is required for all versions of the kernel.

    $ make clean

### Build the Kernel

We are now (finally) ready to start the actual kernel build. At the prompt type:

    $ make bzImage

As the Kbuild documentation states:

> Kbuild 2.4 Documentation

>     			Some computers won't work with make bzImage, either due to hardware
>     			problems or very old versions of lilo or loadlin. If your kernel image
>     			is small, you may use make zImage, make zdisk, or make zlilo
>     			on these systems.

The difference between `zImage` files and `bzImage` files is that `bzImage` uses a different layout and a different loading algorithm, and thus has a larger capacity. Both files use gzip compression. The 'bz' in `bzImage` stands for 'big zImage', not for 'bzip'!

On an Athlon 1800XP, building the bzImage took approximately seven minutes for a moderately configured kernel. On a Pentium 100 used as a baseline, a similar configuration took almost 45 minutes. If you are not in a hurry you may want to start the build on a console while you continue to work.

The main difference between the 2.4 and 2.6 trees is the amount of information presented on the screen. Much less information is displayed with 2.6.x series making errors and warnings easier to spot.

If everything went correctly then the new kernel should exist in `./arch/$ARCH/boot`. For example, on IA32 systems we can verify this with:

    $ ls -l arch/i386/boot

### Build the Modules

There is one more step needed for the build process, however. You have created the kernel, but now you need to create all the loadable modules if you have them configured. Be aware that typical distribution kernels tend to have almost every feature installed, plus a few others for good measure. These can typically take an hour or so to build on our Athlon XP1800. The stock kernels are somewhat leaner by default and take, on average, 25 minutes to compile. To build the modules we run:

    $ make modules

Again, lots of messages will scroll by on the screen. Here also the 2.6.x series is less talkative, outputting only summary information. Once the modules are built they can be installed. If you were building as a non-privileged user you will now need to switch to root to complete this next step:

    $ su
    password:
    $ make modules_install

The freshly baked modules will be copied into `/lib/modules/KERNEL_VERSION`.

### Create Initial RAMDisk

If you have built your main boot drivers as modules (e.g., SCSI host adapter, filesystem, RAID drivers) then you will need to create an initial RAMdisk image. The initrd is a way of sidestepping the chicken and egg problem of booting -- drivers are needed to load the root filesystem but the filesystem cannot be loaded because the drivers are on the filesystem. As the manpage for `mkinitrd` states:

> MKINITRD(8)

>     	       mkinitrd creates filesystem images which are suitable for use as Linux initial
>     	       ramdisk(initrd) images. Such images are often used for preloading  the
>     	       block device modules (such as IDE, SCSI or RAID) which are needed to access the
>     	       root filesystem. mkinitrd automatically loads filesystem  modules (such as
>     	       ext3 and jbd), IDE modules,all scsi_hostadapter entries in /etc/modules.conf,
>     	       and raid modules if the systems root partition is on raid, which makes it
>     	       simple to build and use kernels using modular device drivers.

To create the initrd, do the following:

    $ mkinitrd /boot/initrd-2.6.0.img 2.6.0

Some versions of mkinitrd may require other options to specify the location of the new kernel. On SuSe 9.0, for example, the following syntax is required:

    $ mkinitrd -k vmlinux-VERSION -i initrd-VERSION

At this writing there are some issues with the modules.conf when moving from 2.4 to 2.6 kernels. Some module names have changed which seems to cause glitches with initrd.

### Troubleshooting Build Failures

If your build fails with a signal 11 error it is most likely because of hardware problems; often the culprit is failing memory. Unfortunately, the BIOS memory check is close to useless in detecting intermittent memory failures. Even dedicated memory checkers do not stress memory as much as gcc running a kernel build. One way to tell if hardware is at fault is to restart the 'make bzImage' process. If you can get a little further before failing again then it is a hardware error. There are several possible ways to try to correct these.

Try changing your memory settings in the BIOS to more conservative levels. For example, change to SLOW or NORMAL instead of FAST. Verify that all the fans are working correctly. For a long while, I thought that the xmatrix screensaver was crashing my machine because of the numerous core dumps I would discover in my home directory. It turned out that xmatrix was cpu intensive. Unknown to me, the CPU fan on this machine had failed. Everything was fine until xmatrix started, causing the processor to overheat, eventually leading to a crash. Swap out the memory. One trick is to specify less memory than is actually installed by passing values to the kernel on boot. This prevents the kernel from accessing all the memory in the machine, and could help diagnose bad SIMMs or SDRAMs.

If instead the 'make' fails at the same point each time, then it is a configuration error. These usually result from not enabling a feature that is required by another. For example, IP Firewalling requires TCP/IP. If the prerequisite is not enabled, the build will fail. You may also get errors if you select the wrong processor or are using either a very old or development compiler.

Also keep in mind that the kernel is highly sensitive to the versions of the build tools such as the compiler and linker. Double check that your tools and libraries are the minimum required. In other words, the versions listed in in the `Documentation/Changes` are necessary to build the kernel correctly and are not merely suggestions.

## Installation

### Copy the Kernel and System.map

Once your kernel is created, you can prepare it for use. From the `./linux` directory, copy the kernel and `System.map` file to /boot. In the following examples change KERNEL_VERSION to the version of your kernel. Jerome Walter offers the following information for PowerPPC plaforms: On a PowerPC (PreP architecture). To make the system bootable, one needs to copy the bzImage file into the special partition (PreP Boot Partition type 41), using dd. Assuming that the so called partition is named /dev/sda1, the command should look like :

    $ dd if=bzImage-you-have-just-done.img of=/dev/sda1

People should be warned that if their partition is too small, the bzImage will not fit, and the boot procedure will fail.

    $ cp arch/i386/boot/bzImage /boot/bzImage-KERNEL_VERSION
    $ cp System.map /boot/System.map-KERNEL_VERSION
    $ ln -s /boot/System.map-KERNEL_VERSION /boot/System.map

The next step is to configure your bootloader. The bootloader is the first program that runs when a computer is booted. For this document it is assumed that you are running an IA32 system with a standard PC BIOS. If you are running the LiLO bootloader skip to the otherwise proceed to .

FIXME: Need information on non-IA32 bootloaders!!

### GrUB Configuration

GrUB is beginning to supplant LiLO as the bootloader of choice in more recent Linux distributions. It is generally more flexible and a lot more forgiving of system errors. For example, LiLO generally requires that an alternate boot disk is used if the kernel configuration renders the system unbootable Grub allows on-the-fly modification of kernel location, boot parameters, kernel to boot, etc..

Once you have copied the bzImage and System.map to `/boot`, edit the grub configuration file located in `/boot/grub/menu.lst`. On some distributions `/etc/grub.conf` is a symbolic link to this file.

    # Note that you do not have to rerun grub after making changes to this file
    #boot=/dev/hda
    default=0
    timeout=10
    title Red Hat Linux (2.4.20-24.9)
    	root (hd0,1)
    	kernel /boot/vmlinuz-2.4.20-24.9 ro root=LABEL=/
    	initrd /boot/initrd-2.4.20-24.9.img
    title Red Hat Linux (2.4.20-20.9)
    	root (hd0,1)
    	kernel /boot/vmlinuz-2.4.20-20.9 ro root=LABEL=/
    	initrd /boot/initrd-2.4.20-20.9.img

Edit the file to include your new kernel information. Keep in mind that GrUB counts starting from 0, so (hd0,1) references the first controller, second partition. If you have created an initial RAMdisk be sure to include it here too. A typical configuration may look something like this:

    title Test Kernel (2.6.0)
    	root (hd0,1)
    	kernel /boot/bzImage-2.6.0 ro root=LABEL=/
    	initrd /boot/initrd-2.6.0.img

### LiLO Configuration

LiLO is an older bootloader. Its configuration file is located in `/etc/lilo.conf` on most systems. Unlike GrUB, any changes to lilo.conf will not be set until the lilo program is rerun.

    boot=/dev/hda
    map=/boot/map
    install=/boot/boot.b
    default=test-2.6.0
    keytable=/boot/us.klt
    lba32
    prompt
    timeout=50
    message=/boot/message
    menu-scheme=wb:bw:wb:bw
    image=/boot/vmlinuz
    	label=linux
    	root=/dev/hda3
    	append=" ide1=autotune ide0=autotune"
    	read-only

    image=/boot/bzImage-2.6.0
    	label=test-2.6.0
    	root=/dev/hda2
    	read-only

The important sections are the image=/boot/bzImage and the default=test-2.6.0 options. Notice that you can have several image sections in the lilo.conf, allowing multiple configurations. Install the new kernel by running the lilo program.

    $ /sbin/lilo -v

If you are installing and testing the kernel remotely, you can instead specify to LiLO that the new kernel is loaded only for the next boot by using the following syntax:

    $  /sbin/lilo -R test-2.6.0

Messages will appear showing the newly added kernel with an asterisk marking the default image. If you get errors, consult the lilo documentation for the correct syntax.

## Bibliography

### Books

LinuxKernel Daniel P.Dovet Marco Cesati 2003 SAMS FIXME FIXME 0672325128 SAMS

### Linux Kernel Development

## Example Patch file

### Online Resources

    Index: Config.in
    ===================================================================
    RCS file: /usr/local/cvs/linux/os/linux/arch/cris/drivers/Config.in,v
    retrieving revision 1.46
    diff -u -d -r1.46 Config.in
    --- Config.in   11 Oct 2002 16:14:33 -0000      1.46
    +++ Config.in   31 Oct 2002 08:44:37 -0000
    @@ -317,3 +317,8 @@
     fi

     endmenu
    +
    +# The following if statement was added by arch/cris/drivers/bluetooth/Makefile
    +if [ "$CONFIG_ETRAX_SERIAL" = "y" ]; then
    +  source arch/cris/drivers/bluetooth/src/Config.in
    +fi
    Index: Makefile
    ===================================================================
    RCS file: /usr/local/cvs/linux/os/linux/arch/cris/drivers/Makefile,v
    retrieving revision 1.20
    diff -u -d -r1.20 Makefile
    --- Makefile    14 Aug 2002 18:32:33 -0000      1.20
    +++ Makefile    31 Oct 2002 08:44:37 -0000
    @@ -24,5 +24,9 @@
     obj-$(CONFIG_ETRAX_ETHERNET_LPSLAVE)    += lpslave/lpslavedrivers.o
     subdir-$(CONFIG_ETRAX_ETHERNET_LPSLAVE) += lpslave

    +# The following two lines were added by arch/cris/drivers/bluetooth/Makefile
    +obj-$(CONFIG_BLUETOOTH)                 += bluetooth/src/bt.o
    +subdir-$(CONFIG_BLUETOOTH)              += bluetooth/src
    +
     include $(TOPDIR)/Rules.make

## Resources

### Online Resources

## Feedback

### Comments and corrections

The current maintainer of this HOWTO is Kwan Lowe. Please send corrections, additions, comments and criticisms to kwan@digitalhermit.com.

The HOWTO's maintainer is not a professional writer. If you find some parts of this HOWTO difficult to comprehend then let the maintainer know.

## GNU Free Documentation License

### 0. PREAMBLE

The purpose of this License is to make a manual, textbook, or other written document free in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of copyleft, which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

### 1. APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. The Document, below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as you.

A Modified Version of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A Secondary Section is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (For example, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The Invariant Sections are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License.

The Cover Texts are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License.

A Transparent copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, whose contents can be viewed and edited directly and straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup has been designed to thwart or discourage subsequent modification by readers is not Transparent. A copy that is not Transparent is called Opaque.

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML designed for human modification. Opaque formats include PostScript, PDF, proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML produced by some word processors for output purposes only.

The Title Page means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, Title Page means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

### 2. VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

### 3. COPYING IN QUANTITY

If you publish printed copies of the Document numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a publicly-accessible computer-network location containing a complete Transparent copy of the Document, free of added material, which the general network-using public has access to download anonymously at no charge using public-standard network protocols. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

### 4. MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

- #### A

  Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.

- #### B

  List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has less than five).

- #### C

  State on the Title Page the name of the publisher of the Modified Version, as the publisher.

- #### D

  Preserve all the copyright notices of the Document.

- #### E

  Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.

- #### F

  Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.

- #### G

  Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.

- #### H

  Include an unaltered copy of this License.

- #### I

  Preserve the section entitled History, and its title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section entitled History in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.

- #### J

  Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the History section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.

- #### K

  In any section entitled Acknowledgements or Dedications, preserve the section's title, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.

- #### L

  Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.

- #### M

  Delete any section entitled Endorsements. Such a section may not be included in the Modified Version.

- #### N

  Do not retitle any existing section as Endorsements or to conflict in title with any Invariant Section.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section entitled Endorsements, provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version .

### 5. COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections entitled History in the various original documents, forming one section entitled History; likewise combine any sections entitled Acknowledgements, and any sections entitled Dedications. You must delete all sections entitled Endorsements.

### 6. COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and dispbibute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

### 7. AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, does not as a whole count as a Modified Version of the Document, provided no compilation copyright is claimed for the compilation. Such a compilation is called an aggregate, and this License does not apply to the other self-contained works thus compiled with the Document , on account of their being thus compiled, if they are not themselves derivative works of the Document. If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one quarter of the entire aggregate, the Document's Cover Texts may be placed on covers that surround only the Document within the aggregate. Otherwise they must appear on covers around the whole aggregate.

### 8. TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License provided that you also include the original English version of this License. In case of a disagreement between the translation and the original English version of this License, the original English version will prevail.

### 9. TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

### 10. FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License or any later version applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

### Addendum

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

> Copyright © YEAR YOUR NAME.

> Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1 or any later version published by the Free Software Foundation; with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST. A copy of the license is included in the section entitled GNU Free Documentation License.

If you have no Invariant Sections, write with no Invariant Sections instead of saying which ones are invariant. If you have no Front-Cover Texts, write no Front-Cover Texts instead of Front-Cover Texts being LIST; likewise for Back-Cover Texts.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

Written in DocBook 4.1 SGML. Vim was used to create the SGML source file. The HTML, PostScript and PDF output was generated from the DocBook source by the Linux Documentation Project.