Linux kernel mirror (for testing)
git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
kernel
os
linux
docs: describe how to quickly build a trimmed kernel
Add a text explaining how to quickly build a kernel, as that's something
users will often have to do when they want to report an issue or test
proposed fixes. This is a huge and frightening task for quite a few
users these days, as many rely on pre-compiled kernels and have never
built their own. They find help on quite a few websites explaining the
process in various ways, but those howtos often omit important details
or make things too hard for the 'quickly build just for testing' case
that 'localmodconfig' is really useful for. Hence give users something
at hand to guide them, as that makes it easier for them to help with
testing, debugging, and fixing the kernel.
To keep the complexity at bay, the document explicitly focuses on how to
compile the kernel on commodity distributions running on commodity
hardware. People that deal with less common distributions or hardware
will often know their way around already anyway.
The text describes a few oddities of Arch and Debian that were found by
the author and a few volunteers that tested the described procedure.
There are likely more such quirks that need to be covered as well as a
few things the author will have missed -- but one has to start
somewhere.
The document heavily uses anchors and links to them, which makes things
slightly harder to read in the source form. But the intended target
audience is way more likely to read rendered versions of this text on
pages like docs.kernel.org anyway -- and there those anchors and links
allow easy jumps to the reference section and back, which makes the
document a lot easier to work with for the intended target audience.
Aspects relevant for bisection were left out on purpose, as that is a
related, but in the end different use case. The rough plan is to have a
second document with a similar style to cover bisection. The idea is to
reuse a few bits from this document and link quite often to entries in
the reference section with the help of the anchors in this text.
Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Reviewed-by: Greg Kroah-Hartman <gregkh@linuxfoundation.org>
Link: https://lore.kernel.org/r/1a788a8e7ba8a2063df08668f565efa832016032.1678021408.git.linux@leemhuis.info
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
authored by
Thorsten Leemhuis
and committed by
Jonathan Corbet
efe92046
775a445d
+1094
+1
Documentation/admin-guide/index.rst
+1
Documentation/admin-guide/index.rst
+1092
Documentation/admin-guide/quickly-build-trimmed-linux.rst
+1092
Documentation/admin-guide/quickly-build-trimmed-linux.rst
···
1
+
.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
2
+
.. [see the bottom of this file for redistribution information]
3
+
4
+
===========================================
5
+
How to quickly build a trimmed Linux kernel
6
+
===========================================
7
+
8
+
This guide explains how to swiftly build Linux kernels that are ideal for
9
+
testing purposes, but perfectly fine for day-to-day use, too.
10
+
11
+
The essence of the process (aka 'TL;DR')
12
+
========================================
13
+
14
+
*[If you are new to compiling Linux, ignore this TLDR and head over to the next
15
+
section below: it contains a step-by-step guide, which is more detailed, but
16
+
still brief and easy to follow; that guide and its accompanying reference
17
+
section also mention alternatives, pitfalls, and additional aspects, all of
18
+
which might be relevant for you.]*
19
+
20
+
If your system uses techniques like Secure Boot, prepare it to permit starting
21
+
self-compiled Linux kernels; install compilers and everything else needed for
22
+
building Linux; make sure to have 12 Gigabyte free space in your home directory.
23
+
Now run the following commands to download fresh Linux mainline sources, which
24
+
you then use to configure, build and install your own kernel::
25
+
26
+
git clone --depth 1 -b master \
27
+
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
28
+
cd ~/linux/
29
+
# Hint: if you want to apply patches, do it at this point. See below for details.
30
+
# Hint: it's recommended to tag your build at this point. See below for details.
31
+
yes "" | make localmodconfig
32
+
# Hint: at this point you might want to adjust the build configuration; you'll
33
+
# have to, if you are running Debian. See below for details.
34
+
make -j $(nproc --all)
35
+
# Note: on many commodity distributions the next command suffices, but on Arch
36
+
# Linux, its derivatives, and some others it does not. See below for details.
37
+
command -v installkernel && sudo make modules_install install
38
+
reboot
39
+
40
+
If you later want to build a newer mainline snapshot, use these commands::
41
+
42
+
cd ~/linux/
43
+
git fetch --depth 1 origin
44
+
# Note: the next command will discard any changes you did to the code:
45
+
git checkout --force --detach origin/master
46
+
# Reminder: if you want to (re)apply patches, do it at this point.
47
+
# Reminder: you might want to add or modify a build tag at this point.
48
+
make olddefconfig
49
+
make -j $(nproc --all)
50
+
# Reminder: the next command on some distributions does not suffice.
51
+
command -v installkernel && sudo make modules_install install
52
+
reboot
53
+
54
+
Step-by-step guide
55
+
==================
56
+
57
+
Compiling your own Linux kernel is easy in principle. There are various ways to
58
+
do it. Which of them actually work and is the best depends on the circumstances.
59
+
60
+
This guide describes a way perfectly suited for those who want to quickly
61
+
install Linux from sources without being bothered by complicated details; the
62
+
goal is to cover everything typically needed on mainstream Linux distributions
63
+
running on commodity PC or server hardware.
64
+
65
+
The described approach is great for testing purposes, for example to try a
66
+
proposed fix or to check if a problem was already fixed in the latest codebase.
67
+
Nonetheless, kernels built this way are also totally fine for day-to-day use
68
+
while at the same time being easy to keep up to date.
69
+
70
+
The following steps describe the important aspects of the process; a
71
+
comprehensive reference section later explains each of them in more detail. It
72
+
sometimes also describes alternative approaches, pitfalls, as well as errors
73
+
that might occur at a particular point -- and how to then get things rolling
74
+
again.
75
+
76
+
..
77
+
Note: if you see this note, you are reading the text's source file. You
78
+
might want to switch to a rendered version, as it makes it a lot easier to
79
+
quickly look something up in the reference section and afterwards jump back
80
+
to where you left off. Find a the latest rendered version here:
81
+
https://docs.kernel.org/admin-guide/quickly-build-trimmed-linux.html
82
+
83
+
.. _backup_sbs:
84
+
85
+
* Create a fresh backup and put system repair and restore tools at hand, just
86
+
to be prepared for the unlikely case of something going sideways.
87
+
88
+
[:ref:`details<backup>`]
89
+
90
+
.. _secureboot_sbs:
91
+
92
+
* On platforms with 'Secure Boot' or similar techniques, prepare everything to
93
+
ensure the system will permit your self-compiled kernel to boot later. The
94
+
quickest and easiest way to achieve this on commodity x86 systems is to
95
+
disable such techniques in the BIOS setup utility; alternatively, remove
96
+
their restrictions through a process initiated by
97
+
``mokutil --disable-validation``.
98
+
99
+
[:ref:`details<secureboot>`]
100
+
101
+
.. _buildrequires_sbs:
102
+
103
+
* Install all software required to build a Linux kernel. Often you will need:
104
+
'bc', 'binutils' ('ld' et al.), 'bison', 'flex', 'gcc', 'git', 'openssl',
105
+
'pahole', 'perl', and the development headers for 'libelf' and 'openssl'. The
106
+
reference section shows how to quickly install those on various popular Linux
107
+
distributions.
108
+
109
+
[:ref:`details<buildrequires>`]
110
+
111
+
.. _diskspace_sbs:
112
+
113
+
* Ensure to have enough free space for building and installing Linux. For the
114
+
latter 150 Megabyte in /lib/ and 100 in /boot/ are a safe bet. For storing
115
+
sources and build artifacts 12 Gigabyte in your home directory should
116
+
typically suffice. If you have less available, be sure to check the reference
117
+
section for the step that explains adjusting your kernels build
118
+
configuration: it mentions a trick that reduce the amount of required space
119
+
in /home/ to around 4 Gigabyte.
120
+
121
+
[:ref:`details<diskspace>`]
122
+
123
+
.. _sources_sbs:
124
+
125
+
* Retrieve the sources of the Linux version you intend to build; then change
126
+
into the directory holding them, as all further commands in this guide are
127
+
meant to be executed from there.
128
+
129
+
*[Note: the following paragraphs describe how to retrieve the sources by
130
+
partially cloning the Linux stable git repository. This is called a shallow
131
+
clone. The reference section explains two alternatives:* :ref:`packaged
132
+
archives<sources_archive>` *and* :ref:`a full git clone<sources_full>` *;
133
+
prefer the latter, if downloading a lot of data does not bother you, as that
134
+
will avoid some* :ref:`peculiar characteristics of shallow clones the
135
+
reference section explains<sources_shallow>` *.]*
136
+
137
+
First, execute the following command to retrieve a fresh mainline codebase::
138
+
139
+
git clone --no-checkout --depth 1 -b master \
140
+
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
141
+
cd ~/linux/
142
+
143
+
If you want to access recent mainline releases and pre-releases, deepen you
144
+
clone's history to the oldest mainline version you are interested in::
145
+
146
+
git fetch --shallow-exclude=v6.0 origin
147
+
148
+
In case you want to access a stable/longterm release (say v6.1.5), simply add
149
+
the branch holding that series; afterwards fetch the history at least up to
150
+
the mainline version that started the series (v6.1)::
151
+
152
+
git remote set-branches --add origin linux-6.1.y
153
+
git fetch --shallow-exclude=v6.0 origin
154
+
155
+
Now checkout the code you are interested in. If you just performed the
156
+
initial clone, you will be able to check out a fresh mainline codebase, which
157
+
is ideal for checking whether developers already fixed an issue::
158
+
159
+
git checkout --detach origin/master
160
+
161
+
If you deepened your clone, you instead of ``origin/master`` can specify the
162
+
version you deepened to (``v6.0`` above); later releases like ``v6.1`` and
163
+
pre-release like ``v6.2-rc1`` will work, too. Stable or longterm versions
164
+
like ``v6.1.5`` work just the same, if you added the appropriate
165
+
stable/longterm branch as described.
166
+
167
+
[:ref:`details<sources>`]
168
+
169
+
.. _patching_sbs:
170
+
171
+
* In case you want to apply a kernel patch, do so now. Often a command like
172
+
this will do the trick::
173
+
174
+
patch -p1 < ../proposed-fix.patch
175
+
176
+
If the ``-p1`` is actually needed, depends on how the patch was created; in
177
+
case it does not apply thus try without it.
178
+
179
+
If you cloned the sources with git and anything goes sideways, run ``git
180
+
reset --hard`` to undo any changes to the sources.
181
+
182
+
[:ref:`details<patching>`]
183
+
184
+
.. _tagging_sbs:
185
+
186
+
* If you patched your kernel or have one of the same version installed already,
187
+
better add a unique tag to the one you are about to build::
188
+
189
+
echo "-proposed_fix" > localversion
190
+
191
+
Running ``uname -r`` under your kernel later will then print something like
192
+
'6.1-rc4-proposed_fix'.
193
+
194
+
[:ref:`details<tagging>`]
195
+
196
+
.. _configuration_sbs:
197
+
198
+
* Create the build configuration for your kernel based on an existing
199
+
configuration.
200
+
201
+
If you already prepared such a '.config' file yourself, copy it to
202
+
~/linux/ and run ``make olddefconfig``.
203
+
204
+
Use the same command, if your distribution or somebody else already tailored
205
+
your running kernel to your or your hardware's needs: the make target
206
+
'olddefconfig' will then try to use that kernel's .config as base.
207
+
208
+
Using this make target is fine for everybody else, too -- but you often can
209
+
save a lot of time by using this command instead::
210
+
211
+
yes "" | make localmodconfig
212
+
213
+
This will try to pick your distribution's kernel as base, but then disable
214
+
modules for any features apparently superfluous for your setup. This will
215
+
reduce the compile time enormously, especially if you are running an
216
+
universal kernel from a commodity Linux distribution.
217
+
218
+
There is a catch: the make target 'localmodconfig' will disable kernel
219
+
features you have not directly or indirectly through some program utilized
220
+
since you booted the system. You can reduce or nearly eliminate that risk by
221
+
using tricks outlined in the reference section; for quick testing purposes
222
+
that risk is often negligible, but it is an aspect you want to keep in mind
223
+
in case your kernel behaves oddly.
224
+
225
+
[:ref:`details<configuration>`]
226
+
227
+
.. _configmods_sbs:
228
+
229
+
* Check if you might want to or have to adjust some kernel configuration
230
+
options:
231
+
232
+
* Evaluate how you want to handle debug symbols. Enable them, if you later
233
+
might need to decode a stack trace found for example in a 'panic', 'Oops',
234
+
'warning', or 'BUG'; on the other hand disable them, if you are short on
235
+
storage space or prefer a smaller kernel binary. See the reference section
236
+
for details on how to do either. If neither applies, it will likely be fine
237
+
to simply not bother with this. [:ref:`details<configmods_debugsymbols>`]
238
+
239
+
* Are you running Debian? Then to avoid known problems by performing
240
+
additional adjustments explained in the reference section.
241
+
[:ref:`details<configmods_distros>`].
242
+
243
+
* If you want to influence the other aspects of the configuration, do so now
244
+
by using make targets like 'menuconfig' or 'xconfig'.
245
+
[:ref:`details<configmods_individual>`].
246
+
247
+
.. _build_sbs:
248
+
249
+
* Build the image and the modules of your kernel::
250
+
251
+
make -j $(nproc --all)
252
+
253
+
If you want your kernel packaged up as deb, rpm, or tar file, see the
254
+
reference section for alternatives.
255
+
256
+
[:ref:`details<build>`]
257
+
258
+
.. _install_sbs:
259
+
260
+
* Now install your kernel::
261
+
262
+
command -v installkernel && sudo make modules_install install
263
+
264
+
Often all left for you to do afterwards is a ``reboot``, as many commodity
265
+
Linux distributions will then create an initramfs (also known as initrd) and
266
+
an entry for your kernel in your bootloader's configuration; but on some
267
+
distributions you have to take care of these two steps manually for reasons
268
+
the reference section explains.
269
+
270
+
On a few distributions like Arch Linux and its derivatives the above command
271
+
does nothing at all; in that case you have to manually install your kernel,
272
+
as outlined in the reference section.
273
+
274
+
[:ref:`details<install>`]
275
+
276
+
.. _another_sbs:
277
+
278
+
* To later build another kernel you need similar steps, but sometimes slightly
279
+
different commands.
280
+
281
+
First, switch back into the sources tree::
282
+
283
+
cd ~/linux/
284
+
285
+
In case you want to build a version from a stable/longterm series you have
286
+
not used yet (say 6.2.y), tell git to track it::
287
+
288
+
git remote set-branches --add origin linux-6.2.y
289
+
290
+
Now fetch the latest upstream changes; you again need to specify the earliest
291
+
version you care about, as git otherwise might retrieve the entire commit
292
+
history::
293
+
294
+
git fetch --shallow-exclude=v6.1 origin
295
+
296
+
If you modified the sources (for example by applying a patch), you now need
297
+
to discard those modifications; that's because git otherwise will not be able
298
+
to switch to the sources of another version due to potential conflicting
299
+
changes::
300
+
301
+
git reset --hard
302
+
303
+
Now checkout the version you are interested in, as explained above::
304
+
305
+
git checkout --detach origin/master
306
+
307
+
At this point you might want to patch the sources again or set/modify a build
308
+
tag, as explained earlier; afterwards adjust the build configuration to the
309
+
new codebase and build your next kernel::
310
+
311
+
# reminder: if you want to apply patches, do it at this point
312
+
# reminder: you might want to update your build tag at this point
313
+
make olddefconfig
314
+
make -j $(nproc --all)
315
+
316
+
Install the kernel as outlined above::
317
+
318
+
command -v installkernel && sudo make modules_install install
319
+
320
+
[:ref:`details<another>`]
321
+
322
+
.. _uninstall_sbs:
323
+
324
+
* Your kernel is easy to remove later, as its parts are only stored in two
325
+
places and clearly identifiable by the kernel's release name. Just ensure to
326
+
not delete the kernel you are running, as that might render your system
327
+
unbootable.
328
+
329
+
Start by deleting the directory holding your kernel's modules, which is named
330
+
after its release name -- '6.0.1-foobar' in the following example::
331
+
332
+
sudo rm -rf /lib/modules/6.0.1-foobar
333
+
334
+
Now try the following command, which on some distributions will delete all
335
+
other kernel files installed while also removing the kernel's entry from the
336
+
bootloader configuration::
337
+
338
+
command -v kernel-install && sudo kernel-install -v remove 6.0.1-foobar
339
+
340
+
If that command does not output anything or fails, see the reference section;
341
+
do the same if any files named '*6.0.1-foobar*' remain in /boot/.
342
+
343
+
[:ref:`details<uninstall>`]
344
+
345
+
.. _submit_improvements:
346
+
347
+
Did you run into trouble following any of the above steps that is not cleared up
348
+
by the reference section below? Or do you have ideas how to improve the text?
349
+
Then please take a moment of your time and let the maintainer of this document
350
+
know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the
351
+
Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
352
+
improve this document further, which is in everybody's interest, as it will
353
+
enable more people to master the task described here.
354
+
355
+
Reference section for the step-by-step guide
356
+
============================================
357
+
358
+
This section holds additional information for each of the steps in the above
359
+
guide.
360
+
361
+
.. _backup:
362
+
363
+
Prepare for emergencies
364
+
-----------------------
365
+
366
+
*Create a fresh backup and put system repair and restore tools at hand*
367
+
[:ref:`... <backup_sbs>`]
368
+
369
+
Remember, you are dealing with computers, which sometimes do unexpected things
370
+
-- especially if you fiddle with crucial parts like the kernel of an operating
371
+
system. That's what you are about to do in this process. Hence, better prepare
372
+
for something going sideways, even if that should not happen.
373
+
374
+
[:ref:`back to step-by-step guide <backup_sbs>`]
375
+
376
+
.. _secureboot:
377
+
378
+
Dealing with techniques like Secure Boot
379
+
----------------------------------------
380
+
381
+
*On platforms with 'Secure Boot' or similar techniques, prepare everything to
382
+
ensure the system will permit your self-compiled kernel to boot later.*
383
+
[:ref:`... <secureboot_sbs>`]
384
+
385
+
Many modern systems allow only certain operating systems to start; they thus by
386
+
default will reject booting self-compiled kernels.
387
+
388
+
You ideally deal with this by making your platform trust your self-built kernels
389
+
with the help of a certificate and signing. How to do that is not described
390
+
here, as it requires various steps that would take the text too far away from
391
+
its purpose; 'Documentation/admin-guide/module-signing.rst' and various web
392
+
sides already explain this in more detail.
393
+
394
+
Temporarily disabling solutions like Secure Boot is another way to make your own
395
+
Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup
396
+
utility; the steps to do so are not described here, as they greatly vary between
397
+
machines.
398
+
399
+
On mainstream x86 Linux distributions there is a third and universal option:
400
+
disable all Secure Boot restrictions for your Linux environment. You can
401
+
initiate this process by running ``mokutil --disable-validation``; this will
402
+
tell you to create a one-time password, which is safe to write down. Now
403
+
restart; right after your BIOS performed all self-tests the bootloader Shim will
404
+
show a blue box with a message 'Press any key to perform MOK management'. Hit
405
+
some key before the countdown exposes. This will open a menu and choose 'Change
406
+
Secure Boot state' there. Shim's 'MokManager' will now ask you to enter three
407
+
randomly chosen characters from the one-time password specified earlier. Once
408
+
you provided them, confirm that you really want to disable the validation.
409
+
Afterwards, permit MokManager to reboot the machine.
410
+
411
+
[:ref:`back to step-by-step guide <secureboot_sbs>`]
412
+
413
+
.. _buildrequires:
414
+
415
+
Install build requirements
416
+
--------------------------
417
+
418
+
*Install all software required to build a Linux kernel.*
419
+
[:ref:`...<buildrequires_sbs>`]
420
+
421
+
The kernel is pretty stand-alone, but besides tools like the compiler you will
422
+
sometimes need a few libraries to build one. How to install everything needed
423
+
depends on your Linux distribution and the configuration of the kernel you are
424
+
about to build.
425
+
426
+
Here are a few examples what you typically need on some mainstream
427
+
distributions:
428
+
429
+
* Debian, Ubuntu, and derivatives::
430
+
431
+
sudo apt install bc binutils bison dwarves flex gcc git make openssl \
432
+
pahole perl-base libssl-dev libelf-dev
433
+
434
+
* Fedora and derivatives::
435
+
436
+
sudo dnf install binutils /usr/include/{libelf.h,openssl/pkcs7.h} \
437
+
/usr/bin/{bc,bison,flex,gcc,git,openssl,make,perl,pahole}
438
+
439
+
* openSUSE and derivatives::
440
+
441
+
sudo zypper install bc binutils bison dwarves flex gcc git make perl-base \
442
+
openssl openssl-devel libelf-dev
443
+
444
+
In case you wonder why these lists include openssl and its development headers:
445
+
they are needed for the Secure Boot support, which many distributions enable in
446
+
their kernel configuration for x86 machines.
447
+
448
+
Sometimes you will need tools for compression formats like bzip2, gzip, lz4,
449
+
lzma, lzo, xz, or zstd as well.
450
+
451
+
You might need additional libraries and their development headers in case you
452
+
perform tasks not covered in this guide. For example, zlib will be needed when
453
+
building kernel tools from the tools/ directory; adjusting the build
454
+
configuration with make targets like 'menuconfig' or 'xconfig' will require
455
+
development headers for ncurses or Qt5.
456
+
457
+
[:ref:`back to step-by-step guide <buildrequires_sbs>`]
458
+
459
+
.. _diskspace:
460
+
461
+
Space requirements
462
+
------------------
463
+
464
+
*Ensure to have enough free space for building and installing Linux.*
465
+
[:ref:`... <diskspace_sbs>`]
466
+
467
+
The numbers mentioned are rough estimates with a big extra charge to be on the
468
+
safe side, so often you will need less.
469
+
470
+
If you have space constraints, remember to read the reference section when you
471
+
reach the :ref:`section about configuration adjustments' <configmods>`, as
472
+
ensuring debug symbols are disabled will reduce the consumed disk space by quite
473
+
a few gigabytes.
474
+
475
+
[:ref:`back to step-by-step guide <diskspace_sbs>`]
476
+
477
+
478
+
.. _sources:
479
+
480
+
Download the sources
481
+
--------------------
482
+
483
+
*Retrieve the sources of the Linux version you intend to build.*
484
+
[:ref:`...<sources_sbs>`]
485
+
486
+
The step-by-step guide outlines how to retrieve Linux' sources using a shallow
487
+
git clone. There is :ref:`more to tell about this method<sources_shallow>` and
488
+
two alternate ways worth describing: :ref:`packaged archives<sources_archive>`
489
+
and :ref:`a full git clone<sources_full>`. And the aspects ':ref:`wouldn't it
490
+
be wiser to use a proper pre-release than the latest mainline code
491
+
<sources_snapshot>`' and ':ref:`how to get an even fresher mainline codebase
492
+
<sources_fresher>`' need elaboration, too.
493
+
494
+
Note, to keep things simple the commands used in this guide store the build
495
+
artifacts in the source tree. If you prefer to separate them, simply add
496
+
something like ``O=~/linux-builddir/`` to all make calls; also adjust the path
497
+
in all commands that add files or modify any generated (like your '.config').
498
+
499
+
[:ref:`back to step-by-step guide <sources_sbs>`]
500
+
501
+
.. _sources_shallow:
502
+
503
+
Noteworthy characteristics of shallow clones
504
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
505
+
506
+
The step-by-step guide uses a shallow clone, as it is the best solution for most
507
+
of this document's target audience. There are a few aspects of this approach
508
+
worth mentioning:
509
+
510
+
* This document in most places uses ``git fetch`` with ``--shallow-exclude=``
511
+
to specify the earliest version you care about (or to be precise: its git
512
+
tag). You alternatively can use the parameter ``--shallow-since=`` to specify
513
+
an absolute (say ``'2023-07-15'``) or relative (``'12 months'``) date to
514
+
define the depth of the history you want to download. As a second
515
+
alternative, you can also specify a certain depth explicitly with a parameter
516
+
like ``--depth=1``, unless you add branches for stable/longterm kernels.
517
+
518
+
* When running ``git fetch``, remember to always specify the oldest version,
519
+
the time you care about, or an explicit depth as shown in the step-by-step
520
+
guide. Otherwise you will risk downloading nearly the entire git history,
521
+
which will consume quite a bit of time and bandwidth while also stressing the
522
+
servers.
523
+
524
+
Note, you do not have to use the same version or date all the time. But when
525
+
you change it over time, git will deepen or flatten the history to the
526
+
specified point. That allows you to retrieve versions you initially thought
527
+
you did not need -- or it will discard the sources of older versions, for
528
+
example in case you want to free up some disk space. The latter will happen
529
+
automatically when using ``--shallow-since=`` or
530
+
``--depth=``.
531
+
532
+
* Be warned, when deepening your clone you might encounter an error like
533
+
'fatal: error in object: unshallow cafecaca0c0dacafecaca0c0dacafecaca0c0da'.
534
+
In that case run ``git repack -d`` and try again``
535
+
536
+
* In case you want to revert changes from a certain version (say Linux 6.3) or
537
+
perform a bisection (v6.2..v6.3), better tell ``git fetch`` to retrieve
538
+
objects up to three versions earlier (e.g. 6.0): ``git describe`` will then
539
+
be able to describe most commits just like it would in a full git clone.
540
+
541
+
[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
542
+
543
+
.. _sources_archive:
544
+
545
+
Downloading the sources using a packages archive
546
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
547
+
548
+
People new to compiling Linux often assume downloading an archive via the
549
+
front-page of https://kernel.org is the best approach to retrieve Linux'
550
+
sources. It actually can be, if you are certain to build just one particular
551
+
kernel version without changing any code. Thing is: you might be sure this will
552
+
be the case, but in practice it often will turn out to be a wrong assumption.
553
+
554
+
That's because when reporting or debugging an issue developers will often ask to
555
+
give another version a try. They also might suggest temporarily undoing a commit
556
+
with ``git revert`` or might provide various patches to try. Sometimes reporters
557
+
will also be asked to use ``git bisect`` to find the change causing a problem.
558
+
These things rely on git or are a lot easier and quicker to handle with it.
559
+
560
+
A shallow clone also does not add any significant overhead. For example, when
561
+
you use ``git clone --depth=1`` to create a shallow clone of the latest mainline
562
+
codebase git will only retrieve a little more data than downloading the latest
563
+
mainline pre-release (aka 'rc') via the front-page of kernel.org would.
564
+
565
+
A shallow clone therefore is often the better choice. If you nevertheless want
566
+
to use a packaged source archive, download one via kernel.org; afterwards
567
+
extract its content to some directory and change to the subdirectory created
568
+
during extraction. The rest of the step-by-step guide will work just fine, apart
569
+
from things that rely on git -- but this mainly concerns the section on
570
+
successive builds of other versions.
571
+
572
+
[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
573
+
574
+
.. _sources_full:
575
+
576
+
Downloading the sources using a full git clone
577
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578
+
579
+
If downloading and storing a lot of data (~4,4 Gigabyte as of early 2023) is
580
+
nothing that bothers you, instead of a shallow clone perform a full git clone
581
+
instead. You then will avoid the specialties mentioned above and will have all
582
+
versions and individual commits at hand at any time::
583
+
584
+
curl -L \
585
+
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git/clone.bundle \
586
+
-o linux-stable.git.bundle
587
+
git clone clone.bundle ~/linux/
588
+
rm linux-stable.git.bundle
589
+
cd ~/linux/
590
+
git remote set-url origin
591
+
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
592
+
git fetch origin
593
+
git checkout --detach origin/master
594
+
595
+
[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
596
+
597
+
.. _sources_snapshot:
598
+
599
+
Proper pre-releases (RCs) vs. latest mainline
600
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
601
+
602
+
When cloning the sources using git and checking out origin/master, you often
603
+
will retrieve a codebase that is somewhere between the latest and the next
604
+
release or pre-release. This almost always is the code you want when giving
605
+
mainline a shot: pre-releases like v6.1-rc5 are in no way special, as they do
606
+
not get any significant extra testing before being published.
607
+
608
+
There is one exception: you might want to stick to the latest mainline release
609
+
(say v6.1) before its successor's first pre-release (v6.2-rc1) is out. That is
610
+
because compiler errors and other problems are more likely to occur during this
611
+
time, as mainline then is in its 'merge window': a usually two week long phase,
612
+
in which the bulk of the changes for the next release is merged.
613
+
614
+
[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
615
+
616
+
.. _sources_fresher:
617
+
618
+
Avoiding the mainline lag
619
+
~~~~~~~~~~~~~~~~~~~~~~~~~
620
+
621
+
The explanations for both the shallow clone and the full clone both retrieve the
622
+
code from the Linux stable git repository. That makes things simpler for this
623
+
document's audience, as it allows easy access to both mainline and
624
+
stable/longterm releases. This approach has just one downside:
625
+
626
+
Changes merged into the mainline repository are only synced to the master branch
627
+
of the Linux stable repository every few hours. This lag most of the time is
628
+
not something to worry about; but in case you really need the latest code, just
629
+
add the mainline repo as additional remote and checkout the code from there::
630
+
631
+
git remote add mainline \
632
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
633
+
git fetch mainline
634
+
git checkout --detach mainline/master
635
+
636
+
When doing this with a shallow clone, remember to call ``git fetch`` with one
637
+
of the parameters described earlier to limit the depth.
638
+
639
+
[:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
640
+
641
+
.. _patching:
642
+
643
+
Patch the sources (optional)
644
+
----------------------------
645
+
646
+
*In case you want to apply a kernel patch, do so now.*
647
+
[:ref:`...<patching_sbs>`]
648
+
649
+
This is the point where you might want to patch your kernel -- for example when
650
+
a developer proposed a fix and asked you to check if it helps. The step-by-step
651
+
guide already explains everything crucial here.
652
+
653
+
[:ref:`back to step-by-step guide <patching_sbs>`]
654
+
655
+
.. _tagging:
656
+
657
+
Tagging this kernel build (optional, often wise)
658
+
------------------------------------------------
659
+
660
+
*If you patched your kernel or already have that kernel version installed,
661
+
better tag your kernel by extending its release name:*
662
+
[:ref:`...<tagging_sbs>`]
663
+
664
+
Tagging your kernel will help avoid confusion later, especially when you patched
665
+
your kernel. Adding an individual tag will also ensure the kernel's image and
666
+
its modules are installed in parallel to any existing kernels.
667
+
668
+
There are various ways to add such a tag. The step-by-step guide realizes one by
669
+
creating a 'localversion' file in your build directory from which the kernel
670
+
build scripts will automatically pick up the tag. You can later change that file
671
+
to use a different tag in subsequent builds or simply remove that file to dump
672
+
the tag.
673
+
674
+
[:ref:`back to step-by-step guide <tagging_sbs>`]
675
+
676
+
.. _configuration:
677
+
678
+
Define the build configuration for your kernel
679
+
----------------------------------------------
680
+
681
+
*Create the build configuration for your kernel based on an existing
682
+
configuration.* [:ref:`... <configuration_sbs>`]
683
+
684
+
There are various aspects for this steps that require a more careful
685
+
explanation:
686
+
687
+
Pitfalls when using another configuration file as base
688
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
689
+
690
+
Make targets like localmodconfig and olddefconfig share a few common snares you
691
+
want to be aware of:
692
+
693
+
* These targets will reuse a kernel build configuration in your build directory
694
+
(e.g. '~/linux/.config'), if one exists. In case you want to start from
695
+
scratch you thus need to delete it.
696
+
697
+
* The make targets try to find the configuration for your running kernel
698
+
automatically, but might choose poorly. A line like '# using defaults found
699
+
in /boot/config-6.0.7-250.fc36.x86_64' or 'using config:
700
+
'/boot/config-6.0.7-250.fc36.x86_64' tells you which file they picked. If
701
+
that is not the intended one, simply store it as '~/linux/.config'
702
+
before using these make targets.
703
+
704
+
* Unexpected things might happen if you try to use a config file prepared for
705
+
one kernel (say v6.0) on an older generation (say v5.15). In that case you
706
+
might want to use a configuration as base which your distribution utilized
707
+
when they used that or an slightly older kernel version.
708
+
709
+
Influencing the configuration
710
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
711
+
712
+
The make target olddefconfig and the ``yes "" |`` used when utilizing
713
+
localmodconfig will set any undefined build options to their default value. This
714
+
among others will disable many kernel features that were introduced after your
715
+
base kernel was released.
716
+
717
+
If you want to set these configurations options manually, use ``oldconfig``
718
+
instead of ``olddefconfig`` or omit the ``yes "" |`` when utilizing
719
+
localmodconfig. Then for each undefined configuration option you will be asked
720
+
how to proceed. In case you are unsure what to answer, simply hit 'enter' to
721
+
apply the default value.
722
+
723
+
Big pitfall when using localmodconfig
724
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
725
+
726
+
As explained briefly in the step-by-step guide already: with localmodconfig it
727
+
can easily happen that your self-built kernel will lack modules for tasks you
728
+
did not perform before utilizing this make target. That's because those tasks
729
+
require kernel modules that are normally autoloaded when you perform that task
730
+
for the first time; if you didn't perform that task at least once before using
731
+
localmodonfig, the latter will thus assume these modules are superfluous and
732
+
disable them.
733
+
734
+
You can try to avoid this by performing typical tasks that often will autoload
735
+
additional kernel modules: start a VM, establish VPN connections, loop-mount a
736
+
CD/DVD ISO, mount network shares (CIFS, NFS, ...), and connect all external
737
+
devices (2FA keys, headsets, webcams, ...) as well as storage devices with file
738
+
systems you otherwise do not utilize (btrfs, ext4, FAT, NTFS, XFS, ...). But it
739
+
is hard to think of everything that might be needed -- even kernel developers
740
+
often forget one thing or another at this point.
741
+
742
+
Do not let that risk bother you, especially when compiling a kernel only for
743
+
testing purposes: everything typically crucial will be there. And if you forget
744
+
something important you can turn on a missing feature later and quickly run the
745
+
commands to compile and install a better kernel.
746
+
747
+
But if you plan to build and use self-built kernels regularly, you might want to
748
+
reduce the risk by recording which modules your system loads over the course of
749
+
a few weeks. You can automate this with `modprobed-db
750
+
<https://github.com/graysky2/modprobed-db>`_. Afterwards use ``LSMOD=<path>`` to
751
+
point localmodconfig to the list of modules modprobed-db noticed being used::
752
+
753
+
yes "" | make LSMOD="${HOME}"/.config/modprobed.db localmodconfig
754
+
755
+
Remote building with localmodconfig
756
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
757
+
758
+
If you want to use localmodconfig to build a kernel for another machine, run
759
+
``lsmod > lsmod_foo-machine`` on it and transfer that file to your build host.
760
+
Now point the build scripts to the file like this: ``yes "" | make
761
+
LSMOD=~/lsmod_foo-machine localmodconfig``. Note, in this case
762
+
you likely want to copy a base kernel configuration from the other machine over
763
+
as well and place it as .config in your build directory.
764
+
765
+
[:ref:`back to step-by-step guide <configuration_sbs>`]
766
+
767
+
.. _configmods:
768
+
769
+
Adjust build configuration
770
+
--------------------------
771
+
772
+
*Check if you might want to or have to adjust some kernel configuration
773
+
options:*
774
+
775
+
Depending on your needs you at this point might want or have to adjust some
776
+
kernel configuration options.
777
+
778
+
.. _configmods_debugsymbols:
779
+
780
+
Debug symbols
781
+
~~~~~~~~~~~~~
782
+
783
+
*Evaluate how you want to handle debug symbols.*
784
+
[:ref:`...<configmods_sbs>`]
785
+
786
+
Most users do not need to care about this, it's often fine to leave everything
787
+
as it is; but you should take a closer look at this, if you might need to decode
788
+
a stack trace or want to reduce space consumption.
789
+
790
+
Having debug symbols available can be important when your kernel throws a
791
+
'panic', 'Oops', 'warning', or 'BUG' later when running, as then you will be
792
+
able to find the exact place where the problem occurred in the code. But
793
+
collecting and embedding the needed debug information takes time and consumes
794
+
quite a bit of space: in late 2022 the build artifacts for a typical x86 kernel
795
+
configured with localmodconfig consumed around 5 Gigabyte of space with debug
796
+
symbols, but less than 1 when they were disabled. The resulting kernel image and
797
+
the modules are bigger as well, which increases load times.
798
+
799
+
Hence, if you want a small kernel and are unlikely to decode a stack trace
800
+
later, you might want to disable debug symbols to avoid above downsides::
801
+
802
+
./scripts/config --file .config -d DEBUG_INFO \
803
+
-d DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -d DEBUG_INFO_DWARF4 \
804
+
-d DEBUG_INFO_DWARF5 -e CONFIG_DEBUG_INFO_NONE
805
+
make olddefconfig
806
+
807
+
You on the other hand definitely want to enable them, if there is a decent
808
+
chance that you need to decode a stack trace later (as explained by 'Decode
809
+
failure messages' in Documentation/admin-guide/tainted-kernels.rst in more
810
+
detail)::
811
+
812
+
./scripts/config --file .config -d DEBUG_INFO_NONE -e DEBUG_KERNEL
813
+
-e DEBUG_INFO -e DEBUG_INFO_DWARF_TOOLCHAIN_DEFAULT -e KALLSYMS -e KALLSYMS_ALL
814
+
make olddefconfig
815
+
816
+
Note, many mainstream distributions enable debug symbols in their kernel
817
+
configurations -- make targets like localmodconfig and olddefconfig thus will
818
+
often pick that setting up.
819
+
820
+
[:ref:`back to step-by-step guide <configmods_sbs>`]
821
+
822
+
.. _configmods_distros:
823
+
824
+
Distro specific adjustments
825
+
~~~~~~~~~~~~~~~~~~~~~~~~~~~
826
+
827
+
*Are you running* [:ref:`... <configmods_sbs>`]
828
+
829
+
The following sections help you to avoid build problems that are known to occur
830
+
when following this guide on a few commodity distributions.
831
+
832
+
**Debian:**
833
+
834
+
* Remove a stale reference to a certificate file that would cause your build to
835
+
fail::
836
+
837
+
./scripts/config --file .config --set-str SYSTEM_TRUSTED_KEYS ''
838
+
839
+
Alternatively, download the needed certificate and make that configuration
840
+
option point to it, as `the Debian handbook explains in more detail
841
+
<https://debian-handbook.info/browse/stable/sect.kernel-compilation.html>`_
842
+
-- or generate your own, as explained in
843
+
Documentation/admin-guide/module-signing.rst.
844
+
845
+
[:ref:`back to step-by-step guide <configmods_sbs>`]
846
+
847
+
.. _configmods_individual:
848
+
849
+
Individual adjustments
850
+
~~~~~~~~~~~~~~~~~~~~~~
851
+
852
+
*If you want to influence the other aspects of the configuration, do so
853
+
now* [:ref:`... <configmods_sbs>`]
854
+
855
+
You at this point can use a command like ``make menuconfig`` to enable or
856
+
disable certain features using a text-based user interface; to use a graphical
857
+
configuration utilize, use the make target ``xconfig`` or ``gconfig`` instead.
858
+
All of them require development libraries from toolkits they are based on
859
+
(ncurses, Qt5, Gtk2); an error message will tell you if something required is
860
+
missing.
861
+
862
+
[:ref:`back to step-by-step guide <configmods_sbs>`]
863
+
864
+
.. _build:
865
+
866
+
Build your kernel
867
+
-----------------
868
+
869
+
*Build the image and the modules of your kernel* [:ref:`... <build_sbs>`]
870
+
871
+
A lot can go wrong at this stage, but the instructions below will help you help
872
+
yourself. Another subsection explains how to directly package your kernel up as
873
+
deb, rpm or tar file.
874
+
875
+
Dealing with build errors
876
+
~~~~~~~~~~~~~~~~~~~~~~~~~
877
+
878
+
When a build error occurs, it might be caused by some aspect of your machine's
879
+
setup that often can be fixed quickly; other times though the problem lies in
880
+
the code and can only be fixed by a developer. A close examination of the
881
+
failure messages coupled with some research on the internet will often tell you
882
+
which of the two it is. To perform such a investigation, restart the build
883
+
process like this::
884
+
885
+
make V=1
886
+
887
+
The ``V=1`` activates verbose output, which might be needed to see the actual
888
+
error. To make it easier to spot, this command also omits the ``-j $(nproc
889
+
--all)`` used earlier to utilize every CPU core in the system for the job -- but
890
+
this parallelism also results in some clutter when failures occur.
891
+
892
+
After a few seconds the build process should run into the error again. Now try
893
+
to find the most crucial line describing the problem. Then search the internet
894
+
for the most important and non-generic section of that line (say 4 to 8 words);
895
+
avoid or remove anything that looks remotely system-specific, like your username
896
+
or local path names like ``/home/username/linux/``. First try your regular
897
+
internet search engine with that string, afterwards search Linux kernel mailing
898
+
lists via `lore.kernel.org/all/ <https://lore.kernel.org/all/>`_.
899
+
900
+
This most of the time will find something that will explain what is wrong; quite
901
+
often one of the hits will provide a solution for your problem, too. If you
902
+
do not find anything that matches your problem, try again from a different angle
903
+
by modifying your search terms or using another line from the error messages.
904
+
905
+
In the end, most trouble you are to run into has likely been encountered and
906
+
reported by others already. That includes issues where the cause is not your
907
+
system, but lies the code. If you run into one of those, you might thus find a
908
+
solution (e.g. a patch) or workaround for your problem, too.
909
+
910
+
Package your kernel up
911
+
~~~~~~~~~~~~~~~~~~~~~~
912
+
913
+
The step-by-step guide uses the default make targets (e.g. 'bzImage' and
914
+
'modules' on x86) to build the image and the modules of your kernel, which later
915
+
steps of the guide then install. You instead can also directly build everything
916
+
and directly package it up by using one of the following targets:
917
+
918
+
* ``make -j $(nproc --all) bindeb-pkg`` to generate a deb package
919
+
920
+
* ``make -j $(nproc --all) binrpm-pkg`` to generate a rpm package
921
+
922
+
* ``make -j $(nproc --all) tarbz2-pkg`` to generate a bz2 compressed tarball
923
+
924
+
This is just a selection of available make targets for this purpose, see
925
+
``make help`` for others. You can also use these targets after running
926
+
``make -j $(nproc --all)``, as they will pick up everything already built.
927
+
928
+
If you employ the targets to generate deb or rpm packages, ignore the
929
+
step-by-step guide's instructions on installing and removing your kernel;
930
+
instead install and remove the packages using the package utility for the format
931
+
(e.g. dpkg and rpm) or a package management utility build on top of them (apt,
932
+
aptitude, dnf/yum, zypper, ...). Be aware that the packages generated using
933
+
these two make targets are designed to work on various distributions utilizing
934
+
those formats, they thus will sometimes behave differently than your
935
+
distribution's kernel packages.
936
+
937
+
[:ref:`back to step-by-step guide <build_sbs>`]
938
+
939
+
.. _install:
940
+
941
+
Install your kernel
942
+
-------------------
943
+
944
+
*Now install your kernel* [:ref:`... <install_sbs>`]
945
+
946
+
What you need to do after executing the command in the step-by-step guide
947
+
depends on the existence and the implementation of an ``installkernel``
948
+
executable. Many commodity Linux distributions ship such a kernel installer in
949
+
``/sbin/`` that does everything needed, hence there is nothing left for you
950
+
except rebooting. But some distributions contain an installkernel that does
951
+
only part of the job -- and a few lack it completely and leave all the work to
952
+
you.
953
+
954
+
If ``installkernel`` is found, the kernel's build system will delegate the
955
+
actual installation of your kernel's image and related files to this executable.
956
+
On almost all Linux distributions it will store the image as '/boot/vmlinuz-
957
+
<your kernel's release name>' and put a 'System.map-<your kernel's release
958
+
name>' alongside it. Your kernel will thus be installed in parallel to any
959
+
existing ones, unless you already have one with exactly the same release name.
960
+
961
+
Installkernel on many distributions will afterwards generate an 'initramfs'
962
+
(often also called 'initrd'), which commodity distributions rely on for booting;
963
+
hence be sure to keep the order of the two make targets used in the step-by-step
964
+
guide, as things will go sideways if you install your kernel's image before its
965
+
modules. Often installkernel will then add your kernel to the bootloader
966
+
configuration, too. You have to take care of one or both of these tasks
967
+
yourself, if your distributions installkernel doesn't handle them.
968
+
969
+
A few distributions like Arch Linux and its derivatives totally lack an
970
+
installkernel executable. On those just install the modules using the kernel's
971
+
build system and then install the image and the System.map file manually::
972
+
973
+
sudo make modules_install
974
+
sudo install -m 0600 $(make -s image_name) /boot/vmlinuz-$(make -s kernelrelease)
975
+
sudo install -m 0600 System.map /boot/System.map-$(make -s kernelrelease)
976
+
977
+
If your distribution boots with the help of an initramfs, now generate one for
978
+
your kernel using the tools your distribution provides for this process.
979
+
Afterwards add your kernel to your bootloader configuration and reboot.
980
+
981
+
[:ref:`back to step-by-step guide <install_sbs>`]
982
+
983
+
.. _another:
984
+
985
+
Another round later
986
+
-------------------
987
+
988
+
*To later build another kernel you need similar, but sometimes slightly
989
+
different commands* [:ref:`... <another_sbs>`]
990
+
991
+
The process to build later kernels is similar, but at some points slightly
992
+
different. You for example do not want to use 'localmodconfig' for succeeding
993
+
kernel builds, as you already created a trimmed down configuration you want to
994
+
use from now on. Hence instead just use ``oldconfig`` or ``olddefconfig`` to
995
+
adjust your build configurations to the needs of the kernel version you are
996
+
about to build.
997
+
998
+
If you created a shallow-clone with git, remember what the :ref:`section that
999
+
explained the setup described in more detail <sources>`: you need to use a
1000
+
slightly different ``git fetch`` command and when switching to another series
1001
+
need to add an additional remote branch.
1002
+
1003
+
[:ref:`back to step-by-step guide <another_sbs>`]
1004
+
1005
+
.. _uninstall:
1006
+
1007
+
Uninstall the kernel later
1008
+
--------------------------
1009
+
1010
+
*All parts of your installed kernel are identifiable by its release name and
1011
+
thus easy to remove later.* [:ref:`... <uninstall_sbs>`]
1012
+
1013
+
Do not worry installing your kernel manually and thus bypassing your
1014
+
distribution's packaging system will totally mess up your machine: all parts of
1015
+
your kernel are easy to remove later, as files are stored in two places only and
1016
+
normally identifiable by the kernel's release name.
1017
+
1018
+
One of the two places is a directory in /lib/modules/, which holds the modules
1019
+
for each installed kernel. This directory is named after the kernel's release
1020
+
name; hence, to remove all modules for one of your kernels, simply remove its
1021
+
modules directory in /lib/modules/.
1022
+
1023
+
The other place is /boot/, where typically one to five files will be placed
1024
+
during installation of a kernel. All of them usually contain the release name in
1025
+
their file name, but how many files and their name depends somewhat on your
1026
+
distribution's installkernel executable (:ref:`see above <install>`) and its
1027
+
initramfs generator. On some distributions the ``kernel-install`` command
1028
+
mentioned in the step-by-step guide will remove all of these files for you --
1029
+
and the entry for your kernel in the bootloader configuration at the same time,
1030
+
too. On others you have to take care of these steps yourself. The following
1031
+
command should interactively remove the two main files of a kernel with the
1032
+
release name '6.0.1-foobar'::
1033
+
1034
+
rm -i /boot/{System.map,vmlinuz}-6.0.1-foobar
1035
+
1036
+
Now remove the belonging initramfs, which often will be called something like
1037
+
``/boot/initramfs-6.0.1-foobar.img`` or ``/boot/initrd.img-6.0.1-foobar``.
1038
+
Afterwards check for other files in /boot/ that have '6.0.1-foobar' in their
1039
+
name and delete them as well. Now remove the kernel from your bootloader's
1040
+
configuration.
1041
+
1042
+
Note, be very careful with wildcards like '*' when deleting files or directories
1043
+
for kernels manually: you might accidentally remove files of a 6.0.11 kernel
1044
+
when all you want is to remove 6.0 or 6.0.1.
1045
+
1046
+
[:ref:`back to step-by-step guide <uninstall_sbs>`]
1047
+
1048
+
.. _faq:
1049
+
1050
+
FAQ
1051
+
===
1052
+
1053
+
Why does this 'how-to' not work on my system?
1054
+
---------------------------------------------
1055
+
1056
+
As initially stated, this guide is 'designed to cover everything typically
1057
+
needed [to build a kernel] on mainstream Linux distributions running on
1058
+
commodity PC or server hardware'. The outlined approach despite this should work
1059
+
on many other setups as well. But trying to cover every possible use-case in one
1060
+
guide would defeat its purpose, as without such a focus you would need dozens or
1061
+
hundreds of constructs along the lines of 'in case you are having <insert
1062
+
machine or distro>, you at this point have to do <this and that>
1063
+
<instead|additionally>'. Each of which would make the text longer, more
1064
+
complicated, and harder to follow.
1065
+
1066
+
That being said: this of course is a balancing act. Hence, if you think an
1067
+
additional use-case is worth describing, suggest it to the maintainers of this
1068
+
document, as :ref:`described above <submit_improvements>`.
1069
+
1070
+
1071
+
..
1072
+
end-of-content
1073
+
..
1074
+
This document is maintained by Thorsten Leemhuis <linux@leemhuis.info>. If
1075
+
you spot a typo or small mistake, feel free to let him know directly and
1076
+
he'll fix it. You are free to do the same in a mostly informal way if you
1077
+
want to contribute changes to the text -- but for copyright reasons please CC
1078
+
linux-doc@vger.kernel.org and 'sign-off' your contribution as
1079
+
Documentation/process/submitting-patches.rst explains in the section 'Sign
1080
+
your work - the Developer's Certificate of Origin'.
1081
+
..
1082
+
This text is available under GPL-2.0+ or CC-BY-4.0, as stated at the top
1083
+
of the file. If you want to distribute this text under CC-BY-4.0 only,
1084
+
please use 'The Linux kernel development community' for author attribution
1085
+
and link this as source:
1086
+
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/quickly-build-trimmed-linux.rst
1087
+
..
1088
+
Note: Only the content of this RST file as found in the Linux kernel sources
1089
+
is available under CC-BY-4.0, as versions of this text that were processed
1090
+
(for example by the kernel's build system) might contain content taken from
1091
+
files which use a more restrictive license.
1092
+
+1
MAINTAINERS
+1
MAINTAINERS