From: Dirk Behme <dirk.behme@de.bosch.com>
To: <rust-for-linux@vger.kernel.org>
Cc: <dirk.behme@de.bosch.com>, Miguel Ojeda <ojeda@kernel.org>
Subject: [PATCH] docs: rust: Add description of Rust documentation test as KUnit ones
Date: Mon, 22 Jan 2024 06:42:19 +0100 [thread overview]
Message-ID: <20240122054219.779928-1-dirk.behme@de.bosch.com> (raw)
Rust documentation tests are automatically converted into KUnit
tests. The mainline commit adding this feature
commit a66d733da801 ("rust: support running Rust documentation tests as KUnit ones")
from Mingual has a very nice commit message with a lot details
for this. To not 'hide' that just in a commit message pick main
parts of it and add it to the documentation. And add a short info
how to enable this.
Co-developed-by: Miguel Ojeda <ojeda@kernel.org>
Signed-off-by: Dirk Behme <dirk.behme@de.bosch.com>
---
Documentation/rust/general-information.rst | 94 ++++++++++++++++++++++
1 file changed, 94 insertions(+)
diff --git a/Documentation/rust/general-information.rst b/Documentation/rust/general-information.rst
index 58283f4894ea0..d68460a2fea13 100644
--- a/Documentation/rust/general-information.rst
+++ b/Documentation/rust/general-information.rst
@@ -100,3 +100,97 @@ Additionally, there are the ``#[test]`` tests. These can be run using
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.
+
+KUnit tests == documentation tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Rust has documentation tests: these are typically examples of
+usage of any item (e.g. function, struct, module...).
+
+They are very convenient because they are just written
+alongside the documentation. For instance::
+
+ /// Sums two numbers.
+ ///
+ /// ```
+ /// assert_eq!(mymod::f(10, 20), 30);
+ /// ```
+ pub fn f(a: i32, b: i32) -> i32 {
+ a + b
+ }
+
+In userspace, the tests are collected and run via `rustdoc`.
+Using the tool as-is would be useful already, since it allows
+to compile-test most tests (thus enforcing they are kept
+in sync with the code they document) and run those that do not
+depend on in-kernel APIs.
+
+However, by transforming the tests into a KUnit test suite,
+they can also be run inside the kernel. Moreover, the tests
+get to be compiled as other Rust kernel objects instead of
+targeting userspace.
+
+On top of that, the integration with KUnit means the Rust
+support gets to reuse the existing testing facilities. For
+instance, the kernel log would look like::
+
+ KTAP version 1
+ 1..1
+ KTAP version 1
+ # Subtest: rust_doctests_kernel
+ 1..59
+ # rust_doctest_kernel_build_assert_rs_0.location: rust/kernel/build_assert.rs:13
+ ok 1 rust_doctest_kernel_build_assert_rs_0
+ # rust_doctest_kernel_build_assert_rs_1.location: rust/kernel/build_assert.rs:56
+ ok 2 rust_doctest_kernel_build_assert_rs_1
+ # rust_doctest_kernel_init_rs_0.location: rust/kernel/init.rs:122
+ ok 3 rust_doctest_kernel_init_rs_0
+ ...
+ # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
+ ok 59 rust_doctest_kernel_types_rs_2
+ # rust_doctests_kernel: pass:59 fail:0 skip:0 total:59
+ # Totals: pass:59 fail:0 skip:0 total:59
+ ok 1 rust_doctests_kernel
+
+Tests using the ``?`` operator are also supported as usual, e.g.::
+
+ /// ```
+ /// # use kernel::{spawn_work_item, workqueue};
+ /// spawn_work_item!(workqueue::system(), || pr_info!("x"))?;
+ /// # Ok::<(), Error>(())
+ /// ```
+
+The tests are also compiled with Clippy under ``CLIPPY=1``, just
+like normal code, thus also benefitting from extra linting.
+
+In order for developers to easily see from which original line
+a failed doctests came from, a KTAP diagnostic line is printed
+to the log, containing the location (file and line) of the
+original test (i.e. instead of the location in the generated
+Rust file)::
+
+ # rust_doctest_kernel_types_rs_2.location: rust/kernel/types.rs:150
+
+A notable difference from KUnit C tests is that the Rust tests
+appear to assert using the usual ``assert!`` and ``assert_eq!``
+macros from the Rust standard library (``core``). We provide
+a custom version that forwards the call to KUnit instead.
+Importantly, these macros do not require passing context,
+unlike the KUnit C ones (i.e. ``struct kunit *``). This makes
+them easier to use, and readers of the documentation do not need
+to care about which testing framework is used. In addition, it
+may allow us to test third-party code more easily in the future.
+
+However, a current limitation is that KUnit does not support
+assertions in other tasks. Thus we presently simply print an
+error to the kernel log if an assertion actually failed.
+
+To use this it is required to enable::
+
+ CONFIG_KUNIT
+ Kernel hacking -> Kernel Testing and Coverage -> KUnit - Enable support for unit tests
+ CONFIG_RUST_KERNEL_DOCTESTS
+ Kernel hacking -> Rust hacking -> Doctests for the `kernel` crate
+
+in the kernel config system. Note that these options should
+not be enabled in a production system.
--
2.28.0
next reply other threads:[~2024-01-22 5:42 UTC|newest]
Thread overview: 3+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-01-22 5:42 Dirk Behme [this message]
2024-01-22 10:28 ` [PATCH] docs: rust: Add description of Rust documentation test as KUnit ones Trevor Gross
2024-01-22 10:57 ` Miguel Ojeda
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20240122054219.779928-1-dirk.behme@de.bosch.com \
--to=dirk.behme@de.bosch.com \
--cc=ojeda@kernel.org \
--cc=rust-for-linux@vger.kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).