### macOS Portable Build Environment Setup in Install

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

Demonstrates the environment setup for portable compilation on macOS within the `install` method, including warnings for newer macOS versions and linker flag adjustments.

```ruby
# macOS Setup:
if OS.mac? && OS.kernel_version.major > TARGET_DARWIN_VERSION.major
  opoo "Building on newer macOS than target!"
  puts "This binary may not work on the targeted older version."
  puts "For true portability, build on macOS #{TARGET_DARWIN_VERSION}."
end

ENV.append "LDFLAGS", "-Wl,-search_paths_first"
```

--------------------------------

### Install and Configure Docker with Lima

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

If Docker is not installed, use these commands to install Docker and Lima, then configure Docker to use the Lima VM. This setup is necessary to run the Homebrew Docker container.

```bash
brew install --formula docker lima
limactl start template://docker
docker context create lima --docker "host=unix://${HOME}/.lima/docker/sock/docker.sock"
docker context use lima
```

--------------------------------

### Make Installation Pattern

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

A simple installation pattern for projects that primarily use Make for building and installation, specifying the installation prefix.

```ruby
def install
  system "make", "install", "PREFIX=#{prefix}"
end
```

--------------------------------

### Linux Portable Build Environment Setup in Install

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

Illustrates the environment reset and C compiler flag addition for portable compilation on Linux, ensuring the use of system libraries.

```ruby
# Linux Setup:
ENV.delete "LDFLAGS"
ENV.delete "LIBRARY_PATH"
ENV.delete "LD_RUN_PATH"
ENV.delete "LD_LIBRARY_PATH"
ENV.delete "TERMINFO_DIRS"
ENV.delete "HOMEBREW_RPATH_PATHS"
ENV.delete "HOMEBREW_DYNAMIC_LINKER"

ENV.append_to_cflags "-fPIC"
```

--------------------------------

### Test Block Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Provides an example of a test block within a formula, demonstrating how to execute the installed binary and assert its output.

```ruby
test do
  system bin/"myapp", "--version"
  assert_match(/1.0.0/, shell_output("#{bin}/myapp --version"))
end
```

--------------------------------

### Environment Manipulation Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Demonstrates how to modify environment variables and compiler flags during the installation process, including appending, prepending, and deleting variables.

```ruby
def install
  ENV.append "LDFLAGS", "-Wl,-search_paths_first"
  ENV.append_to_cflags "-fPIC"
  ENV.delete "LDFLAGS"
  system "./configure"
end
```

--------------------------------

### Standard Autotools Installation Pattern

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Demonstrates the standard installation procedure for packages using the Autotools build system, including configure, make, and make install steps.

```ruby
def install
  system "./configure",
         "--prefix=#{prefix}",
         "--sysconfdir=#{etc}",
         *std_configure_args
  system "make"
  system "make", "install"
end
```

--------------------------------

### CMake Installation Pattern

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Shows the typical installation process for projects using CMake as their build system, involving CMake configuration, building, and installation steps.

```ruby
def install
  system "cmake", "-S", ".", "-B", "build", *std_cmake_args
  system "cmake", "--build", "build"
  system "cmake", "--install", "build"
end
```

--------------------------------

### Simple Portable Formula Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

An example of a basic portable formula for a simple application. It demonstrates setting metadata, defining the URL and checksum, and implementing the install and test blocks using portable configuration arguments.

```ruby
class MyPortableApp < PortableFormula
  desc "A portable application"
  homepage "https://example.com"
  url "https://example.com/myapp-1.0.0.tar.gz"
  sha256 "abc123def456..."
  
  def install
    system "./configure",
           "--prefix=#{prefix}",
           *portable_configure_args,
           *std_configure_args
    system "make"
    system "make", "install"
  end
  
  test do
    system bin+"myapp", "--version"
  end
end
```

--------------------------------

### Install and Test Formula from Source

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

Before submitting a PR, build the formula from source using `HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>`. Then, run tests with `brew test <formula>`.

```sh
# Build from source (required)
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>

# Run tests
brew test <formula>
```

--------------------------------

### Complete Formula Example: a2ps

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

A comprehensive example of a Homebrew formula, including dependencies, network access denial, build configuration, installation steps, and a test case.

