rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-10-31 08:37:45 +02:00
Code Issues Releases Activity

Add note clarifying xtask not a package to be installed. (#2847)

Browse Source 
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 <egithinji@google.com>
This commit is contained in:
Eric Githinji
2025-08-13 05:08:56 +03:00
committed by GitHub
parent 9e936b6b70
commit 6d3dec9c4c
2 changed files with 13 additions and 29 deletions
Download Patch File Download Diff File Expand all files Collapse all files

7
.cargo/config.toml
View File

@@ -1,12 +1,5 @@
[alias]
# WARNING: Using the `xtask` alias is deprecated and will be unsupported in a
# future version of Cargo. See https://github.com/rust-lang/cargo/issues/10049.
xtask = "run --package xtask --"
install-tools = "run --package xtask -- install-tools"
web-tests = "run --package xtask -- web-tests"
rust-tests = "run --package xtask -- rust-tests"
serve = "run --package xtask -- serve"
build-book = "run --package xtask -- build"
[env]
# To provide an anchor to the root of the workspace when working with paths.

35
README.md
View File

@@ -71,35 +71,26 @@ Then install these tools with:
cargo xtask install-tools
```
> **Note** We use `xtask` for task automation within the project (e.g.
> installing required tools). Xtask is not a package that you should install.
> Visit https://github.com/matklad/cargo-xtask for more information.
## Commands
Here is a summary of the various commands you can run in the project.
Here are some of the commonly used commands you can run in the project. Run
`cargo xtask` to view all available commands.
| Command | Description |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cargo install-tools` | Install all the tools the project depends on. |
| `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). |
| `cargo rust-tests` | Test the included Rust snippets. |
| `cargo web-tests` | Run the web driver tests in the tests directory. |
| `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. |
| Command | Description |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cargo xtask install-tools` | Install all the tools the project depends on. |
| `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). |
| `cargo xtask rust-tests` | Test the included Rust snippets. |
| `cargo xtask web-tests` | Run the web driver tests in the tests directory. |
| `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. |
> **Note** On Windows, you need to enable symlinks
> (`git config --global core.symlinks true`) and Developer Mode.
> **Note** Previous versions this README recommended that you use
> `cargo xtool <tool>`, i.e. `cargo xtool install-tools`. This causes issues
> with pre-existing installations of `cargo-xtool` and is now deprecated.
>
> The new syntax is almost a 1:1 mapping, although `cargo xtool build` has
> become `cargo build-book` to avoid conflicting with the built-in Cargo
> subcommand.
>
> - `cargo xtool build` -> `cargo build-book`
> - `cargo xtool install-tools` -> `cargo install-tools`
> - `cargo xtool serve` -> `cargo serve`
> - `cargo xtool run-tests` -> `cargo run-tests`
> - `cargo xtool web-tests` -> `cargo web-tests`
## Contributing
We would like to receive your contributions. Please see