1// SPDX-License-Identifier: GPL-2.0
2
3//! Generates KUnit tests from saved `rustdoc`-generated tests.
4//!
5//! KUnit passes a context (`struct kunit *`) to each test, which should be forwarded to the other
6//! KUnit functions and macros.
7//!
8//! However, we want to keep this as an implementation detail because:
9//!
10//!   - Test code should not care about the implementation.
11//!
12//!   - Documentation looks worse if it needs to carry extra details unrelated to the piece
13//!     being described.
14//!
15//!   - Test code should be able to define functions and call them, without having to carry
16//!     the context.
17//!
18//!   - Later on, we may want to be able to test non-kernel code (e.g. `core`, `alloc` or
19//!     third-party crates) which likely use the standard library `assert*!` macros.
20//!
21//! For this reason, instead of the passed context, `kunit_get_current_test()` is used instead
22//! (i.e. `current->kunit_test`).
23//!
24//! Note that this means other threads/tasks potentially spawned by a given test, if failing, will
25//! report the failure in the kernel log but will not fail the actual test. Saving the pointer in
26//! e.g. a `static` per test does not fully solve the issue either, because currently KUnit does
27//! not support assertions (only expectations) from other tasks. Thus leave that feature for
28//! the future, which simplifies the code here too. We could also simply not allow `assert`s in
29//! other tasks, but that seems overly constraining, and we do want to support them, eventually.
30
31use std::{
32    fs,
33    fs::File,
34    io::{BufWriter, Read, Write},
35    path::{Path, PathBuf},
36};
37
38/// Find the real path to the original file based on the `file` portion of the test name.
39///
40/// `rustdoc` generated `file`s look like `sync_locked_by_rs`. Underscores (except the last one)
41/// may represent an actual underscore in a directory/file, or a path separator. Thus the actual
42/// file might be `sync_locked_by.rs`, `sync/locked_by.rs`, `sync_locked/by.rs` or
43/// `sync/locked/by.rs`. This function walks the file system to determine which is the real one.
44///
45/// This does require that ambiguities do not exist, but that seems fair, especially since this is
46/// all supposed to be temporary until `rustdoc` gives us proper metadata to build this. If such
47/// ambiguities are detected, they are diagnosed and the script panics.
48fn find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec<PathBuf>, file: &str) -> &'a str {
49    valid_paths.clear();
50
51    let potential_components: Vec<&str> = file.strip_suffix("_rs").unwrap().split('_').collect();
52
53    find_candidates(srctree, valid_paths, Path::new(""), &potential_components);
54    fn find_candidates(
55        srctree: &Path,
56        valid_paths: &mut Vec<PathBuf>,
57        prefix: &Path,
58        potential_components: &[&str],
59    ) {
60        // The base case: check whether all the potential components left, joined by underscores,
61        // is a file.
62        let joined_potential_components = potential_components.join("_") + ".rs";
63        if srctree
64            .join("rust/kernel")
65            .join(prefix)
66            .join(&joined_potential_components)
67            .is_file()
68        {
69            // Avoid `srctree` here in order to keep paths relative to it in the KTAP output.
70            valid_paths.push(
71                Path::new("rust/kernel")
72                    .join(prefix)
73                    .join(joined_potential_components),
74            );
75        }
76
77        // In addition, check whether each component prefix, joined by underscores, is a directory.
78        // If not, there is no need to check for combinations with that prefix.
79        for i in 1..potential_components.len() {
80            let (components_prefix, components_rest) = potential_components.split_at(i);
81            let prefix = prefix.join(components_prefix.join("_"));
82            if srctree.join("rust/kernel").join(&prefix).is_dir() {
83                find_candidates(srctree, valid_paths, &prefix, components_rest);
84            }
85        }
86    }
87
88    assert!(
89        valid_paths.len() > 0,
90        "No path candidates found. This is likely a bug in the build system, or some files went \
91        away while compiling."
92    );
93
94    if valid_paths.len() > 1 {
95        eprintln!("Several path candidates found:");
96        for path in valid_paths {
97            eprintln!("    {path:?}");
98        }
99        panic!(
100            "Several path candidates found, please resolve the ambiguity by renaming a file or \
101            folder."
102        );
103    }
104
105    valid_paths[0].to_str().unwrap()
106}
107
108fn main() {
109    let srctree = std::env::var("srctree").unwrap();
110    let srctree = Path::new(&srctree);
111
112    let mut paths = fs::read_dir("rust/test/doctests/kernel")
113        .unwrap()
114        .map(|entry| entry.unwrap().path())
115        .collect::<Vec<_>>();
116
117    // Sort paths.
118    paths.sort();
119
120    let mut rust_tests = String::new();
121    let mut c_test_declarations = String::new();
122    let mut c_test_cases = String::new();
123    let mut body = String::new();
124    let mut last_file = String::new();
125    let mut number = 0;
126    let mut valid_paths: Vec<PathBuf> = Vec::new();
127    let mut real_path: &str = "";
128    for path in paths {
129        // The `name` follows the `{file}_{line}_{number}` pattern (see description in
130        // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
131        let name = path.file_name().unwrap().to_str().unwrap().to_string();
132
133        // Extract the `file` and the `line`, discarding the `number`.
134        let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
135
136        // Generate an ID sequence ("test number") for each one in the file.
137        if file == last_file {
138            number += 1;
139        } else {
140            number = 0;
141            last_file = file.to_string();
142
143            // Figure out the real path, only once per file.
144            real_path = find_real_path(srctree, &mut valid_paths, file);
145        }
146
147        // Generate a KUnit name (i.e. test name and C symbol) for this test.
148        //
149        // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
150        // bisection purposes. However, to aid developers in mapping back what test failed, we will
151        // print a diagnostics line in the KTAP report.
152        let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
153
154        // Read the test's text contents to dump it below.
155        body.clear();
156        File::open(path).unwrap().read_to_string(&mut body).unwrap();
157
158        // Calculate how many lines before `main` function (including the `main` function line).
159        let body_offset = body
160            .lines()
161            .take_while(|line| !line.contains("fn main() {"))
162            .count()
163            + 1;
164
165        use std::fmt::Write;
166        write!(
167            rust_tests,
168            r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
169#[no_mangle]
170pub extern "C" fn {kunit_name}(__kunit_test: *mut kernel::bindings::kunit) {{
171    /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
172    #[allow(unused)]
173    macro_rules! assert {{
174        ($cond:expr $(,)?) => {{{{
175            kernel::kunit_assert!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond);
176        }}}}
177    }}
178
179    /// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
180    #[allow(unused)]
181    macro_rules! assert_eq {{
182        ($left:expr, $right:expr $(,)?) => {{{{
183            kernel::kunit_assert_eq!("{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right);
184        }}}}
185    }}
186
187    // Many tests need the prelude, so provide it by default.
188    #[allow(unused)]
189    use kernel::prelude::*;
190
191    // Unconditionally print the location of the original doctest (i.e. rather than the location in
192    // the generated file) so that developers can easily map the test back to the source code.
193    //
194    // This information is also printed when assertions fail, but this helps in the successful cases
195    // when the user is running KUnit manually, or when passing `--raw_output` to `kunit.py`.
196    //
197    // This follows the syntax for declaring test metadata in the proposed KTAP v2 spec, which may
198    // be used for the proposed KUnit test attributes API. Thus hopefully this will make migration
199    // easier later on.
200    kernel::kunit::info(format_args!("    # {kunit_name}.location: {real_path}:{line}\n"));
201
202    /// The anchor where the test code body starts.
203    #[allow(unused)]
204    static __DOCTEST_ANCHOR: i32 = core::line!() as i32 + {body_offset} + 1;
205    {{
206        {body}
207        main();
208    }}
209}}
210
211"#
212        )
213        .unwrap();
214
215        write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
216        write!(c_test_cases, "    KUNIT_CASE({kunit_name}),\n").unwrap();
217    }
218
219    let rust_tests = rust_tests.trim();
220    let c_test_declarations = c_test_declarations.trim();
221    let c_test_cases = c_test_cases.trim();
222
223    write!(
224        BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
225        r#"//! `kernel` crate documentation tests.
226
227const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
228
229{rust_tests}
230"#
231    )
232    .unwrap();
233
234    write!(
235        BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
236        r#"/*
237 * `kernel` crate documentation tests.
238 */
239
240#include <kunit/test.h>
241
242{c_test_declarations}
243
244static struct kunit_case test_cases[] = {{
245    {c_test_cases}
246    {{ }}
247}};
248
249static struct kunit_suite test_suite = {{
250    .name = "rust_doctests_kernel",
251    .test_cases = test_cases,
252}};
253
254kunit_test_suite(test_suite);
255
256MODULE_LICENSE("GPL");
257"#
258    )
259    .unwrap();
260}
261