From 7c23d3bcf8d6535b4b91b5d109d32286217121ae Mon Sep 17 00:00:00 2001 From: Tim McNamara Date: Sun, 6 Jul 2025 05:44:47 +1200 Subject: [PATCH] Provide shorter Cargo aliases for xtool subcommands (#2804) This change deprecates the use of `cargo xtask ` in favor of dedicated aliases for each tool. | Proposed | Current | |----------|---------| | `cargo install-tools` | `cargo xtask install-tools` | | `cargo web-tests` | `cargo xtask web-tests` | | `cargo rust-tests` | `cargo xtask rust-tests` | | `cargo serve` | `cargo xtask serve` | | `cargo build-book` | `cargo xtask build` | _Note_: Because `build` is a pre-existing Cargo sub-command, I've proposed `cargo build-book` as a strawman. Fixes #2803 --- .cargo/config.toml | 9 +++++++-- README.md | 28 +++++++++++++++++++++------- 2 files changed, 28 insertions(+), 9 deletions(-) diff --git a/.cargo/config.toml b/.cargo/config.toml index c8e54362..c0909084 100644 --- a/.cargo/config.toml +++ b/.cargo/config.toml @@ -1,7 +1,12 @@ [alias] -# We use this alias for task automation in the project. -# See README in xtask directory. +# 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. diff --git a/README.md b/README.md index c5357aac..a41b45d2 100644 --- a/README.md +++ b/README.md @@ -75,17 +75,31 @@ cargo xtask install-tools Here is a summary of the various commands you can run in the project. -| 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. | -| `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, run MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx where xx is the ISO 639 language code (e.g. da for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. | +| 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. | +| `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, run MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx where xx is the ISO 639 language code (e.g. 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 `, 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