Merge pull request #15 from faddat/codex/update-readme-and-ci-for-cgo-and-wazero

Document wazero build option

Author: faddat

.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

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

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.