Gembrew

Generate conventional Homebrew formulae for published Ruby command-line gems.

gem install gembrew

See the Bashly Homebrew tap for a real-world tap generated and maintained with Gembrew.

mkdir homebrew-tap
cd homebrew-tap
gembrew init GEM
gembrew build
gembrew check

init creates a tap repository containing README.md, gembrew/, Formula/, and a GitHub Actions workflow that uses Homebrew's test-bot on Linux and Apple Silicon. Pull requests test changed formulae; pushes and manual runs test every formula. It accepts an empty directory or an existing tap containing Formula/. Supplying a gem name also creates its first configuration. The gem name is optional, so gembrew init can prepare an empty tap or add Gembrew to an existing one. Existing README and workflow files are never overwritten.

For example, gembrew init example generates:

README.md
.github/
  workflows/
    test.yml
gembrew/
  example/
    formula.yml
    test.rb
Formula/

gembrew/example/formula.yml contains the gem metadata and source:

gem: example
version: "" # required
source:
  type: rubygems

gembrew/example/test.rb contains the generated default test:

system bin/"example", "--version"

Edit these files as needed, then generate Formula/example.rb:

gembrew build

Each directory under gembrew/ describes one formula. Add more published gems with:

gembrew add another-gem

Plain build generates every configured formula. Pass a configuration name to generate just one:

gembrew build example

The required settings in formula.yml are gem, version, and source. The output defaults to Formula/NAME.rb, where NAME is the configuration directory name. Relative output paths are resolved from the tap root.

gem: example
version: "1.2.3"
source:
  type: rubygems

# Optional gem metadata overrides:
desc: Example command-line application
homepage: https://example.com
license: MIT
executable: example

# Optional additional Homebrew formula dependencies:
dependencies:
  - bash
  - bash :macos_only
  - libffi :system_on_macos

# Optional output override. The default for gembrew/example is shown here.
output: Formula/example.rb

Tag a dependency with :system_on_macos when macOS provides it and Homebrew should install its formula only on other platforms. Tag it with :macos_only when Homebrew should install it only on macOS.

You may add these optional Ruby hook files beside formula.yml:

install_extra.rb  Runs after the standard gem installation
test.rb           Defines the formula test

Gembrew generates a basic COMMAND --version test when test.rb is absent. gembrew init GEM and gembrew add GEM create that test file so it can be replaced with a meaningful functional test. Gembrew inserts install_extra.rb at the end of the formula's install method, after installing the gem and creating its executable wrapper.

To build the root gem from a GitHub tag while continuing to fetch its dependencies from RubyGems, use:

source:
  type: github
  repo: owner/repository
  # tag: v1.2.3
  # gemspec: example.gemspec

The tag defaults to vVERSION; the gemspec path defaults to GEMNAME.gemspec.

Gembrew resolves the generic Ruby dependency graph and generates a Homebrew resource for every runtime dependency. Original .gem archives are reused from RubyGems' local cache when available. Downloaded archives are retained in ${XDG_CACHE_HOME:-~/.cache}/gembrew/gems.

Open the generated Homebrew environment with:

gembrew shell

The repository is mounted as a local tap, so formulae can be addressed by gem name inside the shell:

brew style gembrew/tap/example
brew audit --new --online gembrew/tap/example
brew install --build-from-source gembrew/tap/example
brew test gembrew/tap/example
brew linkage --test gembrew/tap/example

To use a stock, current Homebrew container without mounting the local repository or changing Homebrew's update, API, or cleanup behavior, open a pristine shell:

gembrew shell --pristine

Run non-installing style and audit checks with the local Homebrew:

gembrew check

Run gembrew build first. The check command runs Homebrew style and online audit against the generated formulae without installing them. Use gembrew check example to check only one formula.

Run the complete workflow in a clean, disposable Homebrew container:

gembrew check --container

Container checks additionally perform source installation, the formula test, and linkage validation. The short form is gembrew check -c. Gembrew invokes Docker directly; the tap does not need generated container support files.

Preview either check workflow without running any commands:

gembrew check --dry-run
gembrew check --container --dry-run

The short form is gembrew check -n.

If you experience any issue, have a question or a suggestion, or if you wish to contribute, feel free to open an issue.