From 8ecb35d3ed4ab120ac86f801f4f2177f2c9171c5 Mon Sep 17 00:00:00 2001
From: Danny Yoo <dyoo@cs.wpi.edu>
Date: Tue, 3 May 2011 15:16:59 -0400
Subject: [PATCH] preliminary README

---
 README | 100 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 100 insertions(+)
 create mode 100644 README

diff --git a/README b/README
new file mode 100644
index 0000000..45e3694
--- /dev/null
+++ b/README
@@ -0,0 +1,100 @@
+Compiler from Racket to JavaScript.
+
+
+
+
+Prerequisite: Racket 5.1.1.  The majority of the project is written
+Typed Racket, and I highly recommend you use a version of Racket
+that's at least 5.1.1; otherwise, compilation times may take an
+unusual amount of time.
+
+
+
+======================================================================
+
+Architecture:
+
+The basic idea is to reuse most of the Racket compiler infrastructure.
+The underlying Racket compiler will produce bytecode from Racket
+source, and perform macro expansion and module-level optimizations for
+us.  We will parse that bytecode using the compiler/zo-parse
+collection to get an AST, compile that to an intermediate language,
+and finally assemble JavaScript.
+
+
+                 AST          IL                     JS
+ bytecode.rkt ----------> compiler.rkt --------> assembler.rkt ------->
+    (todo)
+
+
+The IL is intended to be translated straightforwardly.  We currently
+have an assembler to JavaScript, as well as a simulator
+(simulator.rkt).  The simulator allows us to test the compiler in a
+controlled environment.
+
+
+
+======================================================================
+
+bytecode.rkt
+
+dyoo is currently working on bytecode.rkt.  Not done yet.  This is
+intended to reuse the Racket compiler to produce the AST structures
+defined in compiler/zo-parse.
+
+
+
+For the moment there's a hacky parser in parse.rkt that produces the
+AST expression structures that are consumed by the rest of the system.
+
+
+
+
+======================================================================
+
+compiler.rkt
+
+Translates the AST to the intermediate language.  Much of this
+compiler was styled after the register compiler in Structure and
+Interpretation of Computer Programs, but with some significant
+changes.  Since this is a stack machine, we don't need any of the
+register-saving infrastructure in the original compiler.
+
+
+
+======================================================================
+
+Intermediate language forms and machine model.
+
+The intermediate language is defined in il-structs.rkt, and a
+simulator for the IL in simulator.rkt.  See test-simulator.rkt to see
+the simulator in action, and test-compiler.rkt to see how the output
+of the compiler can be fed into the simulator.
+
+
+
+The assumed machine is a stack machine with the following atomic
+registers:
+
+    val: value
+    proc: procedure
+    argcount: number of arguments
+
+and two stack registers:
+
+    env: environment stack
+    control: control stack
+
+
+
+
+======================================================================
+
+Tests
+
+The test suite in test-all.rkt runs the test suite.  You'll need to
+run this on a system with a web browser, as the suite will evaluate
+JavaScript and make sure it is producing values.  A bridge module
+browser-evaluate.rkt brings up a temporary web server that allows us
+to pass values between Racket and the JavaScript evaluator on the
+browser.
\ No newline at end of file