```ruby
class A2ps < Formula
  desc "Any-to-PostScript filter"
  homepage "https://www.gnu.org/software/a2ps/"
  url "https://ftpmirror.gnu.org/gnu/a2ps/a2ps-4.15.8.tar.gz"
  sha256 "8d13915a36ebbfa8e7b236b350cc81adc714acb217a18e8d8c60747c0ad353f9"
  license "GPL-3.0-or-later"

  bottle do
    sha256 arm64_tahoe:   "f6895a00c5e039d81af9950d1e22c6012e50d6b8c19b5ad576953d06194ffc41"
    sha256 sonoma:        "1460a22fe6091322739e60676866cca20541f9c6789a1c698468e702f3e99789"
  end

  depends_on "pkgconf" => :build
  depends_on "bdw-gc"
  depends_on "libpaper"

  deny_network_access!

  def install
    system "./configure",
           "--sysconfdir=#{etc}",
           "--with-lispdir=#{elisp}",
           *std_configure_args
    system "make"
    system "make", "install", "sysconfdir=#{prefix}/etc"
    inreplace prefix/"etc/a2ps.cfg", prefix, opt_prefix
    etc.install (prefix/"etc").children
  end

  test do
    (testpath/"test.txt").write("Hello World!\n")
    system bin/"a2ps", "test.txt", "-o", "test.ps"
    assert_match "(Hello World!) p n\n", File.read("test.ps")
  end
end
```

--------------------------------

### Install Formulae with Brew

Source: https://github.com/homebrew/homebrew-core/blob/main/README.md

Use this command to install any formula from the Homebrew Core tap. This is the default tap and is installed automatically.

```bash
brew install <formula>
```

--------------------------------

### Install and Verify Formula Build from Source

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

To verify a new formula builds correctly, use `HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>` with verbose and debug flags (`-vd`).

```sh
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>
```

--------------------------------

### Example: Basic Metadata Declaration

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

An example demonstrating how to declare core metadata for a formula, including description, homepage, download URL, checksum, license, and head repository.

```ruby
class Vim < Formula
  desc "Highly configurable text editor"
  homepage "https://www.vim.org"
  url "https://github.com/vim/vim/archive/refs/tags/v9.0.1234.tar.gz"
  sha256 "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  license "Vim"
  head "https://github.com/vim/vim.git", branch: "master"
end
```

--------------------------------

### Get Workflow Run Status Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-ci-status-command.md

Example of how to retrieve and display CI workflow status and individual check run details for a given pull request.

```ruby
ci_status_cmd = Homebrew::Cmd::CheckCiStatusCmd.new
ci_node, check_runs = ci_status_cmd.get_workflow_run_status(123)

if ci_node
  puts "CI Status: #{ci_node['status']}"
  puts "Run ID: #{ci_node.dig('workflowRun', 'databaseId')}"
  check_runs.each do |run|
    puts "#{run['name']}: #{run['status']}"
  end
end
```

--------------------------------

### Add a New Formula

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

Commands to create, install, audit, and commit a new formula. Use `HOMEBREW_NO_INSTALL_FROM_API=1` to ensure installation from source.

```shell
brew create $URL
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source foo
brew audit --new foo
git commit -m "foo 2.3.4 (new formula)"
```

--------------------------------

### Install Formula Migrated to Cask

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Shows how Homebrew handles installing a formula that has been moved to a different tap, like Homebrew Cask.

```bash
# Formula has moved to cask
brew install gimp

# Homebrew redirects to cask
brew install --cask gimp
```

--------------------------------

### UnstableAllowlist Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Allows packaging pre-release versions for specific packages. This is a JSON object where keys are formula names and values are version strings.

```json
{
  "aalib": "1.4rc",
  "libcaca": "0.99.beta"
}
```

--------------------------------

### Example Generated Resource Blocks

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/aspell-dictionaries-command.md

Sample output of the `brew aspell-dictionaries` command, showing resource declarations for different languages.

```ruby
resource "ca" do
  url "https://ftpmirror.gnu.org/gnu/aspell/dict/ca/aspell6-ca-0.50-2.tar.bz2"
  mirror "https://ftp.gnu.org/gnu/aspell/dict/ca/aspell6-ca-0.50-2.tar.bz2"
  sha256 "abc123def456abc123def456abc123def456abc123def456abc123def456abc1"
end

resource "de" do
  url "https://ftpmirror.gnu.org/gnu/aspell/dict/de/aspell6-de-0.60-2.tar.bz2"
  mirror "https://ftp.gnu.org/gnu/aspell/dict/de/aspell6-de-0.60-2.tar.bz2"
  sha256 "def456ghi789def456ghi789def456ghi789def456ghi789def456ghi789def456g"
end

resource "en_AU" do
  url "https://ftpmirror.gnu.org/gnu/aspell/dict/en/aspell6-en-2024.01.14-0.tar.bz2"
  mirror "https://ftp.gnu.org/gnu/aspell/dict/en/aspell6-en-2024.01.14-0.tar.bz2"
  sha256 "ghi789jkl012..."
end
```

--------------------------------

### Example Output of portable_configure_args

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

Illustrates the expected output of the `portable_configure_args` method under different macOS build scenarios, including cross-compilation and native compilation.

```ruby
# Building on macOS 14 (Sonoma) for macOS 12 (Monterey):
[
  "--build=aarch64-apple-darwin23",
  "--host=aarch64-apple-darwin20"
]

# Building on same macOS version:
[]
```

--------------------------------

### Linux-Specific Portable Build Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

An example of a portable formula specifically for Ruby, demonstrating how to configure it for maximum portability on Linux. It includes setting up shared library support and notes the specific build environment requirements.

