Gembrew

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

Install

gem install gembrew

Usage

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 styles, audits, installs, tests, and checks the linkage of every formula on Linux and macOS. 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.yml
Formula/

gembrew/example.yml contains:

gem: example

test: |-
  system bin/"example", "--version"

Edit the configuration as needed, then generate Formula/example.rb:

gembrew build

Each YAML file 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 are gem, version, source, and exactly one of test or test_from_file. The output defaults to Formula/NAME.rb, where NAME is the configuration filename. Relative 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
  - libffi :system_on_macos

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

test: |-
  system bin/"example", "--version"

# Use this instead of `test` to load the test body from another file:
# test_from_file: support/test.rb

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

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 example
brew audit --new --online example
brew install --build-from-source example
brew test example
brew linkage --test example

To test a published tap without mounting the local repository, open a pristine Homebrew shell:

gembrew shell --pristine

Run the complete workflow non-interactively in one clean container:

gembrew check

This rebuilds every configured formula, then runs Homebrew style, online audit, source installation, the formula test, and linkage validation in disposable Homebrew containers. Use gembrew check example to check only one formula. Gembrew invokes Docker directly; the tap does not need generated container support files.

Contributing / Support

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

---