Document CARGO_ALIAS_<name> #16521
Document CARGO_ALIAS_<name> #16521
Conversation
rustbot
added
A-documenting-cargo-itself
|
r? @weihanglo rustbot has assigned @weihanglo. Use |
| recursive_example = "rr --example recursions" | ||
| ``` | ||
|
|
||
| Aliases can also be defined via environment variables. Each such environment variable is named `CARGO_ALIAS_<name>`, i.e. `CARGO_ALIAS_`, followed by the alias name in uppercase. For example, setting CARGO_ALIAS_BR="build --release" allows running `cargo br` as an alias for running `cargo build --release` without making any changes to a Cargo `config.toml` file. |
There was a problem hiding this comment.
There wasn't any discussion about CARGO_ALIAS_, apart from mentioning it being listed as an environment variable associated with cargo aliases.
This is the case for most environment variables, including ones with substitution like this.
The environment variables we do talk about are either
- to clarify handling of
bool(1and0) - very particular cases of precedence
Is there something specific to CARGO_ALIAS_* that we are needing to cover or are you feeling our approach to environment variables is lacking and could you describe why?
FYI this might be better discussed in an issue. Multiple PRs may be created for the same issue which can split discussion and if we need to find past design discussions, we tend to look among Issues, not Prs.
There was a problem hiding this comment.
The other environment variables have their full names as part of their definition.
This has a placeholder, <name>, for an embedded binding of a definition for an alias, and I didn't see any documentation of how <name> works, e.g. whether I should be defining CARGO_ALIAS_br or CARGO_ALIAS_BR.
That is why I put up the PR.
There was a problem hiding this comment.
After reviewing the broader docs, I do see other occurrences of the use of <name> to describe a placeholder, but whether or not it is going to some kind of case-tranformation (e.g. mapping to lower-case, as is done for CARGO_ALIAS_<name>) is almost never indicated. (One rare exception is the discussion of CARGO_REGISTRIES_<name>_TOKEN.)
Many of the other occurrences of <name> are places where there is a general template being described, e.g. [profile.<name>], [registries.<name>.index], etc, and <name> occurs multiple times in those contexts. CARGO_ALIAS_<name> is an exception to that pattern, which probably why I thought it deserved some discussion.
Some of those cases are places where <name> is used in a context where a lower-case form is expected, and then there are sometimes subcontexts where a environment variable like CARGO_PROFILE_<name>_CODEGEN_UNITS or CARGO_PROFILE_<name>_DEBUG is then introduced.
My current assumption is that the reader is expected to do a case-mapping in all such occurrences; e.g. mapping to lower-case for the occurrences in a toml file, and mapping to upper-case for occurrences when embedded in the name of an environment variable.
I'll open a general issue. Given that there are 53 occurrences of the string <name> in the reference.html, I have sympathy for the idea that we probably prefer not to address this in an ad hoc manner. But on the other hand, it might be easiest to just blanket the appropriate places with the addendum "where is the name in all capital letters", analogous to what was done in the discussion of CARGO_REGISTRIES_<name>_TOKEN.
There was a problem hiding this comment.
I would lean towards closing in favor of #16532, particularly if knowing how to convert <name> was what led to this.
4 participants
What does this PR try to resolve?
There wasn't any discussion about CARGO_ALIAS_, apart from mentioning it being listed as an environment variable associated with cargo aliases.
How to test and review this PR?
I guess you should confirm that the described behavior matches your mental model and the actual behavior, the same way that I did.