Package: release.debian.org Severity: normal User: release.debian....@packages.debian.org Usertags: unblock X-Debbugs-Cc: kernel-handb...@packages.debian.org, debian-ker...@lists.debian.org Control: affects -1 + src:kernel-handbook
Please unblock package kernel-handbook [ Reason ] The current debian-kernel-handbook package has some outdated and confusing information and instructions that cause people to waste time when trying to rebuild linux source packages. [ Impact ] Wasting users' time and computing resources. [ Tests ] This package contains documentation in HTML pages. I have re-read them and tested the new instructions. [ Risks ] This package contains documentation in HTML pages. If the new instructions are wrong, that would also waste resources. [ Checklist ] [X] all changes are documented in the d/changelog [X] I reviewed all changes and I approve them [X] attach debdiff against the package in testing [ Other info ] unblock kernel-handbook/1.0.21
diff -Nru kernel-handbook-1.0.20/chapter-common-tasks.dbk kernel-handbook-1.0.21/chapter-common-tasks.dbk --- kernel-handbook-1.0.20/chapter-common-tasks.dbk 2022-07-18 19:37:14.000000000 +0200 +++ kernel-handbook-1.0.21/chapter-common-tasks.dbk 2023-05-08 23:05:29.000000000 +0200 @@ -5,8 +5,7 @@ <title>Common kernel-related tasks</title> <section id="s-common-getting"><title>Obtaining the Debian kernel source</title> <para> -To get the Debian kernel source at the current maximum patchlevel, it is -sufficient to install the latest +To get the Debian kernel source, it is sufficient to install the latest <package>linux-source-<replaceable>version</replaceable></package> package and unpack the source, for example: </para> @@ -20,18 +19,266 @@ </para> </section> +<section id="s-common-building"><title>Building a custom kernel from Debian kernel source</title> +<para> +This section describes the simplest possible procedure to build a custom kernel +the "Debian way". It is assumed that user is somewhat familiar with kernel +configuration and build process. If that's not the case, it is recommended to +consult the kernel documentation and many excellent online resources dedicated +to it. +</para> +<para> +The easiest way to build a custom kernel (the kernel with the configuration +different from the one used in the official packages) from the Debian kernel +source is to use the <package>linux-source</package> package and the +<command>make bindeb-pkg</command> target. First, prepare the kernel tree: +</para> +<screen> +<prompt>#</prompt> <userinput>apt-get install linux-source-4.3</userinput> +<prompt>$</prompt> <userinput>tar xaf /usr/src/linux-source-4.3.tar.xz</userinput> +<prompt>$</prompt> <userinput>cd linux-source-4.3</userinput> +</screen> +<para> +The kernel now needs to be configured, that is you have to set the kernel +options and select the drivers which are going to be included, either as +built-in, or as external modules. +</para> +<para> +It is possible to reuse an old configuration file by placing it as a +<filename>.config</filename> file in the top-level directory. +Alternately, you can use the default configuration for the +architecture (<command>make defconfig</command>) or generate a +configuration based on the running kernel and the currently loaded +modules (<command>make localmodconfig</command>). +</para> +<para> +If you reuse a Debian kernel config file, you may need to disable +module signing (<command>scripts/config --disable +MODULE_SIG</command>) or enable signing with an ephemeral key +(<command>scripts/config --set-str MODULE_SIG_KEY +certs/signing_key.pem</command>). The build will use less time and +disk space (see <xref linkend="s-common-size"/>) if debug information +is disabled (<command>scripts/config --disable DEBUG_INFO</command>). +Debuginfo is only needed if you plan to use binary object tools like +crash, kgdb, and SystemTap on the kernel. +</para> +<para> +The kernel build infrastructure offers a number of targets, which +invoke different configuration frontends. For example, one can use +console-based menu configuration by invoking the command +</para> +<screen> +<prompt>$</prompt> <userinput>make nconfig</userinput> +</screen> +<para> +Instead of <literal>nconfig</literal> one can use <literal>oldconfig</literal> +(text-based line-by-line configuration frontend) or <literal>xconfig</literal> +(graphical configuration frontend). Note that different frontends may require different additional +libraries and utilities to be installed to function properly. For example, the +<literal>nconfig</literal> frontend requires the <literal>ncurses</literal> +library, which is provided by the <package>libncurses-dev</package> package. +</para> +<para> +After the configuration process is finished, the new or updated kernel +configuration will be stored in <filename>.config</filename> file in the +top-level directory. The build is started using the commands +</para> +<screen> +<prompt>$</prompt> <userinput>make clean</userinput> +<prompt>$</prompt> <userinput>make bindeb-pkg</userinput> +</screen> +<para> +As a result of the build, a custom kernel package +<filename>linux-image-3.2.19_3.2.19-1_i386.deb</filename> (name will reflect the +version of the kernel and build number) will be created in the directory one +level above the top of the tree. It may be installed using +<command>dpkg</command> just as any other package: +</para> +<screen> +<prompt>#</prompt> <userinput>dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb</userinput> +</screen> +<para> +This command will unpack the kernel, generate the initrd if necessary (see +<xref linkend="ch-initramfs"/> for details), and configure the bootloader to make +the newly installed kernel the default one. If this command completed without +any problems, you can reboot using the +</para> +<screen> +<prompt>#</prompt> <userinput>shutdown -r now</userinput> +</screen> +<para> +command to boot the new kernel. +</para> +<para> +For much more information about bootloaders and their configuration please +check their documentation. For GRUB this can be accessed using the command +<command>info grub</command>. You can also look for documentation in the +<filename>/usr/share/doc/<replaceable>package</replaceable></filename> directories, +with <replaceable>package</replaceable> being the name of the +package involved. +</para> +</section> + +<section id="s-kernel-org-package"><title>Building a custom kernel from the "pristine" kernel source</title> +<para> +Building a kernel from the "pristine" (also sometimes called "vanilla") kernel +source, distributed from <ulink +url="https://www.kernel.org";>www.kernel.org</ulink> and its mirrors, may be +occasionally useful for debugging or in the situations when a newer kernel +version is desired. The procedure differs only in obtaining the kernel source: +instead of unpacking the kernel source from Debian packages, the "pristine" +source is downloaded using your favourite browser or using wget, as follows: +</para> +<screen> +<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.xz</userinput> +</screen> +<para> +The integrity of the downloaded archive may be verified by fetching the +corresponding cryptographic signature +</para> +<screen> +<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.sign</userinput> +</screen> +<para> +and running this command (<package>gnupg</package> package must be installed): +</para> +<screen> +<prompt>$</prompt> <userinput>unxz -c linux-4.3.tar.xz | gpg --verify linux-4.3.tar.sign -</userinput> +</screen> +<para> +Successful verification results in output similar to the one below: +</para> +<screen> +<computeroutput>gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886 +gpg: Good signature from "Linus Torvalds <torva...@linux-foundation.org>" +gpg: WARNING: This key is not certified with a trusted signature! +gpg: There is no indication that the signature belongs to the owner. +Primary key fingerprint: ABAF 11C6 5A29 70B1 30AB E3C4 79BE 3E43 0041 1886</computeroutput> +</screen> +<para> +After that the archive may be unpacked using +</para> +<screen> +<prompt>$</prompt> <userinput>tar xaf linux-4.3.tar.xz</userinput> +<prompt>$</prompt> <userinput>cd linux-4.3</userinput> +</screen> +<para> +The unpacked kernel tree (in <filename>linux-4.3</filename>) can now be +configured and built, in the same way described in the previous section. +</para> +</section> +<section id="s-common-out-of-tree"><title>Out-of-tree kernel modules</title> +<para> +Some kernel modules are not included in the upstream or Debian kernel source, +but are provided as third-party source packages. +There is a fair chance that the Debian archive contains the +<emphasis>source</emphasis> for the kernel modules, packaged for use +with the Dynamic Kernel Module System (DKMS), with a package name +ending with <literal>-dkms</literal>. Alternatively, it might be +packaged for use with Debian's module-assistant (m-a), with a package +name ending with <literal>-source</literal>. +</para> + +<section id="s-common-out-of-tree-dkms"><title>Building modules with DKMS</title> +<para> +Check the current kernel release by running <command>uname +-r</command>. If it shows, for example, +<literal>5.10.0-16-amd64</literal>, you need the package +<package>linux-headers-5.10.0-16-amd64</package>. However, usually +you should not install this directly. Instead, note the "flavour" +name that appears after the four numbers, which in this case is +<literal>amd64</literal>. You can then run: +</para> +<screen> +<prompt>#</prompt> <userinput>apt-get install linux-headers-<replaceable>flavour</replaceable> <replaceable>module-name</replaceable>-dkms</userinput> +</screen> +<para> +The installation of these packages will automatically invoke DKMS to +build and install the module(s) for the current kernel release. +Future kernel package upgrades will also automatically invoke DKMS to +rebuild and install the module(s). +</para> +</section> + +<section id="s-common-out-of-tree-m-a"><title>Building modules with module-assistant</title> +<para> +First, install module-assistant: +</para> +<screen> +<prompt>#</prompt> <userinput>apt-get install module-assistant</userinput> +</screen> +<para> +To build a custom binary module package for the currently running +kernel: +</para> +<screen> +<prompt>#</prompt> <userinput>m-a a-i <replaceable>module-name</replaceable>-source</userinput> +</screen> +<para> +Check out the <command>module-assistant</command> documentation (<command>man +module-assistant</command>) for other options and much more information on how +to use it. +</para> +</section> + +<section id="s-common-out-of-tree-unpackaged"><title>Building unpackaged modules</title> +<para> +In some rare circumstances, you might need to build the kernel modules +from the upstream source packages. In that case, follow the documentation +included with the package to build the modules. If the build process will +require you to specify the directory with the kernel headers, matching the +currently running kernel, for stock Debian kernels this directory is +<filename>/usr/src/linux-headers-<replaceable>uname</replaceable></filename>, provided +by the <package>linux-headers-<replaceable>uname</replaceable></package> package. +Here <replaceable>uname</replaceable> is the output of the +<command>uname -r</command> command. If you are building and running your own +custom kernels, it is a good idea to keep the original build tree around, as it +also can be used for out-of-tree module building. +</para> +</section> + +<section id="s-common-out-of-tree-signing"><title>Out-of-tree modules and Secure Boot</title> +<para> +In case your computer has UEFI Secure Boot enabled, the Debian +packaged kernel will normally only allow modules signed by a trusted +key to be loaded. In order to load the modules you build, you need +to either: +</para> +<itemizedlist> +<listitem> +<para> +Generate a signing key, add it to the trust list of your computer, and +use it to sign all out-of-tree modules; or +</para> +</listitem> +<listitem> +<para> +Disable Secure Boot enforcement +</para> +</listitem> +</itemizedlist> +<para> +Both options are documented on the Debian wiki's +<ulink +url="https://wiki.debian.org/SecureBoot#MOK_-_Machine_Owner_Key";>SecureBoot +page, under "MOK - Machine Owner Key"</ulink>. +</para> +</section> + +</section> + <section id="s-common-official"><title>Rebuilding official Debian kernel packages</title> <para> You can build all or selected kernel packages by following these instructions. You may be asked to do this in order to test a potential bug fix. </para> -<section id="s4.2.1"><title>Preparation</title> +<section><title>Preparation</title> <para> Run the following commands: </para> <variablelist> <varlistentry> -<term><prompt>#</prompt> <userinput>apt-get install build-essential fakeroot</userinput></term> +<term><prompt>#</prompt> <userinput>apt-get install build-essential</userinput></term> <term><prompt>#</prompt> <userinput>apt-get build-dep linux</userinput></term> <listitem> <para> @@ -45,10 +292,7 @@ <para> This will download and unpack the <package>linux</package> source package, making the tree available in the -<filename>linux-<replaceable>version</replaceable></filename> directory. As always, -the revision part of the version of this package (for example, 1 in 3.2.19-1) -will determine its patchlevel with respect to the original upstream kernel -source. +<filename>linux-<replaceable>version</replaceable></filename> directory. </para> </listitem> </varlistentry> @@ -60,6 +304,14 @@ </para> </listitem> </varlistentry> +<varlistentry> +<term><prompt>$</prompt> <userinput>export MAKEFLAGS=-j$(nproc)</userinput></term> +<listitem> +<para> +Enable parallel builds using one job per CPU by default. +</para> +</listitem> +</varlistentry> </variablelist> <section id="s-common-size"><title>Disk space requirements</title> <para> @@ -69,7 +321,14 @@ </para> <para> Building with debug info disabled requires about 2 GB and 25 MB respectively. -You can disable debug info by changing the value of +In packages of kernel version 5.17 or later, you can disable building +debug info through build profiles: +</para> +<screen> +<prompt>$</prompt> <userinput>export DEB_BUILD_PROFILES='pkg.linux.nokerneldbg pkg.linux.nokerneldbginfo'</userinput> +</screen> +<para> +In older package versions, you must change the value of <literal>debug-info</literal> to <literal>false</literal> in <filename>debian/config/<replaceable>arch</replaceable>/defines</filename>, if it's set there, or in @@ -84,29 +343,59 @@ </section> -<section id="s4.2.2"><title>Simple patching and building</title> +<section><title>Simple patching and building</title> <para> The source package includes a script to simplify the process of building with extra patches. You can use this by running commands such as: </para> <screen> <prompt>#</prompt> <userinput>apt-get install devscripts</userinput> -<prompt>$</prompt> <userinput>bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput> +<prompt>$</prompt> <userinput>debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput> </screen> <para> This script has options to control the flavour, featureset, etc. For a summary of the options, run: </para> <screen> -<prompt>$</prompt> <userinput>bash debian/bin/test-patches</userinput> +<prompt>$</prompt> <userinput>debian/bin/test-patches</userinput> </screen> <para> However, if you need to change the configuration or make other changes, you should not use this script and should follow the instructions below. </para> +<warning> +<para> +Older versions of the <command>test-patches</command> script (before +package version 6.1.27-1), have some important bugs and limitations: +</para> +<itemizedlist> +<listitem> +<para> +The <package>linux-image</package> package it builds will usually +replace or conflict with the currently installed kernel package. +</para> +</listitem> +<listitem> +<para> +The <package>linux-headers</package> package it builds won't be +installable. +</para> +</listitem> +<listitem> +<para> +In package versions from 5.17 onward, it is not possible to disable +building debug info. +</para> +</listitem> +</itemizedlist> +<para> +To avoid these bugs in older versions of the source package, follow +the instructions below. +</para> +</warning> </section> -<section id="s4.2.3"><title>Applying patches or configuration changes</title> +<section><title>Applying patches or configuration changes</title> <para> It is possible to apply extra patches to the source before starting the build. In the <package>linux</package> source package, the default (non-featureset) @@ -139,48 +428,49 @@ <command>quilt</command> utility to do this. </para> <para> +You should also change the ABI name so that the resulting packages are +co-installable with the current kernel packages; see <xref +linkend="s-abi-name"/>. +</para> +<para> To change the configuration before building, for example for the 686-pae flavour on i386, run the commands: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen setup_i386_none_686-pae</userinput> +<prompt>$</prompt> <userinput>make -f debian/rules.gen setup_i386_none_686-pae</userinput> <prompt>$</prompt> <userinput>make -C debian/build/build_i386_none_686-pae nconfig</userinput> </screen> -<para> -If the patches or configuration changes alter type definitions for the kernel, -you may need to change the ABI name; see <xref linkend="s-abi-name"/>. -</para> </section> -<section id="s4.2.4"><title>Building many packages</title> +<section><title>Building many packages</title> <para> To build all possible packages for this architecture, run: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules binary</userinput> +<prompt>$</prompt> <userinput>dpkg-buildpackage -b -nc -uc</userinput> </screen> <para> To build all architecture-dependent packages, run: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules binary-arch</userinput> +<prompt>$</prompt> <userinput>dpkg-buildpackage -B -nc -uc</userinput> </screen> <para> To build all architecture-independent packages, run: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules binary-indep</userinput> +<prompt>$</prompt> <userinput>dpkg-buildpackage -A -nc -uc</userinput> </screen> </section> -<section id="s4.2.5"><title>Building packages for one flavour</title> +<section><title>Building packages for one flavour</title> <para> For example, to build only the binary packages for 686-pae flavour on i386 architecture, use the following commands: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput> -<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput> +<prompt>$</prompt> <userinput>debian/rules source</userinput> +<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput> </screen> <para> The target in this command has the general form of @@ -192,12 +482,12 @@ binary package, which can be built using the commands: </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput> -<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_real</userinput> +<prompt>$</prompt> <userinput>debian/rules source</userinput> +<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-indep_none_real</userinput> </screen> <para> The target in this command has the general form of -<literal><replaceable>target</replaceable>_<replaceable>arch</replaceable>_<replaceable>featureset</replaceable>_<replaceable>real</replaceable></literal> +<literal>binary-indep_<replaceable>featureset</replaceable>_real</literal> </para> </section> @@ -210,7 +500,7 @@ </para> <variablelist> <varlistentry> -<term><prompt>#</prompt> <userinput>apt-get install build-essential fakeroot rsync git</userinput></term> +<term><prompt>#</prompt> <userinput>apt-get install build-essential rsync git</userinput></term> <term><prompt>#</prompt> <userinput>apt-get build-dep linux</userinput></term> <listitem> <para> @@ -261,7 +551,7 @@ </listitem> </varlistentry> <varlistentry> -<term><prompt>$</prompt> <userinput>fakeroot debian/rules <replaceable>target</replaceable></userinput></term> +<term><prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no debian/rules <replaceable>target</replaceable></userinput></term> <listitem> <para> Finally, build binary packages as explained in <xref @@ -298,253 +588,5 @@ </screen> </section> -<section id="s-common-building"><title>Building a custom kernel from Debian kernel source</title> -<para> -This section describes the simplest possible procedure to build a custom kernel -the "Debian way". It is assumed that user is somewhat familiar with kernel -configuration and build process. If that's not the case, it is recommended to -consult the kernel documentation and many excellent online resources dedicated -to it. -</para> -<para> -The easiest way to build a custom kernel (the kernel with the configuration -different from the one used in the official packages) from the Debian kernel -source is to use the <package>linux-source</package> package and the -<command>make bindeb-pkg</command> target. First, prepare the kernel tree: -</para> -<screen> -<prompt>#</prompt> <userinput>apt-get install linux-source-4.3</userinput> -<prompt>$</prompt> <userinput>tar xaf /usr/src/linux-source-4.3.tar.xz</userinput> -<prompt>$</prompt> <userinput>cd linux-source-4.3</userinput> -</screen> -<para> -The kernel now needs to be configured, that is you have to set the kernel -options and select the drivers which are going to be included, either as -built-in, or as external modules. -</para> -<para> -It is possible to reuse an old configuration file by placing it as a -<filename>.config</filename> file in the top-level directory. -Alternately, you can use the default configuration for the -architecture (<command>make defconfig</command>) or generate a -configuration based on the running kernel and the currently loaded -modules (<command>make localmodconfig</command>). -</para> -<para> -If you reuse a Debian kernel config file, you may need to disable -module signing (<command>scripts/config --disable -MODULE_SIG</command>) or enable signing with an ephemeral key -(<command>scripts/config --set-str MODULE_SIG_KEY -certs/signing_key.pem</command>). The build will use less time and -disk space (see <xref linkend="s-common-size"/>) if debug information -is disabled (<command>scripts/config --disable DEBUG_INFO</command>). -Debuginfo is only needed if you plan to use binary object tools like -crash, kgdb, and SystemTap on the kernel. -</para> -<para> -The kernel build infrastructure offers a number of targets, which -invoke different configuration frontends. For example, one can use -console-based menu configuration by invoking the command -</para> -<screen> -<prompt>$</prompt> <userinput>make nconfig</userinput> -</screen> -<para> -Instead of <literal>nconfig</literal> one can use <literal>oldconfig</literal> -(text-based line-by-line configuration frontend) or <literal>xconfig</literal> -(graphical configuration frontend). Note that different frontends may require different additional -libraries and utilities to be installed to function properly. For example, the -<literal>nconfig</literal> frontend requires the <literal>ncurses</literal> -library, which is provided by the <package>libncurses-dev</package> package. -</para> -<para> -After the configuration process is finished, the new or updated kernel -configuration will be stored in <filename>.config</filename> file in the -top-level directory. The build is started using the commands -</para> -<screen> -<prompt>$</prompt> <userinput>make clean</userinput> -<prompt>$</prompt> <userinput>make bindeb-pkg</userinput> -</screen> -<para> -As a result of the build, a custom kernel package -<filename>linux-image-3.2.19_3.2.19-1_i386.deb</filename> (name will reflect the -version of the kernel and build number) will be created in the directory one -level above the top of the tree. It may be installed using -<command>dpkg</command> just as any other package: -</para> -<screen> -<prompt>#</prompt> <userinput>dpkg -i ../linux-image-3.2.19_3.2.19-1_i386.deb</userinput> -</screen> -<para> -This command will unpack the kernel, generate the initrd if necessary (see -<xref linkend="ch-initramfs"/> for details), and configure the bootloader to make -the newly installed kernel the default one. If this command completed without -any problems, you can reboot using the -</para> -<screen> -<prompt>#</prompt> <userinput>shutdown -r now</userinput> -</screen> -<para> -command to boot the new kernel. -</para> -<para> -For much more information about bootloaders and their configuration please -check their documentation. For GRUB this can be accessed using the command -<command>info grub</command>. You can also look for documentation in the -<filename>/usr/share/doc/<replaceable>package</replaceable></filename> directories, -with <replaceable>package</replaceable> being the name of the -package involved. -</para> -</section> - -<section id="s-kernel-org-package"><title>Building a custom kernel from the "pristine" kernel source</title> -<para> -Building a kernel from the "pristine" (also sometimes called "vanilla") kernel -source, distributed from <ulink -url="https://www.kernel.org";>www.kernel.org</ulink> and its mirrors, may be -occasionally useful for debugging or in the situations when a newer kernel -version is desired. The procedure differs only in obtaining the kernel source: -instead of unpacking the kernel source from Debian packages, the "pristine" -source is downloaded using your favourite browser or using wget, as follows: -</para> -<screen> -<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.xz</userinput> -</screen> -<para> -The integrity of the downloaded archive may be verified by fetching the -corresponding cryptographic signature -</para> -<screen> -<prompt>$</prompt> <userinput>wget https://kernel.org/pub/linux/kernel/v4.x/linux-4.3.tar.sign</userinput> -</screen> -<para> -and running this command (<package>gnupg</package> package must be installed): -</para> -<screen> -<prompt>$</prompt> <userinput>unxz -c linux-4.3.tar.xz | gpg --verify linux-4.3.tar.sign -</userinput> -</screen> -<para> -Successful verification results in output similar to the one below: -</para> -<screen> -<computeroutput>gpg: Signature made Mon 21 May 2012 01:48:14 AM CEST using RSA key ID 00411886 -gpg: Good signature from "Linus Torvalds <torva...@linux-foundation.org>" -gpg: WARNING: This key is not certified with a trusted signature! -gpg: There is no indication that the signature belongs to the owner. -Primary key fingerprint: ABAF 11C6 5A29 70B1 30AB E3C4 79BE 3E43 0041 1886</computeroutput> -</screen> -<para> -After that the archive may be unpacked using -</para> -<screen> -<prompt>$</prompt> <userinput>tar xaf linux-4.3.tar.xz</userinput> -<prompt>$</prompt> <userinput>cd linux-4.3</userinput> -</screen> -<para> -The unpacked kernel tree (in <filename>linux-4.3</filename>) can now be -configured and built, in the same way described in the previous section. -</para> -</section> -<section id="s-common-out-of-tree"><title>Out-of-tree kernel modules</title> -<para> -Some kernel modules are not included in the upstream or Debian kernel source, -but are provided as third-party source packages. -There is a fair chance that the Debian archive contains the -<emphasis>source</emphasis> for the kernel modules, packaged for use -with the Dynamic Kernel Module System (DKMS), with a package name -ending with <literal>-dkms</literal>. Alternatively, it might be -packaged for use with Debian's module-assistant (m-a), with a package -name ending with <literal>-source</literal>. -</para> - -<section id="s-common-out-of-tree-dkms"><title>Building modules with DKMS</title> -<para> -Check the current kernel release by running <command>uname --r</command>. If it shows, for example, -<literal>5.10.0-16-amd64</literal>, you need the package -<package>linux-headers-5.10.0-16-amd64</package>. However, usually -you should not install this directly. Instead, note the "flavour" -name that appears after the four numbers, which in this case is -<literal>amd64</literal>. You can then run: -</para> -<screen> -<prompt>#</prompt> <userinput>apt-get install linux-headers-<replaceable>flavour</replaceable> <replaceable>module-name</replaceable>-dkms</userinput> -</screen> -<para> -The installation of these packages will automatically invoke DKMS to -build and install the module(s) for the current kernel release. -Future kernel package upgrades will also automatically invoke DKMS to -rebuild and install the module(s). -</para> -</section> - -<section id="s-common-out-of-tree-m-a"><title>Building modules with module-assistant</title> -<para> -First, install module-assistant: -</para> -<screen> -<prompt>#</prompt> <userinput>apt-get install module-assistant</userinput> -</screen> -<para> -To build a custom binary module package for the currently running -kernel: -</para> -<screen> -<prompt>#</prompt> <userinput>m-a a-i <replaceable>module-name</replaceable>-source</userinput> -</screen> -<para> -Check out the <command>module-assistant</command> documentation (<command>man -module-assistant</command>) for other options and much more information on how -to use it. -</para> -</section> - -<section id="s-common-out-of-tree-unpackaged"><title>Building unpackaged modules</title> -<para> -In some rare circumstances, you might need to build the kernel modules -from the upstream source packages. In that case, follow the documentation -included with the package to build the modules. If the build process will -require you to specify the directory with the kernel headers, matching the -currently running kernel, for stock Debian kernels this directory is -<filename>/usr/src/linux-headers-<replaceable>uname</replaceable></filename>, provided -by the <package>linux-headers-<replaceable>uname</replaceable></package> package. -Here <replaceable>uname</replaceable> is the output of the -<command>uname -r</command> command. If you are building and running your own -custom kernels, it is a good idea to keep the original build tree around, as it -also can be used for out-of-tree module building. -</para> -</section> - -<section id="s-common-out-of-tree-signing"><title>Out-of-tree modules and Secure Boot</title> -<para> -In case your computer has UEFI Secure Boot enabled, the Debian -packaged kernel will normally only allow modules signed by a trusted -key to be loaded. In order to load the modules you build, you need -to either: -</para> -<itemizedlist> -<listitem> -<para> -Generate a signing key, add it to the trust list of your computer, and -use it to sign all out-of-tree modules; or -</para> -</listitem> -<listitem> -<para> -Disable Secure Boot enforcement -</para> -</listitem> -</itemizedlist> -<para> -Both options are documented on the Debian wiki's -<ulink -url="https://wiki.debian.org/SecureBoot#MOK_-_Machine_Owner_Key";>SecureBoot -page, under "MOK - Machine Owner Key"</ulink>. -</para> -</section> - -</section> - </chapter> diff -Nru kernel-handbook-1.0.20/chapter-packaging.dbk kernel-handbook-1.0.21/chapter-packaging.dbk --- kernel-handbook-1.0.20/chapter-packaging.dbk 2017-06-06 00:40:35.000000000 +0200 +++ kernel-handbook-1.0.21/chapter-packaging.dbk 2023-05-08 23:05:29.000000000 +0200 @@ -22,11 +22,8 @@ <term><package>linux-source-<replaceable>version</replaceable></package></term> <listitem> <para> -This package contains the Debian kernel source tarball. The patchlevel of the -source is determined by the Debian revision of the package, for example the -version 4.2.5-1 of the package <package>linux-source-4.2</package> contains -the version 4.2.5 of the Debian kernel source patched to patchlevel 1. Once -the package is installed, the source tarball is available at +This package contains the Debian kernel source tarball. Once the +package is installed, the source tarball is available at <filename>/usr/src/linux-source-<replaceable>version</replaceable>.tar.xz</filename>. </para> </listitem> diff -Nru kernel-handbook-1.0.20/chapter-source.dbk kernel-handbook-1.0.21/chapter-source.dbk --- kernel-handbook-1.0.20/chapter-source.dbk 2016-03-18 18:54:57.000000000 +0100 +++ kernel-handbook-1.0.21/chapter-source.dbk 2023-05-08 23:05:29.000000000 +0200 @@ -41,14 +41,7 @@ <filename>linux_<replaceable>version</replaceable>.orig.tar.xz</filename> (that is, pristine kernel source with problematic parts removed) and applying a set of Debian patches. These patches typically implement essential fixes for serious -bugs and security holes. The Debian version of the kernel packages has the -form <replaceable>version</replaceable><literal>-</literal><replaceable>revision</replaceable> where -<replaceable>version</replaceable> is the upstream version of the -kernel (like 3.2.20) and <replaceable>revision</replaceable> -determines the patchlevel. For example, the packages with version 3.2.20-1 are -built from the <filename>linux_3.2.20.orig.tar.xz</filename> source, patched up -to patchlevel 1. Certain packages include extra 'featuresets' not included in -the upstream source, such as <literal>rt</literal>. +bugs and security holes. </para> </section> diff -Nru kernel-handbook-1.0.20/chapter-versions.dbk kernel-handbook-1.0.21/chapter-versions.dbk --- kernel-handbook-1.0.20/chapter-versions.dbk 2016-03-18 18:54:57.000000000 +0100 +++ kernel-handbook-1.0.21/chapter-versions.dbk 2023-05-08 23:05:29.000000000 +0200 @@ -67,7 +67,18 @@ part of the kernel version to mark ABI changes that aren't due to a new upstream version. This part comes from the <literal>abiname</literal> setting in <filename>debian/config/defines</filename>. We use either a number or 'trunk' -(for experimental), but for a custom package it should be some other string. +(for experimental). +</para> +<para> +If you are rebuilding the package with local modifications, you should +change the ABI name to some other string, for example +<userinput>0.local</userinput>. Then run the command +</para> +<screen> +<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput> +</screen> +<para> +to regenerate the package definitions for this ABI name. </para> </section> @@ -109,7 +120,7 @@ <filename>debian/config/defines</filename>. Then run the command </para> <screen> -<prompt>$</prompt> <userinput>fakeroot debian/rules debian/control-real</userinput> +<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput> </screen> <para> to regenerate the package definitions for this ABI name. diff -Nru kernel-handbook-1.0.20/debian/changelog kernel-handbook-1.0.21/debian/changelog --- kernel-handbook-1.0.20/debian/changelog 2022-10-03 01:56:35.000000000 +0200 +++ kernel-handbook-1.0.21/debian/changelog 2023-05-08 23:17:30.000000000 +0200 @@ -1,3 +1,20 @@ +kernel-handbook (1.0.21) unstable; urgency=medium + + * Try to reduce pain points in rebuilding official kernel packages + (Closes: #1022061): + - Reorder sections in "Common kernel-related tasks" to reduce confusion + - Deprecate older versions of test-patches + - Recommend changing ABI name before rebuilding + - Add command to enable parallel builds when invoking make directly + - Avoid using fakeroot + * Remove obsolete text referring to "patchlevels" in source packages + * Remove redundant "bash" from debian/bin/test-patches command lines + * Update instructions for disabling debug info (Closes: #1023773) + * Update instructions for building linux-headers-common package + * Update copyright years + + -- Ben Hutchings <b...@debian.org> Mon, 08 May 2023 23:17:30 +0200 + kernel-handbook (1.0.20) unstable; urgency=medium [ Tomasz Warniełło ] diff -Nru kernel-handbook-1.0.20/debian/copyright kernel-handbook-1.0.21/debian/copyright --- kernel-handbook-1.0.20/debian/copyright 2022-07-18 16:08:26.000000000 +0200 +++ kernel-handbook-1.0.21/debian/copyright 2023-05-08 23:17:14.000000000 +0200 @@ -1,7 +1,7 @@ Format: https://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ Files: * -Copyright: 2005-2018, 2020, 2022 Debian Kernel Handbook Project +Copyright: 2005-2018, 2020, 2022-2023 Debian Kernel Handbook Project License: GPL-2+ This package is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by diff -Nru kernel-handbook-1.0.20/kernel-handbook.dbk kernel-handbook-1.0.21/kernel-handbook.dbk --- kernel-handbook-1.0.20/kernel-handbook.dbk 2022-07-18 16:08:22.000000000 +0200 +++ kernel-handbook-1.0.21/kernel-handbook.dbk 2023-05-08 23:16:37.000000000 +0200 @@ -21,7 +21,7 @@ <pubdate>&date;</pubdate> -<copyright><year>2005-2018, 2020, 2022</year><holder>Debian Kernel Handbook Project</holder></copyright> +<copyright><year>2005-2018, 2020, 2022-2023</year><holder>Debian Kernel Handbook Project</holder></copyright> <legalnotice> <para> This handbook is free software; you may redistribute it and/or modify it under diff -Nru kernel-handbook-1.0.20/po4a/kernel-handbook.ja.po kernel-handbook-1.0.21/po4a/kernel-handbook.ja.po --- kernel-handbook-1.0.20/po4a/kernel-handbook.ja.po 2022-10-03 00:55:55.000000000 +0200 +++ kernel-handbook-1.0.21/po4a/kernel-handbook.ja.po 2023-05-08 23:05:29.000000000 +0200 @@ -1704,8 +1704,8 @@ #. type: Content of: <chapter><section><section><screen> #: chapter-versions.dbk:112 #, no-wrap -msgid "<prompt>$</prompt> <userinput>fakeroot debian/rules debian/control-real</userinput>\n" -msgstr "<prompt>$</prompt> <userinput>fakeroot debian/rules debian/control-real</userinput>\n" +msgid "<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput>\n" +msgstr "<prompt>$</prompt> <userinput>debian/rules debian/control-real</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-versions.dbk:115 @@ -1908,11 +1908,9 @@ #. type: Content of: <chapter><section><section><variablelist><varlistentry><term> #: chapter-common-tasks.dbk:34 msgid "" -"<prompt>#</prompt> <userinput>apt-get install build-essential fakeroot</" -"userinput>" +"<prompt>#</prompt> <userinput>apt-get install build-essential</userinput>" msgstr "" -"<prompt>#</prompt> <userinput>apt-get install build-essential fakeroot</" -"userinput>" +"<prompt>#</prompt> <userinput>apt-get install build-essential</userinput>" #. type: Content of: <chapter><section><variablelist><varlistentry><term> #: chapter-common-tasks.dbk:35 chapter-common-tasks.dbk:221 @@ -2023,10 +2021,10 @@ #, no-wrap msgid "" "<prompt>#</prompt> <userinput>apt-get install devscripts</userinput>\n" -"<prompt>$</prompt> <userinput>bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput>\n" +"<prompt>$</prompt> <userinput>debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput>\n" msgstr "" "<prompt>#</prompt> <userinput>apt-get install devscripts</userinput>\n" -"<prompt>$</prompt> <userinput>bash debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput>\n" +"<prompt>$</prompt> <userinput>debian/bin/test-patches ../fix-bug123456.patch ../add-foo-driver.patch</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:98 @@ -2040,8 +2038,8 @@ #. type: Content of: <chapter><section><section><screen> #: chapter-common-tasks.dbk:102 #, no-wrap -msgid "<prompt>$</prompt> <userinput>bash debian/bin/test-patches</userinput>\n" -msgstr "<prompt>$</prompt> <userinput>bash debian/bin/test-patches</userinput>\n" +msgid "<prompt>$</prompt> <userinput>debian/bin/test-patches</userinput>\n" +msgstr "<prompt>$</prompt> <userinput>debian/bin/test-patches</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:105 @@ -2133,10 +2131,10 @@ #: chapter-common-tasks.dbk:153 #, no-wrap msgid "" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen setup_i386_none_686-pae</userinput>\n" +"<prompt>$</prompt> <userinput>make -f debian/rules.gen setup_i386_none_686-pae</userinput>\n" "<prompt>$</prompt> <userinput>make -C debian/build/build_i386_none_686-pae nconfig</userinput>\n" msgstr "" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen setup_i386_none_686-pae</userinput>\n" +"<prompt>$</prompt> <userinput>make -f debian/rules.gen setup_i386_none_686-pae</userinput>\n" "<prompt>$</prompt> <userinput>make -C debian/build/build_i386_none_686-pae nconfig</userinput>\n" #. type: Content of: <chapter><section><section><para> @@ -2164,8 +2162,8 @@ #. type: Content of: <chapter><section><section><screen> #: chapter-common-tasks.dbk:167 #, no-wrap -msgid "<prompt>$</prompt> <userinput>fakeroot debian/rules binary</userinput>\n" -msgstr "<prompt>$</prompt> <userinput>fakeroot debian/rules binary</userinput>\n" +msgid "<prompt>$</prompt> <userinput>dpkg-buildpackage -b -nc -uc</userinput>\n" +msgstr "<prompt>$</prompt> <userinput>dpkg-buildpackage -b -nc -uc</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:170 @@ -2177,8 +2175,8 @@ #. type: Content of: <chapter><section><section><screen> #: chapter-common-tasks.dbk:173 #, no-wrap -msgid "<prompt>$</prompt> <userinput>fakeroot debian/rules binary-arch</userinput>\n" -msgstr "<prompt>$</prompt> <userinput>fakeroot debian/rules binary-arch</userinput>\n" +msgid "<prompt>$</prompt> <userinput>dpkg-buildpackage -B -nc -uc</userinput>\n" +msgstr "<prompt>$</prompt> <userinput>dpkg-buildpackage -B -nc -uc</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:176 @@ -2190,8 +2188,8 @@ #. type: Content of: <chapter><section><section><screen> #: chapter-common-tasks.dbk:179 #, no-wrap -msgid "<prompt>$</prompt> <userinput>fakeroot debian/rules binary-indep</userinput>\n" -msgstr "<prompt>$</prompt> <userinput>fakeroot debian/rules binary-indep</userinput>\n" +msgid "<prompt>$</prompt> <userinput>dpkg-buildpackage -A -nc -uc</userinput>\n" +msgstr "<prompt>$</prompt> <userinput>dpkg-buildpackage -A -nc -uc</userinput>\n" #. type: Content of: <chapter><section><section><title> #: chapter-common-tasks.dbk:183 @@ -2211,11 +2209,11 @@ #: chapter-common-tasks.dbk:189 #, no-wrap msgid "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput>\n" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput>\n" +"<prompt>$</prompt> <userinput>debian/rules source</userinput>\n" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput>\n" msgstr "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput>\n" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput>\n" +"<prompt>$</prompt> <userinput>debian/rules source</userinput>\n" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_686-pae</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:193 @@ -2244,11 +2242,11 @@ #: chapter-common-tasks.dbk:202 #, no-wrap msgid "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput>\n" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_real</userinput>\n" +"<prompt>$</prompt> <userinput>debian/rules source</userinput>\n" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_real</userinput>\n" msgstr "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules source</userinput>\n" -"<prompt>$</prompt> <userinput>fakeroot make -f debian/rules.gen binary-arch_i386_none_real</userinput>\n" +"<prompt>$</prompt> <userinput>debian/rules source</userinput>\n" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no make -f debian/rules.gen binary-arch_i386_none_real</userinput>\n" #. type: Content of: <chapter><section><section><para> #: chapter-common-tasks.dbk:206 @@ -2280,10 +2278,10 @@ #. type: Content of: <chapter><section><variablelist><varlistentry><term> #: chapter-common-tasks.dbk:220 msgid "" -"<prompt>#</prompt> <userinput>apt-get install build-essential fakeroot rsync " +"<prompt>#</prompt> <userinput>apt-get install build-essential rsync " "git</userinput>" msgstr "" -"<prompt>#</prompt> <userinput>apt-get install build-essential fakeroot rsync " +"<prompt>#</prompt> <userinput>apt-get install build-essential rsync " "git</userinput>" #. type: Content of: <chapter><section><variablelist><varlistentry><listitem><para> @@ -2372,10 +2370,10 @@ #. type: Content of: <chapter><section><variablelist><varlistentry><term> #: chapter-common-tasks.dbk:271 msgid "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules <replaceable>target</" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no debian/rules <replaceable>target</" "replaceable></userinput>" msgstr "" -"<prompt>$</prompt> <userinput>fakeroot debian/rules <replaceable>target</" +"<prompt>$</prompt> <userinput>DEB_RULES_REQUIRES_ROOT=no debian/rules <replaceable>target</" "replaceable></userinput>" #. type: Content of: <chapter><section><variablelist><varlistentry><listitem><para>
