### APT Package Installation

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Installs specified build dependencies using apt-get in non-interactive mode. Requires an initialized apt.Apt instance.

```go
// Install build dependencies
a := apt.New(run)
err := a.Install(ctx, s.AptPackages["php_build"]...)
```

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

### Using autoconf.Recipe Abstraction

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Demonstrates how to wrap the `autoconf.Recipe` in a custom struct to implement the `recipe.Recipe` interface. This is useful for dependencies that follow the configure/make/make install cycle.

```go
type MyRecipe struct{ Fetcher fetch.Fetcher }

func (r *MyRecipe) Name() string         { return "mylib" }
func (r *MyRecipe) Artifact() ArtifactMeta { return ArtifactMeta{OS: "linux", Arch: "x64"} }

func (r *MyRecipe) Build(ctx context.Context, s *stack.Stack, src *source.Input,
    run runner.Runner, out *output.OutData) error {
    return (&autoconf.Recipe{
        DepName: "mylib",
        Fetcher: r.Fetcher,
        Hooks: autoconf.Hooks{
            AptPackages:   func(s *stack.Stack) []string { return s.AptPackages["mylib_build"] },
            ConfigureArgs: func(_, prefix string) []string { return []string{"--prefix=" + prefix, "--enable-shared"} },
            PackDirs:      func() []string { return []string{"include", "lib"} },
        },
    }).Build(ctx, s, src, run, out)
}
```

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

### Sample data.json File Paths

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

These are example paths for data.json files used in parity testing, located on the build host at /tmp/. Each file corresponds to a specific dependency and version.

```bash
/tmp/go-data.json
```

```bash
/tmp/node-data.json
```

```bash
/tmp/php-data.json
```

```bash
/tmp/r-data.json
```

```bash
/tmp/jruby-data.json
```

```bash
/tmp/appdynamics-data.json
```

```bash
/tmp/skywalking-data.json
```

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

### Run Tests with RSpec

Source: https://github.com/cloudfoundry/binary-builder/blob/main/CONTRIBUTING.md

Execute this command to run the project's tests after installing dependencies.

```bash
bundle
bundle exec rspec
```

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

### Autoconf Recipe Engine for Builds

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Illustrates how to use the Autoconf Recipe Engine for building software with the standard configure/make/make-install cycle, including custom hooks for package installation, configuration arguments, and build steps.

```APIDOC
## Autoconf Recipe Engine

### Description
Hook-based build engine for software using standard configure/make/make-install cycle.

### Method
`Build` method of `autoconf.Recipe`

### Endpoint
N/A (Code-based interaction)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
// Using autoconf.Recipe for a new dependency
type LibunwindRecipe struct {
    Fetcher fetch.Fetcher
}

func (r *LibunwindRecipe) Name() string { return "libunwind" }
func (r *LibunwindRecipe) Artifact() ArtifactMeta {
    return ArtifactMeta{OS: "linux", Arch: "x64"}
}

func (r *LibunwindRecipe) Build(ctx context.Context, s *stack.Stack, src *source.Input,
    run runner.Runner, out *output.OutData) error {
    return (&autoconf.Recipe{
        DepName: "libunwind",
        Fetcher: r.Fetcher,
        Hooks: autoconf.Hooks{
            AptPackages: func(s *stack.Stack) []string {
                return s.AptPackages["libunwind_build"]
            },
            AfterExtract: func(ctx context.Context, srcDir, prefix string, r runner.Runner) error {
                return r.RunInDir(srcDir, "autoreconf", "-i")
            },
            ConfigureArgs: func(srcDir, prefix string) []string {
                return []string{
                    "--prefix=" + prefix,
                    "--enable-shared",
                    "--disable-static",
                }
            },
            PackDirs: func() []string {
                return []string{"include", "lib"}
            },
        },
    }).Build(ctx, s, src, run, out)
}
```

