Andrew flagged the new helper introduced for the value-pool-leak fix
as missing documentation. akbasic_environment_create() and
akbasic_environment_create_empty() are already documented in the
header; the shared static helper they both call was the only
undocumented new function definition.
Co-authored-by: andrew <andrew@aklabs.net>
Create structure parameters before allocating their representation, then keep pointer references in the call variable's inline slot. Add an 8,000-call regression and document the remaining by-value structure escape limitation.
Co-authored-by: andrew <andrew@aklabs.net>
Co-authored-by: OpenAI Codex (GPT-5) <noreply@openai.com>
Review findings and follow-ups from PR #61 review:
- runtime_generator.c: akbasic_runtime_release_generator() now releases the
forGeneratorEnv of every scope it walks through. Abandoning a generator
that was itself suspended inside a FOR EACH over another generator
stranded the inner generator's pool slot; a loop doing so exhausted the
twelve-slot pool and died far from the cause.
- runtime.c/runtime.h: new akbasic_runtime_unwind_to_environment(), the
shared teardown for the error unwinds in pump_generator() and
call_function() -- both previously bare prev_environment() loops with the
same suspended-generator blindness.
- runtime_commands.c: bare RETURN standing in a GEN's own frame ends the
generator exactly as END GEN does -- a GEN is a function at heart. RETURN
with a value there is refused (values leave a GEN only through EMIT). The
no-frame error message now says "GOSUB, DEF, or GEN".
- runtime_structure.c: LOOP WHILE/UNTIL composes with DO EACH -- checked
after each trip with the loop variable still holding that trip's value; a
condition that stops the loop abandons the generator exactly as EXIT
does. Previously the condition was silently ignored, while the verb
reference documented it as working.
- parser_commands.c: trailing tokens after the generator call on a FOR
EACH/DO EACH line are refused at parse. Previously they sat unparsed and
blew up only after the loop completed, when the parent scope resumed the
line mid-statement -- an error at the loop's end pointing at its start.
- tests/generators.c: pool-exhaustion tests for the nested-abandonment and
LOOP-condition paths, RETURN semantics tests, and a direct test of the
unwind primitive. Three new golden pairs cover RETURN, LOOP conditions
and the misplaced-condition parse error.
- docs: RETURN and LOOP-condition semantics in 04-control-flow.md and
11-verb-reference.md; corrected the self-recursion analogy (functions
are re-entrant here). TODO.md 1.10 records the generator design
decisions the code comments were already citing, plus the zero-arg
parameter-list limitation. MAINTENANCE.md gains the abandoned-generators
invariant those comments also cited.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Adds generator support per the plan in issue 57:
- environment.h: isGenerator/generatorFn on a GEN call's own environment,
isEachLoop and forGeneratorEnv on a FOR EACH/DO EACH loop's own
environment.
- runtime.c: splits akbasic_runtime_prev_environment() into
akbasic_runtime_detach_environment() (return to parent without releasing)
and akbasic_runtime_release_environment() (give variables and the pool
slot back, on any environment); prev_environment() is now the two in
sequence. akbasic_runtime_call_function() refuses to call a GEN like an
ordinary function.
- verbs.c/verbs.h/scanner: new keywords GEN, EMIT, EACH, IN and the compound
verb "END GEN" (built by a new akbasic_parse_end(), the same trick
akbasic_parse_print() uses for PRINT #).
- parser_commands.c: akbasic_parse_gen() (modelled on multi-line DEF),
akbasic_parse_end(), and EACH branches in akbasic_parse_for()/
akbasic_parse_do().
- runtime_generator.c (new): akbasic_cmd_gen, akbasic_cmd_emit,
akbasic_cmd_end_gen, and the invoke/pump/release machinery FOR EACH, DO
EACH, NEXT and LOOP share. EMIT walks up to the nearest isGenerator
ancestor rather than assuming it is standing directly in the GEN's own
call frame, because a GEN body may nest its own FOR/DO/GOSUB around an
EMIT -- the issue's own ROOMOBJECTS example does exactly that.
- runtime_commands.c/runtime_structure.c: EACH branches in cmd_for/cmd_do,
matching EACH branches in cmd_next/cmd_loop, and forGeneratorEnv release
on every path that can abandon a live generator (EXIT, a NEXT that pops
for a mismatched loop variable).
Deviates from the plan in one place: FunctionDef gained an isGenerator flag
(not in the plan's field list) because refusing a GEN called like a
function has to happen before anything is pushed. Relying on EMIT's own
isGenerator check for that case doesn't work: akbasic_runtime_call_function()
drives its own step loop the same way akbasic_runtime_pump_generator() does,
and a BASIC-level error inside that loop is swallowed by process_line_run()
as reported-but-not-propagated, so the call would silently "succeed" with a
meaningless return value instead of failing.
Also: a zero-argument parameter list is not supported by the DEF/GEN
parameter parser this reuses (a pre-existing limitation, not
generator-specific); every generator in the tests takes at least one
parameter as a result.
Tests: tests/generators.c (pool exhaustion under repeated EXIT, calling a
GEN like a function, EMIT outside a GEN, self-recursion, sibling/nested
invocations) and tests/language/flowcontrol/generators_*.bas -- the
issue's own ROOMOBJECTS example in both loop shapes, an empty generator,
non-numeric EMIT, nested/interleaved invocations, and three error-path
golden cases. Docs: control-flow chapter 4 gets a GEN/EMIT/FOR EACH/DO EACH
section, the verb reference gets GEN/EMIT/END GEN entries and updated
FOR/DO/NEXT/LOOP/EXIT rows, and architecture chapter 14 documents the
detach/release split and the two-environment generator invocation.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
libakerror main now includes the fix for issue #37 (per-TU static TLS
akerr_last_ignored -> single extern definition in src/error.c, one copy
per thread instead of one per translation unit) and issue #38 (project()
now stamps 2.0.3, matching the release notes).
Bump deps/libakerror to origin/main (9249f8c) and update MAINTENANCE.md:
drop the now-stale 'IGNORE change costs' subsection and the 2.0.2/2.0.3
version-disagreement note, since both are resolved upstream.
Verified: build/basic has no TLS segment and zero -Wunused-variable
warnings for akerr_last_ignored; 114/114 tests pass.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Four independent defects that made 'doxygen Doxyfile' exit 1:
- runtime.h: a stacked doc block above akbasic_runtime_new_function
was left directly above akbasic_runtime_call_function's declaration
with no function in between, so Doxygen glommed both blocks onto
call_function and duplicated the @param obj/@param dest entries.
Moved the block back to sit directly above new_function.
- sprite.h/akgl.h/sprite_akgl.c: three #AKGL_*/#AKBASIC_SHAPE_* Doxygen
autolinks pointed at libakgl symbols outside this Doxyfile's INPUT,
so they could never resolve. Converted them to plain code spans.
- scanner.c: peek(), peek_next() and match_next_char() were each
missing @param obj (and match_next_char also cm/truetype/falsetype).
Filled in the missing entries.
- Doxyfile: the error.h include graph hit DOT_GRAPH_MAX_NODES at
exactly the default of 50. Raised it to 100.
Verified 'doxygen Doxyfile' now exits 0 with graphviz installed.
Refs #56
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Adding native RND and ASC (ae2c702) made RND a function name, and a suffixed
identifier that collides with one is refused -- "SYNTAX ERROR Reserved word in
variable name". Three example programs held their PRNG output in a variable
called RND#, or a host field called RND%, and none of them had run since:
- examples/galaga/ bound RND% as a host field on both ENEMY and GAME. The
BASIC-visible name is ROLL% now; the C member stays `rnd`. This one was
caught by example_galaga and example_galaga_interop, which have been
failing.
- examples/breakout/characters/breakout.bas and examples/megademo/
megademo.bas both use RND# for their LCG output, renamed to ROLL#. Neither
is in any test, so neither failure was visible.
examples/breakout/sprites/breakout.bas was broken a second way: seven REM lines
the reader refuses. Worth recording that the ceiling is not the one the message
names -- src/sink_stdio.c fails when the read filled the buffer without seeing
a terminator, so with AKBASIC_MAX_LINE_LENGTH at 80 the message says "79
character limit" and the real maximum is 78, because a 79-character line leaves
no room for the newline. The sweeps that fixed the corpus and the megademo for
this did not reach this file. The seven comments are reflowed.
The prose went stale with the code. Chapter 21 said "there is no RND verb in
this dialect; issue #16 tracks adding one", chapter 17's historical aside
offered an LCG that no longer parses, and four REM blocks across the two games
said the same thing. All of them now say RND exists, and say why these programs
keep their own generator anyway: the sequence has to be reproducible for a
headless run to be the same game on every machine, which is what lets
interop_test.c assert exact counts.
Chapter 21 also gains the rule that bit them, since a reader writing a host
type will hit it: a host field name is a bare word and shares a namespace with
every verb and function.
None of this came from the submodule bump -- all three were already broken on
main. It was found by running the tutorial games, which nothing else does;
that gap is akbasic issue #58.
Verified: all three run clean under the dummy drivers, and 114/114 default,
116/116 with akgl.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Code (Claude Opus 5, claude-opus-5[1m]) <noreply@anthropic.com>
Bumps all three ak* submodules to their current main, applies what their
upgrade notes require, and retires the two workarounds they make obsolete.
libakerror 2.0.1 -> 2.0.2 (63 commits). Two of its fixes were this
repository's own filed issues, and both workarounds are gone:
- It namespaces its embedded `coverage` target now, the same
CMAKE_SOURCE_DIR test it already applied to `mutation` (its issue #15).
The add_custom_target() shadow that renamed it on the way past could
only ever fire on a name the dependency has stopped using, so it is
deleted rather than left as dead code.
- It installs akerrorConfigVersion.cmake at SameMajorVersion (its issue
#16). MAINTENANCE.md said to add a `1.0` floor to our find_dependency
calls when this landed; the floor is now `2.0`, and we have no
find_dependency calls to add it to, so the paragraph says that instead
of an instruction nobody can follow.
Its IGNORE context also changed shape: `__akerr_last_ignored` was an extern
pointer, and is now a per-translation-unit `static akerr_last_ignored` holding
a copy, so the pool slot can be released. Nothing here referenced the symbol,
but it costs us 1.35 MiB of thread-local storage -- 38 TUs x 37,296 bytes,
measured as the entire TLS segment of build/basic, where 2.0.1 produced no TLS
segment at all -- plus 84 -Wunused-variable warnings. Filed upstream as
libakerror issue #37 and recorded in MAINTENANCE.md rather than patched here,
because patching a submodule forks it.
libakstdlib gains directory and file-metadata wrappers with no version bump.
aksl_snprintf keeps its `int *count` -- an intermediate commit removed it and
the merge put it back -- but now reports the required length on truncation
rather than 0. Every call site here reads it only after a successful return,
so nothing moved.
The directory wrappers close the gap DIRECTORY was refused for (libakstdlib
issue #10). The verb is still unwritten, so it still refuses, but it no longer
blames a wrapper that exists: the message is "DIRECTORY is not implemented
yet" and tests/disk_verbs.c asserts both that it says so and that it does not
name libakstdlib. What writing it would need is akbasic issue #55.
libakgl moves to the current main at 0.9.0. It registers libccd and tg as
submodules, so a tree that only ran `git submodule update --init --recursive`
before the bump needs it again or the configure fails on a missing
libccd/src/ccd/config.h.cmake.in.
Verified: 114/114 default, 116/116 under -DAKBASIC_WITH_AKGL=ON, docs_examples
green in both. libakerror's UPGRADING.md documents a 2.0.3 that project()
never stamped, so the version tables read 2.0.2 -- libakerror issue #38.
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Co-Authored-By: Claude Code (Claude Opus 5, claude-opus-5[1m]) <noreply@anthropic.com>
Implement bounded random integers with lazy clock seeding and add ASC as the inverse of CHR. Cover dispatch, validation, deterministic LCG output, UTF-8 round trips, function reference, and the breakout tutorial.
Closes#16.
Co-authored-by: andrew <andrew@aklabs.net>
AKBASIC_MAX_LINE_LENGTH's cut from 256 to 80 left seventeen lines of
examples/megademo unloadable: the sixteen IM$() picture strings (up to
252 characters) and TUNEA/TUNEB's four-bar PLAY strings (174 and 175).
The real ceiling is 78 characters, not 80 -- stdio_readline() refuses a
read that fills the 80-byte buffer without a newline, so content plus
its terminator must fit in 79.
The picture: vaporwave.py's PAYLOAD drops from 240 to 64, so every
emitted IM$(NN) = "..." line fits under the ceiling. chop() no longer
slices blind; it walks the stream a record at a time -- two characters
for a run, three for an R row record -- and never cuts inside one,
because the decoder reads a record's tail with MID on the string it is
walking and a record straddling two IM$ entries decodes as garbage.
The old blind slice at 240 only happened to be safe. verify() now
simulates the CHOPPED strings with the cursor threaded across the
boundaries exactly the way DRAWSTREAM executes them, so a bad cut is
an assertion failure instead of a corrupted screen, and emit_block()
asserts every emitted line fits. The picture is 56 strings where it
was 16; the decoder needed no changes at all, since it already carries
X#/Y# from one IM$ entry to the next.
The music: TUNEA and TUNEB each become four PLAY statements, one bar
apiece. play.c keeps voice, envelope, level and duration state on the
runtime across statements and every PLAY appends to the same queue, so
four bars queue exactly as one long string did. Each bar restates the
V1T3U9S prefix so a bar dropped by QFULL cannot leave the next batch
playing on the drum kit's envelope.
Everything still clears the shrunken pools with room to spare: 1625
source lines of 2048, ~704 array slots of 2048, identifiers within the
24-character symtab key. Verified end to end against this branch's
build: the demo loads, the offscreen host renders every scene, and the
scene-5 still is pixel-identical to vaporwave.py's own preview. The
test suite fails the same seventeen cases with and without this
commit.
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01ACffnV6F7sxQuG3Y8a1L3s
Reflow the approved reference cases, shorten local fixture comments, and split the executable docs line so the 80-byte input buffer can read every source line.
Co-authored-by: andrew <andrew@aklabs.net>
Keep the two immutable reference cases and fourteen local cases that exceed the current 80-column input contract in CTest, but mark their existing failures as expected until issue #32 is resolved. This keeps every CI configuration green without editing the reference corpus or weakening the runtime limit.\n\nCo-authored-by: andrew <andrew@aklabs.net>
Three more Haiku-class cold reads of the chapters, each against the
amended text. What each surfaced is now shown rather than described: the
akbasic_host_register_type()/akbasic_host_bind() boot calls, the
declare_play() label listing, the akgl_UiMenu static and its
handle_event signature, one control-handler pair, and main()'s
ATTEMPT/HANDLE_DEFAULT/FINISH_NORETURN shape with the CATCH-inside-
ATTEMPT rule stated. By the fourth read the generated player.c and
enemies.c compiled untouched and every remaining guess was a tuning
value the chapters deliberately leave open.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
The interop test now ends with a measured comparison: 24,000 formation
updates through the script boundary against a line-for-line C
translation of the same state machine. 881 us against 0.01 us per call
on this machine, quoted verbatim in the new chapter 21 Step 11 with the
architectural decisions it prices.
A Haiku-class cold read of the chapters produced a build whose failures
were all mechanical -- invented include paths, never-shown sink statics,
guessed status codes and character names. The chapters now carry the
include lists, the script.c statics, the status-code roster, the
sprite/character table, the full CMake recipe and the explosion spawn's
HANDLE example, so none of those have to be guessed again.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
docs/20 builds the engine and the boundary: the startup order, the
starfield, actors and collision, booting a DEF-only script, the issue #8
mode workaround, the custom update hook, first light, screens, and the
headless harness. docs/21 builds the three shared structures and the AI:
the host type tables, the actor binding, the randomness route around
issue #16, the measured case against structure arguments (issue #36),
the three language rules that shape the script, the maneuvers, the
argued formation decision, the script-death policy, and the interop
proof. Every fenced block runs under tests/docs_examples.sh in both
build configurations; five new preludes carry the C fragments.
docs/10 gains the 'Calling a function every frame' section the chapters
lean on: the per-call akbasic_environment_zero() rule, the set_mode(RUN)
workaround, the clear_error() revival, and the case for rebinding over
structure arguments. Index rows and chapter counts updated.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
The environment pool shrank from 32 to 12 in the memory-reduction work
and the chapter's exhaustion transcript still asserted the old number,
which is a docs_examples failure on every run of this branch.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
A GALAGA-style fixed shooter whose engine is C on libakgl (null physics)
with the interpreter embedded as the scripting engine that owns every
enemy's behavior. One DEF-only script is called per enemy per frame
through a custom akgl_Actor update hook; SELF@, ACTOR@ and GAME@ are host
bindings, so the script reads and writes the engine's real memory -- the
boss even swaps its own damage sprite by raising an actor state bit from
BASIC. Bullets, collision, scoring and screens stay C.
Structure arguments were measured and rejected for the per-frame path:
each pointer parameter spends a value-pool slot the pool never reclaims,
1,015 calls to exhaustion against an unbounded rebind (issue #36).
Built when AKBASIC_WITH_AKGL=ON. Two CTest entries: a 600-frame headless
autoplay run under the dummy SDL drivers, and an interop round-trip test
that links the real script.c and galaga.bas and pins the four boundary
claims, 24,000 sustained calls among them. docs_galaga_figures
regenerates the two checked-in figures. Art is Kenney CC0, byte for
byte, with provenance.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
akbasic_runtime_call_function()'s body loop drives process_line_run()
directly, skipping the per-line prologue akbasic_runtime_step() provides.
The call environment's value scratch therefore accumulated across the
whole body, and any body past about ten real lines died with 'Maximum
values per line reached' -- a limit that is supposed to be per line. The
loop now runs the same prologue step() does.
A body that died also left its call scopes active: nothing popped them,
so a host absorbing script errors drained the twelve-slot environment
pool after twelve dead calls. The loop now unwinds to the caller's
environment on every exit path.
New: akbasic_runtime_clear_error(), the missing half of host revival. A
run's first BASIC-level error latches deliberately, and set_mode(RUN)
alone cannot un-decide that; a host that absorbed the error calls this
beside it. Both defects and the revival dance are pinned in
tests/user_functions.c.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
The REM early-exit leaves tokentype holding AKBASIC_TOK_REM, and the scan
loop's post-switch check reads it before the next line's first character
has assigned anything. A line opening with whitespace then re-triggered
the REM break and scanned to nothing: every indented line after a REM was
silently skipped. Numbered programs never saw it -- the line number is the
first token and overwrites the leftover -- which is why the whole golden
corpus missed it and the unnumbered, indented galaga.bas found it.
Co-authored-by: andrew <andrew@aklabs.net>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XiGgpHuXUm2mR4Wzndw3dc
Nothing in this interpreter mallocs; every pool is a fixed array sized by an
AKBASIC_MAX_* constant, so sizeof(akbasic_Runtime) is a compile-time number
and most of it was headroom nobody was using. Measured concurrent-use
high-water marks off examples/breakout and examples/megademo -- the two most
demanding programs this interpreter runs -- against each pool's ceiling:
AKBASIC_MAX_ENVIRONMENTS 32 -> 12 (measured peak concurrency: 6-7)
AKBASIC_MAX_FUNCTIONS 64 -> 8 (measured: 0, neither program uses DEF FN)
AKBASIC_MAX_ARRAY_VALUES 4096 -> 2048 (measured peak: 1618 slots)
AKBASIC_MAX_SOURCE_LINES 9999 -> 2048 (measured: ~1270-1496 non-blank lines)
AKBASIC_SYMTAB_MAX_SLOTS 256 -> 172 (no caller ever requests more than 128)
AKBASIC_SYMTAB_MAX_KEY 64 -> 24 (longest identifier measured: 11 chars)
AKBASIC_MAX_LINE_LENGTH 256 -> 80 (Commodore BASIC's own line limit)
AKBASIC_MAX_VARIABLES (128) is untouched on purpose: breakout alone reaches
121 of 128 concurrent named variables, so it has the least slack of any pool
measured and is not a shrink candidate.
akbasic_Variable.name shrinks from AKBASIC_MAX_STRING_LENGTH (256) to
AKBASIC_SYMTAB_MAX_KEY: every variable name is registered with
akbasic_symtab_set() right after this field is populated
(akbasic_environment_create(), src/environment.c), and that call already
refuses anything AKBASIC_SYMTAB_MAX_KEY characters or longer. The wider field
was headroom nothing could ever put a byte into.
Two defects surfaced while testing the line-length drop against the golden
corpus, both fixed here because the 80-byte ceiling makes them routine rather
than theoretical:
- sourcepath (runtime.h) was borrowing AKBASIC_MAX_LINE_LENGTH by accident.
It holds a directory, not a line of BASIC, and this checkout's own test
paths are 81+ characters deep -- every golden test failed to load until
this split into its own AKBASIC_MAX_SOURCE_PATH_LENGTH, backed by PATH_MAX
the way libakerror already sizes its own path buffers.
- src/sink_stdio.c's stdio_readline() called aksl_fgets() but never checked
its own documented contract: a full buffer with no trailing newline means
the line was longer than the buffer, and the unread remainder is still in
the stream. Unchecked, the next readline() picks that remainder up as its
own statement -- a real line silently becomes two wrong ones instead of a
clean AKBASIC_ERR_BOUNDS refusal. At 256 bytes this was theoretical; at 80
it is not, so it now refuses loudly.
tests/value_pool.c's test_pool_is_untouched_by_scopes() was pinned to the old
4x1024=4096 pool math (four max-size arrays proving nothing leaked); rewritten
to 2x1024=2048 for the same proof against the new AKBASIC_MAX_ARRAY_VALUES.
Known consequence, tracked in andrew/akbasic#32 rather than worked around
here: two files in the protected tests/reference/ corpus
(language/functions/mod.bas, language/flowcontrol/nestedforloopwaitingfor
command.bas) have 82-character lines and cannot be shortened -- MAINTENANCE.md
and CMakeLists.txt:585 are explicit that tests/reference/ is never edited to
suit this interpreter. Twelve tests/language/ cases and one docs/18 line are
in the same position but are this project's own content. Shipping 80 anyway,
with the fallout tracked rather than hidden, was an explicit call on this PR
rather than something decided here.
Verified: cmake --build build-akgl && ctest --test-dir build-akgl, 97/112 (15
known failures, all AKBASIC_MAX_LINE_LENGTH-related, filed as #32).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Move every program and expectation out of tests/reference and register the unified tests/language corpus as local cases. Remove the old immutable-corpus protections from build, maintenance, and documentation paths.
Co-authored-by: andrew <andrew@aklabs.net>
Run #31's sanitizers job failed, and not on anything in src/. The ASan build
reached 100% and the runner's Docker daemon went away before ctest emitted a
single line: "Cannot connect to the Docker daemon at unix:///var/run/docker.sock".
The tree under test is identical to run #30's -- 9e5496f touched only this
file -- and run #30's sanitizers job passed 112/112 in 83 s. What changed is
that #30 was still losing akgl_build and coverage early, so #31 was the first
push on which all five jobs did real work at the same time. All five say
runs-on: ubuntu-latest, so all five share one runner, and every build step
asked for a bare --parallel, i.e. nproc compilers each.
The timestamps are unambiguous. Through 20:36:16 the sanitizers job links an
executable in well under a second. akgl_build starts at 20:36:02 and begins
compiling SDL, SDL_image, SDL_mixer, SDL_ttf, libccd and clay; mutation_test
starts at 20:36:41. From 20:36:16 onward a single `Linking C executable` step
takes one to two minutes -- a sixtyfold regression with no source change --
and at 20:49:55 the daemon is gone. ASan links are memory-hungry and the SDL
tree is large; the runner ran out.
The only lever on that is how many compiler and linker processes exist at
once, so bound each build to 2. Worst case is now 8 rather than 5 x nproc.
mutation_test drives its own builds through the harness and is left alone.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Two more gaps that only became visible once the errno fix let the jobs
run far enough to hit them.
akgl_build cloned six of libakgl's submodules and needs eight. libakgl
does not add_subdirectory deps/libccd or deps/clay -- their own
CMakeLists are unusable as subprojects -- it compiles them into itself,
so nothing declares them and configuration dies at
deps/libakgl/CMakeLists.txt:282 with "File
deps/libccd/src/ccd/config.h.cmake.in does not exist". deps/tg stays out:
nothing references it.
The X11 packages from the previous commit did their job -- SDL now
configures the lot: "X11 libraries: xcursor xdbe xfixes xinput2 xrandr
xscrnsaver xshape xsync xtest".
coverage passes its gate now (112/112, lines 94.1% against a 90 floor)
and failed on the upload instead. actions/upload-artifact@v4 bundles
@actions/artifact v2, whose isGhes() treats any GITHUB_SERVER_URL that is
not github.com as GitHub Enterprise Server and refuses outright. @v3 uses
the older artifact API, which Gitea 1.25.3 does implement. The step had
never had a file to upload before -- gcovr was never reached, so it
warned "No files were found" and passed -- which is why this surfaced
only now. Same class of accommodation as annotate_only on the junit
reporter.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Every job in ci.yaml has failed on every run since #2, on main and on
every branch, for two reasons that have nothing to do with any of the
code under test.
moreutils, for errno(1). deps/libakerror/scripts/generrno.sh shells out
to it to generate its errno name table and to stamp
AKERR_LAST_ERRNO_VALUE into the generated akerror.h. The runner does not
have it, and its absence does not fail the build -- which is what made
this expensive to find. The script prints "errno: command not found",
emits an empty akerr_init_errno() so no errno ever gets a name, and
substitutes an empty AKERR_LAST_ERRNO_VALUE, so every code in
libakerror's reserved band collapses from (134 + n) to ( + n), i.e. to n.
AKERR_OUTOFBOUNDS is (AKERR_LAST_ERRNO_VALUE + 2) and therefore becomes
literally 2, so ERR(2) answers "Out Of Bounds Error" where ENOENT's "No
such file or directory" belongs. That is the docs_examples failure at
docs/15-error-codes.md:105, and it took cmake_build, sanitizers and
coverage down with it; mutation_test then aborted on "baseline is not
green" because the same suite is its baseline.
Reproduced locally by shimming errno(1) out of PATH: identical failure,
same test #47, same two lines of diff. With errno present the suite is
112/112.
The nine X11 dev packages, for akgl_build, which has never once been
green. SDL_X11 and its sub-options default ON on Linux, and CheckX11()
calls SDL_missing_dependency() -- a hard CMake error, not a downgrade --
for any whose header is absent. The runner has libx11-dev but none of
the extension packages, so configuration stopped at the first of them:
"Couldn't find dependency package for XCURSOR". The list is SDL's own,
from deps/SDL/docs/README-linux.md, reduced to the X11 entries; the
audio, Wayland, KMSDRM and Vulkan backends all degrade to "not found"
and skip themselves rather than erroring, so they cost nothing to leave
out. Turning the missing options OFF would also configure and is the
wrong answer -- the point of that job is that an AKGL build is a real
SDL program. The tests still run headless under SDL_VIDEODRIVER=dummy.
release.yaml's full_mutation job builds the same tree and gets moreutils
for the same reason.
No source file changes. The port itself was never the problem.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
akbasic's src/ now calls libakstdlib 313 times and raw libc 7 -- 2.2%
bypassed, against 86.4% on the same tree before this. The submodule bump
669b2b3 -> 2b79aca needed no source change of its own: the release is
drop-in for what akbasic already used.
Seven of the eight sites the earlier port left on raw libc change their own
signature rather than swallowing an error, per andrew's ruling on
libakstdlib#38. word_is, the is_waiting_for pair, the scanner's is_at_end,
peek, peek_next and match_next_char, format.c's overflow, and sink_akgl's
scroll/newline/putchar_at/echo_line/edit_key chain all return an
akerr_ErrorContext * and hand the answer back through an out parameter.
is_waiting_for and is_waiting_for_any are a public header change; every
call site that used one as a term in a condition hoists it into a
statement first.
verb_compare is the eighth and stays on strcmp. bsearch(3) fixes the
comparator's signature, so there is no out parameter to report through --
which is what libakstdlib#38 concluded. It carries a comment saying so and
saying why the bypass is safe there.
Six snprintf sites stay raw because they want truncation as an answer
rather than an error, and aksl_snprintf cannot express that until
libakstdlib#34 hands the required length back. Each of the six says so at
the site. Two of them, in host.c, are a latent defect rather than a
decision: a host type name over 31 characters truncates silently and two
sharing a prefix then collide, where structtype.c refuses the same case.
DLOAD leaked a file descriptor. Its read loop sat inside an ATTEMPT and the
PASS in it returned past CLEANUP, so a scan error left the file open.
Hoisting the loop into its own helper to convert fgets fixes it.
Refs libakstdlib#26, libakstdlib#38
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Its own SS0-SS9 structure survived the move to the tracker, so 133 citations
still resolve and are left alone. Thirteen did not.
Six named another repository's TODO.md by a section number: libakstdlib 1.6,
2.2.2 and 2.3, and libakgl's file. Those repositories dropped their numbering
entirely, so each now names UPGRADING.md, an issue, or the tracker.
Three cited 'TODO.md section 12', which has never existed here -- the defect
list is SS6. TODO.md itself caught two others of that class earlier. The
CMakeLists comment carried a stale premise with it: eleven defects
'deliberately reproduced and not yet fixed' stopped being the rule when SS0.1
retired the fidelity constraint.
Four told a reader to record work in TODO.md; the scanner defect is issue #4,
the audio_tables mutation gap is #25, and the UI gaps are libakgl #79 and #80.
Verified: cmake --build build && ctest --test-dir build, 112/112.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
This repository has no AGENTS.md; CLAUDE.md and MAINTENANCE.md carry the same
rules, so both are updated.
Outstanding work is an issue on the forge now, with the file and line, the
functional consequence, and what closing it would touch. TODO.md is the record
-- settled design decisions, the deviation register, defects already fixed, and
the reasoning behind the measurements -- and its row in CLAUDE.md's reading
table says so, with the tracker listed above it.
The dependency rule gains the correction this migration produced. 'Never work
around a missing dependency capability here' now says to open an issue in that
repository's tracker, and says plainly that recording it here instead is not
filing it: two akgl_ui gaps sat in TODO.md for a release on the reasoning that
changing a submodule is that repository's decision, which is true of changing it
and not of reporting it. Both are libakgl issues now.
Cross-repository citations of deps/*/TODO.md sections point at the trackers.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Twenty-six issues on source.starfort.tech/andrew/akbasic, labelled by kind and
blast radius and milestoned by what they can land in: 0.1.x for anything that
changes no public contract, 0.2.0 for new verbs and observable behaviour
changes, 1.0.0 for the design decisions. Everything carries status::grooming.
Block surgery rather than a rewrite. Every open item is replaced by a line
saying what it was and which issue carries it; everything else -- the settled
design decisions, the deviation register, the fixed defects and the reasoning
behind the measurements -- is byte-identical. 3338 lines to 2966.
Two corrections found while doing it. The "what remains, in priority order"
list named groups A, D, F, J and H as outstanding language work; SS4's own table
shows every one of them done, and what actually survives is one piece of
structural work that is not a verb -- block skipping by source line, which is
why a whole FOR/NEXT on one line never loops. And the two UI gaps SS7 recorded
and declined to file are now libakgl #79 and #80: that section's rule is right
that changing a dependency is that repository's decision, and it does not
follow that reporting the gap is.
Cross-repository references to deps/*/TODO.md sections are repointed at the
trackers that now hold them, here and in MAINTENANCE.md.
Verified: cmake --build build && ctest --test-dir build, 112/112.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
Group K, and the first verbs to reach the akgl_ui subsystem 0.9.0 brought
in: MENU and GETMENU and RMENU, DIALOG, HUD and UISTYLE. A program that
wanted a title screen had to draw one out of CHAR and GETKEY, which is
what both breakout tutorials make a reader do.
The interesting part is the impedance mismatch. libakgl's UI is immediate
mode -- widgets are re-declared inside a frame bracket every frame and
clay borrows their text until the bracket closes -- and a BASIC program
says MENU 1, "START" on line 100 and expects it up on line 900, several
hundred frames later. So src/ui_akgl.c is retained on this side and
immediate on that one: the record's entry points are setters that copy
into akbasic_AkglUi, and akbasic_ui_akgl_render() replays the whole set
once a frame from the host's pump. No BASIC string, which lives in the
per-line value pool, is ever what clay is handed.
The shapes are borrowed rather than invented. MENU retires the way SOLID
does -- no entries retires one, no arguments retire them all. GETMENU
holds the step loop the way GETKEY does, so parking is not blocking: the
step still returns, the host keeps its frame rate, and the sprite, audio
and collision services keep running underneath because they run before
the blocking checks. RMENU(n,1) reads and clears the way BUMP() does.
Withdrawing the device or retiring the menu releases a holding GETMENU
with 0 rather than wedging the script, which is akbasic_input_service()'s
rule for a withdrawn keyboard.
One thing a program has to know, and docs/19-user-interface.md says it
twice: a menu that is up owns the cursor keys and Return. It has to, and
retiring it gives them back -- forget the MENU n before an INPUT and the
INPUT never sees the Return that ends it.
akbasic_runtime_set_ui() is its own function rather than a fifth argument
to akbasic_runtime_set_devices(), whose signature has twenty-eight call
sites in tests and documentation that are about something else.
deps/libakgl is not touched. akgl_UiAnchor has the four corners and dead
centre, so HUD offers exactly those five; TODO.md records what a
top-centre and bottom-centre would cost upstream, along with the three
other things this deliberately leaves out. No new error code either --
DEVICE, BOUNDS, SYNTAX and TYPE cover the group, and 520 stays free.
tools/screenshot.c had to learn that "needs a font" and "draws the text
grid" are two questions. They were one, and a UI figure came out black:
the text layer owns every pixel of the rows it covers and painted over
the widgets. The new ui=1 fence attribute asks for the first without the
second; MAINTENANCE.md documents it.
112/112 in both configurations, 112/112 under ASan and UBSan, coverage
94.1% against the 90% gate with src/runtime_ui.c at 99% of lines and
100% of functions, doxygen clean, and the four new figures byte-identical
on a re-render. TODO.md section 8's gate table was stale on several
counts besides these and is refreshed with measured numbers.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
0.9.0 is the akgl_ui subsystem: a vendored clay, an arena, menus, HUDs and
dialogs, reached through a new akgl/ui.h this project does not include. Every
header the akbasic_akgl target actually compiles against is byte-identical to
0.8.0, so unlike the 0.8.0 bump there is no sizeof to get wrong. The floor in
include/akbasic/akgl.h moves to 0.9.0 anyway, on the standing rule that the
soname carries MAJOR.MINOR while the major is 0.
It does not configure as it stands. 0.9.0 moved eight test property calls off
set_tests_properties -- correctly, because that command splits a
semicolon-separated value and had been silently reducing its LD_LIBRARY_PATH
prepend list to one directory -- onto set_property(TEST ...). This repository
suppresses add_test() while it pulls its dependencies in, so those test names do
not exist, and set_property errors on an unknown test name where
set_tests_properties was silent: eight hard configure failures. Shadow
set_property in its TEST form only; every other form has to pass through, since
the dependencies set target and directory properties their own builds need.
libakgl's status band grew to seven codes with AKGL_ERR_UI and it now owns 256
to 262, so the coordinated range map, docs/15-error-codes.md and both header
comments follow. TODO.md section 5's persistent-drawing-layer item still stands:
0.9.0's arena draws inside the frame like everything else, and there is still no
render-to-texture layer.
Both configurations build and both suites pass -- 110/110 without libakgl,
111/111 with it, akgl_typing included.
Co-Authored-By: Tachikoma (Claude Code Opus 5 1M) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
The megademo gains a scene: an 800x600 vaporwave sunset carried inside
the listing, then six looping delta frames of full motion video -- the
floor grid rolling forward and the sun's slices crawling, about 220
bytes a frame. DATA cannot carry an image (512 items, ~350 owned by the
stroke font), so the picture rides in RLE-encoded string literals
decoded with INSTR: 2 KB of base frame, 1.3 KB of video. Row records
jump the decoder between changed rows, an unreachable colour is the
skip, black draws so a delta can erase, and the rays are struck live
over every frame rather than encoded. The 63-byte bird gliding over it
is the one image DATA does have room for, via SPRSAV's type-in form.
examples/megademo/vaporwave.py composes the image in palette space,
dithers by row so the gradients band instead of shattering the RLE,
proves base-plus-deltas reproduces every frame against a simulation of
the decoder, and owns the generated block between the PICTURE markers.
TODO.md section 4 records the DATA ceiling and the wanted verb.
Co-Authored-By: Claude Code (Fable 5) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
A six-scene demoscene production that pushes the interpreter to its
edges on purpose: an LCG where there is no RND, redrawn strokes where
the palette cannot be written, the sprite bank as the scrolltext, a
supernova and black hole out of SOLID/COLLISION/RSPPOS, wireframe 3D
from two rotations and a perspective divide, and a single-queue
beeper-style soundtrack with a noise drum break.
The same file runs in the standalone frontend and in the clockless
screenshot host, which gets each scene as a still. Three interpreter
lessons learned the hard way are recorded in the example's README and
TODO.md section 4: a scalar first assigned in a GOSUB dies with its
scope, predeclaring scratch runs the 128-slot variable pool dry, and
a TI# busy-wait starves the PLAY queue of its one release per frame.
Co-Authored-By: Claude Code (Fable 5) <noreply@anthropic.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
The assembly step still carried the pre-conversion FILLROW, without the
SOLID registration Step 8 spends a section teaching -- a reader following
the assembly order got a wall the ball passes straight through.
DRAWHUD cleared the graphics layer and never stamped the HBL$ eraser Step 6
tells you to make. Both together took the field down every time a digit in
the HUD changed. It is GRAPHIC 1, 0 and a GSHAPE of HBL$ at 0, 0, and the
difference between that and the routines that draw the field is now stated
rather than left to be discovered.
Also say where HUDTEXT is called from, which nothing did.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
A reader building the game from the chapter alone had to guess at all of
these, and three of them are code the chapter describes and never shows:
- the HUD eraser stamp, promised in Step 6 as "make a second one while you
are here" and then never given
- the gem roll at the end of ONEBRICK, without which nothing ever drops
- BX1# and BY1#, which SPAWNGEM reads and only ONEBRICK can set
And three rules the chapter leans on without stating:
- MID and INSTR count from zero, which is what makes a glyph number an
array index with no adjustment
- sprite n sets bit 2^(n-1), which is where 16, 32 and 64 come from
- states 5 and 6 have no tick routine on purpose; that is what a pause is
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
A reader building chapter 17 from the text alone had to infer that
COLLISION 2, BRICKHIT belongs in the setup block rather than the frame
loop, and met SCNCLR and QUIT for the first time in the assembly step.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
§6 item 39 is done: both listings and both tutorials are on SOLID,
COLLISION 2 and RCOLLISION. Record the two traps the conversion turned up
that no error reports -- BUMP's mask is by sprite number, so the artwork
game's balls are bits 16, 32 and 64; and a bare SOLID after the fill loop
retires the rectangles it was meant to precede.
§6 item 38 and §9 item 9 carried statements the work since made false.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EwxGB6TdoVvZ11KQQME9cL
Co-Authored-By: Andrew Kesterson <andrew@aklabs.net>
