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