tsuki - GitLite

KO | EN

gitlite — search

#javascript #hacktoberfest #react #typescript #golang #go #machine-learning #linux #macos #nodejs #java #cli #mcp #openai

tsuki

(★ 149)

Lua 5.4 ported to Rust

File Explorer

Download Latest Version (.zip)

- - ci-linux.yml
  - ci-mac.yml
  - ci-windows.yml
  - main.yml
  - publish.yml
- FUNDING.yml
- settings.json
- fannkuch-redux.lua
- lua.rs
- - lib.rs
- Cargo.toml
- - mod.rs
- - btree_map.rs
  - mod.rs
  - value.rs
- - arg.rs
  - mod.rs
- - mod.rs
- - mark.rs
  - mod.rs
  - object.rs
  - ref.rs
- - mod.rs
- - mod.rs
- - float.rs
  - mod.rs
- - mod.rs
- - mod.rs
  - value.rs
- - mod.rs
  - table.rs
- - iter.rs
  - legacy.rs
  - mod.rs
  - node.rs
  - rust.rs
- - input.rs
  - mod.rs
  - output.rs
  - stack.rs
- - mod.rs
- - class.rs
  - mod.rs
  - property.rs
- - mod.rs
  - serde.rs
- - mod.rs
- lapi.rs
- lauxlib.rs
- lcode.rs
- lcorolib.rs
- lctype.rs
- ldebug.rs
- ldo.rs
- lfunc.rs
- lib.rs
- liolib.rs
- llex.rs
- lmathlib.rs
- lmem.rs
- loadlib.rs
- lobject.rs
- loslib.rs
- lparser.rs
- lstate.rs
- lstring.rs
- lstrlib.rs
- ltablib.rs
- ltm.rs
- lutf8lib.rs
- lzio.rs
- - badkey.lua
  - close.lua
  - closure.lua
  - coroutine.lua
  - error.lua
  - errors.lua
  - events.lua
  - locals.lua
  - math.lua
  - print.lua
  - strings.lua
  - tpack.lua
  - userdata.lua
  - vararg.lua
- api.rs
- async.rs
- lua.rs
.gitignore
.gitmodules
Cargo.toml
LICENSE
lua
README.md

# Installation Guide

1. Get the code

git clone https://github.com/ultimaweapon/tsuki

Downloads the entire project code from GitHub to your computer.

cd tsuki

Moves into the project folder you just downloaded.

2. Rust

Medium Recommended

Prerequisites

Git Needed to download the project code from GitHub.
Rust (rustup) Installing via rustup also installs cargo.

cargo build --release

Compiles the Rust project.

cargo run

Builds and then immediately runs the program.

