linux/scripts/rustdoc_test_gen.rs

261 lines
9.5 KiB
Rust
Raw Normal View History

rust: support running Rust documentation tests as KUnit ones 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 Therefore, add support for running Rust documentation tests in KUnit. Some other notes about the current implementation and support follow. The transformation is performed by a couple scripts written as Rust hostprogs. 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. The names of the tests are currently automatically generated. This allows to reduce the burden for documentation writers, while keeping them fairly stable for bisection. This is an improvement over the `rustdoc`-generated names, which include the line number; but ideally we would like to get `rustdoc` to provide the Rust item path and a number (for multiple examples in a single documented Rust item). 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 This line follows the syntax for declaring test metadata in the proposed KTAP v2 spec [1], which may be used for the proposed KUnit test attributes API [2]. Thus hopefully this will make migration easier later on (suggested by David [3]). The original line in that test attribute is figured out by providing an anchor (suggested by Boqun [4]). The original file is found by walking the filesystem, checking directory prefixes to reduce the amount of combinations to check, and it is only done once per file. Ambiguities are detected and reported. 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. This should be revisited to properly fail the test, perhaps saving the context somewhere else, or letting KUnit handle it. Link: https://lore.kernel.org/lkml/20230420205734.1288498-1-rmoar@google.com/ [1] Link: https://lore.kernel.org/linux-kselftest/20230707210947.1208717-1-rmoar@google.com/ [2] Link: https://lore.kernel.org/rust-for-linux/CABVgOSkOLO-8v6kdAGpmYnZUb+LKOX0CtYCo-Bge7r_2YTuXDQ@mail.gmail.com/ [3] Link: https://lore.kernel.org/rust-for-linux/ZIps86MbJF%2FiGIzd@boqun-archlinux/ [4] Signed-off-by: Miguel Ojeda <ojeda@kernel.org> Reviewed-by: David Gow <davidgow@google.com> Signed-off-by: Shuah Khan <skhan@linuxfoundation.org>
2023-07-18 13:27:51 +08:00
// SPDX-License-Identifier: GPL-2.0
//! Generates KUnit tests from saved `rustdoc`-generated tests.
//!
//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
//! KUnit functions and macros.
//!
//! However, we want to keep this as an implementation detail because:
//!
//! - Test code should not care about the implementation.
//!
//! - Documentation looks worse if it needs to carry extra details unrelated to the piece
//! being described.
//!
//! - Test code should be able to define functions and call them, without having to carry
//! the context.
//!
//! - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
//! third-party crates) which likely use the standard library `assert*!` macros.
//!
//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
//! (i.e. `current->kunit_test`).
//!
//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
//! not support assertions (only expectations) from other tasks. Thus leave that feature for
//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
//! other tasks, but that seems overly constraining, and we do want to support them, eventually.
use std::{
fs,
fs::File,
io::{BufWriter, Read, Write},
path::{Path, PathBuf},
};
/// Find the real path to the original file based on the `file` portion of the test name.
///
/// `rustdoc` generated `file`s look like `sync_locked_by_rs`. Underscores (except the last one)
/// may represent an actual underscore in a directory/file, or a path separator. Thus the actual
/// file might be `sync_locked_by.rs`, `sync/locked_by.rs`, `sync_locked/by.rs` or
/// `sync/locked/by.rs`. This function walks the file system to determine which is the real one.
///
/// This does require that ambiguities do not exist, but that seems fair, especially since this is
/// all supposed to be temporary until `rustdoc` gives us proper metadata to build this. If such
/// ambiguities are detected, they are diagnosed and the script panics.
fn find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec<PathBuf>, file: &str) -> &'a str {
valid_paths.clear();
let potential_components: Vec<&str> = file.strip_suffix("_rs").unwrap().split('_').collect();
find_candidates(srctree, valid_paths, Path::new(""), &potential_components);
fn find_candidates(
srctree: &Path,
valid_paths: &mut Vec<PathBuf>,
prefix: &Path,
potential_components: &[&str],
) {
// The base case: check whether all the potential components left, joined by underscores,
// is a file.
let joined_potential_components = potential_components.join("_") + ".rs";
if srctree
.join("rust/kernel")
.join(prefix)
.join(&joined_potential_components)
.is_file()
{
// Avoid `srctree` here in order to keep paths relative to it in the KTAP output.
valid_paths.push(
Path::new("rust/kernel")
.join(prefix)
.join(joined_potential_components),
);
}
// In addition, check whether each component prefix, joined by underscores, is a directory.
// If not, there is no need to check for combinations with that prefix.
for i in 1..potential_components.len() {
let (components_prefix, components_rest) = potential_components.split_at(i);
let prefix = prefix.join(components_prefix.join("_"));
if srctree.join("rust/kernel").join(&prefix).is_dir() {
find_candidates(srctree, valid_paths, &prefix, components_rest);
}
}
}
assert!(
valid_paths.len() > 0,
"No path candidates found. This is likely a bug in the build system, or some files went \
away while compiling."
);
if valid_paths.len() > 1 {
eprintln!("Several path candidates found:");
for path in valid_paths {
eprintln!(" {path:?}");
}
panic!(
"Several path candidates found, please resolve the ambiguity by renaming a file or \
folder."
);
}
valid_paths[0].to_str().unwrap()
}
fn main() {
let srctree = std::env::var("srctree").unwrap();
let srctree = Path::new(&srctree);
let mut paths = fs::read_dir("rust/test/doctests/kernel")
.unwrap()
.map(|entry| entry.unwrap().path())
.collect::<Vec<_>>();
// Sort paths.
paths.sort();
let mut rust_tests = String::new();
let mut c_test_declarations = String::new();
let mut c_test_cases = String::new();
let mut body = String::new();
let mut last_file = String::new();
let mut number = 0;
let mut valid_paths: Vec<PathBuf> = Vec::new();
let mut real_path: &str = "";
for path in paths {
// The `name` follows the `{file}_{line}_{number}` pattern (see description in
// `scripts/rustdoc_test_builder.rs`). Discard the `number`.
let name = path.file_name().unwrap().to_str().unwrap().to_string();
// Extract the `file` and the `line`, discarding the `number`.
let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
// Generate an ID sequence ("test number") for each one in the file.
if file == last_file {
number += 1;
} else {
number = 0;
last_file = file.to_string();
// Figure out the real path, only once per file.
real_path = find_real_path(srctree, &mut valid_paths, file);
}
// Generate a KUnit name (i.e. test name and C symbol) for this test.
//
// We avoid the line number, like `rustdoc` does, to make things slightly more stable for
// bisection purposes. However, to aid developers in mapping back what test failed, we will
// print a diagnostics line in the KTAP report.
let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
// Read the test's text contents to dump it below.
body.clear();
File::open(path).unwrap().read_to_string(&mut body).unwrap();
// Calculate how many lines before `main` function (including the `main` function line).
let body_offset = body
.lines()
.take_while(|line| !line.contains("fn main() {"))
.count()
+ 1;
use std::fmt::Write;
write!(
rust_tests,
r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
#[no_mangle]
pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
/// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
#[allow(unused)]
macro_rules! assert {{
($cond:expr $(,)?) => {{{{
kernel::kunit_assert!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond);
}}}}
}}
/// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
#[allow(unused)]
macro_rules! assert_eq {{
($left:expr, $right:expr $(,)?) => {{{{
kernel::kunit_assert_eq!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right);
}}}}
}}
// Many tests need the prelude, so provide it by default.
#[allow(unused)]
use kernel::prelude::*;
// Unconditionally print the location of the original doctest (i.e. rather than the location in
// the generated file) so that developers can easily map the test back to the source code.
//
// This information is also printed when assertions fail, but this helps in the successful cases
// when the user is running KUnit manually, or when passing `--raw_output` to `kunit.py`.
//
// This follows the syntax for declaring test metadata in the proposed KTAP v2 spec, which may
// be used for the proposed KUnit test attributes API. Thus hopefully this will make migration
// easier later on.
kernel::kunit::info(format_args!(" # {kunit_name}.location: {real_path}:{line}\n"));
/// The anchor where the test code body starts.
#[allow(unused)]
static __DOCTEST_ANCHOR: i32 = core::line!() as i32 + {body_offset} + 1;
{{
{body}
main();
}}
}}
"#
)
.unwrap();
write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
write!(c_test_cases, " KUNIT_CASE({kunit_name}),\n").unwrap();
}
let rust_tests = rust_tests.trim();
let c_test_declarations = c_test_declarations.trim();
let c_test_cases = c_test_cases.trim();
write!(
BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
r#"//! `kernel` crate documentation tests.
const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
{rust_tests}
"#
)
.unwrap();
write!(
BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
r#"/*
* `kernel` crate documentation tests.
*/
#include <kunit/test.h>
{c_test_declarations}
static struct kunit_case test_cases[] = {{
{c_test_cases}
{{ }}
}};
static struct kunit_suite test_suite = {{
.name = "rust_doctests_kernel",
.test_cases = test_cases,
}};
kunit_test_suite(test_suite);
MODULE_LICENSE("GPL");
"#
)
.unwrap();
}