### Response Example
N/A (Build process results in compiled artifacts or errors)
```

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

### APT Download .deb Files Without Installing

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Downloads and installs specific .deb packages, such as development headers, without triggering a full installation. Useful for dependencies like Python's tcl/tk.

```go
// Download .deb files without installing (for Python tcl/tk)
err = a.InstallReinstall(ctx, s.Python.UseForceYes,
    "tcl8.6-dev", "tk8.6-dev")
```

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

### Fetcher Interface for HTTP Downloads

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Explains the Fetcher interface for downloading files over HTTP with checksum verification, including examples for downloading with SHA256 and reading URL bodies.

```APIDOC
## Fetcher Interface

### Description
HTTP download functionality with checksum verification supporting SHA256, SHA512, MD5, and SHA1 algorithms.

### Method
Interface methods: `Download`, `ReadBody`

### Endpoint
N/A (Code-based interaction)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
// Create fetcher with 10-minute timeout
f := fetch.NewHTTPFetcher()

// Download with SHA256 verification
checksum := source.Checksum{
    Algorithm: "sha256",
    Value:     "abc123def456...",
}
err := f.Download(ctx,
    "https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.gz",
    "/tmp/ruby-3.3.6.tar.gz",
    checksum,
)

// Read URL body directly
body, err := f.ReadBody(ctx, "https://api.github.com/repos/ruby/ruby/releases")
```

### Response Example
N/A (Execution results in downloaded files or byte slices)
```

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

### Runner Interface for System Commands

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Details the Runner interface for executing system commands, including variations for environment variables and directory context, with examples for both production and testing scenarios.

```APIDOC
## Runner Interface

### Description
Abstraction for executing system commands with support for directory context and environment variables. Enables unit testing via FakeRunner.

### Method
Interface methods: `Run`, `RunWithEnv`, `RunInDir`, `RunInDirWithEnv`, `Output`

### Endpoint
N/A (Code-based interaction)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
```go
// Production usage with RealRunner
r := &runner.RealRunner{}
err := r.RunInDirWithEnv(
    "/tmp/ruby-3.3.6",
    map[string]string{"CFLAGS": "-O2"},
    "./configure",
    "--prefix=/app/vendor/ruby-3.3.6",
    "--enable-load-relative",
)

// Testing with FakeRunner
fake := runner.NewFakeRunner()
fake.OutputMap["ruby --version"] = "ruby 3.3.6"
fake.ErrorMap["make install"] = errors.New("permission denied")

// Execute recipe with fake
recipe.Build(ctx, stack, src, fake, outData)

// Verify calls
assert.Equal(t, "make", fake.Calls[2].Name)
assert.Equal(t, []string{"-j4"}, fake.Calls[2].Args)
assert.Equal(t, "/tmp/ruby-3.3.6", fake.Calls[2].Dir)
```

### Response Example
N/A (Execution results in errors or output strings)
```

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

### Fetcher Interface for HTTP Downloads

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Defines the Fetcher interface for downloading files over HTTP with checksum verification. Includes examples for downloading with SHA256 and reading URL body directly.

```go
// Fetcher is the interface for downloading files.
type Fetcher interface {
    Download(ctx context.Context, url, dest string, checksum source.Checksum) error
    ReadBody(ctx context.Context, url string) ([]byte, error)
}
```

```go
// Create fetcher with 10-minute timeout
f := fetch.NewHTTPFetcher()

// Download with SHA256 verification
checksum := source.Checksum{
    Algorithm: "sha256",
    Value:     "abc123def456...",
}
err := f.Download(ctx,
    "https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.gz",
    "/tmp/ruby-3.3.6.tar.gz",
    checksum,
)
```

```go
// Read URL body directly
body, err := f.ReadBody(ctx, "https://api.github.com/repos/ruby/ruby/releases")
```

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

### Get Primary Checksum from Source Input

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Retrieves the strongest available checksum (prioritizing SHA512, then SHA256, MD5, and SHA1) from the parsed source data.

