docs/content/shared-javascript-and-cpp-documentation/emscripten.md

   1 <!--
   2 /**-->
   3
   4 [TOC]
   5
   6 # DALi Emscripten {#emscripten}
   7
   8
   9 ## Introduction - What is Emscripten? {#emscripten-introduction}
  10
  11 Emscripten is a backend for LLVM that allows C and C++ to be compiled to Javascript.
  12 This can then be run within a web browser at near native speed (without plugins).
  13
  14 ## DALi Emscripten {#emscripten-dali}
  15
  16 Dali-Core can be built using with Emscripten producing a Javascript version of DALi.
  17 A web page can then be made with HTML, and by embedding Javascript can reference and control the DALi Javascript canvas.
  18
  19 This allows you to have a DALi canvas within a webpage that can either:
  20 - Run autonomously
  21 - Be controlled by HTML / Javascript controls elsewhere on the webpage
  22
  23 The necessary scripts for building are included within each DALi repository.
  24
  25
  26 # Building DALi Emscripten {#emscripten-building}
  27
  28 Within each DALi repository, the README file gives the respective instructions for building that repository.
  29 In summary, this process involves:
  30
  31 - Setting up a DALi environment with the Emscripten SDK (the dali_env script will do this if specified)
  32 - Building dali-core as Javascript (using Emscriptens configure and make replacements)
  33 - Building dali-adaptor Emscripten replacement with a separate build script found in dali-adaptor
  34 - Installing the examples within the dali-demo repository
  35
  36 ## Build Artefacts {#emscripten-artefacts}
  37
  38 Each step in the build process will produce artefacts that will be written to the DALi environment directory.
  39
  40 - dali-core: Produces a dali-core.so in bytecode.
  41 - dali-adaptor: Produces:
  42   - dali-emscripten.js (the main DALi Javascript runtime).
  43   - dali-wrapper.js    (wrapped DALi calls that call into their cpp-built-to-js counterpart to execute DALi calls).
  44 - dali-toolkit: Note: Does not currently have Emscripten support.
  45 - dali-demo: Does not build with Emscripten, but includes some Javascript examples that can be run with an Emscripten build of DALi.
  46
  47
  48 # Running The Examples {#emscripten-examples}
  49
  50 After building by following the README within each repository, navigate to the emscripten directory within your DALi environment. Assuming your DESKTOP_PREFIX environment variable is set (from your DALi environment), run:
  51
  52 ~~~
  53 cd $DESKTOP_PREFIX/share/emscripten
  54 ~~~
  55
  56 You will see the following files (among others):
  57
  58 - dali-toy.html          - An interactive DALi editor. Add actors, edit shaders and more.
  59 - dali-toy.js            - Required runtime for dali-toy.
  60 - dali-doc-demo.html     - Live documentation demo (a document containing a live DALi canvas).
  61 - dali-tests.html        - Live unit tests for DALi Emscripten.
  62 - dali-emscripten.html   - Required DALi Emscripten runtime.
  63 - dali-emscripten.js     - Required DALi Emscripten runtime.
  64 - dali-wrapper.js        - Required DALi Emscripten runtime.
  65
  66 The other files within the directory are part of the live unit tests.
  67
  68 You can use various browsers to run the examples, however for compatibility we recommend chrome.
  69 To install chrome on Ubuntu:
  70
  71 ~~~
  72 sudo apt-get install chromium-browser
  73 ~~~
  74
  75 To run an example:
  76
  77 <br>
  78 ~~~
  79 chromium-browser ./dali-toy.html
  80 ~~~
  81
  82 ![ ](../assets/img/emscripten/emscripten-dali-toy.png) ![ ](./emscripten-dali-toy.png)
  83
  84 <br><br>
  85 ~~~
  86 chromium-browser ./dali-doc-demo.html
  87 ~~~
  88
  89 ![ ](../assets/img/emscripten/emscripten-live-doc.png) ![ ](./emscripten-live-doc.png)
  90
  91 <br><br>
  92
  93
  94 # Running The Live Unit Tests {#emscripten-tests}
  95
  96 Included are some live unit tests.
  97 These run as a webpage within a browser, a DALi canvas is created and used to run each test.
  98 The QUnit test suite is used (included within the repository for compatibility).
  99
 100 ![ ](../assets/img/emscripten/emscripten-tests.png) ![ ](./emscripten-tests.png)
 101
 102 <br>
 103
 104 For the tests to work correctly, the webpage should be run through a webserver, rather than directly with a browser.
 105 This can be achieved simply using npms's zero configuration command line server: "http-server".
 106
 107 To install "http-server":
 108
 109 ~~~
 110 npm install http-server -g
 111 ~~~
 112
 113 To start the server, just run:
 114
 115 ~~~
 116 http-server
 117 ~~~
 118
 119 This will give the following output:
 120
 121 ~~~
 122 http-server
 123 Starting up http-server, serving ./
 124 Available on:
 125   http://127.0.0.1:8080
 126   http://106.1.10.118:8080
 127 Hit CTRL-C to stop the server
 128 ~~~
 129
 130 This will automatically create a server and serve the contents of the current directory.
 131 The command outputs the URL to paste into your browser, in the above case:
 132
 133 So to run the tests:
 134
 135 - cd $DESKTOP_PREFIX/share/emscripten
 136 - http-server
 137 - Open a browser and paste the URL into the address bar.
 138 - Click "All" to run all the tests.
 139 - After a short while the tests will complete and any errors will be shown.
 140 - A test can be re-run by clicking the "Rerun" link by that test. There is also a global Rerun option.
 141
 142 # Debugging & Usage Tips {#emscripten-debugging}
 143
 144 Most browsers provide a Javascript console.
 145 In many cases this will open when inspecting an element. However to jump straight to the console (within chromium), press:
 146
 147 - "Ctrl + Shift + J" (Windows/Linux)
 148 - "Command + Option + J" (Mac)
 149
 150 From this console, any references within your Javascript code and DALi itself can be accessed directly.
 151 This allows you to run commands live.
 152
 153 EG. Within the console you could enter:
 154
 155 ~~~
 156 var MyActor = new dali.Actor();
 157 MyActor.name = "MyName";
 158 ...
 159 MyActor.name
 160 <- "MyName"
 161 ~~~
 162
 163 You can also inspect elements like so:
 164
 165 ~~~
 166 var MyActor = new dali.Actor();
 167 MyActor
 168 <- ▶ Object {$$: Object}
 169 ~~~
 170
 171 Then clicking on the tree node toggle "▶" Will expand the objects hierarchy like so:
 172
 173 ~~~
 174 ▼ Object {$$: Object}
 175   ▶ $$: Object
 176     anchorPoint: (...)
 177   ▶ get anchorPoint: function ()
 178   ▶ set anchorPoint: function (newValue)
 179     anchorPointX: (...)
 180   ▶ get anchorPointX: function ()
 181   ▶ set anchorPointX: function (newValue)
 182   <etc>
 183 ~~~
 184
 185 You can then further expand the tree by clicking on the "▶" nodes.
 186
 187 You can also expand the "(...)" sections to show type information, EG:
 188
 189 ~~~
 190     anchorPoint: (...)
 191 Becomes:
 192     anchorPoint: Array[3]
 193 ~~~
 194
 195 Note: You can access and modify existing objects created by the Javascript also.
 196
 197
 198 @class _Guide_Emscripten
 199 */