[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安装。

etc.install "options.conf" => "docker-connector.conf"

如果安装包没有配置文件，为了初始化话配置文件，可以在安装时生成

(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