Merge branch 'zig-0.12.0'

.github/workflows/mastercheck.yml

@@ -1,21 +1,20 @@
 name: Works with Zig master
 on: 
-  #   push:
-  #     branches:
-  #     - master
-  #   pull_request:
-  #     branches:
-  #     - master
-  #   schedule:
-  #     - cron: "0 0 * * *"
-  workflow_dispatch:
+    push:
+      branches:
+      - zig-0.12.0
+    pull_request:
+      branches:
+      - zig-0.12.0
+    schedule:
+      - cron: "0 0 * * *"
+    workflow_dispatch:
 
 jobs:
   ci:
     strategy:
       matrix:
-        # platform: [ubuntu-latest, windows-latest, macos-latest]
-        platform: [ubuntu-latest]
+        platform: [ubuntu-latest, macos-latest]
     runs-on: ${{ matrix.platform }}
     steps:
       - uses: actions/checkout@v3
@@ -26,5 +25,46 @@ jobs:
         run: zig version
       - name: Build all examples
         run: zig build all
-      - name: Run all tests
-        run: zig build test
+      # Run tests separately so we can see more clearly which one fails
+      - name: Run mustache tests
+        run: zig build test-mustache
+      - name: Run httpparams tests
+        run: zig build test-httpparams
+      - name: Run sendfile tests
+        run: zig build test-sendfile
+      - name: Run authentication tests
+        run: zig build test-authentication
+      - name: Report end of tests
+        run: echo "tests finished"
+
+  update-readme:
+    runs-on: ubuntu-latest
+    permissions: 
+      id-token: write
+      contents: write
+
+    steps:
+      - uses: actions/checkout@v3
+      - uses: goto-bus-stop/setup-zig@v2
+        with:
+          version: master
+
+      - name: Build announceybot
+        run: zig build announceybot
+
+      - name: Run script to update README
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG_NAME: ${{ steps.tag.outputs.version }}
+        run: |
+          zig-out/bin/announceybot update-readme "zig-0.12.0"
+  
+      - name: Commit and push if it has changed
+        run: |
+          git diff
+          git checkout zig-0.12.0
+          git config --local user.email "[email protected]"
+          git config --local user.name "GitHub Action"
+          git commit -am "Update README"
+          git push origin zig-0.12.0
+>>>>>>> zig-0.12.0

.gitignore

@@ -11,7 +11,6 @@ wrk/csharp/obj/
 wrk/csharp/out/
 scratch
 **/.mypy_cache/*
-docs/
 .DS_Store
 .vs/
 **/*.perflog

README.md

