Commit | Line | Data |
---|---|---|
efe92046 TL |
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 |