Update docs
This commit is contained in:
parent
2fd6757f39
commit
f6da437d8b
|
@ -12,12 +12,13 @@ license = "MIT"
|
||||||
links = "lua"
|
links = "lua"
|
||||||
build = "build/main.rs"
|
build = "build/main.rs"
|
||||||
description = """
|
description = """
|
||||||
High level bindings to Lua 5.1/5.2/5.3 (including LuaJIT)
|
High level bindings to Lua 5.1/5.2/5.3/5.4 (including LuaJIT)
|
||||||
with async/await features and support of writing native lua modules in Rust.
|
with async/await features and support of writing native lua modules in Rust.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
[badges]
|
[badges]
|
||||||
# github-actions = { repository = "khvzak/mlua", workflow = "CI" }
|
# github-actions = { repository = "khvzak/mlua", workflow = "CI" }
|
||||||
|
maintenance = { status = "actively-developed" }
|
||||||
|
|
||||||
[package.metadata.docs.rs]
|
[package.metadata.docs.rs]
|
||||||
features = ["async"]
|
features = ["async"]
|
||||||
|
|
55
README.md
55
README.md
|
@ -10,17 +10,26 @@
|
||||||
|
|
||||||
[Guided Tour](examples/guided_tour.rs)
|
[Guided Tour](examples/guided_tour.rs)
|
||||||
|
|
||||||
A fork of [rlua 0.15](https://github.com/kyren/rlua/tree/0.15.3) which provides a high level
|
`mlua` is bindings to [Lua](https://www.lua.org) programming language for Rust with a goal to provide
|
||||||
interface between Rust and Lua. Unlike `rlua` , `mlua` supports Lua 5.1 (including LuaJIT), 5.2 and 5.3.
|
_safe_ (as far as it's possible), high level, easy to use, practical and flexible API.
|
||||||
The `mlua` goal is to be an easy to use, practical and flexible API between Rust and Lua but
|
|
||||||
*__not__* always 100% safe due to the Lua VM nature. Also, `mlua` provides a way to write native lua
|
Started as [rlua v0.15](https://github.com/amethyst/rlua/tree/0.15.3) fork, `mlua` supports *__all__* major Lua versions (including LuaJIT) and allows to write native Lua modules on Rust as well as use Lua a standalone mode.
|
||||||
modules in Rust.
|
|
||||||
|
`mlua` supports the following Lua versions (and tested on Windows/macOS/Linux):
|
||||||
|
- Lua 5.4 (`feature = "lua54"`)
|
||||||
|
- Lua 5.3 (`feature = "lua53"`, enabled by default)
|
||||||
|
- Lua 5.2 (`feature = "lua52"`)
|
||||||
|
- Lua 5.1 (`feature = "lua51"`)
|
||||||
|
- LuaJIT 2.0.5 stable (`feature = "luajit"`), although I'm not encouraging to use this version
|
||||||
|
- LuaJIT 2.1.0 beta (`feature = "luajit"`)
|
||||||
|
|
||||||
|
Additional `feature = "vendored"` enables building Lua from sources during `mlua` compilation.
|
||||||
|
|
||||||
## Usage
|
## Usage
|
||||||
|
|
||||||
### Async/await support
|
### Async/await support
|
||||||
|
|
||||||
Starting from 0.3, mlua supports async/await for all Lua versions. This works using Lua [coroutines](https://www.lua.org/manual/5.3/manual.html#2.6) and require running [Thread](https://docs.rs/mlua/latest/mlua/struct.Thread.html) along with enabling `async` feature in `Cargo.toml`.
|
Starting from v0.3, `mlua` supports async/await for all Lua versions. This works using Lua [coroutines](https://www.lua.org/manual/5.3/manual.html#2.6) and require running [Thread](https://docs.rs/mlua/latest/mlua/struct.Thread.html) along with enabling `feature = "async"` in `Cargo.toml`.
|
||||||
|
|
||||||
**Examples**:
|
**Examples**:
|
||||||
- [HTTP Client](examples/async_http_client.rs)
|
- [HTTP Client](examples/async_http_client.rs)
|
||||||
|
@ -29,9 +38,10 @@ Starting from 0.3, mlua supports async/await for all Lua versions. This works us
|
||||||
|
|
||||||
### Choosing Lua version
|
### Choosing Lua version
|
||||||
|
|
||||||
The following features could be used to choose Lua version: `lua53` (default), `lua52`, `lua51` and `luajit`.
|
The following features could be used to choose Lua version: `lua54`, `lua53` (default), `lua52`, `lua51` and `luajit`.
|
||||||
|
To switch between Lua versions it's required to set `default_features = false` in `mlua` dependency.
|
||||||
|
|
||||||
By default mlua uses `pkg-config` tool to find lua includes and lib.
|
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.
|
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.
|
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).
|
`LUA_LINK` is optional and may be `dylib` (a dynamic library) or `static` (a static library, `.a` archive).
|
||||||
|
@ -43,14 +53,14 @@ my_project $ LUA_INC=$HOME/tmp/lua-5.2.4/src LUA_LIB=$HOME/tmp/lua-5.2.4/src LUA
|
||||||
|
|
||||||
`mlua` also supports vendored lua/luajit using the auxilary crates [lua-src](https://crates.io/crates/lua-src) and
|
`mlua` also supports vendored lua/luajit using the auxilary crates [lua-src](https://crates.io/crates/lua-src) and
|
||||||
[luajit-src](https://crates.io/crates/luajit-src).
|
[luajit-src](https://crates.io/crates/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.
|
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
|
### Standalone mode
|
||||||
Add to `Cargo.toml` :
|
Add to `Cargo.toml` :
|
||||||
|
|
||||||
``` toml
|
``` toml
|
||||||
[dependencies]
|
[dependencies]
|
||||||
mlua = "0.3"
|
mlua = "0.4"
|
||||||
```
|
```
|
||||||
|
|
||||||
`main.rs`
|
`main.rs`
|
||||||
|
@ -82,8 +92,8 @@ Add to `Cargo.toml` :
|
||||||
crate-type = ["cdylib"]
|
crate-type = ["cdylib"]
|
||||||
|
|
||||||
[dependencies]
|
[dependencies]
|
||||||
mlua = "0.3"
|
mlua = "0.4"
|
||||||
mlua_derive = "0.3"
|
mlua_derive = "0.4"
|
||||||
```
|
```
|
||||||
|
|
||||||
`lib.rs` :
|
`lib.rs` :
|
||||||
|
@ -106,7 +116,7 @@ fn my_module(lua: &Lua) -> LuaResult<LuaTable> {
|
||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
And then (macos example):
|
And then (macOS example):
|
||||||
|
|
||||||
``` sh
|
``` sh
|
||||||
$ cargo build
|
$ cargo build
|
||||||
|
@ -118,15 +128,13 @@ hello, world!
|
||||||
## Safety
|
## Safety
|
||||||
|
|
||||||
One of the `mlua` goals is to provide *safe* API between Rust and Lua.
|
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
|
Every place where the Lua C API may trigger an error longjmp in any way is protected by `lua_pcall`,
|
||||||
in any way is protected by `lua_pcall` , and the user of the library is protected
|
and the user of the library is protected from directly interacting with unsafe things like the Lua stack,
|
||||||
from directly interacting with unsafe things like the Lua stack, and there is
|
and there is overhead associated with this safety.
|
||||||
overhead associated with this safety.
|
|
||||||
|
|
||||||
Unfortunately, `mlua` does not provide absolute safety even without using `unsafe` .
|
Unfortunately, `mlua` does not provide absolute safety even without using `unsafe` .
|
||||||
This library contains a huge amount of unsafe code. There are almost
|
This library contains a huge amount of unsafe code. There are almost certainly bugs still lurking in this library!
|
||||||
certainly bugs still lurking in this library! It is surprisingly, fiendishly
|
It is surprisingly, fiendishly difficult to use the Lua C API without the potential for unsafety.
|
||||||
difficult to use the Lua C API without the potential for unsafety.
|
|
||||||
|
|
||||||
## Panic handling
|
## Panic handling
|
||||||
|
|
||||||
|
@ -150,10 +158,9 @@ let _ = lua.load(r#"
|
||||||
unreachable!()
|
unreachable!()
|
||||||
```
|
```
|
||||||
|
|
||||||
`mlua` should also be panic safe in another way as well, which is that any `Lua`
|
`mlua` should also be panic safe in another way as well, which is that any `Lua` instances or handles
|
||||||
instances or handles remains usable after a user generated panic, and such
|
remains usable after a user generated panic, and such panics should not break internal invariants or
|
||||||
panics should not break internal invariants or leak Lua stack space. This is
|
leak Lua stack space. This is mostly important to safely use `mlua` types in Drop impls, as you should not be
|
||||||
mostly important to safely use `mlua` types in Drop impls, as you should not be
|
|
||||||
using panics for general error handling.
|
using panics for general error handling.
|
||||||
|
|
||||||
Below is a list of `mlua` behaviors that should be considered a bug.
|
Below is a list of `mlua` behaviors that should be considered a bug.
|
||||||
|
|
|
@ -114,7 +114,7 @@ impl Lua {
|
||||||
/// Creates a new Lua state and loads the safe subset of the standard libraries.
|
/// Creates a new Lua state and loads the safe subset of the standard libraries.
|
||||||
///
|
///
|
||||||
/// # Safety
|
/// # Safety
|
||||||
/// The created Lua state would have safety guarantees and would not allow to load unsafe
|
/// The created Lua state would have _some_ safety guarantees and would not allow to load unsafe
|
||||||
/// standard libraries or C modules.
|
/// standard libraries or C modules.
|
||||||
#[allow(clippy::new_without_default)]
|
#[allow(clippy::new_without_default)]
|
||||||
pub fn new() -> Lua {
|
pub fn new() -> Lua {
|
||||||
|
@ -137,7 +137,7 @@ impl Lua {
|
||||||
/// Use the [`StdLib`] flags to specifiy the libraries you want to load.
|
/// Use the [`StdLib`] flags to specifiy the libraries you want to load.
|
||||||
///
|
///
|
||||||
/// # Safety
|
/// # Safety
|
||||||
/// The created Lua state would have safety guarantees and would not allow to load unsafe
|
/// The created Lua state would have _some_ safety guarantees and would not allow to load unsafe
|
||||||
/// standard libraries or C modules.
|
/// standard libraries or C modules.
|
||||||
///
|
///
|
||||||
/// [`StdLib`]: struct.StdLib.html
|
/// [`StdLib`]: struct.StdLib.html
|
||||||
|
|
Loading…
Reference in New Issue