Add support for doctests (#52)

Author: Freax13

azure-pipelines.yml

@@ -191,6 +191,10 @@ jobs:
     workingDirectory: example-kernels/runner
     displayName: 'Run `cargo xrun` for "runner" kernel'
 
+  - script: cargo xtest -Z doctest-xcompile
+    workingDirectory: example-kernels/runner-doctest
+    displayName: 'Run `cargo xtest -Z doctest-xcompile` for "runner-doctest" kernel'
+
   - script: cargo xtest
     workingDirectory: example-kernels/runner-test
     displayName: 'Run `cargo xtest` for "runner-test" kernel'

example-kernels/Cargo.lock

@@ -4,6 +4,7 @@ members = [
     "default-target-bootimage",
     "default-target-cargo",
     "runner",
+    "runner-doctest",
     "runner-test",
     "testing-qemu-exit-code",
     "testing-serial-result",

example-kernels/Cargo.toml

@@ -0,0 +1,5 @@
+[build]
+target = "../x86_64-bootimage-example-kernels.json"
+
+[target.'cfg(target_os = "none")']
+runner = "bootimage runner"

example-kernels/runner-doctest/.cargo/config

@@ -0,0 +1,2 @@
+/target/
+**/*.rs.bk

example-kernels/runner-doctest/.gitignore

@@ -0,0 +1,13 @@
+[package]
+name = "runner-doctest"
+version = "0.1.0"
+authors = ["Philipp Oppermann <[email protected]>"]
+edition = "2018"
+
+[dependencies]
+bootloader = "0.6.4"
+x86_64 = "0.5.3"
+
+[package.metadata.bootimage]
+test-success-exit-code = 33 # (0x10 << 1) | 1
+test-args = ["-device", "isa-debug-exit,iobase=0xf4,iosize=0x04", "-display", "none"]

example-kernels/runner-doctest/Cargo.toml

@@ -0,0 +1,90 @@
+#![no_std]
+#![cfg_attr(test, no_main)]
+#![feature(custom_test_frameworks)]
+#![test_runner(crate::test_runner)]
+#![reexport_test_harness_main = "test_main"]
+
+/// add two numbers
+///
+/// ```
+/// #![no_std]
+/// #![no_main]
+/// use runner_doctest::{add, exit_qemu, ExitCode};
+/// #[export_name = "_start"]
+/// extern "C" fn start() {
+///     assert_eq!(add(1, 2), 3);
+///     unsafe { exit_qemu(ExitCode::Success); }
+/// }
+/// ```
+pub fn add(a: u32, b: u32) -> u32 {
+    a + b
+}
+
+/// multiply two numbers
+///
+/// ```
+/// #![no_std]
+/// #![no_main]
+/// use runner_doctest::{mul, exit_qemu, ExitCode};
+/// #[export_name = "_start"]
+/// extern "C" fn start() {
+///     assert_eq!(mul(2, 3), 6);
+///     unsafe { exit_qemu(ExitCode::Success); }
+/// }
+/// ```
+pub fn mul(a: u32, b: u32) -> u32 {
+    a * b
+}
+
+#[cfg(test)]
+fn test_runner(tests: &[&dyn Fn()]) {
+    for test in tests.iter() {
+        test();
+    }
+
+    unsafe {
+        exit_qemu(ExitCode::Success);
+    }
+}
+
+pub enum ExitCode {
+    Success,
+    Failed,
+}
+
+impl ExitCode {
+    fn code(&self) -> u32 {
+        match self {
+            ExitCode::Success => 0x10,
+            ExitCode::Failed => 0x11,
+        }
+    }
+}
+
+/// exit QEMU (see https://os.phil-opp.com/integration-tests/#shutting-down-qemu)
+pub unsafe fn exit_qemu(exit_code: ExitCode) {
+    use x86_64::instructions::port::Port;
+
+    let mut port = Port::<u32>::new(0xf4);
+    port.write(exit_code.code());
+}
+
+#[cfg(test)]
+#[no_mangle]
+pub extern "C" fn _start() -> ! {
+    test_main();
+
+    unsafe {
+        exit_qemu(ExitCode::Failed);
+    }
+
+    loop {}
+}
+
+#[panic_handler]
+fn panic(_info: &core::panic::PanicInfo) -> ! {
+    unsafe {
+        exit_qemu(ExitCode::Failed);
+    }
+    loop {}
+}

example-kernels/runner-doctest/src/lib.rs

@@ -9,7 +9,13 @@ pub(crate) fn runner(args: RunnerArgs) -> Result<i32, ErrorMessage> {
         .executable
         .parent()
         .ok_or("kernel executable has no parent")?;
-    let is_test = exe_parent.ends_with("deps");
+    let is_doctest = exe_parent
+        .file_name()
+        .ok_or("kernel executable's parent has no file name")?
+        .to_str()
+        .ok_or("kernel executable's parent file name is not valid UTF-8")?
+        .starts_with("rustdoctest");
+    let is_test = is_doctest || exe_parent.ends_with("deps");
 
     let bootimage_bin = {
         let file_stem = args