Homebrew 文档

向 Homebrew 添加软件

您最喜欢的软件在 Homebrew 中缺失吗？那么您就是解决此问题的不二人选。

如果您想添加闭源软件或仅限 GUI 的程序，您需要按照 Casks 的指南进行操作。否则，请按照 Formulae 的指南进行操作（另请参阅：Homebrew 术语）。

在开始之前，请检查 Homebrew/homebrew-core 或 Homebrew/homebrew-cask 的开放拉取请求，以确保没有其他人抢先一步。

接下来，您需要通读 可接受的 Formulae 或 可接受的 Casks 文档，以确定该软件是否适合添加到 Homebrew 中。如果您正在为 Homebrew 中已有的软件的备用版本（例如与现有版本有显著差异的主要/次要版本）创建公式，请务必阅读 版本 文档，以了解版本化公式的要求。

如果一切正常，您就可以开始着手编写新公式了！

Formulae

编写公式

1. 最好在 Homebrew 中找到与您要添加的软件类似的现有公式。这将帮助您了解通常如何处理特定语言、构建方法等。首先点击 homebrew/core：首先在您的 shell 环境中设置 HOMEBREW_NO_INSTALL_FROM_API=1，然后运行 brew tap homebrew/core 将 homebrew/core tap 克隆到 brew --repository homebrew/core 返回的路径。

2. 如果您从头开始，可以使用 brew create 命令 生成公式的基本版本。此命令接受许多选项，您可以通过使用适当的模板选项（如 --python）来节省一些工作。

3. 现在，您必须将 brew create 中的样板代码开发为一个成熟的公式。您的主要参考将是 Formula Cookbook、Homebrew 中类似的公式以及您所选软件的上游文档。如果适用，请务必注意 Homebrew 的文档，了解如何编写 Python 和 Node 公式。

4. 确保在公式中编写一个好的测试。有关这方面的帮助，请参阅 Cookbook 中的 向公式添加测试 部分。

5. 尝试使用 brew install --build-from-source <formula> 安装您的公式，其中 <formula> 是您的公式的名称。如果出现任何错误，请更正您的公式并尝试再次安装。在本步骤结束时，公式安装应顺利完成，不会出现任何错误。

如果您遇到困难，请在 GitHub 或 Homebrew 讨论论坛 上寻求帮助。维护人员非常乐于提供帮助，但我们也希望看到您已尽力尝试找到解决方案。

测试和审核公式

1. 使用 brew audit --strict --new --online <formula> 对您的公式运行。如果出现任何错误，请更正您的公式并再次运行审核。在本步骤结束时，审核应顺利完成，不会出现任何错误。

2. 使用 brew test <formula> 运行您的公式测试。测试应顺利完成，不会出现任何错误。

提交公式

您终于可以将您的公式提交到 homebrew-core 存储库了。如果您之前没有这样做过，可以参考 如何打开 Homebrew Pull Request 文档获取帮助。维护人员将审查 Pull Request 并提供有关在将公式添加到 Homebrew 之前需要解决的任何领域的反馈。

如果您已经完成了这些步骤，恭喜您提交了 Homebrew 公式！我们感谢您为此付出的辛勤工作，并且您可以满意地知道您的工作也可能使其他 Homebrew 用户受益。

Cask

注意：在花时间制作新 Cask 之前

• 请务必查看 被拒绝的 Cask 常见问题解答 以确保它可以被接受，以及
• 检查 Cask 是否 尚未被拒绝。

编写 Cask

制作新 Cask 非常容易。按照 如何打开 Homebrew Pull Request 中的说明开始操作。

示例

以下是一个 dixa Cask 示例。请注意 url 下方的 verified 参数，当 url 和主页主机名不同 时需要此参数。

cask "dixa" do
  version "4.0.12"
  sha256 "a4e1a30d074e724ba24e9e2674a72bc4050f00161fb7dc23295a2c189ecda5bb"

  url "https://github.com/dixahq/dixa-desktop-app-release/releases/download/v#{version}/dixa-#{version}.dmg",
      verified: "github.com/dixahq/dixa-desktop-app-release/"
  name "Dixa"
  desc "Customer service platform"
  homepage "https://dixa.com/"

  livecheck do
    url :url
    strategy :github_latest
  end

  app "Dixa.app"

  zap trash: [
    "~/Library/Application Support/Dixa",
    "~/Library/Logs/Dixa",
    "~/Library/Preferences/dixa.plist",
    "~/Library/Saved Application State/dixa.savedState",
  ]
