3 releases (breaking)
new 0.3.0 | Jun 28, 2024 |
---|---|
0.2.0 | Jun 27, 2024 |
0.1.0 | Jun 26, 2024 |
#372 in Development tools
91 downloads per month
23KB
298 lines
cargo-run
A CLI tool to run custom scripts in Rust, defined in Scripts.toml
.
Features
- Run scripts defined in
Scripts.toml
. - Specify interpreters for scripts (e.g., bash, zsh, PowerShell).
- Initialize a
Scripts.toml
file with default content. - Chain multiple scripts together using the
include
feature. - Set global environment variables and script-specific environment variables with precedence handling.
- Show detailed information about scripts.
Installation
To install cargo-run
, use the following command:
cargo install cargo-run
Usage
When cargo-run
crate is installed it provides a binary cargo-script
or cgs
to run custom scripts. Commands can start with cargo-script
or cgs
.
The examples below use cgs
as the command prefix for simplicity.
Initialize Scripts.toml
The init
command initializes a Scripts.toml
file in the root of your project directory with default content. This file is used to define and manage your custom scripts.
To initialize a Scripts.toml
file, use the following command:
cgs init
Default Scripts.toml
content:
[global_env]
[scripts]
dev = "cargo run"
build = { command = "cargo build", env = { RUST_LOG = "info" } }
release = "cargo build --release"
test = { command = "cargo test", env = { RUST_LOG = "warn" } }
doc = "cargo doc --no-deps --open"
Run a Script
To run a script, use the following command:
cgs run <script_name>
Understanding Scripts.toml
The Scripts.toml
file is used to define scripts. The file is located in the root of the project directory. The following is an example of a Scripts.toml
file:
Simple Script
A simple script that runs a command directly.
[scripts]
build = "echo 'build'"
Script with Interpreter
You can specify an interpreter for the script.
[scripts]
config = { interpreter = "bash", command = "echo 'test'", info = "Script to test" }
Chain of Scripts
You can chain multiple scripts together using the include feature.
[scripts]
release = { include = ["i_am_shell", "build"] }
Detailed Script
A detailed script can include interpreter, command, info, and other scripts to run.
[scripts]
i_am_shell_obj = { interpreter = "bash", command = "./.scripts/i_am_shell.sh", info = "Detect shell script" }
Add info to a script
You can add info to a script to provide more details about the script.
[scripts]
build = { command = "cargo build", info = "Build the project" }
Global Environment Variables
You can define global environment variables that will be available to all scripts. Script-specific environment variables can override these global variables.
[global_env]
RUST_BACKTRACE = "1"
EXAMPLE_VAR = "example_value"
Script-Specific Environment Variables
You can define script-specific environment variables that will override global environment variables.
[scripts]
example01 = { command = "echo $EXAMPLE_VAR", env = { EXAMPLE_VAR = "change_value" } }
example02 = { command = "echo ${RUST_LOG:-unset} ${COMMON_VAR:-unset}", env = { RUST_LOG = "warn" } }
example03 = { command = "echo ${EXAMPLE_VAR:-unset} ${RUST_LOG:-unset} ${COMMON_VAR:-unset}", env = { EXAMPLE_VAR = "change_value_again", RUST_LOG = "info" } }
Environment Variables Precedence
The precedence order for environment variables is as follows:
- Command-line overrides: Environment variables passed through the command line when running a script.
- Script-specific environment variables: Variables defined in the env section of a script.
- Global environment variables: Variables defined in the [global_env] section.
This order ensures that command-line overrides have the highest precedence, followed by script-specific variables, and finally global variables.
Running a Script with Environment Variables
To run a script and override environment variables from the command line, use the following format:
cgs run <script_name> --env <ENV_VAR1>=<value1>
Show command
To show all the scripts and their details, use the following command:
cgs show
Explanation
- Features: Summarizes the main features of the tool.
- Installation: Provides the command to install the tool.
- Usage: Explains how to run scripts using
cargo-script
orcgs
. - Initializing
Scripts.toml
: Explains the purpose of theinit
command and provides the command to initialize the file. - Default
Scripts.toml
Content: Shows the default content created by theinit
command. - Understanding
Scripts.toml
: Details different configurations possible in theScripts.toml
file, including simple scripts, scripts with interpreters, chained scripts, and detailed scripts. - Example
Scripts.toml
File: Provides a complete example of aScripts.toml
file. - Example Usage: Shows how to run scripts and initialize the
Scripts.toml
file. - Global Environment Variables: Explains how to define global environment variables.
- Script-Specific Environment Variables: Explains how to define script-specific environment variables.
- Environment Variables Precedence: Explains the order of precedence for environment variables.
- Show Command: Explains how to show all the scripts and their details.
Dependencies
~63MB
~1.5M SLoC