Ziglua

Zig bindings for the Lua C API. Ziglua currently supports the latest releases of Lua 5.1, 5.2, 5.3, 5.4, 5.5, LuaJIT and Luau.

Ziglua can be used in two ways, either

• embedded to statically embed the Lua VM in a Zig program,
• or as a shared module to create Lua libraries that can be loaded at runtime in other Lua-based software.

In both cases, Ziglua will compile Lua from source and link against your Zig code making it easy to create software that integrates with Lua without requiring any system Lua libraries.

Ziglua main is kept up to date with Zig master. See the zig-0.15.2 branch for Zig 0.15.2 support.

Documentation

Docs are automatically generated and contain a guide on getting started with ziglua. Most functions and public declarations are documented:

• Ziglua Docs

Example code is included in the examples directory.

• Run an example with zig build run-example-<name>
• Install an example with zig build install-example-<name>

An additional example (examples/lpeg) shows how to compile and link a Lua module written in C like LPeg.

Why use Ziglua?

Ziglua is a simple wrapper around the C API. Ziglua aims to mirror the Lua C API as closely as possible, while improving ergonomics using Zig's features. For example:

• Zig error unions to require failure state handling
• Null-terminated slices instead of C strings
• Type-checked enums for parameters and return values
• Compiler-enforced checking of optional pointers
• Better types in many cases (e.g. bool instead of int)
• Comptime convenience functions to make binding creation easier

Nearly every function in the C API is exposed in Ziglua. Additional convenience functions like toAny and pushAny use comptime reflection to make the API easier to use.

Integrating Ziglua in your project

Run zig fetch --save git+https://github.com/natecraddock/ziglua to add the most recent commit of ziglua to your build.zig.zon file.

Add a #<tag> to the url to use a specific tagged release or commit like zig fetch --save git+https://github.com/natecraddock/ziglua#0.3.0

Then in your build.zig file you can use the dependency.

pub fn build(b: *std.Build) void {
    // ... snip ...

    const lua_dep = b.dependency("zlua", .{
        .target = target,
        .optimize = optimize,
    });

    // ... snip ...

    // add the zlua module and lua artifact
    exe.root_module.addImport("zlua", lua_dep.module("zlua"));

}

This will compile the Lua C sources and link with your project.

You can also use lua_dep.artifact("lua") to access the compiled lua library.

There are currently three additional options that can be passed to b.dependency():

• .lang: Set the Lua language to build and embed. Defaults to .lua55. Possible values are .lua51, .lua52, .lua53, .lua54, .lua55, and luau.
• .shared: Defaults to false for embedding in a Zig program. Set to true to dynamically link the Lua source code (useful for creating shared modules).
• luau_use_4_vector: defaults to false. Set to true to use 4-vectors instead of the default 3-vector in Luau.
• lua_user_h: defaults to null. Provide a path to an additional header file for the Lua compilation. Must be set to to examples/user.h in order to run the multithreaded example.

For example, here is a b.dependency() call that and links against a shared Lua 5.2 library:

const zlua = b.dependency("zlua", .{
    .target = target,
    .optimize = optimize,
    .lang = .lua52,
    .shared = true,
});

The zlua module will now be available in your code. Here is a simple example that pushes and inspects an integer on the Lua stack:

const std = @import("std");
const zlua = @import("zlua");

const Lua = zlua.Lua;

pub fn main(init: std.process.Init) anyerror!void {
    // Get an allocator from juicy main
    const gpa = init.gpa;

    // Initialize the Lua vm
    var lua = try Lua.init(gpa);
    defer lua.deinit();

    // Add an integer to the Lua stack and retrieve it
    lua.pushInteger(42);
    std.debug.print("{}\n", .{try lua.toInteger(1)});
}

Contributing

Please make suggestions, report bugs, and create pull requests. Anyone is welcome to contribute!

I only use a subset of the Lua API through Ziglua, so if there are parts that aren't easy to use or understand, please fix it yourself or let me know!

Thank you to the Lua team for creating such a great language!