```ruby
class PortableRuby < PortableFormula
  desc "Ruby built for maximum portability"
  
  def install
    # Configure with cross-compilation support
    system "./configure",
           "--prefix=#{prefix}",
           *portable_configure_args,
           "--enable-shared"
    system "make"
    system "make", "install"
  end
end
```

--------------------------------

### Example: Dependency Declaration

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Illustrates how to declare various types of dependencies for a formula, including build-time, test-time, and system libraries, with platform-specific configurations.

```ruby
class Prowler < Formula
  depends_on "cmake" => :build
  depends_on "meson" => :build
  depends_on "ninja" => :build
  depends_on "pkgconf" => :build
  depends_on "openssl@3"
  depends_on "libsodium"
  
  uses_from_macos "libffi"
  
  on_linux do
    depends_on "patchelf" => :build
    depends_on "openblas"
  end
  
  on_mac do
    depends_on "coreutils" => :build
  end
end
```

--------------------------------

### Integrating Portable Configure Arguments in Formula Install

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

Shows how to integrate `portable_configure_args` into a formula's install method to automatically include necessary cross-compilation flags.

```ruby
def install
  system "./configure",
         "--prefix=#{prefix}",
         *portable_configure_args,
         *std_configure_args
  system "make"
  system "make", "install"
end
```

--------------------------------

### Install Formula with Deprecated Name

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Demonstrates how Homebrew redirects an installation attempt using a deprecated formula name to its current name.

```bash
# User tries old name
brew install amtk

# Homebrew redirects to new name
# Installs libgedit-amtk instead
```

--------------------------------

### Example macOS Runner Name

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

An example of a generated macOS runner name following the specified convention.

```bash
sonoma-x86_64-123456789-dispatch
```

--------------------------------

### Example: Fast x86_64 Linux Build

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

Demonstrates calling `linux_runner_spec` for a fast x86_64 Linux build, resulting in the standard GitHub-hosted runner.

```ruby
# Fast x86_64 Linux build (< 6 minutes)
spec = cmd.linux_runner_spec(:x86_64, 300)
# Returns: {runner: "ubuntu-latest", container: {...}, workdir: "/github/home"}
```

--------------------------------

### Formula Inheritance Hierarchy

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Illustrates the class inheritance for Homebrew formulae, starting from the base Formula class.

```text
Formula (base class from Homebrew)
├── PortableFormula (for portable builds)
│   └── Mixin: PortableFormulaMixin
└── Specific formula classes (e.g., Vim, Bash, Python)
```

--------------------------------

### Tap Migration Mapping Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Shows how formula names are mapped to their destination taps, used for routing formulae to the correct repository. This is utilized in `tap_migrations.json` and by the Homebrew CLI.

```json
{
  "android-ndk": "homebrew/cask",
  "gimp": "homebrew/cask",
  "inkscape": "homebrew/cask"
}
```

--------------------------------

### Example: Slow ARM64 Linux Build

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

Illustrates calling `linux_runner_spec` for a slow ARM64 Linux build, which selects a self-hosted ARM runner.

```ruby
# Slow ARM64 build (> 6 minutes)
spec = cmd.linux_runner_spec(:arm64, 600)
# Returns: {runner: OS::LINUX_CI_ARM_RUNNER, container: {...}, workdir: "/github/home"}
```

--------------------------------

### Comprehensive Test Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Demonstrates a complete test case using various test methods like `testpath`, `system`, `assert_match`, and `refute_match` within a `test` block.

```ruby
test do
  (testpath/"test.txt").write("Hello World!\n")
  system bin/"a2ps", "test.txt", "-o", "test.ps"
  assert_match "(Hello World!) p n\n", File.read("test.ps")
  
  refute_match(/Homebrew libraries/,
               shell_output("#{HOMEBREW_BREW_FILE} linkage #{full_name}"))
end
```

--------------------------------

### Define and Stage a Resource

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Use `resource` blocks to define external resources. The `stage` method unpacks and changes the directory to the resource's location for installation.

```ruby
resource "plugin1" do
  url "https://example.com/plugin1-1.0.0.tar.gz"
  sha256 "abc123..."
end

def install
  resource("plugin1").stage do
    system "make", "install", "PREFIX=#{prefix}/share/plugins"
  end
end
```

--------------------------------

### Bottle Tag Example Usage

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Demonstrates how to iterate through supported bottle tags for a formula and display their system, architecture, and OS version. This is useful for understanding bottle compatibility and build configurations.

```ruby
formula = Formula["vim"]
tags = formula.bottle_specification.collector.tags
tags.each do |tag|
  puts "#{tag.system}/#{tag.arch}: #{tag.os_version || '(no version)'}"
end
```

--------------------------------

### Check if CI is Cancellable Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-ci-status-command.md

Example demonstrating how to check if a pull request's CI workflow can be cancelled and retrieve its run ID.

