1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
|
<chapt id="common-tasks">
<heading>Common kernel-related tasks</heading>
<sect id="common-getting">
<heading>Obtaining the Debian kernel source</heading>
<p>
To get the Debian kernel source at the current maximum patchlevel,
it is sufficient to install the latest <tt>linux-source-<em>version</em></tt>
package and unpack the source, for example:
<example>
# apt-get install linux-source-3.2
$ tar jxf /usr/src/linux-source-3.2.tar.bz2
</example>
The unpacked source tree then will be available in <tt>linux-source-3.2</tt> directory.
</p>
</sect>
<sect id="common-official">
<heading>Rebuilding official Debian kernel packages</heading>
<p>
You can build all or selected kernel packages by following
these instructions. You may be asked to do this in order to
test a potential bug fix.
</p>
<sect1>
<heading>Preparation</heading>
<p>
For Debian 6.0 (squeeze) and earlier versions, substitute
the source package name <tt>linux-2.6</tt> for
<tt>linux</tt>.
</p>
<p>
Run the following commands:
<taglist>
<tag><tt>$ apt-get source linux</tt></tag>
<item>
This will download and unpack the
<tt>linux</tt> source package, making the
tree available in the
<tt>linux-<em>version</em></tt>
directory. As always, the revision part of the version
of this package (for example, 1 in 3.2.19-1) will
determine its patchlevel with respect to the original
upstream kernel source.
</item>
<tag><tt># apt-get install build-essential fakeroot</tt></tag>
<tag><tt># apt-get build-dep linux</tt></tag>
<item>
The last two commands will install the build dependencies required by the kernel
build process.
</item>
<tag><tt>$ cd linux-<em>version</em></tt></tag>
<item>
Enter the source directory.
</item>
</taglist>
</p>
<sect2 id="common-size">
<heading>Disk space requirements</heading>
<p>
Building binary packages for a single kernel flavour
with debug info enabled (currently true for
the <tt>686-pae</tt>, <tt>amd64</tt>, <tt>rt-686-pae</tt>,
<tt>rt-amd64</tt> and <tt>s390x</tt> configurations)
requires up to 10 GB space in the package directory
and 300 MB in <tt>/tmp</tt> (or <tt>$TMPDIR</tt>).
</p>
<p>
Building with debug info disabled requires about
2 GB and 25 MB respectively. You can disable
debug info by changing the value of <tt>debug-info</tt>
to <tt>false</tt> in
<tt>debian/config/</tt><var>arch</var><tt>/defines</tt>.
</p>
<p>
Building all binary packages for i386 or amd64 currently
requires about 20 GB space in the package
directory. Other architectures with no debug info or
fewer drivers will require less space.
</p>
</sect2>
</sect1>
<sect1>
<heading>Simple patching and building</heading>
<p>
The source package includes a script to simplify the
process of building with extra patches. You can use this
by running commands such as:
<example>
# apt-get install devscripts
$ bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch
</example>
This script has options to control the flavour, featureset,
etc. For a summary of the options, run:
<example>
$ bash debian/bin/test-patches
</example>
</p>
<p>
You may then need to build the linux-base package as well:
<example>
$ fakeroot make -f debian/rules.real install-linux-base
</example>
</p>
<p>
However, if you need to change the configuration or make
other changes, you should not use this script and should
follow the instructions below.
</p>
</sect1>
<sect1>
<heading>Applying patches or configuration changes</heading>
<p>
It is possible to apply extra patches to the source before
starting the build. In the <tt>linux</tt> source package,
the default (non-featureset) patches are automatically
applied in the top level directory. If you are building
the <tt>linux-2.6</tt> source package or building with a
featureset, you should first apply the existing patches by
running:
<example>
$ fakeroot debian/rules source
</example>
The patched source appears in the following directories.
<taglist>
<tag>linux default source:</tag>
<item>top level</item>
<tag>linux source with featureset:</tag>
<item><tt>debian/build/source_<em>featureset</em></tt></item>
<tag><tt>linux-2.6</tt> default source:</tag>
<item><tt>debian/build/source_<em>arch</em>_none</tt></item>
<tag><tt>linux-2.6</tt> source with featureset:</tag>
<item><tt>debian/build/source_<em>arch</em>_<em>featureset</em></tt></item>
</taglist>
You should apply the extra patches in the appropriate
directory. In the <tt>linux</tt> source package you can
use the <tt>quilt</tt> utility to do this.
</p>
<p>
To change the configuration before building, for example
for the 686-pae flavour on i386, run the commands:
<example>
$ fakeroot make -f debian/rules.gen setup_i386_none_686-pae
$ make -C debian/build/build_i386_none_686-pae menuconfig
</example>
</p>
<p>
If the patches or configuration changes alter type
definitions for the kernel, you may need to change the ABI
name; see <ref id="abi-name">.
</p>
</sect1>
<sect1>
<heading>Building many packages</heading>
<p>
To build all possible packages for this architecture, run:
<example>
$ fakeroot debian/rules binary
</example>
To build all architecture-dependent packages, run:
<example>
$ fakeroot debian/rules binary-arch
</example>
To build all architecture-independent packages, run:
<example>
$ fakeroot debian/rules binary-indep
</example>
</p>
</sect1>
<sect1>
<heading>Building packages for one flavour</heading>
<p>
For example, to build only the binary packages for 686-pae
flavour on i386 architecture, use the following commands:
<example>
$ fakeroot debian/rules source
$ fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae
</example>
The target in this command has the general form of
<tt><em>target</em>_<em>arch</em>_<em>featureset</em>_<em>flavour</em></tt>.
Replace the <tt><em>featureset</em></tt> with
<tt>none</tt> if you do not want any of the extra
featuresets. This command will build the linux image and
kernel headers packages. You may also need
the <tt>linux-headers-<em>version</em>-common</tt> binary
package, which can be built using the commands:
<example>
$ fakeroot debian/rules source
$ fakeroot make -f debian/rules.gen binary-arch_i386_none_real
</example>
The target in this command has the general form of
<tt><em>target</em>_<em>arch</em>_<em>featureset</em>_<em>real</em></tt>
</p>
</sect1>
</sect>
<sect id="common-official-vcs">
<heading>Building a development version of the Debian kernel package</heading>
<p>
For Debian 6.0 (squeeze) and earlier versions, substitute
the source package name <tt>linux-2.6</tt> for
<tt>linux</tt>.
</p>
<p>
To build a kernel image based on the kernel team's
unreleased development version:
<taglist>
<tag><tt># apt-get install build-essential fakeroot rsync svn</tt></tag>
<tag><tt># apt-get build-dep linux</tt></tag>
<item>
The last two commands will install the build
dependencies required by the kernel build process.
</item>
<tag><tt>$ svn co svn://anonscm.debian.org/svn/kernel/dists/<em>dist</em>/linux</tt></tag>
<item>
This will check out the Debian packaging. <em>dist</em>
is normally the distribution codename such as
<tt>wheezy</tt> or <tt>sid</tt> (unstable). For the very
latest version, usually based on an upstream release
candidate, use <tt>trunk</tt>.
</item>
<tag><tt>$ apt-get source -d linux</tt></tag>
<item>
This will download the <tt>linux</tt> upstream
source (and the last released Debian patches).
Depending on which version you are trying to build,
you might need to override APT's version selection
or download a tarball from
<url id="http://people.debian.org"
name="people.debian.org"> instead.
</item>
<tag><tt>$ cd linux</tt></tag>
<tag><tt>$ debian/rules orig</tt></tag>
<item>
This unpacks the upstream source and merges it with
the Debian packaging.
</item>
<tag><tt>$ debian/rules debian/control</tt></tag>
<item>
This generates a Debian package control file based on
the current definitions of the various kernel flavours
which can be built.
</item>
<tag><tt>$ fakeroot debian/rules <em>target</em></tt></tag>
<item>
Finally, build binary packages as explained in
<ref id="common-official">.
</item>
</taglist>
</p>
</sect>
<sect id="gen-orig">
<heading>Generating orig tarball from newer upstream</heading>
<p>
First you must add a changelog entry for the new upstream
version. If the new version is a release candidate, change
the string <tt>-rc</tt> to <tt>~rc</tt>. (In Debian package
versions, a suffix beginning with <tt>~</tt> indicates a
pre-release.)
</p>
<p>
The 'orig' tarball is generated by the <tt>genorig.py</tt>
script. It takes either a tarball and optional patch from
kernel.org, or a git repository. If you have a tarball, run
a command such as:
<example>
$ python debian/bin/genorig.py ../linux-3.4.tar.bz2 ../patch-3.5-rc1.bz2
</example>
</p>
<p>
If you have a git repository, pass the name of its
directory:
<example>
$ python debian/bin/genorig.py ~/src/linux
</example>
</p>
<p>
Either of these will generate a file such as
<tt>../orig/linux_3.5~rc1.orig.tar.xz</tt>.
You can then combine this tarball with the Debian packaging
by running:
<example>
$ debian/rules orig
</example>
</p>
</sect>
<sect id="common-building">
<heading>Building a custom kernel from Debian kernel source</heading>
<p>
This section describes the simplest possible procedure to
build a custom kernel the "Debian way". It is assumed that
user is somewhat familiar with kernel configuration and
build process. If that's not the case, it is recommended to
consult the kernel documentation and many excellent online
resources dedicated to it.
</p>
<p>
The easiest way to build a custom kernel (the kernel with
the configuration different from the one used in the
official packages) from the Debian kernel source is to use
the <tt>linux-source</tt> package and the <tt>make deb-pkg</tt>
target. First, prepare the kernel tree:
<example>
# apt-get install linux-source-3.2
$ tar xjf /usr/src/linux-source-3.2.tar.bz2
$ cd linux-source-3.2
</example>
The kernel now needs to be configured, that is you have to
set the kernel options and select the drivers which are
going to be included, either as built-in, or as external
modules. The kernel build infrastructure offers a number of
targets, which invoke different configuration frontends. For
example, one can use console-based menu configuration by
invoking the command
<example>
$ make menuconfig
</example>
Instead of <tt>menuconfig</tt> one can use <tt>config</tt>
(text-based line-by-line configuration frontend) or
<tt>xconfig</tt> (graphical configuration frontend). It is
also possible to reuse your old configuration file by
placing it as a <tt>.config</tt> file in the top-level
directory and running one of the configuration targets (if
you want to adjust something) or <tt>make oldconfig</tt>
(to keep the same configuration).
Note that different frontends may require different
additional libraries and utilities to be installed to
function properly. For example, the <tt>menuconfig</tt>
frontend requires the <tt>ncurses</tt> library, which at
time of writing is provided by the <tt>libncurses5-dev</tt>
package.
</p>
<p>
The build will use less disk space if the CONFIG_DEBUG_INFO
option is disabled (see <ref id="common-size">).
Debuginfo is only needed if you plan to use binary object
tools like crash, kgdb, and SystemTap on the kernel.
<example>
$ scripts/config --disable DEBUG_INFO
</example>
</p>
<p>
After the configuration process is finished, the new or
updated kernel configuration will be stored in
<tt>.config</tt> file in the top-level directory. The build
is started using the commands
<example>
$ make clean
$ make deb-pkg
</example>
As a result of the build, a custom kernel package
<tt>linux-image-3.2.19_3.2.19-1_i386.deb</tt> (name will
reflect the version of the kernel and build number) will be
created in the directory one level above the top of the
tree. It may be installed using
<tt>dpkg</tt> just as any other package:
<example>
# dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb
</example>
This command will unpack the kernel, generate the initrd if
necessary (see <ref id="initramfs"> for details), and configure
the bootloader to make the newly installed kernel the
default one. If this command completed without any problems,
you can reboot using the
<example>
# shutdown -r now
</example>
command to boot the new kernel.
</p>
<p>
For much more information about
bootloaders and their configuration please check their
documentation, which can be accessed using the commands
<tt>man lilo</tt>, <tt>man
lilo.conf</tt>, <tt>man grub</tt>, and so on. You can also
look for documentation in the
<tt>/usr/share/doc/<em>package</em></tt> directories, with
<tt><em>package</em></tt> being the name of the package
involved.
</p>
</sect>
<sect id="kernel-org-package">
<heading>Building a custom kernel from the "pristine" kernel source</heading>
<p>Building a kernel from the "pristine" (also sometimes called "vanilla")
kernel source, distributed from <url id="http://www.kernel.org" name="www.kernel.org">
and its mirrors, may be occasionally useful for debugging or in the
situations when a newer kernel version is desired. The procedure
differs only in obtaining the kernel source: instead of unpacking
the kernel source from Debian packages, the "pristine" source is
downloaded using your favourite browser or using wget, as follows:
<example>
$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.bz2
</example>
The integrity of the downloaded archive may be verified by fetching
the corresponding cryptographic signature
<example>
$ wget http://kernel.org/pub/linux/kernel/v3.x/linux-3.4.tar.bz2.sign
</example>
and running this command (<tt>gnupg</tt> package must be installed):
<example>
$ gpg --verify linux-3.4.tar.bz2.sign
</example>
Successful verification results in output similar to the one below:
<example>
gpg: Signature made Wed 29 Nov 2006 02:50:07 PM PST using DSA key ID 517D0F0E
gpg: Good signature from "Linux Kernel Archives Verification Key <ftpadmin@kernel.org>"
gpg: WARNING: This key is not certified with a trusted signature!
gpg: There is no indication that the signature belongs to the owner.
Primary key fingerprint: C75D C40A 11D7 AF88 9981 ED5B C86B A06A 517D 0F0E
</example>
After that the archive may be unpacked using
<example>
$ tar xjf linux-3.4.tar.bz2
$ cd linux-3.4
</example>
The unpacked kernel tree (in <tt>linux-3.4</tt> now has to be configured.
The existing configuration file may be used as a starting point
<example>
$ cp /boot/config-3.2.0-2-686-pae ./.config
</example>
After the configuration with one of the configuration frontends (invoked by <tt>make oldconfig</tt>,
<tt>make config</tt>, <tt>make menuconfig</tt>, etc) is completed, the build
may be started using <tt>make deb-pkg</tt> target as described above.
</sect>
<sect id="common-out-of-tree">
<heading>Building out-of-tree kernel modules</heading>
<p>
Some kernel modules are not included in the upstream or
Debian kernel source, but are provided as third-party source
packages. For some of the most popular out-of-tree modules,
the binary Debian packages with modules built against the
stock Debian kernels are provided. For example, if you are
running stock Debian kernel <tt>3.2.0-2-686-pae</tt> (use the
<tt>uname -r</tt> command to verify the version) from the
<tt>linux-image-3.2.0-2-686-pae</tt> package, and would like to
use the squash filesystem, all you need to do is install
<tt>squashfs-modules-3.2.0-2-686-pae</tt> binary package, which
provides the neccessary binary kernel modules.
</p>
<p>
If you are not so lucky, and there are no binary module
packages in the archive, there is a fair chance that the
Debian archive contains the packaged <strong>source</strong>
for the kernel modules. Names of such packages typically end
in <tt>-source</tt>, for example <tt>squashfs-source</tt>,
<tt>thinkpad-source</tt>, <tt>rt2x00-source</tt> and many
others. These packages contain debianized source code of the
kernel modules, suitable for building using the
<tt>module-assistant</tt> (or <tt>m-a</tt>) script from the
<tt>module-assistant</tt> package. Typical sequence to
build a custom binary module package, matching a kernel
<tt>3.2.0-2-686-pae</tt> (as returned by <tt>uname -r</tt>)
from the debianized source consists of the following steps:
</p>
<p>
Install a set of kernel headers, matching the kernel for
which the modules are going to be built:
<example>
# apt-get install linux-headers-3.2.0-2-686-pae
</example>
Install the package containing the source:
<example>
# apt-get install squashfs-source
</example>
Invoke <tt>module-assistant</tt> (aka <tt>m-a</tt>) to do
the heavy lifting:
<example>
# m-a build squashfs
</example>
As a result, a Debian package is going to be built and placed
in <tt>/usr/src</tt>. It can be installed the usual way, using
<tt>dpkg -i</tt>. Two last steps (building and installation)
may be combined using the invocation
<example>
# m-a auto-install squashfs
</example>
Check out the <tt>module-assistant</tt> documentation (<tt>man module-assistant</tt>)
for other options and much more information on how to use it.
</p>
<p>
Finally, in some rare circumstances, you might need to build the kernel modules
from the upstream source packages. In that case, follow the documentation included
with the package to build the modules. If the build process will
require you to specify the directory with the kernel headers,
matching the currently running kernel, for stock Debian kernels this directory is
<tt>/usr/src/linux-headers-<em>uname</em></tt>, provided by the
<tt>linux-headers-<em>uname</em></tt> package. Here <tt><em>uname</em></tt> is the
output of the <tt>uname -r</tt> command. If you are building and running your own
custom kernels, it is a good idea to keep the original build tree around, as it
also can be used for out-of-tree module building.
</p>
</sect>
</chapt>
|
