@thi.ng/wasm-api 1.3.2 → 1.4.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-02-10T14:03:11Z
+- **Last updated**: 2023-03-02T18:09:03Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,19 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [1.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.4.0) (2023-02-17)
+
+#### 🚀 Features
+
+- add build script for Zig v0.11.0-dev ([4c8abcb](https://github.com/thi-ng/umbrella/commit/4c8abcb))
+
+#### ♻️ Refactoring
+
+- update build-v0.11.zig build script ([fe7c24c](https://github.com/thi-ng/umbrella/commit/fe7c24c))
+  - single source of truth for core module names
+  - rename .mode => .optimize (as per new zig nomenclature)
+  - add autodoc generation option
+
 ## [1.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.3.0) (2023-02-05)
 
 #### 🚀 Features

package/README.md

@@ -16,6 +16,9 @@ This project is part of the
   - [API module auto-initialization](#api-module-auto-initialization)
 - [Object indices & handles](#object-indices--handles)
 - [Using the Zig build system](#using-the-zig-build-system)
+  - [Zig v0.10.1 or older](#zig-v0101-or-older)
+  - [Zig v0.11.0-dev or newer](#zig-v0110-dev-or-newer)
+  - [Example projects](#example-projects)
 - [Naming & structural conventions](#naming--structural-conventions)
 - [Status](#status)
 - [Support packages](#support-packages)
@@ -309,6 +312,8 @@ This package provides utilities to simplify using hybrid TS/Zig WASM API modules
 which are distributed as NPM packages. Using these utils, a build file for Zig's
 built-in build system is as simple as:
 
+### Zig v0.10.1 or older
+
 ```zig
 const std = @import("std");
 
@@ -335,10 +340,45 @@ pub fn build(b: *std.build.Builder) void {
 }
 ```
 
+### Zig v0.11.0-dev or newer
+
+(Note: Several new build options have been added, e.g. initial/max memory
+config, autodoc generation)
+
+```zig
+const std = @import("std");
+
+pub fn build(b: *std.Build) void {
+    // obtain a standard std.Build.CompileStep, pre-configured w/ given options
+    // see source comments in imported build-v0.11.zig for further details...
+    var lib = @import("node_modules/@thi.ng/wasm-api/zig/build-v0.11.zig").wasmLib(b, .{
+        // Declare extra WASM API modules to use
+        // Each can also declare dependencies to other modules
+        // (`wasm-api` and `wasm-api-bindgen` are made available everywhere)
+        .modules = &.{
+            .{ .name = "wasm-api-dom", .path = "@thi.ng/wasm-api-dom/zig/lib.zig" },
+            .{ .name = "wasm-api-schedule", .path = "@thi.ng/wasm-api-schedule/zig/lib.zig" },
+        },
+        // (optional) optimization mode override
+        // if commented out, we can pass CLI args to choose mode (default: .Debug)
+        .optimize = .ReleaseSmall,
+    });
+    // optionally, add further custom configuration
+    // ...
+
+    // finally trigger build
+    lib.install();
+}
+```
+
+### Example projects
+
 All bundled example projects (see [list below](#usage-examples)) are being built
 via this script. **Please find more details/options in the commented source
 code:**
-[`/zig/build.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/build.zig)
+
+- [`/zig/build.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/build.zig)
+- [`/zig/build-v0.11.zig`](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api/zig/build-v0.11.zig)
 
 ## Naming & structural conventions
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.3.2",
+  "version": "1.4.1",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -35,12 +35,12 @@
     "test:build-zig": "zig build-lib -O ReleaseSmall -target wasm32-freestanding -dynamic --strip --pkg-begin wasmapi zig/lib.zig --pkg-end test/custom.zig && wasm-dis -o custom.wast custom.wasm && cp custom.wasm test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.2",
-    "@thi.ng/arrays": "^2.5.4",
+    "@thi.ng/api": "^8.7.3",
+    "@thi.ng/arrays": "^2.5.6",
     "@thi.ng/checks": "^3.3.9",
-    "@thi.ng/errors": "^2.2.11",
+    "@thi.ng/errors": "^2.2.12",
     "@thi.ng/hex": "^2.3.6",
-    "@thi.ng/idgen": "^2.1.27",
+    "@thi.ng/idgen": "^2.1.28",
     "@thi.ng/logger": "^1.4.9"
   },
   "devDependencies": {
@@ -115,5 +115,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "cafa4ecea90fb681949dc3885a5bd6ddefa38b51\n"
+  "gitHead": "a2915dee637c1b8cd2e11a78a23bd035e4f750e7\n"
 }

package/zig/build-v0.11.zig

@@ -0,0 +1,128 @@
+//! Build helpers for using modules/packages distributed via NPM
+//! Intended for use with https://thi.ng/wasm-api and support packages
+//!
+//! This version of the script is only compatible with:
+//! Zig v0.11.0-dev.1622+fc48467a9 or newer
+//!
+//! Use build.zig (in this same directory) for earlier Zig versions
+
+const std = @import("std");
+const Build = std.Build;
+
+/// Config options
+pub const WasmLibOpts = struct {
+    /// Base path to common node_modules directory under which
+    /// all to be imported modules are located
+    base: []const u8 = "node_modules",
+    /// Relative path to root source file
+    root: []const u8 = "zig/main.zig",
+    /// Relative path to output directory
+    out: []const u8 = "src",
+    /// Additional WASM API support modules.
+    /// Only need to specify custom/extra modules
+    /// `wasm-api` and `wasm-api-bindgen` are auto-added as dependency for all...
+    modules: ?[]const ModuleSpec = null,
+    /// Build mode override (else allows config via CLI args)
+    optimize: ?std.builtin.Mode = null,
+    /// Additional WASM target features, e.g. `.simd128` to enable SIMD
+    features: ?[]const std.Target.wasm.Feature = null,
+    /// Initial memory (in bytes, MUST be multiple of 0x10000)
+    initialMemory: ?u64 = null,
+    /// Max memory (in bytes, MUST be multiple of 0x10000)
+    maxMemory: ?u64 = null,
+    /// If true, build will also generate docs
+    docs: bool = false,
+};
+
+/// WASM API sub-module declaration
+pub const ModuleSpec = struct {
+    /// module import name/ID
+    name: []const u8,
+    /// Relative path to configured base path
+    path: []const u8,
+    /// Module IDs of other modules this module depends on
+    /// Only need to specify custom/extra modules
+    /// `wasm-api` and `wasm-api-bindgen` are auto-added as dependency for all...
+    dependencies: ?[]const []const u8 = null,
+};
+
+const wasmapi = "wasm-api";
+const wasmbind = "wasm-api-bindgen";
+
+/// Creates and returns a build step to build a dynamic WASM library, configured
+/// with given options and package declarations. The given package specs will be inserted
+pub fn wasmLib(b: *Build, opts: WasmLibOpts) *Build.CompileStep {
+    const lib = b.addSharedLibrary(.{
+        .name = "main",
+        .root_source_file = .{ .path = opts.root },
+        .target = .{
+            .cpu_arch = .wasm32,
+            .os_tag = .freestanding,
+            .cpu_features_add = if (opts.features) |features| std.Target.wasm.featureSet(features) else std.Target.Cpu.Feature.Set.empty,
+        },
+        .optimize = if (opts.optimize) |m| m else b.standardOptimizeOption(.{}),
+    });
+    if (lib.optimize == .ReleaseSmall or lib.optimize == .ReleaseFast) lib.strip = true;
+    lib.setOutputDir(opts.out);
+    // build flags
+    lib.rdynamic = true;
+    lib.import_symbols = true;
+    lib.initial_memory = opts.initialMemory;
+    lib.max_memory = opts.maxMemory;
+    if (opts.docs) lib.emit_docs = .emit;
+    // add default dependencies
+    lib.addModule(
+        wasmapi,
+        b.createModule(.{
+            .source_file = modulePath(b.allocator, opts.base, "@thi.ng/wasm-api/zig/lib.zig"),
+        }),
+    );
+    lib.addModule(
+        wasmbind,
+        b.createModule(.{
+            .source_file = modulePath(b.allocator, opts.base, "@thi.ng/wasm-api-bindgen/zig/lib.zig"),
+        }),
+    );
+    if (opts.modules) |modules| {
+        for (modules) |mod| {
+            register(lib, mod, opts);
+        }
+    }
+    return lib;
+}
+
+/// Registers a single package and its deps (also injects core wasm-api deps)
+pub fn register(step: *Build.CompileStep, mod: ModuleSpec, opts: WasmLibOpts) void {
+    const num = if (mod.dependencies) |ids| ids.len else 0;
+    var dpkgs = step.builder.allocator.alloc(Build.ModuleDependency, num + 2) catch unreachable;
+    dpkgs[0] = if (step.modules.get(wasmapi)) |m| .{ .name = wasmapi, .module = m } else unreachable;
+    dpkgs[1] = if (step.modules.get(wasmbind)) |m| .{ .name = wasmbind, .module = m } else unreachable;
+    var i: usize = 2;
+    if (mod.dependencies) |ids| {
+        for (ids) |id| {
+            if (step.modules.get(id)) |m| {
+                if (isDuplicateId(dpkgs[0..i], id)) {
+                    std.log.info("ignoring duplicate dependency: {s}", .{id});
+                    continue;
+                }
+                dpkgs[i] = .{ .name = id, .module = m };
+                i += 1;
+            } else @panic("unknown dependency");
+        }
+    }
+    step.addModule(mod.name, step.builder.createModule(.{
+        .source_file = modulePath(step.builder.allocator, opts.base, mod.path),
+        .dependencies = dpkgs[0..i],
+    }));
+}
+
+fn isDuplicateId(deps: []Build.ModuleDependency, name: []const u8) bool {
+    for (deps) |d| {
+        if (std.mem.eql(u8, d.name, name)) return true;
+    }
+    return false;
+}
+
+fn modulePath(allocator: std.mem.Allocator, base: []const u8, path: []const u8) Build.FileSource {
+    return .{ .path = std.fs.path.join(allocator, &.{ base, path }) catch unreachable };
+}

package/zig/build.zig

@@ -1,3 +1,9 @@
+//! Build helpers for using modules/packages distributed via NPM
+//! Intended for use with https://thi.ng/wasm-api and support packages
+//!
+//! This version of the script is only compatible with Zig v0.10.1 or older
+//! Use build-v0.11.zig (in this same directory) for newer Zig versions
+
 const std = @import("std");
 
 /// Definition for a (usually hybrid) Zig package which will be distributed via NPM