diff --git a/doc/platforms-android.dox b/doc/platforms-android.dox index 180c878ed..a18169ef0 100644 --- a/doc/platforms-android.dox +++ b/doc/platforms-android.dox @@ -57,7 +57,7 @@ Gradle requires Android SDK version of CMake, which is currently at version 3.6. See below for an experimental way to @ref platforms-android-system-cmake "use the system CMake" instead. -@section platforms-android-command-line Building and running console applications +@section platforms-android-console Building and running console applications Android allows to run arbitrary console utilities and tests via ADB. Assuming you have Magnum installed in the NDK path as described in @ref building-cross-android, diff --git a/doc/platforms-html5.dox b/doc/platforms-html5.dox index de120a592..57a818c86 100644 --- a/doc/platforms-html5.dox +++ b/doc/platforms-html5.dox @@ -25,22 +25,255 @@ namespace Magnum { -/** @page platforms-html5 HTML5 and WebGL +/** @page platforms-html5 JavaScript, HTML5 and WebGL @brief Building, testing and deploying HTML5 and WebGL projects @tableofcontents @m_footernavigation +@m_keywords{HTML5 Emscripten} -@todoc move stuff from Sdl2App and WindowlessEglApp -@todoc explain the css and js file, command-line args @todoc testing, gl tests, coverage, travis setup @todoc static plugins +@todoc speeding up compilation The following guide explains basic workflow of using [Emscripten](http://kripken.github.io/emscripten-site/) for deploying HTML5 apps using WebGL. -See also @ref Platform::Sdl2Application for more information. +At the very least you need to have Emscripten installed. Running console +applications requires Node.js, running browser apps require a webserver that's +able to serve static content (for example Apache, if you have Python installed, +it has a builtin webserver too). + +@note On ArchLinux it's the `emscripten` and `nodejs` packages, both in the + `[extras]` repository. + +Cross-compilation to Emscripten is done using a CMake toolchain that's part of +the toolchains repository at https://github.com/mosra/toolchains. Add it as a +submodule to your project or fetch the contents any other way that suits your project. The following guide will assume the contents of the repository are +placed in a `toolchains/` subdirectory. + +@code{.sh} +git submodule add git://github.com/mosra/toolchains +@endcode + +There are two toolchain files. The `generic/Emscripten.cmake` is for the +classical (asm.js) build, the `generic/Emscripten-wasm.cmake` is for +WebAssembly build. The following guide will work with the WASM toolchain. Don't +forget to adapt `EMSCRIPTEN_PREFIX` variable in +`toolchains/generic/Emscripten*.cmake` to path where Emscripten is installed; +you can also pass it explicitly on command-line using `-DEMSCRIPTEN_PREFIX`. +Default is `/usr/emscripten`. + +@section platforms-html5-console Building and running console applications + +Emscripten allows you to run arbitrary console utilities and tests via Node.js, +except for all code that accesses browsers APIs such as WebGL or audio. +Assuming you have Magnum installed in the Emscripten path as described in +@ref building-cross-emscripten, build your project simply as this, using one +of the toolchain files from above: + +@code{.sh} +mkdir build-emscripten-wasm && cd build-emscripten-wasm +cmake .. \ + -DCMAKE_TOOLCHAIN_FILE="../toolchains/generic/Emscripten-wasm.cmake" \ + -DCMAKE_BUILD_TYPE=Release +cmake --build . +@endcode + +After that you can run the generated JavaScript file using Node.js. Note that +it looks for the corresponding `*.wasm` file in the current directory, so you +need to @cb{.sh} cd @ce there first: + +@code{.sh} +cd build-emscripten-wasm/src +node my-application.js +@endcode + +@section platforms-html5-apps Building and deploying graphics apps + +In case you don't have an OpenGL ES build set up yet, you need to copy +`FindOpenGLES2.cmake` (or `FindOpenGLES3.cmake`) from the +[modules/](https://github.com/mosra/magnum/tree/master/modules) directory in +Magnum source to the `modules/` dir in your project so it is able to find the +WebGL libraries. + +Magnum provides an Emscripten application wrapper in +@ref Platform::Sdl2Application. See its documentation for more information +about general usage. You can also use the Emscripten APIs directly or any other +way. + +@note The @ref Platform::Sdl2Application also contains a fully configured + bootstrap project that's ready to build and deploy. Check its documentation + for details. + +To target the web browser, you need to provide a HTML markup for your +application. Template one is below. The markup references two files, +`EmscriptenApplication.js` and `WebApplication.css`, both are in the +[src/Magnum/Platform/](https://github.com/mosra/magnum/tree/master/src/Magnum/Platform) +directory in the source tree and are also put into `share/magnum/` inside your +install prefix. + +@code{.html-jinja} + + +
+ +