[Guile-commits] 33/86: Flesh out README

[Andy Wingo]

wingo pushed a commit to branch lightening
in repository guile.

commit 02ce8952efd1349cdbecc88d6d576f9be7259448
Author: Andy Wingo <address@hidden>
Date:   Mon Mar 25 15:36:12 2019 +0100

    Flesh out README
---
 README    |  3 ---
 README.md | 29 +++++++++++++++++++++++++++++
 2 files changed, 29 insertions(+), 3 deletions(-)

diff --git a/README b/README
deleted file mode 100644
index ae36ea5..0000000
--- a/README
+++ /dev/null
@@ -1,3 +0,0 @@
-GNU lightning is a library to aid in making portable programs
-that compile assembly code at run time.  For more information,
-look at the info documentation.
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..448e4c8
--- /dev/null
+++ b/README.md
@@ -0,0 +1,29 @@
+# Lightening
+
+Lightening is a just-in-time code generation library derived from GNU
+Lightning, adapted to the purposes of the GNU Guile project.
+
+## Use
+
+```
+gcc -flto -O2 -g -o jit.o -c jit/jit.c
+gcc -flto -O2 -g -o my-program jit.o my-program.c
+```
+
+See the GNU Lightning manual for more on how to program against
+Lightening (much of the details are the same).
+
+## What's the difference with GNU Lightning?
+
+This project is called Lightening because it's lighter-weight than GNU
+Lightning.  When you go to generate code at run-time with GNU Lightning,
+what happens is that you build up a graph of nodes which GNU Lightning
+"optimizes" before finally emitting machine code.  These optimizations
+can improve register allocation around call sites.  However they are not
+helpful from a Guile perspective, as they get in the way of register
+allocation that we need to do; and they actually prevent access to all
+the registers that we would like to have.
+
+Guile needs a simple, light-weight code generation library.  The GNU
+Lightning architecture-specific backends provide the bulk of this
+functionality, and Lightening wraps it all in a lightweight API.