Add wasm32 example

Author: nickpdemarco

Cargo.lock

@@ -10,6 +10,10 @@ members = [
     "xtask",
     "benchmark",
 ]
+# Exclude tutorial-wasm32 from default workspace builds since it requires extra dependencies
+exclude = [
+    "examples/tutorial-wasm32",
+]
 resolver = "2"
 
 [workspace.package]

Cargo.toml

@@ -0,0 +1,18 @@
+generated.h
+generated.rs
+generated.cpp
+generated.o
+main.js
+main.wasm
+target/
+a.out
+example_tutorial_wasm32.wasm
+
+# WASI SDK and dependencies
+wasi-sdk-*
+wasi-sdk-latest.tar.gz
+wasi-sdk-installed
+wasm32-wasip1-target
+
+# Build artifacts
+actual_output.txt

examples/tutorial-wasm32/.gitignore

@@ -0,0 +1,14 @@
+[package]
+name = "example-tutorial-wasm32"
+version = "0.6.0"
+edition = "2024"
+rust-version = "1.85"
+license = "MIT OR Apache-2.0"
+publish = false
+
+[lib]
+crate-type = ["staticlib"]
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]

examples/tutorial-wasm32/Cargo.lock

@@ -0,0 +1,88 @@
+# Detect platform for WASI SDK
+UNAME_S := $(shell uname -s)
+ifeq ($(UNAME_S),Linux)
+    WASI_SDK_PLATFORM = x86_64-linux
+else ifeq ($(UNAME_S),Darwin)
+    WASI_SDK_PLATFORM = x86_64-macos
+else
+    $(error Unsupported platform: $(UNAME_S))
+endif
+
+# WASI SDK paths and URLs
+WASI_SDK_VERSION = 25.0
+WASI_SDK_DIR = wasi-sdk-$(WASI_SDK_VERSION)-$(WASI_SDK_PLATFORM)
+WASI_SDK_PATH = $(shell pwd)/$(WASI_SDK_DIR)
+WASI_SDK_URL = $(or $(WASI_SDK_DOWNLOAD_URL),https://github.com/WebAssembly/wasi-sdk/releases/download/wasi-sdk-25/$(WASI_SDK_DIR).tar.gz)
+
+# WASI build flags for C++ compilation with wasmtime
+WASIFLAGS = -std=c++14 \
+           --target=wasm32-wasi \
+           --sysroot=$(WASI_SDK_PATH)/share/wasi-sysroot \
+           -D_WASI_EMULATED_SIGNAL \
+           -lwasi-emulated-signal \
+           -fno-exceptions
+
+# Use the WASI SDK C++ compiler
+CXX = $(WASI_SDK_PATH)/bin/clang++
+
+# Detect wasmtime location (system PATH or home directory)
+WASMTIME := $(shell which wasmtime 2>/dev/null || echo "$$HOME/.wasmtime/bin/wasmtime")
+
+# Default target
+all: run a.out
+
+# Run the example with wasmtime (installs all deps automatically)
+run: main.wasm
+	$(WASMTIME) run --allow-precompiled main.wasm
+
+# CI expects a.out; we create it as a bash script that simply execs wasmtime
+a.out: main.wasm
+	@printf '%s\n' '#!/usr/bin/env bash' 'exec $(WASMTIME) run --allow-precompiled "$$(dirname "$$0")/main.wasm" "$$@"' > $@
+	@chmod +x $@
+
+main.wasm: wasi-sdk-installed main.cpp generated.h generated.cpp \
+           target/wasm32-wasip1/release/libexample_tutorial_wasm32.a
+	$(CXX) $(WASIFLAGS) \
+	    main.cpp generated.cpp \
+	    target/wasm32-wasip1/release/libexample_tutorial_wasm32.a \
+	    -o $@
+
+target/wasm32-wasip1/release/libexample_tutorial_wasm32.a: wasm32-wasip1-target generated.h ./src/generated.rs ./src/lib.rs
+	cargo build --target=wasm32-wasip1 --release
+
+generated.h ./src/generated.rs generated.cpp: main32.zng
+	cargo run --release --manifest-path ../../zngur-cli/Cargo.toml g main32.zng
+
+# Install wasmtime and WASI SDK automatically
+wasi-sdk-installed:
+	@echo "Checking dependencies..."
+	@if ! command -v wasmtime >/dev/null 2>&1 && [ ! -f "$$HOME/.wasmtime/bin/wasmtime" ]; then \
+		echo "Installing wasmtime..."; \
+		curl https://wasmtime.dev/install.sh -sSf | bash; \
+	fi
+	@if [ ! -d "$(WASI_SDK_DIR)" ]; then \
+		echo "Installing WASI SDK for $(WASI_SDK_PLATFORM)..."; \
+		curl -L -o wasi-sdk-latest.tar.gz "$(WASI_SDK_URL)" && \
+		tar -xzf wasi-sdk-latest.tar.gz; \
+	fi
+	@touch wasi-sdk-installed
+
+# Ensure wasm32-wasip1 target is installed
+wasm32-wasip1-target:
+	@rustup target list --installed | grep -q wasm32-wasip1 || { \
+		echo "Installing wasm32-wasip1 Rust target..."; \
+		rustup target add wasm32-wasip1; \
+	}
+	@touch wasm32-wasip1-target
+
+clean:
+	cargo clean
+	rm -f generated.h ./src/generated.rs generated.cpp generated.o
+	rm -f main.wasm example_tutorial_wasm32.wasm a.out wasi-sdk-latest.tar.gz
+	rm -f wasi-sdk-installed wasm32-wasip1-target
+	rm -rf wasi-sdk-*
+
+# Legacy target for manual dependency installation (now automatic)
+install-deps: wasi-sdk-installed wasm32-wasip1-target
+
+FORCE: ;

examples/tutorial-wasm32/Cargo.toml

@@ -0,0 +1,20 @@
+# Wasm32 Example
+
+This example builds a sample application for wasmtime to test zngur's support for basic WASM applications.
+
+## To build and run
+
+```
+$ make run
+```
+
+This automatically installs all dependencies (wasmtime, WASI SDK, Rust targets) and runs the example.
+
+## Alternative targets
+
+```
+$ make            # Same as 'make run'
+$ make main.wasm  # Build without running
+$ make a.out      # Create executable wrapper script
+$ make clean      # Clean all build artifacts
+```

examples/tutorial-wasm32/Makefile

@@ -0,0 +1,14 @@
+17
+s[2] = 7
+Rust panic would happen if we accessed invalid index, but we avoid it
+hello 2 2
+hello 5 7
+hello 7 14
+hello 3 17
+34 17
+vector iterator has been destructed
+[main.cpp:70] t = [
+    10,
+    20,
+    60,
+]

examples/tutorial-wasm32/README.md

@@ -0,0 +1,72 @@
+#include <iostream>
+#include <vector>
+
+#include "./generated.h"
+
+// Rust values are available in the `::rust` namespace from their absolute path
+// in Rust
+template <typename T> using Vec = rust::std::vec::Vec<T>;
+template <typename T> using Option = rust::std::option::Option<T>;
+template <typename T> using BoxDyn = rust::Box<rust::Dyn<T>>;
+
+// You can implement Rust traits for your classes
+template <typename T>
+class VectorIterator : public rust::std::iter::Iterator<T> {
+  std::vector<T> vec;
+  size_t pos;
+
+public:
+  VectorIterator(std::vector<T> &&v) : vec(v), pos(0) {}
+  ~VectorIterator() {
+    std::cout << "vector iterator has been destructed" << std::endl;
+  }
+
+  Option<T> next() override {
+    if (pos >= vec.size()) {
+      return Option<T>::None();
+    }
+    T value = vec[pos++];
+    // You can construct Rust enum with fields in C++
+    return Option<T>::Some(value);
+  }
+};
+
+int main() {
+  // You can call Rust functions that return things by value, and store that
+  // value in your stack.
+  auto s = Vec<int32_t>::new_();
+  s.push(2);
+  Vec<int32_t>::push(s, 5);
+  s.push(7);
+  Vec<int32_t>::push(s, 3);
+  // You can call Rust functions just like normal Rust.
+  std::cout << s.clone().into_iter().sum() << std::endl;
+  // Access valid indices
+  std::cout << "s[2] = " << *s.get(2).unwrap() << std::endl;
+  // TODO: Uncomment this line after enabling wasmtime exceptions.
+  // std::cout << "s[4] = " << *s.get(4).unwrap() << std::endl;
+  std::cout << "Rust panic would happen if we accessed invalid index, but we avoid it" << std::endl;
+
+  int state = 0;
+  // You can convert a C++ lambda into a `Box<dyn Fn>` and friends.
+  auto f = BoxDyn<rust::Fn<int32_t, int32_t>>::make_box([&](int32_t x) {
+    state += x;
+    std::cout << "hello " << x << " " << state << "\n";
+    return x * 2;
+  });
+  // And pass it to Rust functions that accept closures.
+  auto x = s.into_iter().map(std::move(f)).sum();
+  std::cout << x << " " << state << "\n";
+  std::vector<int32_t> vec{10, 20, 60};
+  // You can convert a C++ type that implements `Trait` to a `Box<dyn Trait>`.
+  // `make_box` is similar to the `make_unique`, it takes constructor arguments
+  // and construct it inside the `Box` (instead of `unique_ptr`).
+  auto vec_as_iter = BoxDyn<rust::std::iter::Iterator<int32_t>>::make_box<
+      VectorIterator<int32_t>>(std::move(vec));
+  // Then use it like a normal Rust value.
+  auto t = vec_as_iter.collect();
+  // Some utilities are also provided. For example, `zngur_dbg` is the
+  // equivalent of `dbg!` macro.
+  zngur_dbg(t);
+  return 0;
+}

examples/tutorial-wasm32/expected_output.txt

@@ -0,0 +1,59 @@
+type Box<dyn Fn(i32) -> i32> {
+    #layout(size = 8, align = 4);
+}
+
+mod ::std {
+    type option::Option<i32> {
+        #layout(size = 8, align = 4);
+        wellknown_traits(Copy);
+
+        constructor None;
+        constructor Some(i32);
+
+        fn unwrap(self) -> i32;
+    }
+
+    type option::Option<&i32> {
+        #layout(size = 4, align = 4);
+        wellknown_traits(Copy);
+
+        fn unwrap(self) -> &i32;
+    }
+
+    type iter::Map<::std::vec::IntoIter<i32>, Box<dyn Fn(i32) -> i32>> {
+        #layout(size = 24, align = 4);
+
+        fn sum<i32>(self) -> i32;
+    }
+
+    mod vec {
+        type IntoIter<i32> {
+            #layout(size = 16, align = 4);
+
+            fn sum<i32>(self) -> i32;
+            fn map<i32, Box<dyn Fn(i32) -> i32>>(self, Box<dyn Fn(i32) -> i32>)
+                -> ::std::iter::Map<::std::vec::IntoIter<i32>, Box<dyn Fn(i32) -> i32>>;
+        }
+
+        type Vec<i32> {
+            #layout(size = 12, align = 4);
+            wellknown_traits(Debug);
+
+            fn new() -> Vec<i32>;
+            fn push(&mut self, i32);
+            fn clone(&self) -> Vec<i32>;
+            fn get(&self, usize) -> ::std::option::Option<&i32> deref [i32];
+            fn into_iter(self) -> ::std::vec::IntoIter<i32>;
+        }
+    }
+
+    trait iter::Iterator::<Item = i32> {
+        fn next(&mut self) -> ::std::option::Option<i32>;
+    }
+}
+
+type Box<dyn ::std::iter::Iterator<Item = i32>> {
+    #layout(size = 8, align = 4);
+
+    fn collect<::std::vec::Vec<i32>>(self) -> ::std::vec::Vec<i32>;
+}