388 lines
10 KiB
HTML
388 lines
10 KiB
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 1.9.53
|
|
<p>
|
|
<small>
|
|
Copyright © 2007-2009 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">examples</a>
|
|
·
|
|
<a href="#2">concepts</a>
|
|
·
|
|
<a href="#3">libraries</a>
|
|
·
|
|
<a href="#4">building</a>
|
|
·
|
|
<a href="#5">downloads</a>
|
|
·
|
|
<a href="#6">release notes</a>
|
|
|
|
<!-- ====================================================================== -->
|
|
<p>
|
|
<font color=#800000><em>
|
|
This is a development release for a planned luaj 2.0. The most recent stable release is 1.0.2
|
|
</em></font>
|
|
|
|
|
|
<h1>1 - <a name="1">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-1.9.53.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-1.9.53.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-1.9.53.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-1.9.53.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-1.9.53.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-1.9.53.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-1.9.53.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>2 - <a name="2">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>3 - <a name="3">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-1.9.53.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>4 - <a name="4">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>5 - <a name="5">Downloads</a></h1>
|
|
|
|
<h2>Downloads and Project Pages</h2>
|
|
Downloads for version 1.0.2 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>6 - <a name="6">Release Notes</a></h1>
|
|
|
|
Main changes by version:
|
|
<table cellspacing="10"><tr><td><table cellspacing="4">
|
|
<tr valign="top"><td> <b>1.9.53</b></td><td>
|
|
Most interpreter features are working. Initial port of all libraries has been done.
|
|
</td></tr>
|
|
<tr valign="top"><td> <b>1.9.53</b></td><td>
|
|
All unit tests that have been included in the project pass.
|
|
Compile-to-Java based on bcel 5.2 is working.
|
|
</td></tr>
|
|
</table>
|