Merge pull request #61 from eska014/build-web

Document building for web

reference/_compiling.rst

@@ -13,6 +13,7 @@ Compiling
    compiling_for_ios
    cross-compiling_for_ios_on_linux
    compiling_for_universal_windows_apps
+   compiling_for_web
    batch_building_templates
    configuring_an_ide
 

reference/compiling_for_web.rst

@@ -0,0 +1,160 @@
+.. _doc_compiling_for_web:
+
+Compiling for web export
+========================
+
+.. highlight:: shell
+
+Requirements
+------------
+
+To compile export templates for the web, the following is required:
+
+-  `Emscripten SDK <http://emscripten.org/>`__
+-  `Python 2.7+ <https://www.python.org/>`__ (3.0 is
+   untested as of now)
+-  `SCons <http://www.scons.org>`__ build system
+
+Compiling
+---------
+
+Start a terminal and set the environment variable ``EMSCRIPTEN_ROOT`` to the
+installation directory of Emscripten::
+
+    export EMSCRIPTEN_ROOT=~/emsdk/emscripten/master
+
+Now go to the root directory of the engine source code and instruct SCons to
+compile for JavaScript. Specify ``target`` as either ``release`` for a release
+build or ``release_debug`` for a debug build::
+
+    scons platform=javascript tools=no target=release
+    scons platform=javascript tools=no target=release_debug
+
+The engine will now be compiled to JavaScript by Emscripten. If all goes well,
+the resulting file will be placed in the ``bin`` subdirectory. Its name is
+``godot.javascript.opt.js`` for release or ``godot.javascript.opt.debug.js``
+for debug. Additionally, a file of the same name but with the extension
+``.html.mem`` will be generated.
+
+Building export templates
+-------------------------
+
+After compiling, further steps are required to build the template.
+The actual web export template has the form of a zip file containing at least
+these 4 files:
+
+1. ``godot.js`` — This is the file that was just compiled, but under a different
+   name.
+
+   For the release template::
+
+       cp bin/godot.javascript.opt.js godot.js
+
+   For the debug template::
+
+       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
+   ``.html.mem``.
+
+   For the release template::
+
+       cp bin/godot.javascript.opt.html.mem godot.mem
+
+   For the debug template::
+
+       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/``.
+
+::
+
+    cp tools/html_fs/godot.html .
+    cp tools/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
+
+And ``javascript_debug.zip`` for the debug template::
+
+    zip javascript_debug godot.js godot.mem godotfs.js godot.html
+
+The resulting files must be placed in the ``templates`` directory in your Godot
+user directory::
+
+    mv javascript_release ~/.godot/templates
+    mv javascript_debug ~/.godot/templates
+
+If you are writing custom modules or using custom C++ code, you may want to
+configure your zip files as custom export templates. This can be done in the
+export GUI, using the "Custom Package" option.
+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.
+
+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.
+
+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
+
+The default HTML page offers a good example to start off with, separating the
+Emscripten interface logic in the JavaScript ``Module`` object from the page
+logic in the ``Presentation`` object.
+
+When exporting a game, several placeholders in the ``godot.html`` file are
+substituted by values dependent on the export:
+
++------------------------------+-----------------------------------------------+
+| Placeholder                  | substituted by                                |
++==============================+===============================================+
+| ``$GODOT_JS``                | Name of the compiled Godot Engine JavaScript  |
+|                              | file                                          |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_FS``                | Name of the filesystem access JavaScript      |
+|                              | file                                          |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_MEM``               | Name of the memory initialization file        |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_CANVAS_WIDTH``      | Integer specifying the initial display width  |
+|                              | of the game                                   |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_CANVAS_HEIGHT``     | Integer specifying the initial display height |
+|                              | of the game                                   |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_DEBUG_ENABLED``     | String ``true`` if debugging, ``false``       |
+|                              | otherwise                                     |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_CONTROLS_ENABLED``  | String ``true`` if ``html/controls_enabled``  |
+|                              | is enabled, ``false`` otherwise               |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_HEAD_TITLE``        | Title of the page, normally used as content   |
+|                              | of the HTML ``<title>`` element               |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_HEAD_INCLUDE``      | Custom string to include just before the end  |
+|                              | of the HTML ``<head>`` element                |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_STYLE_FONT_FAMILY`` | CSS format ``font-family`` to use, without    |
+|                              | terminating semicolon                         |
++------------------------------+-----------------------------------------------+
+| ``$GODOT_STYLE_INCLUDE``     | Custom string to include just before the end  |
+|                              | of the page's CSS style sheet                 |
++------------------------------+-----------------------------------------------+
+
+The first five 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.
+
+Finally, the custom HTML page is installed by replacing the existing
+``godot.html`` file in the export template with the new one, retaining the name
+of the original.