pkgmgr-homebrew-formula-dev

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Homebrew Formula Development

Homebrew Formula开发

Guide for researching, creating, testing, and maintaining Homebrew formulas in a custom tap.

本指南介绍了在自定义tap中研究、创建、测试和维护Homebrew formula的方法。

When to Use This Skill

何时使用本技能

Creating a new Homebrew formula for a project
Debugging formula build or test failures
Running local validation before CI
Understanding Homebrew's Ruby DSL
Setting up livecheck for automatic version detection

为项目创建新的Homebrew formula
调试formula构建或测试失败的问题
在CI前运行本地验证
理解Homebrew的Ruby DSL
设置livecheck以自动检测版本

Template Pipeline

模板流水线

This skill includes a JSON Schema → Mustache template pipeline for generating formulas from structured data.

本技能包含一条JSON Schema → Mustache模板流水线，用于从结构化数据生成formula。

Workflow

工作流程

Create a JSON file conforming to
```
scripts/formula.schema.ts
```
Run
```
just template-formula <path-to-json>
```
to validate and render
The pipeline validates with AJV, preprocesses (PascalCase, language dispatch, license rendering), then renders via Mustache

创建符合
```
scripts/formula.schema.ts
```
规范的JSON文件
运行
```
just template-formula <path-to-json>
```
命令进行验证和渲染
流水线会通过AJV进行验证，然后进行预处理（转换为PascalCase、语言分发、许可证渲染），最后通过Mustache完成渲染

Key Files

关键文件

File	Purpose
`scripts/formula.schema.ts`	JSON Schema (draft-2020-12) defining formula structure
`scripts/formula.helper.ts`	Preprocessing: PascalCase, license rendering, install flattening, partials loading
`reference/templates/main.mustache`	Main template — renders all shared fields, dispatches to language partials
`reference/templates/langs/*.mustache`	Language-specific install partials (go, rust, python, zig, cmake, autotools, meson)
`test/data/*.json`	Test fixtures covering each scenario
`test/cases/*.sh`	Test cases that validate rendered output

文件	用途
`scripts/formula.schema.ts`	定义formula结构的JSON Schema（draft-2020-12版本）
`scripts/formula.helper.ts`	预处理：转换为PascalCase、许可证渲染、安装信息扁平化、加载部分模板
`reference/templates/main.mustache`	主模板——渲染所有共享字段，分发到语言相关的部分模板
`reference/templates/langs/*.mustache`	特定语言的安装部分模板（go、rust、python、zig、cmake、autotools、meson）
`test/data/*.json`	覆盖各种场景的测试用例数据
`test/cases/*.sh`	验证渲染输出的测试用例

Running

运行方式

bash

undefined

bash

undefined

Render a formula from JSON

从JSON文件渲染formula

just template-formula path/to/formula.json

Run all tests

运行所有测试

just test

undefined

just test

undefined

Adding a New Language

添加新语言

Add
```
install-<lang>
```
definition to
```
scripts/formula.schema.ts
```
Add language dispatch
```
allOf
```
entry in the
```
formula
```
definition

Create

reference/templates/langs/<lang>.mustache

partial

Add
```
"<lang>"
```
to the
```
language
```
enum
Add a test fixture in
```
test/data/
```
and test case in
```
test/cases/
```

在
```
scripts/formula.schema.ts
```
中添加
```
install-<lang>
```
定义
在
```
formula
```
定义中添加语言分发的
```
allOf
```
条目

创建

reference/templates/langs/<lang>.mustache

部分模板

在
```
language
```
枚举中添加
```
"<lang>"
```
在
```
test/data/
```
中添加测试用例数据，在
```
test/cases/
```
中添加测试用例

Research Phase

调研阶段

Before creating a formula, gather this information:

Field	How to Find
Latest version	`gh api repos/owner/repo/releases/latest --jq '.tag_name'` (404 → HEAD-only)
License	Check LICENSE file or repo metadata (use SPDX identifier)
Build system	Look at Makefile, go.mod, Cargo.toml, pyproject.toml, etc.
Dependencies	Check build docs, CI files, or dependency manifests
Default branch	Check repo settings — may be `main` or `master`
Binary name	May differ from formula name — check Cargo.toml `[[bin]]` , Go `cmd/` , or pyproject.toml `[project.scripts]`

在创建formula之前，需要收集以下信息：

