From b02140329f64b7152f4c36b807f3f9e8ec3349e5 Mon Sep 17 00:00:00 2001 From: Victor Vogel Date: Sun, 8 Nov 2026 18:11:51 +0000 Subject: [PATCH] tools: print every tool's --help from its header with one helper 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 each edited it. On #287 the maintainer suggested working the range out from the file; #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 (#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 #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 --- tests/all | 9 ++++--- tests/kernel-pr-check | 17 +++---------- tests/tools-help | 55 +++++++++++++++++++++++++++++++++++++++++ tools/build-flame-probe | 2 +- tools/build-packages | 2 +- tools/build-rootfs | 2 +- tools/fetch-published | 2 +- tools/fetch-toolchain | 2 +- tools/install-phone | 3 ++- tools/kernel-pr-check | 2 +- tools/lib/usage.sh | 26 +++++++++++++++++++ tools/make-bundle | 2 +- tools/phone-demo | 2 +- tools/phone-mirror | 2 +- tools/phone-smoke | 2 +- tools/publish-kernel | 2 +- tools/release | 2 +- tools/release-upload | 2 +- tools/repo-publish | 2 +- 19 files changed, 105 insertions(+), 33 deletions(-) create mode 100755 tests/tools-help create mode 100644 tools/lib/usage.sh diff --git a/tests/all b/tests/all index 0f79edbb2..3ee02a1fc 100755 --- a/tests/all +++ b/tests/all @@ -22,13 +22,14 @@ # report's differences on the host, bin/lineage-ref sync's branch handling # against stand-ins for docker and repo, tools/repo-publish --from-main's # copy of the prebuilt binaries into a fixture's publish tree, -# tools/repo-publish's staging, and tools/extract-vendor-firmware's output -# generations (made-up files, no factory image). +# tools/repo-publish's staging, tools/extract-vendor-firmware's output +# generations (made-up files, no factory image), and the tools' --help from +# their header comments (tools/lib/usage.sh). set -euo pipefail cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." for f in tools/install-phone tools/phone-provision tools/nv-backup tools/build-rootfs tools/build-packages tools/make-bundle \ tools/local-key-init tools/fetch-published tools/fetch-toolchain tools/repo-publish tools/repo-build tools/release tools/release-upload tools/server/releases-nginx.sh \ - tools/lib/alarm.sh tools/lib/alarm-setup tools/lib/signing.sh tools/lib/bundle-tar.sh rootfs/build-inside rootfs/resolve.sh tests/*; do + tools/lib/alarm.sh tools/lib/alarm-setup tools/lib/signing.sh tools/lib/bundle-tar.sh tools/lib/usage.sh rootfs/build-inside rootfs/resolve.sh tests/*; do [[ -f $f ]] || continue # tests/owl is the OWL conformance suite's folder [[ $f == *.py ]] && continue bash -n "$f" || { echo "not ok - $f parses" >&2; exit 1; } @@ -40,7 +41,7 @@ sh -n device/flame/initramfs/build bash -n tools/build-flame-probe echo "ok - scripts parse" python3 tests/bt-uart-gpio.py -for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/rootfs-resolve tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/modules-push tests/make-bundle-keys tests/make-bundle tests/release-signing tests/pinned-packages tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release tests/lineage-ref tests/repo-publish tests/repo-publish-stage tests/extract-vendor-firmware; do +for t in tests/pr-check tests/kernel-pr-check tests/phone-smoke tests/alarm-wake-test tests/install-phone tests/build-rootfs tests/rootfs-resolve tests/phone-provision tests/nv-backup tests/initramfs-grow tests/images-layout tests/boot-update-parity tests/stage-boot-files tests/initramfs-reproducible tests/device-overlays tests/simplefb-trigger tests/initramfs-steps tests/storage-guard tests/usb-product tests/boot-method tests/modules-push tests/make-bundle-keys tests/make-bundle tests/release-signing tests/pinned-packages tests/flame-probe packages/omamobile-firstboot/test/all packages/omamobile-device-felix/test/all packages/omamobile-device-lynx/test/all packages/omamobile-device-panther/test/all tests/local-builds tests/phone-install-package tests/publish-kernel tests/fetch-toolchain tests/release-upload tests/extract-camera-data tests/release tests/lineage-ref tests/repo-publish tests/repo-publish-stage tests/extract-vendor-firmware tests/tools-help; do echo "# $t" "$t" done diff --git a/tests/kernel-pr-check b/tests/kernel-pr-check index 079588d51..47457d38c 100755 --- a/tests/kernel-pr-check +++ b/tests/kernel-pr-check @@ -3,26 +3,15 @@ # tools/kernel-pr-check's commit checks against a stand-in kernel tree (a # git repository with a fake scripts/checkpatch.pl): sign-offs, prefixes, # checkpatch errors and warnings, and a checker that is missing or doesn't -# run to the end, and --help. Its device-tree comparison runs against a -# second stand-in whose make prints the messages each board file asks for; -# the real builds (clang, dtc, dt-validate) need a real tree and are run by hand. +# run to the end. Its device-tree comparison runs against a second +# stand-in whose make prints the messages each board file asks for; the +# real builds (clang, dtc, dt-validate) need a real tree and are run by hand. set -euo pipefail here=$(cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." && pwd) t=$(mktemp -d) trap 'rm -rf "$t"' EXIT fail() { echo "not ok - $*" >&2; exit 1; } -# --help prints the whole header comment and no code, from a copy whose -# header has grown by a line: a hard-coded range cut its last line after -# #287, #288 and #310 each edited the header. -h=$t/help/tools/kernel-pr-check -mkdir -p "${h%/*}" -sed '3a\# A line added to the header.' "$here/tools/kernel-pr-check" > "$h" -chmod +x "$h" -diff <("$h" --help) <(sed -n '3,/^set -uo pipefail$/p' "$h" | sed '$d') \ - || fail "--help isn't the header comment, from line 3 to the line before set -uo pipefail" -echo "ok - --help prints the whole header comment, however long it grows, and no code" - k=$t/linux mkdir -p "$k/scripts" "$k/drivers" # checkpatch's stand-in: an ERROR for any added line with "BADSTYLE", a diff --git a/tests/tools-help b/tests/tools-help new file mode 100755 index 000000000..cb27c288f --- /dev/null +++ b/tests/tools-help @@ -0,0 +1,55 @@ +#!/bin/bash +# SPDX-License-Identifier: MIT +# The tools' --help: no tool hard-codes the line range of its header +# comment, and every tool that prints its header with usage_from_header +# (tools/lib/usage.sh), or with the same awk line inline (the tools the +# bundle ships alone), prints all of it, or whole paragraphs from its start, +# and no code, also from a copy whose header has grown by a line. A +# hard-coded range cut the last line of a header that grew and printed code +# after one that shrank (#287). +set -euo pipefail +cd -- "$(dirname -- "${BASH_SOURCE[0]}")/.." +t=$(mktemp -d) +trap 'rm -rf "$t"' EXIT +fail() { echo "not ok - $*" >&2; exit 1; } + +hard=$(grep -s -d skip -lE "sed -n '3,[0-9]+" tools/* || true) +[[ -z $hard ]] || fail "a hard-coded --help range in: ${hard//$'\n'/ }" +echo "ok - no tool hard-codes its --help line range" + +# --help's output, from stdout or stderr (phone-mirror's usage goes to +# stderr and exits 2) +help_of() { "$1" --help 2>&1 || true; } +# The header comment: line 3 up to the first line that isn't a comment +header() { awk 'NR > 2 && !/^#/ { exit } NR > 2' "$1"; } +# whole_paras HELP TEXT: HELP is TEXT, or TEXT's lines up to a blank comment line +whole_paras() { + [[ -n $1 ]] || return 1 + [[ $1 == "$2" ]] && return 0 + [[ $2 == "$1"$'\n'* ]] || return 1 + local rest=${2#"$1"$'\n'} + [[ ${rest%%$'\n'*} =~ ^#?[[:space:]]*$ ]] +} +# is_header FILE HELP: HELP is FILE's header, kept as it is or with "# " off +is_header() { + local h + h=$(header "$1") + whole_paras "$2" "$h" || whole_paras "$2" "$(sed 's/^# \{0,1\}//' <<<"$h")" +} + +mapfile -t tools < <(grep -s -d skip -lE 'usage_from_header|awk .NR > 2 && !/\^#/ \{ exit \}' tools/* || true) +((${#tools[@]})) || fail "no tool prints its header as --help" +mkdir -p "$t/r/tools" +cp -r tools/lib "$t/r/tools/" +for f in "${tools[@]}"; do + out=$(help_of "$PWD/$f") + is_header "$f" "$out" || fail "$f --help isn't its header comment (or whole paragraphs of it)" + g=$t/r/$f + sed '3a\# A line added to the header.' "$f" > "$g" + chmod +x "$g" + grown=$(help_of "$g") + is_header "$g" "$grown" || fail "$f --help isn't its header comment once the header grows by a line" + (($(wc -l <<<"$grown") == $(wc -l <<<"$out") + 1)) \ + || fail "$f --help doesn't follow its header when it grows by a line" +done +echo "ok - ${#tools[@]} tools print their header comment as --help, however long it grows, and no code" diff --git a/tools/build-flame-probe b/tools/build-flame-probe index c4f4ed058..4f05498f9 100755 --- a/tools/build-flame-probe +++ b/tools/build-flame-probe @@ -26,7 +26,7 @@ while (($#)); do --ssh-key) key=${2:?}; shift ;; --mkbootimg) mkbootimg=${2:?}; shift ;; --out) out=${2:?}; shift ;; - -h|--help) sed -n '3,18p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source "$ROOT/tools/lib/usage.sh"; usage_from_header "$0"; exit 0 ;; *) die "unknown argument: $1" ;; esac shift diff --git a/tools/build-packages b/tools/build-packages index fe3e2549f..388e52945 100755 --- a/tools/build-packages +++ b/tools/build-packages @@ -83,7 +83,7 @@ while (($#)); do --resign) resign=1 ;; --import) imports+=("${2:?--import needs a directory}"); shift ;; --local) local_name=${2:?--local needs a device codename}; shift ;; - -h|--help) sed -n '3,33p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0" 2; exit 0 ;; -*) alarm_die "unknown option $1" ;; *) dirs+=("${1%/}") ;; esac diff --git a/tools/build-rootfs b/tools/build-rootfs index b8c0fd06d..43ca1c753 100755 --- a/tools/build-rootfs +++ b/tools/build-rootfs @@ -84,7 +84,7 @@ while (($#)); do --keep-raw) KEEP_RAW=1 ;; --local) LOCAL=${2:?}; shift ;; --channel) CHANNEL=${2:?}; shift ;; - -h|--help) sed -n '3,54p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0"; exit 0 ;; *) alarm_die "unknown argument $1" ;; esac shift diff --git a/tools/fetch-published b/tools/fetch-published index a96ad2d02..824764c75 100755 --- a/tools/fetch-published +++ b/tools/fetch-published @@ -19,7 +19,7 @@ channel=development dir="" while (($#)); do case $1 in --channel) channel=${2:?}; shift ;; - -h|--help) sed -n '3,13p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0"; exit 0 ;; -*) die "unknown option $1" ;; *) [[ -z $dir ]] || die "one DIR only"; dir=$1 ;; esac diff --git a/tools/fetch-toolchain b/tools/fetch-toolchain index 67dea7181..4aeca482f 100755 --- a/tools/fetch-toolchain +++ b/tools/fetch-toolchain @@ -76,7 +76,7 @@ while (($#)); do --lock) lock=${2:?--lock needs a file}; shift ;; --verify) verify=1 ;; --digest) tree_digest "${2:?--digest needs a directory}"; exit ;; - -h|--help) sed -n '3,33p' "$self" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source "$ROOT/tools/lib/usage.sh"; usage_from_header "$self"; exit 0 ;; *) die "unknown argument $1" ;; esac shift diff --git a/tools/install-phone b/tools/install-phone index 0339dca95..28f808952 100755 --- a/tools/install-phone +++ b/tools/install-phone @@ -82,7 +82,8 @@ while (($#)); do --bootloader-slots-match) slots_match=${2:?}; shift ;; --reinstall) reinstall=1 ;; --unsigned) unsigned=1 ;; - -h|--help) sed -n '3,50p' "${BASH_SOURCE[0]}" | sed 's/^# \{0,1\}//'; exit 0 ;; + # Not tools/lib/usage.sh: the bundle ships this file alone, as install + -h|--help) awk 'NR > 2 && !/^#/ { exit } NR > 2 { sub(/^# ?/, ""); print }' "${BASH_SOURCE[0]}"; exit 0 ;; *) die "unknown argument $1 (see --help)" ;; esac shift diff --git a/tools/kernel-pr-check b/tools/kernel-pr-check index 47f94a0ac..cb82011f0 100755 --- a/tools/kernel-pr-check +++ b/tools/kernel-pr-check @@ -69,7 +69,7 @@ while (($#)); do --merge) merge=1; shift ;; --no-checkpatch) checkpatch=0; shift ;; --strict-trailers) shift ;; # no longer stricter; see above - -h|--help) awk 'NR > 2 && !/^#/ { exit } NR > 2' "$self"; exit 0 ;; + -h|--help) source "$repo/tools/lib/usage.sh"; usage_from_header --raw "$self"; exit 0 ;; -*) echo "kernel-pr-check: unknown option $1" >&2; exit 2 ;; *) break ;; esac diff --git a/tools/lib/usage.sh b/tools/lib/usage.sh new file mode 100644 index 000000000..63299f273 --- /dev/null +++ b/tools/lib/usage.sh @@ -0,0 +1,26 @@ +# SPDX-License-Identifier: MIT +# A tool's --help from its own header comment: the comment lines from line 3 +# (after the shebang and the SPDX line) up to the first line that isn't a +# comment. The range comes from the file, so it can't drift from the header +# the way hard-coded line ranges did (#287): a header that gained a line cut +# its last one, and one that lost a line printed code. Tools load it only +# for --help, so a copy of a tool runs without it; the ones the bundle +# ships alone (install-phone, phone-provision, nv-backup) keep the same awk +# line inline. tests/tools-help checks them all. +# +# source tools/lib/usage.sh +# usage_from_header [--raw] FILE [PARAGRAPHS] +# prints FILE's header with each line's "#" and one space after it taken +# off (--raw keeps them). With PARAGRAPHS, only that many paragraphs of +# it (a bare "#" line ends one), for a tool whose help is the first part +# of a longer header. + +usage_from_header() { + local raw=0 + [[ ${1:-} == --raw ]] && { raw=1; shift; } + awk -v raw="$raw" -v paras="${2:-0}" ' + NR <= 2 { next } + !/^#/ { exit } + /^#[ \t]*$/ && ++blank == paras { exit } + { if (!raw) sub(/^# ?/, ""); print }' "${1:?usage_from_header FILE [PARAGRAPHS]}" +} diff --git a/tools/make-bundle b/tools/make-bundle index fd08dec68..375cdfe45 100755 --- a/tools/make-bundle +++ b/tools/make-bundle @@ -67,7 +67,7 @@ while (($#)); do --unsigned) unsigned=1 ;; --label) label=${2:?}; shift ;; --base-url) base_url=${2:?}; shift ;; - -h|--help) sed -n '3,47p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0"; exit 0 ;; *) die "unknown argument $1" ;; esac shift diff --git a/tools/phone-demo b/tools/phone-demo index 3cec85915..8a9721186 100755 --- a/tools/phone-demo +++ b/tools/phone-demo @@ -47,7 +47,7 @@ # person holding the phone will notice. set -uo pipefail -usage() { sed -n '3,12p' "$0" | sed 's/^# \{0,1\}//'; exit "${1:-0}"; } +usage() { source "$(dirname -- "${BASH_SOURCE[0]}")/lib/usage.sh"; usage_from_header "$0" 2; exit "${1:-0}"; } here=0 if [[ ${1:-} == --here ]]; then here=1; shift; fi diff --git a/tools/phone-mirror b/tools/phone-mirror index 05260f30d..3821b4540 100755 --- a/tools/phone-mirror +++ b/tools/phone-mirror @@ -25,7 +25,7 @@ TITLE="Omarchy Mobile phone" PHONE_W=1440 PHONE_H=3120 # the panel in pixels, what wayvnc sends (portrait): read from the phone below KEEP=0 FIT=0 VIEWER= HEIGHT=900 -usage() { sed -n '3,19s/^# \{0,1\}//p' "$0" >&2; exit 2; } +usage() { source tools/lib/usage.sh; usage_from_header "$0" >&2; exit 2; } die() { echo "phone-mirror: $*" >&2; exit 1; } while [[ $# -gt 0 ]]; do case $1 in diff --git a/tools/phone-smoke b/tools/phone-smoke index 3ac3b4925..13784226a 100755 --- a/tools/phone-smoke +++ b/tools/phone-smoke @@ -29,7 +29,7 @@ while (($#)); do --json) json=1 ;; # tests only: the kernel health rows for a saved error log, then exit --errors-from) errors_from=${1:?--errors-from FILE}; shift; here=1 ;; - -h|--help) sed -n '3,21p' "$0"; exit 0 ;; + -h|--help) source "$(dirname -- "${BASH_SOURCE[0]}")/lib/usage.sh"; usage_from_header --raw "$0"; exit 0 ;; *) echo "phone-smoke: unknown option $a" >&2; exit 2 ;; esac done diff --git a/tools/publish-kernel b/tools/publish-kernel index 3f34410da..757b17a4b 100755 --- a/tools/publish-kernel +++ b/tools/publish-kernel @@ -37,7 +37,7 @@ while (($#)); do case $1 in -n|--dry-run) dry=1; shift ;; --tag) tag=${2:?--tag needs a name}; shift 2 ;; - -h|--help) sed -n '3,30p' "$self"; exit 0 ;; + -h|--help) source "$repo/tools/lib/usage.sh"; usage_from_header --raw "$self"; exit 0 ;; -*) echo "publish-kernel: unknown option $1" >&2; echo "$usage" >&2; exit 2 ;; *) break ;; esac diff --git a/tools/release b/tools/release index 148a56e7a..514abe39e 100755 --- a/tools/release +++ b/tools/release @@ -115,7 +115,7 @@ while (($#)); do --dry-run|-n) dry=1 ;; --version) version=${2:?--version needs a value}; shift ;; --kernel-tag) kernel_tag=${2:?--kernel-tag needs a value}; shift ;; - -h|--help) sed -n '3,60p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0" 3; exit 0 ;; -*) die "unknown option $1 (see --help)" ;; *) break ;; esac diff --git a/tools/release-upload b/tools/release-upload index 36ddbb70e..33db26a39 100755 --- a/tools/release-upload +++ b/tools/release-upload @@ -81,7 +81,7 @@ while (($#)); do --verify-only) verify_only=1 ;; --latest) latest=1 ;; --allow-older) allow_older=1 ;; - -h|--help) sed -n '3,61p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0"; exit 0 ;; -*) die "unknown option $1" ;; *) [[ -z $bundle ]] || die "one bundle at a time"; bundle=$1 ;; esac diff --git a/tools/repo-publish b/tools/repo-publish index e87ee3045..89b3646bf 100755 --- a/tools/repo-publish +++ b/tools/repo-publish @@ -70,7 +70,7 @@ while (($#)); do --yes) yes=1 ;; --expect-index) expect_index=${2:?--expect-index needs a SHA-256}; args+=("$expect_index"); shift ;; --remind) remind=1 ;; - -h|--help) sed -n '3,45p' "$0" | sed 's/^# \{0,1\}//'; exit 0 ;; + -h|--help) source tools/lib/usage.sh; usage_from_header "$0"; exit 0 ;; *) die "unknown argument $1" ;; esac shift