```ruby
run_id = ci_status_cmd.run_id_if_cancellable(123)
if run_id
  puts "Can cancel run #{run_id}"
  # Use GitHub API to cancel: gh api repos/owner/repo/actions/runs/{run_id}/cancel
else
  puts "Cannot cancel: CI already completed or not found"
end
```

--------------------------------

### Example of Unknown Architecture Error

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Demonstrates how an invalid architecture in a bottle tag triggers an 'Unknown tag' error.

```ruby
tag = {system: :bsd, arch: :mips}  # Invalid
# Raises: "Unknown tag: {:system=>:bsd, :arch=>:mips}"
```

--------------------------------

### Run Homebrew Docker Container

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

Use this command to enter the Homebrew Docker container for Linux CI emulation. Ensure Docker is installed and configured.

```bash
docker run --interactive --tty --rm --pull always ghcr.io/homebrew/brew:latest /bin/bash
```

--------------------------------

### Disabled New User Relocation Formulae

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Lists formulae exempt from automatic relocation to `/opt/homebrew` or `/usr/local`, preserving their original installation locations for backward compatibility.

```json
[
  "colordiff",
  "cpanminus",
  "davmail",
  "goenv@2",
  "luarocks",
  "meson",
  "mockserver",
  "opendoor",
  "phpmyadmin",
  "python-setuptools",
  "qnm",
  "rabbitmq",
  "ruby-install",
  "sqlite-utils",
  "zsh-completions"
]
```

--------------------------------

### Example Matches for Bottle Block Regex

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Illustrates lines that would be matched by the `MODIFIED_BOTTLE_BLOCK_REGEX`, showing added or removed bottle block content.

```text
+ bottle do
- sha256 "abc123abc123abc123abc123abc123abc123abc123abc123abc123abc123abc1"
  sha256 arm64_sonoma: "def456def456def456def456def456def456def456def456def456def456def4"

```

--------------------------------

### Build Formula Locally

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Build a formula from source locally. This command ensures that the formula can be built without relying on pre-built binaries. Set HOMEBREW_NO_INSTALL_FROM_API=1 to prevent installation from the API.

```bash
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source formula
```

--------------------------------

### GitHub Actions Output Format

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-ci-status-command.md

Example of the output format written to the `GITHUB_OUTPUT` file when using the command. This format is used by GitHub Actions to set environment variables or outputs.

```text
cancellable-run-id=12345
allow-long-timeout-label-removal=true
```

--------------------------------

### Handle Homebrew UsageError

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

This example shows how to catch and handle a `Homebrew::UsageError` exception, typically raised when a command is invoked with incorrect arguments or options. It prints the error message and exits.

```ruby
begin
  # Homebrew command
rescue Homebrew::UsageError => e
  puts "Usage error: #{e.message}"
  exit 1
end
```

--------------------------------

### Audit New Formulae

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

After installing a new formula, run `brew audit --new --strict <formula>` before opening a PR. Fix any reported style or audit issues.

```sh
brew audit --new --strict <formula>
```

--------------------------------

### Test Formula Functionality

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

Ensure tests verify actual functionality by executing the installed binary or library. Include at least one assertion beyond version or help checks, and validate the build produced a working result.

```sh
# Run tests
brew test <formula>
```

--------------------------------

### Set Test Environment Variable for Source Installation

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Use this command to ensure that Homebrew uses local source code for testing formulae, rather than relying on precompiled bottles.

```bash
HOMEBREW_NO_INSTALL_FROM_SOURCE=1 brew test foo
```

--------------------------------

### Set Build Environment Variable for Source Installation

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Use this command to force Homebrew to build formulae from source instead of using precompiled bottles. This is useful for debugging build issues or when bottles are unavailable.

```bash
HOMEBREW_BUILD_FROM_SOURCE=1 brew install foo
```

--------------------------------

### PortableFormula and PortableFormulaMixin

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/INDEX.md

Defines classes for portable formulas, including methods for configuring build arguments, overriding installation, and handling testing across different environments.

```APIDOC
## PortableFormula and PortableFormulaMixin

### Description
These classes provide the foundation for creating portable formulas, enabling consistent behavior across different platforms and build environments. They include methods for customizing build arguments, overriding standard installation and testing procedures, and managing environment specifics.

### Classes
- **PortableFormula**: The main class for defining portable formulas.
- **PortableFormulaMixin**: A mixin providing additional functionality for portable formulas.

### Constants
- **TARGET_MACOS**: Target macOS identifier.
- **TARGET_DARWIN_VERSION**: Target Darwin version.
- **CROSS_COMPILING**: Boolean indicating if cross-compiling is active.

### Methods
- **portable_configure_args**: Generates configure arguments tailored for portable builds.
- **install** (override): Overrides the default installation process for portable formulas.
- **test** (override): Overrides the default testing process for portable formulas.

### Usage Examples
- Demonstrations of how to use `PortableFormula` and `PortableFormulaMixin`.

### Environment Behavior
- Specific environment handling for macOS and Linux.

### Error Handling
- Details on error handling and related abstractions within the portable formula context.
```