@@ -1,5 +1,3 @@
-
-
 # ⚡zap⚡ - blazingly fast backends in zig
 
 ![](https://github.com/zigzap/zap/actions/workflows/build-zig-11.yml/badge.svg) ![](https://github.com/zigzap/zap/actions/workflows/mastercheck.yml/badge.svg) [![Discord](https://img.shields.io/discord/1107835896356675706?label=chat&logo=discord&style=plastic)](https://discord.gg/jQAAN6Ubyj)
@@ -26,17 +24,17 @@ that it proved to be:
 
 Exactly the goals I set out to achieve!
 
-
 ## Most FAQ:
 
-### Zap uses the latest stable zig release (0.11.0) for a reason. So you don't have to keep up with frequent breaking changes. It's an "LTS feature". If you want to use zig master, use the `zig-0.12.0` branch but be aware that I don't provide `build.zig.zon` snippets or tagged releases for it for the time being. If you know what you are doing, that shouldn't stop you from using it with zig master though.
+### Zap uses the latest stable zig release (0.1@.0) for a reason. So you don't have to keep up with frequent breaking changes. It's an "LTS feature". If you want to use zig master, use the `zig-0.13.0` branch (coming soon) but be aware that I don't provide `build.zig.zon` snippets or tagged releases for it for the time being. If you know what you are doing, that shouldn't stop you from using it with zig master though.
 
 - Q: **Where is the API documentation?**
-    - A: Docs are a work in progress. You can check them out [here](https://zigzap.org/zap). The docs are based on the `zig-0.12.0` branch but apply to the current release (zig 0.11.0), too.
+    - A: Docs are a work in progress. You can check them out [here](https://zigzap.org/zap).
+    - A: Run `zig build run-docserver` to serve them locally.
 - Q: **Zap doesn't build with Zig master?**
-    - A: See the 0.12.0 branch. An example of how to use it is
-      [here](https://github.com/zigzap/hello-0.12.0). Please note that the 0.12.0
-      branch is not the official master branch of ZAP. Yet. Until zig 0.12.0 is
+    - A: See the 0.13.0 branch (soon). An example of how to use it is
+      [here](https://github.com/zigzap/hello-0.13.0). Please note that the 0.13.0
+      branch is not the official master branch of ZAP. Yet. Until zig 0.13.0 is
       released.
 - Q: **Does ZAP work on Windows?**
     - A: No. This is due to the underlying facil.io C library. Future versions of
@@ -57,6 +55,10 @@ I recommend checking out **Endpoint-based examples for more realistic
 use cases**. Most of the examples are super stripped down to only include 
 what's necessary to show a feature.
 
+**NOTE: To see API docs, run `zig build run-docserver`.** To specify a custom
+port and docs dir: `zig build docserver && zig-out/bin/docserver --port=8989
+--docs=path/to/docs`.
+
 - **Super easy build process**: Zap's `build.zig` now uses the new Zig package
   manager for its C-dependencies, no git submodules anymore.
   - _tested on Linux and macOS (arm, M1)_
@@ -222,7 +224,7 @@ code leaks memory.
 
 ## Getting started
 
-Make sure you have **the latest zig release (0.11.0)** installed. Fetch it from
+Make sure you have zig 0.12.0 installed. Fetch it from
 [here](https://ziglang.org/download).
 
 ```shell
@@ -236,7 +238,7 @@ $ # open http://localhost:3000 in your browser
 
 ## Using ⚡zap⚡ in your own projects
 
-Make sure you have **the latest zig release (0.11.0)** installed. Fetch it from
+Make sure you have **the latest zig release (0.12.0)** installed. Fetch it from
 [here](https://ziglang.org/download).
 
 If you don't have an existing zig project, create one like this:
@@ -250,7 +252,7 @@ $ git init      ## (optional)
 `nix develop` to get a development shell providing zig and all
 dependencies to build and run the GO, python, and rust examples for the
 `wrk` performance tests. For the mere building of zap projects, 
-`nix develop .#build` will only fetch zig 0.11.0.
+`nix develop .#build` will only fetch zig 0.11.0. TODO: upgrade to zig 0.12.
 
 With an existing Zig project, adding Zap to it is easy:
 
@@ -268,9 +270,14 @@ To add zap to `build.zig.zon`:
     .dependencies = .{
         // zap v0.6.0
         .zap = .{
-            .url = "https://github.com/zigzap/zap/archive/refs/tags/v0.6.0.tar.gz",
-            .hash = "1220a5a1e6b18fa384d8a98e5d5a25720ddadbcfed01da2e4ca55c7cfb3dc1caa62a",
-        }
+            // when tagged:
+            // .url = "https://github.com/zigzap/zap/archive/refs/tags/zig-0.12.0.tar.gz",
+            .url = "https://github.com/zigzap/zap/archive/zig-0.12.0.tar.gz",
+            .hash = "122002bc4a3fb6d4c465ce9f7f0af06e9ffbe38a6ed8c7375a2121d05eee294af893",
+        },
+        .paths = .{
+            "",
+        },
     }
 }
 ```
@@ -285,7 +292,8 @@ Then, in your `build.zig`'s `build` function, add the following before
         .optimize = optimize,
         .openssl = false, // set to true to enable TLS support
     });
-    exe.addModule("zap", zap.module("zap"));
+
+    exe.root_module.addImport("zap", zap.module("zap"));
     exe.linkLibrary(zap.artifact("facil.io"));
 ```
 
@@ -404,28 +412,3 @@ pub fn main() !void {
     });
 }
 ```
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-

build.zig

@@ -1,36 +1,51 @@
 const std = @import("std");
 const build_facilio = @import("facil.io/build.zig").build_facilio;
 
-pub fn build(b: *std.build.Builder) !void {
+pub fn build(b: *std.Build) !void {
     const target = b.standardTargetOptions(.{});
-    if (target.getOsTag() == .windows) {
+    if (target.result.os.tag == .windows) {
         std.log.err("\x1b[31mPlatform Not Supported\x1b[0m\nCurrently, Facil.io and Zap are not compatible with Windows. Consider using Linux or Windows Subsystem for Linux (WSL) instead.\nFor more information, please see:\n- https://github.com/zigzap/zap#most-faq\n- https://facil.io/#forking-contributing-and-all-that-jazz\n", .{});
-        std.os.exit(1);
+        std.process.exit(1);
     }
     // Standard release options allow the person running `zig build` to select
     // between Debug, ReleaseSafe, ReleaseFast, and ReleaseSmall.
     const optimize = b.standardOptimizeOption(.{});
 
     const use_openssl = b.option(bool, "openssl", "Use system-installed openssl for TLS support in zap") orelse blk: {
         // Alternatively, use an os env var to determine whether to build openssl support
-        if (std.os.getenv("ZAP_USE_OPENSSL")) |val| {
+        if (std.posix.getenv("ZAP_USE_OPENSSL")) |val| {
             if (std.mem.eql(u8, val, "true")) break :blk true;
         }
         break :blk false;
     };
 
     // create a module to be used internally.
-    var zap_module = b.createModule(.{
-        .source_file = .{ .path = "src/zap.zig" },
+    const zap_module = b.addModule("zap", .{
+        .root_source_file = .{ .path = "src/zap.zig" },
     });
 
     // register the module so it can be referenced using the package manager.
-    try b.modules.put(b.dupe("zap"), zap_module);
+    // try b.modules.put(b.dupe("zap"), zap_module);
 
     const facilio = try build_facilio("facil.io", b, target, optimize, use_openssl);
 
     const all_step = b.step("all", "build all examples");
 
+    // -- Docs
+    const docs_obj = b.addObject(.{
+        .name = "zap", // name doesn't seem to matter
+        .root_source_file = .{ .path = "src/zap.zig" },
+        .target = target,
+        .optimize = .Debug,
+    });
+    const install_docs = b.addInstallDirectory(.{
+        .install_dir = .prefix,
+        .install_subdir = "zap", // will also be the main namespace in the docs
+        .source_dir = docs_obj.getEmittedDocs(),
+    });
+    b.step("docs", "Build docs").dependOn(&install_docs.step);
+    // --
+
     inline for ([_]struct {
         name: []const u8,
         src: []const u8,
@@ -85,8 +100,8 @@ pub fn build(b: *std.build.Builder) !void {
             .optimize = optimize,
         });
 
+        example.root_module.addImport("zap", zap_module);
         example.linkLibrary(facilio);
-        example.addModule("zap", zap_module);
 
         // const example_run = example.run();
         const example_run = b.addRunArtifact(example);
@@ -125,7 +140,7 @@ pub fn build(b: *std.build.Builder) !void {
         .optimize = optimize,
     });
     auth_tests.linkLibrary(facilio);
-    auth_tests.addModule("zap", zap_module);
+    auth_tests.root_module.addImport("zap", zap_module);
 
     const run_auth_tests = b.addRunArtifact(auth_tests);
     const install_auth_tests = b.addInstallArtifact(auth_tests, .{});
@@ -138,7 +153,7 @@ pub fn build(b: *std.build.Builder) !void {
         .optimize = optimize,
     });
     mustache_tests.linkLibrary(facilio);
-    mustache_tests.addModule("zap", zap_module);
+    mustache_tests.root_module.addImport("zap", zap_module);
 
     const run_mustache_tests = b.addRunArtifact(mustache_tests);
     const install_mustache_tests = b.addInstallArtifact(mustache_tests, .{});
@@ -152,7 +167,8 @@ pub fn build(b: *std.build.Builder) !void {
     });
 
     httpparams_tests.linkLibrary(facilio);
-    httpparams_tests.addModule("zap", zap_module);
+    httpparams_tests.root_module.addImport("zap", zap_module);
+
     const run_httpparams_tests = b.addRunArtifact(httpparams_tests);
     // TODO: for some reason, tests aren't run more than once unless
     //       dependencies have changed.
@@ -169,7 +185,7 @@ pub fn build(b: *std.build.Builder) !void {
     });
 
     sendfile_tests.linkLibrary(facilio);
-    sendfile_tests.addModule("zap", zap_module);
+    sendfile_tests.root_module.addImport("zap", zap_module);
     const run_sendfile_tests = b.addRunArtifact(sendfile_tests);
     const install_sendfile_tests = b.addInstallArtifact(sendfile_tests, .{});
 
@@ -202,7 +218,7 @@ pub fn build(b: *std.build.Builder) !void {
     //
     // pkghash
     //
-    var pkghash_exe = b.addExecutable(.{
+    const pkghash_exe = b.addExecutable(.{
         .name = "pkghash",
         .root_source_file = .{ .path = "./tools/pkghash.zig" },
         .target = target,
@@ -213,10 +229,33 @@ pub fn build(b: *std.build.Builder) !void {
     pkghash_step.dependOn(&pkghash_build_step.step);
     all_step.dependOn(&pkghash_build_step.step);
 
+    //
+    // docserver
+    //
+    const docserver_exe = b.addExecutable(.{
+        .name = "docserver",
+        .root_source_file = .{ .path = "./tools/docserver.zig" },
+        .target = target,
+        .optimize = optimize,
+    });
+    docserver_exe.linkLibrary(facilio);
+    docserver_exe.root_module.addImport("zap", zap_module);
+    var docserver_step = b.step("docserver", "Build docserver");
+    const docserver_build_step = b.addInstallArtifact(docserver_exe, .{});
+    docserver_step.dependOn(&docserver_build_step.step);
+    docserver_step.dependOn(&install_docs.step);
+
+    const docserver_run_step = b.step("run-docserver", "run the docserver");
+    const docserver_run = b.addRunArtifact(docserver_exe);
+    docserver_run_step.dependOn(&docserver_run.step);
+    docserver_run_step.dependOn(docserver_step);
+
+    all_step.dependOn(&docserver_build_step.step);
+
     //
     // announceybot
     //
-    var announceybot_exe = b.addExecutable(.{
+    const announceybot_exe = b.addExecutable(.{
         .name = "announceybot",
         .root_source_file = .{ .path = "./tools/announceybot.zig" },
         .target = target,

build.zig.zon

@@ -1 +1,10 @@
-.{ .name = "zap", .version = "0.6.0" }
+.{
+    .name = "zap",
+    .version = "0.7.0",
+    .paths = .{
+        "build.zig",
+        "build.zig.zon",
+        "src",
+        "facil.io",
+    },
+}

doc/release-template.md

@@ -22,7 +22,10 @@ Here is a complete `build.zig.zon` example:
         .zap = .{
             .url = "https://github.com/zigzap/zap/archive/refs/tags/{tag}.tar.gz",
             .hash = "{hash}",
-        }
+        },
+        .paths = .{
+            "",
+        },
     }
 }
 
@@ -35,7 +38,8 @@ Then, in your `build.zig`'s `build` function, add the following before
     const zap = b.dependency("zap", .{
         .target = target,
         .optimize = optimize,
+        .openssl = false, // set to true to enable TLS support
     });
-    exe.addModule("zap", zap.module("zap"));
+    exe.root_module.addImport("zap", zap.module("zap"));
     exe.linkLibrary(zap.artifact("facil.io"));
 ```