docs(ref): Add section on Apple deployment target environment variables

[madsmtm]

These aren't actually read by Cargo (yet), but since rustc doesn't read any other environment variables by itself, this seemed like the most obvious place to document them.

To get into the habit of using it:
@rustbot ping macos
@rustbot label O-macos

[rustbot]

r? @epage

rustbot has assigned @epage.
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

[rustbot]

Error: Only Rust team members can ping teams.

Please file an issue on GitHub at triagebot if there's a problem with this bot, or reach out on #t-infra on Zulip.

[weihanglo]

Thanks for the PR!

I am a bit unsure about it for some reasons:

• This is a reference-like documentation for environment variables Cargo cares about. The new paragraph added is a “best practice” like guide, which seems to be a misplacement here.
• There is no a single paragraph just for a specific platform in this reference. Not sure why prefer putting Apple specific things here. They might change over time so should avoid mentioning any single value.
• People have different ways to set up their workflows. Haven't fully got the idea of emphasizing the [env] section here.

[madsmtm]

Thanks for the PR!

I am a bit unsure about it for some reasons:

* This is a reference-like documentation for environment variables Cargo cares about. The new paragraph added is a “best practice” like guide, which seems to be a misplacement here.

Do you mean that I should write it more tersely, or what do you mean by "best practice"?

* There is no a single paragraph just for a specific platform in this reference. Not sure why prefer putting Apple specific things here. They might change over time so should avoid mentioning any single value.

I'm not really aware of other platforms, but I think that these (along with SDKROOT) is the only environment variables that rustc and clang ever reads? And then I thought it'd make sense to document them in the same place as where other environment variables in the Rust ecosystem (i.e. Cargo's) is documented.

* People have different ways to set up their workflows. Haven't fully got the idea of emphasizing the `[env]` section here.

Emphazising [env] is not really important, mostly wanted to say that it was possible, i.e. that the parsing of the variables happens after [env].

[weihanglo]

By best practice I mean this addition isn't going to be use as a reference book you will check very often. It's more like a how-to guide, which requires a different kind of reading flow. For example, the Cargo Guide shares a more similar reading flow with best practices like docs.

We couuld possibly tweak it into a reference-like doc, but at that point we might probably just refer to Apple's official documentation instead.

the only environment variables that rustc and clang ever reads

Then in my opinion this might be better being in rustc doc or elsewhere. Cargo is not the only tool calling rustc. Cargo also doesn't read those env vars, so prefer not adding them here to avoid any false impression that Cargo handles them for users.

---

I understand discoverability matters. Putting it here seems like a good place to expose to a wider audience. Cargo already have some cookbook like content for some CI best practices. That style of content is a better fit for this I feel like. Rust By Examples might also be a good place for it.

[weihanglo]

Like, we can combine some practices from #13115 and write something somewhere.

[madsmtm]

I've submitted rust-lang/rust#124772 to update the documentation in the platform support docs, let's see where that one goes first.

[weihanglo]

rust-lang/rust#124772 just got merged. Should we close this then?

[madsmtm]

I think I'd still prefer this to be here in some way, maybe just as a quick one or two-liner that links to the platform support docs?

I'd also be fine with writing a fuller guide-level documentation, if you think that'd be useful? Though it might also be a bit too platform-specific to really fit in the Cargo guide?

[weihanglo]

To me, still feel a bit odd to have a paragraph explaining something that Cargo doesn't really read. Even some variables like RUST_BACKTRACE, and RUSTUP_TOOLCHAIN, CLIPPY_CONF_DIR, which could also potentially affect how Cargo works, are left off because they are either an implementation detail, or not really directly read/written/controlled by Cargo. I just don't know how to fit them in.

[madsmtm]

Yeah, that's a great argument actually.

I'll close this, thanks for taking the time to review and discuss it! If Cargo one day decides to read these environment variables, we can document it then.