Problem

According to The Cargo Book, the build.rs file can emit the cargo:rustc-link-arg-tests=FLAG setting to have it applied passed to rustc as a -C link-arg=FLAG but only when building a "tests target". From the documentation it's not immediately clear that this only works with integration-style tests in tests/. Furthermore, there's no indication of how special link args might be specified for unit tests (this is particularly relevant for running tests for PyO3 extension modules on MacOS).

Also, if there are no tests tests/, the cargo test comands fails with the message:

error: invalid instruction `cargo:rustc-link-arg-tests` from build script of ...
The package xyz ... does not have a test target

Steps

1. Create a project with the following files:

Cargo.toml:

[package]
name = "build-script-link-args-for-tests"
version = "0.1.0"
edition = "2021"
[dependencies]

build.rs:

fn main() {
    println!("cargo:rustc-link-arg-tests=-Wl,-rpath,/usr/local/lib") // Arbitrary flag.
}

src/lib.rs:

pub struct Foo;

#[cfg(test)]
mod tests {
    #[test]
    fn can_haz_foo() {
        let _ = crate::Foo;
    }
}

2. Run tests

cargo test

(observe cargo "invalid instruction" error)

3. Add an integration test

tests/test_foo.rs:

use build_script_link_args_for_tests::Foo;

#[test]
fn i_haz_foo() {
    let _ = Foo;
}

4. Run tests

cargo test

(observe no cargo error)

5. Observe application of linker arguments

RUSTFLAGS='--print link-args' cargo test | grep '\-Wl,\-rpath,/usr/local/lib'

(observe linker arg only applied to .../build-script-link-args-for-tests/target/debug/deps/test_foo-...)

Possible Solution(s)

a. Allow cargo:rustc-link-arg-tests to apply to unit (in-module) tests, or create a new flag specific to unit tests. 😄
b. Update documentation to indicate unit tests aren't supported by this feature. 😞

Notes

May also apply to #[bench] functions.

Version

cargo 1.62.1 (a748cf5a3 2022-06-08)
release: 1.62.1
commit-hash: a748cf5a3e666bc2dcdf54f37adef8ef22196452
commit-date: 2022-06-08
host: aarch64-apple-darwin
libgit2: 1.4.2 (sys:0.14.2 vendored)
libcurl: 7.79.1 (sys:0.4.51+curl-7.80.0 system ssl:(SecureTransport) LibreSSL/3.3.6)
os: Mac OS 12.4.0 [64-bit]