feat: add an option to link as a shared library

Fixes the linking code, and adds a new option to the build function to
link Ziglua as a shared library rather than as a static library. This is
for the use case of creating shared modules to require at runtime in
Lua.

Author: natecraddock

build.zig

@@ -8,7 +8,7 @@ const LuaVersion = enum {
     lua_52,
     lua_53,
     lua_54,
-    lua_jit,
+    // lua_jit,
 };
 
 fn libPath(version: LuaVersion) []const u8 {
@@ -17,8 +17,6 @@ fn libPath(version: LuaVersion) []const u8 {
         .lua_52 => "src/ziglua-5.2/lib.zig",
         .lua_53 => "src/ziglua-5.3/lib.zig",
         .lua_54 => "src/ziglua-5.4/lib.zig",
-        else => unreachable,
-        // .lua_jit => "src/ziglua-jit/lib.zig",
     };
 }
 
@@ -30,9 +28,8 @@ pub fn build(b: *Builder) void {
         .lua_52 => "src/ziglua-5.2/tests.zig",
         .lua_53 => "src/ziglua-5.3/tests.zig",
         .lua_54 => "src/ziglua-5.4/tests.zig",
-        else => unreachable,
     });
-    link(b, tests, libPath(version), .{ .use_apicheck = true, .version = version });
+    link(b, tests, .{ .use_apicheck = true, .version = version });
 
     const test_step = b.step("test", "Run ziglua library tests");
     test_step.dependOn(&tests.step);
@@ -47,47 +44,49 @@ const Options = struct {
     use_apicheck: bool = false,
     /// Defines the Lua version to build and link
     version: LuaVersion = .lua_54,
+
+    shared: bool = false,
 };
 
 pub fn linkAndPackage(b: *Builder, step: *LibExeObjStep, options: Options) std.build.Pkg {
-    const lib_path = libPath(options.version);
-    link(b, step, lib_path, options);
+    link(b, step, options);
 
+    const lib_path = libPath(options.version);
     return .{
         .name = "ziglua",
         .path = .{ .path = std.fs.path.join(b.allocator, &.{ dir(), lib_path }) catch unreachable },
     };
 }
 
 // TODO: expose the link and package steps separately for advanced use cases?