```go
// Get strongest available checksum (SHA512 > SHA256 > MD5 > SHA1)
checksum := src.PrimaryChecksum()
// checksum.Algorithm = "sha256"
// checksum.Value = "abc123..."
```

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

### Runner Interface for System Commands

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Defines the Runner interface for executing system commands, supporting environment variables and directory context. Includes examples for production usage with RealRunner and testing with FakeRunner.

```go
// Runner is the interface for executing system commands.
type Runner interface {
    Run(name string, args ...string) error
    RunWithEnv(env map[string]string, name string, args ...string) error
    RunInDir(dir string, name string, args ...string) error
    RunInDirWithEnv(dir string, env map[string]string, name string, args ...string) error
    Output(name string, args ...string) (string, error)
}
```

```go
// Production usage with RealRunner
r := &runner.RealRunner{}
err := r.RunInDirWithEnv(
    "/tmp/ruby-3.3.6",
    map[string]string{"CFLAGS": "-O2"},
    "./configure",
    "--prefix=/app/vendor/ruby-3.3.6",
    "--enable-load-relative",
)
```

```go
// Testing with FakeRunner
fake := runner.NewFakeRunner()
fake.OutputMap["ruby --version"] = "ruby 3.3.6"
fake.ErrorMap["make install"] = errors.New("permission denied")

// Execute recipe with fake
recipe.Build(ctx, stack, src, fake, outData)

// Verify calls
assert.Equal(t, "make", fake.Calls[2].Name)
assert.Equal(t, []string{"-j4"}, fake.Calls[2].Args)
assert.Equal(t, "/tmp/ruby-3.3.6", fake.Calls[2].Dir)
```

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

### Depwatcher Data JSON Input Format

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Example of the depwatcher data.json input format used by both Ruby and Go builders. It includes source details and version information, with SHA256 and SHA512 checksums.

```json
{
  "source": { "name": "ruby", "type": "github_releases", "repo": "ruby/ruby" },
  "version": { "url": "https://...", "ref": "3.3.6", "sha256": "...", "sha512": "" }
}
```

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

### Load and Access Stack Configuration

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Demonstrates how to load stack configuration from a file and access its properties like APT packages, compiler details, and bootstrap URLs.

```go
// Loading stack configuration
s, err := stack.Load("stacks", "cflinuxfs4")
if err != nil {
    return fmt.Errorf("loading stack: %w", err)
}

// Access stack-specific values
pkgs := s.AptPackages["ruby_build"]
gfortranBin := s.Compilers.Gfortran.Bin
goBootstrap := s.Bootstrap.Go.URL
```

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

### Build Binary

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Compile the binary-builder tool.

```bash
go build ./cmd/binary-builder
```

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

### Stack Configuration Loading and Access

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Demonstrates how to load stack configurations and access their properties using the Go SDK.

```APIDOC
## Stack Configuration

### Description
Loading and accessing stack-specific configurations like apt packages, compilers, and bootstrap dependencies.

### Method
Go SDK functions

### Endpoint
N/A (Code-based interaction)

### Request Example
```go
// Loading stack configuration
s, err := stack.Load("stacks", "cflinuxfs4")
if err != nil {
    return fmt.Errorf("loading stack: %w", err)
}

// Access stack-specific values
pkgs := s.AptPackages["ruby_build"]
gfortranBin := s.Compilers.Gfortran.Bin
goBootstrap := s.Bootstrap.Go.URL
```

### Response Example
N/A (Code execution results in variables)
```

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

### Execute Binary Builder CLI Commands

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Use direct flags for manual builds or a source JSON file for automated CI/CD workflows.

