Homebrew 文件

將軟體加入 Homebrew

您最愛的軟體在 Homebrew 中找不到嗎？那麼您就是解決這個問題的最佳人選。

如果您想加入封閉原始碼軟體或僅有 GUI 的程式，您會想遵循 Casks 指南。否則，請遵循 Formulae 指南（另請參閱：Homebrew 術語）。

在您開始之前，請查看 Homebrew/homebrew-core 或 Homebrew/homebrew-cask 的開放式 pull request，以確保沒有其他人搶先您一步。

接下來，您會想瀏覽 可接受的 Formulae 或 可接受的 Casks 文件，以確定該軟體是否適合加入 Homebrew。如果您正在為 Homebrew 中已有的軟體建立一個替代版本（例如，與現有版本有顯著差異的主要/次要版本），請務必閱讀 版本 文件，以了解版本化 formulae 的需求。

如果一切都檢查完畢，您就可以開始建立新的 formulae 了！

Formulae

撰寫 formulae

1. 建議您在 Homebrew 中尋找與您想加入的軟體有相似之處的現有 formulae。這將有助於您了解特定語言、建置方法等通常是如何處理的。首先點選 homebrew/core：首先在您的 shell 環境中設定 HOMEBREW_NO_INSTALL_FROM_API=1，然後執行 brew tap homebrew/core 將 homebrew/core tap 克隆到 brew --repository homebrew/core 回傳的路徑。

2. 如果您從頭開始，您可以使用 brew create 命令 來產生您的 formulae 的基本版本。此命令接受多個選項，您可能可以使用適當的範本選項（如 --python）來省下一些工作。

3. 現在您必須將 brew create 的樣板程式碼開發成一個完整的 formulae。您的主要參考將會是 Formulae 食譜、Homebrew 中類似的 formulae，以及您選擇的軟體的上游文件。如果您適用，請務必注意 Homebrew 文件，以撰寫 Python 和 Node formulae。

4. 請務必在您的 formulae 中撰寫一個好的測試。請參閱食譜中的 將測試加入 formulae 部分，以取得這方面的說明。

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 使用者受益。

Casks

注意：在花時間製作新的 cask 之前

• 請務必查看 已拒絕的 Casks 常見問題解答，以確認它可以被接受，並且
• 檢查 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

為 Cask 產生權杖

Cask 權杖 是助記字串，人們將使用它透過 brew install 等方式與 Cask 互動。Cask 檔案 的名稱只是權杖加上附檔名 .rb。

為 Cask 產生權杖最簡單的方式是執行 generate_cask_token

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

如果您想要為其建立 Cask 的軟體未安裝，或沒有相關聯的 App 捆綁，請提供軟體的完整正式名稱，而非路徑名稱

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

如果 generate_cask_token 腳本對您不起作用，請參閱 Cask 權杖詳細資料。

建立 Cask 檔案

一旦您知道權杖，請使用 brew create --cask 指令建立您的 Cask

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

這將開啟 EDITOR，其中包含您新 Cask 的範本，儲存在檔案 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，您將在您的 pull request 中使用它

$ 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 上 pull request 的標題，就像電子郵件的主旨行一樣。在第一行包含關鍵資訊將有助於我們更快回應您的 pull request。

對於 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 上提交 pull request

a) 使用 git push 的建議

git push 指令會列印建議，說明如何建立 pull request

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 分支，並提供一個方便的按鈕，用於 比較並建立 pull request。

c) 手動在 GitHub 上建立 pull request

否則，按一下 貢獻 > 開啟 pull request 按鈕，並選擇 跨分支比較。基礎分支應該是 Homebrew/homebrew-cask @ master，而目標分支應該是 my-github-username/homebrew-cask @ my-new-cask-branch。您也可以在此階段為 pull request 新增任何進一步的意見。

恭喜！

您現在已經完成了，您的 cask 應該會在不久後被拉取或以其他方式被注意到。如果維護人員建議進行一些變更，請在 my-new-cask-branch 分支上進行變更，並 推播。

清理

在提交 pull request 後，您應該回到 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