Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 4 additions & 3 deletions tests/all
Original file line number Diff line number Diff line change
Expand Up @@ -26,12 +26,13 @@
# tools/repo-publish's staging, tools/extract-vendor-firmware's output
# generations (made-up files, no factory image), the callers of
# tools/alpine-fetch.py stopping when it fails, and its dependency
# resolution against synthetic indexes.
# resolution against synthetic indexes, 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; }
Expand All @@ -43,7 +44,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/grep-q-pipes 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/alpine-fetch-callers tests/alpine-fetch; 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/grep-q-pipes 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/alpine-fetch-callers tests/alpine-fetch tests/tools-help; do
echo "# $t"
"$t"
done
Expand Down
17 changes: 3 additions & 14 deletions tests/kernel-pr-check
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
55 changes: 55 additions & 0 deletions tests/tools-help
Original file line number Diff line number Diff line change
@@ -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"
2 changes: 1 addition & 1 deletion tools/build-flame-probe
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/build-packages
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/build-rootfs
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/fetch-published
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/fetch-toolchain
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
3 changes: 2 additions & 1 deletion tools/install-phone
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/kernel-pr-check
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
26 changes: 26 additions & 0 deletions tools/lib/usage.sh
Original file line number Diff line number Diff line change
@@ -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]}"
}
2 changes: 1 addition & 1 deletion tools/make-bundle
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/phone-demo
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/phone-mirror
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/phone-smoke
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/publish-kernel
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/release
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/release-upload
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
2 changes: 1 addition & 1 deletion tools/repo-publish
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down