Skip to content
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

docs(cargo-fix): troubleshooting failing fixes #15148

Open
wants to merge 2 commits into
base: master
Choose a base branch
from
Open

docs(cargo-fix): troubleshooting failing fixes #15148

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5cea8f1
docs(cargo-fix): remove unnecessary issue tracker link
weihanglo Feb 5, 2025
bf85988
docs(cargo-fix): troubleshooting failing fixes
weihanglo Feb 5, 2025
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
25 changes: 16 additions & 9 deletions src/doc/man/cargo-fix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,10 +37,6 @@ pass `--target` to fix code for the given target.

cargo fix --target x86_64-pc-windows-gnu

If you encounter any problems with `cargo fix` or otherwise have any questions
or feature requests please don't hesitate to file an issue at
<https://github.com/rust-lang/cargo>.

### Edition migration

The `cargo fix` subcommand can also be used to migrate a package from one
Expand All @@ -56,11 +52,22 @@ The `cargo fix` subcommand can also be used to migrate a package from one
(without the `--edition` flag) to apply any suggestions given by the
compiler.

And hopefully that's it! Just keep in mind of the caveats mentioned above that
`cargo fix` cannot update code for inactive features or `cfg` expressions.
Also, in some rare cases the compiler is unable to automatically migrate all
code to the new edition, and this may require manual changes after building
with the new edition.
If you encounter failing fixes during migration, instead of fixing everything
in a single `cargo fix` invocation, try fixing only a subset of packages for
specific features and Cargo targets. Fixing each combination separately can
help identify the root cause of failures more easily and avoid unintended
feature unification between packages. For example:
Comment on lines +55 to +59
Copy link
Contributor

Choose a reason for hiding this comment

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

This is less about "failing fixes" and more about "unrelated compilation errors", right?

For the conntext, if I'm understanding correctly, this is coming down to either helping the user are working around #2980 (a workflow that runs counter to Cargo's design) or dealing with #14415 (a bug). This is not something unique to cargo fix except that --all-targets is the default which can get unexpected unification from dev-dependencies when combined with migrating multiple packages at once. I would assume someone knows that they can't run cargo check --workspace --all-targets so I wonder why cargo fix failing would be so surprising and without knowing how to workaround it already. Note that we give a Migrating <build-target-path> message for each build target, which is an indirect way of telling users that --all-targets is being used.

A small part of me also wonders about the balance in meeting a user where they are at vs documenting (and somewhat blessing) unsupported workflows.

Copy link
Member Author

Choose a reason for hiding this comment

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

Yes I agree the troubleshooting can be generalized to cargo check. To me the distinction is that unlike failures in cargo check, cargo fix --all-features is a suggested workflow here. People are exposed to potential failure immediately.

It would be great as well if we can find a place for general troubleshooting

Copy link
Member Author

Choose a reason for hiding this comment

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

I would assume someone knows that they can't run cargo check --workspace --all-targets so I wonder why cargo fix failing would be so surprising and without knowing how to workaround it already.

I would also say from my observation at work, average Rust developers don't really know how each command actually works. What they do is fiddling around different flags, not to mention the indirection from Migrating <path> message. We are able to tell it's feature unification issue because we have read the cargo doc a hundred times.

A small part of me also wonders about the balance in meeting a user where they are at vs documenting (and somewhat blessing) unsupported workflows.

Mutually exclusive features isn't really officially unsupported. It is indeed unrecommended and Cargo features can't handle it well now though. The officially suggested alternative cfg-if may still cause issues like one wants is to test only a specific feature but it got overridden and test failed. So we also want to take care of those alternative workflows.


* Use the `--package` flag to fix only some packages, e.g., `cargo fix --package foo`.
* Instead of `--all-features`, use the `--features` flag to activate a specific
set of features, e.g., `cargo fix --package foo --features myfeat`.
* `cargo fix` implies `--all-targets` by default. Use target selection flags to
fix only a subset of Cargo targets, e.g., `cargo fix --bin mybin`.

Also keep in mind of the caveats mentioned above that `cargo fix` cannot update
code for inactive features or `cfg` expressions. Also, in some rare cases the
compiler is unable to automatically migrate all code to the new edition,
and this may require manual changes after building with the new edition.

[edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html
[edition field]: ../reference/manifest.html#the-edition-field
Expand Down
32 changes: 23 additions & 9 deletions src/doc/man/generated_txt/cargo-fix.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,6 @@ DESCRIPTION

cargo fix --target x86_64-pc-windows-gnu

If you encounter any problems with cargo fix or otherwise have any
questions or feature requests please don’t hesitate to file an issue
at <https://github.com/rust-lang/cargo>.

Edition migration
The cargo fix subcommand can also be used to migrate a package from one
edition
Expand All @@ -57,11 +53,29 @@ DESCRIPTION
(without the --edition flag) to apply any suggestions given by the
compiler.

And hopefully that’s it! Just keep in mind of the caveats mentioned
above that cargo fix cannot update code for inactive features or cfg
expressions. Also, in some rare cases the compiler is unable to
automatically migrate all code to the new edition, and this may require
manual changes after building with the new edition.
If you encounter failing fixes during migration, instead of fixing
everything in a single cargo fix invocation, try fixing only a subset of
packages for specific features and Cargo targets. Fixing each
combination separately can help identify the root cause of failures more
easily and avoid unintended feature unification between packages. For
example:

o Use the --package flag to fix only some packages, e.g., cargo fix
--package foo.

o Instead of --all-features, use the --features flag to activate a
specific set of features, e.g., cargo fix --package foo --features
myfeat.

o cargo fix implies --all-targets by default. Use target selection
flags to fix only a subset of Cargo targets, e.g., cargo fix --bin
mybin.

Also keep in mind of the caveats mentioned above that cargo fix cannot
update code for inactive features or cfg expressions. Also, in some rare
cases the compiler is unable to automatically migrate all code to the
new edition, and this may require manual changes after building with the
new edition.

OPTIONS
Fix options
Expand Down
25 changes: 16 additions & 9 deletions src/doc/src/commands/cargo-fix.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,6 @@ pass `--target` to fix code for the given target.

cargo fix --target x86_64-pc-windows-gnu

If you encounter any problems with `cargo fix` or otherwise have any questions
or feature requests please don't hesitate to file an issue at
<https://github.com/rust-lang/cargo>.

### Edition migration

The `cargo fix` subcommand can also be used to migrate a package from one
Expand All @@ -52,11 +48,22 @@ The `cargo fix` subcommand can also be used to migrate a package from one
(without the `--edition` flag) to apply any suggestions given by the
compiler.

And hopefully that's it! Just keep in mind of the caveats mentioned above that
`cargo fix` cannot update code for inactive features or `cfg` expressions.
Also, in some rare cases the compiler is unable to automatically migrate all
code to the new edition, and this may require manual changes after building
with the new edition.
If you encounter failing fixes during migration, instead of fixing everything
in a single `cargo fix` invocation, try fixing only a subset of packages for
specific features and Cargo targets. Fixing each combination separately can
help identify the root cause of failures more easily and avoid unintended
feature unification between packages. For example:

* Use the `--package` flag to fix only some packages, e.g., `cargo fix --package foo`.
* Instead of `--all-features`, use the `--features` flag to activate a specific
set of features, e.g., `cargo fix --package foo --features myfeat`.
* `cargo fix` implies `--all-targets` by default. Use target selection flags to
fix only a subset of Cargo targets, e.g., `cargo fix --bin mybin`.

Also keep in mind of the caveats mentioned above that `cargo fix` cannot update
code for inactive features or `cfg` expressions. Also, in some rare cases the
compiler is unable to automatically migrate all code to the new edition,
and this may require manual changes after building with the new edition.

[edition]: https://doc.rust-lang.org/edition-guide/editions/transitioning-an-existing-project-to-a-new-edition.html
[edition field]: ../reference/manifest.html#the-edition-field
Expand Down
33 changes: 24 additions & 9 deletions src/etc/man/cargo-fix.1
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,10 +43,6 @@ pass \fB\-\-target\fR to fix code for the given target.
cargo fix \-\-target x86_64\-pc\-windows\-gnu
.fi
.RE
.sp
If you encounter any problems with \fBcargo fix\fR or otherwise have any questions
or feature requests please don\[cq]t hesitate to file an issue at
<https://github.com/rust\-lang/cargo>\&.
.SS "Edition migration"
The \fBcargo fix\fR subcommand can also be used to migrate a package from one
\fIedition\fR <https://doc.rust\-lang.org/edition\-guide/editions/transitioning\-an\-existing\-project\-to\-a\-new\-edition.html> to the next. The general procedure is:
Expand All @@ -68,11 +64,30 @@ warnings are issued, you may want to consider running \fBcargo fix\fR again
compiler.
.RE
.sp
And hopefully that\[cq]s it! Just keep in mind of the caveats mentioned above that
\fBcargo fix\fR cannot update code for inactive features or \fBcfg\fR expressions.
Also, in some rare cases the compiler is unable to automatically migrate all
code to the new edition, and this may require manual changes after building
with the new edition.
If you encounter failing fixes during migration, instead of fixing everything
in a single \fBcargo fix\fR invocation, try fixing only a subset of packages for
specific features and Cargo targets. Fixing each combination separately can
help identify the root cause of failures more easily and avoid unintended
feature unification between packages. For example:
.sp
.RS 4
\h'-04'\(bu\h'+02'Use the \fB\-\-package\fR flag to fix only some packages, e.g., \fBcargo fix \-\-package foo\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'Instead of \fB\-\-all\-features\fR, use the \fB\-\-features\fR flag to activate a specific
set of features, e.g., \fBcargo fix \-\-package foo \-\-features myfeat\fR\&.
.RE
.sp
.RS 4
\h'-04'\(bu\h'+02'\fBcargo fix\fR implies \fB\-\-all\-targets\fR by default. Use target selection flags to
fix only a subset of Cargo targets, e.g., \fBcargo fix \-\-bin mybin\fR\&.
.RE
.sp
Also keep in mind of the caveats mentioned above that \fBcargo fix\fR cannot update
code for inactive features or \fBcfg\fR expressions. Also, in some rare cases the
compiler is unable to automatically migrate all code to the new edition,
and this may require manual changes after building with the new edition.
.SH "OPTIONS"
.SS "Fix options"
.sp
Expand Down