Andrew Kesterson
80b76ad467
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m2s
akbasic CI Build / sanitizers (push) Successful in 3m51s
akbasic CI Build / coverage (push) Failing after 3m24s
akbasic CI Build / akgl_build (push) Failing after 20s
akbasic CI Build / mutation_test (push) Has been cancelled
README.md was 577 lines and answered four different questions at once: what
the project is, how to build it, every verb and function in the language, and
how to maintain the test harness. The verb and function lists had already been
written a second time in docs/11 and docs/12, which is how a list of that size
goes stale -- there is no way to notice the two have drifted apart.
README.md is now 150 lines and holds only what somebody evaluating the project
needs: what it is, the quickstart, why it was rewritten in C, the five rules
embedding imposes on the design, the two ways to use it, and where everything
else lives. Technical detail goes to docs/, maintenance to MAINTENANCE.md.
The akbasic_TextSink struct moved to docs/10-embedding.md rather than being
deleted. It was the corpus's only `c excerpt=` block -- the check that caught
the stale struct two commits ago -- so dropping it with the README would have
quietly retired a test. docs/10 also stopped claiming README.md carries the
full API surface and the pool limits, which the trim made false.
CLAUDE.md went from 458 lines to 62, because almost none of it was
agent-specific. The project goals, the Go reference and its architecture, the
dependency version and ABI rules, the four ways an embedded build collides,
the libakerror convention, the error-code range map and the style rules are
all things a maintainer needs, and they are now in MAINTENANCE.md with one
copy to keep true. CLAUDE.md points there and keeps only the rules no test
enforces: tests in the same commit asserting the correct contract, file a
missing dependency capability upstream, do not edit generated output or
tests/reference/, co-author your commits.
Four claims did not survive the move, having gone stale where nothing could
notice:
- "The repository is currently empty apart from its submodules -- no
commits, no source tree, no build files." There are 43 commits.
- libakgl's target_compile_definitions(akerror PUBLIC AKERR_MAX_ERR_VALUE)
at deps/libakgl/CMakeLists.txt:44, described as inert but present. It is
gone; only a historical mention in a comment remains.
- "akbasic_init() claims 512-767." There is no akbasic_init. It is
akbasic_error_register(), called from akbasic_runtime_init().
- Time-relative phrasing ("libakgl hit two of them in the last week").
Five places pointed at CLAUDE.md for the range map or the file-it-upstream
rule and now point at MAINTENANCE.md: include/akbasic/error.h,
src/runtime_disk.c and three entries in TODO.md. Both source changes are
comments. deps/libakgl/TODO.md cites it too and is left alone; it is a
submodule, and the rule it quotes is still reachable from CLAUDE.md.
ctest is green at 95 of 95, docs_examples included: 36 programs, 9
transcripts, 44 output comparisons, 3 C snippets, 1 excerpt.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
3.7 KiB
3.7 KiB
CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
Read MAINTENANCE.md first
MAINTENANCE.md is the authoritative document for changing this project,
and it is written for whoever has to do the changing — human or agent. It carries what used to
live in this file: the project goals, the Go reference implementation and its architecture, the
dependency versions and their ABI rules, the four ways an embedded build collides, the
libakerror error convention, the coordinated error-code range map, the test lists, the
documentation-example harness, and the style and commit rules.
There is one copy of all of that, on purpose. Anything you would have added here, add there instead — the maintainer needs it as much as you do, and a second copy is a second thing to keep true.
akbasic is a C rewrite of the Go BASIC interpreter in deps/basicinterpret, written in the
idiom of the ak* C libraries it builds on, and meant to end up embedded in libakgl as a
scripting engine for game authors.
| Read | For |
|---|---|
MAINTENANCE.md |
Everything above. Start here |
TODO.md |
Outstanding defects, with file, line and consequence. §0.1 first — it retires the byte-for-byte fidelity constraint several later sections were written on |
README.md |
What the project is and why, for somebody who has not seen it |
docs/ |
The language itself: thirteen chapters, verb and function reference |
deps/libakerror/AGENTS.md |
The ATTEMPT/CLEANUP/PROCESS/HANDLE/FINISH protocol, authoritatively |
deps/libakerror/UPGRADING.md |
1.0.0's status registry. Required before writing an error code |
deps/<library>/AGENTS.md |
Per-repo rules. Read the relevant one before editing a submodule |
Before doing anything else in a fresh clone:
git submodule update --init --recursive
Rules that are on you rather than on a test
Most of the conventions in MAINTENANCE.md are enforced by something — a sorted-table test, a
WILL_FAIL list, a Doxygen gate, a byte-compared corpus. These are not, so they are worth
repeating where you will see them:
- Add tests in the same commit as the behaviour change, and assert the correct contract
even where the code is currently wrong. A known-failing test goes in
AKBASIC_KNOWN_FAILING_TESTSwith aTODO.mdentry; it does not get pinned to the buggy behaviour, because that turns the eventual fix into a test failure. - Never work around a missing dependency capability here. File it in that repository's
TODO.md— what the BASIC verb requires, what the entry point should look like, what tests would cover it.MAINTENANCE.mdexplains why, and names the four gaps this closed upstream. - Never edit generated output —
build/trees, the generatedakerror.h,akgl.pc,include/akgl/SDL_GameControllerDB.h. Change the template or the generator script. - Do not reformat code you are not otherwise changing. Several files mix tabs and spaces and there is no repo-wide formatter; style conversions get their own commit.
- Do not edit
tests/reference/. Those expectations came from the Go implementation and are never edited to suit this interpreter. A deliberate divergence goes inTODO.mdanddocs/13-differences.md. - Update
TODO.mdwhen you learn something about a defect, including that it is worse or better than recorded. Publishing a problem you cannot fix yet is a contribution. - Add yourself — program, model and version — as a commit co-author.
libakgl'sAGENTS.mdrequires it and this repository follows the same rule.