Minki/linux
1
0
Fork 1
mirror of https://github.com/torvalds/linux.git synced 2024-11-24 21:21:41 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: verify/bisect: fixes, finetuning, and support for Arch

Browse Source 
Assorted changes for the recently added document.

Improvements:

* Add instructions for installing required software on Arch Linux.

Fixes:

* Move a 'git remote add -t master stable [...]' from a totally wrong
  to the right place.

* Fix two anchors.

* Add two required packages to the openSUSE install instructions.

Fine tuning:

* Improve the reference section about downloading Linux mainline sources
  to make it more obvious that those are alternatives.

* Include the full instructions for git bundles to ensure the remote
  gets the right name; that way the text also works stand alone.

* Install ncurses and qt headers for use of menuconfig and xconfig by
  default, but tell users that they are free to omit them.

* Mention ahead of time which version number are meant as example in
  commands used during the step-by-step guide.

* Mention that 'kernel-install remove' might do a incomplete job.

Signed-off-by: Thorsten Leemhuis <linux@leemhuis.info>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>
Message-ID: <6592c9ef4244faa484b4113f088dbc1beca61015.1709716794.git.linux@leemhuis.info>
This commit is contained in:
Thorsten Leemhuis 2024-03-06 10:21:12 +01:00 committed by Jonathan Corbet
parent a304fa1d10
commit 0c8e9b538e
1 changed files with 84 additions and 51 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

135
Documentation/admin-guide/verify-bugs-and-bisect-regressions.rst
View File

