#LuaJ

---

#Getting Started with LuaJ.

James Roseborough, Ian Farmer, Version 3.0

<small>Copyright © 2009-2014 Luaj.org. (Also Nathan, Marcus, and Pratik for the crazy hack job with the chainsaw that makes it make it through proguard on Android without warnings.) Freely available under the terms of the Luaj license.</small>

---

introduction · examples · concepts · libraries · luaj api · parser · building · downloads · release notes

1 - <a name="1">Introduction</a>

Goals of Luaj

Luaj is a lua interpreter based on the 5.2.x version of lua with the following goals in mind:

• Java-centric implementation of lua vm built to leverage standard Java features.
• Lightweight, high performance execution of lua.
• Multi-platform to be able to run on JME, JSE, or JEE environments.
• Complete set of libraries and tools for integration into real-world projects.
• Dependable due to sufficient unit testing of vm and library features.

Luaj version and Lua Versions

Luaj 3.0.x

Support for lua 5.2.x features:

• _ENV environments model.
• yield from pcall or metatags.
• Bitwise operator library.

It also includes miscellaneous improvements over luaj 2.0.x:

• Better thread safety.
• More compatible table behavior.
• Better coroutine-related garbage collection.
• Maven integration.
• Better debug reporting when using closures.
• Line numbers in parse syntax tree.

Luaj 2.0.x

Support for lua 5.1.x features, plus:

• Support for compiling lua source code into Java source code.
• Support for compiling lua bytecode directly into Java bytecode.
• Stackless vm design centered around dynamically typed objects.
• Good alignment with C API (see names.csv for details)
• Implementation of weak keys and values, and all metatags.

Luaj 1.0.x

Support for most lua 5.1.x features.

Performance

Good performance is a major goal of luaj. The following table provides measured execution times on a subset of benchmarks from the computer language benchmarks game in comparison with the standard C distribution.

| Project | Version | Mode | Benchmark execution time (sec) | | | | Language | Sample Command | |----------|---------|------------------|--------------------------------|---------------|-------------|----------|----------|-----------------------------------------------------------------| | | | | binarytrees (15) | fannkuch (10) | nbody (1e6) | nsieve 9 | | | | luaj | 3.0 | -b (luajc) | 2.980 | 5.073 | 16.794 | 11.274 | Java | java -cp luaj-jse-3.0.1.jar;bcel-5.2.jar lua -b fannkuch.lua 10 | | | | -n (interpreted) | 12.838 | 23.290 | 36.894 | 15.163 | | java -cp luaj-jse-3.0.1.jar lua -n fannkuch.lua 10 | | lua | 5.1.4 | | 17.637 | 16.044 | 15.201 | 5.477 | C | lua fannkuch.lua 10 | | jill | 1.0.1 | | 44.512 | 54.630 | 72.172 | 20.779 | Java | | | kahlua | 1.0 | jse | 22.963 | 63.277 | 68.223 | 21.529 | Java | | | mochalua | 1.0 | | 50.457 | 70.368 | 82.868 | 41.262 | Java | |

Luaj in interpreted mode performs well for the benchmarks, and even better when the lua-to-java-bytecode (luajc) compiler is used, and actually executes faster than C-based lua in some cases. It is also faster than Java-lua implementations Jill, Kahlua, and Mochalua for all benchmarks tested.

2 - <a name="2">Examples</a>

Run a lua script in Java SE

From the main distribution directory line type:

<pre> java -cp lib/luaj-jse-3.0.jar lua examples/lua/hello.lua </pre>

You should see the following output:

<pre> hello, world </pre>

To see how luaj can be used to acccess most Java API's including swing, try:

<pre> java -cp lib/luaj-jse-3.0.jar lua examples/lua/swingapp.lua </pre>

Links to sources: examples/lua/hello.lua examples/lua/swingapp.lua

Compile lua source to lua bytecode

From the main distribution directory line type:

<pre> java -cp lib/luaj-jse-3.0.jar luac examples/lua/hello.lua java -cp lib/luaj-jse-3.0.jar lua luac.out </pre>

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

Compile lua source or bytecode to java bytecode

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

<pre> ant bcel-lib java -cp "lib/luaj-jse-3.0.jar;lib/bcel-5.2.jar" luajc -s examples/lua -d . hello.lua java -cp "lib/luaj-jse-3.0.jar;." lua -l hello </pre>

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 at runtime, unless runtime jit-compiling via luajc and bcel are desired (see later sections).

Lua scripts can also be run directly in this mode without precompiling using the lua command with the -b option and providing the bcel library in the class path:

<pre> java -cp "lib/luaj-jse-3.0.jar;lib/bcel-5.2.jar" lua -b examples/lua/hello.lua </pre>

Run a script in a Java Application

A simple hello, world example in luaj is:

	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.jse.*;

	Globals globals = JsePlatform.standardGlobals();
	LuaValue chunk = globals.load("print 'hello, world'");
	chunk.call();

Loading from a file is done via Globals.loadFile():

	LuaValue chunk = globals.loadfile("examples/lua/hello.lua");

Chunks can also be loaded from a Reader as text source

	chunk = globals.load(new StringReader("print 'hello, world'"), "main.lua");

or an InputStream to be loaded as text source "t", or binary lua file "b":

<pre> chunk = globals.load(new FileInputSStream("examples/lua/hello.lua"), "main.lua", "bt")); </pre>

A simple example may be found in examples/jse/SampleJseMain.java

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

Run a script in a MIDlet

For MIDlets the JmePlatform is used instead:

	import org.luaj.vm2.*;
	import org.luaj.vm2.lib.jme.*;

	Globals globals = JmePlatform.standardGlobals();
	LuaValue chunk = globals.loadfile("examples/lua/hello.lua");
	chunk.call();

The file must be a resource within within the midlet jar for the loader 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-3.0.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.

Run a script using JSR-223 Dynamic Scripting

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

	ScriptEngineManager mgr = new ScriptEngineManager();
	ScriptEngine e = mgr.getEngineByName("luaj");
	e.put("x", 25);
	e.eval("y = math.sqrt(x)");
	System.out.println( "y="+e.get("y") );

You can also look up the engine by language "lua" or mimetypes "text/lua" or "application/lua".

All standard aspects of script engines including compiled statements are supported.

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

A working example may be found in examples/jse/ScriptEngineSample.java

To compile and run it using Java 1.6 or higher:

<pre> javac -cp lib/luaj-jse-3.0.jar examples/jse/ScriptEngineSample.java java -cp "lib/luaj-jse-3.0.jar;examples/jse" ScriptEngineSample </pre>

Excluding the lua bytecode compiler

By default, the compiler is included whenever standardGlobals() or debugGlobals() are called. 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 exclude the lua-to-lua-bytecode compiler, do not call standardGlobals() or debugGlobals() but instead initialize globals with including only those libraries that are needed and omitting the line:

<pre> org.luaj.vm2.compiler.LuaC.install(globals); </pre>

Including the LuaJC lua-bytecode-to-Java-bytecode compiler

To compile from lua to Java bytecode for all lua loaded at runtime, install the LuaJC compiler into a globals object use:

<pre> org.luaj.vm2.jse.luajc.LuaJC.install(globals); </pre>

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

The requires bcel to be on the class path, and the ClassLoader of JSE or CDC.

3 - <a name="3">Concepts</a>

Globals

The old notion of platform has been replaced with creation of globals. The Globals class holds global state needed for executing closures as well as providing convenience functions for compil