-fn link(b: *Builder, step: *LibExeObjStep, lib_path: []const u8, options: Options) void {
-    const lib = buildLua(b, step, lib_path, options);
+fn link(b: *Builder, step: *LibExeObjStep, options: Options) void {
+    const lib = buildLua(b, step, options);
     step.linkLibrary(lib);
     step.linkLibC();
 }
 
 // TODO: how to test all versions? May need a make/help script to test all
 // versions separately because there might be name collisions
-fn buildLua(b: *Builder, step: *LibExeObjStep, lib_path: []const u8, options: Options) *LibExeObjStep {
+fn buildLua(b: *Builder, step: *LibExeObjStep, options: Options) *LibExeObjStep {
     const lib_dir = switch (options.version) {
         .lua_51 => "lib/lua-5.1.5/src/",
         .lua_52 => "lib/lua-5.2.4/src/",
         .lua_53 => "lib/lua-5.3.6/src/",
         .lua_54 => "lib/lua-5.4.4/src/",
-        else => unreachable,
-        // .lua_jit => "lib/lua-5.4.4/src/",
     };
 
-    const absolute_lib_path = std.fs.path.join(b.allocator, &.{ dir(), lib_path }) catch unreachable;
-    const lib = b.addStaticLibrary("lua", absolute_lib_path);
-    lib.setBuildMode(step.build_mode);
-    lib.setTarget(step.target);
+    const lua = brk: {
+        if (options.shared) break :brk b.addSharedLibrary("lua", null, .unversioned);
+        break :brk b.addStaticLibrary("lua", null);
+    };
+    lua.setBuildMode(step.build_mode);
+    lua.setTarget(step.target);
 
     const apicheck = step.build_mode == .Debug and options.use_apicheck;
 
     step.addIncludeDir(std.fs.path.join(b.allocator, &.{ dir(), lib_dir }) catch unreachable);
 
-    const target = (std.zig.system.NativeTargetInfo.detect(b.allocator, lib.target) catch unreachable).target;
+    const target = (std.zig.system.NativeTargetInfo.detect(b.allocator, step.target) catch unreachable).target;
 
     const flags = [_][]const u8{
         // Standard version used in Lua Makefile
@@ -110,16 +109,14 @@ fn buildLua(b: *Builder, step: *LibExeObjStep, lib_path: []const u8, options: Op
         .lua_52 => &lua_52_source_files,
         .lua_53 => &lua_53_source_files,
         .lua_54 => &lua_54_source_files,
-        else => unreachable,
-        // .lua_jit => &lua_jit_source_files,
     };
 
     for (lua_source_files) |file| {
         const path = std.fs.path.join(b.allocator, &.{ dir(), lib_dir, file }) catch unreachable;
-        step.addCSourceFile(path, &flags);
+        lua.addCSourceFile(path, &flags);
     }
 
-    return lib;
+    return lua;
 }
 
 const lua_51_source_files = [_][]const u8 {

docs.md

@@ -126,12 +126,14 @@ pub fn build(b: *Builder) void {
 
 This makes the `ziglua` package available in your project. Access with `@import("ziglua")`.
 
-There are currently two options that can be passed in the third argument to `ziglua.link()`:
+There are currently three options that can be passed in the third argument to `ziglua.link()`:
 
 * `.use_apicheck`: defaults to **false**. When **true** defines the macro `LUA_USE_APICHECK` in debug builds. See [The C API docs](https://www.lua.org/manual/5.4/manual.html#4) for more information on this macro.
 
 * `.version`: Set the Lua version to build and embed. Defaults to `.lua_54`. Possible values are `.lua_51`, `.lua_52`, `.lua_53`, and `.lua_54`.
 
+* `.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).
+
 For example, here is a `ziglua.linkAndPackage()` call that enables api check and embeds Lua 5.2:
 
 ```

readme.md

@@ -1,32 +1,36 @@
-# ziglua
+# Ziglua
 
-A Zig library that provides a lightweight wrapper around the [Lua C API](https://www.lua.org/manual/5.4/manual.html#4) to embed the Lua virtual machine into your Zig programs. Currently tracks the latest Lua version (5.4.4).
+A Zig library that provides a complete yet lightweight wrapper around 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, and 5.4.
 
-Like the Lua C API, the ziglua API "emphasizes flexibility and simplicity... common tasks may involve several API calls. This may be boring, but it gives us full control over all the details" (_Programming In Lua 4th Edition_). However, ziglua takes advantage of Zig's features to make it easier and safer to interact with the Lua API.
+Ziglua offers two approaches as a library:
+* **embedded**: used to embed the Lua VM in a Zig program
+* **module**: used to create shared Lua modules that can be loaded at runtime in other Lua-based software
+
+Like the Lua C API, the Ziglua API "emphasizes flexibility and simplicity... common tasks may involve several API calls. This may be boring, but it gives us full control over all the details" (_Programming In Lua 4th Edition_). However, Ziglua takes advantage of Zig's features to make it easier and safer to interact with the Lua API.
 
 * [Docs](https://github.com/natecraddock/ziglua/blob/master/docs.md)
 * [Examples](https://github.com/natecraddock/ziglua/blob/master/docs.md#examples)
 
-## Why use ziglua?
+## Why use Ziglua?
 
-In 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:
+In 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:
 
 * 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
 * More precise types (e.g. `bool` instead of `int`)
 
-While there are some helper functions added to complement the C API, ziglua aims to remain low-level. This allows full access to the Lua API through a layer of Zig's improvements over C.
+While there are some helper functions added to complement the C API, Ziglua aims to remain low-level. This allows full access to the Lua API through a layer of Zig's improvements over C.
 
 If you want something higher-level (but doesn't expose the full API), perhaps try [zoltan](https://github.com/ranciere/zoltan).
 
 ## Getting Started
 
-Adding ziglua to your project is easy. First add this repo as a git submodule, or copy the source into your repo. Then add the following to your `build.zig` file (assuming cloned/copied into a `lib/` subdirectory):
+Adding Ziglua to your project is easy. First add this repo as a git submodule, or copy the source into your repo. Then add the following to your `build.zig` file (assuming cloned/copied into a `lib/` subdirectory):
 
 ```zig
-// use the path to the ziglua build.zig file
+// use the path to the Ziglua build.zig file
 const ziglua = @import("lib/ziglua/build.zig");
 
 pub fn build(b: *Builder) void {
@@ -56,13 +60,13 @@ pub fn main() anyerror!void {
 }
 ```
 
-See [docs.md](https://github.com/natecraddock/ziglua/blob/master/docs.md) for documentation and detailed [examples](https://github.com/natecraddock/ziglua/blob/master/docs.md#examples) of using ziglua.
+See [docs.md](https://github.com/natecraddock/ziglua/blob/master/docs.md) for documentation and detailed [examples](https://github.com/natecraddock/ziglua/blob/master/docs.md#examples) of using Ziglua.
 
 ## Status
 
-Nearly all functions, types, and constants in the C API have been wrapped in ziglua. Only a few exceptions have been made when the function doesn't make sense in Zig (like functions using `va_list`).
+Nearly all functions, types, and constants in the C API have been wrapped in Ziglua. Only a few exceptions have been made when the function doesn't make sense in Zig (like functions using `va_list`).
 
-All functions have been type checked, but only the standard C API has been tested fully. ziglua should be relatively stable and safe to use now, but is still new and changing frequently.
+All functions have been type checked, but only the standard C API has been tested fully. Ziglua should be relatively stable and safe to use now, but is still new and changing frequently.
 
 ## Acknowledgements