Release kernel-handbook (1.0.11).
[kernel-handbook/kernel-handbook.git] / 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>