--------------------------------

### Formula Rename Mapping Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Illustrates the mapping of deprecated formula names to their current canonical names. This configuration is used in `formula_renames.json` and by the Homebrew CLI for formula name resolution.

```json
{
  "act_runner": "gitea-runner",
  "alloy": "alloy-analyzer",
  "amtk": "libgedit-amtk",
  "annie": "lux"
}
```

--------------------------------

### Handle GitHub API Errors with StandardError

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

This example shows how to catch general `StandardError` exceptions that may arise from GitHub API calls (GraphQL or REST). It prints the error message to standard error and exits, providing a fallback for network or API-related issues.

```ruby
begin
  response = GitHub::API.open_graphql(query, variables:)
  # Process response
rescue StandardError => e
  $stderr.puts "GitHub API error: #{e.message}"
  exit 1
end
```

--------------------------------

### Synchronized Versions Group Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

An array of formula names that must maintain synchronized versions. This is used in `synced_versions_formulae.json` for version synchronization validation and formula update tooling.

```json
[
  "aarch64-elf-binutils",
  "arm-linux-gnueabihf-binutils",
  "arm-none-eabi-binutils",
  "binutils",
  "i686-elf-binutils",
  "m68k-elf-binutils",
  "mips-linux-gnu-binutils",
  "mipsel-linux-gnu-binutils",
  "riscv64-elf-binutils",
  "x86_64-elf-binutils",
  "x86_64-linux-gnu-binutils"
]
```

--------------------------------

### Marking Formula as Keg-Only

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

This configuration marks a formula as 'keg-only', preventing symlinks in standard locations and ensuring it's installed in a versioned cellar. This is crucial for portable formulae to avoid conflicts and manage dependencies explicitly.

```ruby
keg_only "portable formulae are keg-only"
```

--------------------------------

### Get Pull Request Commits Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Retrieves human-authored commit SHAs for a given pull request, excluding merge and bot commits. Ensure the GITHUB_REPOSITORY environment variable is set.

```ruby
commits = cmd.get_pull_request_commits(1234)
# Returns: ["abc123def456...", "def456ghi789..."]
# (commits by humans, excluding BrewTestBot and merges)
```

--------------------------------

### Set Specific Compiler and Build from Source

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use CC and CXX environment variables to specify compilers. Set HOMEBREW_NO_INSTALL_FROM_API to 1 to force building from source.

```bash
CC=gcc-11 CXX=g++-11 HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source formula
```

--------------------------------

### Determine if Long Timeout Label Can Be Removed Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-ci-status-command.md

Example showing how to determine if the long-timeout label can be removed from a pull request based on CI status.

```ruby
if ci_status_cmd.allow_long_timeout_label_removal?(123)
  puts "Remove long-timeout label"
else
  puts "Keep long-timeout label - slow jobs still running"
end
```

--------------------------------

### Get Major Version

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Extracts the major component from a Version object.

```ruby
Version.new("20.1.0").major
```

--------------------------------

### Configuration Hierarchy in Homebrew

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Details the priority order of configuration settings in Homebrew, from environment variables to repository-level configurations.

```text
Environment Variables (highest priority)
├── Build flags (CFLAGS, LDFLAGS, etc.)
├── Platform vars (HOMEBREW_NO_INSTALL_FROM_API, etc.)
└── System detection (OS, CPU architecture)
    
Formula-Level Config (mid priority)
├── options (--with-*, --without-*)
├── depends_on declarations
└── uses_from_macos declarations

Repository-Level Config (lowest priority)
├── formula_renames.json
├── tap_migrations.json
├── synced_versions_formulae.json
└── audit_exceptions/*.json
```

--------------------------------

### Formula Renames Mapping

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Maps deprecated formula names to their current names, allowing automatic redirection during installation.

```json
{
  "act_runner": "gitea-runner",
  "alloy": "alloy-analyzer",
  "amtk": "libgedit-amtk",
  "annie": "lux",
  "ark": "velero",
  "arm": "nyx",
  "asciigen": "glyph",
  "at-spi2-atk": "at-spi2-core",
  "atk": "at-spi2-core",
  "azion-cli": "azion",
  "aztfy": "aztfexport"
}
```

--------------------------------

### Fix Portable Formula Library Linkage

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Example of fixing a portable formula that incorrectly links against Homebrew libraries by using `uses_from_macos`.

```ruby
uses_from_macos "ncurses"
```

--------------------------------

### Pre-flight Environment and Formula Checks

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use 'test' commands to validate environment variables and formula existence before proceeding. Exit with status 1 if checks fail.

```bash
# Validate environment
test -n "$GITHUB_REPOSITORY" || exit 1
test -n "$GITHUB_OUTPUT" || exit 1

# Validate formula exists
brew list formula-name &>/dev/null || exit 1
```