end

这里有一个 pomello 的例子。请注意，它有一个未版本化的下载（下载 url 不包含版本号，与上面的示例不同）。它还使用 sha256 :no_check 禁止校验和，这是必需的，因为由于下载 url 不包含版本号，所以当新版本可用时，其校验和将更改。

cask "pomello" do
  version "0.10.17"
  sha256 :no_check

  url "https://pomelloapp.com/download/mac/latest"
  name "Pomello"
  desc "Turns your Trello cards into Pomodoro tasks"
  homepage "https://pomelloapp.com/"

  livecheck do
    url :url
    strategy :header_match
  end

  app "Pomello.app"

  zap trash: [
    "~/Library/Application Support/com.apple.sharedfilelist/com.apple.LSSharedFileList.ApplicationRecentDocuments/com.tinynudge.pomello.*",
    "~/Library/Application Support/Pomello",
    "~/Library/Caches/com.tinynudge.pomello",
    "~/Library/Caches/com.tinynudge.pomello.ShipIt",
    "~/Library/HTTPStorages/com.tinynudge.pomello",
    "~/Library/Preferences/com.tinynudge.pomello.plist",
    "~/Library/Saved Application State/com.tinynudge.pomello.savedState",
  ]
end

这是 fabfilter-one 的最后一个示例，它使用 pkg 安装程序安装应用程序，而不是独立的应用程序包 (.app)。请注意 uninstall pkgutil 节，这是卸载使用安装程序安装的所有文件所必需的。

您还将看到如何将 version 调整到下载 url。使用 我们的自定义 version 方法 来执行此操作，当它们不足时，求助于标准 Ruby 字符串方法。

cask "fabfilter-one" do
  version "3.37"
  sha256 "4059594580e365237ded16a213d8d549cbb01c4b8bad80895c61f44bcff7eb68"

  url "https://download.fabfilter.com/ffone#{version.no_dots}.dmg"
  name "FabFilter One"
  desc "Synthesizer plug-in"
  homepage "https://www.fabfilter.com/products/volcano-2-powerful-filter-plug-in"

  livecheck do
    url "https://www.fabfilter.com/download"
    strategy :page_match do |page|
      match = page.match(/ffone(\d)(\d+)\.dmg/i)
      next if match.blank?

      "#{match[1]}.#{match[2]}"
    end
  end

  depends_on macos: ">= :sierra"

  pkg "FabFilter One #{version} Installer.pkg"

  uninstall pkgutil: "com.fabfilter.One.#{version.major}"

  # No zap stanza required
end

为木桶生成令牌

木桶令牌是人们将通过 brew install 等与木桶交互时使用的助记字符串。木桶文件的名称只是令牌，后面附加了扩展名 .rb。

为木桶生成令牌的最简单方法是运行 generate_cask_token

$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "/full/path/to/new/software.app"

如果您要为其创建木桶的软件未安装，或没有关联的应用程序包，只需提供软件的完整正式名称，而不是路径名

$(brew --repository homebrew/cask)/developer/bin/generate_cask_token "Google Chrome"

如果 generate_cask_token 脚本对您不起作用，请参阅 木桶令牌详细信息。

创建木桶文件

一旦您知道了令牌，就使用 brew create --cask 命令创建您的木桶

brew create --cask download-url --set-name my-new-cask

这将使用新木桶的模板打开 EDITOR，将其存储在文件 my-new-cask.rb 中。

Cask 节

为你的 cask 填写以下节

其他常用的节是

对于特殊用例，可能需要其他 artifact 节段。更多特殊用途的节段列在 可选节段 中。

Cask 令牌详细信息

如果令牌与已存在的 cask 冲突，作者应通过添加供应商名称手动使新令牌唯一。示例：unison.rb 和 panic-unison.rb。

如果可能，避免创建仅在连字符位置不同的令牌。

要手动生成令牌，或了解针对异常情况的例外，请参阅 令牌参考。

带子文件夹的存档

当下载的存档扩展到子文件夹时，子文件夹名称必须包含在 app 值中。

示例

1. Simple Floating Clock 下载到文件 sfc.zip。
2. sfc.zip 解压到名为 Simple Floating Clock 的文件夹。
3. 文件夹 Simple Floating Clock 包含应用程序 SimpleFloatingClock.app。

