The Kernel Configuration and Build Process

Greg Kroah-Hartman

Issue #109, May 2003

Starting with the 2.5 series, it's simpler and faster to customize your kernel or add a driver.

The process of building a kernel has two parts: configuring the kernel options and building the source with those options. In versions before the 2.5 kernel, configuration was driven by a Config.in file within every subdirectory and a main help file, Documentation/Configure.help. The language used to describe the build process was based loosely on a shell-style language that would control which configuration options were presented to the user, depending on which options were currently presented.

This worked reasonably well, but over time the variety of different options in the kernel stretched the language beyond what it could reasonably handle. In the 2.5.45 kernel release, Roman Zippel's rewrite of the configuration language and configuration programs was placed in the main kernel tree. The new configuration language is much more flexible and powerful. It also unifies the help text with the configuration logic, making it easier to apply patches for individual drivers, without having to worry about conflicts within a single Configuration.help file.

Also during the 2.5 series, Kai Germaschewski and the other kbuild developers slowly reworked makefile logic within the kernel, making it easier to build the kernel based on the selected options. This article describes the format of the makefile and configuration files in the 2.5 kernel and shows how to add a new driver to the build process.

Configuring the Kernel

To configure different kernel options, a user runs either a text-mode or a graphical kernel configurator. The text-mode configurator can be run with make config and prompts the user to select configuration options in order (Figure 1). The ncurses text version is more popular and is run with the make menuconfig option (Figure 2). The graphical configurator is run with make xconfig and uses Qt as the widget set (Figure 3).

Figure 1. Configuring the Kernel with make config

Figure 2. make menuconfig makes it easier to back up and correct mistakes.

Figure 3. The Qt-Based make xconfig

When the kernel configurator is run, it reads the main kernel configuration file, located in arch/i386/Kconfig for the i386 platform. Other architectures have the main configuration files located in their main directories. This main configuration file then includes other configuration files from the different subdirectories in the kernel directory tree. Those configuration files also can include other configuration files as needed. For example, the arch/i386/Kconfig file contains the line:

source "sound/Kconfig"

which will read information from that file. This sound/Kconfig file then includes a lot of other files:

source "sound/core/Kconfig"
source "sound/drivers/Kconfig"
source "sound/isa/Kconfig"
source "sound/pci/Kconfig"
source "sound/ppc/Kconfig"
source "sound/arm/Kconfig"
source "sound/usb/Kconfig"
The sound/usb/Kconfig file describes all of the ALSA USB driver options, like this:
# ALSA USB drivers
menu "ALSA USB devices"
    depends on SND!=n && USB!=n

config SND_USB_AUDIO
    tristate "USB Audio/MIDI driver"
    depends on SND && USB
    help
      Say 'Y' or 'M' to include support for
      USB audio and USB MIDI devices.
endmenu
The # character can be used to comment Kconfig files. Anything written after it on the same line is not read by the configurator, but it is useful for documenting what the file is for and what it should do.

The menu and endmenu commands tell the configurator to declare a new menu level or new screen in some of the configuration programs. On the menu line, the name of the menu should be specified within “ characters. For this file, the menu is called "ALSA USB devices".

Menus and configuration options can be controlled to display or not. In this example, the USB option menu is only displayed if the CONFIG_SND and CONFIG_USB options are selected, which is controlled by the line depends on SND!=n && USB!=n. To help decrease the amount of typing involved, all configuration options automatically start with CONFIG, which is not used within the configuration language. The valid states for a configuration option are:

  • y—the option is enabled.

  • n—the option is not enabled.

  • m—the option is set to be built as a module.

If both the CONFIG_SND and CONFIG_USB options are not set to n (meaning they are set either to be built in to the kernel or to build as a module), the CONFIG_SND_USB_AUDIO option is presented to the user. This option can be set to one of the three values, and it is described as a “tristate” value. The text that should be shown to the user is "USB Audio/MIDI driver":

tristate "USB Audio/MIDI driver"

The valid values for describing a configuration variable are:

  • bool—the variable can be set only to y or n.

  • tristate—the variable can be set to y, n or m.

  • int—the variable can be set to any numeric value.

This configuration option is controlled by a depends logic line, which follows the same logic as a menu option. The CONFIG_SND_USB_AUDIO option depends on both the CONFIG_SND and CONFIG_USB options, meaning that if one of these options is set to a module, then the CONFIG_SND_USB_AUDIO option also should be set to a module. If both of the controlling options are not enabled (meaning both are set to n), this option will not be displayed. If both of these options are set to y, this option can be selected as n, y or m. All of this is defined with the simple line:

depends on SND && USB

Within the kernel code, the configuration variable will be seen (the CONFIG_SND_USB_AUDIO in the above example), so the code can test for it or any other kernel configuration option's existence. However, using #ifdef within a .c file to test for different configuration options is against the kernel-style programming guidelines, which I covered in my article “Proper Linux Kernel Coding Style” [LJ, July 2002, www.linuxjournal.com/article/5780]. Instead, limit the use of #ifdef to .h files, keeping the .c files cleaner and easier to read.

