From 59da1339b48605e3a1ca93bad9800bd1f011a5a2 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 8 Apr 2022 14:23:38 -0400 Subject: [PATCH] doc: add maintaining-webassembly.md MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 PR-URL: https://github.com/nodejs/node/pull/42660 Reviewed-By: Tobias Nießen Reviewed-By: Colin Ihrig --- doc/contributing/maintaining-web-assembly.md | 97 ++++++++++++++++++++ 1 file changed, 97 insertions(+) create mode 100644 doc/contributing/maintaining-web-assembly.md diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md new file mode 100644 index 00000000000000..9d8d8626ba9c84 --- /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)