[brew|Mac]如何将軟體釋出到Homebrew

開發了一個用于

macOS

的工具軟體，如何友善使用者進行安裝呢？在

macOS

上比較常用的安裝管理工具是brew。以我最近開發的一個用于打通

macOS

和

docker

容器網絡的工具用戶端docker-connector為例，說明如何讓軟體可以通過

brew install

安裝。

準備軟體

要通過

brew

進行安裝，需要提供軟體下載下傳位址，下載下傳的可以是源碼，也可以是編譯好的可執行檔案的tar包。我使用了編譯好的可執行檔案，打成tar包，并且生成SHA256。

$ tar -czf docker-connector-mac.tar.gz docker-connector
$ shasum -a 256 docker-connector-mac.tar.gz | awk '{print $1}' > docker-connector-mac-sha256.txt
           

把編譯好的可執行檔案打包之後上傳到

Github

的

Releases

中（也可以放到任何能夠公共通路的地方），上傳之後可以擷取下載下傳連結，後續會用到。

https://github.com/wenjunxiao/mac-docker-connector/releases/download/v1.0/docker-connector-mac.tar.gz

準備tap倉庫

Homebrew除了核心倉庫之外，還支援第三方倉庫，如何送出到核心倉庫，可以檢視官方文檔。前期為了友善測試和及時更新，準備自己的第三方倉庫。在

Github

建立一個倉庫，倉庫的名稱必須是

homebrew-

開頭，後面的名稱自定義，安裝的時候需要指定該名稱，我把倉庫命名為homebrew-brew，語言選擇

Ruby

。克隆到本地之後建立

$ git clone https://github.com/wenjunxiao/homebrew-brew
$ cd homebrew-brew
$ mkdir Formula
           

後續需要送出軟體隻需要在

Formula

增加一個

Ruby

檔案即可。

準備

Formula

每個軟體對應一個

Formula

檔案，該檔案使用

Ruby

語言，以docker-connector.rb為例，分析一下如何編寫。

最基本的結構如下

class DockerConnector < Formula
  desc "軟體功能描述"
  homepage "https://github.com/wenjunxiao/mac-docker-connector"
  url "https://github.com/wenjunxiao/mac-docker-connector/releases/download/v1.0/docker-connector-mac.tar.gz"
  sha256 "....."
  version "1.0"
  def install
    bin.install "docker-connector"
  end
end
           

第一行

class DockerConnector < Formula

定了一個

Ruby

的類繼承自

Formula

，類的名稱可以自定義。必須

end

結尾

desc

屬性

desc

是軟體的功能描述

homepage

屬性

homepage

是軟體的首頁位址

url

屬性

url

是軟體的下載下傳位址，用前面準備的下載下傳位址

sha256

屬性

sha256

是軟體包的

SHA256

用于驗證軟體包的

version

屬性

version

是指定軟體版本

install

方法

接下來

def install

是定義了安裝行為的方法，必須用

end

結尾。

bin.install

bin.install

是安裝可執行檔案，後面跟的是軟體包中的可執行檔案，軟體通常會安裝(或連結)到

/usr/local/bin/

目錄。如果安裝包中的的名稱與安裝之後名稱不一緻，可以使用

=>

重新指定，比如，把名稱

a

修改為

b

bin.install "a" => "b"
           

這是最簡單的安裝單個可執行檔案。

etc.install

如果還有配置檔案可以通過

etc.install

安裝。

如果安裝包沒有配置檔案，為了初始化話配置檔案，可以在安裝時生成

(buildpath/"options.conf").write <<~EOS
  # addr 192.168.251.1/24
  # mtu 1400
  # host 127.0.0.1
  # port 2511
  # route 172.17.0.0/16
EOS
etc.install "options.conf" => "docker-connector.conf"
           

以上的代碼是在建構目錄

buildpath

下生成一個

options.conf

的檔案，寫入檔案的内容是

EOS

擴起來的内容

# addr 192.168.251.1/24
# mtu 1400
# host 127.0.0.1
# port 2511
# route 172.17.0.0/16
           

同樣上面由于配置檔案名與最終安裝的配置檔案名不一樣是以使用

=>

重命名了，也可以生成的時候就使用相同的名稱。

(buildpath/"docker-connector.conf").write <<~EOS
EOS
etc.install "docker-connector.conf"
           

plist

方法

除了安裝軟體之外，還可以安裝對應的服務，以便通過服務管理

plist

方法定義了生成

macOS

服務的

plist

内容。

def plist
  <<~EOS
    <?xml version="1.0" encoding="UTF-8"?>
    <!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
    <plist version="1.0">
      <dict>
        <key>KeepAlive</key>
        <dict>
          <key>SuccessfulExit</key>
          <false/>
        </dict>
        <key>Label</key>
        <string>#{plist_name}</string>
        <key>ProgramArguments</key>
        <array>
          <string>#{opt_bin}/docker-connector</string>
          <string>-config</string>
          <string>#{etc}/docker-connector.conf</string>
        </array>
        <key>RunAtLoad</key>
        <true/>
        <key>WorkingDirectory</key>
        <string>#{var}</string>
        <key>StandardErrorPath</key>
        <string>#{var}/log/docker-connector.log</string>
        <key>StandardOutPath</key>
        <string>#{var}/log/docker-connector.log</string>
      </dict>
    </plist>
  EOS
end
           

其中

ProgramArguments

後的數組中配置了運作服務的指令，

#{opt_bin}

是安裝軟體的目錄，

#{etc}

是配置檔案的安裝位置，這些都是安裝時的變量，安裝完成之後會被替換成具體的值。

StandardErrorPath

和

StandardOutPath

分别表示軟體運作的标準錯誤和标準輸出的日志檔案。

caveats

方法

def caveats

方法中定義了安裝完成之後輸出的提示資訊，用于引導使用者執行正确的操作，系統會有預設的提示資訊，也可以添加額外的提示資訊，比如使用者該執行什麼操作來完善配置等

def caveats
  <<~EOS
  For the first time, you can add all the bridge networks of docker to the routing table by the following command:
    docker network ls --filter driver=bridge --format "{{.ID}}" | xargs docker network inspect --format "route {{range .IPAM.Config}}{{.Subnet}}{{end}}" >> #{HOMEBREW_PREFIX}/etc/docker-connector.conf
  Or add the route of network you want to access to following config file at any time:
    #{HOMEBREW_PREFIX}/etc/docker-connector.conf
  Route format is `route subnet`, such as:
    route 172.17.0.0/16
  The route modification will take effect immediately without restarting the service.
  EOS
end
           

安裝軟體

把

Formula

送出之後就可以在

macOS

執行

brew install

了，由于是第三方的，是以首次安裝之前需要下載下傳倉庫，下載下傳時指定使用者名和倉庫名(不需要

homebrew-

)

$ brew tap wenjunxiao/brew
           

執行安裝安裝

$ brew install docker-connector
           

也可以通過一個指令進行安裝(如果和其他倉庫有重名時也可以通過該指令安裝)

$ brew install wenjunxiao/brew/docker-connector