From 7c72a9feafb153652054318679909971ac446d0e Mon Sep 17 00:00:00 2001
From: James Roseborough <james.roseborough@luaj.org>
Date: Sun, 9 May 2010 05:36:03 +0000
Subject: [PATCH] Update documentation.

---
 README.html        | 96 +++++++++++++++++++++++++---------------------
 build-coverage.xml | 15 +++++---
 2 files changed, 62 insertions(+), 49 deletions(-)

diff --git a/README.html b/README.html
index 1f994fa9..dd30e2e3 100644
--- a/README.html
+++ b/README.html
@@ -51,7 +51,7 @@ This is an alpha release for a luaj 2.0.  The most recent stable release is 1.0.
 <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:
 <ul>
-<li>Java-centric implementation to take advantage of native Java features like garbage collection, and a robust class model.
+<li>Java-centric implementation built to use Java features like garbage collection, and class dispatch.
 <li>Lightweight to allow for small, fast interpretation of lua bytecode. 
 <li>Complete set of libraries and tools for integration into real-world projects.
 <li>Multi-platform to be able to run on JME, JSE, or JEE environments. 
@@ -63,17 +63,12 @@ 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 into Java off-line for JME, and at runtime for JSE.
-<li>Faster bytecode processing for interpreted code.
-<li>Tighter integration between lua and Java layers.
-<li>Stackless implementation of interpreted code.
-<li>Streamlined processing model with modular interpreter. 
+<li>Fastest possible bytecode processing for interpreted code.
 <li>More alignment with C API (see <a href="names.csv">names.csv</a> for details)
-<li>More uniform naming of classes. 
-<li>Better package layout. 
-<li>Better unit tests of core classes. 
+<li>Improved class and package naming conventions. 
+<li>Improved unit tests of core classes. 
 </ul>
 
-
 <h1>2 - <a name="2">Simple Examples</a></h1>
 
 <h2>Run a script in Java SE</h2>
@@ -271,43 +266,54 @@ Libraries are coded to closely match the behavior specified in
 See <a href="http://www.lua.org/manual/5.1/">standard lua documentation</a> for details on the library API's
 
 <p>
-The following libraries are loaded by default in Java ME and Java SE platforms:
+The following libraries are loaded in py both <em>JsePlatform.standardGlobals()</em> and <em>JmePlatform.standardGlobals()</em>:
 <pre>
 	base
 	coroutine
+	io
 	math
+	os
 	package
 	string
 	table
 </pre>
 
 <p>
-The following libraries are optional, but preconfigured for some platforms and tools:
+The <em>JsePlatform.standardGlobals()</em> globals also include:
 <pre>           
-	io
-	os
-	debug     
 	luajava 
 </pre>
 
-<h2>Optional  Libraries</h2>
+<p>
+The <em>JsePlatform.debugGlobals()</em> and <em>JsePlatform.debugGlobals()</em> functions produce globals that include:
+<pre>           
+	debug
+</pre>
 
 <h3>I/O Library</h3>
-The Java SE platform contains the <em>io</em> library by default.
+The implementation of the <em>io</em> library differs by platform owing to platform limitations.
 
 <p>
-The Java ME platform has an optional, partial implementation of the <em>io</em> in 
+The <em>JmePlatform.standardGlobals()</em> instantiated the io library <em>io</em> in 
 <pre>
 	src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
 </pre>
 
+The <em>JsePlatform.standardGlobals()</em> includes support for random access and is in 
+<pre>
+	src/jse/org/luaj/vm2/lib/jse/JseIoLib.java
+</pre>
+
 <h3>OS Library</h3>
-A basic os library implementation for either Java ME or Java SE is provided ins 
+The implementation of the <em>os</em> library also differs per platform.
+
+<p>
+The basic <em>os</em> library implementation us used by <em>JmePlatform</em> and is in:
 <pre>
 	src/core/org/luaj/lib/OsLib.java
 </pre>
 
-A slightly more complete version for Java SE is in: 
+A richer version for use by <em>JsePlatform</em> is : 
 <pre>
 	src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
 </pre>
@@ -317,31 +323,22 @@ and most time and date formatting, locales, and other features
 are not implemented.
 
 <h3>Debug Library</h3>
-The following library is optional:
-<pre>
-	debug
-</pre>
+The <em>debug</em> library is not included by default by 
+<em>JmePlatform.standardGlobals()</em> or <em>JsePlatform.standardGlobsls()</em> .
 
-Install from Java using:
-<pre>
-	_G.load( new DebugLib() );
-</pre>
+The functions <em>JmePlatform.debugGlobals()</em> and <em>JsePlatform.debugGlobsls()</em> 
+create globals that contain the debug library in addition to the other standard libraries. 
 
-or change startup code to use:
-<pre>
-	LuaValue _G = JsePlatform.debugGlobals();
-</pre>
-
-To install from lua use</em>:
+To install dynamically from lua use java-class-based require:</em>:
 <pre>
 	require 'org.luaj.vm2.lib.DebugLib'
 </pre>
 
-The <em>lua</em> command line utility includes the debug library by default.
+The <em>lua</em> command line utility includes the <em>debug</em> library by default.
 
 
 <h3>The Luajava Library</h3>
