[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]


Debian Linux Kernel Handbook
Chapter 4 - Common kernel-related tasks


4.1 Obtaining the Debian kernel source

To get the Debian kernel source at the current maximum patchlevel, it is sufficient to install the latest linux-source-version package and unpack the source, for example:

     # apt-get install linux-source-3.2
     $ tar jxf /usr/src/linux-source-3.2.tar.bz2

The unpacked source tree then will be available in linux-source-3.2 directory.


4.2 Rebuilding official Debian kernel packages

You can build all or selected kernel packages by following these instructions. You may be asked to do this in order to test a potential bug fix.


4.2.1 Preparation

For Debian 6.0 (squeeze) and earlier versions, substitute the source package name linux-2.6 for linux.

Run the following commands:

# apt-get install build-essential fakeroot
# apt-get build-dep linux

This will install the packages required by the kernel build process.

$ apt-get source linux

This will download and unpack the linux source package, making the tree available in the linux-version directory. As always, the revision part of the version of this package (for example, 1 in 3.2.19-1) will determine its patchlevel with respect to the original upstream kernel source.

$ cd linux-version

Enter the source directory.


4.2.1.1 Disk space requirements

Building binary packages for a single kernel flavour with debug info enabled (currently true for the 686-pae, amd64, rt-686-pae, rt-amd64 and s390x configurations) requires up to 10 GB space in the package directory and 300 MB in /tmp (or $TMPDIR).

Building with debug info disabled requires about 2 GB and 25 MB respectively. You can disable debug info by changing the value of debug-info to false in debian/config/arch/defines.

Building all binary packages for i386 or amd64 currently requires about 20 GB space in the package directory. Other architectures with no debug info or fewer drivers will require less space.


4.2.2 Simple patching and building

The source package includes a script to simplify the process of building with extra patches. You can use this by running commands such as:

     # apt-get install devscripts
     $ bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch

This script has options to control the flavour, featureset, etc. For a summary of the options, run:

     $ bash debian/bin/test-patches

You may then need to build the linux-base package as well:

     $ fakeroot make -f debian/rules.real install-linux-base

However, if you need to change the configuration or make other changes, you should not use this script and should follow the instructions below.


4.2.3 Applying patches or configuration changes

It is possible to apply extra patches to the source before starting the build. In the linux source package, the default (non-featureset) patches are automatically applied in the top level directory. If you are building the linux-2.6 source package or building with a featureset, you should first apply the existing patches by running:

     $ fakeroot debian/rules source

The patched source appears in the following directories.

linux default source:

top level

linux source with featureset:

debian/build/source_featureset

linux-2.6 default source:

debian/build/source_arch_none

linux-2.6 source with featureset:

debian/build/source_arch_featureset

You should apply the extra patches in the appropriate directory. In the linux source package you can use the quilt utility to do this.

To change the configuration before building, for example for the 686-pae flavour on i386, run the commands:

     $ fakeroot make -f debian/rules.gen setup_i386_none_686-pae
     $ make -C debian/build/build_i386_none_686-pae menuconfig

If the patches or configuration changes alter type definitions for the kernel, you may need to change the ABI name; see The ABI name, Section 5.2.1.


4.2.4 Building many packages

To build all possible packages for this architecture, run:

     $ fakeroot debian/rules binary

To build all architecture-dependent packages, run:

     $ fakeroot debian/rules binary-arch

To build all architecture-independent packages, run:

     $ fakeroot debian/rules binary-indep

4.2.5 Building packages for one flavour

For example, to build only the binary packages for 686-pae flavour on i386 architecture, use the following commands:

     $ fakeroot debian/rules source
     $ fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae

The target in this command has the general form of target_arch_featureset_flavour. Replace the featureset with none if you do not want any of the extra featuresets. This command will build the linux image and kernel headers packages. You may also need the linux-headers-version-common binary package, which can be built using the commands:

     $ fakeroot debian/rules source
     $ fakeroot make -f debian/rules.gen binary-arch_i386_none_real

The target in this command has the general form of target_arch_featureset_real


4.3 Building a development version of the Debian kernel package

