build-cran-binaries/local/patches/README.md

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, use:

x <- jsonlite::fromJSON("local/patches/registry.json", simplifyVector = FALSE)

This loads the registry; inspect the structure to verify correctness.