```bash
# Mode 1: Direct flags (manual/local use)
binary-builder build \
  --stack cflinuxfs4 \
  --name ruby \
  --version 3.3.6 \
  --sha256 abc123... \
  --url https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.gz

# Mode 2: Source file (CI / depwatcher use)
binary-builder build \
  --stack cflinuxfs4 \
  --source-file source/data.json \
  --output-file summary.json
```

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

### Build a binary using direct flags

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Use direct flags for manual or local builds. The --url, --sha256, and --sha512 flags are optional depending on the recipe requirements.

```bash
binary-builder build \
  --stack cflinuxfs4 \
  --name ruby \
  --version 3.3.6 \
  --sha256 <source-tarball-checksum>
```

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

### Run Go Builder Command

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Executes the Go binary-builder command to build a dependency. It requires specifying the stack, source file, stacks directory, and output file for the summary.

```bash
binary-builder build \
  --stack <stack> \
  --source-file /tmp/data.json \
  --stacks-dir /binary-builder/stacks \
  --output-file /out/summary.json
```

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

### Build a binary using a source file

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Use a source file for CI or depwatcher workflows. If the file is omitted, the tool automatically looks for source/data.json in the current directory.

```bash
binary-builder build \
  --stack cflinuxfs4 \
  --source-file source/data.json
```

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

### RepackRecipe with Custom Destination Filename for PyPI sdist

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Configures a repack recipe for 'setuptools' to use a custom destination filename, extracting it from the PyPI URL. This is useful for source distributions (sdist).

```go
// Custom destination filename (for PyPI sdist)
&RepackRecipe{
    DepName:          "setuptools",
    Meta:             ArtifactMeta{OS: "linux", Arch: "noarch", Stack: "any-stack"},
    Fetcher:          f,
    StripTopLevelDir: true,
    DestFilename: func(version, url string) string {
        // Extract filename from PyPI URL
        parts := strings.Split(url, "/")
        return parts[len(parts)-1]
    },
}
```

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

### Autoconf Recipe Engine Implementation

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Provides a hook-based build engine for software using the standard configure/make/make-install cycle. Demonstrates defining a new dependency recipe for libunwind.

```go
// Using autoconf.Recipe for a new dependency
type LibunwindRecipe struct {
    Fetcher fetch.Fetcher
}

func (r *LibunwindRecipe) Name() string { return "libunwind" }
func (r *LibunwindRecipe) Artifact() ArtifactMeta {
    return ArtifactMeta{OS: "linux", Arch: "x64"}
}

func (r *LibunwindRecipe) Build(ctx context.Context, s *stack.Stack, src *source.Input,
    run runner.Runner, out *output.OutData) error {
    return (&autoconf.Recipe{
        DepName: "libunwind",
        Fetcher: r.Fetcher,
        Hooks: autoconf.Hooks{
            AptPackages: func(s *stack.Stack) []string {
                return s.AptPackages["libunwind_build"]
            },
            AfterExtract: func(ctx context.Context, srcDir, prefix string, r runner.Runner) error {
                return r.RunInDir(srcDir, "autoreconf", "-i")
            },
            ConfigureArgs: func(srcDir, prefix string) []string {
                return []string{
                    "--prefix=" + prefix,
                    "--enable-shared",
                    "--disable-static",
                }
            },
            PackDirs: func() []string {
                return []string{"include", "lib"}
            },
        },
    }).Build(ctx, s, src, run, out)
}
```

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

### APT PPA Addition

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Adds a Personal Package Archive (PPA) to the system's sources and updates the package list. Requires an initialized apt.Apt instance.

```go
// Add PPA and update
err = a.AddPPA(ctx, "ppa:ubuntu-toolchain-r/test")
```

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

### Implement Recipe Interface

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

The core Go interface for dependency builders and the registry pattern for managing them.

