Warn when relying on default musl target static linkage behaviour

[Gelbpunkt]

This introduces a new lint, "musl_missing_crt_static" that warns when compiling code for a musl target that defaults to static linkage without explicitly specifying -Ctarget-feature=+crt-static.

The targets will be changed to link dynamically by default in the future, after which this lint can be removed again.

See the accepted MCP rust-lang/compiler-team#422 which proposed this lint.

TODO: Decide on a deadline and write a blog post about this?

Example in action (on a powerpc64le-unknown-linux-musl host):

$ rustc test.rs
warning: on musl targets, the implicit default for `crt-static` is going to change
  |
  = help: explicitly pass `-C target-feature=+crt-static` or `-C target-feature=-crt-static`
  = note: `#[warn(musl_missing_crt_static)]` on by default

warning: 1 warning emitted
$ rustc test.rs -Ctarget-feature=-crt-static
$ rustc test.rs -Ctarget-feature=+crt-static
# notice that no warning is emitted

The lint will not be emitted on targets that already default to dynamic linkage, like e.g. the loongarch64 targets.

[rustbot]

r? @lcnr

rustbot has assigned @lcnr.
They will have a look at your PR within the next two weeks and either review your PR or reassign to another reviewer.

Use r? to explicitly pick a reviewer

[rust-log-analyzer]

The job aarch64-gnu-llvm-19-2 failed! Check out the build log: (web) (plain enhanced) (plain)

Click to see the possible cause of the failure (guessed by this bot)

[TIMING] core::build_steps::test::BookTest { compiler: Compiler { stage: 2, host: aarch64-unknown-linux-gnu, forced_compiler: false }, path: "src/doc/rustc", name: "rustc", is_ext_doc: false, dependencies: [] } -- 3.645
[TIMING] core::build_steps::test::RustcBook { compiler: Compiler { stage: 2, host: aarch64-unknown-linux-gnu, forced_compiler: false } } -- 0.000
Generating lint docs (aarch64-unknown-linux-gnu)
##[group]Running stage2 lint-docs (aarch64-unknown-linux-gnu)
error: failed to test example in lint docs for `musl_missing_crt_static` in /checkout/compiler/rustc_lint_defs/src/builtin.rs:5104: lint docs should contain the line `### Example`

This error was generated by the lint-docs tool.
This tool extracts documentation for lints from the source code and places
them in the rustc book. See the declare_lint! documentation
https://doc.rust-lang.org/nightly/nightly-rustc/rustc_lint_defs/macro.declare_lint.html
for an example of the format of documentation this tool expects.

To re-run these tests, run: ./x.py test --keep-stage=0 src/tools/lint-docs
The --keep-stage flag should be used if you have already built the compiler
and are only modifying the doc comments to avoid rebuilding the compiler.

Command has failed. Rerun with -v to see more details.
Build completed unsuccessfully in 0:41:26
  local time: Sat Jul 26 23:43:24 UTC 2025
  network time: Sat, 26 Jul 2025 23:43:24 GMT
##[error]Process completed with exit code 1.
Post job cleanup.

[Noratrieb]

This lint will be seen by a lot of people, many of which may not be familiar with the details of compiler flags. I think this lint documents here should spend more effort explaining exactly how to pass the flag (via RUSTFLAGS) and what exactly it means (what is libc, what are the differences between static and dynamic linkage, why is this change being made exactly etc) in an accessible way. I can write down such a text if you want to, or you can do it yourself.

The lint output should then contain a link to this documentation here in the rustc book.

[Noratrieb]

Because I think there are a lot of projects that have just copied the --target from somewhere because they heard that this makes a binary that works everywhere, without being familiar with the details of Rust compilation.

[Noratrieb]

Alternatively all these details can be in the blog post and we link to the blog post.

[Gelbpunkt]

I don't really mind where the details are, I think both ways are fine. However, before I write such a blog post, I'd like to know for how long we want to keep the lint around before we change the behavior, since I'd have to mention that in the blog post and it needs to be decided on either way, so better start that process now than later

[lcnr]

r? @Noratrieb maybe, but feel free to reassign

[rustbot]

Noratrieb is not on the review rotation at the moment.
They may take a while to respond.

[usamoi]

I have a small concern. Because of rust-lang/cargo#4423, when the host is musl and cross-compilation is used, -Ctarget-feature=-crt-static or -Amusl_missing_crt_static cannot be passed to proc-macros and build scripts, making it impossible (without nightly cargo) to suppress this warning.

[Gelbpunkt]

I have a small concern. Because of rust-lang/cargo#4423, when the host is musl and cross-compilation is used, -Ctarget-feature=-crt-static or -Amusl_missing_crt_static cannot be passed to proc-macros and build scripts, making it impossible (without nightly cargo) to suppress this warning.

The lint does not apply to proc macros, not sure about build scripts, I'll have to try it and see.