Andrew Kesterson
cb0e2d0800
Some checks failed
akbasic CI Build / cmake_build (push) Failing after 3m10s
akbasic CI Build / sanitizers (push) Failing after 4m5s
akbasic CI Build / coverage (push) Failing after 3m29s
akbasic CI Build / akgl_build (push) Failing after 21s
akbasic CI Build / mutation_test (push) Failing after 3m19s
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>
63 lines
4.0 KiB
Markdown
63 lines
4.0 KiB
Markdown
# 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`](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`](MAINTENANCE.md) | Everything above. Start here |
|
|
| [`TODO.md`](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`](README.md) | What the project is and why, for somebody who has not seen it |
|
|
| [`docs/`](docs/README.md) | The language itself: eighteen chapters, verb and function reference. [Chapter 14](docs/14-architecture.md) is the interpreter's architecture — the step loop, the pools, the two kinds of error, and how to debug it. [Chapter 15](docs/15-error-codes.md) is the error-code appendix. [Chapters 17](docs/17-tutorial-breakout.md) and [18](docs/18-tutorial-breakout-artwork.md) 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:
|
|
|
|
```sh
|
|
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_TESTS` with a `TODO.md` entry; 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.md` explains why, and names the four gaps this closed upstream.
|
|
- **Never edit generated output** — `build/` trees, the generated `akerror.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 in `TODO.md` and
|
|
`docs/13-differences.md`.
|
|
- **Update `TODO.md` when 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`'s
|
|
`AGENTS.md` requires it and this repository follows the same rule.
|