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
31 use 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.
find_real_path<'a>(srctree: &Path, valid_paths: &'a mut Vec<PathBuf>, file: &str) -> &'a str48 fn 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
main()109 fn 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]
171 pub 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(format_args!(" # {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} + 1;
210 {{
211 {body}
212 main();
213 }}
214 }}
215
216 "#
217 )
218 .unwrap();
219
220 write!(c_test_declarations, "void {kunit_name}(struct kunit *);\n").unwrap();
221 write!(c_test_cases, " KUNIT_CASE({kunit_name}),\n").unwrap();
222 }
223
224 let rust_tests = rust_tests.trim();
225 let c_test_declarations = c_test_declarations.trim();
226 let c_test_cases = c_test_cases.trim();
227
228 write!(
229 BufWriter::new(File::create("rust/doctests_kernel_generated.rs").unwrap()),
230 r#"//! `kernel` crate documentation tests.
231
232 const __LOG_PREFIX: &[u8] = b"rust_doctests_kernel\0";
233
234 {rust_tests}
235 "#
236 )
237 .unwrap();
238
239 write!(
240 BufWriter::new(File::create("rust/doctests_kernel_generated_kunit.c").unwrap()),
241 r#"/*
242 * `kernel` crate documentation tests.
243 */
244
245 #include <kunit/test.h>
246
247 {c_test_declarations}
248
249 static struct kunit_case test_cases[] = {{
250 {c_test_cases}
251 {{ }}
252 }};
253
254 static struct kunit_suite test_suite = {{
255 .name = "rust_doctests_kernel",
256 .test_cases = test_cases,
257 }};
258
259 kunit_test_suite(test_suite);
260
261 MODULE_LICENSE("GPL");
262 "#
263 )
264 .unwrap();
265 }
266