```go
// Recipe is the interface every dependency builder must implement.
type Recipe interface {
    // Name returns the dependency name (e.g. "ruby", "php").
    Name() string

    // Build performs the full build: download, configure, compile, install, archive.
    // It populates outData with artifact URL, SHA256, and any sub-dependencies.
    Build(ctx context.Context, s *stack.Stack, src *source.Input, r runner.Runner, outData *output.OutData) error

    // Artifact returns the artifact metadata for this recipe.
    Artifact() ArtifactMeta
}

// ArtifactMeta describes the artifact naming for a recipe.
type ArtifactMeta struct {
    OS    string // "linux" or "windows"
    Arch  string // "x64", "noarch", "x86-64"
    Stack string // stack name, "any-stack", or "" (use build stack)
}

// Registry usage
reg := recipe.NewRegistry()
reg.Register(&recipe.RubyRecipe{Fetcher: f})
reg.Register(&recipe.PHPRecipe{Fetcher: f})

rec, err := reg.Get("ruby")
if err != nil {
    log.Fatal(err)
}

err = rec.Build(ctx, stack, sourceInput, runner, outData)
```

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

### Run tests

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Commands for executing unit and parity tests.

```bash
# Unit tests (no Docker or network required)
make unit-test

# Unit tests with race detector
make unit-test-race

# Parity test for a single dep from the matrix (requires Docker + network)
# VERSION is not an argument — each dep runs at the version pinned in run-all.sh.
make parity-test DEP=ruby
make parity-test DEP=php STACK=cflinuxfs4

# To test a specific version not in the matrix, call compare-builds.sh directly
# with a custom data.json:
test/parity/compare-builds.sh --dep php --data-json /tmp/php-8.3.0-data.json --stack cflinuxfs4

# Parity test for all deps
make parity-test-all
```

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

### Build PHP dependencies

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

PHP is built using the same command structure as other dependencies.

```bash
binary-builder build \
  --stack cflinuxfs4 \
  --name php \
  --version 8.1.32 \
  --sha256 <checksum>
```

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

### Access Parsed Source Values

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Demonstrates how to access key information like the dependency name, version, and URL from a parsed source object.

```go
// Access parsed values
fmt.Println(src.Name)    // "node"
fmt.Println(src.Version) // "20.11.0"
fmt.Println(src.URL)     // "https://..."
```

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

### Initialize Build Output Data

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Creates a new 'OutData' structure, which holds information about a build artifact, initialized from parsed source input.

```go
// Initialize from source input
outData := output.NewOutData(src)
```

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

### Monitor build logs

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Tails the log file for a specific dependency build to observe progress in real-time.

```bash
tail -f /tmp/parity-logs/ruby-3.3.6-cflinuxfs4.log
```

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

### Populate Build Output Metadata

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Adds computed SHA256 checksum, artifact URL, and sub-dependency information to the 'OutData' structure before writing metadata.

```go
// Recipe populates additional fields
outData.SHA256 = "computed-artifact-sha256"
outData.URL = "https://buildpacks.cloudfoundry.org/dependencies/ruby/..."
outData.SubDependencies = map[string]output.SubDependency{
    "bundler": {
        Version: "2.5.6",
        Source: &output.SubDepSource{
            URL:    "https://rubygems.org/gems/bundler-2.5.6.gem",
            SHA256: "bundler-sha256",
        },
    },
}
```

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

### Compare Builds for a Single Dependency

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Runs both the Ruby and Go builders for a specific dependency and compares their output. Requires specifying the dependency, data JSON, and stack.

```bash
test/parity/compare-builds.sh --dep ruby --data-json /tmp/ruby-data.json --stack cflinuxfs4
```

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

### Run All Unit Tests

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Executes all unit tests within the project. This is the standard command for running the test suite.

```bash
# Run all unit tests
go test ./... 
```

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

### RepackRecipe for Simple Bower Download

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

A basic repack recipe for the 'bower' dependency, which only requires downloading the artifact without any archive transformations.

```go
// RepackRecipe for bower (simple download)
&RepackRecipe{
    DepName: "bower",
    Meta:    ArtifactMeta{OS: "linux", Arch: "noarch", Stack: "any-stack"},
    Fetcher: f,
}
```

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

