diff --git a/README.md b/README.md index 3fe54d8..29623e7 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,24 @@ # lisp-compiler -Compiles a LISP dialect into regular binaries using LLVM. \ No newline at end of file +This is an experimental implementation of a LISP dialect, using LLVM to produce executable binaries. The objective of this project is to allow for the use of LISP in compiled contexts, accompanying other compiled code from languages like C and C++. +In particular, this would allow for the use of LISP in embedded or other low-resource applications that require native execution speed. + +The compiler is being designed according to the [R7RS-small](https://small.r7rs.org/) standard for the Scheme dialect of LISP. Complete compliance is the goal, though the priority of producing compiled binaries with low overhead may require some deviations from the standard. + +## Compilation + +This project requires the LLVM development libraries and a compiler that supports C++20. Simply run `make` to produce the compiler binary `main`. + +## Usage + +`main` takes the LISP code in its arguments and attempts to compile it. If successful, an `out.o` object file will be produced; this can be executed if linked using a compiler like `gcc`: `gcc out.o -o out`. + +Statements are processed in order, and command statements are placed inside a `main` function. For example: + +``` +./main "(define myvariable 13) (define getmyvariable (lambda () myvariable)) (getmyvariable)" +``` + +The above code defines a global variable, a function that returns that variable's value, and then puts a call to that function in `main`. Soon, that return value will be returned through `main` as one would expect. + +Support for reading source code from files or stdin will be added in the future.