feat(wasm): add experimental WIT parser and component model wrapper

cmd/tools/vwit_wrap.v

@@ -0,0 +1,17 @@
+import os
+import wit
+import wasm
+
+fn main() {
+	if os.args.len < 5 {
+		println('usage: v run cmd/tools/vwit_wrap.v <core.wasm> <input.wit> <world> <out.component.wasm>')
+		return
+	}
+	core := os.read_file(os.args[1]) or { panic(err) }
+	src := os.read_file(os.args[2]) or { panic(err) }
+	doc := wit.parse(src) or { panic(err) }
+	out := wit.wrap_component(core.bytes(), doc, os.args[3])
+	os.write_file_array(os.args[4], out) or { panic(err) }
+	println('wrote ${os.args[4]} (${out.len} bytes)')
+	_ = wasm.is_component
+}

doc/wasm.md

@@ -71,3 +71,18 @@ optimized SSA:
 ./v test vlib/v/gen/wasm/ssa_gen_test.v
 V3_TEST_WASM=1 ./v vlib/v/compiler_tests/wasm_codegen_test.v
 ```
+
+## Emscripten output (needs the Emscripten SDK)
+
+The native backend above emits a standalone `.wasm` module and never invokes Emscripten.
+If you instead need Emscripten's JavaScript shell or HTML page, target `wasm32_emscripten`
+explicitly and compile the generated C with `emcc` from an activated
+[Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html) on your `PATH`:
+
+```sh
+./v -os wasm32_emscripten -cc emcc -o hello.html examples/hello_world.v
+```
+
+Without `emcc` on `PATH`, that combination fails with a message pointing back here.
+Emitting only C (`-o hello.c`) never invokes a C compiler, so it works without Emscripten
+installed.

examples/wasm/component/README.md

@@ -0,0 +1,17 @@
+# V WebAssembly Component Example
+
+## Build
+
+```sh
+v -b wasm -component -wit hello.wit hello.v -o hello.wasm
+```
+
+## Run
+
+Requires `wasmtime`:
+
+```sh
+wasmtime run hello.component.wasm
+```
+
+If wasmtime is not installed, the build still succeeds but running is skipped.

examples/wasm/component/hello.v

@@ -0,0 +1,5 @@
+module main
+
+fn main() {
+	println('hello from V component')
+}

examples/wasm/component/hello.wit

@@ -0,0 +1,5 @@
+package example:hello@0.1.0;
+
+world hello {
+	export run: func();
+}

examples/wasm/component/run.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -e
+V=${V:-v}
+$V -b wasm -component -wit hello.wit hello.v -o hello.wasm
+if command -v wasmtime >/dev/null 2>&1; then
+  wasmtime run hello.component.wasm
+else
+  echo "wasmtime not found; skipping execution"
+fi

examples/wasm/playground/README.md

@@ -7,7 +7,9 @@ the V compiler and V's direct WebAssembly backend. No compilation server is need
 
 Build V in the repository root (`make` if `./v` is missing, then `./v self`). Install and
 activate the [Emscripten SDK](https://emscripten.org/docs/getting_started/downloads.html), so
-`emcc` is on your `PATH`. From the repository root, run:
+`emcc` is on your `PATH`. (That SDK is only needed to compile the compiler itself into the
+browser playground; ordinary `-b wasm` output never requires it.) From the repository root,
+run:
 
 ```sh
 sh examples/wasm/playground/build.sh

examples/wasm/wasi_preview2/README.md

@@ -0,0 +1,19 @@
+# WASI Preview 2 Example
+
+Generated V bindings from WASI preview2 WIT files.
+
+## Build
+
+```sh
+v -b wasm -component -wit hello.wit hello.v -o hello.wasm
+```
+
+## Run
+
+Requires `wasmtime`:
+
+```sh
+wasmtime run hello.component.wasm
+```
+
+If wasmtime is not installed, the build still succeeds but running is skipped.

examples/wasm/wasi_preview2/hello.v

@@ -0,0 +1,5 @@
+module main
+
+fn main() {
+	println('hello from WASI preview2 component')
+}

examples/wasm/wasi_preview2/hello.wit

@@ -0,0 +1,5 @@
+package example:hello@0.1.0;
+
+world hello {
+	export run: func();
+}

