build-cran-binaries/local/patches

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:

Rscript local/validate-patches.R

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

Triaging failures into entries

local/failing-builds-report.R turns recorded build failures into triaged patch suggestions instead of hand-scraping Crow logs (issue #115, steps 1 + 2). It is read-only: it queries single_builds WHERE error_occurred, groups failures by a normalised error fingerprint, classifies each group against the known signature set in local/failing-builds-classify.R, and prints a report.

# All platforms/arches; needs the DB password.
PGPASS=... Rscript local/failing-builds-report.R
# Restrict scope and also emit a machine-readable report.
PGPASS=... Rscript local/failing-builds-report.R --platform alpine-321 --arch amd64 --json report.json

Each group is tagged AUTO-PROPOSABLE (a known env/makevars lever, or an already-curated package patch, safe to pre-fill as a registry.json entry) or HUMAN TRIAGE (unknown signature, or a fix that needs a novel source diff). For auto-proposable groups it prints a ready-to-review registry entry; still run validate-patches.R and an isolated trial build before merging. Novel source diffs and unknown signatures stay human-reviewed by design.

Add a new signature by appending a rule to build_signatures() in local/failing-builds-classify.R; the pure helpers are covered by local/tests/test-failing-builds-classify.R.