Lines Matching +full:back +full:- +full:to +full:- +full:back
1 .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
5 How to quickly build a trimmed Linux kernel
8 This guide explains how to swiftly build Linux kernels that are ideal for
9 testing purposes, but perfectly fine for day-to-day use, too.
14 *[If you are new to compiling Linux, ignore this TLDR and head over to the next
15 section below: it contains a step-by-step guide, which is more detailed, but
16 still brief and easy to follow; that guide and its accompanying reference
20 If your system uses techniques like Secure Boot, prepare it to permit starting
21 self-compiled Linux kernels; install compilers and everything else needed for
22 building Linux; make sure to have 12 Gigabyte free space in your home directory.
23 Now run the following commands to download fresh Linux mainline sources, which
24 you then use to configure, build and install your own kernel::
26 git clone --depth 1 -b master \
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.
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)
37 command -v installkernel && sudo make modules_install install
40 If you later want to build a newer mainline snapshot, use these commands::
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.
49 make -j $(nproc --all)
51 command -v installkernel && sudo make modules_install install
54 Step-by-step guide
57 Compiling your own Linux kernel is easy in principle. There are various ways to
60 This guide describes a way perfectly suited for those who want to quickly
62 goal is to cover everything typically needed on mainstream Linux distributions
65 The described approach is great for testing purposes, for example to try a
66 proposed fix or to check if a problem was already fixed in the latest codebase.
67 Nonetheless, kernels built this way are also totally fine for day-to-day use
68 while at the same time being easy to keep up to date.
73 that might occur at a particular point -- and how to then get things rolling
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
86 to be prepared for the unlikely case of something going sideways.
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
97 ``mokutil --disable-validation``.
103 * Install all software required to build a Linux kernel. Often you will need:
106 reference section shows how to quickly install those on various popular Linux
113 * Ensure to have enough free space for building and installing Linux. For the
116 typically suffice. If you have less available, be sure to check the reference
119 in /home/ to around 4 Gigabyte.
125 * Retrieve the sources of the Linux version you intend to build; then change
127 meant to be executed from there.
129 *[Note: the following paragraphs describe how to retrieve the sources by
137 First, execute the following command to retrieve a fresh mainline codebase::
139 git clone --no-checkout --depth 1 -b master \
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::
146 git fetch --shallow-exclude=v6.0 origin
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
152 git remote set-branches --add origin linux-6.1.y
153 git fetch --shallow-exclude=v6.0 origin
156 initial clone, you will be able to check out a fresh mainline codebase, which
159 git checkout --detach origin/master
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
171 * In case you want to apply a kernel patch, do so now. Often a command like
174 patch -p1 < ../proposed-fix.patch
176 If the ``-p1`` is actually needed, depends on how the patch was created; in
180 reset --hard`` to undo any changes to the sources.
187 better add a unique tag to the one you are about to build::
189 echo "-proposed_fix" > localversion
191 Running ``uname -r`` under your kernel later will then print something like
192 '6.1-rc4-proposed_fix'.
201 If you already prepared such a '.config' file yourself, copy it to
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.
208 Using this make target is fine for everybody else, too -- but you often can
213 This will try to pick your distribution's kernel as base, but then disable
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
231 * Check if you might want to or have to adjust some kernel configuration
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',
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>`]
241 * Are you running Debian? Then to avoid known problems by performing
245 * If you want to influence the other aspects of the configuration, do so now
253 make -j $(nproc --all)
264 command -v installkernel && sudo make modules_install install
266 Often all left for you to do afterwards is a ``reboot``, as many commodity
269 distributions you have to take care of these two steps manually for reasons
273 does nothing at all; in that case you have to manually install your kernel,
277 and the web to find out how to install your own kernel there.
283 * To later build another kernel you need similar steps, but sometimes slightly
286 First, switch back into the sources tree::
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::
293 git remote set-branches --add origin linux-6.2.y
295 Now fetch the latest upstream changes; you again need to specify the earliest
299 git fetch --shallow-exclude=v6.0 origin
301 Now switch to the version you are interested in -- but be aware the command
303 conflict with the sources you want to checkout::
305 git checkout --force --detach origin/master
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
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
319 make -j $(nproc --all)
323 command -v installkernel && sudo make modules_install install
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
335 after its release name -- '6.0.1-foobar' in the following example::
337 sudo rm -rf /lib/modules/6.0.1-foobar
343 command -v kernel-install && sudo kernel-install -v remove 6.0.1-foobar
346 do the same if any files named '*6.0.1-foobar*' remain in /boot/.
353 by the reference section below? Or do you have ideas how to improve the text?
356 Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
358 enable more people to master the task described here.
360 Reference section for the step-by-step guide
369 -----------------------
375 -- especially if you fiddle with crucial parts like the kernel of an operating
376 system. That's what you are about to do in this process. Hence, better prepare
379 [:ref:`back to step-by-step guide <backup_sbs>`]
384 ----------------------------------------
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.*
390 Many modern systems allow only certain operating systems to start; they thus by
391 default will reject booting self-compiled kernels.
393 You ideally deal with this by making your platform trust your self-built kernels
394 with the help of a certificate and signing. How to do that is not described
396 its purpose; 'Documentation/admin-guide/module-signing.rst' and various web
399 Temporarily disabling solutions like Secure Boot is another way to make your own
400 Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup
401 utility; the steps to do so are not described here, as they greatly vary between
406 initiate this process by running ``mokutil --disable-validation``; this will
407 tell you to create a one-time password, which is safe to write down. Now
408 restart; right after your BIOS performed all self-tests the bootloader Shim will
409 show a blue box with a message 'Press any key to perform MOK management'. Hit
411 Secure Boot state' there. Shim's 'MokManager' will now ask you to enter three
412 randomly chosen characters from the one-time password specified earlier. Once
413 you provided them, confirm that you really want to disable the validation.
414 Afterwards, permit MokManager to reboot the machine.
416 [:ref:`back to step-by-step guide <secureboot_sbs>`]
421 --------------------------
423 *Install all software required to build a Linux kernel.*
426 The kernel is pretty stand-alone, but besides tools like the compiler you will
427 sometimes need a few libraries to build one. How to install everything needed
429 about to build.
437 pahole perl-base libssl-dev libelf-dev
446 sudo zypper install bc binutils bison dwarves flex gcc git make perl-base \
447 openssl openssl-devel libelf-dev
462 [:ref:`back to step-by-step guide <buildrequires_sbs>`]
467 ------------------
469 *Ensure to have enough free space for building and installing Linux.*
472 The numbers mentioned are rough estimates with a big extra charge to be on the
475 If you have space constraints, remember to read the reference section when you
480 [:ref:`back to step-by-step guide <diskspace_sbs>`]
486 --------------------
488 *Retrieve the sources of the Linux version you intend to build.*
491 The step-by-step guide outlines how to retrieve Linux' sources using a shallow
492 git clone. There is :ref:`more to tell about this method<sources_shallow>` and
495 be 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
499 Note, to keep things simple the commands used in this guide store the build
500 artifacts in the source tree. If you prefer to separate them, simply add
501 something like ``O=~/linux-builddir/`` to all make calls; also adjust the path
504 [:ref:`back to step-by-step guide <sources_sbs>`]
511 The step-by-step guide uses a shallow clone, as it is the best solution for most
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
521 like ``--depth=1``, unless you add branches for stable/longterm kernels.
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
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=``.
539 In that case run ``git repack -d`` and try again``
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.
546 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
553 People new to compiling Linux often assume downloading an archive via the
554 front-page of https://kernel.org is the best approach to retrieve Linux'
555 sources. It actually can be, if you are certain to build just one particular
557 be the case, but in practice it often will turn out to be a wrong assumption.
559 That's because when reporting or debugging an issue developers will often ask to
561 with ``git revert`` or might provide various patches to try. Sometimes reporters
562 will also be asked to use ``git bisect`` to find the change causing a problem.
563 These things rely on git or are a lot easier and quicker to handle with it.
566 you use ``git clone --depth=1`` to create a shallow clone of the latest mainline
568 mainline pre-release (aka 'rc') via the front-page of kernel.org would.
571 to use a packaged source archive, download one via kernel.org; afterwards
572 extract its content to some directory and change to the subdirectory created
573 during extraction. The rest of the step-by-step guide will work just fine, apart
574 from things that rely on git -- but this mainly concerns the section on
577 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
589 curl -L \
591 -o linux-stable.git.bundle
592 git clone linux-stable.git.bundle ~/linux/
593 rm linux-stable.git.bundle
595 git remote set-url origin \
598 git checkout --detach origin/master
600 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
604 Proper pre-releases (RCs) vs. latest mainline
609 release or pre-release. This almost always is the code you want when giving
610 mainline a shot: pre-releases like v6.1-rc5 are in no way special, as they do
613 There is one exception: you might want to stick to the latest mainline release
614 (say v6.1) before its successor's first pre-release (v6.2-rc1) is out. That is
615 because compiler errors and other problems are more likely to occur during this
619 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
628 document's audience, as it allows easy access to both mainline and
631 Changes merged into the mainline repository are only synced to the master branch
633 not something to worry about; but in case you really need the latest code, just
639 git checkout --detach mainline/master
641 When doing this with a shallow clone, remember to call ``git fetch`` with one
642 of the parameters described earlier to limit the depth.
644 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
649 ----------------------------
651 *In case you want to apply a kernel patch, do so now.*
654 This is the point where you might want to patch your kernel -- for example when
655 a developer proposed a fix and asked you to check if it helps. The step-by-step
658 [:ref:`back to step-by-step guide <patching_sbs>`]
663 ------------------------------------------------
671 its modules are installed in parallel to any existing kernels.
673 There are various ways to add such a tag. The step-by-step guide realizes one by
676 to use a different tag in subsequent builds or simply remove that file to dump
679 [:ref:`back to step-by-step guide <tagging_sbs>`]
684 ----------------------------------------------
696 want to be aware of:
699 (e.g. '~/linux/.config'), if one exists. In case you want to start from
700 scratch you thus need to delete it.
702 * The make targets try to find the configuration for your running kernel
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
709 * Unexpected things might happen if you try to use a config file prepared for
711 might want to use a configuration as base which your distribution utilized
718 localmodconfig will set any undefined build options to their default value. This
722 If you want to set these configurations options manually, use ``oldconfig``
725 how to proceed. In case you are unsure what to answer, simply hit 'enter' to
731 As explained briefly in the step-by-step guide already: with localmodconfig it
732 can easily happen that your self-built kernel will lack modules for tasks you
739 You can try to avoid this by performing typical tasks that often will autoload
740 additional kernel modules: start a VM, establish VPN connections, loop-mount a
744 is hard to think of everything that might be needed -- even kernel developers
750 commands to compile and install a better kernel.
752 But if you plan to build and use self-built kernels regularly, you might want to
754 a few weeks. You can automate this with `modprobed-db
755 <https://github.com/graysky2/modprobed-db>`_. Afterwards use ``LSMOD=<path>`` to
756 point localmodconfig to the list of modules modprobed-db noticed being used::
763 If 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.
765 Now point the build scripts to the file like this: ``yes "" | make
766 LSMOD=~/lsmod_foo-machine localmodconfig``. Note, in this case
767 you likely want to copy a base kernel configuration from the other machine over
770 [:ref:`back to step-by-step guide <configuration_sbs>`]
775 --------------------------
777 *Check if you might want to or have to adjust some kernel configuration
780 Depending on your needs you at this point might want or have to adjust some
788 *Evaluate how you want to handle debug symbols.*
791 Most users do not need to care about this, it's often fine to leave everything
792 as it is; but you should take a closer look at this, if you might need to decode
793 a stack trace or want to reduce space consumption.
797 able to find the exact place where the problem occurred in the code. But
804 Hence, if you want a small kernel and are unlikely to decode a stack trace
805 later, you might want to disable debug symbols to avoid above downsides::
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
812 You on the other hand definitely want to enable them, if there is a decent
813 chance that you need to decode a stack trace later (as explained by 'Decode
814 failure messages' in Documentation/admin-guide/tainted-kernels.rst in more
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
822 configurations -- make targets like localmodconfig and olddefconfig thus will
825 [:ref:`back to step-by-step guide <configmods_sbs>`]
834 The following sections help you to avoid build problems that are known to occur
839 * Remove a stale reference to a certificate file that would cause your build to
842 ./scripts/config --file .config --set-str SYSTEM_TRUSTED_KEYS ''
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.
850 [:ref:`back to step-by-step guide <configmods_sbs>`]
857 *If you want to influence the other aspects of the configuration, do so
860 You at this point can use a command like ``make menuconfig`` to enable or
861 disable certain features using a text-based user interface; to use a graphical
867 [:ref:`back to step-by-step guide <configmods_sbs>`]
872 -----------------
877 yourself. Another subsection explains how to directly package your kernel up as
887 which of the two it is. To perform such a investigation, restart the build
892 The ``V=1`` activates verbose output, which might be needed to see the actual
893 error. To make it easier to spot, this command also omits the ``-j $(nproc
894 --all)`` used earlier to utilize every CPU core in the system for the job -- but
898 to find the most crucial line describing the problem. Then search the internet
899 for the most important and non-generic section of that line (say 4 to 8 words);
900 avoid or remove anything that looks remotely system-specific, like your username
910 In the end, most trouble you are to run into has likely been encountered and
918 The step-by-step guide uses the default make targets (e.g. 'bzImage' and
919 'modules' on x86) to build the image and the modules of your kernel, which later
923 * ``make -j $(nproc --all) bindeb-pkg`` to generate a deb package
925 * ``make -j $(nproc --all) binrpm-pkg`` to generate a rpm package
927 * ``make -j $(nproc --all) tarbz2-pkg`` to generate a bz2 compressed tarball
931 ``make -j $(nproc --all)``, as they will pick up everything already built.
933 If you employ the targets to generate deb or rpm packages, ignore the
934 step-by-step guide's instructions on installing and removing your kernel;
938 these two make targets are designed to work on various distributions utilizing
942 [:ref:`back to step-by-step guide <build_sbs>`]
947 -------------------
951 What you need to do after executing the command in the step-by-step guide
956 only part of the job -- and a few lack it completely and leave all the work to
960 actual installation of your kernel's image and related files to this executable.
961 On 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
963 name>' alongside it. Your kernel will thus be installed in parallel to any
968 hence be sure to keep the order of the two make targets used in the step-by-step
970 modules. Often installkernel will then add your kernel to the bootloader
971 configuration, too. You have to take care of one or both of these tasks
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)
984 Afterwards add your kernel to your bootloader configuration and reboot.
986 [:ref:`back to step-by-step guide <install_sbs>`]
991 -------------------
993 *To later build another kernel you need similar, but sometimes slightly
996 The process to build later kernels is similar, but at some points slightly
997 different. You for example do not want to use 'localmodconfig' for succeeding
998 kernel builds, as you already created a trimmed down configuration you want to
999 use from now on. Hence instead just use ``oldconfig`` or ``olddefconfig`` to
1000 adjust your build configurations to the needs of the kernel version you are
1001 about to build.
1003 If you created a shallow-clone with git, remember what the :ref:`section that
1004 explained the setup described in more detail <sources>`: you need to use a
1005 slightly different ``git fetch`` command and when switching to another series
1006 need to add an additional remote branch.
1008 [:ref:`back to step-by-step guide <another_sbs>`]
1013 --------------------------
1016 thus easy to remove later.* [:ref:`... <uninstall_sbs>`]
1020 your kernel are easy to remove later, as files are stored in two places only and
1025 name; hence, to remove all modules for one of your kernels, simply remove its
1028 The other place is /boot/, where typically one to five files will be placed
1032 initramfs generator. On some distributions the ``kernel-install`` command
1033 mentioned in the step-by-step guide will remove all of these files for you --
1035 too. On others you have to take care of these steps yourself. The following
1037 release name '6.0.1-foobar'::
1039 rm -i /boot/{System.map,vmlinuz}-6.0.1-foobar
1042 ``/boot/initramfs-6.0.1-foobar.img`` or ``/boot/initrd.img-6.0.1-foobar``.
1043 Afterwards check for other files in /boot/ that have '6.0.1-foobar' in their
1049 when all you want is to remove 6.0 or 6.0.1.
1051 [:ref:`back to step-by-step guide <uninstall_sbs>`]
1058 Why does this 'how-to' not work on my system?
1059 ---------------------------------------------
1061 As initially stated, this guide is 'designed to cover everything typically
1062 needed [to build a kernel] on mainstream Linux distributions running on
1064 on many other setups as well. But trying to cover every possible use-case in one
1067 machine or distro>, you at this point have to do <this and that>
1069 complicated, and harder to follow.
1072 additional use-case is worth describing, suggest it to the maintainers of this
1077 end-of-content
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'.
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,
1091 …/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide/quickly-build-trimmed-linux.r…
1094 is available under CC-BY-4.0, as versions of this text that were processed