From a5d7889d2767c54e6b624dd2c736e50c5c65aeb3 Mon Sep 17 00:00:00 2001
From: James Roseborough <james.roseborough@luaj.org>
Date: Thu, 29 Jul 2010 04:49:19 +0000
Subject: [PATCH] Update documentation for lua2java compiler.

---
 README.html        | 90 +++++++++++++++++++++++++++++-----------------
 version.properties |  3 +-
 2 files changed, 58 insertions(+), 35 deletions(-)

diff --git a/README.html b/README.html
index 19bb8fa3..12b224dd 100644
--- a/README.html
+++ b/README.html
@@ -17,7 +17,7 @@
 Getting Started with LuaJ
 
 </h1>
-James Roseborough, Ian Farmer, Version 2.0-beta2
+James Roseborough, Ian Farmer, Version 2.0
 <p>
 <small>
 Copyright &copy; 2009-2010 Luaj.org.
@@ -43,13 +43,10 @@ Freely available under the terms of the
 
 <!-- ====================================================================== -->
 <p>
-<font color=#800000><em>
-This is a beta release for a luaj 2.0.  The most recent stable release is 1.0.3
-</em></font> 
 
 <h1>1 - <a name="1">Introduction</a></h1>
 <h2>Goals of Luaj</h2>
-Luaj is a lua interpreter based on the 5.1.x line of lua with the following goals in mind:
+Luaj is a lua interpreter based on the 5.1.x version of lua with the following goals in mind:
 <ul>
 <li>Java-centric implementation of lua vm built to leverage standard Java features.
 <li>Lightweight to allow for small, fast interpretation of lua bytecode. 
@@ -62,8 +59,10 @@ Luaj is a lua interpreter based on the 5.1.x line of lua with the following goal
 In addition to the basic goals of luaj, version 2.0 is aimed 
 at improving on the 1.0 vm in the following aspects. 
 <ul>
+<li>Support for compiling lua source code into Java source code.
 <li>Support for compiling lua bytecode directly into Java bytecode.
-<li>Improve performance of bytecode processing when lua bytecode is used.
+<li>Improved performance of of lua bytecode processing.
+<li>Stackless vm design centered around dynamically typed objects.
 <li>More alignment with C API (see <a href="names.csv">names.csv</a> for details)
 <li>Improved class and package naming conventions. 
 <li>Improved unit tests of core classes. 
@@ -72,13 +71,13 @@ at improving on the 1.0 vm in the following aspects.
 
 <h1>2 - <a name="2">Simple Examples</a></h1>
 
-<h2>Run a script in Java SE</h2>
+<h2>Run a lua script in Java SE</h2>
 
 <p>
 From the main distribution directory line type:
 
 <pre>
-	java -cp lib/luaj-jse-2.0-beta2.jar lua examples/lua/hello.lua
+	java -cp lib/luaj-jse-2.0.jar lua examples/lua/hello.lua
 </pre>
 
 <p>
@@ -87,34 +86,50 @@ You should see the following output:
 	hello, world
 </pre>
 
-<h2>Compile a script to lua bytecode</h2>
+<h2>Compile lua source to lua bytecode</h2>
 
 <p>
 From the main distribution directory line type:
 
 <pre>
-	java -cp lib/luaj-jse-2.0-beta2.jar luac examples/lua/hello.lua
-	java -cp lib/luaj-jse-2.0-beta2.jar lua luac.out
+	java -cp lib/luaj-jse-2.0.jar luac examples/lua/hello.lua
+	java -cp lib/luaj-jse-2.0.jar lua luac.out
 </pre>
 
 <p>
 The compiled output "luac.out" is lua bytecode and should run and produce the same result.
 
-<h2>Compile a script to java bytecode</h2>
+<h2>Compile lua source to java source</h2>
 
 <p>
-Luaj can compile to lua bytecode if the bcel library is on the class path. From the main distribution directory line type:
+Luaj can compile to lua source code to Java source code:
+
+<pre>
+	java -cp lib/luaj-jse-2.0.jar lua2java -s examples/lua -d . hello.lua
+	javac -cp lib/luaj-jse-2.0.jar hello.java
+	java -cp &quot;lib/luaj-jse-2.0.jar;.&quot; lua -l hello
+</pre>
+
+<p>
+The output <em>hello.java</em> is Java source, that implements the logic in hello.lua directly.
+Once <em>hello.java</em> is compiled into <em>hello.class</em> it can be required and used in place of the original lua script, but with better performance.  
+There are no additional dependencies for compiling or running source-to-source compiled lua. 
+
+<h2>Compile lua bytecode to java bytecode</h2>
+
+<p>
+Luaj can compile lua sources or binaries directly to java bytecode if the bcel library is on the class path. From the main distribution directory line type:
 
 <pre>
 	ant bcel-lib
