Skip to content

Commit

Permalink
docs: update dependency documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
natecraddock committed Jan 10, 2024
1 parent 744da91 commit b71a42e
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 74 deletions.
53 changes: 0 additions & 53 deletions docs.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,59 +10,6 @@ This documentation provides

Documentation on each individual function is found in the source code.

## Build Documentation

Example `build.zig.zon` file. The hash in the url is the hash of the commit you are using.

```
.{
.name = "myproject",
.version = "0.0.1",
.dependencies = .{
.ziglua = .{
.url = "https://github.com/natecraddock/ziglua/archive/ab111adb06d2d4dc187ee9e1e352617ca8659155.tar.gz",
.hash = "12206cf9e90462ee6e14f593ea6e0802b9fe434429ba10992a1451e32900f741005c",
},
}
}
```

Example usage in `build.zig`.

```zig
pub fn build(b: *std.Build) void {
// ... snip ...
const ziglua = b.dependency("ziglua", .{
.target = target,
.optimize = optimize,
});
// ... snip ...
// add the ziglua module and lua artifact
exe.addModule("ziglua", ziglua.module("ziglua"));
exe.linkLibrary(ziglua.artifact("lua"));
}
```

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

* `.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 `b.dependency()` call that and links against a shared Lua 5.2 library:

```zig
const ziglua = b.dependency("ziglua", .{
.target = target,
.optimize = optimize,
.version = .lua52,
.shared = true,
});
```

## Moving from the C API to Zig

While efforts have been made to keep the Ziglua API similar to the C API, many changes have been made including:
Expand Down
44 changes: 23 additions & 21 deletions readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,27 +37,12 @@ In a nutshell, Ziglua is a simple wrapper around the C API you would get by usin
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.

## Integrating Ziglua in your project
First create a `build.zig.zon` file in your Zig project if you do not already have one. Add a ziglua dependency.

```
.{
.name = "myproject",
.version = "0.0.1",
.dependencies = .{
.ziglua = .{
// Use a tagged release of Ziglua tracking a stable Zig release
.url = "https://github.com/natecraddock/ziglua/archive/refs/tags/0.2.0.tar.gz",
// Or a url with a hash for a specific Ziglua commit
.url = "https://github.com/natecraddock/ziglua/archive/ab111adb06d2d4dc187ee9e1e352617ca8659155.tar.gz",
},
}
}
```
Find the archive url of the Ziglua version you want to integrate with your project. For example, the url for the commit **41a110981cf016465f72208c3f1732fd4c92a694** is https://github.com/natecraddock/ziglua/archive/41a110981cf016465f72208c3f1732fd4c92a694.tar.gz.

When you run `zig build` it will instruct you to add a `.hash` field to this file.
Then run `zig fetch --save <url>`. This will add the dependency to your `build.zig.zon` file.

In your `build.zig` file create and use the dependency
Then in your `build.zig` file you can use the dependency.

```zig
pub fn build(b: *std.Build) void {
Expand All @@ -71,13 +56,30 @@ pub fn build(b: *std.Build) void {
// ... snip ...
// add the ziglua module and lua artifact
exe.addModule("ziglua", ziglua.module("ziglua"));
exe.linkLibrary(ziglua.artifact("lua"));
exe.root_module.addImport("ziglua", ziglua.module("ziglua"));
}
```

This will compile the Lua C sources and link with your project. The `ziglua` module will now be available in your code. Here is a simple example that pushes and inspects an integer on the Lua stack:
This will compile the Lua C sources and link with your project.

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

* `.version`: Set the Lua version 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).

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

```zig
const ziglua = b.dependency("ziglua", .{
.target = target,
.optimize = optimize,
.version = .lua52,
.shared = true,
});
``````
The `ziglua` module will now be available in your code. Here is a simple example that pushes and inspects an integer on the Lua stack:
```zig
const std = @import("std");
Expand Down

0 comments on commit b71a42e

Please sign in to comment.