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