-The Java SE platform includes the <em>luajava</em> library, which simplifies binding to Java classes and methods.  
+The <em>JsePlatform.standardGlobals()</em> includes the <em>luajava</em> library, which simplifies binding to Java classes and methods.  
 It is patterned after the original <a href="http://www.keplerproject.org/luajava/">luajava project</a>.
 
 <p>
@@ -363,6 +360,9 @@ See a longer sample in <em>src/test/res/swingapp.lua</em> for details, or try ru
 <p>
 The Java ME platform does not include this library, and it cannot be made to work because of the lack of a reflection API in Java SE. 
 
+<p>
+The <em>lua</em> connand line tool includes <em>luajava</em>. 
+
 <h1>5 - <a name="5">Building and Testing</a></h1>
 
 <h2>Building the jars</h2>
@@ -374,19 +374,29 @@ Other targets exist for creating distribution file an measuring code coverage of
 <h2>Unit tests</h2>
 
 <p>
-A large array of test scripts may be found in
-<pre>
-	test/lua/*.lua
-</pre>
-
-<p>
-A large set of JUnit tests are invoked by the JUnit 3 suite:
+The main luaj JUnit tests are organized into a JUnit 3 suite:
 <pre>
 	test/junit/org/luaj/vm2/AllTests.lua
 </pre>
 
 <p>
-These tests are used for to produce code coverage statistics using build-coverage.xml.
+Unit test scripts can be found in these locations
+<pre>
+	test/lua/*.lua
+	test/junit/org/luaj/vm2/compiler/lua5.1-tests.zip
+	test/junit/org/luaj/vm2/compiler/regressions.zip
+	test/junit/org/luaj/vm2/vm1/luajvm1-tests.zip
+</pre>
+
+<h2>Code coverage</h2>
+
+<p>
+A build script for running unit tests and producing code coverage statistics is in 
+<pre>
+	build-coverage.xml
+</pre>
+
+It relies on the cobertura code coverage library.
 
 <h1>6 - <a name="6">Downloads</a></h1>
 
diff --git a/build-coverage.xml b/build-coverage.xml
index d2c5438f..e371d1b0 100644
--- a/build-coverage.xml
+++ b/build-coverage.xml
@@ -12,6 +12,9 @@
 
 	<artifact:dependencies filesetId="cobutura.fileset">
 		<dependency groupId="cobertura" artifactId="cobertura" version="1.8"/>
+		<dependency groupId="log4j" artifactId="log4j" version="1.2.9"/>
+		<dependency groupId="asm" artifactId="asm" version="2.2.1"/>
+		<dependency groupId="oro" artifactId="oro" version="2.0.7"/>
 		<dependency groupId="junit" artifactId="junit" version="3.8.1"/>
 	</artifact:dependencies>
 	
@@ -24,10 +27,6 @@
 	<import file="wtk.xml"/>
 	
 	<property environment="env"/>
-	<property name="antlr.version"     value="3.1.3"/>
-	<property name="antlr.home"        value="${env.ANTLR_HOME}"/>
-	<property name="antlr.tool.jar"    value="${antlr.home}/lib/antlr-${antlr.version}.jar"/>
-	<property name="antlr.runtime.jar" value="${antlr.home}/lib/antlr-runtime-${antlr.version}.jar"/>
 
 	<target name="clean" description="Remove all files created by the build/test process.">
 		<delete dir="build" failonerror="no"/>
@@ -36,6 +35,8 @@
 	</target>
 
 	<target name="init">
+		<ant antfile="build.xml" target="bcel-lib"/>
+		<ant antfile="build.xml" target="luaj1-lib"/>
 		<mkdir dir="${classes.dir}" />
 		<mkdir dir="${instrumented.dir}" />
 		<mkdir dir="${reports.xml.dir}" />
@@ -48,7 +49,8 @@
 		<javac destdir="${classes.dir}" debug="yes" target="1.5">
 			<classpath refid="cobertura.classpath" />
 		    <classpath refid="wtk-libs" />
-			<classpath path="${antlr.runtime.jar}"/>
+		    <classpath path="lib/bcel-5.2.jar" />
+		    <classpath path="lib/luaj-j2se-1.0.3.jar" />
 		    <src path="src/core"/>
 		    <src path="src/jme"/>
 		    <src path="src/jse"/>
@@ -68,7 +70,6 @@
 				<include name="org/luaj/vm2/lib/jme/*.class" />
 				<include name="org/luaj/vm2/compiler/*.class" />
 				<include name="org/luaj/vm2/luajc/*.class" />
-				<include name="org/luaj/vm2/luajc/antlr/*.class" />
 				<include name="org/luaj/vm2/luajc/lst/*.class" />
 				<include name="org/luaj/vm2/script/*.class" />
 				<exclude name="**/*Test*.class" />
@@ -82,6 +83,8 @@
 			<classpath location="${classes.dir}" />
 			<classpath location="src/test/res" />
 			<classpath refid="cobertura.classpath" />
+		    <classpath path="lib/bcel-5.2.jar" />
+		    <classpath path="lib/luaj-j2se-1.0.3.jar" />
 			<formatter type="xml" />
 			<batchtest todir="${reports.xml.dir}">
 				<fileset dir="test/junit">