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

Template Pipeline

This skill includes a JSON Schema → Mustache template pipeline for generating formulas from structured data.

Workflow

1. Create a JSON file conforming to scripts/formula.schema.ts
2. Run just template-formula <path-to-json> to validate and render
3. The pipeline validates with AJV, preprocesses (PascalCase, language dispatch, license rendering), then renders via Mustache

Key Files

Running

# Render a formula from JSON
just template-formula path/to/formula.json

# Run all tests
just test

Adding a New Language

1. Add install-<lang> definition to scripts/formula.schema.ts
2. Add language dispatch allOf entry in the formula definition
3. Create reference/templates/langs/<lang>.mustache partial
4. Add "<lang>" to the language enum
5. Add a test fixture in test/data/ and test case in test/cases/

Research Phase

Before creating a formula, gather this information:

Determine Formula Type

Calculate SHA256

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

Formula Naming

• Formula name: kebab-case (hex-patch, jwt-ui)
• Class name: PascalCase (HexPatch, JwtUi)

Formula Structure

File Location

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

Key Elements

SPDX License Identifiers

Always specify -only or -or-later for GPL/LGPL/AGPL.

Language-Specific Patterns

Each language has a reference doc with install patterns, schema fields, and common issues:

• Go: reference/langs/go.md
• Rust: reference/langs/rust.md
• Python: reference/langs/python.md

Additional languages supported by the template pipeline (cmake, autotools, meson, zig) — see their Mustache partials in reference/templates/langs/.

Reference Materials

Batch Formula Creation

When creating many formulas at once:

1. Compute SHA256 hashes in parallel — launch multiple curl | shasum calls concurrently
2. Research build details in parallel — check build manifests concurrently
3. Write all formula files — no dependencies between them
4. Create branches/PRs sequentially — one branch per formula, each from main
5. Use ruby -c *.rb to syntax-check all formulas before pushing

Architecture-Specific Binaries

When a project provides pre-built binaries for different architectures:

Preferred: Build from source (avoids architecture complexity)

If pre-built binaries required: Use resource blocks, NOT url/sha256 in on_arm/on_intel:

on_arm do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-arm64.tar.gz"
    sha256 "..."
  end
end

on_intel do
  resource "binary" do
    url "https://github.com/org/repo/releases/download/vX.Y.Z/tool-darwin-amd64.tar.gz"
    sha256 "..."
  end
end

def install
  resource("binary").stage do
    bin.install "tool"
  end
end

See reference/faq/common.md for details on deprecated patterns.

Common Pitfalls

Dependency Issues

Python Formula Issues

Test Block Issues

See reference/faq/common.md for detailed explanations and additional issues.

Checklist

• Research complete (version, license, build system, deps, binary name, default branch)
• Formula type determined (standard vs HEAD-only)
• SHA256 calculated (if not HEAD-only)
• Formula file created at Formula/<letter>/<name>.rb
• ruby -c passes (syntax check)
• brew audit --new passes
• brew style passes (or issues addressed)
• brew install --build-from-source succeeds
• brew test passes
• Binary executes correctly
• PR created with CI passing

References

• Homebrew Formula Cookbook
• SPDX License List
• Homebrew Ruby Style Guide
• Homebrew Python Guidelines