From: Paul Wisbey Date: Mon, 14 Mar 2016 13:11:26 +0000 (-0700) Subject: Merge "Added Emscripten guide" into devel/master X-Git-Tag: dali_1.1.26~2 X-Git-Url: http://review.tizen.org/git/?p=platform%2Fcore%2Fuifw%2Fdali-toolkit.git;a=commitdiff_plain;h=5b4982566aba41b5e21c3b8ce3e01a7e86db8f28;hp=748e31d36c07e45b75ffbfad770319c3f2909705 Merge "Added Emscripten guide" into devel/master --- diff --git a/build/tizen/docs/dali_doxygen.css b/build/tizen/docs/dali_doxygen.css index 223b8ef..3de4bf4 100644 --- a/build/tizen/docs/dali_doxygen.css +++ b/build/tizen/docs/dali_doxygen.css @@ -6,5 +6,5 @@ } div.image img { - max-width: 50em; + max-width: 70em; } diff --git a/docs/content/images/emscripten/emscripten-dali-toy.png b/docs/content/images/emscripten/emscripten-dali-toy.png new file mode 100644 index 0000000..fb79223 Binary files /dev/null and b/docs/content/images/emscripten/emscripten-dali-toy.png differ diff --git a/docs/content/images/emscripten/emscripten-live-doc.png b/docs/content/images/emscripten/emscripten-live-doc.png new file mode 100644 index 0000000..b14831a Binary files /dev/null and b/docs/content/images/emscripten/emscripten-live-doc.png differ diff --git a/docs/content/images/emscripten/emscripten-tests.png b/docs/content/images/emscripten/emscripten-tests.png new file mode 100644 index 0000000..ad5c2ae Binary files /dev/null and b/docs/content/images/emscripten/emscripten-tests.png differ diff --git a/docs/content/shared-javascript-and-cpp-documentation/emscripten.md b/docs/content/shared-javascript-and-cpp-documentation/emscripten.md new file mode 100644 index 0000000..81c963e --- /dev/null +++ b/docs/content/shared-javascript-and-cpp-documentation/emscripten.md @@ -0,0 +1,199 @@ + + +[TOC] + +# DALi Emscripten {#emscripten} + + +## Introduction - What is Emscripten? {#emscripten-introduction} + +Emscripten is a backend for LLVM that allows C and C++ to be compiled to Javascript. +This can then be run within a web browser at near native speed (without plugins). + +## DALi Emscripten {#emscripten-dali} + +Dali-Core can be built using with Emscripten producing a Javascript version of DALi. +A web page can then be made with HTML, and by embedding Javascript can reference and control the DALi Javascript canvas. + +This allows you to have a DALi canvas within a webpage that can either: +- Run autonomously +- Be controlled by HTML / Javascript controls elsewhere on the webpage + +The necessary scripts for building are included within each DALi repository. + + +# Building DALi Emscripten {#emscripten-building} + +Within each DALi repository, the README file gives the respective instructions for building that repository. +In summary, this process involves: + +- Setting up a DALi environment with the Emscripten SDK (the dali_env script will do this if specified) +- Building dali-core as Javascript (using Emscriptens configure and make replacements) +- Building dali-adaptor Emscripten replacement with a separate build script found in dali-adaptor +- Installing the examples within the dali-demo repository + +## Build Artefacts {#emscripten-artefacts} + +Each step in the build process will produce artefacts that will be written to the DALi environment directory. + +- dali-core: Produces a dali-core.so in bytecode. +- dali-adaptor: Produces: + - dali-emscripten.js (the main DALi Javascript runtime). + - dali-wrapper.js (wrapped DALi calls that call into their cpp-built-to-js counterpart to execute DALi calls). +- dali-toolkit: Note: Does not currently have Emscripten support. +- dali-demo: Does not build with Emscripten, but includes some Javascript examples that can be run with an Emscripten build of DALi. + + +# Running The Examples {#emscripten-examples} + +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: + +~~~ +cd $DESKTOP_PREFIX/share/emscripten +~~~ + +You will see the following files (among others): + +- dali-toy.html - An interactive DALi editor. Add actors, edit shaders and more. +- dali-toy.js - Required runtime for dali-toy. +- dali-doc-demo.html - Live documentation demo (a document containing a live DALi canvas). +- dali-tests.html - Live unit tests for DALi Emscripten. +- dali-emscripten.html - Required DALi Emscripten runtime. +- dali-emscripten.js - Required DALi Emscripten runtime. +- dali-wrapper.js - Required DALi Emscripten runtime. + +The other files within the directory are part of the live unit tests. + +You can use various browsers to run the examples, however for compatibility we recommend chrome. +To install chrome on Ubuntu: + +~~~ +sudo apt-get install chromium-browser +~~~ + +To run an example: + +
+~~~ +chromium-browser ./dali-toy.html +~~~ + +![ ](../assets/img/emscripten/emscripten-dali-toy.png) ![ ](./emscripten-dali-toy.png) + +

