Bronze Age Lisp Readme File
---------------------------
* About Bronze Age Lisp
---------------------
Bronze Age Lisp is an interpreter of Kernel Programming
Language and compatible with klisp. It is written in
assembly and Klisp, and runs on Linux on 32-bit x86
platforms. The interpreter, including its source code,
is freely available under under the MIT license.
* About the language
------------------
Kernel is a dialect of Lisp, descended from Scheme,
featuring FEXPRs and first-class environments. Klisp
is a robust interpreter of the language. You can
find more information about Kernel and Klisp here:
http://web.cs.wpi.edu/~jshutt/kernel.html
http://www.klisp.org/
https://bitbucket.org/AndresNavarro/klisp
* Installation
------------
To build the interpreter, you need a x86 Linux system, and:
- Klisp (https://bitbucket.org/AndresNavarro/klisp)
- NASM the Netwide Assembler (http://nasm.sourceforge.net)
- GNU toolchain (GCC, GNU linker and Make, http://www.gnu.org)
- Unicode Character Database (http://www.unicode.org/ucd/)
1) Download and unpack the Unicode Character Database:
$ mkdir UNIDATA
$ cd UNIDATA
$ wget http://www.unicode.org/Public/UNIDATA/UCD.zip
$ unzip UCD.zip
2) Generate unicode-related tables for the interpreter:
$ cd src/unicode
$ ./extract.sh <PATH-TO-UNIDATA>
3) Make sure that Klisp executable is in $PATH. Build
the interpreter:
$ cd src
$ ./build.sh
Then, you can run the REPL
$ build/bronze.bin
* Binary distribution
-------------------
If you do not want to build from source, you can download
compiled executables from
https://bitbucket.org/havleoto/bronze-age-lisp/downloads
* Interpreter characteristics
---------------------------
The language runtime is implemented in assembly, with
the help of NASM macros and code generated by a klisp
program. Notably, the interpreter does not use and
is not compatible with C language runtime. Currently,
it is not possible to link the interpreter with programs
or libraries written in C or any other language.
Built-in combiners are implemented partly in assembly,
and partly by interpreted lisp code. The interpreted code is
included in the interpreter executable in binary form, along
with table representing the ground environment and strings,
symbols and other necessary constants.
Lisp values are represented by 32-bit words. Fixints,
characters, booleans and special values like #inert are
stored directly. Strings, symbols, keywords and bytevectors
are represented by tagged indices to a global table of
string-like values (blobs). Pairs are represented by tagged
pointers to 8-byte memory blocks without a header. Other
values are represented by pointers to memory blocks with a
4-byte header. The header encodes the type and length of the
block.
Structured values are allocated at runtime on heap managed
by simple copying collector. Special mode of allocation
is employed for some continuations and environments, allowing
faster reclamation. Blobs are allocated separately from
structured values and reclaimed by a mark-and-compact
garbage collector. Symbols are never reclaimed.
Since the objects may be stored in read-only memory,
the objects do not contain mutable mark bits. If necessary,
the marks are stored in the unused half-space of the
copying collector.
Heap size and other interpreter configuration parameters
are fixed at build time and cannot be changed at run time.
* Contents
--------
src/
runtime/*.{k,asm} -- implements basic runtime
modules/*.{k,asm} -- implements language features
unicode/* -- generates tables for (char-alphabetic? ...) etc.
configuration.k -- contains configuration (heap size, etc.)
mold.k -- generates code of the interpreter
other *.k files -- contain support procedures
build.sh -- controls the building and linking
quickbuild.sh -- faster version of build.sh
doc/
compatibility.txt -- Notes on compatibility with language definition
and klisp
reference.txt -- List of implemented bindings and documentation
of extensions not present in klisp.
tst/
asm/*.asm -- unit tests on assembly level
smoke/*.k -- tests by comparison with klisp
dual/*.k -- test builtins against derivations from the Kernel Report
self/*.k -- other tests
test.sh -- runs all tests
tools/
*.k -- small collection of utility scripts
benchmarks/
*.k -- short benchmark programs
benchmark.sh -- runs benchmarks and compares performance against klisp
examples/
*.k -- example programs
README -- this file
TODO -- lists missing functionality
TROUBLESHOOTING -- explains causes of usual problems