akbasic/CLAUDE.md

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
the issue tracker	Outstanding defects and gaps. Labelled by kind and blast radius; status::grooming means the scope is not settled yet
TODO.md	The record: settled design decisions, the deviation register, defects already fixed, and the reasoning behind the measurements. §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_TESTS with an open issue; 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. Open an issue in that repository's tracker on https://source.starfort.tech — 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. Recording it here instead is not filing it: two akgl_ui gaps sat in TODO.md for a release because changing a submodule is that repository's decision — which is true of changing it and not of reporting it.
• 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.
• Keep tests/language/ editable. Its .bas programs and sibling .txt expectations are changed together when behavior changes. Record deliberate language decisions in TODO.md or docs/13-differences.md.
• Open an issue for outstanding work; do not add it to TODO.md. https://source.starfort.tech/andrew/akbasic/issues, or tea issues create --repo andrew/akbasic. Name the file and line, the functional consequence, and what closing it would touch. Publishing a problem you cannot fix yet is a contribution — and when you learn something about an open issue, say so in the issue, including that it is worse than recorded, already fixed, or resting on a premise that has expired.
• Add yourself — program, model and version — as a commit co-author. libakgl's AGENTS.md requires it and this repository follows the same rule.