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