From 45415816008f1b1f6b63bf8632f1cc601ab786d2 Mon Sep 17 00:00:00 2001
From: Jacob Gadikian <jacobgadikian@gmail.com>
Date: Wed, 21 May 2025 00:05:22 +0700
Subject: [PATCH] docs: document wazero build and update ci

---
 .github/workflows/go.yml |  7 +++++--
 README.md                | 26 +++++++++++++++++++-------
 docs/MIGRATING.md        | 19 +++++++++++++++++++
 3 files changed, 43 insertions(+), 9 deletions(-)

diff --git a/.github/workflows/go.yml b/.github/workflows/go.yml
index 8a7d89548..6eeb8a52c 100644
--- a/.github/workflows/go.yml
+++ b/.github/workflows/go.yml
@@ -2,7 +2,7 @@ name: Go Build and Test
 
 on:
   push:
-    branches: [ main ]
+    branches: [main]
   pull_request:
   workflow_dispatch:
 
@@ -14,7 +14,7 @@ jobs:
 
       - uses: actions/setup-go@v5
         with:
-          go-version: '1.24'
+          go-version: "1.24"
           cache: false
 
       - name: Check go mod tidy
@@ -28,5 +28,8 @@ jobs:
       - name: Go integration tests
         run: make test
 
+      - name: Go wazero tests
+        run: go test -tags wazero ./...
+
       - name: Go safety tests
         run: make test-safety
diff --git a/README.md b/README.md
index b4fcdabd8..21f0b6c83 100644
--- a/README.md
+++ b/README.md
@@ -7,8 +7,8 @@ applications, in particular from
 [x/wasm](https://github.com/CosmWasm/wasmd/tree/master/x/wasm).
 
 More information on what is CosmWasm and how to use it can be found here:
-[CosmWasm Docs](https://docs.cosmwasm.com). To generate and show
-the Rust part documentation you can run `make doc-rust`.
+[CosmWasm Docs](https://docs.cosmwasm.com). To generate and show the Rust part
+documentation you can run `make doc-rust`.
 
 ## Structure
 
@@ -80,8 +80,9 @@ CGO_ENABLED=0 go build ./types
 
 This package contains the code binding the libwasmvm build to the Go code. All
 low level FFI handling code belongs there. This package can only be built using
-cgo. Using the `internal/` convention makes this package fully private.
-For an overview of the exported C functions and their Go wrappers see [docs/CGO_INTERFACE.md](docs/CGO_INTERFACE.md).
+cgo. Using the `internal/` convention makes this package fully private. For an
+overview of the exported C functions and their Go wrappers see
+[docs/CGO_INTERFACE.md](docs/CGO_INTERFACE.md).
 
 #### Package github.com/CosmWasm/wasmvm
 
@@ -103,6 +104,17 @@ linking disabled an additional build tag is available.
 go build -tags "nolink_libwasmvm"
 ```
 
+You can also build using the experimental
+[wazero](https://github.com/tetratelabs/wazero) runtime which removes the need
+for CGO:
+
+```sh
+CGO_ENABLED=0 go build -tags wazero .
+```
+
+Once wazero has feature parity with the Rust implementation, the Rust dependency
+will be removed.
+
 ## Supported Platforms
 
 See [COMPILER_VERSIONS.md](docs/COMPILER_VERSIONS.md) for information on Go and
@@ -153,9 +165,9 @@ which for example excludes all 32 bit systems.
 
 ## Development
 
-There are two halves to this code - go and rust. The first step is to ensure that
-there is a proper dll built for your platform. This should be `api/libwasmvm.X`,
-where X is:
+There are two halves to this code - go and rust. The first step is to ensure
+that there is a proper dll built for your platform. This should be
+`api/libwasmvm.X`, where X is:
 
 - `so` for Linux systems
 - `dylib` for MacOS
diff --git a/docs/MIGRATING.md b/docs/MIGRATING.md
index 7425f2327..d21177a13 100644
--- a/docs/MIGRATING.md
+++ b/docs/MIGRATING.md
@@ -72,3 +72,22 @@ where the old name was deprecated.
 | `VoteMsg.Vote`                    | `VoteMsg.Option`                      | Brings consistency with Cosmos SDK naming                    |
 
 [ft]: https://stackoverflow.com/a/60073310
+
+## Building with or without CGO
+
+The default build links against the Rust based `libwasmvm` and therefore
+requires CGO:
+
+```sh
+go build ./...
+```
+
+If you want a pure Go build without the Rust dependency, disable CGO and enable
+the `wazero` build tag:
+
+```sh
+CGO_ENABLED=0 go build -tags wazero ./...
+```
+
+Once wazero provides all features of the Rust implementation, the Rust
+dependency will be removed.