Cicero Commands

CI code frequently relies on external CLI tools.
Cicero aids in centrally tracking these, installing them and setting default arguments.

You specify the CLI you want to use and then retrieve a std::process::Command object with the .command() method:

use cicero_commands::*;

pub static CROSS: Cli = Crate::new("cross").into_cli();

CROSS.command()
    .arg("build")
    .arg("--release")
    .arg("--target=aarch64-unknown-linux-gnu")
    .status();

This will automatically install the cross crate, if you don't have it installed yet.

There's various methods for configuring the installation and produced Command object:

use cicero_commands::*;

pub static CLIPPY: Cli = ExpectProgram::new("cargo-clippy").into_cli();

pub static CROSS_BUILD: Cli = Crate::new("cross")
    .into_cli()
    .with_base_command(&|mut command| {
        command
            .arg("build")
            .arg("--release");
        command
    });

pub static TRUNK: Cli = Crate::new("trunk")
    .with_install_args(&["--locked"])
    .into_cli();

When a crate needs to be installed, Cicero will ask you to specify the version in the workspace Cargo.toml:

[workspace.metadata.cicero.commands.dependencies]
cross = "0.2.5"
trunk = "0.20.3"

You can also register the Venv task to be able to run and manage the installed CLI crates from the command-line, e.g.:

cargo ci venv trunk serve  # Run the Cicero-managed `trunk` binary directly.

cargo ci venv bash  # Start a new shell with the venv active.
trunk serve  # Run the Cicero-managed `trunk` binary directly.

cargo install mdbook  # Use `cargo (un-)install` to add or remove Cicero-managed crates, while the venv is active.

exit  # Close the shell to deactivate the venv.

Details on Crate Installation

• Cicero doesn't install crates globally on your system, but rather into a folder in your project's repository.
  This allows you to have different versions of CLI crates between projects. By default, the folder $REPO_ROOT/.cargo-venv is used. This is outside of the target-directory, because removing the installed CLIs when running cargo clean is rarely useful. The folder to use can be overridden by setting the CICERO_VENV_INSTALL_DIR environment variable to a path. The path will be evaluated relative to the repository root. It can also be set to an absolute path.

• Cicero only installs CLI crates when you actually use them.
  For example, you might only use cross in a CI/CD runner, then you don't need it on your development machine.

• Some crates use a different executable name than their crate name,
  for example the crate diesel_cli installs an executable called diesel. Cicero will automatically use this executable name.