https://github.com/rsaz/cargo-script
A CLI tool to run custom scripts in Rust, defined in Scripts.toml
https://github.com/rsaz/cargo-script
Last synced: 18 days ago
JSON representation
A CLI tool to run custom scripts in Rust, defined in Scripts.toml
- Host: GitHub
- URL: https://github.com/rsaz/cargo-script
- Owner: rsaz
- Created: 2024-06-26T00:53:36.000Z (10 months ago)
- Default Branch: main
- Last Pushed: 2024-07-05T11:53:31.000Z (10 months ago)
- Last Synced: 2025-04-02T21:42:22.291Z (26 days ago)
- Language: Rust
- Size: 55.7 KB
- Stars: 20
- Watchers: 2
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# cargo-run
[](https://crates.io/crates/cargo-run)
[](https://docs.rs/cargo-run)
[](https://deps.rs/crate/cargo-run/0.1.0)
[](https://crates.io/crates/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.
- Define scripts requirements and toolchains.
## Installation
To install `cargo-run`, use the following command:
```sh
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:
```sh
cgs init
```
Default `Scripts.toml` content:
```toml
[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:
```sh
cgs run
```
## Understanding `Scripts.toml`
The `Scripts.toml` file is used to define scripts. The file is located in the root of the project directory. Here are all the possible configurations for a script:
- **command**: The command to run. Can be a string, path to a script.
- **interpreter**: The interpreter to use for the script. (e.g., bash, zsh, PowerShell).
- **info**: Additional information about the script. (Optional information about the script).
- **include**: Chain multiple scripts together. (e.g., ["script1", "script2"]).
- **env**: Script-specific environment variables. (e.g., { EXAMPLE_VAR = "example_value" }).
- **requires**: Required versions of tools and toolchains. (e.g., ["tool1>=version1", "tool2>=version2"]).
- **toolchain**: The toolchain to use for the script. (e.g., "stable", "nightly", "python:3.8").
## Scripts Examples
The following is an example of a `Scripts.toml` file:
### Simple Script
A simple script that runs a command directly.
```toml
[scripts]
build = "echo 'build'"
```
### Script with Interpreter
You can specify an interpreter for the script.
```toml
[scripts]
config = { interpreter = "bash", command = "echo 'test'", info = "Script to test" }
```
### Chain of Scripts
You can chain multiple scripts together using the include feature.
```toml
[scripts]
release = { include = ["i_am_shell", "build"] }
```
### Detailed Script
A detailed script can include interpreter, command, info, and other scripts to run.
```toml
[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.
```toml
[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.
```toml
[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.
```toml
[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:
1. Command-line overrides: Environment variables passed through the command line when running a script.
2. Script-specific environment variables: Variables defined in the env section of a script.
3. 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:
```sh
cgs run --env =
```
### Script Requirements and Toolchains
You can specify the required versions of tools and toolchains for your scripts. If the requirements are not met, the script will not run.
**Inline Configuration:**
```toml
[scripts]
deploy = { command = "./deploy.sh", requires = ["docker>=19.03", "kubectl>=1.18"], info = "Deployment script", env = { EXAMPLE_VAR = "deploy_value" } }
```
**Detailed Configuration:**
```toml
[scripts.build]
command = "cargo build"
info = "Run cargo build"
[scripts.test01]
command = "cargo run"
requires = ["rustup < 1.24.3"]
toolchain = "stable"
info = "Build project with nightly toolchain"
env = { EXAMPLE_VAR = "build_value" }
[scripts.build_with_python]
command = "python setup.py build"
requires = ["python >= 3.8"]
toolchain = "python:3.8"
info = "Build project with Python 3.8"
env = { EXAMPLE_VAR = "build_with_python" }
```
### Show command
To show all the scripts and their details, use the following command:
```sh
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` or `cgs`.
- **Initializing `Scripts.toml`**: Explains the purpose of the `init` command and provides the command to initialize the file.
- **Default `Scripts.toml` Content**: Shows the default content created by the `init` command.
- **Understanding `Scripts.toml`**: Details different configurations possible in the `Scripts.toml` file, including simple scripts, scripts with interpreters, chained scripts, and detailed scripts.
- **Example `Scripts.toml` File**: Provides a complete example of a `Scripts.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.
- **Script Requirements and Toolchains**: Explains how to specify required tool versions and toolchains for scripts, with examples of both inline and CI/CD-like configurations.