-
Notifications
You must be signed in to change notification settings - Fork 30k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add maintaining-webassembly.md with strategy based on discussion in Next-10 mini-summit: nodejs/next-10#127 Signed-off-by: Michael Dawson <[email protected]> PR-URL: #42660 Reviewed-By: Tobias Nießen <[email protected]> Reviewed-By: Colin Ihrig <[email protected]>
- Loading branch information
Showing
1 changed file
with
97 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,97 @@ | ||
| # Maintaining WebAssembly | ||
|
|
||
| Support for [WebAssembly](https://webassembly.org/) | ||
| has been identified as one of the | ||
| [top technical priorities](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#webassembly) | ||
| for the future success of Node.js. | ||
|
|
||
| This document provides an overview of our high-level strategy for | ||
| supporting WebAssembly and information about our current implementation | ||
| as a starting point for contributors. | ||
|
|
||
| ## High-level approach | ||
|
|
||
| The key elements of our WebAssembly strategy include: | ||
|
|
||
| * Up-to-date core WebAssembly support | ||
| * Support for high-level APIs | ||
| * Making it easy to load WebAssembly | ||
| * Making sure the core Node.js APIs are compatible with WebAssembly | ||
| and can be called in an efficient manner from WebAssembly | ||
|
|
||
| ### Up-to-date core WebAssembly support | ||
|
|
||
| Node.js gets its core WebAssembly support through V8. We don't need | ||
| to do anything specific to support this, all we have to do is keep | ||
| the version of V8 as up-to-date as possible. | ||
|
|
||
| ### Key API support | ||
|
|
||
| As a runtime, Node.js must implement a number of APIs in addition | ||
| to the core WebAssembly support in order to be a good choice to run | ||
| WebAssembly. The project has currently identified these additional | ||
| APIs as important: | ||
|
|
||
| * WebAssembly System Interface (WASI). This provides the ability for | ||
| WebAssembly to interact with the outside world. Node.js currently | ||
| has an implementation (see below for more details). | ||
| * WebAssembly streaming APIs - As the Node.js implementation of | ||
| [WebStreams](https://nodejs.org/api/webstreams.html) matures, | ||
| implementing the embedder APIs to enable streaming with WebAssembly | ||
| will be important. | ||
| * [WebAssembly Component Model](https://github.com/WebAssembly/component-model/). | ||
| This API is still in the definition stage but the project should | ||
| keep track of its development as a way to simplify native code | ||
| integration. | ||
|
|
||
| ### Making it as easy as possible to load WASM | ||
|
|
||
| The most important thing we can do on this front is to either find and | ||
| reference resources or provide resources on how to: | ||
|
|
||
| * Compile your WebAssembly code (outside of Node.js) and integrate that | ||
| into an npm workflow. | ||
| * Load and run WebAssembly code in your Node.js application. | ||
|
|
||
| It is also important to support and track the ongoing work in ESM to enable | ||
| loading of WebAssembly with ESM. | ||
|
|
||
| ### Making sure the core Node.js APIs are compatible with WebAssembly | ||
|
|
||
| Use cases for which Node.js will be a good runtime will include code | ||
| both in JavaScript and compiled into WebAssembly. It is important | ||
| that Node.js APIs are able to be called from WebAssembly in | ||
| an efficient manner without extra buffer copies. We need to: | ||
|
|
||
| * Review APIs and identify those that can be called often from | ||
| WebAssembly. | ||
| * Where appropriate, make additions to identified APIs to allow | ||
| a pre-existing buffer to be passed in order to avoid copies. | ||
|
|
||
| ## Current implementation and assets | ||
|
|
||
| ### WebAssembly System Interface (WASI) | ||
|
|
||
| The Node.js WASI implementation is maintained in the | ||
| [uvwasi](https://github.com/nodejs/uvwasi) repository in the | ||
| Node.js GitHub organization. As needed, an updated copy | ||
| is vendored into the Node.js deps in | ||
| [deps/uvwasi](https://github.com/nodejs/node/tree/master/deps/uvwasi). | ||
|
|
||
| To update the copy of uvwasi in the Node.js deps: | ||
|
|
||
| * Copy over the contents of `include` and `src` to the corresponding | ||
| directories. | ||
| * Check if any additional files have been added and need to be added | ||
| to the `sources` list in `deps/uvwasi/uvwasi.gyp`. | ||
|
|
||
| In addition to the code from uvwasi, Node.js includes bindings and | ||
| APIs that allow WebAssembly to be run with WASI support from Node.js. | ||
| The documentation for this API is in | ||
| [WebAssembly System Interface (WASI)](https://nodejs.org/api/wasi.html). | ||
|
|
||
| The implementation of the bindings and the public API is in: | ||
|
|
||
| * [src/node\_wasi.h](https://github.com/nodejs/node/blob/master/src/node_wasi.h) | ||
| * [src/node\_wasi.cc](https://github.com/nodejs/node/blob/master/src/node_wasi.cc) | ||
| * [lib/wasi.js](https://github.com/nodejs/node/blob/master/lib/wasi.js) |