--------------------------------

### Assertion in Formula Test Block

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Example of using `assert_match` within a formula's test block to verify command output.

```ruby
test do
  assert_match(/version 1.0/, shell_output("#{bin}/myapp --version"))
  # Raises: Minitest::Assertion if pattern doesn't match
end
```

--------------------------------

### Validate Pull Request with brew check-bottle-modification

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Example of using the `brew check-bottle-modification` command to validate a specific pull request number.

```bash
brew check-bottle-modification 1234
```

--------------------------------

### Bump Formula Version with brew bump-formula-pr

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

Automate version bumps, URL/checksum updates, and PR creation using `brew bump-formula-pr`. Use the `--strict` flag for rigorous checks and specify the new `--version`.

```sh
brew bump-formula-pr --strict <formula> --version=<version>
```

--------------------------------

### Submit a Version Upgrade for a Formula

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

Use `brew bump-formula-pr` to automate version upgrades. Requires specifying URL and SHA256, or tag and revision.

```shell
brew tap homebrew/core
brew bump-formula-pr --strict foo --url=... --sha256=...
```

```shell
brew tap homebrew/core
brew bump-formula-pr --strict foo --tag=... --revision=...
```

```shell
brew tap homebrew/core
brew bump-formula-pr --strict foo --version=...
```

--------------------------------

### Define a Resource with URL, Mirror, and SHA256

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Use the `Resource` class to define external downloadable files for a formula. Specify the primary URL, fallback mirror URLs, and the checksum for verification. The `stage` method is used to extract and process the downloaded resource.

```ruby
resource "plugin" do
  url "https://example.com/plugin-1.0.0.tar.gz"
  mirror "https://mirror.example.com/plugin-1.0.0.tar.gz"
  sha256 "abc123..."
end

def install
  resource("plugin").stage do
    system "make", "install", "PREFIX=#{prefix}"
  end
end
```

--------------------------------

### Aspell Formula Structure with Resources

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/aspell-dictionaries-command.md

Illustrates how the `brew aspell-dictionaries` command output is integrated into the `Formula/a/aspell.rb` file, defining resources for different language dictionaries.

```ruby
class Aspell < Formula
  # ... standard metadata ...
  
  # Generated by: brew aspell-dictionaries
  resource "af" do
    url "..."
    mirror "..."
    sha256 "..."
  end
  
  resource "am" do
    url "..."
    mirror "..."
    sha256 "..."
  end
  
  # ... more resources ...
  
  def install
    # Install main aspell
    system "./configure", *std_configure_args
    system "make"
    system "make", "install"
    
    # Install dictionaries from resources
    resources.each do |resource|
      resource.stage do
        system "./configure", *std_configure_args
        system "make"
        system "make", "install"
      end
    end
  end
end
```

--------------------------------

### Contribute a Fix to an Existing Formula

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

Steps for modifying and testing a formula locally before submitting a pull request. Includes uninstalling, installing from source, testing, auditing, and styling.

```shell
brew uninstall --force foo
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source foo
brew test foo
brew audit --strict foo
brew style foo
```

--------------------------------

### Declare Formula Option Without Feature

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Define a build-time option for a formula that disables a specific feature. This example shows how to declare an option to disable X11 support.

```ruby
option "without-x11", "Build without X11 support"
```

--------------------------------

### Rebottle All Supported Versions Command

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

This command rebottles a formula across all supported versions, including Linux and macOS, using the `:all` bottle tag.

```bash
brew determine-rebottle-runners bash 600
```

--------------------------------

### Allowlist for Unstable Versions

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

This JSON file specifies packages that are allowed to be packaged even if they are pre-release or beta versions. It maps package names to their allowed unstable version identifiers.

```json
{
  "aalib": "1.4rc",
  "automysqlbackup": "3.0-rc",
  "avahi": "0.9-rc",
  "aview": "1.3.0rc",
  "ftgl": "2.1.3-rc",
  "libcaca": "0.99.beta",
  "librasterlite2": "1.1.0-beta",
  "premake": "5.0.0-beta",
  "pwnat": "0.3-beta",
  "recode": "3.7-beta",
  "spatialite-gui": "2.1.0-beta",
  "tcptraceroute": "1.5beta",
  "vbindiff": "3.0_beta"
}
```

--------------------------------

### Declare Formula Option

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Define a build-time option for a formula, allowing users to customize its build with specific features. This example shows how to declare an option for Python support.

```ruby
option "with-python", "Build with Python support"
```

--------------------------------

### Homebrew Core Project File Structure

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/INDEX.md

This snippet outlines the directory structure of the Homebrew Core project, detailing the purpose of each markdown file.