✅ If cargo build finishes without errors, it worked. The executable is created under target/.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Tsuki
[![Crates.io Version](https://img.shields.io/crates/v/tsuki)](https://crates.io/crates/tsuki)

Tsuki is a port of Lua 5.4 to Rust. This is porting, not binding; which mean all code are Rust and can be using without C compiler. The initial works was done by [C2Rust](https://github.com/immunant/c2rust). Note that this port was done **without** compatibility with previous Lua version. You can see a list of the differences [here](https://www.lua.org/manual/5.4/manual.html#8).

> [!IMPORTANT]
> One of the project non-goal has been dropped and it is very likely Tsuki will add some extensions to Lua to boost performance on JIT.

## Status

The VM to run Lua code is fully working almost exactly as vanilla Lua (see some of differences below). Some functions on Lua standard library are still missing.

> [!IMPORTANT]
> All types in Tsuki does not implement `Send` and `Sync` and no plan to support this at the moment.

## Safety

All public API of Tsuki should provide 100% safety as long as you don't use unsafe API incorrectly.

However, Tsuki was not designed to run untrusted Lua script. Although you can limit what Lua script can do by not expose a function to it but there is no way to limit amount of memory or execution time used by Lua script. The meaning of this is Lua script can cause a panic due to out of memory or never return the control back to Rust with infinite loop. It is also possible for Lua script to cause stack overflow on Rust.

## Performance

### Interpreter

Tsuki is slower than Lua about 40% on Linux, 22% on macOS and faster than Lua about 6% on Windows. The reason Tsuki are slower than Lua is because computed goto currently not available on Rust.

#### Async

A call to async function without any suspend on Tsuki is faster than mlua about 2.6x. For 1 suspend Tsuki it faster about 2.3x. For 8 suspend Tsuki is faster about 1.8x.

### JIT

Tsuki is faster than Lua about 38% on AMD Ryzen 5 5600G and 63% on Apple M1. The performance improved from interpreter is almost 2x.

#### Async

A call to async function without any suspend on Tsuki is faster than mlua about 3x. For 1 suspend Tsuki it faster about 2.5x. For 8 suspend Tsuki is faster about 2.1x.

## Features

- 100% Rust code.
  - [libc](https://crates.io/crates/libc) is required at the moment.
- Support JIT.
  - This is a preview feature and may contains memory bugs.
- Support both synchronous and asynchronous.
- Safe, ergonomic and low overhead API.
- Strongly typed registry.
- Rust collections to store Lua values (e.g. [BTreeMap](https://doc.rust-lang.org/alloc/collections/btree_map/struct.BTreeMap.html)).
- Any error propagated to the caller via Rust `Result` instead of a long jump.
- `core::any::Any` as Lua userdata and can be created without the need to define its metatable.
- Metatable for a userdata is lookup with `core::any::TypeId` instead of a string.
- Property system on userdata to store per-object values for fast access from Lua.

## Differences from Lua

### VM and Language

- Binary chunk is not supported.
- Yield across Rust boundaries is not supported.
- Hook functions is not supported.
- Light userdata is not supported.
- Error with Lua value is not supported.
- Panic when memory allocation is failed without retry (same as Rust).
- No recursion checks on a call to Rust function.
- Rust function cannot yield the values back to Lua in the middle.
- GC has only one mode and cannot control from outside.
- Chunk name does not have a prefix (e.g. `@`).
- Second argument to `__close` metamethod always `nil`.
- `__gc` metamethod is not supported.
- `__name` metavalue must be UTF-8 string.
- `__tostring` metamethod must return a UTF-8 string.
- Float to string conversion does not truncate precision (Lua limit to 14 digits by default).
- Float literal does not accept hexadecimal format.
- String literal must be a UTF-8 string.
  - The result string can be non-UTF-8, only the literal need to be UTF-8.
- Comment must be a UTF-8 string.
- U+000B VERTICAL TAB is not considered as a whitespace.
- C locale is ignored (once `libc` has been completely removed).

### Standard library

- No `_VERSION`, `collectgarbage`, `dofile`, `loadfile`, `warn`, `xpcall`, `string.dump` and debug library.
- Second argument of `assert` accept only a UTF-8 string.
- `coroutine.isyieldable` does not accept any arguments.
- Arguments of `error`:
  - First argument accept only a UTF-8 string.
  - Second argument is not supported and it is always assume 1.
- Arguments of `load`:
  - First argument accept only a string.
  - Second argument accept only a UTF-8 string and will be empty when absent.
  - Third argument must be `nil` or `"t"`.
- `pcall` can produce up to 4 results on error and the message does not have a prefix.
  - 3rd result is a chunk name.
  - 4th result is a line number.
  - 3rd and 4th results will be absent if the called function is a Rust function.
- `coroutine.resume` can produce up to 4 results on error the same as `pcall`.
- `string.format` requires format string to be UTF-8.
  - `a`, `A`, `e`, `E`, `g` and `G` format is not supported.
  - `q` format requires string value to be UTF-8 and will use decimal notation instead of hexadecimal exponent notation for float.
  - Format have unlimited length.
- `string.find` and `string.gsub` does not support class `z`.
- `string.pack`, `string.packsize` and `string.unpack` requires UTF-8 string for format string and format error always argument error.
- `string.unpack` always report data error as argument error.
- Native module is not supported.
- Environment variable `LUA_PATH` and `LUA_PATH_5_4` is ignored.
- `LUA_NOENV` in registry is ignored.

## Differences between JIT and interpreter

When JIT is enabled, calling Lua function from Lua also consume Rust stack. The meaning of this is the number of nested calls are much lower in JIT and it will trigger stack overflow on Rust stack when too much nested calls, which results in program termination. Although the limit are much lower it is still high enough for most applications. Usually the only cases you will hit this limit is too much recursive call.

## Non-goals

- C API compatibility.
- Stand-alone mode.
- 16-bit systems.

## Roadmap

- Complete Lua standard library.
- Remove libc.

## Breaking changes in 0.4

- `YieldFp` has been added to `Value`.
- `Float` methods has been removed.
- `BadInst` has been removed.
- `ChunkInfo` was replaced with `String`.
- `Context::push_from_index` and `Context::push_from_index_with_int` has been replaced with `Thread::index`.
- `Str::as_str` has been renamed to `Str::as_utf8`.
- `Arg::as_int` has additional parameter.
- `Str`, `Table`, `LuaFn` and `UserData` no longer implement `Unpin`.
- `DynamicInputs::push_num` has been renamed to `DynamicInputs::push_float`.
- `DynamicInputs::push_fp` now accept `Fp` instead of function pointer.
- `pcall` now produce up to 4 results on error and the message does not have a prefix.
- `string.format` now implemented in Rust with some breaking changes.
- `string.rep` now have the same result limit as Lua.
- Main thread has been removed.
- Recursion checks on a call to Rust function has been removed.
- String literal now required a UTF-8 string.
- Comment now required a UTF-8 string.

## Frequently Asked Questions

### Can we have zero-based indexing?

This requires too much changes to the language so the answer is no. See [#16](https://github.com/ultimaweapon/tsuki/issues/16) for more details.

### Does JIT mode the same as LuaJIT?

No. LuaJIT is Tracing JIT while Tsuki is Method JIT. It is likely for LuaJIT to be faster since Lua is dynamic typing, which make some type checking still present at runtime for Method JIT. The benefits Tsuki got from JIT is the elimination of some branches, interpreter jump table, dead code and possibility of optimization from Cranelift.

## Contribution

We don't accept AI generated code. This also include code documentation.

## License

Same as Lua, which is MIT.