1 files changed, 112 insertions, 0 deletions
diff --git a/README.rst b/README.rst
new file mode 100644
index 0000000..531c9fa
--- /dev/null
+++ b/README.rst
@@ -0,0 +1,112 @@
+lisp16
+======
+
+Simple cross platform 16bit Lisp interpreter.
+
+* documentation - `<https://lisp16.kopic.xyz>`_
+* git repository - `<https://github.com/bozokopic/lisp16.git>`_
+
+
+About
+-----
+
+This project is intended as case study of Lisp implementation with following
+features:
+
+    * cross platform compatibility
+        * support for 8bit/16bit architectures (microcontrollers)
+        * possibility of running on POSIX systems
+        * small platform compatibility layer
+    * reduced Lisp dialect mostly based on Scheme
+        * LISP-1 namespace
+        * tail call optimization
+        * macros
+    * tree walking interpreter
+        * possibility of multiple independent interpreter instances as part of
+          single process
+        * simple mark and sweep garbage collection
+        * API design taking into account possibility of usage with foreign
+          function interface
+    * intended for educational/testing purposes
+        * emphasis on source code functionality organization over binary size
+          or lines of code (or other kinds of optimization)
+        * accompanied documentation with implementation explanation
+
+Following features are considered out of scope for this project:
+
+    * real-life production usage
+    * execution speed optimization
+    * virtual machine or machine code compilation
+    * rich standard library
+
+
+Building and usage
+------------------
+
+8bit AVR microcontrollers
+'''''''''''''''''''''''''
+
+Build targeting 8bit AVR microcontrollers (tested with ATmega328P) depends
+on `avr-gcc` and associated `binutils`.
+
+Shell script::
+
+    $ ./build-avr8.sh
+
+produces ``build/avr8/lisp16.bin`` binary that can be written to
+microcontroller's flash.
+
+After writing binary to flash, microcontroller will execute `lisp16` repl with
+UART used as input/output port.
+
+
+POSIX system
+''''''''''''
+
+Build targeting POSIX systems depends on C compiler (gcc with musl C library is
+used by default) and implementation of `getchar`/`putchar` and `malloc`/`free`
+functions (`malloc` can be replaced with static allocation in case multiple
+interpreter instances are not needed).
+
+Shell script::
+
+    $ ./build-posix.sh
+
+produces ``build/posix/lisp16`` static binary.
+
+Execution of ``build/posix/lisp16`` starts `lisp16` repl `stdin`/`stdout` used
+as input/output port.
+
+
+Documentation
+'''''''''''''
+
+Building of documentation depends on python with sphinx and furo modules
+available.
+
+Shell script::
+
+    $ ./build-docs.sh
+
+produces ``build/docs`` folder containing documentation.
+
+
+License
+-------
+
+lisp16 - simple cross platform 16bit Lisp interpreter
+
+Copyright (C) 2022 Bozo Kopic
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU General Public License as published by
+the Free Software Foundation, either version 3 of the License, or
+(at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.