Confusing suggestion to use `cargo:rustc-link-lib` in a cargo project with a lib and bins

[kusnezoff-alexander]

Problem

-- I created this repo to showcase/reproduce the error: https://github.com/kusnezoff-alexander/cargo-build-linking-bug --

The success of linking C-libraries during cargo build seems to depend on the existence of lib.rs even if only the binary is built.
Building packages which offer both a library and binary could suffer from this potential bug. This bug has been only been reproduced so far for linking against a library via

println!("cargo:rustc-link-search=../libs");
println!("cargo:rustc-link-lib=static=mylib");

inside build.rs.

Exptected behavior: The existence of a file called lib.rs should have no effect on the linking during cargo build:

Observed behavior:

1. Without the existence of lib.rs: Linking to custom C-library does work (see ./linking-without-lib-works for working example)
2. Withthe existence of lib.rs: Linking to custom C-library does not work (see ./linking-with-lib-doesnt for working example)

Steps

1. git clone https://github.com/kusnezoff-alexander/cargo-build-linking-bug
2. cd libs && make all
3. cd linking-does-work && cargo build - should exit successfully
4. cd linking-doesnt-work && cargo build - should throw an error that extern function-symbol isn't defined (although the only difference to the previous case is the existence of lib.rs)

Possible Solution(s)

No response

Notes

• interestlingly though, it does work if export RUSTFLAGS="-L <absolute-path-to-this-dir>/libs/ -l mylib" is set

Version

cargo 1.80.1 (376290515 2024-07-16)
release: 1.80.1
commit-hash: 37629051518c3df9ac2c1744589362a02ecafa99
commit-date: 2024-07-16
host: x86_64-unknown-linux-gnu
libgit2: 1.7.2 (sys:0.18.3 vendored)
libcurl: 8.6.0-DEV (sys:0.4.72+curl-8.6.0 vendored ssl:OpenSSL/1.1.1w)
ssl: OpenSSL 1.1.1w  11 Sep 2023
os: Fedora 40.0.0 [64-bit]

[ehuss]

Can you please share the exact output you are receiving in the case where it doesn't seem to work? I am unable to reproduce given your example.

[ehuss]

Oh, correction, I am able to reproduce:

  = note: /usr/bin/ld: /tmp/cargo-build-linking-bug/linking-with-lib-doesnt/target/debug/deps/buildrs_linking_bug-87372c54d74efe55.6x51e5ear2x9hplszhwkzwe3l.rcgu.o: in function `buildrs_linking_bug::main':
          /tmp/cargo-build-linking-bug/linking-with-lib-doesnt/src/main.rs:6: undefined reference to `my_custom_fn'
          collect2: error: ld returned 1 exit status

  = note: some `extern` functions couldn't be found; some native libraries may need to be installed or have their path specified
  = note: use the `-l` flag to specify native libraries to link
  = note: use the `cargo:rustc-link-lib` directive to specify the native libraries to link with Cargo (see https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-link-lib)

warning: `buildrs-linking-bug` (bin "buildrs-linking-bug") generated 1 warning
error: could not compile `buildrs-linking-bug` (bin "buildrs-linking-bug") due to 1 previous error; 1 warning emitted

This behavior is documented here: https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-link-lib

Does the explanation there help understand why it works that way?

[kusnezoff-alexander]

Ah yes I see, it's all documented there. Thank you.

Still I find the error message to be misleading, since it tells to specify the library via cargo:rustc-link-lib which is already done. I think it would be a good thing to display another error-message in the case of both a library- and binary-target existing for the package. Something like:

 = note: /usr/bin/ld: /tmp/cargo-build-linking-bug/linking-with-lib-doesnt/target/debug/deps/buildrs_linking_bug-87372c54d74efe55.6x51e5ear2x9hplszhwkzwe3l.rcgu.o: in function `buildrs_linking_bug::main':
          /tmp/cargo-build-linking-bug/linking-with-lib-doesnt/src/main.rs:6: undefined reference to `my_custom_fn'
          collect2: error: ld returned 1 exit status

  = note: Your package has both a binary and library target. Since  the library has access to the symbols from the given lib, the binary should access them through the library target’s public API. (see https://doc.rust-lang.org/cargo/reference/build-scripts.html#rustc-link-lib)

[ehuss]

Unfortunately I don't know of a feasible way to do that right now. rustc doesn't know anything about cargo, and it is the one generating the message. Cargo doesn't know anything about linking, and wouldn't be able to know what is happening.

Transferred to rust-lang/rust since this message is generated by rustc. I don't know if the wording could possibly be tweaked to avoid this confusion.