Skip to content

tools: print every tool's --help from its header with one helper - #559

Merged
derekross merged 2 commits into
derekross:mainfrom
only21mil:build/tools-help-from-header
Nov 9, 2026
Merged

derekross merged 2 commits into
derekross:mainfrom
only21mil:build/tools-help-from-header

Conversation

@only21mil

@only21mil only21mil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor

What and why

Follows #529, now merged, which worked kernel-pr-check's --help range 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 --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 #287, #288 and #310. They now share one helper, tools/lib/usage.sh: usage_from_header FILE prints 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-check moves 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.

Tool Old range Same output
release-upload, fetch-published, make-bundle, repo-publish 3,61p, 3,13p, 3,47p, 3,45p yes
phone-smoke, publish-kernel, kernel-pr-check (--raw) 3,21p, 3,30p, awk yes
phone-mirror usage() 3,19s///p yes
build-packages, phone-demo usage() (first 2 paragraphs) 3,33p, 3,12p yes
fetch-toolchain, build-flame-probe 3,33p, 3,18p no: they printed 2 lines of code after the header
install-phone 3,50p no: it cut --reinstall, --unsigned and the last paragraph
build-rootfs 3,54p no: it cut --channel
release (first 3 paragraphs) 3,60p no: it cut the check-bundle stage

"Same output" is cmp of 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-demo and release show 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-phone keeps the awk line inline, as nv-backup and phone-provision already do: make-bundle ships these three without tools/lib (review lesson L-497). A bundled install --help prints the same as tools/install-phone --help.

tests/tools-help (new, in tests/all) fails if any tool still hard-codes the range. It runs --help on 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 in tests/kernel-pr-check.

Not changed:

  • The tools that pick their help by marker lines (/^# 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.
  • The package scripts that run on the phone. omamobile-boot-images (3,33p, header ends at 31) and omamobile-remote (3,28p, header ends at 30) look off; they could be a follow-up.

tests/all gains tests/tools-help at the end of its loop. Main's #535 has since appended tests/alpine-fetch-callers to the same line, so it conflicts there; keeping both tests resolves it.

Device and build

  • Phone: none: laptop tools only
  • Kernel release (uname -r): n/a
  • Packages changed, with versions: none

Checks (no phone needed)

  • tools/pr-check origin/main passes
  • tests/all passes (456 ok, 0 not ok; the end-to-end, mkbootimg, dtc, lz4, repo-add and rootfs-smoke checks skip on this build machine for lack of those tools)
  • tests/packages passes (or the packages I touched: none)
  • Each changed package has its version bumped, and the new version is in the commit subject (no package changed)
  • Commits have area prefixes and bodies that say why; any AI help is a Co-Authored-By: or Assisted-by: trailer, never a Signed-off-by:

On the phone

  • I ran this on my own phone, booted into this build: n/a, laptop tools only
  • Runbook steps passed (plan, step, result): n/a
  • What I did not test: on a phone. phone-smoke and phone-demo stream themselves to the phone, but they load the helper only on their --help/usage path, which the phone never runs.
  • Nothing in this change writes outside slot B and userdata, weakens the storage guard, or reads registers from userspace (AGENTS.md §1)
tools/phone-smoke report

Not applicable: a laptop-tool change (CONTRIBUTING.md §6.5).

Generated with Claude Opus 5.5 in T3 Code Nightly

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>
@derekross

Copy link
Copy Markdown
Owner

Thank you, Victor. This finishes what #529 started: no more line ranges to
forget, and tests/tools-help will catch the next one. I resolved the
tests/all conflict locally (main's alpine-fetch suites plus yours at the end
of the loop) and ran tests/tools-help and tests/kernel-pr-check on the
result; both pass, so nothing added to main since your base hard-codes a
range. Since the test now runs --help on 17 tools, I also read each tool's
top up to its --help case: none does anything there but set defaults, which
is what I wanted to be sure of.

I'll resolve the conflict when I merge. tools/install-phone will also meet
#576, which rewrites the same --help line to the same awk; I'll keep your
comment above it.

One small thing for later, not for this PR: run from another directory by a
relative path (cd ..; omarchy-mobile/tools/build-packages --help), the
cd-first tools can't find "$0" any more after their cd. Main has the same
bug, so it isn't yours, but usage_from_header would be a good place to fix it
one day.

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>
@derekross
derekross merged commit 0beb824 into derekross:main Nov 9, 2026
2 checks passed
@only21mil

only21mil commented Nov 9, 2026 •

Copy link
Copy Markdown
Contributor Author

Note

🤖 Opus 5.5 replying on behalf of Victor.

The relative-path --help is fixed in #586, in usage_from_header as you suggested: it now reads the tool by name from the tools directory beside the helper, so the eight cd-first tools work from the repository's parent or from tools/ with no call site changed. tests/tools-help now runs every tool's --help from both places and compares the output and exit code with a run from the root.

derekross pushed a commit that referenced this pull request Nov 10, 2026
…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>
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…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>
robertzas pushed a commit to robertzas/omarchy-mobile that referenced this pull request Nov 14, 2026
…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>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants