# Patch Registry

This directory contains the curated registry of per-package build-time patches consumed by bincraft's `patches` argument.

## Schema

The registry is defined in `registry.json` as an array of patch entries. Each entry specifies lightweight build-time overrides (environment variables, configure arguments, Makevars) and optionally a source diff to apply before building.

### Field semantics

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `package` | string | yes | CRAN package name. |
| `versions` | string | yes | `"*"` for any, a constraint such as `">=5.1.0"`, or an exact version `"5.1.11-2"`. Env-tier fixes are typically `"*"`; source diffs are normally exact or lower-bounded because a diff is pinned to the source it was generated against. |
| `platforms` | array of strings | yes | Matched against the running build's platform tokens — distro family (`alpine`, `ubuntu`, `redhat`), codename (`ubuntu-2604`, `alpine-324`), and arch (`amd64`, `arm64`). An entry matches if any listed token matches any build token. `["*"]` matches all platforms. |
| `env` | object | no | Environment variables exported only for this package's isolated build. |
| `configure_args` | array | no | Arguments passed as `--configure-args` to the isolated build. |
| `makevars` | object | no | Key/value pairs written into a package-local Makevars for the isolated build. |
| `patch` | string or null | no | Path (relative to `local/patches/`) to a unified diff applied to the unpacked CRAN source before building. |
| `reason` | string | yes | Human explanation, surfaced in logs and metadata. |

## Adding an entry

To add a new patch entry:

1. Add an object to the array in `registry.json` with the fields documented above.
   Start with lightweight overrides (environment variables, configure arguments, Makevars) before resorting to source diffs.

2. If a source diff is needed, place it in `local/patches/<package>/<file>.patch` and reference its path in the `patch` field.
   For example, a diff for `RcppParallel` would go in `local/patches/RcppParallel/fix.patch` and be referenced as `"patch": "RcppParallel/fix.patch"`.

3. The `reason` field should clearly explain why the patch is needed and what problem it solves.

## Validation

The registry is validated and applied by bincraft during the build process.
For manual validation, run the validator from the repo root:

```bash
Rscript local/validate-patches.R
```

This validates the schema, referenced patch-file existence, and checks for duplicate entries across platforms and versions.