{"id":13711048,"url":"https://github.com/natecraddock/ziglua","last_synced_at":"2025-05-16T01:07:45.180Z","repository":{"id":41262521,"uuid":"498992145","full_name":"natecraddock/ziglua","owner":"natecraddock","description":"Zig bindings for the Lua C API","archived":false,"fork":false,"pushed_at":"2025-05-02T13:01:49.000Z","size":1517,"stargazers_count":347,"open_issues_count":24,"forks_count":52,"subscribers_count":11,"default_branch":"main","last_synced_at":"2025-05-02T14:23:39.532Z","etag":null,"topics":["binding","library","lua","lua-bindings","package","zig","zig-package"],"latest_commit_sha":null,"homepage":"","language":"Zig","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/natecraddock.png","metadata":{"files":{"readme":"readme.md","changelog":"changelog.md","contributing":null,"funding":null,"license":"license","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2022-06-02T04:37:17.000Z","updated_at":"2025-05-02T13:01:54.000Z","dependencies_parsed_at":"2024-01-02T04:27:13.802Z","dependency_job_id":"44387bd9-26f3-4a35-bd07-e85c4ceb0284","html_url":"https://github.com/natecraddock/ziglua","commit_stats":{"total_commits":294,"total_committers":14,"mean_commits":21.0,"dds":0.08163265306122447,"last_synced_commit":"74796808b5bf7c81bf6f1e1b48d97ad01f87ec45"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fziglua","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fziglua/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fziglua/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/natecraddock%2Fziglua/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/natecraddock","download_url":"https://codeload.github.com/natecraddock/ziglua/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254448578,"owners_count":22072764,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["binding","library","lua","lua-bindings","package","zig","zig-package"],"created_at":"2024-08-02T23:01:03.886Z","updated_at":"2025-05-16T01:07:40.161Z","avatar_url":"https://github.com/natecraddock.png","language":"Zig","readme":"# Ziglua\n[![shield showing current tests status](https://github.com/natecraddock/ziglua/actions/workflows/tests.yml/badge.svg)](https://github.com/natecraddock/ziglua/actions/workflows/tests.yml)\n[![Discord](https://img.shields.io/discord/1196908820140671077?style=flat\u0026logo=discord)](https://discord.com/invite/XpZqDFvAtK)\n\nZig bindings for the [Lua C API](https://www.lua.org/manual/5.4/manual.html#4). Ziglua currently supports the latest releases of Lua 5.1, 5.2, 5.3, 5.4, and [Luau](https://luau-lang.org).\n\nZiglua can be used in two ways, either\n* **embedded** to statically embed the Lua VM in a Zig program,\n* or as a shared **module** to create Lua libraries that can be loaded at runtime in other Lua-based software.\n\nIn 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.\n\nZiglua `main` is kept up to date with Zig `master`. See the [`zig-0.13.0`](https://github.com/natecraddock/ziglua/tree/zig-0.13.0) branch for Zig 0.13.0 support.\n\n## Documentation\nDocs are a work in progress and are automatically generated. Most functions and public declarations are documented:\n* [Ziglua Docs](https://natecraddock.github.io/ziglua/#ziglua.lib.Lua)\n\nSee [docs.md](https://github.com/natecraddock/ziglua/blob/main/docs.md) for more general information on Ziglua and how it differs from the C API.\n\nExample code is included in the [examples](https://github.com/natecraddock/ziglua/tree/main/examples) directory.\n* Run an example with `zig build run-example-\u003cname\u003e`\n* Install an example with `zig build install-example-\u003cname\u003e`\n\n## Why use Ziglua?\nIn a nutshell, Ziglua is a simple wrapper around the C API you would get by using Zig's `@cImport()`. Ziglua aims to mirror the [Lua C API](https://www.lua.org/manual/5.4/manual.html#4) as closely as possible, while improving ergonomics using Zig's features. For example:\n\n* Zig error unions to require failure state handling\n* Null-terminated slices instead of C strings\n* Type-checked enums for parameters and return values\n* Compiler-enforced checking of optional pointers\n* Better types in many cases (e.g. `bool` instead of `int`)\n* Comptime convenience functions to make binding creation easier\n\nNearly 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.\n\n## Integrating Ziglua in your project\n\nRun `zig fetch --save git+https://github.com/natecraddock/ziglua` to add the most recent commit of ziglua to your `build.zig.zon` file.\n\nAdd a `#\u003ctag\u003e` to the url to use a specific tagged release or commit like `zig fetch --save git+https://github.com/natecraddock/ziglua#0.3.0`\n\nThen in your `build.zig` file you can use the dependency.\n\n```zig\npub fn build(b: *std.Build) void {\n    // ... snip ...\n\n    const lua_dep = b.dependency(\"zlua\", .{\n        .target = target,\n        .optimize = optimize,\n    });\n\n    // ... snip ...\n\n    // add the zlua module and lua artifact\n    exe.root_module.addImport(\"zlua\", lua_dep.module(\"zlua\"));\n\n}\n```\n\nThis will compile the Lua C sources and link with your project.\n\nThere are currently three additional options that can be passed to `b.dependency()`:\n\n* `.lang`: Set the Lua language to build and embed. Defaults to `.lua54`. Possible values are `.lua51`, `.lua52`, `.lua53`, `.lua54`, and `luau`.\n* `.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).\n* `luau_use_4_vector`: defaults to false. Set to true to use 4-vectors instead of the default 3-vector in Luau.\n\nFor example, here is a `b.dependency()` call that and links against a shared Lua 5.2 library:\n\n```zig\nconst zlua = b.dependency(\"zlua\", .{\n    .target = target,\n    .optimize = optimize,\n    .lang = .lua52,\n    .shared = true,\n});\n``````\n\nThe `zlua` module will now be available in your code. Here is a simple example that pushes and inspects an integer on the Lua stack:\n\n```zig\nconst std = @import(\"std\");\nconst zlua = @import(\"zlua\");\n\nconst Lua = zlua.Lua;\n\npub fn main() anyerror!void {\n    // Create an allocator\n    var gpa = std.heap.GeneralPurposeAllocator(.{}){};\n    const allocator = gpa.allocator();\n    defer _ = gpa.deinit();\n\n    // Initialize the Lua vm\n    var lua = try Lua.init(allocator);\n    defer lua.deinit();\n\n    // Add an integer to the Lua stack and retrieve it\n    lua.pushInteger(42);\n    std.debug.print(\"{}\\n\", .{try lua.toInteger(1)});\n}\n```\n\n## Contributing\nPlease make suggestions, report bugs, and create pull requests. Anyone is welcome to contribute!\n\nI 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!\n\nThank you to the [Lua](https://lua.org) team for creating such a great language!\n","funding_links":[],"categories":["Zig","Interoperability"],"sub_categories":["FFI Bindings"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatecraddock%2Fziglua","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnatecraddock%2Fziglua","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnatecraddock%2Fziglua/lists"}