Add instructions on how to interface the library in a Zig project.

[monomycelium]

Hello, there! I've been wanting to write a WebSocket server in Zig, and this project seems wonderful. However, the only thing blocking me from building amazing things is my not knowing how to use this library from my own Zig project, which I initialised using zig build-exe. Could you help me?

[karlseguin]

If you're asking how to actually add the library to your project then...

Two or so months ago, the developed branch of Zig (0.11.0-dev..) added a built-in package manager. It's relatively cumbersome to use right now, but it works. https://medium.com/@edlyuu/zig-package-manager-wtf-is-zon-df5ecbafcc54 is maybe the best end-to-end guide I've seen.

In short, you'd create a build.zig.zon file in the root, and it'll contain something like:

.{
    .name = "your-app-name",
    .version = "0.0.0",
    .dependencies = .{
        .websocket = .{
            .url = "https://github.com/karlseguin/websocket.zig/archive/fda94dbf012783553209d384b56549dbe0367105.tar.gz",
            .hash = "1220a436e7e2e498447d79057194e84c9f7158a8c796dbe721dbe14bb1de5f25c92f"
        }
    }
}

That archive is the latest version of websocket.zig. There's no great way to get the hash right now, as far as I know, aside from putting in the wrong one and letting Zig tell you what it should be. The above hash is wrong, when you try to run, it should complain about it and tell you what the right one is, just copy and paste the right one over the wrong value above.

Now in your build.zig, you can grab this dependency and add the module to your project, something like:

const websocket = b.dependency("websocket", .{
  .target = target,
  .optimize = optimize,
});
const exe = b.addExecutable(.{
  .name = "your-app",
  .root_source_file = .{ .path = "src/main.zig" },
  .target = target,
  .optimize = optimize,
});
exec.addModule("websocket", websocket.module("websocket"));
...

If you have other steps, like one created from b.addTest then you also addModule(....) on that step.

Once that's done, you can @import("websocket") in your project as shown in the readme.

[monomycelium]

Thanks; that's working like a charm! Though, zls seems to be oblivious to the dependency, which makes it hard to discover the library's features. I'd really appreciate some documentation (or a build step to generate them)!

[karlseguin]

I guess zls might not work because it the library largely works by being given a handler which takes over processing the request, so aside from the initial call to listen and the ability write to the client, there isn't much else.

There's the autobahn.zig file, in the root of the repo, which is a working example (the actual code that's used to test the implementation against the autobahn test framework). That, and the readme, are pretty complete documentation.