@thi.ng/wasm-api 1.1.1 → 1.2.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-11-30T22:27:37Z
+- **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)
 
@@ -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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/wasm-api",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Generic, modular, extensible API bridge and infrastructure for hybrid JS & WebAssembly projects",
   "type": "module",
   "module": "./index.js",
@@ -110,5 +110,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "1fe40da507070653f420156d91e6b27cf682004f\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;
+}