将项目发布到 homebrew 官方仓库

最近将 kubecm 推到了官方 homebrew-core 仓库,分享一下经验。

作者 guoxudong 发表于 2020年12月3日 更新于 2023年11月25日

前言

Homebrew 标榜自己是 “macOS(或 Linux)缺失的软件包的管理器”,使用 macOS 作为开发终端的用户,往往绕不过 brew 这个软件包管理工具。确实在 macOS 上没有比 brew 更好用的软件包管理工具了,基本上想用的 CLI 工具,只需一行命令就可一键安装,非常的方便。记得去年博主还写过一篇 《Golang 装逼指南 Ⅱ:在 Homwebrew 上发布 Golang 项目》,当时只是介绍了如何将 Golang 开发的 CLI 工具发布到自建的 homebrew-tap 上。本文则是讲解如何将自己开发的软件,推送到官方的 homebrew-core 仓库中,使用像 brew install kubecm 这样的命令即可完成安装。

Homebrew-core

homebrew-core 中存储着所有官方的安装脚本,而这些安装脚本都是由软件开发者自己提交 PR 合并到仓库中的。同时 homebrew 也提供了查询页面,用户可以在网页 Homebrew Formulae 上查询自己的软件总共被下载安装了多少次,如下:

kubecm

新的项目只需向这个仓库提交 PR 即可。

准备阶段

首先需要在 GitHub 上 fork homebrew-core 项目。

然后在本地找到保存 homebrew-core 的目录:

$ cd $(brew --repository homebrew/core)

新增 remote 地址为 fork 仓库的地址:

$ git remote add <YOUR_USERNAME> https://github.com/<YOUR_USERNAME>/homebrew-core.git

这里的 YOUR_USERNAME 是 GitHub username。

新建分支

这里的操作就和向开源项目提交 PR 一样,新建 branch 并创建安装脚本。

$ git checkout master

更新 master 分支

$ brew update

从最新的 master 分支创建新 branch

$ git checkout -b <YOUR_BRANCH_NAME> origin/master

编写脚本

首先需要使用 brew search <formula> 来查看上游仓库中是否有同名的项目,同时确保你的项目是稳定版且带有 tag(不能只是一个 GitHub repo)。

使用 brew create 创建一个脚本模板,命令如下:

$ brew create https://example.com/foo-0.1.tar.gz

这里的 URL 地址,就是 GitHub Release 页面的 Source code(tar.gz) 的 URL 地址。

打开 Formula/foo.rb 可以看到:

class Foo < Formula
  desc ""
  homepage ""
  url "https://example.com/foo-0.1.tar.gz"
  sha256 "85cc828a96735bdafcf29eb6291ca91bac846579bcef7308536e0c875d6c81d7"
  license ""

  # depends_on "cmake" => :build

  def install
    # ENV.deparallelize
    system "./configure", "--disable-debug",
                          "--disable-dependency-tracking",
                          "--disable-silent-rules",
                          "--prefix=#{prefix}"
    # system "cmake", ".", *std_cmake_args
    system "make", "install"
  end

  test do
    system "false"
  end
end

之后就是完善这个脚本,deschomepagelicense 都请根据项目情况填写。

如果是 Golang 项目,则需要添加 Go 依赖 depends_on "go" => :build,同时在 install 中完善安装脚本,golang 开发的项目一般都是使用 go build 来构建。

这里附上一份 kind 的脚本供大家参考:

