homebrew-cask-authoring

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Homebrew Cask Authoring

Homebrew Cask 编写指南

Author and maintain Homebrew Casks with correct token naming, stanzas, audit/style compliance, and local install testing.

编写并维护符合令牌命名规范、正确使用代码块、通过审计/风格检查，且可进行本地安装测试的Homebrew Casks。

Operating rules

操作规则

Prefer the official Homebrew documentation (Cask Cookbook, Acceptable Casks) when uncertain.
Keep casks minimal: only add stanzas that are required for correct install/uninstall/cleanup.
Avoid destructive system changes unless explicitly requested; call out any
```
rm
```
/tap changes before suggesting them.
When testing local casks, ensure Homebrew reads from the local file (not the API).

不确定时优先参考官方Homebrew文档（Cask Cookbook、Acceptable Casks）。
保持cask精简：仅添加安装/卸载/清理所需的必要代码块。
除非明确要求，否则避免进行破坏性系统更改；在建议执行
```
rm
```
或tap更改前需提前说明。
测试本地cask时，确保Homebrew读取本地文件（而非API）。

Quick intake (ask these first)

快速收集信息（先询问这些内容）

Collect:

App name (exact
```
.app
```
bundle name)
Homepage (official)
Download URL(s) (DMG/ZIP/PKG) and whether they differ by arch
Version scheme (single version? per-arch?)
Install artifact type (
```
app
```
,
```
pkg
```
,
```
suite
```
, etc.)
Uninstall requirements (pkgutil ids, launch agents, kernel extensions)
Desired cleanup (zap paths)

If any of these are unknown, propose a short plan to discover them.

收集以下信息：

应用名称（精确的
```
.app
```
包名称）
官方主页
下载URL（DMG/ZIP/PKG格式），以及是否因架构不同而存在差异
版本方案（单一版本？分架构版本？）
安装产物类型（
```
app
```
、
```
pkg
```
、
```
suite
```
等）
卸载要求（pkgutil标识符、launch agents、内核扩展）
所需的清理操作（zap路径）

若有信息未知，提出简短的探索计划。

Workflow: create or update a cask

工作流：创建或更新cask

1) Choose the token

1) 选择令牌

Start from the
```
.app
```
bundle name.
Remove
```
.app
```
and common suffixes: “App”, “Mac”, “Desktop”, “for macOS”, version numbers.
Downcase; replace spaces/underscores with hyphens.
Remove non-alphanumerics except hyphens.
Use
```
@beta
```
,
```
@nightly
```
, or
```
@<major>
```
for variants.

Confirm the token before writing the file.

从
```
.app
```
包名称入手。
移除
```
.app
```
及常见后缀：“App”、“Mac”、“Desktop”、“for macOS”、版本号。
转为小写；将空格/下划线替换为连字符。
移除除连字符外的非字母数字字符。
变体版本使用
```
@beta
```
、
```
@nightly
```
或
```
@<major>
```
格式。

在编写文件前确认令牌。

2) Draft a minimal cask

2) 编写精简的cask

Use this canonical structure:

ruby

cask "token" do
  version "1.2.3"
  sha256 "..."

  url "https://example.com/app-#{version}.dmg"
  name "Official App Name"
  desc "Short one-line description"
  homepage "https://example.com"

  app "AppName.app"
end

Rules of thumb:

Prefer
```
https
```
URLs.
Add
```
verified:
```
when download host domain differs from
```
homepage
```
domain.
Keep
```
desc
```
factual and concise (no marketing).

使用以下标准结构：

ruby

cask "token" do
  version "1.2.3"
  sha256 "..."

  url "https://example.com/app-#{version}.dmg"
  name "Official App Name"
  desc "Short one-line description"
  homepage "https://example.com"

  app "AppName.app"
end

经验法则：

优先使用
```
https
```
URLs。
当下载主机域名与
```
homepage
```
域名不同时，添加
```
verified:
```
字段。
```
desc
```
需真实简洁（不含营销话术）。

3) Handle architecture (if needed)

3) 处理架构差异（若有需要）

If URLs and/or sha256 differ by CPU:

Use
```
arch
```
+
```
sha256 arm: ..., intel: ...
```
when versions match.
Use
```
on_arm
```
/
```
on_intel
```
blocks when versions differ.

若URL和/或sha256因CPU架构不同而存在差异：

当版本一致时，使用
```
arch
```
+
```
sha256 arm: ..., intel: ...
```
格式。
当版本不同时，使用
```
on_arm
```
/
```
on_intel
```
代码块。

4) Add required uninstall/zap

4) 添加必要的卸载/zap配置

Add
```
uninstall
```
for
```
pkg
```
installs (include
```
pkgutil:
```
identifiers).
Add
```
zap
```
for user data cleanup (support directories, preferences, caches), but keep it accurate.

对于
```
pkg
```
安装包，添加
```
uninstall
```
配置（包含
```
pkgutil:
```
标识符）。
添加
```
zap
```
配置以清理用户数据（支持目录、偏好设置、缓存），但需确保配置准确。

5) Validate and test locally

5) 本地验证与测试

Run, in this order:

bash

brew style --fix <token>
brew audit --cask --online <token>

For new casks also run:

bash

brew audit --cask --new <token>
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <token>
brew uninstall --cask <token>

If install fails:

Re-check URL reachability,
```
sha256
```
, and artifact name.
Re-run with verbosity:
```
brew install --cask --verbose <token>
```
.

按以下顺序运行命令：

bash

brew style --fix <token>
brew audit --cask --online <token>

对于新cask，还需运行：

bash

brew audit --cask --new <token>
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --cask <token>
brew uninstall --cask <token>

若安装失败：

重新检查URL可达性、
```
sha256
```
及产物名称。
启用详细模式重新运行：
```
brew install --cask --verbose <token>
```
。

6) PR hygiene

6) PR规范

Before suggesting submission:

Ensure
```
brew style
```
and all relevant
```
brew audit
```
commands pass.
For new casks, check the token has not been previously refused/unmerged.

建议提交前：

确保
```
brew style
```
及所有相关
```
brew audit
```
命令执行通过。
对于新cask，检查令牌是否曾被拒绝/未合并。

Local development patterns

本地开发模式

If the user is editing

Homebrew/homebrew-cask

locally and wants Homebrew to execute their working copy, use a tap symlink workflow.

Read the full end-to-end checklist here:

references/homebrew-cask-contribution-workflow.md

若用户在本地编辑

Homebrew/homebrew-cask

并希望Homebrew使用其工作副本，可使用tap符号链接工作流。

完整的端到端检查清单请参考：

references/homebrew-cask-contribution-workflow.md