<!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-beta2
<p>
<small>
Copyright © 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>
·
<a href="#2">examples</a>
·
<a href="#3">concepts</a>
·
<a href="#4">libraries</a>
·
<a href="#5">building</a>
·
<a href="#6">downloads</a>
·
<a href="#7">release notes</a>
<!-- ====================================================================== -->
<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:
<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.
<li>Multi-platform to be able to run on JME, JSE, or JEE environments.
<li>Complete set of libraries and tools for integration into real-world projects.
<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 bytecode directly into Java bytecode.
<li>Improve performance of bytecode processing when lua bytecode is used.
<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.
<li>Improved quality due to major redesign and rewrite of core elements.
</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-beta2.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-beta2.jar luac examples/lua/hello.lua
java -cp lib/luaj-jse-2.0-beta2.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-beta2.jar;lib/bcel-5.2.jar" luajc -s examples/lua -d . hello.lua
java -cp "lib/luaj-jse-2.0-beta2.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 at runtime.
<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.*;
String script = "examples/lua/hello.lua";
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-beta2.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.*;
String script = "examples/lua/hello.lua";
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-beta2.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>Excluding the lua bytecode compiler</h2>
By default, the compiler is included whenever <em>standardGlobals()</em> or <em>debugGlobals()</em> are called.
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 exclude the lua-to-lua-bytecode compiler, do not call
<em>standardGlobals()</em> or <em>debugGlobals()</em>
but instead initialize globals with including only those libraries
that are needed and omitting the line:
<pre>
org.luaj.vm2.compiler.LuaC.install();
</pre>
<h2>Including the lua-to-Java-bytecode compiler</h2>
<p>
To compile from lua to Java bytecode for all lua loaded at runtime,
install the LuaJC compiler <em>after</em> globals have been created using:
<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-beta2.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 both <em>JsePlatform.standardGlobals()</em> and <em>JmePlatform.standardGlobals()</em>:
<pre> base
coroutine
io
math
os
package
string
table
</pre>
<p>
The <em>JsePlatform.standardGlobals()</em> globals also include:
<pre> luajava
</pre>
<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 implementation of the <em>io</em> library differs by platform owing to platform limitations.
<p>
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>
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 richer version for use by <em>JsePlatform</em> is :
<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 <em>debug</em> library is not included by default by
<em>JmePlatform.standardGlobals()</em> or <em>JsePlatform.standardGlobsls()</em> .
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.
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 <em>debug</em> library by default.
<h3>The Luajava Library</h3>
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>
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-beta2.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.
<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>
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>
The main luaj JUnit tests are organized into a JUnit 3 suite:
<pre>
test/junit/org/luaj/vm2/AllTests.lua
</pre>
<p>
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>
<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> <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.
</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>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.
</ul>