gojs: makes experimental status explicit (#1200)

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.

Signed-off-by: Adrian Cole <adrian@tetrate.io>

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:

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"

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).

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

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"
 )
 

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"

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 (

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

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"

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"
 )
 

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