Repository navigation
tools: print every tool's --help from its header with one helper - #559
Conversation
Fourteen tools printed --help as a hard-coded line range of their header comment (sed -n '3,NNp'), the pattern that cut kernel-pr-check's header after derekross#287, derekross#288 and derekross#310 each edited it. On derekross#287 the maintainer suggested working the range out from the file; derekross#529 did that for kernel-pr-check alone. This moves all of them onto one helper, tools/lib/usage.sh: usage_from_header prints the comment lines from line 3 up to the first line that isn't a comment (derekross#529's awk line), with "# " taken off or, with --raw, kept. Tools load it only for --help, so the copies the tests make of a tool, with only the lib files it needs, still run. kernel-pr-check moves onto it too. Ten tools print byte for byte what they printed before (cmp of stdout, stderr and exit status, and of phone-demo's and phone-mirror's error usage). Five ranges were already wrong, and print the header now: fetch-toolchain and build-flame-probe printed two lines of code after it; install-phone cut --reinstall, --unsigned and its last paragraph, build-rootfs cut --channel, and release cut its check-bundle stage. build-packages, phone-demo and release print only the start of a longer header, so the helper takes a paragraph count (a bare "#" line ends one) and their output stays what the range meant. install-phone keeps the awk line inline, as nv-backup and phone-provision already do: make-bundle ships these three alone, without tools/lib (review lesson L-497). tests/tools-help fails if any tool still hard-codes the range, and runs --help on every tool that prints its header (the helper's users and the three inline ones): it must print the header, or whole paragraphs from its start, and no code, and a copy whose header has grown by a line must print that line too. It replaces derekross#529's single-tool check in tests/kernel-pr-check. On the base it fails on the range check, and the per-tool check fails for 13 of the 15 tools. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Thank you, Victor. This finishes what #529 started: no more line ranges to I'll resolve the conflict when I merge. One small thing for later, not for this PR: run from another directory by a |
tests/all keeps every suite: main's (alpine-fetch-callers, alpine-fetch, grep-q-pipes and the rest) and this branch's tools-help. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|
Note 🤖 Opus 5.5 replying on behalf of Victor. The relative-path |
…ory (#586) Run by a relative path from somewhere other than the repository root (cd ..; omarchy-mobile/tools/build-packages --help, or ./release --help from tools/), the eight tools that cd to the repository before they read their options failed --help: they passed "$0", which is relative to the directory they had just left, and awk couldn't open it (exit 2). Derek pointed this out on #559 and suggested usage_from_header as the place to fix it. usage_from_header now takes only FILE's name and reads that tool from the tools directory above tools/lib/usage.sh. The helper's own path is still valid when it runs, because every caller has just sourced it from its current directory, so this fixes all eight callers in one place with no call site changed. The tools that resolve their own path first (fetch-toolchain, kernel-pr-check, publish-kernel) or don't cd before --help (build-flame-probe, phone-smoke, phone-demo), and the bundle's inline-awk tools (install-phone, nv-backup, phone-provision), already worked; their files are unchanged. phone-smoke and phone-demo still load the helper only on the help path. tests/tools-help now runs every tool's --help from the repository's parent and from tools/ by a relative path and compares the output and exit code with a run from the root. On main it fails at tools/build-packages. --help from the root is byte-identical before and after for all 17 tools (16 exit 0, phone-mirror exit 2). Tested: tests/tools-help, tools/pr-check origin/main, tests/kernel-pr-check, tests/install-phone, tests/make-bundle, and tests/all, which passes except tests/release-upload. That suite fails the same way on main because the worktree path contains "/.". Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
…ekross#559) Fourteen tools printed --help as a hard-coded line range of their header comment (sed -n '3,NNp'), the pattern that cut kernel-pr-check's header after derekross#287, derekross#288 and derekross#310 each edited it. On derekross#287 the maintainer suggested working the range out from the file; derekross#529 did that for kernel-pr-check alone. This moves all of them onto one helper, tools/lib/usage.sh: usage_from_header prints the comment lines from line 3 up to the first line that isn't a comment (derekross#529's awk line), with "# " taken off or, with --raw, kept. Tools load it only for --help, so the copies the tests make of a tool, with only the lib files it needs, still run. kernel-pr-check moves onto it too. Ten tools print byte for byte what they printed before (cmp of stdout, stderr and exit status, and of phone-demo's and phone-mirror's error usage). Five ranges were already wrong, and print the header now: fetch-toolchain and build-flame-probe printed two lines of code after it; install-phone cut --reinstall, --unsigned and its last paragraph, build-rootfs cut --channel, and release cut its check-bundle stage. build-packages, phone-demo and release print only the start of a longer header, so the helper takes a paragraph count (a bare "#" line ends one) and their output stays what the range meant. install-phone keeps the awk line inline, as nv-backup and phone-provision already do: make-bundle ships these three alone, without tools/lib (review lesson L-497). tests/tools-help fails if any tool still hard-codes the range, and runs --help on every tool that prints its header (the helper's users and the three inline ones): it must print the header, or whole paragraphs from its start, and no code, and a copy whose header has grown by a line must print that line too. It replaces derekross#529's single-tool check in tests/kernel-pr-check. On the base it fails on the range check, and the per-tool check fails for 13 of the 15 tools. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Derek Ross <derekross@gmail.com>
…ory (derekross#586) Run by a relative path from somewhere other than the repository root (cd ..; omarchy-mobile/tools/build-packages --help, or ./release --help from tools/), the eight tools that cd to the repository before they read their options failed --help: they passed "$0", which is relative to the directory they had just left, and awk couldn't open it (exit 2). Derek pointed this out on derekross#559 and suggested usage_from_header as the place to fix it. usage_from_header now takes only FILE's name and reads that tool from the tools directory above tools/lib/usage.sh. The helper's own path is still valid when it runs, because every caller has just sourced it from its current directory, so this fixes all eight callers in one place with no call site changed. The tools that resolve their own path first (fetch-toolchain, kernel-pr-check, publish-kernel) or don't cd before --help (build-flame-probe, phone-smoke, phone-demo), and the bundle's inline-awk tools (install-phone, nv-backup, phone-provision), already worked; their files are unchanged. phone-smoke and phone-demo still load the helper only on the help path. tests/tools-help now runs every tool's --help from the repository's parent and from tools/ by a relative path and compares the output and exit code with a run from the root. On main it fails at tools/build-packages. --help from the root is byte-identical before and after for all 17 tools (16 exit 0, phone-mirror exit 2). Tested: tests/tools-help, tools/pr-check origin/main, tests/kernel-pr-check, tests/install-phone, tests/make-bundle, and tests/all, which passes except tests/release-upload. That suite fails the same way on main because the worktree path contains "/.". Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
What and why
Follows #529, now merged, which worked
kernel-pr-check's--helprange out from the file as suggested on #287 ("working the range out from the file would end this for good"); on #529 the shared helper for the other tools was welcomed as its own PR.Fourteen tools printed
--helpas a hard-coded line range of their header comment (sed -n '3,NNp'), the pattern that cutkernel-pr-check's header after #287, #288 and #310. They now share one helper,tools/lib/usage.sh:usage_from_header FILEprints the comment lines from line 3 up to the first line that isn't a comment (#529's awk line), with#taken off, or kept with--raw.kernel-pr-checkmoves onto it too. Tools load it only for--help, so the copies the tests make of a tool (with only the lib files it needs) still run.3,61p,3,13p,3,47p,3,45p--raw)3,21p,3,30p, awkusage()3,19s///pusage()(first 2 paragraphs)3,33p,3,12p3,33p,3,18p3,50p--reinstall,--unsignedand the last paragraph3,54p--channel3,60pcheck-bundlestage"Same output" is
cmpof stdout, stderr and exit status, before and after, and also of phone-demo's and phone-mirror's error usage. The five that change only lose code or gain header lines.build-packages,phone-demoandreleaseshow only the start of a longer header, so the helper takes a paragraph count (a bare#line ends one) and their output stays what the range meant. If you'd rather they print the whole header, drop the count.install-phonekeeps the awk line inline, asnv-backupandphone-provisionalready do:make-bundleships these three withouttools/lib(review lesson L-497). A bundledinstall --helpprints the same astools/install-phone --help.tests/tools-help(new, intests/all) fails if any tool still hard-codes the range. It runs--helpon every tool that prints its header and checks that it prints the header, or whole paragraphs from its start, and no code, and that a copy whose header grew by a line prints that line too. On the base the range check fails; on the candidate, the per-tool check covers the 17 helper and inline-header users and passes. It replaces #529's single-tool check intests/kernel-pr-check.Not changed:
/^# Usage:/,/^# …/: acpm-stage, aoc-stage, camera-stage, display-hz, fingerprint-capture, husky-deadman, usbc-deadman, wifi-w1-capture, power-ab). They start mid-header, so the helper would change their output.omamobile-boot-images(3,33p, header ends at 31) andomamobile-remote(3,28p, header ends at 30) look off; they could be a follow-up.tests/allgainstests/tools-helpat the end of its loop. Main's #535 has since appendedtests/alpine-fetch-callersto the same line, so it conflicts there; keeping both tests resolves it.Device and build
uname -r): n/aChecks (no phone needed)
tools/pr-check origin/mainpassestests/allpasses (456 ok, 0 not ok; the end-to-end, mkbootimg, dtc, lz4,repo-addand rootfs-smoke checks skip on this build machine for lack of those tools)tests/packagespasses (or the packages I touched: none)versionbumped, and the new version is in the commit subject (no package changed)Co-Authored-By:orAssisted-by:trailer, never aSigned-off-by:On the phone
phone-smokeandphone-demostream themselves to the phone, but they load the helper only on their--help/usage path, which the phone never runs.userdata, weakens the storage guard, or reads registers from userspace (AGENTS.md §1)tools/phone-smokereportNot applicable: a laptop-tool change (CONTRIBUTING.md §6.5).
Generated with Claude Opus 5.5 in T3 Code Nightly