# 1. Introduction

## What akbasic is

A BASIC interpreter written in C, styled after **Commodore BASIC 7.0** and
**Dartmouth BASIC**. It does three things:

- **Runs a program from a file.** `basic program.bas` loads it, runs it, and exits.
- **Gives you a prompt.** `basic` with no arguments is a REPL: type lines with
  numbers to build a program, type verbs without numbers to run them immediately.
- **Links into a program as a library.** A game can embed the interpreter, hand it a
  script, and step it a frame at a time. That is the reason for most of the design
  decisions you will notice.

It is a rewrite of an earlier Go implementation, which is kept only as a reference for
questions about semantics. Its acceptance corpus is checked in here and runs on every
build.

## What akbasic is not

**It is not an emulator.** There is no 6502, no VIC-II, no SID, no 1541 and no
bank-switched memory. Verbs that only make sense against that hardware are either
reinterpreted for a modern machine — and Chapter 13 says exactly how — or refused by
name with the reason. Nothing is silently ignored.

**It is not byte-compatible with a C128.** Error numbers are not Commodore's, floating
point is IEEE double rather than Commodore's five-byte format, and a handful of
statements parse differently. Again: Chapter 13.

## Two builds

The default build has no dependency on SDL and no graphics, sound, sprites or windowed
text. Everything else works, and the whole test suite runs on a machine with no SDL
installed at all.

```sh
cmake -S . -B build
cmake --build build
```

The SDL build adds a window, the Commodore font, and the graphics, sound and sprite
devices. It needs [libakgl](https://source.starfort.tech/andrew/libakgl), which is
vendored as a submodule.

```sh
git submodule update --init --recursive
cmake -S . -B build-akgl -DAKBASIC_WITH_AKGL=ON
cmake --build build-akgl
```

A verb that needs a device the build does not have does not crash and does not lie. It
reports itself by name:

```
? 10 : RUNTIME ERROR DRAW needs a graphics device and this runtime has none
```

That is the same message an embedded host sees when it deliberately withholds a
device — a game may want a script that can print but not draw.

## Running the tests

```sh
ctest --test-dir build --output-on-failure
```

The suite includes the original Go implementation's acceptance corpus, byte-compared,
plus this project's own tests for everything the corpus does not reach.

## Where to go next

Chapter 2 gets a program running. If you already write BASIC 7.0, read
**[Chapter 13](13-differences.md)** first — it is short, and it will save you the
three or four surprises that would otherwise find you one at a time.