The "Run Tests on qemu" section of run_wrapper.rst had a few issues left
over from the last big documentation refactor[1]:
- It referenced a run_uml.rst page, which was integrated into the other
pages (including run_wrapper.rst).
- It skimmed over the use of --arch= and --cross_compile= in favour of
using a custom --qemu_config. Since most users will want to use the
former, let's give examples.
Remove the reference to the non-existant page, and add a couple of
examples to encourage the use of --arch= and --cross_compile=.
With this change, there should be no more broken references in the KUnit
documentation (i.e., the one mentioned in [2] is gone).
[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
[2]: https://lore.kernel.org/linux-doc/[email protected]/
Signed-off-by: David Gow <[email protected]>
---
Thanks, Mauro, for noticing this in [2]: for whatever reason my version
of Sphinx wasn't warning on it.
Unless anyone objects, I'll add this to the list of things to be taken
in via the kunit/kunit-fixes tree.
Cheers,
-- David
---
Documentation/dev-tools/kunit/run_wrapper.rst | 17 ++++++++++++++---
1 file changed, 14 insertions(+), 3 deletions(-)
diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index 653985ce9cae..a695f58cd64e 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -192,6 +192,20 @@ via UML. To run tests on qemu, by default it requires two flags:
if we have downloaded the microblaze toolchain from the 0-day
website to a directory in our home directory called toolchains.
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+ ./tools/testing/kunit/kunit.py run --arch=x86_64
+
+If a special toolchain is required, it can be slightly more complicated:
+
+.. code-block:: bash
+
+ ./tools/testing/kunit/kunit.py run \
+ --arch=s390 \
+ --cross_compile=s390x-linux-gnu-
+
If we want to run KUnit tests on an architecture not supported by
the ``--arch`` flag, or want to run KUnit tests on qemu using a
non-default configuration; then we can write our own``QemuConfig``.
@@ -214,9 +228,6 @@ as
--jobs=12 \
--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
-To run existing KUnit tests on non-UML architectures, see:
-Documentation/dev-tools/kunit/non_uml.rst.
-
Command-Line Arguments
======================
--
2.37.0.rc0.161.g10f37bed90-goog
On 6/26/22 17:15, David Gow wrote:
> +If a special toolchain is required, it can be slightly more complicated:
> +
> +.. code-block:: bash
> +
> + ./tools/testing/kunit/kunit.py run \
> + --arch=s390 \
> + --cross_compile=s390x-linux-gnu-
> +
This describes cross-compiling usage, so the text should be "For
cross-compiling, pass --arch and --cross_compile flags:"
--
An old man doll... just what I always wanted! - Clara
The "Run Tests on qemu" section of run_wrapper.rst had a few issues left
over from the last big documentation refactor[1]:
- It referenced a non_uml.rst page, which was integrated into the other
pages (including run_wrapper.rst).
- It skimmed over the use of --arch= and --cross_compile= in favour of
using a custom --qemu_config. Since most users will want to use the
former, let's give examples.
Remove the reference to the non-existant page, and add a couple of
examples to encourage the use of --arch= and --cross_compile=.
With this change, there should be no more broken references in the KUnit
documentation (i.e., the one mentioned in [2] is gone).
[1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
[2]: https://lore.kernel.org/linux-doc/[email protected]/
Signed-off-by: David Gow <[email protected]>
---
Changes since v1:
https://lore.kernel.org/linux-kselftest/[email protected]/
- Reword the --cross_compile example (Thanks Bagas Sanjaya)
- Fix the name of run_uml.rst -> non_uml.rst in the commit description.
---
Documentation/dev-tools/kunit/run_wrapper.rst | 18 +++++++++++++++---
1 file changed, 15 insertions(+), 3 deletions(-)
diff --git a/Documentation/dev-tools/kunit/run_wrapper.rst b/Documentation/dev-tools/kunit/run_wrapper.rst
index 653985ce9cae..5e560f2c5fca 100644
--- a/Documentation/dev-tools/kunit/run_wrapper.rst
+++ b/Documentation/dev-tools/kunit/run_wrapper.rst
@@ -192,6 +192,21 @@ via UML. To run tests on qemu, by default it requires two flags:
if we have downloaded the microblaze toolchain from the 0-day
website to a directory in our home directory called toolchains.
+This means that for most architectures, running under qemu is as simple as:
+
+.. code-block:: bash
+
+ ./tools/testing/kunit/kunit.py run --arch=x86_64
+
+When cross-compiling, we'll likely need to specify a different toolchain, for
+example:
+
+.. code-block:: bash
+
+ ./tools/testing/kunit/kunit.py run \
+ --arch=s390 \
+ --cross_compile=s390x-linux-gnu-
+
If we want to run KUnit tests on an architecture not supported by
the ``--arch`` flag, or want to run KUnit tests on qemu using a
non-default configuration; then we can write our own``QemuConfig``.
@@ -214,9 +229,6 @@ as
--jobs=12 \
--qemu_config=./tools/testing/kunit/qemu_configs/x86_64.py
-To run existing KUnit tests on non-UML architectures, see:
-Documentation/dev-tools/kunit/non_uml.rst.
-
Command-Line Arguments
======================
--
2.37.0.rc0.161.g10f37bed90-goog
On 6/29/22 11:06, David Gow wrote:
> +This means that for most architectures, running under qemu is as simple as:
> +
> +.. code-block:: bash
> +
> + ./tools/testing/kunit/kunit.py run --arch=x86_64
> +
> +When cross-compiling, we'll likely need to specify a different toolchain, for
> +example:
> +
> +.. code-block:: bash
> +
> + ./tools/testing/kunit/kunit.py run \
> + --arch=s390 \
> + --cross_compile=s390x-linux-gnu-
> +
nit: s/we'll/you'll/
Otherwise looks OK.
--
An old man doll... just what I always wanted! - Clara
On Wed, Jun 29, 2022 at 4:44 PM Bagas Sanjaya <[email protected]> wrote:
>
> On 6/29/22 11:06, David Gow wrote:
> > +This means that for most architectures, running under qemu is as simple as:
> > +
> > +.. code-block:: bash
> > +
> > + ./tools/testing/kunit/kunit.py run --arch=x86_64
> > +
> > +When cross-compiling, we'll likely need to specify a different toolchain, for
> > +example:
> > +
> > +.. code-block:: bash
> > +
> > + ./tools/testing/kunit/kunit.py run \
> > + --arch=s390 \
> > + --cross_compile=s390x-linux-gnu-
> > +
>
> nit: s/we'll/you'll/
>
> Otherwise looks OK.
Thanks. The rest of this document is using "we" rather than "you", so
I used "we'll" for consistency. If "you" is preferred generally, it'd
be best to change it throughout the document (probably in a separate
patch).
Cheers,
-- David
David Gow <[email protected]> writes:
> Thanks. The rest of this document is using "we" rather than "you", so
> I used "we'll" for consistency. If "you" is preferred generally, it'd
> be best to change it throughout the document (probably in a separate
> patch).
Nobody has ever tried to articulate a wider policy on first or
second-person usage for kernel docs, so far as I know, and I think
that's just fine. We have far bigger things to worry about before we
get concerned about consistency at that level.
Thanks,
jon
On Wed, Jun 29, 2022 at 12:06 AM David Gow <[email protected]> wrote:
>
> The "Run Tests on qemu" section of run_wrapper.rst had a few issues left
> over from the last big documentation refactor[1]:
> - It referenced a non_uml.rst page, which was integrated into the other
> pages (including run_wrapper.rst).
> - It skimmed over the use of --arch= and --cross_compile= in favour of
> using a custom --qemu_config. Since most users will want to use the
> former, let's give examples.
>
> Remove the reference to the non-existant page, and add a couple of
> examples to encourage the use of --arch= and --cross_compile=.
>
> With this change, there should be no more broken references in the KUnit
> documentation (i.e., the one mentioned in [2] is gone).
>
> [1]: https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/commit/?id=46201d47d6c4be594c1d57b7f3251c371626a9c4
> [2]: https://lore.kernel.org/linux-doc/[email protected]/
>
> Signed-off-by: David Gow <[email protected]>
Reviewed-by: Brendan Higgins <[email protected]>