### Standard Import Grouping

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Organize imports into three distinct blocks: standard library, third-party, and internal packages.

```go
import (
    // 1. stdlib
    "context"
    "fmt"
    "os"

    // 2. third-party
    "gopkg.in/yaml.v3"
    "github.com/stretchr/testify/assert"

    // 3. internal
    "github.com/cloudfoundry/binary-builder/internal/runner"
    "github.com/cloudfoundry/binary-builder/internal/stack"
)
```

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

### Recipe Interface Definition

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Defines the core `Recipe` interface that all recipes must implement, including methods for naming, building, and artifact metadata.

```go
type Recipe interface {
    Name() string
    Build(ctx context.Context, s *stack.Stack, src *source.Input, r runner.Runner, outData *output.OutData) error
    Artifact() ArtifactMeta  // OS, Arch, Stack ("" = use build stack)
}
```

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

### Execute Unit Tests

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Run tests for all packages or with the race detector enabled.

```bash
go test ./...                  # all packages
go test -race ./...            # with race detector (CI requirement)
```

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

### Parity Test Script Usage

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Use this script to compare builds for parity testing. Specify the dependency name and path to the data JSON file. An optional stack can also be specified.

```bash
test/parity/compare-builds.sh --dep <name> --data-json <path> [--stack <stack>]
```

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

### Run All Parity Tests

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Executes all parity tests for every dependency in the test matrix sequentially. It provides a pass/fail summary and tails failure logs. Requires Docker and network access.

```bash
test/parity/run-all.sh [<stack>]
```

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

### Monitor Parity Build Progress

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Follows the log output for parity build processes in real-time. This is useful for observing the progress of long-running parity tests.

```bash
# Watch build progress
tail -f /tmp/parity-logs/ruby-3.3.6-cflinuxfs4.log
```

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

### Execute Parity Tests

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Run parity tests for specific dependencies or all dependencies, optionally specifying the stack.

```bash
make parity-test DEP=httpd [STACK=cflinuxfs4]
make parity-test-all [STACK=cflinuxfs4]
```

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

### Perform All Dependencies Parity Test

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Runs parity tests for all dependencies defined in the test matrix against the specified stack. This is a comprehensive check for build consistency.

```bash
# All dependencies in test matrix
make parity-test-all STACK=cflinuxfs4
```

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

### Run Package Unit Tests Verbose

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Runs unit tests for a specific package and outputs verbose information during the test execution. Useful for detailed debugging.

```bash
# Run package verbosely
go test -v ./internal/recipe/
```

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

### Parse Build Summary Output

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

The JSON structure generated by the tool containing artifact metadata and source details.

```json
{
  "artifact_path": "ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz",
  "version": "3.3.6",
  "sha256": "abcdef01234567890...",
  "url": "https://buildpacks.cloudfoundry.org/dependencies/ruby/ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz",
  "source": {
    "url": "https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.gz",
    "sha256": "abc123...",
    "sha512": "",
    "md5": null,
    "sha1": null
  },
  "sub_dependencies": {
    "bundler": {
      "version": "2.5.6",
      "source": {
        "url": "https://rubygems.org/gems/bundler-2.5.6.gem",
        "sha256": "..."
      }
    }
  }
}
```

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

### Write Dependency Metadata JSON

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Generates and writes the dependency metadata JSON file. The filename is derived from the artifact name and includes a '_metadata.json' suffix.

```go
// Write dep-metadata JSON
meta := output.NewDepMetadataOutput("/task/dep-metadata")
err := meta.WriteMetadata("ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz", outData)
// Creates: /task/dep-metadata/ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz_metadata.json
```

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

### Run Specific Tests

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Execute individual tests by name, run entire packages verbosely, or apply the race detector to specific packages.

