Andrew Kesterson
23ccb66f69
Some checks failed
akbasic CI Build / cmake_build (push) Successful in 3m2s
akbasic CI Build / sanitizers (push) Successful in 3m50s
akbasic CI Build / coverage (push) Failing after 3m22s
akbasic CI Build / akgl_build (push) Failing after 20s
akbasic CI Build / mutation_test (push) Successful in 12m19s
Chapters 1 through 13 describe the language. Nothing described the machine that runs it, and the answers were spread across header comments, TODO.md sections written for a different purpose, and the source itself. Somebody embedding the interpreter, debugging something it did, or adding a verb had to reconstruct the shape from all three. docs/14-architecture.md is that shape, and only that: the three targets and the driver, the single akbasic_Runtime and why nothing is file-scope, akbasic_runtime_step() unrolled with the reason each stage sits where it does, the four modes and what set_mode() does beyond assigning, a line's journey from text through tokens and leaves to a verb handler, the dispatch table, the pool map with what each exhaustion actually says, environments doubling as block state, the two kinds of error, devices, and interrupts. It defers rather than restates. The headers are the authority on every function's contract and the chapter says so up front; where a rule is subtle the header comment already states it at more length than a chapter should. MAINTENANCE.md keeps the conventions and now points here for the mechanism, so there is still one copy of each. Two sections are the reason it exists at all. Debugging: reading a TRON trace as evidence about the loop rather than the lines, reading an akerror stack trace and what it is not, four breakpoints and the expressions worth printing at them, narrowing with ctest -R and the mock devices, and a symptom-to-cause table. Changing it: the verb recipe end to end including the private src/verbs.h prototype that is easy to miss, the rule that a missing dependency capability gets filed upstream rather than worked around, and the five constraints goal 3 puts on any change. A `text` fence tag comes with it. Every fenced block in docs/ is executed and an untagged one is a hard error, so six block diagrams had nowhere to live. The tag means never executed, it is counted in the skip line like `cmake`, and MAINTENANCE.md documents it -- the alternative was an indented block the extractor never sees, and a picture nobody decided about is indistinguishable from a test nobody ran. tests/docs_examples.sh now makes --root and --basic absolute before it starts. Both are used from inside a sandbox directory it cd's into, so the invocation MAINTENANCE.md itself documents -- --root . --basic ./build/basic -- failed every example with "exited 127" and every setup= with "setup failed". CTest passes absolute paths and never saw it; running one document by hand hits it immediately. Writing the error section turned up a defect and TODO.md section 8 records it. The ATTEMPT blocks that turn a script's mistake into an error line wrap parsing and interpretation but not scanning, so a line with more than 32 tokens escapes as an interpreter error: stack trace, exit 1, and at a prompt the REPL is gone. That is the same shape as section 8 item 2, on a path that fix did not cover. Not fixed here -- it is a behaviour change and wants its own tests -- but written down with the three call sites and what would cover them. Both configurations stay green: 95/95 and 94/94. docs_examples now runs 37 programs, 9 transcripts, 45 output comparisons, 3 C snippets, 2 excerpts and 2 shell blocks, and skips 9 text blocks. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
63 lines
3.8 KiB
Markdown
63 lines
3.8 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: fourteen 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 |
|
|
| `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.
|