@thi.ng/wasm-api 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-28T13:36:49Z
+- **Last updated**: 2022-12-01T18:02:30Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,12 @@ 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.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.2.0) (2022-12-01)
+
+#### 🚀 Features
+
+- add build script for user projects ([7164f5e](https://github.com/thi-ng/umbrella/commit/7164f5e))
+
 ## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/wasm-api@1.1.0) (2022-11-28)
 
 #### 🚀 Features

package/README.md

@@ -11,11 +11,12 @@ This project is part of the
 
 - [About](#about)
 - [Custom API modules](#custom-api-modules)
-  - [Building Zig projects with these hybrid API modules](#building-zig-projects-with-these-hybrid-api-modules)
 - [String handling](#string-handling)
 - [Memory allocations](#memory-allocations)
   - [API module auto-initialization](#api-module-auto-initialization)
 - [Object indices & handles](#object-indices--handles)
+- [Using the Zig build system](#using-the-zig-build-system)
+- [Naming & structural conventions](#naming--structural-conventions)
 - [Status](#status)
 - [Support packages](#support-packages)
 - [Installation](#installation)
@@ -55,13 +56,15 @@ WebGL, WebGPU, WebAudio etc. is being actively worked on.
    defining glue code for the TypeScript [core
    API](https://docs.thi.ng/umbrella/wasm-api/interfaces/CoreAPI.html) defined
    by this package
-7. Extensible shared [datatype code generator
+7. [Zig build files]() to simplify using hybrid TS/Zig packages with the
+   built-in build system
+8. Extensible shared [datatype code generator
    infrastructure](https://github.com/thi-ng/umbrella/tree/develop/packages/wasm-api-bindgen/)
    for (currently) Zig & TypeScript and C11. For TS fully type checked and
 memory-mapped (zero-copy) accessors of WASM-side data are generated. In
 principle, all languages with a WASM target are supported, however currently
 only bindings for these mentioned langs are included.
-8. [CLI
+9. [CLI
    frontend/utility](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-bindgen/README.md#cli-generator)
    for the code generator(s)
 
@@ -148,7 +151,7 @@ Main Zig file:
 
 ```zig
 // Import JS core API
-const js = @import("wasmapi");
+const js = @import("wasm-api");
 const custom = @import("custom.zig");
 
 export fn test_randomVec4() void {
@@ -165,19 +168,6 @@ export fn test_randomVec4() void {
 }
 ```
 
-### Building Zig projects with these hybrid API modules
-
-Some example projects (see [list below](#usage-examples)) provide custom
-[`build.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/build.zig)
-&
-[`npm.zig`](https://github.com/thi-ng/umbrella/blob/develop/examples/zig-canvas/npm.zig)
-build scripts to easily integrate these hybrid TS/Zig packages into users'
-development processes.
-
-To avoid guesswork about the internals of these API modules, all of them are
-using an overall uniform structure, with the main Zig entry point in
-`/zig/lib.zig`...
-
 ## String handling
 
 Most low-level languages deal with strings very differently and alas there's no
@@ -313,6 +303,38 @@ in the
 [@thi.ng/wasm-api-schedule](https://github.com/thi-ng/umbrella/blob/develop/packages/wasm-api-schedule/)
 packages this is used to manage Zig-side event listeners.
 
+## Using the Zig build system
+
+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
+const std = @import("std");
+
+pub fn build(b: *std.build.Builder) void {
+    @import("node_modules/@thi.ng/wasm-api/zig/build.zig").wasmLib(b, .{
+        // Declare extra WASM API packages to use
+		// Each package can also declare its dependencies
+        .packages = &.{
+            .{ .id = "wasm-api-dom", .path = "@thi.ng/wasm-api-dom/zig/lib.zig" },
+            .{ .id = "wasm-api-schedule", .path = "@thi.ng/wasm-api-schedule/zig/lib.zig" },
+        },
+        // (optional) build mode override
+        .mode = .ReleaseSmall,
+    }).install();
+}
+```
+
+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)
+
+## Naming & structural conventions
+
+To avoid guesswork about the internals of any of the supplied WASM API modules,
+please also consult the information in
+[#368](https://github.com/thi-ng/umbrella/issues/368).
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -348,7 +370,7 @@ node --experimental-repl-await
 > const wasmApi = await import("@thi.ng/wasm-api");
 ```
 
-Package sizes (gzipped, pre-treeshake): ESM: 2.73 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.47 KB
 
 ## Dependencies
 
@@ -371,6 +393,7 @@ A selection:
 | Screenshot                                                                                                           | Description                                                        | Live demo                                           | Source                                                                           |
 |:---------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------|:----------------------------------------------------|:---------------------------------------------------------------------------------|
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-canvas.png" width="240"/>    | Zig-based DOM creation & canvas drawing app                        | [Demo](https://demo.thi.ng/umbrella/zig-canvas/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-canvas)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-cellular.jpg" width="240"/>  | Zig-based 2D multi-behavior cellular automata                      | [Demo](https://demo.thi.ng/umbrella/zig-cellular/)  | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-cellular)  |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-counter.png" width="240"/>   | Simple Zig/WASM click counter DOM component                        | [Demo](https://demo.thi.ng/umbrella/zig-counter/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-counter)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/zig-todo-list.png" width="240"/> | Zig-based To-Do list, DOM creation, local storage task persistence | [Demo](https://demo.thi.ng/umbrella/zig-todo-list/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/zig-todo-list) |
 
@@ -413,7 +436,7 @@ Requires [Zig](https://ziglang.org) to be installed:
 
 /// import externals
 /// see build command for configuration
-const js = @import("wasmapi");
+const js = @import("wasm-api");
 
 export fn start() void {
     js.printStr("hello world!");
@@ -427,7 +450,7 @@ folder):
 ```bash
 # compile WASM binary
 zig build-lib \
-    --pkg-begin wasmapi node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
+    --pkg-begin wasm-api node_modules/@thi.ng/wasm-api/zig/lib.zig --pkg-end \
     -target wasm32-freestanding \
     -O ReleaseSmall -dynamic \
     hello.zig

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -35,17 +35,17 @@
     "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.5.0",
-    "@thi.ng/arrays": "^2.4.3",
-    "@thi.ng/checks": "^3.3.3",
-    "@thi.ng/errors": "^2.2.4",
-    "@thi.ng/hex": "^2.3.0",
-    "@thi.ng/idgen": "^2.1.19",
-    "@thi.ng/logger": "^1.4.3"
+    "@thi.ng/api": "^8.5.1",
+    "@thi.ng/arrays": "^2.4.4",
+    "@thi.ng/checks": "^3.3.4",
+    "@thi.ng/errors": "^2.2.5",
+    "@thi.ng/hex": "^2.3.1",
+    "@thi.ng/idgen": "^2.1.20",
+    "@thi.ng/logger": "^1.4.4"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.5",
-    "@thi.ng/testament": "^0.3.5",
+    "@thi.ng/testament": "^0.3.6",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.20",
@@ -110,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "75ec32ff7f1b7b5e72e7a04ace24732cd5d6c774\n"
+  "gitHead": "199dcde33bf3d0b0bbd205d3b870dff43b735b22\n"
 }

package/zig/build.zig

@@ -0,0 +1,135 @@
+const std = @import("std");
+
+/// Definition for a (usually hybrid) Zig package which will be distributed via NPM
+pub const Pkg = struct {
+    /// Package ID used for @import
+    id: []const u8,
+    /// Package sub path (appended to base path)
+    path: []const u8,
+    /// Package dependencies aka other package IDs.
+    /// All of them must already have been registered
+    deps: ?[]const []const u8 = null,
+};
+
+pub const PkgOpts = struct {
+    /// Base path to common node_modules directory under which
+    /// all to be imported packages are located
+    base: []const u8 = "node_modules",
+    /// Additional WASM API support packages.
+    /// We don't need to specify core wasmapi, only custom/extra ones
+    /// `wasm-api` and `wasm-api-bindgen` are also auto-added
+    /// as dependency for each of these...
+    packages: ?[]const Pkg = null,
+};
+
+/// Dependency graph for WASM API packages
+/// Expands & resolves the more compact/convenient/human friendly format of PkgOpts
+/// into the data structures used by Zig's build system
+/// Provides a `addAllTo()` function to add all declared packages to a build step
+pub const PkgGraph = struct {
+    arena: std.heap.ArenaAllocator,
+    basePath: []const u8,
+    packages: std.StringArrayHashMap(std.build.Pkg),
+
+    const Self = @This();
+
+    pub fn init(opts: PkgOpts) Self {
+        var arena = std.heap.ArenaAllocator.init(std.heap.page_allocator);
+        var self = Self{
+            .arena = arena,
+            .basePath = opts.base,
+            .packages = std.StringArrayHashMap(std.build.Pkg).init(arena.allocator()),
+        };
+        const api = "wasm-api";
+        self.packages.put(api, .{
+            .name = api,
+            .source = .{ .path = self.modulePath("@thi.ng/wasm-api/zig/lib.zig") },
+        }) catch unreachable;
+        const apiTypes = "wasm-api-bindgen";
+        self.packages.put(apiTypes, .{
+            .name = apiTypes,
+            .source = .{ .path = self.modulePath("@thi.ng/wasm-api-bindgen/zig/lib.zig") },
+        }) catch unreachable;
+        if (opts.packages) |pkgs| {
+            for (pkgs) |pkg| {
+                self.register(pkg.id, pkg.path, pkg.deps);
+            }
+        }
+        return self;
+    }
+
+    pub fn deinit(self: *const Self) void {
+        self.arena.deinit();
+    }
+
+    /// Registers a single package and its deps (also injects core wasm-api deps)
+    pub fn register(
+        self: *Self,
+        name: []const u8,
+        path: []const u8,
+        dependencies: ?[]const []const u8,
+    ) void {
+        var pkg = std.build.Pkg{
+            .name = name,
+            .source = .{ .path = self.modulePath(path) },
+        };
+        const num = if (dependencies) |deps| deps.len else 0;
+        var dpkgs = self.arena.allocator().alloc(std.build.Pkg, num + 2) catch unreachable;
+        dpkgs[0] = if (self.packages.get("wasm-api")) |p| p else unreachable;
+        dpkgs[1] = if (self.packages.get("wasm-api-bindgen")) |p| p else unreachable;
+        if (dependencies) |deps| {
+            var i: usize = 0;
+            while (i < deps.len) : (i += 1) {
+                if (self.packages.get(deps[i])) |p| {
+                    dpkgs[i + 1] = p;
+                } else @panic("unknown dependency");
+            }
+        }
+        pkg.dependencies = dpkgs;
+        self.packages.put(name, pkg) catch unreachable;
+    }
+
+    /// Adds all registered packages to the given build step
+    pub fn addAllTo(self: *const Self, step: *std.build.LibExeObjStep) void {
+        for (self.packages.values()) |pkg| step.addPackage(pkg);
+    }
+
+    fn modulePath(self: *Self, path: []const u8) []const u8 {
+        return std.fs.path.join(self.arena.allocator(), &.{ self.basePath, path }) catch unreachable;
+    }
+};
+
+/// Config options
+pub const WasmLibOpts = struct {
+    /// Relative path to base directory for WASM API packages
+    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",
+    /// Package definitions for additional WASM API modules
+    packages: ?[]const Pkg = null,
+    /// Build mode override (else allows config via CLI args)
+    mode: ?std.builtin.Mode = null,
+    /// Additional WASM target features, e.g. `.simd128` to enable SIMD
+    features: ?[]const std.Target.wasm.Feature = null,
+};
+
+/// 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: *std.build.Builder, opts: WasmLibOpts) *std.build.LibExeObjStep {
+    const lib = b.addSharedLibrary("main", opts.root, .unversioned);
+    lib.setTarget(.{
+        .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,
+    });
+    const mode = if (opts.mode) |m| m else b.standardReleaseOptions();
+    lib.setBuildMode(mode);
+    if (mode == .ReleaseSmall or mode == .ReleaseFast) lib.strip = true;
+    const pkgs = PkgGraph.init(.{ .base = opts.base, .packages = opts.packages });
+    defer pkgs.deinit();
+    pkgs.addAllTo(lib);
+    lib.setOutputDir(opts.out);
+    return lib;
+}