Repository: tetratelabs/wazero
Pull request #1200 (2023-03-06 00:53:43)

gojs: makes experimental status explicit
Before, our README said gojs `GOOS=js compiled wasm` was experimental. However, as we head to 1.0 we should be more explicit about that.

When we started gojs, there was no likely future where `GOOS=wasi` would happen in the standard go compiler. This has changed, so we'll only keep the gojs package around until wasi is usable for two Go releases. Being in an experimental package helps others know to watch out for this.


Patch:
diff --git a/Makefile b/Makefile
index 7d844313..37ab9900 100644
--- a/Makefile
+++ b/Makefile
@@ -44,7 +44,7 @@ build.bench:
 
 .PHONY: test.examples
 test.examples:
-	@go test $(go_test_options) ./examples/... ./imports/assemblyscript/example/... ./imports/emscripten/... ./imports/go/example/... ./imports/wasi_snapshot_preview1/example/...
+	@go test $(go_test_options) ./examples/... ./imports/assemblyscript/example/... ./imports/emscripten/... ./experimental/gojs/example/... ./imports/wasi_snapshot_preview1/example/...
 
 .PHONY: build.examples.as
 build.examples.as:
diff --git a/cmd/wazero/wazero.go b/cmd/wazero/wazero.go
index 82819269..0534b0bd 100644
--- a/cmd/wazero/wazero.go
+++ b/cmd/wazero/wazero.go
@@ -15,8 +15,8 @@ import (
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/api"
 	"github.com/tetratelabs/wazero/experimental"
+	"github.com/tetratelabs/wazero/experimental/gojs"
 	"github.com/tetratelabs/wazero/experimental/logging"
-	gojs "github.com/tetratelabs/wazero/imports/go"
 	"github.com/tetratelabs/wazero/imports/wasi_snapshot_preview1"
 	"github.com/tetratelabs/wazero/internal/version"
 	"github.com/tetratelabs/wazero/sys"
diff --git a/examples/import-go/README.md b/examples/import-go/README.md
index 3503548f..1221fb20 100644
--- a/examples/import-go/README.md
+++ b/examples/import-go/README.md
@@ -24,15 +24,9 @@ produced, the export/import mechanics are the same!
 
 The following examples continue the path of learning about importing and exporting functions with wazero:
 
-#### [WebAssembly System Interface (WASI)](../wasi)
+#### [WebAssembly System Interface (WASI)](../../imports/wasi_snapshot_preview1/example)
 
 This uses an ad-hoc Go-defined function to print to the console. There is an emerging specification to standardize
 system calls (similar to Go's [x/sys](https://pkg.go.dev/golang.org/x/sys/unix)) called WebAssembly System Interface
 [(WASI)](https://github.com/WebAssembly/WASI). While this is not yet a W3C standard, wazero includes a
 [wasi package](https://pkg.go.dev/github.com/tetratelabs/wazero/wasi).
-
-#### [Replace Import](../replace-import)
-
-You may use WebAssembly modules that have imports that don't match your ideal packaging structure. wazero allows you to
-replace imports with different module names as needed, on a function granularity using
-[ModuleConfig.WithImport](https://pkg.go.dev/github.com/tetratelabs/wazero#ModuleConfig.WithImport).
diff --git a/imports/go/README.md b/experimental/gojs/README.md
similarity index 58%
rename from imports/go/README.md
rename to experimental/gojs/README.md
index d5e09a75..d28debf3 100644
--- a/imports/go/README.md
+++ b/experimental/gojs/README.md
@@ -3,7 +3,7 @@
 When `GOOS=js` and `GOARCH=wasm`, Go's compiler targets WebAssembly Binary
 format (%.wasm).
 
-Wazero's "github.com/tetratelabs/wazero/imports/go" package allows you to run
+Wazero's "github.com/tetratelabs/wazero/experimental/gojs" package allows you to run
 a `%.wasm` file compiled by Go.  This is similar to what is implemented in
 [wasm_exec.js][1]. See https://wazero.io/languages/go/ for more.
 
@@ -15,7 +15,12 @@ wazero includes an [example](example) that makes HTTP client requests.
 
 Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise."
 Accordingly, wazero cannot guarantee this will work from release to release,
-or that usage will be relatively free of bugs. Due to this and the
-relatively high implementation overhead, most will choose TinyGo instead.
+or that usage will be relatively free of bugs. Moreover, [`GOOS=wasi`] will
+happen, and once that's available in two releases wazero will remove this
+package.
+
+Due to these concerns and the relatively high implementation overhead, most
+will choose TinyGo instead of gojs.
 
 [1]: https://github.com/golang/go/blob/go1.20/misc/wasm/wasm_exec.js
+[2]: https://github.com/golang/go/issues/58141
diff --git a/imports/go/example/.gitignore b/experimental/gojs/example/.gitignore
similarity index 100%
rename from imports/go/example/.gitignore
rename to experimental/gojs/example/.gitignore
diff --git a/imports/go/example/README.md b/experimental/gojs/example/README.md
similarity index 100%
rename from imports/go/example/README.md
rename to experimental/gojs/example/README.md
diff --git a/imports/go/example/stars.go b/experimental/gojs/example/stars.go
similarity index 98%
rename from imports/go/example/stars.go
rename to experimental/gojs/example/stars.go
index d6a78eb9..0acd4974 100644
--- a/imports/go/example/stars.go
+++ b/experimental/gojs/example/stars.go
@@ -12,7 +12,7 @@ import (
 	"time"
 
 	"github.com/tetratelabs/wazero"
-	gojs "github.com/tetratelabs/wazero/imports/go"
+	"github.com/tetratelabs/wazero/experimental/gojs"
 	"github.com/tetratelabs/wazero/sys"
 )
 
diff --git a/imports/go/gojs.go b/experimental/gojs/gojs.go
similarity index 94%
rename from imports/go/gojs.go
rename to experimental/gojs/gojs.go
index 1fb7a27b..730bc47d 100644
--- a/imports/go/gojs.go
+++ b/experimental/gojs/gojs.go
@@ -5,8 +5,12 @@
 //
 // Go defines js "EXPERIMENTAL... exempt from the Go compatibility promise."
 // Accordingly, wazero cannot guarantee this will work from release to release,
-// or that usage will be relatively free of bugs. Due to this and the
-// relatively high implementation overhead, most will choose TinyGo instead.
+// or that usage will be relatively free of bugs. Moreover, `GOOS=wasi` will
+// happen, and once that's available in two releases wazero will remove this
+// package.
+//
+// Due to these concerns and the relatively high implementation overhead, most
+// will choose TinyGo instead of gojs.
 package gojs
 
 import (
diff --git a/imports/README.md b/imports/README.md
index 17bef9f8..080ea53b 100644
--- a/imports/README.md
+++ b/imports/README.md
@@ -5,7 +5,6 @@ languages or shared compiler toolchains.
 
 * [AssemblyScript](assemblyscript) e.g. `asc X.ts --debug -b none -o X.wasm`
 * [Emscripten](emscripten) e.g. `em++ ... -s STANDALONE_WASM -o X.wasm X.cc`
-* [Go](go) e.g. `GOARCH=wasm GOOS=js go build -o X.wasm X.go`
 * [WASI](wasi_snapshot_preview1) e.g. `tinygo build -o X.wasm -target=wasi X.go`
 
 Note: You may not see a language listed here because it either works without
diff --git a/site/content/languages/go.md b/site/content/languages/go.md
index 023dc8b2..a5eb73a5 100644
--- a/site/content/languages/go.md
+++ b/site/content/languages/go.md
@@ -361,7 +361,7 @@ the host operating system's underlying controls permit.
 [11]: https://github.com/WebAssembly/proposals
 [12]: https://github.com/golang/go/blob/go1.20/src/cmd/link/internal/ld/data.go#L2457
 [13]: https://github.com/golang/go/blob/go1.20/src/syscall/tables_js.go#L371-L494
-[14]: https://github.com/tetratelabs/wazero/tree/main/imports/go/example
+[14]: https://github.com/tetratelabs/wazero/tree/main/experimental/gojs/example
 [15]: https://www.w3.org/TR/2019/REC-wasm-core-1-20191205/
 [16]: https://github.com/golang/go/blob/go1.20/src/internal/buildcfg/cfg.go#L136-L150
 [17]: https://github.com/WebAssembly/spec/blob/wg-2.0.draft1/proposals/nontrapping-float-to-int-conversion/Overview.md


Test patch:
diff --git a/imports/go/example/stars/go.mod b/experimental/gojs/example/stars/go.mod
similarity index 100%
rename from imports/go/example/stars/go.mod
rename to experimental/gojs/example/stars/go.mod
diff --git a/imports/go/example/stars/main.go b/experimental/gojs/example/stars/main.go
similarity index 100%
rename from imports/go/example/stars/main.go
rename to experimental/gojs/example/stars/main.go
diff --git a/imports/go/example/stars_test.go b/experimental/gojs/example/stars_test.go
similarity index 98%
rename from imports/go/example/stars_test.go
rename to experimental/gojs/example/stars_test.go
index 78d17555..e84e8c13 100644
--- a/imports/go/example/stars_test.go
+++ b/experimental/gojs/example/stars_test.go
@@ -10,7 +10,7 @@ import (
 	"testing"
 
 	"github.com/tetratelabs/wazero"
-	gojs "github.com/tetratelabs/wazero/imports/go"
+	"github.com/tetratelabs/wazero/experimental/gojs"
 	"github.com/tetratelabs/wazero/internal/platform"
 	"github.com/tetratelabs/wazero/internal/testing/maintester"
 	"github.com/tetratelabs/wazero/internal/testing/require"
diff --git a/internal/gojs/compiler_test.go b/internal/gojs/compiler_test.go
index 0bd91169..a2392c7c 100644
--- a/internal/gojs/compiler_test.go
+++ b/internal/gojs/compiler_test.go
@@ -17,7 +17,7 @@ import (
 
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/api"
-	gojs "github.com/tetratelabs/wazero/imports/go"
+	"github.com/tetratelabs/wazero/experimental/gojs"
 	"github.com/tetratelabs/wazero/internal/fstest"
 	internalgojs "github.com/tetratelabs/wazero/internal/gojs"
 	"github.com/tetratelabs/wazero/internal/gojs/run"
diff --git a/internal/gojs/http_test.go b/internal/gojs/http_test.go
index 178eb451..86bd2999 100644
--- a/internal/gojs/http_test.go
+++ b/internal/gojs/http_test.go
@@ -8,7 +8,7 @@ import (
 	"testing"
 
 	"github.com/tetratelabs/wazero"
-	gojs "github.com/tetratelabs/wazero/imports/go"
+	"github.com/tetratelabs/wazero/experimental/gojs"
 	"github.com/tetratelabs/wazero/internal/testing/require"
 )