Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/mjanicek/rembulan

Rembulan, an implementation of Lua 5.3 for the Java Virtual Machine
https://github.com/mjanicek/rembulan

Last synced: about 2 months ago
JSON representation

Rembulan, an implementation of Lua 5.3 for the Java Virtual Machine

Awesome Lists containing this project

README 

        
[![Build Status](https://travis-ci.org/mjanicek/rembulan.svg?branch=master)](https://travis-ci.org/mjanicek/rembulan)



# Rembulan



(*Rembulan* is Javanese/Indonesian for *Moon*.)



## About



Rembulan is an implementation of Lua 5.3 for the Java Virtual Machine (JVM), written in

pure Java with minimal dependencies.

The goal of the Rembulan project is to develop a correct, complete and scalable Lua

implementation for running sandboxed Lua programs on the JVM.



Rembulan implements Lua 5.3 as specified by the

[Lua Reference Manual](http://www.lua.org/manual/5.3/manual.html), explicitly attempting to mimic

the behaviour of PUC-Lua whenever possible. This includes language-level features (such

as metamethods and coroutines) and the standard library.



## Status



The majority of language-level features is implemented, and may be expected

to work. If you find behaviour that does not conform to Lua 5.3 as defined by the Lua Reference

Manual, please [open a new issue](https://github.com/mjanicek/rembulan/issues).



See also the [completeness table](doc/CompletenessTable.md) that maps out the current

completeness status of Rembulan with regard to PUC-Lua, in particular the standard library.



## Frequently asked questions (FAQ)



#### What is Rembulan good for?



Lua is a small, beautifully-designed and simple-yet-powerful programming language.

Lua has been traditionally used as an embedded scripting language. Rembulan aims to serve

a similar purpose on the JVM, with an explicit focus on sandboxing the client Lua programs.



There are two main use-cases for Rembulan: running untrusted Lua scripts on the JVM,

and enhancing Java applications by adding the ability to script them with Lua.



#### Does Rembulan implement the Lua C API?



No, at this point Rembulan requires libraries to be written against its Java interface.

 

#### Does Rembulan work with Lua bytecode?



No. The Lua bytecode (i.e., the bytecode generated by PUC-Lua's `luac`) is considered

an implementation detail by both Rembulan and the Lua Reference Manual. Rembulan implements

its own compiler and compiles to Java bytecode directly. It uses its own

intermediate representation (IR) annotated with statically-inferred type information,

but does not expose it to the user, and the IR has no serialisable form.

 

For more information about the Rembulan compiler, see the

[compiler overview](doc/CompilerOverview.md). 

 

#### How are coroutines implemented?

 

See [How are coroutines implemented?](doc/CoroutinesOverview.md)  



## Using Rembulan



Rembulan requires a Java Runtime Environment (JRE) version 7 or higher.



### Documentation



Generated JavaDocs are available online:



 * [Runtime module](https://mjanicek.github.io/rembulan/apidocs/rembulan-runtime/index.html)

 * [Compiler](https://mjanicek.github.io/rembulan/apidocs/rembulan-compiler/index.html)

 * [Standard Library](https://mjanicek.github.io/rembulan/apidocs/rembulan-stdlib/index.html)



There are also a few short texts in the `doc` folder:



 * [How are coroutines implemented?](doc/CoroutinesOverview.md)

 * [Overview of the Rembulan compiler](doc/CompilerOverview.md)

 * [Rembulan completeness table](doc/CompletenessTable.md)



### Building from source



To build Rembulan, you will need the following:



 * Java Development Kit (JDK) version 7 or higher

 * Maven version 3 or higher



Maven will pull in the remaining dependencies as part of the build process.



To fetch the latest code on the `master` branch and build it, run



```sh

git clone https://github.com/mjanicek/rembulan.git

cd rembulan    

mvn install

```



This will build all modules, run tests and finally install all artifacts into your local

Maven repository.    



#### Standalone REPL



Much like PUC-Lua, Rembulan contains a standalone REPL. This is provided in the module

`rembulan-standalone`. To build the REPL, run



```sh

mvn package -DskipTests -Dmaven.javadoc.skip=true -DstandaloneFinalName=rembulan

```



The standalone REPL is packaged as a self-contained, executable [Capsule](http://www.capsule.io)

and is placed in the directory `rembulan-standalone/target`.

 

To run the REPL:



```sh

cd rembulan-standalone/target

./rembulan-capsule.x

```



The standalone REPL mimics the behaviour or the standalone PUC-Lua interpreter and may be

used as its drop-in replacement.



```

$ ./rembulan-capsule.x

Rembulan 0.1-SNAPSHOT (Java HotSpot(TM) 64-Bit Server VM, Java 1.8.0_60)

> print("hello world!")

hello world!

```



### Using Rembulan from Maven



There are no releases yet, but snapshot artifacts are published to the Sonatype OSSRH Snapshot

Repository. To use the snapshot artifacts, add the following configuration to your `pom.xml`:



```xml



  

    sonatype-ossrh-snapshots

    Sonatype OSSRH (Snapshots)

    https://oss.sonatype.org/content/repositories/snapshots/

    

  



```



To include the **runtime** as a dependency:



```xml



  net.sandius.rembulan

  rembulan-runtime

  0.1-SNAPSHOT



```



To include the **compiler** as a dependency:



```xml



  net.sandius.rembulan

  rembulan-compiler

  0.1-SNAPSHOT



```



To include the **standard library** as a dependency:



```xml



  net.sandius.rembulan

  rembulan-stdlib

  0.1-SNAPSHOT



```



Note that `rembulan-compiler` and `rembulan-stdlib` both pull in `rembulan-runtime` as

a dependency, but are otherwise independent. (I.e., to use the compiler and the standard

library, you need to declare both `-compiler` and `-stdlib` as dependencies, but do not need

to include `-runtime`).



## Getting started



Rembulan compiles Lua functions into Java classes and loads them into the JVM;

the compiler performs a type analysis of the Lua programs in order to generate a more

tightly-typed code whenever feasible.



Since the JVM does not directly support coroutines, Rembulan treats Lua functions as state

machines and controls their execution (i.e., yields, resumes and pauses) using exceptions.

Since the Rembulan runtime retains control of the control state, this technique is also used

to implement CPU accounting and scheduling of asynchronous operations.



#### Example: Hello world  



The following snippet loads the Lua program `print('hello world!')`, compiles it, loads

it into a (non-sandboxed) state, and runs it:



(From [`rembulan-examples/.../HelloWorld.java`](rembulan-examples/src/main/java/net/sandius/rembulan/examples/HelloWorld.java))



```java

String program = "print('hello world!')";



// initialise state

StateContext state = StateContexts.newDefaultInstance();

Table env = StandardLibrary.in(RuntimeEnvironments.system()).installInto(state);



// compile

ChunkLoader loader = CompilerChunkLoader.of("hello_world");

LuaFunction main = loader.loadTextChunk(new Variable(env), "hello", program);



// execute

DirectCallExecutor.newExecutor().call(state, main);

```



The output (printed to `System.out`) is:



```

hello world!

```



#### Example: CPU accounting



Lua functions can be called in a mode that automatically pauses their execution once the

given number of operations has been performed:



(From [`rembulan-examples/.../InfiniteLoop.java`](rembulan-examples/src/main/java/net/sandius/rembulan/examples/InfiniteLoop.java))



```java

String program = "n = 0; while true do n = n + 1 end";



// initialise state

StateContext state = StateContexts.newDefaultInstance();

Table env = StandardLibrary.in(RuntimeEnvironments.system()).installInto(state);



// compile

ChunkLoader loader = CompilerChunkLoader.of("infinite_loop");

LuaFunction main = loader.loadTextChunk(new Variable(env), "loop", program);



// execute at most one million ops

DirectCallExecutor executor = DirectCallExecutor.newExecutorWithTickLimit(1000000);



try {

    executor.call(state, main);

    throw new AssertionError();  // never reaches this point!

}

catch (CallPausedException ex) {

    System.out.println("n = " + env.rawget("n"));

}

```



Prints:



```

n = 199999

```



The [`CallPausedException`](https://mjanicek.github.io/rembulan/apidocs/rembulan-runtime/net/sandius/rembulan/exec/CallPausedException.html) contains a *continuation* of the call. The call can be resumed:

the pause is transparent to the Lua code, and the loop does not end with an error (it is merely

paused).



#### Further examples



For further examples, see the classes in

[`rembulan-examples/src/main/java/net/sandius/rembulan/examples`](rembulan-examples/src/main/java/net/sandius/rembulan/examples).



### Project structure



Rembulan is a multi-module Maven build, consisting of the following modules that are deployed

to Sonatype OSSRH:



 * `rembulan-runtime` ... the core classes and runtime;

 * `rembulan-compiler` ... a compiler of Lua sources to Java bytecode;

 * `rembulan-stdlib` ... the Lua standard library;

 * `rembulan-standalone` ... standalone REPL, a (mostly) drop-in replacement

                             for the `lua` command from PUC-Lua.



There are also auxiliary modules that are not deployed:



 * `rembulan-tests` ... project test suite, including benchmarks from

                        the Benchmarks Game;

 * `rembulan-examples` ... examples of the Rembulan API.                       



## Contributing



Contributions of all kinds are welcome!



## License



Rembulan is licensed under the Apache License Version 2.0. See the file

[LICENSE.txt](LICENSE.txt) for details.