A collection of utility functions and command line interfaces for cargo-xtask.
This crate provides the following utilities:
cargo xtask dist
and related subcommands- Builds a distributable tar.gz package for your bin crate.
cargo xtask lint
and related subcommands- Runs the lints for your bin/lib crate.
- Integrated with
rustdoc
,rustfmt
,clippy
,cargo-sync-rdme
,cargo-udeps
.
cargo xtask tidy
and related subcommands- Fixes the problems on your bin/lib crate.
- Integrated with
rustfmt
,clippy
,cargo-sync-rdme
.
cargo xtask pre-release
- Checks if your bin/lib crate is ready for a release.
cargo xtask build
,clippy
,doc
,fmt
,test
- Runs the cargo commands with options useful for testing and continuous
integration.
--all-workspaces
- Runs the cargo commands for all workspaces.--workspace
- Runs the cargo commands for all packages in the workspace.--each-features
- Repeats to runs the cargo commands for each feature enabled.--exhaustive
- Same as--all-workspaces --workspace --each-features
.
- Runs the cargo commands with options useful for testing and continuous
integration.
cargo xtask docsrs
- Builds the documentation for your lib crate with configuration for docs.rs.
cargo xtask exec
- Runs a command in the gicontext of all workspaces.
First, create an xtask
crate following the instructions on the
cargo-xtask website.
Then, run the following command to add cli-xtask
to the dependencies.
-
For bin crates:
cargo add -p xtask cli-xtask --features main,bin-crate
If you want to use extra tools such as
cargo-sync-rdme
andcargo-udeps
, add thebin-crate-extra
feature.cargo add -p xtask cli-xtask --features main,bin-crate,bin-crate-extra
-
For lib crates:
cargo add -p xtask cli-xtask --features main,lib-crate
If you want to use extra tools such as
cargo-sync-rdme
andcargo-udeps
, add thelib-crate-extra
feature.cargo add -p xtask cli-xtask --features main,lib-crate,lib-crate-extra
Finally, edit xtask/src/main.rs
as follows
use cli_xtask::{Result, Xtask};
fn main() -> Result<()> {
<Xtask>::main()
}
Now you can run various workflows with cargo xtask
.
If you want to remove the subcommands that are not useful for your project, you can remove them by disabling the corresponding cargo features. See the Feature flags section for more information.
If you want to add the subcommands that are not included in this crate,
you can add them by creating a new data structure that implements the
clap::Subcommand
and Run
.
See the documentation of Xtask
for more
information.
By using the features flags of cli-xtask, you can enable only the features and commands you need. By default, all features are disabled.
The following section contains a list of available features:
main
- Enables [Xtask::main
] function and [Xtask::main_with_config
] function that are the premade entry point for the CLI.error-handler
- Enables functions for error handling inerror_handler
module.logger
- Enables functions for logging inlogger
module.
There are two types of features that enable subcommands:
- Combined features - features that enable several useful subcommands at once, depending on the type of crate
- Separated features - features that enable each subcommand separately
bin-crate
:- Enables useful subcommands for bin crates.lib-crate
- Enables useful subcommands for lib crates.bin-crate-extra
- Enables the additional subcommands useful for bin crates.lib-crate-extra
- Enables the additional subcommands useful for lib crates.
The {bin,lib}-crate
feature requires only the standard Rust tools that can
be installed with rustup
. The {bin,lib}-crate-extra
feature may require
third-party tools.
The following features require only the standard Rust tools:
subcommand-build
- Enablescargo xtask build
.subcommand-clippy
- Enablescargo xtask clippy
.subcommand-dist
- Enablescargo xtask dist
.subcommand-dist-archive
- Enablescargo xtask dist-archive
.subcommand-dist-build-bin
- Enablescargo xtask dist-build-bin
.subcommand-dist-build-completion
- Enablescargo xtask dist-build-completion
.subcommand-dist-build-doc
- Enablescargo xtask dist-build-doc
.subcommand-dist-build-license
- Enablescargo xtask dist-build-license
.subcommand-dist-build-man
- Enablescargo xtask dist-build-man
.subcommand-dist-build-readme
- Enablescargo xtask dist-build-readme
.subcommand-dist-clean
- Enablescargo xtask dist-clean
.subcommand-doc
- Enablescargo xtask doc
.subcommand-docsrs
- Enablescargo xtask docsrs
.subcommand-exec
- Enablescargo xtask exec
.subcommand-fmt
- Enablescargo xtask fmt
.subcommand-lint
- Enablescargo xtask lint
.subcommand-pre-release
- Enablescargo xtask pre-release
.subcommand-test
- Enablescargo xtask test
.subcommand-tidy
- Enablescargo xtask tidy
.
The following features require third-party tools:
subcommand-sync-rdme
- Enablescargo xtask sync-rdme
. Requirescargo-sync-rdme
installed.subcommand-udeps
- Enablescargo xtask udeps
. Requirescargo-udeps
installed.
archive
- Enablesarchive
module which provides the functionality to create the archive file for distribution.
The minimum supported Rust version is Rust 1.74.0. At least the last 3 versions of stable Rust are supported at any given time.
While a crate is a pre-release status (0.x.x) it may have its MSRV bumped in a patch release. Once a crate has reached 1.x, any MSRV bump will be accompanied by a new minor version.
This project is licensed under either of
- Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
See CONTRIBUTING.md.