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