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 | |
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. |
48 | 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 | 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 | |
108 | fn 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] |
170 | pub 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 | |
227 | const __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 | |
244 | static struct kunit_case test_cases[] = {{ |
245 | {c_test_cases} |
246 | {{ }} |
247 | }}; |
248 | |
249 | static struct kunit_suite test_suite = {{ |
250 | .name = "rust_doctests_kernel" , |
251 | .test_cases = test_cases, |
252 | }}; |
253 | |
254 | kunit_test_suite(test_suite); |
255 | |
256 | MODULE_LICENSE("GPL" ); |
257 | "# |
258 | ) |
259 | .unwrap(); |
260 | } |
261 | |