Port the README from the Go version and document embedding

Carries the reference README across, adjusted where C changes the answer: cmake
instead of make, the ak* libraries instead of the go-sdl2 bindings, and the
limits table now includes the three ceilings the Go version did not need because
it called make().

The new "Embedding the interpreter" section is the point of the rewrite, so it
states the four rules the library holds to -- nothing terminates the process,
nothing calls malloc, no file-scope mutable state, the host owns the loop -- and
each was checked against the tree rather than asserted.

Adds akbasic_runtime_load(). Writing the section turned up a real gap: a host
usually already holds its script as a string and wants the sink reserved for
output, and the only path that existed was AKBASIC_MODE_RUNSTREAM reading the
program through the sink's readline, which forces a game to point its output
device at its source text. The alternative was reaching into the header's
"internal API" block for store_line. Neither is something to put in a README.

Adds examples/embed.c, which is the code the README quotes -- a custom sink, a
bounded per-frame run, and the PASS-not-CATCH rule for a loop inside an ATTEMPT.
It is built by every build and registered as a CTest case, so a signature change
breaks the build instead of rotting the document. The README's own snippet is
compiled separately as a check; both were run before committing.

The "What Isn't Implemented / Isn't Working" section leads with the eleven
inherited defects rather than burying them, because five of them were found by
this port and a reader deserves to know that 1 - 2 - 3 computes 1 - 2 before
they hit it. Corrected two claims while verifying: the runtime is 10.1MB rather
than the ~8MB first written, and its largest single cost is the environment pool
at 4.1MB, not the source table.

ctest 60/60; ASan+UBSan 60/60; no warnings under -Wall -Wextra.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
2026-07-31 06:42:08 -04:00
parent 7531df57ec
commit cde6fa8f59
7 changed files with 586 additions and 4 deletions

View File

@@ -20,6 +20,7 @@ include(CTest)
include(GNUInstallDirs)
option(AKBASIC_WITH_AKGL "Build the libakgl-backed text sink and link SDL3" OFF)
option(AKBASIC_BUILD_EXAMPLES "Build the embedding example in examples/" ON)
option(AKBASIC_COVERAGE "Instrument the build with gcov coverage counters" OFF)
option(AKBASIC_SANITIZE "Build with ASan + UBSan" OFF)
@@ -153,6 +154,16 @@ if(AKBASIC_WITH_AKGL)
endif()
akbasic_instrument(basic)
# The embedding example. It is built by default and registered as a test so the
# code README.md quotes cannot rot: a signature change breaks the build.
if(AKBASIC_BUILD_EXAMPLES)
add_executable(akbasic_example_embed examples/embed.c)
target_compile_options(akbasic_example_embed PRIVATE -Wall -Wextra)
target_link_libraries(akbasic_example_embed PRIVATE akbasic)
akbasic_instrument(akbasic_example_embed)
_add_test(NAME example_embed COMMAND akbasic_example_embed)
endif()
# ---------------------------------------------------------------------------
# Tests.
#