4. 因此，app 节段应将子文件夹作为相对路径包含在内

   app "Simple Floating Clock/SimpleFloatingClock.app"
   

测试和审计 cask

使用以下命令尝试一下

export HOMEBREW_NO_AUTO_UPDATE=1
export HOMEBREW_NO_INSTALL_FROM_API=1
brew install my-new-cask

它是否安装了？如果出现问题，请使用 brew edit my-new-cask 编辑 cask 以修复它。

还测试卸载是否成功

brew uninstall my-new-cask

如果一切看起来都不错，你还需要确保 cask 通过以下命令进行审计

brew audit --new --cask my-new-cask

你还应该使用 brew style 检查文体细节

brew style --fix my-new-cask

请记住，当你提交 PR 时，将进行所有这些检查，因此提前进行这些检查可以为每个人节省大量时间和麻烦。

如果你的应用程序和 Homebrew Cask 无法很好地协同工作，请在查看公开问题后随时 提交问题。

提交 cask

为你的 cask 寻找一个家

请参阅 可接受的 Cask 文档。

进入你的 tap 并检查以确保你的新 cask 存在

$ cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
$ git status
On branch master
Untracked files:
  (use "git add <file>..." to include in what will be committed)
        Casks/m/my-new-cask.rb

到目前为止，一切都好。现在创建一个功能分支 my-new-cask-branch，你将在你的拉取请求中使用它

$ git checkout -b my-new-cask-branch
Switched to a new branch 'my-new-cask-branch'

使用以下命令暂存你的 cask

git add Casks/m/my-new-cask.rb

你可以使用以下命令查看将要提交的更改

git diff --cached

使用以下命令提交你的更改

git commit -v

提交消息

对于任何 Git 项目，一些有关提交消息的良好规则是

• 第一行是提交摘要，少于 50 个字符，
• 后跟一个空行，
• 后跟对提交的解释，换行至 72 个字符。

有关更多信息，请参阅 关于 Git 提交消息的说明。

提交消息的第一行将成为 GitHub 上拉取请求的标题，就像电子邮件的主题行一样。在第一行中包含关键信息将有助于我们更快地响应你的拉取请求。

对于 Homebrew Cask 项目中的 cask 提交，我们希望在第一行中包含应用程序名称、版本号和提交目的。

良好、清晰的提交摘要示例

• transmission 1.0（新 cask）
• transmission 2.82
• transmission：修复校验和
• codebox 最新（新 cask）

困难、不明确的提交摘要示例

• 升级到 v2.82
• 校验和错误

推送

将 my-new-cask-branch 分支上的更改推送到你的 GitHub 帐户

git push  my-new-cask-branch

如果你正在使用 GitHub 双因素身份验证，并且已将你的远程存储库设置为 HTTPS，则需要 设置个人访问令牌，并使用它来代替你的密码。

在 GitHub 上提交拉取请求

a) 使用 git push 的建议

git push 命令打印有关如何创建拉取请求的建议

remote: Create a pull request for 'new-cask-cask' on GitHub by visiting:
remote:      https://github.com//homebrew-cask/pull/new/my-new-cask-branch

b) 使用 GitHub 网站的建议

现在转到 homebrew-cask GitHub 存储库。GitHub 通常会显示你的 my-new-cask-branch 分支，并带有用于 比较和拉取请求 的便捷按钮。

c) 在 GitHub 上手动创建一个拉取请求

否则，单击 贡献 > 打开拉取请求 按钮，然后选择 跨分支比较。基本分支应为 Homebrew/homebrew-cask @ master，而头部分支应为 my-github-username/homebrew-cask @ my-new-cask-branch。你还可以在此阶段向你的拉取请求添加任何进一步的评论。

恭喜！

你现在完成了，你的 cask 应该在一段时间内被拉入或以其他方式被注意到。如果维护者建议进行一些更改，只需在本地 my-new-cask-branch 分支上进行更改并 推送。

清理

提交你的 pull 请求后，你应该回到 master，这样 brew update 才能正确拉取新的 cask

cd "$(brew --repository)"/Library/Taps/homebrew/homebrew-cask
git checkout master

如果你之前设置了变量 HOMEBREW_NO_AUTO_UPDATE 和 HOMEBREW_NO_INSTALL_FROM_API，那么用以下命令清理它

unset HOMEBREW_NO_AUTO_UPDATE
unset HOMEBREW_NO_INSTALL_FROM_API