class Kind < Formula
  desc "Run local Kubernetes cluster in Docker"
  homepage "https://kind.sigs.k8s.io/"
  url "https://github.com/kubernetes-sigs/kind/archive/v0.9.0.tar.gz"
  sha256 "c154289659a7ef30b301a0787ecfa2e08edaada6059bf5acefe9f3be1e026381"
  license "Apache-2.0"
  head "https://github.com/kubernetes-sigs/kind.git"

  bottle do
    cellar :any_skip_relocation
    rebuild 1
    sha256 "e40a2343bf999585fa4fcb1a1e9b801427e921c098fc3f7e3026c071a0e72520" => :big_sur
    sha256 "e5ba99b5f14711e0dcb121a992d74c5ee6c6b0468b27e5200bf796d4987e13c0" => :catalina
    sha256 "d52a780ad6af93a2a7c480a41c5178a461b9966ddc1adb66adde8ff3bce15238" => :mojave
    sha256 "423ea750ae8589d1a199847f746d8e9b5b1f1d81ceff3a9dab2d63f161532588" => :high_sierra
  end

  depends_on "go" => :build

  def install
    system "go", "build", "-o", bin/"kind"
    prefix.install_metafiles

    # Install bash completion
    output = Utils.safe_popen_read("#{bin}/kind", "completion", "bash")
    (bash_completion/"kind").write output

    # Install zsh completion
    output = Utils.safe_popen_read("#{bin}/kind", "completion", "zsh")
    (zsh_completion/"_kind").write output

    # Install fish completion
    output = Utils.safe_popen_read("#{bin}/kind", "completion", "fish")
    (fish_completion/"kind.fish").write output
  end

  test do
    # Should error out as creating a kind cluster requires root
    status_output = shell_output("#{bin}/kind get kubeconfig --name homebrew 2>&1", 1)
    assert_match "failed to list clusters", status_output
  end
end

更多内容见官方文档

检测脚本

在脚本完成后,请先进行如下测试,确保测试通过且无任何报错。

$ brew tests
$ brew install --build-from-source <CHANGED_FORMULA>
$ brew test <CHANGED_FORMULA>
$ brew audit --strict <CHANGED_FORMULA>

提交代码

在通过所有测试后,就可以提交代码了,需要对每个更改单独提交 PR,且 commit 有格式要求,一般为 <FORMULA_NAME> <NEW_VERSION>kbecm 0.10.3

$ git add Formula/foo.rb
$ git commit -m 'foo 0.0.1'
$ git push --set-upstream <YOUR_USERNAME> <YOUR_BRANCH_NAME>

在这里提交后,代码就会 push 到之前 fork 的 homebrew/core 项目。

提交 PR

之后就可以在 GitHub 页面操作提交 PR 了。项目维护者的响应还是很及时的,在 PR 通过所有 CI test 后,就会有维护者进行 review 并指出需要修改的地方,根据要求修复即可。

提交 PR

提交新版本

PR 合并成功后,如果要发布新版本,这里推荐两种方式提交新版本。

CLI

brew 提供了十分简单的方式自动创建 PR,命令如下:

$ brew bump-formula-pr --url https://example.com/foo-0.1.tar.gz

更多的信息可以通过 brew bump-formula-pr --help 查看。

GitHub action

这一步也可以在 GitHub action 中自动完成,使用 homebrew-bump-formula 插件。原理其实也是使用了 brew bump-formula-pr,但是这样就无需手动触发,可以集成到 Release 的 CI 中。

name: Bump Homebrew kubecm formula

on:
  push:
    tags: 'v*'

jobs:
  homebrew:
    runs-on: ubuntu-latest

    steps:
      - name: Update Homebrew formula
        uses: dawidd6/action-homebrew-bump-formula@v3
        with:
          # GitHub token, required, not the default one
          token: ${{secrets.TOKEN}}
          # Optional, defaults to homebrew/core
          tap: USER/REPO
          # Formula name, required
          formula: FORMULA
          # Optional, will be determined automatically
          tag: ${{github.ref}}
          # Optional, will be determined automatically
          revision: ${{github.sha}}
          # Optional, if don't want to check for already open PRs
          force: false # true

结语

总的来说,这一套流程都比较简单,笔者也只是在 GitHub action 的 TOKEN 上浪费了一些时间。使用 brew 不但简化了安装步骤,提升了用户体验,还可以把诸如 completion 命令生成的自动补全脚本在安装时就注入到系统中,无需在装好后再进行其他操作,体验极佳。