From 3d71723cca9353a655652aacee582edc7b225ff6 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Fri, 8 Apr 2022 14:23:38 -0400 Subject: [PATCH 1/5] 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 --- 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..e3f214953f4c0e --- /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 wrappers 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 for the wrapper 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) From eb76789e2c54d7bddc068053c64c2c71b04f6f62 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Wed, 20 Apr 2022 17:51:05 -0400 Subject: [PATCH 2/5] Update doc/contributing/maintaining-web-assembly.md Co-authored-by: Mohammed Keyvanzadeh --- doc/contributing/maintaining-web-assembly.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md index e3f214953f4c0e..14d82576e027d6 100644 --- a/doc/contributing/maintaining-web-assembly.md +++ b/doc/contributing/maintaining-web-assembly.md @@ -23,7 +23,7 @@ The key elements of our WebAssembly strategy include: 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. +the version of V8 as up-to-date as possible. ### Key API support From 108f6cd7a054d770efeb9041973acb0af051e833 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 16:10:00 -0400 Subject: [PATCH 3/5] Update doc/contributing/maintaining-web-assembly.md Co-authored-by: Colin Ihrig --- doc/contributing/maintaining-web-assembly.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md index 14d82576e027d6..2d7f6c5bdffbf3 100644 --- a/doc/contributing/maintaining-web-assembly.md +++ b/doc/contributing/maintaining-web-assembly.md @@ -85,7 +85,7 @@ To update the copy of uvwasi in the Node.js deps: * 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 wrappers and +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). From 06263f8013ddcc0d93fb78a6ce100ec16cfd1386 Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 16:10:08 -0400 Subject: [PATCH 4/5] Update doc/contributing/maintaining-web-assembly.md Co-authored-by: Colin Ihrig --- doc/contributing/maintaining-web-assembly.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md index 2d7f6c5bdffbf3..bd7de0f051eaa6 100644 --- a/doc/contributing/maintaining-web-assembly.md +++ b/doc/contributing/maintaining-web-assembly.md @@ -90,7 +90,7 @@ 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 for the wrapper and the public API is in: +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) From a43f3a146b85d0b52b8a641ecbc56c1d2cc8529a Mon Sep 17 00:00:00 2001 From: Michael Dawson Date: Thu, 21 Apr 2022 16:10:13 -0400 Subject: [PATCH 5/5] Update doc/contributing/maintaining-web-assembly.md Co-authored-by: Colin Ihrig --- doc/contributing/maintaining-web-assembly.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/contributing/maintaining-web-assembly.md b/doc/contributing/maintaining-web-assembly.md index bd7de0f051eaa6..9d8d8626ba9c84 100644 --- a/doc/contributing/maintaining-web-assembly.md +++ b/doc/contributing/maintaining-web-assembly.md @@ -94,4 +94,4 @@ 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) +* [lib/wasi.js](https://github.com/nodejs/node/blob/master/lib/wasi.js)