Lines Matching +full:in +full:- +full:kernel
1 .. SPDX-License-Identifier: (GPL-2.0+ OR CC-BY-4.0)
5 How to quickly build a trimmed Linux kernel
9 testing purposes, but perfectly fine for day-to-day use, too.
15 section below: it contains a step-by-step guide, which is more detailed, but
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.
24 you then use to configure, build and install your own kernel::
26 git clone --depth 1 -b master \
27 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
34 make -j $(nproc --all)
37 command -v installkernel && sudo make modules_install install
43 git fetch --depth 1 origin
45 git checkout --force --detach origin/master
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
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
71 comprehensive reference section later explains each of them in more detail. It
73 that might occur at a particular point -- and how to then get things rolling
79 quickly look something up in the reference section and afterwards jump back
81 https://docs.kernel.org/admin-guide/quickly-build-trimmed-linux.html
93 ensure the system will permit your self-compiled kernel to boot later. The
95 disable such techniques in the BIOS setup utility; alternatively, remove
97 ``mokutil --disable-validation``.
103 * Install all software required to build a Linux kernel. Often you will need:
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
119 in /home/ to around 4 Gigabyte.
126 into the directory holding them, as all further commands in this guide are
139 git clone --no-checkout --depth 1 -b master \
140 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git ~/linux/
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
152 git remote set-branches --add origin linux-6.1.y
153 git fetch --shallow-exclude=v6.0 origin
155 Now checkout the code you are interested in. If you just performed the
159 git checkout --detach origin/master
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.
186 * If you patched your kernel or have one of the same version installed already,
189 echo "-proposed_fix" > localversion
191 Running ``uname -r`` under your kernel later will then print something like
192 '6.1-rc4-proposed_fix'.
198 * Create the build configuration for your kernel based on an existing
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
216 universal kernel from a commodity Linux distribution.
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
222 section outlines; but when building a kernel just for quick testing purposes
224 aspect in mind when using a kernel built with this make target, as it might
231 * Check if you might want to or have to adjust some kernel configuration
235 might need to decode a stack trace found for example in a 'panic', 'Oops',
237 storage space or prefer a smaller kernel binary. See the reference section
242 additional adjustments explained in the reference section.
251 * Build the image and the modules of your kernel::
253 make -j $(nproc --all)
255 If you want your kernel packaged up as deb, rpm, or tar file, see the
262 * Now install your kernel::
264 command -v installkernel && sudo make modules_install install
268 an entry for your kernel in your bootloader's configuration; but on some
273 does nothing at all; in that case you have to manually install your kernel,
274 as outlined in the reference section.
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
290 In case you want to build a version from a stable/longterm series you have
293 git remote set-branches --add origin linux-6.2.y
299 git fetch --shallow-exclude=v6.0 origin
301 Now switch to the version you are interested in -- but be aware the command
305 git checkout --force --detach origin/master
311 kernel::
317 Now build your kernel::
319 make -j $(nproc --all)
321 Afterwards install the kernel as outlined above::
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
331 not delete the kernel you are running, as that might render your system
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::
337 sudo rm -rf /lib/modules/6.0.1-foobar
340 other kernel files installed while also removing the kernel's entry from the
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/.
356 Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
357 improve this document further, which is in everybody's interest, as it will
360 Reference section for the step-by-step guide
363 This section holds additional information for each of the steps in the above
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 ----------------------------------------
387 ensure the system will permit your self-compiled kernel to boot later.*
391 default will reject booting self-compiled kernels.
393 You ideally deal with this by making your platform trust your self-built kernels
396 its purpose; 'Documentation/admin-guide/module-signing.rst' and various web
397 sides already explain this in more detail.
400 Linux boot. On commodity x86 systems it is possible to do this in the BIOS Setup
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
412 randomly chosen characters from the one-time password specified earlier. Once
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
428 depends on your Linux distribution and the configuration of the kernel you are
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
449 In case you wonder why these lists include openssl and its development headers:
450 they are needed for the Secure Boot support, which many distributions enable in
451 their kernel configuration for x86 machines.
456 You might need additional libraries and their development headers in case you
457 perform tasks not covered in this guide. For example, zlib will be needed when
458 building kernel tools from the tools/ directory; adjusting the build
462 [:ref:`back to step-by-step guide <buildrequires_sbs>`]
467 ------------------
480 [:ref:`back to step-by-step guide <diskspace_sbs>`]
486 --------------------
491 The step-by-step guide outlines how to retrieve Linux' sources using a shallow
495 be wiser to use a proper pre-release than the latest mainline code
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
502 in all commands that add files or modify any generated (like your '.config').
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=``
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
521 like ``--depth=1``, unless you add branches for stable/longterm kernels.
524 the time you care about, or an explicit depth as shown in the step-by-step
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=``.
538 'fatal: error in object: unshallow cafecaca0c0dacafecaca0c0dacafecaca0c0da'.
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
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>`]
554 front-page of https://kernel.org is the best approach to retrieve Linux'
556 kernel version without changing any code. Thing is: you might be sure this will
557 be the case, but in practice it often will turn out to be a wrong assumption.
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
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 \
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
595 git remote set-url origin \
596 https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
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
614 (say v6.1) before its successor's first pre-release (v6.2-rc1) is out. That is
616 time, as mainline then is in its 'merge window': a usually two week long phase,
617 in which the bulk of the changes for the next release is merged.
619 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
633 not something to worry about; but in case you really need the latest code, just
637 https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
639 git checkout --detach mainline/master
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>`]
662 Tagging this kernel build (optional, often wise)
663 ------------------------------------------------
665 *If you patched your kernel or already have that kernel version installed,
666 better tag your kernel by extending its release name:*
669 Tagging your kernel will help avoid confusion later, especially when you patched
670 your kernel. Adding an individual tag will also ensure the kernel's image and
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
674 creating a 'localversion' file in your build directory from which the kernel
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>`]
683 Define the build configuration for your kernel
684 ----------------------------------------------
686 *Create the build configuration for your kernel based on an existing
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
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
710 one kernel (say v6.0) on an older generation (say v5.15). In that case you
712 when they used that or an slightly older kernel version.
719 among others will disable many kernel features that were introduced after your
720 base kernel was released.
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
734 require kernel modules that are normally autoloaded when you perform that task
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
747 Do not let that risk bother you, especially when compiling a kernel only for
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.
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
768 as well and place it as .config in your build directory.
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
781 kernel configuration options.
795 Having debug symbols available can be important when your kernel throws a
797 able to find the exact place where the problem occurred in the code. But
799 quite a bit of space: in late 2022 the build artifacts for a typical x86 kernel
801 symbols, but less than 1 when they were disabled. The resulting kernel image and
804 Hence, if you want a small kernel and are unlikely to decode a stack trace
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
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
821 Note, many mainstream distributions enable debug symbols in their kernel
822 configurations -- make targets like localmodconfig and olddefconfig thus will
825 [:ref:`back to step-by-step guide <configmods_sbs>`]
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>`]
861 disable certain features using a text-based user interface; to use a graphical
867 [:ref:`back to step-by-step guide <configmods_sbs>`]
871 Build your kernel
872 -----------------
874 *Build the image and the modules of your kernel* [:ref:`... <build_sbs>`]
877 yourself. Another subsection explains how to directly package your kernel up as
884 setup that often can be fixed quickly; other times though the problem lies in
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
895 this parallelism also results in some clutter when failures occur.
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
902 internet search engine with that string, afterwards search Linux kernel mailing
903 lists via `lore.kernel.org/all/ <https://lore.kernel.org/all/>`_.
910 In the end, most trouble you are to run into has likely been encountered and
915 Package your kernel up argument
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.
934 step-by-step guide's instructions on installing and removing your kernel;
940 distribution's kernel packages.
942 [:ref:`back to step-by-step guide <build_sbs>`]
946 Install your kernel
947 -------------------
949 *Now install your kernel* [:ref:`... <install_sbs>`]
951 What you need to do after executing the command in the step-by-step guide
953 executable. Many commodity Linux distributions ship such a kernel installer in
956 only part of the job -- and a few lack it completely and leave all the work to
959 If ``installkernel`` is found, the kernel's build system will delegate the
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
969 guide, as things will go sideways if you install your kernel's image before its
970 modules. Often installkernel will then add your kernel to the bootloader
975 installkernel executable. On those just install the modules using the kernel's
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)
983 your kernel using the tools your distribution provides for this process.
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
998 kernel builds, as you already created a trimmed down configuration you want to
1000 adjust your build configurations to the needs of the kernel version you are
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
1008 [:ref:`back to step-by-step guide <another_sbs>`]
1012 Uninstall the kernel later
1013 --------------------------
1015 *All parts of your installed kernel are identifiable by its release name and
1018 Do not worry installing your kernel manually and thus bypassing your
1020 your kernel are easy to remove later, as files are stored in two places only and
1021 normally identifiable by the kernel's release name.
1023 One of the two places is a directory in /lib/modules/, which holds the modules
1024 for each installed kernel. This directory is named after the kernel's release
1026 modules directory in /lib/modules/.
1029 during installation of a kernel. All of them usually contain the release name in
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 --
1034 and the entry for your kernel in the bootloader configuration at the same time,
1036 command should interactively remove the two main files of a kernel with the
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
1044 name and delete them as well. Now remove the kernel from your bootloader's
1048 for kernels manually: you might accidentally remove files of a 6.0.11 kernel
1051 [:ref:`back to step-by-step guide <uninstall_sbs>`]
1058 Why does this 'how-to' not work on my system?
1059 ---------------------------------------------
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
1066 hundreds of constructs along the lines of 'in case you are having <insert
1072 additional use-case is worth describing, suggest it to the maintainers of this
1077 end-of-content
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,
1089 please use 'The Linux kernel development community' for author attribution
1091 …https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/plain/Documentation/admin-guide…
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