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.
• More alignment with C API (see names.csv for details)
• 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 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 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-2.0-alpha1.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-2.0-alpha1.jar in your midlet jar. They can be obfuscated if desired.

Including the compiler

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-2.0-alpha1.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-2.0-alpha1.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-2.0-alpha1.jar;lib/bcel-5.2.jar luajc hello.lua
	ls -l hello.class

	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-2.0-alpha1.jar;. lua -l hello

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

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

	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