README.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>

<head>
<title>Getting Started with LuaJ</title>
<link rel="stylesheet" type="text/css" href="http://sourceforge.net/dbimage.php?id=196140">
<link rel="stylesheet" type="text/css" href="http://sourceforge.net/dbimage.php?id=196141">
<META HTTP-EQUIV="content-type" CONTENT="text/html; charset=iso-8859-1">
</head>

<body>

<hr>
<h1>
<a href="README.html"><img src="http://sourceforge.net/dbimage.php?id=196139" alt="" border="0"></a>

Getting Started with LuaJ

</h1>
James Roseborough, Ian Farmer, Version 2.0-alpha1
<p>
<small>
Copyright &copy; 2009-2010 Luaj.org.
Freely available under the terms of the
<a href="http://sourceforge.net/dbimage.php?id=196142">Luaj license</a>.
</small>
<hr>
<p>

<a href="#1">introduction</a>
&middot;
<a href="#2">examples</a>
&middot;
<a href="#3">concepts</a>
&middot;
<a href="#4">libraries</a>
&middot;
<a href="#5">building</a>
&middot;
<a href="#6">downloads</a>
&middot;
<a href="#7">release notes</a>

<!-- ====================================================================== -->
<p>
<font color=#800000><em>
This is an alpha 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:
<ul>
<li>Java-centric implementation to take advantage of native Java features like garbage collection, and a robust class model.
<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. 
<li>Dependable due to sufficient unit testing of vm and library features. 
</ul>

<h2>Differences with 1.0</h2>
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>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. 
</ul>


<h1>2 - <a name="2">Simple Examples</a></h1>

<h2>Run a script in Java SE</h2>

<p>
From the main distribution directory line type:

<pre>
	java -cp lib/luaj-jse-2.0-alpha1.jar lua examples/lua/hello.lua
</pre>

<p>
You should see the following output:
<pre>
	hello, world
</pre>

<h2>Compile a script to lua bytecode</h2>

<p>
From the main distribution directory line type:

<pre>
	java -cp lib/luaj-jse-2.0-alpha1.jar luac examples/lua/hello.lua
	java -cp lib/luaj-jse-2.0-alpha1.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>

<p>
Luaj can compile to lua bytecode if the bcel library is on the class path. From the main distribution directory line type:

<pre>
	ant bcel-lib
	java -cp lib/luaj-jse-2.0-alpha1.jar;lib/bcel-5.2.jar luajc -s examples/lua -d . hello.lua
	java -cp lib/luaj-jse-2.0-alpha1.jar;. 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.

<pre>
</pre>

<h2>Run a script in a Java Application</h2>

<p>
The following pattern is used within Java SE

<pre>
	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.*;
	import org.luaj.vm2.compiler.LuaC;

	String script = "examples/lua/hello.lua";
	LuaC.install();
	LuaValue _G = JsePlatform.standardGlobals();
	_G.get("dofile").call( LuaValue.valueOf(script) );
</pre>

<p>
A simple example may be found in
<pre>
	examples/jse/SampleJseMain.java
</pre>

<p>
You must include the library <b>lib/luaj-jse-2.0-alpha1.jar</b> in your class path.

<h2>Run a script in a MIDlet</h2>

<p>
The for MIDlets the <em>JmePlatform</em> is used instead:

<pre>
	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.*;
	import org.luaj.vm2.compiler.LuaC;

	String script = "examples/lua/hello.lua";
	LuaC.install();
	LuaValue _G = JmePlatform.standardGlobals();
	_G.get("dofile").call( LuaValue.valueOf(script) );
</pre>

<p>
The file must be a resource within within the midlet jar for <em>dofile()</em> to find it.
Any files included via <em>require()</em> must also be part of the midlet resources.

<p>
A simple example may be found in
<pre>
	examples/jme/SampleMIDlet.java
</pre>

<p>
You must include the library <b>lib/luaj-jme-2.0-alpha1.jar</b> in your midlet jar.

<p>
An ant script to build and run the midlet is in
<pre>
	build-midlet.xml
</pre>

<p>
You must install the wireless toolkit and define <em>WTK_HOME</em> for this script to work. 

<h2>Including the lua bytecode compiler</h2>

By default, the compiler is not included so as to minimize footprint.  
Without a compiler, files can still be executed, but they must be compiled elsewhere beforehand.
The "luac" utility is provided in the jse jar for this purpose, or a standard lua compiler can be used.  

<p>
To include the lua-to-lua-bytecode compiler, include the following sometime before lua source files are loaded:
<pre>
	org.luaj.vm2.compiler.LuaC.install();
</pre>

<p>
To omit the compiler, omit this line from your startup code. 

<h2>Including the lua-to-Java-bytecode compiler</h2>

<p>
To compile from lua to Java bytecode for all lua loaded at runtime, use the LuaJC class:

<pre>
	org.luaj.vm2.jse.luajc.LuaJC.install();
</pre>

<p>
This will compile all lua bytecode into Java bytecode, regardless of if they are loaded as
lua source or lua binary files.

<p>
The <em>bcel</em> library must be on the class path for this to work.

