From d9c450d285d2607a6dd6e8f922da5493e5682c54 Mon Sep 17 00:00:00 2001 From: Paul Guyot Date: Sat, 7 Oct 2023 17:14:57 +0200 Subject: [PATCH] Update and improve documentation for WebAssembly port Signed-off-by: Paul Guyot --- doc/src/getting-started-guide.md | 58 +++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 8 deletions(-) diff --git a/doc/src/getting-started-guide.md b/doc/src/getting-started-guide.md index b5599dfcf..460e1d75a 100644 --- a/doc/src/getting-started-guide.md +++ b/doc/src/getting-started-guide.md @@ -358,25 +358,67 @@ The following resources may be useful for understanding how to develop Erlang or * [Programmers Guide](./programmers-guide.md) -## Getting Started with AtomVM WebAssembly port. +## Getting Started with AtomVM WebAssembly port for NodeJS -AtomVM may be run on platforms with NodeJS from the AtomVM.js file (with its companion AtomVM.wasm file). +AtomVM's WebAssembly port for NodeJS may be run using `node` command and AtomVM.js, AtomVM.worker.js and AtomVM.wasm files. -Currently, these files must be built and installed from source. + shell$ node /path/to/AtomVM.js /path/to/myapp.avm -> See the AtomVM [Build Instructions](./build-instructions.md) for instructions about how to build AtomVM WebAssembly port. +## Getting Started with AtomVM WebAssembly port for browsers -AtomVM may also be run in modern browsers (Safari, Chrome and Chrome-based, Firefox) from the AtomVM.js, AtomVM.worker.js and AtomVM.wasm files. +AtomVM may also be run in modern browsers (Safari, Chrome and Chrome-based, Firefox) using AtomVM.js, AtomVM.worker.js and AtomVM.wasm files. -Currently, these files must be built and installed from source. They also need to be installed on a web server that send `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers as explained in [Mozilla's documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements). +Please note that these files are different from the NodeJS ones. -AtomVM comes with a toy web server you can use and run with AtomVM built for Generic Unix with: +Because AtomVM uses SharedArrayBuffer, to be executed by a browser, these files need to be served: +- on localhost or over HTTPS +- by a web server that also sends `Cross-Origin-Opener-Policy` and `Cross-Origin-Embedder-Policy` headers. These headers are also called COOP and COEP headers. + +These security requirements are documented in [Mozilla's documentation](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SharedArrayBuffer#security_requirements). + +### Trying locally from AtomVM source tree + +If you compile AtomVM for Unix as well as for Node as explained in the [build instructions](./build-instructions.md), you can use an AtomVM-based toy webserver to serve the WebAssembly examples with: ``` ./src/AtomVM examples/emscripten/wasm_webserver.avm ``` -This web server serves HTML files from `examples/emscripten/` which you can copy to a webserver along with binaries and built files. +This web server serves HTML files from `examples/emscripten/`. It works without HTTPS because files are served on localhost. + +### Using a hosting service with a `_headers` file + +You can also host the three files on a hosting service such as Netlify that uses `_headers` files. + +The file could have the following content: + +``` +/* + Cross-Origin-Opener-Policy: same-origin + Cross-Origin-Embedder-Policy: require-corp +``` + +### Using web server such as Nginx + +You can also host the three files on web server such as Nginx or Apache. + +The configuration for Nginx would be: + +``` +server { + add_header Cross-Origin-Opener-Policy "same-origin"; + add_header Cross-Origin-Embedder-Policy "require-corp"; + location / { + ... + } +} +``` + +### Using Javascript service worker trick + +If you have no possibility to modify the headers, for example with GitHub pages, you can still get AtomVM to run in the browser using a Javascript service worker trick. + +We did successfully use [coi-serviceworker](https://github.com/gzuidhof/coi-serviceworker). ## Where to go from here