diff options
author | Michael Dawson <mdawson@devrus.com> | 2022-04-08 21:23:38 +0300 |
---|---|---|
committer | Michaël Zasso <targos@protonmail.com> | 2022-04-28 07:57:21 +0300 |
commit | 59da1339b48605e3a1ca93bad9800bd1f011a5a2 (patch) | |
tree | 72cfbd8a6abe5405d1ac3e1724585d061cf14a63 /doc | |
parent | d9f3f05cabecfeff7c267b9193f21b71013679b0 (diff) |
doc: add maintaining-webassembly.md
Add maintaining-webassembly.md with strategy based
on discussion in Next-10 mini-summit:
https://github.com/nodejs/next-10/pull/127
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: https://github.com/nodejs/node/pull/42660
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/contributing/maintaining-web-assembly.md | 97 |
1 files changed, 97 insertions, 0 deletions
diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md new file mode 100644 index 00000000000..9d8d8626ba9 --- /dev/null +++ b/doc/contributing/maintaining-web-assembly.md @@ -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) |