Tachikoma
e2039ae63e
Chapters 6 and 8 described what a verb draws in prose. Eight figures now show it, and each one is produced by running the BASIC listing printed immediately above it -- so a picture cannot drift away from the code beside it, which is the way a screenshot goes wrong and the way nothing notices. tools/screenshot.c is a second SDL host, much smaller than the frontend: dummy video driver, software renderer, run to completion, read the target back, write a PNG. It draws no text layer on purpose, so a READY in the corner is not noise in a figure about BOX and no font has to be resolved. tools/docs_screenshots.sh reads the new screenshot=NAME fence tag straight out of the markdown. size=WxH is the second tag, and SCALE's figure uses it: the point being made is a 320x200 listing filling a larger window, which cannot be made on a 320x200 surface. Two gates, answering different questions. docs_examples fails a tagged block with no image, in both configurations, so a figure cannot be added and forgotten. docs_screenshots -- a CTest, AKGL build only -- re-renders every figure and compares byte for byte, so a listing edited without regenerating fails. Only the second catches a stale picture. The PNGs are checked in because a reader on the forge has no build tree, and docs/images/README.md says loudly that they are generated. Regenerating is never part of a build: the target is run deliberately, so a make cannot put eight binary diffs in front of whoever ran it. Drawing the BOX figure caught a defect in TODO.md itself. Deviation 16 claimed in bold that BOX fills on a negative angle while its own paragraph said the fill was filed rather than implemented. BOX cannot fill, and filled_rect is reached by no verb as a result. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
550 lines
19 KiB
Bash
Executable File
550 lines
19 KiB
Bash
Executable File
#!/bin/bash
|
|
#
|
|
# Run every example in the documentation and check what it produces.
|
|
#
|
|
# The guide in docs/ and the walkthrough in README.md are full of programs,
|
|
# transcripts, C snippets and shell commands. Every one of them was checked by
|
|
# hand once, when it was written, and that is not a standard that survives
|
|
# contact with a changing interpreter. Three of them were already wrong when this
|
|
# harness was written -- two transcripts carrying a leading space PRINT does not
|
|
# emit, and a struct in README.md that had grown two members hours earlier.
|
|
#
|
|
# Documentation goes stale because the *code* moved, not because somebody edited
|
|
# a chapter, so this runs on every ctest rather than on a docs path filter.
|
|
#
|
|
# **Exit status is the number of failed examples**, the house convention.
|
|
#
|
|
# The contract with the documentation is a set of fence info strings. They are
|
|
# ordinary markdown, they render as syntax highlighting on the forge, and they
|
|
# sit next to the thing they describe. MAINTENANCE.md is the reference; the short
|
|
# version:
|
|
#
|
|
# ```basic a whole program: run it, and it must not error
|
|
# ```basic repl input lines fed to a fresh interpreter on stdin
|
|
# ```basic norun a fragment, shown but not run
|
|
# ```basic requires=akgl only run in the -DAKBASIC_WITH_AKGL=ON build
|
|
# ```basic requires=noakgl only run in the build with no devices attached
|
|
# ```basic screenshot=N also the source of docs/images/N.png; checked to exist
|
|
# ```basic size=WxH that figure's surface size, when it is not 320x200
|
|
# ```output the exact stdout of the block above, byte for byte
|
|
# ```c a translation unit: compile it with -fsyntax-only
|
|
# ```c wrap=NAME the same, wrapped in tests/docs_preludes/NAME.pre/.post
|
|
# ```c excerpt=PATH must appear verbatim in PATH; not compiled
|
|
# ```c norun shown but not compiled
|
|
# ```sh run in a sandbox; must exit 0
|
|
# ```sh setup=NAME the same, after tests/docs_setups/NAME.sh
|
|
# ```sh norun destructive, networked, or re-enters this suite
|
|
# ```cmake never executed; hand-maintained, by decision
|
|
# ```text a diagram or a captured dump; there is nothing to execute
|
|
#
|
|
# A block with **no** info string is a hard error. That is deliberate: the
|
|
# failure mode this whole harness exists to avoid is passing because it quietly
|
|
# ran nothing, so an unannotated block is a missing decision rather than a
|
|
# default.
|
|
|
|
set -u
|
|
|
|
ROOT=""
|
|
BASIC=""
|
|
CFLAGS_FILE=""
|
|
WITH_AKGL=0
|
|
|
|
usage()
|
|
{
|
|
cat >&2 <<'EOF'
|
|
usage: docs_examples.sh --root DIR --basic PATH [--cflags-file FILE] [--akgl] [FILE...]
|
|
|
|
--root DIR repository root; documentation paths are relative to it
|
|
--basic PATH the built interpreter
|
|
--cflags-file FILE one compiler flag per line, for the ```c blocks
|
|
--akgl this is an AKBASIC_WITH_AKGL build; run requires=akgl blocks
|
|
FILE... which documents to check (default: README.md docs/*.md)
|
|
EOF
|
|
exit 2
|
|
}
|
|
|
|
while [ $# -gt 0 ]; do
|
|
case "$1" in
|
|
--root) ROOT="$2"; shift 2 ;;
|
|
--basic) BASIC="$2"; shift 2 ;;
|
|
--cflags-file) CFLAGS_FILE="$2"; shift 2 ;;
|
|
--akgl) WITH_AKGL=1; shift ;;
|
|
--help|-h) usage ;;
|
|
--*) echo "unknown option $1" >&2; usage ;;
|
|
*) break ;;
|
|
esac
|
|
done
|
|
|
|
[ -n "${ROOT}" ] || usage
|
|
[ -n "${BASIC}" ] || usage
|
|
[ -x "${BASIC}" ] || { echo "FAIL: no interpreter at ${BASIC}" >&2; exit 2; }
|
|
|
|
# Both of these are used from inside a sandbox directory this script cd's into,
|
|
# so a relative one silently resolves against the wrong place: `--basic
|
|
# ./build/basic` fails every example with "exited 127", and `--root .` cannot
|
|
# find tests/docs_setups. CTest passes absolute paths and never saw it; a person
|
|
# running one document by hand hits it immediately. Resolve them here instead of
|
|
# documenting the trap.
|
|
case "${BASIC}" in
|
|
/*) ;;
|
|
*) BASIC="${PWD}/${BASIC}" ;;
|
|
esac
|
|
|
|
cd "${ROOT}" || exit 2
|
|
ROOT="${PWD}"
|
|
|
|
DOCS=("$@")
|
|
if [ ${#DOCS[@]} -eq 0 ]; then
|
|
# MAINTENANCE.md is here for the tagging rule rather than for its examples:
|
|
# every one of its blocks is `norun`, and the point is that the file which
|
|
# documents the convention is held to it.
|
|
DOCS=(README.md MAINTENANCE.md)
|
|
for _doc in docs/*.md; do
|
|
DOCS+=("${_doc}")
|
|
done
|
|
fi
|
|
|
|
# Refuse a document that is not there rather than checking nothing and passing.
|
|
# An empty argument is the specific case that got here: a CMake generator
|
|
# expression evaluating to nothing still contributes an empty argument, which
|
|
# looked like a filename and silently replaced the whole default list.
|
|
for _doc in "${DOCS[@]}"; do
|
|
if [ ! -r "${_doc}" ]; then
|
|
echo "FAIL: no document at \"${_doc}\"" >&2
|
|
exit 2
|
|
fi
|
|
done
|
|
|
|
WORK="$(mktemp -d)"
|
|
trap 'rm -rf "${WORK}"' EXIT
|
|
|
|
# The compiler flags the ```c blocks need. CMake writes them, because the
|
|
# include path is transitive through akerror, akstdlib and (in the AKGL build)
|
|
# akgl, and hardcoding it here would go stale exactly the way the docs do.
|
|
CFLAGS=()
|
|
if [ -n "${CFLAGS_FILE}" ] && [ -r "${CFLAGS_FILE}" ]; then
|
|
while IFS= read -r _flag; do
|
|
[ -n "${_flag}" ] && CFLAGS+=("${_flag}")
|
|
done < "${CFLAGS_FILE}"
|
|
fi
|
|
CC="${CC:-cc}"
|
|
|
|
FAILURES=0
|
|
declare -A RAN=([basic]=0 [repl]=0 [output]=0 [c]=0 [excerpt]=0 [sh]=0 [screenshot]=0)
|
|
declare -A SKIPPED=([norun]=0 [akgl]=0 [cmake]=0 [text]=0 [nocc]=0)
|
|
|
|
# Every failure names the file and line of the block, so the message points at
|
|
# the thing to edit rather than at this script.
|
|
fail()
|
|
{
|
|
local where="$1"; shift
|
|
echo "FAIL ${where}: $*" >&2
|
|
FAILURES=$((FAILURES + 1))
|
|
}
|
|
|
|
# Show a byte-exact comparison. `cat -A` because the errors this catches are
|
|
# leading spaces and missing newlines, which a plain diff renders invisibly.
|
|
show_diff()
|
|
{
|
|
local want="$1" got="$2"
|
|
echo "--- expected ---" >&2
|
|
cat -A "${want}" >&2
|
|
echo "--- actual ---" >&2
|
|
cat -A "${got}" >&2
|
|
}
|
|
|
|
# ---------------------------------------------------------------- extraction
|
|
#
|
|
# One pass per document, writing each block's body to ${WORK}/blocks/NNNN and a
|
|
# line to ${WORK}/index. Keeping the bodies in files rather than shell variables
|
|
# means a block containing a NUL, a backslash or an unbalanced quote is carried
|
|
# through untouched -- and BASIC string literals contain plenty of all three.
|
|
extract()
|
|
{
|
|
local doc="$1" out="$2"
|
|
|
|
awk -v OUT="${out}" -v INDEX="${out}/index" '
|
|
function pad(n) { return sprintf("%04d", n) }
|
|
/^```/ {
|
|
if ( !inblock ) {
|
|
inblock = 1
|
|
tag = substr($0, 4)
|
|
sub(/[ \t]+$/, "", tag)
|
|
start = NR
|
|
count++
|
|
body = OUT "/" pad(count)
|
|
printf "" > body
|
|
next
|
|
}
|
|
if ( $0 == "```" ) {
|
|
close(body)
|
|
printf "%s\t%d\t%s\n", pad(count), start, tag >> INDEX
|
|
inblock = 0
|
|
next
|
|
}
|
|
}
|
|
inblock { print >> body }
|
|
' "${doc}"
|
|
}
|
|
|
|
# ------------------------------------------------------------------- helpers
|
|
|
|
# The value of attribute $1 in an info string $2, or empty. `wrap=embed` and
|
|
# `requires=akgl` are both read this way.
|
|
attr()
|
|
{
|
|
local name="$1" info="$2" word
|
|
for word in ${info}; do
|
|
case "${word}" in
|
|
"${name}"=*) echo "${word#*=}"; return ;;
|
|
esac
|
|
done
|
|
}
|
|
|
|
# True when a bare word appears in an info string. Used for `norun` and `repl`.
|
|
has_word()
|
|
{
|
|
local want="$1" info="$2" word
|
|
for word in ${info}; do
|
|
[ "${word}" = "${want}" ] && return 0
|
|
done
|
|
return 1
|
|
}
|
|
|
|
# Strip C comments and collapse whitespace, so an excerpt can be compared to the
|
|
# header it came from without either side having to carry the other's doc
|
|
# comments or indentation.
|
|
normalise_c()
|
|
{
|
|
awk '
|
|
{
|
|
line = $0
|
|
out = ""
|
|
while ( length(line) > 0 ) {
|
|
if ( incomment ) {
|
|
i = index(line, "*/")
|
|
if ( i == 0 ) { line = ""; break }
|
|
incomment = 0
|
|
line = substr(line, i + 2)
|
|
continue
|
|
}
|
|
i = index(line, "/*")
|
|
j = index(line, "//")
|
|
if ( j > 0 && (i == 0 || j < i) ) {
|
|
out = out substr(line, 1, j - 1)
|
|
line = ""
|
|
break
|
|
}
|
|
if ( i == 0 ) { out = out line; line = ""; break }
|
|
out = out substr(line, 1, i - 1)
|
|
incomment = 1
|
|
line = substr(line, i + 2)
|
|
}
|
|
printf "%s ", out
|
|
}
|
|
END { printf "\n" }
|
|
' "$1" | tr -s ' \t' ' ' | sed -e 's/^ //' -e 's/ $//'
|
|
}
|
|
|
|
# --------------------------------------------------------------- block kinds
|
|
|
|
# A BASIC program in a file, or a transcript on stdin. Both go through the same
|
|
# comparison, because the only difference is how the interpreter is invoked.
|
|
run_basic()
|
|
{
|
|
local where="$1" body="$2" info="$3" expected="$4"
|
|
local sandbox="${WORK}/run" got="${WORK}/got" status=0 setup
|
|
|
|
rm -rf "${sandbox}"
|
|
mkdir -p "${sandbox}"
|
|
|
|
# An example that reads a file needs that file. Putting the fixture in a
|
|
# setup script rather than in the chapter keeps the example the shape a
|
|
# reader wants to see -- `SPRSAV "ship.png", 1` and nothing else.
|
|
setup="$(attr setup "${info}")"
|
|
if [ -n "${setup}" ]; then
|
|
if [ ! -r "tests/docs_setups/${setup}.sh" ]; then
|
|
fail "${where}" "setup=${setup} names no tests/docs_setups/${setup}.sh"
|
|
return
|
|
fi
|
|
if ! ( cd "${sandbox}" && bash "${ROOT}/tests/docs_setups/${setup}.sh" ) >/dev/null 2>&1; then
|
|
fail "${where}" "setup=${setup} failed"
|
|
return
|
|
fi
|
|
fi
|
|
|
|
if has_word repl "${info}"; then
|
|
( cd "${sandbox}" && "${BASIC}" < "${body}" ) > "${got}.raw" 2> "${WORK}/stderr"
|
|
status=$?
|
|
# Drop the startup banner. A piped interpreter prints READY once, before
|
|
# it has read anything, so carrying it in every transcript would be one
|
|
# line of noise per example and would put it in the wrong place besides:
|
|
# at a real prompt READY comes back *after* each line. Chapter 2 shows
|
|
# that interactively, which is where it belongs.
|
|
sed -e '1{/^READY$/d}' "${got}.raw" > "${got}"
|
|
RAN[repl]=$((RAN[repl] + 1))
|
|
else
|
|
cp "${body}" "${sandbox}/example.bas"
|
|
( cd "${sandbox}" && "${BASIC}" example.bas ) > "${got}" 2> "${WORK}/stderr"
|
|
status=$?
|
|
RAN[basic]=$((RAN[basic] + 1))
|
|
fi
|
|
|
|
if [ "${status}" -ne 0 ]; then
|
|
fail "${where}" "the interpreter exited ${status}"
|
|
sed -n '1,20p' "${got}" "${WORK}/stderr" >&2
|
|
return
|
|
fi
|
|
|
|
# stdout only, the way tests/golden.cmake compares its cases. libakgl logs
|
|
# registry activity to stderr -- three lines every time a sprite is created
|
|
# -- and folding that into the comparison would put library chatter into the
|
|
# documentation of a BASIC verb.
|
|
if [ -n "${expected}" ]; then
|
|
RAN[output]=$((RAN[output] + 1))
|
|
if ! cmp -s "${expected}" "${got}"; then
|
|
fail "${where}" "output does not match the block below it"
|
|
show_diff "${expected}" "${got}"
|
|
fi
|
|
return
|
|
fi
|
|
|
|
# No expectation given, so the only thing to assert is that it ran cleanly.
|
|
# A BASIC-level error prints "? LINE : CLASS" and still exits 0 -- that is
|
|
# correct for the interpreter and useless as a test result, so look for it.
|
|
if grep -qE '^\? [0-9]+ :' "${got}"; then
|
|
fail "${where}" "the program raised a BASIC error"
|
|
grep -E '^\? [0-9]+ :' "${got}" >&2
|
|
fi
|
|
}
|
|
|
|
# A C snippet. Compiled, never linked and never run: what these examples are for
|
|
# is showing the API, and the API is exactly what -fsyntax-only checks.
|
|
run_c()
|
|
{
|
|
local where="$1" body="$2" info="$3" doc="$4" line="$5"
|
|
local wrap unit="${WORK}/unit.c" log="${WORK}/cc.log"
|
|
|
|
if [ ${#CFLAGS[@]} -eq 0 ]; then
|
|
SKIPPED[nocc]=$((SKIPPED[nocc] + 1))
|
|
return
|
|
fi
|
|
|
|
wrap="$(attr wrap "${info}")"
|
|
: > "${unit}"
|
|
if [ -n "${wrap}" ]; then
|
|
if [ ! -r "tests/docs_preludes/${wrap}.pre" ]; then
|
|
fail "${where}" "wrap=${wrap} names no tests/docs_preludes/${wrap}.pre"
|
|
return
|
|
fi
|
|
cat "tests/docs_preludes/${wrap}.pre" >> "${unit}"
|
|
fi
|
|
# Hand the compiler the document's own coordinates, so a diagnostic points
|
|
# at the line of markdown to fix rather than at a scratch file.
|
|
printf '#line %d "%s"\n' "$((line + 1))" "${doc}" >> "${unit}"
|
|
cat "${body}" >> "${unit}"
|
|
if [ -n "${wrap}" ] && [ -r "tests/docs_preludes/${wrap}.post" ]; then
|
|
printf '#line 1 "tests/docs_preludes/%s.post"\n' "${wrap}" >> "${unit}"
|
|
cat "tests/docs_preludes/${wrap}.post" >> "${unit}"
|
|
fi
|
|
|
|
# gnu99 rather than c99: akerror.h uses PATH_MAX, which <limits.h> hides
|
|
# under __STRICT_ANSI__, and the library itself is built with the compiler's
|
|
# default dialect. A stricter flag here would fail on the dependency rather
|
|
# than on the example.
|
|
if "${CC}" -fsyntax-only -std=gnu99 -Wall -Wextra -Werror \
|
|
"${CFLAGS[@]}" "${unit}" > " |