<h2>Run a script using JSR-233 Dynamic Scripting</h2>

<p>
The standard use of JSR-233 scripting engines may be used:

<pre>
	ScriptEngineManager mgr = new ScriptEngineManager();
	ScriptEngine e = mgr.getEngineByExtension(".lua");
	e.put("x", 25);
	e.eval("y = math.sqrt(x)");
	System.out.println( "y="+e.get("y") );
</pre>

<p>
All standard aspects of script engines including compiled statements should be supported.

<p>
You must include the library <b>lib/luaj-jse-2.0-alpha1.jar</b> in your class path.

<p>
A working example may be found in
<pre>
	examples/jse/ScriptEngineSample.java
</pre>

<h1>3 - <a name="3">Concepts</a></h1>

<h2>Globals</h2>
The old notion of platform has been replaced with creation of globals. 
Two classes are provided to encapsulate common combinations of libraries.  

<h3>JsePlatform</h3>

This class can be used as a factory for globals in a typical Java SE application. 
All standard libraries are included, as well as the luajava library. 
The default search path is the current directory,
and the math operations include all those supported by Java SE.

<h3>JmePlatform</h3>

This class can be used to set up the basic environment for a Java ME application.
The default search path is limited to the jar resources,
and the math operations are limited to those supported by Java ME.
All libraries are included except luajava, and the os, io, and math libraries are 
limited to those functions that can be supported on that platform.


<h1>4 - <a name="4">Libraries</a></h1>

<h2>Standard Libraries</h2>

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:
<pre>
	base
	coroutine
	math
	package
	string
	table
</pre>

<p>
The following libraries are optional, but preconfigured for some platforms and tools:
<pre>           
	io
	os
	debug     
	luajava 
</pre>

<h2>Optional  Libraries</h2>

<h3>I/O Library</h3>
The Java SE platform contains the <em>io</em> library by default.

<p>
The Java ME platform has an optional, partial implementation of the <em>io</em> in 
<pre>
	src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java
</pre>

<h3>OS Library</h3>
A basic os library implementation for either Java ME or Java SE is provided ins 
<pre>
	src/core/org/luaj/lib/OsLib.java
</pre>

A slightly more complete version for Java SE is in: 
<pre>
	src/jse/org/luaj/vm2/lib/jse/JseOsLib.java
</pre>

Time is a represented as number of milliseconds since the epoch, 
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>

Install from Java using:
<pre>
	_G.load( new DebugLib() );
</pre>

or change startup code to use:
<pre>
	LuaValue _G = JsePlatform.debugGlobals();
</pre>

To install from lua use</em>:
<pre>
	require 'org.luaj.vm2.lib.DebugLib'
</pre>

The <em>lua</em> command line utility includes the debug 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.  
It is patterned after the original <a href="http://www.keplerproject.org/luajava/">luajava project</a>.

<p>
The following lua script will open a swiing frame on Java SE:
<pre>
	jframe = luajava.bindClass( "javax.swing.JFrame" )
	frame = luajava.newInstance( "javax.swing.JFrame", "Texts" );
	frame:setDefaultCloseOperation(jframe.EXIT_ON_CLOSE)
	frame:setSize(300,400)
	frame:setVisible(true)
</pre>

<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-alpha1.jar lua src/test/res/swingapp.lua
</pre>

<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. 

<h1>5 - <a name="5">Building and Testing</a></h1>

<h2>Building the jars</h2>
An ant file is included in the root directory which builds the libraries by default.

<p>
Other targets exist for creating distribution file an measuring code coverage of unit tests.

<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:
<pre>
	test/junit/org/luaj/vm2/AllTests.lua
</pre>

<p>
These tests are used for to produce code coverage statistics using build-coverage.xml.

<h1>6 - <a name="6">Downloads</a></h1>

<h2>Downloads and Project Pages</h2>
Downloads for version 1.0.3 are currently hosted on SourceForge.  
Downloads of built packages for 2.0 are not yet available.
Sources are available via sourceforge.net    
<br/>
<pre>
	<a href="http://luaj.sourceforge.net/">SourceForge Luaj Project Page</a>
	<a href="http://sourceforge.net/project/platformdownload.php?group_id=197627">SourceForge Luaj Download Area</a>
</pre>
<p/>
and LuaForge:
<pre>
	<a href="http://luaforge.net/projects/luaj/">LuaForge Luaj Project Page</a>
	<a href="http://luaforge.net/frs/?group_id=457">LuaForge Luaj Project Area</a>
</pre>

<h1>7 - <a name="7">Release Notes</a></h1>

<h2>Main Changes by Version</h2>
<table cellspacing="10"><tr><td><table cellspacing="4">
<tr valign="top"><td>&nbsp;&nbsp;<b>2.0-alpha1</b></td><td><ul>
<li>All basic bunit tests pass.  
<li>Initial port of all libraries has been done.
<li>Compile-to-Java based on bcel 5.2.  
</ul></td></tr>
</table>

<h2>Known Issues</h2>
<ul>
<li>module() and setfenv() don't work with compiled code  
<li>debug code may not be removed by obfuscators
<li>not all luajava bugfixes have been ported over
</ul>