Skip to content

Commit

Permalink
doc: add maintaining-webassembly.md
Browse files Browse the repository at this point in the history
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: nodejs#42660
Reviewed-By: Tobias Nießen <tniessen@tnie.de>
Reviewed-By: Colin Ihrig <cjihrig@gmail.com>
  • Loading branch information
mhdawson committed Apr 21, 2022
1 parent 4ad342a commit 3a6b975
Showing 1 changed file with 97 additions and 0 deletions.
97 changes: 97 additions & 0 deletions doc/contributing/maintaining-web-assembly.md
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)

0 comments on commit 3a6b975

Please sign in to comment.