<chapt id="packaging">
  <heading>Debian kernel packages</heading>
  <sect id="source-pkg">
    <heading>Source package</heading>
    <p>

      To ensure that the latest kernel version, containing all the
      essential bug and security fixes is available on as many
      architectures as possible, starting with 2.6.12 the kernel team
      introduced a new packaging scheme. In it most of the
      kernel-related binary packages are built from a single source
      package <tt>linux</tt> (previously <tt>linux-2.6</tt>). The
      <tt>linux</tt> source package supports building of kernel
      images and headers for all currently supported
      architectures. Subsequent sections of this chapter document the
      naming and contents of the binary packages built from the
      <tt>linux</tt> source package.

    </p>
    <sect id="arch-indep">
      <heading>Architecture-independent packages</heading>
      <p>
      <taglist>
        <tag><tt>linux-source-<em>version</em></tt></tag> 
	  <item>

 	    This package contains the Debian kernel source
	    tarball. The patchlevel of the source is determined by the
	    Debian revision of the package, for example the version 3.2.19-1
	    of the package <tt>linux-source-3.2</tt> contains the
	    version 3.2.19 of the Debian kernel source patched to
	    patchlevel 1. Once the package is installed, the source
	    tarball is available at
	    <tt>/usr/src/linux-source-<em>version</em>.tar.bz2</tt>.
	  </item>
	<tag><tt>linux-manual-<em>version</em></tt></tag>
	  <item>

	    This package contains the manual pages for the functions,
	    constituting the kernel API. These pages are installed
	    into <tt>/usr/share/man/man9/</tt>, and are accessible
	    with the standard <tt>man</tt> command. Due to filename
	    conflicts, only one <tt>linux-manual</tt> package may be
	    installed at any given time.

	  </item>
	<tag><tt>linux-doc-<em>version</em></tt></tag>
	  <item>

	    This package contains the rest of the kernel documentation
	    in various formats. It is installed in
	    <tt>/usr/share/doc/linux-doc-<em>version</em></tt>.

	  </item>
        <tag><tt>linux-support-<em>version</em>-<em>abiname</em></tt></tag> 
	<item>

            This package contains the support files for building of
            out-of-tree modules for given version and abiname.

	</item>
      </taglist>
      </p>
      </sect>
      <sect id="arch-dep">
        <heading>Architecture-dependent packages</heading>
	<p>

	  The kind of hardware the particular kernel package is
	  designed for is uniquely identified by the
	  <em>architecture</em>, <em>featureset</em>, and
	  <em>flavour</em>. Kernels for all architectures are built
	  from the same Debian kernel source tree, which is obtained
	  using the procedure described in <ref id="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 <strong>same</strong> kernel tree.

	</p>

	<p>

	  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 <tt>i386</tt> architecture has a number of
	  different flavours, such as <tt>486</tt>, <tt>686-pae</tt> and
	  <tt>amd64</tt>, built from the common Debian kernel source. It
	  also contains the <tt>rt</tt> 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 <tt>rt-686-pae</tt>
	  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.

	</p>
	<p>

	  Package names also include the <em>abiname</em>, 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.

        </p>
	<p>
	  <taglist>
	  <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt></tag>
	  <item>

	    This package contains a common set of kernel headers for a
	    particular featureset (or arch, if featureset is
	    empty). Together with the flavour-specific
	    <tt>linux-headers</tt> 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 next description). It unpacks into
	    the
	    <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
	    directory.

	  </item>
	  </taglist>
	  <taglist>
	  <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
	  <item>

	    This package provides flavour-specific header files. It
	    depends on the corresponding
	    <tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
	    package, and sets up symbolic links into its directory
	    tree in such a way that the directory
	    <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt>
	    appears to contain a full set of headers, required for
	    building of out-of-tree kernel modules.  For more
	    information on this check out <ref
	    id="common-out-of-tree">. A complete set of kernel headers
	    matching the currently running official kernel may be
	    installed with a command

	    <example>
apt-get install linux-headers-$(uname -r)
            </example>

	  </item>
	  <tag><tt>linux-image[-<em>featureset</em>]-<em>flavour</em></tt></tag>
	  <tag><tt>linux-headers[-<em>featureset</em>]-<em>flavour</em></tt></tag>
	  <item>
	    <p>
	      These virtual packages provide (via dependencies) the latest 
	      binary image and matching set of header files (respectively)
	      for a particular flavour. Example: <tt>linux-image-rt-686-pae</tt>
	    </p>
	    <p>
	      In Debian 6.0 (squeeze) and earlier, the headers
	      metapackages were
	      named <tt>linux-headers-2.6[-<em>featureset</em>]-<em>flavour</em></tt>.
	    </p>
	  </item>
	  <tag><tt>linux-image-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
	  <item>
	    <p>
	      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 <tt>i386</tt> architecture are:
	      <taglist>
	        <tag><tt>/boot/vmlinuz-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
		<item>
		  The binary (compressed) kernel image.
		</item>
	        <tag><tt>/boot/initrd.img-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
		<item>
		  Initial RAM filesystem (initramfs) image. Note, that this file is automatically generated
		  in the installation process and is <strong>not</strong> shipped as a part of the package.
		  See <ref id="initramfs"> for more details.
		</item>
		<tag><tt>/boot/config-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
		<item>
		  The kernel configuration file used to build this particular kernel. May be used
		  to rebuild the kernel from source, if necessary.
		</item>
		<tag><tt>/lib/modules/<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em>/</tt></tag>
		<item>
		  Directory containing the pre-built binary kernel modules.
		</item>
	      </taglist>
	  </item>
	  <tag><tt>linux-libc-dev</tt></tag>
	  <item>
	    <p>
	      This package provides Linux kernel headers for use by userspace programs,
	      such as GNU glibc and other system libraries.
	    </p>
	  </item>
	  </taglist>
	</p>
      </sect>
    </chapt>
