[PATCH v4] docs: rust: Add rusttest info

[PATCH v4] docs: rust: Add rusttest info

[Dirk Behme]

Searching the Rust kernel documentation all existing Rust Make
targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and
rust-analyzer) are explicitly documented with their Make commands.
While the Make target rusttest is mentioned two times in the
existing documentation, it's Make command is not explicitly
documented, yet. Add a test section to document this.

While at it, add some info about the more important KUnit testing
too.

Reviewed-by: David Gow <davidgow@google.com>
Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
---

v4: Swap the KUnit and make parts to make the more important KUnit
    being the first. Add and optimize the links to the KUnit docs
    and mention the KUnit built-in option. Fix some typos and wording.

    P.S.: In my 6.7.0-rc1 setup "make LLVM=1 rusttest" seems to work.

 Documentation/rust/general-information.rst | 23 ++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
index 081397827a7ea..58283f4894ea0 100644
--- a/Documentation/rust/general-information.rst
+++ b/Documentation/rust/general-information.rst
@@ -77,3 +77,26 @@ configuration:
 	#[cfg(CONFIG_X="y")]   // Enabled as a built-in (`y`)
 	#[cfg(CONFIG_X="m")]   // Enabled as a module   (`m`)
 	#[cfg(not(CONFIG_X))]  // Disabled
+
+Testing
+-------
+
+There are the tests that come from the examples in the Rust documentation
+and get transformed into KUnit tests. These can be run via KUnit. For example
+via ``kunit_tool`` (``kunit.py``) on the command line::
+
+	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
+
+Alternatively, KUnit can run them as kernel built-in at boot. Refer to
+Documentation/dev-tools/kunit/index.rst for the general KUnit documentation
+and Documentation/dev-tools/kunit/architecture.rst for the details of kernel
+built-in vs. command line testing.
+
+Additionally, there are the ``#[test]`` tests. These can be run using
+``rusttest`` Make target::
+
+	make LLVM=1 rusttest
+
+This requires the kernel .config and downloads external repos. It
+runs the ``#[test]`` tests on the host (currently) and thus is fairly
+limited in what these tests can test.
-- 
2.28.0

Re: [PATCH v4] docs: rust: Add rusttest info

[Benno Lossin]

On 12/12/23 09:13, Dirk Behme wrote:
> Searching the Rust kernel documentation all existing Rust Make
> targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and
> rust-analyzer) are explicitly documented with their Make commands.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make command is not explicitly
> documented, yet. Add a test section to document this.
> 
> While at it, add some info about the more important KUnit testing
> too.
> 
> Reviewed-by: David Gow <davidgow@google.com>
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---

Reviewed-by: Benno Lossin <benno.lossin@proton.me>

-- 
Cheers,
Benno

Re: [PATCH v4] docs: rust: Add rusttest info

[Martin Rodriguez Reboredo]

On 12/12/23 05:13, Dirk Behme wrote:
> Searching the Rust kernel documentation all existing Rust Make
> targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and
> rust-analyzer) are explicitly documented with their Make commands.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make command is not explicitly
> documented, yet. Add a test section to document this.
> 
> While at it, add some info about the more important KUnit testing
> too.
> 
> Reviewed-by: David Gow <davidgow@google.com>
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---
> [...]

Reviewed-by: Martin Rodriguez Reboredo <yakoyoku@gmail.com>

Re: [PATCH v4] docs: rust: Add rusttest info

[Miguel Ojeda]

On Tue, Dec 12, 2023 at 9:14 AM Dirk Behme <dirk.behme@de.bosch.com> wrote:
>
> Searching the Rust kernel documentation all existing Rust Make
> targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and
> rust-analyzer) are explicitly documented with their Make commands.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make command is not explicitly
> documented, yet. Add a test section to document this.
>
> While at it, add some info about the more important KUnit testing
> too.
>
> Reviewed-by: David Gow <davidgow@google.com>
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>

Applied to `rust-next` with a few nits tweaked (added "the", newline
and quotes for `.config`; expanded "repos") -- thanks everyone!

David: your `Reviewed-by` was here but the change substantially
changed from v3 to v4 -- I have kept it, but if you want it out,
please shout :) For instance, perhaps we could simplify the paragraph
about KUnit to just:

    Alternatively, KUnit can run built-in KUnit tests on boot. Please see
    Documentation/dev-tools/kunit/index.rst for details.

since the KUnit docs explain in several places the boot option vs.
`kunit_tool`, and it is one less thing to maintain, but I have left it
as-is.

Cheers,
Miguel

Re: [PATCH v4] docs: rust: Add rusttest info

[David Gow]

[-- Attachment #1: Type: text/plain, Size: 1611 bytes --]

On Fri, 22 Dec 2023 at 05:41, Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> On Tue, Dec 12, 2023 at 9:14 AM Dirk Behme <dirk.behme@de.bosch.com> wrote:
> >
> > Searching the Rust kernel documentation all existing Rust Make
> > targets (rustavailable, rustfmt, rustfmtcheck, rustdoc and
> > rust-analyzer) are explicitly documented with their Make commands.
> > While the Make target rusttest is mentioned two times in the
> > existing documentation, it's Make command is not explicitly
> > documented, yet. Add a test section to document this.
> >
> > While at it, add some info about the more important KUnit testing
> > too.
> >
> > Reviewed-by: David Gow <davidgow@google.com>
> > Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
>
> Applied to `rust-next` with a few nits tweaked (added "the", newline
> and quotes for `.config`; expanded "repos") -- thanks everyone!
>
> David: your `Reviewed-by` was here but the change substantially
> changed from v3 to v4 -- I have kept it, but if you want it out,
> please shout :) For instance, perhaps we could simplify the paragraph
> about KUnit to just:
>
>     Alternatively, KUnit can run built-in KUnit tests on boot. Please see
>     Documentation/dev-tools/kunit/index.rst for details.
>
> since the KUnit docs explain in several places the boot option vs.
> `kunit_tool`, and it is one less thing to maintain, but I have left it
> as-is.


Yeah, this still seems fine to me. I think it'll need updating later
when we support additional types of KUnit tests, but this works for
now.

Thanks,
-- David

[-- Attachment #2: S/MIME Cryptographic Signature --]
[-- Type: application/pkcs7-signature, Size: 4003 bytes --]