Andrew Kesterson
cb0e2d0800
Two complete games in `examples/breakout/`, both 100% BASIC: `characters/` draws its wall in the text grid with two `DATA` sprites for the ball and paddle, and `sprites/` loads CC0 artwork and captures its whole screen with `SSHAPE`/`SPRSAV`. They take opposite shapes for reasons that are entirely this interpreter's, which is what the chapters are for. `docs/17-tutorial-breakout.md` and `docs/18-tutorial-breakout-artwork.md` build each one a step at a time, and end in a checklist of the rules a real program runs into: create every name before the loop starts, write a text row whole, loop with `GOTO` rather than `DO`, put the float on the left. Every trap is a runnable block with its own output rather than a claim -- the value pool dying at four thousand names, the skipped `BEGIN` block that breaks its caller's `RETURN`, `SSHAPE` ignoring a subscript, `READ`'s single cursor. Five figures, generated from the listings beside them by `docs_screenshots`, and a `breakout_art` setup so the ones that load artwork load the example's own. The character game's wall cannot be photographed -- the screenshot host omits the text layer on purpose -- so it is shown as compared output instead. `docs/07-sound.md` never said `SOUND`'s frequency is a SID register value rather than hertz, which both games depend on. It says so now, with the conversion from `src/audio_tables.c:84`. `TODO.md` gains the thirteen defects the two games turned up -- §6 items 30 to 33 and all of §9 -- each with a reduction that fits on a screen, the file and line of the cause, and what a fix would touch. Verified: `docs_examples` passes in both build configurations, `docs_screenshots --check` re-renders all thirteen figures and byte-compares them, the full 109-test suite passes in both builds, every quoted fragment was checked to appear verbatim in the listing it came from, and every relative link and anchor resolves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
4.0 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: eighteen chapters, verb and function reference. Chapter 14 is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. Chapter 15 is the error-code appendix. Chapters 17 and 18 are tutorials that build the games in examples/breakout/ |
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.