From 7130bd41c56ddd941e0036cae227815529f1e282 Mon Sep 17 00:00:00 2001 From: Aaradhy Chinche Date: Tue, 20 Jan 2026 17:13:45 +0530 Subject: [PATCH 1/5] docs: add native Go (Go 1.21) WASI documentation Signed-off-by: Aaradhy Chinche git push --force-with-lease --- docs/develop/go/hello_world.md | 5 +- docs/develop/go/native-go-wasi.md | 84 +++++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+), 1 deletion(-) create mode 100644 docs/develop/go/native-go-wasi.md diff --git a/docs/develop/go/hello_world.md b/docs/develop/go/hello_world.md index 3385a3b7..eba14db7 100644 --- a/docs/develop/go/hello_world.md +++ b/docs/develop/go/hello_world.md @@ -4,9 +4,12 @@ sidebar_position: 1 # TinyGo +This page focuses on using TinyGo with WasmEdge. Native Go (Go 1.21+) support is documented separately. + The best way to run Go programs in WasmEdge is to compile Go source code to WebAssembly using [TinyGo](https://tinygo.org/). In this article, we will show you how. -The Golang is adding WASI support. Stay tuned! +Native Go (Go 1.21+) now supports compiling to WASI. For details on using native Go with WasmEdge, see the Native Go WASI guide. + ## Install TinyGo diff --git a/docs/develop/go/native-go-wasi.md b/docs/develop/go/native-go-wasi.md new file mode 100644 index 00000000..7c8a1baf --- /dev/null +++ b/docs/develop/go/native-go-wasi.md @@ -0,0 +1,84 @@ +--- +sidebar_position: 2 +--- + +# Native Go with WASI (Go 1.21+) + +Starting with Go 1.21, the Go toolchain natively supports compiling applications to the WebAssembly System Interface (WASI). This enables developers to build WebAssembly applications using the standard Go compiler and run them on WASI-compliant runtimes such as WasmEdge. + +This page describes how to develop and run WASI-based applications using native Go with WasmEdge. It also highlights key differences compared to using TinyGo, which has historically been the primary way to run Go applications on WebAssembly. + +Native Go support is particularly useful for developers who require functionality that is not fully available in the TinyGo standard library, such as more complete language features or integration with existing Go codebases. + + +## TinyGo vs Native Go + +There are currently two ways to develop Go applications for WasmEdge: using TinyGo or using the native Go compiler with WASI support introduced in Go 1.21. Each approach has different trade-offs. + +| Aspect | TinyGo | Native Go (Go 1.21+) | +|------|--------|----------------------| +| Compiler | TinyGo (LLVM-based) | Standard Go compiler | +| Standard library | Partial | More complete | +| Binary size | Smaller | Larger | +| WASI support | Mature | Introduced in Go 1.21 | +| Networking | Not available by default | Not available by default (WASI limitation) | +| Typical use cases | Small, resource-constrained workloads | Existing Go codebases, richer language features | + +TinyGo has historically been the primary way to run Go applications on WebAssembly and remains a good choice for lightweight workloads. Native Go with WASI support enables developers to reuse more existing Go code and tooling, but it is still subject to the limitations of the WASI environment. + + +## Building a WASI module with Go 1.21 + +To compile a Go application to a WASI-compatible WebAssembly module, Go 1.21 or newer is required. + +Use the following environment variables when building your application: + +```bash +GOOS=wasip1 GOARCH=wasm go build -o app.wasm +``` + +In this command: + +GOOS=wasip1 specifies the WASI Preview 1 target + +GOARCH=wasm selects the WebAssembly architecture + +app.wasm is the generated WebAssembly module + +The resulting .wasm file can be executed by WASI-compliant runtimes such as WasmEdge. + + +## Running the module with WasmEdge + +After building the WebAssembly module (for example, `app.wasm`), it can be executed using the WasmEdge CLI. + +```bash +wasmedge app.wasm +``` + +WasmEdge executes the WASI _start entry point by default. Command-line arguments provided after the module path are forwarded to the module at runtime. The --dir option can be used to preopen host directories for file system access when required. + + +## Networking and WASI limitations + +The current WASI Preview 1 specification does not include native support for networking primitives such as TCP or UDP sockets. As a result, Go packages that depend on the standard `net` or `net/http` libraries cannot function out of the box in a WASI environment. + +This limitation applies to both TinyGo and native Go when targeting WASI and is not specific to WasmEdge. Networking support requires additional abstractions or host-provided functionality, which are discussed in the following sections. + + +## Networking with stealthrocket/net + +To work around the lack of native networking support in WASI Preview 1, alternative approaches are required. One such approach is the use of the `stealthrocket/net` project, which provides a networking implementation designed for WASI environments. + +Rather than relying on traditional socket APIs, `stealthrocket/net` enables networking by forwarding requests to host-provided functionality. This allows Go applications compiled to WASI to perform HTTP requests and other network operations when supported by the runtime environment. + +When using native Go with WASI, libraries such as `stealthrocket/net` can be used to enable networking functionality that is otherwise unavailable through the standard Go `net` and `net/http` packages. + + +## Importing host functions in Go 1.21 + +In addition to using libraries such as `stealthrocket/net`, native Go applications compiled to WASI can interact with runtime-provided functionality by importing host functions. + +Starting with Go 1.21, host functions can be declared using the `//go:wasmimport` directive. This allows Go code to call functions that are implemented by the WebAssembly runtime, such as WasmEdge, rather than inside the WebAssembly module itself. + +Host functions can be used to expose capabilities that are not available in the WASI specification, including networking, system integration, or custom platform services. The exact set of available host functions depends on the runtime and its configuration. From d8af2da1c12ccffd64676c22a956110a5c6accff Mon Sep 17 00:00:00 2001 From: Aaradhy Chinche Date: Tue, 20 Jan 2026 22:22:47 +0530 Subject: [PATCH 2/5] docs: add native Go WASI hello world and host function examples Signed-off-by: Aaradhy Chinche --- docs/develop/go/native-go-wasi.md | 88 ++++++++++++++++++++++++++++--- 1 file changed, 81 insertions(+), 7 deletions(-) diff --git a/docs/develop/go/native-go-wasi.md b/docs/develop/go/native-go-wasi.md index 7c8a1baf..c0c5ea8b 100644 --- a/docs/develop/go/native-go-wasi.md +++ b/docs/develop/go/native-go-wasi.md @@ -27,6 +27,46 @@ There are currently two ways to develop Go applications for WasmEdge: using Tiny TinyGo has historically been the primary way to run Go applications on WebAssembly and remains a good choice for lightweight workloads. Native Go with WASI support enables developers to reuse more existing Go code and tooling, but it is still subject to the limitations of the WASI environment. +## Hello World example + +The following example demonstrates a minimal Go application compiled to WASI and executed using WasmEdge. + +### hello.go + +```go +package main + +import "fmt" + +func main() { + fmt.Println("Hello, world") +} +``` + +### Build + +```bash +# initialize a module (optional, but recommended) +go mod init hello +# build a WASI-compatible WebAssembly module +GOOS=wasip1 GOARCH=wasm go build -o hello.wasm +``` + +### Run with WasmEdge + +```bash +wasmedge hello.wasm +``` + +Expected output: + +``` +Hello, world +``` + +Ensure the example prints "Hello, world" when run with WasmEdge. This section is intentionally minimal to demonstrate the native Go WASI path working end-to-end. + + ## Building a WASI module with Go 1.21 To compile a Go application to a WASI-compatible WebAssembly module, Go 1.21 or newer is required. @@ -68,17 +108,51 @@ This limitation applies to both TinyGo and native Go when targeting WASI and is ## Networking with stealthrocket/net -To work around the lack of native networking support in WASI Preview 1, alternative approaches are required. One such approach is the use of the `stealthrocket/net` project, which provides a networking implementation designed for WASI environments. +To work around the lack of native networking support in WASI Preview 1, +alternative approaches are required. One such experimental approach is the use +of the external `stealthrocket/net` project, which provides a networking +implementation designed for WASI environments. + +Rather than relying on traditional socket APIs, `stealthrocket/net` forwards +network requests to host-provided functionality. This can enable limited HTTP +and networking capabilities for Go applications compiled to WASI, depending on +the runtime environment. -Rather than relying on traditional socket APIs, `stealthrocket/net` enables networking by forwarding requests to host-provided functionality. This allows Go applications compiled to WASI to perform HTTP requests and other network operations when supported by the runtime environment. +> **Note** +> `stealthrocket/net` is **not part of WasmEdge** and is mentioned here only as an +> external reference. Usage details, compatibility, and examples should be +> verified directly with the project maintainers. -When using native Go with WASI, libraries such as `stealthrocket/net` can be used to enable networking functionality that is otherwise unavailable through the standard Go `net` and `net/http` packages. +For more information, see the official repository: +- https://github.com/stealthrocket/net -## Importing host functions in Go 1.21 -In addition to using libraries such as `stealthrocket/net`, native Go applications compiled to WASI can interact with runtime-provided functionality by importing host functions. +## Importing host functions in native Go (Go 1.21+) + +Native Go applications compiled to WASI can call functions that are implemented +by the WebAssembly runtime (such as WasmEdge) rather than inside the module +itself. + +Starting with Go 1.21, host functions can be declared using the +`//go:wasmimport` directive. + +### Example + +```go +package main + +//go:wasmimport wasi_snapshot_preview1 proc_exit +func procExit(code uint32) + +func main() { + procExit(0) +} +``` -Starting with Go 1.21, host functions can be declared using the `//go:wasmimport` directive. This allows Go code to call functions that are implemented by the WebAssembly runtime, such as WasmEdge, rather than inside the WebAssembly module itself. +In this example, proc_exit is a WASI host function provided by the runtime. +The implementation is supplied by the WASI environment rather than by Go code +inside the WebAssembly module. -Host functions can be used to expose capabilities that are not available in the WASI specification, including networking, system integration, or custom platform services. The exact set of available host functions depends on the runtime and its configuration. +For more details, see the official Go documentation: +- https://pkg.go.dev/cmd/compile#hdr-Directives From e1f7789cc1c1aec00377585b86acac5b54cdfdf6 Mon Sep 17 00:00:00 2001 From: Aaradhy Chinche Date: Tue, 20 Jan 2026 22:25:05 +0530 Subject: [PATCH 3/5] docs: link TinyGo hello world to native Go WASI docs Signed-off-by: Aaradhy Chinche --- docs/develop/go/hello_world.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/develop/go/hello_world.md b/docs/develop/go/hello_world.md index eba14db7..69c63525 100644 --- a/docs/develop/go/hello_world.md +++ b/docs/develop/go/hello_world.md @@ -4,7 +4,10 @@ sidebar_position: 1 # TinyGo -This page focuses on using TinyGo with WasmEdge. Native Go (Go 1.21+) support is documented separately. +This page focuses on using TinyGo with WasmEdge. +Native Go (Go 1.21+) support is documented separately in +[native Go WASI documentation](./native-go-wasi.md). + The best way to run Go programs in WasmEdge is to compile Go source code to WebAssembly using [TinyGo](https://tinygo.org/). In this article, we will show you how. From 993625e65d11f10947f88f58a1267c5ea5b5253f Mon Sep 17 00:00:00 2001 From: Aaradhy Chinche Date: Wed, 21 Jan 2026 02:43:32 +0530 Subject: [PATCH 4/5] docs: clarify meaning of binary size in Go WASI comparison Signed-off-by: Aaradhy Chinche --- docs/develop/go/native-go-wasi.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/docs/develop/go/native-go-wasi.md b/docs/develop/go/native-go-wasi.md index c0c5ea8b..29035091 100644 --- a/docs/develop/go/native-go-wasi.md +++ b/docs/develop/go/native-go-wasi.md @@ -19,11 +19,16 @@ There are currently two ways to develop Go applications for WasmEdge: using Tiny |------|--------|----------------------| | Compiler | TinyGo (LLVM-based) | Standard Go compiler | | Standard library | Partial | More complete | -| Binary size | Smaller | Larger | +| Binary size (generated .wasm output) | Typically smaller | Typically larger | | WASI support | Mature | Introduced in Go 1.21 | | Networking | Not available by default | Not available by default (WASI limitation) | | Typical use cases | Small, resource-constrained workloads | Existing Go codebases, richer language features | +Binary size here refers to the size of the generated WebAssembly (`.wasm`) file. +Actual output size can vary depending on the application, enabled features, and +dependencies. The comparison reflects typical behavior rather than a +benchmarked guarantee. + TinyGo has historically been the primary way to run Go applications on WebAssembly and remains a good choice for lightweight workloads. Native Go with WASI support enables developers to reuse more existing Go code and tooling, but it is still subject to the limitations of the WASI environment. From 7235425a49618df2069a859b3324e6be5b1427b7 Mon Sep 17 00:00:00 2001 From: Aaradhy Chinche Date: Wed, 21 Jan 2026 09:38:12 +0530 Subject: [PATCH 5/5] docs: remove unsupported binary size comparison Signed-off-by: Aaradhy Chinche --- docs/develop/go/native-go-wasi.md | 6 ------ 1 file changed, 6 deletions(-) diff --git a/docs/develop/go/native-go-wasi.md b/docs/develop/go/native-go-wasi.md index 29035091..bf0ee1ae 100644 --- a/docs/develop/go/native-go-wasi.md +++ b/docs/develop/go/native-go-wasi.md @@ -19,16 +19,10 @@ There are currently two ways to develop Go applications for WasmEdge: using Tiny |------|--------|----------------------| | Compiler | TinyGo (LLVM-based) | Standard Go compiler | | Standard library | Partial | More complete | -| Binary size (generated .wasm output) | Typically smaller | Typically larger | | WASI support | Mature | Introduced in Go 1.21 | | Networking | Not available by default | Not available by default (WASI limitation) | | Typical use cases | Small, resource-constrained workloads | Existing Go codebases, richer language features | -Binary size here refers to the size of the generated WebAssembly (`.wasm`) file. -Actual output size can vary depending on the application, enabled features, and -dependencies. The comparison reflects typical behavior rather than a -benchmarked guarantee. - TinyGo has historically been the primary way to run Go applications on WebAssembly and remains a good choice for lightweight workloads. Native Go with WASI support enables developers to reuse more existing Go code and tooling, but it is still subject to the limitations of the WASI environment.