| Message ID | 20220822180956.4013497-1-sadiyakazi@google.com (mailing list archive) |
|---|---|
| State | New |
| Delegated to: | Brendan Higgins |
| Headers | show |
| Series | Documentation: KUnit: Reword kunit_tool guide | expand |
On 8/23/22 01:09, Sadiya Kazi wrote: > Updated the kunit_tool.rst guide to streamline it. The following changes > were made: > 1. Updated headings > 2. Reworded content across sections > 3. Added a cross reference to full list of command-line args > What about this description:? "Rework kunit_tool How-To, which includes: - grammatical fixes - change title to 'Understanding kunit_tool', and - add a reference link to command line arguments list." Thanks.
On Tue, Aug 23, 2022 at 2:10 AM Sadiya Kazi <sadiyakazi@google.com> wrote: > > Updated the kunit_tool.rst guide to streamline it. The following changes > were made: > 1. Updated headings > 2. Reworded content across sections > 3. Added a cross reference to full list of command-line args > > Signed-off-by: Sadiya Kazi <sadiyakazi@google.com> > --- This looks okay overall, but there are definitely some parts I'm more comfortable with than others. The "kunit_tool How-To" name was fine by my book, but I also like "Understanding kunit_tool". My biggest concern here is actually that there's another patch which removes this page entirely. It makes very little sense to tidy this up only to delete it: https://lore.kernel.org/all/20220822022646.98581-2-tales.aparecida@gmail.com/ While there is an argument for keeping this page (its purpose as a "reference" differs slightly from the more "tutorialised" run_wrapper.rst, as well as wanting to avoid breaking any external links if we can), I think that overall, we'll probably lose this page entirely. Regardless, I've commented on the exact changes below. Cheers, -- David > Documentation/dev-tools/kunit/kunit-tool.rst | 82 ++++++++++---------- > 1 file changed, 42 insertions(+), 40 deletions(-) > > diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst > index ae52e0f489f9..33186679f5de 100644 > --- a/Documentation/dev-tools/kunit/kunit-tool.rst > +++ b/Documentation/dev-tools/kunit/kunit-tool.rst > @@ -1,8 +1,10 @@ > .. SPDX-License-Identifier: GPL-2.0 > > -================= > -kunit_tool How-To > -================= > +======================== > +Understanding kunit_tool > +======================== > + > +This page introduces the kunit_tool and covers the concepts and working of this tool. Nit: just "kunit_tool", not "the kunit_tool". Also, is this sentence really telling us anything? > > What is kunit_tool? > =================== > @@ -10,39 +12,37 @@ What is kunit_tool? > kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building > the Linux kernel as UML (`User Mode Linux > <http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing > -the test results and displaying them in a user friendly manner. > +the test results and displaying them in a user-friendly manner. > > kunit_tool addresses the problem of being able to run tests without needing a > virtual machine or actual hardware with User Mode Linux. User Mode Linux is a > Linux architecture, like ARM or x86; however, unlike other architectures it > -compiles the kernel as a standalone Linux executable that can be run like any > +compiles the kernel as a standalone Linux executable. This executable can be run like any > other program directly inside of a host operating system. To be clear, it does > not require any virtualization support: it is just a regular program. > > -What is a .kunitconfig? > -======================= > +What is .kunitconfig? > +===================== There can be multiple .kunitconfig files, so this may make sense to leave as "a .kunitconfig" > > -It's just a defconfig that kunit_tool looks for in the build directory > -(``.kunit`` by default). kunit_tool uses it to generate a .config as you might > -expect. In addition, it verifies that the generated .config contains the CONFIG > -options in the .kunitconfig; the reason it does this is so that it is easy to > -be sure that a CONFIG that enables a test actually ends up in the .config. > +.kunitconfig is a default configuration file (defconfig) that kunit_tool looks > +for in the build directory (``.kunit``). The kunit_tool uses this file to > +generate a .config. Additionally, it also verifies that the generated .config contains the CONFIG options in the .kunitconfig file. This is done to make sure that a CONFIG that enables a test is actually part of the .config file. Word wrapping, "the kunit_tool" -> "kunit_tool", the build directory may not be ``.kunit``, so re-introduce "by default". > > -It's also possible to pass a separate .kunitconfig fragment to kunit_tool, > +It is also possible to pass a separate .kunitconfig fragment to kunit_tool, > which is useful if you have several different groups of tests you wish > -to run independently, or if you want to use pre-defined test configs for > +to run independently, or if you want to use pre-defined test configurations for > certain subsystems. > > -Getting Started with kunit_tool > +Getting started with kunit_tool The capitalisation of headings in the KUnit documentation (and, indeed, the whole kernel documentation) is pretty inconsistent. I wouldn't mind it if these changes to improve consistency, but let's not just change one page without committing to doing so on all of them. Particularly since, at the moment, I think we're using (an approximation of) title-case in more pages. > =============================== > > -If a kunitconfig is present at the root directory, all you have to do is: > +If a kunitconfig is present at the root directory, run the following command: Do we want to standardise on .kunitconfig or kunitconfig? I think we'd decided that we should use ".kunitconfig" everywhere. Also, this is outdated: the .kunitconfig needs to be in the build directory, not the root directory. > .. code-block:: bash > > ./tools/testing/kunit/kunit.py run > > -However, you most likely want to use it with the following options: > +However, most likely you may want to use it with the following options: Personally, I find the earlier version clearer here, but could live with the change if there's a good reason behind it I'm missing... > > .. code-block:: bash > > @@ -68,20 +68,20 @@ For a list of all the flags supported by kunit_tool, you can run: > > ./tools/testing/kunit/kunit.py run --help > > -Configuring, Building, and Running Tests > +Configuring, building, and running tests > ======================================== > > -It's also possible to run just parts of the KUnit build process independently, > -which is useful if you want to make manual changes to part of the process. > +It is also possible to run specific parts of the KUnit build process independently. > +This is useful if you want to make manual changes to part of the process. > > -A .config can be generated from a .kunitconfig by using the ``config`` argument > +If you want to generate a .config from a .kunitconfig, you can use the ``config`` argument > when running kunit_tool: > > .. code-block:: bash > > ./tools/testing/kunit/kunit.py config > > -Similarly, if you just want to build a KUnit kernel from the current .config, > +Similarly, if you want to build a KUnit kernel from the current .config, I think the "just" here is valuable: "kunit.py run" is the default that most people will use, and it's very easy to assume "kunit.py build" will do everything required to build the kernel (including config), but it doesn't. > you can use the ``build`` argument: > > .. code-block:: bash > @@ -95,33 +95,31 @@ run the kernel and display the test results with the ``exec`` argument: > > ./tools/testing/kunit/kunit.py exec > > -The ``run`` command which is discussed above is equivalent to running all three > +The ``run`` command, discussed above is equivalent to running all three > of these in sequence. > > All of these commands accept a number of optional command-line arguments. The > ``--help`` flag will give a complete list of these, or keep reading this page > for a guide to some of the more useful ones. > > -Parsing Test Results > +Parsing test results > ==================== > > -KUnit tests output their results in TAP (Test Anything Protocol) format. > -kunit_tool will, when running tests, parse this output and print a summary > -which is much more pleasant to read. If you wish to look at the raw test > -results in TAP format, you can pass the ``--raw_output`` argument. > +The output of the KUnit test results are displayed in TAP (Test Anything Protocol) format. > +When running tests, the kunit_tool parses this output and prints a plaintext, human-readable summary. To view the raw test results in TAP format, you can use the ``--raw_output`` argument. Word wrapping. > > .. code-block:: bash > > ./tools/testing/kunit/kunit.py run --raw_output > > The raw output from test runs may contain other, non-KUnit kernel log > -lines. You can see just KUnit output with ``--raw_output=kunit``: > +lines. To view only the KUnit output, you can use ``--raw_output=kunit``: > > .. code-block:: bash > > ./tools/testing/kunit/kunit.py run --raw_output=kunit > > -If you have KUnit results in their raw TAP format, you can parse them and print > +If you have KUnit results in the raw TAP format, you can parse them and print > the human-readable summary with the ``parse`` command for kunit_tool. This > accepts a filename for an argument, or will read from standard input. > > @@ -135,11 +133,11 @@ accepts a filename for an argument, or will read from standard input. > This is very useful if you wish to run tests in a configuration not supported > by kunit_tool (such as on real hardware, or an unsupported architecture). > > -Filtering Tests > +Filtering tests > =============== > > -It's possible to run only a subset of the tests built into a kernel by passing > -a filter to the ``exec`` or ``run`` commands. For example, if you only wanted > +It is possible to run only a subset of the tests built into a kernel by passing > +a filter to the ``exec`` or ``run`` commands. For example, if you want > to run KUnit resource tests, you could use: Again, I'm quite partial to the "only" here, as test filtering can only _remove_ tests/suites from the set to be executed, not add them. > > .. code-block:: bash > @@ -148,15 +146,14 @@ to run KUnit resource tests, you could use: > > This uses the standard glob format for wildcards. > > -Running Tests on QEMU > +Running tests on QEMU > ===================== > > -kunit_tool supports running tests on QEMU as well as via UML (as mentioned > -elsewhere). The default way of running tests on QEMU requires two flags: > +kunit_tool supports running tests on QEMU as well as via UML. The default way of running tests on QEMU requires two flags: Word Wrapping > > ``--arch`` > Selects a collection of configs (Kconfig as well as QEMU configs > - options, etc) that allow KUnit tests to be run on the specified > + options and so on) that allow KUnit tests to be run on the specified Do we really need to remove "etc"? "and so on" is less visually distinct, IMO. > architecture in a minimal way; this is usually not much slower than > using UML. The architecture argument is the same as the name of the > option passed to the ``ARCH`` variable used by Kbuild. Not all > @@ -196,8 +193,8 @@ look something like this: > --jobs=12 \ > --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py > > -Other Useful Options > -==================== > +Other useful options > +====================== > > kunit_tool has a number of other command-line arguments which can be useful > when adapting it to fit your environment or needs. > @@ -228,5 +225,10 @@ Some of the more useful ones are: > dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your > .kunitconfig is preferable. > > -There are several other options (and new ones are often added), so do check > +There are several other options (and new ones are often added), so do run > ``--help`` if you're looking for something not mentioned here. > +For more information on these options, see `Command-line-arguments > +<https://www.kernel.org/doc/html/latest/dev-tools/kunit/run_wrapper.html#command-line-arguments>`__ > + > + > +. Newlines, full stop at the end of this doc should be removed. > -- > 2.37.1.595.g718a3a8f04-goog >
diff --git a/Documentation/dev-tools/kunit/kunit-tool.rst b/Documentation/dev-tools/kunit/kunit-tool.rst index ae52e0f489f9..33186679f5de 100644 --- a/Documentation/dev-tools/kunit/kunit-tool.rst +++ b/Documentation/dev-tools/kunit/kunit-tool.rst @@ -1,8 +1,10 @@ .. SPDX-License-Identifier: GPL-2.0 -================= -kunit_tool How-To -================= +======================== +Understanding kunit_tool +======================== + +This page introduces the kunit_tool and covers the concepts and working of this tool. What is kunit_tool? =================== @@ -10,39 +12,37 @@ What is kunit_tool? kunit_tool is a script (``tools/testing/kunit/kunit.py``) that aids in building the Linux kernel as UML (`User Mode Linux <http://user-mode-linux.sourceforge.net/>`_), running KUnit tests, parsing -the test results and displaying them in a user friendly manner. +the test results and displaying them in a user-friendly manner. kunit_tool addresses the problem of being able to run tests without needing a virtual machine or actual hardware with User Mode Linux. User Mode Linux is a Linux architecture, like ARM or x86; however, unlike other architectures it -compiles the kernel as a standalone Linux executable that can be run like any +compiles the kernel as a standalone Linux executable. This executable can be run like any other program directly inside of a host operating system. To be clear, it does not require any virtualization support: it is just a regular program. -What is a .kunitconfig? -======================= +What is .kunitconfig? +===================== -It's just a defconfig that kunit_tool looks for in the build directory -(``.kunit`` by default). kunit_tool uses it to generate a .config as you might -expect. In addition, it verifies that the generated .config contains the CONFIG -options in the .kunitconfig; the reason it does this is so that it is easy to -be sure that a CONFIG that enables a test actually ends up in the .config. +.kunitconfig is a default configuration file (defconfig) that kunit_tool looks +for in the build directory (``.kunit``). The kunit_tool uses this file to +generate a .config. Additionally, it also verifies that the generated .config contains the CONFIG options in the .kunitconfig file. This is done to make sure that a CONFIG that enables a test is actually part of the .config file. -It's also possible to pass a separate .kunitconfig fragment to kunit_tool, +It is also possible to pass a separate .kunitconfig fragment to kunit_tool, which is useful if you have several different groups of tests you wish -to run independently, or if you want to use pre-defined test configs for +to run independently, or if you want to use pre-defined test configurations for certain subsystems. -Getting Started with kunit_tool +Getting started with kunit_tool =============================== -If a kunitconfig is present at the root directory, all you have to do is: +If a kunitconfig is present at the root directory, run the following command: .. code-block:: bash ./tools/testing/kunit/kunit.py run -However, you most likely want to use it with the following options: +However, most likely you may want to use it with the following options: .. code-block:: bash @@ -68,20 +68,20 @@ For a list of all the flags supported by kunit_tool, you can run: ./tools/testing/kunit/kunit.py run --help -Configuring, Building, and Running Tests +Configuring, building, and running tests ======================================== -It's also possible to run just parts of the KUnit build process independently, -which is useful if you want to make manual changes to part of the process. +It is also possible to run specific parts of the KUnit build process independently. +This is useful if you want to make manual changes to part of the process. -A .config can be generated from a .kunitconfig by using the ``config`` argument +If you want to generate a .config from a .kunitconfig, you can use the ``config`` argument when running kunit_tool: .. code-block:: bash ./tools/testing/kunit/kunit.py config -Similarly, if you just want to build a KUnit kernel from the current .config, +Similarly, if you want to build a KUnit kernel from the current .config, you can use the ``build`` argument: .. code-block:: bash @@ -95,33 +95,31 @@ run the kernel and display the test results with the ``exec`` argument: ./tools/testing/kunit/kunit.py exec -The ``run`` command which is discussed above is equivalent to running all three +The ``run`` command, discussed above is equivalent to running all three of these in sequence. All of these commands accept a number of optional command-line arguments. The ``--help`` flag will give a complete list of these, or keep reading this page for a guide to some of the more useful ones. -Parsing Test Results +Parsing test results ==================== -KUnit tests output their results in TAP (Test Anything Protocol) format. -kunit_tool will, when running tests, parse this output and print a summary -which is much more pleasant to read. If you wish to look at the raw test -results in TAP format, you can pass the ``--raw_output`` argument. +The output of the KUnit test results are displayed in TAP (Test Anything Protocol) format. +When running tests, the kunit_tool parses this output and prints a plaintext, human-readable summary. To view the raw test results in TAP format, you can use the ``--raw_output`` argument. .. code-block:: bash ./tools/testing/kunit/kunit.py run --raw_output The raw output from test runs may contain other, non-KUnit kernel log -lines. You can see just KUnit output with ``--raw_output=kunit``: +lines. To view only the KUnit output, you can use ``--raw_output=kunit``: .. code-block:: bash ./tools/testing/kunit/kunit.py run --raw_output=kunit -If you have KUnit results in their raw TAP format, you can parse them and print +If you have KUnit results in the raw TAP format, you can parse them and print the human-readable summary with the ``parse`` command for kunit_tool. This accepts a filename for an argument, or will read from standard input. @@ -135,11 +133,11 @@ accepts a filename for an argument, or will read from standard input. This is very useful if you wish to run tests in a configuration not supported by kunit_tool (such as on real hardware, or an unsupported architecture). -Filtering Tests +Filtering tests =============== -It's possible to run only a subset of the tests built into a kernel by passing -a filter to the ``exec`` or ``run`` commands. For example, if you only wanted +It is possible to run only a subset of the tests built into a kernel by passing +a filter to the ``exec`` or ``run`` commands. For example, if you want to run KUnit resource tests, you could use: .. code-block:: bash @@ -148,15 +146,14 @@ to run KUnit resource tests, you could use: This uses the standard glob format for wildcards. -Running Tests on QEMU +Running tests on QEMU ===================== -kunit_tool supports running tests on QEMU as well as via UML (as mentioned -elsewhere). The default way of running tests on QEMU requires two flags: +kunit_tool supports running tests on QEMU as well as via UML. The default way of running tests on QEMU requires two flags: ``--arch`` Selects a collection of configs (Kconfig as well as QEMU configs - options, etc) that allow KUnit tests to be run on the specified + options and so on) that allow KUnit tests to be run on the specified architecture in a minimal way; this is usually not much slower than using UML. The architecture argument is the same as the name of the option passed to the ``ARCH`` variable used by Kbuild. Not all @@ -196,8 +193,8 @@ look something like this: --jobs=12 \ --qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py -Other Useful Options -==================== +Other useful options +====================== kunit_tool has a number of other command-line arguments which can be useful when adapting it to fit your environment or needs. @@ -228,5 +225,10 @@ Some of the more useful ones are: dependencies by adding ``CONFIG_KUNIT_ALL_TESTS=1`` to your .kunitconfig is preferable. -There are several other options (and new ones are often added), so do check +There are several other options (and new ones are often added), so do run ``--help`` if you're looking for something not mentioned here. +For more information on these options, see `Command-line-arguments +<https://www.kernel.org/doc/html/latest/dev-tools/kunit/run_wrapper.html#command-line-arguments>`__ + + +.
Updated the kunit_tool.rst guide to streamline it. The following changes were made: 1. Updated headings 2. Reworded content across sections 3. Added a cross reference to full list of command-line args Signed-off-by: Sadiya Kazi <sadiyakazi@google.com> --- Documentation/dev-tools/kunit/kunit-tool.rst | 82 ++++++++++---------- 1 file changed, 42 insertions(+), 40 deletions(-)