```bash
# By test name (regex) within a package:
go test ./internal/recipe/ -run TestRubyRecipeBuild
go test ./internal/runner/  -run TestFakeRunner
go test ./internal/stack/   -run TestLoad

# Run an entire package verbosely:
go test -v ./internal/recipe/

# Run with race detector for a single package:
go test -race ./internal/recipe/ -run TestHTTPD
```

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

### Perform Single Dependency Parity Test

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Compares the build output of a single specified dependency against the original Ruby builder for parity. Requires specifying the dependency name and stack.

```bash
# Single dependency parity test
make parity-test DEP=ruby STACK=cflinuxfs4
```

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

### Parse Source Input from File

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Reads and parses dependency source information from a JSON file. Assumes the file contains data in either modern or legacy depwatcher JSON format.

```go
// Parse from file
src, err := source.FromFile("source/data.json")
```

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

### PHP Extension Configuration

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Defines base extensions and version-specific patches for PHP builds using YAML configuration files.

```yaml
# internal/php/assets/php8-base-extensions.yml
# Base extensions for PHP 8.x
extensions:
  - name: opcache
    type: native
  - name: redis
    type: pecl
    version: 5.3.7

# internal/php/assets/php83-extensions-patch.yml
# Additions/exclusions for PHP 8.3
add:
  - name: sodium
    type: native
exclude:
  - name: mcrypt
```

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

### Build Canonical Artifact Filename

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Constructs a canonical filename for an artifact, including its name, version, OS, architecture, stack, and SHA256 checksum. This format is used for S3 storage.

```go
// Build canonical filename
a := artifact.Artifact{
    Name:    "ruby",
    Version: "3.3.6",
    OS:      "linux",
    Arch:    "x64",
    Stack:   "cflinuxfs4",
}
filename := a.Filename(sha256hex, "tgz")
// Output: ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz
```

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

### Define Source Input JSON

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

The expected JSON format for dependency source definitions, compatible with depwatcher.

```json
{
  "source": {
    "name": "ruby",
    "type": "github_releases",
    "repo": "ruby/ruby"
  },
  "version": {
    "url": "https://cache.ruby-lang.org/pub/ruby/3.3/ruby-3.3.6.tar.gz",
    "ref": "3.3.6",
    "sha256": "abc123...",
    "sha512": ""
  }
}
```

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

### Build summary JSON structure

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

The structure of the JSON file generated at the path specified by --output-file.

```json
{
  "artifact_path":    "ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz",
  "version":          "3.3.6",
  "sha256":           "abcdef01...",
  "url":              "https://buildpacks.cloudfoundry.org/dependencies/ruby/ruby_3.3.6_...",
  "source":           { "url": "...", "sha256": "...", "sha512": "...", "md5": "...", "sha1": "..." },
  "sub_dependencies": { "bundler": { "version": "2.5.6", "source": { ... } } },
  "git_commit_sha":   "..."
}
```

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

### Run parity comparison for R dependency

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

Executes the parity comparison script for the R dependency, requiring a data JSON file and a directory for sub-dependencies.

```bash
test/parity/compare-builds.sh --dep r --data-json /tmp/r-data.json \
  --sub-deps-dir /tmp/r-sub-deps
```

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

### Parity Test with Custom Data JSON

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Executes a parity test for a specific dependency using a custom JSON file for build data. This allows for testing with specific configurations or versions.

```bash
# Direct script usage with custom data.json
test/parity/compare-builds.sh \
  --dep php \
  --data-json /tmp/php-8.3.0-data.json \
  --stack cflinuxfs4
```

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

### Execute Exerciser Test

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

Run the exerciser test for a specific artifact and stack.

```bash
make exerciser-test ARTIFACT=/tmp/ruby_3.3.6_...tgz STACK=cflinuxfs4
```

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

### Run Unit Tests with Race Detector

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Runs all unit tests while enabling the race detector. This is a CI requirement to catch potential data races in concurrent code.