@ -192,8 +192,8 @@ will be considered the 'good' release and used to prepare the .config file.
sudo rm -rf /lib/modules/6.0-rc1-local-gcafec0cacaca0 sudo rm -rf /lib/modules/6.0-rc1-local-gcafec0cacaca0
sudo kernel-install -v remove 6.0-rc1-local-gcafec0cacaca0 sudo kernel-install -v remove 6.0-rc1-local-gcafec0cacaca0
# * Note, if kernel-install is missing, you will have to # * Note, on some distributions kernel-install is missing
# manually remove the kernel image and related files. # or does only part of the job.
b) If you performed a bisection and successfully validated the result, feel b) If you performed a bisection and successfully validated the result, feel
free to remove all kernels built during the actual bisection (Segment 3 c); free to remove all kernels built during the actual bisection (Segment 3 c);
@ -348,11 +348,14 @@ Preparations: set up everything to build your own kernels
one downloads less than 500 MByte, the other works better with unreliable one downloads less than 500 MByte, the other works better with unreliable
internet connections.* internet connections.*
Execute the following command to retrieve a fresh mainline codebase:: Execute the following command to retrieve a fresh mainline codebase while
preparing things to add stable/longterm branches later::
git clone -o mainline --no-checkout \ git clone -o mainline --no-checkout \
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/
cd ~/linux/ cd ~/linux/
git remote add -t master stable \
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
[:ref:`details<sources_bisref>`] [:ref:`details<sources_bisref>`]
@ -365,7 +368,7 @@ Preparations: set up everything to build your own kernels
identifier using ``uname -r``. identifier using ``uname -r``.
Afterwards check out the source code for the version earlier established as Afterwards check out the source code for the version earlier established as
'good' and create a .config file:: 'good' (in this example this is assumed to be 6.0) and create a .config file::
git checkout --detach v6.0 git checkout --detach v6.0
make olddefconfig make olddefconfig
@ -462,8 +465,10 @@ Preparations: set up everything to build your own kernels
[:ref:`details<configmods_distros_bisref>`]. [:ref:`details<configmods_distros_bisref>`].
* If you want to influence other aspects of the configuration, do so now * If you want to influence other aspects of the configuration, do so now using
by using make targets like 'menuconfig' or 'xconfig'. your preferred tool. Note, to use make targets like 'menuconfig' or
'nconfig', you will need to install the development files of ncurses; for
'xconfig' you likewise need the Qt5 or Qt6 headers.
[:ref:`details<configmods_individual_bisref>`]. [:ref:`details<configmods_individual_bisref>`].
@ -601,8 +606,8 @@ be a waste of time. [:ref:`details<introlatestcheck_bisref>`]
* Are you facing a problem within a stable/longterm release, but failed to * Are you facing a problem within a stable/longterm release, but failed to
reproduce it with the mainline kernel you just built? Then check if the latest reproduce it with the mainline kernel you just built? Then check if the latest
codebase for the particular series might already fix the problem. To do so, codebase for the particular series might already fix the problem. To do so,
add the stable series Git branch for your 'good' kernel and check out the add the stable series Git branch for your 'good' kernel (again, this here is
latest version:: assumed to be 6.0) and check out the latest version::
cd ~/linux/ cd ~/linux/
git remote set-branches --add stable linux-6.0.y git remote set-branches --add stable linux-6.0.y
@ -652,7 +657,7 @@ otherwise would be a waste of time. [:ref:`details<introworkingcheck_bisref>`]
regressed works as expected with it. regressed works as expected with it.
Start by checking out the sources for the version earlier established as Start by checking out the sources for the version earlier established as
'good':: 'good' (once again assumed to be 6.0 here)::
cd ~/linux/ cd ~/linux/
git checkout --detach v6.0 git checkout --detach v6.0
@ -697,15 +702,13 @@ each kernel on commodity x86 machines.
stable branch, unless you already did so earlier:: stable branch, unless you already did so earlier::
cd ~/linux/ cd ~/linux/
git remote add -t master stable \
https://git.kernel.org/pub/scm/linux/kernel/git/stable/stable.git
git remote set-branches --add stable linux-6.1.y git remote set-branches --add stable linux-6.1.y
git fetch stable git fetch stable
.. _bisectstart_bissbs: .. _bisectstart_bissbs:
* Start the bisection and tell Git about the versions earlier established as * Start the bisection and tell Git about the versions earlier established as
'good' and 'bad':: 'good' (6.0 in the following example command) and 'bad' (6.1.5)::
cd ~/linux/ cd ~/linux/
git bisect start git bisect start
@ -884,8 +887,9 @@ space might run out.
On quite a few distributions this will delete all other kernel files installed On quite a few distributions this will delete all other kernel files installed
while also removing the kernel's entry from the boot menu. But on some while also removing the kernel's entry from the boot menu. But on some
distributions this command does not exist or will fail; in that case consult distributions kernel-install does not exist or leaves boot-loader entries or
the reference section, as your Linux distribution needs special care. kernel image and related files behind; in that case remove them as described
in the reference section.
[:ref:`details<makeroom_bisref>`] [:ref:`details<makeroom_bisref>`]
@ -1015,8 +1019,6 @@ the right thing.
[:ref:`back to step-by-step guide <bootworking_bissbs>`] [:ref:`back to step-by-step guide <bootworking_bissbs>`]
.. _buildrequires_bisref:
.. _diskspace_bisref: .. _diskspace_bisref:
Space requirements Space requirements
@ -1060,7 +1062,7 @@ to do this as well, if you tried bisecting between 6.0.11 and 6.1.13.
[:ref:`back to step-by-step guide <rangecheck_bissbs>`] [:ref:`back to step-by-step guide <rangecheck_bissbs>`]
.. _sources_bisref: .. _buildrequires_bisref:
Install build requirements Install build requirements
-------------------------- --------------------------
@ -1076,72 +1078,103 @@ about to build.
Here are a few examples what you typically need on some mainstream Here are a few examples what you typically need on some mainstream
distributions: distributions:
* Arch Linux and derivatives::
sudo pacman --needed -S bc binutils bison flex gcc git kmod libelf openssl \
pahole perl zlib ncurses qt6-base
* Debian, Ubuntu, and derivatives:: * Debian, Ubuntu, and derivatives::
sudo apt install bc binutils bison dwarves flex gcc git make openssl \ sudo apt install bc binutils bison dwarves flex gcc git kmod libelf-dev \
pahole perl-base libssl-dev libelf-dev libssl-dev make openssl pahole perl-base pkg-config zlib1g-dev \
libncurses-dev qt6-base-dev g++
* Fedora and derivatives:: * Fedora and derivatives::
sudo dnf install binutils /usr/include/{libelf.h,openssl/pkcs7.h} \ sudo dnf install binutils \
/usr/bin/{bc,bison,flex,gcc,git,openssl,make,perl,pahole} /usr/bin/{bc,bison,flex,gcc,git,openssl,make,perl,pahole,rpmbuild} \
/usr/include/{libelf.h,openssl/pkcs7.h,zlib.h,ncurses.h,qt6/QtGui/QAction}
* openSUSE and derivatives:: * openSUSE and derivatives::
sudo zypper install bc binutils bison dwarves flex gcc git make perl-base \ sudo zypper install bc binutils bison dwarves flex gcc git \
openssl openssl-devel libelf-dev kernel-install-tools libelf-devel make modutils openssl openssl-devel \
perl-base zlib-devel rpm-build ncurses-devel qt6-base-devel
In case you wonder why these lists include openssl and its development headers: These commands install a few packages that are often, but not always needed. You
they are needed for the Secure Boot support, which many distributions enable in for example might want to skip installing the development headers for ncurses,
their kernel configuration for x86 machines. which you will only need in case you later might want to adjust the kernel build
configuration using make the targets 'menuconfig' or 'nconfig'; likewise omit
Sometimes you will need tools for compression formats like bzip2, gzip, lz4, the headers of Qt6 is you do not plan to adjust the .config using 'xconfig'.
lzma, lzo, xz, or zstd as well.
In case you want to adjust the build configuration with make targets like
'menuconfig' or 'xconfig' later, ensure to also install development headers for
ncurses and Qt5.
You furthermore might need additional libraries and their development headers You furthermore might need additional libraries and their development headers
for tasks not covered in this guide. For example, zlib will be needed when for tasks not covered in this guide -- for example when building utilities from
building kernel tools from the tools/ directory;. the kernel's tools/ directory.
[:ref:`back to step-by-step guide <buildrequires_bissbs>`] [:ref:`back to step-by-step guide <buildrequires_bissbs>`]
Download the sources using git .. _sources_bisref:
Download the sources using Git
------------------------------ ------------------------------
*Retrieve the Linux mainline sources.* *Retrieve the Linux mainline sources.*
[:ref:`...<sources_bissbs>`] [:ref:`...<sources_bissbs>`]
The step-by-step guide outlines how to retrieve the Linux sources using a full The step-by-step guide outlines how to download the Linux sources using a full
Git clone of Linus' mainline repository. If you have an unreliable internet Git clone of Linus' mainline repository. There is nothing more to say about
connection, you instead might want to use a 'Git bundle' to retrieve the that -- but there are two alternatives ways to retrieve the sources that might
sources; if downloading the complete repository would take too long or requires work better for you:
too much storage space, use a shallow clone instead.
Downloading Linux mainline using a bundle * If you have an unreliable internet connection, consider
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ :ref:`using a 'Git bundle'<sources_bundle_bisref>`.
Switch to you home directory and follow the instructions `kernel.org provides * If downloading the complete repository would take too long or requires too
for this case <https://www.kernel.org/cloning-linux-from-a-bundle.html>`_. much storage space, consider :ref:`using a 'shallow
clone'<sources_shallow_bisref>`.
Afterwards add the stable Git repository as remote and all required .. _sources_bundle_bisref:
stable/branches as explained in the step-by-step guide.
Downloading Linux mainline using a shallow clone Downloading Linux mainline sources using a bundle
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Use the following commands to retrieve the Linux mainline sources using a
bundle::
wget -c \
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/clone.bundle
git clone --no-checkout clone.bundle ~/linux/
cd ~/linux/
git remote remove origin
git remote add mainline \
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
git fetch mainline
git remote add -t master stable \
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
In case the 'wget' command fails, just re-execute it, it will pick up where
it left off.
[:ref:`back to step-by-step guide <sources_bissbs>`]
[:ref:`back to section intro <sources_bisref>`]
.. _sources_shallow_bisref:
Downloading Linux mainline sources using a shallow clone
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
First, execute the following command to retrieve the latest mainline codebase:: First, execute the following command to retrieve the latest mainline codebase::
git clone -o mainline --no-checkout --depth 1 -b master \ git clone -o mainline --no-checkout --depth 1 -b master \
https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/ https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git ~/linux/
cd ~/linux/ cd ~/linux/
git remote add -t master stable \
https://git.kernel.org/pub/scm/linux/kernel/git/stable/linux.git
Now deepen your clone's history to the second predecessor of the mainline Now deepen your clone's history to the second predecessor of the mainline
release of your 'good' version. In case the latter are 6.0 or 6.0.11, 5.19 would release of your 'good' version. In case the latter are 6.0 or 6.0.11, 5.19 would
be the first predecessor and 5.18 the second -- hence deepen the history up to be the first predecessor and 5.18 the second -- hence deepen the history up to
the latter:: that version::
git fetch --shallow-exclude=v5.18 mainline git fetch --shallow-exclude=v5.18 mainline
@ -1150,7 +1183,7 @@ branches as explained in the step-by-step guide.
Note, shallow clones have a few peculiar characteristics: Note, shallow clones have a few peculiar characteristics:
* For bisections the history needs to be deepend a few mainline versions * For bisections the history needs to be deepened a few mainline versions
farther than it seems necessary, as explained above already. That's because farther than it seems necessary, as explained above already. That's because
Git otherwise will be unable to revert or describe most of the commits within Git otherwise will be unable to revert or describe most of the commits within
a range (say v6.1..v6.2), as they are internally based on earlier kernels a range (say v6.1..v6.2), as they are internally based on earlier kernels