BuildSystemBreakdown

Differences between revisions 1 and 5 (spanning 4 versions)
Revision 1 as of 2010-07-07 16:57:23
Size: 3773
Editor: cpe-70-114-236-114
Comment:
Revision 5 as of 2010-07-07 22:11:24
Size: 3655
Editor: cpe-70-114-236-114
Comment:
Deletions are marked like this. Additions are marked like this.
Line 1: Line 1:
== Build system breakdown ==
This requires some knowledge of the Debian build system (including the debian/rules file, etc).

== Flavours ==
=== Flavours ===
Line 13: Line 10:
== configs == === configs ===
Line 18: Line 15:
== debian/control ==  === debian/control ===
Line 25: Line 22:
== debian/changelog == === debian/changelog ===
Line 28: Line 25:
== ABI == === ABI ===
Line 47: Line 44:
== Module lists ==  === Module lists ===
Line 50: Line 47:
== Commit templates == === Commit templates ===

Flavours

Flavours are how we define different types of kernels on the same architecture. Each flavour can be targeted to a specific CPU, or provide some functionality for a specific purpose.

For example, the amd64 (x86_64) architecture has these flavours:

  • generic - The default install kernel.
  • server - Optimized for server installations.

When building on the amd64 architecture, these are the kernels that are built. In reality, they only differ in slight variations of kernel config options.

configs

Each flavour is built using a pre-defined configuration file (used by the kernel build system). Each architecture contains it's config files in debian/config/<arch>/. The files are split for each flavour in debian/config/<arch>/config.<flavour>, and common options are shared in debian/config/<arch>/config.

When the kernels are built, the common and flavour specific config files are concatenated together in the build directory.

debian/control

The debian/control file is generated from debian/control.stub by the kernel-wedge command. This will be actioned automatically during a 'fakeroot debian/rules clean'.

The debian/control.stub file is generated from debian/control.stub.in by a debian/rules target. This is populated by files defining the flavours in debian/control.d/vars.*.

The vars files define package descriptions for each flavour.

debian/changelog

The changelog file is where we track all changes made to the repository. This is a standard debian/changelog. However, changes are not added to it manually. Instead, it is done automatically at release time using git log. See below for process.

ABI

The ABI is probably one of the most important features of the build system. In the kernel package naming, the ABI is the numerical component immediately following the kernel version. E.g.

2.6.26-1-generic

The ABI in the above example is 1. The ABI is represented in the <debian>/changelog as:

linux (2.6.26-1.1) intrepid; urgency=low

The minor version after the ABI is an ever increasing revision. It basically denotes how many uploads have been made for this kernel version.

The kernel ABI is derived from the Modules.symver file produced during the kernel build. Each exported function is given a hash defining the function's arguments and return value, making it easy to detect changes which can break modules built against the kernel (such as our own linux-restricted-modules package).

The ABI files for the previous build are located in <debian>/abi/<prev-rev>/. The layout is similar to the <debian>/config/ directory in that each architecture is a subdirectory, and each flavour is a file with the ABI for that flavour in it.

When the kernel build process finishes, it checks each flavour against the prev ABI. If the previous and current ABI's are the same version (e.g. 6), and the ABI has changed, the build will fail. This signifies that an ABI bump is needed (see below).

As of now, a single ABI change in any flavour results in an ABI bump for the entire build. There is no per-flavour or per-architecture ABI number. This is for sanity reasons.

Module lists

Module lists are tracked similarly to the ABI, and are kept in <debian>/abi/<prev-ver>/<arch>/<flavour>.modules. The file is a basename sorted list, sans .ko extension, of all the modules in a particular flavour. This is checked regardless of ABI, since it's meant to track release-to-release to avoid modules going missing by mistake.

Commit templates

In debian/commit-templates/ in the source tree there are several templates that should be used when committing changes that you expect to be integrated with the Ubuntu kernel repo. The commit templates contain comments for how to fill out the required information. Also note that all commits must have a Signed-off-by line (the "-s" option to git commit). A typical git commit command will look like:

  • git commit -s -F debian/commit-templates/patch -e

Note that the -e (edit) option must follow the -F option, else git will not let you edit the commit-template before committing. The primary one you will use is the patch template. It is commented heavily, so should be self explanatory. Some templates do not require editing such as the bumpabi and updateconfigs templates. An example commit log will look like this:

  • UBUNTU: scsi: My cool change to the scsi subsystem
    
    UpstreamStatus: Merged with 2.6.15-rc3
    
    My cool change to the scsi subsystem makes scsi transfers increase
    magically to 124GiB/sec.
    
    Signed-off-by: Joe Cool Hacker <jch@ubuntu.com>

The first line is critical and should summarise the change. The prefix for the line defines the type of the commit (see below). The last line should contain your sign-off for the patch and any acks it has received. The remainder of the text should concisely describe the change.

  • Prefix

    Meaning

    UBUNTU: SAUCE:

    a kernel source modification which is specific to Ubuntu

    UBUNTU: [Config]

    a change to the kernel configuration

    UBUNTU:

    any other change to the debian packaging for the kernel

    <none>

    upstream kernel patches

Kernel/Action/BuildSystemBreakdown (last edited 2010-07-07 22:11:24 by cpe-70-114-236-114)