Better documentation about which libraries are linked by default by the rust compiler

[weiznich]

Location

Release notes, possibly the reference, not sure where else

Summary

There is currently no documentation about which system libraries are linked by rustc via the standard library and which of these libraries are guaranteed to be linked in the future. This was noticed while reporting #139352 and should likely be fixed before that change is stable.

Ideally there would be a list/table of linked libraries per target for at least tier 1 targets that contains all linked system libraries and also clarify which of these libraries are guaranteed to be linked in the future. (If none are guaranteed to be linked that's also fine, if that's stated explicitly). In addition it would be great to include documentation on how to test if your code relies on such not-guaranteed linkage. For windows that seems to be the command described by @ChrisDenton here. I'm not sure if similar commands exist for other platforms?

[ChrisDenton]

--print native-static-libs can be used to list the current libraries that will be linked. E.g.:

rustc empty.rs --print native-static-libs --crate-type staticlib

Currently on Windows it is: kernel32.lib, ntdll.lib, userenv.lib, ws2_32.lib and dbghelp.lib.

---

When compiling C/C++ libraries perhaps the easier thing to do would be to test them in a minimal C/C++ program. If it can't link without specifying extra libraries than it may break in Rust too.

[weiznich]

@ChrisDenton That still doesn't really answer the question which of these libraries are guaranteed to be linked and which are considered to be an implementation detail. It would be very meaningful to clarify that, even if the answer is that none of them are guaranteed to be linked. Ideally this output would then state that these are not guaranteed to be the same over different rust versions.

[ChrisDenton]

Unless otherwise documented, we do not make any guarantees about which C functions are available to C/C++ libraries without explicitly linking the required import lib.

We do document that some std functions use certain platform APIs but we also document that this is subject to change: https://doc.rust-lang.org/stable/std/io/index.html#platform-specific-behavior

We do not currently say anything about functions like RegOpenKey that aren't likely to ever be used by std. But, yes, using them in a C static library may mean needing to manually link the relevant import library if the C library does not declare its own dependencies.

[weiznich]

@ChrisDenton Again: Would it be possible to explicitly call out that none of these libraries are guaranteed to be linked in future rust version in the documentation and also in the output of --print native-static-libs then? This would at least make clear that this is something you cannot rely on. The current documentation is unclear on this topic.

And to be clear here: Removing that dependency is still a build breaking change (not necessarily semver major) from the rust project.