For Debian 6.0 (squeeze) and earlier versions, substitute the source package name linux-2.6 for linux.

To build a kernel image based on the kernel team's unreleased development version:

# apt-get install build-essential fakeroot rsync svn
# apt-get build-dep linux

The last two commands will install the build dependencies required by the kernel build process.

$ svn co svn://anonscm.debian.org/svn/kernel/dists/dist/linux

This will check out the Debian packaging. dist is normally the distribution codename such as wheezy or sid (unstable). For the very latest version, usually based on an upstream release candidate, use trunk.

$ apt-get source -d linux

This will download the linux upstream source (and the last released Debian patches). Depending on which version you are trying to build, you might need to override APT's version selection or download a tarball from people.debian.org instead.

$ cd linux
$ debian/rules orig

This unpacks the upstream source and merges it with the Debian packaging.

$ debian/rules debian/control

This generates a Debian package control file based on the current definitions of the various kernel flavours which can be built.

$ fakeroot debian/rules target

Finally, build binary packages as explained in Rebuilding official Debian kernel packages, Section 4.2.


4.4 Generating orig tarball from newer upstream

First you must add a changelog entry for the new upstream version. If the new version is a release candidate, change the string -rc to ~rc. (In Debian package versions, a suffix beginning with ~ indicates a pre-release.)

The 'orig' tarball is generated by the genorig.py script. It takes either a tarball and optional patch from kernel.org, or a git repository. First ensure you have the necessary tools installed:

     # apt-get install unifdef

Then if you have a tarball, run a command such as:

     $ python debian/bin/genorig.py ../linux-3.4.tar.bz2 ../patch-3.5-rc1.bz2

Or if you have a git repository, pass the name of its directory:

     $ python debian/bin/genorig.py ~/src/linux

Either of these will generate a file such as ../orig/linux_3.5~rc1.orig.tar.xz. You can then combine this tarball with the Debian packaging by running:

     $ debian/rules orig

4.5 Building a custom kernel from Debian kernel source

This section describes the simplest possible procedure to build a custom kernel the "Debian way". It is assumed that user is somewhat familiar with kernel configuration and build process. If that's not the case, it is recommended to consult the kernel documentation and many excellent online resources dedicated to it.

The easiest way to build a custom kernel (the kernel with the configuration different from the one used in the official packages) from the Debian kernel source is to use the linux-source package and the make deb-pkg target. First, prepare the kernel tree:

     # apt-get install linux-source-3.2
     $ tar xjf /usr/src/linux-source-3.2.tar.bz2
     $ cd linux-source-3.2

The kernel now needs to be configured, that is you have to set the kernel options and select the drivers which are going to be included, either as built-in, or as external modules. The kernel build infrastructure offers a number of targets, which invoke different configuration frontends. For example, one can use console-based menu configuration by invoking the command

     $ make menuconfig

Instead of menuconfig one can use config (text-based line-by-line configuration frontend) or xconfig (graphical configuration frontend). It is also possible to reuse your old configuration file by placing it as a .config file in the top-level directory and running one of the configuration targets (if you want to adjust something) or make oldconfig (to keep the same configuration). Note that different frontends may require different additional libraries and utilities to be installed to function properly. For example, the menuconfig frontend requires the ncurses library, which at time of writing is provided by the libncurses5-dev package.

The build will use less disk space if the CONFIG_DEBUG_INFO option is disabled (see Disk space requirements, Section 4.2.1.1). Debuginfo is only needed if you plan to use binary object tools like crash, kgdb, and SystemTap on the kernel.

     $ scripts/config --disable DEBUG_INFO

After the configuration process is finished, the new or updated kernel configuration will be stored in .config file in the top-level directory. The build is started using the commands

     $ make clean
     $ make deb-pkg

As a result of the build, a custom kernel package linux-image-3.2.19_3.2.19-1_i386.deb (name will reflect the version of the kernel and build number) will be created in the directory one level above the top of the tree. It may be installed using dpkg just as any other package:

      
     # dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb

