From fe9055a86b6a2d297b5ae8174521cc379d347a66 Mon Sep 17 00:00:00 2001
From: yiv1 <lexx_moscow@bk.ru>
Date: Thu, 17 Jul 2025 12:41:44 +0300
Subject: [PATCH] improvement(docs): adding to documentation

---
 docs.md                                       | 32 +++++++++++++++++
 examples/shared-module-template/build.zig     | 35 +++++++++++++++++++
 examples/shared-module-template/build.zig.zon | 21 +++++++++++
 examples/shared-module-template/lua.zig       | 27 ++++++++++++++
 examples/shared-module-template/test.lua      |  4 +++
 readme.md                                     |  3 +-
 6 files changed, 121 insertions(+), 1 deletion(-)
 create mode 100644 examples/shared-module-template/build.zig
 create mode 100644 examples/shared-module-template/build.zig.zon
 create mode 100644 examples/shared-module-template/lua.zig
 create mode 100644 examples/shared-module-template/test.lua

diff --git a/docs.md b/docs.md
index 0dbc183..32438fa 100644
--- a/docs.md
+++ b/docs.md
@@ -103,3 +103,35 @@ This is a macro for `lua_pushstring`, so use `Lua.pushString()` instead.
 ### `pcall`
 
 Both `lua_pcall` and `lua_pcallk` are expanded to `protectedCall` and `protectedCallCont` for readability.
+
+## Compile Shared Module
+
+Thanks to **Shared Module** we can write our code in `zig`, and compile it into a small library file, which can be imported in a `*.lua` file.
+
+The point of **Shared Module** is to not drag the entire lua source code along with you.
+It is assumed that lua functions already exist in an external library file (for example `*.so` or `*.dll`),
+and we need to make dynamic links (import) of the external library.
+
+```zig
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    // ... snip ...
+
+    const library_name: []const u8 = "lua54";
+
+    const lua_dep = b.dependency("zlua", .{
+        .target = target,
+        .optimize = .ReleaseFast,
+        .lang = .lua54,
+        .shared = true, // set to `true` to dynamically link the Lua source code (useful for creating shared modules)
+        .library_name = library_name, // change lua library name for linkage
+    });
+
+    libraryLua.root_module.addImport("zlua", lua_dep.module("zlua"));
+
+    b.installArtifact(libraryLua);
+}
+```
+
+A detailed full example can be found at `examples/shared-module-template`.
diff --git a/examples/shared-module-template/build.zig b/examples/shared-module-template/build.zig
new file mode 100644
index 0000000..3b23276
--- /dev/null
+++ b/examples/shared-module-template/build.zig
@@ -0,0 +1,35 @@
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    const target = b.standardTargetOptions(.{});
+
+    const moduleLua = b.createModule(.{
+        .root_source_file = b.path("./lua.zig"), // our module with source code
+        .target = target,
+        .optimize = .ReleaseFast,
+    });
+
+    const libraryLua = b.addLibrary(.{
+        .linkage = .dynamic,
+        .name = "lualib", // the name of our source file (shared module) that we will import into lua
+        .root_module = moduleLua,
+    });
+
+    // if you download the prebinaries files from https://luabinaries.sourceforge.net
+    // from SourceForge `Home/5.4.2/Windows Libraries/Dynamic/lua-5.4.2_Win64_dll17_lib.zip`
+    // you will see that the lua library is called `lua54.dll`, not `lua.dll`
+    // by default ziglua imports `lua.dll`, and we want to change this behavior
+    const library_name: []const u8 = "lua54";
+
+    const lua_dep = b.dependency("zlua", .{
+        .target = target,
+        .optimize = .ReleaseFast,
+        .lang = .lua54,
+        .shared = true, // set to `true` to dynamically link the Lua source code (useful for creating shared modules)
+        .library_name = library_name, // change lua library name for linkage
+    });
+
+    libraryLua.root_module.addImport("zlua", lua_dep.module("zlua"));
+
+    b.installArtifact(libraryLua);
+}
diff --git a/examples/shared-module-template/build.zig.zon b/examples/shared-module-template/build.zig.zon
new file mode 100644
index 0000000..66b3931
--- /dev/null
+++ b/examples/shared-module-template/build.zig.zon
@@ -0,0 +1,21 @@
+.{
+    // create a fresh zon file using `zig fetch --save git+https://github.com/natecraddock/ziglua`
+    .name = .ziglua,
+    .version = "0.0.0",
+    .fingerprint = 0x98bbbba34dcf48,
+    .minimum_zig_version = "0.14.0",
+    .dependencies = .{
+        .zlua = .{
+            .url = "git+https://github.com/natecraddock/ziglua#b1fa62844dafb782219631d88b7fc70e0b7cfe37",
+            .hash = "zlua-0.1.0-hGRpCxwbBQCft7Dgs_DsO0OGBbCUGgXn_mQd5c382Jn5",
+        },
+    },
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        // For example...
+        //"LICENSE",
+        //"README.md",
+    },
+}
diff --git a/examples/shared-module-template/lua.zig b/examples/shared-module-template/lua.zig
new file mode 100644
index 0000000..5bb42e6
--- /dev/null
+++ b/examples/shared-module-template/lua.zig
@@ -0,0 +1,27 @@
+const std = @import("std");
+const zlua = @import("zlua");
+const Lua = zlua.Lua;
+
+fn add(L: *Lua) i32 {
+    const arg = L.toInteger(1) catch 0;
+
+    std.debug.print("Argument from Lua: {}\n", .{arg});
+
+    L.pushInteger(arg + 1);
+
+    return 1;
+}
+
+fn module(lua: *Lua) i32 {
+    const functions = [_]zlua.FnReg{
+        zlua.FnReg{ .name = "add", .func = zlua.wrap(add) },
+    };
+
+    Lua.newLib(lua, &functions);
+
+    return 1;
+}
+
+comptime {
+    _ = zlua.exportFn("lualib", module);
+}
diff --git a/examples/shared-module-template/test.lua b/examples/shared-module-template/test.lua
new file mode 100644
index 0000000..2680e55
--- /dev/null
+++ b/examples/shared-module-template/test.lua
@@ -0,0 +1,4 @@
+local lualib = require("lualib")
+
+local result = lualib.add(42)
+print("Result:", result)
\ No newline at end of file
diff --git a/readme.md b/readme.md
index a4199ad..1f9741d 100644
--- a/readme.md
+++ b/readme.md
@@ -64,7 +64,8 @@ This will compile the Lua C sources and link with your project.
 There are currently three additional options that can be passed to `b.dependency()`:
 
 * `.lang`: Set the Lua language to build and embed. Defaults to `.lua54`. Possible values are `.lua51`, `.lua52`, `.lua53`, `.lua54`, 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).
+* `.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). See [docs.md](https://github.com/natecraddock/ziglua/blob/main/docs.md) chapter `Compile Shared Module`
+* `.library_name`: defaults to `lua`. Only for `.lang` with `lua5*`. See [docs.md](https://github.com/natecraddock/ziglua/blob/main/docs.md) chapter `Compile Shared Module`
 * `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.