README.md (4051 bytes)
1 # forthlisp 2 3 A Scheme that runs on a small chip, on top of a Forth kernel built for that chip, on top of 4 machine code assembled by Lisp on the host. Every layer is built from scratch. This repo 5 holds the parts that both targets share: the host-side Lisp, the Scheme (written in Forth 6 words), the R7RS test harness and the reference-page generator. 7 8 ``` 9 4 LISP R7RS-small subset Scheme, written in Forth words (lisp.fs), loaded through 10 the chip's Forth console; prims.lisp + prelude.scm on top 11 3 FORTH the target's own Forth kernel (in the target repo) 12 2 SBCL breadboard on the host: assembler, primitive templates, metacompiler, 13 serial driver, test harness (host.lisp, suite.lisp here; assemblers in the targets) 14 1 ASM the target's instructions: Thumb-2 (STM32F446) or Z80 15 ``` 16 17 Targets: 18 19 - [forthlisp-stm32](https://github.com/equwal/forthlisp-stm32): STM32F446 (Cortex-M4F) in QEMU `netduinoplus2` 20 - [forthlisp-z80](https://github.com/equwal/forthlisp-z80): Z80 in z80pack `cpmsim` 21 22 Reference page with cheat sheets and the full spec: https://dickt.store/forthlisp/ 23 24 ## Quickstart 25 26 Check out this repo next to a target repo; the targets find it at `../forthlisp` (or set 27 `FORTHLISP_CORE`): 28 29 ```sh 30 git clone https://github.com/equwal/forthlisp 31 git clone https://github.com/equwal/forthlisp-stm32 32 cd forthlisp-stm32 && ./build-firmware.sh && ./stm32-lisp 33 ``` 34 35 Needs SBCL, `qemu-system-arm`, `arm-none-eabi-as`/`objcopy` (for the assembler tests), and 36 `nc`. At the `>` prompt, type Scheme. `(forth)` returns to the Forth prompt. 37 38 ## Files 39 40 - `host.lisp`: host compiler for a small Lisp dialect into Forth words, the serial 41 driver, and the commands `load`, `demo`, `ktest`, `test`, `suite`, `eval`, `forth` 42 - `lisp.fs`: the Scheme in Forth: tagged values, mark-sweep GC with a conservative stack 43 scan, a compacting blob heap for strings, vectors and bytevectors, a tail-calling eval, 44 the reader and the printer 45 - `prims.lisp`: arithmetic and type primitives, written in the host dialect 46 - `prelude.scm`: library procedures written in the chip Scheme 47 - `r7rs-tests.scm`: our own regression suite (`EXPR ==> printed result`) 48 - `tests/r7rs/`: chibi-scheme's R7RS-small suite, vendored unmodified (BSD, see its 49 `LICENSE`), with `shim.scm`, the machine-readable `skip.scm` and `results.txt` 50 - `suite.lisp`: runs that suite over the serial link 51 - `docs/build-docs.py`: generates the reference page from the sources 52 53 ## Test counts (STM32F446 target, QEMU) 54 55 - Our regression suite: see `conformance.txt` (390/390 at publication) 56 - chibi-scheme R7RS suite: see `tests/r7rs/results.txt` (603 passed, 140 failed, 389 skipped 57 of 1132 at publication; every skip names its reason) 58 59 ## Limits 60 61 - Fixnums are 31-bit; overflow is an error, and there are no bignums. 62 - Inexact reals are IEEE single precision (the M4F FPU); R7RS expects double. 63 - Characters are bytes; there is no Unicode. 64 - `syntax-rules` is not hygienic, and `call/cc` is escape-only. There are no libraries and no 65 ports beyond the console yet. `NOTES.md` lists every deviation. 66 67 ## Influences 68 69 - Paul Khuong, "SBCL: the ultimate assembly code breadboard" 70 (https://pvk.ca/Blog/2014/03/15/sbcl-the-ultimate-assembly-code-breadboard/): machine code 71 written and tested from the SBCL REPL. The assemblers here reuse SBCL's `sb-assem` segments 72 and labels. 73 - Ron Garret, gll-mag-patch (https://github.com/rongarret/gll-mag-patch): a Lisp-hosted Forth 74 toolchain that rebuilt and patched the Galileo magnetometer's flight code. 75 - Ron Garret, "Lisping at JPL" (https://flownet.com/gat/jpl-lisp.html): the live REPL on 76 Deep Space 1, and why a patchable live image matters. 77 78 ## Licence 79 80 MIT (see `LICENSE`). `tests/r7rs/r7rs-tests.scm` is chibi-scheme's, under its BSD licence 81 (`tests/r7rs/LICENSE`). 82 83 ## CI 84 85 `ci-local.sh` (in the forthlisp core repo) runs every test layer of all three repos in a 86 clean `ubuntu:24.04` container. It runs after each publish, without a hosted CI service. 87 The last result is on https://dickt.store/forthlisp/.