56 lines
3 KiB
Markdown
56 lines
3 KiB
Markdown
# 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.
|