devxy/build-cran-binaries
Watch
1
0
Fork
You've already forked build-cran-binaries
 0
Code Issues 11 Pull requests Releases Activity

fix(patches): validator portability, clearer docs, broader hook trigger

Browse source
This commit is contained in:
Patrick Schratz 2026-06-30 09:17:24 +02:00
commit f3f3bfa20d
Signed by: pat-s
GPG key ID: 3C6318841EF78925
1 changed files with 2428 additions and 8 deletions
Download patch file Download diff file Expand all files Collapse all files

56
.superpowers/handoff/task-B5-report.md Normal file
View file

@ -0,0 +1,56 @@
# 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:
1. **Problem statement:** Compiler/OS-specific build failures in packages like RcppParallel that cascade to all dependents.
2. **Registry location:** Points to `local/patches/registry.json` and references `local/patches/README.md` for the schema.
3. **Two-tier approach:**
- Lightweight overrides (env vars, configure args, Makevars)
- Source diffs (version-pinned, deeper fixes)
4. **Implementation:** Explains that bincraft pre-builds patched binaries and serves them to pak, ensuring transitive dependents receive the fixed package.
5. **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.