cargo-run

一个用于在 Rust 中运行自定义脚本（在 Scripts.toml 中定义）的 CLI 工具。

功能

• 运行 Scripts.toml 中定义的脚本。
• 指定脚本的解释器（例如，bash，zsh，PowerShell）。
• 使用默认内容初始化 Scripts.toml 文件。
• 使用 include 功能将多个脚本连接在一起。
• 设置全局环境变量和脚本特定环境变量，并处理优先级。
• 显示有关脚本的详细信息。
• 定义脚本要求和工具链。

安装

要安装 cargo-run，请使用以下命令

cargo install cargo-run

用法

当安装 cargo-run crate 时，它提供了一个二进制文件 cargo-script 或 cgs 来运行自定义脚本。命令可以以 cargo-script 或 cgs 开头。

以下示例使用 cgs 作为命令前缀以简化。

初始化 Scripts.toml

init 命令在项目目录的根目录中初始化一个带有默认内容的 Scripts.toml 文件。该文件用于定义和管理您的自定义脚本。

要初始化 Scripts.toml 文件，请使用以下命令

cgs init

默认 Scripts.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"

运行脚本

要运行脚本，请使用以下命令

cgs run <script_name>

理解 Scripts.toml

Scripts.toml 文件用于定义脚本。该文件位于项目目录的根目录中。以下是脚本的所有可能配置

• command：要运行的命令。可以是字符串，脚本的路径。
• interpreter：用于脚本的解释器。（例如，bash，zsh，PowerShell）。
• info：有关脚本的其他信息。（有关脚本的可选信息）。
• include：将多个脚本连接在一起。（例如，["script1"，"script2"】）。
• env: 脚本特定的环境变量。（例如，{ EXAMPLE_VAR = "example_value" }）。
• requires: 工具和工具链的必需版本。（例如，["tool1>=version1", "tool2>=version2"]）。
• toolchain: 用于脚本的工具链。（例如，"stable", "nightly", "python:3.8"）。

脚本示例

以下是一个 Scripts.toml 文件的示例

简单脚本

一个直接运行命令的简单脚本。

[scripts]
build = "echo 'build'"

带有解释器的脚本

您可以为脚本指定解释器。

[scripts]
config = { interpreter = "bash", command = "echo 'test'", info = "Script to test" }

脚本链

您可以使用包含功能将多个脚本链接在一起。

[scripts]
release = { include = ["i_am_shell", "build"] }

详细脚本

详细脚本可以包括解释器、命令、信息和要运行的其它脚本。

[scripts]
i_am_shell_obj = { interpreter = "bash", command = "./.scripts/i_am_shell.sh", info = "Detect shell script" }

向脚本添加信息

您可以向脚本添加信息，以提供有关脚本的更多细节。

[scripts]
build = { command = "cargo build", info = "Build the project" }

全局环境变量

您可以定义全局环境变量，这些变量将可供所有脚本使用。脚本特定的环境变量可以覆盖这些全局变量。

[global_env]
RUST_BACKTRACE = "1"
EXAMPLE_VAR = "example_value"

脚本特定环境变量

您可以定义脚本特定的环境变量，这些变量将覆盖全局环境变量。

[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" } }

环境变量优先级

环境变量的优先级顺序如下

1. 命令行覆盖：在运行脚本时通过命令行传递的环境变量。
2. 脚本特定环境变量：在脚本 env 部分定义的变量。
3. 全局环境变量：在 [global_env] 部分定义的变量。

此顺序确保命令行覆盖具有最高优先级，其次是脚本特定变量，最后是全球变量。

使用环境变量运行脚本

要运行脚本并从命令行覆盖环境变量，请使用以下格式

cgs run <script_name> --env <ENV_VAR1>=<value1>

脚本需求和工具链

您可以为脚本指定工具和工具链的必需版本。如果不符合要求，则脚本不会运行。

内联配置

[scripts]
deploy = { command = "./deploy.sh", requires = ["docker>=19.03", "kubectl>=1.18"], info = "Deployment script", env = { EXAMPLE_VAR = "deploy_value" } }

详细配置

[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" }

显示命令

要显示所有脚本及其详细信息，请使用以下命令

cgs show

说明

• 特性：总结了工具的主要特性。
• 安装：提供安装工具的命令。
• 使用：解释如何使用 cargo-script 或 cgs 运行脚本。
• 初始化 Scripts.toml：解释 init 命令的目的，并提供初始化文件的命令。
• 默认 Scripts.toml 内容：显示 init 命令创建的默认内容。
• 理解 Scripts.toml：详细说明 Scripts.toml 文件中可能的不同配置，包括简单脚本、带有解释器的脚本、链式脚本和详细脚本。
• 示例 Scripts.toml 文件：提供完整的 Scripts.toml 文件示例。
• 示例使用：显示如何运行脚本和初始化 Scripts.toml 文件。
• 全局环境变量：解释如何定义全局环境变量。
• 脚本特定环境变量：解释如何定义脚本特定环境变量。
• 环境变量优先级：解释环境变量的优先级顺序。
• 显示命令：解释如何显示所有脚本及其详细信息。
• 脚本需求和工具链：解释如何指定脚本的必需工具版本和工具链，包括内联和类似 CI/CD 的配置示例。