字段	获取方式
最新版本	`gh api repos/owner/repo/releases/latest --jq '.tag_name'` （返回404则为仅HEAD版本）
许可证	查看LICENSE文件或仓库元数据（使用SPDX标识符）
构建系统	查看Makefile、go.mod、Cargo.toml、pyproject.toml等文件
依赖项	查看构建文档、CI文件或依赖清单
默认分支	查看仓库设置——可能是 `main` 或 `master`
二进制文件名	可能与formula名称不同——查看Cargo.toml的 `[[bin]]` 、Go的 `cmd/` 目录，或pyproject.toml的 `[project.scripts]`

Determine Formula Type

确定Formula类型

Scenario	Type	Has `url` / `sha256` ?	Has `livecheck` ?
Tagged releases	Standard	Yes	Yes
No releases	HEAD-only	No	No
Monorepo subdirectory	Standard	Yes	Yes

场景	类型	是否包含 `url` / `sha256` ？	是否包含 `livecheck` ？
带标签的版本	标准类型	是	是
无正式版本	仅HEAD版本	否	否
单体仓库的子目录	标准类型	是	是

Calculate SHA256

计算SHA256值

bash

curl -sL "https://github.com/owner/repo/archive/refs/tags/vX.Y.Z.tar.gz" | shasum -a 256

bash

curl -sL "https://github.com/owner/repo/archive/refs/tags/vX.Y.Z.tar.gz" | shasum -a 256

Formula Naming

Formula命名规则

Formula name: kebab-case (
```
hex-patch
```
,
```
jwt-ui
```
)
Class name: PascalCase (
```
HexPatch
```
,
```
JwtUi
```
)

Formula名称：短横线分隔小写（kebab-case）（例如
```
hex-patch
```
、
```
jwt-ui
```
）
类名：大驼峰式（PascalCase）（例如
```
HexPatch
```
、
```
JwtUi
```
）

Formula Structure

Formula结构

File Location

文件位置

Formulas are organized alphabetically:

Formula/<first-letter>/<name>.rb

Formula按字母顺序组织：

Formula/<首字母>/<名称>.rb

Key Elements

核心元素

Element	Purpose
`desc`	Short description (~80 chars) for `brew info`
`homepage`	Project homepage URL
`url`	Source tarball URL (omit for HEAD-only)
`sha256`	Checksum (omit for HEAD-only)
`license`	SPDX identifier
`head`	Git URL for `--HEAD` installs
`livecheck`	Auto-detect new versions (omit for HEAD-only)
`depends_on`	Build or runtime dependencies
`test`	Verification block

元素	用途
`desc`	简短描述（约80字符），用于 `brew info` 命令输出
`homepage`	项目主页URL
`url`	源码压缩包URL（仅HEAD版本可省略）
`sha256`	校验和（仅HEAD版本可省略）
`license`	SPDX标识符
`head`	用于 `--HEAD` 安装的Git URL
`livecheck`	自动检测新版本（仅HEAD版本可省略）
`depends_on`	构建或运行时依赖项
`test`	验证代码块

SPDX License Identifiers

SPDX许可证标识符

License	SPDX
MIT	`"MIT"`
Apache 2.0	`"Apache-2.0"`
GPL 3.0 (only)	`"GPL-3.0-only"`
GPL 3.0 (or later)	`"GPL-3.0-or-later"`
BSD 2-Clause	`"BSD-2-Clause"`
BSD 3-Clause	`"BSD-3-Clause"`

Always specify

-only

-or-later

for GPL/LGPL/AGPL.

许可证	SPDX标识符
MIT	`"MIT"`
Apache 2.0	`"Apache-2.0"`
GPL 3.0（仅）	`"GPL-3.0-only"`
GPL 3.0（或更新版本）	`"GPL-3.0-or-later"`
BSD 2-Clause	`"BSD-2-Clause"`
BSD 3-Clause	`"BSD-3-Clause"`

对于GPL/LGPL/AGPL许可证，必须指定

-only

或

-or-later

。

Language-Specific Patterns

特定语言的模式

Each language has a reference doc with install patterns, schema fields, and common issues:

Go:
```
reference/langs/go.md
```
Rust:
```
reference/langs/rust.md
```
Python:
```
reference/langs/python.md
```

Additional languages supported by the template pipeline (cmake, autotools, meson, zig) — see their Mustache partials in

reference/templates/langs/

每种语言都有对应的参考文档，包含安装模式、Schema字段和常见问题：

Go:
```
reference/langs/go.md
```
Rust:
```
reference/langs/rust.md
```
Python:
```
reference/langs/python.md
```

模板流水线还支持其他语言（cmake、autotools、meson、zig）——可查看

reference/templates/langs/

中的Mustache部分模板。

Reference Materials

参考资料

