Brix

Brix 是一个用 Rust 编写的 CLI 工具，用于搭建和代码生成。

致谢

特别感谢 Caleb Cushing 提供原始 Java 版本、早期界面设计和内部架构。

安装

Brix 可在 crates.io 和 Arch Linux 的 AUR 上获取。

使用 cargo 安装

cargo install brix

Arch Linux (使用 AUR 辅助工具，如 yay 或 trizen)

yay -S brix-git

运行

用法

brix [LANGUAGE] [CONFIG NAME] [PROJECT] [MODULE]
brix [OPTIONS] --config-dir | -d [CONFIG DIRECTORY]
brix [OPTIONS] --workdir | -w [WORKING DIRECTORY]

本地构建

要求

• Cargo 和至少 Rust 版本 1.43.1

运行

• 运行 cargo build
• 运行 cargo run

测试

运行 cargo test --all 测试整个工作空间。

生成文档

运行 cargo doc --no-deps --workspace --document-private-items --open

使用 Brix

语言目录

要在项目中开始使用 Brix，请在你的项目目录中创建一个 .config/brix 目录。此目录将包含你的配置文件。运行 brix 后指定第一个参数将告诉它使用哪个子目录。例如，使用 brix java 启动 Brix 将在项目目录中的 .config/brix/java 目录中查找配置文件。此参数称为 语言。如果找不到配置文件，Brix 将向上移动到父目录，直到找到包含 .config/brix/java 的目录。此参数不一定必须限制为编程语言，它存在是为了将使用方式相似的配置文件分组，例如用于启动特定项目。

配置名称

当然，在未指定特定配置文件的情况下运行 brix [language] 是有点无用的。第二个参数指定要使用的文件名。运行 brix java tutorial 将在 .config/brix/java 中搜索名为 tutorial.brix.yml 或 tutorial.brix.yaml 的文件。目前，文件必须以 YAML 编写，但将来将支持更多选项，如 JSON 和 TOML。

项目和模块

这两个参数特定于你的配置文件，你可以随意使用它们，所以让我们先看看配置文件的结构。

配置文件

Brix 提供了各种命令，供你用于构建和生成项目。在最顶层，配置文件只是一个命令列表，因此我们可以从声明 commands 属性开始

# example.brix.yml
commands:
  - search_replace:
    # ...
  - exec:
    # ...

你列出的命令将按从上到下的顺序依次执行。以下命令受支持：

• copy

  将文件或目录复制到新位置。

• search_replace

  在文件中搜索字符串或正则表达式，并用另一个字符串替换它。

• exec

  执行一系列命令。

• mkdir

  创建目录。

• template

  将文件模板到新位置。

让我们从最基本的 copy 命令开始，并使用 Brix 简单地复制一个 .gitignore 文件。我们的配置文件可能看起来像这样

# .config/brix/js/gitignore.brix.yml
commands:
  - copy:
      source: .gitignore
      destination: app/.gitignore

源代码目录始终相对于配置文件的位置。在这种情况下，它将是 .config/brix/js/.gitignore。目标目录相对于您运行 brix 的位置，这通常称为工作目录，可以使用 --workdir 或 -w 标志来覆盖。现在，如果我们要在项目目录中运行 brix js gitignore，实际上会得到一个错误。这是因为 Brix 需要指定 project 和 module 参数。在我们的情况下，我们还没有使用它们，因此可以指定任何内容。现在，运行 brix js gitignore project module 将会执行命令。如果您还没有 app 目录，Brix 会为您创建一个，并将 .gitignore 文件复制到其中。

但是，如果我们想将文件放在 app 之外的位置，这对我们的项目来说就不太方便了。假设现在我们除了 app 之外还有一个 backend 文件夹。要将 .gitignore 文件复制到 backend，我们必须每次都更改配置文件中的目标。相反，这正是项目参数和模块参数派上用场的地方。让我们将配置文件更改为

# .config/brix/js/gitignore.brix.yml
commands:
  - copy:
      source: .gitignore
      destination: {{project}}/.gitignore

在这里，我们在目标中使用 project 参数。运行 brix js gitignore backend module 现在会将文件复制到 backend/.gitignore。如果我们想将其复制到其他地方，我们只需运行 brix js gitignore somewhere_else module。

我们还可以使用模块参数来，例如，采样不同的 gitignore 文件。

# .config/brix/js/gitignore.brix.yml
commands:
  - copy:
      source: {{module}}/.gitignore
      destination: {{project}}/.gitignore

运行 brix js gitignore dashboard default 将会使用 .config/brix/js/default/.gitignore 并将其复制到 dashboard/.gitignore。

