Pkgmgr Homebrew Formula Dev

Homebrew Formula Development

Guide for researching, creating, testing, and maintaining Homebrew formulas in a custom tap.

When to Use This Skill

• Creating a new Homebrew formula for a project
• Debugging formula build or test failures
• Running local validation before CI
• Understanding Homebrew's Ruby DSL
• Setting up livecheck for automatic version detection

Research Phase

Before creating a formula, gather this information:

Required Information

Calculate SHA256

Always calculate the checksum for the source tarball:

curl -sL "https://github.com/owner/repo/archive/refs/tags/vX.Y.Z.tar.gz" | shasum -a 256

Formula Structure

File Location

Formulas are organized alphabetically: Formula/<first-letter>/<name>.rb

Example: Formula/m/mustache.rb

Template

See the slash command /add-homebrew-formula for a complete template, or reference existing formulas in Formula/ directory.

Key Elements

Language-Specific Patterns

Go Projects:

depends_on "go" => :build

def install
  system "go", "build", *std_go_args(ldflags: "-s -w"), "./cmd/binary"
end

Rust Projects:

depends_on "rust" => :build

def install
  system "cargo", "install", *std_cargo_args
end

Local Validation

Step 1: Sync to Tap Location

Formula files must be in the Homebrew tap location for testing:

mkdir -p /usr/local/Homebrew/Library/Taps/arustydev/homebrew-tap/Formula/<letter>/
cp Formula/<letter>/<name>.rb /usr/local/Homebrew/Library/Taps/arustydev/homebrew-tap/Formula/<letter>/
chmod a+r /usr/local/Homebrew/Library/Taps/arustydev/homebrew-tap/Formula/<letter>/<name>.rb

Step 2: Run Audit

brew audit --new --formula arustydev/tap/<name>

This checks for common formula issues but NOT style violations.

Step 3: Run CI Syntax Check (Critical)

brew test-bot --only-tap-syntax

This runs brew style (rubocop) against ALL files in the tap - same as CI. This catches issues that brew audit misses.

Step 4: Test Installation

brew install --build-from-source arustydev/tap/<name>

Step 5: Run Formula Tests

brew test arustydev/tap/<name>

Step 6: Verify Binary

<name> --help

Version Updates with Livecheck

Homebrew's livecheck automatically detects new versions from the formula's URL pattern. No manual version registry needed.

Test livecheck:

brew livecheck arustydev/tap/<name>

Common Issues

CI Failures from Rubocop

Problem: brew test-bot --only-tap-syntax fails on markdown files containing Ruby code blocks.

Cause: brew style uses rubocop-md which lints code fenced as ruby in markdown files. The tap's .rubocop.yml exclusions do NOT apply - brew style uses Homebrew's central config.

Solution: Use text instead of ruby for code fence language in any markdown documentation.

Line Length Errors

Problem: Lines longer than 118 characters.

Solution: Split long strings or use Homebrew's allowed patterns (URLs, sha256 lines, etc. are exempt).

Test Block Failures

Problem: Formula installs but brew test fails.

Solution: Ensure test block creates necessary test files and uses proper paths:

test do
  (testpath/"input.txt").write("test content")
  output = shell_output("#{bin}/tool #{testpath}/input.txt")
  assert_equal "expected", output.strip
end

Checklist

• Research complete (version, license, build system, deps)
• SHA256 calculated for source tarball
• Formula file created at Formula/<letter>/<name>.rb
• brew audit --new passes
• brew test-bot --only-tap-syntax passes
• brew install --build-from-source succeeds
• brew test passes
• Binary executes correctly
• Feature branch created and committed
• PR created with CI passing

References

• Homebrew Formula Cookbook
• SPDX License List
• Homebrew Ruby Style Guide
• Existing formulas in Formula/ directory for patterns