Getting Started with LuaJ

James Roseborough, Ian Farmer, Version 1.9.53

examples · concepts · libraries · building · downloads · release notes

This is a development release for a planned luaj 2.0. The most recent stable release is 1.0.2

1 - Simple Examples

Run a script in Java SE

From the main distribution directory line type:

	java -cp lib/luaj-jse-1.9.53.jar lua examples/lua/hello.lua

You should see the following output:

	hello, world

Compile a script in Java SE

From the main distribution directory line type:

	java -cp lib/luaj-jse-1.0.jar luac examples/lua/hello.lua
	java -cp lib/luaj-jse-1.0.jar lua luac.out

The compiled output should run and produce the same result.

Run a script in a Java Application

The following pattern is used within Java SE

	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) );

A simple example may be found in

	examples/jse/SampleJseMain.java

You must include the library lib/luaj-jse-1.9.53.jar in your class path.

Run a script in a MIDlet

The following pattern is used within MIDlets:

	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) );

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

A simple example may be found in

	examples/jme/SampleMIDlet.java

You must include the library lib/luaj-jme-1.9.53.jar in your midlet jar. They can be obfuscated if desired.

Including the compiler

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.

To include the Java it, include the following sometime before lua source files are loaded:

	org.luaj.vm2.compiler.LuaC.install();

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

Run a script using JSR-233 Dynamic Scripting

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

	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") );

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

You must include the library lib/luaj-jse-1.9.53.jar in your class path.

A working example may be found in

	examples/jse/ScriptEngineSample.java

Compile lua to Java bytecode using luajc

A code generator that compiles lua to java bytecode base on the bcel library is now included.

To use it at runtime, the tool "lua" has an option "-j" to compile into java bytecode.

	java -cp luaj-jse-1.9.53.jar;lib/bcel-5.2.jar lua -j examples/lua/hello.lua

To compile lua files into Java in advance, the tool "luajc" is provided:

	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

You should see a class file of 906 bytes or so. A version of the bcel library must be in your class path for code generation to work. The ant script contains a target for fetching bcel v 5.2:

	ant bcel-lib

Files compiled into java in this way can be run via Java class loading, without the bcel libraries (generated class files must be in your class path):

	java -cp luaj-jse-1.9.53.jar;. lua -l hello

The current bytecode generator produces a separate class file for each prototype, and generated class files do not work properly with module() or setfenv().

2 - Concepts

Globals

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

JsePlatform

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.

JmePlatform

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.

3 - Libraries

Standard Libraries

Libraries are coded to closely match the behavior specified in See standard lua documentation for details on the library API's

The following libraries are loaded by default in Java ME and Java SE platforms:

	base
	coroutine
	math
	package
	string
	table

The following libraries are optional, but preconfigured for some platforms and tools:

           
	io
	os
	debug     
	luajava

Optional Libraries

I/O Library

The Java SE platform contains the io library by default.

The Java ME platform has an optional, partial implementation of the io in

	src/jme/org/luaj/vm2/lib/jme/JmeIoLib.java

OS Library

A basic os library implementation for either Java ME or Java SE is provided ins

	src/core/org/luaj/lib/OsLib.java

A slightly more complete version for Java SE is in:

	src/jse/org/luaj/vm2/lib/jse/JseOsLib.java

Time is a represented as number of milliseconds since the epoch, and most time and date formatting, locales, and other features are not implemented.

Debug Library

The following library is optional:

	debug

Install from Java using:

	org.luaj.vm2.lib.DebugLib.install(vm);

or install from lua using:

	require 'org.luaj.vm2.lib.DebugLib'

The lua command line utility includes the debug library by default.

The Luajava Library

The Java SE platform includes the luajava library, which simplifies binding to Java classes and methods. It is patterned after the original luajava project.

The following lua script will open a swiing frame on Java SE:

	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)

See a longer sample in src/test/res/swingapp.lua for details, or try running it using:

	java -cp lib/luaj-jse-1.9.53.jar lua src/test/res/swingapp.lua

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.

4 - Building and Testing

Building the jars

An ant file is included in the root directory which builds the libraries by default.

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

Unit tests

A large array of test scripts may be found in

	test/lua/*.lua

A large set of JUnit tests are invoked by the JUnit 3 suite:

	test/junit/org/luaj/vm2/AllTests.lua

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

5 - Downloads

Downloads and Project Pages

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

	SourceForge Luaj Project Page
	SourceForge Luaj Download Area

and LuaForge:

	LuaForge Luaj Project Page
	LuaForge Luaj Project Area

6 - Release Notes

Main changes by version:

1.9.53	Most interpreter features are working. Initial port of all libraries has been done.
1.9.53	All unit tests that have been included in the project pass. Compile-to-Java based on bcel 5.2 is working.