现在，让我们全面看看所有的命令。

复制

commands:
  - copy:
      source: file.txt
      destination: output/file.txt
      overwrite: true # Optional, will ask by default to overwrite if the file already exists

搜索替换

搜索替换在 search 字段中使用 fancy regex 进行正则表达式，并支持回溯。语法最好在这里解释 这里。

commands:
  - search_replace:
      destination: file-to-search-replace.txt
      search: search string # fancy-regex supported
      replace: replace string

执行

按顺序执行命令。

commands:
  - exec:
      commands:
        - 'echo "Hello World!"'
        - "prettier --write ."
        - "cargo --version"
      stdout: true # Optional

创建目录

创建目录。

commands:
  - mkdir:
      destination: output/directory

模板

模板化文件。

commands:
  - template:
      source: file.ex.hbs
      destination: output/file.ex
      overwrite: true # Optional
      context: # Optional
        first: {{project}}Service
        second: {{module}}

file.ex.hbs 可能看起来像

defmodule App.{{first}.{{second}} do
  # ...
end

当模板化时，output/file.ex

defmodule App.UsersService.Store do
  # ...
end

上下文和模板化

Brix 使用 Handlebars，特别是 Rust 版本，在 template 命令和配置文件中一般都使用。命令中的 context 参数不是必需的，因为如果模板文件中指定了，{{project}} 和 {{module}} 会自动处理。

在配置文件中还可以指定全局上下文

context:
  edition: 2022
  name: {{project}}
commands:
  - template:
      source: file.txt.hbs
      destination: output/file-{{edition}}.txt
  - copy:
      source: {{edition}}/notes.txt
      destination: output/notes.txt

在这种情况下，参数 edition、name、project 和 module 都可以在配置文件本身以及 template 命令中引用的所有模板文件中使用。全局上下文对于声明在多个命令之间共享的常量也非常有用。

模板辅助工具

Brix 还提供了一些有用的辅助工具来操作这些变量，特别是用于更改大小写和格式。以下是一些辅助工具：

• to-upper
• to-lower
• to-title
• to-case
• to-flat
• to-java-package
• to-java-package-path

所有这些都可以用来替换，例如，使用 {{project}}

context:
  project: 'foo BAR 40'

{{to-upper              project}} # FOO BAR 40
{{to-lower              project}} # foo bar 40
{{to-title              project}} # Foo Bar 40
{{to-flat               project}} # foobar40
{{to-java-package       project}} # foo.bar40
{{to-java-package-path  project}} # foo/bar40

重用模板

Brix 有一个额外的优点，即不需要在语言目录中使用特定的文件夹结构。模板和其他文件与配置文件完全独立。这意味着重用模板变得容易得多，因为所有内容都仅通过路径进行引用。如果您需要在两个不同的配置文件中使用相同的模板，只需在两个文件中引用文件路径并使用不同的上下文即可。

完整示例

最后，让我们看一下使用 Brix 引导 Java 项目的完整示例。将 .config/brix 目录放置在 HOME 目录中，以便可以从任何地方运行 brix 并创建这样的项目。

commands:
  - copy: # Copy all of the shared files to the project directory
      source: project/shared
      destination: .
      overwrite: true
  - template: # Template build.gradle.kts
      source: module/build.gradle.kts.hbs
      destination: "module/{{module}}/build.gradle.kts"
      overwrite: false
  - template: # Template module-info.java
      source: module/src/main/java/module-info.java.hbs
      destination: "module/{{module}}/src/main/java/module-info.java"
      overwrite: false
  - template: # Teplate package.json
      source: project/templates/shared/package.json.hbs
      destination: "package.json"
      overwrite: false
  - template: # Template settings.gradle.kts.hbs
      source: project/templates/shared/settings.gradle.kts.hbs
      destination: "settings.gradle.kts"
      overwrite: false
  - mkdir: # Create the main directory for the module
      destination: "module/{{module}}/src/main/java/com/example/{{module}}"
  - mkdir: # Create the test directory for the module
      destination: "module/{{module}}/src/test/java/com/example/{{module}}"
  - exec: # Run the following commands with no stdout
      commands:
        - git init
        - git add .
        - git commit -m initial
        - yarn up
      stdout: false

更多示例

一些额外的示例位于 ./config/brix/rust。

• copy cargo run -- rust copy brix foo
• exec cargo run -- rust exec foo foo
• mkdir cargo run -- rust mkdir brix foo
• search_replace cargo run -- rust search_replace brix foo
• template cargo run -- rust template brix foo