@@ -145,6 +145,48 @@ can be added as a non-externalizable dependency. In this case |
145 | 145 | simply add the path to the JavaScript file in the `deps_files` |
146 | 146 | list in the `node.gyp` file. |
147 | 147 |
|
| 148 | +## 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 | + |
148 | 190 | ## Updating dependencies |
149 | 191 |
|
150 | 192 | Most dependencies are automatically updated by |
|