<!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 © 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 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>More alignment with C API (see <a href="names.csv">names.csv</a> for details)
<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 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 in Java SE</h2>
<p>
From the main distribution directory line type:
<pre>
java -cp lib/luaj-jse-1.0.jar luac examples/lua/hello.lua
java -cp lib/luaj-jse-1.0.jar lua luac.out
</pre>
<p>
The compiled output should run and produce the same result.
<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 following pattern is used within MIDlets:
<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.
They can be obfuscated if desired.
<h2>Including the 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 Java it, 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>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>
<h2>Compile lua to Java bytecode using luajc</h2>
<p>
A code generator that compiles lua to java bytecode base on the
bcel library is now included.
<p>
To use it at runtime, the tool "lua" has an option "-j" to compile into java bytecode.
<pre>
java -cp luaj-jse-2.0-alpha1.jar;lib/bcel-5.2.jar lua -j examples/lua/hello.lua
</pre>
<p>
To compile lua files into Java in advance, the tool "luajc" is provided:
<pre>
cp examples/lua/hello.lua .
java -cp luaj-jse-2.0-alpha1.jar;lib/bcel-5.2.jar luajc hello.lua
ls -l hello.class
</pre>
You should see a class file of 906 bytes or so. A version of the <a href="http://jakarta.apache.org/bcel/">bcel</a>
library must be in your class path for code generation to work.
The ant script contains a target for fetching bcel v 5.2:
<pre>
ant bcel-lib
</pre>
<p>
Files compiled into java in this way can be run via Java class loading, <em>without</em> the bcel libraries
(generated class files must be in your class path):
<pre>
java -cp luaj-jse-2.0-alpha1.jar;. lua -l hello
</pre>
The current bytecode generator produces a separate class file for each prototype,
and generated class files do not work properly with module() or setfenv().
<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>
org.luaj.vm2.lib.DebugLib.install(vm);
</pre>
or install from lua using</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> <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>