This command will unpack the kernel, generate the initrd if necessary (see Managing the initial ramfs (initramfs) archive, Chapter 7 for details), and configure the bootloader to make the newly installed kernel the default one. If this command completed without any problems, you can reboot using the

     # shutdown -r now

command to boot the new kernel.

For much more information about bootloaders and their configuration please check their documentation, which can be accessed using the commands man lilo, man lilo.conf, man grub, and so on. You can also look for documentation in the /usr/share/doc/package directories, with package being the name of the package involved.


4.6 Building a custom kernel from the "pristine" kernel source

Building a kernel from the "pristine" (also sometimes called "vanilla") kernel source, distributed from www.kernel.org and its mirrors, may be occasionally useful for debugging or in the situations when a newer kernel version is desired. The procedure differs only in obtaining the kernel source: instead of unpacking the kernel source from Debian packages, the "pristine" source is downloaded using your favourite browser or using wget, as follows:

      
     $ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.bz2

The integrity of the downloaded archive may be verified by fetching the corresponding cryptographic signature

      
     $ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.sign

and running this command (gnupg package must be installed):

     $ bunzip2 -c linux-3.4.tar.bz2 | gpg --verify linux-3.4.tar.sign -

Successful verification results in output similar to the one below:

     gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886
     gpg: Good signature from "Linus Torvalds <torvalds@linux-foundation.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: ABAF 11C6 5A29 70B1 30AB  E3C4 79BE 3E43 0041 1886

After that the archive may be unpacked using

     $ tar xjf linux-3.4.tar.bz2
     $ cd linux-3.4

The unpacked kernel tree (in linux-3.4 now has to be configured. The existing configuration file may be used as a starting point

     $ cp /boot/config-3.2.0-2-686-pae ./.config

After the configuration with one of the configuration frontends (invoked by make oldconfig, make config, make menuconfig, etc) is completed, the build may be started using make deb-pkg target as described above.


4.7 Building out-of-tree kernel modules

Some kernel modules are not included in the upstream or Debian kernel source, but are provided as third-party source packages. For some of the most popular out-of-tree modules, the binary Debian packages with modules built against the stock Debian kernels are provided. For example, if you are running stock Debian kernel 3.2.0-2-686-pae (use the uname -r command to verify the version) from the linux-image-3.2.0-2-686-pae package, and would like to use the squash filesystem, all you need to do is install squashfs-modules-3.2.0-2-686-pae binary package, which provides the neccessary binary kernel modules.

If you are not so lucky, and there are no binary module packages in the archive, there is a fair chance that the Debian archive contains the packaged source for the kernel modules. Names of such packages typically end in -source, for example squashfs-source, thinkpad-source, rt2x00-source and many others. These packages contain debianized source code of the kernel modules, suitable for building using the module-assistant (or m-a) script from the module-assistant package. Typical sequence to build a custom binary module package, matching a kernel 3.2.0-2-686-pae (as returned by uname -r) from the debianized source consists of the following steps:

Install a set of kernel headers, matching the kernel for which the modules are going to be built:

     # apt-get install linux-headers-3.2.0-2-686-pae

Install the package containing the source:

     # apt-get install squashfs-source

Invoke module-assistant (aka m-a) to do the heavy lifting:

     # m-a build squashfs

As a result, a Debian package is going to be built and placed in /usr/src. It can be installed the usual way, using dpkg -i. Two last steps (building and installation) may be combined using the invocation

     # m-a auto-install squashfs

Check out the module-assistant documentation (man module-assistant) for other options and much more information on how to use it.

Finally, in some rare circumstances, you might need to build the kernel modules from the upstream source packages. In that case, follow the documentation included with the package to build the modules. If the build process will require you to specify the directory with the kernel headers, matching the currently running kernel, for stock Debian kernels this directory is /usr/src/linux-headers-uname, provided by the linux-headers-uname package. Here uname is the output of the uname -r command. If you are building and running your own custom kernels, it is a good idea to keep the original build tree around, as it also can be used for out-of-tree module building.


[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ 8 ] [ 9 ] [ next ]


Debian Linux Kernel Handbook

version 1.0.16, Sat 14 Dec 16:00:39 GMT 2013

The Debian Kernel Handbook Project