Skip to content

Commit

Permalink
Remove old code and update documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
jart committed Oct 9, 2021
1 parent cbb4ecc commit 4233210
Show file tree
Hide file tree
Showing 14 changed files with 3,757 additions and 704 deletions.
1 change: 1 addition & 0 deletions LICENSE
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
Copyright 2020 Justine Alexandra Roberts Tunney
Copyright 2021 Alain Greppin

Permission to use, copy, modify, and/or distribute this software for
any purpose with or without fee is hereby granted, provided that the
Expand Down
60 changes: 9 additions & 51 deletions Makefile
Original file line number Diff line number Diff line change
@@ -1,70 +1,28 @@
CFLAGS ?= -g
CFLAGS += -fno-pie
LDFLAGS += -no-pie # -s -static -N

REALFLAGS = \
-Os \
-D__REAL_MODE__ \
-wrapper ./realify.sh \
-ffixed-r8 \
-ffixed-r9 \
-ffixed-r10 \
-ffixed-r11 \
-ffixed-r12 \
-ffixed-r13 \
-ffixed-r14 \
-ffixed-r15 \
-mno-red-zone \
-fcall-used-rbx \
-fno-jump-tables \
-fno-shrink-wrap \
-fno-schedule-insns2 \
-flive-range-shrinkage \
-fno-omit-frame-pointer \
-momit-leaf-frame-pointer \
-mpreferred-stack-boundary=3 \
-fno-delete-null-pointer-checks

CLEANFILES = \
lisp \
lisp.o \
lisp.real.o \
bestline.o \
sectorlisp.o \
start.o \
lisp.bin \
sectorlisp.bin \
lisp.bin.dbg \
sectorlisp.bin.dbg

.PHONY: all
all: lisp \
lisp.bin \
lisp.bin.dbg \
sectorlisp.bin \
sectorlisp.bin.dbg

.PHONY: clean
clean:; $(RM) $(CLEANFILES)
clean:; $(RM) lisp lisp.o bestline.o sectorlisp.o sectorlisp.bin sectorlisp.bin.dbg

lisp.bin.dbg: start.o lisp.real.o lisp.lds
lisp: lisp.o

start.o: start.S Makefile
lisp.o: lisp.c lisp.h Makefile
lisp.real.o: lisp.c lisp.h Makefile
lisp: lisp.o bestline.o
lisp.o: lisp.c bestline.h
bestline.o: bestline.c bestline.h

sectorlisp.o: sectorlisp.S
$(AS) -g -mtune=i386 -o $@ $<
$(AS) -g -mtune=i386 -o $@ $<

sectorlisp.bin.dbg: sectorlisp.o
$(LD) -oformat:binary -Ttext=0x7600 -o $@ $<
sectorlisp.bin: sectorlisp.bin.dbg
objcopy -SO binary sectorlisp.bin.dbg sectorlisp.bin

%.real.o: %.c
$(CC) $(CPPFLAGS) $(CFLAGS) $(REALFLAGS) -c -o $@ $<

%.bin.dbg:
$(LD) $(LDFLAGS) -static -o $@ $(patsubst %.lds,-T %.lds,$^)

%.bin: %.bin.dbg
objcopy -SO binary $< $@
sectorlisp.bin: sectorlisp.bin.dbg
objcopy -S -O binary sectorlisp.bin.dbg sectorlisp.bin
80 changes: 57 additions & 23 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,37 +1,71 @@
# sectorlisp

sectorlisp is an effort to bootstrap John McCarthy's meta-circular
evaluator on bare metal from a 512-byte boot sector.
sectorlisp is a 512-byte implementation of LISP that's able to bootstrap
John McCarthy's meta-circular evaluator on bare metal.

![Yo dawg, I heard you like LISP so I put a LISP in your LISP so you can eval while you eval](bin/yodawg.png)

## Motivations
## Overview

Much of the information about LISP online tends to focus on
[wild macros](http://www.paulgraham.com/onlisp.html),
[JIT compilation](http://pixielang.org/), or its merits as
[a better XML](http://www.defmacro.org/ramblings/lisp.html)
as well as [a better JSON](https://stopa.io/post/265). However
there's been comparatively little focus on the
[primary materials](https://people.cs.umass.edu/~emery/classes/cmpsci691st/readings/PL/LISP.pdf)
from the 1950's which emphasize the radically simple nature of
LISP, as best evidenced by the meta-circular evaluator above.
LISP has been described as the [Maxwell's equations of
software](https://michaelnielsen.org/ddi/lisp-as-the-maxwells-equations-of-software/).
Yet there's been very little focus to date on reducing these equations
to their simplest possible form. Even the [original LISP
paper](https://people.cs.umass.edu/~emery/classes/cmpsci691st/readings/PL/LISP.pdf)
from the 1960's defines LISP with nonessential elements, e.g. `LABEL`.

This project aims to solve that by doing three things:

1. We provide a LISP implementation that's written in LISP, as a single
pure expression, using only the essential functions of the language.
See [lisp.lisp](lisp.lisp). It's the same meta-circular evaluator in
John McCarthy's paper from the 1960's, except with its bugs fixed,
dependencies included, and syntactic sugar removed.

2. We provide a readable portable C reference implementation to show how
the meta-circular evaluator can be natively bootstrapped on POSIX
conforming platforms, with a pleasant readline-like interface. See
[lisp.c](lisp.c).

2. We provide a 512-byte i8086 implementation of LISP that boots from
BIOS on personal computers. See [sectorlisp.S](sectorlisp.S). To the
best of our knowledge, this is the tiniest true LISP implementation
to date.

<p align="center">
<img alt="Binary Footprint Comparison"
width="750" height="348" src="bin/footprint.png">
<img alt="Binary Footprint Comparison" src="bin/footprint.png">
</p>

This project aims to promote the radical simplicity of the essential
elements of LISP's original design, by building the tiniest LISP machine
possible. With a binary footprint less than one kilobyte, that's capable
of running natively without dependencies on modern PCs, sectorlisp might
be the tiniest self-hosting LISP interpreter to date.
## Getting Started

See [lisp.lisp](lisp.lisp) for code examples that you can copy and paste
into your LISP REPL.

You can run the C implementation as follows:

```sh
$ make
$ ./lisp
```

After running `make` you should see a `sectorlisp.bin` file, which is a
master boot record you can put on a flopy disk and boot from BIOS. If
you would prefer to run it in an emulator, we recommend using
[Das Blinkenlights](https://justine.lol/blinkenlights/).

```sh
curl --compressed https://justine.lol/blinkenlights/blinkenlights-latest.com >blinkenlights.com
chmod +x blinkenlights.com
./blinkenlights.com -rt sectorlisp.bin
```

Alternatively you may use QEMU as follows:

```sh
qemu-system-i386 -nographic -fda sectorlisp.bin
```

We're still far off however from reaching our goal, which is to have
sectorlisp be small enough to fit in the master boot record of a floppy
disk, like [sectorforth](https://github.com/cesarblum/sectorforth). If
you can help this project reach its goal, please send us a pull request!
Further information may be found on [our wiki](https://github.com/jart/sectorlisp/wiki).

## Demo

Expand Down
Loading

0 comments on commit 4233210

Please sign in to comment.