Skip to content

Commit 6d3dec9

Browse files
egithinjiEric Githinji
egithinji
and
Eric Githinji
authored
Add note clarifying xtask not a package to be installed. (#2847)
As mentioned in #2803 , if someone has the `cargo-xtask` crate installed in their system, they will get a deprecation warning every time they run one of the `cargo xtask ...` commands. The only way to encounter the deprecation warning is by someone intentionally running `cargo install cargo-xtask`. To mitigate this we are adding a note in the README to explain the usage of xtask in the project and that it is not a package to be installed. A previous PR #2804 addressed this by adding aliases for each xtask subcommand and deprecating the use of `cargo xtask` as a prefix for these commands. While this fixes the warning, the disadvantage is that it doesn't allow one to run `cargo xtask` to view all available subcommands in the project with help instructions. Also the help message that appears if one does e.g. `cargo install-tools --help` still refers to `xtask` which might be confusing for the user. So overall it's a better user experience to keep the usage as `cargo xtask <subcommand>`. Also the use of `cargo xtask` is a pattern used in other large rust projects (see some examples [here](https://github.com/matklad/cargo-xtask?tab=readme-ov-file#external-examples)). Co-authored-by: Eric Githinji <[email protected]>
1 parent 9e936b6 commit 6d3dec9

File tree

2 files changed

+13
-29
lines changed

2 files changed

+13
-29
lines changed

‎.cargo/config.toml

Lines changed: 0 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,12 +1,5 @@
11
[alias]
2-
# WARNING: Using the `xtask` alias is deprecated and will be unsupported in a
3-
# future version of Cargo. See https://github.com/rust-lang/cargo/issues/10049.
42
xtask = "run --package xtask --"
5-
install-tools = "run --package xtask -- install-tools"
6-
web-tests = "run --package xtask -- web-tests"
7-
rust-tests = "run --package xtask -- rust-tests"
8-
serve = "run --package xtask -- serve"
9-
build-book = "run --package xtask -- build"
103

114
[env]
125
# To provide an anchor to the root of the workspace when working with paths.

‎README.md

Lines changed: 13 additions & 22 deletions
Original file line numberDiff line numberDiff line change
@@ -71,35 +71,26 @@ Then install these tools with:
7171
cargo xtask install-tools
7272
```
7373

74+
> **Note** We use `xtask` for task automation within the project (e.g.
75+
> installing required tools). Xtask is not a package that you should install.
76+
> Visit https://github.com/matklad/cargo-xtask for more information.
77+
7478
## Commands
7579

76-
Here is a summary of the various commands you can run in the project.
80+
Here are some of the commonly used commands you can run in the project. Run
81+
`cargo xtask` to view all available commands.
7782

78-
| Command | Description |
79-
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80-
| `cargo install-tools` | Install all the tools the project depends on. |
81-
| `cargo serve` | Start a web server with the course. You'll find the content on http://localhost:3000. To serve any of the translated versions of the course, add the language flag (`--language` or `-l`) followed by xx, where xx is the ISO 639 language code (e.g. `cargo xtask serve -l da` for the Danish translation). |
82-
| `cargo rust-tests` | Test the included Rust snippets. |
83-
| `cargo web-tests` | Run the web driver tests in the tests directory. |
84-
| `cargo build-book` | Create a static version of the course in the `book/` directory. Note that you have to separately build and zip exercises and add them to book/html. To build any of the translated versions of the course, add the language flag (`--language` or `-l`) followed by xx, where xx is the ISO 639 language code (e.g. `cargo xtask build -l da` for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. |
83+
| Command | Description |
84+
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
85+
| `cargo xtask install-tools` | Install all the tools the project depends on. |
86+
| `cargo xtask serve` | Start a web server with the course. You'll find the content on http://localhost:3000. To serve any of the translated versions of the course, add the language flag (--language or -l) followed by xx, where xx is the ISO 639 language code (e.g. cargo xtask serve -l da for the Danish translation). |
87+
| `cargo xtask rust-tests` | Test the included Rust snippets. |
88+
| `cargo xtask web-tests` | Run the web driver tests in the tests directory. |
89+
| `cargo xtask build` | Create a static version of the course in the `book/` directory. Note that you have to separately build and zip exercises and add them to book/html. To build any of the translated versions of the course, add the language flag (--language or -l) followed by xx, where xx is the ISO 639 language code (e.g. cargo xtask build -l da for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. |
8590

8691
> **Note** On Windows, you need to enable symlinks
8792
> (`git config --global core.symlinks true`) and Developer Mode.
8893
89-
> **Note** Previous versions this README recommended that you use
90-
> `cargo xtool <tool>`, i.e. `cargo xtool install-tools`. This causes issues
91-
> with pre-existing installations of `cargo-xtool` and is now deprecated.
92-
>
93-
> The new syntax is almost a 1:1 mapping, although `cargo xtool build` has
94-
> become `cargo build-book` to avoid conflicting with the built-in Cargo
95-
> subcommand.
96-
>
97-
> - `cargo xtool build` -> `cargo build-book`
98-
> - `cargo xtool install-tools` -> `cargo install-tools`
99-
> - `cargo xtool serve` -> `cargo serve`
100-
> - `cargo xtool run-tests` -> `cargo run-tests`
101-
> - `cargo xtool web-tests` -> `cargo web-tests`
102-
10394
## Contributing
10495

10596
We would like to receive your contributions. Please see

0 commit comments

Comments
 (0)