Unclear documentation around `CARGO_BUILD_RUSTFLAGS`

[lswith]

Problem

The documentation for the build.rustflags is unclear.

I have a .cargo/config.yml file that I wish to override with an environment variable. It's unclear if CARGO_BUILD_RUSTFLAGS, CARGO_ENCODED_RUSTFLAGS and the RUSTFLAGS environment variable will work for this. For reference, it seems CARGO_BUILD_RUSTFLAGS doesn't work and the RUSTFLAGS variable does.

It's possible I'm misunderstanding how this feature works from the documentation, but I'm hoping that it can be improved for future users.

Steps

No response

Possible Solution(s)

No response

Notes

No response

Version

No response

[weihanglo]

Thanks for the report.

The environment variable CARGO_BUILD_RUSTFLAGS is the counterpart of build.rustflags in .cargo/config.toml. We see it as the config value, just from differen sources. The same config value from different source will either merge or override. Generally, array values are merged together¹:

If a key is specified in multiple config files, the values will get merged together. Numbers, strings, and booleans will … Arrays will be joined together.

At this moment, you could run your command with --verbose to check if rustflags are passed correctly to your rust invocations. You could also use cargo +nightly -Zunstable-options config get to check the rustflag passed, though it is not good at displaying merged environment variables (this is a known issue).

Here is an issue with a similar confusion #12087.

I think this is mostly a good opportunity to enhance the doc around but I don't have a clear idea now.

Hope this helps.
And if possible, I encourage attaching version info in issue reports. It helps track issues a lot. Thanks!

---

@rustbot label -S-triage +A-rustflags +A-documenting-cargo-itself +E-medium +S-needs-design

Footnotes

1. https://doc.rust-lang.org/cargo/reference/config.html#hierarchical-structure ↩

[lswith]

Thanks for that @weihanglo!