Commit | Line | Data |
---|---|---|
a66d733d MO |
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 | } |