zig-luajit

About

The goal of the zig-luajit project is to provide the most idiomatic Zig language bindings for the LuaJIT C API and C API Auxilary Library. Additionally the zig-luajit project emphasizes safety by making liberal use of runtime safety checks in Debug and ReleaseSafe builds and provides full test coverage of the API.

Zig Version

The main branch targets the latest stable Zig version. Currently 0.15.1.

For other Zig versions look for branches with the named version.

Installation & Usage

It is recommended that you install zig-luajit using zig fetch. This will add a luajit dependency to your build.zig.zon file.

zig fetch --save=luajit git+https://github.com/sackosoft/zig-luajit

Next, in order for your code to import zig-luajit, you'll need to update your build.zig to do the following:

1. get a reference the zig-luajit dependency.
2. get a reference to the luajit module, which contains the core Zig language bindings for LuaJIT.
3. add the module as an import to your executable or library.

// (1) Get a reference to the `zig fetch`'ed dependency
const luajit_dep = b.dependency("luajit", .{
    .target = target,
    .optimize = optimize,
});

// (2) Get a reference to the language bindings module.
const luajit = luajit_dep.module("luajit");

// Set up your library or executable
const lib = // ...
const exe = // ...

// (3) Add the module as an import to your executable or library.
my_exe.root_module.addImport("luajit", luajit);
my_lib.root_module.addImport("luajit", luajit);

Now the code in your library or exectable can import and use the LuaJIT Zig API!

const luajit = @import("luajit");
const Lua = luajit.Lua;

var gpa = std.heap.GeneralPurposeAllocator(.{}){};
const lua = Lua.init(gpa.allocator());
defer lua.deinit();

lua.openBaseLib();
lua.doString(
    \\ print("Hello, world!")
);

Examples

Some examples are provided in examples/ to aid users in learning to use zig-luajit. These small self-contained applications should always be working, please create an issue if they do not work for you.

const std = @import("std");
const Lua = @import("luajit").Lua;

pub fn main() !void {
    var gpa = std.heap.GeneralPurposeAllocator(.{}){};
    defer _ = gpa.deinit();

    const lua = try Lua.init(gpa.allocator());
    defer lua.deinit();

    lua.openBaseLib();

    try lua.doString(
        \\ message = "Hello, world!"
        \\ print(message)
    );
}

Language Binding Coverage Progress

†: Coroutine yield/resume is not yet part of the public zig-luajit Zig API, see #6.

Coverage and Compatibility

This section describes the current status of Zig language bindings ("the Zig API").

• ☑️ Fully Supported: Test coverage and runtime safety checks enabled in Debug or ReleaseSafe builds.
• ➖ Internal: Used internally and intentionally hidden from the Zig API.
• 🆖 Superseded: Has no direct Zig equivalent, but the functionality is provided by a different part of the Zig API.
• 📢 Renamed: Renamed in a non-obvious way from the C API. Renaming is avoided but done in cases deemed required:
  1. to conform to Zig idioms or patterns, such as the init() / deinit() pattern.
  2. to avoid conflicts with Zig language keywords, such as the Zig error keyword.
  3. to show that the Zig API has slightly different behavior than the C API, such as using lua.setAllocator() instead of lua.setAllocF(); since the Zig API uses std.mem.Allocator instead of allocation functions.
  4. to improve the clarity, discoverability or consistency of the symbol in the overall API surface.

Core C API Coverage (lua_)

Auxilary Library Coverage (luaL_)

Debug API Coverage (lua_Debug)

Additions to the API in zig-luajit

The following functions are added in zig-luajit and do not necessarily have a corresponding function or macro in the C API.

Licensing

The zig-luajit Zig languge bindings are distributed under the terms of the open and permissive MIT License. The terms of this license can be found in the LICENSE file.

This project depends on source code and other artifacts from third parties. Information about their respective licenses can be found in the COPYRIGHT file.

• The LuaJIT Project
• Lua

Credits

This project was inspired by natecraddock/ziglua which provides great functionality if you're looking to use Lua runtimes other than LuaJIT!