### What does this PR try to resolve?
This PR addresses a typo in the "Shared cache" section. The word
"environmental" has been corrected to "environment" for proper grammar
in the phrase:
- "set `RUSTC_WRAPPER` environmental variable to `sccache`" → "set
`RUSTC_WRAPPER` environment variable to `sccache`".
### How should we test and review this PR?
Review the change in the relevant documentation section and verify that
the typo has been corrected. No functional changes are involved.
### Additional information
This is a simple grammar fix to ensure clarity in the documentation.
This fixes various issues with the future-incompat report. In
particular, it addresses the off-by-one for the `--id` flag when the
report is already cached, and it doesn't recommend updating dependencies
when the error comes from a local crate. See each commit for more
details.
Fixes#15337
This fixes a problem introduced by
https://github.com/rust-lang/cargo/pull/11648 where the future-incompat
report will tell you to run with an `--id` flag with the wrong value
if the report is already cached.
The solution is to add a method to determine which ID to use for the
suggestions *before* attempting to save the report.
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.
You can use `Fixes #<issue number>` to associate this PR to an existing
issue.
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
### What does this PR try to resolve?
Related to https://github.com/rust-lang/cargo/issues/14520
This PR introduces auto-completion for the `cargo <TAB>` option. When a
user types `cargo <TAB>` and presses the TAB key, the system will
automatically suggest aliases defined in `config.toml`
### How should we test and review this PR?
To verify this feature, follow these steps:
1. In the terminal, type `cargo <TAB>`
2. Press the TAB key.
3. You should see aliases suggestions
https://github.com/user-attachments/assets/d8a265e8-bbd9-4f58-8121-80caf142d8a6
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.
You can use `Fixes #<issue number>` to associate this PR to an existing
issue.
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
### What does this PR try to resolve?
Small PR to rename `workspace-manifest-path-hash` to
`workspace-path-hash` in the build-dir template as mentioned
[here](https://github.com/rust-lang/cargo/issues/14125#issuecomment-2733611870)
(cc: #14125)
r? @epage
### What does this PR try to resolve?
Related to https://github.com/rust-lang/cargo/issues/14520
This PR introduces auto-completion for following options:
1. `--color` option with values: auto, always, never
2. `--vcs` option with values: git, hg, pijul, fossil, none
3. `--message-format` option with values: human, short, json,
json-diagnostic-short, json-diagnostic-rendered
Take `--color` as an example, when a user types ` cargo build --color
<TAB>`the system will automatically suggest auto, always, never
### How should we test and review this PR?
To verify this feature, follow these steps:
1. In the terminal, type `cargo build --color <TAB>` or `cargo new
my_project --vcs <TAB>` or `cargo check --message-format <TAB>`
2. Press the TAB key.
3. You should see option suggestions
https://github.com/user-attachments/assets/0cf12785-fdc0-4fb1-84b5-715c29a95e0e
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.
You can use `Fixes #<issue number>` to associate this PR to an existing
issue.
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
Current short description does not match reality nor the longer
description:
> Setting the relative flag evaluates the value as a config-relative
path that is relative to the parent directory of the .cargo directory
that contains the config.toml file. The value of the environment
variable will be the full absolute path.
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.
You can use `Fixes #<issue number>` to associate this PR to an existing
issue.
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
fix some typos
This does a little bit of cleanup around rustc-link-arg-cdylib build
script instruction:
* Reorders the documentation so that it is consistent.
* Updates the documentation to mention both the new
(`rustc-link-arg-cdylib`) and old (`rustc-cdylib-link-arg`) forms are
documented, with the new form as the primary form.
* Adds a test for the old form, since we didn't have any.
Somehow I missed all this in
https://github.com/rust-lang/cargo/pull/8441 and
https://github.com/rust-lang/cargo/pull/9557.
### What does this PR try to resolve?
This PR is a follow up on #15104 and and adds support for the path
templating in `build.build-dir` as defined in #14125.
Supported templates:
* `{workspace-root}`
* `{cargo-cache}` (pointing to `CARGO_HOME` for now)
* `{workspace-manifest-path-hash}`
#### Unresolved questions
What should we name `{workspace-manifest-path-hash}` and what should it
include? Should we shorten to `{workspace-hash}` or even just `{hash}`?
Should we include the Cargo version so we get unique whole-target
directories for easier cleanup (#13136)
How should this handle unknown variables (error) or unclosed `{` / `}`
(ignored), see
https://github.com/rust-lang/cargo/pull/15236#discussion_r1977898973
When using `{workspace-manifest-path-hash}` this hash will change based
on the project path. In the event of a cargo being executed in a
symlinked project, the hash will change.
For example, given the following directory
```
/Users/
└─ user1/
└─ projects/
├─ actual-crate/
│ └─ Cargo.toml
└─ symlink-to-crate/ -> actual-crate/
```
the hash will be unique when running cargo from each of the following
directories.
* `/Users/user1/actual-crate`
* `/Users/user1/symlink-to-crate`
Figuring out whether to handle this is deferred out, see
- https://github.com/rust-lang/cargo/pull/15236#discussion_r1971938021
-
https://github.com/poliorcetics/rfcs/blob/cargo-target-directories/text/3371-cargo-target-dir-templates.md#symbolic-links
-
https://github.com/rust-lang/cargo/issues/12207#issuecomment-2711402159
### How should we test and review this PR?
This PR is fairly small. I included tests for each template variable.
You can also clone my branch and test it locally with
```console
CARGO_BUILD_BUILD_DIR='{workspace-root}/foo' cargo -Z build-dir build
```
### Additional information
While searching Cargo for any prior art for path templating, I found
[`sources/registry/download.rs`](https://github.com/rust-lang/cargo/blob/master/src/cargo/sources/registry/download.rs#L84)
doing a simple string replace. Thus I followed the same behavior.
r? @epage
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them. -->
### What does this PR try to resolve?
The current wording makes it sound like Cargo will only refuse to
compile the package if it encounters any missing functionality in stdlib
while compiling the package on an unsupported toolchain. However, cargo
will actually refuse to build the package unless overridden or the
toolchain is updated.
### How should we test and review this PR?
No tests are required or applicable for this PR unless I am mistaken
### Additional information
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
Explain the motivation behind this change.
A clear overview along with an in-depth explanation are helpful.
You can use `Fixes #<issue number>` to associate this PR to an existing
issue.
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
### What does this PR try to resolve?
Related to https://github.com/rust-lang/cargo/issues/14520
This PR introduces auto-completion for the `cargo +<TAB>` option. When a
user types `cargo +<TAB>` and presses the TAB key, the system will
automatically suggest toolchain in current device
### How should we test and review this PR?
To verify this feature, follow these steps:
1. In the terminal, type `cargo +<TAB>`
2. Press the TAB key.
3. You should see toolchain suggestions
https://github.com/user-attachments/assets/c8bd8a5e-e97d-4d0a-b284-1ed52734c4a2
<!--
Thanks for submitting a pull request 🎉! Here are some tips for you:
* If this is your first contribution, read "Cargo Contribution Guide"
first:
https://doc.crates.io/contrib/
* Run `cargo fmt --all` to format your code changes.
* Small commits and pull requests are always preferable and easy to
review.
* If your idea is large and needs feedback from the community, read how:
https://doc.crates.io/contrib/process/#working-on-large-features
* Cargo takes care of compatibility. Read our design principles:
https://doc.crates.io/contrib/design.html
* When changing help text of cargo commands, follow the steps to
generate docs:
https://github.com/rust-lang/cargo/tree/master/src/doc#building-the-man-pages
* If your PR is not finished, set it as "draft" PR or add "WIP" in its
title.
* It's ok to use the CI resources to test your PR, but please don't
abuse them.
### What does this PR try to resolve?
### How should we test and review this PR?
Demonstrate how you test this change and guide reviewers through your
PR.
With a smooth review process, a pull request usually gets reviewed
quicker.
If you don't know how to write and run your tests, please read the
guide:
https://doc.crates.io/contrib/tests
### Additional information
Other information you want to mention in this PR, such as prior arts,
future extensions, an unresolved problem, or a TODO list.
-->
fix some typos
This commit adds logic to check for unexpected variables in templated
paths like `build.build-dir`. Cargo will error if it finds a variable
that it does not know how to expand.
I was seeing an error like the following in my `rust-analyzer` output.
```
error: failed to load source for dependency `fontdue`
Caused by:
Unable to update https://github.com/xiphseer/fontdue.git?rev=67b963af0d5ca9e09bfeb0b5a9adf85c302d0a67
Caused by:
failed to fetch into: /home/daniel/.local/share/cargo/git/db/fontdue-4d0b06b88bb2e092
Caused by:
revision 67b963af0d5ca9e09bfeb0b5a9adf85c302d0a67 not found
Caused by:
failed to authenticate when downloading repository
* attempted to find username/password via git's `credential.helper` support, but failed
if the git CLI succeeds then `net.git-fetch-with-cli` may help here
https://doc.rust-lang.org/cargo/reference/config.html#netgit-fetch-with-cli
Caused by:
failed to acquire username/password from local configuration
```
I spent about 10 minutes reading the docs on *git authentication*,
before realizing I had just typo'ed my own GitHub username. This PR adds
a note to the reference that explicitly mentions wrong (not malformed)
URLs as a cause of authentication errors.
It's not directly on the linked
<https://doc.rust-lang.org/cargo/reference/config.html#netgit-fetch-with-cli>
mainly because *Git Authentication* is already linked there, so it may
catch more people and that's meant as the more detailed explanation
anyway.
### What does this PR try to resolve?
Fixes#15059Fixes#15159
This provides an escape hatch `--exclude-lockfile`for uncommon workflows
that don't verify (`--no-verify` is passed) the build with their
unpublished packages
In effect, this takes the heuristic removed in #14815 and replaces it
with a flag
When `--exclude-lockfile` is enabled,
`cargo package` will not verify the lock file if present,
nor will it generate a new one if absent.
Cargo.lock will not be included in the resulting tarball.
Together with `--no-verify`,
this flag decouples packaging from checking the registry index.
While this is useful for some non-normal workflows that requires
to assemble packages having unpublished dependencies.
It is recommended to use `-Zpackage-workspace` to package the entire
workspace, instead of opting out lockfile.
### How should we test and review this PR?
The first commit was stolen from
<1a104b5444>
(credit to @NoisyCoil!)
The second added two failing cases we observed in #15059.
### Additional information
This expands the text introduced by #12323.
`x.y.*` is equivalent to `>=x.y.0, <x.(y+1).0`, so it can create an
unresolvable conflict in the same way as already discussed.
I also added a little punctuation to improve the structure of some
nearby sentences.
@rustbot label A-documenting-cargo-itself
