[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 < Formuladesc "软件功能描述"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 installbin.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<<~EOSFor 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.confOr add the route of network you want to access to following config file at any time:#{HOMEBREW_PREFIX}/etc/docker-connector.confRoute format is `route subnet`, such as:route 172.17.0.0/16The 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