This page collects and organizes documentation about the Linux kernel, taken from many different sources. What is the kernel, how do you build it, how do you use it, how do you change it...
This is a work in progress, and probably always will be. Please let us know on the linux-doc mailing list (on vger.kernel.org) about any documentation you'd like added to this index, and feel free to ask about any topics that aren't covered here yet. This index is maintained by Rob Landley <rob@landley.net>, and tracked in this mercurial repostiory. The cannonical location for the page is here.
These are various upstream sources of documentation, many of which are linked into the linux kernel documentation index.
Building source packages is usually a three step process: configure, build, and install.
The Linux kernel is configured with the command "make menuconfig", built with the command "make", and installed either manually or with the command "make install".
tar xvjf linux-2.6.??.tar.bz2 cd linux-2.6.?? make menuconfig make make install
For a description of the make options and targets, type make help.
The Linux kernel source code is distributed by kernel.org as tar archives. Grab the most recent "stable" release (using the tiny little letter F link) to grab a file of the form "linux-2.6.*.tar.bz2" from the Linux 2.6 releases directory. Then extract this archive with the command "tar xvjf linux-2.6.*.tar.bz2". (Type the command "man tar" for more information on the tar command.) Then cd into the directory created by extracting the archive.
To obtain other Linux kernel versions (such as development releases and kernels supplied by distributions) see Following Linux development.
To return your linux kernel source directory to its original (unconfigured) condition after configuring and building in it, either either delete the directory with "rm -r" and re-extract it from the tar archive, or run the command "make distclean".
Before you can build the kernel, you have to configure it. Configuring selects which features this kernel build should include, and specifies other technical information such as buffer sizes and optimization strategies. This information is stored in a file named ".config" in the top level directory of the kernel source code. To see the various user interfaces to the configuration system, type "make help".
Note that "make clean" does not delete configuration information, but the more thorough "make distclean" does.
Often when building a kernel, an existing .config file is supplied from elsewhere. Copy it into place, and optionally run "make oldconfig" to run the kernel's diagnostics against it to ensure it matches the kernel version you're using, updating anything that's out of sync.
Several preset configurations are shipped with the kernel source code. Run the command find . -name "*_defconfig" in the kernel source directory to seem them all. Any of these can be copied to .config and used as a starting point.
The kernel can also automatically generate various configurations, mostly to act as starting points for customization:
The most common user interface for configuring the kernel is menuconfig, an interactive terminal based menuing interface invoked through the makefiles via "make menuconfig". This interface groups the configuration questions into a series of menus, showing the current values of each symbol and allowing them to be changed in any order. Each symbol has associated help text, explaining what the symbol does and where to find more information about it. This help text is also available as html.
The menuconfig interface is controlled with the following keys:
Other configuration interfaces (functionally equivalent to menuconfig) include:
By default, Linux builds for the same architecture the host system is running. This is called "native compiling". An x86 system building an x86 kernel, x86-64 building x86-64, or powerpc building powerpc are all examples of native compiling.
Building different binaries than the host runs is called cross compiling. Cross compiling is hard. The build system for the Linux kernel supports cross compiling via a two step process: 1) Specify a different architecture (ARCH) during the configure, make, and install stages. 2) Supply a cross compiler (CROSS_COMPILE) which can output the correct kind of binary code. An example cross compile command line (building the "arm" architecture) looks like:
make ARCH=arm menuconfig make ARCH=arm CROSS_COMPILE=armv5l-
To specify a different architecture than the host, either define the "ARCH" environment variable or else add "ARCH=xxx" to the make command line for each of the make config, make, and make install stages. The acceptable values for ARCH are the names of the directories in the "arch" subdirectory of the Linux kernel source code, see Architectures for details. All stages of the build must use the same ARCH value, and building a second architecture in the same source directory requires "make distclean". (Just "make clean" isn't sufficient, things like the include/asm symlink need to be removed and recreated.)
To specify a cross compiler prefix, define the CROSS_COMPILE environment variable (or add CROSS_COMPILE= to each make command line). Native compiler tools, which output code aimed at the environment they're running in, usually have a simple name ("gcc", "ld", "strip"). Cross compilers usually add a prefix to the name of each tool, indicating the target they produce code for. To tell the Linux kernel build to use a cross compiler named "armv4l-gcc" (and corresponding "armv4l-ld" and "armv4l-strip") specify "CROSS_COMPILE=armv4l-". (Prefixes ending in a dash are common, and forgetting the trailing dash in CROSS_COMPILE is a common mistake. Don't forget to add the cross compiler tools to your $PATH.)
The Linux configuration system is called Kconfig. The various configuration front-ends (such as menuconfig) parse data files written in the Kconfig language, which define the available symbols and provide default values, help entries, and so on.
The source code for the front ends is in scripts/kconfig. The Makefile in this directory defines the make targets for the configuration system.
The Linux kernel runs programs in response to the exec syscall, which is called on a file. This file must have the executable bit set, and must be on a filesystem that implements mmap() and which isn't mounted with the "noexec" option. The kernel understands several different executable file formats, the most common of which are shell scripts and ELF binaries.
If the first two bytes of an executable file are the characters "#!", the file is treated as a script file. The kernel parses the first line of the file (until the first newline), and the first argument (immediately following the #! with no space) is used as absolute path to the script's interpreter, which must be an executable file. Any additional arguments on the first line of the file (separated by whitespace) are passed as the first arguments to that interpreter executable. The interpreter's next argument is the name of the script file, followed by the arguments given on the command line.
To see this behavior in action, run the following:
echo "#!/bin/echo hello" > temp chmod +x temp ./temp one two three
The result should be:
hello ./temp one two three
This is how shell scripts, perl, python, and other scripting languages work. Even C code can be run as a script by installing the tinycc package, adding "#!/usr/bin/tcc -run" to the start of the .c file, and setting the executable bit on the .c file.