rustdoc_test_gen.rs

  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` or third-party
 19//!     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    match valid_paths.as_slice() {
 89        [] => panic!(
 90            "No path candidates found for `{file}`. This is likely a bug in the build system, or \
 91            some files went away while compiling."
 92        ),
 93        [valid_path] => valid_path.to_str().unwrap(),
 94        valid_paths => {
 95            use std::fmt::Write;
 96
 97            let mut candidates = String::new();
 98            for path in valid_paths {
 99                writeln!(&mut candidates, "    {path:?}").unwrap();
100            }
101            panic!(
102                "Several path candidates found for `{file}`, please resolve the ambiguity by \
103                renaming a file or folder. Candidates:\n{candidates}",
104            );
105        }
106    }
107}
108
109fn main() {
110    let srctree = std::env::var("srctree").unwrap();
111    let srctree = Path::new(&srctree);
112
113    let mut paths = fs::read_dir("rust/test/doctests/kernel")
114        .unwrap()
115        .map(|entry| entry.unwrap().path())
116        .collect::<Vec<_>>();
117
118    // Sort paths.
119    paths.sort();
120
121    let mut rust_tests = String::new();
122    let mut c_test_declarations = String::new();
123    let mut c_test_cases = String::new();
124    let mut body = String::new();
125    let mut last_file = String::new();
126    let mut number = 0;
127    let mut valid_paths: Vec<PathBuf> = Vec::new();
128    let mut real_path: &str = "";
129    for path in paths {
130        // The `name` follows the `{file}_{line}_{number}` pattern (see description in
131        // `scripts/rustdoc_test_builder.rs`). Discard the `number`.
132        let name = path.file_name().unwrap().to_str().unwrap().to_string();
133
134        // Extract the `file` and the `line`, discarding the `number`.
135        let (file, line) = name.rsplit_once('_').unwrap().0.rsplit_once('_').unwrap();
136
137        // Generate an ID sequence ("test number") for each one in the file.
138        if file == last_file {
139            number += 1;
140        } else {
141            number = 0;
142            last_file = file.to_string();
143
144            // Figure out the real path, only once per file.
145            real_path = find_real_path(srctree, &mut valid_paths, file);
146        }
147
148        // Generate a KUnit name (i.e. test name and C symbol) for this test.
149        //
150        // We avoid the line number, like `rustdoc` does, to make things slightly more stable for
151        // bisection purposes. However, to aid developers in mapping back what test failed, we will
152        // print a diagnostics line in the KTAP report.
153        let kunit_name = format!("rust_doctest_kernel_{file}_{number}");
154
155        // Read the test's text contents to dump it below.
156        body.clear();
157        File::open(path).unwrap().read_to_string(&mut body).unwrap();
158
159        // Calculate how many lines before `main` function (including the `main` function line).
160        let body_offset = body
161            .lines()
162            .take_while(|line| !line.contains("fn main() {"))
163            .count()
164            + 1;
165
166        use std::fmt::Write;
167        write!(
168            rust_tests,
169            r#"/// Generated `{name}` KUnit test case from a Rust documentation test.
170#[no_mangle]
171pub extern "C" fn {kunit_name}(__kunit_test: *mut ::kernel::bindings::kunit) {{
172    /// Overrides the usual [`assert!`] macro with one that calls KUnit instead.
173    #[allow(unused)]
174    macro_rules! assert {{
175        ($cond:expr $(,)?) => {{{{
176            ::kernel::kunit_assert!(
177                "{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $cond
178            );
179        }}}}
180    }}
181
182    /// Overrides the usual [`assert_eq!`] macro with one that calls KUnit instead.
183    #[allow(unused)]
184    macro_rules! assert_eq {{
185        ($left:expr, $right:expr $(,)?) => {{{{
186            ::kernel::kunit_assert_eq!(
187                "{kunit_name}", "{real_path}", __DOCTEST_ANCHOR - {line}, $left, $right
188            );
189        }}}}
190    }}
191
192    // Many tests need the prelude, so provide it by default.
193    #[allow(unused)]
194    use ::kernel::prelude::*;
195
196    // Unconditionally print the location of the original doctest (i.e. rather than the location in
197    // the generated file) so that developers can easily map the test back to the source code.
198    //
199    // This information is also printed when assertions fail, but this helps in the successful cases
200    // when the user is running KUnit manually, or when passing `--raw_output` to `kunit.py`.
201    //
202    // This follows the syntax for declaring test metadata in the proposed KTAP v2 spec, which may
203    // be used for the proposed KUnit test attributes API. Thus hopefully this will make migration
204    // easier later on.
205    ::kernel::kunit::info(fmt!("    # {kunit_name}.location: {real_path}:{line}\n"));
206
207    /// The anchor where the test code body starts.
208    #[allow(unused)]
209    static __DOCTEST_ANCHOR: i32 = ::core::line!() as i32 + {body_offset} + 2;
210    {{
211        #![allow(unreachable_pub, clippy::disallowed_names)]
212        {body}
213        main();
214    }}
215}}
216
217"#
218        )
219        .unwrap();
220
221        write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
222        write!(c_test_cases, "    KUNIT_CASE({kunit_name}),\n").unwrap();
223    }
224
225    let rust_tests = rust_tests.trim();
226    let c_test_declarations = c_test_declarations.trim();
227    let c_test_cases = c_test_cases.trim();
228
229    write!(
230        BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
231        r#"//! `kernel` crate documentation tests.
232
233const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
234
235{rust_tests}
236"#
237    )
238    .unwrap();
239
240    write!(
241        BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
242        r#"/*
243 * `kernel` crate documentation tests.
244 */
245
246#include <kunit/test.h>
247
248{c_test_declarations}
249
250static struct kunit_case test_cases[] = {{
251    {c_test_cases}
252    {{ }}
253}};
254
255static struct kunit_suite test_suite = {{
256    .name = "rust_doctests_kernel",
257    .test_cases = test_cases,
258}};
259
260kunit_test_suite(test_suite);
261
262MODULE_LICENSE("GPL");
263"#
264    )
265    .unwrap();
266}