examples/wasm/wasi_preview2/run.sh

@@ -0,0 +1,9 @@
+#!/bin/sh
+set -e
+V=${V:-v}
+$V -b wasm -component -wit hello.wit hello.v -o hello.wasm
+if command -v wasmtime >/dev/null 2>&1; then
+  wasmtime run hello.component.wasm
+else
+  echo "wasmtime not found; skipping execution"
+fi

examples/wasm_component/hello.v

@@ -0,0 +1,5 @@
+module main
+
+fn main() {
+	println('hello from V wasm component')
+}

examples/wasm_component/hello.wit

@@ -0,0 +1,9 @@
+package example:hello@0.1.0;
+
+interface api {
+	run: func() -> string;
+}
+
+world hello {
+	export api;
+}

examples/wit/example.wit

@@ -0,0 +1,12 @@
+package example:demo@0.1.0;
+
+interface calc {
+	record point { x: f64, y: f64 }
+	add: func(a: s32, b: s32) -> s32;
+	scale: func(p: point, factor: f64) -> point;
+}
+
+world app {
+	import calc;
+	export run: func() -> string;
+}

examples/wit/main.v

@@ -0,0 +1,8 @@
+import os
+import wit
+
+fn main() {
+	src := os.read_file('example.wit') or { panic(err) }
+	doc := wit.parse(src) or { panic(err) }
+	println(doc.to_v())
+}

vlib/v/compiler_tests/driver_cli_test.v

@@ -2236,6 +2236,36 @@ fn main() {
 	assert_driver_wasm_output(explicit_output)
 }
 
