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

scripts/formula.schema.ts

scripts/formula.helper.ts

reference/templates/main.mustache

reference/templates/langs/*.mustache

test/data/*.json

test/cases/*.sh

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:

gh api repos/owner/repo/releases/latest --jq '.tag_name'

main

master

[[bin]]

cmd/

[projectcli]

Determine Formula Type

url

sha256

livecheck

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

desc

brew info

homepage

url

sha256

license

head

--HEAD

livecheck

depends_on

test

SPDX License Identifiers

"MIT"

"Apache-2.0"

"GPL-3.0-only"

"GPL-3.0-or-later"

"BSD-2-Clause"

"BSD-3-Clause"

Always specify

-only

-or-later

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

reference/checklists/local-validation.md

reference/faq/common.md

reference/testing/patterns.md

reference/templates/formulas/*.rb

scripts/formula.schema.ts

reference/security/attestation.md

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

Common Pitfalls

Dependency Issues

brew linkage --test

on_linux

brew style

=> :build

libssl.3.dylib

depends_on "openssl@3"

Python Formula Issues

pip_install buildpath

ModuleNotFoundError

pip_install "package==#{version}"

pyproject.toml

name

ktool

k2l

No module named 'pkg_resources'

venv.pip_install "setuptools"

Failed to execute: .../libexec/bin/pip

venv.pip_install

system libexec/"bin/pip"

Test Block Issues

Cargo.toml [[bin]]

pyproject.toml [projectcli]

assert_match

shell_output

2>&1

shell_output("#{bin}/tool --help 2>&1")

See

reference/faq/common.md

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