Rox

Rox 是一个强大的开发者工作流程框架，受 Nox、Make 和 cargo-make 启发。

Rox 允许您使用 YAML 文件构建自己的 devtools CLI，从终端检查 CI 流水线状态，甚至阅读文档。任务和流水线将在运行时动态添加到 CLI 的子命令中。Rox 的灵活性旨在使开发团队能够标准化他们的工作流程，而无需编写无尽的“胶水”脚本。

子命令及其帮助信息将在运行时自动从每个 task 或 pipeline 的 name 和 description 中填充。

请参阅 synthesizer 以了解实际项目中的使用示例。

目录

• 为什么选择 Rox？
• 安装
• Roxfile 语法
  • CI
  • 文档
  • 模板
  • 任务
  • 流水线
  • 日志
• 整合一切

为什么选择 Rox？

Rox 的创建目的是使构建和开发应用程序更加容易。它旨在关注可扩展性、性能和文档。以下是一些帮助 Rox 实现这一目标的几个关键功能：

• 动态生成的 CLI：Rox 的子命令在运行时动态添加到 CLI 中。配置完全通过 YAML 处理。
• 强大的原语：通过组合 Rox 的原语（如 Tasks、Pipelines 和 Templates 等），可以处理几乎任何用例，而无需编写大量样板代码。
• 将文档作为一等特性：名称和描述将在运行时自动注入到 CLI 中，因此您的 help 命令始终准确。这有助于开发者了解各种任务和流水线的作用，而无需深入了解代码或理解复杂的 bash。
• 高性能：最小化开销，并为各种架构和操作系统提供本地可执行文件。
• 高效：通过利用流水线阶段和并行执行，开发者可以利用多核机器加快构建和开发任务。
• 用户友好：任务结果以易于消费的表格格式显示给用户，并附带有用的元数据。这使得调试更加容易，并显示出构建步骤中的潜在瓶颈。

安装

Rox可以通过每个发布版本提供的二进制文件进行安装在此处。作为替代方案，也可以通过cargo使用以下命令安装：cargo install rox-cli。

Roxfile 语法

Rox需要一个具有正确格式和语法的YAML文件来解析为CLI。默认情况下，该文件位于./roxfile.yml，但可以在运行时使用-f标志进行覆盖。

CI

Rox允许开发者通过终端以最小的配置查看CI管道结果。

它将自动获取当前分支的CI管道。

ci:
  # The CI provider to use. Currently only GitHub Actions is supported.
  provider: github_actions
  repo_owner: ThomasLaPiana
  repo_name: rox
  # The name of the env var with the stored PAT (Personal Access Token)
  token_env_var: GITHUB_TOKEN

文档

在您的roxfile中指定docs可以使您跟踪项目中各种类型的文档。

• url -> 打开指向path中提供的URL的网页浏览器。
• markdown -> 在特殊的终端Markdown查看器中打开位于path的文件。这允许开发者在不离开终端的情况下在Markdown文档中导航。
• text -> 将文本文件打印到终端。

docs:
  - name: testing
    description: Docs around testing
    kind: markdown # [markdown|url|text]
    path: docs/testing.md

模板

模板允许您指定可由tasks重用的模板化命令。值以位置方式注入。这些旨在促进代码重用并在结构类似命令中保持一致性。

templates:
  - name: docker_build
    command: "docker build {path} -t rox:{image_tag}"
    symbols: ["{path}", "{image_tag}"]

任务

任务是执行的单位。它们旨在是单个shell命令，然后可以通过pipelines进行组合。它们还可以通过指定一个uses并使用values注入值来利用模板。

tasks:
  - name: build-prod
    description: "Build the application dockerfile"
    uses: docker_build
    values: [".", "latest"]
    
  - name: "watch-run"
    description: "Run the application, restarting on file changes"
    command: "cargo watch -c -x run"

流水线

管道是将多个任务链接到单个执行单元的规范方式。注意，stages对象期望一个列表的列表，我们将在下面进一步讨论。

pipelines: 
  - name: example-pipeline
    description: Composes a few tasks
    stages:
      - ["task-a"]
      - ["task-b", "task-c"]

为了提高执行效率，管道支持简单的调度语法，允许在相同阶段的tasks并行执行。这使用户可以更精细地控制多个任务的执行方式，同时仍然保持语法相对简单。

注意：默认情况下不使用并行执行，需要在调用时使用--parallel或-p标志。

stages字段期望一个列表的列表，以促进这一点。每个stage本身就像一个小型管道，并且每个阶段的任务必须全部执行完毕，然后才能开始下一个阶段的执行。

在下面的示例中，并行执行模式如下所示

1. 执行任务a
2. 执行任务b和c，可能并行执行
3. 执行任务e和d，可能并行执行。
4. 最后，执行任务f。

pipelines: 
  - name: example-pipeline
    description: Composes a few tasks
    stages:
      - ["task-a"]
      - ["task-b", "task-c"]
      - ["task-e", "task-d"]
      - ["task-f"]

日志

没有特定的roxfile部分，但logs子命令对于快速查看最近日志非常有用。

将所有这些结合起来

现在我们已经看到了Rox拼图的每一块，我们可以将它们全部组合成一个完整的roxfile。请参见这个仓库中的roxfile.yml示例，其中包含一个有效示例！