Lines Matching refs:you
20 Note: if you see this note, you are reading the text's source file. You
22 read and navigate this document -- especially when you want to look something
23 up in the reference section, then jump back to where you left off.
31 *[If you are new to building or bisecting Linux, ignore this section and head
38 **In case you want to check if a bug is present in code currently supported by
40 consider the newest Linux kernel you regularly use to be the 'working' kernel.
44 **In case you face a regression**, follow the steps at least till the end of
45 *segment 2*. Then you can submit a preliminary report -- or continue with
56 # * If you are not already running the 'working' kernel, reboot into it.
65 # * Hint: if you used an existing clone, ensure no stale .config is around.
76 # * Hint: at this point you might want to adjust the build configuration;
77 # you'll have to, if you are running Debian.
105 # enables you to make better estimates later:
108 # * Hint: the output of the following command will help you pick the
112 # * Once booted, ensure you are running the kernel you just built by
131 section b* -- just feel free to skip the 'du' commands, as you have a rough
162 things. If you run short of disk space during this process, check the
187 a) To avoid running out of disk space during a bisection, you might need to
188 remove some kernels you built earlier. You most likely want to keep those
189 you built during segment 1 and 2 around for a while, but you will most
203 b) If you performed a bisection and successfully validated the result, feel
205 the kernels you built earlier and later you might want to keep around for
226 or regressions you intend to report. How far you want to follow the instructions
230 is present in code supported by Linux kernel developers**. If it is, you are all
234 outcome you then are ready to report a bug or submit a preliminary regression
243 :ref:`Segment 2: check if the kernels you build work fine <introworkingcheck_bissbs>`.
259 with this document. It among others explains why you need to verify bugs with
261 even if you face a problem with a kernel from a 'stable/longterm' series
269 If you run into any problems while following this guide or have ideas how to
279 Note: the instructions assume you are building and testing on the same
280 machine; if you want to compile the kernel on another system, check
314 * Do you follow this guide to verify if a bug is present in the code the
316 you regularly use currently as 'good' (e.g. 6.0, 6.0.13, or 6.1-rc2).
318 * Do you face a regression, e.g. something broke or works worse after
337 (e.g. 6.0.13 and 6.0.15), as you need to bisect within that series.
354 directory should typically suffice. If you have less available, be sure to pay
357 should allow you to master these tasks with about 4 Gigabytes free space.
363 * Install all software required to build a Linux kernel. Often you will need:
396 * Is one of the versions you earlier established as 'good' or 'bad' a stable or
407 Before doing so, ensure you are still running the 'working' kernel an earlier
408 step told you to boot; if you are unsure, check the current kernelrelease
424 you checked out. While doing so, it will print a few lines you need to check.
430 the .config file for your running kernel -- in which case you have to put one
433 In case you can not find such a line, look for one containing '# configuration
434 written to .config'. If that's the case you have a stale build configuration
435 lying around. Unless you intend to use it, delete it; afterwards run
447 case you should skip this step.
449 To prepare the trimming, connect external hardware you occasionally use (USB
450 keys, tokens, ...), quickly start a VM, and bring up VPNs. And if you rebooted
451 since you started that guide, ensure that you tried using the feature causing
452 trouble since you started the system. Only then trim your .config::
463 loads when you execute tasks like the aforementioned ones for the first time.
465 This drawback of localmodconfig is nothing you should lose sleep over, but
477 * Ensure all the kernels you will build are clearly identifiable using a special
490 decent chance you will need to decode a stack trace from a 'panic', 'Oops',
496 But if you are extremely short on storage space, you might want to disable
506 * Check if you may want or need to adjust some other kernel configuration
509 * Are you running Debian? Then you want to avoid known problems by performing
514 * If you want to influence other aspects of the configuration, do so now using
516 'nconfig', you will need to install the development files of ncurses; for
517 'xconfig' you likewise need the Qt5 or Qt6 headers.
537 supported by developers. In case you face a regression, it also checks that the
554 tag. In that case you might want to check if a successor series (say
566 * Build the image and the modules of your first kernel using the config file you
573 If you want your kernel packaged up as deb, rpm, or tar file, see the
606 Once you figured out the steps needed at this point, consider writing them
607 down: if you will build more kernels as described in segment 2 and 3, you will
614 * In case you plan to follow this guide further, check how much storage space
620 Write down or remember those two values for later: they enable you to prevent
627 * Show and store the kernelrelease identifier of the kernel you just built::
631 Remember the identifier momentarily, as it will help you pick the right kernel
635 you just built, you might want to verify if the output of these commands
662 * Did you just built a stable or longterm kernel? And were you able to reproduce
663 the regression with it? Then you should test the latest mainline codebase as
685 Confirm you booted the kernel you intended to start and check its tainted
692 Now verify if this kernel is showing the problem. If it does, then you need
698 Do you follow this guide to verify if a problem is present in the code
699 currently supported by Linux kernel developers? Then you are done at this
700 point. If you later want to remove the kernel you just built, check out
703 In case you face a regression, move on and execute at least the next segment
708 Segment 2: check if the kernels you build work fine
711 In case of a regression, you now want to ensure the trimmed configuration file
712 you created earlier works as expected; a bisection with the .config file
739 When the system booted, you may want to verify once again that the
740 kernel you started is the one you just built::
755 With all the preparations and precaution builds taken care of, you are now ready
756 to begin the bisection. This will make you build quite a few kernels -- usually
757 about 15 in case you encountered a regression when updating to a newer series
793 In case you skipped the 'test latest codebase' step in the guide, check its
798 identifiers that might look odd or wrong to you -- which they are not, as it's
800 if you bisect between versions 6.1 and 6.2 for example.
806 * Now check if the feature that regressed works in the kernel you just built.
808 You again might want to start by making sure the kernel you booted is the one
809 you just built::
824 Be sure about what you tell Git, as getting this wrong just once will send the
827 While the bisection is ongoing, Git will use the information you provided to
828 find and check out another bisection point for you to test. While doing so, it
834 Repeat this again and again until you finish the bisection -- that's the case
838 description of the change. The latter might fill your terminal screen, so you
868 Begin by checking out the latest codebase depending on the range you bisected:
870 * Did you face a regression within a stable/longterm series (say between
882 If you bisected a regression within a stable/longterm series that also
913 Now check one last time if the feature that made you perform a bisection works
923 During and after following this guide you might want or need to remove some of
924 the kernels you installed: the boot menu otherwise will become confusing or
929 * To remove one of the kernels you installed, look up its 'kernelrelease'
936 actual bisection (e.g. segment 3 of this guide). The two ones you created
939 around, unless you are really short on storage space.
961 * Once you have finished the bisection, do not immediately remove anything you
962 set up, as you might need a few things again. What is safe to remove depends
965 * Could you initially reproduce the regression with the latest codebase and
967 top of the latest codebase? Then you want to keep those two kernels around
972 reasons? Then you want to keep as many kernels as possible around for a few
973 days: it's pretty likely that you will be asked to recheck something.
977 the version considered 'good', and the last three or four you compiled
987 While or after reporting a bug, you might want or potentially will be asked to
993 * In case you want to test mainline, fetch its latest changes before checking
999 * In case you want to test a stable or longterm kernel, first add the branch
1000 holding the series you are interested in (6.2 in the example), unless you
1015 * Your next step depends on what you want to do:
1017 * In case you just want to test the latest codebase, head to the next step,
1018 you are already all set.
1020 * In case you want to test if a revert fixes an issue, revert one or multiple
1030 * In case you want to test a patch, store the patch in a file like
1054 * Now verify you booted the newly built kernel and check it.
1065 Did you run into trouble following any of the above steps not cleared up by the
1066 reference section below? Did you spot errors? Or do you have ideas how to
1101 Remember, you are dealing with computers, which sometimes do unexpected things
1102 -- especially if you fiddle with crucial parts like the kernel of an operating
1103 system. That's what you are about to do in this process. Hence, better prepare
1152 tell you to create a one-time password, which is safe to write down. Now
1156 Secure Boot state'. Shim's 'MokManager' will now ask you to enter three
1158 you provided them, confirm you really want to disable the validation.
1185 safe side, so often you will need less.
1187 If you have space constraints, be sure to hay attention to the :ref:`step about
1209 that the issue you face with 6.1.5 only worked in 6.0.13, as it was fixed by a
1214 will be built and tested in the segment '2' of this guide; Git would force you
1215 to do this as well, if you tried bisecting between 6.0.13 and 6.1.15.
1227 The kernel is pretty stand-alone, but besides tools like the compiler you will
1229 depends on your Linux distribution and the configuration of the kernel you are
1232 Here are a few examples what you typically need on some mainstream
1260 which you will only need in case you later might want to adjust the kernel build
1262 the headers of Qt6 if you do not plan to adjust the .config using 'xconfig'.
1281 work better for you:
1283 * If you have an unreliable internet connection, consider
1347 to specify the earliest version you care about (or to be precise: its git
1350 define the depth of the history you want to download. When using them while
1354 * Be warned, when deepening your clone you might encounter an error like
1371 tree to keep things simple. In case you prefer storing the build artifacts
1382 that's what you intend (see next step), but in all other cases you want to
1383 delete it. This for example is important in case you followed this guide
1395 Once you put it there, run ``make olddefconfig`` again to adjust it to the
1399 default value. If you prefer to set such configuration options manually, use
1400 ``make oldconfig`` instead. Then for each undefined configuration option you
1401 will be asked how to proceed; in case you are unsure what to answer, simply hit
1402 'enter' to apply the default value. Note though that for bisections you normally
1403 want to go with the defaults, as you otherwise might enable a new feature that
1410 you to boot the kernel where everything works. If you manually add a .config
1411 file you thus want to ensure it's from the working kernel and not from a one
1414 In case you want to build kernels for another machine, locate its kernel build
1430 can easily happen that your self-built kernels will lack modules for tasks you
1432 when a task requires kernel modules which are only autoloaded when you execute
1433 it for the first time. So when you never performed that task since starting your
1442 systems you otherwise do not utilize (btrfs, ext4, FAT, NTFS, XFS, ...). But it
1446 Do not let that risk bother you, especially when compiling a kernel only for
1447 testing purposes: everything typically crucial will be there. And if you forget
1448 something important you can turn on a missing feature manually later and quickly
1449 run the commands again to compile and install a kernel that has everything you
1452 But if you plan to build and use self-built kernels regularly, you might want to
1460 That parameter also allows you to build trimmed kernels for another machine in
1461 case you copied a suitable .config over to use as base (see previous step). Just
1475 *Ensure all the kernels you will build are clearly identifiable using a
1478 This allows you to differentiate your distribution's kernels from those created
1481 not lose track of you kernels, as their version numbers will look slightly
1494 'panic', 'Oops', 'warning', or 'BUG' later when running, as then you will be
1503 In case you want a small kernel and are unlikely to decode a stack trace later,
1504 you thus might want to disable debug symbols to avoid those downsides. If it
1505 later turns out that you need them, just enable them as shown and rebuild the
1509 is a decent chance that you need to decode a stack trace later. The section
1520 *Check if you may want or need to adjust some other kernel configuration
1523 Depending on your needs you at this point might want or have to adjust some
1531 *Are you running* [:ref:`... <configmods_bissbs>`]
1533 The following sections help you to avoid build problems that are known to occur
1556 *If you want to influence the other aspects of the configuration, do so
1559 At this point you can use a command like ``make menuconfig`` or ``make nconfig``
1563 respectively Qt5 or Qt6); an error message will tell you if something required
1576 Put the .config you prepared aside, as you want to copy it back to the build
1577 directory every time during this guide before you start building another
1594 point, especially if you did that already with a kernel prepared by your
1598 * You will run into any problems caused by your setup before you actually begin
1608 older kernel. That security feature might get into the way of something you
1612 You thus would waste your time if you'd try to bisect this.
1615 codebase, you'd perform the bisection for nothing. This holds true for a
1616 regression you encountered with a stable/longterm release as well, as they are
1633 Your report might be ignored if you send it to the wrong party -- and even
1634 when you get a reply there is a decent chance that developers tell you to
1647 In case you later want to recheck if an ever newer codebase might fix the
1659 you prepared.* [:ref:`... <build_bissbs>`]
1661 A lot can go wrong at this stage, but the instructions below will help you help
1671 failure messages coupled with some research on the internet will often tell you
1691 often one of the hits will provide a solution for your problem, too. If you
1695 In the end, most issues you run into have likely been encountered and
1697 system, but lies in the code. If you run into one of those, you might thus find
1718 If you employ the targets to generate deb or rpm packages, ignore the
1734 *Install the kernel you just built.* [:ref:`... <install_bissbs>`]
1736 What you need to do after executing the command in the step-by-step guide
1781 /lib/modules/, especially if you enabled debug symbols. That makes it easy to
1783 work earlier might fail to boot. To prevent that you will need to know how much
1788 path nor the naming scheme are mandatory. On some distributions you thus will
1806 That's why you want check why a kernel is tainted as explained in
1821 the kernel you built from the latest codebase. These are the most frequent:
1825 * What you suspected to be a regression was caused by a change in the build
1832 * In case you encountered the regression with a stable/longterm kernel it might
1843 *Are you facing a regression within a stable/longterm release, but failed to
1844 reproduce it with the kernel you just built using the latest mainline sources?
1858 *Check if the kernels you build work fine.*
1864 It will ensure the .config file you prepared earlier actually works as expected.
1866 and you might be building and testing ten or more kernels for nothing before
1878 ensure the kernel version you assumed to be 'good' earlier in the process (e.g.
1899 test the feature? Then you might want to recreate a .config file based on the
1910 Note, if you found and fixed problems with the .config file, you want to use it
1920 *With all the preparations and precaution builds taken care of, you are now
1937 for you to test.
1947 same commands you used earlier.* [:ref:`... <bisectbuild_bissbs>`]
1974 *Check if the feature that regressed works in the kernel you just built.*
1977 Ensure what you tell Git is accurate: getting it wrong just one time will bring
1992 render the end result of a bisection useless. In that case you'd normally have
1995 instead of testing ten or more kernels you might only have to build a few to
1999 ask for it after you report the regression.
2011 This is an optional step, but whenever possible one you should try: there is a
2012 decent chance that developers will ask you to perform this step when you bring
2013 the bisection result up. So give it a try, you are in the flow already, building
2017 rare thing: did you bisected a regression that also happened with mainline using
2027 *During and after following this guide you might want or need to remove some
2028 of the kernels you installed.* [:ref:`... <introclosure_bissbs>`]
2039 *To remove one of the kernels you installed, look up its 'kernelrelease'
2042 The kernels you install during this process are easy to remove later, as its
2044 need to worry to mess up your machine when you install a kernel manually (and
2050 identifier; hence, to remove all modules for one of the kernels you built,
2058 step-by-step guide will delete all of these files for you while also removing
2059 the menu entry for the kernel from your bootloader configuration. On others you
2072 for kernels manually: you might accidentally remove files of a 6.0.13 kernel
2073 when all you want is to remove 6.0 or 6.0.1.
2082 *Once you have finished the bisection, do not immediately remove anything
2083 you set up, as you might need a few things again.*
2086 When you are really short of storage space removing the kernels as described in
2087 the step-by-step guide might not free as much space as you would like. In that
2094 is a decent chance developers will ask you to build another kernel to
2099 Additional tests are also the reason why you want to keep the
2109 *While or after reporting a bug, you might want or potentially will be asked
2132 * Start following the guide on the machine where you want to install and test
2146 * When you reach ':ref:`Start preparing a kernel build configuration[...]
2173 * Switch to the test machine to check if you have enough space to hold another
2174 kernel. Then extract the file you transferred::
2184 Now reboot and ensure you started the intended kernel.
2205 you spot a typo or small mistake, feel free to let him know directly and
2206 he'll fix it. You are free to do the same in a mostly informal way if you
2213 of the file. If you want to distribute this text under CC-BY-4.0 only,