Skip to content

Document CARGO_ALIAS_<name> #16521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pnkfelix wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Document CARGO_ALIAS_<name> #16521

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions src/doc/src/reference/config.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,9 @@ Aliases are recursive:
rr = "run --release"
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.
Copy link
Contributor

@epage epage Jan 16, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 (1 and 0)
  • 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.

Copy link
Contributor Author

@pnkfelix pnkfelix Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@pnkfelix pnkfelix Jan 20, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

@pnkfelix pnkfelix Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Spawned off into #16532

Copy link
Contributor

@epage epage Jan 20, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would lean towards closing in favor of #16532, particularly if knowing how to convert <name> was what led to this.



### `[build]`

Expand Down