doc: document approach for building wasm in deps · nodejs/node@6e7e9a1

@@ -145,6 +145,48 @@ can be added as a non-externalizable dependency. In this case

145145

simply add the path to the JavaScript file in the `deps_files`

146146

list in the `node.gyp` file.

147147148+

## Common approach for dependencies with WASM components

149+150+

WASM components within dependencies are most often built

151+

outside of the regular Node.js `make build` step. They also

152+

require different tools.

153+154+

It is important that the tools and their versions used to build

155+

WASM components shipped within Node.js are well documented and

156+

be available if needed to rebuild/update older Node.js versions.

157+158+

In order to minimize the different number of tools and versions

159+

used to build WASM components and to document and ensure future

160+

availability, the project builds and maintains a common

161+

[wasm-builder](https://github.com/nodejs/wasm-builder) container

162+

that should be use to build WASM components in Node.js

163+

dependencies.

164+165+

The container provides a durable copy of the versions of the tools

166+

used for a specific build which are under the control of the Node.js

167+

project. In addition, the tools and verions are documented through metadata

168+

within the container in the `/home/node/metadata directory`.

169+170+

The available tools can be found by looking at the current version of the

171+

[Dockerfile](https://github.com/nodejs/wasm-builder/blob/main/container-build-info/Dockerfile)

172+

used to create the container.

173+174+

If additional WASM tool are needed beyond those available in the

175+

container, additions should be PR'd into the wasm-builder container.

176+177+

Examples of using the container include:

178+179+

* [build/wasm.js](https://github.com/nodejs/undici/blob/main/build/wasm.js) from undici

180+

* [tools/build-wasm.js](https://github.com/nodejs/amaro/blob/main/tools/build-wasm.js) from amaro

181+182+

In addition to using the container to build WASM components, the goal is also

183+

for the WASM components and final files that are shipped with Node.js to be

184+

built by the [dep-updaters](https://github.com/nodejs/node/tree/main/tools/dep_updaters)

185+

that are run on a regular basis and that they use only the files available in the Node.js

186+

repo for the dependency. For example, being able to rebuild the WASM and files that

187+

we ship in Node.js using only the files in

188+

[../deps/undici](https://github.com/nodejs/node/tree/main/deps/undici).

189+148190

## Updating dependencies

149191150192

Most dependencies are automatically updated by