75 lines
2.7 KiB
Markdown
75 lines
2.7 KiB
Markdown
|
# 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.
|