mirror of
https://github.com/tc39/test262.git
synced 2025-05-04 15:00:42 +02:00
e9a5a7f918
* [javascriptcore-test262-automation] changes from git@github.com:WebKit/webkit.git at sha 949e26452cfa153a7f4afe593da97e2fe9e1b706 on Tue Jul 03 2018 14:35:15 GMT-0400 (Eastern Daylight Time)
99 lines
3.8 KiB
Markdown
99 lines
3.8 KiB
Markdown
# `wasmjs`: JavaScript tooling for WebAssembly
|
|
|
|
`wasmjs` is a self-contained collection of JavaScript tools which can create and
|
|
manipulate WebAssembly representations and binaries. At its core is `wasm.json`,
|
|
a JSON decription of the WebAssembly format and other interesting facts about
|
|
WebAssembly as used by the Webkit project (such as the names of associated
|
|
JavaScriptCore B3 opcodes).
|
|
|
|
`wasmjs` requires modern JavaScript features such as ES6 modules, which is
|
|
acceptable because WebAssembly is itself contemporary to these other features.
|
|
|
|
|
|
# `Builder` API
|
|
|
|
The current core API of `wasmjs` is the `Builder` API from `Builder.js`. It is
|
|
used to build WebAssembly modules, and assemble them to valid `.wasm` binaries
|
|
(held in an `ArrayBuffer`). The `Builder` is a small DSL which looks similar to
|
|
the WebAssembly [binary format][]. Each section is declared through a property
|
|
on the `Builder` object, and each declaration returns a proxy object which has
|
|
properties specific to that section. Proxies are "popped" back by invoking their
|
|
`.End()` property.
|
|
|
|
The `Code` section has properties for each [WebAssembly opcode][]. Opcode which
|
|
create a scope can be nested using a lambda.
|
|
|
|
[binary format]: https://github.com/WebAssembly/design/blob/master/BinaryEncoding.md#high-level-structure
|
|
[WebAssembly opcode]: https://github.com/WebAssembly/design/blob/master/Semantics.md
|
|
|
|
A simple example:
|
|
|
|
```javascript
|
|
import Builder from 'Builder.js';
|
|
|
|
const builder = new Builder();
|
|
|
|
// Construct the equivalent of: (module (func "answer" (i32.const 42) (return)))
|
|
builder
|
|
// Declare a Type section, which the builder will auto-fill as functions are defined.
|
|
.Type().End()
|
|
// Declare a Function section, which the builder will auto-fill as functions are defined.
|
|
.Function().End()
|
|
.Export()
|
|
// Export the "answer" function (defined below) to JavaScript.
|
|
.Function("answer")
|
|
.End()
|
|
.Code()
|
|
// The "answer" function takes an i32 parameters, and returns an i32.
|
|
.Function("answer", { params: ["i32"], ret: "i32" })
|
|
// Create a block returning an i32, whose body is the enclosed lambda.
|
|
.Block("i32", b => b
|
|
.GetLocal(0) // Parameters are in the same index space as locals.
|
|
.I32Const(0) // Generate an i32 constant.
|
|
.I32Eq() // A comparison, using the two values currently on the stack.
|
|
.If("i32") // Consume the comparison result, returning an i32.
|
|
.I32Const(42)
|
|
.Else()
|
|
.I32Const(1)
|
|
.End()
|
|
)
|
|
.Return() // Return the top of the stack: the value returned by the block.
|
|
.End() // End the current function.
|
|
.End(); // End the Code section.
|
|
|
|
// Create an ArrayBuffer which is a valid WebAssembly `.wasm` file.
|
|
const bin = builder.WebAssembly().get();
|
|
|
|
// Use the standard WebAssembly JavaScript API to compile the module, and instantiate it.
|
|
const module = new WebAssembly.Module(bin);
|
|
const instance = new WebAssembly.Instance(module);
|
|
|
|
// Invoke the compiled WebAssembly function.
|
|
const result0 = instance.exports.answer(0);
|
|
if (result0 !== 42)
|
|
throw new Error(`Expected 42, got ${result0}.`);
|
|
|
|
const result1 = instance.exports.answer(1);
|
|
if (result1 !== 1)
|
|
throw new Error(`Expected 1, got ${result1}.`);
|
|
```
|
|
|
|
|
|
# Testing
|
|
|
|
* `self-test` tests `wasmjs` itself.
|
|
* `js-api` tests the [WebAssembly JavaScript API](https://github.com/WebAssembly/design/blob/master/JS.md).
|
|
* `function-tests` tests the WebAssembly compiler's implementation.
|
|
|
|
All tests can be executed using:
|
|
|
|
```bash
|
|
JSSHELL=/path/to/my/js-shell test.sh
|
|
```
|
|
|
|
They can also be executed by using WebKit's `run-javascriptcore-tests` tool:
|
|
|
|
```bash
|
|
./Tools/Scripts/run-javascriptcore-tests --release --filter wasm -arch x86_64
|
|
```
|