luaj/README.md

# License notice
All third party licenses can be found in the module resources/license folder
Project license is in LICENSE-File

# LuaJ

LuaJ is a Java implementation of Lua with JSE and JME targets.

This fork is maintained by Open Autonomous Connection and is built with Maven only. The current codebase targets Lua 5.5 semantics in the supported runtime paths, including `global`, named vararg tables, read-only `for` variables, `table.create`, updated `utf8.offset`, binary chunk compatibility, and the existing Lua 5.4 `<close>` and `<const>` behavior.

## Modules

- `core`: VM, compiler, standard runtime pieces
- `jse`: Java SE platform, JSR-223 integration, LuaJC support
- `jme`: Java ME platform support

## Requirements

- Java 25
- Maven 3.9+

The repository includes a Maven Wrapper:

- Windows: `mvnw.cmd`
- Unix-like shells: `./mvnw`

## Build

Build all modules:

```powershell
.\mvnw.cmd clean package
```

Run the full test suite:

```powershell
.\mvnw.cmd clean test
```

Build a single module with dependencies:

```powershell
.\mvnw.cmd -pl jse -am package
```

## Quick Start

Minimal JSE embedding example:

```java
import org.luaj.vm2.Globals;
import org.luaj.vm2.LuaValue;
import org.luaj.vm2.libs.jse.JsePlatform;

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

## Maven Usage

Use the published modules directly from Maven:

```xml
<dependency>
  <groupId>org.openautonomousconnection.luaj</groupId>
  <artifactId>jse</artifactId>
  <version>3.0.2</version>
</dependency>
```

For the core VM without the JSE platform layer:

```xml
<dependency>
  <groupId>org.openautonomousconnection.luaj</groupId>
  <artifactId>core</artifactId>
  <version>3.0.2</version>
</dependency>
```

## Notable Runtime Notes

- LuaJ runs on the host JVM garbage collector. Resource cleanup is not equivalent to native Lua finalization.
- Explicit close is still the correct pattern for files, iterators, and host-backed resources.
- `LuaJC` is available on JSE and covered by the current Maven test path. For 5.5-only constructs that the legacy bytecode generator does not model directly, it falls back to generated delegate wrappers over `LuaClosure`.
- JME support remains in the Maven build, with environment-specific limitations depending on available Java ME APIs.
- The repository currently passes `.\mvnw.cmd -q clean test`.

## Examples

Relevant examples are in:

- `examples/jse`
- `examples/jme`
- `examples/lua`
- `examples/maven`

## License

This project is distributed under the terms in `LICENSE`.