```text
/workspace/home/output/
├── README.md                          # Master navigation guide
├── INDEX.md                           # This file
├── overview.md                        # Project structure
├── formula-dsl.md                    # Formula language reference
├── configuration.md                   # Configuration system
├── types.md                          # Data structures
├── errors.md                         # Error handling
└── api-reference/                    # Command documentation
    ├── check-ci-status-command.md
    ├── determine-rebottle-runners-command.md
    ├── check-bottle-modification-command.md
    ├── aspell-dictionaries-command.md
    └── portable-formula.md
```

--------------------------------

### Output for All Supported Versions Rebottle

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

The output includes Linux runners (with container details) and macOS runners, indicating support for universal rebottling.

```json
runners=[
  {"runner":"ubuntu-latest","container":{"image":"ghcr.io/homebrew/brew:main",...},"workdir":"/github/home"},
  {"runner":"sonoma-x86_64-123456789-dispatch"},
  {"runner":"sonoma-arm64-123456789-dispatch"},
  ...
]
```

--------------------------------

### Output Generation Logic

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/aspell-dictionaries-command.md

The Ruby code snippet demonstrates how resource names, URLs, mirrors, and SHA256 checksums are formatted into resource blocks for output.

```ruby
<<-EOS
resource "#{resource.name}" do
  url "#{resource.url}"
  mirror "#{resource.mirrors.first}"
  sha256 "#{resource.cached_download.sha256}"
end

EOS
```

--------------------------------

### Debug Configure Script Errors

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Build a formula with verbose output and inspect the `config.log` file to debug configure script failures.

```bash
# Build with verbose output
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source --verbose formula-name

# Configure was likely invoked as:
./configure --prefix=/opt/homebrew/Cellar/formula/version ...

# Check config.log for details
cat config.log | tail -50
```

--------------------------------

### Create a Version Object

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Instantiates a Version object from a string for comparison and manipulation.

```ruby
Version.new("1.2.3")
```

--------------------------------

### Run All Required Validations

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

Before submitting a PR, ensure all checks pass locally. This includes building from source, running tests, and auditing the formula.

```sh
# Build from source (required)
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source <formula>

# Run tests
brew test <formula>

# Audit (existing formula) add --new for new formulae
brew audit --strict [--new] <formula>
```

--------------------------------

### Regex for Detecting Bottle Block Modifications

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

This regex pattern is used to identify lines in diffs that indicate modifications to bottle blocks, including the start of a bottle block or SHA256 entries.

```ruby
/^(\+|-) \s*(bottle do|sha256.*: \s+"\h{64}")/"
```

--------------------------------

### Clone Homebrew Core Repository

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Use this command to clone the Homebrew Core repository to your local machine. Replace YOUR_USERNAME with your GitHub username.

```bash
git clone https://github.com/YOUR_USERNAME/homebrew-core.git
```

--------------------------------

### Build, Test, Audit, and Style Formula

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Ensure formula integrity by building from source, running tests, performing strict audits, and checking style. These steps help catch errors early.

```bash
# Build from source to catch errors
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source formula

# Run tests
brew test formula

# Run audit
brew audit --strict formula

# Check style
brew style formula
```

--------------------------------

### Check if Commit Modifies Bottle Block Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Determines if a specific commit modifies any formula's bottle block. This check is limited to files within the 'Formula/' directory and ending in '.rb'.

```ruby
if cmd.commit_modifies_bottle_block?("abc123def456")
  puts "This commit modifies a bottle block!"
else
  puts "No bottle modifications found"
end
```

--------------------------------

### Homebrew Command Module Organization

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Shows the organization of command modules within the Homebrew::Cmd namespace.

```text
Homebrew::Cmd
├── CheckCiStatusCmd
├── DetermineRebottleRunnersCmd
├── CheckBottleModificationCmd
├── AspellDictionariesCmd
└── Others
```

--------------------------------

### Run Aspell Dictionaries Command

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/aspell-dictionaries-command.md

Execute the command to generate Aspell dictionary resource declarations. No parameters or options are required.

```bash
brew aspell-dictionaries
```

--------------------------------

### Check if Patch Modifies Bottle Block Example

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Performs low-level regex matching on a file patch to detect bottle block modifications. It identifies lines added or removed that contain 'bottle do' or SHA256 hash patterns.

```ruby
patch = <<~PATCH
  bottle do
-   sha256 "old123old123old123..."
+   sha256 "new456new456new456..."
  end
PATCH

if cmd.patch_modifies_bottle_block?(patch)
  puts "Bottle modification detected!"
end
```

--------------------------------

### Portable Configure Arguments for macOS Cross-Compilation

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/portable-formula.md

Returns an array of configure arguments necessary for cross-compilation on macOS. This is used when the build environment's macOS version differs from the target version for portability.

```ruby
def portable_configure_args
  if OS.mac? && CROSS_COMPILING
    [
      "--build=#{cpu}-apple-darwin#{OS.kernel_version}",
      "--host=#{cpu}-apple-darwin#{TARGET_DARWIN_VERSION}"
    ]
  else
    []
  end
end
```

--------------------------------

