[PATCH v3] docs: rust: Add rusttest info

[PATCH v3] 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 syntax.
While the Make target rusttest is mentioned two times in the
existing documentation, it's Make syntax is not explicitly
documented, yet. Add a test section to document this.

Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
---

v3: Add the comments from Benno and Miguel. Thanks!

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

diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
index 081397827a7ea..016c7feb433ce 100644
--- a/Documentation/rust/general-information.rst
+++ b/Documentation/rust/general-information.rst
@@ -77,3 +77,22 @@ 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
+-------
+
+To run the Rust tests, you can use the following 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.
+
+Additonally, 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::
+
+	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
+
+See the :doc:`KUnit documentation</dev-tools/kunit/index>` for the details how to use it.
-- 
2.28.0

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

[Mika Westerberg]

Hi,

On Mon, Dec 11, 2023 at 01:16:13PM +0100, 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 syntax.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make syntax is not explicitly
> documented, yet. Add a test section to document this.
> 
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---
> 
> v3: Add the comments from Benno and Miguel. Thanks!
> 
>  Documentation/rust/general-information.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
> index 081397827a7ea..016c7feb433ce 100644
> --- a/Documentation/rust/general-information.rst
> +++ b/Documentation/rust/general-information.rst
> @@ -77,3 +77,22 @@ 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
> +-------
> +
> +To run the Rust tests, you can use the following 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.
> +
> +Additonally, there are the tests that come from the examples in the

Typo: Additonally -> Additionally

> +Rust documentation and get transformed into KUnit tests. These can be
> +run via KUnit. For example::
> +
> +	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
> +
> +See the :doc:`KUnit documentation</dev-tools/kunit/index>` for the details how to use it.
> -- 
> 2.28.0
> 

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

[Miguel Ojeda]

On Mon, Dec 11, 2023 at 1:16 PM Dirk Behme <dirk.behme@de.bosch.com> wrote:
>
> existing documentation, it's Make syntax is not explicitly
> documented, yet. Add a test section to document this.

Nit: what syntax are you referring to? i.e. the Make targets do not
really have syntax. I imagine you mean there is no example? In that
case, I would say so.

> +Additonally, there are the tests that come from the examples in the

On top of what Mika said: if you pass the `--codespell*` options to
`checkpatch.pl` you can get your patches typo-checked. It is quite
handy!

> +Rust documentation and get transformed into KUnit tests. These can be
> +run via KUnit. For example::

The KUnit tests are the most important ones currently, so I would
prefer to put those first if you don't mind. Also, if we are going to
mention this line of how to run the tests, I would also mention that
they can be run by booting the kernel for symmetry (please see the
KUnit docs on the 2 ways of running the docs).

> +See the :doc:`KUnit documentation</dev-tools/kunit/index>` for the details how to use it.

We can simply write the path (e.g. see what we do for another case
grepping for `Documentation/kbuild/llvm.rst`). It should automatically
figure out that it is a link, create the link, use its title, etc.

Thanks!

Cheers,
Miguel

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

[John Hubbard]

On 12/11/23 04:16, 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 syntax.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make syntax is not explicitly
> documented, yet. Add a test section to document this.
> 
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---
> 
> v3: Add the comments from Benno and Miguel. Thanks!
> 
>   Documentation/rust/general-information.rst | 19 +++++++++++++++++++
>   1 file changed, 19 insertions(+)
> 
> diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
> index 081397827a7ea..016c7feb433ce 100644
> --- a/Documentation/rust/general-information.rst
> +++ b/Documentation/rust/general-information.rst
> @@ -77,3 +77,22 @@ 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
> +-------
> +
> +To run the Rust tests, you can use the following make target::
> +
> +	make LLVM=1 rusttest

"make LLVM=1 <anything>" doesn't work for me, and therefore I suspect it
doesn't work for at least a few other people, as well.

Instead, I have to run "make CC=clang <anything>", which works just
fine.

The docs should consistently reflect this, yes?

> +
> +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.
> +
> +Additonally, 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::
> +
> +	./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y

Very helpful! Coming mostly from linux-mm, if someone says "run KUnit", I
have to pause and maybe go look it up, but having the command right in
front of me makes it all easy again. :)

Same comment about LLVM=1 vs. CC=clang, though.

> +
> +See the :doc:`KUnit documentation</dev-tools/kunit/index>` for the details how to use it.