```bash
# Run with race detector (CI requirement)
go test -race ./... 
```

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

### RepackRecipe for Yarn Download and Archive Stripping

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Defines a repack recipe for the 'yarn' dependency. It specifies downloading the artifact and stripping the top-level directory from the archive. The 'StripVersionPrefix' option removes 'v' from version strings.

```go
// RepackRecipe for yarn (download + strip top-level dir)
&RepackRecipe{
    DepName:            "yarn",
    Meta:               ArtifactMeta{OS: "linux", Arch: "noarch", Stack: "any-stack"},
    Fetcher:            f,
    StripTopLevelDir:   true,
    StripVersionPrefix: "v", // strips "v" from "v1.22.0" -> "1.22.0"
}
```

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

### Run Specific Unit Test by Name

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Executes a specific unit test or a set of tests within a package, identified by a name pattern. Useful for targeted testing.

```bash
# Run specific test by name
go test ./internal/recipe/ -run TestRubyRecipeBuild
```

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

### Depwatcher source file format

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

The standard JSON format expected by the tool when using the --source-file flag.

```json
{
  "source":  { "name": "ruby", "type": "github_releases", "repo": "ruby/ruby" },
  "version": { "url": "https://...", "ref": "3.3.6", "sha256": "...", "sha512": "" }
}
```

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

### Parse Source Input from Bytes

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Parses dependency source information directly from a byte slice containing JSON data. Supports both modern and legacy depwatcher JSON formats.

```go
// Parse from bytes
data := []byte(`{
    "source": {"name": "node", "type": "github_releases", "repo": "nodejs/node"},
    "version": {"url": "https://...", "ref": "20.11.0", "sha256": "..."}
}`)
src, err := source.Parse(data)
```

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

### Compute SHA256 Checksum of Artifact File

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Calculates the SHA256 checksum for a given file. This is essential for verifying file integrity.

```go
// Compute SHA256 of artifact file
sha256hex, err := artifact.SHA256File("/tmp/ruby-3.3.6-linux-x64.tgz")
```

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

### Parity Test for R Dependency with Sub-dependencies

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Performs a parity test for the 'R' dependency, including its sub-dependencies. Requires specifying the dependency, a custom data JSON, and a directory for sub-dependency data.

```bash
# R dependency with sub-deps
test/parity/compare-builds.sh \
  --dep r \
  --data-json /tmp/r-data.json \
  --sub-deps-dir /tmp/r-sub-deps
```

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

### Makefile Targets for Testing

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

These Makefile targets can be used to run various types of tests, including unit tests, race detection tests, parity tests, and exerciser tests.

```makefile
unit-test
```

```makefile
unit-test-race
```

```makefile
parity-test
```

```makefile
exerciser-test
```

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

### Generate Canonical S3 URL for Artifact

Source: https://context7.com/cloudfoundry/binary-builder/llms.txt

Creates a canonical S3 URL for an artifact using its generated filename. Special characters like '+' are URL-encoded to ensure compatibility with AWS.

```go
// Generate S3 URL (encodes + as %2B for AWS compatibility)
url := a.S3URL(filename)
// Output: https://buildpacks.cloudfoundry.org/dependencies/ruby/ruby_3.3.6_linux_x64_cflinuxfs4_abcdef01.tgz
```

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

### Artifact naming convention

Source: https://github.com/cloudfoundry/binary-builder/blob/main/README.md

The canonical filename format used for artifacts written to the current working directory.

```text
<name>_<version>_<os>_<arch>_<stack>_<sha8>.<ext>
```

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

### R Sub-dependency data.json Path

Source: https://github.com/cloudfoundry/binary-builder/blob/main/AGENTS.md

R sub-dependency data.json files are located under a specific directory structure, allowing for granular testing of R packages.

```bash
/tmp/r-sub-deps/source-{pkg}-latest/data.json
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.