Drops support for the WebAssembly text format

This drops the text format (%.wat) and renames
InstantiateModuleFromCode to InstantiateModuleFromBinary as it is no
longer ambiguous.

We decided to stop supporting the text format as it isn't typically used
in production, yet costs a lot of work to develop. Given the resources
available and the increased work added with WebAssembly 2.0 and soon
WASI 2, we can't afford to spend the time on it.

The old parser is used only internally and will eventually be moved to
its own repository named watzero, possibly towards archival.

See #59

Signed-off-by: Adrian Cole <[email protected]>

README.md

@@ -25,7 +25,7 @@ func main() {
 
 	// Read a WebAssembly binary containing an exported "fac" function.
 	// * Ex. (func (export "fac") (param i64) (result i64) ...
-	source, err := os.ReadFile("./path/to/fac.wasm")
+	wasm, err := os.ReadFile("./path/to/fac.wasm")
 	if err != nil {
 		log.Panicln(err)
 	}
@@ -35,7 +35,7 @@ func main() {
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
 	// Instantiate the module and return its exported functions
-	module, err := r.InstantiateModuleFromCode(ctx, source)
+	module, err := r.InstantiateModuleFromBinary(ctx, wasm)
 	if err != nil {
 		log.Panicln(err)
 	}

api/wasm.go

@@ -393,7 +393,7 @@ func DecodeF64(input uint64) float64 {
 	return math.Float64frombits(input)
 }
 
-// ImportRenamer applies during compilation after a module has been decoded from source, but before it is instantiated.
+// ImportRenamer applies during compilation after a module has been decoded from wasm, but before it is instantiated.
 //
 // For example, you may have a module like below, but the exported functions are in two different modules:
 //	(import "js" "increment" (func $increment (result i32)))
@@ -420,7 +420,7 @@ func DecodeF64(input uint64) float64 {
 //
 type ImportRenamer func(externType ExternType, oldModule, oldName string) (newModule, newName string)
 
-// MemorySizer applies during compilation after a module has been decoded from source, but before it is instantiated.
+// MemorySizer applies during compilation after a module has been decoded from wasm, but before it is instantiated.
 // This determines the amount of memory pages (65536 bytes per page) to use when a memory is instantiated as a []byte.
 //
 // Ex. Here's how to set the capacity to max instead of min, when set:

assemblyscript/assemblyscript_test.go

@@ -13,26 +13,27 @@ import (
 	"github.com/tetratelabs/wazero"
 	"github.com/tetratelabs/wazero/api"
 	"github.com/tetratelabs/wazero/internal/testing/require"
+	"github.com/tetratelabs/wazero/internal/watzero"
 	"github.com/tetratelabs/wazero/sys"
 )
 
-var abortWasm = []byte(`(module
+var abortWat = `(module
   (import "env" "abort" (func $~lib/builtins/abort (param i32 i32 i32 i32)))
   (memory 1 1)
   (export "abort" (func 0))
-)`)
+)`
 
-var seedWasm = []byte(`(module
+var seedWat = `(module
   (import "env" "seed" (func $~lib/builtins/seed (result f64)))
   (memory 1 1)
   (export "seed" (func 0))
-)`)
+)`
 
-var traceWasm = []byte(`(module
+var traceWat = `(module
   (import "env" "trace" (func $~lib/builtins/trace (param i32 i32 f64 f64 f64 f64 f64)))
   (memory 1 1)
   (export "trace" (func 0))
-)`)
+)`
 
 // testCtx is an arbitrary, non-default context. Non-nil also prevents linter errors.
 var testCtx = context.WithValue(context.Background(), struct{}{}, "arbitrary")
@@ -72,6 +73,9 @@ func TestAbort(t *testing.T) {
 				require.NoError(t, err)
 			}
 
+			abortWasm, err := watzero.Wat2Wasm(abortWat)
+			require.NoError(t, err)
+
 			code, err := r.CompileModule(testCtx, abortWasm, wazero.NewCompileConfig())
 			require.NoError(t, err)
 
@@ -98,6 +102,9 @@ func TestSeed(t *testing.T) {
 	_, err := Instantiate(testCtx, r)
 	require.NoError(t, err)
 
+	seedWasm, err := watzero.Wat2Wasm(seedWat)
+	require.NoError(t, err)
+
 	code, err := r.CompileModule(testCtx, seedWasm, wazero.NewCompileConfig())
 	require.NoError(t, err)
 
@@ -194,6 +201,9 @@ func TestTrace(t *testing.T) {
 			_, err := as.Instantiate(testCtx, r)
 			require.NoError(t, err)
 
+			traceWasm, err := watzero.Wat2Wasm(traceWat)
+			require.NoError(t, err)
+
 			code, err := r.CompileModule(testCtx, traceWasm, wazero.NewCompileConfig())
 			require.NoError(t, err)
 
@@ -314,6 +324,9 @@ func TestAbort_error(t *testing.T) {
 			_, err := Instantiate(testCtx, r)
 			require.NoError(t, err)
 
+			abortWasm, err := watzero.Wat2Wasm(abortWat)
+			require.NoError(t, err)
+
 			compiled, err := r.CompileModule(testCtx, abortWasm, wazero.NewCompileConfig())
 			require.NoError(t, err)
 
@@ -381,6 +394,9 @@ wasm stack trace:
 			_, err := Instantiate(testCtx, r)
 			require.NoError(t, err)
 
+			seedWasm, err := watzero.Wat2Wasm(seedWat)
+			require.NoError(t, err)
+
 			compiled, err := r.CompileModule(testCtx, seedWasm, wazero.NewCompileConfig())
 			require.NoError(t, err)
 
@@ -429,6 +445,9 @@ wasm stack trace:
 			_, err := NewBuilder(r).WithTraceToStdout().Instantiate(testCtx, r)
 			require.NoError(t, err)
 
+			traceWasm, err := watzero.Wat2Wasm(traceWat)
+			require.NoError(t, err)
+
 			compiled, err := r.CompileModule(testCtx, traceWasm, wazero.NewCompileConfig())
 			require.NoError(t, err)
 

config.go

@@ -53,7 +53,7 @@ type RuntimeConfig interface {
 	// WithFeatureMutableGlobal allows globals to be mutable. This defaults to true as the feature was finished in
 	// WebAssembly 1.0 (20191205).
 	//
-	// When false, an api.Global can never be cast to an api.MutableGlobal, and any source that includes global vars
+	// When false, an api.Global can never be cast to an api.MutableGlobal, and any wasm that includes global vars
 	// will fail to parse.
 	WithFeatureMutableGlobal(bool) RuntimeConfig
 
@@ -279,7 +279,7 @@ func (c *compiledModule) Close(_ context.Context) error {
 	return nil
 }
 
-// CompileConfig allows you to override what was decoded from source, prior to compilation (ModuleBuilder.Compile or
+// CompileConfig allows you to override what was decoded from wasm, prior to compilation (ModuleBuilder.Compile or
 // Runtime.CompileModule).
 //
 // For example, WithImportRenamer allows you to override hard-coded names that don't match your requirements.

example_test.go

@@ -7,25 +7,24 @@ import (
 	"log"
 )
 
+// addWasm was generated by the following:
+//	cd examples/basic/testdata/testdata; wat2wasm --debug-names add.wat
+//go:embed examples/basic/testdata/add.wasm
+var addWasm []byte
+
 // This is an example of how to use WebAssembly via adding two numbers.
 //
-// See https://github.com/tetratelabs/wazero/tree/main/examples for more examples.
+// See https://github.com/tetratelabs/wazero/tree/main/examples for more.
 func Example() {
 	// Choose the context to use for function calls.
 	ctx := context.Background()
 
 	// Create a new WebAssembly Runtime.
 	r := NewRuntime()
 
-	// Add a module to the runtime named "wasm/math" which exports one function "add", implemented in WebAssembly.
-	mod, err := r.InstantiateModuleFromCode(ctx, []byte(`(module $wasm/math
-    (func $add (param i32 i32) (result i32)
-        local.get 0
-        local.get 1
-        i32.add
-    )
-    (export "add" (func $add))
-)`))
+	// Add a module to the runtime named "wasm/math" which exports one function
+	// "add", implemented in WebAssembly.
+	mod, err := r.InstantiateModuleFromBinary(ctx, addWasm)
 	if err != nil {
 		log.Panicln(err)
 	}

examples/allocation/rust/greet.go

@@ -38,7 +38,7 @@ func main() {
 
 	// Instantiate a WebAssembly module that imports the "log" function defined
 	// in "env" and exports "memory" and functions we'll use in this example.
-	mod, err := r.InstantiateModuleFromCode(ctx, greetWasm)
+	mod, err := r.InstantiateModuleFromBinary(ctx, greetWasm)
 	if err != nil {
 		log.Panicln(err)
 	}

examples/allocation/tinygo/greet.go

@@ -45,7 +45,7 @@ func main() {
 
 	// Instantiate a WebAssembly module that imports the "log" function defined
 	// in "env" and exports "memory" and functions we'll use in this example.
-	mod, err := r.InstantiateModuleFromCode(ctx, greetWasm)
+	mod, err := r.InstantiateModuleFromBinary(ctx, greetWasm)
 	if err != nil {
 		log.Panicln(err)
 	}

examples/basic/add.go

@@ -12,6 +12,11 @@ import (
 	"github.com/tetratelabs/wazero/api"
 )
 
+// addWasm was generated by the following:
+//	cd testdata; wat2wasm --debug-names add.wat
+//go:embed testdata/add.wasm
+var addWasm []byte
+
 // main implements a basic function in both Go and WebAssembly.
 func main() {
 	// Choose the context to use for function calls.
@@ -22,14 +27,7 @@ func main() {
 	defer r.Close(ctx) // This closes everything this Runtime created.
 
 	// Add a module to the runtime named "wasm/math" which exports one function "add", implemented in WebAssembly.
-	wasm, err := r.InstantiateModuleFromCode(ctx, []byte(`(module $wasm/math
-    (func $add (param i32 i32) (result i32)
-        local.get 0
-        local.get 1
-        i32.add
-    )
-    (export "add" (func $add))
-)`))
+	wasm, err := r.InstantiateModuleFromBinary(ctx, addWasm)
 	if err != nil {
 		log.Panicln(err)
 	}

examples/basic/testdata/add.wat

@@ -0,0 +1,15 @@
+(module
+  ;; Define the optional module name. '$' prefixing is a part of the text format.
+  $wasm/math
+
+  ;; add returns $x+$y.
+  ;;
+  ;; Notes:
+  ;; * The stack begins empty and anything left must match the result type.
+  ;; * export allows api.Module to return this via ExportedFunction("add")
+  (func (export "add") (param $x i32) (param $y i32) (result i32)
+    local.get $x ;; stack: [$x]
+    local.get $y ;; stack: [$x, $y]
+    i32.add      ;; stack: [$x+$y]
+  )
+)

examples/import-go/age-calculator.go

@@ -12,6 +12,11 @@ import (
 	"github.com/tetratelabs/wazero"
 )
 
+// ageCalculatorWasm was generated by the following:
+//	cd testdata; wat2wasm --debug-names age_calculator.wat
+//go:embed testdata/age_calculator.wasm
+var ageCalculatorWasm []byte
+
 // main shows how to define, import and call a Go-defined function from a
 // WebAssembly-defined function.
 //
@@ -51,39 +56,7 @@ func main() {
 	//
 	// Note: The import syntax in both Text and Binary format is the same
 	// regardless of if the function was defined in Go or WebAssembly.
-	ageCalculator, err := r.InstantiateModuleFromCode(ctx, []byte(`
-;; Define the optional module name. '$' prefixing is a part of the text format.
-(module $age-calculator
-
-  ;; In WebAssembly, you don't import an entire module, rather each function.
-  ;; This imports the functions and gives them names which are easier to read
-  ;; than the alternative (zero-based index).
-  ;;
-  ;; Note: Importing unused functions is not an error in WebAssembly.
-  (import "env" "log_i32" (func $log (param i32)))
-  (import "env" "current_year" (func $year (result i32)))
-
-  ;; get_age looks up the current year and subtracts the input from it.
-  ;; Note: The stack begins empty and anything left must match the result type.
-  (func $get_age (param $year_born i32) (result i32)
-                 ;; stack: []
-    call $year   ;; stack: [$year.result]
-    local.get 0  ;; stack: [$year.result, $year_born]
-    i32.sub      ;; stack: [$year.result-$year_born]
-  )
-  ;; export allows api.Module to return this via ExportedFunction("get_age")
-  (export "get_age" (func $get_age))
-
-  ;; log_age
-  (func $log_age (param $year_born i32)
-	              ;; stack: []
-    local.get 0   ;; stack: [$year_born]
-    call $get_age ;; stack: [$get_age.result]
-    call $log     ;; stack: []
-  )
-  (export "log_age" (func $log_age))
-)`))
-	// ^^ Note: wazero's text compiler is incomplete #59. We are using it anyway to keep this example dependency free.
+	ageCalculator, err := r.InstantiateModuleFromBinary(ctx, ageCalculatorWasm)
 	if err != nil {
 		log.Panicln(err)
 	}

examples/import-go/testdata/age_calculator.wat

@@ -0,0 +1,25 @@
+(module $age-calculator
+
+  ;; In WebAssembly, you don't import an entire module, rather each function.
+  ;; This imports the functions and gives them names which are easier to read
+  ;; than the alternative (zero-based index).
+  ;;
+  ;; Note: Importing unused functions is not an error in WebAssembly.
+  (import "env" "log_i32" (func $log (param i32)))
+  (import "env" "current_year" (func $year (result i32)))
+
+  ;; get_age looks up the current year and subtracts the input from it.
+  (func $get_age (export "get_age") (param $year_born i32) (result i32)
+    call $year            ;; stack: [$year.result]
+    local.get $year_born  ;; stack: [$year.result, $year_born]
+    i32.sub               ;; stack: [$year.result-$year_born]
+  )
+
+  ;; log_age calls $log with the result of $get_age
+  (func (export "log_age") (param $year_born i32)
+	                       ;; stack: []
+    local.get $year_born   ;; stack: [$year_born]
+    call $get_age          ;; stack: [$get_age.result]
+    call $log              ;; stack: []
+  )
+)

examples/multiple-results/README.md

@@ -1,3 +1,4 @@
 ## Multiple results example
 
-This example shows how to return more than one result from WebAssembly or Go-defined functions.
+This example shows how to return more than one result from WebAssembly or
+Go-defined functions.