+fn test_emscripten_missing_emcc_suggests_native_wasm() {
+	root := os.join_path(os.vtmp_dir(), 'v3_driver_emscripten_toolchain_${os.getpid()}')
+	os.rmdir_all(root) or {}
+	os.mkdir_all(root) or { panic(err) }
+	defer {
+		os.rmdir_all(root) or {}
+	}
+	v3_bin := build_driver_cli_v3(root)
+	source := os.join_path(root, 'hello.v')
+	os.write_file(source, 'module main\n\nfn main() {\n\tprintln("hi")\n}\n') or {
+		panic(err)
+	}
+	if _ := os.find_abs_path_of_executable('emcc') {
+		println('skipping ${@FN}: emcc is on PATH, so the missing-toolchain guidance cannot trigger')
+	} else {
+		html_output := os.join_path(root, 'hello.html')
+		assert_driver_cli_failure(v3_bin, ['-os', 'wasm32_emscripten', '-cc', 'emcc', '-o',
+			html_output, source], 'was not found')
+		missing := cmdexec.run(v3_bin, ['-os', 'wasm32_emscripten', '-cc', 'emcc', '-o', html_output,
+			source])
+		assert missing.output.contains('Emscripten SDK'), missing.output
+		assert missing.output.contains('v -b wasm'), missing.output
+	}
+	// Emitting only C never invokes a C compiler, so it must work without emcc.
+	c_output := os.join_path(root, 'hello_emscripten.c')
+	c_only := cmdexec.run(v3_bin, ['-os', 'wasm32_emscripten', '-o', c_output, source])
+	assert c_only.exit_code == 0, c_only.output
+	assert os.is_file(c_output)
+}
+
 fn test_driver_rejects_invalid_cli_and_parses_vmod_subdirs() {
 	root := os.join_path(os.vtmp_dir(), 'v3_driver_cli_${os.getpid()}')
 	os.rmdir_all(root) or {}

vlib/v/driver/driver.v

@@ -57,6 +57,7 @@ $if !skip_ssa ? {
 
 $if !skip_wasm ? {
 	import v.gen.wasm as wasmgen
+	import wit
 }
 // vfmt on
 
@@ -10059,6 +10060,8 @@ pub fn run(args []string) {
 	mut is_livemain := false
 	mut is_liveshared := false
 	mut hot_fn := ''
+	mut component_flag := false
+	mut wit_file_path := ''
 	mut subsystem := pref.Subsystem.auto
 	mut icon_path := ''
 	mut is_strict := false
@@ -10236,6 +10239,12 @@ pub fn run(args []string) {
 			backend = normalize_backend_name(args[i].all_after('='))
 			backend_explicit = !backend_from_project
 			i++
+		} else if args[i] == '-component' {
+			component_flag = true
+			i++
+		} else if args[i] == '-wit' && i + 1 < args.len {
+			wit_file_path = args[i + 1]
+			i += 2
 		} else if args[i] == '-cross' {
 			// A modifier, not a target: it combines with `-os`/`-cc`, as in
 			// `v -cross -os windows -cc msvc`. See `v help build-c`.
@@ -11278,6 +11287,21 @@ pub fn run(args []string) {
 		// The executable suffix does not belong to the requested generated C path.
 		bin_file = target_bin_file
 	}
+	if backend in ['c', 'fastc'] && target.os == 'wasm32_emscripten' && !c_only {
+		// The emscripten target links through emcc, so fail here with guidance
+		// instead of a generic missing-executable error later. Emitting only C
+		// (`-o file.c`) never reaches this point, so it stays toolchain-free.
+		cc_base := os.file_name(c_compiler).to_lower()
+		if c_compiler_explicit && cc_base in ['emcc', 'emcc.bat', 'em++', 'em++.bat'] {
+			if _ := os.find_abs_path_of_executable(c_compiler) {
+			} else {
+				eprintln('error: cannot build for target `wasm32_emscripten`: C compiler `${c_compiler}` was not found.')
+				eprintln('Install the Emscripten SDK (https://emscripten.org/docs/getting_started/downloads.html) and activate it so `emcc` is on PATH,')
+				eprintln('or build a native WebAssembly module instead, which needs no Emscripten: `v -b wasm -o out.wasm input.v`.')
+				exit(1)
+			}
+		}
+	}
 	validate_windows_icon_option(icon_path, target.os, backend, is_shared, is_o, c_only,
 		generate_c_project) or {
 		eprintln(err.msg())
@@ -11422,6 +11446,19 @@ pub fn run(args []string) {
 		eprintln('fastc-phase driver.prefs ${driver_sw.elapsed().microseconds()}us')
 	}
 	prefs.target = target
+	prefs.component = component_flag
+	prefs.wit_file = wit_file_path
+	prefs.wasm_cabi = component_flag || 'wasm_cabi' in user_defines
+	if prefs.component {
+		if prefs.wit_file == '' {
+			eprintln('error: -component requires -wit <file.wit>')
+			exit(1)
+		}
+		if backend != 'wasm' {
+			eprintln('error: -component requires -b wasm')
+			exit(1)
+		}
+	}
 	prefs.output_cross_c = output_cross_c
 	prefs.thread_stack_size = if thread_stack_size_set {
 		thread_stack_size
@@ -14801,6 +14838,7 @@ pub fn run(args []string) {
 			}
 			m.release_codegen_analysis_metadata()
 			mut g := wasmgen.SSAGen.new(m)
+			g.set_wasm_cabi(prefs.wasm_cabi || prefs.component)
 			mut main_fn := config.main_fn
 			mut exports := config.exports.clone()
 			if main_fn.len == 0 {
@@ -14823,6 +14861,31 @@ pub fn run(args []string) {
 				eprintln('error writing ${output_file}')
 				exit(1)
 			}
+			if prefs.component {
+				// Invoke WIT parser + component wrapper (native flow).
+				wit_src := os.read_file(prefs.wit_file) or {
+					eprintln('error reading wit file ${prefs.wit_file}')
+					exit(1)
+				}
+				doc := wit.parse(wit_src) or {
+					eprintln('error parsing wit file ${prefs.wit_file}: ${err}')
+					exit(1)
+				}
+				core := os.read_file(output_file) or {
+					eprintln('error reading ${output_file}')
+					exit(1)
+				}
+				// Component output path
+				comp_out := output_file.all_before_last('.wasm') + '.component.wasm'
+				// Wrap with WIT-aware canonical lifting (string params lift via
+				// memory + realloc); falls back to plain wrapping.
+				wrapped := wit.wrap_component(core.bytes(), doc, '')
+				os.write_file_array(comp_out, wrapped) or {
+					eprintln('error writing ${comp_out}')
+					exit(1)
+				}
+				eprintln('component: wrote ${comp_out}')
+			}
 			for warning in g.warnings_list() {
 				eprintln('wasm: ${warning}')
 			}