commit 15f53482a61de6b6c43f85d1845e53b580e9080f
parent f73b0ab8419d3e2781fc654d0e107a2206e719d8
Author: Ryan Sepassi <rsepassi@gmail.com>
Date: Thu, 16 Jul 2026 11:24:52 -0700
Simplify help examples to use kit from PATH
Diffstat:
10 files changed, 77 insertions(+), 76 deletions(-)
diff --git a/driver/cmd/addr2line.c b/driver/cmd/addr2line.c
@@ -103,16 +103,15 @@ void driver_help_addr2line(void) {
" -h, --help show this help\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " SDK=$(\"$K\" cc -print-sysroot)\n"
+ " SDK=$(kit cc -print-sysroot)\n"
" printf 'int main(void) { return 0; }\\n' > debug.c\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -isysroot \"$SDK\" "
+ " kit cc -isysroot \"$SDK\" "
"-g -no-pie debug.c -o debug-app\n"
- " \"$K\" nm -n debug-app\n"
- " ADDR=$(\"$K\" nm -n debug-app | awk '$3 == \"main\" || "
+ " kit nm -n debug-app\n"
+ " ADDR=$(kit nm -n debug-app | awk '$3 == \"main\" || "
"$3 == \"_main\" { print $1; exit }')\n"
- " \"$K\" addr2line -a -f -p -e debug-app \"0x$ADDR\"\n"
- " printf '%s\\n' \"$ADDR\" | \"$K\" addr2line -f -e debug-app\n"
+ " kit addr2line -a -f -p -e debug-app \"0x$ADDR\"\n"
+ " printf '%s\\n' \"$ADDR\" | kit addr2line -f -e debug-app\n"
"\n"
"EXIT CODES\n"
" 0 success 1 debug/object or I/O error\n"
diff --git a/driver/cmd/build.c b/driver/cmd/build.c
@@ -2649,15 +2649,14 @@ void driver_help_build_exe(void) {
" the discovered SDK by default. Hosted cross builds require --sysroot.\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " \"$K\" build-exe main.c util.c -o app\n"
+ " kit build-exe main.c util.c -o app\n"
"\n"
" # Flag-scoped C groups plus an assembly source.\n"
- " \"$K\" build-exe --group -DLEFT=20 -- left.c \\\n"
+ " kit build-exe --group -DLEFT=20 -- left.c \\\n"
" --group -DRIGHT=22 -- right.c main.c helper.s -o grouped\n"
"\n"
" # Freestanding: provide startup code and a linker script.\n"
- " \"$K\" build-exe --support-dir \"$DIST/support\" \\\n"
+ " kit build-exe \\\n"
" -target aarch64-none-elf -T link.ld -e _start \\\n"
" start.s kernel.c -o kernel.elf\n"
"\n"
@@ -2710,13 +2709,12 @@ void driver_help_build_lib(void) {
" -dynamic/-shared is ELF-only.\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " \"$K\" build-lib --support-dir \"$DIST/support\" \\\n"
+ " kit build-lib \\\n"
" -o libanswer.a answer.c helper.s\n"
"\n"
" # Replace SYSROOT with a supplied x86-64 Linux sysroot.\n"
" SYSROOT=/replace/with/x86_64-linux-sysroot\n"
- " \"$K\" build-lib --support-dir \"$DIST/support\" \\\n"
+ " kit build-lib \\\n"
" -target x86_64-linux-gnu --sysroot \"$SYSROOT\" \\\n"
" -dynamic -fPIC -o libanswer.so answer.c\n"
"\n"
@@ -2778,17 +2776,16 @@ void driver_help_build_obj(void) {
" -O0 semantic pipeline; -O1/-O2 are accepted and normalized to -O0.\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" main.c\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" \\\n"
+ " kit build-obj main.c\n"
+ " kit build-obj \\\n"
" main.c helper.c -o combined.o\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" \\\n"
+ " kit build-obj \\\n"
" --emit=asm source.c -o source.s\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" \\\n"
+ " kit build-obj \\\n"
" --emit=c -O0 source.c -o portable.c\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" \\\n"
+ " kit build-obj \\\n"
" --emit=ir -O1 source.c -o source.ir\n"
- " \"$K\" build-obj --support-dir \"$DIST/support\" \\\n"
+ " kit build-obj \\\n"
" -fsyntax-only -I include source.c\n"
"\n"
"EXIT CODES\n"
diff --git a/driver/cmd/build_coord.c b/driver/cmd/build_coord.c
@@ -100,8 +100,7 @@ void driver_help_build(void) {
" $KIT_BUILD_OUT. It receives a clean environment containing\n"
" KIT_BUILD_SOCK, KIT_BUILD_OUT, KIT_BUILD_TARGET, KIT_BUILD_REPO,\n"
" KIT_BUILD_PACKAGE, and KIT_BUILD_LOCAL, plus values explicitly\n"
- " propagated with --env/--config env.NAME. `KIT` is not built in; the\n"
- " example propagates it so the recipe can call the same Kit binary.\n"
+ " propagated with --env/--config env.NAME.\n"
"\n"
" Recipe-only `source` records a source dependency and prints its CAS\n"
" materialization path or requested id form. `need` records another\n"
@@ -132,17 +131,14 @@ void driver_help_build(void) {
driver_printf(
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
" mkdir -p demo/recipes\n"
- " printf 'input from source\\n' > demo/input.txt\n"
" printf '%%s\\n' 'kit-build 1' '[target copy]' \\\n"
" 'recipe recipes/copy.sh' > demo/BUILD.kit\n"
" printf '%%s\\n' '#!/bin/sh' 'set -eu' \\\n"
- " 'source_path=$(\"$KIT\" build source input.txt)' \\\n"
- " '/bin/cp \"$source_path\" \"$KIT_BUILD_OUT/result.txt\"' \\\n"
+ " 'printf \"%%s\\n\" built > \"$KIT_BUILD_OUT/result.txt\"' \\\n"
" > demo/recipes/copy.sh\n"
" chmod +x demo/recipes/copy.sh\n"
- " \"$K\" build --root \"$PWD/demo\" --env KIT=\"$K\" \\\n"
+ " kit build --root \"$PWD/demo\" \\\n"
" --verify --stats copy\n"
" # Repeat the same command to observe a cache hit.\n"
"\n"
diff --git a/driver/cmd/cc.c b/driver/cmd/cc.c
@@ -280,28 +280,26 @@ void driver_help_cc(void) {
" --version Show Kit version and exit\n"
"\n"
"EXAMPLES\n"
- " # Native macOS: support and the SDK are discovered automatically.\n"
- " DIST=\"$PWD/kit\"\n"
- " K=\"$DIST/bin/kit\"\n"
+ " # Native compile.\n"
" printf 'int main(void) { return 0; }\\n' > hello.c\n"
- " \"$K\" cc hello.c -o hello\n"
+ " kit cc hello.c -o hello\n"
" ./hello\n"
"\n"
" # Replace SYSROOT with a supplied hosted cross sysroot.\n"
" SYSROOT=/replace/with/aarch64-linux-sysroot\n"
- " \"$K\" cc -target aarch64-linux-gnu --sysroot \"$SYSROOT\" \\\n"
+ " kit cc -target aarch64-linux-gnu --sysroot \"$SYSROOT\" \\\n"
" hello.c -o hello.aa64\n"
"\n"
" # Freestanding final link; provide startup object and linker script.\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -target aarch64-none-elf \\\n"
+ " kit cc -target aarch64-none-elf \\\n"
" -ffreestanding -c kernel.c -o kernel.o\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -target aarch64-none-elf \\\n"
+ " kit cc -target aarch64-none-elf \\\n"
" -ffreestanding -T link.ld -e _start start.o kernel.o -o kernel.elf\n"
"\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -E -DVALUE=42 input.c\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -MM input.c -MF input.d\n"
- " \"$K\" cc --support-dir \"$DIST/support\" --emit=c -O0 input.c -o input.out.c\n"
- " \"$K\" cc --support-dir \"$DIST/support\" --emit=ir -O1 input.c -o input.ir\n"
+ " kit cc -E -DVALUE=42 input.c\n"
+ " kit cc -MM input.c -MF input.d\n"
+ " kit cc --emit=c -O0 input.c -o input.out.c\n"
+ " kit cc --emit=ir -O1 input.c -o input.ir\n"
"\n"
"EXIT CODES\n"
" 0 success 1 compile/link/I/O error 2 bad usage\n")));
@@ -337,8 +335,7 @@ void driver_help_check(void) {
" --version Show Kit version and exit\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/kit\"\n"
- " \"$DIST/bin/kit\" check --support-dir \"$DIST/support\" \\\n"
+ " kit check \\\n"
" -I include -DDEBUG=1 src/main.c src/util.c\n"
"\n"
"EXIT CODES\n"
diff --git a/driver/cmd/gram.c b/driver/cmd/gram.c
@@ -131,23 +131,9 @@ void driver_help_gram(void) {
" printf '%s\\n' 'start = \"hello\";' > grammar.ebnf\n"
" kit gram --dump-sexpr grammar.ebnf\n"
"\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " \"$K\" gram -o lexer.c --header lexer.h --prefix demo grammar.ebnf\n"
- " \"$K\" gram --lexer-standalone --parser-codegen \\\n"
+ " kit gram -o lexer.c --header lexer.h --prefix demo grammar.ebnf\n"
+ " kit gram --lexer-standalone --parser-codegen \\\n"
" -o parser.c --header parser.h --prefix demop grammar.ebnf\n"
- " printf '%s\\n' '#include \"parser.h\"' '#include <stdio.h>' \\\n"
- " 'int main(void) {' \\\n"
- " ' size_t ctl = 0, vals = 0;' \\\n"
- " ' demopstack_bounds(8, &ctl, &vals);' \\\n"
- " ' printf(\"tokens=%d rules=%d control=%zu values=%zu scratch=%zu\\n\",' \\\n"
- " ' DEMOPTOK__COUNT, DEMOPR__COUNT, ctl, vals,' \\\n"
- " ' demopgenerate_scratch_count());' \\\n"
- " ' return ctl == 0 || vals == 0;' '}' > main.c\n"
- " SDK=\"$(\"$K\" cc -print-sysroot)\"\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -isysroot \"$SDK\" \\\n"
- " -I \"$DIST/include\" -I . main.c lexer.c parser.c \\\n"
- " \"$DIST/lib/libkit.a\" -o generated-parser\n"
- " ./generated-parser\n"
"\n"
"EXIT CODES\n"
" 0 success 1 compile / I/O error 2 bad usage\n")));
diff --git a/driver/cmd/image.c b/driver/cmd/image.c
@@ -116,23 +116,22 @@ void driver_help_image(void) {
"\n"
"EXAMPLES\n"
" # Build a minimal aarch64 freestanding linked image.\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
" printf '.global _start\\n.text\\n_start:\\n b _start\\n' > start.s\n"
" printf 'ENTRY(_start)\\nSECTIONS { . = 0x400000; .text : { "
"*(.text*) } }\\n' > link.ld\n"
- " \"$K\" as -target aarch64-none-elf -o start.o start.s\n"
- " \"$K\" ld --support-dir \"$DIST/support\" -T link.ld \\\n"
+ " kit as -target aarch64-none-elf -o start.o start.s\n"
+ " kit ld -T link.ld \\\n"
" -e _start -o kernel.elf start.o\n"
- " \"$K\" image --format bin --require-entry \\\n"
+ " kit image --format bin --require-entry \\\n"
" --require-symbol _start --require-section .text \\\n"
" --metadata kernel.json kernel.elf -o kernel.bin\n"
- " \"$K\" size kernel.elf\n"
+ " kit size kernel.elf\n"
" # A high-address IHEX image needs an explicit representable bias.\n"
" printf 'ENTRY(_start)\\nSECTIONS { . = 0x100000000; .text : "
"{ *(.text*) } }\\n' > high.ld\n"
- " \"$K\" ld --support-dir \"$DIST/support\" -T high.ld \\\n"
+ " kit ld -T high.ld \\\n"
" -e _start -o high.elf start.o\n"
- " \"$K\" image --format ihex --bias -4294967296 \\\n"
+ " kit image --format ihex --bias -4294967296 \\\n"
" high.elf -o high.hex\n"
"\n"
"EXIT CODES\n"
diff --git a/driver/cmd/install.c b/driver/cmd/install.c
@@ -63,14 +63,12 @@ void driver_help_install(void) {
" relocatable path lookup.\n"
"\n"
"EXAMPLES\n"
- " DIST=\"$PWD/Kit Release\"\n"
" PREFIX=\"$PWD/isolated prefix\"\n"
" mkdir -p \"$PREFIX/bin\"\n"
- " \"$DIST/bin/kit\" install --all \"$PREFIX/bin\"\n"
+ " kit install --all \"$PREFIX/bin\"\n"
" PATH=\"$PREFIX/bin:/usr/bin:/bin\" cc --help\n"
"\n"
- " # After moving DIST, refresh absolute symlinks from the new path.\n"
- " \"$PWD/Moved Kit/bin/kit\" install --all --force \"$PREFIX/bin\"\n"
+ " kit install --all --force \"$PREFIX/bin\"\n"
"\n"
"EXIT CODES\n"
" 0 success 1 one or more links failed 2 bad usage\n");
diff --git a/driver/cmd/ld.c b/driver/cmd/ld.c
@@ -240,15 +240,15 @@ void driver_help_ld(void) {
" --build-id=MODE none | sha256 | uuid | 0xHEX\n"
"\n"
"EXAMPLES\n"
- " # Hosted link; replace the quoted paths for your extraction/SDK.\n"
- " kit ld --support-dir \"/path/to/kit/support\" \\\n"
- " --sysroot \"/path/to/sysroot\" -l c -o hello hello.o\n"
+ " # Hosted link with a user-supplied sysroot.\n"
+ " SYSROOT=/replace/with/hosted-sysroot\n"
+ " kit ld --sysroot \"$SYSROOT\" -l c -o hello hello.o\n"
" # Archive order: main.o references symbols in libfoo.a.\n"
" kit ld -o app main.o libfoo.a\n"
" kit ld -r -o combined.o a.o b.o\n"
" kit ld -shared -soname libfoo.so.1 -o libfoo.so foo.pic.o\n"
" # Freestanding final link; link.ld must define the memory map.\n"
- " kit ld --support-dir \"/path/to/kit/support\" -T link.ld \\\n"
+ " kit ld -T link.ld \\\n"
" -e _start -o kernel.elf start.o\n"
"\n"
"GETTING HELP\n"
diff --git a/driver/cmd/objdump.c b/driver/cmd/objdump.c
@@ -123,13 +123,12 @@ void driver_help_objdump(void) {
" kit objdump -d a.o\n"
" kit objdump -h -j .text -j .rodata a.o\n"
" kit objdump -t libfoo.a\n"
- " DIST=\"$PWD/kit\"; K=\"$DIST/bin/kit\"\n"
- " SDK=$(\"$K\" cc -print-sysroot)\n"
+ " SDK=$(kit cc -print-sysroot)\n"
" printf 'extern int value; int add(void) { return value + 1; }\\n' "
"> debug.c\n"
- " \"$K\" cc --support-dir \"$DIST/support\" -isysroot \"$SDK\" "
+ " kit cc -isysroot \"$SDK\" "
"-g -c debug.c -o debug.o\n"
- " \"$K\" objdump -t -r --dwarf=line debug.o\n"
+ " kit objdump -t -r --dwarf=line debug.o\n"
"\n"
"EXIT CODES\n"
" 0 success 1 parse / I/O error 2 bad "
diff --git a/test/driver/help_uniform.sh b/test/driver/help_uniform.sh
@@ -92,6 +92,36 @@ else
not_ok "top-help-groups" "$work/top.groups.diag"
fi
+# Examples assume `kit` is already on PATH. Keep extraction-layout variables,
+# direct bin/kit paths, and explicit sibling support paths out of this section.
+: > "$work/example-path-noise.diag"
+example_tools=$(awk -F '|' '{ print $2 }' "$work/top.groups")
+for tool in $example_tools emu; do
+ example_help="$work/$tool.examples.help"
+ example_err="$work/$tool.examples.err"
+ example_body="$work/$tool.examples"
+ if ! "$KIT" "$tool" --help > "$example_help" 2> "$example_err"; then
+ printf '%s: help failed\n' "$tool" >> "$work/example-path-noise.diag"
+ sed 's/^/ /' "$example_err" >> "$work/example-path-noise.diag"
+ continue
+ fi
+ awk '
+ $0 == "EXAMPLES" { in_examples = 1; next }
+ in_examples && /^[A-Z][A-Z ]*$/ { exit }
+ in_examples { print }
+ ' "$example_help" > "$example_body"
+ example_noise="$work/$tool.examples.noise"
+ if grep -En 'DIST|/bin/kit|/path/to/kit|--support-dir|(^|[[:space:]])K=' \
+ "$example_body" > "$example_noise"; then
+ sed "s/^/$tool:/" "$example_noise" >> "$work/example-path-noise.diag"
+ fi
+done
+if [ ! -s "$work/example-path-noise.diag" ]; then
+ ok "examples-use-kit-from-path"
+else
+ not_ok "examples-use-kit-from-path" "$work/example-path-noise.diag"
+fi
+
help_shape() {
tool=$1
out="$work/$tool.help"
