- HomebrewはmacOSでCLIツールを簡単にインストール・管理できるパッケージマネージャーであり、開発者がよく使うツールを通じてシステム環境を効率よく構成できる
- このガイドではHomebrewを使って個人のCLIスクリプトを配布する流れを説明し、GitHub連携と自動化ワークフローによって保守を簡素化する方法を示す
- 配布プロセスはCLIの作成 → GitHubリリース → Tap作成 → Formula作成と更新という流れで進み、最終的には
brew tapとbrew installコマンドだけでインストールできる
- Homebrewの用語体系とベストプラクティスを理解すれば、再現性とサプライチェーンセキュリティを強化した安定的な配布が可能になる
- GitHub Actionsワークフローで自動化でき、一度設定すればその後ほかのCLIの配布も非常に簡単になる利点がある
背景と動機
- HomebrewはCLIツールのインストール時に好まれるパッケージマネージャーで、多くの開発者に使われている
- しかし、自作CLIはnpmやRubyGemで配布されることが多く、Homebrewでの配布方式は手順がなじみにくく感じられることがある
- Homebrewの公式coreリポジトリでは自作ツールの登録にHomebrewチームが消極的な方針のため、一般開発者は別個のtapとformulaで配布する
- 本ガイドはシンプルなRubyベースCLIの配布経験をもとに説明する
用語説明
- Homebrewはビール醸造テーマを反映した独特の用語を使うため、これを理解するとシステム構造を把握しやすい
- Formulaはパッケージ定義ファイルで、ソースコードやバイナリをインストールするための手順を含む
- TapはFormula群のGitリポジトリで、ユーザー単位または組織単位でカスタムパッケージを管理する
- CaskはGUIアプリや大型バイナリをインストールするためのマニフェストで、Formulaと似ているが事前ビルド済みファイルを扱う
- Bottleはソースからビルドせず事前ビルド済みバイナリパッケージをコピーする形で、インストール速度を高める
- Cellarはインストール済みFormulaが置かれるディレクトリで、たとえば
/opt/homebrew/Cellarというパスを持つ
- Kegは特定Formulaのインストールインスタンス用ディレクトリで、Cellar内にバージョンごとに配置される
概要
- Homebrewのコアリポジトリはニッチなものや個人提出のコンテンツを受け付けないため、ユーザーは別途tapリポジトリを作ってCLIを配布する必要がある
- 1. CLIを作成してGitHubに置き、タグ付きリリースを作る
- 2.
brew tap-newでTapを作成してGitHubにpushする
- 3.
brew createでFormulaを作成する（tarball URLとSHA256を含む）
- 4. 新バージョンをリリースするたびにFormulaを更新し、ユーザーが
brew installコマンドで簡単にインストールできるようにする
- 配布完了後、ユーザーは2つのコマンドでCLIをインストールできる:
brew tap your_github_handle/tap と brew install your_cool_cli
- このガイドではCLI開発そのものは省略し、tap作成、Formula作成、更新手順に焦点を当てる
- 例として、iMessageデータベースからインタラクティブなWebアーカイブを作る
imsg CLIを使う
tapの作成
- Homebrewのtap作成ガイドに従い、GitHubのユーザー名や組織名に置き換えて設定する
- 今後すべてのCLIツールを1つのtapにまとめるため、名前は
homebrew-tapを推奨する。homebrew接頭辞はCLIで特別扱いされ、tap接頭辞は慣習的である
- tap作成コマンドを実行:
brew tap-new searlsco/homebrew-tap
- これにより
/opt/homebrew/Library/Taps/searlsco/homebrew-tapにスキャフォールドが生成される
- 対応するGitHubリポジトリを作成し、生成された内容をpushする:
cd /opt/homebrew/Library/Taps/searlsco/homebrew-tap, git remote add origin git@github.com:searlsco/homebrew-tap.git, git push -u origin main
- tapを所有した後は、ほかのユーザーが
brew tap searlsco/tapコマンドでそのリポジトリをクローンし、/opt/homebrew/Library/Tapsに配置できる
- 初期状態では有用な内容はないが、基本動作は確認できる
Formulaの作成
- HomebrewはGitHubリポジトリを直接参照できるが、バージョン付きtarballとチェックサムの使用を推奨しており、再現性とオープンソースのサプライチェーンセキュリティを強化できる
- Formula作成コマンド:
brew create https://github.com/searlsco/imsg/archive/refs/tags/v0.0.5.tar.gz --tap searlsco/homebrew-tap --set-name imsg --ruby
--tapフラグはカスタムtapを指定し、Formulaを/opt/homebrew/Library/Taps/searlsco/homebrew-tap/Formulaに配置する--set-name imsgはFormula名を明示的に設定するもので、名前の重複を避けるためユニークに選ぶべきである（例: 既存のTLDRやstandard CLIとの衝突に注意）--rubyはRuby CLI向けのテンプレートプリセットで、カスタマイズを簡素化する複数オプションの1つである
- 生成されたFormulaは最初は動かないことがあるため、LLMを活用して修正する:
brew install --verbose imsgを実行し、エラーをChatGPTに入力してFormula更新を繰り返す
- 最終的なFormula/imsg.rbファイルは、Ruby CLI配布の出発点としてコピー可能
- 言語固有のパッケージマネージャーではなくHomebrew経由で配布すれば、実装言語を変更してもユーザーのアップグレードは円滑に行える
Formulaの主なポイント
- すべてのFormulaはRubyで書かれている。これはJavaScriptやAI以前に人気だった開発ツールの多くがRubyベースだったためである
headメソッドでGitリポジトリを指定できるが、実際の効果は不明livecheckを追加するとFormulaのバージョン更新が容易になり、価値がある- バイナリ実行テストはヘルプ出力の確認で簡単に実装でき、生成されたコメントに気後れする必要はない
brew style searlsco/tapコマンドでスタイルエラーを確認できる--rubyテンプレートのデフォルトであるuses_from_macos "ruby"は2.6.10版（COVID以前のリリースで、3年前にEOL）を使うため、depends_on "ruby@3"で最新のruby Formulaへの依存を推奨する
- Formulaに満足できたら
git pushで本番配布し、ユーザーはbrew tap searlsco/tapとbrew install imsgでインストールできる
各CLIリリースごとのFormula更新
- Formula先頭の
urlとsha256ハッシュをリリースごとに手動更新するのは面倒で、タグのpushやGitHubリリース作成ですら負担だと指摘している
- Homebrewの
bump-formula-prコマンドやGitHub ActionsでPRを作ることもできるが、forkとPRのプロセスは不必要に複雑
- tapの所有者であれば、mainブランチへ直接コミットする簡単な方法が望ましい
- これを避けるため、FormulaリポジトリにGitHubワークフローを追加し、リリース時にtapを自動更新することを推奨する
- ワークフロー例をコピーして使える
- 設定が必要: GitHub個人アクセストークン（PAT）を作成する際、
homebrew-tapリポジトリにContent → Write権限を付与し、FormulaリポジトリのSecretsにHOMEBREW_TAP_TOKENとして保存する
- 環境変数でtapとFormulaを指定する（例: 13〜15行目）
- GitHubボットアカウントでの更新を推奨:
GH_EMAIL: 41898282+github-actions[bot]@users.noreply.github.com, GH_NAME: github-actions[bot]
- リリース作成後に
git push --tagsを実行すれば、数秒以内に自動更新され、ユーザーはbrew updateとbrew upgrade imsgでアップグレードできる
いちばん良い点
- このプロセスは複雑だが、tapの設定と1つのFormula例が完成すれば、追加のCLI配布はほぼ些細な作業になる
- Homebrewの公式プロセスはやや複雑だが、自動化によって楽になる
- 各ツールのリリースから配布までの煩雑さを減らし、さまざまな言語のCLIにも拡張して対応できる
- 実際に別のFormulaを公開するかは未定だが、その可能性が開けたことに満足している
まだコメントはありません。