1.. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
2.. [see the bottom of this file for redistribution information]
3
4===========================================
5How to quickly build a trimmed Linux kernel
6===========================================
7
8This guide explains how to swiftly build Linux kernels that are ideal for
9testing purposes, but perfectly fine for day-to-day use, too.
10
11The 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
15section below: it contains a step-by-step guide, which is more detailed, but
16still brief and easy to follow; that guide and its accompanying reference
17section also mention alternatives, pitfalls, and additional aspects, all of
18which might be relevant for you.]*
19
20If your system uses techniques like Secure Boot, prepare it to permit starting
21self-compiled Linux kernels; install compilers and everything else needed for
22building Linux; make sure to have 12 Gigabyte free space in your home directory.
23Now run the following commands to download fresh Linux mainline sources, which
24you 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
40If 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
54Step-by-step guide
55==================
56
57Compiling your own Linux kernel is easy in principle. There are various ways to
58do it. Which of them actually work and is the best depends on the circumstances.
59
60This guide describes a way perfectly suited for those who want to quickly
61install Linux from sources without being bothered by complicated details; the
62goal is to cover everything typically needed on mainstream Linux distributions
63running on commodity PC or server hardware.
64
65The described approach is great for testing purposes, for example to try a
66proposed fix or to check if a problem was already fixed in the latest codebase.
67Nonetheless, kernels built this way are also totally fine for day-to-day use
68while at the same time being easy to keep up to date.
69
70The following steps describe the important aspects of the process; a
71comprehensive reference section later explains each of them in more detail. It
72sometimes also describes alternative approaches, pitfalls, as well as errors
73that might occur at a particular point -- and how to then get things rolling
74again.
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
347Did you run into trouble following any of the above steps that is not cleared up
348by the reference section below? Or do you have ideas how to improve the text?
349Then please take a moment of your time and let the maintainer of this document
350know by email (Thorsten Leemhuis <linux@leemhuis.info>), ideally while CCing the
351Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
352improve this document further, which is in everybody's interest, as it will
353enable more people to master the task described here.
354
355Reference section for the step-by-step guide
356============================================
357
358This section holds additional information for each of the steps in the above
359guide.
360
361.. _backup:
362
363Prepare for emergencies
364-----------------------
365
366   *Create a fresh backup and put system repair and restore tools at hand*
367   [:ref:`... <backup_sbs>`]
368
369Remember, you are dealing with computers, which sometimes do unexpected things
370-- especially if you fiddle with crucial parts like the kernel of an operating
371system. That's what you are about to do in this process. Hence, better prepare
372for something going sideways, even if that should not happen.
373
374[:ref:`back to step-by-step guide <backup_sbs>`]
375
376.. _secureboot:
377
378Dealing 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
385Many modern systems allow only certain operating systems to start; they thus by
386default will reject booting self-compiled kernels.
387
388You ideally deal with this by making your platform trust your self-built kernels
389with the help of a certificate and signing. How to do that is not described
390here, as it requires various steps that would take the text too far away from
391its purpose; 'Documentation/admin-guide/module-signing.rst' and various web
392sides already explain this in more detail.
393
394Temporarily disabling solutions like Secure Boot is another way to make your own
395Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup
396utility; the steps to do so are not described here, as they greatly vary between
397machines.
398
399On mainstream x86 Linux distributions there is a third and universal option:
400disable all Secure Boot restrictions for your Linux environment. You can
401initiate this process by running ``mokutil --disable-validation``; this will
402tell you to create a one-time password, which is safe to write down. Now
403restart; right after your BIOS performed all self-tests the bootloader Shim will
404show a blue box with a message 'Press any key to perform MOK management'. Hit
405some key before the countdown exposes. This will open a menu and choose 'Change
406Secure Boot state' there. Shim's 'MokManager' will now ask you to enter three
407randomly chosen characters from the one-time password specified earlier. Once
408you provided them, confirm that you really want to disable the validation.
409Afterwards, permit MokManager to reboot the machine.
410
411[:ref:`back to step-by-step guide <secureboot_sbs>`]
412
413.. _buildrequires:
414
415Install build requirements
416--------------------------
417
418   *Install all software required to build a Linux kernel.*
419   [:ref:`...<buildrequires_sbs>`]
420
421The kernel is pretty stand-alone, but besides tools like the compiler you will
422sometimes need a few libraries to build one. How to install everything needed
423depends on your Linux distribution and the configuration of the kernel you are
424about to build.
425
426Here are a few examples what you typically need on some mainstream
427distributions:
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
444In case you wonder why these lists include openssl and its development headers:
445they are needed for the Secure Boot support, which many distributions enable in
446their kernel configuration for x86 machines.
447
448Sometimes you will need tools for compression formats like bzip2, gzip, lz4,
449lzma, lzo, xz, or zstd as well.
450
451You might need additional libraries and their development headers in case you
452perform tasks not covered in this guide. For example, zlib will be needed when
453building kernel tools from the tools/ directory; adjusting the build
454configuration with make targets like 'menuconfig' or 'xconfig' will require
455development headers for ncurses or Qt5.
456
457[:ref:`back to step-by-step guide <buildrequires_sbs>`]
458
459.. _diskspace:
460
461Space requirements
462------------------
463
464   *Ensure to have enough free space for building and installing Linux.*
465   [:ref:`... <diskspace_sbs>`]
466
467The numbers mentioned are rough estimates with a big extra charge to be on the
468safe side, so often you will need less.
469
470If you have space constraints, remember to read the reference section when you
471reach the :ref:`section about configuration adjustments' <configmods>`, as
472ensuring debug symbols are disabled will reduce the consumed disk space by quite
473a few gigabytes.
474
475[:ref:`back to step-by-step guide <diskspace_sbs>`]
476
477
478.. _sources:
479
480Download the sources
481--------------------
482
483  *Retrieve the sources of the Linux version you intend to build.*
484  [:ref:`...<sources_sbs>`]
485
486The step-by-step guide outlines how to retrieve Linux' sources using a shallow
487git clone. There is :ref:`more to tell about this method<sources_shallow>` and
488two alternate ways worth describing: :ref:`packaged archives<sources_archive>`
489and :ref:`a full git clone<sources_full>`. And the aspects ':ref:`wouldn't it
490be 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
494Note, to keep things simple the commands used in this guide store the build
495artifacts in the source tree. If you prefer to separate them, simply add
496something like ``O=~/linux-builddir/`` to all make calls; also adjust the path
497in 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
503Noteworthy characteristics of shallow clones
504~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
505
506The step-by-step guide uses a shallow clone, as it is the best solution for most
507of this document's target audience. There are a few aspects of this approach
508worth 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
545Downloading the sources using a packages archive
546~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
547
548People new to compiling Linux often assume downloading an archive via the
549front-page of https://kernel.org is the best approach to retrieve Linux'
550sources. It actually can be, if you are certain to build just one particular
551kernel version without changing any code. Thing is: you might be sure this will
552be the case, but in practice it often will turn out to be a wrong assumption.
553
554That's because when reporting or debugging an issue developers will often ask to
555give another version a try. They also might suggest temporarily undoing a commit
556with ``git revert`` or might provide various patches to try. Sometimes reporters
557will also be asked to use ``git bisect`` to find the change causing a problem.
558These things rely on git or are a lot easier and quicker to handle with it.
559
560A shallow clone also does not add any significant overhead. For example, when
561you use ``git clone --depth=1`` to create a shallow clone of the latest mainline
562codebase git will only retrieve a little more data than downloading the latest
563mainline pre-release (aka 'rc') via the front-page of kernel.org would.
564
565A shallow clone therefore is often the better choice. If you nevertheless want
566to use a packaged source archive, download one via kernel.org; afterwards
567extract its content to some directory and change to the subdirectory created
568during extraction. The rest of the step-by-step guide will work just fine, apart
569from things that rely on git -- but this mainly concerns the section on
570successive 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
576Downloading the sources using a full git clone
577~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
578
579If downloading and storing a lot of data (~4,4 Gigabyte as of early 2023) is
580nothing that bothers you, instead of a shallow clone perform a full git clone
581instead. You then will avoid the specialties mentioned above and will have all
582versions 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
599Proper pre-releases (RCs) vs. latest mainline
600~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
601
602When cloning the sources using git and checking out origin/master, you often
603will retrieve a codebase that is somewhere between the latest and the next
604release or pre-release. This almost always is the code you want when giving
605mainline a shot: pre-releases like v6.1-rc5 are in no way special, as they do
606not get any significant extra testing before being published.
607
608There 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
610because compiler errors and other problems are more likely to occur during this
611time, as mainline then is in its 'merge window': a usually two week long phase,
612in 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
618Avoiding the mainline lag
619~~~~~~~~~~~~~~~~~~~~~~~~~
620
621The explanations for both the shallow clone and the full clone both retrieve the
622code from the Linux stable git repository. That makes things simpler for this
623document's audience, as it allows easy access to both mainline and
624stable/longterm releases. This approach has just one downside:
625
626Changes merged into the mainline repository are only synced to the master branch
627of the Linux stable repository  every few hours. This lag most of the time is
628not something to worry about; but in case you really need the latest code, just
629add 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
636When doing this with a shallow clone, remember to call ``git fetch`` with one
637of 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
643Patch the sources (optional)
644----------------------------
645
646  *In case you want to apply a kernel patch, do so now.*
647  [:ref:`...<patching_sbs>`]
648
649This is the point where you might want to patch your kernel -- for example when
650a developer proposed a fix and asked you to check if it helps. The step-by-step
651guide already explains everything crucial here.
652
653[:ref:`back to step-by-step guide <patching_sbs>`]
654
655.. _tagging:
656
657Tagging 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
664Tagging your kernel will help avoid confusion later, especially when you patched
665your kernel. Adding an individual tag will also ensure the kernel's image and
666its modules are installed in parallel to any existing kernels.
667
668There are various ways to add such a tag. The step-by-step guide realizes one by
669creating a 'localversion' file in your build directory from which the kernel
670build scripts will automatically pick up the tag. You can later change that file
671to use a different tag in subsequent builds or simply remove that file to dump
672the tag.
673
674[:ref:`back to step-by-step guide <tagging_sbs>`]
675
676.. _configuration:
677
678Define 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
684There are various aspects for this steps that require a more careful
685explanation:
686
687Pitfalls when using another configuration file as base
688~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
689
690Make targets like localmodconfig and olddefconfig share a few common snares you
691want 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
709Influencing the configuration
710~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
711
712The make target olddefconfig and the ``yes "" |`` used when utilizing
713localmodconfig will set any undefined build options to their default value. This
714among others will disable many kernel features that were introduced after your
715base kernel was released.
716
717If you want to set these configurations options manually, use ``oldconfig``
718instead of ``olddefconfig`` or omit the ``yes "" |`` when utilizing
719localmodconfig. Then for each undefined configuration option you will be asked
720how to proceed. In case you are unsure what to answer, simply hit 'enter' to
721apply the default value.
722
723Big pitfall when using localmodconfig
724~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
725
726As explained briefly in the step-by-step guide already: with localmodconfig it
727can easily happen that your self-built kernel will lack modules for tasks you
728did not perform before utilizing this make target. That's because those tasks
729require kernel modules that are normally autoloaded when you perform that task
730for the first time; if you didn't perform that task at least once before using
731localmodonfig, the latter will thus assume these modules are superfluous and
732disable them.
733
734You can try to avoid this by performing typical tasks that often will autoload
735additional kernel modules: start a VM, establish VPN connections, loop-mount a
736CD/DVD ISO, mount network shares (CIFS, NFS, ...), and connect all external
737devices (2FA keys, headsets, webcams, ...) as well as storage devices with file
738systems you otherwise do not utilize (btrfs, ext4, FAT, NTFS, XFS, ...). But it
739is hard to think of everything that might be needed -- even kernel developers
740often forget one thing or another at this point.
741
742Do not let that risk bother you, especially when compiling a kernel only for
743testing purposes: everything typically crucial will be there. And if you forget
744something important you can turn on a missing feature later and quickly run the
745commands to compile and install a better kernel.
746
747But if you plan to build and use self-built kernels regularly, you might want to
748reduce the risk by recording which modules your system loads over the course of
749a few weeks. You can automate this with `modprobed-db
750<https://github.com/graysky2/modprobed-db>`_. Afterwards use ``LSMOD=<path>`` to
751point localmodconfig to the list of modules modprobed-db noticed being used::
752
753    yes "" | make LSMOD="${HOME}"/.config/modprobed.db localmodconfig
754
755Remote building with localmodconfig
756~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
757
758If 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.
760Now point the build scripts to the file like this: ``yes "" | make
761LSMOD=~/lsmod_foo-machine localmodconfig``. Note, in this case
762you likely want to copy a base kernel configuration from the other machine over
763as 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
769Adjust build configuration
770--------------------------
771
772   *Check if you might want to or have to adjust some kernel configuration
773   options:*
774
775Depending on your needs you at this point might want or have to adjust some
776kernel configuration options.
777
778.. _configmods_debugsymbols:
779
780Debug symbols
781~~~~~~~~~~~~~
782
783   *Evaluate how you want to handle debug symbols.*
784   [:ref:`...<configmods_sbs>`]
785
786Most users do not need to care about this, it's often fine to leave everything
787as it is; but you should take a closer look at this, if you might need to decode
788a stack trace or want to reduce space consumption.
789
790Having 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
792able to find the exact place where the problem occurred in the code. But
793collecting and embedding the needed debug information takes time and consumes
794quite a bit of space: in late 2022 the build artifacts for a typical x86 kernel
795configured with localmodconfig consumed around 5 Gigabyte of space with debug
796symbols, but less than 1 when they were disabled. The resulting kernel image and
797the modules are bigger as well, which increases load times.
798
799Hence, if you want a small kernel and are unlikely to decode a stack trace
800later, 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
807You on the other hand definitely want to enable them, if there is a decent
808chance that you need to decode a stack trace later (as explained by 'Decode
809failure messages' in Documentation/admin-guide/tainted-kernels.rst in more
810detail)::
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
816Note, many mainstream distributions enable debug symbols in their kernel
817configurations -- make targets like localmodconfig and olddefconfig thus will
818often pick that setting up.
819
820[:ref:`back to step-by-step guide <configmods_sbs>`]
821
822.. _configmods_distros:
823
824Distro specific adjustments
825~~~~~~~~~~~~~~~~~~~~~~~~~~~
826
827   *Are you running* [:ref:`... <configmods_sbs>`]
828
829The following sections help you to avoid build problems that are known to occur
830when 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
849Individual adjustments
850~~~~~~~~~~~~~~~~~~~~~~
851
852   *If you want to influence the other aspects of the configuration, do so
853   now* [:ref:`... <configmods_sbs>`]
854
855You at this point can use a command like ``make menuconfig`` to enable or
856disable certain features using a text-based user interface; to use a graphical
857configuration utilize, use the make target ``xconfig`` or ``gconfig`` instead.
858All 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
860missing.
861
862[:ref:`back to step-by-step guide <configmods_sbs>`]
863
864.. _build:
865
866Build your kernel
867-----------------
868
869  *Build the image and the modules of your kernel* [:ref:`... <build_sbs>`]
870
871A lot can go wrong at this stage, but the instructions below will help you help
872yourself. Another subsection explains how to directly package your kernel up as
873deb, rpm or tar file.
874
875Dealing with build errors
876~~~~~~~~~~~~~~~~~~~~~~~~~
877
878When a build error occurs, it might be caused by some aspect of your machine's
879setup that often can be fixed quickly; other times though the problem lies in
880the code and can only be fixed by a developer. A close examination of the
881failure messages coupled with some research on the internet will often tell you
882which of the two it is. To perform such a investigation, restart the build
883process like this::
884
885    make V=1
886
887The ``V=1`` activates verbose output, which might be needed to see the actual
888error. 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
890this parallelism also results in some clutter when failures occur.
891
892After a few seconds the build process should run into the error again. Now try
893to find the most crucial line describing the problem. Then search the internet
894for the most important and non-generic section of that line (say 4 to 8 words);
895avoid or remove anything that looks remotely system-specific, like your username
896or local path names like ``/home/username/linux/``. First try your regular
897internet search engine with that string, afterwards search Linux kernel mailing
898lists via `lore.kernel.org/all/ <https://lore.kernel.org/all/>`_.
899
900This most of the time will find something that will explain what is wrong; quite
901often one of the hits will provide a solution for your problem, too. If you
902do not find anything that matches your problem, try again from a different angle
903by modifying your search terms or using another line from the error messages.
904
905In the end, most trouble you are to run into has likely been encountered and
906reported by others already. That includes issues where the cause is not your
907system, but lies the code. If you run into one of those, you might thus find a
908solution (e.g. a patch) or workaround for your problem, too.
909
910Package your kernel up
911~~~~~~~~~~~~~~~~~~~~~~
912
913The 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
915steps of the guide then install. You instead can also directly build everything
916and 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
924This 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
928If you employ the targets to generate deb or rpm packages, ignore the
929step-by-step guide's instructions on installing and removing your kernel;
930instead 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,
932aptitude, dnf/yum, zypper, ...). Be aware that the packages generated using
933these two make targets are designed to work on various distributions utilizing
934those formats, they thus will sometimes behave differently than your
935distribution's kernel packages.
936
937[:ref:`back to step-by-step guide <build_sbs>`]
938
939.. _install:
940
941Install your kernel
942-------------------
943
944  *Now install your kernel* [:ref:`... <install_sbs>`]
945
946What you need to do after executing the command in the step-by-step guide
947depends on the existence and the implementation of an ``installkernel``
948executable. Many commodity Linux distributions ship such a kernel installer in
949``/sbin/`` that does everything needed, hence there is nothing left for you
950except rebooting. But some distributions contain an installkernel that does
951only part of the job -- and a few lack it completely and leave all the work to
952you.
953
954If ``installkernel`` is found, the kernel's build system will delegate the
955actual installation of your kernel's image and related files to this executable.
956On 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
958name>' alongside it. Your kernel will thus be installed in parallel to any
959existing ones, unless you already have one with exactly the same release name.
960
961Installkernel on many distributions will afterwards generate an 'initramfs'
962(often also called 'initrd'), which commodity distributions rely on for booting;
963hence be sure to keep the order of the two make targets used in the step-by-step
964guide, as things will go sideways if you install your kernel's image before its
965modules. Often installkernel will then add your kernel to the bootloader
966configuration, too. You have to take care of one or both of these tasks
967yourself, if your distributions installkernel doesn't handle them.
968
969A few distributions like Arch Linux and its derivatives totally lack an
970installkernel executable. On those just install the modules using the kernel's
971build 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
977If your distribution boots with the help of an initramfs, now generate one for
978your kernel using the tools your distribution provides for this process.
979Afterwards add your kernel to your bootloader configuration and reboot.
980
981[:ref:`back to step-by-step guide <install_sbs>`]
982
983.. _another:
984
985Another round later
986-------------------
987
988  *To later build another kernel you need similar, but sometimes slightly
989  different commands* [:ref:`... <another_sbs>`]
990
991The process to build later kernels is similar, but at some points slightly
992different. You for example do not want to use 'localmodconfig' for succeeding
993kernel builds, as you already created a trimmed down configuration you want to
994use from now on. Hence instead just use ``oldconfig`` or ``olddefconfig`` to
995adjust your build configurations to the needs of the kernel version you are
996about to build.
997
998If you created a shallow-clone with git, remember what the :ref:`section that
999explained the setup described in more detail <sources>`: you need to use a
1000slightly different ``git fetch`` command and when switching to another series
1001need to add an additional remote branch.
1002
1003[:ref:`back to step-by-step guide <another_sbs>`]
1004
1005.. _uninstall:
1006
1007Uninstall 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
1013Do not worry installing your kernel manually and thus bypassing your
1014distribution's packaging system will totally mess up your machine: all parts of
1015your kernel are easy to remove later, as files are stored in two places only and
1016normally identifiable by the kernel's release name.
1017
1018One of the two places is a directory in /lib/modules/, which holds the modules
1019for each installed kernel. This directory is named after the kernel's release
1020name; hence, to remove all modules for one of your kernels, simply remove its
1021modules directory in /lib/modules/.
1022
1023The other place is /boot/, where typically one to five files will be placed
1024during installation of a kernel. All of them usually contain the release name in
1025their file name, but how many files and their name depends somewhat on your
1026distribution's installkernel executable (:ref:`see above <install>`) and its
1027initramfs generator. On some distributions the ``kernel-install`` command
1028mentioned in the step-by-step guide will remove all of these files for you --
1029and the entry for your kernel in the bootloader configuration at the same time,
1030too. On others you have to take care of these steps yourself. The following
1031command should interactively remove the two main files of a kernel with the
1032release name '6.0.1-foobar'::
1033
1034    rm -i /boot/{System.map,vmlinuz}-6.0.1-foobar
1035
1036Now 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``.
1038Afterwards check for other files in /boot/ that have '6.0.1-foobar' in their
1039name and delete them as well. Now remove the kernel from your bootloader's
1040configuration.
1041
1042Note, be very careful with wildcards like '*' when deleting files or directories
1043for kernels manually: you might accidentally remove files of a 6.0.11 kernel
1044when 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
1050FAQ
1051===
1052
1053Why does this 'how-to' not work on my system?
1054---------------------------------------------
1055
1056As initially stated, this guide is 'designed to cover everything typically
1057needed [to build a kernel] on mainstream Linux distributions running on
1058commodity PC or server hardware'. The outlined approach despite this should work
1059on many other setups as well. But trying to cover every possible use-case in one
1060guide would defeat its purpose, as without such a focus you would need dozens or
1061hundreds of constructs along the lines of 'in case you are having <insert
1062machine or distro>, you at this point have to do <this and that>
1063<instead|additionally>'. Each of which would make the text longer, more
1064complicated, and harder to follow.
1065
1066That being said: this of course is a balancing act. Hence, if you think an
1067additional use-case is worth describing, suggest it to the maintainers of this
1068document, 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
1093