+~~~ +chromium-browser ./dali-doc-demo.html +~~~ + +![ ](../assets/img/emscripten/emscripten-live-doc.png) ![ ](./emscripten-live-doc.png) + +

+ + +# Running The Live Unit Tests {#emscripten-tests} + +Included are some live unit tests. +These run as a webpage within a browser, a DALi canvas is created and used to run each test. +The QUnit test suite is used (included within the repository for compatibility). + +![ ](../assets/img/emscripten/emscripten-tests.png) ![ ](./emscripten-tests.png) + +
+ +For the tests to work correctly, the webpage should be run through a webserver, rather than directly with a browser. +This can be achieved simply using npms's zero configuration command line server: "http-server". + +To install "http-server": + +~~~ +npm install http-server -g +~~~ + +To start the server, just run: + +~~~ +http-server +~~~ + +This will give the following output: + +~~~ +http-server +Starting up http-server, serving ./ +Available on: + http://127.0.0.1:8080 + http://106.1.10.118:8080 +Hit CTRL-C to stop the server +~~~ + +This will automatically create a server and serve the contents of the current directory. +The command outputs the URL to paste into your browser, in the above case: + +So to run the tests: + +- cd $DESKTOP_PREFIX/share/emscripten +- http-server +- Open a browser and paste the URL into the address bar. +- Click "All" to run all the tests. +- After a short while the tests will complete and any errors will be shown. +- A test can be re-run by clicking the "Rerun" link by that test. There is also a global Rerun option. + +# Debugging & Usage Tips {#emscripten-debugging} + +Most browsers provide a Javascript console. +In many cases this will open when inspecting an element. However to jump straight to the console (within chromium), press: + +- "Ctrl + Shift + J" (Windows/Linux) +- "Command + Option + J" (Mac) + +From this console, any references within your Javascript code and DALi itself can be accessed directly. +This allows you to run commands live. + +EG. Within the console you could enter: + +~~~ +var MyActor = new dali.Actor(); +MyActor.name = "MyName"; +... +MyActor.name +<- "MyName" +~~~ + +You can also inspect elements like so: + +~~~ +var MyActor = new dali.Actor(); +MyActor +<- ▶ Object {$$: Object} +~~~ + +Then clicking on the tree node toggle "▶" Will expand the objects hierarchy like so: + +~~~ +▼ Object {$$: Object} + ▶ $$: Object + anchorPoint: (...) + ▶ get anchorPoint: function () + ▶ set anchorPoint: function (newValue) + anchorPointX: (...) + ▶ get anchorPointX: function () + ▶ set anchorPointX: function (newValue) + +~~~ + +You can then further expand the tree by clicking on the "▶" nodes. + +You can also expand the "(...)" sections to show type information, EG: + +~~~ + anchorPoint: (...) +Becomes: + anchorPoint: Array[3] +~~~ + +Note: You can access and modify existing objects created by the Javascript also. + + +@class _Guide_Emscripten +*/