Previously, the help text for a configuration option was placed in one big Configuration.help file. Now the help text is placed right after the depends line within the Kconfig file. It begins with a line containing either help or ---help---, followed by a number of lines of help text that are indented two spaces from the help line.

Adding a New Configuration Option

To add a new configuration option, simply add new lines to an existing Kconfig file, in the same location as a related configuration option. For example, if a new USB sound device driver is written for the ALSA sound system, it would go into the sound/usb directory, and the sound/usb/Kconfig file would be added. This new device driver controls the mythical FooBar USB speaker device. It depends on having the CONFIG_SND and CONFIG_USB options enabled in addition to the CONFIG_SND_USB_AUDIO option, as the new driver uses some functions found in that driver. The new configuration option should be placed after the SND_USB_AUDIO option but before the closing endmenu command, and it would look something like:

config SND_USB_FOOBAR
    tristate "USB FooBar speaker device driver"
    depends SND_USB_AUDIO
    help
        Say Y here if you want to use FooBar USB
        speaker device.
        This code is also available as a module
        (= code which can be inserted in and
        removed from the running kernel whenever
        you want). The module will be called
        usbfoobar.o.

This option will now show up when the SND_USB_AUDIO option is selected (Figure 4).

Figure 4. The Newly Enabled FooBar USB Speaker Device

Building the Kernel

The kernel is built with a system of individual makefiles that are all linked together when the kernel is built, forming a large makefile. The individual makefiles do not look like any standard makefile, but instead follow a special format that is unique to the kernel build process. The makefile needs to build only the necessary files, depending on the configuration options enabled, in the proper format (as modules or built in to the kernel). As an example, drivers/usb/misc/Makefile in the 2.5.59 kernel release looks like:

#
# Makefile for the rest of the USB drivers
# (the ones that don't fit into any other
# categories)
#
obj-$(CONFIG_USB_AUERSWALD)  += auerswald.o
obj-$(CONFIG_USB_BRLVGER)    += brlvger.o
obj-$(CONFIG_USB_EMI26)      += emi26.o
obj-$(CONFIG_USB_LCD)        += usblcd.o
obj-$(CONFIG_USB_RIO500)     += rio500.o
obj-$(CONFIG_USB_SPEEDTOUCH) += speedtch.o
obj-$(CONFIG_USB_TEST)       += usbtest.o
obj-$(CONFIG_USB_TIGL)       += tiglusb.o
obj-$(CONFIG_USB_USS720)     += uss720.o
speedtch-objs := speedtouch.o atmsar.o

The line:

obj-$(CONFIG_USB_LCD)        += usblcd.o
builds the usblcd.c file into a module if the CONFIG_USB_LCD configuration option is set to m. Otherwise, it is built into the kernel directly if that configuration option is set to y. This step is all that is necessary to add to a kernel makefile if the module is made from only a single .c file.

If the driver consists of multiple .c files, the name of the files needs to be listed on separate lines, along with the name of the module that this driver is called. In the previous example file, this listing of file and driver names looks like:

obj-$(CONFIG_USB_SPEEDTOUCH) += speedtch.o

and

speedtch-objs := speedtouch.o atmsar.o
The first line controls whether the speedtch module is built. If it is, the line indicates whether it is compiled into the kernel or stands as a module. The second line explains that the speedtouch.c and atmsar.c files will be built into .o files and then linked together into the speedtch.o module.

In older kernels, if a file exported symbols, it needed to be explicitly mentioned in the kernel makefiles. In 2.5 and later kernels, that mention is no longer necessary.

Adding a New Driver to the Build Process

To add a new driver to the kernel build process, a single line needs to be added if the driver is contained within a single file. Based on the previous example of the FooBar USB speaker device, the line:

obj-$(CONFIG_SND_USB_FOOBAR) += usbfoobar.o

is added to sound/usb/Makefile.

If the driver is contained in two files, such as foobar1.c and foobar2.c, an additional line needs to be added:

usbfoobar-objs := foobar1.o foobar2.o

Conclusion

The kernel configuration and build process in the 2.5 kernel is much simpler and more flexible than in the previous kernel versions. Thanks go to Roman Zippel and Kai Germaschewski for doing the work to make it easier for kernel developers to focus on writing code and not have to worry about the intricacies of the kernel build process.

A good resource for more information on the specifics of the Kbuild process is available from Sam Ravnborg, at marc.theaimsgroup.com/?l=linux-kernel&m=104162417329638.

Greg Kroah-Hartman is currently the Linux USB and PCI Hot Plug kernel maintainer. He works for IBM, doing various Linux kernel-related things and can be reached at greg@kroah.com.