Lines Matching +full:debian +full:- +full:build +full:- +full:testing
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.
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
24 you then use to configure, build and install your own kernel::
26 git clone --depth 1 -b master \
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
45 git checkout --force --detach origin/master
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
65 The described approach is great for testing purposes, for example to try a
67 Nonetheless, kernels built this way are also totally fine for day-to-day use
73 that might occur at a particular point -- and how to then get things rolling
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
97 ``mokutil --disable-validation``.
103 * Install all software required to build a Linux kernel. Often you will need:
115 sources and build artifacts 12 Gigabyte in your home directory should
117 section for the step that explains adjusting your kernels build
125 * Retrieve the sources of the Linux version you intend to build; then change
139 git clone --no-checkout --depth 1 -b master \
143 If you want to access recent mainline releases and pre-releases, deepen you
146 git fetch --shallow-exclude=v6.0 origin
152 git remote set-branches --add origin linux-6.1.y
153 git fetch --shallow-exclude=v6.0 origin
159 git checkout --detach origin/master
163 pre-release like ``v6.2-rc1`` will work, too. Stable or longterm versions
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'.
198 * Create the build configuration for your kernel based on an existing
208 Using this make target is fine for everybody else, too -- but you often can
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
241 * Are you running Debian? Then to avoid known problems by performing
251 * Build the image and the modules of your kernel::
253 make -j $(nproc --all)
258 [:ref:`details<build>`]
264 command -v installkernel && sudo make modules_install install
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
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
314 # reminder: you might want to update your build tag at this point
317 Now build your kernel::
319 make -j $(nproc --all)
323 command -v installkernel && sudo make modules_install install
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/.
356 Linux docs mailing list (linux-doc@vger.kernel.org). Such feedback is vital to
360 Reference section for the step-by-step guide
369 -----------------------
375 -- especially if you fiddle with crucial parts like the kernel of an operating
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
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>`]
420 Install build requirements
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.
434 * Debian, Ubuntu, and derivatives::
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
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 --------------------
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
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
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=``
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
534 automatically when using ``--shallow-since=`` or
535 ``--depth=``.
539 In that case run ``git repack -d`` and try again``
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'
555 sources. It actually can be, if you are certain to build just one particular
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.
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
611 not get any significant extra testing before being published.
614 (say v6.1) before its successor's first pre-release (v6.2-rc1) is out. That is
619 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
639 git checkout --detach mainline/master
644 [:ref:`back to step-by-step guide <sources_sbs>`] [:ref:`back to section intro <sources>`]
649 ----------------------------
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 ------------------------------------------------
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
675 build scripts will automatically pick up the tag. You can later change that file
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
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
718 localmodconfig will set any undefined build options to their default value. This
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
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
748 testing purposes: everything typically crucial will be there. And if you forget
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
768 as well and place it as .config in your build directory.
770 [:ref:`back to step-by-step guide <configuration_sbs>`]
774 Adjust build configuration
775 --------------------------
799 quite a bit of space: in late 2022 the build artifacts for a typical x86 kernel
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
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
837 **Debian:**
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>`]
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>`]
880 Dealing with build errors
883 When a build error occurs, it might be caused by some aspect of your machine's
887 which of the two it is. To perform such a investigation, restart the build
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
897 After a few seconds the build process should run into the error again. Now try
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
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
920 steps of the guide then install. You instead can also directly build everything
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;
936 (e.g. dpkg and rpm) or a package management utility build on top of them (apt,
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
959 If ``installkernel`` is found, the kernel's build system will delegate the
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
968 hence be sure to keep the order of the two make targets used in the step-by-step
976 build system and then install the image and the System.map file manually::
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)
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
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
1008 [:ref:`back to step-by-step guide <another_sbs>`]
1013 --------------------------
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 --
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
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
1072 additional use-case is worth describing, suggest it to the maintainers of this
1077 end-of-content
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
1095 (for example by the kernel's build system) might contain content taken from