Task B5 Report: Document the feature in the README

Status

COMPLETED

Section Added

Added ## Patching packages section to README.md after the "Build Process" section (before "Build Environment").

Content

The new section explains:

Problem statement: Compiler/OS-specific build failures in packages like RcppParallel that cascade to all dependents.
Registry location: Points to local/patches/registry.json and references local/patches/README.md for the schema.
Two-tier approach:
- Lightweight overrides (env vars, configure args, Makevars)
- Source diffs (version-pinned, deeper fixes)
Implementation: Explains that bincraft pre-builds patched binaries and serves them to pak, ensuring transitive dependents receive the fixed package.
Design spec link: References specs/2026-06-30-package-patching-design.md.

Verification

Git Diff

+## Patching packages
+
+Some CRAN packages fail to compile on specific platforms due to compiler- or OS-specific issues unrelated to the package itself.
+The canonical example is `RcppParallel`, whose bundled TBB sources fail on musl (Alpine) and newer compiler/OS combinations.
+Because such packages are often transitive dependencies of many others, a single failure cascades: all dependents fail even though nothing is wrong with the dependent itself.
+
+To address this, frequently-failing packages can be "patched" before they are installed — whether as a direct build target or a transitive dependency pulled in by `pak`.
+
+The patch registry lives in `local/patches/registry.json`.
+Each entry specifies a package and the platforms/versions it applies to, along with either lightweight build-time overrides (environment variables, configure arguments, Makevars) or a source diff (for deeper fixes).
+See `local/patches/README.md` for the complete schema.
+
+Patching uses a two-tier approach:
+
+1. **Lightweight overrides:** environment variables, configure arguments, or Makevars settings applied during build — typically version-independent and fast.
+2. **Source diffs:** unified diff patches applied to the unpacked source before building — more powerful but version-pinned.
+
+The system is implemented in `bincraft`: when a package needs patching, `bincraft` pre-builds it with the patch and serves the patched binary to `pak`, ensuring transitive dependents receive the fixed package.
+This way, the fix cascades to all packages that depend on it.
+
+For the design rationale and architecture, see `specs/2026-06-30-package-patching-design.md`.

Linting

markdownlint-cli2: No errors (0 error(s))
Style: Follows existing README conventions (one sentence per line for prose, bullet lists for structure)
Commit: a826a27 docs(patches): document the package patching workflow

Files Modified

/Users/pjs/.t3/worktrees/build-cran-binaries/t3code-6d007901/README.md

Concerns

None. The section is complete, properly placed, lints cleanly, and follows all repository conventions.

3 KiB Raw Blame History