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
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: fourteen 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
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 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.