A collection of easy-to-use and extensible commands to be used in your xtask CLI based on clap.
We rely on these commands in each of our Tracel repositories. By centralizing our redundant commands we save a big amount of code duplication, boilerplate and considerably lower their maintenance cost. This also provides a unified interface across all of our repositories.
These commands are not specific to Tracel repositories and they should be pretty much usable in any Rust repositories with a cargo workspace as well as other repositories where Rust is not necessarily the only language. The commands can be easily extended using handy proc macros and by following some patterns described in this README.
- Create a new Cargo workspace:
cargo new my_workspace --vcs none
cd my_workspace
- Create the
xtask
binary crate:
cargo new xtask --bin --vcs none
- Configure the workspace:
Edit the Cargo.toml
file in the root of the workspace to include the following:
[workspace]
members = ["xtask"]
- Add the
tracel-xtask
dependency:
In the xtask/Cargo.toml
file, add the following under [dependencies]
:
[dependencies]
tracel-xtask = "~1.0"
- Build the workspace:
cargo build
Your workspace is now set up with a xtask
binary crate that depends on tracel-xtask
version 1.0.x.
- In the
main.rs
file of the newly createdxtask
crate, import thetracel_xtask
prelude module and then declare aCommand
enum. Select the base commands you want to use by adding themacros::base_commands
attribute:
use tracel_xtask::prelude::*;
#[macros::base_commands(
Bump,
Check,
Fix
Test,
)]
pub enum Command {}
- Update the
main
function to initialize the xtask parser and dispatch the base commands:
fn main() -> anyhow::Result<()> {
let args = init_xtask::<Command>()?;
match args.command {
// dispatch_base_commands function is generated by the commands macro
_ => dispatch_base_commands(args),
}
}
-
Build the workspace with
cargo build
at the root of the repository to verify that everything is. -
You should now be able to display the main help screen which lists the commands you selected previously:
cargo xtask --help
Invoking the xtask binary with cargo is very verbose and not really usable as is. Happily we can create a cargo alias to make it really effortless to invoke it.
Create a new file .cargo/config.toml
in your repository with the following contents:
[alias]
xtask = "run --target-dir target/xtask --package xtask --bin xtask --"
This saves quite a few characters to type as you can now invoke xtask
directly like this:
cargo xtask
Try it with cargo xtask --help
.
We can save even more typing by creating a shell alias for cargo xtask
.
For instance we can set the alias to cx
. Here is how to do it in various shells.
- For bash:
nano ~/.bashrc
# add this to the file
alias cx='cargo xtask'
# save and source the file or restart the shell session
source ~/.bashrc
- For zsh:
nano ~/.zshrc
# add this to the file
alias cx='cargo xtask'
# save and source the file or restart the shell session
source ~/.zshrc
- For fish:
nano ~/.config/fish/config.fish
# add this to the file
alias cx='cargo xtask'
# save and source the file or restart the shell session
source ~/.config/fish/config.fish
- For powershell:
notepad $PROFILE
# add this at the end of file
function cx {
cargo xtask $args
}
# save and quit then open a new powershell terminal
Try it with cx --help
at the root of the repository.
All our repositories follow the same directory hierarchy:
- a
crates
directory which contains all the crates of the workspace - an
examples
directory which holds all the examples crates - a
xtask
directory which is the binary crate for our xtask CLI usingtracel-xtask
As per Cargo convention, Integration tests are tests contained in a tests
directory of a crate besides its src
directory.
Inline tests in src
directory are called Unit tests.
tracel-xtask
allow to easily execute them separately using the test
command.
There are 4 default targets provided by tracel-xtask
:
workspace
which targets the cargo workspace, this is the default targetcrates
are all the binary crates and library cratesexamples
are all the example cratesall-packages
are bothcrates
andexamples
targets
workspace
and all-packages
are different because workspace
uses the --workspace
flag of cargo whereas all-packages
relies on crates
and examples
targets which use the --package
flag. So all-packages
executes a command for each crate
or example individually.
Here are some examples:
# run all the crates tests
cargo xtask test --target crates all
# check format for examples, binaries and libs
cargo xtask check --target all-packages unit
# build the workspace
cargo xtask build --target workspace
# workspace is the default target so this has the same effect
cargo xtask build
The following options are global and precede the actual command on the command line:
- Environment (
-e
,--environment
):
cargo xtask -e production build
-e
or --environment
does not do anything per se in the base commands, it is a flag whose only goal is
to inform your custom commands or dispatch functions about the targeted environment which can be development
(default),
staging
or production
.
- Execution environment (
-E
,--execution-environment
):
cargo xtask -E no-std build
-E
or --execution-environment
does not do anything per se in the base commands, it is a flag whose only goal is
to inform your custom commands or dispatch functions about the targeted execution environment which can be std
or
no-std
.
- Coverage (
-c
,--enable-coverage
):
-c
or --enabled-coverage
setups the Rust toolchain to generate coverage information.
We use the derive API of clap which is based on structs, enums and attribute proc macros. Each base command is a
submodule of the base_commands
module. If the command accepts arguments there is a corresponding struct named <command>CmdArgs
which declare the options, arguments and subcommands. In the case of subcommands a corresponding enum named <command>SubCommand
is defined.
Here is an example with a foo
command:
#[macros::declare_command_args(Target, FooSubCommand)]
struct FooCmdArgs {}
pub enum FooSubCommand {
/// A sub command for foo (usage on the command line: cargo xtask foo print-something)
PrintSomething,
}
Note that it is possible to have an arbitrary level of nested subcommands but deeper nested subcommands cannot be extended, in other words, only the first level of subcommands can be extended. If possible, try to design commands with only one level of subcommands to keep the interface simple.
In the following sections we will see how to create completely new commands as well how to extend existing base commands.
-
First, we organize commands by creating a
commands
module. Create a filextask/src/commands/mycommand.rs
as well as the correspondingmod.rs
file to declare the module contents. -
Then, in
mycommand.rs
define the arguments struct with thedeclare_command_args
macro and define thehandle_command
function. Thedeclare_command_args
macro takes two parameters, the first is the type of the target enum and the second is the type of the subcommand enum if any. If the command has no target or no subcommand then putNone
for each argument respectively.Target
is the default target type provided bytracel-xtask
. This type can be extended to support more targets as we will see in a later section.
use tracel_xtask::prelude::*;
#[macros::declare_command_args(Target, None)]
struct MyCommandCmdArgs {}
pub fn handle_command(_args: MyCommandCmdArgs) -> anyhow::Result<()> {
println!("Hello from my-command");
Ok(())
}
- Make sure to update the
mod.rs
file to declare the command module:
pub(crate) mod my_command;
- We can now add a new variant to the
Command
enum inmain.rs
:
mod commands;
use tracel_xtask::prelude::*;
#[macros::base_commands(
Bump,
Check,
Fix,
Test,
)]
pub enum Command {
MyCommand(commands::mycommand::MyCommandCmdArgs),
}
- And dispatch its handling to our new command module:
fn main() -> anyhow::Result<()> {
let args = init_xtask::<Command>()?;
match args.command {
Command::NewCommand(args) => commands::new_command::handle_command(args),
_ => dispatch_base_commands(args),
}
}
- You can now test your new command with:
cargo xtask my-command --help
cargo xtask my-command
Let's implement a new command called extended-target
to illustrate how to extend the default Target
enum.
-
Create a
commands/extended_target.rs
file and update themod.rs
file as we saw in the previous section. -
We also need to add a new
strum
dependency to ourCargo.toml
file:
[dependencies]
strum = {version = "0.26.3", features = ["derive"]}
- Then we can extend the
Target
enum with themacros::extend_targets
attribute in ourextended_target.rs
file. Here we choose to add a new target calledfrontend
which targets the frontend component we could find for instance in a monorepo:
use tracel_xtask::prelude::*;
#[macros::extend_targets]
pub enum MyTarget {
/// Target the frontend component of the monorepo.
Frontend,
}
- Then we define our command arguments by referencing our newly created
MyTarget
enum in thedeclare_command_args
attribute:
#[macros::declare_command_args(MyTarget, None)]
struct ExtendedTargetCmdArgs {}
- Our new target is then available for use in the
handle_command
function:
pub fn handle_command(args: ExtendedTargetCmdArgs) -> anyhow::Result<()> {
match args.target {
// Default targets
MyTarget::AllPackages => println!("You chose the target: all-packages"),
MyTarget::Crates => println!("You chose the target: crates"),
MyTarget::Examples => println!("You chose the target: examples"),
MyTarget::Workspace => println!("You chose the target: workspace"),
// Additional target
MyTarget::Frontend => println!("You chose the target: frontend"),
};
Ok(())
}
- Register our new command the usual way by adding it to our
Command
enum and dispatch it in themain
function:
mod commands;
use tracel_xtask::prelude::*;
#[macros::base_commands(
Bump,
Check,
Fix,
Test,
)]
pub enum Command {
ExtendedTarget(commands::extended_target::ExtendedTargetCmdArgs),
}
fn main() -> anyhow::Result<()> {
let args = init_xtask::<Command>()?;
match args.command {
Command::ExtendedTarget(args) => commands::extended_target::handle_command(args),
_ => dispatch_base_commands(args),
}
}
- Test the command with:
cargo xtask extended-target --help
cargo xtask extended-target --target frontend
To extend an existing command we use the macros::extend_command_args
attribute which takes three parameters:
- first argument is the type of the base command arguments struct to extend,
- second argument is the target type (or
None
if there is no target), - third argument is the subcommand type (or
None
if there is no subcommand).
Let's use two examples to illustrate this, the first is a command to extend the build
base command with
a new --debug
argument; and the second is a new command to extend the subcommands of the check
base command
to add a new my-check
subcommand.
Note that you can find more examples in the xtask
crate of this repository.
We create a new command called extended-build-args
which will have an additional argument called --debug
.
-
Create the
commands/extended_build_args.rs
file and update themod.rs
file as we saw in the previous section. -
Extend the
BuildCommandArgs
struct using the attributemacros::extend_command_args
and define thehandle_command
function. Note that the macro automatically implements theTryInto
trait which makes it easy to dispatch back to the base command ownhandle_command
function. Also note that if the base command requires a target then you need to provide a target as well in your extension, i.e. the target parameter of the macro cannot beNone
if the base command has aTarget
.
use tracel_xtask::prelude::*;
#[macros::extend_command_args(BuildCmdArgs, Target, None)]
pub struct ExtendedBuildArgsCmdArgs {
/// Print additional debug info when set
#[arg(short, long)]
pub debug: bool,
}
pub fn handle_command(args: ExtendedBuildArgsCmdArgs) -> anyhow::Result<()> {
if args.debug {
println!("Debug is enabled");
}
base_commands::build::handle_command(args.try_into().unwrap())
}
- Register the new command the usual way by adding it to the
Command
enum and dispatch it in themain
function:
mod commands;
use tracel_xtask::prelude::*;
#[macros::base_commands(
Bump,
Check,
Fix,
Test,
)]
pub enum Command {
ExtendedBuildArgs(commands::extended_build_args::ExtendedBuildArgsCmdArgs),
}
fn main() -> anyhow::Result<()> {
let args = init_xtask::<Command>()?;
match args.command {
Command::ExtendedBuildArgs(args) => commands::extended_build_args::handle_command(args),
_ => dispatch_base_commands(args),
}
}
- Test the command with:
cargo xtask extended-build-args --help
cargo xtask extended-build-args --debug
For this one we create a new command called extended-check-subcommands
which will have an additional subcommand.
-
Create a
commands/extended_check_subcommands.rs
file and update themod.rs
file as we saw in the previous section. -
Extend the
CheckCommandArgs
struct using the attributemacros::extend_command_args
:
use tracel_xtask::prelude::*;
#[macros::extend_command_args(CheckCmdArgs, Target, ExtendedCheckSubcommand)]
pub struct ExtendedCheckedArgsCmdArgs {}
- Implement the
ExtendedCheckSubcommand
enum by extending theCheckSubcommand
base enum with the macroextend_subcommands
. It takes the name of the type of the subcommand enum to extend:
#[macros::extend_subcommands(CheckSubCommand)]
pub enum ExtendedCheckSubcommand {
/// An additional subcommand for our extended check command.
MySubcommand,
}
- Implement the
handle_command
function to handle the new subcommand. Note that we must handle theAll
subcommand as well:
use strum::IntoEnumIterator;
pub fn handle_command(args: ExtendedCheckedArgsCmdArgs) -> anyhow::Result<()> {
match args.get_command() {
ExtendedCheckSubcommand::MySubcommand => run_my_subcommand(args.clone()),
ExtendedCheckSubcommand::All => {
ExtendedCheckSubcommand::iter()
.filter(|c| *c != ExtendedCheckSubcommand::All)
.try_for_each(|c| {
handle_command(
ExtendedCheckedArgsCmdArgs {
command: Some(c),
target: args.target.clone(),
exclude: args.exclude.clone(),
only: args.only.clone(),
},
)
})
}
_ => base_commands::check::handle_command(args.try_into().unwrap()),
}
}
fn run_my_subcommand(_args: ExtendedCheckedArgsCmdArgs) -> Result<(), anyhow::Error> {
println!("Executing new subcommand");
Ok(())
}
- Register the new command the usual way by adding it to the
Command
enum and dispatch it in themain
function:
mod commands;
use tracel_xtask::prelude::*;
#[macros::base_commands(
Bump,
Check,
Fix,
Test,
)]
pub enum Command {
ExtendedCheckSubcommand(commands::extended_check_subcommands::ExtendedCheckedArgsCmdArgs),
}
fn main() -> anyhow::Result<()> {
let args = init_xtask::<Command>()?;
match args.command {
Command::ExtendedCheckSubcommand(args) => commands::extended_check_subcommands::handle_command(args),
_ => dispatch_base_commands(args),
}
}
- Test the command with:
cargo xtask extended-check-subcommands --help
cargo xtask extended-check-subcommands my-check
tracel-xtask
provides helper functions to easily execute custom builds or tests with specific features or build targets (do not confuse
Rust build targets which is an argument of the cargo build
command with the xtask target we introduced previously).
For instance we can extend the build
command to build additional crates with custom features or build targets using the helper function:
pub fn handle_command(mut args: tracel_xtask::commands::build::BuildCmdArgs) -> anyhow::Result<()> {
// regular execution of the build command
tracel_xtask::commands::build::handle_command(args)?;
// additional crate builds
// build 'my-crate' with all the features
tracel_xtask::utils::helpers::custom_crates_build(vec!["my-crate"], vec!["--all-features"], None, None, "all features")?;
// build 'my-crate' with specific features
tracel_xtask::utils::helpers::custom_crates_build(vec!["my-crate"], vec!["--features", "myfeature1,myfeature2"], None, None, "myfeature1,myfeature2")?;
// build 'my-crate' with a different target than the default one
tracel_xtask::utils::helpers::custom_crates_build(vec!["my-crate"], vec!["--target", "thumbv7m-none-eabi"], None, None, "thumbv7m-none-eabi target")?;
Ok(())
}
Here is a example GitHub job which shows how to setup coverage, enable it and upload coverage information to codecov:
env:
GRCOV_LINK: "https://github.com/mozilla/grcov/releases/download"
GRCOV_VERSION: "0.8.19"
jobs:
my-job:
runs-on: ubuntu-22.04
steps:
- name: Checkout
uses: actions/checkout@v4
- name: install rust
uses: dtolnay/rust-toolchain@master
with:
components: rustfmt, clippy
toolchain: stable
- name: Install grcov
shell: bash
run: |
curl -L "$GRCOV_LINK/v$GRCOV_VERSION/grcov-x86_64-unknown-linux-musl.tar.bz2" |
tar xj -C $HOME/.cargo/bin
cargo xtask coverage install
- name: Build
shell: bash
run: cargo xtask build
- name: Tests
shell: bash
run: cargo xtask --enable-coverage test all
- name: Generate lcov.info
shell: bash
# /* is to exclude std library code coverage from analysis
run: cargo xtask coverage generate --ignore "/*,xtask/*,examples/*"
- name: Codecov upload lcov.info
uses: codecov/codecov-action@v4
with:
files: lcov.info
token: ${{ secrets.CODECOV_TOKEN }}
By convention this command is responsible to run all the checks, builds, and/or tests that validate the code before opening a pull request or merge request.
The command Validate
can been added via the macro tracel_xtask_macros::commands
like the other commands.
By default all the checks from the check
command are run as well as both unit and integration tests from
the test
command.
You can make your own handle_command
function if you need to perform more validations. Ideally this function
should only call the other commands handle_command
functions.
For quick reference here is a simple example to perform all checks and tests against the workspace:
pub fn handle_command(args: ValidateCmdArgs) -> anyhow::Result<()> {
let target = Target::Workspace;
let exclude = vec![];
let only = vec![];
// checks
[
CheckSubCommand::Audit,
CheckSubCommand::Format,
CheckSubCommand::Lint,
CheckSubCommand::Typos,
]
.iter()
.try_for_each(|c| {
super::check::handle_command(CheckCmdArgs {
target: target.clone(),
exclude: exclude.clone(),
only: only.clone(),
command: Some(c.clone()),
ignore_audit: args.ignore_audit,
})
})?;
// tests
super::test::handle_command(TestCmdArgs {
target: target.clone(),
exclude: exclude.clone(),
only: only.clone(),
threads: None,
jobs: None,
command: Some(TestSubCommand::All),
})?;
Ok(())
}
The check
and fix
commands are designed to help you maintain code quality during development.
They run various checks and fix issues, ensuring that your code is clean and follows best practices.
check
and fix
contains the same subcommands to audit, format, lint or proofread a code base.
While the check
command only reports issues, the fix
command attempts to fix them as they are encountered.
Each check can be executed separately or all of them can be executed sequentially using all
.
Usage to lint the code base:
cargo xtask check lint
cargo xtask fix lint
cargo xtask fix all
Testing is a crucial part of development, and the test
command is designed to make this process easy.
This command makes the distinction between unit tests and integrations tests. Unit tests are inline tests under the
src
directory of a crate. Integration tests are tests defined in files under the tests
directory of a crate besides
the src
directory.
Usage:
# execute workspace unit tests
cargo xtask test unit
# execute workspace integration tests
cargo xtask test integration
# execute workspace both unit tests and integration tests
cargo xtask test all
Note that documentation tests are supported by the doc
command.
Command to build and test the documentation in a workspace.
This is a command reserved for repository maintainers.
The bump
command is used to update the version numbers of all first-party crates in the repository.
This is particularly useful when you're preparing for a new release and need to ensure that all crates have the correct version.
You can bump the version by major, minor, or patch levels, depending on the changes made. For example, if you’ve made breaking changes, you should bump the major version. For new features that are backwards compatible, bump the minor version. For bug fixes, bump the patch version.
Usage:
cargo xtask bump <SUBCOMMAND>
This is a command reserved for repository maintainers and is typically used in publish
GitHub workflows.
This command automates the process of publishing crates to crates.io
, the Rust package registry.
By specifying the name of the crate, xtask
handles the publication process, ensuring that the crate is available for others to use.
Usage:
cargo xtask publish <NAME>
As mentioned, this command is often used in a GitHub workflow. We provide a Tracel's reusable publish-crate workflow that makes use of this command. Here is a simple example with a workflow that publishes two crates A and B with A depending on B.
name: publish all crates
on:
push:
tags:
- "v*"
jobs:
publish-B:
uses: tracel-ai/github-actions/.github/workflows/publish-crate.yml@v1
with:
crate: B
secrets:
CRATES_IO_API_TOKEN: ${{ secrets.CRATES_IO_API_TOKEN }}
# --------------------------------------------------------------------------------
publish-A:
uses: tracel-ai/github-actions/.github/workflows/publish-crate.yml@v1
with:
crate: A
needs:
- publish-B
secrets:
CRATES_IO_API_TOKEN: ${{ secrets.CRATES_IO_API_TOKEN }}
This command provide a subcommand to install the necessary dependencies for performing code coverage and a subcommand to generate the
coverage info file that can then be uploaded to a service provider like codecov. See dedicated section Enable and generate coverage information
.
Various additional subcommands about dependencies.
deny
make sure that all dependencies meet requirements using cargo-deny.
unused
detects dependencies in the workspace that are not in ussed.
This command makes it easier to execute sanitizers as described in the Rust unstable book.
These sanitizers require a nightly toolchain.
Run the specified vulnerability check locally. These commands must be called with 'cargo +nightly'
Usage: xtask vulnerabilities <COMMAND>
Commands:
all Run all most useful vulnerability checks
address-sanitizer Run Address sanitizer (memory error detector)
control-flow-integrity Run LLVM Control Flow Integrity (CFI) (provides forward-edge control flow protection)
hw-address-sanitizer Run newer variant of Address sanitizer (memory error detector similar to AddressSanitizer, but based on partial hardware assistance)
kernel-control-flow-integrity Run Kernel LLVM Control Flow Integrity (KCFI) (provides forward-edge control flow protection for operating systems kerneljs)
leak-sanitizer Run Leak sanitizer (run-time memory leak detector)
memory-sanitizer Run memory sanitizer (detector of uninitialized reads)
mem-tag-sanitizer Run another address sanitizer (like AddressSanitizer and HardwareAddressSanitizer but with lower overhead suitable for use as hardening for production binaries)
nightly-checks Run nightly-only checks through cargo-careful `<https://crates.io/crates/cargo-careful>`
safe-stack Run SafeStack check (provides backward-edge control flow protection by separating stack into safe and unsafe regions)
shadow-call-stack Run ShadowCall check (provides backward-edge control flow protection - aarch64 only)
thread-sanitizer Run Thread sanitizer (data race detector)
help Print this message or the help of the given subcommand(s)