### Compare Version Objects

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/types.md

Compares two Version objects to determine their order.

```ruby
Version.new("2.0") > Version.new("1.9")
```

--------------------------------

### Test Method: testpath

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Provides a temporary directory for creating test files. Use this to write temporary files needed during testing.

```ruby
(testpath/"test.txt").write("hello")
```

--------------------------------

### Check Formula Linkage

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use `brew linkage` to inspect a formula's dynamic library dependencies.

```bash
brew linkage vim
```

--------------------------------

### Safely Access Environment Variables with Defaults

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use ENV.fetch with a block to provide a default value or raise an error if the variable is not set. This prevents runtime errors due to missing configuration.

```ruby
# Always set a default or handle missing variable
GITHUB_OUTPUT = ENV.fetch("GITHUB_OUTPUT") { raise "GITHUB_OUTPUT is not defined" }
```

```ruby
# Or with guard:
owner, repo = ENV.fetch("GITHUB_REPOSITORY", "").split("/")
raise "GITHUB_REPOSITORY is not set" unless owner && repo
```

--------------------------------

### CI Integration in GitHub Actions

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/check-bottle-modification-command.md

Shows how to integrate the `brew check-bottle-modification` command into a GitHub Actions workflow to check pull requests before merging.

```yaml
- name: Check bottle modifications
  run: brew check-bottle-modification ${{ github.event.pull_request.number }}
```

--------------------------------

### Tap Migration Mapping

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/configuration.md

Routes formulae to alternative Homebrew taps when they are no longer maintained in core, such as moving to Homebrew Cask.

```json
{
  "android-ndk": "homebrew/cask",
  "android-platform-tools": "homebrew/cask",
  "avidemux": "homebrew/cask",
  "chromedriver": "homebrew/cask",
  "cockatrice": "homebrew/cask",
  "gimp": "homebrew/cask",
  "inkscape": "homebrew/cask",
  "joplin": "homebrew/cask",
  "keybase": "homebrew/cask",
  "luanti": "homebrew/cask",
  "transmission-remote-gtk": "homebrew/cask/transmission-remote-gui",
  "wesnoth": "homebrew/cask/the-battle-for-wesnoth"
}
```

--------------------------------

### Environment Manipulation: ENV.prepend

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Prepends a string to an existing environment variable. Often used for modifying the PATH.

```ruby
ENV.prepend "PATH", "#{prefix}/bin"
```

--------------------------------

### Livecheck Block Configuration

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Sets up automatic version update detection for a formula, specifying the URL to check and the regex pattern to extract the version.

```ruby
livecheck do
  url "https://github.com/example/example/releases"
  regex(/v?(\d+(?:\.\d+)*)/i)
  strategy :github_latest
end
```

--------------------------------

### Define a Service Block in a Formula

Source: https://github.com/homebrew/homebrew-core/blob/main/AGENTS.md

Use a `service` block to define how a formula should run as a daemon. Ensure the `run` command and `keep_alive` status are correctly specified.

```ruby
service do
  run [opt_bin/"foo", "start"]
  keep_alive true
end
```

--------------------------------

### Create a New Branch for Formula Changes

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/README.md

Before making changes, create a new branch for your formula. Replace formula-name-version with a descriptive name for your branch.

```bash
git checkout -b formula-name-version
```

--------------------------------

### Contribute a Fix to an Existing Formula (Alternative Method)

Source: https://github.com/homebrew/homebrew-core/blob/main/CONTRIBUTING.md

An alternative method for contributing fixes, involving tapping the core repository, editing the formula, and testing.

```shell
brew tap homebrew/core --force
brew edit foo
brew uninstall --force foo
HOMEBREW_NO_INSTALL_FROM_API=1 brew install --build-from-source foo
brew test foo
brew audit --strict foo
brew style foo
git commit -m "foo <insert new version number>"
```

--------------------------------

### Rebottle Single macOS Version Command

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/api-reference/determine-rebottle-runners-command.md

Use this command to specify runners for a single macOS version (Sonoma in this case) for a given formula.

```bash
brew determine-rebottle-runners vim 300
```

--------------------------------

### Test Method: system

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/formula-dsl.md

Executes a shell command within the test environment. Useful for running executables and checking their behavior.

```ruby
system "#{bin}/myapp", "--help"
```

--------------------------------

### Safely Perform File Write Operations

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use a begin-rescue block to catch IOError exceptions during file operations. This prevents the script from crashing due to file access issues and provides an error message.

```ruby
begin
  File.open(github_output, "a") do |f|
    f.puts("key=value")
  end
rescue IOError => e
  $stderr.puts "File write error: #{e.message}"
  exit 1
end
```

--------------------------------

### Run Formula Audit for Circular Dependencies

Source: https://github.com/homebrew/homebrew-core/blob/main/_autodocs/errors.md

Use `brew audit --strict` to check for circular dependencies in a formula.

```bash
brew audit --strict formula-name
```