Description
This is reopening #681, which was closed by the reporter without a response from the Rust team. In #681, the reporter was able to work around it by forcing static linking, but I don't think that should be a requirement for writing examples in documentation.
When building a crate with native dependencies (such as libusb), the doc tests fail to link because the flags from the build script are not included in the linker command. I distilled it down to a minimal example, which is hosted here: https://github.com/dcuddeback/rust-link-bug
The doc example can be anything. It doesn't have to be related to the native library:
/// Returns the string "hello".
///
/// ```
/// bug::hello(); // returns "hello"
/// ```
pub fn hello() -> &'static str {
"hello"
}It seems the only requirement for triggering this bug is to have a links property in Cargo.toml for a library that requires additional linker flags. For this example, I'm linking to libusb-1.0:
[package]
name = "bug"
version = "0.0.1"
authors = ["David Cuddeback <[email protected]>"]
build = "build.rs"
links = "usb-1.0"I wrote a simple build script to provide the correct flags on my system. This is also the output from using pkg-config-rs on my system, but I wanted to minimize the moving parts in my example.
fn main() {
println!("cargo:rustc-flags=-L native=/usr/local/Cellar/libusb/1.0.19/lib");
println!("cargo:rustc-flags=-l usb-1.0");
}
Compiling with cargo build works fine. Running cargo test produces this link error:
failures:
---- hello_0 stdout ----
error: linking with `cc` failed: exit code: 1
note: "cc" "-m64" "-L" "/usr/local/lib/rustlib/x86_64-apple-darwin/lib" "-o" "/var/folders/7f/z9y9c0gj52gb38jlrsr2pzkc0000gn/T/rustdoctest.uFWruUs3fErH/rust-out" "/var/folders/7f/z9y9c0gj52gb38jlrsr2pzkc0000gn/T/rustdoctest.uFWruUs3fErH/rust_out.o" "-Wl,-force_load,/usr/local/lib/rustlib/x86_64-apple-darwin/lib/libmorestack.a" "-Wl,-dead_strip" "-nodefaultlibs" "/Users/david/src/bug/target/libbug-a0a1f90974336c26.rlib" "-L" "/usr/local/lib/rustlib/x86_64-apple-darwin/lib" "-lstd-4e7c5e5c" "-L" "/Users/david/src/bug/target" "-L" "/Users/david/src/bug/target/deps" "-L" "/usr/local/lib/rustlib/x86_64-apple-darwin/lib" "-L" "/Users/david/src/bug/.rust/lib/x86_64-apple-darwin" "-L" "/Users/david/src/bug/lib/x86_64-apple-darwin" "-lusb-1.0" "-lSystem" "-lpthread" "-lc" "-lm" "-lcompiler-rt"
note: ld: warning: directory not found for option '-L/Users/david/src/bug/.rust/lib/x86_64-apple-darwin'
ld: warning: directory not found for option '-L/Users/david/src/bug/lib/x86_64-apple-darwin'
ld: library not found for -lusb-1.0
clang: error: linker command failed with exit code 1 (use -v to see invocation)
error: aborting due to previous error
thread 'hello_0' panicked at 'Box<Any>', /Users/rustbuild/src/rust-buildbot/slave/nightly-dist-rustc-mac/build/src/libsyntax/diagnostic.rs:151
The directory /usr/local/Cellar/libusb/1.0.19/lib is missing from the linker flags.