-	java -cp &quot;lib/luaj-jse-2.0-beta2.jar;lib/bcel-5.2.jar&quot; luajc -s examples/lua -d . hello.lua
-	java -cp &quot;lib/luaj-jse-2.0-beta2.jar;.&quot; lua -l hello
+	java -cp &quot;lib/luaj-jse-2.0.jar;lib/bcel-5.2.jar&quot; luajc -s examples/lua -d . hello.lua
+	java -cp &quot;lib/luaj-jse-2.0.jar;.&quot; lua -l hello
 </pre>
 
 <p>
 The output <em>hello.class</em> is Java bytecode, should run and produce the same result.
 There is no runtime dependency on the bcel library, 
-but the compiled classes must be in the class path at runtime.
+but the compiled classes must be in the class path at runtime, unless runtime jit-compiling via luajc and bcel are desired (see later sections).
 
 <pre>
 </pre>
@@ -140,7 +155,7 @@ A simple example may be found in
 </pre>
 
 <p>
-You must include the library <b>lib/luaj-jse-2.0-beta2.jar</b> in your class path.
+You must include the library <b>lib/luaj-jse-2.0.jar</b> in your class path.
 
 <h2>Run a script in a MIDlet</h2>
 
@@ -167,7 +182,7 @@ A simple example may be found in
 </pre>
 
 <p>
-You must include the library <b>lib/luaj-jme-2.0-beta2.jar</b> in your midlet jar.
+You must include the library <b>lib/luaj-jme-2.0.jar</b> in your midlet jar.
 
 <p>
 An ant script to build and run the midlet is in
@@ -194,7 +209,20 @@ that are needed and omitting the line:
 </pre>
 
 
-<h2>Including the lua-to-Java-bytecode compiler</h2>
+<h2>Including the lua-source-to-Java-source compiler</h2>
+
+<p>
+To compile from lua sources to Java sources for all lua loaded at runtime, 
+install the Lua2Java compiler <em>after</em> globals have been created using:
+
+<pre>
+	org.luaj.vm2.jse.lua2java.Lua2Java.install();
+</pre>
+
+This uses the system Java compiler to compile from Java source to Java bytecode, 
+and cannot compile lua binary files containing lua bytecode at runtime. 
+
+<h2>Including the lua-bytecode-to-Java-bytecode compiler</h2>
 
 <p>
 To compile from lua to Java bytecode for all lua loaded at runtime, 
@@ -228,7 +256,7 @@ The standard use of JSR-233 scripting engines may be used:
 All standard aspects of script engines including compiled statements should be supported.
 
 <p>
-You must include the library <b>lib/luaj-jse-2.0-beta2.jar</b> in your class path.
+You must include the library <b>lib/luaj-jse-2.0.jar</b> in your class path.
 
 <p>
 A working example may be found in
@@ -351,7 +379,7 @@ The following lua script will open a swiing frame on Java SE:
 <p>
 See a longer sample in <em>src/test/res/swingapp.lua</em> for details, or try running it using: 
 <pre>
-	java -cp lib/luaj-jse-2.0-beta2.jar lua src/test/res/swingapp.lua
+	java -cp lib/luaj-jse-2.0.jar lua src/test/res/swingapp.lua
 </pre>
 
 <p>
@@ -417,23 +445,19 @@ and LuaForge:
 
 <h2>Main Changes by Version</h2>
 <table cellspacing="10"><tr><td><table cellspacing="4">
-<tr valign="top"><td>&nbsp;&nbsp;<b>2.0-beta1</b></td><td><ul>
-<li>All basic unit tests pass.  
-<li>Initial port of all libraries has been done.
-<li>Compile-to-Java based on bcel 5.2 working for unit tests.  
+<tr valign="top"><td>&nbsp;&nbsp;<b>2.0</b></td><td><ul>
+<li>Core vm and core libraries completed.  
+<li>lua2java source-to-source compiler produces working files for all unit tests.
+<li>luajc bytecode-to-bytecode compiler produces working files for all unit tests.  
 </ul></td></tr>
 </table>
 
 <h2>Known Issues</h2>
 <ul>
-<li>module() and setfenv() don't work with closures in compiled chunks
-<li>debug code may not be removed by obfuscators
-<li>lua-to-java bytecode generation can produce incorrect results
-<li>weak tables may not release items in all cases
-<li>tail calls may not work as expected in some cases
+<li>debug code may not be completely removed by some obfuscators
 <li>tail calls are not tracked in debug information
-<li>using both version 1 and version 2 libraries together in the same java vm has not been tested.
-<li>design of default file loading behavior may change.
-<li>likely to make changes to support the lua 5.2 API once it is finalized. 
+<li>using both version 1 and 2 libraries together in the same java vm has not been tested.
+<li>module() and setfenv() only partially supported for lau2java or luajc compiled lua
+<li>luajc may infer incorrect upvalue boundaries
 </ul>
 
diff --git a/version.properties b/version.properties
index 360ccc7a..6ec12fe9 100644
--- a/version.properties
+++ b/version.properties
@@ -1,2 +1 @@
-# on the way to version 2.0
-version: 2.0-beta2
+version: 2.0