<?xml version='1.0' encoding='utf-8'?>
<!-- -*- DocBook -*- -->
<chapter id="ch-packaging">
<?dbhtml filename="ch-packaging.html" ?>
<title>Debian kernel packages</title>
<section id="s-source-pkg"><title>Source packages</title>
<para>
The <package>linux</package> source package supports building of
kernel images and headers for all currently supported architectures.
The <package>linux-latest</package> source package supports building of
meta-packages that depend on them.
The <package>linux-signed</package> source package supports building
of signed kernel images and modules for some architectures.
Subsequent sections of this chapter document the naming and contents
of the binary packages built from these source packages.
</para>
</section>

<section id="s-arch-indep"><title>Architecture-independent packages</title>
<variablelist>
<varlistentry>
<term><package>linux-source-<replaceable>version</replaceable></package></term>
<listitem>
<para>
This package contains the Debian kernel source tarball.  Once the
package is installed, the source tarball is available at
<filename>/usr/src/linux-source-<replaceable>version</replaceable>.tar.xz</filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-manual-<replaceable>version</replaceable></package></term>
<listitem>
<para>
This package contains the manual pages for the functions, constituting the
kernel API.  These pages are installed into
<filename>/usr/share/man/man9/</filename>, and are accessible with the standard
<command>man</command> command.  Due to filename conflicts, only one
<package>linux-manual</package> package may be installed at any given time.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-doc-<replaceable>version</replaceable></package></term>
<listitem>
<para>
This package contains the rest of the kernel documentation in various formats.
It is installed in
<filename>/usr/share/doc/linux-doc-<replaceable>version</replaceable></filename>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-support-<replaceable>version</replaceable>-<replaceable>abiname</replaceable></package></term>
<listitem>
<para>
This package contains metadata from the <package>linux</package>
source package that is needed to prepare and build the other source
packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</package></term>
<listitem>
<para>
This package contains a common set of kernel headers for a particular
featureset (or no featureset).  Together with the flavour-specific
<package>linux-headers</package> package it provides a full set of
kernel headers, suitable for building of out-of-tree modules.  This
package should not normally be installed directly, but only as a
dependency of the flavour-specific headers package (see below).  It
unpacks into the
<filename>/usr/src/linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</filename>
directory.  Before version 4.9 these packages were
architecture-dependent.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

<section id="s-arch-dep"><title>Architecture-dependent packages</title>
<para>
The kind of hardware the particular kernel package is designed for is uniquely
identified by the <emphasis>architecture</emphasis>,
<emphasis>featureset</emphasis>, and <emphasis>flavour</emphasis>.  Kernels for
all architectures are built from the same Debian kernel source tree, which is
obtained using the procedure described in <xref linkend="ch-source"/>.  Each
architecture usually has multiple flavours of the binary kernel images.
Different flavours correspond to different kernel configuration files, used to
build the binary images from the <emphasis role="strong">same</emphasis> kernel
tree.
</para>
<para>
In order to build a working kernel with an extra featureset not provided by the
upstream source, additional changes to the Debian kernel source are required.
Again, multiple flavours of binary images may be built from the featureset
tree.  For example, the <literal>i386</literal> architecture has a number of
different flavours, such as <literal>686</literal> and
<literal>686-pae</literal>, built from the common Debian kernel source.  It
also contains the <literal>rt</literal> featureset.  The source tree for
building the kernels for each of these featuresets is obtained by applying
additional patches to the Debian kernel source.  It may be used to build the
<literal>rt-686-pae</literal> binary image flavours.  The names of the Debian
binary packages incorporate the name of the flavour and, if necessary, the name
of the featureset (there is no need to worry about the name of the
architecture, since Debian tools will only allow installation of the packages
with "correct" architecture).  If the arch does not have any featuresets, the
featureset part is omitted from the name, as indicated by the square brackets
below.
</para>
<para>
Package names also include the <emphasis>abiname</emphasis>, a small integer,
which identifies the kernel's binary compatibility level.  The kernels with
different abinames are binary incompatible, so upgrading to a kernel with a
different abiname will most likely require recompilation of third-party binary
modules against the new kernel.  The list of architecture-dependent packages
together with a short description is given below.
</para>
<variablelist>
<varlistentry>
<term><package>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></package></term>
<listitem>
<para>
This package provides flavour-specific header files.  It depends on the
corresponding
<package>linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>-common[-<replaceable>featureset</replaceable>]</package>
package, and sets up symbolic links into its directory tree in such a way that
the directory
<filename>/usr/src/linux-headers-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></filename>
appears to contain a full set of headers, required for building of out-of-tree
kernel modules.  For more information on this check out <xref
linkend="s-common-out-of-tree"/>.  A complete set of kernel headers matching the
currently running official kernel may be installed with a command
</para>
<screen>
apt-get install linux-headers-$(uname -r)
</screen>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-image[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></package></term>
<term><package>linux-headers[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></package></term>
<listitem>
<para>
These meta-packages provide (via dependencies) the latest binary image and
matching set of header files (respectively) for a particular flavour.  Example:
<package>linux-image-rt-686-pae</package>
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-image-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></package></term>
<listitem>
<para>
This package contains the binary kernel image and pre-built binary modules for
a particular arch/featureset/flavour combination.  Names of the files installed
by this package are architecture-dependent.  Typical locations of essential
files for the <literal>i386</literal> architecture are:
</para>
<variablelist>
<varlistentry>
<term><filename>/boot/vmlinuz-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></filename></term>
<listitem>
<para>
The binary (compressed) kernel image.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/boot/initrd.img-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></filename></term>
<listitem>
<para>
Initial RAM filesystem (initramfs) image.  Note, that this file is
automatically generated in the installation process and is <emphasis
role="strong">not</emphasis> shipped as a part of the package.  See <xref
linkend="ch-initramfs"/> for more details.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/boot/config-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable></filename></term>
<listitem>
<para>
The kernel configuration file used to build this particular kernel.  May be
used to rebuild the kernel from source, if necessary.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><filename>/lib/modules/<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>/</filename></term>
<listitem>
<para>
Directory containing the pre-built binary kernel modules.
</para>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-image-<replaceable>version</replaceable>-<replaceable>abiname</replaceable>[-<replaceable>featureset</replaceable>]-<replaceable>flavour</replaceable>-unsigned</package></term>
<listitem>
<para>
This package contains the binary kernel image and pre-built binary modules for
a particular arch/featureset/flavour combination, that are meant to be signed
and copied into a package without the <package>-unsigned</package> suffix.
There is normally no need to install these packages.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><package>linux-libc-dev</package></term>
<listitem>
<para>
This package provides Linux kernel headers for use by userspace programs, such
as GNU glibc and other system libraries.
</para>
</listitem>
</varlistentry>
</variablelist>
</section>

</chapter>