rust - 如何对使用 crate 中特征的函数进行文档测试？

Question

我尝试为使用 sysinfo 箱子的函数编写一个 doctest。虽然代码工作得很好，但我无法编译 doctest。一个最小的示例如下所示:

库.rs

extern crate sysinfo;

use sysinfo::SystemExt;

/// Test
///
/// ```
/// sysinfo_error::read_sysinfo()
/// ```
pub fn read_sysinfo() {
    let mut system = sysinfo::System::new();
}

运行时，此代码按预期工作(编译但不执行任何操作)，但是当我运行 cargo test 时，出现以下错误:

running 1 test
test src/lib.rs - read_sysinfo (line 7) ... FAILED

failures:

---- src/lib.rs - read_sysinfo (line 7) stdout ----
        error: linking with `cc` failed: exit code: 1
  |
  = note: "cc" "-Wl,--as-needed" "-Wl,-z,noexecstack" "-m64" "-L" "/home/me/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib" "/tmp/rustdoctest.mkPht54FLMyA/rust_out.rust_out0.rcgu.o" "-o" "/tmp/rustdoctest.mkPht54FLMyA/rust_out" "/tmp/rustdoctest.mkPht54FLMyA/rust_out.crate.allocator.rcgu.o" "-Wl,--gc-sections" "-pie" "-Wl,-z,relro,-z,now" "-nodefaultlibs" "-L" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps" "-L" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps" "-L" "/home/me/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-Wl,-Bstatic" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps/libsysinfo_error-ad346d9cb3d265cb.rlib" "-L" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps" "-Wl,-Bdynamic" "-l" "sysinfo-bde19d7fa61f93a0" "-Wl,-Bstatic" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps/libcfg_if-34509d450d3a6e7b.rlib" "/home/me/repos/rust_book/sysinfo_error/target/debug/deps/liblibc-b1ca85687f9f2272.rlib" "-L" "/home/me/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib" "-Wl,-Bdynamic" "-l" "std-58a9e2944951d97f" "-Wl,-Bstatic" "/home/me/.rustup/toolchains/stable-x86_64-unknown-linux-gnu/lib/rustlib/x86_64-unknown-linux-gnu/lib/libcompiler_builtins-a6b6fad6cc543169.rlib" "-Wl,-Bdynamic" "-l" "util" "-l" "util" "-l" "dl" "-l" "rt" "-l" "pthread" "-l" "pthread" "-l" "gcc_s" "-l" "c" "-l" "m" "-l" "rt" "-l" "pthread" "-l" "util" "-l" "util"
  = note: /home/me/repos/rust_book/sysinfo_error/target/debug/deps/libsysinfo_error-ad346d9cb3d265cb.rlib(sysinfo_error-ad346d9cb3d265cb.sysinfo_error15.rcgu.o): In function `sysinfo_error::read_sysinfo':
          /home/me/repos/rust_book/sysinfo_error/src/lib.rs:11: undefined reference to `_$LT$sysinfo..linux..system..System$u20$as$u20$sysinfo..traits..SystemExt$GT$::new::h2ef0fda9b3bb905d'
          collect2: error: ld returned 1 exit status


error: aborting due to previous error

thread 'rustc' panicked at 'Box<Any>', /checkout/src/librustc_errors/lib.rs:504:8
note: Run with `RUST_BACKTRACE=1` for a backtrace.
thread 'rustc' panicked at 'couldn't compile the test', /checkout/src/librustdoc/test.rs:288:12


failures:
    src/lib.rs - read_sysinfo (line 7)

test result: FAILED. 0 passed; 1 failed; 0 ignored; 0 measured; 0 filtered out

error: test failed, to rerun pass '--doc'

特征 SystemExt 缺失。我尝试按如下方式在 doctest 中导入箱子

/// Test
///
/// ```
/// extern crate sysinfo;
/// use sysinfo::SystemExt;
/// assert_eq!(16317367, sysinfo_error::read_sysinfo());
/// ```
pub fn read_sysinfo() {
    ...
}

但这并没有解决问题，因为仍然找不到箱子:

---- src/lib.rs - read_sysinfo (line 8) stdout ----
        error[E0432]: unresolved import `sysinfo`
 --> src/lib.rs:4:5
  |
4 | use sysinfo::SystemExt;
  |     ^^^^^^^ Maybe a missing `extern crate sysinfo;`?
[...]

有没有办法在 doctest 期间从 crate 导入特征？

Answer 1

如 this issue 中所述, rustdoc 将所有测试包装在 fn main() {... } 包装器中。您可以通过显式定义一个 main 函数来避免这种情况。为此，将 # 添加到应该位于主测试代码“外部”的行。对于问题中的示例，解决方案如下所示:

/// Test
/// ```
/// # extern crate sysinfo;
/// # extern crate sysinfo_error;  // The name of my crate
/// # fn main() {
///     assert_eq!(16317367, sysinfo_error::read_sysinfo());
/// # }
/// ```
pub fn read_sysinfo() {
    ...
}