Commit 59da133
doc: add maintaining-webassembly.md
Add maintaining-webassembly.md with strategy based
on discussion in Next-10 mini-summit:
nodejs/next-10#127
Signed-off-by: Michael Dawson <mdawson@devrus.com>
PR-URL: #42660
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>1 parent d9f3f05 commit 59da133
1 file changed
Lines changed: 97 additions & 0 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
@@ -0,0 +1,97 @@ | |||
| 1 | + # Maintaining WebAssembly | ||
| 2 | + | ||
| 3 | + Support for [WebAssembly](https://webassembly.org/) | ||
| 4 | + has been identified as one of the | ||
| 5 | + [top technical priorities](https://github.com/nodejs/node/blob/master/doc/contributing/technical-priorities.md#webassembly) | ||
| 6 | + for the future success of Node.js. | ||
| 7 | + | ||
| 8 | + This document provides an overview of our high-level strategy for | ||
| 9 | + supporting WebAssembly and information about our current implementation | ||
| 10 | + as a starting point for contributors. | ||
| 11 | + | ||
| 12 | + ## High-level approach | ||
| 13 | + | ||
| 14 | + The key elements of our WebAssembly strategy include: | ||
| 15 | + | ||
| 16 | + * Up-to-date core WebAssembly support | ||
| 17 | + * Support for high-level APIs | ||
| 18 | + * Making it easy to load WebAssembly | ||
| 19 | + * Making sure the core Node.js APIs are compatible with WebAssembly | ||
| 20 | + and can be called in an efficient manner from WebAssembly | ||
| 21 | + | ||
| 22 | + ### Up-to-date core WebAssembly support | ||
| 23 | + | ||
| 24 | + Node.js gets its core WebAssembly support through V8. We don't need | ||
| 25 | + to do anything specific to support this, all we have to do is keep | ||
| 26 | + the version of V8 as up-to-date as possible. | ||
| 27 | + | ||
| 28 | + ### Key API support | ||
| 29 | + | ||
| 30 | + As a runtime, Node.js must implement a number of APIs in addition | ||
| 31 | + to the core WebAssembly support in order to be a good choice to run | ||
| 32 | + WebAssembly. The project has currently identified these additional | ||
| 33 | + APIs as important: | ||
| 34 | + | ||
| 35 | + * WebAssembly System Interface (WASI). This provides the ability for | ||
| 36 | + WebAssembly to interact with the outside world. Node.js currently | ||
| 37 | + has an implementation (see below for more details). | ||
| 38 | + * WebAssembly streaming APIs - As the Node.js implementation of | ||
| 39 | + [WebStreams](https://nodejs.org/api/webstreams.html) matures, | ||
| 40 | + implementing the embedder APIs to enable streaming with WebAssembly | ||
| 41 | + will be important. | ||
| 42 | + * [WebAssembly Component Model](https://github.com/WebAssembly/component-model/). | ||
| 43 | + This API is still in the definition stage but the project should | ||
| 44 | + keep track of its development as a way to simplify native code | ||
| 45 | + integration. | ||
| 46 | + | ||
| 47 | + ### Making it as easy as possible to load WASM | ||
| 48 | + | ||
| 49 | + The most important thing we can do on this front is to either find and | ||
| 50 | + reference resources or provide resources on how to: | ||
| 51 | + | ||
| 52 | + * Compile your WebAssembly code (outside of Node.js) and integrate that | ||
| 53 | + into an npm workflow. | ||
| 54 | + * Load and run WebAssembly code in your Node.js application. | ||
| 55 | + | ||
| 56 | + It is also important to support and track the ongoing work in ESM to enable | ||
| 57 | + loading of WebAssembly with ESM. | ||
| 58 | + | ||
| 59 | + ### Making sure the core Node.js APIs are compatible with WebAssembly | ||
| 60 | + | ||
| 61 | + Use cases for which Node.js will be a good runtime will include code | ||
| 62 | + both in JavaScript and compiled into WebAssembly. It is important | ||
| 63 | + that Node.js APIs are able to be called from WebAssembly in | ||
| 64 | + an efficient manner without extra buffer copies. We need to: | ||
| 65 | + | ||
| 66 | + * Review APIs and identify those that can be called often from | ||
| 67 | + WebAssembly. | ||
| 68 | + * Where appropriate, make additions to identified APIs to allow | ||
| 69 | + a pre-existing buffer to be passed in order to avoid copies. | ||
| 70 | + | ||
| 71 | + ## Current implementation and assets | ||
| 72 | + | ||
| 73 | + ### WebAssembly System Interface (WASI) | ||
| 74 | + | ||
| 75 | + The Node.js WASI implementation is maintained in the | ||
| 76 | + [uvwasi](https://github.com/nodejs/uvwasi) repository in the | ||
| 77 | + Node.js GitHub organization. As needed, an updated copy | ||
| 78 | + is vendored into the Node.js deps in | ||
| 79 | + [deps/uvwasi](https://github.com/nodejs/node/tree/master/deps/uvwasi). | ||
| 80 | + | ||
| 81 | + To update the copy of uvwasi in the Node.js deps: | ||
| 82 | + | ||
| 83 | + * Copy over the contents of `include` and `src` to the corresponding | ||
| 84 | + directories. | ||
| 85 | + * Check if any additional files have been added and need to be added | ||
| 86 | + to the `sources` list in `deps/uvwasi/uvwasi.gyp`. | ||
| 87 | + | ||
| 88 | + In addition to the code from uvwasi, Node.js includes bindings and | ||
| 89 | + APIs that allow WebAssembly to be run with WASI support from Node.js. | ||
| 90 | + The documentation for this API is in | ||
| 91 | + [WebAssembly System Interface (WASI)](https://nodejs.org/api/wasi.html). | ||
| 92 | + | ||
| 93 | + The implementation of the bindings and the public API is in: | ||
| 94 | + | ||
| 95 | + * [src/node\_wasi.h](https://github.com/nodejs/node/blob/master/src/node_wasi.h) | ||
| 96 | + * [src/node\_wasi.cc](https://github.com/nodejs/node/blob/master/src/node_wasi.cc) | ||
| 97 | + * [lib/wasi.js](https://github.com/nodejs/node/blob/master/lib/wasi.js) | ||
0 commit comments