README

README

    Nil: Not an Implementation of Lisp

ChangeLog:

    v0.0.8    * All seven standard primitives.

    v0.0.7    * First-class primitives, first-class exceptions, bindings,
                evaluation.

    v0.0.6    * Evaluator skeleton.

    v0.0.5    * Parses the input correctly.

    v0.0.4.p1 * Cleanup release preparatory to parsing--the only visible
                change is the (+) notation for a new string added to the
                list.

    v0.0.4    * Now we have a list implementation and the list of known
                strings uses it.

    v0.0.3    * Same behavior as v0.0.2, but now the lexer is producing
                genuine Nil symbols and the read loop is printing them
                properly.

    v0.0.2    * Recognizes and prints the tokens entered on the input line.
                Added a welcome message and user-friendlified the input
                loop behavior.

    v0.0.1    * Echoes input lines and detects EOF, illegal characters,
                and I/O errors.

Nil is (will be, at this stage) a minimal lisp implemented directly in
handwritten LLVM Intermediate Representation ("LLVM Assembly").  See the
discussion at http://stoneknives.posterous.com for excuses as to why this is
not a deranged act (but note that you don't have to believe a word of it).  The
public repository is at http://github.com/dllaurence/Nil.

For the time being the code is licensed under the LGPL3, just so I'm
not guilty of releasing code into the wild with ambiguous terms.  But
frankly, if this is a concern for you, get help for your compulsion to
treat experimental code as more than it is. :-)

Building:

    Um...just type "make".  If it fails, figure out why and send me a
    patch.  A real build system would probably involve more red tape
    than all the Nil code. :-) You'll need a C compiler (for the bits of
    interfaced to the system) and LLVM.  Probably LLVM >= 2.5, possibly
    >= 2.6 if I've accidentally used anything new in 2.6.

Installation:

    Are you nuts?!?  I suppose you could copy the "nil" executable into
    /usr/local/bin or something.

Running:

Type "./nil" in the build directory and behold the glory.

In Nil 0.0.8 we have a minimal list-oriented language and even a small luxury
or two.  In particular we have the seven primitive operators from Graham's (and
therefore McCarthy's) paper: quote, atom, eq, car, cdr, cons, and cond, as well
as the predefined values t and () needed by atom and cond.  We also have
commands to quit, turn on and off a mode where undefined symbols are
self-quoting, display known symbols and strings, and even a minimal help
facility.  Of course there is a great deal of work under the hood to support
that functionality.

The most important features still missing are user-defined symbols and
especially functions.

HACKING

While there isn't much there yet, it's on github to be played with.  Note that
this is *very* unstable development code. :-)  While portability is a minor
concern at the moment the code has been built (if I felt like it) with LLVM 2.5
on x86 Fedora 11 as well as the with LLVM 2.6 on AMD64 Fedora 12 Linux.
However, LLVM should take care of most machine dependencies and Nil aspires to
be reasonably portable someday when it grows up, so report gross incivilities
in the github issue tracker.

This will help you know where to look first:

Conventions:

*.llm         IR source modules, to be preprocessed with CPP.
*.llh         Module declarations for #include

Code overview:

Makefile      I assume you know what this is.

Skel/         Skeleton source .llm, .llh, and test files

Main Nil implementation files:

nil.llh       Global declarations (types, #defines) for all source files.

nil.llm       has main(), and documentation you will want to read.  Also
              the evaluator and language-level functions during development.

System support files:

c_defs.c      A simple C program that writes things Nil needs to know
              about the local C implementation (e.g. the types needed
              to call into libc) into c_defs.llh

system_c.c    Some C functions callable from LLVM to obtain things not
              available through c_defs.llh (e.g. the stdio FILE pointers
              for stdin and stdout).

system_ll.llm Misc. utility functions, such as an LLVM assert() and nicer
              wrappers for particularly annoying libc functions.  Nothing
              in system_ll.llm, system_c.c, or system.llh should depend
              on the actual nil implementation, which means the code there
              should use the C calling convention and the C/libc types.

system.llh    #includes c_defs.llh, declares prototypes of useful libc
              functions (so LLVM knows their signatures and can typecheck
              calls) plus the prototypes for the functions in system_c.c
              and system_ll.llm, defines ASCII convenience constants, etc.

exp.ll[hm]    The expression implementation, plus support code such as
              the unique string list.

memory.ll[hm] The memory-handling code is here, both for strings (the
              unique string facility) and cells.

lex.ll[hm]    The nil lexer.  This should only depend on c_defs, system,
              and nil.llh--nothing here should use the expression code.
              That means the Lexemes get turned into Nil expressions
              in the parser.

parse.ll[hm]  The nil parser.