Getting Started with LuaJ

Copyright © 2009-2010 Luaj.org. Freely available under the terms of the Luaj license.

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

This is an alpha release for a luaj 2.0. The most recent stable release is 1.0.3

1 - Introduction

Goals of Luaj

• Java-centric implementation to take advantage of native Java features like garbage collection, and a robust class model.
• Lightweight to allow for small, fast interpretation of lua bytecode.
• Complete set of libraries and tools for integration into real-world projects.
• Multi-platform to be able to run on JME, JSE, or JEE environments.
• Dependable due to sufficient unit testing of vm and library features.

Differences with 1.0

• Support for compiling lua into Java off-line for JME, and at runtime for JSE.
• Faster bytecode processing for interpreted code.
• Tighter integration between lua and Java layers.
• Stackless implementation of interpreted code.
• Streamlined processing model with modular interpreter.
• More alignment with C API (see names.csv for details)
• More uniform naming of classes.
• Better package layout.
• Better unit tests of core classes.

2 - Simple Examples

Run a script in Java SE

From the main distribution directory line type:

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

You should see the following output:

	hello, world

Compile a script to lua bytecode

From the main distribution directory line type:

	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

The compiled output "luac.out" is lua bytecode and should run and produce the same result.

Compile a script to java bytecode

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

	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

The output hello.class 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.

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-2.0-alpha1.jar in your class path.

Run a script in a MIDlet

The for MIDlets the JmePlatform is used instead:

	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-2.0-alpha1.jar in your midlet jar.

An ant script to build and run the midlet is in

	build-midlet.xml

You must install the wireless toolkit and define WTK_HOME for this script to work.

Including the lua bytecode compiler

To include the lua-to-lua-bytecode compiler, 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.

Including the lua-to-Java-bytecode compiler

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

	org.luaj.vm2.jse.luajc.LuaJC.install();

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

The bcel library must be on the class path for this to work.

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-2.0-alpha1.jar in your class path.

A working example may be found in

	examples/jse/ScriptEngineSample.java

3 - Concepts

Globals

JsePlatform

JmePlatform

4 - Libraries

Standard Libraries

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 ME platform has an optional, partial implementation of the io in

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

OS Library

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

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

Debug Library

	debug

	_G.load( new DebugLib() );

	LuaValue _G = JsePlatform.debugGlobals();

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

The Luajava Library

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

5 - Building and Testing

Building the jars

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.

6 - Downloads

Downloads and Project Pages

	SourceForge Luaj Project Page
	SourceForge Luaj Download Area

and LuaForge:

	LuaForge Luaj Project Page
	LuaForge Luaj Project Area

7 - Release Notes

Main Changes by Version