Homebrew Formula Development

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

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

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

main

master

[[bin]]

cmd/

[project.scripts]

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

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"

-only

-or-later

Language-Specific Patterns

• Go:

  reference/langs/go.md

• Rust:

  reference/langs/rust.md

• Python:

  reference/langs/python.md

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

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

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

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