Document building WebAssembly export templates

reference/compiling_for_web.rst

@@ -62,8 +62,8 @@ these 4 files:
 
        cp bin/godot.javascript.opt.debug.js godot.js
 
-2. ``godot.mem`` — Another file created during compilation. This file initially
-   has the same name as the JavaScript file, except ``.js`` is replaced by
+2. ``godot.mem`` — Also created during compilation, this file initially has the
+   same name as the JavaScript file, except ``.js`` is replaced by
    ``.html.mem``.
 
    For the release template::
@@ -74,24 +74,33 @@ these 4 files:
 
        cp bin/godot.javascript.opt.debug.html.mem godot.mem
 
-3. ``godot.html`` and
-4. ``godotfs.js`` — Both of these files are located within the Godot Engine
-   repository, under ``tools/html_fs/``.
+3. ``godot.html`` — Another file created during compilation. This file has a
+   ``.html`` extension.
+
+   For the release template::
+
+       cp bin/godot.javascript.opt.html godot.html
+
+   For the debug template::
+
+       cp bin/godot.javascript.opt.debug.html godot.html
+
+4. ``godotfs.js`` — This file is located within the Godot Engine repository,
+   under ``/tools/dist/html_fs/``.
 
 ::
 
-    cp tools/html_fs/godot.html .
-    cp tools/html_fs/godotfs.js .
+    cp tools/dist/html_fs/godotfs.js .
 
 Once these 4 files are assembled, zip them up and your export template is ready
 to go. The correct name for the template file is ``javascript_release.zip`` for
 the release template::
 
-    zip javascript_release godot.js godot.mem godotfs.js godot.html
+    zip javascript_release.zip godot.js godot.mem godotfs.js godot.html
 
 And ``javascript_debug.zip`` for the debug template::
 
-    zip javascript_debug godot.js godot.mem godotfs.js godot.html
+    zip javascript_debug.zip godot.js godot.mem godotfs.js godot.html
 
 The resulting files must be placed in the ``templates`` directory in your Godot
 user directory::
@@ -106,12 +115,73 @@ There's no need to copy the templates in this case — you can simply reference
 the resulting files in your Godot source folder, so the next time you build,
 the custom templates will already be referenced.
 
+Compiling to WebAssembly
+-------------------------
+
+The current default for exporting to the web is to compile to *asm.js*, a
+highly optimizable subset of JavaScript.
+
+It is also possible to compile to the experimental WebAssembly format, which
+should eventually offer better performance and loading times. Its specification
+is still in flux and compile tools may sporadically fail to build Godot.
+Running a game per WebAssembly requires nightly browser builds with special
+flags set. As such, WebAssembly builds are currently not suitable for
+publishing.
+
+WebAssembly can be compiled in two ways: The default way is to first
+compile to asm.js similarly to the default method, then translate to
+WebAssembly using a tool called ``asm2wasm``. Emscripten automatically takes
+care of both processes, we simply run SCons.
+
+The other method uses LLVM's WebAssembly backend, which should eventually
+produce more performant binaries. To build LLVM with this backend, set the
+CMake variable ``LLVM_EXPERIMENTAL_TARGETS_TO_BUILD` to ``WebAssembly`` when
+building LLVM.
+
+Compiling with this backend outputs files in LLVM's ``.s`` format, which is
+translated to actual WebAssembly using a tool called ``s2wasm``. Emscripten
+manages these processes as well, so we just invoke SCons.
+
+In order to choose one of the two methods, the ``LLVM_ROOT`` variable in the
+Emscripten configuration file ``~/.emscripten`` is set. If it points to a
+directory containing binaries of Emscripten's *fastcomp* fork of clang,
+``asm2wasm`` is used. This is the default in a normal Emscripten installation.
+Otherwise, LLVM binaries built with the WebAssembly backend will be expected
+and ``s2wasm`` is used.
+
+With ``LLVM_ROOT`` set up correctly, compiling to WebAssembly is as easy as
+adding ``wasm=yes`` to the SCons arguments::
+
+    scons platform=javascript target=release wasm=yes
+    scons platform=javascript target=release_debug wasm=yes
+
+These commands will build WebAssembly binaries in either release or debug mode.
+The generated files' names contain ``.webassembly`` as an additional file
+suffix before the extension.
+
+WebAssembly builds do not use a memory initializer file, so do not add a
+``godot.mem`` file in the archive — there is none.
+However, the binary WebAssembly file with the ``.wasm`` extension must be
+added to the archive as ``godot.wasm``.
+
+For the release template::
+
+   cp bin/godot.javascript.opt.webassembly.wasm godot.wasm
+
+For the debug template::
+
+   cp bin/godot.javascript.opt.debug.webassembly.wasm godot.wasm
+
+The WebAssembly export templates simply replace the previous asm.js-based web
+export templates with the names ``javascript_release.zip`` and
+``javascript_debug.zip``
+
 Customizing the HTML page
 -------------------------
 
-Rather than the default ``godot.html`` file from the Godot Engine repository's
-``tools/html_fs/`` directory, it is also possible to use a custom HTML page.
-This allows drastic customization of the final web presentation.
+Rather than the default ``godot.html`` file generated when compiling, it is
+also possible to use a custom HTML page. This allows drastic customization of
+the final web presentation.
 
 The JavaScript object ``Module`` is the page's interface to Emscripten. Check
 the official documentation for information on how to use it: https://kripken.github.io/emscripten-site/docs/api_reference/module.html
@@ -126,13 +196,11 @@ substituted by values dependent on the export:
 +------------------------------+-----------------------------------------------+
 | Placeholder                  | substituted by                                |
 +==============================+===============================================+
-| ``$GODOT_JS``                | Name of the compiled Godot Engine JavaScript  |
-|                              | file                                          |
+| ``{{{ SCRIPT }}}``           | ``<script>`` element responsible for loading  |
+|                              | the engine, generated by Emscripten           |
 +------------------------------+-----------------------------------------------+
-| ``$GODOT_FS``                | Name of the filesystem access JavaScript      |
-|                              | file                                          |
-+------------------------------+-----------------------------------------------+
-| ``$GODOT_MEM``               | Name of the memory initialization file        |
+| ``$GODOT_BASE``              | Basename of files referenced within the page, |
+|                              | without file extension or other suffixes      |
 +------------------------------+-----------------------------------------------+
 | ``$GODOT_CANVAS_WIDTH``      | Integer specifying the initial display width  |
 |                              | of the game                                   |
@@ -159,7 +227,7 @@ substituted by values dependent on the export:
 |                              | of the page's CSS style sheet                 |
 +------------------------------+-----------------------------------------------+
 
-The first five of the placeholders listed should always be implemented in the
+The first four of the placeholders listed should always be implemented in the
 HTML page, since they are important for the correct presentation of the game.
 The other placeholders are optional.