chapter-packaging.sgml

   1 <chapt id="packaging">
   2   <heading>Debian kernel packages</heading>
   3   <sect id="source-pkg">
   4     <heading>Source package</heading>
   5     <p>
   6
   7       To ensure that the latest kernel version, containing all the
   8       essential bug and security fixes is available on as many
   9       architectures as possible, starting with 2.6.12 the kernel team
  10       introduced a new packaging scheme. In it most of the
  11       kernel-related binary packages are built from a single source
  12       package <tt>linux-2.6</tt>. The
  13       <tt>linux-2.6</tt> source package supports building of kernel
  14       images and headers for all currently supported
  15       architectures. Subsequent sections of this chapter document the
  16       naming and contents of the binary packages built from the
  17       <tt>linux-2.6</tt> source package.
  18
  19     </p>
  20     <sect id="arch-indep">
  21       <heading>Architecture-independent packages</heading>
  22       <p>
  23       <taglist>
  24         <tag><tt>linux-source-<em>version</em></tt></tag>
  25           <item>
  26
  27             This package contains the Debian kernel source
  28             tarball. The patchlevel of the source is determined by the
  29             Debian revision of the package, for example the version 2.6.26-2
  30             of the package <tt>linux-source-2.6.26</tt> contains the
  31             version 2.6.26 of the Debian kernel source patched to
  32             patchlevel 2. Once the package is installed, the source
  33             tarball is available at
  34             <tt>/usr/src/linux-source-<em>version</em>.tar.bz2</tt>. For
  35             the instructions on obtaining Debian kernel source with
  36             arbitrary patchlevel, see <ref id="common-getting">.
  37
  38           </item>
  39         <tag><tt>linux-manual-<em>version</em></tt></tag>
  40           <item>
  41
  42             This package contains the manual pages for the functions,
  43             constituting the kernel API. These pages are installed
  44             into <tt>/usr/share/man/man9/</tt>, and are accessible
  45             with the standard <tt>man</tt> command. Due to filename
  46             conflicts, only one <tt>linux-manual</tt> package may be
  47             installed at any given time.
  48
  49           </item>
  50         <tag><tt>linux-doc-<em>version</em></tt></tag>
  51           <item>
  52
  53             This package contains the rest of the kernel documentation
  54             in various formats. It is installed in
  55             <tt>/usr/share/doc/linux-doc-<em>version</em></tt>.
  56
  57           </item>
  58         <tag><tt>linux-patch-debian-<em>version</em></tt></tag>
  59           <item>
  60
  61             This package contains all patches used to produce the
  62             Debian kernel source. It also contains the scripts which
  63             allow application or un-application of patchsets, bringing
  64             the source to the desired patchlevel. After the
  65             installation the patches are installed in
  66             <tt>/usr/src</tt> as follows:
  67
  68             <taglist>
  69             <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/debian/</tt></tag>
  70             <item>
  71
  72               This directory contains the hierarchy of subdirectories with individual
  73               compressed patch files for a given version. Subdirectories indicate
  74               source or purpose of the patches contained within it, like <tt>bugfix</tt>
  75               (essential bugfixes), <tt>debian</tt> (Debian-specific patches) or
  76               <tt>features</tt> (kernel features not yet merged upstream). Within
  77               these directories patches are further subdivided by architecture.
  78
  79             </item>
  80           <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/debian/series/</tt></tag>
  81             <item>
  82
  83               This directory contains the control files, which
  84               determine which patches need to be applied (or
  85               unapplied) to move from one patchlevel to another. These
  86               are text files named <tt><em>N</em></tt>
  87               (or <tt><em>N</em>-extra</tt>), where <tt><em>N</em></tt>
  88               is the number specifiying the patchlevel. The file
  89               <tt><em>N</em></tt> contains a
  90               list of patches which need to be applied (in case when
  91               the name of the patch prepended with plus) or unapplied
  92               (if it is prepended with a minus) to move from
  93               patchlevel <tt><em>N</em>-1</tt> to patchlevel
  94               <tt><em>N</em></tt>.  For example, the file
  95               <tt>1</tt> lists the patches which need
  96               to be applied to go from the original Debian kernel source to
  97               the patchlevel 1. Files
  98               named <tt><em>N</em>-extra</tt> list
  99               the architecture-specific patches, along with the
 100               architectures they apply to. There is also a special file
 101               <tt>orig-0</tt>, which lists the patches (scripts) which
 102               were applied (run) in order to obtain the Debian kernel
 103               source from upstream kernel source (by removing the parts
 104               incompatible with DFSG). Invocation of a script is identified
 105               by <tt>X</tt> in the first column in this file.
 106
 107             </item>
 108           <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/apply/debian</tt></tag>
 109             <item>
 110
 111               This script may be used to change the patchlevel of the
 112               currently available source tree, when run from its
 113               top-level directory. For usage example see <ref
 114               id="common-getting">. Current patchlevel of the source tree
 115               is stored in the <tt>version.Debian</tt> file in the top-level
 116               directory, and script modifies it appropriately when switching
 117               from one patchlevel to another. You can specify patchlevel <tt>orig</tt>
 118               to remove all Debian-specific patches, rolling back to the original
 119               Debian kernel source (differing from upstream by removal of
 120               firmware and other problematic files, as well as changes required
 121               for the resulting kernel to be buildable). Note that there is currently
 122               a bug in the script, preventing rollbacks of more than one patchlevel.
 123               For example, if your tree is currently at patchlevel 2, a command
 124               <example>
 125 $ /usr/src/kernel-patches/all/2.6.26/apply/debian orig
 126               </example>
 127               is likely to fail, so use commands
 128               <example>
 129 $ /usr/src/kernel-patches/all/2.6.26/apply/debian 1
 130 $ /usr/src/kernel-patches/all/2.6.26/apply/debian orig
 131               </example>
 132               i.e. switch the levels one by one instead.
 133
 134           <tag><tt>/usr/src/kernel-patches/all/<em>version</em>/unpatch/debian</tt></tag>
 135             <item>
 136
 137               This script brings the tree to the <tt>orig</tt> patchlevel (equivalent
 138               to running <tt>/usr/src/kernel-patches/all/<em>version</em>/apply/debian orig</tt>).
 139               See previous sections for discussion.
 140
 141             </item>
 142           </taglist>
 143         </item>
 144         <tag><tt>linux-tree-<em>version</em></tt></tag>
 145         <item>
 146
 147             This is a dummy package whose sole purpose is to satisfy
 148             the build dependencies for a successful kernel build. In
 149             the old kernel build system build-depending on the package
 150             <tt>linux-tree-<em>version</em>-<em>N</em></tt>, provided
 151             by the <tt>linux-tree-<em>version</em></tt>, would result
 152             in the automatic installation of all the required source
 153             and patch packages, and patching of the kernel source to
 154             patchlevel <tt><em>N</em></tt> before building. It has
 155             been obsoleted by the new common packaging system and is
 156             provided for backward compatibility only.
 157
 158         </item>
 159         <tag><tt>linux-support-<em>version</em>-<em>abiname</em></tt></tag>
 160         <item>
 161
 162             This package contains the support files for building of
 163             out-of-tree modules for given version and abiname.
 164
 165         </item>
 166       </taglist>
 167       </p>
 168       </sect>
 169       <sect id="arch-dep">
 170         <heading>Architecture-dependent packages</heading>
 171         <p>
 172
 173           The kind of hardware the particular kernel package is
 174           designed for is uniquely identified by the
 175           <em>architecture</em>, <em>featureset</em>, and
 176           <em>flavour</em>. Kernels for all architectures are built
 177           from the same Debian kernel source tree, which is obtained
 178           using the procedure described in <ref id="source">. Each
 179           architecture usually has multiple flavours of the binary
 180           kernel images. Different flavours correspond to different
 181           kernel configuration files, used to build the binary images
 182           from the <strong>same</strong> kernel tree.
 183
 184         </p>
 185
 186         <p>
 187
 188           In order to build a working kernel with an extra featureset
 189           not provided by the upstream source, additional changes to
 190           the Debian kernel source are required. Again, multiple
 191           flavours of binary images may be built from the featureset
 192           tree. For example, the <tt>i386</tt> architecture has a number of
 193           different flavours, such as <tt>486</tt>, <tt>686</tt> and
 194           <tt>686-bigmem</tt>, built from the common Debian kernel source. It
 195           also contains <tt>xen</tt> and <tt>openvz</tt>
 196           featuresets. The source tree for
 197           building the kernels for each of these featuresets is
 198           obtained by applying additional patches to the Debian kernel
 199           source. It may be used to build the <tt>xen-686</tt> and
 200           <tt>openvz-686</tt> binary image flavours. The names of the
 201           Debian binary packages incorporate the name of the flavour
 202           and, if necessary, the name of the featureset (there is
 203           no need to worry about the name of the architecture, since
 204           Debian tools will only allow installation of the packages
 205           with "correct" architecture). If the arch does not have any
 206           featuresets, the featureset part is omitted from the name, as
 207           indicated by the square brackets below.
 208
 209         </p>
 210         <p>
 211
 212           Package names also include the <em>abiname</em>, a small
 213           integer, which identifies the kernel's binary compatibility
 214           level. The kernels with different abinames are binary
 215           incompatible, so upgrading to a kernel with a different
 216           abiname will most likely require recompilation of
 217           third-party binary modules against the new kernel. The list
 218           of architecture-dependent packages together with a short
 219           description is given below.
 220
 221         </p>
 222         <p>
 223           <taglist>
 224           <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt></tag>
 225           <item>
 226
 227             This package contains a common set of kernel headers for a
 228             particular featureset (or arch, if featureset is
 229             empty). Together with the flavour-specific
 230             <tt>linux-headers</tt> package it provides a full set of
 231             kernel headers, suitable for building of out-of-tree
 232             modules. This package should not normally be installed
 233             directly, but only as a dependency of the flavour-specific
 234             headers package (see next description). It unpacks into
 235             the
 236             <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
 237             directory.
 238
 239           </item>
 240           </taglist>
 241           <taglist>
 242           <tag><tt>linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 243           <item>
 244
 245             This package provides flavour-specific header files. It
 246             depends on the corresponding
 247             <tt>linux-headers-<em>version</em>-<em>abiname</em>-common[-<em>featureset</em>]</tt>
 248             package, and sets up symbolic links into its directory
 249             tree in such a way that the directory
 250             <tt>/usr/src/linux-headers-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt>
 251             appears to contain a full set of headers, required for
 252             building of out-of-tree kernel modules.  For more
 253             information on this check out <ref
 254             id="common-out-of-tree">. A complete set of kernel headers
 255             matching the currently running official kernel may be
 256             installed with a command
 257
 258             <example>
 259 apt-get install linux-headers-$(uname -r)
 260             </example>
 261
 262           </item>
 263           <tag><tt>linux-image[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 264           <item>
 265             <p>
 266               This is a virtual package, providing (via dependencies) the latest
 267               binary image for a particular flavour. Example: <tt>linux-image-openvz-686</tt>.
 268           </item>
 269           <tag><tt>linux-image-2.6[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 270           <tag><tt>linux-headers-2.6[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 271           <item>
 272             <p>
 273               These virtual packages provide (via dependencies) the latest
 274               2.6 series binary image and matching set of header files (respectively)
 275               for a particular flavour. Example: <tt>linux-image-2.6-openvz-686</tt>
 276           </item>
 277           <tag><tt>linux-image-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 278           <item>
 279             <p>
 280               This package contains the binary kernel image and
 281               pre-built binary modules for a particular
 282               arch/featureset/flavour combination. Names of the files
 283               installed by this package are
 284               architecture-dependent. Typical locations of essential
 285               files for the <tt>i386</tt> architecture are:
 286               <taglist>
 287                 <tag><tt>/boot/vmlinuz-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 288                 <item>
 289                   The binary (compressed) kernel image.
 290                 </item>
 291                 <tag><tt>/boot/initrd.img-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 292                 <item>
 293                   Initial RAM filesystem (initramfs) image. Note, that this file is automatically generated
 294                   in the installation process and is <strong>not</strong> shipped as a part of the package.
 295                   See <ref id="initramfs"> for more details.
 296                 </item>
 297                 <tag><tt>/boot/config-<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em></tt></tag>
 298                 <item>
 299                   The kernel configuration file used to build this particular kernel. May be used
 300                   to rebuild the kernel from source, if necessary.
 301                 </item>
 302                 <tag><tt>/lib/modules/<em>version</em>-<em>abiname</em>[-<em>featureset</em>]-<em>flavour</em>/</tt></tag>
 303                 <item>
 304                   Directory containing the pre-built binary kernel modules.
 305                 </item>
 306               </taglist>
 307           </item>
 308           <tag><tt>linux-libc-dev</tt></tag>
 309           <item>
 310             <p>
 311               This package provides Linux kernel headers for use by userspace programs,
 312               such as GNU glibc and other system libraries.
 313             </p>
 314           </item>
 315           </taglist>
 316         </p>
 317       </sect>
 318     </chapt>