Also good.


thanks,
-- 
John Hubbard
NVIDIA

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

[David Gow]

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

On Mon, 11 Dec 2023 at 20:16, 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 syntax.
> While the Make target rusttest is mentioned two times in the
> existing documentation, it's Make syntax is not explicitly
> documented, yet. Add a test section to document this.
>
> Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
> ---

The KUnit parts of this look fine to me, though it's not actually
necessary to use --arch x86_64; the default UML should work (if your
host is x86).

There was a previous PR to add some documentation here:
https://github.com/Rust-for-Linux/linux/pull/935

Maybe it'd make sense to borrow some ideas from that and create a
rust/.kunitconfig file so we can move the --kconfig_add CONFIG_RUST=y
(and any other options we may want to enable rust-specific tests)
somewhere.

(Though there's a distinction there between 'I want to test that Rust
support is functional' and 'I want to test something else, but want
Rust support enabled'. I think adding a .kunitconfig would be fine for
both for the time being, though.)

None of those are show-stoppers for me, though, so this is nevertheless

Reviewed-by: David Gow <davidgow@google.com>

Cheers,
-- David

>
> v3: Add the comments from Benno and Miguel. Thanks!
>
>  Documentation/rust/general-information.rst | 19 +++++++++++++++++++
>  1 file changed, 19 insertions(+)
>
> diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
> index 081397827a7ea..016c7feb433ce 100644
> --- a/Documentation/rust/general-information.rst
> +++ b/Documentation/rust/general-information.rst
> @@ -77,3 +77,22 @@ 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
> +-------
> +
> +To run the Rust tests, you can use the following 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.
> +
> +Additonally, 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::
> +
> +       ./tools/testing/kunit/kunit.py run --make_options LLVM=1 --arch x86_64 --kconfig_add CONFIG_RUST=y
> +
> +See the :doc:`KUnit documentation</dev-tools/kunit/index>` for the details how to use it.
> --
> 2.28.0
>
>

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

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

[Miguel Ojeda]

On Tue, Dec 12, 2023 at 4:14 AM John Hubbard <jhubbard@nvidia.com> wrote:
>
> "make LLVM=1 <anything>" doesn't work for me, and therefore I suspect it
> doesn't work for at least a few other people, as well.
>
> Instead, I have to run "make CC=clang <anything>", which works just
> fine.
>
> The docs should consistently reflect this, yes?

No, they should not. `LLVM=1` is the "right" one for all architectures
(except s390) -- see Documentation/kbuild/llvm.rst.

If `LLVM=1` does not work for you, then that should be fixed. Could
you please give some details? For instance, is it related to Rust
(does it work with a `defconfig` build without enabling Rust)? Do you
have all the LLVM software installed with the right names (see what
`LLVM=1` expands to)? etc.

