low-luajit

A lightweight library that aims to add low level but safe (as much as possible) bindings to the LuaJIT C API with no dependencies and no-std support.

These bindings can be used to create dynamic Rust libraries (.dll/.so) that can be loaded and ran from LuaJIT like any other Lua module.

use low_luajit::{LuaState, AmountReturned};

extern "C-unwind" fn multiply(mut lua: LuaState) -> AmountReturned {
	let x = lua.check_number(1);
	let y = lua.check_number(2);

	lua.return_number(x * y);
}

#[unsafe(no_mangle)]
extern "C-unwind" fn luaopen_mymodule(mut lua: LuaState) -> AmountReturned {
	lua.return_cfunction(multiply)
}

local multiply = require("mymodule")

print(multiply(52, 196))

For more information, check out the documentation and the examples directory.

Compatibility & Maintenance

This library is used internally for BlossomDevs games, so it should stay maintained for at least a very long time. Version 1.0 will be reached once things feel stable, comfortable and tested enough.

LuaJIT wise, the objective is currently to support v2.0 and v2.1's LuaJIT C API, as it should not receive any breaking changes. If LuaJIT v3.0 is released...support will be added based on the severity of the breaking changes (most likely via a cargo feature).

Anything LuaJIT officially supports (i.e. which devices and CPU architectures are supported) should be compatible. While anything not officially supported will be disregarded and may or may not be compatible.

Why only official LuaJIT?

Simply because it's the Lua I personally use and know best, I wouldn't feel qualified to add proper support for anything else.

Feel free to fork low-luajit and create your own library to support other versions/variants of Lua if needed! (Just remember to follow the licensing conditions...)

Safety policy

Ideally, every safe function in this library should not directly cause any undefined behavior (excluding external factors coming from Lua itself, like an unsafe metamethod being triggered or a function using the ffi library).

Additionally, it should be reasonably safe for the users of your module to use it and its output. (LuaJIT itself is not fully safe so at worst your module is as unsafe as any Lua module can be...)

Since the LuaJIT C API is rather unsafe, there could sadly always be some unsafe bug hidden somewhere. Report any such bug and I'll try to fix it right away!

If needed, it's possible to access the raw unsafe LuaJIT C API directly via the ffi module.

Licensing

This library is licensed under the Boost Software License.

Contributing

Currently, feel free to email me a patch to contribute! (Unless you're one of the lucky few with an account on this forgejo instance...)

If enough people seem interested in this library, I will host a mirror on codeberg.