rust-lang / rust-lang/cargo

docs about cargo-provided environment variables could be clearer that they're compile-time only

Open
#8,593 6 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

A-documenting-cargo-itself C-bug S-needs-design
Dominant language
Rust
Stars
15.5k
Forks
3k
Avg merge
23h 30m
Merged PRs (30d)
51

Description

This section of the docs:
https://doc.rust-lang.org/cargo/reference/environment-variables.html#environment-variables-cargo-sets-for-crates
(https://github.com/ehuss/cargo/blob/master/src/doc/src/reference/environment-variables.md#environment-variables-cargo-sets-for-crates)

says:

Cargo exposes these environment variables to your crate when it is compiled. Note that this applies for running binaries with cargo run and cargo test as well.

I think what this means to say is something like: "Cargo exposes these environment variables to your crate when any of its targets is compiled, including when compiling binaries that you might later run with cargo run and cargo test. [These environment variables are not provided at runtime.]"

It's easy to misread what's there as: "Cargo exposes these environment variables to your crate when it is compiled, and when running binaries with cargo run and cargo test as well."

The difference is whether the variables are available at runtime, which as far as I can tell they aren't.

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start in src/doc/src/reference/environment-variables.md at the “Environment variables Cargo sets for crates” section, and compare it with the published documentation. Clarify that the variables are available while targets are compiled, including for cargo run and cargo test, rather than at runtime. Done when the wording cannot be read as promising runtime environment variables.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
Under an hour
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.