vasilito/RedBear-OS
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0c402cc7388d8d2907dcafc92fd511abbeb06018
RedBear-OS/local/scripts/TOOLS.md
T
vasilito 6d8ef13dc1 LG Gram Round 1: redox-driver-sys stub replacements + doc reference fixes 
Round 1 of the LG Gram 16Z90TP compatibility work. Two parallel
workstreams in one commit:

1. Stub replacements in redox-driver-sys (per project zero-tolerance
   policy):

   - load_dmi_acpi_quirks() (was hardcoded AcpiQuirkFlags::empty()):
     real loader walking a new compiled-in DMI_ACPI_QUIRK_RULES table
     (currently empty — documented why) plus a new [[dmi_acpi_quirk]]
     TOML section parser in toml_loader.rs. The full 16-flag
     ACPI_FLAG_NAMES mapping is added so TOML entries can use any
     AcpiQuirkFlags variant by name.

   - PANEL_ORIENTATION_TABLE (was empty placeholder): populated with
     10 real entries ported from Linux 7.x
     drivers/gpu/drm/drm_panel_orientation.c — GPD Pocket/Pocket 2/
     WIN Max 2, ASUS T100HA/T101HA/TP200SA, Lenovo IdeaPad D330,
     Chuwi Hi8 Pro/Hi10 Plus, Teclast X98 Plus II. Each entry cites
     its Linux source commit.

   - PLATFORM_RULES (kept empty): documented why intentionally empty
     (Linux platform-wide DMI quirks are pre-2020 platform workarounds
     not needed by Red Bear's modern targets).

2. Broken reference fixes after the 2026-07-25 archive
   (commit 589a1044e6 moved 9 docs to legacy-obsolete-2026-07-25/
   but didn't update references). 30+ files referenced the moved
   docs by their old local/docs/<name>.md path. This commit updates
   every reference to point at local/docs/legacy-obsolete-2026-07-25/
   <name>.md so links work again. Files touched: AGENTS.md,
   README.md, docs/{AGENTS,README,07-RED-BEAR-OS-IMPLEMENTATION-PLAN}.md,
   local/AGENTS.md, 14 docs under local/docs/, local/patches/README.md,
   5 scripts under local/scripts/.

The matching acpid+ps2d consumer wiring landed earlier today in
submodule/base commit 45452c5a (force_s2idle, no_legacy_pm1b,
kbd_deactivate_fixup). The bootstrap reference fix is submodule/base
commit 263a41a9. Both are tracked by the updated submodule pointer
in this commit.

Build verification: redox-driver-sys 80 cargo tests pass. acpid/ps2d
host tests not runnable (require cross-compile). Canonical build
attempts uncovered two pre-existing failures unrelated to Round 1:
relibc edition-2024 unsafe-block issue in crtn, and the base fork's
'common' path resolution relies on the build script's overlay
integrity auto-repair which is currently failing. Neither is in code
touched by Round 1.

See local/docs/evidence/lg-gram/ASSESSMENT-2026-07-26.md for the full
round-by-round assessment and next-round plan.
2026-07-26 16:59:32 +09:00

229 lines
10 KiB
Markdown
Raw Blame History

# Red Bear OS — Build System Tools Reference
**Round 14** | **15 tools** | `local/scripts/`
This is the canonical reference for build-system operator tools.
Test scripts (~120) are excluded; see `local/scripts/test-*.sh`
for QEMU/runtime validation helpers.
## Quick Reference
| Tool | Purpose | Example |
|------|---------|---------|
| **patch-status.sh** | Consolidated status report | `./local/scripts/patch-status.sh` (--brief, --json) |
| **sync-versions.sh** | Cat 0+1+2 version sync + lockfile regen | `./local/scripts/sync-versions.sh --check` |
| **verify-patch-content.py** | Orphan patch detection + decision support | `python3 local/scripts/verify-patch-content.py --report action` |
| **verify-fork-versions.sh** | Cat 2 fork supremacy + content check | `./local/scripts/verify-fork-versions.sh` |
| **verify-collision-detection.py** | Config [[files]] vs recipe installs/files collision | `python3 local/scripts/verify-collision-detection.py --strict` |
| **pre-push-checks.sh** | 7-check pre-push safety net (opt-in hook) | `cp local/scripts/pre-push-checks.sh .git/hooks/pre-push` |
| **push-fork-branches.sh** | Operator-reviewed fork push helper | `./local/scripts/push-fork-branches.sh` (--execute) |
| **unblock-base-push.sh** | Base fork deadlock resolver (3 operator paths) | `./local/scripts/unblock-base-push.sh path-a` |
| **commit-msg** | Auto-phase-prefix hook (opt-in) | `cp local/scripts/commit-msg .git/hooks/commit-msg` |
| **build-preflight.sh** | Build-time validation (called by build-redbear.sh) | `./local/scripts/build-preflight.sh --config=redbear-mini` |
| **bump-release.sh** | Canonical release-bump orchestrator | `./local/scripts/bump-release.sh --with-sources --with-external` |
| **check-external-versions.sh** | External desktop-stack version reporter | `./local/scripts/check-external-versions.sh --strict` |
| **bump-graphics-recipes.sh** | Map-driven Qt6/KF6/Plasma recipe bumper | `./local/scripts/bump-graphics-recipes.sh --dry-run` |
| **post-checkout-version-sync.sh** | Auto label-sync on semver branch switch (opt-in hook) | `cp local/scripts/post-checkout-version-sync.sh .git/hooks/post-checkout` |
| **install-git-hooks.sh** | Idempotent opt-in hook installer | `./local/scripts/install-git-hooks.sh --all` |
## Modes and Flags
### patch-status.sh
```
--brief One-line summary: [orph=0/122 col=0 sync=OK fork=OK cargo=OK]
--json Machine-readable JSON
(default) Full text report with fork push status
```
### sync-versions.sh
```
--check Verify only, exit 1 on drift
--regen Apply version sync + regen Cargo.lock files (opt-in)
--dry-run Preview: show what --regen WOULD change, revert after
--no-regen Apply version sync, skip Cargo.lock regen (same as default)
--regen-only Only regenerate Cargo.lock files
(default) Apply version sync only (lockfile regen is opt-in)
```
### verify-patch-content.py
```
--strict Exit 1 on any orphan
--report action Operator-decision suggestions (INTEGRATED/SUPERSEDED/etc.)
--report detail Per-orphan listing with file paths
--selftest 5 regression test cases
(default) Per-component summary
```
### verify-collision-detection.py
```
--strict Exit 1 on any collision
--selftest 8 regression test cases
(default) Per-config summary
```
### verify-fork-versions.sh
```
REDBEAR_SKIP_FORK_VERIFY=1 Skip entirely
REDBEAR_STRICT_DIVERGED_CHECK=1 Treat diverged as ERROR
(default) Diverged = WARN (advisory)
```
### pre-push-checks.sh
```
--soft Warn-only, don't block push
(default) Block push on any check failure
```
### push-fork-branches.sh
```
--execute Actually push (default = print-only with 5-second abort)
(default) Show status + commands
```
### bump-release.sh (canonical release-bump orchestrator)
`bump-release.sh` is the single entry point for a Red Bear OS release bump.
It DECIDES what needs to move (per-fork routing, external group) and
DELEGATES execution to existing single-purpose tools (`sync-versions.sh`
for label rewrites, `upgrade-forks.sh --to=<tag>` for source rebases,
`bump-graphics-recipes.sh` for the desktop stack). It never duplicates sed
logic and never auto-commits. See `local/docs/RELEASE-BUMP-WORKFLOW.md`
for the full runbook and decision tree.
```
(no args) Label sync (sync-versions.sh --no-regen) + fork upstream
REPORT. Fast, local + cached network. (The post-checkout
hook calls sync-versions.sh --no-regen directly — not this
script. External version report is only via --with-external
or a standalone check-external-versions.sh run.)
--with-sources Additionally perform fork source bumps for eligible
forks (mode snapshot/tracked, newer upstream semver tag)
via upgrade-forks.sh --to=<tag>, then re-sync labels and
update local/fork-upstream-map.toml column 3 in place.
--with-external Additionally run the rewritten bump-graphics-recipes.sh
for the Qt6/KF6/Plasma desktop stack (group-coherent).
--check Read-only: report drift + upgradeable-found; exit 1 if
any. CI-friendly.
--dry-run Print intended changes only; no file mutations.
--no-fetch Use cached upstream lookups; no network.
--regen Also regenerate Cargo.lock files (sync-versions.sh --regen).
--force-diverged Allow source-bump attempts on `diverged` forks
(kernel/bootloader/installer). Default = report-only.
--fork=<name> Scope to a single fork (e.g. --fork=relibc).
```
Map input: `local/fork-upstream-map.toml` (columns: name, url, tag, mode).
Never auto-commits. Prints exact commit commands (parent repo + the
relevant `submodule/<fork>` branch) for the operator to run.
### check-external-versions.sh (external desktop-stack version reporter)
Reads `local/external-upstream-map.toml` (`[groups.*]` for Qt6/KF6/Plasma
and `[packages.*]` for singletons like mesa/libdrm/libwayland/sddm) and
resolves the latest published version per group/package. Index fetches are
cached under `.redbear-recipe-bump/` so `--no-fetch` can reuse a prior run.
```
(no args) Print table: name current latest CURRENT|OUTDATED.
Exit 0 always (report).
--strict Exit 1 if any package is OUTDATED.
--no-fetch Reuse cached index from .redbear-recipe-bump/.
--json Emit machine-readable JSON instead of a table.
```
### bump-graphics-recipes.sh (rewritten, map-driven)
Map-driven recipe bumper for the external desktop stack. Driven by
`local/external-upstream-map.toml`. Group version resolved ONCE per group
(Qt6/KF6/Plasma); per-recipe realpath dedup (symlinked recipes bumped
exactly once). tar sources: download → `b3sum` → sed `tar =` + `blake3 =`
(+ sync `[package] version =` if semver-mismatched). git-rev sources:
`git ls-remote --tags` → latest tag commit sha → sed `rev =`.
```
(no args) Apply bumps; run `repo validate-patches` per recipe;
write stabilization report to
.redbear-recipe-bump/last-report.txt.
--dry-run Print intended changes only (recipe= old= new=).
--no-fetch Reuse cached tarballs / index from .redbear-recipe-bump/.
```
Report format (one line per evaluated recipe):
`recipe= old= new= patches_total= patches_pass= patches_fail= fail_details=`
Never commits. Never removes a recipe for failing validation (per AGENTS.md
ABSOLUTE RULE) — failures land in the report for the stabilization phase.
### post-checkout-version-sync.sh (opt-in hook)
```
(installed as .git/hooks/post-checkout)
(no args) On semver branch switch with clean tree: run
sync-versions.sh --no-regen (labels only). Always
exits 0.
REDBEAR_NO_AUTO_SYNC=1 Bypass for a single checkout.
```
Guards: `$3==1`, anchored semver branch, no rebase/cherry-pick/merge in
progress, `REDBEAR_NO_AUTO_SYNC` unset, clean tree. Never network, never
regen, never commit. See `local/docs/legacy-obsolete-2026-07-25/HOOKS.md`.
### install-git-hooks.sh (hook installer)
```
(no args) Install post-checkout only (default, least surprise).
--all Also install pre-push-checks.sh and commit-msg.
--uninstall Remove installed hooks (restores .bak if present).
--uninstall --all Remove the full --all set.
```
Idempotent: up-to-date installs are no-ops; differing existing hooks are
backed up to `<name>.bak` (rotated) before overwrite.
## Where each tool runs
```
build-preflight.sh
├── sync-versions.sh --check
├── verify-fork-versions.sh
├── verify-patch-content.py
└── verify-collision-detection.py
pre-push-checks.sh (opt-in git hook)
├── sync-versions.sh --check
├── verify-fork-versions.sh
├── verify-patch-content.py
├── verify-patch-content.py --report action
├── verify-patch-content.py --selftest
├── verify-collision-detection.py
└── verify-collision-detection.py --selftest
post-checkout-version-sync.sh (opt-in git hook)
└── sync-versions.sh --no-regen (label-only; NEVER --regen)
bump-release.sh (canonical release-bump orchestrator)
├── sync-versions.sh --no-regen (labels)
├── update_map_tag_inplace() (in-script map column-3 update;
│ refresh-fork-upstream-map.sh is a
│ standalone complement that also
│ appends missing fork rows)
├── upgrade-forks.sh --to=<tag> (source bumps, --with-sources)
└── bump-graphics-recipes.sh (desktop stack, --with-external)
└── repo validate-patches <recipe>
install-git-hooks.sh (operator opt-in hook installer)
└── cp into .git/hooks/{post-checkout,pre-push,commit-msg}
```
## See also
- `local/docs/legacy-obsolete-2026-07-25/HOOKS.md` — git hooks documentation
- `local/docs/RELEASE-BUMP-WORKFLOW.md` — release-bump operator runbook
- `local/docs/legacy-obsolete-2026-07-25/PATCH-PRESERVATION-AUDIT-2026-07-12.md` — cumulative rounds 0-12
- `local/fork-upstream-map.toml` — fork → upstream tag/mode map
- `local/external-upstream-map.toml` — external desktop-stack version map
- `local/patches/README.md` — patch archive structure
---
**Last updated:** 2026-07-18 (Round 14 — release-bump pipeline)
Reference in New Issue View Git Blame Copy Permalink