(Cc'ing Nathan)

Cheers,
Miguel

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

[Nathan Chancellor]

On Tue, Dec 12, 2023 at 01:43:16PM +0100, Miguel Ojeda wrote:
> On Tue, Dec 12, 2023 at 4:14 AM John Hubbard <jhubbard@nvidia.com> wrote:
> >
> > "make LLVM=1 <anything>" doesn't work for me, and therefore I suspect it
> > doesn't work for at least a few other people, as well.
> >
> > Instead, I have to run "make CC=clang <anything>", which works just
> > fine.
> >
> > The docs should consistently reflect this, yes?
> 
> No, they should not. `LLVM=1` is the "right" one for all architectures
> (except s390) -- see Documentation/kbuild/llvm.rst.
> 
> If `LLVM=1` does not work for you, then that should be fixed. Could
> you please give some details? For instance, is it related to Rust
> (does it work with a `defconfig` build without enabling Rust)? Do you
> have all the LLVM software installed with the right names (see what
> `LLVM=1` expands to)? etc.

Right, there are definitely edges cases with LLVM=1, namely for s390 as
mentioned as well as powerpc but for at least arm{,64} and x86{,_64},
things should work well and they should be fixed if not. Additional
information and bug reports are always welcomed at either
llvm@lists.linux.dev or https://github.com/ClangBuiltLinux/linux/issues.

Cheers,
Nathan

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

[Miguel Ojeda]

On Tue, Dec 12, 2023 at 5:36 AM David Gow <davidgow@google.com> wrote:
>
> Maybe it'd make sense to borrow some ideas from that and create a
> rust/.kunitconfig file so we can move the --kconfig_add CONFIG_RUST=y
> (and any other options we may want to enable rust-specific tests)
> somewhere.

Yeah, that may be a good idea for "core" Rust stuff (I imagine
subsystems could/should independently/eventually add Rust on their own
if they use it in any case). We also have `kernel/configs/rust.config`
for Make.

Cheers,
Miguel

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

[John Hubbard]

On 12/12/23 04:43, Miguel Ojeda wrote:
> On Tue, Dec 12, 2023 at 4:14 AM John Hubbard <jhubbard@nvidia.com> wrote:
>>
>> "make LLVM=1 <anything>" doesn't work for me, and therefore I suspect it
>> doesn't work for at least a few other people, as well.
>>
>> Instead, I have to run "make CC=clang <anything>", which works just
>> fine.
>>
>> The docs should consistently reflect this, yes?
> 
> No, they should not. `LLVM=1` is the "right" one for all architectures
> (except s390) -- see Documentation/kbuild/llvm.rst.

ah OK. I appear to have been slightly misled by
Documentation/rust/quick-start.rst, which made it seem like CC=clang
was...a thing. This excerpt made me do it:

Building a kernel with a complete LLVM toolchain is the best supported setup
at the moment. That is::

	make LLVM=1

For architectures that do not support a full LLVM toolchain, use::

	make CC=clang


> 
> If `LLVM=1` does not work for you, then that should be fixed. Could
> you please give some details? For instance, is it related to Rust
> (does it work with a `defconfig` build without enabling Rust)? Do you
> have all the LLVM software installed with the right names (see what
> `LLVM=1` expands to)? etc.
> 
> (Cc'ing Nathan)
> 

Probably just a basic failure to fully set up LLVM on my part. I'll
use the bug reporting that Nathan pointed to, if it turns out that
there is anything actually wrong upstream. I just short-circuited
the whole investigation (it's a "quick" start, after all) when I
saw the CC=clang point.

Anyway, I wanted to provide this "how does the documentation look
to a newcomer" feedback, in case it helps.


thanks,
-- 
John Hubbard
NVIDIA

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

[Miguel Ojeda]

On Wed, Dec 13, 2023 at 2:44 AM John Hubbard <jhubbard@nvidia.com> wrote:
>
> ah OK. I appear to have been slightly misled by
> Documentation/rust/quick-start.rst, which made it seem like CC=clang
> was...a thing. This excerpt made me do it:

Yeah, it is the "old way" for many architectures, but nowadays
`LLVM=1` is the recommended way for most (in the last couple years a
few architectures got promoted from `CC=clang` to `LLVM=1`).

Given that most arches are `LLVM=1` nowadays, including those that we
currently support Rust for, and that perhaps by the time e.g. s390
supports Rust it is also a `LLVM=1` architecture, we should probably
just remove `CC=clang` at this point and perhaps add an extra link to
Documentation/kbuild/llvm.rst again just in case (the link is also
elsewhere in that document, but I guess it does not hurt).

I will send a patch.

> Anyway, I wanted to provide this "how does the documentation look
> to a newcomer" feedback, in case it helps.

It does -- thanks a lot!

Cheers,
Miguel

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

[Miguel Ojeda]

On Fri, Dec 15, 2023 at 11:43 AM Miguel Ojeda
<miguel.ojeda.sandonis@gmail.com> wrote:
>
> Yeah, it is the "old way" for many architectures, but nowadays
> `LLVM=1` is the recommended way for most (in the last couple years a
> few architectures got promoted from `CC=clang` to `LLVM=1`).
>
> Given that most arches are `LLVM=1` nowadays, including those that we
> currently support Rust for, and that perhaps by the time e.g. s390
> supports Rust it is also a `LLVM=1` architecture, we should probably
> just remove `CC=clang` at this point and perhaps add an extra link to
> Documentation/kbuild/llvm.rst again just in case (the link is also
> elsewhere in that document, but I guess it does not hurt).
>
> I will send a patch.

Patch at https://lore.kernel.org/rust-for-linux/20231215124751.175191-1-ojeda@kernel.org/

Hope that helps! (and, sorry, I should have Cc'd you in that one).

Cheers,
Miguel