luaj/README.md

# 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.4 semantics in the supported runtime paths, including the recent work around `<close>`, `<const>`, updated weak-table behavior, binary chunk compatibility, and library alignment.

## 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.
- JME support remains in the Maven build, with environment-specific limitations depending on available Java ME APIs.

## Examples

Relevant examples are in:

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

## Status

Current implementation notes for the Lua 5.4 work are tracked in `LUA54_STATUS.md`.

## License

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