Topic	Location
Local validation steps	`reference/checklists/local-validation.md`
Common issues & FAQ	`reference/faq/common.md`
Test block patterns	`reference/testing/patterns.md`
Generated formula examples	`reference/templates/formulas/*.rb`
JSON Schema definition	`scripts/formula.schema.ts`
Bottle attestation & provenance	`reference/security/attestation.md`

主题	位置
本地验证步骤	`reference/checklists/local-validation.md`
常见问题与FAQ	`reference/faq/common.md`
测试代码块模式	`reference/testing/patterns.md`
生成的formula示例	`reference/templates/formulas/*.rb`
JSON Schema定义	`scripts/formula.schema.ts`
Bottle认证与溯源	`reference/security/attestation.md`

Batch Formula Creation

批量创建Formula

When creating many formulas at once:

Compute SHA256 hashes in parallel — launch multiple
```
curl | shasum
```
calls concurrently
Research build details in parallel — check build manifests concurrently
Write all formula files — no dependencies between them
Create branches/PRs sequentially — one branch per formula, each from main
Use
ruby -c *.rb
to syntax-check all formulas before pushing

当需要批量创建多个formula时：

并行计算SHA256哈希值——同时启动多个
```
curl | shasum
```
命令
并行调研构建细节——同时检查多个构建清单
编写所有formula文件——文件之间无依赖关系
按顺序创建分支/PR——每个formula对应一个分支，均基于main分支创建
**使用
```
ruby -c *.rb
```
**在推送前语法检查所有formula

Architecture-Specific Binaries

特定架构的二进制文件

When a project provides pre-built binaries for different architectures:

Preferred: Build from source (avoids architecture complexity)

If pre-built binaries required: Use resource blocks, NOT url/sha256 in on_arm/on_intel:

ruby

on_arm do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-arm64.tar.gz"
    sha256 "..."
  end
end

on_intel do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-amd64.tar.gz"
    sha256 "..."
  end
end

def install
  resource("binary").stage do
    bin.install "tool"
  end
end

See

reference/faq/common.md

for details on deprecated patterns.

当项目为不同架构提供预编译二进制文件时：

首选方式： 从源码构建（避免架构复杂性）

如果必须使用预编译二进制文件： 使用resource块，不要在on_arm/on_intel中使用url/sha256：

ruby

on_arm do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-arm64.tar.gz"
    sha256 "..."
  end
end

on_intel do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-amd64.tar.gz"
    sha256 "..."
  end
end

def install
  resource("binary").stage do
    bin.install "tool"
  end
end

关于已弃用的模式，可查看

reference/faq/common.md

获取详情。

Checklist

检查清单

Research complete (version, license, build system, deps, binary name, default branch)
Formula type determined (standard vs HEAD-only)
SHA256 calculated (if not HEAD-only)
Formula file created at
```
Formula/<letter>/<name>.rb
```
```
ruby -c
```
passes (syntax check)
```
brew audit --new
```
passes
```
brew style
```
passes (or issues addressed)
```
brew install --build-from-source
```
succeeds
```
brew test
```
passes
Binary executes correctly
PR created with CI passing

调研完成（版本、许可证、构建系统、依赖项、二进制文件名、默认分支）
确定Formula类型（标准类型 vs 仅HEAD版本）
计算SHA256值（非仅HEAD版本）
在
```
Formula/<首字母>/<名称>.rb
```
路径下创建Formula文件
```
ruby -c
```
语法检查通过
```
brew audit --new
```
检查通过
```
brew style
```
检查通过（或已处理相关问题）
```
brew install --build-from-source
```
安装成功
```
brew test
```
测试通过
二进制文件可正常执行
创建PR且CI检查通过

pkgmgr-homebrew-formula-dev

Original

Translation

Homebrew Formula Development

Homebrew Formula开发

When to Use This Skill

何时使用本技能

Template Pipeline

模板流水线

Workflow

工作流程

Key Files

关键文件

Running

运行方式

Render a formula from JSON

从JSON文件渲染formula

Run all tests

运行所有测试

Adding a New Language

添加新语言

Research Phase

调研阶段

Determine Formula Type

确定Formula类型

Calculate SHA256

计算SHA256值

Formula Naming

Formula命名规则

Formula Structure

Formula结构

File Location

文件位置

Key Elements

核心元素

SPDX License Identifiers

SPDX许可证标识符

Language-Specific Patterns

特定语言的模式

Reference Materials

参考资料

Batch Formula Creation

批量创建Formula

Architecture-Specific Binaries

特定架构的二进制文件

Checklist

检查清单

References

参考链接