From 25493fe271d39a55dfd3581e5c8d8c06041e5822 Mon Sep 17 00:00:00 2001 From: Crypt Keeper <64215+codefromthecrypt@users.noreply.github.com> Date: Mon, 6 Mar 2023 09:22:58 +0800 Subject: [PATCH] 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 --- Makefile | 2 +- cmd/wazero/wazero.go | 2 +- examples/import-go/README.md | 8 +------- {imports/go => experimental/gojs}/README.md | 11 ++++++++--- {imports/go => experimental/gojs}/example/.gitignore | 0 {imports/go => experimental/gojs}/example/README.md | 0 {imports/go => experimental/gojs}/example/stars.go | 2 +- .../go => experimental/gojs}/example/stars/go.mod | 0 .../go => experimental/gojs}/example/stars/main.go | 0 .../go => experimental/gojs}/example/stars_test.go | 2 +- {imports/go => experimental/gojs}/gojs.go | 8 ++++++-- imports/README.md | 1 - internal/gojs/compiler_test.go | 2 +- internal/gojs/http_test.go | 2 +- site/content/languages/go.md | 2 +- 15 files changed, 22 insertions(+), 20 deletions(-) rename {imports/go => experimental/gojs}/README.md (58%) rename {imports/go => experimental/gojs}/example/.gitignore (100%) rename {imports/go => experimental/gojs}/example/README.md (100%) rename {imports/go => experimental/gojs}/example/stars.go (98%) rename {imports/go => experimental/gojs}/example/stars/go.mod (100%) rename {imports/go => experimental/gojs}/example/stars/main.go (100%) rename {imports/go => experimental/gojs}/example/stars_test.go (98%) rename {imports/go => experimental/gojs}/gojs.go (94%) diff --git a/Makefile b/Makefile index 7d844313f..37ab99007 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 82819269e..0534b0bd3 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 3503548f8..1221fb20f 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 d5e09a75f..d28debf31 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 d6a78eb9c..0acd49743 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/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 78d17555a..e84e8c135 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/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 1fb7a27be..730bc47d3 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 17bef9f85..080ea53b1 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/internal/gojs/compiler_test.go b/internal/gojs/compiler_test.go index 0bd91169a..a2392c7c8 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 178eb451b..86bd29991 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" ) diff --git a/site/content/languages/go.md b/site/content/languages/go.md index 023dc8b20..a5eb73a56 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