7 releases
0.9.0-beta.4 | Aug 22, 2024 |
---|---|
0.9.0-beta.2 | May 20, 2023 |
0.8.0 | Jun 9, 2022 |
0.8.0-beta.5-3 | May 28, 2022 |
0.8.0-beta.5-2 | May 25, 2022 |
#106 in Asynchronous
28 downloads per month
755KB
16K
SLoC
mlua
Guided Tour | Benchmarks | FAQ
Note
Please see the v0.8 branch for the stable versions of
mlua
released to crates.io.
mlua
is bindings to Lua programming language for Rust with a goal to provide
safe (as far as it's possible), high level, easy to use, practical and flexible API.
Started as rlua
fork, mlua
supports Lua 5.4, 5.3, 5.2, 5.1 (including LuaJIT) and Roblox Luau and allows to write native Lua modules in Rust as well as use Lua in a standalone mode.
This is a fork with added Factorio Lua support.
mlua
tested on Windows/macOS/Linux including module mode in GitHub Actions on x86_64
platform and cross-compilation to aarch64
(other targets are also supported).
Usage
Feature flags
mlua
uses feature flags to reduce the amount of dependencies, compiled code and allow to choose only required set of features.
Below is a list of the available feature flags. By default mlua
does not enable any features.
lua54
: activate Lua 5.4 supportlua53
: activate Lua 5.3 supportlua52
: activate Lua 5.2 supportlua51
: activate Lua 5.1 supportluajit
: activate LuaJIT supportluajit52
: activate LuaJIT support with partial compatibility with Lua 5.2luau
: activate Luau support (auto vendored mode)lua-factorio
: activate Factorio Lua support (auto vendored mode)vendored
: build static Lua(JIT) library from sources duringmlua
compilation using lua-src or luajit-src cratesmodule
: enable module mode (building loadablecdylib
library for Lua)async
: enable async/await support (any executor can be used, eg. tokio or async-std)send
: makemlua::Lua
transferable across thread boundaries (addsSend
requirement tomlua::Function
andmlua::UserData
)serialize
: add serialization and deserialization support tomlua
types using serde frameworkmacros
: enable procedural macros (such aschunk!
)parking_lot
: support UserData types wrapped in parking_lot's primitives (Arc<Mutex>
andArc<RwLock>
)unstable
: enable unstable features. The public API of these features may break between releases.
Async/await support
mlua
supports async/await for all Lua versions including Luau.
This works using Lua coroutines and require running Thread along with enabling feature = "async"
in Cargo.toml
.
Examples:
Serialization (serde) support
With serialize
feature flag enabled, mlua
allows you to serialize/deserialize any type that implements serde::Serialize
and serde::Deserialize
into/from mlua::Value
. In addition mlua
provides serde::Serialize
trait implementation for it (including UserData
support).
Compiling
You have to enable one of the features: lua54
, lua53
, lua52
, lua51
, luajit(52)
or luau
, according to the chosen Lua version.
By default mlua
uses pkg-config
tool to find lua includes and libraries for the chosen Lua version.
In most cases it works as desired, although sometimes could be more preferable to use a custom lua library.
To achieve this, mlua supports LUA_INC
, LUA_LIB
, LUA_LIB_NAME
and LUA_LINK
environment variables.
LUA_LINK
is optional and may be dylib
(a dynamic library) or static
(a static library, .a
archive).
An example how to use them:
my_project $ LUA_INC=$HOME/tmp/lua-5.2.4/src LUA_LIB=$HOME/tmp/lua-5.2.4/src LUA_LIB_NAME=lua LUA_LINK=static cargo build
mlua
also supports vendored lua/luajit using the auxiliary crates lua-src and
luajit-src.
Just enable the vendored
feature and cargo will automatically build and link specified lua/luajit version. This is the easiest way to get started with mlua
.
Standalone mode
In a standalone mode mlua
allows to add to your application scripting support with a gently configured Lua runtime to ensure safety and soundness.
Add to Cargo.toml
:
[dependencies]
mlua = { version = "0.8", features = ["lua54", "vendored"] }
main.rs
use mlua::prelude::*;
fn main() -> LuaResult<()> {
let lua = Lua::new();
let map_table = lua.create_table()?;
map_table.set(1, "one")?;
map_table.set("two", 2)?;
lua.globals().set("map_table", map_table)?;
lua.load("for k,v in pairs(map_table) do print(k,v) end").exec()?;
Ok(())
}
Module mode
In a module mode mlua
allows to create a compiled Lua module that can be loaded from Lua code using require
. In this case mlua
uses an external Lua runtime which could lead to potential unsafety due to unpredictability of the Lua environment and usage of libraries such as debug
.
Add to Cargo.toml
:
[lib]
crate-type = ["cdylib"]
[dependencies]
mlua = { version = "0.8", features = ["lua54", "vendored", "module"] }
lib.rs
:
use mlua::prelude::*;
fn hello(_: &Lua, name: String) -> LuaResult<()> {
println!("hello, {}!", name);
Ok(())
}
#[mlua::lua_module]
fn my_module(lua: &Lua) -> LuaResult<LuaTable> {
let exports = lua.create_table()?;
exports.set("hello", lua.create_function(hello)?)?;
Ok(exports)
}
And then (macOS example):
$ cargo rustc -- -C link-arg=-undefined -C link-arg=dynamic_lookup
$ ln -s ./target/debug/libmy_module.dylib ./my_module.so
$ lua5.4 -e 'require("my_module").hello("world")'
hello, world!
On macOS, you need to set additional linker arguments. One option is to compile with cargo rustc --release -- -C link-arg=-undefined -C link-arg=dynamic_lookup
, the other is to create a .cargo/config
with the following content:
[target.x86_64-apple-darwin]
rustflags = [
"-C", "link-arg=-undefined",
"-C", "link-arg=dynamic_lookup",
]
[target.aarch64-apple-darwin]
rustflags = [
"-C", "link-arg=-undefined",
"-C", "link-arg=dynamic_lookup",
]
On Linux you can build modules normally with cargo build --release
.
Vendored and non-vendored builds are supported for these OS.
On Windows vendored
mode for modules is not supported since you need to link to a Lua dll.
Easiest way is to use either MinGW64 (as part of MSYS2 package) with pkg-config
or
MSVC with LUA_INC
/ LUA_LIB
/ LUA_LIB_NAME
environment variables.
More details about compiling and linking Lua modules can be found on the Building Modules page.
Publishing to luarocks.org
There is a LuaRocks build backend for mlua modules luarocks-build-rust-mlua
.
Modules written in Rust and published to luarocks:
Safety
One of the mlua
goals is to provide safe API between Rust and Lua.
Every place where the Lua C API may trigger an error longjmp in any way is protected by lua_pcall
,
and the user of the library is protected from directly interacting with unsafe things like the Lua stack,
and there is overhead associated with this safety.
Unfortunately, mlua
does not provide absolute safety even without using unsafe
.
This library contains a huge amount of unsafe code. There are almost certainly bugs still lurking in this library!
It is surprisingly, fiendishly difficult to use the Lua C API without the potential for unsafety.
Panic handling
mlua
wraps panics that are generated inside Rust callbacks in a regular Lua error. Panics could be
resumed then by returning or propagating the Lua error to Rust code.
For example:
let lua = Lua::new();
let f = lua.create_function(|_, ()| -> LuaResult<()> {
panic!("test panic");
})?;
lua.globals().set("rust_func", f)?;
let _ = lua.load(r#"
local status, err = pcall(rust_func)
print(err) -- prints: test panic
error(err) -- propagate panic
"#).exec();
unreachable!()
Optionally mlua
can disable Rust panics catching in Lua via pcall
/xpcall
and automatically resume
them across the Lua API boundary. This is controlled via LuaOptions
and done by wrapping the Lua pcall
/xpcall
functions on a way to prevent catching errors that are wrapped Rust panics.
mlua
should also be panic safe in another way as well, which is that any Lua
instances or handles
remains usable after a user generated panic, and such panics should not break internal invariants or
leak Lua stack space. This is mostly important to safely use mlua
types in Drop impls, as you should not be
using panics for general error handling.
Below is a list of mlua
behaviors that should be considered a bug.
If you encounter them, a bug report would be very welcome:
-
If you can cause UB with
mlua
without typing the word "unsafe", this is a bug. -
If your program panics with a message that contains the string "mlua internal error", this is a bug.
-
Lua C API errors are handled by longjmp. All instances where the Lua C API would otherwise longjmp over calling stack frames should be guarded against, except in internal callbacks where this is intentional. If you detect that
mlua
is triggering a longjmp over your Rust stack frames, this is a bug! -
If you detect that, after catching a panic or during a Drop triggered from a panic, a
Lua
or handle method is triggering other bugs or there is a Lua stack space leak, this is a bug.mlua
instances are supposed to remain fully usable in the face of user generated panics. This guarantee does not extend to panics marked with "mlua internal error" simply because that is already indicative of a separate bug.
Sandboxing
Please check the Luau Sandboxing page if you are interested in running untrusted Lua scripts in controlled environment.
mlua
provides Lua::sandbox
method for enabling sandbox mode (Luau only).
License
This project is licensed under the MIT license
Dependencies
~0.7–7MB
~49K SLoC